From fed2ef5d64392a100f09ff59afff7bfb4c6ba7ce Mon Sep 17 00:00:00 2001
From: Dave Abrahams <dave@boostpro.com>
Date: Sun, 12 Nov 2000 20:50:48 +0000
Subject: [PATCH] Documented new conversion facilities; went into a little more
 detail.

[SVN r8180]
---
 enums.html | 60 ++++++++++++++++++++++++++++++++++++++----------------
 1 file changed, 43 insertions(+), 17 deletions(-)

diff --git a/enums.html b/enums.html
index 53c88d41..77bfea6a 100644
--- a/enums.html
+++ b/enums.html
@@ -11,18 +11,44 @@
 <p>Because there is in general no way to deduce that a value of arbitrary type T
 is an enumeration constant, py_cpp cannot automatically convert enum values to
 and from Python. To handle this case, you need to decide how you want the enum
-to show up in Python (since Python doesn't have enums). If you are satisfied
-with a Python int as a way to represent your enum values, you can write some
-simple <code>from_python()</code> and <code>to_python()</code> functions in
-<code>namespace py::</code>
+to show up in Python (since Python doesn't have enums). Once you have done that,
+you can write some simple <code>from_python()</code> and
+<code>to_python()</code> functions.
 
-<blockquote><pre>
-#ifndef PY_NO_INLINE_FRIENDS_IN_NAMESPACE // workaround GCC 2.95.2 bug
+<p>If you are satisfied with a Python int as a way to represent your enum
+values, py_cpp provides a shorthand for these functions. You just need to
+instantiate <code>py::enum_as_int_converters&lt;EnumType&gt;</code> where
+<code>EnumType</code> is your enumerated type. There are two convenient ways to do this:
+
+<ol>
+<li><blockquote>
+<pre>
+// drop into namespace py and explicitly instantiate
 namespace py {
-#endif
+  template class enum_as_int_converters<extclass_demo::EnumOwner::enum_type>;
+}
+</pre>
+</blockquote>
+<li><blockquote><pre>
+// instantiate as base class in any namespace
+struct EnumTypeConverters
+    : py::py_enum_as_int_converters<EnumType>
+{
+};
+</blockquote></pre>
+</ol>
 
-  MyEnumType from_python(PyObject* x,
-       py::Type&lt;MyEnumType&gt;)
+<p>Either of the above is equivalent to the following declarations:
+<blockquote><pre>
+PY_BEGIN_CONVERSION_NAMESPACE // this is a gcc 2.95.2 bug workaround
+
+  MyEnumType from_python(PyObject* x, py::Type&lt;MyEnumType&gt;)
+  {
+      return static_cast&lt;MyEnum&gt;(
+        from_python(x, py::Type&lt;long&gt;()));
+  }
+
+  MyEnumType from_python(PyObject* x, py::Type&lt;const MyEnumType&amp;&gt;)
   {
       return static_cast&lt;MyEnum&gt;(
         from_python(x, py::Type&lt;long&gt;()));
@@ -32,13 +58,10 @@ namespace py {
   {
       return to_python(static_cast&lt;long&gt;(x));
   }
-
-#ifndef PY_NO_INLINE_FRIENDS_IN_NAMESPACE
-}
-#endif
-
+PY_END_CONVERSION_NAMESPACE
 </pre></blockquote>
- This technique defines the conversions of
+
+<p>This technique defines the conversions of
 <code>MyEnumType</code> in terms of the conversions for the built-in
  <code>long</code> type.
 
@@ -50,7 +73,10 @@ mymodule.add(py::to_python(enum_value_1), "enum_value_1");
 mymodule.add(py::to_python(enum_value_2), "enum_value_2");
 ...
 </pre></blockquote>
-You can also add these to an extension class definition:
+
+You can also add these to an extension class definition, if your enum happens to
+be local to a class and you want the analogous interface in Python:
+
 <blockquote><pre>
 my_class.add(py::to_python(enum_value_1), "enum_value_1");
 my_class.add(py::to_python(enum_value_2), "enum_value_2");
@@ -63,6 +89,6 @@ my_class.add(py::to_python(enum_value_2), "enum_value_2");
         express or implied warranty, and with no claim as to its suitability
         for any purpose.
       <p>
-         Updated: Nov 5, 2000
+         Updated: Nov 12, 2000
     </div>