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])