C++ Boost

Boost.Python

Headers <boost/python/indexing/indexing_suite.hpp>
<boost/python/indexing/vector_indexing_suite.hpp>


Contents

Introduction
Interface
indexing_suite
indexing_suite sub-classes
vector_indexing_suite
indexing_suite class
vector_indexing_suite class
map_indexing_suite class

Introduction

Indexing is a Boost Python facility for easy exportation of indexable C++ containers to Python. Indexable containers are containers that allow random access through the operator[] (e.g. std::vector).

˷ҽ㨉ndexing㩊ǒ떖Boost Pythonɨʩ㬍 ˼ʇΪK罱㏲Python弳濉˷ҽ儃++ȝƷᣍ 璽㨩ndexable㩈݆奔㬍 Ԋͨ齯perator[]˦뺷IʵĈ݆磨ȧstd::vector㩡㍊

While Boost Python has all the facilities needed to expose indexable C++ containers such as the ubiquitous std::vector to Python, the procedure is not as straightforward as we'd like it to be. Python containers do not map easily to C++ containers. Emulating Python containers in C++ (see Python Reference Manual, Emulating container types) using Boost Python is non trivial. There are a lot of issues to consider before we can map a C++ container to Python. These involve implementing wrapper functions for the methods __len__, __getitem__, __setitem__, __delitem__, __iter__ and __contains.

ˤȻBoost Pythonґߓ뇐ᘒꉨʩ㬍 Ĝ黏␹thon弳濉˷ҽC++ȝƷ 㨀툧Ξ˹⻔ڵijtd::vector㩣썊 嫵쳶齳̲빻첵塣 PythonȝƷ⢲넜ǡ¯ӳɤ彃++ȝƷᣍ ʹӃBoost PythonԚC++֐ģĢPythonȝƷ㨼됹thon⎿슖⡣켡 href= "http://www.python.org/doc/current/ref/sequence-types.html">Emulating container types㩲ⲻ첵塣 ϲPythonӳɤC++ȝƷ֮ǰ㬓ܶΊ̢Ҫ〞ǡ㍊ Ƥ֐ɦ찎꒔ς罷芵ϖ碗ຯʽ㺍 __len__ᢼstrong>__getitem__ᢍ __setitem__ᢼstrong>__delitem__ᢍ __iter__㬺ͼstrong>__containsᣍ

The goals:

Ŀ᪣ꍊ


The Boost.Python Indexing Interface

indexing_suite [ Header <boost/python/indexing/indexing_suite.hpp> ]

The indexing_suite class is the base class for the management of C++ containers intended to be integrated to Python. The objective is make a C++ container look and feel and behave exactly as we'd expect a Python container. The class automatically wraps these special Python methods (taken from the Python reference: Emulating container types):

indexing_suite ʇһ趻造㬍 ӃӚ需퓻쯳ɵ퐹thon儃++ȝƷᣍ ƤĿ᪊ǣ승C++ȝƷ儹۸͐ЎꓫΒC˹ƚ併ĐythonȝƷͪȫһւᣍ 脹ה毷◰բ̘ʢ儐ython罷裨ȡהPython⎿슖⡣꼡 href= "http://www.python.org/doc/current/ref/sequence-types.html">Emulating container types㩣ꍊ

__len__(self)
Called to implement the built-in function len()  Should return the length of the object, an integer >= 0. Also, an object that doesn't define a __nonzero__() method and whose __len__() method returns zero is considered to be false in a Boolean context.  

ִĚփꯊt class="function">len()ᣍ Ӧ絻ضԏ㳤戣싼ʇ>= 0 儕늽ᣍ 䋍⣬ȧ黶ԏ㎴樒弴t class= "method">__nonzero__()罷裬 ⢇Ҽtt class= "method">__len__()罷踐똁㣬 Բ膠ԏ㔚⼶뉏ς΄֐Ịӎꦡlseᣍ

__getitem__(self, key)
Called to implement evaluation of self[key]. For sequence types, the accepted keys should be integers and slice objects.  Note that the special interpretation of negative indexes (if the class wishes to emulate a sequence type) is up to the __getitem__() method. If key is of an inappropriate type, TypeError may be raised; if of a value outside the set of indexes for the sequence (after any special interpretation of negative values), IndexError should be raised. Note: for loops expect that an IndexError will be raised for illegal indexes to allow proper detection of the end of the sequence.

ִself[key]dzֵᣍ 攓ڐ⁐ Ѝ㬿ɽӊܵīeyӦ胊Ǖ늽ꍳlice攏㡣 עҢ㬣舧黀ӻģĢP Ѝ㩣썊 攸ꊽ˷ҽ儌؊⽢ʍʇӉ __getitem__()罷踺԰儡㍊ ȧ黼var>keyʇ䭎〠Ѝ㬍 ԒTypeError㻍 ȧ黋璽ֵ㨔ڶԸꖵ팘ʢ͖㩔㬍 Ӧ胒IndexErrorע㺼/b> forѭ뷒ꇳ 燷甘ҽŗ㶼tt class= "exception">IndexError㬍 Ҕսȷ쬲␲P衣

__setitem__(self, key, value)
Called to implement assignment to self[key]. Same note as for __getitem__(). This should only be implemented for mappings if the objects support changes to the values for keys, or if new keys can be added, or for sequences if elements can be replaced. The same exceptions should be raised for improper key values as for the __getitem__() method.

捍code>self[key]賒塣 עҢʂϮӫ__getitem__()Ϡͬᣍ Ӧ能措䋀ӳɤʵϖ㺍 攏㖧㖸츄key˹攓淨ֵ㬍 법߿ɒԌЂ豪ey㬍 법ߐ⁐儔ꋘԱ댦뻡㍊ 攓ڲ땽ȷ儼var>keyֵ㬍 Ӧҽ碓뼴t class= "method">__getitem__()罷荬ѹ儒쳣ᣍ

__delitem__(self, key)
Called to implement deletion of self[key]. Same note as for __getitem__(). This should only be implemented for mappings if the objects support removal of keys, or for sequences if elements can be removed from the sequence. The same exceptions should be raised for improper key values as for the __getitem__() method.

ɾ㽼code>self[key]ᣍ עҢʂϮӫ__getitem__()Ϡͬᣍ Ӧ能措䋀ӳɤʵϖ㺍 攏㖧㖉key㬍 법ߔꋘ뉾㽵Đ⁐ᣍ 攲땽ȷ儼var>key㬍 Ӧҽ碓뼴t class="method">__getitem__()罷菠ͬ儒쳣ᣍ

__iter__(self)
This method is called when an iterator is required for a container. This method should return a new iterator object that can iterate over all the objects in the container. For mappings, it should iterate over the keys of the container, and should also be made available as the method iterkeys().

胸ԚȝƷҪ弴ꆷʱ巔a㍊ 胸Ӧ絻ؒ븶Ђ儵촺Ʒ攏㣬 胵촺ƷԱ遠ȝƷ֐˹Ӑ攜ԏ㡣 攓ړ㉤㬋쓦ᩀꈝƷ儼억㬍 ⢇Ғ⿉ͨ齷iterkeys()̡驡㍊

Iterator objects also need to implement this method; they are required to return themselves. For more information on iterator objects, see ``Iterator Types'' in the Python Library Reference.

弴ꆷ攏㒲Ӑᘒꊵϖ胸㬍 ˼Cᘐ뷵똋샇הɭᣍ 弴ꆷ攏㵄輶ЅϢ㬇뼻 PythonΒ튖⡼/a> ֐傻 ᰼a class="ulink" href= "http://www.python.org/doc/current/lib/typeiter.html">Iterator Typesᱡ㍊

__contains__(self, item)
Called to implement membership test operators. Should return true if item is in self, false otherwise. For mapping objects, this should consider the keys of the mapping rather than the values or the key-item pairs.

ִ㉔Ტʔ♗硣 ȧitemԚself֐Բ絻ؕ棬籔ⷵ똼١㍊ 攓ړ㉤攏㣬Ӧ胿삇ӳɤ儼죬兗ǖ廲嶔ᣍ

indexing_suite sub-classes

The indexing_suite is not meant to be used as is. A couple of policy functions must be supplied by subclasses of indexing_suite. However, a set of indexing_suite subclasses for the standard indexable STL containers will be provided, In most cases, we can simply use the available predefined suites. In some cases, we can refine the predefined suites to suit our needs.

indexing_suite⻄ܖὓʹӃᣠ ᘐ덨齼̳tt>indexing_suite̡駝踶⟂Ժᣍ ⻹攓ڿɋ璽儱ꗼSTLȝƷ㬍 롌ṩһ̗indexing_suiteד ᣍ Ԛ䳶ʽǩﶏ£쎒CԼⵥ嘀듃ϖӐ儔䶨ҥsuiteᣍ Ԛijǩﶏ£쎒CԐ޸Ĕ䶨ҥsuite㬒ԂꗣΒC儐蒪ᣍ

vector_indexing_suite [ Header <boost/python/indexing/vector_indexing_suite.hpp> ]

The vector_indexing_suite class is a predefined indexing_suite derived class designed to wrap std::vector (and std::vector like [i.e. a class with std::vector interface]) classes. It provides all the policies required by the indexing_suite.

vector_indexing_suite ʇԤ樒嵄 indexing_suiteʼnɺ 㬍 ּԚ碗༴t>std::vector 㨺̀༴t>std::vector [촾ߓtd::vector퓿ڵĀݩᣍ ˼̡驁˼tt>indexing_suiteҪdz儋銬⟂ԡ㍊

Example usage:

Ӄ=㺍

    class X {...};
    ...

    class_<std::vector<X> >("XVec")
        .def(vector_indexing_suite<std::vector<X> >())
    ;

XVec is now a full-fledged Python container (see the example in full, along with its python test).

XVecϖԚ休˒븶ͪȫ儐ythonȝƷ㨼덊 ͪջ儀헓㬍 빓Ћ쵄python⢊ԍ 㩡㍊

map_indexing_suite [ Header <boost/python/indexing/map_indexing_suite.hpp> ]

The map_indexing_suite class is a predefined indexing_suite derived class designed to wrap std::map (and std::map like [i.e. a class with std::map interface]) classes. It provides all the policies required by the indexing_suite.

map_indexing_suite Ԥ樒嵄indexing_suiteʼnɺ 㬍 ּԚ碗༴t>std::map 㨺̀༴t>std::map [촾ߓtd::map퓿ڵĀݣ顣 ˼̡驁˼tt>indexing_suiteҪdz儋銬⟂ԡ㍊

Example usage:

Ӄ=㺍

    class X {...};
    ...

    class_<std::map<X> >("XMap")
        .def(map_indexing_suite<std::map<X> >())
    ;

By default indexed elements are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter. XMap is now a full-fledged Python container (see the example in full, along with its python test).

Ĭȏǩﶏ£챻˷ҽ儔ꋘʇӉ龜똵ġ㍊ բԍ蹽ԚNoProxyģॲΊ햐̡駝tt>true4a㍊ XMapϖԚ休˒븶ͪȫ儐ythonȝƷ 㨼뼡 href="../../test/map_indexing_suite.cpp">ͪջ儀헓㬍 빓Ћ쵄python⢊Լ/a>㩡㍊


indexing_suite class

indexing_suite<
class Container
, class DerivedPolicies
, bool NoProxy
, bool NoSlice
, class Data
, class Index
, class Key

Template Parameter
Requirements Semantics Default
Container A class type The container type to be wrapped to Python.

佷◰ython儈݆瀠Ѝᣍ

 
DerivedPolicies A subclass of indexing_suite Derived classes provide the policy hooks. See DerivedPolicies below.

ʼnɺ ̡馹߂Թ㗓᣼돂a儼a href= "#DerivedPolicies">DerivedPolicies

 
NoProxy A boolean By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter.

Ĭȏǩﶏ£챻˷ҽ儔ꋘythonҽӃӯҥ㬲Ⓣ龜똡㕢ԍ蹽Ԛ NoProxyģॲΊ햐̡駝strong>true4a㠍

false
NoSlice A boolean Do not allow slicing.

⻔ʐƬᣍ

false
Data   The container's data type.

ȝƷ儊 Ѝᣍ

Container::value_type
Index   The container's index type.

ȝƷ儋璽 Ѝᣍ

Container::size_type
Key   The container's key type.

ȝƷ儼쀠Ѝᣍ

Container::value_type
    template <
class Container , class DerivedPolicies , bool NoProxy = false
, bool NoSlice = false , class Data = typename Container::value_type , class Index = typename Container::size_type , class Key = typename Container::value_type >
class indexing_suite : unspecified { public: indexing_suite(); // default constructor }

DerivedPolicies

Derived classes provide the hooks needed by the indexing_suite:

ʼnɺ ̡駝tt>indexing_suite˹儹㗓ꯊ

        data_type&
        get_item(Container& container, index_type i);

        static object
        get_slice(Container& container, index_type from, index_type to);

        static void
        set_item(Container& container, index_type i, data_type const& v);

        static void
        set_slice(
            Container& container, index_type from,
            index_type to, data_type const& v
        );

        template <class Iter>
        static void
set_slice(Container& container, index_type from, index_type to, Iter first, Iter last ); static void delete_item(Container& container, index_type i); static void delete_slice(Container& container, index_type from, index_type to); static size_t size(Container& container); template <class T> static bool contains(Container& container, T const& val); static index_type convert_index(Container& container, PyObject* i); static index_type adjust_index(index_type current, index_type from, index_type to, size_type len );

Most of these policies are self explanatory. However, convert_index and adjust_index deserve some explanation.

բ⟂ԵĴ㶠ʽʇ⻽◔÷儡㍊ 嫼tt>convert_indexadjust_indexֵ僗琩͡㍊

convert_index converts a Python index into a C++ index that the container can handle. For instance, negative indexes in Python, by convention, start counting from the right(e.g. C[-1] indexes the rightmost element in C). convert_index should handle the necessary conversion for the C++ container (e.g. convert -1 to C.size()-1). convert_index should also be able to convert the type of the index (A dynamic Python type) to the actual type that the C++ container expects.

convert_index ython˷ҽת뻳Ɉ݆翉䦀C++˷ҽᣍ =ȧPython֐儸ꋷҽ㬰䕕馶芇䓓ұ߿ꊼ傻 㨈繳t>C[-1]˷ҽ儊Ǽtt>C׮Ӓ៵Ĕꋘ㩡㍊ convert_indexӦ胎ꃫ+ȝƷ䦀Ҫ儗껻 㨈簑-1ת뻎꼴t>C.size()-1㩡㍊ convert_indexҲӦ胄ܹ밑˷ҽ儀Ѝ 㨶儐ython Ѝ㩣엪뻎ꃫ+ȝƷƚͻ儊弊 Ѝᣍ

When a container expands or contracts, held indexes to its elements must be adjusted to follow the movement of data. For instance, if we erase 3 elements, starting from index 0 from a 5 element vector, what used to be at index 4 will now be at index 1:

屈݆瀩䳻⋵ʱ㬳֓Ĕꋘ˷ҽᘐ뵷ջ㬍 Ҕ躋抽Ēƶ =ȧ㬈繻䓵趔ꋘ攜ector֐㬴Ӌ璽0慠쉾㽳趔ꋘ㬍 ԭ4儋璽4ᎻӚ˷ҽ1㺍

    [a][b][c][d][e] ---> [d][e]
                 ^           ^
                 4           1

adjust_index takes care of the adjustment. Given a current index, the function should return the adjusted index when data in the container at index from..to is replaced by len elements.

adjust_index䦀핢֖巕롣 屈݆疐儊 ഋ璽from..to̦뻎꼴t>len趔ꋘ㬍 ʤȫ屇˷ҽcurrent㬍 ꯊ퓦胸廘巕뺳儋璽ᣍ


vector_indexing_suite class

Class template
vector_indexing_suite<
class Container
, bool NoProxy
, class DerivedPolicies>

Template Parameter
Requirements Semantics Default
Container A class type The container type to be wrapped to Python.

佷◰ython儈݆瀠Ѝᣍ

 
NoProxy A boolean By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter.

Ĭȏǩﶏ£챻˷ҽ儔ꋘythonҽӃӯҥ㬲Ⓣ龜똡㍊ բԍ蹽ԚNoProxyģॲΊ햐 ̡駝strong>true4a㍊

false
DerivedPolicies A subclass of indexing_suite The vector_indexing_suite may still be derived to further tweak any of the predefined policies. Static polymorphism through CRTP (James Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995) enables the base indexing_suite class to call policy function of the most derived class

vector_indexing_suiteȔ蹽ʼnɺ 벽巕눎ꎔ䶨ҥ儲߂ԡ㍊ ͨ齃RTP㨊ames Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995㩵ľ⌬櫨쐔㬍 ʹindexing_suite빀࿉Ĝ巔×ʼnɺ 儲߂Ժᣍ

 
    template <
class Container,
bool NoProxy = false,
class DerivedPolicies = unspecified_default
class vector_indexing_suite : unspecified_base
{
public:

typedef typename Container::value_type data_type;
typedef typename Container::value_type key_type;
typedef typename Container::size_type index_type;
typedef typename Container::size_type size_type;
typedef typename Container::difference_type difference_type;

data_type&
get_item(Container& container, index_type i); static object get_slice(Container& container, index_type from, index_type to); static void
set_item(Container& container, index_type i, data_type const& v); static void set_slice(Container& container, index_type from, index_type to, data_type const& v); template <class Iter>
static void
set_slice(Container& container, index_type from,
index_type to, Iter first, Iter last); static void delete_item(Container& container, index_type i); static void delete_slice(Container& container, index_type from, index_type to);
static size_t size(Container& container); static bool contains(Container& container, key_type const& key); static index_type convert_index(Container& container, PyObject* i); static index_type adjust_index(index_type current, index_type from, index_type to, size_type len); };

map_indexing_suite class

Class template
map_indexing_suite<
class Container
, bool NoProxy
, class DerivedPolicies>

Template Parameter
Requirements Semantics Default
Container A class type The container type to be wrapped to Python.

佷◰ython儈݆瀠ᣍ

 
NoProxy A boolean By default indexed elements have Python reference semantics and are returned by proxy. This can be disabled by supplying true in the NoProxy template parameter.

Ĭȏǩﶏ£챻˷ҽ儔ꋘythonҽӃӯҥ㬲Ⓣ龜똡㍊ բԍ蹽ԚNoProxyģॲΊ햐 ̡駝strong>true4a㍊

false
DerivedPolicies A subclass of indexing_suite The vector_indexing_suite may still be derived to further tweak any of the predefined policies. Static polymorphism through CRTP (James Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995) enables the base indexing_suite class to call policy function of the most derived class

vector_indexing_suiteȔ蹽ʼnɺ 벽巕눎ꎔ䶨ҥ儲߂ԡ㍊ ͨ齃RTP㨊ames Coplien. "Curiously Recurring Template Pattern". C++ Report, Feb. 1995㩵ľ⌬櫨쐔㬍 ʹindexing_suite빀࿉Ĝ巔×ʼnɺ 儲߂Ժᣍ

 
    template <
class Container,
bool NoProxy = false,
class DerivedPolicies = unspecified_default
class map_indexing_suite : unspecified_base
{
public:

typedef typename Container::value_type value_type;
typedef typename Container::value_type::second_type data_type;
typedef typename Container::key_type key_type;
typedef typename Container::key_type index_type;
typedef typename Container::size_type size_type;
typedef typename Container::difference_type difference_type;

static data_type&
get_item(Container& container, index_type i); static void
set_item(Container& container, index_type i, data_type const& v); static void delete_item(Container& container, index_type i);
static size_t size(Container& container); static bool contains(Container& container, key_type const& key); static bool
compare_index(Container& container, index_type a, index_type b);
static index_type convert_index(Container& container, PyObject* i); };

© Copyright Joel de Guzman 2003. Permission to copy, use, modify, sell and distribute this document is granted provided this copyright notice appears in all copies. This document is provided "as is" without express or implied warranty, and with no claim as to its suitability for any purpose.

筒룺켯a>

ҫ΄輐£결08.6.5