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.
+