###

# Boost.Python

## Header <boost/python/enum.hpp>

## Contents

Introduction
Classes
  Class template `enum_`
    Class template `enum_` synopsis
    Class template `enum_` constructors
    Class template `enum_` modifier functions
Example(s)

## Introduction

`<boost/python/enum.hpp>` defines the interface through which users expose their C++ enumeration types to Python. It declares the `enum_` class template, which is parameterized on the enumeration type being exposed.

## Classes

### Class template `enum_<T>`

Creates a Python class derived from Python's `int` type which is associated with the C++ type passed as its first parameter.

#### Class template `enum_` synopsis

    namespace boost { namespace python
    {
      template <class T>
      class enum_ : public object
      {
        enum_(char const* name);
        enum_<T>& value(char const* name, T);
        enum_<T>& export_values();
      };
    }}

#### Class template `enum_` constructors

    enum_(char const* name);

Requires: `name` is an ntbs which conforms to Python's identifier naming rules.
Effects: Constructs an `enum_` object holding a Python extension type derived from `int` which is named `name`. The `name`d attribute of the current scope is bound to the new extension type.

#### Class template `enum_` modifier functions

    inline enum_<T>& value(char const* name, T x);

Requires: `name` is an ntbs which conforms to Python's identifier naming rules.
Effects: adds an instance of the wrapped enumeration type with value `x` to the type's dictionary as the `name`d attribute
.
Returns: `*this`

    inline enum_<T>& export_values();

Effects: sets attributes in the current `scope` with the same names and values as all enumeration values exposed so far by calling `value()`
.
Returns: `*this`

## Example(s)

C++ module definition

    #include <boost/python/enum.hpp>
    #include <boost/python/def.hpp>
    #include <boost/python/module.hpp>

    using namespace boost::python;

    enum color { red = 1, green = 2, blue = 4 };

    color identity_(color x) { return x; }

    BOOST_PYTHON_MODULE(enums)
    {
        enum_<color>("color")
            .value("red", red)
            .value("green", green)
            .export_values()
            .value("blue", blue)
            ;

        def("identity", identity_);
    }

Interactive Python:

    >>> from enums import *

    >>> identity(red)
    enums.color.red

    >>> identity(color.red)
    enums.color.red

    >>> identity(green)
    enums.color.green

    >>> identity(color.green)
    enums.color.green

    >>> identity(blue)
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    NameError: name blue' is not defined

    >>> identity(color.blue)
    enums.color.blue

    >>> identity(color(1))
    enums.color.red

    >>> identity(color(2))
    enums.color.green

    >>> identity(color(3))
    enums.color(3)

    >>> identity(color(4))
    enums.color.blue

    >>> identity(1)
    Traceback (most recent call last):
      File "<stdin>", line 1, in ?
    TypeError: bad argument type for built-in operation

Revised 13 December, 2002

© Copyright Dave Abrahams 2002.