diff options
author | David Robillard <d@drobilla.net> | 2018-06-16 10:26:47 -0400 |
---|---|---|
committer | David Robillard <d@drobilla.net> | 2023-12-02 18:49:08 -0500 |
commit | 8fb8b922fb7575d7aed2f2184a02586b56ba873a (patch) | |
tree | 06ea3a48cefb5cb221359b17911380460e68e7c8 /bindings/cpp/doc/cpp_facilities.rst | |
parent | 74ddf7934336f16dcdce688333040d82972817fc (diff) | |
download | serd-8fb8b922fb7575d7aed2f2184a02586b56ba873a.tar.gz serd-8fb8b922fb7575d7aed2f2184a02586b56ba873a.tar.bz2 serd-8fb8b922fb7575d7aed2f2184a02586b56ba873a.zip |
[WIP] Add C++ bindings
Diffstat (limited to 'bindings/cpp/doc/cpp_facilities.rst')
-rw-r--r-- | bindings/cpp/doc/cpp_facilities.rst | 53 |
1 files changed, 53 insertions, 0 deletions
diff --git a/bindings/cpp/doc/cpp_facilities.rst b/bindings/cpp/doc/cpp_facilities.rst new file mode 100644 index 00000000..53b8704d --- /dev/null +++ b/bindings/cpp/doc/cpp_facilities.rst @@ -0,0 +1,53 @@ +C++ Facilities +============== + +.. default-domain:: cpp +.. highlight:: cpp +.. namespace:: serd + +String Views +------------ + +For performance reasons, +most functions that take a string take a :type:`StringView`. +This allows many types of string to be passed as an argument, +and redundant string measurement to be avoided. + +:type:`StringView` works similarly to ``std::string_view`` (and will likely be removed when C++17 support is more widespread). +A :type:`StringView` parameter will accept a string literal, +dynamic C string, +or a ``std::string`` as an argument. +Note, however, that the constructor that takes only a ``const char*`` calls ``strlen`` to measure the string, +so care should be taken to avoid this in performance-critical code if the string length is already known. + +Optionals +--------- + +Several places in the C API take or return a pointer that may be null. +This is wrapped more safely in the C++ API as an :class:`Optional`. + +From a user perspective, :class:`Optional` works similarly to ``std::optional``, +with pointer-like access operators and explicit boolean conversion enabling code like: + +.. code-block:: cpp + + if (optional_value) { + use_value(*optional_value); + } + +or: + +.. code-block:: cpp + + if (optional_object) { + optional_object->do_something(); + } + +The :class:`Optional` implementation is serd-specific, +and takes advantage of the fact that the contained object is really just a "fancy pointer". +This means that null can be used to represent an unset value, +avoiding the space overhead of more general types like ``std::optional``. + +A pointer to the underlying C object can be retrieved with the :func:`~Optional::cobj` method, +which will return null if the optional is unset. + |