1[section Indexing support] 2[section Introduction] 3Indexing 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`). 4 5While `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, [@http://www.python.org/doc/current/ref/sequence-types.html 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__`. 6 7The goals: 8 9* Make indexable C++ containers behave exactly as one would expect a Python container to behave. 10* Provide default reference semantics for container element indexing (`__getitem__`) such that c[i] can be mutable. Require: 11 12 `` 13 val = c[i] 14 c[i].m() 15 val == c[i] 16 `` 17 18 where m is a non-const (mutating) member function (method). 19* Return safe references from `__getitem__` such that subsequent adds and deletes to and from the container will not result in dangling references (will not crash Python). 20* Support slice indexes. 21* Accept Python container arguments (e.g. `lists`, `tuples`) wherever appropriate. 22* Allow for extensibility through re-definable policy classes. 23* Provide predefined support for the most common STL and STL-like indexable containers. 24 25[endsect] 26[section The Indexing Interface] 27The `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): 28 29[variablelist 30[[__len__(self)] 31 [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.]] 32[[__getitem__(self, key)] 33[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.]]] 34[[__setitem__(self, key, value)] 35 [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.]] 36[[__delitem__(self, key)] 37 [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.]] 38[[__iter__(self)] 39 [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(). 40 41Iterator objects also need to implement this method; they are required to return themselves. For more information on iterator objects, see [@https://docs.python.org/3/library/stdtypes.html#iterator-types Iterator Types] in the [@https://docs.python.org/3/library/index.html Python Library Reference].]] 42 43[[__contains__(self, item)] 44 [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.]] 45 ] 46[endsect] 47[section index_suite sub-classes] 48The `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. 49[section vector_index_suite] 50The `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`. 51 52Example usage: 53`` 54class X {...}; 55... 56class_<std::vector<X> >("XVec") 57 .def(vector_indexing_suite<std::vector<X> >()) 58; 59`` 60 61XVec is now a full-fledged Python container (see the example in full, along with its python test). 62[endsect] 63[section map_index_suite] 64The `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`. 65 66Example usage: 67 68`` 69class X {...}; 70... 71 72class_<std::map<X> >("XMap") 73 .def(map_indexing_suite<std::map<X> >()) 74; 75`` 76 77By 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). 78[endsect] 79[endsect] 80[section `indexing_suite` class] 81[table 82[[Template Parameter][Requirements][Semantics][Default]] 83[[Container][A class type][ The container type to be wrapped to Python. ][]] 84[[DerivedPolicies][A subclass of indexing_suite][ Derived classes provide the policy hooks. See DerivedPolicies below. ][]] 85[[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. ][false]] 86[[NoSlice][A boolean][ Do not allow slicing. ][false]] 87[[Data][][The container's data type.][Container::value_type]] 88[[Index][][The container's index type.][Container::size_type]] 89[[Key][][The container's key type.][Container::value_type]] 90] 91`` 92template <class Container, 93 class DerivedPolicies, 94 bool NoProxy = false, 95 bool NoSlice = false, 96 class Data = typename Container::value_type, 97 class Index = typename Container::size_type, 98 class Key = typename Container::value_type> 99class indexing_suite : unspecified 100{ 101public: 102 indexing_suite(); // default constructor 103} 104`` 105[section DerivedPolicies] 106 107Derived classes provide the hooks needed by the indexing_suite: 108`` 109data_type& 110get_item(Container& container, index_type i); 111 112static object 113get_slice(Container& container, index_type from, index_type to); 114 115static void 116set_item(Container& container, index_type i, data_type const& v); 117 118static void 119set_slice( 120 Container& container, index_type from, 121 index_type to, data_type const& v 122); 123 124template <class Iter> 125static void 126set_slice(Container& container, index_type from, 127 index_type to, Iter first, Iter last 128); 129 130static void 131delete_item(Container& container, index_type i); 132 133static void 134delete_slice(Container& container, index_type from, index_type to); 135 136static size_t 137size(Container& container); 138 139template <class T> 140static bool 141contains(Container& container, T const& val); 142 143static index_type 144convert_index(Container& container, PyObject* i); 145 146static index_type 147adjust_index(index_type current, index_type from, 148 index_type to, size_type len); 149`` 150 151Most of these policies are self explanatory. However, convert_index and adjust_index deserve some explanation. 152 153convert_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. 154 155When 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: 156 157`` 158 [a][b][c][d][e] ---> [d][e] 159 ^ ^ 160 4 1 161`` 162 163adjust_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. 164[endsect] 165[endsect] 166[section class `vector_indexing_suite`] 167[table 168[[Template Parameter][Requirements][Semantics][Default]] 169[[Container][A class type][ The container type to be wrapped to Python. ][]] 170[[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. ][false]] 171[[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 ][]] 172] 173`` 174template <class Container, 175 bool NoProxy = false, 176 class DerivedPolicies = unspecified_default> 177class vector_indexing_suite : unspecified_base 178{ 179public: 180 181 typedef typename Container::value_type data_type; 182 typedef typename Container::value_type key_type; 183 typedef typename Container::size_type index_type; 184 typedef typename Container::size_type size_type; 185 typedef typename Container::difference_type difference_type; 186 187 data_type& 188 get_item(Container& container, index_type i); 189 190 static object 191 get_slice(Container& container, index_type from, index_type to); 192 193 static void 194 set_item(Container& container, index_type i, data_type const& v); 195 196 static void 197 set_slice(Container& container, index_type from, 198 index_type to, data_type const& v); 199 200 template <class Iter> 201 static void 202 set_slice(Container& container, index_type from, 203 index_type to, Iter first, Iter last); 204 205 static void 206 delete_item(Container& container, index_type i); 207 208 static void 209 delete_slice(Container& container, index_type from, index_type to); 210 211 static size_t 212 size(Container& container); 213 214 static bool 215 contains(Container& container, key_type const& key); 216 217 static index_type 218 convert_index(Container& container, PyObject* i); 219 220 static index_type 221 adjust_index(index_type current, index_type from, 222 index_type to, size_type len); 223}; 224`` 225[endsect] 226[section class `map_indexing_suite`] 227[table 228[[Template Parameter][Requirements][Semantics][Default]] 229[[Container][ A class type ][ The container type to be wrapped to Python. ][]] 230[[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. ][ false ]] 231[[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 ][]] 232] 233`` 234template <class Container, 235 bool NoProxy = false, 236 class DerivedPolicies = unspecified_default> 237class map_indexing_suite : unspecified_base 238{ 239public: 240 241 typedef typename Container::value_type value_type; 242 typedef typename Container::value_type::second_type data_type; 243 typedef typename Container::key_type key_type; 244 typedef typename Container::key_type index_type; 245 typedef typename Container::size_type size_type; 246 typedef typename Container::difference_type difference_type; 247 248 static data_type& 249 get_item(Container& container, index_type i); 250 251 static void 252 set_item(Container& container, index_type i, data_type const& v); 253 254 static void 255 delete_item(Container& container, index_type i); 256 257 static size_t 258 size(Container& container); 259 260 static bool 261 contains(Container& container, key_type const& key); 262 263 static bool 264 compare_index(Container& container, index_type a, index_type b); 265 266 static index_type 267 convert_index(Container& container, PyObject* i); 268}; 269`` 270[endsect] 271[endsect] 272