Expanded 02_basic with more access examples

examples/2_basic/main.cpp

@@ -15,14 +15,38 @@ int main()
 {
 	stored::ExampleBasic e;
 
-	// Initialized value.
+	// Initialized value:
 	printf("test42=%" PRId8 "\n", e.test42.get());
 
 	// The thing with the space around the =
 	printf("_42_test42=%" PRId8 "\n", e._42_test42.get());
 
-	// The initialized array element.
-	printf("three ints[1]=%" PRId16 "\n", e.three_ints_1.get());
+	// The initialized array element:
+	printf("three ints[0]=%" PRId16 "\n", e.three_ints_0.get());
+
+	// Next element through array-like access:
+	printf("three ints[1]=%" PRId16 "\n", e.three_ints_a(1).get<int16_t>());
+
+	// An initialized string:
+	char txt[8];
+	e.string_hello.get(txt, 8);
+	printf("string hello='%s'\n", txt);
+
+	// Change a value by direct assignment:
+	e.f = 3.14F;
+
+	// Or using a setter:
+	e.d.set(2.718);
+
+	// Same for array elements (which are really just variables):
+	e.four_ints_0 = 66;
+
+	// Or through the array accessor:
+	e.four_ints_a(1).set(67);
+
+	// Write to array with:
+	const char new_txt[] = "apples";
+	e.string_hello.set(new_txt, sizeof(new_txt));
 
 	return 0;
 }

sphinx/doc/cpp.rst

@@ -5,6 +5,8 @@
 
    SPDX-License-Identifier: CC-BY-4.0
 
+.. _Cpp:
+
 C++
 ===
 

sphinx/doc/examples.rst

@@ -5,6 +5,8 @@
 
    SPDX-License-Identifier: CC-BY-4.0
 
+.. _Examples:
+
 Examples
 ========
 

sphinx/doc/usage.rst

@@ -0,0 +1,72 @@
+..
+   SPDX-FileCopyrightText: 2020-2023 Jochem Rutgers
+
+   SPDX-License-Identifier: CC-BY-4.0
+
+Usage
+=====
+
+On this page follow some notes on how to use `libstored` in your application.
+
+Consider also the listed :ref:`Examples` and the :ref:`Cpp` API.
+
+
+Store Access
+------------
+
+Store :cpp:class:`variables <stored::Variable>` can be read or set directly most of the time.
+There is also the :cpp:func:`~stored::Variable::get` and :cpp:func:`~stored::Variable::set` methods.
+
+.. code-block::
+
+   // Store definition
+   uint32     my integer
+
+.. code-block:: cpp
+
+   store.my_integer = 1;
+   // ...implies:
+   store.my_integer.set(1);
+
+   unsigned int x;
+   x = store.my_integer;
+   // ...implies:
+   x = store.my_integer.get();
+
+
+Arrays
+^^^^^^
+
+Array elements appear as regular flat variables after code generation, with the addition of an extra ``_a(int)`` method.
+This accessor provides element access based on a variable index:
+
+.. code-block::
+
+   // Store definition
+   bool[10]     my array
+
+.. code-block:: cpp
+
+   store.my_array_a(0).set(true);
+   bool value = store.my_array_a(1).get();
+
+Strings
+^^^^^^^
+
+Strings (and blobs) cannot be set or retrieved through regular assignment, but require the buffered accessors: :cpp:func:`~size_t stored::Variant::get(void*, size_t) const` and :cpp:func:`~size_t stored::Variant::set(void const*, size_t)`.
+
+Note that store strings end with a null-terminator.
+And when reading from a store string to a local buffer it will stop on the first null-terminator it encounters.
+
+.. code-block::
+
+   // Store definition
+   string:16     my string
+
+.. code-block:: cpp
+
+   char txt[16];
+   store.my_string.get(txt, 16);
+
+   const char new_txt[16] = "hi again";
+   store.my_string.set(new_txt, 16);

sphinx/index.rst

@@ -19,6 +19,7 @@ debug it remotely.
    CHANGELOG <doc/changelog>
    Presentation <https://demcon.github.io/libstored/libstored.sozi.html>
    doc/workflow
+   doc/usage
    doc/cpp
    doc/fpga
    doc/py