From f8a59da9c492b7df38f53ba96505313e931d76cc Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Sun, 28 Mar 2021 13:42:35 -0400
Subject: Add high-level documentation

---
 doc/c/string_views.rst | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 58 insertions(+)
 create mode 100644 doc/c/string_views.rst

(limited to 'doc/c/string_views.rst')

diff --git a/doc/c/string_views.rst b/doc/c/string_views.rst
new file mode 100644
index 00000000..2ae7d29b
--- /dev/null
+++ b/doc/c/string_views.rst
@@ -0,0 +1,58 @@
+String Views
+============
+
+.. default-domain:: c
+.. highlight:: c
+
+For performance reasons,
+most functions in serd that take a string take a :struct:`SerdStringView`,
+rather than a bare pointer.
+This forces code to be explicit about string measurement,
+which discourages common patterns of repeated measurement of the same string.
+For convenience, several macros are provided for constructing string views:
+
+:macro:`SERD_EMPTY_STRING`
+
+   Constructs a view of an empty string, for example:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin make-empty-string
+      :end-before: end make-empty-string
+      :dedent: 2
+
+:macro:`SERD_STRING`
+
+   Constructs a view of an entire string or string literal, for example:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin make-static-string
+      :end-before: end make-static-string
+      :dedent: 2
+
+   or:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin measure-string
+      :end-before: end measure-string
+      :dedent: 2
+
+   This macro calls ``strlen`` to measure the string.
+   Modern compilers will optimise this away if the parameter is a string literal.
+
+:macro:`SERD_SUBSTRING`
+
+   Constructs a view of a slice of a string with an explicit length,
+   for example:
+
+   .. literalinclude:: overview_code.c
+      :start-after: begin make-string-view
+      :end-before: end make-string-view
+      :dedent: 2
+
+   This macro can also be used to create a view of a pre-measured string.
+   If the length a dynamic string is already known,
+   it is faster to use this than :macro:`SERD_STRING`.
+
+These macros can be used inline when passing parameters,
+but if the same dynamic string is used several times,
+it is better to make a string view variable to avoid redundant measurement.
-- 
cgit v1.2.1