xo-flatstring: + README + docs + test coverage

docs/CMakeLists.txt

@@ -0,0 +1,110 @@
+# xo-stringliteral/docs/CMakeLists.txt
+
+if (XO_SUBMODULE_BUILD)
+    # in submodule build, rely on toplevel docs/CMakeLists.txt file instead
+else()
+    # build docs starting from here only in standalone build.
+    # otherwise use top-level doxygen setup instead.
+
+    set(ALL_LIBRARY_TARGETS xo_stringliteral)  # todo: automate this from xo-cmake macros
+    set(ALL_UTEST_TARGETS xo_stringliteral_ex1 ) # todo: automate this from xo-cmake macros
+
+    # look for doxygen executable
+    find_program(DOXYGEN_EXECUTABLE NAMES doxygen REQUIRED)
+    message("-- DOXYGEN_EXECUTABLE=${DOXYGEN_EXECUTABLE}")
+
+    # look for sphinx-build executable
+    find_program(SPHINX_EXECUTABLE NAMES sphinx-build REQUIRED)
+    message("-- SPHINX_EXECUTABLE=${SPHINX_EXECUTABLE}")
+
+    set(DOX_CONFIG_FILE ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile)
+
+    set(DOX_INPUT_DIR ${PROJECT_SOURCE_DIR})
+    set(DOX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/dox)
+
+    set(DOX_INDEX_FILE ${DOX_OUTPUT_DIR}/html/index.html)
+
+    # .hpp files reachable from xo-stringliteral/include
+    #
+    # REMINDER: for reliability will need to re-run cmake when the set of .hpp files changes
+    #
+    file(GLOB_RECURSE DOX_HPP_FILES_GLOB ${PROJECT_SOURCE_DIR}/include *.hpp)
+
+    set(SPHINX_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/sphinx/html)
+    set(SPHINX_INDEX_FILE ${SPHINX_OUTPUT_DIR}/index.html)
+    #
+    # sphinx .rst files reachable from cmake-examples/docs
+    #
+    # REMINDER: for reliability will need to re-run cmake when the set of .rst files changes
+    #
+    file(GLOB_RECURSE SPHINX_RST_FILES_GLOB ${CMAKE_CURRENT_SOURCE_DIR} *.rst)
+
+    set(SPHINX_RST_FILES index.rst install.rst lessons.rst flatstring-reference.rst flatstring-class.rst)
+
+    # TODO:
+    # 1. move Doxyfile.in to xo-cmake project
+    # 2. replace this command section with xo-cmake macro
+    #
+    configure_file(
+        Doxyfile.in ${DOX_CONFIG_FILE}
+        FILE_PERMISSIONS OWNER_READ OWNER_EXECUTE GROUP_READ GROUP_EXECUTE WORLD_READ WORLD_EXECUTE
+        @ONLY)
+
+    set(DOX_DEPS ${ALL_LIBRARY_TARGETS} ${ALL_UTEST_TARGETS} ${DOX_HPP_FILES_GLOB})
+
+    file(MAKE_DIRECTORY ${DOX_OUTPUT_DIR})
+    add_custom_command(
+        OUTPUT ${DOX_INDEX_FILE}
+        DEPENDS ${DOX_DEPS}
+        COMMAND "${DOXYGEN_EXECUTABLE}" ${DOX_CONFIG_FILE}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        MAIN_DEPENDENCY ${DOX_CONFIG_FILE}
+        COMMENT "Generating docs (doxygen)")
+
+    # To build this target
+    #   $ cmake --build .build -j -- doxygen
+    # or
+    #   $ cd .build
+    #   $ make doxygen
+    #
+    add_custom_target(
+        doxygen
+        DEPENDS ${DOX_INDEX_FILE} ${DOX_DEPS}
+    )
+
+    # root of sphinx doc tree
+    set(SPHINX_SOURCE ${CMAKE_CURRENT_SOURCE_DIR})
+    set(SPHINX_DEPS doxygen conf.py ${SPHINX_RST_FILES} ${SPHINX_RST_FILES_GLOB} ${DOX_DEPS})
+
+    add_custom_command(
+        OUTPUT ${SPHINX_INDEX_FILE}
+        DEPENDS ${SPHINX_DEPS}
+        COMMAND ${SPHINX_EXECUTABLE}
+        -b html -Dbreathe_projects.xodoxxml=${CMAKE_CURRENT_BINARY_DIR}/dox/xml
+        ${SPHINX_SOURCE} ${SPHINX_OUTPUT_DIR}
+        WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
+        COMMENT "Generating docs (sphinx) -> [${SPHINX_OUTPUT_DIR}]")
+
+    # make sphinx --> generate sphinx documentation
+    #
+    add_custom_target(
+        sphinx
+        DEPENDS ${SPHINX_INDEX_FILE})
+
+    # - html docs generated in build/docs/sphinx
+    # - copy the doc tree to share/doc/xo_unit/html
+    #
+    #  OPTIONAL:    install directory tree if it exists,
+    #               but don't complain if it's missing
+    install(
+        DIRECTORY ${SPHINX_OUTPUT_DIR}
+        FILE_PERMISSIONS OWNER_READ GROUP_READ WORLD_READ
+        DESTINATION ${CMAKE_INSTALL_PREFIX}/share/doc/${PROJECT_NAME}
+        COMPONENT Documentation
+        OPTIONAL)
+
+    # make docs --> generate sphinx documentation
+    add_custom_target(
+        docs
+        DEPENDS sphinx)
+endif()

docs/_static/README

@@ -0,0 +1 @@
+add any static {.html, .js, ..} files for sphinx to pickup here

docs/conf.py

@@ -0,0 +1,35 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'xo stringlit documentation'
+copyright = '2024, Roland Conybeare'
+author = 'Roland Conybeare'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+#extensions = []
+extensions = [ "breathe",
+               "sphinx.ext.autodoc"  # generate info from docstrings
+              ]
+
+# note: breathe requires doxygen xml output -> must have GENERATE_XML = YES in Doxyfile.in
+#       match project name in Doxyfile.in
+breathe_default_project = "xodoxxml"
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+pygments_style = 'sphinx'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']

docs/flatstring-class.rst

@@ -0,0 +1,60 @@
+.. _flatstring-class:
+
+Flatstring
+==========
+
+.. code-block:: cpp
+
+    #include <xo/flatstring/flatstring.hpp>
+
+A ``flatstring`` is a thin wrapper around a character array.
+
+.. doxygenclass:: xo::flatstring
+
+Instance Variables
+------------------
+
+.. doxygengroup:: flatstring-instance-variables
+    :content-only:
+
+Constants
+---------
+
+.. doxygengroup:: flatstring-constants
+    :content-only:
+
+Constructors
+------------
+
+.. doxygengroup:: flatstring-ctor
+    :content-only:
+
+Properties
+----------
+
+.. doxygengroup:: flatstring-properties
+    :content-only:
+
+Access Methods
+--------------
+
+.. doxygengroup:: flatstring-access
+    :content-only:
+
+Iterators
+---------
+
+.. doxygengroup:: flatstring-iterators
+    :content-only:
+
+Assignment
+----------
+
+.. doxygengroup:: flatstring-assign
+    :content-only:
+
+Conversion
+----------
+
+.. doxygengroup:: flatstring-conversion-operators
+    :content-only:

docs/flatstring-functions.rst

@@ -0,0 +1,15 @@
+.. _flatstring_functions:
+
+.. toctree::
+   :maxdepth: 2
+
+Flatstring Functions
+====================
+
+.. code-block:: cpp
+
+    #include <xo/flatstring/flatstring.hpp>
+
+.. doxygenfunction:: xo::flatstring_concat
+
+.. doxygenfunction:: xo::flatstring_compare

docs/flatstring-reference.rst

@@ -0,0 +1,11 @@
+.. _flatstring-reference:
+
+Flatstring Reference
+====================
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Flatstring Reference
+
+   flatstring-class
+   flatstring-functions

docs/index.rst

@@ -0,0 +1,38 @@
+xo-flatstring documentation master file
+
+xo-flatstring documentation
+===========================
+
+xo-flatstring is a lightweight header-only library that provides a constexpr
+fixed-size no-allocation string implementation.
+
+Why ``flatstring``?
+
+1.  ``flatstring`` instances can be used as template arguments. [1]_
+
+2.  ``flatstring`` operations (construction, concatenation, ...) are ``constexpr``, so can be done at compile time. [2]_
+
+3.  a ``flatstring`` expression can occupy both compile-time and runtime roles. [3]_
+
+.. [1] A fixed-size char array *can* be used as a template
+    argument,  but char* pointers cannot. Automatic conversion of char arrays to pointers in various contexts
+    makes them difficult to work with in c++ templates.
+
+.. [2] Although allocation is permitted in constexpr code, it's subject to several restrictions.
+    it's not yet possible (as of c++23) to use ``std::string`` at compile time.
+
+.. [3] contrast with a solution relying on template arguments, which must then be compile-time-only.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: xo-flatstring contents:
+
+   install
+   lessons
+   flatstring-reference
+
+Indices and Tables
+------------------
+
+* :ref:`genindex`
+* :ref:`search`

docs/install.rst

@@ -0,0 +1,56 @@
+.. _install:
+
+.. toctree
+   :maxdepth: 2
+
+Install
+=======
+
+`xo-flatstring source`_ lives on github.
+
+.. _xo-flatstring source: https://github.com/rconybea/xo-flatstring
+
+Implementation relies on c++20 features (for example class-instances as template arguments).
+Tested with gcc 13.2
+
+Include as submodule
+--------------------
+
+.. code-block:: bash
+
+   cd myproject
+   git submodule add -b main https://github.com/rconybea/xo-flatstring ext/xo-flatstring
+   git submodule update --init
+
+This assumes you organize directly-incorporated dependencies under directory ``myproject/ext``.
+You would then add ``myproject/ext/xo-flatstring/include`` to your compiler's include path,
+and from c++ do something like
+
+.. code-block:: c++
+
+   #include <xo/flatstring/flatstring.hpp>
+
+in c++ source files that rely on xo-flatstring
+
+Supported compilers
+-------------------
+
+* developed with gcc 13.2.0;  github CI using gcc 11.4.0 (asof April 2024)
+
+Building from source
+--------------------
+
+Although the xo-flatstring library is header-only, unit tests have some dependencies.
+Example instructions (github CI) for build starting from stock ubuntu are in `ubuntu-main.yml`_
+
+.. _ubuntu-main.yml: https://github.com/Rconybea/xo-flatstring/blob/main/.github/workflows/ubuntu-main.yml
+
+Unit test dependencies:
+
+* `catch2`_ header-only unit-test framework
+* `xo-cmake`_ cmake macros
+* `xo-indentlog`_ logging with call-structure indenting
+
+.. _catch2: https://github.com/catchorg/Catch2
+.. _xo-cmake: https://github.com/rconybea/xo-cmake
+.. _xo-indentlog: https://github.com/rconybea/indentlog

docs/lessons.rst

@@ -0,0 +1,44 @@
+.. _lessons:
+
+.. toctree
+   :maxdepth: 2
+
+Lessons
+=======
+
+This is a rogue's gallery of experiments,  typically unsuccessful.
+One hurdle we've created for ourselves, is we need both gcc and clang to agree
+that an expression can be computed at compile-time;
+otherwise will get false alarms in our IDE (raised by LSP running in the background, which relies on clang).
+
+Must Fully Initialize Memory
+----------------------------
+
+Struggled for a while with the implementation of :ref:xo::flatstring_concat
+
+.. code-block:: cpp
+
+    template <std::size_t N>
+    flatstring::flatstring<N>() {
+        if (N > 0)
+            value_[0] = '\0';
+    }
+
+
+This implementation satisfies gcc, but not clang: in the following snippet, clang doesn't recognize ``tmp`` as constexpr:
+
+.. code-block:: cpp
+
+    constexpr n = ...;
+    flatstring<n> tmp;
+
+    static_assert(tmp.size() == ...);    // tmp not constexpr!
+
+Correction is to prove to clang that every memory address owned by an empty ``flatstring`` is initialized:
+
+.. code-block:: cpp
+
+    template <std::size_t N>
+    flatstring::flatstring<N>() {
+        std::fill_n(value_, N, '\0');
+    }