diff options
Diffstat (limited to '3rdparty/pybind11/docs')
40 files changed, 9393 insertions, 0 deletions
diff --git a/3rdparty/pybind11/docs/Doxyfile b/3rdparty/pybind11/docs/Doxyfile new file mode 100644 index 00000000..1b9d1297 --- /dev/null +++ b/3rdparty/pybind11/docs/Doxyfile @@ -0,0 +1,20 @@ +PROJECT_NAME = pybind11 +INPUT = ../include/pybind11/ +RECURSIVE = YES + +GENERATE_HTML = NO +GENERATE_LATEX = NO +GENERATE_XML = YES +XML_OUTPUT = .build/doxygenxml +XML_PROGRAMLISTING = YES + +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = YES +EXPAND_AS_DEFINED = PYBIND11_RUNTIME_EXCEPTION + +ALIASES = "rst=\verbatim embed:rst" +ALIASES += "endrst=\endverbatim" + +QUIET = YES +WARNINGS = YES +WARN_IF_UNDOCUMENTED = NO diff --git a/3rdparty/pybind11/docs/_static/theme_overrides.css b/3rdparty/pybind11/docs/_static/theme_overrides.css new file mode 100644 index 00000000..1071809f --- /dev/null +++ b/3rdparty/pybind11/docs/_static/theme_overrides.css @@ -0,0 +1,11 @@ +.wy-table-responsive table td, +.wy-table-responsive table th { + white-space: initial !important; +} +.rst-content table.docutils td { + vertical-align: top !important; +} +div[class^='highlight'] pre { + white-space: pre; + white-space: pre-wrap; +} diff --git a/3rdparty/pybind11/docs/advanced/cast/chrono.rst b/3rdparty/pybind11/docs/advanced/cast/chrono.rst new file mode 100644 index 00000000..fbd46057 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/chrono.rst @@ -0,0 +1,81 @@ +Chrono +====== + +When including the additional header file :file:`pybind11/chrono.h` conversions +from C++11 chrono datatypes to python datetime objects are automatically enabled. +This header also enables conversions of python floats (often from sources such +as ``time.monotonic()``, ``time.perf_counter()`` and ``time.process_time()``) +into durations. + +An overview of clocks in C++11 +------------------------------ + +A point of confusion when using these conversions is the differences between +clocks provided in C++11. There are three clock types defined by the C++11 +standard and users can define their own if needed. Each of these clocks have +different properties and when converting to and from python will give different +results. + +The first clock defined by the standard is ``std::chrono::system_clock``. This +clock measures the current date and time. However, this clock changes with to +updates to the operating system time. For example, if your time is synchronised +with a time server this clock will change. This makes this clock a poor choice +for timing purposes but good for measuring the wall time. + +The second clock defined in the standard is ``std::chrono::steady_clock``. +This clock ticks at a steady rate and is never adjusted. This makes it excellent +for timing purposes, however the value in this clock does not correspond to the +current date and time. Often this clock will be the amount of time your system +has been on, although it does not have to be. This clock will never be the same +clock as the system clock as the system clock can change but steady clocks +cannot. + +The third clock defined in the standard is ``std::chrono::high_resolution_clock``. +This clock is the clock that has the highest resolution out of the clocks in the +system. It is normally a typedef to either the system clock or the steady clock +but can be its own independent clock. This is important as when using these +conversions as the types you get in python for this clock might be different +depending on the system. +If it is a typedef of the system clock, python will get datetime objects, but if +it is a different clock they will be timedelta objects. + +Provided conversions +-------------------- + +.. rubric:: C++ to Python + +- ``std::chrono::system_clock::time_point`` → ``datetime.datetime`` + System clock times are converted to python datetime instances. They are + in the local timezone, but do not have any timezone information attached + to them (they are naive datetime objects). + +- ``std::chrono::duration`` → ``datetime.timedelta`` + Durations are converted to timedeltas, any precision in the duration + greater than microseconds is lost by rounding towards zero. + +- ``std::chrono::[other_clocks]::time_point`` → ``datetime.timedelta`` + Any clock time that is not the system clock is converted to a time delta. + This timedelta measures the time from the clocks epoch to now. + +.. rubric:: Python to C++ + +- ``datetime.datetime`` or ``datetime.date`` or ``datetime.time`` → ``std::chrono::system_clock::time_point`` + Date/time objects are converted into system clock timepoints. Any + timezone information is ignored and the type is treated as a naive + object. + +- ``datetime.timedelta`` → ``std::chrono::duration`` + Time delta are converted into durations with microsecond precision. + +- ``datetime.timedelta`` → ``std::chrono::[other_clocks]::time_point`` + Time deltas that are converted into clock timepoints are treated as + the amount of time from the start of the clocks epoch. + +- ``float`` → ``std::chrono::duration`` + Floats that are passed to C++ as durations be interpreted as a number of + seconds. These will be converted to the duration using ``duration_cast`` + from the float. + +- ``float`` → ``std::chrono::[other_clocks]::time_point`` + Floats that are passed to C++ as time points will be interpreted as the + number of seconds from the start of the clocks epoch. diff --git a/3rdparty/pybind11/docs/advanced/cast/custom.rst b/3rdparty/pybind11/docs/advanced/cast/custom.rst new file mode 100644 index 00000000..e4f99ac5 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/custom.rst @@ -0,0 +1,91 @@ +Custom type casters +=================== + +In very rare cases, applications may require custom type casters that cannot be +expressed using the abstractions provided by pybind11, thus requiring raw +Python C API calls. This is fairly advanced usage and should only be pursued by +experts who are familiar with the intricacies of Python reference counting. + +The following snippets demonstrate how this works for a very simple ``inty`` +type that that should be convertible from Python types that provide a +``__int__(self)`` method. + +.. code-block:: cpp + + struct inty { long long_value; }; + + void print(inty s) { + std::cout << s.long_value << std::endl; + } + +The following Python snippet demonstrates the intended usage from the Python side: + +.. code-block:: python + + class A: + def __int__(self): + return 123 + + from example import print + print(A()) + +To register the necessary conversion routines, it is necessary to add +a partial overload to the ``pybind11::detail::type_caster<T>`` template. +Although this is an implementation detail, adding partial overloads to this +type is explicitly allowed. + +.. code-block:: cpp + + namespace pybind11 { namespace detail { + template <> struct type_caster<inty> { + public: + /** + * This macro establishes the name 'inty' in + * function signatures and declares a local variable + * 'value' of type inty + */ + PYBIND11_TYPE_CASTER(inty, _("inty")); + + /** + * Conversion part 1 (Python->C++): convert a PyObject into a inty + * instance or return false upon failure. The second argument + * indicates whether implicit conversions should be applied. + */ + bool load(handle src, bool) { + /* Extract PyObject from handle */ + PyObject *source = src.ptr(); + /* Try converting into a Python integer value */ + PyObject *tmp = PyNumber_Long(source); + if (!tmp) + return false; + /* Now try to convert into a C++ int */ + value.long_value = PyLong_AsLong(tmp); + Py_DECREF(tmp); + /* Ensure return code was OK (to avoid out-of-range errors etc) */ + return !(value.long_value == -1 && !PyErr_Occurred()); + } + + /** + * Conversion part 2 (C++ -> Python): convert an inty instance into + * a Python object. The second and third arguments are used to + * indicate the return value policy and parent object (for + * ``return_value_policy::reference_internal``) and are generally + * ignored by implicit casters. + */ + static handle cast(inty src, return_value_policy /* policy */, handle /* parent */) { + return PyLong_FromLong(src.long_value); + } + }; + }} // namespace pybind11::detail + +.. note:: + + A ``type_caster<T>`` defined with ``PYBIND11_TYPE_CASTER(T, ...)`` requires + that ``T`` is default-constructible (``value`` is first default constructed + and then ``load()`` assigns to it). + +.. warning:: + + When using custom type casters, it's important to declare them consistently + in every compilation unit of the Python extension module. Otherwise, + undefined behavior can ensue. diff --git a/3rdparty/pybind11/docs/advanced/cast/eigen.rst b/3rdparty/pybind11/docs/advanced/cast/eigen.rst new file mode 100644 index 00000000..59ba08c3 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/eigen.rst @@ -0,0 +1,310 @@ +Eigen +##### + +`Eigen <http://eigen.tuxfamily.org>`_ is C++ header-based library for dense and +sparse linear algebra. Due to its popularity and widespread adoption, pybind11 +provides transparent conversion and limited mapping support between Eigen and +Scientific Python linear algebra data types. + +To enable the built-in Eigen support you must include the optional header file +:file:`pybind11/eigen.h`. + +Pass-by-value +============= + +When binding a function with ordinary Eigen dense object arguments (for +example, ``Eigen::MatrixXd``), pybind11 will accept any input value that is +already (or convertible to) a ``numpy.ndarray`` with dimensions compatible with +the Eigen type, copy its values into a temporary Eigen variable of the +appropriate type, then call the function with this temporary variable. + +Sparse matrices are similarly copied to or from +``scipy.sparse.csr_matrix``/``scipy.sparse.csc_matrix`` objects. + +Pass-by-reference +================= + +One major limitation of the above is that every data conversion implicitly +involves a copy, which can be both expensive (for large matrices) and disallows +binding functions that change their (Matrix) arguments. Pybind11 allows you to +work around this by using Eigen's ``Eigen::Ref<MatrixType>`` class much as you +would when writing a function taking a generic type in Eigen itself (subject to +some limitations discussed below). + +When calling a bound function accepting a ``Eigen::Ref<const MatrixType>`` +type, pybind11 will attempt to avoid copying by using an ``Eigen::Map`` object +that maps into the source ``numpy.ndarray`` data: this requires both that the +data types are the same (e.g. ``dtype='float64'`` and ``MatrixType::Scalar`` is +``double``); and that the storage is layout compatible. The latter limitation +is discussed in detail in the section below, and requires careful +consideration: by default, numpy matrices and Eigen matrices are *not* storage +compatible. + +If the numpy matrix cannot be used as is (either because its types differ, e.g. +passing an array of integers to an Eigen parameter requiring doubles, or +because the storage is incompatible), pybind11 makes a temporary copy and +passes the copy instead. + +When a bound function parameter is instead ``Eigen::Ref<MatrixType>`` (note the +lack of ``const``), pybind11 will only allow the function to be called if it +can be mapped *and* if the numpy array is writeable (that is +``a.flags.writeable`` is true). Any access (including modification) made to +the passed variable will be transparently carried out directly on the +``numpy.ndarray``. + +This means you can can write code such as the following and have it work as +expected: + +.. code-block:: cpp + + void scale_by_2(Eigen::Ref<Eigen::VectorXd> v) { + v *= 2; + } + +Note, however, that you will likely run into limitations due to numpy and +Eigen's difference default storage order for data; see the below section on +:ref:`storage_orders` for details on how to bind code that won't run into such +limitations. + +.. note:: + + Passing by reference is not supported for sparse types. + +Returning values to Python +========================== + +When returning an ordinary dense Eigen matrix type to numpy (e.g. +``Eigen::MatrixXd`` or ``Eigen::RowVectorXf``) pybind11 keeps the matrix and +returns a numpy array that directly references the Eigen matrix: no copy of the +data is performed. The numpy array will have ``array.flags.owndata`` set to +``False`` to indicate that it does not own the data, and the lifetime of the +stored Eigen matrix will be tied to the returned ``array``. + +If you bind a function with a non-reference, ``const`` return type (e.g. +``const Eigen::MatrixXd``), the same thing happens except that pybind11 also +sets the numpy array's ``writeable`` flag to false. + +If you return an lvalue reference or pointer, the usual pybind11 rules apply, +as dictated by the binding function's return value policy (see the +documentation on :ref:`return_value_policies` for full details). That means, +without an explicit return value policy, lvalue references will be copied and +pointers will be managed by pybind11. In order to avoid copying, you should +explicitly specify an appropriate return value policy, as in the following +example: + +.. code-block:: cpp + + class MyClass { + Eigen::MatrixXd big_mat = Eigen::MatrixXd::Zero(10000, 10000); + public: + Eigen::MatrixXd &getMatrix() { return big_mat; } + const Eigen::MatrixXd &viewMatrix() { return big_mat; } + }; + + // Later, in binding code: + py::class_<MyClass>(m, "MyClass") + .def(py::init<>()) + .def("copy_matrix", &MyClass::getMatrix) // Makes a copy! + .def("get_matrix", &MyClass::getMatrix, py::return_value_policy::reference_internal) + .def("view_matrix", &MyClass::viewMatrix, py::return_value_policy::reference_internal) + ; + +.. code-block:: python + + a = MyClass() + m = a.get_matrix() # flags.writeable = True, flags.owndata = False + v = a.view_matrix() # flags.writeable = False, flags.owndata = False + c = a.copy_matrix() # flags.writeable = True, flags.owndata = True + # m[5,6] and v[5,6] refer to the same element, c[5,6] does not. + +Note in this example that ``py::return_value_policy::reference_internal`` is +used to tie the life of the MyClass object to the life of the returned arrays. + +You may also return an ``Eigen::Ref``, ``Eigen::Map`` or other map-like Eigen +object (for example, the return value of ``matrix.block()`` and related +methods) that map into a dense Eigen type. When doing so, the default +behaviour of pybind11 is to simply reference the returned data: you must take +care to ensure that this data remains valid! You may ask pybind11 to +explicitly *copy* such a return value by using the +``py::return_value_policy::copy`` policy when binding the function. You may +also use ``py::return_value_policy::reference_internal`` or a +``py::keep_alive`` to ensure the data stays valid as long as the returned numpy +array does. + +When returning such a reference of map, pybind11 additionally respects the +readonly-status of the returned value, marking the numpy array as non-writeable +if the reference or map was itself read-only. + +.. note:: + + Sparse types are always copied when returned. + +.. _storage_orders: + +Storage orders +============== + +Passing arguments via ``Eigen::Ref`` has some limitations that you must be +aware of in order to effectively pass matrices by reference. First and +foremost is that the default ``Eigen::Ref<MatrixType>`` class requires +contiguous storage along columns (for column-major types, the default in Eigen) +or rows if ``MatrixType`` is specifically an ``Eigen::RowMajor`` storage type. +The former, Eigen's default, is incompatible with ``numpy``'s default row-major +storage, and so you will not be able to pass numpy arrays to Eigen by reference +without making one of two changes. + +(Note that this does not apply to vectors (or column or row matrices): for such +types the "row-major" and "column-major" distinction is meaningless). + +The first approach is to change the use of ``Eigen::Ref<MatrixType>`` to the +more general ``Eigen::Ref<MatrixType, 0, Eigen::Stride<Eigen::Dynamic, +Eigen::Dynamic>>`` (or similar type with a fully dynamic stride type in the +third template argument). Since this is a rather cumbersome type, pybind11 +provides a ``py::EigenDRef<MatrixType>`` type alias for your convenience (along +with EigenDMap for the equivalent Map, and EigenDStride for just the stride +type). + +This type allows Eigen to map into any arbitrary storage order. This is not +the default in Eigen for performance reasons: contiguous storage allows +vectorization that cannot be done when storage is not known to be contiguous at +compile time. The default ``Eigen::Ref`` stride type allows non-contiguous +storage along the outer dimension (that is, the rows of a column-major matrix +or columns of a row-major matrix), but not along the inner dimension. + +This type, however, has the added benefit of also being able to map numpy array +slices. For example, the following (contrived) example uses Eigen with a numpy +slice to multiply by 2 all coefficients that are both on even rows (0, 2, 4, +...) and in columns 2, 5, or 8: + +.. code-block:: cpp + + m.def("scale", [](py::EigenDRef<Eigen::MatrixXd> m, double c) { m *= c; }); + +.. code-block:: python + + # a = np.array(...) + scale_by_2(myarray[0::2, 2:9:3]) + +The second approach to avoid copying is more intrusive: rearranging the +underlying data types to not run into the non-contiguous storage problem in the +first place. In particular, that means using matrices with ``Eigen::RowMajor`` +storage, where appropriate, such as: + +.. code-block:: cpp + + using RowMatrixXd = Eigen::Matrix<double, Eigen::Dynamic, Eigen::Dynamic, Eigen::RowMajor>; + // Use RowMatrixXd instead of MatrixXd + +Now bound functions accepting ``Eigen::Ref<RowMatrixXd>`` arguments will be +callable with numpy's (default) arrays without involving a copying. + +You can, alternatively, change the storage order that numpy arrays use by +adding the ``order='F'`` option when creating an array: + +.. code-block:: python + + myarray = np.array(source, order='F') + +Such an object will be passable to a bound function accepting an +``Eigen::Ref<MatrixXd>`` (or similar column-major Eigen type). + +One major caveat with this approach, however, is that it is not entirely as +easy as simply flipping all Eigen or numpy usage from one to the other: some +operations may alter the storage order of a numpy array. For example, ``a2 = +array.transpose()`` results in ``a2`` being a view of ``array`` that references +the same data, but in the opposite storage order! + +While this approach allows fully optimized vectorized calculations in Eigen, it +cannot be used with array slices, unlike the first approach. + +When *returning* a matrix to Python (either a regular matrix, a reference via +``Eigen::Ref<>``, or a map/block into a matrix), no special storage +consideration is required: the created numpy array will have the required +stride that allows numpy to properly interpret the array, whatever its storage +order. + +Failing rather than copying +=========================== + +The default behaviour when binding ``Eigen::Ref<const MatrixType>`` Eigen +references is to copy matrix values when passed a numpy array that does not +conform to the element type of ``MatrixType`` or does not have a compatible +stride layout. If you want to explicitly avoid copying in such a case, you +should bind arguments using the ``py::arg().noconvert()`` annotation (as +described in the :ref:`nonconverting_arguments` documentation). + +The following example shows an example of arguments that don't allow data +copying to take place: + +.. code-block:: cpp + + // The method and function to be bound: + class MyClass { + // ... + double some_method(const Eigen::Ref<const MatrixXd> &matrix) { /* ... */ } + }; + float some_function(const Eigen::Ref<const MatrixXf> &big, + const Eigen::Ref<const MatrixXf> &small) { + // ... + } + + // The associated binding code: + using namespace pybind11::literals; // for "arg"_a + py::class_<MyClass>(m, "MyClass") + // ... other class definitions + .def("some_method", &MyClass::some_method, py::arg().noconvert()); + + m.def("some_function", &some_function, + "big"_a.noconvert(), // <- Don't allow copying for this arg + "small"_a // <- This one can be copied if needed + ); + +With the above binding code, attempting to call the the ``some_method(m)`` +method on a ``MyClass`` object, or attempting to call ``some_function(m, m2)`` +will raise a ``RuntimeError`` rather than making a temporary copy of the array. +It will, however, allow the ``m2`` argument to be copied into a temporary if +necessary. + +Note that explicitly specifying ``.noconvert()`` is not required for *mutable* +Eigen references (e.g. ``Eigen::Ref<MatrixXd>`` without ``const`` on the +``MatrixXd``): mutable references will never be called with a temporary copy. + +Vectors versus column/row matrices +================================== + +Eigen and numpy have fundamentally different notions of a vector. In Eigen, a +vector is simply a matrix with the number of columns or rows set to 1 at +compile time (for a column vector or row vector, respectively). Numpy, in +contrast, has comparable 2-dimensional 1xN and Nx1 arrays, but *also* has +1-dimensional arrays of size N. + +When passing a 2-dimensional 1xN or Nx1 array to Eigen, the Eigen type must +have matching dimensions: That is, you cannot pass a 2-dimensional Nx1 numpy +array to an Eigen value expecting a row vector, or a 1xN numpy array as a +column vector argument. + +On the other hand, pybind11 allows you to pass 1-dimensional arrays of length N +as Eigen parameters. If the Eigen type can hold a column vector of length N it +will be passed as such a column vector. If not, but the Eigen type constraints +will accept a row vector, it will be passed as a row vector. (The column +vector takes precedence when both are supported, for example, when passing a +1D numpy array to a MatrixXd argument). Note that the type need not be +explicitly a vector: it is permitted to pass a 1D numpy array of size 5 to an +Eigen ``Matrix<double, Dynamic, 5>``: you would end up with a 1x5 Eigen matrix. +Passing the same to an ``Eigen::MatrixXd`` would result in a 5x1 Eigen matrix. + +When returning an Eigen vector to numpy, the conversion is ambiguous: a row +vector of length 4 could be returned as either a 1D array of length 4, or as a +2D array of size 1x4. When encountering such a situation, pybind11 compromises +by considering the returned Eigen type: if it is a compile-time vector--that +is, the type has either the number of rows or columns set to 1 at compile +time--pybind11 converts to a 1D numpy array when returning the value. For +instances that are a vector only at run-time (e.g. ``MatrixXd``, +``Matrix<float, Dynamic, 4>``), pybind11 returns the vector as a 2D array to +numpy. If this isn't want you want, you can use ``array.reshape(...)`` to get +a view of the same data in the desired dimensions. + +.. seealso:: + + The file :file:`tests/test_eigen.cpp` contains a complete example that + shows how to pass Eigen sparse and dense data types in more detail. diff --git a/3rdparty/pybind11/docs/advanced/cast/functional.rst b/3rdparty/pybind11/docs/advanced/cast/functional.rst new file mode 100644 index 00000000..d9b46057 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/functional.rst @@ -0,0 +1,109 @@ +Functional +########## + +The following features must be enabled by including :file:`pybind11/functional.h`. + + +Callbacks and passing anonymous functions +========================================= + +The C++11 standard brought lambda functions and the generic polymorphic +function wrapper ``std::function<>`` to the C++ programming language, which +enable powerful new ways of working with functions. Lambda functions come in +two flavors: stateless lambda function resemble classic function pointers that +link to an anonymous piece of code, while stateful lambda functions +additionally depend on captured variables that are stored in an anonymous +*lambda closure object*. + +Here is a simple example of a C++ function that takes an arbitrary function +(stateful or stateless) with signature ``int -> int`` as an argument and runs +it with the value 10. + +.. code-block:: cpp + + int func_arg(const std::function<int(int)> &f) { + return f(10); + } + +The example below is more involved: it takes a function of signature ``int -> int`` +and returns another function of the same kind. The return value is a stateful +lambda function, which stores the value ``f`` in the capture object and adds 1 to +its return value upon execution. + +.. code-block:: cpp + + std::function<int(int)> func_ret(const std::function<int(int)> &f) { + return [f](int i) { + return f(i) + 1; + }; + } + +This example demonstrates using python named parameters in C++ callbacks which +requires using ``py::cpp_function`` as a wrapper. Usage is similar to defining +methods of classes: + +.. code-block:: cpp + + py::cpp_function func_cpp() { + return py::cpp_function([](int i) { return i+1; }, + py::arg("number")); + } + +After including the extra header file :file:`pybind11/functional.h`, it is almost +trivial to generate binding code for all of these functions. + +.. code-block:: cpp + + #include <pybind11/functional.h> + + PYBIND11_MODULE(example, m) { + m.def("func_arg", &func_arg); + m.def("func_ret", &func_ret); + m.def("func_cpp", &func_cpp); + } + +The following interactive session shows how to call them from Python. + +.. code-block:: pycon + + $ python + >>> import example + >>> def square(i): + ... return i * i + ... + >>> example.func_arg(square) + 100L + >>> square_plus_1 = example.func_ret(square) + >>> square_plus_1(4) + 17L + >>> plus_1 = func_cpp() + >>> plus_1(number=43) + 44L + +.. warning:: + + Keep in mind that passing a function from C++ to Python (or vice versa) + will instantiate a piece of wrapper code that translates function + invocations between the two languages. Naturally, this translation + increases the computational cost of each function call somewhat. A + problematic situation can arise when a function is copied back and forth + between Python and C++ many times in a row, in which case the underlying + wrappers will accumulate correspondingly. The resulting long sequence of + C++ -> Python -> C++ -> ... roundtrips can significantly decrease + performance. + + There is one exception: pybind11 detects case where a stateless function + (i.e. a function pointer or a lambda function without captured variables) + is passed as an argument to another C++ function exposed in Python. In this + case, there is no overhead. Pybind11 will extract the underlying C++ + function pointer from the wrapped function to sidestep a potential C++ -> + Python -> C++ roundtrip. This is demonstrated in :file:`tests/test_callbacks.cpp`. + +.. note:: + + This functionality is very useful when generating bindings for callbacks in + C++ libraries (e.g. GUI libraries, asynchronous networking libraries, etc.). + + The file :file:`tests/test_callbacks.cpp` contains a complete example + that demonstrates how to work with callbacks and anonymous functions in + more detail. diff --git a/3rdparty/pybind11/docs/advanced/cast/index.rst b/3rdparty/pybind11/docs/advanced/cast/index.rst new file mode 100644 index 00000000..54c10570 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/index.rst @@ -0,0 +1,42 @@ +Type conversions +################ + +Apart from enabling cross-language function calls, a fundamental problem +that a binding tool like pybind11 must address is to provide access to +native Python types in C++ and vice versa. There are three fundamentally +different ways to do this—which approach is preferable for a particular type +depends on the situation at hand. + +1. Use a native C++ type everywhere. In this case, the type must be wrapped + using pybind11-generated bindings so that Python can interact with it. + +2. Use a native Python type everywhere. It will need to be wrapped so that + C++ functions can interact with it. + +3. Use a native C++ type on the C++ side and a native Python type on the + Python side. pybind11 refers to this as a *type conversion*. + + Type conversions are the most "natural" option in the sense that native + (non-wrapped) types are used everywhere. The main downside is that a copy + of the data must be made on every Python ↔ C++ transition: this is + needed since the C++ and Python versions of the same type generally won't + have the same memory layout. + + pybind11 can perform many kinds of conversions automatically. An overview + is provided in the table ":ref:`conversion_table`". + +The following subsections discuss the differences between these options in more +detail. The main focus in this section is on type conversions, which represent +the last case of the above list. + +.. toctree:: + :maxdepth: 1 + + overview + strings + stl + functional + chrono + eigen + custom + diff --git a/3rdparty/pybind11/docs/advanced/cast/overview.rst b/3rdparty/pybind11/docs/advanced/cast/overview.rst new file mode 100644 index 00000000..b0e32a52 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/overview.rst @@ -0,0 +1,165 @@ +Overview +######## + +.. rubric:: 1. Native type in C++, wrapper in Python + +Exposing a custom C++ type using :class:`py::class_` was covered in detail +in the :doc:`/classes` section. There, the underlying data structure is +always the original C++ class while the :class:`py::class_` wrapper provides +a Python interface. Internally, when an object like this is sent from C++ to +Python, pybind11 will just add the outer wrapper layer over the native C++ +object. Getting it back from Python is just a matter of peeling off the +wrapper. + +.. rubric:: 2. Wrapper in C++, native type in Python + +This is the exact opposite situation. Now, we have a type which is native to +Python, like a ``tuple`` or a ``list``. One way to get this data into C++ is +with the :class:`py::object` family of wrappers. These are explained in more +detail in the :doc:`/advanced/pycpp/object` section. We'll just give a quick +example here: + +.. code-block:: cpp + + void print_list(py::list my_list) { + for (auto item : my_list) + std::cout << item << " "; + } + +.. code-block:: pycon + + >>> print_list([1, 2, 3]) + 1 2 3 + +The Python ``list`` is not converted in any way -- it's just wrapped in a C++ +:class:`py::list` class. At its core it's still a Python object. Copying a +:class:`py::list` will do the usual reference-counting like in Python. +Returning the object to Python will just remove the thin wrapper. + +.. rubric:: 3. Converting between native C++ and Python types + +In the previous two cases we had a native type in one language and a wrapper in +the other. Now, we have native types on both sides and we convert between them. + +.. code-block:: cpp + + void print_vector(const std::vector<int> &v) { + for (auto item : v) + std::cout << item << "\n"; + } + +.. code-block:: pycon + + >>> print_vector([1, 2, 3]) + 1 2 3 + +In this case, pybind11 will construct a new ``std::vector<int>`` and copy each +element from the Python ``list``. The newly constructed object will be passed +to ``print_vector``. The same thing happens in the other direction: a new +``list`` is made to match the value returned from C++. + +Lots of these conversions are supported out of the box, as shown in the table +below. They are very convenient, but keep in mind that these conversions are +fundamentally based on copying data. This is perfectly fine for small immutable +types but it may become quite expensive for large data structures. This can be +avoided by overriding the automatic conversion with a custom wrapper (i.e. the +above-mentioned approach 1). This requires some manual effort and more details +are available in the :ref:`opaque` section. + +.. _conversion_table: + +List of all builtin conversions +------------------------------- + +The following basic data types are supported out of the box (some may require +an additional extension header to be included). To pass other data structures +as arguments and return values, refer to the section on binding :ref:`classes`. + ++------------------------------------+---------------------------+-------------------------------+ +| Data type | Description | Header file | ++====================================+===========================+===============================+ +| ``int8_t``, ``uint8_t`` | 8-bit integers | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``int16_t``, ``uint16_t`` | 16-bit integers | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``int32_t``, ``uint32_t`` | 32-bit integers | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``int64_t``, ``uint64_t`` | 64-bit integers | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``ssize_t``, ``size_t`` | Platform-dependent size | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``float``, ``double`` | Floating point types | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``bool`` | Two-state Boolean type | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``char`` | Character literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``char16_t`` | UTF-16 character literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``char32_t`` | UTF-32 character literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``wchar_t`` | Wide character literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``const char *`` | UTF-8 string literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``const char16_t *`` | UTF-16 string literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``const char32_t *`` | UTF-32 string literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``const wchar_t *`` | Wide string literal | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::string`` | STL dynamic UTF-8 string | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::u16string`` | STL dynamic UTF-16 string | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::u32string`` | STL dynamic UTF-32 string | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::wstring`` | STL dynamic wide string | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::string_view``, | STL C++17 string views | :file:`pybind11/pybind11.h` | +| ``std::u16string_view``, etc. | | | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::pair<T1, T2>`` | Pair of two custom types | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::tuple<...>`` | Arbitrary tuple of types | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::reference_wrapper<...>`` | Reference type wrapper | :file:`pybind11/pybind11.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::complex<T>`` | Complex numbers | :file:`pybind11/complex.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::array<T, Size>`` | STL static array | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::vector<T>`` | STL dynamic array | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::deque<T>`` | STL double-ended queue | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::valarray<T>`` | STL value array | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::list<T>`` | STL linked list | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::map<T1, T2>`` | STL ordered map | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::unordered_map<T1, T2>`` | STL unordered map | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::set<T>`` | STL ordered set | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::unordered_set<T>`` | STL unordered set | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::optional<T>`` | STL optional type (C++17) | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::experimental::optional<T>`` | STL optional type (exp.) | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::variant<...>`` | Type-safe union (C++17) | :file:`pybind11/stl.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::function<...>`` | STL polymorphic function | :file:`pybind11/functional.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::chrono::duration<...>`` | STL time duration | :file:`pybind11/chrono.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``std::chrono::time_point<...>`` | STL date/time | :file:`pybind11/chrono.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``Eigen::Matrix<...>`` | Eigen: dense matrix | :file:`pybind11/eigen.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``Eigen::Map<...>`` | Eigen: mapped memory | :file:`pybind11/eigen.h` | ++------------------------------------+---------------------------+-------------------------------+ +| ``Eigen::SparseMatrix<...>`` | Eigen: sparse matrix | :file:`pybind11/eigen.h` | ++------------------------------------+---------------------------+-------------------------------+ diff --git a/3rdparty/pybind11/docs/advanced/cast/stl.rst b/3rdparty/pybind11/docs/advanced/cast/stl.rst new file mode 100644 index 00000000..e48409f0 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/stl.rst @@ -0,0 +1,240 @@ +STL containers +############## + +Automatic conversion +==================== + +When including the additional header file :file:`pybind11/stl.h`, conversions +between ``std::vector<>``/``std::deque<>``/``std::list<>``/``std::array<>``, +``std::set<>``/``std::unordered_set<>``, and +``std::map<>``/``std::unordered_map<>`` and the Python ``list``, ``set`` and +``dict`` data structures are automatically enabled. The types ``std::pair<>`` +and ``std::tuple<>`` are already supported out of the box with just the core +:file:`pybind11/pybind11.h` header. + +The major downside of these implicit conversions is that containers must be +converted (i.e. copied) on every Python->C++ and C++->Python transition, which +can have implications on the program semantics and performance. Please read the +next sections for more details and alternative approaches that avoid this. + +.. note:: + + Arbitrary nesting of any of these types is possible. + +.. seealso:: + + The file :file:`tests/test_stl.cpp` contains a complete + example that demonstrates how to pass STL data types in more detail. + +.. _cpp17_container_casters: + +C++17 library containers +======================== + +The :file:`pybind11/stl.h` header also includes support for ``std::optional<>`` +and ``std::variant<>``. These require a C++17 compiler and standard library. +In C++14 mode, ``std::experimental::optional<>`` is supported if available. + +Various versions of these containers also exist for C++11 (e.g. in Boost). +pybind11 provides an easy way to specialize the ``type_caster`` for such +types: + +.. code-block:: cpp + + // `boost::optional` as an example -- can be any `std::optional`-like container + namespace pybind11 { namespace detail { + template <typename T> + struct type_caster<boost::optional<T>> : optional_caster<boost::optional<T>> {}; + }} + +The above should be placed in a header file and included in all translation units +where automatic conversion is needed. Similarly, a specialization can be provided +for custom variant types: + +.. code-block:: cpp + + // `boost::variant` as an example -- can be any `std::variant`-like container + namespace pybind11 { namespace detail { + template <typename... Ts> + struct type_caster<boost::variant<Ts...>> : variant_caster<boost::variant<Ts...>> {}; + + // Specifies the function used to visit the variant -- `apply_visitor` instead of `visit` + template <> + struct visit_helper<boost::variant> { + template <typename... Args> + static auto call(Args &&...args) -> decltype(boost::apply_visitor(args...)) { + return boost::apply_visitor(args...); + } + }; + }} // namespace pybind11::detail + +The ``visit_helper`` specialization is not required if your ``name::variant`` provides +a ``name::visit()`` function. For any other function name, the specialization must be +included to tell pybind11 how to visit the variant. + +.. note:: + + pybind11 only supports the modern implementation of ``boost::variant`` + which makes use of variadic templates. This requires Boost 1.56 or newer. + Additionally, on Windows, MSVC 2017 is required because ``boost::variant`` + falls back to the old non-variadic implementation on MSVC 2015. + +.. _opaque: + +Making opaque types +=================== + +pybind11 heavily relies on a template matching mechanism to convert parameters +and return values that are constructed from STL data types such as vectors, +linked lists, hash tables, etc. This even works in a recursive manner, for +instance to deal with lists of hash maps of pairs of elementary and custom +types, etc. + +However, a fundamental limitation of this approach is that internal conversions +between Python and C++ types involve a copy operation that prevents +pass-by-reference semantics. What does this mean? + +Suppose we bind the following function + +.. code-block:: cpp + + void append_1(std::vector<int> &v) { + v.push_back(1); + } + +and call it from Python, the following happens: + +.. code-block:: pycon + + >>> v = [5, 6] + >>> append_1(v) + >>> print(v) + [5, 6] + +As you can see, when passing STL data structures by reference, modifications +are not propagated back the Python side. A similar situation arises when +exposing STL data structures using the ``def_readwrite`` or ``def_readonly`` +functions: + +.. code-block:: cpp + + /* ... definition ... */ + + class MyClass { + std::vector<int> contents; + }; + + /* ... binding code ... */ + + py::class_<MyClass>(m, "MyClass") + .def(py::init<>()) + .def_readwrite("contents", &MyClass::contents); + +In this case, properties can be read and written in their entirety. However, an +``append`` operation involving such a list type has no effect: + +.. code-block:: pycon + + >>> m = MyClass() + >>> m.contents = [5, 6] + >>> print(m.contents) + [5, 6] + >>> m.contents.append(7) + >>> print(m.contents) + [5, 6] + +Finally, the involved copy operations can be costly when dealing with very +large lists. To deal with all of the above situations, pybind11 provides a +macro named ``PYBIND11_MAKE_OPAQUE(T)`` that disables the template-based +conversion machinery of types, thus rendering them *opaque*. The contents of +opaque objects are never inspected or extracted, hence they *can* be passed by +reference. For instance, to turn ``std::vector<int>`` into an opaque type, add +the declaration + +.. code-block:: cpp + + PYBIND11_MAKE_OPAQUE(std::vector<int>); + +before any binding code (e.g. invocations to ``class_::def()``, etc.). This +macro must be specified at the top level (and outside of any namespaces), since +it instantiates a partial template overload. If your binding code consists of +multiple compilation units, it must be present in every file (typically via a +common header) preceding any usage of ``std::vector<int>``. Opaque types must +also have a corresponding ``class_`` declaration to associate them with a name +in Python, and to define a set of available operations, e.g.: + +.. code-block:: cpp + + py::class_<std::vector<int>>(m, "IntVector") + .def(py::init<>()) + .def("clear", &std::vector<int>::clear) + .def("pop_back", &std::vector<int>::pop_back) + .def("__len__", [](const std::vector<int> &v) { return v.size(); }) + .def("__iter__", [](std::vector<int> &v) { + return py::make_iterator(v.begin(), v.end()); + }, py::keep_alive<0, 1>()) /* Keep vector alive while iterator is used */ + // .... + +.. seealso:: + + The file :file:`tests/test_opaque_types.cpp` contains a complete + example that demonstrates how to create and expose opaque types using + pybind11 in more detail. + +.. _stl_bind: + +Binding STL containers +====================== + +The ability to expose STL containers as native Python objects is a fairly +common request, hence pybind11 also provides an optional header file named +:file:`pybind11/stl_bind.h` that does exactly this. The mapped containers try +to match the behavior of their native Python counterparts as much as possible. + +The following example showcases usage of :file:`pybind11/stl_bind.h`: + +.. code-block:: cpp + + // Don't forget this + #include <pybind11/stl_bind.h> + + PYBIND11_MAKE_OPAQUE(std::vector<int>); + PYBIND11_MAKE_OPAQUE(std::map<std::string, double>); + + // ... + + // later in binding code: + py::bind_vector<std::vector<int>>(m, "VectorInt"); + py::bind_map<std::map<std::string, double>>(m, "MapStringDouble"); + +When binding STL containers pybind11 considers the types of the container's +elements to decide whether the container should be confined to the local module +(via the :ref:`module_local` feature). If the container element types are +anything other than already-bound custom types bound without +``py::module_local()`` the container binding will have ``py::module_local()`` +applied. This includes converting types such as numeric types, strings, Eigen +types; and types that have not yet been bound at the time of the stl container +binding. This module-local binding is designed to avoid potential conflicts +between module bindings (for example, from two separate modules each attempting +to bind ``std::vector<int>`` as a python type). + +It is possible to override this behavior to force a definition to be either +module-local or global. To do so, you can pass the attributes +``py::module_local()`` (to make the binding module-local) or +``py::module_local(false)`` (to make the binding global) into the +``py::bind_vector`` or ``py::bind_map`` arguments: + +.. code-block:: cpp + + py::bind_vector<std::vector<int>>(m, "VectorInt", py::module_local(false)); + +Note, however, that such a global binding would make it impossible to load this +module at the same time as any other pybind module that also attempts to bind +the same container type (``std::vector<int>`` in the above example). + +See :ref:`module_local` for more details on module-local bindings. + +.. seealso:: + + The file :file:`tests/test_stl_binders.cpp` shows how to use the + convenience STL container wrappers. diff --git a/3rdparty/pybind11/docs/advanced/cast/strings.rst b/3rdparty/pybind11/docs/advanced/cast/strings.rst new file mode 100644 index 00000000..e25701ec --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/cast/strings.rst @@ -0,0 +1,305 @@ +Strings, bytes and Unicode conversions +###################################### + +.. note:: + + This section discusses string handling in terms of Python 3 strings. For + Python 2.7, replace all occurrences of ``str`` with ``unicode`` and + ``bytes`` with ``str``. Python 2.7 users may find it best to use ``from + __future__ import unicode_literals`` to avoid unintentionally using ``str`` + instead of ``unicode``. + +Passing Python strings to C++ +============================= + +When a Python ``str`` is passed from Python to a C++ function that accepts +``std::string`` or ``char *`` as arguments, pybind11 will encode the Python +string to UTF-8. All Python ``str`` can be encoded in UTF-8, so this operation +does not fail. + +The C++ language is encoding agnostic. It is the responsibility of the +programmer to track encodings. It's often easiest to simply `use UTF-8 +everywhere <http://utf8everywhere.org/>`_. + +.. code-block:: c++ + + m.def("utf8_test", + [](const std::string &s) { + cout << "utf-8 is icing on the cake.\n"; + cout << s; + } + ); + m.def("utf8_charptr", + [](const char *s) { + cout << "My favorite food is\n"; + cout << s; + } + ); + +.. code-block:: python + + >>> utf8_test('🎂') + utf-8 is icing on the cake. + 🎂 + + >>> utf8_charptr('🍕') + My favorite food is + 🍕 + +.. note:: + + Some terminal emulators do not support UTF-8 or emoji fonts and may not + display the example above correctly. + +The results are the same whether the C++ function accepts arguments by value or +reference, and whether or not ``const`` is used. + +Passing bytes to C++ +-------------------- + +A Python ``bytes`` object will be passed to C++ functions that accept +``std::string`` or ``char*`` *without* conversion. On Python 3, in order to +make a function *only* accept ``bytes`` (and not ``str``), declare it as taking +a ``py::bytes`` argument. + + +Returning C++ strings to Python +=============================== + +When a C++ function returns a ``std::string`` or ``char*`` to a Python caller, +**pybind11 will assume that the string is valid UTF-8** and will decode it to a +native Python ``str``, using the same API as Python uses to perform +``bytes.decode('utf-8')``. If this implicit conversion fails, pybind11 will +raise a ``UnicodeDecodeError``. + +.. code-block:: c++ + + m.def("std_string_return", + []() { + return std::string("This string needs to be UTF-8 encoded"); + } + ); + +.. code-block:: python + + >>> isinstance(example.std_string_return(), str) + True + + +Because UTF-8 is inclusive of pure ASCII, there is never any issue with +returning a pure ASCII string to Python. If there is any possibility that the +string is not pure ASCII, it is necessary to ensure the encoding is valid +UTF-8. + +.. warning:: + + Implicit conversion assumes that a returned ``char *`` is null-terminated. + If there is no null terminator a buffer overrun will occur. + +Explicit conversions +-------------------- + +If some C++ code constructs a ``std::string`` that is not a UTF-8 string, one +can perform a explicit conversion and return a ``py::str`` object. Explicit +conversion has the same overhead as implicit conversion. + +.. code-block:: c++ + + // This uses the Python C API to convert Latin-1 to Unicode + m.def("str_output", + []() { + std::string s = "Send your r\xe9sum\xe9 to Alice in HR"; // Latin-1 + py::str py_s = PyUnicode_DecodeLatin1(s.data(), s.length()); + return py_s; + } + ); + +.. code-block:: python + + >>> str_output() + 'Send your résumé to Alice in HR' + +The `Python C API +<https://docs.python.org/3/c-api/unicode.html#built-in-codecs>`_ provides +several built-in codecs. + + +One could also use a third party encoding library such as libiconv to transcode +to UTF-8. + +Return C++ strings without conversion +------------------------------------- + +If the data in a C++ ``std::string`` does not represent text and should be +returned to Python as ``bytes``, then one can return the data as a +``py::bytes`` object. + +.. code-block:: c++ + + m.def("return_bytes", + []() { + std::string s("\xba\xd0\xba\xd0"); // Not valid UTF-8 + return py::bytes(s); // Return the data without transcoding + } + ); + +.. code-block:: python + + >>> example.return_bytes() + b'\xba\xd0\xba\xd0' + + +Note the asymmetry: pybind11 will convert ``bytes`` to ``std::string`` without +encoding, but cannot convert ``std::string`` back to ``bytes`` implicitly. + +.. code-block:: c++ + + m.def("asymmetry", + [](std::string s) { // Accepts str or bytes from Python + return s; // Looks harmless, but implicitly converts to str + } + ); + +.. code-block:: python + + >>> isinstance(example.asymmetry(b"have some bytes"), str) + True + + >>> example.asymmetry(b"\xba\xd0\xba\xd0") # invalid utf-8 as bytes + UnicodeDecodeError: 'utf-8' codec can't decode byte 0xba in position 0: invalid start byte + + +Wide character strings +====================== + +When a Python ``str`` is passed to a C++ function expecting ``std::wstring``, +``wchar_t*``, ``std::u16string`` or ``std::u32string``, the ``str`` will be +encoded to UTF-16 or UTF-32 depending on how the C++ compiler implements each +type, in the platform's native endianness. When strings of these types are +returned, they are assumed to contain valid UTF-16 or UTF-32, and will be +decoded to Python ``str``. + +.. code-block:: c++ + + #define UNICODE + #include <windows.h> + + m.def("set_window_text", + [](HWND hwnd, std::wstring s) { + // Call SetWindowText with null-terminated UTF-16 string + ::SetWindowText(hwnd, s.c_str()); + } + ); + m.def("get_window_text", + [](HWND hwnd) { + const int buffer_size = ::GetWindowTextLength(hwnd) + 1; + auto buffer = std::make_unique< wchar_t[] >(buffer_size); + + ::GetWindowText(hwnd, buffer.data(), buffer_size); + + std::wstring text(buffer.get()); + + // wstring will be converted to Python str + return text; + } + ); + +.. warning:: + + Wide character strings may not work as described on Python 2.7 or Python + 3.3 compiled with ``--enable-unicode=ucs2``. + +Strings in multibyte encodings such as Shift-JIS must transcoded to a +UTF-8/16/32 before being returned to Python. + + +Character literals +================== + +C++ functions that accept character literals as input will receive the first +character of a Python ``str`` as their input. If the string is longer than one +Unicode character, trailing characters will be ignored. + +When a character literal is returned from C++ (such as a ``char`` or a +``wchar_t``), it will be converted to a ``str`` that represents the single +character. + +.. code-block:: c++ + + m.def("pass_char", [](char c) { return c; }); + m.def("pass_wchar", [](wchar_t w) { return w; }); + +.. code-block:: python + + >>> example.pass_char('A') + 'A' + +While C++ will cast integers to character types (``char c = 0x65;``), pybind11 +does not convert Python integers to characters implicitly. The Python function +``chr()`` can be used to convert integers to characters. + +.. code-block:: python + + >>> example.pass_char(0x65) + TypeError + + >>> example.pass_char(chr(0x65)) + 'A' + +If the desire is to work with an 8-bit integer, use ``int8_t`` or ``uint8_t`` +as the argument type. + +Grapheme clusters +----------------- + +A single grapheme may be represented by two or more Unicode characters. For +example 'é' is usually represented as U+00E9 but can also be expressed as the +combining character sequence U+0065 U+0301 (that is, the letter 'e' followed by +a combining acute accent). The combining character will be lost if the +two-character sequence is passed as an argument, even though it renders as a +single grapheme. + +.. code-block:: python + + >>> example.pass_wchar('é') + 'é' + + >>> combining_e_acute = 'e' + '\u0301' + + >>> combining_e_acute + 'é' + + >>> combining_e_acute == 'é' + False + + >>> example.pass_wchar(combining_e_acute) + 'e' + +Normalizing combining characters before passing the character literal to C++ +may resolve *some* of these issues: + +.. code-block:: python + + >>> example.pass_wchar(unicodedata.normalize('NFC', combining_e_acute)) + 'é' + +In some languages (Thai for example), there are `graphemes that cannot be +expressed as a single Unicode code point +<http://unicode.org/reports/tr29/#Grapheme_Cluster_Boundaries>`_, so there is +no way to capture them in a C++ character type. + + +C++17 string views +================== + +C++17 string views are automatically supported when compiling in C++17 mode. +They follow the same rules for encoding and decoding as the corresponding STL +string type (for example, a ``std::u16string_view`` argument will be passed +UTF-16-encoded data, and a returned ``std::string_view`` will be decoded as +UTF-8). + +References +========== + +* `The Absolute Minimum Every Software Developer Absolutely, Positively Must Know About Unicode and Character Sets (No Excuses!) <https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/>`_ +* `C++ - Using STL Strings at Win32 API Boundaries <https://msdn.microsoft.com/en-ca/magazine/mt238407.aspx>`_ diff --git a/3rdparty/pybind11/docs/advanced/classes.rst b/3rdparty/pybind11/docs/advanced/classes.rst new file mode 100644 index 00000000..ae5907de --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/classes.rst @@ -0,0 +1,1126 @@ +Classes +####### + +This section presents advanced binding code for classes and it is assumed +that you are already familiar with the basics from :doc:`/classes`. + +.. _overriding_virtuals: + +Overriding virtual functions in Python +====================================== + +Suppose that a C++ class or interface has a virtual function that we'd like to +to override from within Python (we'll focus on the class ``Animal``; ``Dog`` is +given as a specific example of how one would do this with traditional C++ +code). + +.. code-block:: cpp + + class Animal { + public: + virtual ~Animal() { } + virtual std::string go(int n_times) = 0; + }; + + class Dog : public Animal { + public: + std::string go(int n_times) override { + std::string result; + for (int i=0; i<n_times; ++i) + result += "woof! "; + return result; + } + }; + +Let's also suppose that we are given a plain function which calls the +function ``go()`` on an arbitrary ``Animal`` instance. + +.. code-block:: cpp + + std::string call_go(Animal *animal) { + return animal->go(3); + } + +Normally, the binding code for these classes would look as follows: + +.. code-block:: cpp + + PYBIND11_MODULE(example, m) { + py::class_<Animal>(m, "Animal") + .def("go", &Animal::go); + + py::class_<Dog, Animal>(m, "Dog") + .def(py::init<>()); + + m.def("call_go", &call_go); + } + +However, these bindings are impossible to extend: ``Animal`` is not +constructible, and we clearly require some kind of "trampoline" that +redirects virtual calls back to Python. + +Defining a new type of ``Animal`` from within Python is possible but requires a +helper class that is defined as follows: + +.. code-block:: cpp + + class PyAnimal : public Animal { + public: + /* Inherit the constructors */ + using Animal::Animal; + + /* Trampoline (need one for each virtual function) */ + std::string go(int n_times) override { + PYBIND11_OVERLOAD_PURE( + std::string, /* Return type */ + Animal, /* Parent class */ + go, /* Name of function in C++ (must match Python name) */ + n_times /* Argument(s) */ + ); + } + }; + +The macro :c:macro:`PYBIND11_OVERLOAD_PURE` should be used for pure virtual +functions, and :c:macro:`PYBIND11_OVERLOAD` should be used for functions which have +a default implementation. There are also two alternate macros +:c:macro:`PYBIND11_OVERLOAD_PURE_NAME` and :c:macro:`PYBIND11_OVERLOAD_NAME` which +take a string-valued name argument between the *Parent class* and *Name of the +function* slots, which defines the name of function in Python. This is required +when the C++ and Python versions of the +function have different names, e.g. ``operator()`` vs ``__call__``. + +The binding code also needs a few minor adaptations (highlighted): + +.. code-block:: cpp + :emphasize-lines: 2,3 + + PYBIND11_MODULE(example, m) { + py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal") + .def(py::init<>()) + .def("go", &Animal::go); + + py::class_<Dog, Animal>(m, "Dog") + .def(py::init<>()); + + m.def("call_go", &call_go); + } + +Importantly, pybind11 is made aware of the trampoline helper class by +specifying it as an extra template argument to :class:`class_`. (This can also +be combined with other template arguments such as a custom holder type; the +order of template types does not matter). Following this, we are able to +define a constructor as usual. + +Bindings should be made against the actual class, not the trampoline helper class. + +.. code-block:: cpp + :emphasize-lines: 3 + + py::class_<Animal, PyAnimal /* <--- trampoline*/>(m, "Animal"); + .def(py::init<>()) + .def("go", &PyAnimal::go); /* <--- THIS IS WRONG, use &Animal::go */ + +Note, however, that the above is sufficient for allowing python classes to +extend ``Animal``, but not ``Dog``: see :ref:`virtual_and_inheritance` for the +necessary steps required to providing proper overload support for inherited +classes. + +The Python session below shows how to override ``Animal::go`` and invoke it via +a virtual method call. + +.. code-block:: pycon + + >>> from example import * + >>> d = Dog() + >>> call_go(d) + u'woof! woof! woof! ' + >>> class Cat(Animal): + ... def go(self, n_times): + ... return "meow! " * n_times + ... + >>> c = Cat() + >>> call_go(c) + u'meow! meow! meow! ' + +If you are defining a custom constructor in a derived Python class, you *must* +ensure that you explicitly call the bound C++ constructor using ``__init__``, +*regardless* of whether it is a default constructor or not. Otherwise, the +memory for the C++ portion of the instance will be left uninitialized, which +will generally leave the C++ instance in an invalid state and cause undefined +behavior if the C++ instance is subsequently used. + +Here is an example: + +.. code-block:: python + + class Dachshund(Dog): + def __init__(self, name): + Dog.__init__(self) # Without this, undefined behavior may occur if the C++ portions are referenced. + self.name = name + def bark(self): + return "yap!" + +Note that a direct ``__init__`` constructor *should be called*, and ``super()`` +should not be used. For simple cases of linear inheritance, ``super()`` +may work, but once you begin mixing Python and C++ multiple inheritance, +things will fall apart due to differences between Python's MRO and C++'s +mechanisms. + +Please take a look at the :ref:`macro_notes` before using this feature. + +.. note:: + + When the overridden type returns a reference or pointer to a type that + pybind11 converts from Python (for example, numeric values, std::string, + and other built-in value-converting types), there are some limitations to + be aware of: + + - because in these cases there is no C++ variable to reference (the value + is stored in the referenced Python variable), pybind11 provides one in + the PYBIND11_OVERLOAD macros (when needed) with static storage duration. + Note that this means that invoking the overloaded method on *any* + instance will change the referenced value stored in *all* instances of + that type. + + - Attempts to modify a non-const reference will not have the desired + effect: it will change only the static cache variable, but this change + will not propagate to underlying Python instance, and the change will be + replaced the next time the overload is invoked. + +.. seealso:: + + The file :file:`tests/test_virtual_functions.cpp` contains a complete + example that demonstrates how to override virtual functions using pybind11 + in more detail. + +.. _virtual_and_inheritance: + +Combining virtual functions and inheritance +=========================================== + +When combining virtual methods with inheritance, you need to be sure to provide +an override for each method for which you want to allow overrides from derived +python classes. For example, suppose we extend the above ``Animal``/``Dog`` +example as follows: + +.. code-block:: cpp + + class Animal { + public: + virtual std::string go(int n_times) = 0; + virtual std::string name() { return "unknown"; } + }; + class Dog : public Animal { + public: + std::string go(int n_times) override { + std::string result; + for (int i=0; i<n_times; ++i) + result += bark() + " "; + return result; + } + virtual std::string bark() { return "woof!"; } + }; + +then the trampoline class for ``Animal`` must, as described in the previous +section, override ``go()`` and ``name()``, but in order to allow python code to +inherit properly from ``Dog``, we also need a trampoline class for ``Dog`` that +overrides both the added ``bark()`` method *and* the ``go()`` and ``name()`` +methods inherited from ``Animal`` (even though ``Dog`` doesn't directly +override the ``name()`` method): + +.. code-block:: cpp + + class PyAnimal : public Animal { + public: + using Animal::Animal; // Inherit constructors + std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Animal, go, n_times); } + std::string name() override { PYBIND11_OVERLOAD(std::string, Animal, name, ); } + }; + class PyDog : public Dog { + public: + using Dog::Dog; // Inherit constructors + std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, Dog, go, n_times); } + std::string name() override { PYBIND11_OVERLOAD(std::string, Dog, name, ); } + std::string bark() override { PYBIND11_OVERLOAD(std::string, Dog, bark, ); } + }; + +.. note:: + + Note the trailing commas in the ``PYBIND11_OVERLOAD`` calls to ``name()`` + and ``bark()``. These are needed to portably implement a trampoline for a + function that does not take any arguments. For functions that take + a nonzero number of arguments, the trailing comma must be omitted. + +A registered class derived from a pybind11-registered class with virtual +methods requires a similar trampoline class, *even if* it doesn't explicitly +declare or override any virtual methods itself: + +.. code-block:: cpp + + class Husky : public Dog {}; + class PyHusky : public Husky { + public: + using Husky::Husky; // Inherit constructors + std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, Husky, go, n_times); } + std::string name() override { PYBIND11_OVERLOAD(std::string, Husky, name, ); } + std::string bark() override { PYBIND11_OVERLOAD(std::string, Husky, bark, ); } + }; + +There is, however, a technique that can be used to avoid this duplication +(which can be especially helpful for a base class with several virtual +methods). The technique involves using template trampoline classes, as +follows: + +.. code-block:: cpp + + template <class AnimalBase = Animal> class PyAnimal : public AnimalBase { + public: + using AnimalBase::AnimalBase; // Inherit constructors + std::string go(int n_times) override { PYBIND11_OVERLOAD_PURE(std::string, AnimalBase, go, n_times); } + std::string name() override { PYBIND11_OVERLOAD(std::string, AnimalBase, name, ); } + }; + template <class DogBase = Dog> class PyDog : public PyAnimal<DogBase> { + public: + using PyAnimal<DogBase>::PyAnimal; // Inherit constructors + // Override PyAnimal's pure virtual go() with a non-pure one: + std::string go(int n_times) override { PYBIND11_OVERLOAD(std::string, DogBase, go, n_times); } + std::string bark() override { PYBIND11_OVERLOAD(std::string, DogBase, bark, ); } + }; + +This technique has the advantage of requiring just one trampoline method to be +declared per virtual method and pure virtual method override. It does, +however, require the compiler to generate at least as many methods (and +possibly more, if both pure virtual and overridden pure virtual methods are +exposed, as above). + +The classes are then registered with pybind11 using: + +.. code-block:: cpp + + py::class_<Animal, PyAnimal<>> animal(m, "Animal"); + py::class_<Dog, PyDog<>> dog(m, "Dog"); + py::class_<Husky, PyDog<Husky>> husky(m, "Husky"); + // ... add animal, dog, husky definitions + +Note that ``Husky`` did not require a dedicated trampoline template class at +all, since it neither declares any new virtual methods nor provides any pure +virtual method implementations. + +With either the repeated-virtuals or templated trampoline methods in place, you +can now create a python class that inherits from ``Dog``: + +.. code-block:: python + + class ShihTzu(Dog): + def bark(self): + return "yip!" + +.. seealso:: + + See the file :file:`tests/test_virtual_functions.cpp` for complete examples + using both the duplication and templated trampoline approaches. + +.. _extended_aliases: + +Extended trampoline class functionality +======================================= + +.. _extended_class_functionality_forced_trampoline: + +Forced trampoline class initialisation +-------------------------------------- +The trampoline classes described in the previous sections are, by default, only +initialized when needed. More specifically, they are initialized when a python +class actually inherits from a registered type (instead of merely creating an +instance of the registered type), or when a registered constructor is only +valid for the trampoline class but not the registered class. This is primarily +for performance reasons: when the trampoline class is not needed for anything +except virtual method dispatching, not initializing the trampoline class +improves performance by avoiding needing to do a run-time check to see if the +inheriting python instance has an overloaded method. + +Sometimes, however, it is useful to always initialize a trampoline class as an +intermediate class that does more than just handle virtual method dispatching. +For example, such a class might perform extra class initialization, extra +destruction operations, and might define new members and methods to enable a +more python-like interface to a class. + +In order to tell pybind11 that it should *always* initialize the trampoline +class when creating new instances of a type, the class constructors should be +declared using ``py::init_alias<Args, ...>()`` instead of the usual +``py::init<Args, ...>()``. This forces construction via the trampoline class, +ensuring member initialization and (eventual) destruction. + +.. seealso:: + + See the file :file:`tests/test_virtual_functions.cpp` for complete examples + showing both normal and forced trampoline instantiation. + +Different method signatures +--------------------------- +The macro's introduced in :ref:`overriding_virtuals` cover most of the standard +use cases when exposing C++ classes to Python. Sometimes it is hard or unwieldy +to create a direct one-on-one mapping between the arguments and method return +type. + +An example would be when the C++ signature contains output arguments using +references (See also :ref:`faq_reference_arguments`). Another way of solving +this is to use the method body of the trampoline class to do conversions to the +input and return of the Python method. + +The main building block to do so is the :func:`get_overload`, this function +allows retrieving a method implemented in Python from within the trampoline's +methods. Consider for example a C++ method which has the signature +``bool myMethod(int32_t& value)``, where the return indicates whether +something should be done with the ``value``. This can be made convenient on the +Python side by allowing the Python function to return ``None`` or an ``int``: + +.. code-block:: cpp + + bool MyClass::myMethod(int32_t& value) + { + pybind11::gil_scoped_acquire gil; // Acquire the GIL while in this scope. + // Try to look up the overloaded method on the Python side. + pybind11::function overload = pybind11::get_overload(this, "myMethod"); + if (overload) { // method is found + auto obj = overload(value); // Call the Python function. + if (py::isinstance<py::int_>(obj)) { // check if it returned a Python integer type + value = obj.cast<int32_t>(); // Cast it and assign it to the value. + return true; // Return true; value should be used. + } else { + return false; // Python returned none, return false. + } + } + return false; // Alternatively return MyClass::myMethod(value); + } + + +.. _custom_constructors: + +Custom constructors +=================== + +The syntax for binding constructors was previously introduced, but it only +works when a constructor of the appropriate arguments actually exists on the +C++ side. To extend this to more general cases, pybind11 makes it possible +to bind factory functions as constructors. For example, suppose you have a +class like this: + +.. code-block:: cpp + + class Example { + private: + Example(int); // private constructor + public: + // Factory function: + static Example create(int a) { return Example(a); } + }; + + py::class_<Example>(m, "Example") + .def(py::init(&Example::create)); + +While it is possible to create a straightforward binding of the static +``create`` method, it may sometimes be preferable to expose it as a constructor +on the Python side. This can be accomplished by calling ``.def(py::init(...))`` +with the function reference returning the new instance passed as an argument. +It is also possible to use this approach to bind a function returning a new +instance by raw pointer or by the holder (e.g. ``std::unique_ptr``). + +The following example shows the different approaches: + +.. code-block:: cpp + + class Example { + private: + Example(int); // private constructor + public: + // Factory function - returned by value: + static Example create(int a) { return Example(a); } + + // These constructors are publicly callable: + Example(double); + Example(int, int); + Example(std::string); + }; + + py::class_<Example>(m, "Example") + // Bind the factory function as a constructor: + .def(py::init(&Example::create)) + // Bind a lambda function returning a pointer wrapped in a holder: + .def(py::init([](std::string arg) { + return std::unique_ptr<Example>(new Example(arg)); + })) + // Return a raw pointer: + .def(py::init([](int a, int b) { return new Example(a, b); })) + // You can mix the above with regular C++ constructor bindings as well: + .def(py::init<double>()) + ; + +When the constructor is invoked from Python, pybind11 will call the factory +function and store the resulting C++ instance in the Python instance. + +When combining factory functions constructors with :ref:`virtual function +trampolines <overriding_virtuals>` there are two approaches. The first is to +add a constructor to the alias class that takes a base value by +rvalue-reference. If such a constructor is available, it will be used to +construct an alias instance from the value returned by the factory function. +The second option is to provide two factory functions to ``py::init()``: the +first will be invoked when no alias class is required (i.e. when the class is +being used but not inherited from in Python), and the second will be invoked +when an alias is required. + +You can also specify a single factory function that always returns an alias +instance: this will result in behaviour similar to ``py::init_alias<...>()``, +as described in the :ref:`extended trampoline class documentation +<extended_aliases>`. + +The following example shows the different factory approaches for a class with +an alias: + +.. code-block:: cpp + + #include <pybind11/factory.h> + class Example { + public: + // ... + virtual ~Example() = default; + }; + class PyExample : public Example { + public: + using Example::Example; + PyExample(Example &&base) : Example(std::move(base)) {} + }; + py::class_<Example, PyExample>(m, "Example") + // Returns an Example pointer. If a PyExample is needed, the Example + // instance will be moved via the extra constructor in PyExample, above. + .def(py::init([]() { return new Example(); })) + // Two callbacks: + .def(py::init([]() { return new Example(); } /* no alias needed */, + []() { return new PyExample(); } /* alias needed */)) + // *Always* returns an alias instance (like py::init_alias<>()) + .def(py::init([]() { return new PyExample(); })) + ; + +Brace initialization +-------------------- + +``pybind11::init<>`` internally uses C++11 brace initialization to call the +constructor of the target class. This means that it can be used to bind +*implicit* constructors as well: + +.. code-block:: cpp + + struct Aggregate { + int a; + std::string b; + }; + + py::class_<Aggregate>(m, "Aggregate") + .def(py::init<int, const std::string &>()); + +.. note:: + + Note that brace initialization preferentially invokes constructor overloads + taking a ``std::initializer_list``. In the rare event that this causes an + issue, you can work around it by using ``py::init(...)`` with a lambda + function that constructs the new object as desired. + +.. _classes_with_non_public_destructors: + +Non-public destructors +====================== + +If a class has a private or protected destructor (as might e.g. be the case in +a singleton pattern), a compile error will occur when creating bindings via +pybind11. The underlying issue is that the ``std::unique_ptr`` holder type that +is responsible for managing the lifetime of instances will reference the +destructor even if no deallocations ever take place. In order to expose classes +with private or protected destructors, it is possible to override the holder +type via a holder type argument to ``class_``. Pybind11 provides a helper class +``py::nodelete`` that disables any destructor invocations. In this case, it is +crucial that instances are deallocated on the C++ side to avoid memory leaks. + +.. code-block:: cpp + + /* ... definition ... */ + + class MyClass { + private: + ~MyClass() { } + }; + + /* ... binding code ... */ + + py::class_<MyClass, std::unique_ptr<MyClass, py::nodelete>>(m, "MyClass") + .def(py::init<>()) + +.. _implicit_conversions: + +Implicit conversions +==================== + +Suppose that instances of two types ``A`` and ``B`` are used in a project, and +that an ``A`` can easily be converted into an instance of type ``B`` (examples of this +could be a fixed and an arbitrary precision number type). + +.. code-block:: cpp + + py::class_<A>(m, "A") + /// ... members ... + + py::class_<B>(m, "B") + .def(py::init<A>()) + /// ... members ... + + m.def("func", + [](const B &) { /* .... */ } + ); + +To invoke the function ``func`` using a variable ``a`` containing an ``A`` +instance, we'd have to write ``func(B(a))`` in Python. On the other hand, C++ +will automatically apply an implicit type conversion, which makes it possible +to directly write ``func(a)``. + +In this situation (i.e. where ``B`` has a constructor that converts from +``A``), the following statement enables similar implicit conversions on the +Python side: + +.. code-block:: cpp + + py::implicitly_convertible<A, B>(); + +.. note:: + + Implicit conversions from ``A`` to ``B`` only work when ``B`` is a custom + data type that is exposed to Python via pybind11. + + To prevent runaway recursion, implicit conversions are non-reentrant: an + implicit conversion invoked as part of another implicit conversion of the + same type (i.e. from ``A`` to ``B``) will fail. + +.. _static_properties: + +Static properties +================= + +The section on :ref:`properties` discussed the creation of instance properties +that are implemented in terms of C++ getters and setters. + +Static properties can also be created in a similar way to expose getters and +setters of static class attributes. Note that the implicit ``self`` argument +also exists in this case and is used to pass the Python ``type`` subclass +instance. This parameter will often not be needed by the C++ side, and the +following example illustrates how to instantiate a lambda getter function +that ignores it: + +.. code-block:: cpp + + py::class_<Foo>(m, "Foo") + .def_property_readonly_static("foo", [](py::object /* self */) { return Foo(); }); + +Operator overloading +==================== + +Suppose that we're given the following ``Vector2`` class with a vector addition +and scalar multiplication operation, all implemented using overloaded operators +in C++. + +.. code-block:: cpp + + class Vector2 { + public: + Vector2(float x, float y) : x(x), y(y) { } + + Vector2 operator+(const Vector2 &v) const { return Vector2(x + v.x, y + v.y); } + Vector2 operator*(float value) const { return Vector2(x * value, y * value); } + Vector2& operator+=(const Vector2 &v) { x += v.x; y += v.y; return *this; } + Vector2& operator*=(float v) { x *= v; y *= v; return *this; } + + friend Vector2 operator*(float f, const Vector2 &v) { + return Vector2(f * v.x, f * v.y); + } + + std::string toString() const { + return "[" + std::to_string(x) + ", " + std::to_string(y) + "]"; + } + private: + float x, y; + }; + +The following snippet shows how the above operators can be conveniently exposed +to Python. + +.. code-block:: cpp + + #include <pybind11/operators.h> + + PYBIND11_MODULE(example, m) { + py::class_<Vector2>(m, "Vector2") + .def(py::init<float, float>()) + .def(py::self + py::self) + .def(py::self += py::self) + .def(py::self *= float()) + .def(float() * py::self) + .def(py::self * float()) + .def(-py::self) + .def("__repr__", &Vector2::toString); + } + +Note that a line like + +.. code-block:: cpp + + .def(py::self * float()) + +is really just short hand notation for + +.. code-block:: cpp + + .def("__mul__", [](const Vector2 &a, float b) { + return a * b; + }, py::is_operator()) + +This can be useful for exposing additional operators that don't exist on the +C++ side, or to perform other types of customization. The ``py::is_operator`` +flag marker is needed to inform pybind11 that this is an operator, which +returns ``NotImplemented`` when invoked with incompatible arguments rather than +throwing a type error. + +.. note:: + + To use the more convenient ``py::self`` notation, the additional + header file :file:`pybind11/operators.h` must be included. + +.. seealso:: + + The file :file:`tests/test_operator_overloading.cpp` contains a + complete example that demonstrates how to work with overloaded operators in + more detail. + +.. _pickling: + +Pickling support +================ + +Python's ``pickle`` module provides a powerful facility to serialize and +de-serialize a Python object graph into a binary data stream. To pickle and +unpickle C++ classes using pybind11, a ``py::pickle()`` definition must be +provided. Suppose the class in question has the following signature: + +.. code-block:: cpp + + class Pickleable { + public: + Pickleable(const std::string &value) : m_value(value) { } + const std::string &value() const { return m_value; } + + void setExtra(int extra) { m_extra = extra; } + int extra() const { return m_extra; } + private: + std::string m_value; + int m_extra = 0; + }; + +Pickling support in Python is enabled by defining the ``__setstate__`` and +``__getstate__`` methods [#f3]_. For pybind11 classes, use ``py::pickle()`` +to bind these two functions: + +.. code-block:: cpp + + py::class_<Pickleable>(m, "Pickleable") + .def(py::init<std::string>()) + .def("value", &Pickleable::value) + .def("extra", &Pickleable::extra) + .def("setExtra", &Pickleable::setExtra) + .def(py::pickle( + [](const Pickleable &p) { // __getstate__ + /* Return a tuple that fully encodes the state of the object */ + return py::make_tuple(p.value(), p.extra()); + }, + [](py::tuple t) { // __setstate__ + if (t.size() != 2) + throw std::runtime_error("Invalid state!"); + + /* Create a new C++ instance */ + Pickleable p(t[0].cast<std::string>()); + + /* Assign any additional state */ + p.setExtra(t[1].cast<int>()); + + return p; + } + )); + +The ``__setstate__`` part of the ``py::picke()`` definition follows the same +rules as the single-argument version of ``py::init()``. The return type can be +a value, pointer or holder type. See :ref:`custom_constructors` for details. + +An instance can now be pickled as follows: + +.. code-block:: python + + try: + import cPickle as pickle # Use cPickle on Python 2.7 + except ImportError: + import pickle + + p = Pickleable("test_value") + p.setExtra(15) + data = pickle.dumps(p, 2) + +Note that only the cPickle module is supported on Python 2.7. The second +argument to ``dumps`` is also crucial: it selects the pickle protocol version +2, since the older version 1 is not supported. Newer versions are also fine—for +instance, specify ``-1`` to always use the latest available version. Beware: +failure to follow these instructions will cause important pybind11 memory +allocation routines to be skipped during unpickling, which will likely lead to +memory corruption and/or segmentation faults. + +.. seealso:: + + The file :file:`tests/test_pickling.cpp` contains a complete example + that demonstrates how to pickle and unpickle types using pybind11 in more + detail. + +.. [#f3] http://docs.python.org/3/library/pickle.html#pickling-class-instances + +Multiple Inheritance +==================== + +pybind11 can create bindings for types that derive from multiple base types +(aka. *multiple inheritance*). To do so, specify all bases in the template +arguments of the ``class_`` declaration: + +.. code-block:: cpp + + py::class_<MyType, BaseType1, BaseType2, BaseType3>(m, "MyType") + ... + +The base types can be specified in arbitrary order, and they can even be +interspersed with alias types and holder types (discussed earlier in this +document)---pybind11 will automatically find out which is which. The only +requirement is that the first template argument is the type to be declared. + +It is also permitted to inherit multiply from exported C++ classes in Python, +as well as inheriting from multiple Python and/or pybind11-exported classes. + +There is one caveat regarding the implementation of this feature: + +When only one base type is specified for a C++ type that actually has multiple +bases, pybind11 will assume that it does not participate in multiple +inheritance, which can lead to undefined behavior. In such cases, add the tag +``multiple_inheritance`` to the class constructor: + +.. code-block:: cpp + + py::class_<MyType, BaseType2>(m, "MyType", py::multiple_inheritance()); + +The tag is redundant and does not need to be specified when multiple base types +are listed. + +.. _module_local: + +Module-local class bindings +=========================== + +When creating a binding for a class, pybind11 by default makes that binding +"global" across modules. What this means is that a type defined in one module +can be returned from any module resulting in the same Python type. For +example, this allows the following: + +.. code-block:: cpp + + // In the module1.cpp binding code for module1: + py::class_<Pet>(m, "Pet") + .def(py::init<std::string>()) + .def_readonly("name", &Pet::name); + +.. code-block:: cpp + + // In the module2.cpp binding code for module2: + m.def("create_pet", [](std::string name) { return new Pet(name); }); + +.. code-block:: pycon + + >>> from module1 import Pet + >>> from module2 import create_pet + >>> pet1 = Pet("Kitty") + >>> pet2 = create_pet("Doggy") + >>> pet2.name() + 'Doggy' + +When writing binding code for a library, this is usually desirable: this +allows, for example, splitting up a complex library into multiple Python +modules. + +In some cases, however, this can cause conflicts. For example, suppose two +unrelated modules make use of an external C++ library and each provide custom +bindings for one of that library's classes. This will result in an error when +a Python program attempts to import both modules (directly or indirectly) +because of conflicting definitions on the external type: + +.. code-block:: cpp + + // dogs.cpp + + // Binding for external library class: + py::class<pets::Pet>(m, "Pet") + .def("name", &pets::Pet::name); + + // Binding for local extension class: + py::class<Dog, pets::Pet>(m, "Dog") + .def(py::init<std::string>()); + +.. code-block:: cpp + + // cats.cpp, in a completely separate project from the above dogs.cpp. + + // Binding for external library class: + py::class<pets::Pet>(m, "Pet") + .def("get_name", &pets::Pet::name); + + // Binding for local extending class: + py::class<Cat, pets::Pet>(m, "Cat") + .def(py::init<std::string>()); + +.. code-block:: pycon + + >>> import cats + >>> import dogs + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + ImportError: generic_type: type "Pet" is already registered! + +To get around this, you can tell pybind11 to keep the external class binding +localized to the module by passing the ``py::module_local()`` attribute into +the ``py::class_`` constructor: + +.. code-block:: cpp + + // Pet binding in dogs.cpp: + py::class<pets::Pet>(m, "Pet", py::module_local()) + .def("name", &pets::Pet::name); + +.. code-block:: cpp + + // Pet binding in cats.cpp: + py::class<pets::Pet>(m, "Pet", py::module_local()) + .def("get_name", &pets::Pet::name); + +This makes the Python-side ``dogs.Pet`` and ``cats.Pet`` into distinct classes, +avoiding the conflict and allowing both modules to be loaded. C++ code in the +``dogs`` module that casts or returns a ``Pet`` instance will result in a +``dogs.Pet`` Python instance, while C++ code in the ``cats`` module will result +in a ``cats.Pet`` Python instance. + +This does come with two caveats, however: First, external modules cannot return +or cast a ``Pet`` instance to Python (unless they also provide their own local +bindings). Second, from the Python point of view they are two distinct classes. + +Note that the locality only applies in the C++ -> Python direction. When +passing such a ``py::module_local`` type into a C++ function, the module-local +classes are still considered. This means that if the following function is +added to any module (including but not limited to the ``cats`` and ``dogs`` +modules above) it will be callable with either a ``dogs.Pet`` or ``cats.Pet`` +argument: + +.. code-block:: cpp + + m.def("pet_name", [](const pets::Pet &pet) { return pet.name(); }); + +For example, suppose the above function is added to each of ``cats.cpp``, +``dogs.cpp`` and ``frogs.cpp`` (where ``frogs.cpp`` is some other module that +does *not* bind ``Pets`` at all). + +.. code-block:: pycon + + >>> import cats, dogs, frogs # No error because of the added py::module_local() + >>> mycat, mydog = cats.Cat("Fluffy"), dogs.Dog("Rover") + >>> (cats.pet_name(mycat), dogs.pet_name(mydog)) + ('Fluffy', 'Rover') + >>> (cats.pet_name(mydog), dogs.pet_name(mycat), frogs.pet_name(mycat)) + ('Rover', 'Fluffy', 'Fluffy') + +It is possible to use ``py::module_local()`` registrations in one module even +if another module registers the same type globally: within the module with the +module-local definition, all C++ instances will be cast to the associated bound +Python type. In other modules any such values are converted to the global +Python type created elsewhere. + +.. note:: + + STL bindings (as provided via the optional :file:`pybind11/stl_bind.h` + header) apply ``py::module_local`` by default when the bound type might + conflict with other modules; see :ref:`stl_bind` for details. + +.. note:: + + The localization of the bound types is actually tied to the shared object + or binary generated by the compiler/linker. For typical modules created + with ``PYBIND11_MODULE()``, this distinction is not significant. It is + possible, however, when :ref:`embedding` to embed multiple modules in the + same binary (see :ref:`embedding_modules`). In such a case, the + localization will apply across all embedded modules within the same binary. + +.. seealso:: + + The file :file:`tests/test_local_bindings.cpp` contains additional examples + that demonstrate how ``py::module_local()`` works. + +Binding protected member functions +================================== + +It's normally not possible to expose ``protected`` member functions to Python: + +.. code-block:: cpp + + class A { + protected: + int foo() const { return 42; } + }; + + py::class_<A>(m, "A") + .def("foo", &A::foo); // error: 'foo' is a protected member of 'A' + +On one hand, this is good because non-``public`` members aren't meant to be +accessed from the outside. But we may want to make use of ``protected`` +functions in derived Python classes. + +The following pattern makes this possible: + +.. code-block:: cpp + + class A { + protected: + int foo() const { return 42; } + }; + + class Publicist : public A { // helper type for exposing protected functions + public: + using A::foo; // inherited with different access modifier + }; + + py::class_<A>(m, "A") // bind the primary class + .def("foo", &Publicist::foo); // expose protected methods via the publicist + +This works because ``&Publicist::foo`` is exactly the same function as +``&A::foo`` (same signature and address), just with a different access +modifier. The only purpose of the ``Publicist`` helper class is to make +the function name ``public``. + +If the intent is to expose ``protected`` ``virtual`` functions which can be +overridden in Python, the publicist pattern can be combined with the previously +described trampoline: + +.. code-block:: cpp + + class A { + public: + virtual ~A() = default; + + protected: + virtual int foo() const { return 42; } + }; + + class Trampoline : public A { + public: + int foo() const override { PYBIND11_OVERLOAD(int, A, foo, ); } + }; + + class Publicist : public A { + public: + using A::foo; + }; + + py::class_<A, Trampoline>(m, "A") // <-- `Trampoline` here + .def("foo", &Publicist::foo); // <-- `Publicist` here, not `Trampoline`! + +.. note:: + + MSVC 2015 has a compiler bug (fixed in version 2017) which + requires a more explicit function binding in the form of + ``.def("foo", static_cast<int (A::*)() const>(&Publicist::foo));`` + where ``int (A::*)() const`` is the type of ``A::foo``. + +Custom automatic downcasters +============================ + +As explained in :ref:`inheritance`, pybind11 comes with built-in +understanding of the dynamic type of polymorphic objects in C++; that +is, returning a Pet to Python produces a Python object that knows it's +wrapping a Dog, if Pet has virtual methods and pybind11 knows about +Dog and this Pet is in fact a Dog. Sometimes, you might want to +provide this automatic downcasting behavior when creating bindings for +a class hierarchy that does not use standard C++ polymorphism, such as +LLVM [#f4]_. As long as there's some way to determine at runtime +whether a downcast is safe, you can proceed by specializing the +``pybind11::polymorphic_type_hook`` template: + +.. code-block:: cpp + + enum class PetKind { Cat, Dog, Zebra }; + struct Pet { // Not polymorphic: has no virtual methods + const PetKind kind; + int age = 0; + protected: + Pet(PetKind _kind) : kind(_kind) {} + }; + struct Dog : Pet { + Dog() : Pet(PetKind::Dog) {} + std::string sound = "woof!"; + std::string bark() const { return sound; } + }; + + namespace pybind11 { + template<> struct polymorphic_type_hook<Pet> { + static const void *get(const Pet *src, const std::type_info*& type) { + // note that src may be nullptr + if (src && src->kind == PetKind::Dog) { + type = &typeid(Dog); + return static_cast<const Dog*>(src); + } + return src; + } + }; + } // namespace pybind11 + +When pybind11 wants to convert a C++ pointer of type ``Base*`` to a +Python object, it calls ``polymorphic_type_hook<Base>::get()`` to +determine if a downcast is possible. The ``get()`` function should use +whatever runtime information is available to determine if its ``src`` +parameter is in fact an instance of some class ``Derived`` that +inherits from ``Base``. If it finds such a ``Derived``, it sets ``type += &typeid(Derived)`` and returns a pointer to the ``Derived`` object +that contains ``src``. Otherwise, it just returns ``src``, leaving +``type`` at its default value of nullptr. If you set ``type`` to a +type that pybind11 doesn't know about, no downcasting will occur, and +the original ``src`` pointer will be used with its static type +``Base*``. + +It is critical that the returned pointer and ``type`` argument of +``get()`` agree with each other: if ``type`` is set to something +non-null, the returned pointer must point to the start of an object +whose type is ``type``. If the hierarchy being exposed uses only +single inheritance, a simple ``return src;`` will achieve this just +fine, but in the general case, you must cast ``src`` to the +appropriate derived-class pointer (e.g. using +``static_cast<Derived>(src)``) before allowing it to be returned as a +``void*``. + +.. [#f4] https://llvm.org/docs/HowToSetUpLLVMStyleRTTI.html + +.. note:: + + pybind11's standard support for downcasting objects whose types + have virtual methods is implemented using + ``polymorphic_type_hook`` too, using the standard C++ ability to + determine the most-derived type of a polymorphic object using + ``typeid()`` and to cast a base pointer to that most-derived type + (even if you don't know what it is) using ``dynamic_cast<void*>``. + +.. seealso:: + + The file :file:`tests/test_tagbased_polymorphic.cpp` contains a + more complete example, including a demonstration of how to provide + automatic downcasting for an entire class hierarchy without + writing one get() function for each class. diff --git a/3rdparty/pybind11/docs/advanced/embedding.rst b/3rdparty/pybind11/docs/advanced/embedding.rst new file mode 100644 index 00000000..39303160 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/embedding.rst @@ -0,0 +1,261 @@ +.. _embedding: + +Embedding the interpreter +######################### + +While pybind11 is mainly focused on extending Python using C++, it's also +possible to do the reverse: embed the Python interpreter into a C++ program. +All of the other documentation pages still apply here, so refer to them for +general pybind11 usage. This section will cover a few extra things required +for embedding. + +Getting started +=============== + +A basic executable with an embedded interpreter can be created with just a few +lines of CMake and the ``pybind11::embed`` target, as shown below. For more +information, see :doc:`/compiling`. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(example) + + find_package(pybind11 REQUIRED) # or `add_subdirectory(pybind11)` + + add_executable(example main.cpp) + target_link_libraries(example PRIVATE pybind11::embed) + +The essential structure of the ``main.cpp`` file looks like this: + +.. code-block:: cpp + + #include <pybind11/embed.h> // everything needed for embedding + namespace py = pybind11; + + int main() { + py::scoped_interpreter guard{}; // start the interpreter and keep it alive + + py::print("Hello, World!"); // use the Python API + } + +The interpreter must be initialized before using any Python API, which includes +all the functions and classes in pybind11. The RAII guard class `scoped_interpreter` +takes care of the interpreter lifetime. After the guard is destroyed, the interpreter +shuts down and clears its memory. No Python functions can be called after this. + +Executing Python code +===================== + +There are a few different ways to run Python code. One option is to use `eval`, +`exec` or `eval_file`, as explained in :ref:`eval`. Here is a quick example in +the context of an executable with an embedded interpreter: + +.. code-block:: cpp + + #include <pybind11/embed.h> + namespace py = pybind11; + + int main() { + py::scoped_interpreter guard{}; + + py::exec(R"( + kwargs = dict(name="World", number=42) + message = "Hello, {name}! The answer is {number}".format(**kwargs) + print(message) + )"); + } + +Alternatively, similar results can be achieved using pybind11's API (see +:doc:`/advanced/pycpp/index` for more details). + +.. code-block:: cpp + + #include <pybind11/embed.h> + namespace py = pybind11; + using namespace py::literals; + + int main() { + py::scoped_interpreter guard{}; + + auto kwargs = py::dict("name"_a="World", "number"_a=42); + auto message = "Hello, {name}! The answer is {number}"_s.format(**kwargs); + py::print(message); + } + +The two approaches can also be combined: + +.. code-block:: cpp + + #include <pybind11/embed.h> + #include <iostream> + + namespace py = pybind11; + using namespace py::literals; + + int main() { + py::scoped_interpreter guard{}; + + auto locals = py::dict("name"_a="World", "number"_a=42); + py::exec(R"( + message = "Hello, {name}! The answer is {number}".format(**locals()) + )", py::globals(), locals); + + auto message = locals["message"].cast<std::string>(); + std::cout << message; + } + +Importing modules +================= + +Python modules can be imported using `module::import()`: + +.. code-block:: cpp + + py::module sys = py::module::import("sys"); + py::print(sys.attr("path")); + +For convenience, the current working directory is included in ``sys.path`` when +embedding the interpreter. This makes it easy to import local Python files: + +.. code-block:: python + + """calc.py located in the working directory""" + + def add(i, j): + return i + j + + +.. code-block:: cpp + + py::module calc = py::module::import("calc"); + py::object result = calc.attr("add")(1, 2); + int n = result.cast<int>(); + assert(n == 3); + +Modules can be reloaded using `module::reload()` if the source is modified e.g. +by an external process. This can be useful in scenarios where the application +imports a user defined data processing script which needs to be updated after +changes by the user. Note that this function does not reload modules recursively. + +.. _embedding_modules: + +Adding embedded modules +======================= + +Embedded binary modules can be added using the `PYBIND11_EMBEDDED_MODULE` macro. +Note that the definition must be placed at global scope. They can be imported +like any other module. + +.. code-block:: cpp + + #include <pybind11/embed.h> + namespace py = pybind11; + + PYBIND11_EMBEDDED_MODULE(fast_calc, m) { + // `m` is a `py::module` which is used to bind functions and classes + m.def("add", [](int i, int j) { + return i + j; + }); + } + + int main() { + py::scoped_interpreter guard{}; + + auto fast_calc = py::module::import("fast_calc"); + auto result = fast_calc.attr("add")(1, 2).cast<int>(); + assert(result == 3); + } + +Unlike extension modules where only a single binary module can be created, on +the embedded side an unlimited number of modules can be added using multiple +`PYBIND11_EMBEDDED_MODULE` definitions (as long as they have unique names). + +These modules are added to Python's list of builtins, so they can also be +imported in pure Python files loaded by the interpreter. Everything interacts +naturally: + +.. code-block:: python + + """py_module.py located in the working directory""" + import cpp_module + + a = cpp_module.a + b = a + 1 + + +.. code-block:: cpp + + #include <pybind11/embed.h> + namespace py = pybind11; + + PYBIND11_EMBEDDED_MODULE(cpp_module, m) { + m.attr("a") = 1; + } + + int main() { + py::scoped_interpreter guard{}; + + auto py_module = py::module::import("py_module"); + + auto locals = py::dict("fmt"_a="{} + {} = {}", **py_module.attr("__dict__")); + assert(locals["a"].cast<int>() == 1); + assert(locals["b"].cast<int>() == 2); + + py::exec(R"( + c = a + b + message = fmt.format(a, b, c) + )", py::globals(), locals); + + assert(locals["c"].cast<int>() == 3); + assert(locals["message"].cast<std::string>() == "1 + 2 = 3"); + } + + +Interpreter lifetime +==================== + +The Python interpreter shuts down when `scoped_interpreter` is destroyed. After +this, creating a new instance will restart the interpreter. Alternatively, the +`initialize_interpreter` / `finalize_interpreter` pair of functions can be used +to directly set the state at any time. + +Modules created with pybind11 can be safely re-initialized after the interpreter +has been restarted. However, this may not apply to third-party extension modules. +The issue is that Python itself cannot completely unload extension modules and +there are several caveats with regard to interpreter restarting. In short, not +all memory may be freed, either due to Python reference cycles or user-created +global data. All the details can be found in the CPython documentation. + +.. warning:: + + Creating two concurrent `scoped_interpreter` guards is a fatal error. So is + calling `initialize_interpreter` for a second time after the interpreter + has already been initialized. + + Do not use the raw CPython API functions ``Py_Initialize`` and + ``Py_Finalize`` as these do not properly handle the lifetime of + pybind11's internal data. + + +Sub-interpreter support +======================= + +Creating multiple copies of `scoped_interpreter` is not possible because it +represents the main Python interpreter. Sub-interpreters are something different +and they do permit the existence of multiple interpreters. This is an advanced +feature of the CPython API and should be handled with care. pybind11 does not +currently offer a C++ interface for sub-interpreters, so refer to the CPython +documentation for all the details regarding this feature. + +We'll just mention a couple of caveats the sub-interpreters support in pybind11: + + 1. Sub-interpreters will not receive independent copies of embedded modules. + Instead, these are shared and modifications in one interpreter may be + reflected in another. + + 2. Managing multiple threads, multiple interpreters and the GIL can be + challenging and there are several caveats here, even within the pure + CPython API (please refer to the Python docs for details). As for + pybind11, keep in mind that `gil_scoped_release` and `gil_scoped_acquire` + do not take sub-interpreters into account. diff --git a/3rdparty/pybind11/docs/advanced/exceptions.rst b/3rdparty/pybind11/docs/advanced/exceptions.rst new file mode 100644 index 00000000..75ad7f7f --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/exceptions.rst @@ -0,0 +1,144 @@ +Exceptions +########## + +Built-in exception translation +============================== + +When C++ code invoked from Python throws an ``std::exception``, it is +automatically converted into a Python ``Exception``. pybind11 defines multiple +special exception classes that will map to different types of Python +exceptions: + +.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| + ++--------------------------------------+--------------------------------------+ +| C++ exception type | Python exception type | ++======================================+======================================+ +| :class:`std::exception` | ``RuntimeError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::bad_alloc` | ``MemoryError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::domain_error` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::invalid_argument` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::length_error` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::out_of_range` | ``IndexError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::range_error` | ``ValueError`` | ++--------------------------------------+--------------------------------------+ +| :class:`std::overflow_error` | ``OverflowError`` | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::stop_iteration` | ``StopIteration`` (used to implement | +| | custom iterators) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::index_error` | ``IndexError`` (used to indicate out | +| | of bounds access in ``__getitem__``, | +| | ``__setitem__``, etc.) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::value_error` | ``ValueError`` (used to indicate | +| | wrong value passed in | +| | ``container.remove(...)``) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::key_error` | ``KeyError`` (used to indicate out | +| | of bounds access in ``__getitem__``, | +| | ``__setitem__`` in dict-like | +| | objects, etc.) | ++--------------------------------------+--------------------------------------+ +| :class:`pybind11::error_already_set` | Indicates that the Python exception | +| | flag has already been set via Python | +| | API calls from C++ code; this C++ | +| | exception is used to propagate such | +| | a Python exception back to Python. | ++--------------------------------------+--------------------------------------+ + +When a Python function invoked from C++ throws an exception, it is converted +into a C++ exception of type :class:`error_already_set` whose string payload +contains a textual summary. + +There is also a special exception :class:`cast_error` that is thrown by +:func:`handle::call` when the input arguments cannot be converted to Python +objects. + +Registering custom translators +============================== + +If the default exception conversion policy described above is insufficient, +pybind11 also provides support for registering custom exception translators. +To register a simple exception conversion that translates a C++ exception into +a new Python exception using the C++ exception's ``what()`` method, a helper +function is available: + +.. code-block:: cpp + + py::register_exception<CppExp>(module, "PyExp"); + +This call creates a Python exception class with the name ``PyExp`` in the given +module and automatically converts any encountered exceptions of type ``CppExp`` +into Python exceptions of type ``PyExp``. + +When more advanced exception translation is needed, the function +``py::register_exception_translator(translator)`` can be used to register +functions that can translate arbitrary exception types (and which may include +additional logic to do so). The function takes a stateless callable (e.g. a +function pointer or a lambda function without captured variables) with the call +signature ``void(std::exception_ptr)``. + +When a C++ exception is thrown, the registered exception translators are tried +in reverse order of registration (i.e. the last registered translator gets the +first shot at handling the exception). + +Inside the translator, ``std::rethrow_exception`` should be used within +a try block to re-throw the exception. One or more catch clauses to catch +the appropriate exceptions should then be used with each clause using +``PyErr_SetString`` to set a Python exception or ``ex(string)`` to set +the python exception to a custom exception type (see below). + +To declare a custom Python exception type, declare a ``py::exception`` variable +and use this in the associated exception translator (note: it is often useful +to make this a static declaration when using it inside a lambda expression +without requiring capturing). + + +The following example demonstrates this for a hypothetical exception classes +``MyCustomException`` and ``OtherException``: the first is translated to a +custom python exception ``MyCustomError``, while the second is translated to a +standard python RuntimeError: + +.. code-block:: cpp + + static py::exception<MyCustomException> exc(m, "MyCustomError"); + py::register_exception_translator([](std::exception_ptr p) { + try { + if (p) std::rethrow_exception(p); + } catch (const MyCustomException &e) { + exc(e.what()); + } catch (const OtherException &e) { + PyErr_SetString(PyExc_RuntimeError, e.what()); + } + }); + +Multiple exceptions can be handled by a single translator, as shown in the +example above. If the exception is not caught by the current translator, the +previously registered one gets a chance. + +If none of the registered exception translators is able to handle the +exception, it is handled by the default converter as described in the previous +section. + +.. seealso:: + + The file :file:`tests/test_exceptions.cpp` contains examples + of various custom exception translators and custom exception types. + +.. note:: + + You must call either ``PyErr_SetString`` or a custom exception's call + operator (``exc(string)``) for every exception caught in a custom exception + translator. Failure to do so will cause Python to crash with ``SystemError: + error return without exception set``. + + Exceptions that you do not plan to handle should simply not be caught, or + may be explicitly (re-)thrown to delegate it to the other, + previously-declared existing exception translators. diff --git a/3rdparty/pybind11/docs/advanced/functions.rst b/3rdparty/pybind11/docs/advanced/functions.rst new file mode 100644 index 00000000..3e1a3ff0 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/functions.rst @@ -0,0 +1,507 @@ +Functions +######### + +Before proceeding with this section, make sure that you are already familiar +with the basics of binding functions and classes, as explained in :doc:`/basics` +and :doc:`/classes`. The following guide is applicable to both free and member +functions, i.e. *methods* in Python. + +.. _return_value_policies: + +Return value policies +===================== + +Python and C++ use fundamentally different ways of managing the memory and +lifetime of objects managed by them. This can lead to issues when creating +bindings for functions that return a non-trivial type. Just by looking at the +type information, it is not clear whether Python should take charge of the +returned value and eventually free its resources, or if this is handled on the +C++ side. For this reason, pybind11 provides a several *return value policy* +annotations that can be passed to the :func:`module::def` and +:func:`class_::def` functions. The default policy is +:enum:`return_value_policy::automatic`. + +Return value policies are tricky, and it's very important to get them right. +Just to illustrate what can go wrong, consider the following simple example: + +.. code-block:: cpp + + /* Function declaration */ + Data *get_data() { return _data; /* (pointer to a static data structure) */ } + ... + + /* Binding code */ + m.def("get_data", &get_data); // <-- KABOOM, will cause crash when called from Python + +What's going on here? When ``get_data()`` is called from Python, the return +value (a native C++ type) must be wrapped to turn it into a usable Python type. +In this case, the default return value policy (:enum:`return_value_policy::automatic`) +causes pybind11 to assume ownership of the static ``_data`` instance. + +When Python's garbage collector eventually deletes the Python +wrapper, pybind11 will also attempt to delete the C++ instance (via ``operator +delete()``) due to the implied ownership. At this point, the entire application +will come crashing down, though errors could also be more subtle and involve +silent data corruption. + +In the above example, the policy :enum:`return_value_policy::reference` should have +been specified so that the global data instance is only *referenced* without any +implied transfer of ownership, i.e.: + +.. code-block:: cpp + + m.def("get_data", &get_data, return_value_policy::reference); + +On the other hand, this is not the right policy for many other situations, +where ignoring ownership could lead to resource leaks. +As a developer using pybind11, it's important to be familiar with the different +return value policies, including which situation calls for which one of them. +The following table provides an overview of available policies: + +.. tabularcolumns:: |p{0.5\textwidth}|p{0.45\textwidth}| + ++--------------------------------------------------+----------------------------------------------------------------------------+ +| Return value policy | Description | ++==================================================+============================================================================+ +| :enum:`return_value_policy::take_ownership` | Reference an existing object (i.e. do not create a new copy) and take | +| | ownership. Python will call the destructor and delete operator when the | +| | object's reference count reaches zero. Undefined behavior ensues when the | +| | C++ side does the same, or when the data was not dynamically allocated. | ++--------------------------------------------------+----------------------------------------------------------------------------+ +| :enum:`return_value_policy::copy` | Create a new copy of the returned object, which will be owned by Python. | +| | This policy is comparably safe because the lifetimes of the two instances | +| | are decoupled. | ++--------------------------------------------------+----------------------------------------------------------------------------+ +| :enum:`return_value_policy::move` | Use ``std::move`` to move the return value contents into a new instance | +| | that will be owned by Python. This policy is comparably safe because the | +| | lifetimes of the two instances (move source and destination) are decoupled.| ++--------------------------------------------------+----------------------------------------------------------------------------+ +| :enum:`return_value_policy::reference` | Reference an existing object, but do not take ownership. The C++ side is | +| | responsible for managing the object's lifetime and deallocating it when | +| | it is no longer used. Warning: undefined behavior will ensue when the C++ | +| | side deletes an object that is still referenced and used by Python. | ++--------------------------------------------------+----------------------------------------------------------------------------+ +| :enum:`return_value_policy::reference_internal` | Indicates that the lifetime of the return value is tied to the lifetime | +| | of a parent object, namely the implicit ``this``, or ``self`` argument of | +| | the called method or property. Internally, this policy works just like | +| | :enum:`return_value_policy::reference` but additionally applies a | +| | ``keep_alive<0, 1>`` *call policy* (described in the next section) that | +| | prevents the parent object from being garbage collected as long as the | +| | return value is referenced by Python. This is the default policy for | +| | property getters created via ``def_property``, ``def_readwrite``, etc. | ++--------------------------------------------------+----------------------------------------------------------------------------+ +| :enum:`return_value_policy::automatic` | **Default policy.** This policy falls back to the policy | +| | :enum:`return_value_policy::take_ownership` when the return value is a | +| | pointer. Otherwise, it uses :enum:`return_value_policy::move` or | +| | :enum:`return_value_policy::copy` for rvalue and lvalue references, | +| | respectively. See above for a description of what all of these different | +| | policies do. | ++--------------------------------------------------+----------------------------------------------------------------------------+ +| :enum:`return_value_policy::automatic_reference` | As above, but use policy :enum:`return_value_policy::reference` when the | +| | return value is a pointer. This is the default conversion policy for | +| | function arguments when calling Python functions manually from C++ code | +| | (i.e. via handle::operator()). You probably won't need to use this. | ++--------------------------------------------------+----------------------------------------------------------------------------+ + +Return value policies can also be applied to properties: + +.. code-block:: cpp + + class_<MyClass>(m, "MyClass") + .def_property("data", &MyClass::getData, &MyClass::setData, + py::return_value_policy::copy); + +Technically, the code above applies the policy to both the getter and the +setter function, however, the setter doesn't really care about *return* +value policies which makes this a convenient terse syntax. Alternatively, +targeted arguments can be passed through the :class:`cpp_function` constructor: + +.. code-block:: cpp + + class_<MyClass>(m, "MyClass") + .def_property("data" + py::cpp_function(&MyClass::getData, py::return_value_policy::copy), + py::cpp_function(&MyClass::setData) + ); + +.. warning:: + + Code with invalid return value policies might access uninitialized memory or + free data structures multiple times, which can lead to hard-to-debug + non-determinism and segmentation faults, hence it is worth spending the + time to understand all the different options in the table above. + +.. note:: + + One important aspect of the above policies is that they only apply to + instances which pybind11 has *not* seen before, in which case the policy + clarifies essential questions about the return value's lifetime and + ownership. When pybind11 knows the instance already (as identified by its + type and address in memory), it will return the existing Python object + wrapper rather than creating a new copy. + +.. note:: + + The next section on :ref:`call_policies` discusses *call policies* that can be + specified *in addition* to a return value policy from the list above. Call + policies indicate reference relationships that can involve both return values + and parameters of functions. + +.. note:: + + As an alternative to elaborate call policies and lifetime management logic, + consider using smart pointers (see the section on :ref:`smart_pointers` for + details). Smart pointers can tell whether an object is still referenced from + C++ or Python, which generally eliminates the kinds of inconsistencies that + can lead to crashes or undefined behavior. For functions returning smart + pointers, it is not necessary to specify a return value policy. + +.. _call_policies: + +Additional call policies +======================== + +In addition to the above return value policies, further *call policies* can be +specified to indicate dependencies between parameters or ensure a certain state +for the function call. + +Keep alive +---------- + +In general, this policy is required when the C++ object is any kind of container +and another object is being added to the container. ``keep_alive<Nurse, Patient>`` +indicates that the argument with index ``Patient`` should be kept alive at least +until the argument with index ``Nurse`` is freed by the garbage collector. Argument +indices start at one, while zero refers to the return value. For methods, index +``1`` refers to the implicit ``this`` pointer, while regular arguments begin at +index ``2``. Arbitrarily many call policies can be specified. When a ``Nurse`` +with value ``None`` is detected at runtime, the call policy does nothing. + +When the nurse is not a pybind11-registered type, the implementation internally +relies on the ability to create a *weak reference* to the nurse object. When +the nurse object is not a pybind11-registered type and does not support weak +references, an exception will be thrown. + +Consider the following example: here, the binding code for a list append +operation ties the lifetime of the newly added element to the underlying +container: + +.. code-block:: cpp + + py::class_<List>(m, "List") + .def("append", &List::append, py::keep_alive<1, 2>()); + +For consistency, the argument indexing is identical for constructors. Index +``1`` still refers to the implicit ``this`` pointer, i.e. the object which is +being constructed. Index ``0`` refers to the return type which is presumed to +be ``void`` when a constructor is viewed like a function. The following example +ties the lifetime of the constructor element to the constructed object: + +.. code-block:: cpp + + py::class_<Nurse>(m, "Nurse") + .def(py::init<Patient &>(), py::keep_alive<1, 2>()); + +.. note:: + + ``keep_alive`` is analogous to the ``with_custodian_and_ward`` (if Nurse, + Patient != 0) and ``with_custodian_and_ward_postcall`` (if Nurse/Patient == + 0) policies from Boost.Python. + +Call guard +---------- + +The ``call_guard<T>`` policy allows any scope guard type ``T`` to be placed +around the function call. For example, this definition: + +.. code-block:: cpp + + m.def("foo", foo, py::call_guard<T>()); + +is equivalent to the following pseudocode: + +.. code-block:: cpp + + m.def("foo", [](args...) { + T scope_guard; + return foo(args...); // forwarded arguments + }); + +The only requirement is that ``T`` is default-constructible, but otherwise any +scope guard will work. This is very useful in combination with `gil_scoped_release`. +See :ref:`gil`. + +Multiple guards can also be specified as ``py::call_guard<T1, T2, T3...>``. The +constructor order is left to right and destruction happens in reverse. + +.. seealso:: + + The file :file:`tests/test_call_policies.cpp` contains a complete example + that demonstrates using `keep_alive` and `call_guard` in more detail. + +.. _python_objects_as_args: + +Python objects as arguments +=========================== + +pybind11 exposes all major Python types using thin C++ wrapper classes. These +wrapper classes can also be used as parameters of functions in bindings, which +makes it possible to directly work with native Python types on the C++ side. +For instance, the following statement iterates over a Python ``dict``: + +.. code-block:: cpp + + void print_dict(py::dict dict) { + /* Easily interact with Python types */ + for (auto item : dict) + std::cout << "key=" << std::string(py::str(item.first)) << ", " + << "value=" << std::string(py::str(item.second)) << std::endl; + } + +It can be exported: + +.. code-block:: cpp + + m.def("print_dict", &print_dict); + +And used in Python as usual: + +.. code-block:: pycon + + >>> print_dict({'foo': 123, 'bar': 'hello'}) + key=foo, value=123 + key=bar, value=hello + +For more information on using Python objects in C++, see :doc:`/advanced/pycpp/index`. + +Accepting \*args and \*\*kwargs +=============================== + +Python provides a useful mechanism to define functions that accept arbitrary +numbers of arguments and keyword arguments: + +.. code-block:: python + + def generic(*args, **kwargs): + ... # do something with args and kwargs + +Such functions can also be created using pybind11: + +.. code-block:: cpp + + void generic(py::args args, py::kwargs kwargs) { + /// .. do something with args + if (kwargs) + /// .. do something with kwargs + } + + /// Binding code + m.def("generic", &generic); + +The class ``py::args`` derives from ``py::tuple`` and ``py::kwargs`` derives +from ``py::dict``. + +You may also use just one or the other, and may combine these with other +arguments as long as the ``py::args`` and ``py::kwargs`` arguments are the last +arguments accepted by the function. + +Please refer to the other examples for details on how to iterate over these, +and on how to cast their entries into C++ objects. A demonstration is also +available in ``tests/test_kwargs_and_defaults.cpp``. + +.. note:: + + When combining \*args or \*\*kwargs with :ref:`keyword_args` you should + *not* include ``py::arg`` tags for the ``py::args`` and ``py::kwargs`` + arguments. + +Default arguments revisited +=========================== + +The section on :ref:`default_args` previously discussed basic usage of default +arguments using pybind11. One noteworthy aspect of their implementation is that +default arguments are converted to Python objects right at declaration time. +Consider the following example: + +.. code-block:: cpp + + py::class_<MyClass>("MyClass") + .def("myFunction", py::arg("arg") = SomeType(123)); + +In this case, pybind11 must already be set up to deal with values of the type +``SomeType`` (via a prior instantiation of ``py::class_<SomeType>``), or an +exception will be thrown. + +Another aspect worth highlighting is that the "preview" of the default argument +in the function signature is generated using the object's ``__repr__`` method. +If not available, the signature may not be very helpful, e.g.: + +.. code-block:: pycon + + FUNCTIONS + ... + | myFunction(...) + | Signature : (MyClass, arg : SomeType = <SomeType object at 0x101b7b080>) -> NoneType + ... + +The first way of addressing this is by defining ``SomeType.__repr__``. +Alternatively, it is possible to specify the human-readable preview of the +default argument manually using the ``arg_v`` notation: + +.. code-block:: cpp + + py::class_<MyClass>("MyClass") + .def("myFunction", py::arg_v("arg", SomeType(123), "SomeType(123)")); + +Sometimes it may be necessary to pass a null pointer value as a default +argument. In this case, remember to cast it to the underlying type in question, +like so: + +.. code-block:: cpp + + py::class_<MyClass>("MyClass") + .def("myFunction", py::arg("arg") = (SomeType *) nullptr); + +.. _nonconverting_arguments: + +Non-converting arguments +======================== + +Certain argument types may support conversion from one type to another. Some +examples of conversions are: + +* :ref:`implicit_conversions` declared using ``py::implicitly_convertible<A,B>()`` +* Calling a method accepting a double with an integer argument +* Calling a ``std::complex<float>`` argument with a non-complex python type + (for example, with a float). (Requires the optional ``pybind11/complex.h`` + header). +* Calling a function taking an Eigen matrix reference with a numpy array of the + wrong type or of an incompatible data layout. (Requires the optional + ``pybind11/eigen.h`` header). + +This behaviour is sometimes undesirable: the binding code may prefer to raise +an error rather than convert the argument. This behaviour can be obtained +through ``py::arg`` by calling the ``.noconvert()`` method of the ``py::arg`` +object, such as: + +.. code-block:: cpp + + m.def("floats_only", [](double f) { return 0.5 * f; }, py::arg("f").noconvert()); + m.def("floats_preferred", [](double f) { return 0.5 * f; }, py::arg("f")); + +Attempting the call the second function (the one without ``.noconvert()``) with +an integer will succeed, but attempting to call the ``.noconvert()`` version +will fail with a ``TypeError``: + +.. code-block:: pycon + + >>> floats_preferred(4) + 2.0 + >>> floats_only(4) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: floats_only(): incompatible function arguments. The following argument types are supported: + 1. (f: float) -> float + + Invoked with: 4 + +You may, of course, combine this with the :var:`_a` shorthand notation (see +:ref:`keyword_args`) and/or :ref:`default_args`. It is also permitted to omit +the argument name by using the ``py::arg()`` constructor without an argument +name, i.e. by specifying ``py::arg().noconvert()``. + +.. note:: + + When specifying ``py::arg`` options it is necessary to provide the same + number of options as the bound function has arguments. Thus if you want to + enable no-convert behaviour for just one of several arguments, you will + need to specify a ``py::arg()`` annotation for each argument with the + no-convert argument modified to ``py::arg().noconvert()``. + +.. _none_arguments: + +Allow/Prohibiting None arguments +================================ + +When a C++ type registered with :class:`py::class_` is passed as an argument to +a function taking the instance as pointer or shared holder (e.g. ``shared_ptr`` +or a custom, copyable holder as described in :ref:`smart_pointers`), pybind +allows ``None`` to be passed from Python which results in calling the C++ +function with ``nullptr`` (or an empty holder) for the argument. + +To explicitly enable or disable this behaviour, using the +``.none`` method of the :class:`py::arg` object: + +.. code-block:: cpp + + py::class_<Dog>(m, "Dog").def(py::init<>()); + py::class_<Cat>(m, "Cat").def(py::init<>()); + m.def("bark", [](Dog *dog) -> std::string { + if (dog) return "woof!"; /* Called with a Dog instance */ + else return "(no dog)"; /* Called with None, dog == nullptr */ + }, py::arg("dog").none(true)); + m.def("meow", [](Cat *cat) -> std::string { + // Can't be called with None argument + return "meow"; + }, py::arg("cat").none(false)); + +With the above, the Python call ``bark(None)`` will return the string ``"(no +dog)"``, while attempting to call ``meow(None)`` will raise a ``TypeError``: + +.. code-block:: pycon + + >>> from animals import Dog, Cat, bark, meow + >>> bark(Dog()) + 'woof!' + >>> meow(Cat()) + 'meow' + >>> bark(None) + '(no dog)' + >>> meow(None) + Traceback (most recent call last): + File "<stdin>", line 1, in <module> + TypeError: meow(): incompatible function arguments. The following argument types are supported: + 1. (cat: animals.Cat) -> str + + Invoked with: None + +The default behaviour when the tag is unspecified is to allow ``None``. + +.. note:: + + Even when ``.none(true)`` is specified for an argument, ``None`` will be converted to a + ``nullptr`` *only* for custom and :ref:`opaque <opaque>` types. Pointers to built-in types + (``double *``, ``int *``, ...) and STL types (``std::vector<T> *``, ...; if ``pybind11/stl.h`` + is included) are copied when converted to C++ (see :doc:`/advanced/cast/overview`) and will + not allow ``None`` as argument. To pass optional argument of these copied types consider + using ``std::optional<T>`` + +Overload resolution order +========================= + +When a function or method with multiple overloads is called from Python, +pybind11 determines which overload to call in two passes. The first pass +attempts to call each overload without allowing argument conversion (as if +every argument had been specified as ``py::arg().noconvert()`` as described +above). + +If no overload succeeds in the no-conversion first pass, a second pass is +attempted in which argument conversion is allowed (except where prohibited via +an explicit ``py::arg().noconvert()`` attribute in the function definition). + +If the second pass also fails a ``TypeError`` is raised. + +Within each pass, overloads are tried in the order they were registered with +pybind11. + +What this means in practice is that pybind11 will prefer any overload that does +not require conversion of arguments to an overload that does, but otherwise prefers +earlier-defined overloads to later-defined ones. + +.. note:: + + pybind11 does *not* further prioritize based on the number/pattern of + overloaded arguments. That is, pybind11 does not prioritize a function + requiring one conversion over one requiring three, but only prioritizes + overloads requiring no conversion at all to overloads that require + conversion of at least one argument. diff --git a/3rdparty/pybind11/docs/advanced/misc.rst b/3rdparty/pybind11/docs/advanced/misc.rst new file mode 100644 index 00000000..5b38ec75 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/misc.rst @@ -0,0 +1,306 @@ +Miscellaneous +############# + +.. _macro_notes: + +General notes regarding convenience macros +========================================== + +pybind11 provides a few convenience macros such as +:func:`PYBIND11_DECLARE_HOLDER_TYPE` and ``PYBIND11_OVERLOAD_*``. Since these +are "just" macros that are evaluated in the preprocessor (which has no concept +of types), they *will* get confused by commas in a template argument; for +example, consider: + +.. code-block:: cpp + + PYBIND11_OVERLOAD(MyReturnType<T1, T2>, Class<T3, T4>, func) + +The limitation of the C preprocessor interprets this as five arguments (with new +arguments beginning after each comma) rather than three. To get around this, +there are two alternatives: you can use a type alias, or you can wrap the type +using the ``PYBIND11_TYPE`` macro: + +.. code-block:: cpp + + // Version 1: using a type alias + using ReturnType = MyReturnType<T1, T2>; + using ClassType = Class<T3, T4>; + PYBIND11_OVERLOAD(ReturnType, ClassType, func); + + // Version 2: using the PYBIND11_TYPE macro: + PYBIND11_OVERLOAD(PYBIND11_TYPE(MyReturnType<T1, T2>), + PYBIND11_TYPE(Class<T3, T4>), func) + +The ``PYBIND11_MAKE_OPAQUE`` macro does *not* require the above workarounds. + +.. _gil: + +Global Interpreter Lock (GIL) +============================= + +When calling a C++ function from Python, the GIL is always held. +The classes :class:`gil_scoped_release` and :class:`gil_scoped_acquire` can be +used to acquire and release the global interpreter lock in the body of a C++ +function call. In this way, long-running C++ code can be parallelized using +multiple Python threads. Taking :ref:`overriding_virtuals` as an example, this +could be realized as follows (important changes highlighted): + +.. code-block:: cpp + :emphasize-lines: 8,9,31,32 + + class PyAnimal : public Animal { + public: + /* Inherit the constructors */ + using Animal::Animal; + + /* Trampoline (need one for each virtual function) */ + std::string go(int n_times) { + /* Acquire GIL before calling Python code */ + py::gil_scoped_acquire acquire; + + PYBIND11_OVERLOAD_PURE( + std::string, /* Return type */ + Animal, /* Parent class */ + go, /* Name of function */ + n_times /* Argument(s) */ + ); + } + }; + + PYBIND11_MODULE(example, m) { + py::class_<Animal, PyAnimal> animal(m, "Animal"); + animal + .def(py::init<>()) + .def("go", &Animal::go); + + py::class_<Dog>(m, "Dog", animal) + .def(py::init<>()); + + m.def("call_go", [](Animal *animal) -> std::string { + /* Release GIL before calling into (potentially long-running) C++ code */ + py::gil_scoped_release release; + return call_go(animal); + }); + } + +The ``call_go`` wrapper can also be simplified using the `call_guard` policy +(see :ref:`call_policies`) which yields the same result: + +.. code-block:: cpp + + m.def("call_go", &call_go, py::call_guard<py::gil_scoped_release>()); + + +Binding sequence data types, iterators, the slicing protocol, etc. +================================================================== + +Please refer to the supplemental example for details. + +.. seealso:: + + The file :file:`tests/test_sequences_and_iterators.cpp` contains a + complete example that shows how to bind a sequence data type, including + length queries (``__len__``), iterators (``__iter__``), the slicing + protocol and other kinds of useful operations. + + +Partitioning code over multiple extension modules +================================================= + +It's straightforward to split binding code over multiple extension modules, +while referencing types that are declared elsewhere. Everything "just" works +without any special precautions. One exception to this rule occurs when +extending a type declared in another extension module. Recall the basic example +from Section :ref:`inheritance`. + +.. code-block:: cpp + + py::class_<Pet> pet(m, "Pet"); + pet.def(py::init<const std::string &>()) + .def_readwrite("name", &Pet::name); + + py::class_<Dog>(m, "Dog", pet /* <- specify parent */) + .def(py::init<const std::string &>()) + .def("bark", &Dog::bark); + +Suppose now that ``Pet`` bindings are defined in a module named ``basic``, +whereas the ``Dog`` bindings are defined somewhere else. The challenge is of +course that the variable ``pet`` is not available anymore though it is needed +to indicate the inheritance relationship to the constructor of ``class_<Dog>``. +However, it can be acquired as follows: + +.. code-block:: cpp + + py::object pet = (py::object) py::module::import("basic").attr("Pet"); + + py::class_<Dog>(m, "Dog", pet) + .def(py::init<const std::string &>()) + .def("bark", &Dog::bark); + +Alternatively, you can specify the base class as a template parameter option to +``class_``, which performs an automated lookup of the corresponding Python +type. Like the above code, however, this also requires invoking the ``import`` +function once to ensure that the pybind11 binding code of the module ``basic`` +has been executed: + +.. code-block:: cpp + + py::module::import("basic"); + + py::class_<Dog, Pet>(m, "Dog") + .def(py::init<const std::string &>()) + .def("bark", &Dog::bark); + +Naturally, both methods will fail when there are cyclic dependencies. + +Note that pybind11 code compiled with hidden-by-default symbol visibility (e.g. +via the command line flag ``-fvisibility=hidden`` on GCC/Clang), which is +required for proper pybind11 functionality, can interfere with the ability to +access types defined in another extension module. Working around this requires +manually exporting types that are accessed by multiple extension modules; +pybind11 provides a macro to do just this: + +.. code-block:: cpp + + class PYBIND11_EXPORT Dog : public Animal { + ... + }; + +Note also that it is possible (although would rarely be required) to share arbitrary +C++ objects between extension modules at runtime. Internal library data is shared +between modules using capsule machinery [#f6]_ which can be also utilized for +storing, modifying and accessing user-defined data. Note that an extension module +will "see" other extensions' data if and only if they were built with the same +pybind11 version. Consider the following example: + +.. code-block:: cpp + + auto data = (MyData *) py::get_shared_data("mydata"); + if (!data) + data = (MyData *) py::set_shared_data("mydata", new MyData(42)); + +If the above snippet was used in several separately compiled extension modules, +the first one to be imported would create a ``MyData`` instance and associate +a ``"mydata"`` key with a pointer to it. Extensions that are imported later +would be then able to access the data behind the same pointer. + +.. [#f6] https://docs.python.org/3/extending/extending.html#using-capsules + +Module Destructors +================== + +pybind11 does not provide an explicit mechanism to invoke cleanup code at +module destruction time. In rare cases where such functionality is required, it +is possible to emulate it using Python capsules or weak references with a +destruction callback. + +.. code-block:: cpp + + auto cleanup_callback = []() { + // perform cleanup here -- this function is called with the GIL held + }; + + m.add_object("_cleanup", py::capsule(cleanup_callback)); + +This approach has the potential downside that instances of classes exposed +within the module may still be alive when the cleanup callback is invoked +(whether this is acceptable will generally depend on the application). + +Alternatively, the capsule may also be stashed within a type object, which +ensures that it not called before all instances of that type have been +collected: + +.. code-block:: cpp + + auto cleanup_callback = []() { /* ... */ }; + m.attr("BaseClass").attr("_cleanup") = py::capsule(cleanup_callback); + +Both approaches also expose a potentially dangerous ``_cleanup`` attribute in +Python, which may be undesirable from an API standpoint (a premature explicit +call from Python might lead to undefined behavior). Yet another approach that +avoids this issue involves weak reference with a cleanup callback: + +.. code-block:: cpp + + // Register a callback function that is invoked when the BaseClass object is colelcted + py::cpp_function cleanup_callback( + [](py::handle weakref) { + // perform cleanup here -- this function is called with the GIL held + + weakref.dec_ref(); // release weak reference + } + ); + + // Create a weak reference with a cleanup callback and initially leak it + (void) py::weakref(m.attr("BaseClass"), cleanup_callback).release(); + +.. note:: + + PyPy (at least version 5.9) does not garbage collect objects when the + interpreter exits. An alternative approach (which also works on CPython) is to use + the :py:mod:`atexit` module [#f7]_, for example: + + .. code-block:: cpp + + auto atexit = py::module::import("atexit"); + atexit.attr("register")(py::cpp_function([]() { + // perform cleanup here -- this function is called with the GIL held + })); + + .. [#f7] https://docs.python.org/3/library/atexit.html + + +Generating documentation using Sphinx +===================================== + +Sphinx [#f4]_ has the ability to inspect the signatures and documentation +strings in pybind11-based extension modules to automatically generate beautiful +documentation in a variety formats. The python_example repository [#f5]_ contains a +simple example repository which uses this approach. + +There are two potential gotchas when using this approach: first, make sure that +the resulting strings do not contain any :kbd:`TAB` characters, which break the +docstring parsing routines. You may want to use C++11 raw string literals, +which are convenient for multi-line comments. Conveniently, any excess +indentation will be automatically be removed by Sphinx. However, for this to +work, it is important that all lines are indented consistently, i.e.: + +.. code-block:: cpp + + // ok + m.def("foo", &foo, R"mydelimiter( + The foo function + + Parameters + ---------- + )mydelimiter"); + + // *not ok* + m.def("foo", &foo, R"mydelimiter(The foo function + + Parameters + ---------- + )mydelimiter"); + +By default, pybind11 automatically generates and prepends a signature to the docstring of a function +registered with ``module::def()`` and ``class_::def()``. Sometimes this +behavior is not desirable, because you want to provide your own signature or remove +the docstring completely to exclude the function from the Sphinx documentation. +The class ``options`` allows you to selectively suppress auto-generated signatures: + +.. code-block:: cpp + + PYBIND11_MODULE(example, m) { + py::options options; + options.disable_function_signatures(); + + m.def("add", [](int a, int b) { return a + b; }, "A function which adds two numbers"); + } + +Note that changes to the settings affect only function bindings created during the +lifetime of the ``options`` instance. When it goes out of scope at the end of the module's init function, +the default settings are restored to prevent unwanted side effects. + +.. [#f4] http://www.sphinx-doc.org +.. [#f5] http://github.com/pybind/python_example diff --git a/3rdparty/pybind11/docs/advanced/pycpp/index.rst b/3rdparty/pybind11/docs/advanced/pycpp/index.rst new file mode 100644 index 00000000..6885bdcf --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/pycpp/index.rst @@ -0,0 +1,13 @@ +Python C++ interface +#################### + +pybind11 exposes Python types and functions using thin C++ wrappers, which +makes it possible to conveniently call Python code from C++ without resorting +to Python's C API. + +.. toctree:: + :maxdepth: 2 + + object + numpy + utilities diff --git a/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst b/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst new file mode 100644 index 00000000..458f99e9 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/pycpp/numpy.rst @@ -0,0 +1,386 @@ +.. _numpy: + +NumPy +##### + +Buffer protocol +=============== + +Python supports an extremely general and convenient approach for exchanging +data between plugin libraries. Types can expose a buffer view [#f2]_, which +provides fast direct access to the raw internal data representation. Suppose we +want to bind the following simplistic Matrix class: + +.. code-block:: cpp + + class Matrix { + public: + Matrix(size_t rows, size_t cols) : m_rows(rows), m_cols(cols) { + m_data = new float[rows*cols]; + } + float *data() { return m_data; } + size_t rows() const { return m_rows; } + size_t cols() const { return m_cols; } + private: + size_t m_rows, m_cols; + float *m_data; + }; + +The following binding code exposes the ``Matrix`` contents as a buffer object, +making it possible to cast Matrices into NumPy arrays. It is even possible to +completely avoid copy operations with Python expressions like +``np.array(matrix_instance, copy = False)``. + +.. code-block:: cpp + + py::class_<Matrix>(m, "Matrix", py::buffer_protocol()) + .def_buffer([](Matrix &m) -> py::buffer_info { + return py::buffer_info( + m.data(), /* Pointer to buffer */ + sizeof(float), /* Size of one scalar */ + py::format_descriptor<float>::format(), /* Python struct-style format descriptor */ + 2, /* Number of dimensions */ + { m.rows(), m.cols() }, /* Buffer dimensions */ + { sizeof(float) * m.cols(), /* Strides (in bytes) for each index */ + sizeof(float) } + ); + }); + +Supporting the buffer protocol in a new type involves specifying the special +``py::buffer_protocol()`` tag in the ``py::class_`` constructor and calling the +``def_buffer()`` method with a lambda function that creates a +``py::buffer_info`` description record on demand describing a given matrix +instance. The contents of ``py::buffer_info`` mirror the Python buffer protocol +specification. + +.. code-block:: cpp + + struct buffer_info { + void *ptr; + ssize_t itemsize; + std::string format; + ssize_t ndim; + std::vector<ssize_t> shape; + std::vector<ssize_t> strides; + }; + +To create a C++ function that can take a Python buffer object as an argument, +simply use the type ``py::buffer`` as one of its arguments. Buffers can exist +in a great variety of configurations, hence some safety checks are usually +necessary in the function body. Below, you can see an basic example on how to +define a custom constructor for the Eigen double precision matrix +(``Eigen::MatrixXd``) type, which supports initialization from compatible +buffer objects (e.g. a NumPy matrix). + +.. code-block:: cpp + + /* Bind MatrixXd (or some other Eigen type) to Python */ + typedef Eigen::MatrixXd Matrix; + + typedef Matrix::Scalar Scalar; + constexpr bool rowMajor = Matrix::Flags & Eigen::RowMajorBit; + + py::class_<Matrix>(m, "Matrix", py::buffer_protocol()) + .def("__init__", [](Matrix &m, py::buffer b) { + typedef Eigen::Stride<Eigen::Dynamic, Eigen::Dynamic> Strides; + + /* Request a buffer descriptor from Python */ + py::buffer_info info = b.request(); + + /* Some sanity checks ... */ + if (info.format != py::format_descriptor<Scalar>::format()) + throw std::runtime_error("Incompatible format: expected a double array!"); + + if (info.ndim != 2) + throw std::runtime_error("Incompatible buffer dimension!"); + + auto strides = Strides( + info.strides[rowMajor ? 0 : 1] / (py::ssize_t)sizeof(Scalar), + info.strides[rowMajor ? 1 : 0] / (py::ssize_t)sizeof(Scalar)); + + auto map = Eigen::Map<Matrix, 0, Strides>( + static_cast<Scalar *>(info.ptr), info.shape[0], info.shape[1], strides); + + new (&m) Matrix(map); + }); + +For reference, the ``def_buffer()`` call for this Eigen data type should look +as follows: + +.. code-block:: cpp + + .def_buffer([](Matrix &m) -> py::buffer_info { + return py::buffer_info( + m.data(), /* Pointer to buffer */ + sizeof(Scalar), /* Size of one scalar */ + py::format_descriptor<Scalar>::format(), /* Python struct-style format descriptor */ + 2, /* Number of dimensions */ + { m.rows(), m.cols() }, /* Buffer dimensions */ + { sizeof(Scalar) * (rowMajor ? m.cols() : 1), + sizeof(Scalar) * (rowMajor ? 1 : m.rows()) } + /* Strides (in bytes) for each index */ + ); + }) + +For a much easier approach of binding Eigen types (although with some +limitations), refer to the section on :doc:`/advanced/cast/eigen`. + +.. seealso:: + + The file :file:`tests/test_buffers.cpp` contains a complete example + that demonstrates using the buffer protocol with pybind11 in more detail. + +.. [#f2] http://docs.python.org/3/c-api/buffer.html + +Arrays +====== + +By exchanging ``py::buffer`` with ``py::array`` in the above snippet, we can +restrict the function so that it only accepts NumPy arrays (rather than any +type of Python object satisfying the buffer protocol). + +In many situations, we want to define a function which only accepts a NumPy +array of a certain data type. This is possible via the ``py::array_t<T>`` +template. For instance, the following function requires the argument to be a +NumPy array containing double precision values. + +.. code-block:: cpp + + void f(py::array_t<double> array); + +When it is invoked with a different type (e.g. an integer or a list of +integers), the binding code will attempt to cast the input into a NumPy array +of the requested type. Note that this feature requires the +:file:`pybind11/numpy.h` header to be included. + +Data in NumPy arrays is not guaranteed to packed in a dense manner; +furthermore, entries can be separated by arbitrary column and row strides. +Sometimes, it can be useful to require a function to only accept dense arrays +using either the C (row-major) or Fortran (column-major) ordering. This can be +accomplished via a second template argument with values ``py::array::c_style`` +or ``py::array::f_style``. + +.. code-block:: cpp + + void f(py::array_t<double, py::array::c_style | py::array::forcecast> array); + +The ``py::array::forcecast`` argument is the default value of the second +template parameter, and it ensures that non-conforming arguments are converted +into an array satisfying the specified requirements instead of trying the next +function overload. + +Structured types +================ + +In order for ``py::array_t`` to work with structured (record) types, we first +need to register the memory layout of the type. This can be done via +``PYBIND11_NUMPY_DTYPE`` macro, called in the plugin definition code, which +expects the type followed by field names: + +.. code-block:: cpp + + struct A { + int x; + double y; + }; + + struct B { + int z; + A a; + }; + + // ... + PYBIND11_MODULE(test, m) { + // ... + + PYBIND11_NUMPY_DTYPE(A, x, y); + PYBIND11_NUMPY_DTYPE(B, z, a); + /* now both A and B can be used as template arguments to py::array_t */ + } + +The structure should consist of fundamental arithmetic types, ``std::complex``, +previously registered substructures, and arrays of any of the above. Both C++ +arrays and ``std::array`` are supported. While there is a static assertion to +prevent many types of unsupported structures, it is still the user's +responsibility to use only "plain" structures that can be safely manipulated as +raw memory without violating invariants. + +Vectorizing functions +===================== + +Suppose we want to bind a function with the following signature to Python so +that it can process arbitrary NumPy array arguments (vectors, matrices, general +N-D arrays) in addition to its normal arguments: + +.. code-block:: cpp + + double my_func(int x, float y, double z); + +After including the ``pybind11/numpy.h`` header, this is extremely simple: + +.. code-block:: cpp + + m.def("vectorized_func", py::vectorize(my_func)); + +Invoking the function like below causes 4 calls to be made to ``my_func`` with +each of the array elements. The significant advantage of this compared to +solutions like ``numpy.vectorize()`` is that the loop over the elements runs +entirely on the C++ side and can be crunched down into a tight, optimized loop +by the compiler. The result is returned as a NumPy array of type +``numpy.dtype.float64``. + +.. code-block:: pycon + + >>> x = np.array([[1, 3],[5, 7]]) + >>> y = np.array([[2, 4],[6, 8]]) + >>> z = 3 + >>> result = vectorized_func(x, y, z) + +The scalar argument ``z`` is transparently replicated 4 times. The input +arrays ``x`` and ``y`` are automatically converted into the right types (they +are of type ``numpy.dtype.int64`` but need to be ``numpy.dtype.int32`` and +``numpy.dtype.float32``, respectively). + +.. note:: + + Only arithmetic, complex, and POD types passed by value or by ``const &`` + reference are vectorized; all other arguments are passed through as-is. + Functions taking rvalue reference arguments cannot be vectorized. + +In cases where the computation is too complicated to be reduced to +``vectorize``, it will be necessary to create and access the buffer contents +manually. The following snippet contains a complete example that shows how this +works (the code is somewhat contrived, since it could have been done more +simply using ``vectorize``). + +.. code-block:: cpp + + #include <pybind11/pybind11.h> + #include <pybind11/numpy.h> + + namespace py = pybind11; + + py::array_t<double> add_arrays(py::array_t<double> input1, py::array_t<double> input2) { + py::buffer_info buf1 = input1.request(), buf2 = input2.request(); + + if (buf1.ndim != 1 || buf2.ndim != 1) + throw std::runtime_error("Number of dimensions must be one"); + + if (buf1.size != buf2.size) + throw std::runtime_error("Input shapes must match"); + + /* No pointer is passed, so NumPy will allocate the buffer */ + auto result = py::array_t<double>(buf1.size); + + py::buffer_info buf3 = result.request(); + + double *ptr1 = (double *) buf1.ptr, + *ptr2 = (double *) buf2.ptr, + *ptr3 = (double *) buf3.ptr; + + for (size_t idx = 0; idx < buf1.shape[0]; idx++) + ptr3[idx] = ptr1[idx] + ptr2[idx]; + + return result; + } + + PYBIND11_MODULE(test, m) { + m.def("add_arrays", &add_arrays, "Add two NumPy arrays"); + } + +.. seealso:: + + The file :file:`tests/test_numpy_vectorize.cpp` contains a complete + example that demonstrates using :func:`vectorize` in more detail. + +Direct access +============= + +For performance reasons, particularly when dealing with very large arrays, it +is often desirable to directly access array elements without internal checking +of dimensions and bounds on every access when indices are known to be already +valid. To avoid such checks, the ``array`` class and ``array_t<T>`` template +class offer an unchecked proxy object that can be used for this unchecked +access through the ``unchecked<N>`` and ``mutable_unchecked<N>`` methods, +where ``N`` gives the required dimensionality of the array: + +.. code-block:: cpp + + m.def("sum_3d", [](py::array_t<double> x) { + auto r = x.unchecked<3>(); // x must have ndim = 3; can be non-writeable + double sum = 0; + for (ssize_t i = 0; i < r.shape(0); i++) + for (ssize_t j = 0; j < r.shape(1); j++) + for (ssize_t k = 0; k < r.shape(2); k++) + sum += r(i, j, k); + return sum; + }); + m.def("increment_3d", [](py::array_t<double> x) { + auto r = x.mutable_unchecked<3>(); // Will throw if ndim != 3 or flags.writeable is false + for (ssize_t i = 0; i < r.shape(0); i++) + for (ssize_t j = 0; j < r.shape(1); j++) + for (ssize_t k = 0; k < r.shape(2); k++) + r(i, j, k) += 1.0; + }, py::arg().noconvert()); + +To obtain the proxy from an ``array`` object, you must specify both the data +type and number of dimensions as template arguments, such as ``auto r = +myarray.mutable_unchecked<float, 2>()``. + +If the number of dimensions is not known at compile time, you can omit the +dimensions template parameter (i.e. calling ``arr_t.unchecked()`` or +``arr.unchecked<T>()``. This will give you a proxy object that works in the +same way, but results in less optimizable code and thus a small efficiency +loss in tight loops. + +Note that the returned proxy object directly references the array's data, and +only reads its shape, strides, and writeable flag when constructed. You must +take care to ensure that the referenced array is not destroyed or reshaped for +the duration of the returned object, typically by limiting the scope of the +returned instance. + +The returned proxy object supports some of the same methods as ``py::array`` so +that it can be used as a drop-in replacement for some existing, index-checked +uses of ``py::array``: + +- ``r.ndim()`` returns the number of dimensions + +- ``r.data(1, 2, ...)`` and ``r.mutable_data(1, 2, ...)``` returns a pointer to + the ``const T`` or ``T`` data, respectively, at the given indices. The + latter is only available to proxies obtained via ``a.mutable_unchecked()``. + +- ``itemsize()`` returns the size of an item in bytes, i.e. ``sizeof(T)``. + +- ``ndim()`` returns the number of dimensions. + +- ``shape(n)`` returns the size of dimension ``n`` + +- ``size()`` returns the total number of elements (i.e. the product of the shapes). + +- ``nbytes()`` returns the number of bytes used by the referenced elements + (i.e. ``itemsize()`` times ``size()``). + +.. seealso:: + + The file :file:`tests/test_numpy_array.cpp` contains additional examples + demonstrating the use of this feature. + +Ellipsis +======== + +Python 3 provides a convenient ``...`` ellipsis notation that is often used to +slice multidimensional arrays. For instance, the following snippet extracts the +middle dimensions of a tensor with the first and last index set to zero. + +.. code-block:: python + + a = # a NumPy array + b = a[0, ..., 0] + +The function ``py::ellipsis()`` function can be used to perform the same +operation on the C++ side: + +.. code-block:: cpp + + py::array a = /* A NumPy array */; + py::array b = a[py::make_tuple(0, py::ellipsis(), 0)]; diff --git a/3rdparty/pybind11/docs/advanced/pycpp/object.rst b/3rdparty/pybind11/docs/advanced/pycpp/object.rst new file mode 100644 index 00000000..117131ed --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/pycpp/object.rst @@ -0,0 +1,170 @@ +Python types +############ + +Available wrappers +================== + +All major Python types are available as thin C++ wrapper classes. These +can also be used as function parameters -- see :ref:`python_objects_as_args`. + +Available types include :class:`handle`, :class:`object`, :class:`bool_`, +:class:`int_`, :class:`float_`, :class:`str`, :class:`bytes`, :class:`tuple`, +:class:`list`, :class:`dict`, :class:`slice`, :class:`none`, :class:`capsule`, +:class:`iterable`, :class:`iterator`, :class:`function`, :class:`buffer`, +:class:`array`, and :class:`array_t`. + +Casting back and forth +====================== + +In this kind of mixed code, it is often necessary to convert arbitrary C++ +types to Python, which can be done using :func:`py::cast`: + +.. code-block:: cpp + + MyClass *cls = ..; + py::object obj = py::cast(cls); + +The reverse direction uses the following syntax: + +.. code-block:: cpp + + py::object obj = ...; + MyClass *cls = obj.cast<MyClass *>(); + +When conversion fails, both directions throw the exception :class:`cast_error`. + +.. _python_libs: + +Accessing Python libraries from C++ +=================================== + +It is also possible to import objects defined in the Python standard +library or available in the current Python environment (``sys.path``) and work +with these in C++. + +This example obtains a reference to the Python ``Decimal`` class. + +.. code-block:: cpp + + // Equivalent to "from decimal import Decimal" + py::object Decimal = py::module::import("decimal").attr("Decimal"); + +.. code-block:: cpp + + // Try to import scipy + py::object scipy = py::module::import("scipy"); + return scipy.attr("__version__"); + +.. _calling_python_functions: + +Calling Python functions +======================== + +It is also possible to call Python classes, functions and methods +via ``operator()``. + +.. code-block:: cpp + + // Construct a Python object of class Decimal + py::object pi = Decimal("3.14159"); + +.. code-block:: cpp + + // Use Python to make our directories + py::object os = py::module::import("os"); + py::object makedirs = os.attr("makedirs"); + makedirs("/tmp/path/to/somewhere"); + +One can convert the result obtained from Python to a pure C++ version +if a ``py::class_`` or type conversion is defined. + +.. code-block:: cpp + + py::function f = <...>; + py::object result_py = f(1234, "hello", some_instance); + MyClass &result = result_py.cast<MyClass>(); + +.. _calling_python_methods: + +Calling Python methods +======================== + +To call an object's method, one can again use ``.attr`` to obtain access to the +Python method. + +.. code-block:: cpp + + // Calculate e^π in decimal + py::object exp_pi = pi.attr("exp")(); + py::print(py::str(exp_pi)); + +In the example above ``pi.attr("exp")`` is a *bound method*: it will always call +the method for that same instance of the class. Alternately one can create an +*unbound method* via the Python class (instead of instance) and pass the ``self`` +object explicitly, followed by other arguments. + +.. code-block:: cpp + + py::object decimal_exp = Decimal.attr("exp"); + + // Compute the e^n for n=0..4 + for (int n = 0; n < 5; n++) { + py::print(decimal_exp(Decimal(n)); + } + +Keyword arguments +================= + +Keyword arguments are also supported. In Python, there is the usual call syntax: + +.. code-block:: python + + def f(number, say, to): + ... # function code + + f(1234, say="hello", to=some_instance) # keyword call in Python + +In C++, the same call can be made using: + +.. code-block:: cpp + + using namespace pybind11::literals; // to bring in the `_a` literal + f(1234, "say"_a="hello", "to"_a=some_instance); // keyword call in C++ + +Unpacking arguments +=================== + +Unpacking of ``*args`` and ``**kwargs`` is also possible and can be mixed with +other arguments: + +.. code-block:: cpp + + // * unpacking + py::tuple args = py::make_tuple(1234, "hello", some_instance); + f(*args); + + // ** unpacking + py::dict kwargs = py::dict("number"_a=1234, "say"_a="hello", "to"_a=some_instance); + f(**kwargs); + + // mixed keywords, * and ** unpacking + py::tuple args = py::make_tuple(1234); + py::dict kwargs = py::dict("to"_a=some_instance); + f(*args, "say"_a="hello", **kwargs); + +Generalized unpacking according to PEP448_ is also supported: + +.. code-block:: cpp + + py::dict kwargs1 = py::dict("number"_a=1234); + py::dict kwargs2 = py::dict("to"_a=some_instance); + f(**kwargs1, "say"_a="hello", **kwargs2); + +.. seealso:: + + The file :file:`tests/test_pytypes.cpp` contains a complete + example that demonstrates passing native Python types in more detail. The + file :file:`tests/test_callbacks.cpp` presents a few examples of calling + Python functions from C++, including keywords arguments and unpacking. + +.. _PEP448: https://www.python.org/dev/peps/pep-0448/ diff --git a/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst b/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst new file mode 100644 index 00000000..369e7c94 --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/pycpp/utilities.rst @@ -0,0 +1,144 @@ +Utilities +######### + +Using Python's print function in C++ +==================================== + +The usual way to write output in C++ is using ``std::cout`` while in Python one +would use ``print``. Since these methods use different buffers, mixing them can +lead to output order issues. To resolve this, pybind11 modules can use the +:func:`py::print` function which writes to Python's ``sys.stdout`` for consistency. + +Python's ``print`` function is replicated in the C++ API including optional +keyword arguments ``sep``, ``end``, ``file``, ``flush``. Everything works as +expected in Python: + +.. code-block:: cpp + + py::print(1, 2.0, "three"); // 1 2.0 three + py::print(1, 2.0, "three", "sep"_a="-"); // 1-2.0-three + + auto args = py::make_tuple("unpacked", true); + py::print("->", *args, "end"_a="<-"); // -> unpacked True <- + +.. _ostream_redirect: + +Capturing standard output from ostream +====================================== + +Often, a library will use the streams ``std::cout`` and ``std::cerr`` to print, +but this does not play well with Python's standard ``sys.stdout`` and ``sys.stderr`` +redirection. Replacing a library's printing with `py::print <print>` may not +be feasible. This can be fixed using a guard around the library function that +redirects output to the corresponding Python streams: + +.. code-block:: cpp + + #include <pybind11/iostream.h> + + ... + + // Add a scoped redirect for your noisy code + m.def("noisy_func", []() { + py::scoped_ostream_redirect stream( + std::cout, // std::ostream& + py::module::import("sys").attr("stdout") // Python output + ); + call_noisy_func(); + }); + +This method respects flushes on the output streams and will flush if needed +when the scoped guard is destroyed. This allows the output to be redirected in +real time, such as to a Jupyter notebook. The two arguments, the C++ stream and +the Python output, are optional, and default to standard output if not given. An +extra type, `py::scoped_estream_redirect <scoped_estream_redirect>`, is identical +except for defaulting to ``std::cerr`` and ``sys.stderr``; this can be useful with +`py::call_guard`, which allows multiple items, but uses the default constructor: + +.. code-block:: py + + // Alternative: Call single function using call guard + m.def("noisy_func", &call_noisy_function, + py::call_guard<py::scoped_ostream_redirect, + py::scoped_estream_redirect>()); + +The redirection can also be done in Python with the addition of a context +manager, using the `py::add_ostream_redirect() <add_ostream_redirect>` function: + +.. code-block:: cpp + + py::add_ostream_redirect(m, "ostream_redirect"); + +The name in Python defaults to ``ostream_redirect`` if no name is passed. This +creates the following context manager in Python: + +.. code-block:: python + + with ostream_redirect(stdout=True, stderr=True): + noisy_function() + +It defaults to redirecting both streams, though you can use the keyword +arguments to disable one of the streams if needed. + +.. note:: + + The above methods will not redirect C-level output to file descriptors, such + as ``fprintf``. For those cases, you'll need to redirect the file + descriptors either directly in C or with Python's ``os.dup2`` function + in an operating-system dependent way. + +.. _eval: + +Evaluating Python expressions from strings and files +==================================================== + +pybind11 provides the `eval`, `exec` and `eval_file` functions to evaluate +Python expressions and statements. The following example illustrates how they +can be used. + +.. code-block:: cpp + + // At beginning of file + #include <pybind11/eval.h> + + ... + + // Evaluate in scope of main module + py::object scope = py::module::import("__main__").attr("__dict__"); + + // Evaluate an isolated expression + int result = py::eval("my_variable + 10", scope).cast<int>(); + + // Evaluate a sequence of statements + py::exec( + "print('Hello')\n" + "print('world!');", + scope); + + // Evaluate the statements in an separate Python file on disk + py::eval_file("script.py", scope); + +C++11 raw string literals are also supported and quite handy for this purpose. +The only requirement is that the first statement must be on a new line following +the raw string delimiter ``R"(``, ensuring all lines have common leading indent: + +.. code-block:: cpp + + py::exec(R"( + x = get_answer() + if x == 42: + print('Hello World!') + else: + print('Bye!') + )", scope + ); + +.. note:: + + `eval` and `eval_file` accept a template parameter that describes how the + string/file should be interpreted. Possible choices include ``eval_expr`` + (isolated expression), ``eval_single_statement`` (a single statement, return + value is always ``none``), and ``eval_statements`` (sequence of statements, + return value is always ``none``). `eval` defaults to ``eval_expr``, + `eval_file` defaults to ``eval_statements`` and `exec` is just a shortcut + for ``eval<eval_statements>``. diff --git a/3rdparty/pybind11/docs/advanced/smart_ptrs.rst b/3rdparty/pybind11/docs/advanced/smart_ptrs.rst new file mode 100644 index 00000000..da57748c --- /dev/null +++ b/3rdparty/pybind11/docs/advanced/smart_ptrs.rst @@ -0,0 +1,173 @@ +Smart pointers +############## + +std::unique_ptr +=============== + +Given a class ``Example`` with Python bindings, it's possible to return +instances wrapped in C++11 unique pointers, like so + +.. code-block:: cpp + + std::unique_ptr<Example> create_example() { return std::unique_ptr<Example>(new Example()); } + +.. code-block:: cpp + + m.def("create_example", &create_example); + +In other words, there is nothing special that needs to be done. While returning +unique pointers in this way is allowed, it is *illegal* to use them as function +arguments. For instance, the following function signature cannot be processed +by pybind11. + +.. code-block:: cpp + + void do_something_with_example(std::unique_ptr<Example> ex) { ... } + +The above signature would imply that Python needs to give up ownership of an +object that is passed to this function, which is generally not possible (for +instance, the object might be referenced elsewhere). + +std::shared_ptr +=============== + +The binding generator for classes, :class:`class_`, can be passed a template +type that denotes a special *holder* type that is used to manage references to +the object. If no such holder type template argument is given, the default for +a type named ``Type`` is ``std::unique_ptr<Type>``, which means that the object +is deallocated when Python's reference count goes to zero. + +It is possible to switch to other types of reference counting wrappers or smart +pointers, which is useful in codebases that rely on them. For instance, the +following snippet causes ``std::shared_ptr`` to be used instead. + +.. code-block:: cpp + + py::class_<Example, std::shared_ptr<Example> /* <- holder type */> obj(m, "Example"); + +Note that any particular class can only be associated with a single holder type. + +One potential stumbling block when using holder types is that they need to be +applied consistently. Can you guess what's broken about the following binding +code? + +.. code-block:: cpp + + class Child { }; + + class Parent { + public: + Parent() : child(std::make_shared<Child>()) { } + Child *get_child() { return child.get(); } /* Hint: ** DON'T DO THIS ** */ + private: + std::shared_ptr<Child> child; + }; + + PYBIND11_MODULE(example, m) { + py::class_<Child, std::shared_ptr<Child>>(m, "Child"); + + py::class_<Parent, std::shared_ptr<Parent>>(m, "Parent") + .def(py::init<>()) + .def("get_child", &Parent::get_child); + } + +The following Python code will cause undefined behavior (and likely a +segmentation fault). + +.. code-block:: python + + from example import Parent + print(Parent().get_child()) + +The problem is that ``Parent::get_child()`` returns a pointer to an instance of +``Child``, but the fact that this instance is already managed by +``std::shared_ptr<...>`` is lost when passing raw pointers. In this case, +pybind11 will create a second independent ``std::shared_ptr<...>`` that also +claims ownership of the pointer. In the end, the object will be freed **twice** +since these shared pointers have no way of knowing about each other. + +There are two ways to resolve this issue: + +1. For types that are managed by a smart pointer class, never use raw pointers + in function arguments or return values. In other words: always consistently + wrap pointers into their designated holder types (such as + ``std::shared_ptr<...>``). In this case, the signature of ``get_child()`` + should be modified as follows: + +.. code-block:: cpp + + std::shared_ptr<Child> get_child() { return child; } + +2. Adjust the definition of ``Child`` by specifying + ``std::enable_shared_from_this<T>`` (see cppreference_ for details) as a + base class. This adds a small bit of information to ``Child`` that allows + pybind11 to realize that there is already an existing + ``std::shared_ptr<...>`` and communicate with it. In this case, the + declaration of ``Child`` should look as follows: + +.. _cppreference: http://en.cppreference.com/w/cpp/memory/enable_shared_from_this + +.. code-block:: cpp + + class Child : public std::enable_shared_from_this<Child> { }; + +.. _smart_pointers: + +Custom smart pointers +===================== + +pybind11 supports ``std::unique_ptr`` and ``std::shared_ptr`` right out of the +box. For any other custom smart pointer, transparent conversions can be enabled +using a macro invocation similar to the following. It must be declared at the +top namespace level before any binding code: + +.. code-block:: cpp + + PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>); + +The first argument of :func:`PYBIND11_DECLARE_HOLDER_TYPE` should be a +placeholder name that is used as a template parameter of the second argument. +Thus, feel free to use any identifier, but use it consistently on both sides; +also, don't use the name of a type that already exists in your codebase. + +The macro also accepts a third optional boolean parameter that is set to false +by default. Specify + +.. code-block:: cpp + + PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>, true); + +if ``SmartPtr<T>`` can always be initialized from a ``T*`` pointer without the +risk of inconsistencies (such as multiple independent ``SmartPtr`` instances +believing that they are the sole owner of the ``T*`` pointer). A common +situation where ``true`` should be passed is when the ``T`` instances use +*intrusive* reference counting. + +Please take a look at the :ref:`macro_notes` before using this feature. + +By default, pybind11 assumes that your custom smart pointer has a standard +interface, i.e. provides a ``.get()`` member function to access the underlying +raw pointer. If this is not the case, pybind11's ``holder_helper`` must be +specialized: + +.. code-block:: cpp + + // Always needed for custom holder types + PYBIND11_DECLARE_HOLDER_TYPE(T, SmartPtr<T>); + + // Only needed if the type's `.get()` goes by another name + namespace pybind11 { namespace detail { + template <typename T> + struct holder_helper<SmartPtr<T>> { // <-- specialization + static const T *get(const SmartPtr<T> &p) { return p.getPointer(); } + }; + }} + +The above specialization informs pybind11 that the custom ``SmartPtr`` class +provides ``.get()`` functionality via ``.getPointer()``. + +.. seealso:: + + The file :file:`tests/test_smart_ptr.cpp` contains a complete example + that demonstrates how to work with custom reference-counting holder types + in more detail. diff --git a/3rdparty/pybind11/docs/basics.rst b/3rdparty/pybind11/docs/basics.rst new file mode 100644 index 00000000..7bf4d426 --- /dev/null +++ b/3rdparty/pybind11/docs/basics.rst @@ -0,0 +1,293 @@ +.. _basics: + +First steps +########### + +This sections demonstrates the basic features of pybind11. Before getting +started, make sure that development environment is set up to compile the +included set of test cases. + + +Compiling the test cases +======================== + +Linux/MacOS +----------- + +On Linux you'll need to install the **python-dev** or **python3-dev** packages as +well as **cmake**. On Mac OS, the included python version works out of the box, +but **cmake** must still be installed. + +After installing the prerequisites, run + +.. code-block:: bash + + mkdir build + cd build + cmake .. + make check -j 4 + +The last line will both compile and run the tests. + +Windows +------- + +On Windows, only **Visual Studio 2015** and newer are supported since pybind11 relies +on various C++11 language features that break older versions of Visual Studio. + +To compile and run the tests: + +.. code-block:: batch + + mkdir build + cd build + cmake .. + cmake --build . --config Release --target check + +This will create a Visual Studio project, compile and run the target, all from the +command line. + +.. Note:: + + If all tests fail, make sure that the Python binary and the testcases are compiled + for the same processor type and bitness (i.e. either **i386** or **x86_64**). You + can specify **x86_64** as the target architecture for the generated Visual Studio + project using ``cmake -A x64 ..``. + +.. seealso:: + + Advanced users who are already familiar with Boost.Python may want to skip + the tutorial and look at the test cases in the :file:`tests` directory, + which exercise all features of pybind11. + +Header and namespace conventions +================================ + +For brevity, all code examples assume that the following two lines are present: + +.. code-block:: cpp + + #include <pybind11/pybind11.h> + + namespace py = pybind11; + +Some features may require additional headers, but those will be specified as needed. + +.. _simple_example: + +Creating bindings for a simple function +======================================= + +Let's start by creating Python bindings for an extremely simple function, which +adds two numbers and returns their result: + +.. code-block:: cpp + + int add(int i, int j) { + return i + j; + } + +For simplicity [#f1]_, we'll put both this function and the binding code into +a file named :file:`example.cpp` with the following contents: + +.. code-block:: cpp + + #include <pybind11/pybind11.h> + + int add(int i, int j) { + return i + j; + } + + PYBIND11_MODULE(example, m) { + m.doc() = "pybind11 example plugin"; // optional module docstring + + m.def("add", &add, "A function which adds two numbers"); + } + +.. [#f1] In practice, implementation and binding code will generally be located + in separate files. + +The :func:`PYBIND11_MODULE` macro creates a function that will be called when an +``import`` statement is issued from within Python. The module name (``example``) +is given as the first macro argument (it should not be in quotes). The second +argument (``m``) defines a variable of type :class:`py::module <module>` which +is the main interface for creating bindings. The method :func:`module::def` +generates binding code that exposes the ``add()`` function to Python. + +.. note:: + + Notice how little code was needed to expose our function to Python: all + details regarding the function's parameters and return value were + automatically inferred using template metaprogramming. This overall + approach and the used syntax are borrowed from Boost.Python, though the + underlying implementation is very different. + +pybind11 is a header-only library, hence it is not necessary to link against +any special libraries and there are no intermediate (magic) translation steps. +On Linux, the above example can be compiled using the following command: + +.. code-block:: bash + + $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` + +For more details on the required compiler flags on Linux and MacOS, see +:ref:`building_manually`. For complete cross-platform compilation instructions, +refer to the :ref:`compiling` page. + +The `python_example`_ and `cmake_example`_ repositories are also a good place +to start. They are both complete project examples with cross-platform build +systems. The only difference between the two is that `python_example`_ uses +Python's ``setuptools`` to build the module, while `cmake_example`_ uses CMake +(which may be preferable for existing C++ projects). + +.. _python_example: https://github.com/pybind/python_example +.. _cmake_example: https://github.com/pybind/cmake_example + +Building the above C++ code will produce a binary module file that can be +imported to Python. Assuming that the compiled module is located in the +current directory, the following interactive Python session shows how to +load and execute the example: + +.. code-block:: pycon + + $ python + Python 2.7.10 (default, Aug 22 2015, 20:33:39) + [GCC 4.2.1 Compatible Apple LLVM 7.0.0 (clang-700.0.59.1)] on darwin + Type "help", "copyright", "credits" or "license" for more information. + >>> import example + >>> example.add(1, 2) + 3L + >>> + +.. _keyword_args: + +Keyword arguments +================= + +With a simple code modification, it is possible to inform Python about the +names of the arguments ("i" and "j" in this case). + +.. code-block:: cpp + + m.def("add", &add, "A function which adds two numbers", + py::arg("i"), py::arg("j")); + +:class:`arg` is one of several special tag classes which can be used to pass +metadata into :func:`module::def`. With this modified binding code, we can now +call the function using keyword arguments, which is a more readable alternative +particularly for functions taking many parameters: + +.. code-block:: pycon + + >>> import example + >>> example.add(i=1, j=2) + 3L + +The keyword names also appear in the function signatures within the documentation. + +.. code-block:: pycon + + >>> help(example) + + .... + + FUNCTIONS + add(...) + Signature : (i: int, j: int) -> int + + A function which adds two numbers + +A shorter notation for named arguments is also available: + +.. code-block:: cpp + + // regular notation + m.def("add1", &add, py::arg("i"), py::arg("j")); + // shorthand + using namespace pybind11::literals; + m.def("add2", &add, "i"_a, "j"_a); + +The :var:`_a` suffix forms a C++11 literal which is equivalent to :class:`arg`. +Note that the literal operator must first be made visible with the directive +``using namespace pybind11::literals``. This does not bring in anything else +from the ``pybind11`` namespace except for literals. + +.. _default_args: + +Default arguments +================= + +Suppose now that the function to be bound has default arguments, e.g.: + +.. code-block:: cpp + + int add(int i = 1, int j = 2) { + return i + j; + } + +Unfortunately, pybind11 cannot automatically extract these parameters, since they +are not part of the function's type information. However, they are simple to specify +using an extension of :class:`arg`: + +.. code-block:: cpp + + m.def("add", &add, "A function which adds two numbers", + py::arg("i") = 1, py::arg("j") = 2); + +The default values also appear within the documentation. + +.. code-block:: pycon + + >>> help(example) + + .... + + FUNCTIONS + add(...) + Signature : (i: int = 1, j: int = 2) -> int + + A function which adds two numbers + +The shorthand notation is also available for default arguments: + +.. code-block:: cpp + + // regular notation + m.def("add1", &add, py::arg("i") = 1, py::arg("j") = 2); + // shorthand + m.def("add2", &add, "i"_a=1, "j"_a=2); + +Exporting variables +=================== + +To expose a value from C++, use the ``attr`` function to register it in a +module as shown below. Built-in types and general objects (more on that later) +are automatically converted when assigned as attributes, and can be explicitly +converted using the function ``py::cast``. + +.. code-block:: cpp + + PYBIND11_MODULE(example, m) { + m.attr("the_answer") = 42; + py::object world = py::cast("World"); + m.attr("what") = world; + } + +These are then accessible from Python: + +.. code-block:: pycon + + >>> import example + >>> example.the_answer + 42 + >>> example.what + 'World' + +.. _supported_types: + +Supported data types +==================== + +A large number of data types are supported out of the box and can be used +seamlessly as functions arguments, return values or with ``py::cast`` in general. +For a full overview, see the :doc:`advanced/cast/index` section. diff --git a/3rdparty/pybind11/docs/benchmark.py b/3rdparty/pybind11/docs/benchmark.py new file mode 100644 index 00000000..6dc0604e --- /dev/null +++ b/3rdparty/pybind11/docs/benchmark.py @@ -0,0 +1,88 @@ +import random +import os +import time +import datetime as dt + +nfns = 4 # Functions per class +nargs = 4 # Arguments per function + + +def generate_dummy_code_pybind11(nclasses=10): + decl = "" + bindings = "" + + for cl in range(nclasses): + decl += "class cl%03i;\n" % cl + decl += '\n' + + for cl in range(nclasses): + decl += "class cl%03i {\n" % cl + decl += "public:\n" + bindings += ' py::class_<cl%03i>(m, "cl%03i")\n' % (cl, cl) + for fn in range(nfns): + ret = random.randint(0, nclasses - 1) + params = [random.randint(0, nclasses - 1) for i in range(nargs)] + decl += " cl%03i *fn_%03i(" % (ret, fn) + decl += ", ".join("cl%03i *" % p for p in params) + decl += ");\n" + bindings += ' .def("fn_%03i", &cl%03i::fn_%03i)\n' % \ + (fn, cl, fn) + decl += "};\n\n" + bindings += ' ;\n' + + result = "#include <pybind11/pybind11.h>\n\n" + result += "namespace py = pybind11;\n\n" + result += decl + '\n' + result += "PYBIND11_MODULE(example, m) {\n" + result += bindings + result += "}" + return result + + +def generate_dummy_code_boost(nclasses=10): + decl = "" + bindings = "" + + for cl in range(nclasses): + decl += "class cl%03i;\n" % cl + decl += '\n' + + for cl in range(nclasses): + decl += "class cl%03i {\n" % cl + decl += "public:\n" + bindings += ' py::class_<cl%03i>("cl%03i")\n' % (cl, cl) + for fn in range(nfns): + ret = random.randint(0, nclasses - 1) + params = [random.randint(0, nclasses - 1) for i in range(nargs)] + decl += " cl%03i *fn_%03i(" % (ret, fn) + decl += ", ".join("cl%03i *" % p for p in params) + decl += ");\n" + bindings += ' .def("fn_%03i", &cl%03i::fn_%03i, py::return_value_policy<py::manage_new_object>())\n' % \ + (fn, cl, fn) + decl += "};\n\n" + bindings += ' ;\n' + + result = "#include <boost/python.hpp>\n\n" + result += "namespace py = boost::python;\n\n" + result += decl + '\n' + result += "BOOST_PYTHON_MODULE(example) {\n" + result += bindings + result += "}" + return result + + +for codegen in [generate_dummy_code_pybind11, generate_dummy_code_boost]: + print ("{") + for i in range(0, 10): + nclasses = 2 ** i + with open("test.cpp", "w") as f: + f.write(codegen(nclasses)) + n1 = dt.datetime.now() + os.system("g++ -Os -shared -rdynamic -undefined dynamic_lookup " + "-fvisibility=hidden -std=c++14 test.cpp -I include " + "-I /System/Library/Frameworks/Python.framework/Headers -o test.so") + n2 = dt.datetime.now() + elapsed = (n2 - n1).total_seconds() + size = os.stat('test.so').st_size + print(" {%i, %f, %i}," % (nclasses * nfns, elapsed, size)) + print ("}") diff --git a/3rdparty/pybind11/docs/benchmark.rst b/3rdparty/pybind11/docs/benchmark.rst new file mode 100644 index 00000000..59d533df --- /dev/null +++ b/3rdparty/pybind11/docs/benchmark.rst @@ -0,0 +1,97 @@ +Benchmark +========= + +The following is the result of a synthetic benchmark comparing both compilation +time and module size of pybind11 against Boost.Python. A detailed report about a +Boost.Python to pybind11 conversion of a real project is available here: [#f1]_. + +.. [#f1] http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf + +Setup +----- + +A python script (see the ``docs/benchmark.py`` file) was used to generate a set +of files with dummy classes whose count increases for each successive benchmark +(between 1 and 2048 classes in powers of two). Each class has four methods with +a randomly generated signature with a return value and four arguments. (There +was no particular reason for this setup other than the desire to generate many +unique function signatures whose count could be controlled in a simple way.) + +Here is an example of the binding code for one class: + +.. code-block:: cpp + + ... + class cl034 { + public: + cl279 *fn_000(cl084 *, cl057 *, cl065 *, cl042 *); + cl025 *fn_001(cl098 *, cl262 *, cl414 *, cl121 *); + cl085 *fn_002(cl445 *, cl297 *, cl145 *, cl421 *); + cl470 *fn_003(cl200 *, cl323 *, cl332 *, cl492 *); + }; + ... + + PYBIND11_MODULE(example, m) { + ... + py::class_<cl034>(m, "cl034") + .def("fn_000", &cl034::fn_000) + .def("fn_001", &cl034::fn_001) + .def("fn_002", &cl034::fn_002) + .def("fn_003", &cl034::fn_003) + ... + } + +The Boost.Python version looks almost identical except that a return value +policy had to be specified as an argument to ``def()``. For both libraries, +compilation was done with + +.. code-block:: bash + + Apple LLVM version 7.0.2 (clang-700.1.81) + +and the following compilation flags + +.. code-block:: bash + + g++ -Os -shared -rdynamic -undefined dynamic_lookup -fvisibility=hidden -std=c++14 + +Compilation time +---------------- + +The following log-log plot shows how the compilation time grows for an +increasing number of class and function declarations. pybind11 includes many +fewer headers, which initially leads to shorter compilation times, but the +performance is ultimately fairly similar (pybind11 is 19.8 seconds faster for +the largest largest file with 2048 classes and a total of 8192 methods -- a +modest **1.2x** speedup relative to Boost.Python, which required 116.35 +seconds). + +.. only:: not latex + + .. image:: pybind11_vs_boost_python1.svg + +.. only:: latex + + .. image:: pybind11_vs_boost_python1.png + +Module size +----------- + +Differences between the two libraries become much more pronounced when +considering the file size of the generated Python plugin: for the largest file, +the binary generated by Boost.Python required 16.8 MiB, which was **2.17 +times** / **9.1 megabytes** larger than the output generated by pybind11. For +very small inputs, Boost.Python has an edge in the plot below -- however, note +that it stores many definitions in an external library, whose size was not +included here, hence the comparison is slightly shifted in Boost.Python's +favor. + +.. only:: not latex + + .. image:: pybind11_vs_boost_python2.svg + +.. only:: latex + + .. image:: pybind11_vs_boost_python2.png + + diff --git a/3rdparty/pybind11/docs/changelog.rst b/3rdparty/pybind11/docs/changelog.rst new file mode 100644 index 00000000..2def2b07 --- /dev/null +++ b/3rdparty/pybind11/docs/changelog.rst @@ -0,0 +1,1277 @@ +.. _changelog: + +Changelog +######### + +Starting with version 1.8.0, pybind11 releases use a `semantic versioning +<http://semver.org>`_ policy. + +v2.5.0 (Mar 31, 2020) +----------------------------------------------------- + +* Use C++17 fold expressions in type casters, if available. This can + improve performance during overload resolution when functions have + multiple arguments. + `#2043 <https://github.com/pybind/pybind11/pull/2043>`_. + +* Changed include directory resolution in ``pybind11/__init__.py`` + and installation in ``setup.py``. This fixes a number of open issues + where pybind11 headers could not be found in certain environments. + `#1995 <https://github.com/pybind/pybind11/pull/1995>`_. + +* C++20 ``char8_t`` and ``u8string`` support. `#2026 + <https://github.com/pybind/pybind11/pull/2026>`_. + +* CMake: search for Python 3.9. `bb9c91 + <https://github.com/pybind/pybind11/commit/bb9c91>`_. + +* Fixes for MSYS-based build environments. + `#2087 <https://github.com/pybind/pybind11/pull/2087>`_, + `#2053 <https://github.com/pybind/pybind11/pull/2053>`_. + +* STL bindings for ``std::vector<...>::clear``. `#2074 + <https://github.com/pybind/pybind11/pull/2074>`_. + +* Read-only flag for ``py::buffer``. `#1466 + <https://github.com/pybind/pybind11/pull/1466>`_. + +* Exception handling during module initialization. + `bf2b031 <https://github.com/pybind/pybind11/commit/bf2b031>`_. + +* Support linking against a CPython debug build. + `#2025 <https://github.com/pybind/pybind11/pull/2025>`_. + +* Fixed issues involving the availability and use of aligned ``new`` and + ``delete``. `#1988 <https://github.com/pybind/pybind11/pull/1988>`_, + `759221 <https://github.com/pybind/pybind11/commit/759221>`_. + +* Fixed a resource leak upon interpreter shutdown. + `#2020 <https://github.com/pybind/pybind11/pull/2020>`_. + +* Fixed error handling in the boolean caster. + `#1976 <https://github.com/pybind/pybind11/pull/1976>`_. + +v2.4.3 (Oct 15, 2019) +----------------------------------------------------- + +* Adapt pybind11 to a C API convention change in Python 3.8. `#1950 + <https://github.com/pybind/pybind11/pull/1950>`_. + +v2.4.2 (Sep 21, 2019) +----------------------------------------------------- + +* Replaced usage of a C++14 only construct. `#1929 + <https://github.com/pybind/pybind11/pull/1929>`_. + +* Made an ifdef future-proof for Python >= 4. `f3109d + <https://github.com/pybind/pybind11/commit/f3109d>`_. + +v2.4.1 (Sep 20, 2019) +----------------------------------------------------- + +* Fixed a problem involving implicit conversion from enumerations to integers + on Python 3.8. `#1780 <https://github.com/pybind/pybind11/pull/1780>`_. + +v2.4.0 (Sep 19, 2019) +----------------------------------------------------- + +* Try harder to keep pybind11-internal data structures separate when there + are potential ABI incompatibilities. Fixes crashes that occurred when loading + multiple pybind11 extensions that were e.g. compiled by GCC (libstdc++) + and Clang (libc++). + `#1588 <https://github.com/pybind/pybind11/pull/1588>`_ and + `c9f5a <https://github.com/pybind/pybind11/commit/c9f5a>`_. + +* Added support for ``__await__``, ``__aiter__``, and ``__anext__`` protocols. + `#1842 <https://github.com/pybind/pybind11/pull/1842>`_. + +* ``pybind11_add_module()``: don't strip symbols when compiling in + ``RelWithDebInfo`` mode. `#1980 + <https://github.com/pybind/pybind11/pull/1980>`_. + +* ``enum_``: Reproduce Python behavior when comparing against invalid values + (e.g. ``None``, strings, etc.). Add back support for ``__invert__()``. + `#1912 <https://github.com/pybind/pybind11/pull/1912>`_, + `#1907 <https://github.com/pybind/pybind11/pull/1907>`_. + +* List insertion operation for ``py::list``. + Added ``.empty()`` to all collection types. + Added ``py::set::contains()`` and ``py::dict::contains()``. + `#1887 <https://github.com/pybind/pybind11/pull/1887>`_, + `#1884 <https://github.com/pybind/pybind11/pull/1884>`_, + `#1888 <https://github.com/pybind/pybind11/pull/1888>`_. + +* ``py::details::overload_cast_impl`` is available in C++11 mode, can be used + like ``overload_cast`` with an additional set of parantheses. + `#1581 <https://github.com/pybind/pybind11/pull/1581>`_. + +* Fixed ``get_include()`` on Conda. + `#1877 <https://github.com/pybind/pybind11/pull/1877>`_. + +* ``stl_bind.h``: negative indexing support. + `#1882 <https://github.com/pybind/pybind11/pull/1882>`_. + +* Minor CMake fix to add MinGW compatibility. + `#1851 <https://github.com/pybind/pybind11/pull/1851>`_. + +* GIL-related fixes. + `#1836 <https://github.com/pybind/pybind11/pull/1836>`_, + `8b90b <https://github.com/pybind/pybind11/commit/8b90b>`_. + +* Other very minor/subtle fixes and improvements. + `#1329 <https://github.com/pybind/pybind11/pull/1329>`_, + `#1910 <https://github.com/pybind/pybind11/pull/1910>`_, + `#1863 <https://github.com/pybind/pybind11/pull/1863>`_, + `#1847 <https://github.com/pybind/pybind11/pull/1847>`_, + `#1890 <https://github.com/pybind/pybind11/pull/1890>`_, + `#1860 <https://github.com/pybind/pybind11/pull/1860>`_, + `#1848 <https://github.com/pybind/pybind11/pull/1848>`_, + `#1821 <https://github.com/pybind/pybind11/pull/1821>`_, + `#1837 <https://github.com/pybind/pybind11/pull/1837>`_, + `#1833 <https://github.com/pybind/pybind11/pull/1833>`_, + `#1748 <https://github.com/pybind/pybind11/pull/1748>`_, + `#1852 <https://github.com/pybind/pybind11/pull/1852>`_. + +v2.3.0 (June 11, 2019) +----------------------------------------------------- + +* Significantly reduced module binary size (10-20%) when compiled in C++11 mode + with GCC/Clang, or in any mode with MSVC. Function signatures are now always + precomputed at compile time (this was previously only available in C++14 mode + for non-MSVC compilers). + `#934 <https://github.com/pybind/pybind11/pull/934>`_. + +* Add basic support for tag-based static polymorphism, where classes + provide a method to returns the desired type of an instance. + `#1326 <https://github.com/pybind/pybind11/pull/1326>`_. + +* Python type wrappers (``py::handle``, ``py::object``, etc.) + now support map Python's number protocol onto C++ arithmetic + operators such as ``operator+``, ``operator/=``, etc. + `#1511 <https://github.com/pybind/pybind11/pull/1511>`_. + +* A number of improvements related to enumerations: + + 1. The ``enum_`` implementation was rewritten from scratch to reduce + code bloat. Rather than instantiating a full implementation for each + enumeration, most code is now contained in a generic base class. + `#1511 <https://github.com/pybind/pybind11/pull/1511>`_. + + 2. The ``value()`` method of ``py::enum_`` now accepts an optional + docstring that will be shown in the documentation of the associated + enumeration. `#1160 <https://github.com/pybind/pybind11/pull/1160>`_. + + 3. check for already existing enum value and throw an error if present. + `#1453 <https://github.com/pybind/pybind11/pull/1453>`_. + +* Support for over-aligned type allocation via C++17's aligned ``new`` + statement. `#1582 <https://github.com/pybind/pybind11/pull/1582>`_. + +* Added ``py::ellipsis()`` method for slicing of multidimensional NumPy arrays + `#1502 <https://github.com/pybind/pybind11/pull/1502>`_. + +* Numerous Improvements to the ``mkdoc.py`` script for extracting documentation + from C++ header files. + `#1788 <https://github.com/pybind/pybind11/pull/1788>`_. + +* ``pybind11_add_module()``: allow including Python as a ``SYSTEM`` include path. + `#1416 <https://github.com/pybind/pybind11/pull/1416>`_. + +* ``pybind11/stl.h`` does not convert strings to ``vector<string>`` anymore. + `#1258 <https://github.com/pybind/pybind11/issues/1258>`_. + +* Mark static methods as such to fix auto-generated Sphinx documentation. + `#1732 <https://github.com/pybind/pybind11/pull/1732>`_. + +* Re-throw forced unwind exceptions (e.g. during pthread termination). + `#1208 <https://github.com/pybind/pybind11/pull/1208>`_. + +* Added ``__contains__`` method to the bindings of maps (``std::map``, + ``std::unordered_map``). + `#1767 <https://github.com/pybind/pybind11/pull/1767>`_. + +* Improvements to ``gil_scoped_acquire``. + `#1211 <https://github.com/pybind/pybind11/pull/1211>`_. + +* Type caster support for ``std::deque<T>``. + `#1609 <https://github.com/pybind/pybind11/pull/1609>`_. + +* Support for ``std::unique_ptr`` holders, whose deleters differ between a base and derived + class. `#1353 <https://github.com/pybind/pybind11/pull/1353>`_. + +* Construction of STL array/vector-like data structures from + iterators. Added an ``extend()`` operation. + `#1709 <https://github.com/pybind/pybind11/pull/1709>`_, + +* CMake build system improvements for projects that include non-C++ + files (e.g. plain C, CUDA) in ``pybind11_add_module`` et al. + `#1678 <https://github.com/pybind/pybind11/pull/1678>`_. + +* Fixed asynchronous invocation and deallocation of Python functions + wrapped in ``std::function``. + `#1595 <https://github.com/pybind/pybind11/pull/1595>`_. + +* Fixes regarding return value policy propagation in STL type casters. + `#1603 <https://github.com/pybind/pybind11/pull/1603>`_. + +* Fixed scoped enum comparisons. + `#1571 <https://github.com/pybind/pybind11/pull/1571>`_. + +* Fixed iostream redirection for code that releases the GIL. + `#1368 <https://github.com/pybind/pybind11/pull/1368>`_, + +* A number of CI-related fixes. + `#1757 <https://github.com/pybind/pybind11/pull/1757>`_, + `#1744 <https://github.com/pybind/pybind11/pull/1744>`_, + `#1670 <https://github.com/pybind/pybind11/pull/1670>`_. + +v2.2.4 (September 11, 2018) +----------------------------------------------------- + +* Use new Python 3.7 Thread Specific Storage (TSS) implementation if available. + `#1454 <https://github.com/pybind/pybind11/pull/1454>`_, + `#1517 <https://github.com/pybind/pybind11/pull/1517>`_. + +* Fixes for newer MSVC versions and C++17 mode. + `#1347 <https://github.com/pybind/pybind11/pull/1347>`_, + `#1462 <https://github.com/pybind/pybind11/pull/1462>`_. + +* Propagate return value policies to type-specific casters + when casting STL containers. + `#1455 <https://github.com/pybind/pybind11/pull/1455>`_. + +* Allow ostream-redirection of more than 1024 characters. + `#1479 <https://github.com/pybind/pybind11/pull/1479>`_. + +* Set ``Py_DEBUG`` define when compiling against a debug Python build. + `#1438 <https://github.com/pybind/pybind11/pull/1438>`_. + +* Untangle integer logic in number type caster to work for custom + types that may only be castable to a restricted set of builtin types. + `#1442 <https://github.com/pybind/pybind11/pull/1442>`_. + +* CMake build system: Remember Python version in cache file. + `#1434 <https://github.com/pybind/pybind11/pull/1434>`_. + +* Fix for custom smart pointers: use ``std::addressof`` to obtain holder + address instead of ``operator&``. + `#1435 <https://github.com/pybind/pybind11/pull/1435>`_. + +* Properly report exceptions thrown during module initialization. + `#1362 <https://github.com/pybind/pybind11/pull/1362>`_. + +* Fixed a segmentation fault when creating empty-shaped NumPy array. + `#1371 <https://github.com/pybind/pybind11/pull/1371>`_. + +* The version of Intel C++ compiler must be >= 2017, and this is now checked by + the header files. `#1363 <https://github.com/pybind/pybind11/pull/1363>`_. + +* A few minor typo fixes and improvements to the test suite, and + patches that silence compiler warnings. + +* Vectors now support construction from generators, as well as ``extend()`` from a + list or generator. + `#1496 <https://github.com/pybind/pybind11/pull/1496>`_. + + +v2.2.3 (April 29, 2018) +----------------------------------------------------- + +* The pybind11 header location detection was replaced by a new implementation + that no longer depends on ``pip`` internals (the recently released ``pip`` + 10 has restricted access to this API). + `#1190 <https://github.com/pybind/pybind11/pull/1190>`_. + +* Small adjustment to an implementation detail to work around a compiler segmentation fault in Clang 3.3/3.4. + `#1350 <https://github.com/pybind/pybind11/pull/1350>`_. + +* The minimal supported version of the Intel compiler was >= 17.0 since + pybind11 v2.1. This check is now explicit, and a compile-time error is raised + if the compiler meet the requirement. + `#1363 <https://github.com/pybind/pybind11/pull/1363>`_. + +* Fixed an endianness-related fault in the test suite. + `#1287 <https://github.com/pybind/pybind11/pull/1287>`_. + +v2.2.2 (February 7, 2018) +----------------------------------------------------- + +* Fixed a segfault when combining embedded interpreter + shutdown/reinitialization with external loaded pybind11 modules. + `#1092 <https://github.com/pybind/pybind11/pull/1092>`_. + +* Eigen support: fixed a bug where Nx1/1xN numpy inputs couldn't be passed as + arguments to Eigen vectors (which for Eigen are simply compile-time fixed + Nx1/1xN matrices). + `#1106 <https://github.com/pybind/pybind11/pull/1106>`_. + +* Clarified to license by moving the licensing of contributions from + ``LICENSE`` into ``CONTRIBUTING.md``: the licensing of contributions is not + actually part of the software license as distributed. This isn't meant to be + a substantial change in the licensing of the project, but addresses concerns + that the clause made the license non-standard. + `#1109 <https://github.com/pybind/pybind11/issues/1109>`_. + +* Fixed a regression introduced in 2.1 that broke binding functions with lvalue + character literal arguments. + `#1128 <https://github.com/pybind/pybind11/pull/1128>`_. + +* MSVC: fix for compilation failures under /permissive-, and added the flag to + the appveyor test suite. + `#1155 <https://github.com/pybind/pybind11/pull/1155>`_. + +* Fixed ``__qualname__`` generation, and in turn, fixes how class names + (especially nested class names) are shown in generated docstrings. + `#1171 <https://github.com/pybind/pybind11/pull/1171>`_. + +* Updated the FAQ with a suggested project citation reference. + `#1189 <https://github.com/pybind/pybind11/pull/1189>`_. + +* Added fixes for deprecation warnings when compiled under C++17 with + ``-Wdeprecated`` turned on, and add ``-Wdeprecated`` to the test suite + compilation flags. + `#1191 <https://github.com/pybind/pybind11/pull/1191>`_. + +* Fixed outdated PyPI URLs in ``setup.py``. + `#1213 <https://github.com/pybind/pybind11/pull/1213>`_. + +* Fixed a refcount leak for arguments that end up in a ``py::args`` argument + for functions with both fixed positional and ``py::args`` arguments. + `#1216 <https://github.com/pybind/pybind11/pull/1216>`_. + +* Fixed a potential segfault resulting from possible premature destruction of + ``py::args``/``py::kwargs`` arguments with overloaded functions. + `#1223 <https://github.com/pybind/pybind11/pull/1223>`_. + +* Fixed ``del map[item]`` for a ``stl_bind.h`` bound stl map. + `#1229 <https://github.com/pybind/pybind11/pull/1229>`_. + +* Fixed a regression from v2.1.x where the aggregate initialization could + unintentionally end up at a constructor taking a templated + ``std::initializer_list<T>`` argument. + `#1249 <https://github.com/pybind/pybind11/pull/1249>`_. + +* Fixed an issue where calling a function with a keep_alive policy on the same + nurse/patient pair would cause the internal patient storage to needlessly + grow (unboundedly, if the nurse is long-lived). + `#1251 <https://github.com/pybind/pybind11/issues/1251>`_. + +* Various other minor fixes. + +v2.2.1 (September 14, 2017) +----------------------------------------------------- + +* Added ``py::module::reload()`` member function for reloading a module. + `#1040 <https://github.com/pybind/pybind11/pull/1040>`_. + +* Fixed a reference leak in the number converter. + `#1078 <https://github.com/pybind/pybind11/pull/1078>`_. + +* Fixed compilation with Clang on host GCC < 5 (old libstdc++ which isn't fully + C++11 compliant). `#1062 <https://github.com/pybind/pybind11/pull/1062>`_. + +* Fixed a regression where the automatic ``std::vector<bool>`` caster would + fail to compile. The same fix also applies to any container which returns + element proxies instead of references. + `#1053 <https://github.com/pybind/pybind11/pull/1053>`_. + +* Fixed a regression where the ``py::keep_alive`` policy could not be applied + to constructors. `#1065 <https://github.com/pybind/pybind11/pull/1065>`_. + +* Fixed a nullptr dereference when loading a ``py::module_local`` type + that's only registered in an external module. + `#1058 <https://github.com/pybind/pybind11/pull/1058>`_. + +* Fixed implicit conversion of accessors to types derived from ``py::object``. + `#1076 <https://github.com/pybind/pybind11/pull/1076>`_. + +* The ``name`` in ``PYBIND11_MODULE(name, variable)`` can now be a macro. + `#1082 <https://github.com/pybind/pybind11/pull/1082>`_. + +* Relaxed overly strict ``py::pickle()`` check for matching get and set types. + `#1064 <https://github.com/pybind/pybind11/pull/1064>`_. + +* Conversion errors now try to be more informative when it's likely that + a missing header is the cause (e.g. forgetting ``<pybind11/stl.h>``). + `#1077 <https://github.com/pybind/pybind11/pull/1077>`_. + +v2.2.0 (August 31, 2017) +----------------------------------------------------- + +* Support for embedding the Python interpreter. See the + :doc:`documentation page </advanced/embedding>` for a + full overview of the new features. + `#774 <https://github.com/pybind/pybind11/pull/774>`_, + `#889 <https://github.com/pybind/pybind11/pull/889>`_, + `#892 <https://github.com/pybind/pybind11/pull/892>`_, + `#920 <https://github.com/pybind/pybind11/pull/920>`_. + + .. code-block:: cpp + + #include <pybind11/embed.h> + namespace py = pybind11; + + int main() { + py::scoped_interpreter guard{}; // start the interpreter and keep it alive + + py::print("Hello, World!"); // use the Python API + } + +* Support for inheriting from multiple C++ bases in Python. + `#693 <https://github.com/pybind/pybind11/pull/693>`_. + + .. code-block:: python + + from cpp_module import CppBase1, CppBase2 + + class PyDerived(CppBase1, CppBase2): + def __init__(self): + CppBase1.__init__(self) # C++ bases must be initialized explicitly + CppBase2.__init__(self) + +* ``PYBIND11_MODULE`` is now the preferred way to create module entry points. + ``PYBIND11_PLUGIN`` is deprecated. See :ref:`macros` for details. + `#879 <https://github.com/pybind/pybind11/pull/879>`_. + + .. code-block:: cpp + + // new + PYBIND11_MODULE(example, m) { + m.def("add", [](int a, int b) { return a + b; }); + } + + // old + PYBIND11_PLUGIN(example) { + py::module m("example"); + m.def("add", [](int a, int b) { return a + b; }); + return m.ptr(); + } + +* pybind11's headers and build system now more strictly enforce hidden symbol + visibility for extension modules. This should be seamless for most users, + but see the :doc:`upgrade` if you use a custom build system. + `#995 <https://github.com/pybind/pybind11/pull/995>`_. + +* Support for ``py::module_local`` types which allow multiple modules to + export the same C++ types without conflicts. This is useful for opaque + types like ``std::vector<int>``. ``py::bind_vector`` and ``py::bind_map`` + now default to ``py::module_local`` if their elements are builtins or + local types. See :ref:`module_local` for details. + `#949 <https://github.com/pybind/pybind11/pull/949>`_, + `#981 <https://github.com/pybind/pybind11/pull/981>`_, + `#995 <https://github.com/pybind/pybind11/pull/995>`_, + `#997 <https://github.com/pybind/pybind11/pull/997>`_. + +* Custom constructors can now be added very easily using lambdas or factory + functions which return a class instance by value, pointer or holder. This + supersedes the old placement-new ``__init__`` technique. + See :ref:`custom_constructors` for details. + `#805 <https://github.com/pybind/pybind11/pull/805>`_, + `#1014 <https://github.com/pybind/pybind11/pull/1014>`_. + + .. code-block:: cpp + + struct Example { + Example(std::string); + }; + + py::class_<Example>(m, "Example") + .def(py::init<std::string>()) // existing constructor + .def(py::init([](int n) { // custom constructor + return std::make_unique<Example>(std::to_string(n)); + })); + +* Similarly to custom constructors, pickling support functions are now bound + using the ``py::pickle()`` adaptor which improves type safety. See the + :doc:`upgrade` and :ref:`pickling` for details. + `#1038 <https://github.com/pybind/pybind11/pull/1038>`_. + +* Builtin support for converting C++17 standard library types and general + conversion improvements: + + 1. C++17 ``std::variant`` is supported right out of the box. C++11/14 + equivalents (e.g. ``boost::variant``) can also be added with a simple + user-defined specialization. See :ref:`cpp17_container_casters` for details. + `#811 <https://github.com/pybind/pybind11/pull/811>`_, + `#845 <https://github.com/pybind/pybind11/pull/845>`_, + `#989 <https://github.com/pybind/pybind11/pull/989>`_. + + 2. Out-of-the-box support for C++17 ``std::string_view``. + `#906 <https://github.com/pybind/pybind11/pull/906>`_. + + 3. Improved compatibility of the builtin ``optional`` converter. + `#874 <https://github.com/pybind/pybind11/pull/874>`_. + + 4. The ``bool`` converter now accepts ``numpy.bool_`` and types which + define ``__bool__`` (Python 3.x) or ``__nonzero__`` (Python 2.7). + `#925 <https://github.com/pybind/pybind11/pull/925>`_. + + 5. C++-to-Python casters are now more efficient and move elements out + of rvalue containers whenever possible. + `#851 <https://github.com/pybind/pybind11/pull/851>`_, + `#936 <https://github.com/pybind/pybind11/pull/936>`_, + `#938 <https://github.com/pybind/pybind11/pull/938>`_. + + 6. Fixed ``bytes`` to ``std::string/char*`` conversion on Python 3. + `#817 <https://github.com/pybind/pybind11/pull/817>`_. + + 7. Fixed lifetime of temporary C++ objects created in Python-to-C++ conversions. + `#924 <https://github.com/pybind/pybind11/pull/924>`_. + +* Scope guard call policy for RAII types, e.g. ``py::call_guard<py::gil_scoped_release>()``, + ``py::call_guard<py::scoped_ostream_redirect>()``. See :ref:`call_policies` for details. + `#740 <https://github.com/pybind/pybind11/pull/740>`_. + +* Utility for redirecting C++ streams to Python (e.g. ``std::cout`` -> + ``sys.stdout``). Scope guard ``py::scoped_ostream_redirect`` in C++ and + a context manager in Python. See :ref:`ostream_redirect`. + `#1009 <https://github.com/pybind/pybind11/pull/1009>`_. + +* Improved handling of types and exceptions across module boundaries. + `#915 <https://github.com/pybind/pybind11/pull/915>`_, + `#951 <https://github.com/pybind/pybind11/pull/951>`_, + `#995 <https://github.com/pybind/pybind11/pull/995>`_. + +* Fixed destruction order of ``py::keep_alive`` nurse/patient objects + in reference cycles. + `#856 <https://github.com/pybind/pybind11/pull/856>`_. + +* Numpy and buffer protocol related improvements: + + 1. Support for negative strides in Python buffer objects/numpy arrays. This + required changing integers from unsigned to signed for the related C++ APIs. + Note: If you have compiler warnings enabled, you may notice some new conversion + warnings after upgrading. These can be resolved with ``static_cast``. + `#782 <https://github.com/pybind/pybind11/pull/782>`_. + + 2. Support ``std::complex`` and arrays inside ``PYBIND11_NUMPY_DTYPE``. + `#831 <https://github.com/pybind/pybind11/pull/831>`_, + `#832 <https://github.com/pybind/pybind11/pull/832>`_. + + 3. Support for constructing ``py::buffer_info`` and ``py::arrays`` using + arbitrary containers or iterators instead of requiring a ``std::vector``. + `#788 <https://github.com/pybind/pybind11/pull/788>`_, + `#822 <https://github.com/pybind/pybind11/pull/822>`_, + `#860 <https://github.com/pybind/pybind11/pull/860>`_. + + 4. Explicitly check numpy version and require >= 1.7.0. + `#819 <https://github.com/pybind/pybind11/pull/819>`_. + +* Support for allowing/prohibiting ``None`` for specific arguments and improved + ``None`` overload resolution order. See :ref:`none_arguments` for details. + `#843 <https://github.com/pybind/pybind11/pull/843>`_. + `#859 <https://github.com/pybind/pybind11/pull/859>`_. + +* Added ``py::exec()`` as a shortcut for ``py::eval<py::eval_statements>()`` + and support for C++11 raw string literals as input. See :ref:`eval`. + `#766 <https://github.com/pybind/pybind11/pull/766>`_, + `#827 <https://github.com/pybind/pybind11/pull/827>`_. + +* ``py::vectorize()`` ignores non-vectorizable arguments and supports + member functions. + `#762 <https://github.com/pybind/pybind11/pull/762>`_. + +* Support for bound methods as callbacks (``pybind11/functional.h``). + `#815 <https://github.com/pybind/pybind11/pull/815>`_. + +* Allow aliasing pybind11 methods: ``cls.attr("foo") = cls.attr("bar")``. + `#802 <https://github.com/pybind/pybind11/pull/802>`_. + +* Don't allow mixed static/non-static overloads. + `#804 <https://github.com/pybind/pybind11/pull/804>`_. + +* Fixed overriding static properties in derived classes. + `#784 <https://github.com/pybind/pybind11/pull/784>`_. + +* Added support for write only properties. + `#1144 <https://github.com/pybind/pybind11/pull/1144>`_. + +* Improved deduction of member functions of a derived class when its bases + aren't registered with pybind11. + `#855 <https://github.com/pybind/pybind11/pull/855>`_. + + .. code-block:: cpp + + struct Base { + int foo() { return 42; } + } + + struct Derived : Base {} + + // Now works, but previously required also binding `Base` + py::class_<Derived>(m, "Derived") + .def("foo", &Derived::foo); // function is actually from `Base` + +* The implementation of ``py::init<>`` now uses C++11 brace initialization + syntax to construct instances, which permits binding implicit constructors of + aggregate types. `#1015 <https://github.com/pybind/pybind11/pull/1015>`_. + + .. code-block:: cpp + + struct Aggregate { + int a; + std::string b; + }; + + py::class_<Aggregate>(m, "Aggregate") + .def(py::init<int, const std::string &>()); + +* Fixed issues with multiple inheritance with offset base/derived pointers. + `#812 <https://github.com/pybind/pybind11/pull/812>`_, + `#866 <https://github.com/pybind/pybind11/pull/866>`_, + `#960 <https://github.com/pybind/pybind11/pull/960>`_. + +* Fixed reference leak of type objects. + `#1030 <https://github.com/pybind/pybind11/pull/1030>`_. + +* Improved support for the ``/std:c++14`` and ``/std:c++latest`` modes + on MSVC 2017. + `#841 <https://github.com/pybind/pybind11/pull/841>`_, + `#999 <https://github.com/pybind/pybind11/pull/999>`_. + +* Fixed detection of private operator new on MSVC. + `#893 <https://github.com/pybind/pybind11/pull/893>`_, + `#918 <https://github.com/pybind/pybind11/pull/918>`_. + +* Intel C++ compiler compatibility fixes. + `#937 <https://github.com/pybind/pybind11/pull/937>`_. + +* Fixed implicit conversion of `py::enum_` to integer types on Python 2.7. + `#821 <https://github.com/pybind/pybind11/pull/821>`_. + +* Added ``py::hash`` to fetch the hash value of Python objects, and + ``.def(hash(py::self))`` to provide the C++ ``std::hash`` as the Python + ``__hash__`` method. + `#1034 <https://github.com/pybind/pybind11/pull/1034>`_. + +* Fixed ``__truediv__`` on Python 2 and ``__itruediv__`` on Python 3. + `#867 <https://github.com/pybind/pybind11/pull/867>`_. + +* ``py::capsule`` objects now support the ``name`` attribute. This is useful + for interfacing with ``scipy.LowLevelCallable``. + `#902 <https://github.com/pybind/pybind11/pull/902>`_. + +* Fixed ``py::make_iterator``'s ``__next__()`` for past-the-end calls. + `#897 <https://github.com/pybind/pybind11/pull/897>`_. + +* Added ``error_already_set::matches()`` for checking Python exceptions. + `#772 <https://github.com/pybind/pybind11/pull/772>`_. + +* Deprecated ``py::error_already_set::clear()``. It's no longer needed + following a simplification of the ``py::error_already_set`` class. + `#954 <https://github.com/pybind/pybind11/pull/954>`_. + +* Deprecated ``py::handle::operator==()`` in favor of ``py::handle::is()`` + `#825 <https://github.com/pybind/pybind11/pull/825>`_. + +* Deprecated ``py::object::borrowed``/``py::object::stolen``. + Use ``py::object::borrowed_t{}``/``py::object::stolen_t{}`` instead. + `#771 <https://github.com/pybind/pybind11/pull/771>`_. + +* Changed internal data structure versioning to avoid conflicts between + modules compiled with different revisions of pybind11. + `#1012 <https://github.com/pybind/pybind11/pull/1012>`_. + +* Additional compile-time and run-time error checking and more informative messages. + `#786 <https://github.com/pybind/pybind11/pull/786>`_, + `#794 <https://github.com/pybind/pybind11/pull/794>`_, + `#803 <https://github.com/pybind/pybind11/pull/803>`_. + +* Various minor improvements and fixes. + `#764 <https://github.com/pybind/pybind11/pull/764>`_, + `#791 <https://github.com/pybind/pybind11/pull/791>`_, + `#795 <https://github.com/pybind/pybind11/pull/795>`_, + `#840 <https://github.com/pybind/pybind11/pull/840>`_, + `#844 <https://github.com/pybind/pybind11/pull/844>`_, + `#846 <https://github.com/pybind/pybind11/pull/846>`_, + `#849 <https://github.com/pybind/pybind11/pull/849>`_, + `#858 <https://github.com/pybind/pybind11/pull/858>`_, + `#862 <https://github.com/pybind/pybind11/pull/862>`_, + `#871 <https://github.com/pybind/pybind11/pull/871>`_, + `#872 <https://github.com/pybind/pybind11/pull/872>`_, + `#881 <https://github.com/pybind/pybind11/pull/881>`_, + `#888 <https://github.com/pybind/pybind11/pull/888>`_, + `#899 <https://github.com/pybind/pybind11/pull/899>`_, + `#928 <https://github.com/pybind/pybind11/pull/928>`_, + `#931 <https://github.com/pybind/pybind11/pull/931>`_, + `#944 <https://github.com/pybind/pybind11/pull/944>`_, + `#950 <https://github.com/pybind/pybind11/pull/950>`_, + `#952 <https://github.com/pybind/pybind11/pull/952>`_, + `#962 <https://github.com/pybind/pybind11/pull/962>`_, + `#965 <https://github.com/pybind/pybind11/pull/965>`_, + `#970 <https://github.com/pybind/pybind11/pull/970>`_, + `#978 <https://github.com/pybind/pybind11/pull/978>`_, + `#979 <https://github.com/pybind/pybind11/pull/979>`_, + `#986 <https://github.com/pybind/pybind11/pull/986>`_, + `#1020 <https://github.com/pybind/pybind11/pull/1020>`_, + `#1027 <https://github.com/pybind/pybind11/pull/1027>`_, + `#1037 <https://github.com/pybind/pybind11/pull/1037>`_. + +* Testing improvements. + `#798 <https://github.com/pybind/pybind11/pull/798>`_, + `#882 <https://github.com/pybind/pybind11/pull/882>`_, + `#898 <https://github.com/pybind/pybind11/pull/898>`_, + `#900 <https://github.com/pybind/pybind11/pull/900>`_, + `#921 <https://github.com/pybind/pybind11/pull/921>`_, + `#923 <https://github.com/pybind/pybind11/pull/923>`_, + `#963 <https://github.com/pybind/pybind11/pull/963>`_. + +v2.1.1 (April 7, 2017) +----------------------------------------------------- + +* Fixed minimum version requirement for MSVC 2015u3 + `#773 <https://github.com/pybind/pybind11/pull/773>`_. + +v2.1.0 (March 22, 2017) +----------------------------------------------------- + +* pybind11 now performs function overload resolution in two phases. The first + phase only considers exact type matches, while the second allows for implicit + conversions to take place. A special ``noconvert()`` syntax can be used to + completely disable implicit conversions for specific arguments. + `#643 <https://github.com/pybind/pybind11/pull/643>`_, + `#634 <https://github.com/pybind/pybind11/pull/634>`_, + `#650 <https://github.com/pybind/pybind11/pull/650>`_. + +* Fixed a regression where static properties no longer worked with classes + using multiple inheritance. The ``py::metaclass`` attribute is no longer + necessary (and deprecated as of this release) when binding classes with + static properties. + `#679 <https://github.com/pybind/pybind11/pull/679>`_, + +* Classes bound using ``pybind11`` can now use custom metaclasses. + `#679 <https://github.com/pybind/pybind11/pull/679>`_, + +* ``py::args`` and ``py::kwargs`` can now be mixed with other positional + arguments when binding functions using pybind11. + `#611 <https://github.com/pybind/pybind11/pull/611>`_. + +* Improved support for C++11 unicode string and character types; added + extensive documentation regarding pybind11's string conversion behavior. + `#624 <https://github.com/pybind/pybind11/pull/624>`_, + `#636 <https://github.com/pybind/pybind11/pull/636>`_, + `#715 <https://github.com/pybind/pybind11/pull/715>`_. + +* pybind11 can now avoid expensive copies when converting Eigen arrays to NumPy + arrays (and vice versa). `#610 <https://github.com/pybind/pybind11/pull/610>`_. + +* The "fast path" in ``py::vectorize`` now works for any full-size group of C or + F-contiguous arrays. The non-fast path is also faster since it no longer performs + copies of the input arguments (except when type conversions are necessary). + `#610 <https://github.com/pybind/pybind11/pull/610>`_. + +* Added fast, unchecked access to NumPy arrays via a proxy object. + `#746 <https://github.com/pybind/pybind11/pull/746>`_. + +* Transparent support for class-specific ``operator new`` and + ``operator delete`` implementations. + `#755 <https://github.com/pybind/pybind11/pull/755>`_. + +* Slimmer and more efficient STL-compatible iterator interface for sequence types. + `#662 <https://github.com/pybind/pybind11/pull/662>`_. + +* Improved custom holder type support. + `#607 <https://github.com/pybind/pybind11/pull/607>`_. + +* ``nullptr`` to ``None`` conversion fixed in various builtin type casters. + `#732 <https://github.com/pybind/pybind11/pull/732>`_. + +* ``enum_`` now exposes its members via a special ``__members__`` attribute. + `#666 <https://github.com/pybind/pybind11/pull/666>`_. + +* ``std::vector`` bindings created using ``stl_bind.h`` can now optionally + implement the buffer protocol. `#488 <https://github.com/pybind/pybind11/pull/488>`_. + +* Automated C++ reference documentation using doxygen and breathe. + `#598 <https://github.com/pybind/pybind11/pull/598>`_. + +* Added minimum compiler version assertions. + `#727 <https://github.com/pybind/pybind11/pull/727>`_. + +* Improved compatibility with C++1z. + `#677 <https://github.com/pybind/pybind11/pull/677>`_. + +* Improved ``py::capsule`` API. Can be used to implement cleanup + callbacks that are involved at module destruction time. + `#752 <https://github.com/pybind/pybind11/pull/752>`_. + +* Various minor improvements and fixes. + `#595 <https://github.com/pybind/pybind11/pull/595>`_, + `#588 <https://github.com/pybind/pybind11/pull/588>`_, + `#589 <https://github.com/pybind/pybind11/pull/589>`_, + `#603 <https://github.com/pybind/pybind11/pull/603>`_, + `#619 <https://github.com/pybind/pybind11/pull/619>`_, + `#648 <https://github.com/pybind/pybind11/pull/648>`_, + `#695 <https://github.com/pybind/pybind11/pull/695>`_, + `#720 <https://github.com/pybind/pybind11/pull/720>`_, + `#723 <https://github.com/pybind/pybind11/pull/723>`_, + `#729 <https://github.com/pybind/pybind11/pull/729>`_, + `#724 <https://github.com/pybind/pybind11/pull/724>`_, + `#742 <https://github.com/pybind/pybind11/pull/742>`_, + `#753 <https://github.com/pybind/pybind11/pull/753>`_. + +v2.0.1 (Jan 4, 2017) +----------------------------------------------------- + +* Fix pointer to reference error in type_caster on MSVC + `#583 <https://github.com/pybind/pybind11/pull/583>`_. + +* Fixed a segmentation in the test suite due to a typo + `cd7eac <https://github.com/pybind/pybind11/commit/cd7eac>`_. + +v2.0.0 (Jan 1, 2017) +----------------------------------------------------- + +* Fixed a reference counting regression affecting types with custom metaclasses + (introduced in v2.0.0-rc1). + `#571 <https://github.com/pybind/pybind11/pull/571>`_. + +* Quenched a CMake policy warning. + `#570 <https://github.com/pybind/pybind11/pull/570>`_. + +v2.0.0-rc1 (Dec 23, 2016) +----------------------------------------------------- + +The pybind11 developers are excited to issue a release candidate of pybind11 +with a subsequent v2.0.0 release planned in early January next year. + +An incredible amount of effort by went into pybind11 over the last ~5 months, +leading to a release that is jam-packed with exciting new features and numerous +usability improvements. The following list links PRs or individual commits +whenever applicable. + +Happy Christmas! + +* Support for binding C++ class hierarchies that make use of multiple + inheritance. `#410 <https://github.com/pybind/pybind11/pull/410>`_. + +* PyPy support: pybind11 now supports nightly builds of PyPy and will + interoperate with the future 5.7 release. No code changes are necessary, + everything "just" works as usual. Note that we only target the Python 2.7 + branch for now; support for 3.x will be added once its ``cpyext`` extension + support catches up. A few minor features remain unsupported for the time + being (notably dynamic attributes in custom types). + `#527 <https://github.com/pybind/pybind11/pull/527>`_. + +* Significant work on the documentation -- in particular, the monolithic + ``advanced.rst`` file was restructured into a easier to read hierarchical + organization. `#448 <https://github.com/pybind/pybind11/pull/448>`_. + +* Many NumPy-related improvements: + + 1. Object-oriented API to access and modify NumPy ``ndarray`` instances, + replicating much of the corresponding NumPy C API functionality. + `#402 <https://github.com/pybind/pybind11/pull/402>`_. + + 2. NumPy array ``dtype`` array descriptors are now first-class citizens and + are exposed via a new class ``py::dtype``. + + 3. Structured dtypes can be registered using the ``PYBIND11_NUMPY_DTYPE()`` + macro. Special ``array`` constructors accepting dtype objects were also + added. + + One potential caveat involving this change: format descriptor strings + should now be accessed via ``format_descriptor::format()`` (however, for + compatibility purposes, the old syntax ``format_descriptor::value`` will + still work for non-structured data types). `#308 + <https://github.com/pybind/pybind11/pull/308>`_. + + 4. Further improvements to support structured dtypes throughout the system. + `#472 <https://github.com/pybind/pybind11/pull/472>`_, + `#474 <https://github.com/pybind/pybind11/pull/474>`_, + `#459 <https://github.com/pybind/pybind11/pull/459>`_, + `#453 <https://github.com/pybind/pybind11/pull/453>`_, + `#452 <https://github.com/pybind/pybind11/pull/452>`_, and + `#505 <https://github.com/pybind/pybind11/pull/505>`_. + + 5. Fast access operators. `#497 <https://github.com/pybind/pybind11/pull/497>`_. + + 6. Constructors for arrays whose storage is owned by another object. + `#440 <https://github.com/pybind/pybind11/pull/440>`_. + + 7. Added constructors for ``array`` and ``array_t`` explicitly accepting shape + and strides; if strides are not provided, they are deduced assuming + C-contiguity. Also added simplified constructors for 1-dimensional case. + + 8. Added buffer/NumPy support for ``char[N]`` and ``std::array<char, N>`` types. + + 9. Added ``memoryview`` wrapper type which is constructible from ``buffer_info``. + +* Eigen: many additional conversions and support for non-contiguous + arrays/slices. + `#427 <https://github.com/pybind/pybind11/pull/427>`_, + `#315 <https://github.com/pybind/pybind11/pull/315>`_, + `#316 <https://github.com/pybind/pybind11/pull/316>`_, + `#312 <https://github.com/pybind/pybind11/pull/312>`_, and + `#267 <https://github.com/pybind/pybind11/pull/267>`_ + +* Incompatible changes in ``class_<...>::class_()``: + + 1. Declarations of types that provide access via the buffer protocol must + now include the ``py::buffer_protocol()`` annotation as an argument to + the ``class_`` constructor. + + 2. Declarations of types that require a custom metaclass (i.e. all classes + which include static properties via commands such as + ``def_readwrite_static()``) must now include the ``py::metaclass()`` + annotation as an argument to the ``class_`` constructor. + + These two changes were necessary to make type definitions in pybind11 + future-proof, and to support PyPy via its cpyext mechanism. `#527 + <https://github.com/pybind/pybind11/pull/527>`_. + + + 3. This version of pybind11 uses a redesigned mechanism for instantiating + trampoline classes that are used to override virtual methods from within + Python. This led to the following user-visible syntax change: instead of + + .. code-block:: cpp + + py::class_<TrampolineClass>("MyClass") + .alias<MyClass>() + .... + + write + + .. code-block:: cpp + + py::class_<MyClass, TrampolineClass>("MyClass") + .... + + Importantly, both the original and the trampoline class are now + specified as an arguments (in arbitrary order) to the ``py::class_`` + template, and the ``alias<..>()`` call is gone. The new scheme has zero + overhead in cases when Python doesn't override any functions of the + underlying C++ class. `rev. 86d825 + <https://github.com/pybind/pybind11/commit/86d825>`_. + +* Added ``eval`` and ``eval_file`` functions for evaluating expressions and + statements from a string or file. `rev. 0d3fc3 + <https://github.com/pybind/pybind11/commit/0d3fc3>`_. + +* pybind11 can now create types with a modifiable dictionary. + `#437 <https://github.com/pybind/pybind11/pull/437>`_ and + `#444 <https://github.com/pybind/pybind11/pull/444>`_. + +* Support for translation of arbitrary C++ exceptions to Python counterparts. + `#296 <https://github.com/pybind/pybind11/pull/296>`_ and + `#273 <https://github.com/pybind/pybind11/pull/273>`_. + +* Report full backtraces through mixed C++/Python code, better reporting for + import errors, fixed GIL management in exception processing. + `#537 <https://github.com/pybind/pybind11/pull/537>`_, + `#494 <https://github.com/pybind/pybind11/pull/494>`_, + `rev. e72d95 <https://github.com/pybind/pybind11/commit/e72d95>`_, and + `rev. 099d6e <https://github.com/pybind/pybind11/commit/099d6e>`_. + +* Support for bit-level operations, comparisons, and serialization of C++ + enumerations. `#503 <https://github.com/pybind/pybind11/pull/503>`_, + `#508 <https://github.com/pybind/pybind11/pull/508>`_, + `#380 <https://github.com/pybind/pybind11/pull/380>`_, + `#309 <https://github.com/pybind/pybind11/pull/309>`_. + `#311 <https://github.com/pybind/pybind11/pull/311>`_. + +* The ``class_`` constructor now accepts its template arguments in any order. + `#385 <https://github.com/pybind/pybind11/pull/385>`_. + +* Attribute and item accessors now have a more complete interface which makes + it possible to chain attributes as in + ``obj.attr("a")[key].attr("b").attr("method")(1, 2, 3)``. `#425 + <https://github.com/pybind/pybind11/pull/425>`_. + +* Major redesign of the default and conversion constructors in ``pytypes.h``. + `#464 <https://github.com/pybind/pybind11/pull/464>`_. + +* Added built-in support for ``std::shared_ptr`` holder type. It is no longer + necessary to to include a declaration of the form + ``PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>)`` (though continuing to + do so won't cause an error). + `#454 <https://github.com/pybind/pybind11/pull/454>`_. + +* New ``py::overload_cast`` casting operator to select among multiple possible + overloads of a function. An example: + + .. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age") + .def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name"); + + This feature only works on C++14-capable compilers. + `#541 <https://github.com/pybind/pybind11/pull/541>`_. + +* C++ types are automatically cast to Python types, e.g. when assigning + them as an attribute. For instance, the following is now legal: + + .. code-block:: cpp + + py::module m = /* ... */ + m.attr("constant") = 123; + + (Previously, a ``py::cast`` call was necessary to avoid a compilation error.) + `#551 <https://github.com/pybind/pybind11/pull/551>`_. + +* Redesigned ``pytest``-based test suite. `#321 <https://github.com/pybind/pybind11/pull/321>`_. + +* Instance tracking to detect reference leaks in test suite. `#324 <https://github.com/pybind/pybind11/pull/324>`_ + +* pybind11 can now distinguish between multiple different instances that are + located at the same memory address, but which have different types. + `#329 <https://github.com/pybind/pybind11/pull/329>`_. + +* Improved logic in ``move`` return value policy. + `#510 <https://github.com/pybind/pybind11/pull/510>`_, + `#297 <https://github.com/pybind/pybind11/pull/297>`_. + +* Generalized unpacking API to permit calling Python functions from C++ using + notation such as ``foo(a1, a2, *args, "ka"_a=1, "kb"_a=2, **kwargs)``. `#372 <https://github.com/pybind/pybind11/pull/372>`_. + +* ``py::print()`` function whose behavior matches that of the native Python + ``print()`` function. `#372 <https://github.com/pybind/pybind11/pull/372>`_. + +* Added ``py::dict`` keyword constructor:``auto d = dict("number"_a=42, + "name"_a="World");``. `#372 <https://github.com/pybind/pybind11/pull/372>`_. + +* Added ``py::str::format()`` method and ``_s`` literal: ``py::str s = "1 + 2 + = {}"_s.format(3);``. `#372 <https://github.com/pybind/pybind11/pull/372>`_. + +* Added ``py::repr()`` function which is equivalent to Python's builtin + ``repr()``. `#333 <https://github.com/pybind/pybind11/pull/333>`_. + +* Improved construction and destruction logic for holder types. It is now + possible to reference instances with smart pointer holder types without + constructing the holder if desired. The ``PYBIND11_DECLARE_HOLDER_TYPE`` + macro now accepts an optional second parameter to indicate whether the holder + type uses intrusive reference counting. + `#533 <https://github.com/pybind/pybind11/pull/533>`_ and + `#561 <https://github.com/pybind/pybind11/pull/561>`_. + +* Mapping a stateless C++ function to Python and back is now "for free" (i.e. + no extra indirections or argument conversion overheads). `rev. 954b79 + <https://github.com/pybind/pybind11/commit/954b79>`_. + +* Bindings for ``std::valarray<T>``. + `#545 <https://github.com/pybind/pybind11/pull/545>`_. + +* Improved support for C++17 capable compilers. + `#562 <https://github.com/pybind/pybind11/pull/562>`_. + +* Bindings for ``std::optional<t>``. + `#475 <https://github.com/pybind/pybind11/pull/475>`_, + `#476 <https://github.com/pybind/pybind11/pull/476>`_, + `#479 <https://github.com/pybind/pybind11/pull/479>`_, + `#499 <https://github.com/pybind/pybind11/pull/499>`_, and + `#501 <https://github.com/pybind/pybind11/pull/501>`_. + +* ``stl_bind.h``: general improvements and support for ``std::map`` and + ``std::unordered_map``. + `#490 <https://github.com/pybind/pybind11/pull/490>`_, + `#282 <https://github.com/pybind/pybind11/pull/282>`_, + `#235 <https://github.com/pybind/pybind11/pull/235>`_. + +* The ``std::tuple``, ``std::pair``, ``std::list``, and ``std::vector`` type + casters now accept any Python sequence type as input. `rev. 107285 + <https://github.com/pybind/pybind11/commit/107285>`_. + +* Improved CMake Python detection on multi-architecture Linux. + `#532 <https://github.com/pybind/pybind11/pull/532>`_. + +* Infrastructure to selectively disable or enable parts of the automatically + generated docstrings. `#486 <https://github.com/pybind/pybind11/pull/486>`_. + +* ``reference`` and ``reference_internal`` are now the default return value + properties for static and non-static properties, respectively. `#473 + <https://github.com/pybind/pybind11/pull/473>`_. (the previous defaults + were ``automatic``). `#473 <https://github.com/pybind/pybind11/pull/473>`_. + +* Support for ``std::unique_ptr`` with non-default deleters or no deleter at + all (``py::nodelete``). `#384 <https://github.com/pybind/pybind11/pull/384>`_. + +* Deprecated ``handle::call()`` method. The new syntax to call Python + functions is simply ``handle()``. It can also be invoked explicitly via + ``handle::operator<X>()``, where ``X`` is an optional return value policy. + +* Print more informative error messages when ``make_tuple()`` or ``cast()`` + fail. `#262 <https://github.com/pybind/pybind11/pull/262>`_. + +* Creation of holder types for classes deriving from + ``std::enable_shared_from_this<>`` now also works for ``const`` values. + `#260 <https://github.com/pybind/pybind11/pull/260>`_. + +* ``make_iterator()`` improvements for better compatibility with various + types (now uses prefix increment operator); it now also accepts iterators + with different begin/end types as long as they are equality comparable. + `#247 <https://github.com/pybind/pybind11/pull/247>`_. + +* ``arg()`` now accepts a wider range of argument types for default values. + `#244 <https://github.com/pybind/pybind11/pull/244>`_. + +* Support ``keep_alive`` where the nurse object may be ``None``. `#341 + <https://github.com/pybind/pybind11/pull/341>`_. + +* Added constructors for ``str`` and ``bytes`` from zero-terminated char + pointers, and from char pointers and length. Added constructors for ``str`` + from ``bytes`` and for ``bytes`` from ``str``, which will perform UTF-8 + decoding/encoding as required. + +* Many other improvements of library internals without user-visible changes + + +1.8.1 (July 12, 2016) +---------------------- +* Fixed a rare but potentially very severe issue when the garbage collector ran + during pybind11 type creation. + +1.8.0 (June 14, 2016) +---------------------- +* Redesigned CMake build system which exports a convenient + ``pybind11_add_module`` function to parent projects. +* ``std::vector<>`` type bindings analogous to Boost.Python's ``indexing_suite`` +* Transparent conversion of sparse and dense Eigen matrices and vectors (``eigen.h``) +* Added an ``ExtraFlags`` template argument to the NumPy ``array_t<>`` wrapper + to disable an enforced cast that may lose precision, e.g. to create overloads + for different precisions and complex vs real-valued matrices. +* Prevent implicit conversion of floating point values to integral types in + function arguments +* Fixed incorrect default return value policy for functions returning a shared + pointer +* Don't allow registering a type via ``class_`` twice +* Don't allow casting a ``None`` value into a C++ lvalue reference +* Fixed a crash in ``enum_::operator==`` that was triggered by the ``help()`` command +* Improved detection of whether or not custom C++ types can be copy/move-constructed +* Extended ``str`` type to also work with ``bytes`` instances +* Added a ``"name"_a`` user defined string literal that is equivalent to ``py::arg("name")``. +* When specifying function arguments via ``py::arg``, the test that verifies + the number of arguments now runs at compile time. +* Added ``[[noreturn]]`` attribute to ``pybind11_fail()`` to quench some + compiler warnings +* List function arguments in exception text when the dispatch code cannot find + a matching overload +* Added ``PYBIND11_OVERLOAD_NAME`` and ``PYBIND11_OVERLOAD_PURE_NAME`` macros which + can be used to override virtual methods whose name differs in C++ and Python + (e.g. ``__call__`` and ``operator()``) +* Various minor ``iterator`` and ``make_iterator()`` improvements +* Transparently support ``__bool__`` on Python 2.x and Python 3.x +* Fixed issue with destructor of unpickled object not being called +* Minor CMake build system improvements on Windows +* New ``pybind11::args`` and ``pybind11::kwargs`` types to create functions which + take an arbitrary number of arguments and keyword arguments +* New syntax to call a Python function from C++ using ``*args`` and ``*kwargs`` +* The functions ``def_property_*`` now correctly process docstring arguments (these + formerly caused a segmentation fault) +* Many ``mkdoc.py`` improvements (enumerations, template arguments, ``DOC()`` + macro accepts more arguments) +* Cygwin support +* Documentation improvements (pickling support, ``keep_alive``, macro usage) + +1.7 (April 30, 2016) +---------------------- +* Added a new ``move`` return value policy that triggers C++11 move semantics. + The automatic return value policy falls back to this case whenever a rvalue + reference is encountered +* Significantly more general GIL state routines that are used instead of + Python's troublesome ``PyGILState_Ensure`` and ``PyGILState_Release`` API +* Redesign of opaque types that drastically simplifies their usage +* Extended ability to pass values of type ``[const] void *`` +* ``keep_alive`` fix: don't fail when there is no patient +* ``functional.h``: acquire the GIL before calling a Python function +* Added Python RAII type wrappers ``none`` and ``iterable`` +* Added ``*args`` and ``*kwargs`` pass-through parameters to + ``pybind11.get_include()`` function +* Iterator improvements and fixes +* Documentation on return value policies and opaque types improved + +1.6 (April 30, 2016) +---------------------- +* Skipped due to upload to PyPI gone wrong and inability to recover + (https://github.com/pypa/packaging-problems/issues/74) + +1.5 (April 21, 2016) +---------------------- +* For polymorphic types, use RTTI to try to return the closest type registered with pybind11 +* Pickling support for serializing and unserializing C++ instances to a byte stream in Python +* Added a convenience routine ``make_iterator()`` which turns a range indicated + by a pair of C++ iterators into a iterable Python object +* Added ``len()`` and a variadic ``make_tuple()`` function +* Addressed a rare issue that could confuse the current virtual function + dispatcher and another that could lead to crashes in multi-threaded + applications +* Added a ``get_include()`` function to the Python module that returns the path + of the directory containing the installed pybind11 header files +* Documentation improvements: import issues, symbol visibility, pickling, limitations +* Added casting support for ``std::reference_wrapper<>`` + +1.4 (April 7, 2016) +-------------------------- +* Transparent type conversion for ``std::wstring`` and ``wchar_t`` +* Allow passing ``nullptr``-valued strings +* Transparent passing of ``void *`` pointers using capsules +* Transparent support for returning values wrapped in ``std::unique_ptr<>`` +* Improved docstring generation for compatibility with Sphinx +* Nicer debug error message when default parameter construction fails +* Support for "opaque" types that bypass the transparent conversion layer for STL containers +* Redesigned type casting interface to avoid ambiguities that could occasionally cause compiler errors +* Redesigned property implementation; fixes crashes due to an unfortunate default return value policy +* Anaconda package generation support + +1.3 (March 8, 2016) +-------------------------- + +* Added support for the Intel C++ compiler (v15+) +* Added support for the STL unordered set/map data structures +* Added support for the STL linked list data structure +* NumPy-style broadcasting support in ``pybind11::vectorize`` +* pybind11 now displays more verbose error messages when ``arg::operator=()`` fails +* pybind11 internal data structures now live in a version-dependent namespace to avoid ABI issues +* Many, many bugfixes involving corner cases and advanced usage + +1.2 (February 7, 2016) +-------------------------- + +* Optional: efficient generation of function signatures at compile time using C++14 +* Switched to a simpler and more general way of dealing with function default + arguments. Unused keyword arguments in function calls are now detected and + cause errors as expected +* New ``keep_alive`` call policy analogous to Boost.Python's ``with_custodian_and_ward`` +* New ``pybind11::base<>`` attribute to indicate a subclass relationship +* Improved interface for RAII type wrappers in ``pytypes.h`` +* Use RAII type wrappers consistently within pybind11 itself. This + fixes various potential refcount leaks when exceptions occur +* Added new ``bytes`` RAII type wrapper (maps to ``string`` in Python 2.7) +* Made handle and related RAII classes const correct, using them more + consistently everywhere now +* Got rid of the ugly ``__pybind11__`` attributes on the Python side---they are + now stored in a C++ hash table that is not visible in Python +* Fixed refcount leaks involving NumPy arrays and bound functions +* Vastly improved handling of shared/smart pointers +* Removed an unnecessary copy operation in ``pybind11::vectorize`` +* Fixed naming clashes when both pybind11 and NumPy headers are included +* Added conversions for additional exception types +* Documentation improvements (using multiple extension modules, smart pointers, + other minor clarifications) +* unified infrastructure for parsing variadic arguments in ``class_`` and cpp_function +* Fixed license text (was: ZLIB, should have been: 3-clause BSD) +* Python 3.2 compatibility +* Fixed remaining issues when accessing types in another plugin module +* Added enum comparison and casting methods +* Improved SFINAE-based detection of whether types are copy-constructible +* Eliminated many warnings about unused variables and the use of ``offsetof()`` +* Support for ``std::array<>`` conversions + +1.1 (December 7, 2015) +-------------------------- + +* Documentation improvements (GIL, wrapping functions, casting, fixed many typos) +* Generalized conversion of integer types +* Improved support for casting function objects +* Improved support for ``std::shared_ptr<>`` conversions +* Initial support for ``std::set<>`` conversions +* Fixed type resolution issue for types defined in a separate plugin module +* Cmake build system improvements +* Factored out generic functionality to non-templated code (smaller code size) +* Added a code size / compile time benchmark vs Boost.Python +* Added an appveyor CI script + +1.0 (October 15, 2015) +------------------------ +* Initial release diff --git a/3rdparty/pybind11/docs/classes.rst b/3rdparty/pybind11/docs/classes.rst new file mode 100644 index 00000000..a63f6a19 --- /dev/null +++ b/3rdparty/pybind11/docs/classes.rst @@ -0,0 +1,532 @@ +.. _classes: + +Object-oriented code +#################### + +Creating bindings for a custom type +=================================== + +Let's now look at a more complex example where we'll create bindings for a +custom C++ data structure named ``Pet``. Its definition is given below: + +.. code-block:: cpp + + struct Pet { + Pet(const std::string &name) : name(name) { } + void setName(const std::string &name_) { name = name_; } + const std::string &getName() const { return name; } + + std::string name; + }; + +The binding code for ``Pet`` looks as follows: + +.. code-block:: cpp + + #include <pybind11/pybind11.h> + + namespace py = pybind11; + + PYBIND11_MODULE(example, m) { + py::class_<Pet>(m, "Pet") + .def(py::init<const std::string &>()) + .def("setName", &Pet::setName) + .def("getName", &Pet::getName); + } + +:class:`class_` creates bindings for a C++ *class* or *struct*-style data +structure. :func:`init` is a convenience function that takes the types of a +constructor's parameters as template arguments and wraps the corresponding +constructor (see the :ref:`custom_constructors` section for details). An +interactive Python session demonstrating this example is shown below: + +.. code-block:: pycon + + % python + >>> import example + >>> p = example.Pet('Molly') + >>> print(p) + <example.Pet object at 0x10cd98060> + >>> p.getName() + u'Molly' + >>> p.setName('Charly') + >>> p.getName() + u'Charly' + +.. seealso:: + + Static member functions can be bound in the same way using + :func:`class_::def_static`. + +Keyword and default arguments +============================= +It is possible to specify keyword and default arguments using the syntax +discussed in the previous chapter. Refer to the sections :ref:`keyword_args` +and :ref:`default_args` for details. + +Binding lambda functions +======================== + +Note how ``print(p)`` produced a rather useless summary of our data structure in the example above: + +.. code-block:: pycon + + >>> print(p) + <example.Pet object at 0x10cd98060> + +To address this, we could bind an utility function that returns a human-readable +summary to the special method slot named ``__repr__``. Unfortunately, there is no +suitable functionality in the ``Pet`` data structure, and it would be nice if +we did not have to change it. This can easily be accomplished by binding a +Lambda function instead: + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def(py::init<const std::string &>()) + .def("setName", &Pet::setName) + .def("getName", &Pet::getName) + .def("__repr__", + [](const Pet &a) { + return "<example.Pet named '" + a.name + "'>"; + } + ); + +Both stateless [#f1]_ and stateful lambda closures are supported by pybind11. +With the above change, the same Python code now produces the following output: + +.. code-block:: pycon + + >>> print(p) + <example.Pet named 'Molly'> + +.. [#f1] Stateless closures are those with an empty pair of brackets ``[]`` as the capture object. + +.. _properties: + +Instance and static fields +========================== + +We can also directly expose the ``name`` field using the +:func:`class_::def_readwrite` method. A similar :func:`class_::def_readonly` +method also exists for ``const`` fields. + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def(py::init<const std::string &>()) + .def_readwrite("name", &Pet::name) + // ... remainder ... + +This makes it possible to write + +.. code-block:: pycon + + >>> p = example.Pet('Molly') + >>> p.name + u'Molly' + >>> p.name = 'Charly' + >>> p.name + u'Charly' + +Now suppose that ``Pet::name`` was a private internal variable +that can only be accessed via setters and getters. + +.. code-block:: cpp + + class Pet { + public: + Pet(const std::string &name) : name(name) { } + void setName(const std::string &name_) { name = name_; } + const std::string &getName() const { return name; } + private: + std::string name; + }; + +In this case, the method :func:`class_::def_property` +(:func:`class_::def_property_readonly` for read-only data) can be used to +provide a field-like interface within Python that will transparently call +the setter and getter functions: + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def(py::init<const std::string &>()) + .def_property("name", &Pet::getName, &Pet::setName) + // ... remainder ... + +Write only properties can be defined by passing ``nullptr`` as the +input for the read function. + +.. seealso:: + + Similar functions :func:`class_::def_readwrite_static`, + :func:`class_::def_readonly_static` :func:`class_::def_property_static`, + and :func:`class_::def_property_readonly_static` are provided for binding + static variables and properties. Please also see the section on + :ref:`static_properties` in the advanced part of the documentation. + +Dynamic attributes +================== + +Native Python classes can pick up new attributes dynamically: + +.. code-block:: pycon + + >>> class Pet: + ... name = 'Molly' + ... + >>> p = Pet() + >>> p.name = 'Charly' # overwrite existing + >>> p.age = 2 # dynamically add a new attribute + +By default, classes exported from C++ do not support this and the only writable +attributes are the ones explicitly defined using :func:`class_::def_readwrite` +or :func:`class_::def_property`. + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def(py::init<>()) + .def_readwrite("name", &Pet::name); + +Trying to set any other attribute results in an error: + +.. code-block:: pycon + + >>> p = example.Pet() + >>> p.name = 'Charly' # OK, attribute defined in C++ + >>> p.age = 2 # fail + AttributeError: 'Pet' object has no attribute 'age' + +To enable dynamic attributes for C++ classes, the :class:`py::dynamic_attr` tag +must be added to the :class:`py::class_` constructor: + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet", py::dynamic_attr()) + .def(py::init<>()) + .def_readwrite("name", &Pet::name); + +Now everything works as expected: + +.. code-block:: pycon + + >>> p = example.Pet() + >>> p.name = 'Charly' # OK, overwrite value in C++ + >>> p.age = 2 # OK, dynamically add a new attribute + >>> p.__dict__ # just like a native Python class + {'age': 2} + +Note that there is a small runtime cost for a class with dynamic attributes. +Not only because of the addition of a ``__dict__``, but also because of more +expensive garbage collection tracking which must be activated to resolve +possible circular references. Native Python classes incur this same cost by +default, so this is not anything to worry about. By default, pybind11 classes +are more efficient than native Python classes. Enabling dynamic attributes +just brings them on par. + +.. _inheritance: + +Inheritance and automatic downcasting +===================================== + +Suppose now that the example consists of two data structures with an +inheritance relationship: + +.. code-block:: cpp + + struct Pet { + Pet(const std::string &name) : name(name) { } + std::string name; + }; + + struct Dog : Pet { + Dog(const std::string &name) : Pet(name) { } + std::string bark() const { return "woof!"; } + }; + +There are two different ways of indicating a hierarchical relationship to +pybind11: the first specifies the C++ base class as an extra template +parameter of the :class:`class_`: + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def(py::init<const std::string &>()) + .def_readwrite("name", &Pet::name); + + // Method 1: template parameter: + py::class_<Dog, Pet /* <- specify C++ parent type */>(m, "Dog") + .def(py::init<const std::string &>()) + .def("bark", &Dog::bark); + +Alternatively, we can also assign a name to the previously bound ``Pet`` +:class:`class_` object and reference it when binding the ``Dog`` class: + +.. code-block:: cpp + + py::class_<Pet> pet(m, "Pet"); + pet.def(py::init<const std::string &>()) + .def_readwrite("name", &Pet::name); + + // Method 2: pass parent class_ object: + py::class_<Dog>(m, "Dog", pet /* <- specify Python parent type */) + .def(py::init<const std::string &>()) + .def("bark", &Dog::bark); + +Functionality-wise, both approaches are equivalent. Afterwards, instances will +expose fields and methods of both types: + +.. code-block:: pycon + + >>> p = example.Dog('Molly') + >>> p.name + u'Molly' + >>> p.bark() + u'woof!' + +The C++ classes defined above are regular non-polymorphic types with an +inheritance relationship. This is reflected in Python: + +.. code-block:: cpp + + // Return a base pointer to a derived instance + m.def("pet_store", []() { return std::unique_ptr<Pet>(new Dog("Molly")); }); + +.. code-block:: pycon + + >>> p = example.pet_store() + >>> type(p) # `Dog` instance behind `Pet` pointer + Pet # no pointer downcasting for regular non-polymorphic types + >>> p.bark() + AttributeError: 'Pet' object has no attribute 'bark' + +The function returned a ``Dog`` instance, but because it's a non-polymorphic +type behind a base pointer, Python only sees a ``Pet``. In C++, a type is only +considered polymorphic if it has at least one virtual function and pybind11 +will automatically recognize this: + +.. code-block:: cpp + + struct PolymorphicPet { + virtual ~PolymorphicPet() = default; + }; + + struct PolymorphicDog : PolymorphicPet { + std::string bark() const { return "woof!"; } + }; + + // Same binding code + py::class_<PolymorphicPet>(m, "PolymorphicPet"); + py::class_<PolymorphicDog, PolymorphicPet>(m, "PolymorphicDog") + .def(py::init<>()) + .def("bark", &PolymorphicDog::bark); + + // Again, return a base pointer to a derived instance + m.def("pet_store2", []() { return std::unique_ptr<PolymorphicPet>(new PolymorphicDog); }); + +.. code-block:: pycon + + >>> p = example.pet_store2() + >>> type(p) + PolymorphicDog # automatically downcast + >>> p.bark() + u'woof!' + +Given a pointer to a polymorphic base, pybind11 performs automatic downcasting +to the actual derived type. Note that this goes beyond the usual situation in +C++: we don't just get access to the virtual functions of the base, we get the +concrete derived type including functions and attributes that the base type may +not even be aware of. + +.. seealso:: + + For more information about polymorphic behavior see :ref:`overriding_virtuals`. + + +Overloaded methods +================== + +Sometimes there are several overloaded C++ methods with the same name taking +different kinds of input arguments: + +.. code-block:: cpp + + struct Pet { + Pet(const std::string &name, int age) : name(name), age(age) { } + + void set(int age_) { age = age_; } + void set(const std::string &name_) { name = name_; } + + std::string name; + int age; + }; + +Attempting to bind ``Pet::set`` will cause an error since the compiler does not +know which method the user intended to select. We can disambiguate by casting +them to function pointers. Binding multiple functions to the same Python name +automatically creates a chain of function overloads that will be tried in +sequence. + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def(py::init<const std::string &, int>()) + .def("set", (void (Pet::*)(int)) &Pet::set, "Set the pet's age") + .def("set", (void (Pet::*)(const std::string &)) &Pet::set, "Set the pet's name"); + +The overload signatures are also visible in the method's docstring: + +.. code-block:: pycon + + >>> help(example.Pet) + + class Pet(__builtin__.object) + | Methods defined here: + | + | __init__(...) + | Signature : (Pet, str, int) -> NoneType + | + | set(...) + | 1. Signature : (Pet, int) -> NoneType + | + | Set the pet's age + | + | 2. Signature : (Pet, str) -> NoneType + | + | Set the pet's name + +If you have a C++14 compatible compiler [#cpp14]_, you can use an alternative +syntax to cast the overloaded function: + +.. code-block:: cpp + + py::class_<Pet>(m, "Pet") + .def("set", py::overload_cast<int>(&Pet::set), "Set the pet's age") + .def("set", py::overload_cast<const std::string &>(&Pet::set), "Set the pet's name"); + +Here, ``py::overload_cast`` only requires the parameter types to be specified. +The return type and class are deduced. This avoids the additional noise of +``void (Pet::*)()`` as seen in the raw cast. If a function is overloaded based +on constness, the ``py::const_`` tag should be used: + +.. code-block:: cpp + + struct Widget { + int foo(int x, float y); + int foo(int x, float y) const; + }; + + py::class_<Widget>(m, "Widget") + .def("foo_mutable", py::overload_cast<int, float>(&Widget::foo)) + .def("foo_const", py::overload_cast<int, float>(&Widget::foo, py::const_)); + +If you prefer the ``py::overload_cast`` syntax but have a C++11 compatible compiler only, +you can use ``py::detail::overload_cast_impl`` with an additional set of parentheses: + +.. code-block:: cpp + + template <typename... Args> + using overload_cast_ = pybind11::detail::overload_cast_impl<Args...>; + + py::class_<Pet>(m, "Pet") + .def("set", overload_cast_<int>()(&Pet::set), "Set the pet's age") + .def("set", overload_cast_<const std::string &>()(&Pet::set), "Set the pet's name"); + +.. [#cpp14] A compiler which supports the ``-std=c++14`` flag + or Visual Studio 2015 Update 2 and newer. + +.. note:: + + To define multiple overloaded constructors, simply declare one after the + other using the ``.def(py::init<...>())`` syntax. The existing machinery + for specifying keyword and default arguments also works. + +Enumerations and internal types +=============================== + +Let's now suppose that the example class contains an internal enumeration type, +e.g.: + +.. code-block:: cpp + + struct Pet { + enum Kind { + Dog = 0, + Cat + }; + + Pet(const std::string &name, Kind type) : name(name), type(type) { } + + std::string name; + Kind type; + }; + +The binding code for this example looks as follows: + +.. code-block:: cpp + + py::class_<Pet> pet(m, "Pet"); + + pet.def(py::init<const std::string &, Pet::Kind>()) + .def_readwrite("name", &Pet::name) + .def_readwrite("type", &Pet::type); + + py::enum_<Pet::Kind>(pet, "Kind") + .value("Dog", Pet::Kind::Dog) + .value("Cat", Pet::Kind::Cat) + .export_values(); + +To ensure that the ``Kind`` type is created within the scope of ``Pet``, the +``pet`` :class:`class_` instance must be supplied to the :class:`enum_`. +constructor. The :func:`enum_::export_values` function exports the enum entries +into the parent scope, which should be skipped for newer C++11-style strongly +typed enums. + +.. code-block:: pycon + + >>> p = Pet('Lucy', Pet.Cat) + >>> p.type + Kind.Cat + >>> int(p.type) + 1L + +The entries defined by the enumeration type are exposed in the ``__members__`` property: + +.. code-block:: pycon + + >>> Pet.Kind.__members__ + {'Dog': Kind.Dog, 'Cat': Kind.Cat} + +The ``name`` property returns the name of the enum value as a unicode string. + +.. note:: + + It is also possible to use ``str(enum)``, however these accomplish different + goals. The following shows how these two approaches differ. + + .. code-block:: pycon + + >>> p = Pet( "Lucy", Pet.Cat ) + >>> pet_type = p.type + >>> pet_type + Pet.Cat + >>> str(pet_type) + 'Pet.Cat' + >>> pet_type.name + 'Cat' + +.. note:: + + When the special tag ``py::arithmetic()`` is specified to the ``enum_`` + constructor, pybind11 creates an enumeration that also supports rudimentary + arithmetic and bit-level operations like comparisons, and, or, xor, negation, + etc. + + .. code-block:: cpp + + py::enum_<Pet::Kind>(pet, "Kind", py::arithmetic()) + ... + + By default, these are omitted to conserve space. diff --git a/3rdparty/pybind11/docs/compiling.rst b/3rdparty/pybind11/docs/compiling.rst new file mode 100644 index 00000000..c50c7d8a --- /dev/null +++ b/3rdparty/pybind11/docs/compiling.rst @@ -0,0 +1,289 @@ +.. _compiling: + +Build systems +############# + +Building with setuptools +======================== + +For projects on PyPI, building with setuptools is the way to go. Sylvain Corlay +has kindly provided an example project which shows how to set up everything, +including automatic generation of documentation using Sphinx. Please refer to +the [python_example]_ repository. + +.. [python_example] https://github.com/pybind/python_example + +Building with cppimport +======================== + +[cppimport]_ is a small Python import hook that determines whether there is a C++ +source file whose name matches the requested module. If there is, the file is +compiled as a Python extension using pybind11 and placed in the same folder as +the C++ source file. Python is then able to find the module and load it. + +.. [cppimport] https://github.com/tbenthompson/cppimport + +.. _cmake: + +Building with CMake +=================== + +For C++ codebases that have an existing CMake-based build system, a Python +extension module can be created with just a few lines of code: + +.. code-block:: cmake + + cmake_minimum_required(VERSION 2.8.12) + project(example) + + add_subdirectory(pybind11) + pybind11_add_module(example example.cpp) + +This assumes that the pybind11 repository is located in a subdirectory named +:file:`pybind11` and that the code is located in a file named :file:`example.cpp`. +The CMake command ``add_subdirectory`` will import the pybind11 project which +provides the ``pybind11_add_module`` function. It will take care of all the +details needed to build a Python extension module on any platform. + +A working sample project, including a way to invoke CMake from :file:`setup.py` for +PyPI integration, can be found in the [cmake_example]_ repository. + +.. [cmake_example] https://github.com/pybind/cmake_example + +pybind11_add_module +------------------- + +To ease the creation of Python extension modules, pybind11 provides a CMake +function with the following signature: + +.. code-block:: cmake + + pybind11_add_module(<name> [MODULE | SHARED] [EXCLUDE_FROM_ALL] + [NO_EXTRAS] [SYSTEM] [THIN_LTO] source1 [source2 ...]) + +This function behaves very much like CMake's builtin ``add_library`` (in fact, +it's a wrapper function around that command). It will add a library target +called ``<name>`` to be built from the listed source files. In addition, it +will take care of all the Python-specific compiler and linker flags as well +as the OS- and Python-version-specific file extension. The produced target +``<name>`` can be further manipulated with regular CMake commands. + +``MODULE`` or ``SHARED`` may be given to specify the type of library. If no +type is given, ``MODULE`` is used by default which ensures the creation of a +Python-exclusive module. Specifying ``SHARED`` will create a more traditional +dynamic library which can also be linked from elsewhere. ``EXCLUDE_FROM_ALL`` +removes this target from the default build (see CMake docs for details). + +Since pybind11 is a template library, ``pybind11_add_module`` adds compiler +flags to ensure high quality code generation without bloat arising from long +symbol names and duplication of code in different translation units. It +sets default visibility to *hidden*, which is required for some pybind11 +features and functionality when attempting to load multiple pybind11 modules +compiled under different pybind11 versions. It also adds additional flags +enabling LTO (Link Time Optimization) and strip unneeded symbols. See the +:ref:`FAQ entry <faq:symhidden>` for a more detailed explanation. These +latter optimizations are never applied in ``Debug`` mode. If ``NO_EXTRAS`` is +given, they will always be disabled, even in ``Release`` mode. However, this +will result in code bloat and is generally not recommended. + +By default, pybind11 and Python headers will be included with ``-I``. In order +to include pybind11 as system library, e.g. to avoid warnings in downstream +code with warn-levels outside of pybind11's scope, set the option ``SYSTEM``. + +As stated above, LTO is enabled by default. Some newer compilers also support +different flavors of LTO such as `ThinLTO`_. Setting ``THIN_LTO`` will cause +the function to prefer this flavor if available. The function falls back to +regular LTO if ``-flto=thin`` is not available. + +.. _ThinLTO: http://clang.llvm.org/docs/ThinLTO.html + +Configuration variables +----------------------- + +By default, pybind11 will compile modules with the C++14 standard, if available +on the target compiler, falling back to C++11 if C++14 support is not +available. Note, however, that this default is subject to change: future +pybind11 releases are expected to migrate to newer C++ standards as they become +available. To override this, the standard flag can be given explicitly in +``PYBIND11_CPP_STANDARD``: + +.. code-block:: cmake + + # Use just one of these: + # GCC/clang: + set(PYBIND11_CPP_STANDARD -std=c++11) + set(PYBIND11_CPP_STANDARD -std=c++14) + set(PYBIND11_CPP_STANDARD -std=c++1z) # Experimental C++17 support + # MSVC: + set(PYBIND11_CPP_STANDARD /std:c++14) + set(PYBIND11_CPP_STANDARD /std:c++latest) # Enables some MSVC C++17 features + + add_subdirectory(pybind11) # or find_package(pybind11) + +Note that this and all other configuration variables must be set **before** the +call to ``add_subdirectory`` or ``find_package``. The variables can also be set +when calling CMake from the command line using the ``-D<variable>=<value>`` flag. + +The target Python version can be selected by setting ``PYBIND11_PYTHON_VERSION`` +or an exact Python installation can be specified with ``PYTHON_EXECUTABLE``. +For example: + +.. code-block:: bash + + cmake -DPYBIND11_PYTHON_VERSION=3.6 .. + # or + cmake -DPYTHON_EXECUTABLE=path/to/python .. + +find_package vs. add_subdirectory +--------------------------------- + +For CMake-based projects that don't include the pybind11 repository internally, +an external installation can be detected through ``find_package(pybind11)``. +See the `Config file`_ docstring for details of relevant CMake variables. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 2.8.12) + project(example) + + find_package(pybind11 REQUIRED) + pybind11_add_module(example example.cpp) + +Note that ``find_package(pybind11)`` will only work correctly if pybind11 +has been correctly installed on the system, e. g. after downloading or cloning +the pybind11 repository : + +.. code-block:: bash + + cd pybind11 + mkdir build + cd build + cmake .. + make install + +Once detected, the aforementioned ``pybind11_add_module`` can be employed as +before. The function usage and configuration variables are identical no matter +if pybind11 is added as a subdirectory or found as an installed package. You +can refer to the same [cmake_example]_ repository for a full sample project +-- just swap out ``add_subdirectory`` for ``find_package``. + +.. _Config file: https://github.com/pybind/pybind11/blob/master/tools/pybind11Config.cmake.in + +Advanced: interface library target +---------------------------------- + +When using a version of CMake greater than 3.0, pybind11 can additionally +be used as a special *interface library* . The target ``pybind11::module`` +is available with pybind11 headers, Python headers and libraries as needed, +and C++ compile definitions attached. This target is suitable for linking +to an independently constructed (through ``add_library``, not +``pybind11_add_module``) target in the consuming project. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(example) + + find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) + + add_library(example MODULE main.cpp) + target_link_libraries(example PRIVATE pybind11::module) + set_target_properties(example PROPERTIES PREFIX "${PYTHON_MODULE_PREFIX}" + SUFFIX "${PYTHON_MODULE_EXTENSION}") + +.. warning:: + + Since pybind11 is a metatemplate library, it is crucial that certain + compiler flags are provided to ensure high quality code generation. In + contrast to the ``pybind11_add_module()`` command, the CMake interface + library only provides the *minimal* set of parameters to ensure that the + code using pybind11 compiles, but it does **not** pass these extra compiler + flags (i.e. this is up to you). + + These include Link Time Optimization (``-flto`` on GCC/Clang/ICPC, ``/GL`` + and ``/LTCG`` on Visual Studio) and .OBJ files with many sections on Visual + Studio (``/bigobj``). The :ref:`FAQ <faq:symhidden>` contains an + explanation on why these are needed. + +Embedding the Python interpreter +-------------------------------- + +In addition to extension modules, pybind11 also supports embedding Python into +a C++ executable or library. In CMake, simply link with the ``pybind11::embed`` +target. It provides everything needed to get the interpreter running. The Python +headers and libraries are attached to the target. Unlike ``pybind11::module``, +there is no need to manually set any additional properties here. For more +information about usage in C++, see :doc:`/advanced/embedding`. + +.. code-block:: cmake + + cmake_minimum_required(VERSION 3.0) + project(example) + + find_package(pybind11 REQUIRED) # or add_subdirectory(pybind11) + + add_executable(example main.cpp) + target_link_libraries(example PRIVATE pybind11::embed) + +.. _building_manually: + +Building manually +================= + +pybind11 is a header-only library, hence it is not necessary to link against +any special libraries and there are no intermediate (magic) translation steps. + +On Linux, you can compile an example such as the one given in +:ref:`simple_example` using the following command: + +.. code-block:: bash + + $ c++ -O3 -Wall -shared -std=c++11 -fPIC `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` + +The flags given here assume that you're using Python 3. For Python 2, just +change the executable appropriately (to ``python`` or ``python2``). + +The ``python3 -m pybind11 --includes`` command fetches the include paths for +both pybind11 and Python headers. This assumes that pybind11 has been installed +using ``pip`` or ``conda``. If it hasn't, you can also manually specify +``-I <path-to-pybind11>/include`` together with the Python includes path +``python3-config --includes``. + +Note that Python 2.7 modules don't use a special suffix, so you should simply +use ``example.so`` instead of ``example`python3-config --extension-suffix```. +Besides, the ``--extension-suffix`` option may or may not be available, depending +on the distribution; in the latter case, the module extension can be manually +set to ``.so``. + +On Mac OS: the build command is almost the same but it also requires passing +the ``-undefined dynamic_lookup`` flag so as to ignore missing symbols when +building the module: + +.. code-block:: bash + + $ c++ -O3 -Wall -shared -std=c++11 -undefined dynamic_lookup `python3 -m pybind11 --includes` example.cpp -o example`python3-config --extension-suffix` + +In general, it is advisable to include several additional build parameters +that can considerably reduce the size of the created binary. Refer to section +:ref:`cmake` for a detailed example of a suitable cross-platform CMake-based +build system that works on all platforms including Windows. + +.. note:: + + On Linux and macOS, it's better to (intentionally) not link against + ``libpython``. The symbols will be resolved when the extension library + is loaded into a Python binary. This is preferable because you might + have several different installations of a given Python version (e.g. the + system-provided Python, and one that ships with a piece of commercial + software). In this way, the plugin will work with both versions, instead + of possibly importing a second Python library into a process that already + contains one (which will lead to a segfault). + +Generating binding code automatically +===================================== + +The ``Binder`` project is a tool for automatic generation of pybind11 binding +code by introspecting existing C++ codebases using LLVM/Clang. See the +[binder]_ documentation for details. + +.. [binder] http://cppbinder.readthedocs.io/en/latest/about.html diff --git a/3rdparty/pybind11/docs/conf.py b/3rdparty/pybind11/docs/conf.py new file mode 100644 index 00000000..fa6332de --- /dev/null +++ b/3rdparty/pybind11/docs/conf.py @@ -0,0 +1,332 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# pybind11 documentation build configuration file, created by +# sphinx-quickstart on Sun Oct 11 19:23:48 2015. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys +import os +import shlex +import subprocess + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['breathe'] + +breathe_projects = {'pybind11': '.build/doxygenxml/'} +breathe_default_project = 'pybind11' +breathe_domain_by_extension = {'h': 'cpp'} + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['.templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'pybind11' +copyright = '2017, Wenzel Jakob' +author = 'Wenzel Jakob' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '2.5' +# The full version, including alpha/beta/rc tags. +release = '2.5.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['.build', 'release.rst'] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +default_role = 'any' + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +#pygments_style = 'monokai' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +#keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = False + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. + +on_rtd = os.environ.get('READTHEDOCS', None) == 'True' + +if not on_rtd: # only import and set the theme if we're building docs locally + import sphinx_rtd_theme + html_theme = 'sphinx_rtd_theme' + html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + + html_context = { + 'css_files': [ + '_static/theme_overrides.css' + ] + } +else: + html_context = { + 'css_files': [ + '//media.readthedocs.org/css/sphinx_rtd_theme.css', + '//media.readthedocs.org/css/readthedocs-doc-embed.css', + '_static/theme_overrides.css' + ] + } + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +#html_extra_path = [] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr' +#html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# Now only 'ja' uses this config value +#html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +#html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'pybind11doc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +'preamble': '\DeclareUnicodeCharacter{00A0}{}', + +# Latex figure (float) alignment +#'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'pybind11.tex', 'pybind11 Documentation', + 'Wenzel Jakob', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# latex_logo = 'pybind11-logo.png' + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'pybind11', 'pybind11 Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'pybind11', 'pybind11 Documentation', + author, 'pybind11', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +#texinfo_no_detailmenu = False + +primary_domain = 'cpp' +highlight_language = 'cpp' + + +def generate_doxygen_xml(app): + build_dir = os.path.join(app.confdir, '.build') + if not os.path.exists(build_dir): + os.mkdir(build_dir) + + try: + subprocess.call(['doxygen', '--version']) + retcode = subprocess.call(['doxygen'], cwd=app.confdir) + if retcode < 0: + sys.stderr.write("doxygen error code: {}\n".format(-retcode)) + except OSError as e: + sys.stderr.write("doxygen execution failed: {}\n".format(e)) + + +def setup(app): + """Add hook for building doxygen xml when needed""" + app.connect("builder-inited", generate_doxygen_xml) diff --git a/3rdparty/pybind11/docs/faq.rst b/3rdparty/pybind11/docs/faq.rst new file mode 100644 index 00000000..4d491fb8 --- /dev/null +++ b/3rdparty/pybind11/docs/faq.rst @@ -0,0 +1,324 @@ +Frequently asked questions +########################## + +"ImportError: dynamic module does not define init function" +=========================================================== + +1. Make sure that the name specified in PYBIND11_MODULE is identical to the +filename of the extension library (without prefixes such as .so) + +2. If the above did not fix the issue, you are likely using an incompatible +version of Python (for instance, the extension library was compiled against +Python 2, while the interpreter is running on top of some version of Python +3, or vice versa). + +"Symbol not found: ``__Py_ZeroStruct`` / ``_PyInstanceMethod_Type``" +======================================================================== + +See the first answer. + +"SystemError: dynamic module not initialized properly" +====================================================== + +See the first answer. + +The Python interpreter immediately crashes when importing my module +=================================================================== + +See the first answer. + +CMake doesn't detect the right Python version +============================================= + +The CMake-based build system will try to automatically detect the installed +version of Python and link against that. When this fails, or when there are +multiple versions of Python and it finds the wrong one, delete +``CMakeCache.txt`` and then invoke CMake as follows: + +.. code-block:: bash + + cmake -DPYTHON_EXECUTABLE:FILEPATH=<path-to-python-executable> . + +.. _faq_reference_arguments: + +Limitations involving reference arguments +========================================= + +In C++, it's fairly common to pass arguments using mutable references or +mutable pointers, which allows both read and write access to the value +supplied by the caller. This is sometimes done for efficiency reasons, or to +realize functions that have multiple return values. Here are two very basic +examples: + +.. code-block:: cpp + + void increment(int &i) { i++; } + void increment_ptr(int *i) { (*i)++; } + +In Python, all arguments are passed by reference, so there is no general +issue in binding such code from Python. + +However, certain basic Python types (like ``str``, ``int``, ``bool``, +``float``, etc.) are **immutable**. This means that the following attempt +to port the function to Python doesn't have the same effect on the value +provided by the caller -- in fact, it does nothing at all. + +.. code-block:: python + + def increment(i): + i += 1 # nope.. + +pybind11 is also affected by such language-level conventions, which means that +binding ``increment`` or ``increment_ptr`` will also create Python functions +that don't modify their arguments. + +Although inconvenient, one workaround is to encapsulate the immutable types in +a custom type that does allow modifications. + +An other alternative involves binding a small wrapper lambda function that +returns a tuple with all output arguments (see the remainder of the +documentation for examples on binding lambda functions). An example: + +.. code-block:: cpp + + int foo(int &i) { i++; return 123; } + +and the binding code + +.. code-block:: cpp + + m.def("foo", [](int i) { int rv = foo(i); return std::make_tuple(rv, i); }); + + +How can I reduce the build time? +================================ + +It's good practice to split binding code over multiple files, as in the +following example: + +:file:`example.cpp`: + +.. code-block:: cpp + + void init_ex1(py::module &); + void init_ex2(py::module &); + /* ... */ + + PYBIND11_MODULE(example, m) { + init_ex1(m); + init_ex2(m); + /* ... */ + } + +:file:`ex1.cpp`: + +.. code-block:: cpp + + void init_ex1(py::module &m) { + m.def("add", [](int a, int b) { return a + b; }); + } + +:file:`ex2.cpp`: + +.. code-block:: cpp + + void init_ex2(py::module &m) { + m.def("sub", [](int a, int b) { return a - b; }); + } + +:command:`python`: + +.. code-block:: pycon + + >>> import example + >>> example.add(1, 2) + 3 + >>> example.sub(1, 1) + 0 + +As shown above, the various ``init_ex`` functions should be contained in +separate files that can be compiled independently from one another, and then +linked together into the same final shared object. Following this approach +will: + +1. reduce memory requirements per compilation unit. + +2. enable parallel builds (if desired). + +3. allow for faster incremental builds. For instance, when a single class + definition is changed, only a subset of the binding code will generally need + to be recompiled. + +"recursive template instantiation exceeded maximum depth of 256" +================================================================ + +If you receive an error about excessive recursive template evaluation, try +specifying a larger value, e.g. ``-ftemplate-depth=1024`` on GCC/Clang. The +culprit is generally the generation of function signatures at compile time +using C++14 template metaprogramming. + +.. _`faq:hidden_visibility`: + +"‘SomeClass’ declared with greater visibility than the type of its field ‘SomeClass::member’ [-Wattributes]" +============================================================================================================ + +This error typically indicates that you are compiling without the required +``-fvisibility`` flag. pybind11 code internally forces hidden visibility on +all internal code, but if non-hidden (and thus *exported*) code attempts to +include a pybind type (for example, ``py::object`` or ``py::list``) you can run +into this warning. + +To avoid it, make sure you are specifying ``-fvisibility=hidden`` when +compiling pybind code. + +As to why ``-fvisibility=hidden`` is necessary, because pybind modules could +have been compiled under different versions of pybind itself, it is also +important that the symbols defined in one module do not clash with the +potentially-incompatible symbols defined in another. While Python extension +modules are usually loaded with localized symbols (under POSIX systems +typically using ``dlopen`` with the ``RTLD_LOCAL`` flag), this Python default +can be changed, but even if it isn't it is not always enough to guarantee +complete independence of the symbols involved when not using +``-fvisibility=hidden``. + +Additionally, ``-fvisiblity=hidden`` can deliver considerably binary size +savings. (See the following section for more details). + + +.. _`faq:symhidden`: + +How can I create smaller binaries? +================================== + +To do its job, pybind11 extensively relies on a programming technique known as +*template metaprogramming*, which is a way of performing computation at compile +time using type information. Template metaprogamming usually instantiates code +involving significant numbers of deeply nested types that are either completely +removed or reduced to just a few instructions during the compiler's optimization +phase. However, due to the nested nature of these types, the resulting symbol +names in the compiled extension library can be extremely long. For instance, +the included test suite contains the following symbol: + +.. only:: html + + .. code-block:: none + + __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_ + +.. only:: not html + + .. code-block:: cpp + + __ZN8pybind1112cpp_functionC1Iv8Example2JRNSt3__16vectorINS3_12basic_stringIwNS3_11char_traitsIwEENS3_9allocatorIwEEEENS8_ISA_EEEEEJNS_4nameENS_7siblingENS_9is_methodEA28_cEEEMT0_FT_DpT1_EDpRKT2_ + +which is the mangled form of the following function type: + +.. code-block:: cpp + + pybind11::cpp_function::cpp_function<void, Example2, std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&, pybind11::name, pybind11::sibling, pybind11::is_method, char [28]>(void (Example2::*)(std::__1::vector<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> >, std::__1::allocator<std::__1::basic_string<wchar_t, std::__1::char_traits<wchar_t>, std::__1::allocator<wchar_t> > > >&), pybind11::name const&, pybind11::sibling const&, pybind11::is_method const&, char const (&) [28]) + +The memory needed to store just the mangled name of this function (196 bytes) +is larger than the actual piece of code (111 bytes) it represents! On the other +hand, it's silly to even give this function a name -- after all, it's just a +tiny cog in a bigger piece of machinery that is not exposed to the outside +world. So we'll generally only want to export symbols for those functions which +are actually called from the outside. + +This can be achieved by specifying the parameter ``-fvisibility=hidden`` to GCC +and Clang, which sets the default symbol visibility to *hidden*, which has a +tremendous impact on the final binary size of the resulting extension library. +(On Visual Studio, symbols are already hidden by default, so nothing needs to +be done there.) + +In addition to decreasing binary size, ``-fvisibility=hidden`` also avoids +potential serious issues when loading multiple modules and is required for +proper pybind operation. See the previous FAQ entry for more details. + +Working with ancient Visual Studio 2008 builds on Windows +========================================================= + +The official Windows distributions of Python are compiled using truly +ancient versions of Visual Studio that lack good C++11 support. Some users +implicitly assume that it would be impossible to load a plugin built with +Visual Studio 2015 into a Python distribution that was compiled using Visual +Studio 2008. However, no such issue exists: it's perfectly legitimate to +interface DLLs that are built with different compilers and/or C libraries. +Common gotchas to watch out for involve not ``free()``-ing memory region +that that were ``malloc()``-ed in another shared library, using data +structures with incompatible ABIs, and so on. pybind11 is very careful not +to make these types of mistakes. + +How can I properly handle Ctrl-C in long-running functions? +=========================================================== + +Ctrl-C is received by the Python interpreter, and holds it until the GIL +is released, so a long-running function won't be interrupted. + +To interrupt from inside your function, you can use the ``PyErr_CheckSignals()`` +function, that will tell if a signal has been raised on the Python side. This +function merely checks a flag, so its impact is negligible. When a signal has +been received, you must either explicitly interrupt execution by throwing +``py::error_already_set`` (which will propagate the existing +``KeyboardInterrupt``), or clear the error (which you usually will not want): + +.. code-block:: cpp + + PYBIND11_MODULE(example, m) + { + m.def("long running_func", []() + { + for (;;) { + if (PyErr_CheckSignals() != 0) + throw py::error_already_set(); + // Long running iteration + } + }); + } + +Inconsistent detection of Python version in CMake and pybind11 +============================================================== + +The functions ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` provided by CMake +for Python version detection are not used by pybind11 due to unreliability and limitations that make +them unsuitable for pybind11's needs. Instead pybind provides its own, more reliable Python detection +CMake code. Conflicts can arise, however, when using pybind11 in a project that *also* uses the CMake +Python detection in a system with several Python versions installed. + +This difference may cause inconsistencies and errors if *both* mechanisms are used in the same project. Consider the following +Cmake code executed in a system with Python 2.7 and 3.x installed: + +.. code-block:: cmake + + find_package(PythonInterp) + find_package(PythonLibs) + find_package(pybind11) + +It will detect Python 2.7 and pybind11 will pick it as well. + +In contrast this code: + +.. code-block:: cmake + + find_package(pybind11) + find_package(PythonInterp) + find_package(PythonLibs) + +will detect Python 3.x for pybind11 and may crash on ``find_package(PythonLibs)`` afterwards. + +It is advised to avoid using ``find_package(PythonInterp)`` and ``find_package(PythonLibs)`` from CMake and rely +on pybind11 in detecting Python version. If this is not possible CMake machinery should be called *before* including pybind11. + +How to cite this project? +========================= + +We suggest the following BibTeX template to cite pybind11 in scientific +discourse: + +.. code-block:: bash + + @misc{pybind11, + author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan}, + year = {2017}, + note = {https://github.com/pybind/pybind11}, + title = {pybind11 -- Seamless operability between C++11 and Python} + } diff --git a/3rdparty/pybind11/docs/index.rst b/3rdparty/pybind11/docs/index.rst new file mode 100644 index 00000000..d236611b --- /dev/null +++ b/3rdparty/pybind11/docs/index.rst @@ -0,0 +1,47 @@ +.. only: not latex + + .. image:: pybind11-logo.png + +pybind11 --- Seamless operability between C++11 and Python +========================================================== + +.. only: not latex + + Contents: + +.. toctree:: + :maxdepth: 1 + + intro + changelog + upgrade + +.. toctree:: + :caption: The Basics + :maxdepth: 2 + + basics + classes + compiling + +.. toctree:: + :caption: Advanced Topics + :maxdepth: 2 + + advanced/functions + advanced/classes + advanced/exceptions + advanced/smart_ptrs + advanced/cast/index + advanced/pycpp/index + advanced/embedding + advanced/misc + +.. toctree:: + :caption: Extra Information + :maxdepth: 1 + + faq + benchmark + limitations + reference diff --git a/3rdparty/pybind11/docs/intro.rst b/3rdparty/pybind11/docs/intro.rst new file mode 100644 index 00000000..10e1799a --- /dev/null +++ b/3rdparty/pybind11/docs/intro.rst @@ -0,0 +1,93 @@ +.. image:: pybind11-logo.png + +About this project +================== +**pybind11** is a lightweight header-only library that exposes C++ types in Python +and vice versa, mainly to create Python bindings of existing C++ code. Its +goals and syntax are similar to the excellent `Boost.Python`_ library by David +Abrahams: to minimize boilerplate code in traditional extension modules by +inferring type information using compile-time introspection. + +.. _Boost.Python: http://www.boost.org/doc/libs/release/libs/python/doc/index.html + +The main issue with Boost.Python—and the reason for creating such a similar +project—is Boost. Boost is an enormously large and complex suite of utility +libraries that works with almost every C++ compiler in existence. This +compatibility has its cost: arcane template tricks and workarounds are +necessary to support the oldest and buggiest of compiler specimens. Now that +C++11-compatible compilers are widely available, this heavy machinery has +become an excessively large and unnecessary dependency. +Think of this library as a tiny self-contained version of Boost.Python with +everything stripped away that isn't relevant for binding generation. Without +comments, the core header files only require ~4K lines of code and depend on +Python (2.7 or 3.x, or PyPy2.7 >= 5.7) and the C++ standard library. This +compact implementation was possible thanks to some of the new C++11 language +features (specifically: tuples, lambda functions and variadic templates). Since +its creation, this library has grown beyond Boost.Python in many ways, leading +to dramatically simpler binding code in many common situations. + +Core features +************* +The following core C++ features can be mapped to Python + +- Functions accepting and returning custom data structures per value, reference, or pointer +- Instance methods and static methods +- Overloaded functions +- Instance attributes and static attributes +- Arbitrary exception types +- Enumerations +- Callbacks +- Iterators and ranges +- Custom operators +- Single and multiple inheritance +- STL data structures +- Smart pointers with reference counting like ``std::shared_ptr`` +- Internal references with correct reference counting +- C++ classes with virtual (and pure virtual) methods can be extended in Python + +Goodies +******* +In addition to the core functionality, pybind11 provides some extra goodies: + +- Python 2.7, 3.x, and PyPy (PyPy2.7 >= 5.7) are supported with an + implementation-agnostic interface. + +- It is possible to bind C++11 lambda functions with captured variables. The + lambda capture data is stored inside the resulting Python function object. + +- pybind11 uses C++11 move constructors and move assignment operators whenever + possible to efficiently transfer custom data types. + +- It's easy to expose the internal storage of custom data types through + Pythons' buffer protocols. This is handy e.g. for fast conversion between + C++ matrix classes like Eigen and NumPy without expensive copy operations. + +- pybind11 can automatically vectorize functions so that they are transparently + applied to all entries of one or more NumPy array arguments. + +- Python's slice-based access and assignment operations can be supported with + just a few lines of code. + +- Everything is contained in just a few header files; there is no need to link + against any additional libraries. + +- Binaries are generally smaller by a factor of at least 2 compared to + equivalent bindings generated by Boost.Python. A recent pybind11 conversion + of `PyRosetta`_, an enormous Boost.Python binding project, reported a binary + size reduction of **5.4x** and compile time reduction by **5.8x**. + +- Function signatures are precomputed at compile time (using ``constexpr``), + leading to smaller binaries. + +- With little extra effort, C++ types can be pickled and unpickled similar to + regular Python objects. + +.. _PyRosetta: http://graylab.jhu.edu/RosettaCon2016/PyRosetta-4.pdf + +Supported compilers +******************* + +1. Clang/LLVM (any non-ancient version with C++11 support) +2. GCC 4.8 or newer +3. Microsoft Visual Studio 2015 or newer +4. Intel C++ compiler v17 or newer (v16 with pybind11 v2.0 and v15 with pybind11 v2.0 and a `workaround <https://github.com/pybind/pybind11/issues/276>`_ ) diff --git a/3rdparty/pybind11/docs/limitations.rst b/3rdparty/pybind11/docs/limitations.rst new file mode 100644 index 00000000..a1a4f1af --- /dev/null +++ b/3rdparty/pybind11/docs/limitations.rst @@ -0,0 +1,20 @@ +Limitations +########### + +pybind11 strives to be a general solution to binding generation, but it also has +certain limitations: + +- pybind11 casts away ``const``-ness in function arguments and return values. + This is in line with the Python language, which has no concept of ``const`` + values. This means that some additional care is needed to avoid bugs that + would be caught by the type checker in a traditional C++ program. + +- The NumPy interface ``pybind11::array`` greatly simplifies accessing + numerical data from C++ (and vice versa), but it's not a full-blown array + class like ``Eigen::Array`` or ``boost.multi_array``. + +These features could be implemented but would lead to a significant increase in +complexity. I've decided to draw the line here to keep this project simple and +compact. Users who absolutely require these features are encouraged to fork +pybind11. + diff --git a/3rdparty/pybind11/docs/pybind11-logo.png b/3rdparty/pybind11/docs/pybind11-logo.png Binary files differnew file mode 100644 index 00000000..4cbad54f --- /dev/null +++ b/3rdparty/pybind11/docs/pybind11-logo.png diff --git a/3rdparty/pybind11/docs/pybind11_vs_boost_python1.png b/3rdparty/pybind11/docs/pybind11_vs_boost_python1.png Binary files differnew file mode 100644 index 00000000..833231f2 --- /dev/null +++ b/3rdparty/pybind11/docs/pybind11_vs_boost_python1.png diff --git a/3rdparty/pybind11/docs/pybind11_vs_boost_python1.svg b/3rdparty/pybind11/docs/pybind11_vs_boost_python1.svg new file mode 100644 index 00000000..5bf950e6 --- /dev/null +++ b/3rdparty/pybind11/docs/pybind11_vs_boost_python1.svg @@ -0,0 +1,427 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="468pt" height="252pt" viewBox="0 0 468 252" version="1.1"> +<defs> +<g> +<symbol overflow="visible" id="glyph0-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph0-1"> +<path style="stroke:none;" d="M 3.726562 0 L 2.847656 0 L 2.847656 -5.601562 C 2.636719 -5.398438 2.359375 -5.195312 2.015625 -4.996094 C 1.671875 -4.792969 1.363281 -4.640625 1.089844 -4.539062 L 1.089844 -5.390625 C 1.582031 -5.621094 2.011719 -5.902344 2.378906 -6.230469 C 2.746094 -6.558594 3.007812 -6.878906 3.160156 -7.1875 L 3.726562 -7.1875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-2"> +<path style="stroke:none;" d="M 0.414062 -3.53125 C 0.414062 -4.375 0.503906 -5.058594 0.675781 -5.574219 C 0.851562 -6.089844 1.109375 -6.488281 1.453125 -6.765625 C 1.796875 -7.046875 2.226562 -7.1875 2.75 -7.1875 C 3.132812 -7.1875 3.46875 -7.109375 3.757812 -6.957031 C 4.046875 -6.800781 4.289062 -6.578125 4.476562 -6.285156 C 4.664062 -5.996094 4.8125 -5.640625 4.921875 -5.222656 C 5.03125 -4.804688 5.082031 -4.238281 5.082031 -3.53125 C 5.082031 -2.691406 4.996094 -2.011719 4.824219 -1.496094 C 4.652344 -0.980469 4.394531 -0.582031 4.050781 -0.300781 C 3.707031 -0.0195312 3.273438 0.121094 2.75 0.121094 C 2.058594 0.121094 1.515625 -0.125 1.125 -0.621094 C 0.652344 -1.214844 0.414062 -2.1875 0.414062 -3.53125 Z M 1.320312 -3.53125 C 1.320312 -2.355469 1.457031 -1.574219 1.730469 -1.183594 C 2.007812 -0.796875 2.34375 -0.601562 2.75 -0.601562 C 3.152344 -0.601562 3.492188 -0.796875 3.765625 -1.1875 C 4.042969 -1.578125 4.179688 -2.359375 4.179688 -3.53125 C 4.179688 -4.710938 4.042969 -5.492188 3.765625 -5.878906 C 3.492188 -6.265625 3.148438 -6.460938 2.738281 -6.460938 C 2.335938 -6.460938 2.011719 -6.289062 1.773438 -5.945312 C 1.46875 -5.511719 1.320312 -4.707031 1.320312 -3.53125 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-3"> +<path style="stroke:none;" d="M 5.035156 -0.84375 L 5.035156 0 L 0.304688 0 C 0.296875 -0.210938 0.332031 -0.414062 0.40625 -0.609375 C 0.527344 -0.933594 0.71875 -1.25 0.984375 -1.5625 C 1.25 -1.875 1.632812 -2.234375 2.132812 -2.648438 C 2.910156 -3.285156 3.4375 -3.789062 3.710938 -4.164062 C 3.984375 -4.535156 4.121094 -4.886719 4.121094 -5.21875 C 4.121094 -5.566406 3.996094 -5.863281 3.746094 -6.101562 C 3.5 -6.339844 3.171875 -6.460938 2.773438 -6.460938 C 2.351562 -6.460938 2.011719 -6.332031 1.757812 -6.078125 C 1.503906 -5.824219 1.375 -5.472656 1.371094 -5.023438 L 0.46875 -5.117188 C 0.53125 -5.789062 0.761719 -6.304688 1.167969 -6.65625 C 1.570312 -7.011719 2.113281 -7.1875 2.792969 -7.1875 C 3.480469 -7.1875 4.023438 -6.996094 4.421875 -6.617188 C 4.824219 -6.234375 5.023438 -5.761719 5.023438 -5.199219 C 5.023438 -4.914062 4.964844 -4.632812 4.847656 -4.355469 C 4.730469 -4.078125 4.535156 -3.789062 4.265625 -3.480469 C 3.992188 -3.175781 3.542969 -2.753906 2.910156 -2.222656 C 2.382812 -1.78125 2.042969 -1.480469 1.894531 -1.320312 C 1.746094 -1.164062 1.621094 -1.003906 1.523438 -0.84375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-4"> +<path style="stroke:none;" d="M 0.414062 -1.875 L 1.335938 -1.953125 C 1.40625 -1.503906 1.566406 -1.167969 1.8125 -0.941406 C 2.0625 -0.714844 2.363281 -0.601562 2.714844 -0.601562 C 3.136719 -0.601562 3.496094 -0.761719 3.789062 -1.078125 C 4.082031 -1.398438 4.226562 -1.820312 4.226562 -2.347656 C 4.226562 -2.851562 4.085938 -3.246094 3.804688 -3.535156 C 3.523438 -3.824219 3.15625 -3.96875 2.699219 -3.96875 C 2.417969 -3.96875 2.160156 -3.90625 1.933594 -3.777344 C 1.707031 -3.648438 1.527344 -3.480469 1.398438 -3.277344 L 0.570312 -3.382812 L 1.265625 -7.0625 L 4.824219 -7.0625 L 4.824219 -6.21875 L 1.96875 -6.21875 L 1.582031 -4.296875 C 2.011719 -4.597656 2.460938 -4.746094 2.933594 -4.746094 C 3.558594 -4.746094 4.085938 -4.53125 4.515625 -4.097656 C 4.945312 -3.664062 5.160156 -3.105469 5.160156 -2.425781 C 5.160156 -1.777344 4.972656 -1.21875 4.59375 -0.746094 C 4.136719 -0.167969 3.507812 0.121094 2.714844 0.121094 C 2.0625 0.121094 1.53125 -0.0585938 1.121094 -0.425781 C 0.710938 -0.789062 0.472656 -1.273438 0.414062 -1.875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-5"> +<path style="stroke:none;" d="M 0.820312 0 L 0.820312 -7.15625 L 5.648438 -7.15625 L 5.648438 -6.3125 L 1.765625 -6.3125 L 1.765625 -4.097656 L 5.125 -4.097656 L 5.125 -3.25 L 1.765625 -3.25 L 1.765625 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-6"> +<path style="stroke:none;" d="M 4.058594 0 L 4.058594 -0.761719 C 3.65625 -0.175781 3.105469 0.117188 2.414062 0.117188 C 2.105469 0.117188 1.820312 0.0585938 1.554688 -0.0585938 C 1.289062 -0.175781 1.09375 -0.324219 0.964844 -0.5 C 0.835938 -0.679688 0.746094 -0.894531 0.695312 -1.152344 C 0.65625 -1.324219 0.640625 -1.597656 0.640625 -1.972656 L 0.640625 -5.1875 L 1.519531 -5.1875 L 1.519531 -2.308594 C 1.519531 -1.851562 1.535156 -1.542969 1.570312 -1.382812 C 1.625 -1.152344 1.746094 -0.96875 1.921875 -0.835938 C 2.101562 -0.703125 2.324219 -0.640625 2.585938 -0.640625 C 2.851562 -0.640625 3.097656 -0.707031 3.328125 -0.84375 C 3.5625 -0.976562 3.726562 -1.160156 3.820312 -1.394531 C 3.917969 -1.625 3.964844 -1.964844 3.964844 -2.40625 L 3.964844 -5.1875 L 4.84375 -5.1875 L 4.84375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-7"> +<path style="stroke:none;" d="M 0.660156 0 L 0.660156 -5.1875 L 1.449219 -5.1875 L 1.449219 -4.449219 C 1.832031 -5.019531 2.382812 -5.304688 3.101562 -5.304688 C 3.414062 -5.304688 3.699219 -5.246094 3.960938 -5.132812 C 4.222656 -5.023438 4.421875 -4.875 4.550781 -4.691406 C 4.679688 -4.507812 4.773438 -4.292969 4.824219 -4.042969 C 4.855469 -3.878906 4.875 -3.59375 4.875 -3.1875 L 4.875 0 L 3.992188 0 L 3.992188 -3.15625 C 3.992188 -3.511719 3.960938 -3.78125 3.890625 -3.957031 C 3.824219 -4.132812 3.703125 -4.277344 3.527344 -4.382812 C 3.351562 -4.488281 3.148438 -4.539062 2.914062 -4.539062 C 2.539062 -4.539062 2.21875 -4.421875 1.945312 -4.183594 C 1.671875 -3.945312 1.539062 -3.496094 1.539062 -2.832031 L 1.539062 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-8"> +<path style="stroke:none;" d="M 4.042969 -1.898438 L 4.90625 -1.789062 C 4.8125 -1.191406 4.570312 -0.726562 4.183594 -0.386719 C 3.792969 -0.0507812 3.316406 0.117188 2.75 0.117188 C 2.039062 0.117188 1.46875 -0.113281 1.039062 -0.578125 C 0.605469 -1.042969 0.390625 -1.707031 0.390625 -2.574219 C 0.390625 -3.132812 0.484375 -3.625 0.667969 -4.042969 C 0.855469 -4.460938 1.136719 -4.777344 1.515625 -4.988281 C 1.894531 -5.199219 2.308594 -5.304688 2.753906 -5.304688 C 3.316406 -5.304688 3.777344 -5.160156 4.136719 -4.875 C 4.492188 -4.589844 4.722656 -4.1875 4.824219 -3.664062 L 3.96875 -3.53125 C 3.886719 -3.878906 3.746094 -4.140625 3.539062 -4.316406 C 3.332031 -4.492188 3.082031 -4.578125 2.789062 -4.578125 C 2.34375 -4.578125 1.984375 -4.421875 1.710938 -4.105469 C 1.433594 -3.789062 1.292969 -3.285156 1.292969 -2.597656 C 1.292969 -1.902344 1.425781 -1.394531 1.695312 -1.078125 C 1.960938 -0.761719 2.308594 -0.605469 2.738281 -0.605469 C 3.085938 -0.605469 3.371094 -0.710938 3.601562 -0.921875 C 3.835938 -1.132812 3.980469 -1.460938 4.042969 -1.898438 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-9"> +<path style="stroke:none;" d="M 2.578125 -0.785156 L 2.703125 -0.0078125 C 2.457031 0.0429688 2.234375 0.0703125 2.039062 0.0703125 C 1.722656 0.0703125 1.476562 0.0195312 1.296875 -0.0820312 C 1.121094 -0.183594 1 -0.316406 0.929688 -0.480469 C 0.855469 -0.644531 0.820312 -0.992188 0.820312 -1.519531 L 0.820312 -4.5 L 0.175781 -4.5 L 0.175781 -5.1875 L 0.820312 -5.1875 L 0.820312 -6.46875 L 1.695312 -6.996094 L 1.695312 -5.1875 L 2.578125 -5.1875 L 2.578125 -4.5 L 1.695312 -4.5 L 1.695312 -1.46875 C 1.695312 -1.21875 1.710938 -1.058594 1.742188 -0.984375 C 1.773438 -0.914062 1.820312 -0.859375 1.890625 -0.816406 C 1.960938 -0.773438 2.0625 -0.75 2.191406 -0.75 C 2.289062 -0.75 2.417969 -0.761719 2.578125 -0.785156 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-10"> +<path style="stroke:none;" d="M 0.664062 -6.148438 L 0.664062 -7.15625 L 1.542969 -7.15625 L 1.542969 -6.148438 Z M 0.664062 0 L 0.664062 -5.1875 L 1.542969 -5.1875 L 1.542969 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-11"> +<path style="stroke:none;" d="M 0.332031 -2.59375 C 0.332031 -3.554688 0.597656 -4.265625 1.132812 -4.726562 C 1.578125 -5.109375 2.121094 -5.304688 2.765625 -5.304688 C 3.476562 -5.304688 4.058594 -5.070312 4.511719 -4.601562 C 4.964844 -4.132812 5.191406 -3.488281 5.191406 -2.664062 C 5.191406 -2 5.089844 -1.472656 4.890625 -1.089844 C 4.691406 -0.707031 4.398438 -0.410156 4.015625 -0.199219 C 3.632812 0.0117188 3.214844 0.117188 2.765625 0.117188 C 2.039062 0.117188 1.449219 -0.117188 1.003906 -0.582031 C 0.554688 -1.046875 0.332031 -1.71875 0.332031 -2.59375 Z M 1.234375 -2.59375 C 1.234375 -1.929688 1.378906 -1.429688 1.671875 -1.101562 C 1.960938 -0.769531 2.324219 -0.605469 2.765625 -0.605469 C 3.199219 -0.605469 3.5625 -0.773438 3.851562 -1.101562 C 4.140625 -1.433594 4.289062 -1.941406 4.289062 -2.621094 C 4.289062 -3.261719 4.140625 -3.75 3.851562 -4.078125 C 3.558594 -4.410156 3.195312 -4.574219 2.765625 -4.574219 C 2.324219 -4.574219 1.960938 -4.410156 1.671875 -4.082031 C 1.382812 -3.753906 1.234375 -3.257812 1.234375 -2.59375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-12"> +<path style="stroke:none;" d="M 0.308594 -1.546875 L 1.175781 -1.683594 C 1.226562 -1.335938 1.363281 -1.070312 1.585938 -0.882812 C 1.808594 -0.699219 2.117188 -0.605469 2.519531 -0.605469 C 2.921875 -0.605469 3.222656 -0.6875 3.417969 -0.851562 C 3.613281 -1.015625 3.710938 -1.210938 3.710938 -1.429688 C 3.710938 -1.628906 3.625 -1.785156 3.453125 -1.898438 C 3.332031 -1.976562 3.03125 -2.078125 2.554688 -2.195312 C 1.910156 -2.359375 1.460938 -2.5 1.214844 -2.621094 C 0.964844 -2.738281 0.777344 -2.902344 0.648438 -3.113281 C 0.519531 -3.324219 0.453125 -3.554688 0.453125 -3.808594 C 0.453125 -4.039062 0.507812 -4.253906 0.613281 -4.449219 C 0.71875 -4.648438 0.863281 -4.8125 1.046875 -4.941406 C 1.183594 -5.042969 1.367188 -5.128906 1.605469 -5.199219 C 1.839844 -5.269531 2.09375 -5.304688 2.363281 -5.304688 C 2.769531 -5.304688 3.128906 -5.242188 3.433594 -5.125 C 3.742188 -5.007812 3.96875 -4.851562 4.117188 -4.652344 C 4.261719 -4.453125 4.363281 -4.183594 4.417969 -3.847656 L 3.558594 -3.730469 C 3.519531 -3.996094 3.40625 -4.207031 3.21875 -4.355469 C 3.03125 -4.503906 2.769531 -4.578125 2.425781 -4.578125 C 2.023438 -4.578125 1.734375 -4.511719 1.5625 -4.378906 C 1.390625 -4.246094 1.304688 -4.089844 1.304688 -3.910156 C 1.304688 -3.796875 1.339844 -3.695312 1.410156 -3.601562 C 1.484375 -3.507812 1.59375 -3.429688 1.75 -3.367188 C 1.835938 -3.335938 2.09375 -3.261719 2.523438 -3.144531 C 3.144531 -2.976562 3.578125 -2.84375 3.824219 -2.738281 C 4.070312 -2.632812 4.265625 -2.476562 4.40625 -2.273438 C 4.546875 -2.074219 4.613281 -1.824219 4.613281 -1.523438 C 4.613281 -1.230469 4.527344 -0.953125 4.359375 -0.695312 C 4.1875 -0.4375 3.941406 -0.238281 3.617188 -0.09375 C 3.296875 0.046875 2.929688 0.117188 2.523438 0.117188 C 1.851562 0.117188 1.335938 -0.0234375 0.984375 -0.304688 C 0.632812 -0.582031 0.40625 -0.996094 0.308594 -1.546875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph1-1"> +<path style="stroke:none;" d="M -2.300781 -0.449219 L -2.378906 -1.34375 C -2.019531 -1.386719 -1.726562 -1.484375 -1.496094 -1.636719 C -1.265625 -1.792969 -1.082031 -2.03125 -0.941406 -2.359375 C -0.796875 -2.683594 -0.726562 -3.050781 -0.726562 -3.457031 C -0.726562 -3.820312 -0.78125 -4.136719 -0.890625 -4.414062 C -0.996094 -4.691406 -1.144531 -4.898438 -1.332031 -5.03125 C -1.519531 -5.167969 -1.722656 -5.234375 -1.945312 -5.234375 C -2.167969 -5.234375 -2.363281 -5.167969 -2.53125 -5.039062 C -2.699219 -4.910156 -2.839844 -4.695312 -2.953125 -4.394531 C -3.027344 -4.203125 -3.144531 -3.777344 -3.304688 -3.121094 C -3.460938 -2.460938 -3.609375 -2 -3.75 -1.738281 C -3.929688 -1.398438 -4.152344 -1.140625 -4.417969 -0.972656 C -4.683594 -0.804688 -4.980469 -0.722656 -5.308594 -0.722656 C -5.667969 -0.722656 -6.007812 -0.824219 -6.320312 -1.03125 C -6.632812 -1.234375 -6.875 -1.535156 -7.035156 -1.929688 C -7.199219 -2.324219 -7.28125 -2.761719 -7.28125 -3.242188 C -7.28125 -3.773438 -7.195312 -4.242188 -7.023438 -4.644531 C -6.851562 -5.050781 -6.601562 -5.363281 -6.269531 -5.582031 C -5.9375 -5.800781 -5.5625 -5.917969 -5.140625 -5.933594 L -5.074219 -5.023438 C -5.527344 -4.976562 -5.867188 -4.808594 -6.097656 -4.527344 C -6.328125 -4.246094 -6.445312 -3.832031 -6.445312 -3.28125 C -6.445312 -2.707031 -6.339844 -2.289062 -6.128906 -2.027344 C -5.921875 -1.765625 -5.667969 -1.636719 -5.371094 -1.636719 C -5.113281 -1.636719 -4.902344 -1.726562 -4.734375 -1.914062 C -4.570312 -2.097656 -4.398438 -2.574219 -4.226562 -3.34375 C -4.050781 -4.113281 -3.898438 -4.640625 -3.769531 -4.925781 C -3.578125 -5.34375 -3.335938 -5.652344 -3.039062 -5.851562 C -2.746094 -6.046875 -2.40625 -6.148438 -2.023438 -6.148438 C -1.640625 -6.148438 -1.28125 -6.039062 -0.945312 -5.820312 C -0.609375 -5.601562 -0.347656 -5.289062 -0.160156 -4.878906 C 0.0273438 -4.472656 0.121094 -4.011719 0.121094 -3.5 C 0.121094 -2.851562 0.0273438 -2.308594 -0.160156 -1.871094 C -0.351562 -1.433594 -0.632812 -1.089844 -1.011719 -0.84375 C -1.390625 -0.59375 -1.820312 -0.460938 -2.300781 -0.449219 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-2"> +<path style="stroke:none;" d="M -1.671875 -4.210938 L -1.558594 -5.117188 C -1.027344 -4.972656 -0.617188 -4.707031 -0.320312 -4.320312 C -0.0273438 -3.933594 0.117188 -3.4375 0.117188 -2.835938 C 0.117188 -2.078125 -0.117188 -1.476562 -0.582031 -1.03125 C -1.050781 -0.585938 -1.707031 -0.367188 -2.546875 -0.367188 C -3.421875 -0.367188 -4.097656 -0.589844 -4.578125 -1.039062 C -5.0625 -1.488281 -5.304688 -2.070312 -5.304688 -2.789062 C -5.304688 -3.480469 -5.066406 -4.046875 -4.59375 -4.488281 C -4.121094 -4.925781 -3.457031 -5.148438 -2.601562 -5.148438 C -2.550781 -5.148438 -2.472656 -5.144531 -2.367188 -5.140625 L -2.367188 -1.273438 C -1.796875 -1.304688 -1.363281 -1.46875 -1.058594 -1.757812 C -0.757812 -2.046875 -0.605469 -2.410156 -0.605469 -2.84375 C -0.605469 -3.164062 -0.691406 -3.4375 -0.859375 -3.667969 C -1.027344 -3.894531 -1.296875 -4.074219 -1.671875 -4.210938 Z M -3.089844 -1.324219 L -3.089844 -4.21875 C -3.527344 -4.179688 -3.855469 -4.070312 -4.070312 -3.886719 C -4.410156 -3.605469 -4.578125 -3.242188 -4.578125 -2.796875 C -4.578125 -2.394531 -4.445312 -2.054688 -4.175781 -1.78125 C -3.90625 -1.503906 -3.542969 -1.351562 -3.089844 -1.324219 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-3"> +<path style="stroke:none;" d="M -1.898438 -4.042969 L -1.789062 -4.90625 C -1.191406 -4.8125 -0.726562 -4.570312 -0.386719 -4.183594 C -0.0507812 -3.792969 0.117188 -3.316406 0.117188 -2.75 C 0.117188 -2.039062 -0.113281 -1.46875 -0.578125 -1.039062 C -1.042969 -0.605469 -1.707031 -0.390625 -2.574219 -0.390625 C -3.132812 -0.390625 -3.625 -0.484375 -4.042969 -0.667969 C -4.460938 -0.855469 -4.777344 -1.136719 -4.988281 -1.515625 C -5.199219 -1.894531 -5.304688 -2.308594 -5.304688 -2.753906 C -5.304688 -3.316406 -5.160156 -3.777344 -4.875 -4.136719 C -4.589844 -4.492188 -4.1875 -4.722656 -3.664062 -4.824219 L -3.53125 -3.96875 C -3.878906 -3.886719 -4.140625 -3.746094 -4.316406 -3.539062 C -4.492188 -3.332031 -4.578125 -3.082031 -4.578125 -2.789062 C -4.578125 -2.34375 -4.421875 -1.984375 -4.105469 -1.710938 C -3.789062 -1.433594 -3.285156 -1.292969 -2.597656 -1.292969 C -1.902344 -1.292969 -1.394531 -1.425781 -1.078125 -1.695312 C -0.761719 -1.960938 -0.605469 -2.308594 -0.605469 -2.738281 C -0.605469 -3.085938 -0.710938 -3.371094 -0.921875 -3.601562 C -1.132812 -3.835938 -1.460938 -3.980469 -1.898438 -4.042969 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-4"> +<path style="stroke:none;" d="M -2.59375 -0.332031 C -3.554688 -0.332031 -4.265625 -0.597656 -4.726562 -1.132812 C -5.109375 -1.578125 -5.304688 -2.121094 -5.304688 -2.765625 C -5.304688 -3.476562 -5.070312 -4.058594 -4.601562 -4.511719 C -4.132812 -4.964844 -3.488281 -5.191406 -2.664062 -5.191406 C -2 -5.191406 -1.472656 -5.089844 -1.089844 -4.890625 C -0.707031 -4.691406 -0.410156 -4.398438 -0.199219 -4.015625 C 0.0117188 -3.632812 0.117188 -3.214844 0.117188 -2.765625 C 0.117188 -2.039062 -0.117188 -1.449219 -0.582031 -1.003906 C -1.046875 -0.554688 -1.71875 -0.332031 -2.59375 -0.332031 Z M -2.59375 -1.234375 C -1.929688 -1.234375 -1.429688 -1.378906 -1.101562 -1.671875 C -0.769531 -1.960938 -0.605469 -2.324219 -0.605469 -2.765625 C -0.605469 -3.199219 -0.773438 -3.5625 -1.101562 -3.851562 C -1.433594 -4.140625 -1.941406 -4.289062 -2.621094 -4.289062 C -3.261719 -4.289062 -3.75 -4.140625 -4.078125 -3.851562 C -4.410156 -3.558594 -4.574219 -3.195312 -4.574219 -2.765625 C -4.574219 -2.324219 -4.410156 -1.960938 -4.082031 -1.671875 C -3.753906 -1.382812 -3.257812 -1.234375 -2.59375 -1.234375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-5"> +<path style="stroke:none;" d="M 0 -0.660156 L -5.1875 -0.660156 L -5.1875 -1.449219 L -4.449219 -1.449219 C -5.019531 -1.832031 -5.304688 -2.382812 -5.304688 -3.101562 C -5.304688 -3.414062 -5.246094 -3.699219 -5.132812 -3.960938 C -5.023438 -4.222656 -4.875 -4.421875 -4.691406 -4.550781 C -4.507812 -4.679688 -4.292969 -4.773438 -4.042969 -4.824219 C -3.878906 -4.855469 -3.59375 -4.875 -3.1875 -4.875 L 0 -4.875 L 0 -3.992188 L -3.15625 -3.992188 C -3.511719 -3.992188 -3.78125 -3.960938 -3.957031 -3.890625 C -4.132812 -3.824219 -4.277344 -3.703125 -4.382812 -3.527344 C -4.488281 -3.351562 -4.539062 -3.148438 -4.539062 -2.914062 C -4.539062 -2.539062 -4.421875 -2.21875 -4.183594 -1.945312 C -3.945312 -1.671875 -3.496094 -1.539062 -2.832031 -1.539062 L 0 -1.539062 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-6"> +<path style="stroke:none;" d="M 0 -4.023438 L -0.65625 -4.023438 C -0.140625 -3.695312 0.117188 -3.210938 0.117188 -2.574219 C 0.117188 -2.160156 0.00390625 -1.78125 -0.226562 -1.433594 C -0.453125 -1.085938 -0.769531 -0.816406 -1.179688 -0.628906 C -1.585938 -0.4375 -2.058594 -0.34375 -2.585938 -0.34375 C -3.105469 -0.34375 -3.574219 -0.429688 -3.996094 -0.601562 C -4.417969 -0.773438 -4.742188 -1.03125 -4.964844 -1.375 C -5.191406 -1.722656 -5.304688 -2.109375 -5.304688 -2.535156 C -5.304688 -2.847656 -5.238281 -3.125 -5.105469 -3.367188 C -4.972656 -3.613281 -4.800781 -3.8125 -4.589844 -3.964844 L -7.15625 -3.964844 L -7.15625 -4.839844 L 0 -4.839844 Z M -2.585938 -1.246094 C -1.921875 -1.246094 -1.425781 -1.386719 -1.097656 -1.664062 C -0.769531 -1.945312 -0.605469 -2.273438 -0.605469 -2.65625 C -0.605469 -3.039062 -0.761719 -3.367188 -1.078125 -3.636719 C -1.390625 -3.90625 -1.871094 -4.039062 -2.515625 -4.039062 C -3.226562 -4.039062 -3.746094 -3.902344 -4.078125 -3.628906 C -4.410156 -3.355469 -4.574219 -3.015625 -4.574219 -2.617188 C -4.574219 -2.226562 -4.414062 -1.898438 -4.097656 -1.636719 C -3.777344 -1.375 -3.273438 -1.246094 -2.585938 -1.246094 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-7"> +<path style="stroke:none;" d="M -1.546875 -0.308594 L -1.683594 -1.175781 C -1.335938 -1.226562 -1.070312 -1.363281 -0.882812 -1.585938 C -0.699219 -1.808594 -0.605469 -2.117188 -0.605469 -2.519531 C -0.605469 -2.921875 -0.6875 -3.222656 -0.851562 -3.417969 C -1.015625 -3.613281 -1.210938 -3.710938 -1.429688 -3.710938 C -1.628906 -3.710938 -1.785156 -3.625 -1.898438 -3.453125 C -1.976562 -3.332031 -2.078125 -3.03125 -2.195312 -2.554688 C -2.359375 -1.910156 -2.5 -1.460938 -2.621094 -1.214844 C -2.738281 -0.964844 -2.902344 -0.777344 -3.113281 -0.648438 C -3.324219 -0.519531 -3.554688 -0.453125 -3.808594 -0.453125 C -4.039062 -0.453125 -4.253906 -0.507812 -4.449219 -0.613281 C -4.648438 -0.71875 -4.8125 -0.863281 -4.941406 -1.046875 C -5.042969 -1.183594 -5.128906 -1.367188 -5.199219 -1.605469 C -5.269531 -1.839844 -5.304688 -2.09375 -5.304688 -2.363281 C -5.304688 -2.769531 -5.242188 -3.128906 -5.125 -3.433594 C -5.007812 -3.742188 -4.851562 -3.96875 -4.652344 -4.117188 C -4.453125 -4.261719 -4.183594 -4.363281 -3.847656 -4.417969 L -3.730469 -3.558594 C -3.996094 -3.519531 -4.207031 -3.40625 -4.355469 -3.21875 C -4.503906 -3.03125 -4.578125 -2.769531 -4.578125 -2.425781 C -4.578125 -2.023438 -4.511719 -1.734375 -4.378906 -1.5625 C -4.246094 -1.390625 -4.089844 -1.304688 -3.910156 -1.304688 C -3.796875 -1.304688 -3.695312 -1.339844 -3.601562 -1.410156 C -3.507812 -1.484375 -3.429688 -1.59375 -3.367188 -1.75 C -3.335938 -1.835938 -3.261719 -2.09375 -3.144531 -2.523438 C -2.976562 -3.144531 -2.84375 -3.578125 -2.738281 -3.824219 C -2.632812 -4.070312 -2.476562 -4.265625 -2.273438 -4.40625 C -2.074219 -4.546875 -1.824219 -4.613281 -1.523438 -4.613281 C -1.230469 -4.613281 -0.953125 -4.527344 -0.695312 -4.359375 C -0.4375 -4.1875 -0.238281 -3.941406 -0.09375 -3.617188 C 0.046875 -3.296875 0.117188 -2.929688 0.117188 -2.523438 C 0.117188 -1.851562 -0.0234375 -1.335938 -0.304688 -0.984375 C -0.582031 -0.632812 -0.996094 -0.40625 -1.546875 -0.308594 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph2-1"> +<path style="stroke:none;" d="M 7.054688 -3.011719 L 8.191406 -2.726562 C 7.953125 -1.792969 7.523438 -1.078125 6.90625 -0.589844 C 6.285156 -0.0976562 5.53125 0.148438 4.632812 0.148438 C 3.707031 0.148438 2.957031 -0.0429688 2.375 -0.417969 C 1.796875 -0.796875 1.355469 -1.34375 1.050781 -2.054688 C 0.75 -2.769531 0.597656 -3.539062 0.597656 -4.359375 C 0.597656 -5.253906 0.769531 -6.035156 1.109375 -6.699219 C 1.453125 -7.367188 1.9375 -7.871094 2.570312 -8.21875 C 3.199219 -8.5625 3.894531 -8.734375 4.652344 -8.734375 C 5.511719 -8.734375 6.234375 -8.515625 6.820312 -8.078125 C 7.40625 -7.640625 7.8125 -7.027344 8.046875 -6.234375 L 6.925781 -5.96875 C 6.726562 -6.59375 6.4375 -7.050781 6.058594 -7.335938 C 5.679688 -7.621094 5.203125 -7.765625 4.628906 -7.765625 C 3.96875 -7.765625 3.417969 -7.605469 2.972656 -7.289062 C 2.53125 -6.972656 2.21875 -6.546875 2.039062 -6.015625 C 1.859375 -5.480469 1.769531 -4.929688 1.769531 -4.367188 C 1.769531 -3.636719 1.875 -2.996094 2.089844 -2.453125 C 2.300781 -1.90625 2.632812 -1.5 3.082031 -1.230469 C 3.53125 -0.960938 4.015625 -0.828125 4.539062 -0.828125 C 5.175781 -0.828125 5.71875 -1.007812 6.15625 -1.375 C 6.597656 -1.742188 6.898438 -2.289062 7.054688 -3.011719 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-2"> +<path style="stroke:none;" d="M 0.398438 -3.109375 C 0.398438 -4.261719 0.71875 -5.117188 1.359375 -5.671875 C 1.894531 -6.132812 2.546875 -6.363281 3.316406 -6.363281 C 4.171875 -6.363281 4.871094 -6.082031 5.414062 -5.523438 C 5.957031 -4.960938 6.226562 -4.1875 6.226562 -3.199219 C 6.226562 -2.398438 6.109375 -1.769531 5.867188 -1.308594 C 5.628906 -0.851562 5.277344 -0.492188 4.820312 -0.242188 C 4.359375 0.0117188 3.859375 0.140625 3.316406 0.140625 C 2.445312 0.140625 1.742188 -0.140625 1.203125 -0.695312 C 0.667969 -1.253906 0.398438 -2.0625 0.398438 -3.109375 Z M 1.484375 -3.109375 C 1.484375 -2.3125 1.65625 -1.71875 2.003906 -1.320312 C 2.351562 -0.925781 2.789062 -0.726562 3.316406 -0.726562 C 3.839844 -0.726562 4.273438 -0.925781 4.625 -1.324219 C 4.972656 -1.722656 5.144531 -2.328125 5.144531 -3.148438 C 5.144531 -3.917969 4.96875 -4.5 4.621094 -4.894531 C 4.269531 -5.292969 3.835938 -5.492188 3.316406 -5.492188 C 2.789062 -5.492188 2.351562 -5.292969 2.003906 -4.898438 C 1.65625 -4.503906 1.484375 -3.90625 1.484375 -3.109375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-3"> +<path style="stroke:none;" d="M 0.789062 0 L 0.789062 -6.222656 L 1.734375 -6.222656 L 1.734375 -5.351562 C 1.929688 -5.65625 2.1875 -5.898438 2.515625 -6.085938 C 2.839844 -6.269531 3.207031 -6.363281 3.621094 -6.363281 C 4.082031 -6.363281 4.460938 -6.265625 4.753906 -6.078125 C 5.050781 -5.886719 5.257812 -5.617188 5.378906 -5.273438 C 5.871094 -6 6.511719 -6.363281 7.300781 -6.363281 C 7.917969 -6.363281 8.390625 -6.191406 8.726562 -5.851562 C 9.058594 -5.507812 9.222656 -4.984375 9.222656 -4.273438 L 9.222656 0 L 8.171875 0 L 8.171875 -3.921875 C 8.171875 -4.34375 8.140625 -4.644531 8.070312 -4.832031 C 8.003906 -5.015625 7.878906 -5.164062 7.699219 -5.28125 C 7.519531 -5.394531 7.308594 -5.449219 7.066406 -5.449219 C 6.628906 -5.449219 6.265625 -5.304688 5.976562 -5.011719 C 5.6875 -4.722656 5.542969 -4.257812 5.542969 -3.617188 L 5.542969 0 L 4.488281 0 L 4.488281 -4.042969 C 4.488281 -4.511719 4.402344 -4.863281 4.230469 -5.097656 C 4.058594 -5.332031 3.777344 -5.449219 3.386719 -5.449219 C 3.089844 -5.449219 2.816406 -5.371094 2.5625 -5.214844 C 2.3125 -5.058594 2.128906 -4.828125 2.015625 -4.53125 C 1.902344 -4.230469 1.84375 -3.796875 1.84375 -3.226562 L 1.84375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-4"> +<path style="stroke:none;" d="M 0.789062 2.382812 L 0.789062 -6.222656 L 1.75 -6.222656 L 1.75 -5.414062 C 1.976562 -5.730469 2.234375 -5.96875 2.519531 -6.125 C 2.804688 -6.285156 3.148438 -6.363281 3.554688 -6.363281 C 4.085938 -6.363281 4.554688 -6.226562 4.960938 -5.953125 C 5.367188 -5.679688 5.675781 -5.292969 5.882812 -4.796875 C 6.089844 -4.296875 6.195312 -3.75 6.195312 -3.15625 C 6.195312 -2.519531 6.078125 -1.949219 5.851562 -1.4375 C 5.621094 -0.929688 5.289062 -0.539062 4.855469 -0.265625 C 4.417969 0.00390625 3.960938 0.140625 3.480469 0.140625 C 3.128906 0.140625 2.8125 0.0664062 2.535156 -0.0820312 C 2.253906 -0.230469 2.023438 -0.417969 1.84375 -0.644531 L 1.84375 2.382812 Z M 1.746094 -3.078125 C 1.746094 -2.277344 1.90625 -1.683594 2.234375 -1.300781 C 2.558594 -0.917969 2.949219 -0.726562 3.410156 -0.726562 C 3.878906 -0.726562 4.28125 -0.925781 4.613281 -1.320312 C 4.949219 -1.71875 5.117188 -2.332031 5.117188 -3.164062 C 5.117188 -3.957031 4.953125 -4.550781 4.625 -4.945312 C 4.300781 -5.339844 3.910156 -5.539062 3.457031 -5.539062 C 3.007812 -5.539062 2.609375 -5.328125 2.265625 -4.90625 C 1.917969 -4.488281 1.746094 -3.875 1.746094 -3.078125 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-5"> +<path style="stroke:none;" d="M 0.796875 -7.375 L 0.796875 -8.589844 L 1.851562 -8.589844 L 1.851562 -7.375 Z M 0.796875 0 L 0.796875 -6.222656 L 1.851562 -6.222656 L 1.851562 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-6"> +<path style="stroke:none;" d="M 0.765625 0 L 0.765625 -8.589844 L 1.820312 -8.589844 L 1.820312 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-7"> +<path style="stroke:none;" d="M 4.851562 -0.765625 C 4.460938 -0.433594 4.085938 -0.203125 3.722656 -0.0625 C 3.363281 0.0742188 2.976562 0.140625 2.5625 0.140625 C 1.878906 0.140625 1.351562 -0.0273438 0.984375 -0.359375 C 0.617188 -0.695312 0.433594 -1.121094 0.433594 -1.640625 C 0.433594 -1.945312 0.503906 -2.222656 0.640625 -2.476562 C 0.78125 -2.726562 0.960938 -2.929688 1.1875 -3.082031 C 1.410156 -3.234375 1.664062 -3.351562 1.945312 -3.429688 C 2.152344 -3.484375 2.464844 -3.535156 2.882812 -3.585938 C 3.734375 -3.6875 4.359375 -3.808594 4.765625 -3.949219 C 4.769531 -4.09375 4.769531 -4.1875 4.769531 -4.226562 C 4.769531 -4.65625 4.671875 -4.957031 4.46875 -5.132812 C 4.199219 -5.371094 3.800781 -5.492188 3.269531 -5.492188 C 2.773438 -5.492188 2.40625 -5.402344 2.171875 -5.230469 C 1.933594 -5.054688 1.757812 -4.75 1.648438 -4.304688 L 0.617188 -4.445312 C 0.710938 -4.886719 0.863281 -5.246094 1.078125 -5.515625 C 1.292969 -5.789062 1.601562 -5.996094 2.007812 -6.144531 C 2.414062 -6.289062 2.886719 -6.363281 3.421875 -6.363281 C 3.953125 -6.363281 4.382812 -6.300781 4.71875 -6.175781 C 5.050781 -6.050781 5.292969 -5.894531 5.449219 -5.703125 C 5.605469 -5.515625 5.714844 -5.273438 5.777344 -4.984375 C 5.8125 -4.804688 5.828125 -4.484375 5.828125 -4.015625 L 5.828125 -2.609375 C 5.828125 -1.628906 5.851562 -1.007812 5.898438 -0.746094 C 5.941406 -0.488281 6.03125 -0.238281 6.164062 0 L 5.0625 0 C 4.953125 -0.21875 4.882812 -0.476562 4.851562 -0.765625 Z M 4.765625 -3.125 C 4.382812 -2.96875 3.804688 -2.835938 3.039062 -2.726562 C 2.605469 -2.664062 2.300781 -2.59375 2.121094 -2.515625 C 1.941406 -2.4375 1.804688 -2.320312 1.703125 -2.171875 C 1.605469 -2.019531 1.558594 -1.851562 1.558594 -1.671875 C 1.558594 -1.390625 1.664062 -1.15625 1.878906 -0.96875 C 2.089844 -0.78125 2.402344 -0.6875 2.8125 -0.6875 C 3.21875 -0.6875 3.578125 -0.773438 3.898438 -0.953125 C 4.214844 -1.128906 4.445312 -1.375 4.59375 -1.679688 C 4.707031 -1.917969 4.765625 -2.273438 4.765625 -2.734375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-8"> +<path style="stroke:none;" d="M 3.09375 -0.945312 L 3.246094 -0.0117188 C 2.949219 0.0507812 2.683594 0.0820312 2.449219 0.0820312 C 2.066406 0.0820312 1.769531 0.0234375 1.558594 -0.101562 C 1.347656 -0.222656 1.199219 -0.378906 1.113281 -0.578125 C 1.027344 -0.773438 0.984375 -1.1875 0.984375 -1.820312 L 0.984375 -5.402344 L 0.210938 -5.402344 L 0.210938 -6.222656 L 0.984375 -6.222656 L 0.984375 -7.765625 L 2.03125 -8.398438 L 2.03125 -6.222656 L 3.09375 -6.222656 L 3.09375 -5.402344 L 2.03125 -5.402344 L 2.03125 -1.765625 C 2.03125 -1.464844 2.050781 -1.269531 2.089844 -1.183594 C 2.125 -1.097656 2.1875 -1.03125 2.269531 -0.976562 C 2.355469 -0.925781 2.476562 -0.902344 2.632812 -0.902344 C 2.75 -0.902344 2.902344 -0.914062 3.09375 -0.945312 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-9"> +<path style="stroke:none;" d="M 0.789062 0 L 0.789062 -6.222656 L 1.742188 -6.222656 L 1.742188 -5.335938 C 2.199219 -6.019531 2.859375 -6.363281 3.71875 -6.363281 C 4.09375 -6.363281 4.441406 -6.296875 4.753906 -6.160156 C 5.070312 -6.027344 5.304688 -5.851562 5.460938 -5.632812 C 5.617188 -5.414062 5.726562 -5.152344 5.789062 -4.851562 C 5.828125 -4.65625 5.847656 -4.3125 5.847656 -3.828125 L 5.847656 0 L 4.792969 0 L 4.792969 -3.785156 C 4.792969 -4.214844 4.75 -4.535156 4.671875 -4.75 C 4.589844 -4.960938 4.441406 -5.132812 4.234375 -5.257812 C 4.023438 -5.386719 3.78125 -5.449219 3.5 -5.449219 C 3.050781 -5.449219 2.660156 -5.304688 2.335938 -5.023438 C 2.007812 -4.738281 1.84375 -4.195312 1.84375 -3.398438 L 1.84375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-10"> +<path style="stroke:none;" d="M 5.050781 -2.003906 L 6.140625 -1.867188 C 5.96875 -1.230469 5.648438 -0.738281 5.1875 -0.386719 C 4.722656 -0.0351562 4.125 0.140625 3.40625 0.140625 C 2.496094 0.140625 1.773438 -0.140625 1.238281 -0.699219 C 0.707031 -1.261719 0.4375 -2.046875 0.4375 -3.058594 C 0.4375 -4.105469 0.710938 -4.917969 1.25 -5.496094 C 1.789062 -6.074219 2.484375 -6.363281 3.34375 -6.363281 C 4.175781 -6.363281 4.859375 -6.078125 5.382812 -5.515625 C 5.910156 -4.949219 6.175781 -4.148438 6.175781 -3.125 C 6.175781 -3.0625 6.171875 -2.96875 6.171875 -2.84375 L 1.53125 -2.84375 C 1.570312 -2.160156 1.761719 -1.632812 2.109375 -1.273438 C 2.457031 -0.910156 2.890625 -0.726562 3.410156 -0.726562 C 3.796875 -0.726562 4.125 -0.828125 4.398438 -1.03125 C 4.671875 -1.234375 4.890625 -1.558594 5.050781 -2.003906 Z M 1.585938 -3.710938 L 5.0625 -3.710938 C 5.015625 -4.234375 4.882812 -4.625 4.664062 -4.886719 C 4.328125 -5.292969 3.890625 -5.496094 3.359375 -5.496094 C 2.875 -5.496094 2.464844 -5.335938 2.136719 -5.007812 C 1.804688 -4.683594 1.625 -4.25 1.585938 -3.710938 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-11"> +<path style="stroke:none;" d="M 1.042969 0 L 1.042969 -5.402344 L 0.109375 -5.402344 L 0.109375 -6.222656 L 1.042969 -6.222656 L 1.042969 -6.882812 C 1.042969 -7.300781 1.078125 -7.613281 1.15625 -7.816406 C 1.257812 -8.089844 1.433594 -8.3125 1.691406 -8.480469 C 1.945312 -8.652344 2.304688 -8.734375 2.765625 -8.734375 C 3.0625 -8.734375 3.390625 -8.703125 3.75 -8.632812 L 3.59375 -7.710938 C 3.375 -7.75 3.164062 -7.769531 2.96875 -7.769531 C 2.648438 -7.769531 2.421875 -7.703125 2.289062 -7.5625 C 2.15625 -7.425781 2.09375 -7.171875 2.09375 -6.796875 L 2.09375 -6.222656 L 3.304688 -6.222656 L 3.304688 -5.402344 L 2.09375 -5.402344 L 2.09375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-12"> +<path style="stroke:none;" d="M 4.828125 0 L 4.828125 -0.785156 C 4.433594 -0.167969 3.851562 0.140625 3.085938 0.140625 C 2.589844 0.140625 2.136719 0.00390625 1.71875 -0.269531 C 1.304688 -0.542969 0.980469 -0.925781 0.753906 -1.414062 C 0.523438 -1.90625 0.410156 -2.46875 0.410156 -3.105469 C 0.410156 -3.726562 0.515625 -4.289062 0.71875 -4.796875 C 0.925781 -5.300781 1.238281 -5.6875 1.652344 -5.960938 C 2.066406 -6.230469 2.53125 -6.363281 3.039062 -6.363281 C 3.414062 -6.363281 3.75 -6.285156 4.042969 -6.125 C 4.335938 -5.96875 4.574219 -5.761719 4.757812 -5.507812 L 4.757812 -8.589844 L 5.804688 -8.589844 L 5.804688 0 Z M 1.492188 -3.105469 C 1.492188 -2.308594 1.664062 -1.710938 2 -1.320312 C 2.335938 -0.925781 2.730469 -0.726562 3.1875 -0.726562 C 3.648438 -0.726562 4.039062 -0.914062 4.363281 -1.292969 C 4.683594 -1.667969 4.84375 -2.242188 4.84375 -3.015625 C 4.84375 -3.867188 4.679688 -4.492188 4.351562 -4.890625 C 4.023438 -5.289062 3.621094 -5.492188 3.140625 -5.492188 C 2.671875 -5.492188 2.28125 -5.296875 1.964844 -4.914062 C 1.652344 -4.53125 1.492188 -3.929688 1.492188 -3.105469 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-13"> +<path style="stroke:none;" d="M 4.867188 0 L 4.867188 -0.914062 C 4.382812 -0.210938 3.726562 0.140625 2.894531 0.140625 C 2.527344 0.140625 2.183594 0.0703125 1.867188 -0.0703125 C 1.546875 -0.210938 1.3125 -0.386719 1.15625 -0.601562 C 1.003906 -0.8125 0.894531 -1.074219 0.832031 -1.382812 C 0.789062 -1.589844 0.765625 -1.917969 0.765625 -2.367188 L 0.765625 -6.222656 L 1.820312 -6.222656 L 1.820312 -2.773438 C 1.820312 -2.222656 1.84375 -1.851562 1.886719 -1.65625 C 1.953125 -1.378906 2.09375 -1.164062 2.308594 -1.003906 C 2.523438 -0.847656 2.789062 -0.765625 3.105469 -0.765625 C 3.421875 -0.765625 3.71875 -0.847656 3.996094 -1.011719 C 4.273438 -1.171875 4.46875 -1.394531 4.585938 -1.671875 C 4.699219 -1.953125 4.757812 -2.359375 4.757812 -2.890625 L 4.757812 -6.222656 L 5.8125 -6.222656 L 5.8125 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph3-1"> +<path style="stroke:none;" d="M 0.953125 0 L 0.953125 -9.304688 L 4.445312 -9.304688 C 5.15625 -9.304688 5.722656 -9.210938 6.152344 -9.023438 C 6.582031 -8.835938 6.921875 -8.546875 7.164062 -8.152344 C 7.40625 -7.761719 7.527344 -7.351562 7.527344 -6.925781 C 7.527344 -6.527344 7.421875 -6.152344 7.203125 -5.800781 C 6.988281 -5.449219 6.664062 -5.167969 6.226562 -4.953125 C 6.789062 -4.785156 7.222656 -4.503906 7.523438 -4.105469 C 7.828125 -3.707031 7.980469 -3.238281 7.980469 -2.699219 C 7.980469 -2.261719 7.886719 -1.855469 7.703125 -1.480469 C 7.519531 -1.105469 7.292969 -0.820312 7.019531 -0.617188 C 6.75 -0.414062 6.410156 -0.257812 6 -0.15625 C 5.59375 -0.0507812 5.09375 0 4.5 0 Z M 2.183594 -5.394531 L 4.195312 -5.394531 C 4.742188 -5.394531 5.132812 -5.429688 5.371094 -5.503906 C 5.683594 -5.597656 5.917969 -5.75 6.078125 -5.96875 C 6.238281 -6.183594 6.316406 -6.453125 6.316406 -6.78125 C 6.316406 -7.089844 6.242188 -7.359375 6.09375 -7.59375 C 5.945312 -7.828125 5.734375 -7.992188 5.460938 -8.078125 C 5.183594 -8.164062 4.710938 -8.207031 4.042969 -8.207031 L 2.183594 -8.207031 Z M 2.183594 -1.097656 L 4.5 -1.097656 C 4.898438 -1.097656 5.175781 -1.113281 5.339844 -1.140625 C 5.621094 -1.191406 5.859375 -1.277344 6.050781 -1.398438 C 6.242188 -1.515625 6.394531 -1.6875 6.519531 -1.914062 C 6.640625 -2.140625 6.703125 -2.402344 6.703125 -2.699219 C 6.703125 -3.046875 6.613281 -3.347656 6.4375 -3.601562 C 6.257812 -3.859375 6.011719 -4.039062 5.695312 -4.140625 C 5.382812 -4.246094 4.929688 -4.296875 4.335938 -4.296875 L 2.183594 -4.296875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-2"> +<path style="stroke:none;" d="M 0.429688 -3.371094 C 0.429688 -4.617188 0.777344 -5.542969 1.472656 -6.144531 C 2.050781 -6.644531 2.757812 -6.894531 3.59375 -6.894531 C 4.519531 -6.894531 5.277344 -6.589844 5.867188 -5.984375 C 6.453125 -5.375 6.746094 -4.535156 6.746094 -3.464844 C 6.746094 -2.597656 6.617188 -1.914062 6.355469 -1.417969 C 6.097656 -0.921875 5.71875 -0.535156 5.222656 -0.261719 C 4.722656 0.015625 4.179688 0.152344 3.59375 0.152344 C 2.648438 0.152344 1.886719 -0.148438 1.304688 -0.753906 C 0.722656 -1.359375 0.429688 -2.230469 0.429688 -3.371094 Z M 1.605469 -3.371094 C 1.605469 -2.507812 1.792969 -1.859375 2.171875 -1.429688 C 2.546875 -1 3.023438 -0.789062 3.59375 -0.789062 C 4.160156 -0.789062 4.632812 -1.003906 5.007812 -1.433594 C 5.382812 -1.867188 5.574219 -2.523438 5.574219 -3.410156 C 5.574219 -4.242188 5.382812 -4.875 5.003906 -5.304688 C 4.625 -5.734375 4.15625 -5.949219 3.59375 -5.949219 C 3.023438 -5.949219 2.546875 -5.734375 2.171875 -5.304688 C 1.792969 -4.878906 1.605469 -4.234375 1.605469 -3.371094 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-3"> +<path style="stroke:none;" d="M 0.398438 -2.011719 L 1.53125 -2.191406 C 1.59375 -1.738281 1.769531 -1.390625 2.058594 -1.148438 C 2.347656 -0.90625 2.753906 -0.789062 3.273438 -0.789062 C 3.800781 -0.789062 4.1875 -0.894531 4.445312 -1.109375 C 4.699219 -1.320312 4.824219 -1.570312 4.824219 -1.859375 C 4.824219 -2.117188 4.710938 -2.320312 4.488281 -2.46875 C 4.332031 -2.570312 3.941406 -2.699219 3.320312 -2.855469 C 2.480469 -3.066406 1.902344 -3.25 1.578125 -3.40625 C 1.253906 -3.558594 1.007812 -3.773438 0.839844 -4.046875 C 0.671875 -4.320312 0.589844 -4.621094 0.589844 -4.953125 C 0.589844 -5.253906 0.660156 -5.53125 0.796875 -5.785156 C 0.933594 -6.042969 1.121094 -6.253906 1.359375 -6.421875 C 1.535156 -6.554688 1.777344 -6.667969 2.085938 -6.757812 C 2.390625 -6.847656 2.722656 -6.894531 3.070312 -6.894531 C 3.601562 -6.894531 4.066406 -6.816406 4.464844 -6.664062 C 4.867188 -6.511719 5.160156 -6.304688 5.351562 -6.046875 C 5.542969 -5.785156 5.671875 -5.4375 5.746094 -5 L 4.628906 -4.851562 C 4.578125 -5.195312 4.429688 -5.46875 4.1875 -5.664062 C 3.945312 -5.859375 3.597656 -5.953125 3.15625 -5.953125 C 2.628906 -5.953125 2.253906 -5.867188 2.03125 -5.695312 C 1.808594 -5.519531 1.695312 -5.316406 1.695312 -5.085938 C 1.695312 -4.9375 1.742188 -4.804688 1.835938 -4.683594 C 1.929688 -4.5625 2.074219 -4.460938 2.273438 -4.378906 C 2.386719 -4.335938 2.722656 -4.242188 3.28125 -4.085938 C 4.089844 -3.871094 4.652344 -3.695312 4.972656 -3.558594 C 5.292969 -3.421875 5.542969 -3.21875 5.726562 -2.957031 C 5.90625 -2.695312 6 -2.371094 6 -1.980469 C 6 -1.601562 5.886719 -1.242188 5.664062 -0.90625 C 5.441406 -0.570312 5.121094 -0.308594 4.703125 -0.125 C 4.285156 0.0585938 3.8125 0.152344 3.28125 0.152344 C 2.40625 0.152344 1.738281 -0.03125 1.277344 -0.394531 C 0.820312 -0.757812 0.527344 -1.296875 0.398438 -2.011719 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-4"> +<path style="stroke:none;" d="M 3.351562 -1.023438 L 3.515625 -0.0117188 C 3.195312 0.0546875 2.90625 0.0898438 2.652344 0.0898438 C 2.238281 0.0898438 1.917969 0.0234375 1.6875 -0.109375 C 1.460938 -0.238281 1.300781 -0.410156 1.207031 -0.625 C 1.113281 -0.839844 1.066406 -1.289062 1.066406 -1.972656 L 1.066406 -5.851562 L 0.226562 -5.851562 L 0.226562 -6.742188 L 1.066406 -6.742188 L 1.066406 -8.410156 L 2.203125 -9.097656 L 2.203125 -6.742188 L 3.351562 -6.742188 L 3.351562 -5.851562 L 2.203125 -5.851562 L 2.203125 -1.910156 C 2.203125 -1.585938 2.222656 -1.375 2.261719 -1.28125 C 2.304688 -1.1875 2.367188 -1.113281 2.460938 -1.058594 C 2.550781 -1.003906 2.679688 -0.976562 2.851562 -0.976562 C 2.976562 -0.976562 3.144531 -0.992188 3.351562 -1.023438 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-5"> +<path style="stroke:none;" d="M 1.179688 0 L 1.179688 -1.300781 L 2.480469 -1.300781 L 2.480469 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-6"> +<path style="stroke:none;" d="M 1.003906 0 L 1.003906 -9.304688 L 4.511719 -9.304688 C 5.128906 -9.304688 5.601562 -9.277344 5.929688 -9.21875 C 6.386719 -9.140625 6.769531 -8.996094 7.078125 -8.78125 C 7.386719 -8.566406 7.636719 -8.269531 7.824219 -7.882812 C 8.011719 -7.5 8.105469 -7.074219 8.105469 -6.613281 C 8.105469 -5.824219 7.855469 -5.152344 7.351562 -4.605469 C 6.847656 -4.058594 5.9375 -3.78125 4.621094 -3.78125 L 2.234375 -3.78125 L 2.234375 0 Z M 2.234375 -4.882812 L 4.640625 -4.882812 C 5.4375 -4.882812 6 -5.03125 6.335938 -5.324219 C 6.667969 -5.621094 6.835938 -6.039062 6.835938 -6.578125 C 6.835938 -6.964844 6.738281 -7.296875 6.542969 -7.574219 C 6.34375 -7.851562 6.085938 -8.035156 5.765625 -8.125 C 5.558594 -8.179688 5.171875 -8.207031 4.613281 -8.207031 L 2.234375 -8.207031 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-7"> +<path style="stroke:none;" d="M 0.804688 2.597656 L 0.679688 1.523438 C 0.929688 1.589844 1.148438 1.625 1.332031 1.625 C 1.585938 1.625 1.789062 1.582031 1.941406 1.5 C 2.09375 1.414062 2.21875 1.296875 2.316406 1.140625 C 2.390625 1.027344 2.503906 0.746094 2.664062 0.292969 C 2.6875 0.230469 2.722656 0.136719 2.765625 0.0117188 L 0.210938 -6.742188 L 1.441406 -6.742188 L 2.84375 -2.835938 C 3.027344 -2.34375 3.1875 -1.820312 3.332031 -1.277344 C 3.464844 -1.800781 3.621094 -2.3125 3.800781 -2.8125 L 5.242188 -6.742188 L 6.386719 -6.742188 L 3.820312 0.113281 C 3.546875 0.855469 3.332031 1.363281 3.179688 1.644531 C 2.976562 2.019531 2.746094 2.296875 2.480469 2.472656 C 2.21875 2.648438 1.90625 2.734375 1.542969 2.734375 C 1.324219 2.734375 1.078125 2.6875 0.804688 2.597656 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-8"> +<path style="stroke:none;" d="M 0.855469 0 L 0.855469 -9.304688 L 2 -9.304688 L 2 -5.96875 C 2.53125 -6.585938 3.207031 -6.894531 4.019531 -6.894531 C 4.519531 -6.894531 4.953125 -6.796875 5.320312 -6.597656 C 5.6875 -6.402344 5.949219 -6.128906 6.109375 -5.78125 C 6.269531 -5.433594 6.347656 -4.933594 6.347656 -4.273438 L 6.347656 0 L 5.203125 0 L 5.203125 -4.273438 C 5.203125 -4.84375 5.082031 -5.257812 4.832031 -5.519531 C 4.585938 -5.78125 4.234375 -5.910156 3.78125 -5.910156 C 3.445312 -5.910156 3.125 -5.820312 2.828125 -5.644531 C 2.53125 -5.46875 2.316406 -5.234375 2.191406 -4.933594 C 2.0625 -4.632812 2 -4.21875 2 -3.6875 L 2 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-9"> +<path style="stroke:none;" d="M 0.855469 0 L 0.855469 -6.742188 L 1.886719 -6.742188 L 1.886719 -5.78125 C 2.382812 -6.523438 3.09375 -6.894531 4.03125 -6.894531 C 4.4375 -6.894531 4.808594 -6.820312 5.152344 -6.675781 C 5.492188 -6.527344 5.746094 -6.335938 5.914062 -6.101562 C 6.085938 -5.863281 6.203125 -5.582031 6.273438 -5.257812 C 6.3125 -5.046875 6.335938 -4.675781 6.335938 -4.144531 L 6.335938 0 L 5.191406 0 L 5.191406 -4.101562 C 5.191406 -4.566406 5.148438 -4.914062 5.058594 -5.144531 C 4.96875 -5.375 4.8125 -5.558594 4.585938 -5.695312 C 4.359375 -5.835938 4.09375 -5.902344 3.789062 -5.902344 C 3.304688 -5.902344 2.882812 -5.75 2.53125 -5.441406 C 2.175781 -5.132812 2 -4.546875 2 -3.679688 L 2 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-10"> +<path style="stroke:none;" d="M 0.855469 2.582031 L 0.855469 -6.742188 L 1.898438 -6.742188 L 1.898438 -5.867188 C 2.144531 -6.207031 2.421875 -6.464844 2.730469 -6.636719 C 3.039062 -6.808594 3.414062 -6.894531 3.851562 -6.894531 C 4.429688 -6.894531 4.9375 -6.746094 5.375 -6.449219 C 5.816406 -6.152344 6.148438 -5.734375 6.375 -5.195312 C 6.597656 -4.65625 6.710938 -4.066406 6.710938 -3.421875 C 6.710938 -2.730469 6.585938 -2.109375 6.339844 -1.558594 C 6.089844 -1.007812 5.730469 -0.582031 5.257812 -0.289062 C 4.785156 0.00390625 4.289062 0.152344 3.769531 0.152344 C 3.390625 0.152344 3.046875 0.0703125 2.746094 -0.0898438 C 2.441406 -0.25 2.195312 -0.453125 2 -0.699219 L 2 2.582031 Z M 1.890625 -3.332031 C 1.890625 -2.464844 2.066406 -1.824219 2.417969 -1.410156 C 2.769531 -0.996094 3.195312 -0.789062 3.695312 -0.789062 C 4.203125 -0.789062 4.636719 -1 5 -1.429688 C 5.359375 -1.859375 5.542969 -2.527344 5.542969 -3.429688 C 5.542969 -4.289062 5.363281 -4.929688 5.011719 -5.359375 C 4.65625 -5.785156 4.234375 -6 3.746094 -6 C 3.257812 -6 2.828125 -5.769531 2.453125 -5.316406 C 2.078125 -4.859375 1.890625 -4.199219 1.890625 -3.332031 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-11"> +<path style="stroke:none;" d="M 1.910156 0 L 0.851562 0 L 0.851562 -9.304688 L 1.992188 -9.304688 L 1.992188 -5.984375 C 2.476562 -6.589844 3.089844 -6.894531 3.839844 -6.894531 C 4.253906 -6.894531 4.648438 -6.808594 5.019531 -6.644531 C 5.390625 -6.476562 5.691406 -6.242188 5.933594 -5.9375 C 6.171875 -5.636719 6.359375 -5.269531 6.492188 -4.84375 C 6.628906 -4.414062 6.695312 -3.957031 6.695312 -3.472656 C 6.695312 -2.316406 6.410156 -1.425781 5.839844 -0.792969 C 5.269531 -0.164062 4.582031 0.152344 3.78125 0.152344 C 2.988281 0.152344 2.363281 -0.179688 1.910156 -0.84375 Z M 1.898438 -3.421875 C 1.898438 -2.613281 2.007812 -2.027344 2.226562 -1.667969 C 2.585938 -1.082031 3.074219 -0.789062 3.6875 -0.789062 C 4.1875 -0.789062 4.617188 -1.003906 4.984375 -1.4375 C 5.347656 -1.871094 5.527344 -2.519531 5.527344 -3.375 C 5.527344 -4.257812 5.355469 -4.90625 5.003906 -5.324219 C 4.65625 -5.742188 4.234375 -5.953125 3.738281 -5.953125 C 3.238281 -5.953125 2.808594 -5.738281 2.445312 -5.304688 C 2.082031 -4.871094 1.898438 -4.242188 1.898438 -3.421875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-12"> +<path style="stroke:none;" d="M 0.863281 -7.992188 L 0.863281 -9.304688 L 2.007812 -9.304688 L 2.007812 -7.992188 Z M 0.863281 0 L 0.863281 -6.742188 L 2.007812 -6.742188 L 2.007812 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-13"> +<path style="stroke:none;" d="M 5.230469 0 L 5.230469 -0.851562 C 4.804688 -0.183594 4.175781 0.152344 3.34375 0.152344 C 2.808594 0.152344 2.3125 0.00390625 1.863281 -0.292969 C 1.414062 -0.589844 1.0625 -1 0.816406 -1.53125 C 0.570312 -2.0625 0.445312 -2.675781 0.445312 -3.363281 C 0.445312 -4.035156 0.554688 -4.648438 0.78125 -5.195312 C 1.003906 -5.742188 1.339844 -6.164062 1.789062 -6.457031 C 2.238281 -6.75 2.738281 -6.894531 3.292969 -6.894531 C 3.699219 -6.894531 4.0625 -6.808594 4.378906 -6.636719 C 4.695312 -6.464844 4.957031 -6.242188 5.15625 -5.96875 L 5.15625 -9.304688 L 6.289062 -9.304688 L 6.289062 0 Z M 1.617188 -3.363281 C 1.617188 -2.5 1.800781 -1.855469 2.164062 -1.429688 C 2.527344 -1 2.957031 -0.789062 3.453125 -0.789062 C 3.953125 -0.789062 4.375 -0.992188 4.726562 -1.398438 C 5.074219 -1.808594 5.25 -2.429688 5.25 -3.269531 C 5.25 -4.191406 5.070312 -4.867188 4.714844 -5.300781 C 4.359375 -5.730469 3.921875 -5.949219 3.402344 -5.949219 C 2.894531 -5.949219 2.46875 -5.742188 2.128906 -5.324219 C 1.789062 -4.910156 1.617188 -4.257812 1.617188 -3.363281 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-14"> +<path style="stroke:none;" d="M 4.84375 0 L 3.699219 0 L 3.699219 -7.28125 C 3.425781 -7.019531 3.066406 -6.757812 2.617188 -6.492188 C 2.171875 -6.230469 1.769531 -6.035156 1.414062 -5.902344 L 1.414062 -7.007812 C 2.054688 -7.308594 2.613281 -7.671875 3.089844 -8.101562 C 3.570312 -8.527344 3.90625 -8.941406 4.105469 -9.34375 L 4.84375 -9.34375 Z "/> +</symbol> +</g> +<clipPath id="clip1"> + <path d="M 89 21 L 91 21 L 91 221 L 89 221 Z "/> +</clipPath> +<clipPath id="clip2"> + <path d="M 201 21 L 203 21 L 203 221 L 201 221 Z "/> +</clipPath> +<clipPath id="clip3"> + <path d="M 313 21 L 315 21 L 315 221 L 313 221 Z "/> +</clipPath> +<clipPath id="clip4"> + <path d="M 33 180 L 355 180 L 355 182 L 33 182 Z "/> +</clipPath> +<clipPath id="clip5"> + <path d="M 33 146 L 355 146 L 355 148 L 33 148 Z "/> +</clipPath> +<clipPath id="clip6"> + <path d="M 33 120 L 355 120 L 355 122 L 33 122 Z "/> +</clipPath> +<clipPath id="clip7"> + <path d="M 33 95 L 355 95 L 355 97 L 33 97 Z "/> +</clipPath> +<clipPath id="clip8"> + <path d="M 33 61 L 355 61 L 355 63 L 33 63 Z "/> +</clipPath> +</defs> +<g id="surface11"> +<g clip-path="url(#clip1)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 90.226562 220.007812 L 90.226562 21 "/> +</g> +<g clip-path="url(#clip2)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 201.996094 220.007812 L 201.996094 21 "/> +</g> +<g clip-path="url(#clip3)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 313.761719 220.007812 L 313.761719 21 "/> +</g> +<g clip-path="url(#clip4)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 33 180.734375 L 355 180.734375 "/> +</g> +<g clip-path="url(#clip5)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 33 146.960938 L 355 146.960938 "/> +</g> +<g clip-path="url(#clip6)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 33 121.410156 L 355 121.410156 "/> +</g> +<g clip-path="url(#clip7)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 33 95.859375 L 355 95.859375 "/> +</g> +<g clip-path="url(#clip8)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 33 62.082031 L 355 62.082031 "/> +</g> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 49.128906 169 C 49.128906 168.167969 48.800781 167.375 48.214844 166.785156 C 47.625 166.199219 46.832031 165.871094 46 165.871094 C 45.167969 165.871094 44.375 166.199219 43.785156 166.785156 C 43.199219 167.375 42.871094 168.167969 42.871094 169 C 42.871094 169.832031 43.199219 170.625 43.785156 171.214844 C 44.375 171.800781 45.167969 172.128906 46 172.128906 C 46.832031 172.128906 47.625 171.800781 48.214844 171.214844 C 48.800781 170.625 49.128906 169.832031 49.128906 169 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 82.128906 169 C 82.128906 168.167969 81.800781 167.375 81.214844 166.785156 C 80.625 166.199219 79.832031 165.871094 79 165.871094 C 78.167969 165.871094 77.375 166.199219 76.785156 166.785156 C 76.199219 167.375 75.871094 168.167969 75.871094 169 C 75.871094 169.832031 76.199219 170.625 76.785156 171.214844 C 77.375 171.800781 78.167969 172.128906 79 172.128906 C 79.832031 172.128906 80.625 171.800781 81.214844 171.214844 C 81.800781 170.625 82.128906 169.832031 82.128906 169 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 116.128906 167 C 116.128906 166.167969 115.800781 165.375 115.214844 164.785156 C 114.625 164.199219 113.832031 163.871094 113 163.871094 C 112.167969 163.871094 111.375 164.199219 110.785156 164.785156 C 110.199219 165.375 109.871094 166.167969 109.871094 167 C 109.871094 167.832031 110.199219 168.625 110.785156 169.214844 C 111.375 169.800781 112.167969 170.128906 113 170.128906 C 113.832031 170.128906 114.625 169.800781 115.214844 169.214844 C 115.800781 168.625 116.128906 167.832031 116.128906 167 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 150.128906 159 C 150.128906 158.167969 149.800781 157.375 149.214844 156.785156 C 148.625 156.199219 147.832031 155.871094 147 155.871094 C 146.167969 155.871094 145.375 156.199219 144.785156 156.785156 C 144.199219 157.375 143.871094 158.167969 143.871094 159 C 143.871094 159.832031 144.199219 160.625 144.785156 161.214844 C 145.375 161.800781 146.167969 162.128906 147 162.128906 C 147.832031 162.128906 148.625 161.800781 149.214844 161.214844 C 149.800781 160.625 150.128906 159.832031 150.128906 159 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 183.128906 146 C 183.128906 145.167969 182.800781 144.375 182.214844 143.785156 C 181.625 143.199219 180.832031 142.871094 180 142.871094 C 179.167969 142.871094 178.375 143.199219 177.785156 143.785156 C 177.199219 144.375 176.871094 145.167969 176.871094 146 C 176.871094 146.832031 177.199219 147.625 177.785156 148.214844 C 178.375 148.800781 179.167969 149.128906 180 149.128906 C 180.832031 149.128906 181.625 148.800781 182.214844 148.214844 C 182.800781 147.625 183.128906 146.832031 183.128906 146 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 217.128906 128 C 217.128906 127.167969 216.800781 126.375 216.214844 125.785156 C 215.625 125.199219 214.832031 124.871094 214 124.871094 C 213.167969 124.871094 212.375 125.199219 211.785156 125.785156 C 211.199219 126.375 210.871094 127.167969 210.871094 128 C 210.871094 128.832031 211.199219 129.625 211.785156 130.214844 C 212.375 130.800781 213.167969 131.128906 214 131.128906 C 214.832031 131.128906 215.625 130.800781 216.214844 130.214844 C 216.800781 129.625 217.128906 128.832031 217.128906 128 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 251.128906 108 C 251.128906 107.167969 250.800781 106.375 250.214844 105.785156 C 249.625 105.199219 248.832031 104.871094 248 104.871094 C 247.167969 104.871094 246.375 105.199219 245.785156 105.785156 C 245.199219 106.375 244.871094 107.167969 244.871094 108 C 244.871094 108.832031 245.199219 109.625 245.785156 110.214844 C 246.375 110.800781 247.167969 111.128906 248 111.128906 C 248.832031 111.128906 249.625 110.800781 250.214844 110.214844 C 250.800781 109.625 251.128906 108.832031 251.128906 108 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 284.128906 85 C 284.128906 84.167969 283.800781 83.375 283.214844 82.785156 C 282.625 82.199219 281.832031 81.871094 281 81.871094 C 280.167969 81.871094 279.375 82.199219 278.785156 82.785156 C 278.199219 83.375 277.871094 84.167969 277.871094 85 C 277.871094 85.832031 278.199219 86.625 278.785156 87.214844 C 279.375 87.800781 280.167969 88.128906 281 88.128906 C 281.832031 88.128906 282.625 87.800781 283.214844 87.214844 C 283.800781 86.625 284.128906 85.832031 284.128906 85 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 318.128906 59 C 318.128906 58.167969 317.800781 57.375 317.214844 56.785156 C 316.625 56.199219 315.832031 55.871094 315 55.871094 C 314.167969 55.871094 313.375 56.199219 312.785156 56.785156 C 312.199219 57.375 311.871094 58.167969 311.871094 59 C 311.871094 59.832031 312.199219 60.625 312.785156 61.214844 C 313.375 61.800781 314.167969 62.128906 315 62.128906 C 315.832031 62.128906 316.625 61.800781 317.214844 61.214844 C 317.800781 60.625 318.128906 59.832031 318.128906 59 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 352.128906 31 C 352.128906 30.167969 351.800781 29.375 351.214844 28.785156 C 350.625 28.199219 349.832031 27.871094 349 27.871094 C 348.167969 27.871094 347.375 28.199219 346.785156 28.785156 C 346.199219 29.375 345.871094 30.167969 345.871094 31 C 345.871094 31.832031 346.199219 32.625 346.785156 33.214844 C 347.375 33.800781 348.167969 34.128906 349 34.128906 C 349.832031 34.128906 350.625 33.800781 351.214844 33.214844 C 351.800781 32.625 352.128906 31.832031 352.128906 31 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 49.128906 205 C 49.128906 204.167969 48.800781 203.375 48.214844 202.785156 C 47.625 202.199219 46.832031 201.871094 46 201.871094 C 45.167969 201.871094 44.375 202.199219 43.785156 202.785156 C 43.199219 203.375 42.871094 204.167969 42.871094 205 C 42.871094 205.832031 43.199219 206.625 43.785156 207.214844 C 44.375 207.800781 45.167969 208.128906 46 208.128906 C 46.832031 208.128906 47.625 207.800781 48.214844 207.214844 C 48.800781 206.625 49.128906 205.832031 49.128906 205 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 82.128906 199 C 82.128906 198.167969 81.800781 197.375 81.214844 196.785156 C 80.625 196.199219 79.832031 195.871094 79 195.871094 C 78.167969 195.871094 77.375 196.199219 76.785156 196.785156 C 76.199219 197.375 75.871094 198.167969 75.871094 199 C 75.871094 199.832031 76.199219 200.625 76.785156 201.214844 C 77.375 201.800781 78.167969 202.128906 79 202.128906 C 79.832031 202.128906 80.625 201.800781 81.214844 201.214844 C 81.800781 200.625 82.128906 199.832031 82.128906 199 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 116.128906 190 C 116.128906 189.167969 115.800781 188.375 115.214844 187.785156 C 114.625 187.199219 113.832031 186.871094 113 186.871094 C 112.167969 186.871094 111.375 187.199219 110.785156 187.785156 C 110.199219 188.375 109.871094 189.167969 109.871094 190 C 109.871094 190.832031 110.199219 191.625 110.785156 192.214844 C 111.375 192.800781 112.167969 193.128906 113 193.128906 C 113.832031 193.128906 114.625 192.800781 115.214844 192.214844 C 115.800781 191.625 116.128906 190.832031 116.128906 190 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 150.128906 177 C 150.128906 176.167969 149.800781 175.375 149.214844 174.785156 C 148.625 174.199219 147.832031 173.871094 147 173.871094 C 146.167969 173.871094 145.375 174.199219 144.785156 174.785156 C 144.199219 175.375 143.871094 176.167969 143.871094 177 C 143.871094 177.832031 144.199219 178.625 144.785156 179.214844 C 145.375 179.800781 146.167969 180.128906 147 180.128906 C 147.832031 180.128906 148.625 179.800781 149.214844 179.214844 C 149.800781 178.625 150.128906 177.832031 150.128906 177 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 183.128906 159 C 183.128906 158.167969 182.800781 157.375 182.214844 156.785156 C 181.625 156.199219 180.832031 155.871094 180 155.871094 C 179.167969 155.871094 178.375 156.199219 177.785156 156.785156 C 177.199219 157.375 176.871094 158.167969 176.871094 159 C 176.871094 159.832031 177.199219 160.625 177.785156 161.214844 C 178.375 161.800781 179.167969 162.128906 180 162.128906 C 180.832031 162.128906 181.625 161.800781 182.214844 161.214844 C 182.800781 160.625 183.128906 159.832031 183.128906 159 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 217.128906 138 C 217.128906 137.167969 216.800781 136.375 216.214844 135.785156 C 215.625 135.199219 214.832031 134.871094 214 134.871094 C 213.167969 134.871094 212.375 135.199219 211.785156 135.785156 C 211.199219 136.375 210.871094 137.167969 210.871094 138 C 210.871094 138.832031 211.199219 139.625 211.785156 140.214844 C 212.375 140.800781 213.167969 141.128906 214 141.128906 C 214.832031 141.128906 215.625 140.800781 216.214844 140.214844 C 216.800781 139.625 217.128906 138.832031 217.128906 138 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 251.128906 115 C 251.128906 114.167969 250.800781 113.375 250.214844 112.785156 C 249.625 112.199219 248.832031 111.871094 248 111.871094 C 247.167969 111.871094 246.375 112.199219 245.785156 112.785156 C 245.199219 113.375 244.871094 114.167969 244.871094 115 C 244.871094 115.832031 245.199219 116.625 245.785156 117.214844 C 246.375 117.800781 247.167969 118.128906 248 118.128906 C 248.832031 118.128906 249.625 117.800781 250.214844 117.214844 C 250.800781 116.625 251.128906 115.832031 251.128906 115 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 284.128906 91 C 284.128906 90.167969 283.800781 89.375 283.214844 88.785156 C 282.625 88.199219 281.832031 87.871094 281 87.871094 C 280.167969 87.871094 279.375 88.199219 278.785156 88.785156 C 278.199219 89.375 277.871094 90.167969 277.871094 91 C 277.871094 91.832031 278.199219 92.625 278.785156 93.214844 C 279.375 93.800781 280.167969 94.128906 281 94.128906 C 281.832031 94.128906 282.625 93.800781 283.214844 93.214844 C 283.800781 92.625 284.128906 91.832031 284.128906 91 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 318.128906 65 C 318.128906 64.167969 317.800781 63.375 317.214844 62.785156 C 316.625 62.199219 315.832031 61.871094 315 61.871094 C 314.167969 61.871094 313.375 62.199219 312.785156 62.785156 C 312.199219 63.375 311.871094 64.167969 311.871094 65 C 311.871094 65.832031 312.199219 66.625 312.785156 67.214844 C 313.375 67.800781 314.167969 68.128906 315 68.128906 C 315.832031 68.128906 316.625 67.800781 317.214844 67.214844 C 317.800781 66.625 318.128906 65.832031 318.128906 65 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 352.128906 38 C 352.128906 37.167969 351.800781 36.375 351.214844 35.785156 C 350.625 35.199219 349.832031 34.871094 349 34.871094 C 348.167969 34.871094 347.375 35.199219 346.785156 35.785156 C 346.199219 36.375 345.871094 37.167969 345.871094 38 C 345.871094 38.832031 346.199219 39.625 346.785156 40.214844 C 347.375 40.800781 348.167969 41.128906 349 41.128906 C 349.832031 41.128906 350.625 40.800781 351.214844 40.214844 C 351.800781 39.625 352.128906 38.832031 352.128906 38 Z "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 220.007812 L 33 220.007812 "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 220.007812 L 33 21 "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 21 L 355 21 "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 21 L 355 220.007812 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 90.226562 220.007812 L 90.226562 216.785156 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="84.725786" y="232.006944"/> + <use xlink:href="#glyph0-2" x="90.28731" y="232.006944"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 201.996094 220.007812 L 201.996094 216.785156 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="193.49443" y="232.006944"/> + <use xlink:href="#glyph0-2" x="199.055953" y="232.006944"/> + <use xlink:href="#glyph0-2" x="204.617477" y="232.006944"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 313.761719 220.007812 L 313.761719 216.785156 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="302.763074" y="232.006944"/> + <use xlink:href="#glyph0-2" x="308.324597" y="232.006944"/> + <use xlink:href="#glyph0-2" x="313.88612" y="232.006944"/> + <use xlink:href="#glyph0-2" x="319.447644" y="232.006944"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 45.75 220.007812 L 45.75 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 56.578125 220.007812 L 56.578125 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 65.429688 220.007812 L 65.429688 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 72.914062 220.007812 L 72.914062 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 79.394531 220.007812 L 79.394531 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 85.113281 220.007812 L 85.113281 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 123.871094 220.007812 L 123.871094 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 143.554688 220.007812 L 143.554688 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 157.515625 220.007812 L 157.515625 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 168.347656 220.007812 L 168.347656 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 177.199219 220.007812 L 177.199219 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 184.679688 220.007812 L 184.679688 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 191.164062 220.007812 L 191.164062 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 196.878906 220.007812 L 196.878906 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 235.640625 220.007812 L 235.640625 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 255.320312 220.007812 L 255.320312 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 269.285156 220.007812 L 269.285156 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 280.117188 220.007812 L 280.117188 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 288.96875 220.007812 L 288.96875 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 296.449219 220.007812 L 296.449219 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 302.929688 220.007812 L 302.929688 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 308.648438 220.007812 L 308.648438 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 347.410156 220.007812 L 347.410156 218.398438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 180.734375 L 36.21875 180.734375 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-3" x="24" y="183.235493"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 146.960938 L 36.21875 146.960938 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-4" x="24" y="149.45964"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 121.410156 L 36.21875 121.410156 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="19" y="123.909193"/> + <use xlink:href="#glyph0-2" x="24.561523" y="123.909193"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 95.859375 L 36.21875 95.859375 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-3" x="19" y="98.358747"/> + <use xlink:href="#glyph0-2" x="24.561523" y="98.358747"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 62.082031 L 36.21875 62.082031 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-4" x="19" y="64.582894"/> + <use xlink:href="#glyph0-2" x="24.561523" y="64.582894"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 206.285156 L 34.609375 206.285156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 165.789062 L 34.609375 165.789062 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 155.183594 L 34.609375 155.183594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 140.238281 L 34.609375 140.238281 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 134.558594 L 34.609375 134.558594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 129.632812 L 34.609375 129.632812 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 125.292969 L 34.609375 125.292969 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 80.914062 L 34.609375 80.914062 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 70.308594 L 34.609375 70.308594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 33 36.53125 L 34.609375 36.53125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 90.226562 21 L 90.226562 24.21875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 201.996094 21 L 201.996094 24.21875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 313.761719 21 L 313.761719 24.21875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 45.75 21 L 45.75 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 56.578125 21 L 56.578125 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 65.429688 21 L 65.429688 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 72.914062 21 L 72.914062 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 79.394531 21 L 79.394531 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 85.113281 21 L 85.113281 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 123.871094 21 L 123.871094 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 143.554688 21 L 143.554688 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 157.515625 21 L 157.515625 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 168.347656 21 L 168.347656 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 177.199219 21 L 177.199219 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 184.679688 21 L 184.679688 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 191.164062 21 L 191.164062 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 196.878906 21 L 196.878906 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 235.640625 21 L 235.640625 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 255.320312 21 L 255.320312 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 269.285156 21 L 269.285156 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 280.117188 21 L 280.117188 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 288.96875 21 L 288.96875 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 296.449219 21 L 296.449219 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 302.929688 21 L 302.929688 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 308.648438 21 L 308.648438 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 347.410156 21 L 347.410156 22.609375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 180.734375 L 351.78125 180.734375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 146.960938 L 351.78125 146.960938 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 121.410156 L 351.78125 121.410156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 95.859375 L 351.78125 95.859375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 62.082031 L 351.78125 62.082031 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 206.285156 L 353.390625 206.285156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 165.789062 L 353.390625 165.789062 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 155.183594 L 353.390625 155.183594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 140.238281 L 353.390625 140.238281 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 134.558594 L 353.390625 134.558594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 129.632812 L 353.390625 129.632812 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 125.292969 L 353.390625 125.292969 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 80.914062 L 353.390625 80.914062 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 70.308594 L 353.390625 70.308594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 36.53125 L 353.390625 36.53125 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-5" x="172.5" y="251.006944"/> + <use xlink:href="#glyph0-6" x="178.608398" y="251.006944"/> + <use xlink:href="#glyph0-7" x="184.169922" y="251.006944"/> + <use xlink:href="#glyph0-8" x="189.731445" y="251.006944"/> + <use xlink:href="#glyph0-9" x="194.731445" y="251.006944"/> + <use xlink:href="#glyph0-10" x="197.509766" y="251.006944"/> + <use xlink:href="#glyph0-11" x="199.731445" y="251.006944"/> + <use xlink:href="#glyph0-7" x="205.292969" y="251.006944"/> + <use xlink:href="#glyph0-12" x="210.854492" y="251.006944"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph1-1" x="9" y="140.003472"/> + <use xlink:href="#glyph1-2" x="9" y="133.33355"/> + <use xlink:href="#glyph1-3" x="9" y="127.772027"/> + <use xlink:href="#glyph1-4" x="9" y="122.772027"/> + <use xlink:href="#glyph1-5" x="9" y="117.210503"/> + <use xlink:href="#glyph1-6" x="9" y="111.64898"/> + <use xlink:href="#glyph1-7" x="9" y="106.087457"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph2-1" x="122" y="12"/> + <use xlink:href="#glyph2-2" x="130.666016" y="12"/> + <use xlink:href="#glyph2-3" x="137.339844" y="12"/> + <use xlink:href="#glyph2-4" x="147.335938" y="12"/> + <use xlink:href="#glyph2-5" x="154.009766" y="12"/> + <use xlink:href="#glyph2-6" x="156.675781" y="12"/> + <use xlink:href="#glyph2-7" x="159.341797" y="12"/> + <use xlink:href="#glyph2-8" x="166.015625" y="12"/> + <use xlink:href="#glyph2-5" x="169.349609" y="12"/> + <use xlink:href="#glyph2-2" x="172.015625" y="12"/> + <use xlink:href="#glyph2-9" x="178.689453" y="12"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph2-8" x="188" y="12"/> + <use xlink:href="#glyph2-5" x="191.333984" y="12"/> + <use xlink:href="#glyph2-3" x="194" y="12"/> + <use xlink:href="#glyph2-10" x="203.996094" y="12"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph2-2" x="214" y="12"/> + <use xlink:href="#glyph2-11" x="220.673828" y="12"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph2-3" x="227" y="12"/> + <use xlink:href="#glyph2-2" x="236.996094" y="12"/> + <use xlink:href="#glyph2-12" x="243.669922" y="12"/> + <use xlink:href="#glyph2-13" x="250.34375" y="12"/> + <use xlink:href="#glyph2-6" x="257.017578" y="12"/> + <use xlink:href="#glyph2-10" x="259.683594" y="12"/> +</g> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 382.148438 116 C 382.148438 115.164062 381.816406 114.363281 381.226562 113.773438 C 380.636719 113.183594 379.835938 112.851562 379 112.851562 C 378.164062 112.851562 377.363281 113.183594 376.773438 113.773438 C 376.183594 114.363281 375.851562 115.164062 375.851562 116 C 375.851562 116.835938 376.183594 117.636719 376.773438 118.226562 C 377.363281 118.816406 378.164062 119.148438 379 119.148438 C 379.835938 119.148438 380.636719 118.816406 381.226562 118.226562 C 381.816406 117.636719 382.148438 116.835938 382.148438 116 Z "/> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph3-1" x="391" y="120.28418"/> + <use xlink:href="#glyph3-2" x="399.670898" y="120.28418"/> + <use xlink:href="#glyph3-2" x="406.901367" y="120.28418"/> + <use xlink:href="#glyph3-3" x="414.131836" y="120.28418"/> + <use xlink:href="#glyph3-4" x="420.631836" y="120.28418"/> +</g> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph3-5" x="424" y="120.28418"/> +</g> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph3-6" x="428" y="120.28418"/> + <use xlink:href="#glyph3-7" x="436.670898" y="120.28418"/> + <use xlink:href="#glyph3-4" x="443.170898" y="120.28418"/> + <use xlink:href="#glyph3-8" x="446.783203" y="120.28418"/> + <use xlink:href="#glyph3-2" x="454.013672" y="120.28418"/> + <use xlink:href="#glyph3-9" x="461.244141" y="120.28418"/> +</g> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 382.148438 139 C 382.148438 138.164062 381.816406 137.363281 381.226562 136.773438 C 380.636719 136.183594 379.835938 135.851562 379 135.851562 C 378.164062 135.851562 377.363281 136.183594 376.773438 136.773438 C 376.183594 137.363281 375.851562 138.164062 375.851562 139 C 375.851562 139.835938 376.183594 140.636719 376.773438 141.226562 C 377.363281 141.816406 378.164062 142.148438 379 142.148438 C 379.835938 142.148438 380.636719 141.816406 381.226562 141.226562 C 381.816406 140.636719 382.148438 139.835938 382.148438 139 Z "/> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph3-10" x="391" y="143.28418"/> + <use xlink:href="#glyph3-7" x="398.230469" y="143.28418"/> + <use xlink:href="#glyph3-11" x="404.730469" y="143.28418"/> + <use xlink:href="#glyph3-12" x="411.960938" y="143.28418"/> + <use xlink:href="#glyph3-9" x="414.849609" y="143.28418"/> + <use xlink:href="#glyph3-13" x="422.080078" y="143.28418"/> + <use xlink:href="#glyph3-14" x="429.310547" y="143.28418"/> + <use xlink:href="#glyph3-14" x="436.541016" y="143.28418"/> +</g> +</g> +</svg> diff --git a/3rdparty/pybind11/docs/pybind11_vs_boost_python2.png b/3rdparty/pybind11/docs/pybind11_vs_boost_python2.png Binary files differnew file mode 100644 index 00000000..9f17272c --- /dev/null +++ b/3rdparty/pybind11/docs/pybind11_vs_boost_python2.png diff --git a/3rdparty/pybind11/docs/pybind11_vs_boost_python2.svg b/3rdparty/pybind11/docs/pybind11_vs_boost_python2.svg new file mode 100644 index 00000000..5ed6530c --- /dev/null +++ b/3rdparty/pybind11/docs/pybind11_vs_boost_python2.svg @@ -0,0 +1,427 @@ +<?xml version="1.0" encoding="UTF-8"?> +<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="468pt" height="246pt" viewBox="0 0 468 246" version="1.1"> +<defs> +<g> +<symbol overflow="visible" id="glyph0-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph0-1"> +<path style="stroke:none;" d="M 3.726562 0 L 2.847656 0 L 2.847656 -5.601562 C 2.636719 -5.398438 2.359375 -5.195312 2.015625 -4.996094 C 1.671875 -4.792969 1.363281 -4.640625 1.089844 -4.539062 L 1.089844 -5.390625 C 1.582031 -5.621094 2.011719 -5.902344 2.378906 -6.230469 C 2.746094 -6.558594 3.007812 -6.878906 3.160156 -7.1875 L 3.726562 -7.1875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-2"> +<path style="stroke:none;" d="M 0.414062 -3.53125 C 0.414062 -4.375 0.503906 -5.058594 0.675781 -5.574219 C 0.851562 -6.089844 1.109375 -6.488281 1.453125 -6.765625 C 1.796875 -7.046875 2.226562 -7.1875 2.75 -7.1875 C 3.132812 -7.1875 3.46875 -7.109375 3.757812 -6.957031 C 4.046875 -6.800781 4.289062 -6.578125 4.476562 -6.285156 C 4.664062 -5.996094 4.8125 -5.640625 4.921875 -5.222656 C 5.03125 -4.804688 5.082031 -4.238281 5.082031 -3.53125 C 5.082031 -2.691406 4.996094 -2.011719 4.824219 -1.496094 C 4.652344 -0.980469 4.394531 -0.582031 4.050781 -0.300781 C 3.707031 -0.0195312 3.273438 0.121094 2.75 0.121094 C 2.058594 0.121094 1.515625 -0.125 1.125 -0.621094 C 0.652344 -1.214844 0.414062 -2.1875 0.414062 -3.53125 Z M 1.320312 -3.53125 C 1.320312 -2.355469 1.457031 -1.574219 1.730469 -1.183594 C 2.007812 -0.796875 2.34375 -0.601562 2.75 -0.601562 C 3.152344 -0.601562 3.492188 -0.796875 3.765625 -1.1875 C 4.042969 -1.578125 4.179688 -2.359375 4.179688 -3.53125 C 4.179688 -4.710938 4.042969 -5.492188 3.765625 -5.878906 C 3.492188 -6.265625 3.148438 -6.460938 2.738281 -6.460938 C 2.335938 -6.460938 2.011719 -6.289062 1.773438 -5.945312 C 1.46875 -5.511719 1.320312 -4.707031 1.320312 -3.53125 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-3"> +<path style="stroke:none;" d="M 0.820312 0 L 0.820312 -7.15625 L 5.648438 -7.15625 L 5.648438 -6.3125 L 1.765625 -6.3125 L 1.765625 -4.097656 L 5.125 -4.097656 L 5.125 -3.25 L 1.765625 -3.25 L 1.765625 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-4"> +<path style="stroke:none;" d="M 4.058594 0 L 4.058594 -0.761719 C 3.65625 -0.175781 3.105469 0.117188 2.414062 0.117188 C 2.105469 0.117188 1.820312 0.0585938 1.554688 -0.0585938 C 1.289062 -0.175781 1.09375 -0.324219 0.964844 -0.5 C 0.835938 -0.679688 0.746094 -0.894531 0.695312 -1.152344 C 0.65625 -1.324219 0.640625 -1.597656 0.640625 -1.972656 L 0.640625 -5.1875 L 1.519531 -5.1875 L 1.519531 -2.308594 C 1.519531 -1.851562 1.535156 -1.542969 1.570312 -1.382812 C 1.625 -1.152344 1.746094 -0.96875 1.921875 -0.835938 C 2.101562 -0.703125 2.324219 -0.640625 2.585938 -0.640625 C 2.851562 -0.640625 3.097656 -0.707031 3.328125 -0.84375 C 3.5625 -0.976562 3.726562 -1.160156 3.820312 -1.394531 C 3.917969 -1.625 3.964844 -1.964844 3.964844 -2.40625 L 3.964844 -5.1875 L 4.84375 -5.1875 L 4.84375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-5"> +<path style="stroke:none;" d="M 0.660156 0 L 0.660156 -5.1875 L 1.449219 -5.1875 L 1.449219 -4.449219 C 1.832031 -5.019531 2.382812 -5.304688 3.101562 -5.304688 C 3.414062 -5.304688 3.699219 -5.246094 3.960938 -5.132812 C 4.222656 -5.023438 4.421875 -4.875 4.550781 -4.691406 C 4.679688 -4.507812 4.773438 -4.292969 4.824219 -4.042969 C 4.855469 -3.878906 4.875 -3.59375 4.875 -3.1875 L 4.875 0 L 3.992188 0 L 3.992188 -3.15625 C 3.992188 -3.511719 3.960938 -3.78125 3.890625 -3.957031 C 3.824219 -4.132812 3.703125 -4.277344 3.527344 -4.382812 C 3.351562 -4.488281 3.148438 -4.539062 2.914062 -4.539062 C 2.539062 -4.539062 2.21875 -4.421875 1.945312 -4.183594 C 1.671875 -3.945312 1.539062 -3.496094 1.539062 -2.832031 L 1.539062 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-6"> +<path style="stroke:none;" d="M 4.042969 -1.898438 L 4.90625 -1.789062 C 4.8125 -1.191406 4.570312 -0.726562 4.183594 -0.386719 C 3.792969 -0.0507812 3.316406 0.117188 2.75 0.117188 C 2.039062 0.117188 1.46875 -0.113281 1.039062 -0.578125 C 0.605469 -1.042969 0.390625 -1.707031 0.390625 -2.574219 C 0.390625 -3.132812 0.484375 -3.625 0.667969 -4.042969 C 0.855469 -4.460938 1.136719 -4.777344 1.515625 -4.988281 C 1.894531 -5.199219 2.308594 -5.304688 2.753906 -5.304688 C 3.316406 -5.304688 3.777344 -5.160156 4.136719 -4.875 C 4.492188 -4.589844 4.722656 -4.1875 4.824219 -3.664062 L 3.96875 -3.53125 C 3.886719 -3.878906 3.746094 -4.140625 3.539062 -4.316406 C 3.332031 -4.492188 3.082031 -4.578125 2.789062 -4.578125 C 2.34375 -4.578125 1.984375 -4.421875 1.710938 -4.105469 C 1.433594 -3.789062 1.292969 -3.285156 1.292969 -2.597656 C 1.292969 -1.902344 1.425781 -1.394531 1.695312 -1.078125 C 1.960938 -0.761719 2.308594 -0.605469 2.738281 -0.605469 C 3.085938 -0.605469 3.371094 -0.710938 3.601562 -0.921875 C 3.835938 -1.132812 3.980469 -1.460938 4.042969 -1.898438 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-7"> +<path style="stroke:none;" d="M 2.578125 -0.785156 L 2.703125 -0.0078125 C 2.457031 0.0429688 2.234375 0.0703125 2.039062 0.0703125 C 1.722656 0.0703125 1.476562 0.0195312 1.296875 -0.0820312 C 1.121094 -0.183594 1 -0.316406 0.929688 -0.480469 C 0.855469 -0.644531 0.820312 -0.992188 0.820312 -1.519531 L 0.820312 -4.5 L 0.175781 -4.5 L 0.175781 -5.1875 L 0.820312 -5.1875 L 0.820312 -6.46875 L 1.695312 -6.996094 L 1.695312 -5.1875 L 2.578125 -5.1875 L 2.578125 -4.5 L 1.695312 -4.5 L 1.695312 -1.46875 C 1.695312 -1.21875 1.710938 -1.058594 1.742188 -0.984375 C 1.773438 -0.914062 1.820312 -0.859375 1.890625 -0.816406 C 1.960938 -0.773438 2.0625 -0.75 2.191406 -0.75 C 2.289062 -0.75 2.417969 -0.761719 2.578125 -0.785156 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-8"> +<path style="stroke:none;" d="M 0.664062 -6.148438 L 0.664062 -7.15625 L 1.542969 -7.15625 L 1.542969 -6.148438 Z M 0.664062 0 L 0.664062 -5.1875 L 1.542969 -5.1875 L 1.542969 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-9"> +<path style="stroke:none;" d="M 0.332031 -2.59375 C 0.332031 -3.554688 0.597656 -4.265625 1.132812 -4.726562 C 1.578125 -5.109375 2.121094 -5.304688 2.765625 -5.304688 C 3.476562 -5.304688 4.058594 -5.070312 4.511719 -4.601562 C 4.964844 -4.132812 5.191406 -3.488281 5.191406 -2.664062 C 5.191406 -2 5.089844 -1.472656 4.890625 -1.089844 C 4.691406 -0.707031 4.398438 -0.410156 4.015625 -0.199219 C 3.632812 0.0117188 3.214844 0.117188 2.765625 0.117188 C 2.039062 0.117188 1.449219 -0.117188 1.003906 -0.582031 C 0.554688 -1.046875 0.332031 -1.71875 0.332031 -2.59375 Z M 1.234375 -2.59375 C 1.234375 -1.929688 1.378906 -1.429688 1.671875 -1.101562 C 1.960938 -0.769531 2.324219 -0.605469 2.765625 -0.605469 C 3.199219 -0.605469 3.5625 -0.773438 3.851562 -1.101562 C 4.140625 -1.433594 4.289062 -1.941406 4.289062 -2.621094 C 4.289062 -3.261719 4.140625 -3.75 3.851562 -4.078125 C 3.558594 -4.410156 3.195312 -4.574219 2.765625 -4.574219 C 2.324219 -4.574219 1.960938 -4.410156 1.671875 -4.082031 C 1.382812 -3.753906 1.234375 -3.257812 1.234375 -2.59375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph0-10"> +<path style="stroke:none;" d="M 0.308594 -1.546875 L 1.175781 -1.683594 C 1.226562 -1.335938 1.363281 -1.070312 1.585938 -0.882812 C 1.808594 -0.699219 2.117188 -0.605469 2.519531 -0.605469 C 2.921875 -0.605469 3.222656 -0.6875 3.417969 -0.851562 C 3.613281 -1.015625 3.710938 -1.210938 3.710938 -1.429688 C 3.710938 -1.628906 3.625 -1.785156 3.453125 -1.898438 C 3.332031 -1.976562 3.03125 -2.078125 2.554688 -2.195312 C 1.910156 -2.359375 1.460938 -2.5 1.214844 -2.621094 C 0.964844 -2.738281 0.777344 -2.902344 0.648438 -3.113281 C 0.519531 -3.324219 0.453125 -3.554688 0.453125 -3.808594 C 0.453125 -4.039062 0.507812 -4.253906 0.613281 -4.449219 C 0.71875 -4.648438 0.863281 -4.8125 1.046875 -4.941406 C 1.183594 -5.042969 1.367188 -5.128906 1.605469 -5.199219 C 1.839844 -5.269531 2.09375 -5.304688 2.363281 -5.304688 C 2.769531 -5.304688 3.128906 -5.242188 3.433594 -5.125 C 3.742188 -5.007812 3.96875 -4.851562 4.117188 -4.652344 C 4.261719 -4.453125 4.363281 -4.183594 4.417969 -3.847656 L 3.558594 -3.730469 C 3.519531 -3.996094 3.40625 -4.207031 3.21875 -4.355469 C 3.03125 -4.503906 2.769531 -4.578125 2.425781 -4.578125 C 2.023438 -4.578125 1.734375 -4.511719 1.5625 -4.378906 C 1.390625 -4.246094 1.304688 -4.089844 1.304688 -3.910156 C 1.304688 -3.796875 1.339844 -3.695312 1.410156 -3.601562 C 1.484375 -3.507812 1.59375 -3.429688 1.75 -3.367188 C 1.835938 -3.335938 2.09375 -3.261719 2.523438 -3.144531 C 3.144531 -2.976562 3.578125 -2.84375 3.824219 -2.738281 C 4.070312 -2.632812 4.265625 -2.476562 4.40625 -2.273438 C 4.546875 -2.074219 4.613281 -1.824219 4.613281 -1.523438 C 4.613281 -1.230469 4.527344 -0.953125 4.359375 -0.695312 C 4.1875 -0.4375 3.941406 -0.238281 3.617188 -0.09375 C 3.296875 0.046875 2.929688 0.117188 2.523438 0.117188 C 1.851562 0.117188 1.335938 -0.0234375 0.984375 -0.304688 C 0.632812 -0.582031 0.40625 -0.996094 0.308594 -1.546875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph1-1"> +<path style="stroke:none;" d="M 0.375 -1.6875 L 1.203125 -1.757812 C 1.265625 -1.351562 1.410156 -1.050781 1.632812 -0.847656 C 1.855469 -0.644531 2.125 -0.539062 2.445312 -0.539062 C 2.824219 -0.539062 3.148438 -0.683594 3.410156 -0.972656 C 3.671875 -1.257812 3.804688 -1.640625 3.804688 -2.113281 C 3.804688 -2.566406 3.679688 -2.921875 3.425781 -3.179688 C 3.171875 -3.441406 2.839844 -3.574219 2.429688 -3.574219 C 2.175781 -3.574219 1.945312 -3.515625 1.742188 -3.398438 C 1.535156 -3.28125 1.375 -3.132812 1.257812 -2.949219 L 0.515625 -3.046875 L 1.136719 -6.355469 L 4.34375 -6.355469 L 4.34375 -5.597656 L 1.769531 -5.597656 L 1.421875 -3.867188 C 1.808594 -4.136719 2.214844 -4.273438 2.640625 -4.273438 C 3.203125 -4.273438 3.679688 -4.078125 4.066406 -3.6875 C 4.453125 -3.296875 4.644531 -2.796875 4.644531 -2.183594 C 4.644531 -1.601562 4.476562 -1.097656 4.136719 -0.671875 C 3.722656 -0.152344 3.15625 0.109375 2.445312 0.109375 C 1.859375 0.109375 1.378906 -0.0546875 1.007812 -0.382812 C 0.636719 -0.710938 0.425781 -1.144531 0.375 -1.6875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-2"> +<path style="stroke:none;" d="M 4.476562 -4.863281 L 3.691406 -4.804688 C 3.621094 -5.113281 3.523438 -5.339844 3.390625 -5.480469 C 3.179688 -5.707031 2.914062 -5.820312 2.601562 -5.820312 C 2.351562 -5.820312 2.128906 -5.75 1.9375 -5.609375 C 1.6875 -5.425781 1.492188 -5.160156 1.347656 -4.8125 C 1.203125 -4.464844 1.132812 -3.96875 1.125 -3.320312 C 1.316406 -3.613281 1.546875 -3.828125 1.824219 -3.96875 C 2.097656 -4.109375 2.386719 -4.179688 2.6875 -4.179688 C 3.214844 -4.179688 3.664062 -3.984375 4.035156 -3.597656 C 4.40625 -3.210938 4.59375 -2.707031 4.59375 -2.09375 C 4.59375 -1.6875 4.503906 -1.3125 4.332031 -0.964844 C 4.15625 -0.617188 3.917969 -0.351562 3.613281 -0.167969 C 3.308594 0.015625 2.960938 0.109375 2.574219 0.109375 C 1.914062 0.109375 1.378906 -0.132812 0.960938 -0.617188 C 0.546875 -1.101562 0.339844 -1.902344 0.339844 -3.015625 C 0.339844 -4.261719 0.570312 -5.164062 1.027344 -5.730469 C 1.429688 -6.222656 1.96875 -6.46875 2.648438 -6.46875 C 3.15625 -6.46875 3.570312 -6.328125 3.894531 -6.042969 C 4.21875 -5.757812 4.414062 -5.367188 4.476562 -4.863281 Z M 1.25 -2.085938 C 1.25 -1.8125 1.304688 -1.554688 1.421875 -1.304688 C 1.539062 -1.054688 1.699219 -0.867188 1.90625 -0.734375 C 2.113281 -0.605469 2.332031 -0.539062 2.5625 -0.539062 C 2.894531 -0.539062 3.183594 -0.675781 3.421875 -0.945312 C 3.664062 -1.214844 3.785156 -1.582031 3.785156 -2.042969 C 3.785156 -2.488281 3.664062 -2.839844 3.429688 -3.097656 C 3.191406 -3.351562 2.890625 -3.480469 2.53125 -3.480469 C 2.171875 -3.480469 1.871094 -3.351562 1.621094 -3.097656 C 1.371094 -2.839844 1.25 -2.503906 1.25 -2.085938 Z "/> +</symbol> +<symbol overflow="visible" id="glyph1-3"> +<path style="stroke:none;" d="M 0.425781 -5.597656 L 0.425781 -6.359375 L 4.597656 -6.359375 L 4.597656 -5.742188 C 4.1875 -5.304688 3.78125 -4.726562 3.378906 -4.003906 C 2.976562 -3.28125 2.664062 -2.535156 2.445312 -1.769531 C 2.285156 -1.230469 2.183594 -0.640625 2.140625 0 L 1.328125 0 C 1.335938 -0.507812 1.4375 -1.117188 1.625 -1.835938 C 1.816406 -2.554688 2.089844 -3.246094 2.445312 -3.914062 C 2.800781 -4.578125 3.179688 -5.140625 3.582031 -5.597656 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph2-1"> +<path style="stroke:none;" d="M 0 -0.734375 L -7.15625 -0.734375 L -7.15625 -3.417969 C -7.15625 -3.964844 -7.085938 -4.402344 -6.941406 -4.734375 C -6.796875 -5.0625 -6.574219 -5.324219 -6.273438 -5.511719 C -5.972656 -5.699219 -5.65625 -5.789062 -5.328125 -5.789062 C -5.023438 -5.789062 -4.734375 -5.707031 -4.460938 -5.542969 C -4.191406 -5.375 -3.976562 -5.125 -3.808594 -4.789062 C -3.679688 -5.222656 -3.464844 -5.554688 -3.160156 -5.789062 C -2.851562 -6.023438 -2.492188 -6.136719 -2.074219 -6.136719 C -1.738281 -6.136719 -1.429688 -6.066406 -1.140625 -5.925781 C -0.851562 -5.785156 -0.628906 -5.609375 -0.472656 -5.398438 C -0.316406 -5.191406 -0.199219 -4.929688 -0.121094 -4.617188 C -0.0390625 -4.304688 0 -3.917969 0 -3.460938 Z M -4.148438 -1.679688 L -4.148438 -3.226562 C -4.148438 -3.648438 -4.179688 -3.949219 -4.234375 -4.132812 C -4.304688 -4.371094 -4.421875 -4.554688 -4.589844 -4.675781 C -4.757812 -4.796875 -4.964844 -4.859375 -5.214844 -4.859375 C -5.453125 -4.859375 -5.660156 -4.800781 -5.84375 -4.6875 C -6.023438 -4.574219 -6.148438 -4.410156 -6.214844 -4.199219 C -6.28125 -3.988281 -6.3125 -3.625 -6.3125 -3.109375 L -6.3125 -1.679688 Z M -0.84375 -1.679688 L -0.84375 -3.460938 C -0.84375 -3.765625 -0.855469 -3.984375 -0.878906 -4.105469 C -0.917969 -4.324219 -0.984375 -4.507812 -1.074219 -4.652344 C -1.164062 -4.800781 -1.296875 -4.921875 -1.472656 -5.015625 C -1.648438 -5.109375 -1.847656 -5.15625 -2.074219 -5.15625 C -2.34375 -5.15625 -2.574219 -5.085938 -2.769531 -4.953125 C -2.96875 -4.816406 -3.105469 -4.625 -3.1875 -4.382812 C -3.265625 -4.140625 -3.304688 -3.789062 -3.304688 -3.335938 L -3.304688 -1.679688 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-2"> +<path style="stroke:none;" d="M 1.996094 -0.621094 L 1.171875 -0.523438 C 1.222656 -0.714844 1.25 -0.882812 1.25 -1.023438 C 1.25 -1.21875 1.21875 -1.375 1.152344 -1.492188 C 1.085938 -1.609375 0.996094 -1.707031 0.878906 -1.78125 C 0.789062 -1.835938 0.574219 -1.925781 0.226562 -2.050781 C 0.175781 -2.066406 0.105469 -2.09375 0.0078125 -2.128906 L -5.1875 -0.160156 L -5.1875 -1.109375 L -2.183594 -2.1875 C -1.800781 -2.328125 -1.402344 -2.453125 -0.980469 -2.5625 C -1.382812 -2.664062 -1.777344 -2.785156 -2.164062 -2.925781 L -5.1875 -4.03125 L -5.1875 -4.914062 L 0.0859375 -2.9375 C 0.65625 -2.726562 1.050781 -2.5625 1.265625 -2.445312 C 1.554688 -2.289062 1.765625 -2.109375 1.902344 -1.910156 C 2.039062 -1.707031 2.105469 -1.464844 2.105469 -1.1875 C 2.105469 -1.015625 2.070312 -0.828125 1.996094 -0.621094 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-3"> +<path style="stroke:none;" d="M -0.785156 -2.578125 L -0.0078125 -2.703125 C 0.0429688 -2.457031 0.0703125 -2.234375 0.0703125 -2.039062 C 0.0703125 -1.722656 0.0195312 -1.476562 -0.0820312 -1.296875 C -0.183594 -1.121094 -0.316406 -1 -0.480469 -0.929688 C -0.644531 -0.855469 -0.992188 -0.820312 -1.519531 -0.820312 L -4.5 -0.820312 L -4.5 -0.175781 L -5.1875 -0.175781 L -5.1875 -0.820312 L -6.46875 -0.820312 L -6.996094 -1.695312 L -5.1875 -1.695312 L -5.1875 -2.578125 L -4.5 -2.578125 L -4.5 -1.695312 L -1.46875 -1.695312 C -1.21875 -1.695312 -1.058594 -1.710938 -0.984375 -1.742188 C -0.914062 -1.773438 -0.859375 -1.820312 -0.816406 -1.890625 C -0.773438 -1.960938 -0.75 -2.0625 -0.75 -2.191406 C -0.75 -2.289062 -0.761719 -2.417969 -0.785156 -2.578125 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-4"> +<path style="stroke:none;" d="M -1.671875 -4.210938 L -1.558594 -5.117188 C -1.027344 -4.972656 -0.617188 -4.707031 -0.320312 -4.320312 C -0.0273438 -3.933594 0.117188 -3.4375 0.117188 -2.835938 C 0.117188 -2.078125 -0.117188 -1.476562 -0.582031 -1.03125 C -1.050781 -0.585938 -1.707031 -0.367188 -2.546875 -0.367188 C -3.421875 -0.367188 -4.097656 -0.589844 -4.578125 -1.039062 C -5.0625 -1.488281 -5.304688 -2.070312 -5.304688 -2.789062 C -5.304688 -3.480469 -5.066406 -4.046875 -4.59375 -4.488281 C -4.121094 -4.925781 -3.457031 -5.148438 -2.601562 -5.148438 C -2.550781 -5.148438 -2.472656 -5.144531 -2.367188 -5.140625 L -2.367188 -1.273438 C -1.796875 -1.304688 -1.363281 -1.46875 -1.058594 -1.757812 C -0.757812 -2.046875 -0.605469 -2.410156 -0.605469 -2.84375 C -0.605469 -3.164062 -0.691406 -3.4375 -0.859375 -3.667969 C -1.027344 -3.894531 -1.296875 -4.074219 -1.671875 -4.210938 Z M -3.089844 -1.324219 L -3.089844 -4.21875 C -3.527344 -4.179688 -3.855469 -4.070312 -4.070312 -3.886719 C -4.410156 -3.605469 -4.578125 -3.242188 -4.578125 -2.796875 C -4.578125 -2.394531 -4.445312 -2.054688 -4.175781 -1.78125 C -3.90625 -1.503906 -3.542969 -1.351562 -3.089844 -1.324219 Z "/> +</symbol> +<symbol overflow="visible" id="glyph2-5"> +<path style="stroke:none;" d="M -1.546875 -0.308594 L -1.683594 -1.175781 C -1.335938 -1.226562 -1.070312 -1.363281 -0.882812 -1.585938 C -0.699219 -1.808594 -0.605469 -2.117188 -0.605469 -2.519531 C -0.605469 -2.921875 -0.6875 -3.222656 -0.851562 -3.417969 C -1.015625 -3.613281 -1.210938 -3.710938 -1.429688 -3.710938 C -1.628906 -3.710938 -1.785156 -3.625 -1.898438 -3.453125 C -1.976562 -3.332031 -2.078125 -3.03125 -2.195312 -2.554688 C -2.359375 -1.910156 -2.5 -1.460938 -2.621094 -1.214844 C -2.738281 -0.964844 -2.902344 -0.777344 -3.113281 -0.648438 C -3.324219 -0.519531 -3.554688 -0.453125 -3.808594 -0.453125 C -4.039062 -0.453125 -4.253906 -0.507812 -4.449219 -0.613281 C -4.648438 -0.71875 -4.8125 -0.863281 -4.941406 -1.046875 C -5.042969 -1.183594 -5.128906 -1.367188 -5.199219 -1.605469 C -5.269531 -1.839844 -5.304688 -2.09375 -5.304688 -2.363281 C -5.304688 -2.769531 -5.242188 -3.128906 -5.125 -3.433594 C -5.007812 -3.742188 -4.851562 -3.96875 -4.652344 -4.117188 C -4.453125 -4.261719 -4.183594 -4.363281 -3.847656 -4.417969 L -3.730469 -3.558594 C -3.996094 -3.519531 -4.207031 -3.40625 -4.355469 -3.21875 C -4.503906 -3.03125 -4.578125 -2.769531 -4.578125 -2.425781 C -4.578125 -2.023438 -4.511719 -1.734375 -4.378906 -1.5625 C -4.246094 -1.390625 -4.089844 -1.304688 -3.910156 -1.304688 C -3.796875 -1.304688 -3.695312 -1.339844 -3.601562 -1.410156 C -3.507812 -1.484375 -3.429688 -1.59375 -3.367188 -1.75 C -3.335938 -1.835938 -3.261719 -2.09375 -3.144531 -2.523438 C -2.976562 -3.144531 -2.84375 -3.578125 -2.738281 -3.824219 C -2.632812 -4.070312 -2.476562 -4.265625 -2.273438 -4.40625 C -2.074219 -4.546875 -1.824219 -4.613281 -1.523438 -4.613281 C -1.230469 -4.613281 -0.953125 -4.527344 -0.695312 -4.359375 C -0.4375 -4.1875 -0.238281 -3.941406 -0.09375 -3.617188 C 0.046875 -3.296875 0.117188 -2.929688 0.117188 -2.523438 C 0.117188 -1.851562 -0.0234375 -1.335938 -0.304688 -0.984375 C -0.582031 -0.632812 -0.996094 -0.40625 -1.546875 -0.308594 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph3-1"> +<path style="stroke:none;" d="M 0.984375 0 L 0.984375 -8.589844 L 6.78125 -8.589844 L 6.78125 -7.578125 L 2.121094 -7.578125 L 2.121094 -4.914062 L 6.152344 -4.914062 L 6.152344 -3.902344 L 2.121094 -3.902344 L 2.121094 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-2"> +<path style="stroke:none;" d="M 0.796875 -7.375 L 0.796875 -8.589844 L 1.851562 -8.589844 L 1.851562 -7.375 Z M 0.796875 0 L 0.796875 -6.222656 L 1.851562 -6.222656 L 1.851562 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-3"> +<path style="stroke:none;" d="M 0.765625 0 L 0.765625 -8.589844 L 1.820312 -8.589844 L 1.820312 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-4"> +<path style="stroke:none;" d="M 5.050781 -2.003906 L 6.140625 -1.867188 C 5.96875 -1.230469 5.648438 -0.738281 5.1875 -0.386719 C 4.722656 -0.0351562 4.125 0.140625 3.40625 0.140625 C 2.496094 0.140625 1.773438 -0.140625 1.238281 -0.699219 C 0.707031 -1.261719 0.4375 -2.046875 0.4375 -3.058594 C 0.4375 -4.105469 0.710938 -4.917969 1.25 -5.496094 C 1.789062 -6.074219 2.484375 -6.363281 3.34375 -6.363281 C 4.175781 -6.363281 4.859375 -6.078125 5.382812 -5.515625 C 5.910156 -4.949219 6.175781 -4.148438 6.175781 -3.125 C 6.175781 -3.0625 6.171875 -2.96875 6.171875 -2.84375 L 1.53125 -2.84375 C 1.570312 -2.160156 1.761719 -1.632812 2.109375 -1.273438 C 2.457031 -0.910156 2.890625 -0.726562 3.410156 -0.726562 C 3.796875 -0.726562 4.125 -0.828125 4.398438 -1.03125 C 4.671875 -1.234375 4.890625 -1.558594 5.050781 -2.003906 Z M 1.585938 -3.710938 L 5.0625 -3.710938 C 5.015625 -4.234375 4.882812 -4.625 4.664062 -4.886719 C 4.328125 -5.292969 3.890625 -5.496094 3.359375 -5.496094 C 2.875 -5.496094 2.464844 -5.335938 2.136719 -5.007812 C 1.804688 -4.683594 1.625 -4.25 1.585938 -3.710938 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-5"> +<path style="stroke:none;" d="M 0.367188 -1.859375 L 1.414062 -2.023438 C 1.472656 -1.605469 1.632812 -1.28125 1.902344 -1.0625 C 2.167969 -0.839844 2.542969 -0.726562 3.023438 -0.726562 C 3.507812 -0.726562 3.867188 -0.824219 4.101562 -1.023438 C 4.335938 -1.21875 4.453125 -1.453125 4.453125 -1.71875 C 4.453125 -1.957031 4.351562 -2.140625 4.140625 -2.28125 C 3.996094 -2.375 3.640625 -2.492188 3.0625 -2.636719 C 2.289062 -2.832031 1.753906 -3 1.457031 -3.144531 C 1.15625 -3.285156 0.929688 -3.484375 0.777344 -3.734375 C 0.621094 -3.988281 0.546875 -4.265625 0.546875 -4.570312 C 0.546875 -4.847656 0.609375 -5.105469 0.734375 -5.339844 C 0.863281 -5.578125 1.035156 -5.773438 1.253906 -5.929688 C 1.417969 -6.050781 1.640625 -6.152344 1.925781 -6.238281 C 2.207031 -6.320312 2.511719 -6.363281 2.835938 -6.363281 C 3.324219 -6.363281 3.753906 -6.292969 4.121094 -6.152344 C 4.492188 -6.011719 4.765625 -5.820312 4.9375 -5.582031 C 5.113281 -5.339844 5.234375 -5.019531 5.304688 -4.617188 L 4.273438 -4.476562 C 4.226562 -4.796875 4.089844 -5.046875 3.863281 -5.226562 C 3.640625 -5.40625 3.320312 -5.496094 2.914062 -5.496094 C 2.429688 -5.496094 2.082031 -5.414062 1.875 -5.257812 C 1.667969 -5.097656 1.5625 -4.90625 1.5625 -4.695312 C 1.5625 -4.558594 1.609375 -4.433594 1.695312 -4.324219 C 1.78125 -4.210938 1.914062 -4.117188 2.097656 -4.042969 C 2.203125 -4.003906 2.515625 -3.914062 3.03125 -3.773438 C 3.777344 -3.574219 4.296875 -3.410156 4.589844 -3.285156 C 4.886719 -3.15625 5.117188 -2.972656 5.285156 -2.730469 C 5.453125 -2.488281 5.539062 -2.1875 5.539062 -1.828125 C 5.539062 -1.476562 5.433594 -1.144531 5.230469 -0.835938 C 5.023438 -0.523438 4.726562 -0.285156 4.34375 -0.113281 C 3.957031 0.0546875 3.515625 0.140625 3.03125 0.140625 C 2.222656 0.140625 1.605469 -0.0273438 1.179688 -0.363281 C 0.757812 -0.699219 0.484375 -1.195312 0.367188 -1.859375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-6"> +<path style="stroke:none;" d="M 0.234375 0 L 0.234375 -0.855469 L 4.195312 -5.402344 C 3.746094 -5.378906 3.351562 -5.367188 3.007812 -5.367188 L 0.46875 -5.367188 L 0.46875 -6.222656 L 5.554688 -6.222656 L 5.554688 -5.523438 L 2.1875 -1.578125 L 1.535156 -0.855469 C 2.007812 -0.890625 2.453125 -0.90625 2.867188 -0.90625 L 5.742188 -0.90625 L 5.742188 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-7"> +<path style="stroke:none;" d="M 0.398438 -3.109375 C 0.398438 -4.261719 0.71875 -5.117188 1.359375 -5.671875 C 1.894531 -6.132812 2.546875 -6.363281 3.316406 -6.363281 C 4.171875 -6.363281 4.871094 -6.082031 5.414062 -5.523438 C 5.957031 -4.960938 6.226562 -4.1875 6.226562 -3.199219 C 6.226562 -2.398438 6.109375 -1.769531 5.867188 -1.308594 C 5.628906 -0.851562 5.277344 -0.492188 4.820312 -0.242188 C 4.359375 0.0117188 3.859375 0.140625 3.316406 0.140625 C 2.445312 0.140625 1.742188 -0.140625 1.203125 -0.695312 C 0.667969 -1.253906 0.398438 -2.0625 0.398438 -3.109375 Z M 1.484375 -3.109375 C 1.484375 -2.3125 1.65625 -1.71875 2.003906 -1.320312 C 2.351562 -0.925781 2.789062 -0.726562 3.316406 -0.726562 C 3.839844 -0.726562 4.273438 -0.925781 4.625 -1.324219 C 4.972656 -1.722656 5.144531 -2.328125 5.144531 -3.148438 C 5.144531 -3.917969 4.96875 -4.5 4.621094 -4.894531 C 4.269531 -5.292969 3.835938 -5.492188 3.316406 -5.492188 C 2.789062 -5.492188 2.351562 -5.292969 2.003906 -4.898438 C 1.65625 -4.503906 1.484375 -3.90625 1.484375 -3.109375 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-8"> +<path style="stroke:none;" d="M 1.042969 0 L 1.042969 -5.402344 L 0.109375 -5.402344 L 0.109375 -6.222656 L 1.042969 -6.222656 L 1.042969 -6.882812 C 1.042969 -7.300781 1.078125 -7.613281 1.15625 -7.816406 C 1.257812 -8.089844 1.433594 -8.3125 1.691406 -8.480469 C 1.945312 -8.652344 2.304688 -8.734375 2.765625 -8.734375 C 3.0625 -8.734375 3.390625 -8.703125 3.75 -8.632812 L 3.59375 -7.710938 C 3.375 -7.75 3.164062 -7.769531 2.96875 -7.769531 C 2.648438 -7.769531 2.421875 -7.703125 2.289062 -7.5625 C 2.15625 -7.425781 2.09375 -7.171875 2.09375 -6.796875 L 2.09375 -6.222656 L 3.304688 -6.222656 L 3.304688 -5.402344 L 2.09375 -5.402344 L 2.09375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-9"> +<path style="stroke:none;" d="M 0.789062 0 L 0.789062 -6.222656 L 1.734375 -6.222656 L 1.734375 -5.351562 C 1.929688 -5.65625 2.1875 -5.898438 2.515625 -6.085938 C 2.839844 -6.269531 3.207031 -6.363281 3.621094 -6.363281 C 4.082031 -6.363281 4.460938 -6.265625 4.753906 -6.078125 C 5.050781 -5.886719 5.257812 -5.617188 5.378906 -5.273438 C 5.871094 -6 6.511719 -6.363281 7.300781 -6.363281 C 7.917969 -6.363281 8.390625 -6.191406 8.726562 -5.851562 C 9.058594 -5.507812 9.222656 -4.984375 9.222656 -4.273438 L 9.222656 0 L 8.171875 0 L 8.171875 -3.921875 C 8.171875 -4.34375 8.140625 -4.644531 8.070312 -4.832031 C 8.003906 -5.015625 7.878906 -5.164062 7.699219 -5.28125 C 7.519531 -5.394531 7.308594 -5.449219 7.066406 -5.449219 C 6.628906 -5.449219 6.265625 -5.304688 5.976562 -5.011719 C 5.6875 -4.722656 5.542969 -4.257812 5.542969 -3.617188 L 5.542969 0 L 4.488281 0 L 4.488281 -4.042969 C 4.488281 -4.511719 4.402344 -4.863281 4.230469 -5.097656 C 4.058594 -5.332031 3.777344 -5.449219 3.386719 -5.449219 C 3.089844 -5.449219 2.816406 -5.371094 2.5625 -5.214844 C 2.3125 -5.058594 2.128906 -4.828125 2.015625 -4.53125 C 1.902344 -4.230469 1.84375 -3.796875 1.84375 -3.226562 L 1.84375 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-10"> +<path style="stroke:none;" d="M 4.828125 0 L 4.828125 -0.785156 C 4.433594 -0.167969 3.851562 0.140625 3.085938 0.140625 C 2.589844 0.140625 2.136719 0.00390625 1.71875 -0.269531 C 1.304688 -0.542969 0.980469 -0.925781 0.753906 -1.414062 C 0.523438 -1.90625 0.410156 -2.46875 0.410156 -3.105469 C 0.410156 -3.726562 0.515625 -4.289062 0.71875 -4.796875 C 0.925781 -5.300781 1.238281 -5.6875 1.652344 -5.960938 C 2.066406 -6.230469 2.53125 -6.363281 3.039062 -6.363281 C 3.414062 -6.363281 3.75 -6.285156 4.042969 -6.125 C 4.335938 -5.96875 4.574219 -5.761719 4.757812 -5.507812 L 4.757812 -8.589844 L 5.804688 -8.589844 L 5.804688 0 Z M 1.492188 -3.105469 C 1.492188 -2.308594 1.664062 -1.710938 2 -1.320312 C 2.335938 -0.925781 2.730469 -0.726562 3.1875 -0.726562 C 3.648438 -0.726562 4.039062 -0.914062 4.363281 -1.292969 C 4.683594 -1.667969 4.84375 -2.242188 4.84375 -3.015625 C 4.84375 -3.867188 4.679688 -4.492188 4.351562 -4.890625 C 4.023438 -5.289062 3.621094 -5.492188 3.140625 -5.492188 C 2.671875 -5.492188 2.28125 -5.296875 1.964844 -4.914062 C 1.652344 -4.53125 1.492188 -3.929688 1.492188 -3.105469 Z "/> +</symbol> +<symbol overflow="visible" id="glyph3-11"> +<path style="stroke:none;" d="M 4.867188 0 L 4.867188 -0.914062 C 4.382812 -0.210938 3.726562 0.140625 2.894531 0.140625 C 2.527344 0.140625 2.183594 0.0703125 1.867188 -0.0703125 C 1.546875 -0.210938 1.3125 -0.386719 1.15625 -0.601562 C 1.003906 -0.8125 0.894531 -1.074219 0.832031 -1.382812 C 0.789062 -1.589844 0.765625 -1.917969 0.765625 -2.367188 L 0.765625 -6.222656 L 1.820312 -6.222656 L 1.820312 -2.773438 C 1.820312 -2.222656 1.84375 -1.851562 1.886719 -1.65625 C 1.953125 -1.378906 2.09375 -1.164062 2.308594 -1.003906 C 2.523438 -0.847656 2.789062 -0.765625 3.105469 -0.765625 C 3.421875 -0.765625 3.71875 -0.847656 3.996094 -1.011719 C 4.273438 -1.171875 4.46875 -1.394531 4.585938 -1.671875 C 4.699219 -1.953125 4.757812 -2.359375 4.757812 -2.890625 L 4.757812 -6.222656 L 5.8125 -6.222656 L 5.8125 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-0"> +<path style="stroke:none;" d=""/> +</symbol> +<symbol overflow="visible" id="glyph4-1"> +<path style="stroke:none;" d="M 0.953125 0 L 0.953125 -9.304688 L 4.445312 -9.304688 C 5.15625 -9.304688 5.722656 -9.210938 6.152344 -9.023438 C 6.582031 -8.835938 6.921875 -8.546875 7.164062 -8.152344 C 7.40625 -7.761719 7.527344 -7.351562 7.527344 -6.925781 C 7.527344 -6.527344 7.421875 -6.152344 7.203125 -5.800781 C 6.988281 -5.449219 6.664062 -5.167969 6.226562 -4.953125 C 6.789062 -4.785156 7.222656 -4.503906 7.523438 -4.105469 C 7.828125 -3.707031 7.980469 -3.238281 7.980469 -2.699219 C 7.980469 -2.261719 7.886719 -1.855469 7.703125 -1.480469 C 7.519531 -1.105469 7.292969 -0.820312 7.019531 -0.617188 C 6.75 -0.414062 6.410156 -0.257812 6 -0.15625 C 5.59375 -0.0507812 5.09375 0 4.5 0 Z M 2.183594 -5.394531 L 4.195312 -5.394531 C 4.742188 -5.394531 5.132812 -5.429688 5.371094 -5.503906 C 5.683594 -5.597656 5.917969 -5.75 6.078125 -5.96875 C 6.238281 -6.183594 6.316406 -6.453125 6.316406 -6.78125 C 6.316406 -7.089844 6.242188 -7.359375 6.09375 -7.59375 C 5.945312 -7.828125 5.734375 -7.992188 5.460938 -8.078125 C 5.183594 -8.164062 4.710938 -8.207031 4.042969 -8.207031 L 2.183594 -8.207031 Z M 2.183594 -1.097656 L 4.5 -1.097656 C 4.898438 -1.097656 5.175781 -1.113281 5.339844 -1.140625 C 5.621094 -1.191406 5.859375 -1.277344 6.050781 -1.398438 C 6.242188 -1.515625 6.394531 -1.6875 6.519531 -1.914062 C 6.640625 -2.140625 6.703125 -2.402344 6.703125 -2.699219 C 6.703125 -3.046875 6.613281 -3.347656 6.4375 -3.601562 C 6.257812 -3.859375 6.011719 -4.039062 5.695312 -4.140625 C 5.382812 -4.246094 4.929688 -4.296875 4.335938 -4.296875 L 2.183594 -4.296875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-2"> +<path style="stroke:none;" d="M 0.429688 -3.371094 C 0.429688 -4.617188 0.777344 -5.542969 1.472656 -6.144531 C 2.050781 -6.644531 2.757812 -6.894531 3.59375 -6.894531 C 4.519531 -6.894531 5.277344 -6.589844 5.867188 -5.984375 C 6.453125 -5.375 6.746094 -4.535156 6.746094 -3.464844 C 6.746094 -2.597656 6.617188 -1.914062 6.355469 -1.417969 C 6.097656 -0.921875 5.71875 -0.535156 5.222656 -0.261719 C 4.722656 0.015625 4.179688 0.152344 3.59375 0.152344 C 2.648438 0.152344 1.886719 -0.148438 1.304688 -0.753906 C 0.722656 -1.359375 0.429688 -2.230469 0.429688 -3.371094 Z M 1.605469 -3.371094 C 1.605469 -2.507812 1.792969 -1.859375 2.171875 -1.429688 C 2.546875 -1 3.023438 -0.789062 3.59375 -0.789062 C 4.160156 -0.789062 4.632812 -1.003906 5.007812 -1.433594 C 5.382812 -1.867188 5.574219 -2.523438 5.574219 -3.410156 C 5.574219 -4.242188 5.382812 -4.875 5.003906 -5.304688 C 4.625 -5.734375 4.15625 -5.949219 3.59375 -5.949219 C 3.023438 -5.949219 2.546875 -5.734375 2.171875 -5.304688 C 1.792969 -4.878906 1.605469 -4.234375 1.605469 -3.371094 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-3"> +<path style="stroke:none;" d="M 0.398438 -2.011719 L 1.53125 -2.191406 C 1.59375 -1.738281 1.769531 -1.390625 2.058594 -1.148438 C 2.347656 -0.90625 2.753906 -0.789062 3.273438 -0.789062 C 3.800781 -0.789062 4.1875 -0.894531 4.445312 -1.109375 C 4.699219 -1.320312 4.824219 -1.570312 4.824219 -1.859375 C 4.824219 -2.117188 4.710938 -2.320312 4.488281 -2.46875 C 4.332031 -2.570312 3.941406 -2.699219 3.320312 -2.855469 C 2.480469 -3.066406 1.902344 -3.25 1.578125 -3.40625 C 1.253906 -3.558594 1.007812 -3.773438 0.839844 -4.046875 C 0.671875 -4.320312 0.589844 -4.621094 0.589844 -4.953125 C 0.589844 -5.253906 0.660156 -5.53125 0.796875 -5.785156 C 0.933594 -6.042969 1.121094 -6.253906 1.359375 -6.421875 C 1.535156 -6.554688 1.777344 -6.667969 2.085938 -6.757812 C 2.390625 -6.847656 2.722656 -6.894531 3.070312 -6.894531 C 3.601562 -6.894531 4.066406 -6.816406 4.464844 -6.664062 C 4.867188 -6.511719 5.160156 -6.304688 5.351562 -6.046875 C 5.542969 -5.785156 5.671875 -5.4375 5.746094 -5 L 4.628906 -4.851562 C 4.578125 -5.195312 4.429688 -5.46875 4.1875 -5.664062 C 3.945312 -5.859375 3.597656 -5.953125 3.15625 -5.953125 C 2.628906 -5.953125 2.253906 -5.867188 2.03125 -5.695312 C 1.808594 -5.519531 1.695312 -5.316406 1.695312 -5.085938 C 1.695312 -4.9375 1.742188 -4.804688 1.835938 -4.683594 C 1.929688 -4.5625 2.074219 -4.460938 2.273438 -4.378906 C 2.386719 -4.335938 2.722656 -4.242188 3.28125 -4.085938 C 4.089844 -3.871094 4.652344 -3.695312 4.972656 -3.558594 C 5.292969 -3.421875 5.542969 -3.21875 5.726562 -2.957031 C 5.90625 -2.695312 6 -2.371094 6 -1.980469 C 6 -1.601562 5.886719 -1.242188 5.664062 -0.90625 C 5.441406 -0.570312 5.121094 -0.308594 4.703125 -0.125 C 4.285156 0.0585938 3.8125 0.152344 3.28125 0.152344 C 2.40625 0.152344 1.738281 -0.03125 1.277344 -0.394531 C 0.820312 -0.757812 0.527344 -1.296875 0.398438 -2.011719 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-4"> +<path style="stroke:none;" d="M 3.351562 -1.023438 L 3.515625 -0.0117188 C 3.195312 0.0546875 2.90625 0.0898438 2.652344 0.0898438 C 2.238281 0.0898438 1.917969 0.0234375 1.6875 -0.109375 C 1.460938 -0.238281 1.300781 -0.410156 1.207031 -0.625 C 1.113281 -0.839844 1.066406 -1.289062 1.066406 -1.972656 L 1.066406 -5.851562 L 0.226562 -5.851562 L 0.226562 -6.742188 L 1.066406 -6.742188 L 1.066406 -8.410156 L 2.203125 -9.097656 L 2.203125 -6.742188 L 3.351562 -6.742188 L 3.351562 -5.851562 L 2.203125 -5.851562 L 2.203125 -1.910156 C 2.203125 -1.585938 2.222656 -1.375 2.261719 -1.28125 C 2.304688 -1.1875 2.367188 -1.113281 2.460938 -1.058594 C 2.550781 -1.003906 2.679688 -0.976562 2.851562 -0.976562 C 2.976562 -0.976562 3.144531 -0.992188 3.351562 -1.023438 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-5"> +<path style="stroke:none;" d="M 1.179688 0 L 1.179688 -1.300781 L 2.480469 -1.300781 L 2.480469 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-6"> +<path style="stroke:none;" d="M 1.003906 0 L 1.003906 -9.304688 L 4.511719 -9.304688 C 5.128906 -9.304688 5.601562 -9.277344 5.929688 -9.21875 C 6.386719 -9.140625 6.769531 -8.996094 7.078125 -8.78125 C 7.386719 -8.566406 7.636719 -8.269531 7.824219 -7.882812 C 8.011719 -7.5 8.105469 -7.074219 8.105469 -6.613281 C 8.105469 -5.824219 7.855469 -5.152344 7.351562 -4.605469 C 6.847656 -4.058594 5.9375 -3.78125 4.621094 -3.78125 L 2.234375 -3.78125 L 2.234375 0 Z M 2.234375 -4.882812 L 4.640625 -4.882812 C 5.4375 -4.882812 6 -5.03125 6.335938 -5.324219 C 6.667969 -5.621094 6.835938 -6.039062 6.835938 -6.578125 C 6.835938 -6.964844 6.738281 -7.296875 6.542969 -7.574219 C 6.34375 -7.851562 6.085938 -8.035156 5.765625 -8.125 C 5.558594 -8.179688 5.171875 -8.207031 4.613281 -8.207031 L 2.234375 -8.207031 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-7"> +<path style="stroke:none;" d="M 0.804688 2.597656 L 0.679688 1.523438 C 0.929688 1.589844 1.148438 1.625 1.332031 1.625 C 1.585938 1.625 1.789062 1.582031 1.941406 1.5 C 2.09375 1.414062 2.21875 1.296875 2.316406 1.140625 C 2.390625 1.027344 2.503906 0.746094 2.664062 0.292969 C 2.6875 0.230469 2.722656 0.136719 2.765625 0.0117188 L 0.210938 -6.742188 L 1.441406 -6.742188 L 2.84375 -2.835938 C 3.027344 -2.34375 3.1875 -1.820312 3.332031 -1.277344 C 3.464844 -1.800781 3.621094 -2.3125 3.800781 -2.8125 L 5.242188 -6.742188 L 6.386719 -6.742188 L 3.820312 0.113281 C 3.546875 0.855469 3.332031 1.363281 3.179688 1.644531 C 2.976562 2.019531 2.746094 2.296875 2.480469 2.472656 C 2.21875 2.648438 1.90625 2.734375 1.542969 2.734375 C 1.324219 2.734375 1.078125 2.6875 0.804688 2.597656 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-8"> +<path style="stroke:none;" d="M 0.855469 0 L 0.855469 -9.304688 L 2 -9.304688 L 2 -5.96875 C 2.53125 -6.585938 3.207031 -6.894531 4.019531 -6.894531 C 4.519531 -6.894531 4.953125 -6.796875 5.320312 -6.597656 C 5.6875 -6.402344 5.949219 -6.128906 6.109375 -5.78125 C 6.269531 -5.433594 6.347656 -4.933594 6.347656 -4.273438 L 6.347656 0 L 5.203125 0 L 5.203125 -4.273438 C 5.203125 -4.84375 5.082031 -5.257812 4.832031 -5.519531 C 4.585938 -5.78125 4.234375 -5.910156 3.78125 -5.910156 C 3.445312 -5.910156 3.125 -5.820312 2.828125 -5.644531 C 2.53125 -5.46875 2.316406 -5.234375 2.191406 -4.933594 C 2.0625 -4.632812 2 -4.21875 2 -3.6875 L 2 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-9"> +<path style="stroke:none;" d="M 0.855469 0 L 0.855469 -6.742188 L 1.886719 -6.742188 L 1.886719 -5.78125 C 2.382812 -6.523438 3.09375 -6.894531 4.03125 -6.894531 C 4.4375 -6.894531 4.808594 -6.820312 5.152344 -6.675781 C 5.492188 -6.527344 5.746094 -6.335938 5.914062 -6.101562 C 6.085938 -5.863281 6.203125 -5.582031 6.273438 -5.257812 C 6.3125 -5.046875 6.335938 -4.675781 6.335938 -4.144531 L 6.335938 0 L 5.191406 0 L 5.191406 -4.101562 C 5.191406 -4.566406 5.148438 -4.914062 5.058594 -5.144531 C 4.96875 -5.375 4.8125 -5.558594 4.585938 -5.695312 C 4.359375 -5.835938 4.09375 -5.902344 3.789062 -5.902344 C 3.304688 -5.902344 2.882812 -5.75 2.53125 -5.441406 C 2.175781 -5.132812 2 -4.546875 2 -3.679688 L 2 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-10"> +<path style="stroke:none;" d="M 0.855469 2.582031 L 0.855469 -6.742188 L 1.898438 -6.742188 L 1.898438 -5.867188 C 2.144531 -6.207031 2.421875 -6.464844 2.730469 -6.636719 C 3.039062 -6.808594 3.414062 -6.894531 3.851562 -6.894531 C 4.429688 -6.894531 4.9375 -6.746094 5.375 -6.449219 C 5.816406 -6.152344 6.148438 -5.734375 6.375 -5.195312 C 6.597656 -4.65625 6.710938 -4.066406 6.710938 -3.421875 C 6.710938 -2.730469 6.585938 -2.109375 6.339844 -1.558594 C 6.089844 -1.007812 5.730469 -0.582031 5.257812 -0.289062 C 4.785156 0.00390625 4.289062 0.152344 3.769531 0.152344 C 3.390625 0.152344 3.046875 0.0703125 2.746094 -0.0898438 C 2.441406 -0.25 2.195312 -0.453125 2 -0.699219 L 2 2.582031 Z M 1.890625 -3.332031 C 1.890625 -2.464844 2.066406 -1.824219 2.417969 -1.410156 C 2.769531 -0.996094 3.195312 -0.789062 3.695312 -0.789062 C 4.203125 -0.789062 4.636719 -1 5 -1.429688 C 5.359375 -1.859375 5.542969 -2.527344 5.542969 -3.429688 C 5.542969 -4.289062 5.363281 -4.929688 5.011719 -5.359375 C 4.65625 -5.785156 4.234375 -6 3.746094 -6 C 3.257812 -6 2.828125 -5.769531 2.453125 -5.316406 C 2.078125 -4.859375 1.890625 -4.199219 1.890625 -3.332031 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-11"> +<path style="stroke:none;" d="M 1.910156 0 L 0.851562 0 L 0.851562 -9.304688 L 1.992188 -9.304688 L 1.992188 -5.984375 C 2.476562 -6.589844 3.089844 -6.894531 3.839844 -6.894531 C 4.253906 -6.894531 4.648438 -6.808594 5.019531 -6.644531 C 5.390625 -6.476562 5.691406 -6.242188 5.933594 -5.9375 C 6.171875 -5.636719 6.359375 -5.269531 6.492188 -4.84375 C 6.628906 -4.414062 6.695312 -3.957031 6.695312 -3.472656 C 6.695312 -2.316406 6.410156 -1.425781 5.839844 -0.792969 C 5.269531 -0.164062 4.582031 0.152344 3.78125 0.152344 C 2.988281 0.152344 2.363281 -0.179688 1.910156 -0.84375 Z M 1.898438 -3.421875 C 1.898438 -2.613281 2.007812 -2.027344 2.226562 -1.667969 C 2.585938 -1.082031 3.074219 -0.789062 3.6875 -0.789062 C 4.1875 -0.789062 4.617188 -1.003906 4.984375 -1.4375 C 5.347656 -1.871094 5.527344 -2.519531 5.527344 -3.375 C 5.527344 -4.257812 5.355469 -4.90625 5.003906 -5.324219 C 4.65625 -5.742188 4.234375 -5.953125 3.738281 -5.953125 C 3.238281 -5.953125 2.808594 -5.738281 2.445312 -5.304688 C 2.082031 -4.871094 1.898438 -4.242188 1.898438 -3.421875 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-12"> +<path style="stroke:none;" d="M 0.863281 -7.992188 L 0.863281 -9.304688 L 2.007812 -9.304688 L 2.007812 -7.992188 Z M 0.863281 0 L 0.863281 -6.742188 L 2.007812 -6.742188 L 2.007812 0 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-13"> +<path style="stroke:none;" d="M 5.230469 0 L 5.230469 -0.851562 C 4.804688 -0.183594 4.175781 0.152344 3.34375 0.152344 C 2.808594 0.152344 2.3125 0.00390625 1.863281 -0.292969 C 1.414062 -0.589844 1.0625 -1 0.816406 -1.53125 C 0.570312 -2.0625 0.445312 -2.675781 0.445312 -3.363281 C 0.445312 -4.035156 0.554688 -4.648438 0.78125 -5.195312 C 1.003906 -5.742188 1.339844 -6.164062 1.789062 -6.457031 C 2.238281 -6.75 2.738281 -6.894531 3.292969 -6.894531 C 3.699219 -6.894531 4.0625 -6.808594 4.378906 -6.636719 C 4.695312 -6.464844 4.957031 -6.242188 5.15625 -5.96875 L 5.15625 -9.304688 L 6.289062 -9.304688 L 6.289062 0 Z M 1.617188 -3.363281 C 1.617188 -2.5 1.800781 -1.855469 2.164062 -1.429688 C 2.527344 -1 2.957031 -0.789062 3.453125 -0.789062 C 3.953125 -0.789062 4.375 -0.992188 4.726562 -1.398438 C 5.074219 -1.808594 5.25 -2.429688 5.25 -3.269531 C 5.25 -4.191406 5.070312 -4.867188 4.714844 -5.300781 C 4.359375 -5.730469 3.921875 -5.949219 3.402344 -5.949219 C 2.894531 -5.949219 2.46875 -5.742188 2.128906 -5.324219 C 1.789062 -4.910156 1.617188 -4.257812 1.617188 -3.363281 Z "/> +</symbol> +<symbol overflow="visible" id="glyph4-14"> +<path style="stroke:none;" d="M 4.84375 0 L 3.699219 0 L 3.699219 -7.28125 C 3.425781 -7.019531 3.066406 -6.757812 2.617188 -6.492188 C 2.171875 -6.230469 1.769531 -6.035156 1.414062 -5.902344 L 1.414062 -7.007812 C 2.054688 -7.308594 2.613281 -7.671875 3.089844 -8.101562 C 3.570312 -8.527344 3.90625 -8.941406 4.105469 -9.34375 L 4.84375 -9.34375 Z "/> +</symbol> +</g> +<clipPath id="clip1"> + <path d="M 94 19 L 96 19 L 96 215 L 94 215 Z "/> +</clipPath> +<clipPath id="clip2"> + <path d="M 204 19 L 206 19 L 206 215 L 204 215 Z "/> +</clipPath> +<clipPath id="clip3"> + <path d="M 314 19 L 316 19 L 316 215 L 314 215 Z "/> +</clipPath> +<clipPath id="clip4"> + <path d="M 39 171 L 355 171 L 355 173 L 39 173 Z "/> +</clipPath> +<clipPath id="clip5"> + <path d="M 39 107 L 355 107 L 355 109 L 39 109 Z "/> +</clipPath> +<clipPath id="clip6"> + <path d="M 39 44 L 355 44 L 355 46 L 39 46 Z "/> +</clipPath> +</defs> +<g id="surface18"> +<g clip-path="url(#clip1)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 95.160156 214.296875 L 95.160156 19 "/> +</g> +<g clip-path="url(#clip2)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 204.84375 214.296875 L 204.84375 19 "/> +</g> +<g clip-path="url(#clip3)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 314.53125 214.296875 L 314.53125 19 "/> +</g> +<g clip-path="url(#clip4)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 39 171.960938 L 355 171.960938 "/> +</g> +<g clip-path="url(#clip5)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 39 108.234375 L 355 108.234375 "/> +</g> +<g clip-path="url(#clip6)" clip-rule="nonzero"> +<path style="fill:none;stroke-width:1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:0.5;stroke-dasharray:1,2;stroke-miterlimit:3.25;" d="M 39 44.511719 L 355 44.511719 "/> +</g> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 55.070312 201 C 55.070312 200.183594 54.75 199.402344 54.171875 198.828125 C 53.597656 198.25 52.816406 197.929688 52 197.929688 C 51.183594 197.929688 50.402344 198.25 49.828125 198.828125 C 49.25 199.402344 48.929688 200.183594 48.929688 201 C 48.929688 201.816406 49.25 202.597656 49.828125 203.171875 C 50.402344 203.75 51.183594 204.070312 52 204.070312 C 52.816406 204.070312 53.597656 203.75 54.171875 203.171875 C 54.75 202.597656 55.070312 201.816406 55.070312 201 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 88.070312 176 C 88.070312 175.183594 87.75 174.402344 87.171875 173.828125 C 86.597656 173.25 85.816406 172.929688 85 172.929688 C 84.183594 172.929688 83.402344 173.25 82.828125 173.828125 C 82.25 174.402344 81.929688 175.183594 81.929688 176 C 81.929688 176.816406 82.25 177.597656 82.828125 178.171875 C 83.402344 178.75 84.183594 179.070312 85 179.070312 C 85.816406 179.070312 86.597656 178.75 87.171875 178.171875 C 87.75 177.597656 88.070312 176.816406 88.070312 176 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 121.070312 160 C 121.070312 159.183594 120.75 158.402344 120.171875 157.828125 C 119.597656 157.25 118.816406 156.929688 118 156.929688 C 117.183594 156.929688 116.402344 157.25 115.828125 157.828125 C 115.25 158.402344 114.929688 159.183594 114.929688 160 C 114.929688 160.816406 115.25 161.597656 115.828125 162.171875 C 116.402344 162.75 117.183594 163.070312 118 163.070312 C 118.816406 163.070312 119.597656 162.75 120.171875 162.171875 C 120.75 161.597656 121.070312 160.816406 121.070312 160 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 154.070312 142 C 154.070312 141.183594 153.75 140.402344 153.171875 139.828125 C 152.597656 139.25 151.816406 138.929688 151 138.929688 C 150.183594 138.929688 149.402344 139.25 148.828125 139.828125 C 148.25 140.402344 147.929688 141.183594 147.929688 142 C 147.929688 142.816406 148.25 143.597656 148.828125 144.171875 C 149.402344 144.75 150.183594 145.070312 151 145.070312 C 151.816406 145.070312 152.597656 144.75 153.171875 144.171875 C 153.75 143.597656 154.070312 142.816406 154.070312 142 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 187.070312 124 C 187.070312 123.183594 186.75 122.402344 186.171875 121.828125 C 185.597656 121.25 184.816406 120.929688 184 120.929688 C 183.183594 120.929688 182.402344 121.25 181.828125 121.828125 C 181.25 122.402344 180.929688 123.183594 180.929688 124 C 180.929688 124.816406 181.25 125.597656 181.828125 126.171875 C 182.402344 126.75 183.183594 127.070312 184 127.070312 C 184.816406 127.070312 185.597656 126.75 186.171875 126.171875 C 186.75 125.597656 187.070312 124.816406 187.070312 124 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 220.070312 105 C 220.070312 104.183594 219.75 103.402344 219.171875 102.828125 C 218.597656 102.25 217.816406 101.929688 217 101.929688 C 216.183594 101.929688 215.402344 102.25 214.828125 102.828125 C 214.25 103.402344 213.929688 104.183594 213.929688 105 C 213.929688 105.816406 214.25 106.597656 214.828125 107.171875 C 215.402344 107.75 216.183594 108.070312 217 108.070312 C 217.816406 108.070312 218.597656 107.75 219.171875 107.171875 C 219.75 106.597656 220.070312 105.816406 220.070312 105 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 253.070312 86 C 253.070312 85.183594 252.75 84.402344 252.171875 83.828125 C 251.597656 83.25 250.816406 82.929688 250 82.929688 C 249.183594 82.929688 248.402344 83.25 247.828125 83.828125 C 247.25 84.402344 246.929688 85.183594 246.929688 86 C 246.929688 86.816406 247.25 87.597656 247.828125 88.171875 C 248.402344 88.75 249.183594 89.070312 250 89.070312 C 250.816406 89.070312 251.597656 88.75 252.171875 88.171875 C 252.75 87.597656 253.070312 86.816406 253.070312 86 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 286.070312 67 C 286.070312 66.183594 285.75 65.402344 285.171875 64.828125 C 284.597656 64.25 283.816406 63.929688 283 63.929688 C 282.183594 63.929688 281.402344 64.25 280.828125 64.828125 C 280.25 65.402344 279.929688 66.183594 279.929688 67 C 279.929688 67.816406 280.25 68.597656 280.828125 69.171875 C 281.402344 69.75 282.183594 70.070312 283 70.070312 C 283.816406 70.070312 284.597656 69.75 285.171875 69.171875 C 285.75 68.597656 286.070312 67.816406 286.070312 67 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 319.070312 48 C 319.070312 47.183594 318.75 46.402344 318.171875 45.828125 C 317.597656 45.25 316.816406 44.929688 316 44.929688 C 315.183594 44.929688 314.402344 45.25 313.828125 45.828125 C 313.25 46.402344 312.929688 47.183594 312.929688 48 C 312.929688 48.816406 313.25 49.597656 313.828125 50.171875 C 314.402344 50.75 315.183594 51.070312 316 51.070312 C 316.816406 51.070312 317.597656 50.75 318.171875 50.171875 C 318.75 49.597656 319.070312 48.816406 319.070312 48 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 352.070312 29 C 352.070312 28.183594 351.75 27.402344 351.171875 26.828125 C 350.597656 26.25 349.816406 25.929688 349 25.929688 C 348.183594 25.929688 347.402344 26.25 346.828125 26.828125 C 346.25 27.402344 345.929688 28.183594 345.929688 29 C 345.929688 29.816406 346.25 30.597656 346.828125 31.171875 C 347.402344 31.75 348.183594 32.070312 349 32.070312 C 349.816406 32.070312 350.597656 31.75 351.171875 31.171875 C 351.75 30.597656 352.070312 29.816406 352.070312 29 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 55.070312 191 C 55.070312 190.183594 54.75 189.402344 54.171875 188.828125 C 53.597656 188.25 52.816406 187.929688 52 187.929688 C 51.183594 187.929688 50.402344 188.25 49.828125 188.828125 C 49.25 189.402344 48.929688 190.183594 48.929688 191 C 48.929688 191.816406 49.25 192.597656 49.828125 193.171875 C 50.402344 193.75 51.183594 194.070312 52 194.070312 C 52.816406 194.070312 53.597656 193.75 54.171875 193.171875 C 54.75 192.597656 55.070312 191.816406 55.070312 191 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 88.070312 181 C 88.070312 180.183594 87.75 179.402344 87.171875 178.828125 C 86.597656 178.25 85.816406 177.929688 85 177.929688 C 84.183594 177.929688 83.402344 178.25 82.828125 178.828125 C 82.25 179.402344 81.929688 180.183594 81.929688 181 C 81.929688 181.816406 82.25 182.597656 82.828125 183.171875 C 83.402344 183.75 84.183594 184.070312 85 184.070312 C 85.816406 184.070312 86.597656 183.75 87.171875 183.171875 C 87.75 182.597656 88.070312 181.816406 88.070312 181 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 121.070312 170 C 121.070312 169.183594 120.75 168.402344 120.171875 167.828125 C 119.597656 167.25 118.816406 166.929688 118 166.929688 C 117.183594 166.929688 116.402344 167.25 115.828125 167.828125 C 115.25 168.402344 114.929688 169.183594 114.929688 170 C 114.929688 170.816406 115.25 171.597656 115.828125 172.171875 C 116.402344 172.75 117.183594 173.070312 118 173.070312 C 118.816406 173.070312 119.597656 172.75 120.171875 172.171875 C 120.75 171.597656 121.070312 170.816406 121.070312 170 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 154.070312 157 C 154.070312 156.183594 153.75 155.402344 153.171875 154.828125 C 152.597656 154.25 151.816406 153.929688 151 153.929688 C 150.183594 153.929688 149.402344 154.25 148.828125 154.828125 C 148.25 155.402344 147.929688 156.183594 147.929688 157 C 147.929688 157.816406 148.25 158.597656 148.828125 159.171875 C 149.402344 159.75 150.183594 160.070312 151 160.070312 C 151.816406 160.070312 152.597656 159.75 153.171875 159.171875 C 153.75 158.597656 154.070312 157.816406 154.070312 157 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 187.070312 142 C 187.070312 141.183594 186.75 140.402344 186.171875 139.828125 C 185.597656 139.25 184.816406 138.929688 184 138.929688 C 183.183594 138.929688 182.402344 139.25 181.828125 139.828125 C 181.25 140.402344 180.929688 141.183594 180.929688 142 C 180.929688 142.816406 181.25 143.597656 181.828125 144.171875 C 182.402344 144.75 183.183594 145.070312 184 145.070312 C 184.816406 145.070312 185.597656 144.75 186.171875 144.171875 C 186.75 143.597656 187.070312 142.816406 187.070312 142 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 220.070312 125 C 220.070312 124.183594 219.75 123.402344 219.171875 122.828125 C 218.597656 122.25 217.816406 121.929688 217 121.929688 C 216.183594 121.929688 215.402344 122.25 214.828125 122.828125 C 214.25 123.402344 213.929688 124.183594 213.929688 125 C 213.929688 125.816406 214.25 126.597656 214.828125 127.171875 C 215.402344 127.75 216.183594 128.070312 217 128.070312 C 217.816406 128.070312 218.597656 127.75 219.171875 127.171875 C 219.75 126.597656 220.070312 125.816406 220.070312 125 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 253.070312 107 C 253.070312 106.183594 252.75 105.402344 252.171875 104.828125 C 251.597656 104.25 250.816406 103.929688 250 103.929688 C 249.183594 103.929688 248.402344 104.25 247.828125 104.828125 C 247.25 105.402344 246.929688 106.183594 246.929688 107 C 246.929688 107.816406 247.25 108.597656 247.828125 109.171875 C 248.402344 109.75 249.183594 110.070312 250 110.070312 C 250.816406 110.070312 251.597656 109.75 252.171875 109.171875 C 252.75 108.597656 253.070312 107.816406 253.070312 107 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 286.070312 88 C 286.070312 87.183594 285.75 86.402344 285.171875 85.828125 C 284.597656 85.25 283.816406 84.929688 283 84.929688 C 282.183594 84.929688 281.402344 85.25 280.828125 85.828125 C 280.25 86.402344 279.929688 87.183594 279.929688 88 C 279.929688 88.816406 280.25 89.597656 280.828125 90.171875 C 281.402344 90.75 282.183594 91.070312 283 91.070312 C 283.816406 91.070312 284.597656 90.75 285.171875 90.171875 C 285.75 89.597656 286.070312 88.816406 286.070312 88 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 319.070312 69 C 319.070312 68.183594 318.75 67.402344 318.171875 66.828125 C 317.597656 66.25 316.816406 65.929688 316 65.929688 C 315.183594 65.929688 314.402344 66.25 313.828125 66.828125 C 313.25 67.402344 312.929688 68.183594 312.929688 69 C 312.929688 69.816406 313.25 70.597656 313.828125 71.171875 C 314.402344 71.75 315.183594 72.070312 316 72.070312 C 316.816406 72.070312 317.597656 71.75 318.171875 71.171875 C 318.75 70.597656 319.070312 69.816406 319.070312 69 Z "/> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 352.070312 50 C 352.070312 49.183594 351.75 48.402344 351.171875 47.828125 C 350.597656 47.25 349.816406 46.929688 349 46.929688 C 348.183594 46.929688 347.402344 47.25 346.828125 47.828125 C 346.25 48.402344 345.929688 49.183594 345.929688 50 C 345.929688 50.816406 346.25 51.597656 346.828125 52.171875 C 347.402344 52.75 348.183594 53.070312 349 53.070312 C 349.816406 53.070312 350.597656 52.75 351.171875 52.171875 C 351.75 51.597656 352.070312 50.816406 352.070312 50 Z "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 214.296875 L 39 214.296875 "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 214.296875 L 39 19 "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 19 L 355 19 "/> +<path style="fill:none;stroke-width:0.5;stroke-linecap:square;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 19 L 355 214.296875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 95.160156 214.296875 L 95.160156 211.140625 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="89.659467" y="226.29874"/> + <use xlink:href="#glyph0-2" x="95.220991" y="226.29874"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 204.84375 214.296875 L 204.84375 211.140625 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="196.345465" y="226.29874"/> + <use xlink:href="#glyph0-2" x="201.906989" y="226.29874"/> + <use xlink:href="#glyph0-2" x="207.468512" y="226.29874"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 314.53125 214.296875 L 314.53125 211.140625 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="303.531463" y="226.29874"/> + <use xlink:href="#glyph0-2" x="309.092987" y="226.29874"/> + <use xlink:href="#glyph0-2" x="314.65451" y="226.29874"/> + <use xlink:href="#glyph0-2" x="320.216034" y="226.29874"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 51.511719 214.296875 L 51.511719 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 62.140625 214.296875 L 62.140625 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 70.824219 214.296875 L 70.824219 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 78.167969 214.296875 L 78.167969 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 84.53125 214.296875 L 84.53125 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 90.140625 214.296875 L 90.140625 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 128.179688 214.296875 L 128.179688 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 147.492188 214.296875 L 147.492188 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 161.195312 214.296875 L 161.195312 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 171.828125 214.296875 L 171.828125 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 180.511719 214.296875 L 180.511719 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 187.855469 214.296875 L 187.855469 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 194.214844 214.296875 L 194.214844 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 199.828125 214.296875 L 199.828125 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 237.863281 214.296875 L 237.863281 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 257.179688 214.296875 L 257.179688 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 270.882812 214.296875 L 270.882812 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 281.511719 214.296875 L 281.511719 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 290.199219 214.296875 L 290.199219 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 297.539062 214.296875 L 297.539062 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 303.902344 214.296875 L 303.902344 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 309.511719 214.296875 L 309.511719 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 347.550781 214.296875 L 347.550781 212.71875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 171.960938 L 42.160156 171.960938 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="19" y="176.961688"/> + <use xlink:href="#glyph0-2" x="24.561523" y="176.961688"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph1-1" x="30" y="172.81325"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 108.234375 L 42.160156 108.234375 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="19" y="113.23603"/> + <use xlink:href="#glyph0-2" x="24.561523" y="113.23603"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph1-2" x="30" y="109.087593"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 44.511719 L 42.160156 44.511719 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-1" x="19" y="49.510373"/> + <use xlink:href="#glyph0-2" x="24.561523" y="49.510373"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph1-3" x="30" y="45.361936"/> +</g> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 205.28125 L 40.578125 205.28125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 197.320312 L 40.578125 197.320312 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 191.144531 L 40.578125 191.144531 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 186.097656 L 40.578125 186.097656 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 181.832031 L 40.578125 181.832031 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 178.136719 L 40.578125 178.136719 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 174.878906 L 40.578125 174.878906 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 152.777344 L 40.578125 152.777344 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 141.558594 L 40.578125 141.558594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 133.59375 L 40.578125 133.59375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 127.417969 L 40.578125 127.417969 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 122.375 L 40.578125 122.375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 118.105469 L 40.578125 118.105469 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 114.410156 L 40.578125 114.410156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 111.152344 L 40.578125 111.152344 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 89.050781 L 40.578125 89.050781 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 77.832031 L 40.578125 77.832031 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 69.871094 L 40.578125 69.871094 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 63.695312 L 40.578125 63.695312 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 58.648438 L 40.578125 58.648438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 54.382812 L 40.578125 54.382812 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 50.6875 L 40.578125 50.6875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 47.425781 L 40.578125 47.425781 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 39 25.328125 L 40.578125 25.328125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 95.160156 19 L 95.160156 22.160156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 204.84375 19 L 204.84375 22.160156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 314.53125 19 L 314.53125 22.160156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 51.511719 19 L 51.511719 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 62.140625 19 L 62.140625 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 70.824219 19 L 70.824219 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 78.167969 19 L 78.167969 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 84.53125 19 L 84.53125 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 90.140625 19 L 90.140625 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 128.179688 19 L 128.179688 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 147.492188 19 L 147.492188 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 161.195312 19 L 161.195312 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 171.828125 19 L 171.828125 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 180.511719 19 L 180.511719 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 187.855469 19 L 187.855469 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 194.214844 19 L 194.214844 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 199.828125 19 L 199.828125 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 237.863281 19 L 237.863281 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 257.179688 19 L 257.179688 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 270.882812 19 L 270.882812 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 281.511719 19 L 281.511719 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 290.199219 19 L 290.199219 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 297.539062 19 L 297.539062 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 303.902344 19 L 303.902344 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 309.511719 19 L 309.511719 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 347.550781 19 L 347.550781 20.578125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 171.960938 L 351.839844 171.960938 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 108.234375 L 351.839844 108.234375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 44.511719 L 351.839844 44.511719 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 205.28125 L 353.421875 205.28125 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 197.320312 L 353.421875 197.320312 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 191.144531 L 353.421875 191.144531 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 186.097656 L 353.421875 186.097656 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 181.832031 L 353.421875 181.832031 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 178.136719 L 353.421875 178.136719 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 174.878906 L 353.421875 174.878906 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 152.777344 L 353.421875 152.777344 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 141.558594 L 353.421875 141.558594 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 133.59375 L 353.421875 133.59375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 127.417969 L 353.421875 127.417969 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 122.375 L 353.421875 122.375 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 118.105469 L 353.421875 118.105469 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 114.410156 L 353.421875 114.410156 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 111.152344 L 353.421875 111.152344 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 89.050781 L 353.421875 89.050781 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 77.832031 L 353.421875 77.832031 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 69.871094 L 353.421875 69.871094 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 63.695312 L 353.421875 63.695312 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 58.648438 L 353.421875 58.648438 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 54.382812 L 353.421875 54.382812 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 50.6875 L 353.421875 50.6875 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 47.425781 L 353.421875 47.425781 "/> +<path style="fill:none;stroke-width:0.1;stroke-linecap:butt;stroke-linejoin:miter;stroke:rgb(39.99939%,39.99939%,39.99939%);stroke-opacity:1;stroke-miterlimit:3.25;" d="M 355 25.328125 L 353.421875 25.328125 "/> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph0-3" x="175.5" y="245.29874"/> + <use xlink:href="#glyph0-4" x="181.608398" y="245.29874"/> + <use xlink:href="#glyph0-5" x="187.169922" y="245.29874"/> + <use xlink:href="#glyph0-6" x="192.731445" y="245.29874"/> + <use xlink:href="#glyph0-7" x="197.731445" y="245.29874"/> + <use xlink:href="#glyph0-8" x="200.509766" y="245.29874"/> + <use xlink:href="#glyph0-9" x="202.731445" y="245.29874"/> + <use xlink:href="#glyph0-5" x="208.292969" y="245.29874"/> + <use xlink:href="#glyph0-10" x="213.854492" y="245.29874"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph2-1" x="9" y="129.14937"/> + <use xlink:href="#glyph2-2" x="9" y="122.479448"/> + <use xlink:href="#glyph2-3" x="9" y="117.479448"/> + <use xlink:href="#glyph2-4" x="9" y="114.701128"/> + <use xlink:href="#glyph2-5" x="9" y="109.139605"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph3-1" x="148" y="12"/> + <use xlink:href="#glyph3-2" x="155.330078" y="12"/> + <use xlink:href="#glyph3-3" x="157.996094" y="12"/> + <use xlink:href="#glyph3-4" x="160.662109" y="12"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph3-5" x="170" y="12"/> + <use xlink:href="#glyph3-2" x="176" y="12"/> + <use xlink:href="#glyph3-6" x="178.666016" y="12"/> + <use xlink:href="#glyph3-4" x="184.666016" y="12"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph3-7" x="194" y="12"/> + <use xlink:href="#glyph3-8" x="200.673828" y="12"/> +</g> +<g style="fill:rgb(39.99939%,39.99939%,39.99939%);fill-opacity:1;"> + <use xlink:href="#glyph3-9" x="207" y="12"/> + <use xlink:href="#glyph3-7" x="216.996094" y="12"/> + <use xlink:href="#glyph3-10" x="223.669922" y="12"/> + <use xlink:href="#glyph3-11" x="230.34375" y="12"/> + <use xlink:href="#glyph3-3" x="237.017578" y="12"/> + <use xlink:href="#glyph3-4" x="239.683594" y="12"/> +</g> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(36.84082%,50.67749%,70.979309%);fill-opacity:1;" d="M 382.148438 113 C 382.148438 112.164062 381.816406 111.363281 381.226562 110.773438 C 380.636719 110.183594 379.835938 109.851562 379 109.851562 C 378.164062 109.851562 377.363281 110.183594 376.773438 110.773438 C 376.183594 111.363281 375.851562 112.164062 375.851562 113 C 375.851562 113.835938 376.183594 114.636719 376.773438 115.226562 C 377.363281 115.816406 378.164062 116.148438 379 116.148438 C 379.835938 116.148438 380.636719 115.816406 381.226562 115.226562 C 381.816406 114.636719 382.148438 113.835938 382.148438 113 Z "/> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph4-1" x="391" y="117.28418"/> + <use xlink:href="#glyph4-2" x="399.670898" y="117.28418"/> + <use xlink:href="#glyph4-2" x="406.901367" y="117.28418"/> + <use xlink:href="#glyph4-3" x="414.131836" y="117.28418"/> + <use xlink:href="#glyph4-4" x="420.631836" y="117.28418"/> +</g> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph4-5" x="424" y="117.28418"/> +</g> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph4-6" x="428" y="117.28418"/> + <use xlink:href="#glyph4-7" x="436.670898" y="117.28418"/> + <use xlink:href="#glyph4-4" x="443.170898" y="117.28418"/> + <use xlink:href="#glyph4-8" x="446.783203" y="117.28418"/> + <use xlink:href="#glyph4-2" x="454.013672" y="117.28418"/> + <use xlink:href="#glyph4-9" x="461.244141" y="117.28418"/> +</g> +<path style=" stroke:none;fill-rule:evenodd;fill:rgb(88.070679%,61.103821%,14.204407%);fill-opacity:1;" d="M 382.148438 136 C 382.148438 135.164062 381.816406 134.363281 381.226562 133.773438 C 380.636719 133.183594 379.835938 132.851562 379 132.851562 C 378.164062 132.851562 377.363281 133.183594 376.773438 133.773438 C 376.183594 134.363281 375.851562 135.164062 375.851562 136 C 375.851562 136.835938 376.183594 137.636719 376.773438 138.226562 C 377.363281 138.816406 378.164062 139.148438 379 139.148438 C 379.835938 139.148438 380.636719 138.816406 381.226562 138.226562 C 381.816406 137.636719 382.148438 136.835938 382.148438 136 Z "/> +<g style="fill:rgb(0%,0%,0%);fill-opacity:1;"> + <use xlink:href="#glyph4-10" x="391" y="140.28418"/> + <use xlink:href="#glyph4-7" x="398.230469" y="140.28418"/> + <use xlink:href="#glyph4-11" x="404.730469" y="140.28418"/> + <use xlink:href="#glyph4-12" x="411.960938" y="140.28418"/> + <use xlink:href="#glyph4-9" x="414.849609" y="140.28418"/> + <use xlink:href="#glyph4-13" x="422.080078" y="140.28418"/> + <use xlink:href="#glyph4-14" x="429.310547" y="140.28418"/> + <use xlink:href="#glyph4-14" x="436.541016" y="140.28418"/> +</g> +</g> +</svg> diff --git a/3rdparty/pybind11/docs/reference.rst b/3rdparty/pybind11/docs/reference.rst new file mode 100644 index 00000000..a9fbe600 --- /dev/null +++ b/3rdparty/pybind11/docs/reference.rst @@ -0,0 +1,117 @@ +.. _reference: + +.. warning:: + + Please be advised that the reference documentation discussing pybind11 + internals is currently incomplete. Please refer to the previous sections + and the pybind11 header files for the nitty gritty details. + +Reference +######### + +.. _macros: + +Macros +====== + +.. doxygendefine:: PYBIND11_MODULE + +.. _core_types: + +Convenience classes for arbitrary Python types +============================================== + +Common member functions +----------------------- + +.. doxygenclass:: object_api + :members: + +Without reference counting +-------------------------- + +.. doxygenclass:: handle + :members: + +With reference counting +----------------------- + +.. doxygenclass:: object + :members: + +.. doxygenfunction:: reinterpret_borrow + +.. doxygenfunction:: reinterpret_steal + +Convenience classes for specific Python types +============================================= + +.. doxygenclass:: module + :members: + +.. doxygengroup:: pytypes + :members: + +.. _extras: + +Passing extra arguments to ``def`` or ``class_`` +================================================ + +.. doxygengroup:: annotations + :members: + +Embedding the interpreter +========================= + +.. doxygendefine:: PYBIND11_EMBEDDED_MODULE + +.. doxygenfunction:: initialize_interpreter + +.. doxygenfunction:: finalize_interpreter + +.. doxygenclass:: scoped_interpreter + +Redirecting C++ streams +======================= + +.. doxygenclass:: scoped_ostream_redirect + +.. doxygenclass:: scoped_estream_redirect + +.. doxygenfunction:: add_ostream_redirect + +Python built-in functions +========================= + +.. doxygengroup:: python_builtins + :members: + +Inheritance +=========== + +See :doc:`/classes` and :doc:`/advanced/classes` for more detail. + +.. doxygendefine:: PYBIND11_OVERLOAD + +.. doxygendefine:: PYBIND11_OVERLOAD_PURE + +.. doxygendefine:: PYBIND11_OVERLOAD_NAME + +.. doxygendefine:: PYBIND11_OVERLOAD_PURE_NAME + +.. doxygenfunction:: get_overload + +Exceptions +========== + +.. doxygenclass:: error_already_set + :members: + +.. doxygenclass:: builtin_exception + :members: + + +Literals +======== + +.. doxygennamespace:: literals diff --git a/3rdparty/pybind11/docs/release.rst b/3rdparty/pybind11/docs/release.rst new file mode 100644 index 00000000..9846f971 --- /dev/null +++ b/3rdparty/pybind11/docs/release.rst @@ -0,0 +1,21 @@ +To release a new version of pybind11: + +- Update the version number and push to pypi + - Update ``pybind11/_version.py`` (set release version, remove 'dev'). + - Update ``PYBIND11_VERSION_MAJOR`` etc. in ``include/pybind11/detail/common.h``. + - Ensure that all the information in ``setup.py`` is up-to-date. + - Update version in ``docs/conf.py``. + - Tag release date in ``docs/changelog.rst``. + - ``git add`` and ``git commit``. + - if new minor version: ``git checkout -b vX.Y``, ``git push -u origin vX.Y`` + - ``git tag -a vX.Y.Z -m 'vX.Y.Z release'``. + - ``git push`` + - ``git push --tags``. + - ``python setup.py sdist upload``. + - ``python setup.py bdist_wheel upload``. +- Get back to work + - Update ``_version.py`` (add 'dev' and increment minor). + - Update version in ``docs/conf.py`` + - Update version macros in ``include/pybind11/common.h`` + - ``git add`` and ``git commit``. + ``git push`` diff --git a/3rdparty/pybind11/docs/requirements.txt b/3rdparty/pybind11/docs/requirements.txt new file mode 100644 index 00000000..3818fe80 --- /dev/null +++ b/3rdparty/pybind11/docs/requirements.txt @@ -0,0 +1 @@ +breathe == 4.5.0 diff --git a/3rdparty/pybind11/docs/upgrade.rst b/3rdparty/pybind11/docs/upgrade.rst new file mode 100644 index 00000000..3f569739 --- /dev/null +++ b/3rdparty/pybind11/docs/upgrade.rst @@ -0,0 +1,404 @@ +Upgrade guide +############# + +This is a companion guide to the :doc:`changelog`. While the changelog briefly +lists all of the new features, improvements and bug fixes, this upgrade guide +focuses only the subset which directly impacts your experience when upgrading +to a new version. But it goes into more detail. This includes things like +deprecated APIs and their replacements, build system changes, general code +modernization and other useful information. + + +v2.2 +==== + +Deprecation of the ``PYBIND11_PLUGIN`` macro +-------------------------------------------- + +``PYBIND11_MODULE`` is now the preferred way to create module entry points. +The old macro emits a compile-time deprecation warning. + +.. code-block:: cpp + + // old + PYBIND11_PLUGIN(example) { + py::module m("example", "documentation string"); + + m.def("add", [](int a, int b) { return a + b; }); + + return m.ptr(); + } + + // new + PYBIND11_MODULE(example, m) { + m.doc() = "documentation string"; // optional + + m.def("add", [](int a, int b) { return a + b; }); + } + + +New API for defining custom constructors and pickling functions +--------------------------------------------------------------- + +The old placement-new custom constructors have been deprecated. The new approach +uses ``py::init()`` and factory functions to greatly improve type safety. + +Placement-new can be called accidentally with an incompatible type (without any +compiler errors or warnings), or it can initialize the same object multiple times +if not careful with the Python-side ``__init__`` calls. The new-style custom +constructors prevent such mistakes. See :ref:`custom_constructors` for details. + +.. code-block:: cpp + + // old -- deprecated (runtime warning shown only in debug mode) + py::class<Foo>(m, "Foo") + .def("__init__", [](Foo &self, ...) { + new (&self) Foo(...); // uses placement-new + }); + + // new + py::class<Foo>(m, "Foo") + .def(py::init([](...) { // Note: no `self` argument + return new Foo(...); // return by raw pointer + // or: return std::make_unique<Foo>(...); // return by holder + // or: return Foo(...); // return by value (move constructor) + })); + +Mirroring the custom constructor changes, ``py::pickle()`` is now the preferred +way to get and set object state. See :ref:`pickling` for details. + +.. code-block:: cpp + + // old -- deprecated (runtime warning shown only in debug mode) + py::class<Foo>(m, "Foo") + ... + .def("__getstate__", [](const Foo &self) { + return py::make_tuple(self.value1(), self.value2(), ...); + }) + .def("__setstate__", [](Foo &self, py::tuple t) { + new (&self) Foo(t[0].cast<std::string>(), ...); + }); + + // new + py::class<Foo>(m, "Foo") + ... + .def(py::pickle( + [](const Foo &self) { // __getstate__ + return py::make_tuple(f.value1(), f.value2(), ...); // unchanged + }, + [](py::tuple t) { // __setstate__, note: no `self` argument + return new Foo(t[0].cast<std::string>(), ...); + // or: return std::make_unique<Foo>(...); // return by holder + // or: return Foo(...); // return by value (move constructor) + } + )); + +For both the constructors and pickling, warnings are shown at module +initialization time (on import, not when the functions are called). +They're only visible when compiled in debug mode. Sample warning: + +.. code-block:: none + + pybind11-bound class 'mymodule.Foo' is using an old-style placement-new '__init__' + which has been deprecated. See the upgrade guide in pybind11's docs. + + +Stricter enforcement of hidden symbol visibility for pybind11 modules +--------------------------------------------------------------------- + +pybind11 now tries to actively enforce hidden symbol visibility for modules. +If you're using either one of pybind11's :doc:`CMake or Python build systems +<compiling>` (the two example repositories) and you haven't been exporting any +symbols, there's nothing to be concerned about. All the changes have been done +transparently in the background. If you were building manually or relied on +specific default visibility, read on. + +Setting default symbol visibility to *hidden* has always been recommended for +pybind11 (see :ref:`faq:symhidden`). On Linux and macOS, hidden symbol +visibility (in conjunction with the ``strip`` utility) yields much smaller +module binaries. `CPython's extension docs`_ also recommend hiding symbols +by default, with the goal of avoiding symbol name clashes between modules. +Starting with v2.2, pybind11 enforces this more strictly: (1) by declaring +all symbols inside the ``pybind11`` namespace as hidden and (2) by including +the ``-fvisibility=hidden`` flag on Linux and macOS (only for extension +modules, not for embedding the interpreter). + +.. _CPython's extension docs: https://docs.python.org/3/extending/extending.html#providing-a-c-api-for-an-extension-module + +The namespace-scope hidden visibility is done automatically in pybind11's +headers and it's generally transparent to users. It ensures that: + +* Modules compiled with different pybind11 versions don't clash with each other. + +* Some new features, like ``py::module_local`` bindings, can work as intended. + +The ``-fvisibility=hidden`` flag applies the same visibility to user bindings +outside of the ``pybind11`` namespace. It's now set automatic by pybind11's +CMake and Python build systems, but this needs to be done manually by users +of other build systems. Adding this flag: + +* Minimizes the chances of symbol conflicts between modules. E.g. if two + unrelated modules were statically linked to different (ABI-incompatible) + versions of the same third-party library, a symbol clash would be likely + (and would end with unpredictable results). + +* Produces smaller binaries on Linux and macOS, as pointed out previously. + +Within pybind11's CMake build system, ``pybind11_add_module`` has always been +setting the ``-fvisibility=hidden`` flag in release mode. From now on, it's +being applied unconditionally, even in debug mode and it can no longer be opted +out of with the ``NO_EXTRAS`` option. The ``pybind11::module`` target now also +adds this flag to it's interface. The ``pybind11::embed`` target is unchanged. + +The most significant change here is for the ``pybind11::module`` target. If you +were previously relying on default visibility, i.e. if your Python module was +doubling as a shared library with dependents, you'll need to either export +symbols manually (recommended for cross-platform libraries) or factor out the +shared library (and have the Python module link to it like the other +dependents). As a temporary workaround, you can also restore default visibility +using the CMake code below, but this is not recommended in the long run: + +.. code-block:: cmake + + target_link_libraries(mymodule PRIVATE pybind11::module) + + add_library(restore_default_visibility INTERFACE) + target_compile_options(restore_default_visibility INTERFACE -fvisibility=default) + target_link_libraries(mymodule PRIVATE restore_default_visibility) + + +Local STL container bindings +---------------------------- + +Previous pybind11 versions could only bind types globally -- all pybind11 +modules, even unrelated ones, would have access to the same exported types. +However, this would also result in a conflict if two modules exported the +same C++ type, which is especially problematic for very common types, e.g. +``std::vector<int>``. :ref:`module_local` were added to resolve this (see +that section for a complete usage guide). + +``py::class_`` still defaults to global bindings (because these types are +usually unique across modules), however in order to avoid clashes of opaque +types, ``py::bind_vector`` and ``py::bind_map`` will now bind STL containers +as ``py::module_local`` if their elements are: builtins (``int``, ``float``, +etc.), not bound using ``py::class_``, or bound as ``py::module_local``. For +example, this change allows multiple modules to bind ``std::vector<int>`` +without causing conflicts. See :ref:`stl_bind` for more details. + +When upgrading to this version, if you have multiple modules which depend on +a single global binding of an STL container, note that all modules can still +accept foreign ``py::module_local`` types in the direction of Python-to-C++. +The locality only affects the C++-to-Python direction. If this is needed in +multiple modules, you'll need to either: + +* Add a copy of the same STL binding to all of the modules which need it. + +* Restore the global status of that single binding by marking it + ``py::module_local(false)``. + +The latter is an easy workaround, but in the long run it would be best to +localize all common type bindings in order to avoid conflicts with +third-party modules. + + +Negative strides for Python buffer objects and numpy arrays +----------------------------------------------------------- + +Support for negative strides required changing the integer type from unsigned +to signed in the interfaces of ``py::buffer_info`` and ``py::array``. If you +have compiler warnings enabled, you may notice some new conversion warnings +after upgrading. These can be resolved using ``static_cast``. + + +Deprecation of some ``py::object`` APIs +--------------------------------------- + +To compare ``py::object`` instances by pointer, you should now use +``obj1.is(obj2)`` which is equivalent to ``obj1 is obj2`` in Python. +Previously, pybind11 used ``operator==`` for this (``obj1 == obj2``), but +that could be confusing and is now deprecated (so that it can eventually +be replaced with proper rich object comparison in a future release). + +For classes which inherit from ``py::object``, ``borrowed`` and ``stolen`` +were previously available as protected constructor tags. Now the types +should be used directly instead: ``borrowed_t{}`` and ``stolen_t{}`` +(`#771 <https://github.com/pybind/pybind11/pull/771>`_). + + +Stricter compile-time error checking +------------------------------------ + +Some error checks have been moved from run time to compile time. Notably, +automatic conversion of ``std::shared_ptr<T>`` is not possible when ``T`` is +not directly registered with ``py::class_<T>`` (e.g. ``std::shared_ptr<int>`` +or ``std::shared_ptr<std::vector<T>>`` are not automatically convertible). +Attempting to bind a function with such arguments now results in a compile-time +error instead of waiting to fail at run time. + +``py::init<...>()`` constructor definitions are also stricter and now prevent +bindings which could cause unexpected behavior: + +.. code-block:: cpp + + struct Example { + Example(int &); + }; + + py::class_<Example>(m, "Example") + .def(py::init<int &>()); // OK, exact match + // .def(py::init<int>()); // compile-time error, mismatch + +A non-``const`` lvalue reference is not allowed to bind to an rvalue. However, +note that a constructor taking ``const T &`` can still be registered using +``py::init<T>()`` because a ``const`` lvalue reference can bind to an rvalue. + +v2.1 +==== + +Minimum compiler versions are enforced at compile time +------------------------------------------------------ + +The minimums also apply to v2.0 but the check is now explicit and a compile-time +error is raised if the compiler does not meet the requirements: + +* GCC >= 4.8 +* clang >= 3.3 (appleclang >= 5.0) +* MSVC >= 2015u3 +* Intel C++ >= 15.0 + + +The ``py::metaclass`` attribute is not required for static properties +--------------------------------------------------------------------- + +Binding classes with static properties is now possible by default. The +zero-parameter version of ``py::metaclass()`` is deprecated. However, a new +one-parameter ``py::metaclass(python_type)`` version was added for rare +cases when a custom metaclass is needed to override pybind11's default. + +.. code-block:: cpp + + // old -- emits a deprecation warning + py::class_<Foo>(m, "Foo", py::metaclass()) + .def_property_readonly_static("foo", ...); + + // new -- static properties work without the attribute + py::class_<Foo>(m, "Foo") + .def_property_readonly_static("foo", ...); + + // new -- advanced feature, override pybind11's default metaclass + py::class_<Bar>(m, "Bar", py::metaclass(custom_python_type)) + ... + + +v2.0 +==== + +Breaking changes in ``py::class_`` +---------------------------------- + +These changes were necessary to make type definitions in pybind11 +future-proof, to support PyPy via its ``cpyext`` mechanism (`#527 +<https://github.com/pybind/pybind11/pull/527>`_), and to improve efficiency +(`rev. 86d825 <https://github.com/pybind/pybind11/commit/86d825>`_). + +1. Declarations of types that provide access via the buffer protocol must + now include the ``py::buffer_protocol()`` annotation as an argument to + the ``py::class_`` constructor. + + .. code-block:: cpp + + py::class_<Matrix>("Matrix", py::buffer_protocol()) + .def(py::init<...>()) + .def_buffer(...); + +2. Classes which include static properties (e.g. ``def_readwrite_static()``) + must now include the ``py::metaclass()`` attribute. Note: this requirement + has since been removed in v2.1. If you're upgrading from 1.x, it's + recommended to skip directly to v2.1 or newer. + +3. This version of pybind11 uses a redesigned mechanism for instantiating + trampoline classes that are used to override virtual methods from within + Python. This led to the following user-visible syntax change: + + .. code-block:: cpp + + // old v1.x syntax + py::class_<TrampolineClass>("MyClass") + .alias<MyClass>() + ... + + // new v2.x syntax + py::class_<MyClass, TrampolineClass>("MyClass") + ... + + Importantly, both the original and the trampoline class are now specified + as arguments to the ``py::class_`` template, and the ``alias<..>()`` call + is gone. The new scheme has zero overhead in cases when Python doesn't + override any functions of the underlying C++ class. + `rev. 86d825 <https://github.com/pybind/pybind11/commit/86d825>`_. + + The class type must be the first template argument given to ``py::class_`` + while the trampoline can be mixed in arbitrary order with other arguments + (see the following section). + + +Deprecation of the ``py::base<T>()`` attribute +---------------------------------------------- + +``py::base<T>()`` was deprecated in favor of specifying ``T`` as a template +argument to ``py::class_``. This new syntax also supports multiple inheritance. +Note that, while the type being exported must be the first argument in the +``py::class_<Class, ...>`` template, the order of the following types (bases, +holder and/or trampoline) is not important. + +.. code-block:: cpp + + // old v1.x + py::class_<Derived>("Derived", py::base<Base>()); + + // new v2.x + py::class_<Derived, Base>("Derived"); + + // new -- multiple inheritance + py::class_<Derived, Base1, Base2>("Derived"); + + // new -- apart from `Derived` the argument order can be arbitrary + py::class_<Derived, Base1, Holder, Base2, Trampoline>("Derived"); + + +Out-of-the-box support for ``std::shared_ptr`` +---------------------------------------------- + +The relevant type caster is now built in, so it's no longer necessary to +include a declaration of the form: + +.. code-block:: cpp + + PYBIND11_DECLARE_HOLDER_TYPE(T, std::shared_ptr<T>) + +Continuing to do so won’t cause an error or even a deprecation warning, +but it's completely redundant. + + +Deprecation of a few ``py::object`` APIs +---------------------------------------- + +All of the old-style calls emit deprecation warnings. + ++---------------------------------------+---------------------------------------------+ +| Old syntax | New syntax | ++=======================================+=============================================+ +| ``obj.call(args...)`` | ``obj(args...)`` | ++---------------------------------------+---------------------------------------------+ +| ``obj.str()`` | ``py::str(obj)`` | ++---------------------------------------+---------------------------------------------+ +| ``auto l = py::list(obj); l.check()`` | ``py::isinstance<py::list>(obj)`` | ++---------------------------------------+---------------------------------------------+ +| ``py::object(ptr, true)`` | ``py::reinterpret_borrow<py::object>(ptr)`` | ++---------------------------------------+---------------------------------------------+ +| ``py::object(ptr, false)`` | ``py::reinterpret_steal<py::object>(ptr)`` | ++---------------------------------------+---------------------------------------------+ +| ``if (obj.attr("foo"))`` | ``if (py::hasattr(obj, "foo"))`` | ++---------------------------------------+---------------------------------------------+ +| ``if (obj["bar"])`` | ``if (obj.contains("bar"))`` | ++---------------------------------------+---------------------------------------------+ |
