ceph/src/boost/libs/python/doc/reference/enum.qbk

   1 [section boost/python/enum.hpp]
   2 [section Introduction]
   3 <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.
   4 [endsect]
   5 [section Class template `enum_`]
   6 Creates a Python class derived from Python's `int` type which is associated with the C++ type passed as its first parameter.
   7 ``
   8 namespace boost { namespace python
   9 {
  10   template <class T>
  11   class enum_ : public object
  12   {
  13     enum_(char const* name, char const* doc = 0);
  14     enum_<T>& value(char const* name, T);
  15     enum_<T>& export_values();
  16   };
  17 }}
  18 ``
  19 [endsect]
  20 [section Class template `enum_` constructors]
  21 ``enum_(char const* name, char const* doc=0);``
  22 [variablelist
  23 [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules].]]
  24 [[Effects][Constructs an `enum_` object holding a Python extension type derived from `int` which is named `name`. The named attribute of the [link high_level_components.boost_python_scope_hpp current scope] is bound to the new extension type.]]
  25 ]
  26 [endsect]
  27 [section Class template `enum_` modifier functions]
  28 ``enum_<T>& value(char const* name, T x);``
  29 [variablelist
  30 [[Requires][name is an [link ntbs] which conforms to Python's [@http://www.python.org/doc/current/ref/identifiers.html identifier naming rules].]]
  31 [[Effects][adds an instance of the wrapped enumeration type with value x to the type's dictionary as the named attribute.]]
  32 [[Returns][`*this`]]
  33 ]
  34 ``enum_<T>& export_values();``
  35 [variablelist
  36 [[Effects][sets attributes in the [link high_level_components.boost_python_scope_hpp current scope] with the same names and values as all enumeration values exposed so far by calling value().]]
  37 [[Returns][`*this`]]
  38 ]
  39 [endsect]
  40 [section Example]
  41 C++ module definition
  42 ``
  43 #include <boost/python/enum.hpp>
  44 #include <boost/python/def.hpp>
  45 #include <boost/python/module.hpp>
  46
  47 using namespace boost::python;
  48
  49 enum color { red = 1, green = 2, blue = 4 };
  50
  51 color identity_(color x) { return x; }
  52
  53 BOOST_PYTHON_MODULE(enums)
  54 {
  55   enum_<color>("color")
  56     .value("red", red)
  57     .value("green", green)
  58     .export_values()
  59     .value("blue", blue)
  60     ;
  61
  62   def("identity", identity_);
  63 }
  64 ``
  65 Interactive Python:
  66 ``
  67 >>> from enums import *
  68
  69 >>> identity(red)
  70 enums.color.red
  71
  72 >>> identity(color.red)
  73 enums.color.red
  74
  75 >>> identity(green)
  76 enums.color.green
  77
  78 >>> identity(color.green)
  79 enums.color.green
  80
  81 >>> identity(blue)
  82 Traceback (most recent call last):
  83   File "<stdin>", line 1, in ?
  84 NameError: name 'blue' is not defined
  85
  86 >>> identity(color.blue)
  87 enums.color.blue
  88
  89 >>> identity(color(1))
  90 enums.color.red
  91
  92 >>> identity(color(2))
  93 enums.color.green
  94
  95 >>> identity(color(3))
  96 enums.color(3)
  97
  98 >>> identity(color(4))
  99 enums.color.blue
 100
 101 >>> identity(1)
 102 Traceback (most recent call last):
 103   File "<stdin>", line 1, in ?
 104 TypeError: bad argument type for built-in operation
 105 ``
 106 [endsect]
 107 [endsect]