diff --git a/examples/2_basic/main.cpp b/examples/2_basic/main.cpp index e80b3231..28e44bee 100644 --- a/examples/2_basic/main.cpp +++ b/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()); + + // 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; } diff --git a/sphinx/doc/cpp.rst b/sphinx/doc/cpp.rst index 7c97a5da..bddf530f 100644 --- a/sphinx/doc/cpp.rst +++ b/sphinx/doc/cpp.rst @@ -5,6 +5,8 @@ SPDX-License-Identifier: CC-BY-4.0 +.. _Cpp: + C++ === diff --git a/sphinx/doc/examples.rst b/sphinx/doc/examples.rst index 5f84ee24..40afbd8a 100644 --- a/sphinx/doc/examples.rst +++ b/sphinx/doc/examples.rst @@ -5,6 +5,8 @@ SPDX-License-Identifier: CC-BY-4.0 +.. _Examples: + Examples ======== diff --git a/sphinx/doc/usage.rst b/sphinx/doc/usage.rst new file mode 100644 index 00000000..e11cd54d --- /dev/null +++ b/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 ` 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); diff --git a/sphinx/index.rst b/sphinx/index.rst index 867eba3b..943a9871 100644 --- a/sphinx/index.rst +++ b/sphinx/index.rst @@ -19,6 +19,7 @@ debug it remotely. CHANGELOG Presentation doc/workflow + doc/usage doc/cpp doc/fpga doc/py