Wrapping a template libraryΒΆ

A template library is a library where there are only template classes that can be instantiated. Wrapping such libraries therefore requires AutoWIG to be able to consider various C++ template classes instantiations during the Parse step. It is therefore required to install the pyclanglite parser.

The Standard Template Library (STL) library is a C++ library that provides a set of common C++ template classes such as containers and associative arrays. These classes can be used with any built-in or user-defined type that supports some elementary operations (e.g. copying, assignment). It is divided in four components called algorithms, containers, functional and iterators. STL containers (e.g. std::vector, std::set) are used in many C++ libraries. In such a case, it does not seem relevant that every wrapped C++ library contains wrappers for usual STL containers (e.g. std::vector< double >, std::set< int >). We therefore proposed Python bindings for sequence containers (i.e. pair, array, vector, deque, forward_list and list of the std namespace) and associative containers (set, multiset, map, multimap, unordered_set, unordered_multiset, unordered_map and unordered_multimap of the std namespace). These template instantiations are done for C++ fundamental types (bool, signed char, unsigned char, char, wchar_t, int (with sign modifiers signed and signed combined or not with size modifiers short, long and long long), float, double, long double) and strings (string, wstring of the std namespace). For ordered associative containers both std::less and std::greater comparators are used. We here only illustrate the procedure on the std::vector template class. For the complete procedure refers to the AutoWIG.py file situed at the root of the PySTL repository.

In [ ]:
!git clone https://github.com/StatisKit/STL STL
!git -C STL checkout b9569c67ebc59482dc99a8fa11aa685faebc981d

Then, to install and compile the C++ library we use available Conda recipes.

In [ ]:
!conda build -q STL/conda/libstatiskit_stl -c statiskit
!conda install -y -q libstatiskit_stl --use-local -c statiskit

As presented below, in order to wrap a template library, the user needs to write headers containing aliases for desired template class instantiations.

In [ ]:
!pygmentize STL/src/cpp/STL.h

Once these preliminaries done, we can proceed to the actual generation of wrappers for the PySTL library. For this, we import AutoWIG and create an empty Abstract Semantic Graph (ASG).

We need then to install the C++ headers. This is done using the cpp target in SCons.

In [ ]:
!scons cpp -C STL

Once the headers habe been installed in the system, we parse headers with relevant compilation flags.

In [ ]:
!scons autowig -c -C STL
!scons autowig -C STL

Here is an example of the generated wrappers. We here present the wrappers for the std::vector< int > class.

In [ ]:
!pygmentize STL/src/py/wrapper/wrapper_6b9ae5eac40858c9a0f5e6e21c15d1d3.cpp

Once the wrappers are written on disk, we need to compile and install the Python bindings.

In [ ]:
!conda build STL/conda/python-statiskit_stl -c statiskit
!conda install -y python-statiskit_stl --use-local -c statiskit --force

Finally, we can hereafter use the C++ library in the Python interpreter.

In [ ]:
from statiskit.stl import VectorInt
v = VectorInt()
v.push_back(-1)
v.push_back(0)
v.push_back(1)
v
In [ ]:
list(v)
In [ ]:
v[0]
In [ ]:
v[0] = -2
v[0]
In [ ]:
VectorInt([0, 1])