diff --git a/doc/v2/definitions.html b/doc/v2/definitions.html index 5c21e86e..f36dc284 100644 --- a/doc/v2/definitions.html +++ b/doc/v2/definitions.html @@ -34,26 +34,49 @@ hidden "this" argument to member functions is not counted when specifying arity +

+
+
ntbs: Null-Terminated Byte String, or `C'-string. C++ string literals are ntbses. An ntbs must never be null.
+

+
+
raise: Exceptions in Python are - "raised", not "thrown", as they are in - C++. When this documentation says that some Python exception is - "raised" in the context of C++ code, it means that the - corresponding Python exception is set via the Python/'C' - API, and throw_error_already_set() + "raised", not "thrown", as they are in C++. When this documentation + says that some Python exception is "raised" in the context of C++ code, + it means that the corresponding Python exception is set via the Python/'C' + API, and throw_error_already_set() is called.
+

+
+ +
POD: A technical term from the C++ + standard. Short for "Plain Ol'Data": A POD-struct is an aggregate class + that has no non-static data members of type pointer to member, + non-POD-struct, non-POD-union (or array of such types) or reference, + and has no user-defined copy assign- ment operator and no user-defined + destructor. Similarly, a POD-union is an aggregate union that has no + non-static data members of type pointer to member, non-POD-struct, + non-POD-union (or array of such types) or reference, and has no + user-defined copy assignment operator and no user-defined destructor. A + POD class is a class that is either a POD-struct or a POD-union. An + aggregate is an array or a class (clause 9) with no user-declared + constructors (12.1), no private or protected non-static data members + (clause 11), no base classes (clause 10), and no virtual functions + (10.3).

Revised - 30 September, 2002 + 03 October, 2002

diff --git a/doc/v2/handle.html b/doc/v2/handle.html new file mode 100644 index 00000000..2c0ffcc2 --- /dev/null +++ b/doc/v2/handle.html @@ -0,0 +1,322 @@ + + + + + + + + + Boost.Python - <boost/python/handle.hpp> + + + + + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/handle.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class template + handle
+ +
+
+
Class handle + synopsis
+ +
Class handle + constructors and destructor
+ +
Class handle + modifier functions
+ +
Class handle + observer functions
+
+
+
+
+ +
Functions
+ +
+
+
borrowed
+ +
allow_null
+
+
+ +
+
+ +

Introduction

+ +

<boost/python/handle.hpp> provides + class template handle, a smart pointer for + managing reference-counted Python objects.

+ +

Classes

+ +

Class template handle

+ +

handle is a smart pointer to a Python object type; it + holds a pointer of type T*, where T is its template + parameter. T must be either a type derived from + PyObject or a POD + type whose initial sizeof(PyObject) bytes are + layout-compatible with PyObject. Use + handle<> at the boundary between tehe + Python/'C' API and high-level code; prefer object for a generalized + interface to Python objects. + +

In this document, the term "upcast" refers to an + operation which converts a pointer Y* to a base class + pointer T* via static_cast<T*> if + Y is derived from T, or via C-style cast + (T*) if it is not. However, in the latter case the "upcast" + is ill-formed if the initial sizeof(PyObject) bytes of + Y are not layout-compatible with PyObject.

+ +

Class template handle + synopsis

+
+namespace boost { namespace python
+{
+  template <class T>
+  class handle
+  {
+      typedef unspecified-member-function-pointer bool_type;
+
+   public: // types
+      typedef T element_type;
+
+   public: // member functions
+      ~handle();
+
+      template <class Y>
+      explicit handle(detail::borrowed<null_ok<Y> >* p);
+
+      template <class Y>
+      explicit handle(null_ok<detail::borrowed<Y> >* p);
+
+      template <class Y>
+      explicit handle(detail::borrowed<Y>* p);
+
+      template <class Y>
+      explicit handle(null_ok<Y>* p);
+
+      template <class Y>
+      explicit handle(Y* p);
+
+      handle();
+
+      handle& operator=(handle const& r);
+
+      template<typename Y>
+      handle& operator=(handle<Y> const & r); // never throws
+
+
+      template <typename Y>
+      handle(handle<Y> const& r);
+
+      handle(handle const& r);
+
+      T* operator-> () const;
+      T& operator* () const;
+      T* get() const;
+      T* release();
+
+      operator bool_type() const; // never throws
+   private:
+      T* m_p;
+  };
+  
+  template <class T> struct null_ok;
+  namespace detail { template <class T> struct borrowed; }
+}}
+
+ +

Class handle constructors + and destructor

+
+virtual ~handle();
+
+ +
+
Effects: Py_XDECREF(m_p)
+
+
+template <class Y>
+explicit handle(detail::borrowed<null_ok<Y> >* p);
+
+ +
+
Effects: Py_XDECREF(m_p)
+
+
+template <class Y>
+explicit handle(null_ok<detail::borrowed<Y> >* p);
+
+ +
+
Effects: + m_p = upcast<T*>(p);
+
+
+template <class Y>
+explicit handle(detail::borrowed<Y>* p);
+
+ +
+
Effects: + m_p = upcast<T*>(expect_non_null(p));
+
+
+template <class Y>
+explicit handle(null_ok<Y>* p);
+
+ +
+
Effects: + Py_XINCREF(p); m_p = upcast<T*>(p);
+
+
+template <class Y>
+explicit handle(Y* p);
+
+ +
+
Effects: + Py_XINCREF(p); m_p = upcast<T*>(expect_non_null(p));
+
+
+handle();
+
+ +
+
Effects: m_p = 0;
+
+
+template <typename Y>
+handle(handle<Y> const& r);
+handle(handle const& r);
+
+ +
+
Effects: + m_p = r.m_p; Py_XINCREF(m_p);
+
+ +

Class handle + modifiers

+
+handle& operator=(handle const& r);
+template<typename Y>
+handle& operator=(handle<Y> const & r); // never throws
+
+ +
+
Effects: + Py_XINCREF(r.m_p); Py_XDECREF(m_p); m_p = r.m_p;
+
+
+T* release();
+
+ +
+
Effects: T* x = m_p; m_p = 0;return + x;
+
+ +

Class handle + observers

+
+T* operator-> () const;
+T* get() const;
+
+ +
+
Returns: m_p;
+
+
+T& operator* () const;
+
+ +
+
Returns: *m_p;
+
+
+operator bool_type() const; // never throws
+
+ +
+
Returns: 0 if m_p == 0, a pointer + convertible to true otherwise.
+
+ +

Functions

+ +

borrowed

+
+template 
+detail::borrowed* borrowed(T* p)
+{
+    return (detail::borrowed*)p;
+}
+
+ +

allow_null

+ +
+template 
+null_ok* allow_null(T* p)
+{
+    return (null_ok*)p;
+}
+
+ + +

Revised + + 03 October, 2002 +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ + + diff --git a/doc/v2/reference.html b/doc/v2/reference.html index 0ec9b86c..0923a434 100644 --- a/doc/v2/reference.html +++ b/doc/v2/reference.html @@ -771,24 +771,26 @@ -
reference.hpp
+
handle.hpp
-
Classes
+
Classes
reference
+ "handle.html#handle-spec">handle
- -
Types
+
Functions
-
ref
+
borrowed
+
allow_null