String conversion utilities: the :f:mod:`yaml_strings` module
=============================================================

The :f:mod:`yaml_strings` module provides the portable scalar/array
value-to-string converters used throughout Futile and BigDFT, together with
the ``f_string`` deferred-length container, the ``//`` and ``+`` string/number
concatenation operators, case-insensitive equivalence, and low-level buffer
helpers.

Ordinary client code reaches these routines by writing::

   use yaml_strings

All conversion routines are grouped behind the generic :f:func:`yaml_toa`
interface, which now covers every public ABI kind from :f:mod:`f_precisions`:
``f_int8``, ``f_short``, ``f_integer``, ``f_long`` for integers, ``f_simple``,
``f_double``, ``f_long_double`` for reals, plus characters, logicals and
complex values, with matching 1-D array overloads.  The generic :f:func:`cnv_fmt`
returns the default write format for each kind and drives the conversion.

Value-to-string conversion
--------------------------

The :f:func:`yaml_toa` interface is documented from source with an
``f:autogroup`` block covering the scalar and array converters.  The routines
render values following the YAML scalar conventions of the module; array
overloads render a bracketed ``[ a, b, c ]`` sequence.

.. f:automodule:: yaml_strings
   :members: yaml_toa, cnv_fmt, f_string, YAML_INFINITY

The newly added kind overloads are documented directly in the Fortran source,
with ``fortranliteral`` directives pointing at the CI-compiled examples.

String/number operators
-----------------------

The ``//`` and ``+`` operators concatenate a character or :f:type:`f_string`
with a numeric value of any supported kind, delegating to :f:func:`yaml_toa`
for the conversion.  The ``**`` operator applies an explicit format string to a
value.

.. f:automodule:: yaml_strings
   :members: operator(//), operator(+), operator(**), assignment(=)

String utilities
----------------

Case-insensitive comparison, copying, shifting and alignment helpers:

.. f:automodule:: yaml_strings
   :members: f_strcpy, operator(.eqv.), operator(.neqv.), rstrip, shiftstr, buffer_string, align_message

Parsing helpers
---------------

.. f:automodule:: yaml_strings
   :members: is_atoi, is_atof, is_atol, is_atoli, read_fraction_string

Terminal and C-interop helpers
------------------------------

.. f:automodule:: yaml_strings
   :members: yaml_bold, yaml_blink, yaml_date_toa, yaml_date_and_time_toa, yaml_time_toa, f_char_ptr, convert_f_char_ptr

Examples
--------

The examples below are rendered from ``fortranliteral`` directives placed in
the Fortran source comments next to each public routine.  They are drawn from
the CI-compiled program ``tests/flib/yaml_strings_examples.f90``, so the
rendered documentation and the tested behaviour stay synchronized.

Documentation coverage
-----------------------

The CI documentation contract for this page mirrors the one described for
:f:mod:`f_precisions` and checks three complementary notions of coverage:

``symbol coverage``
   Every expected public ``yaml_strings`` entry must appear in the rendered
   HTML page.  This catches missing converters or operators when the parser or
   the source changes.

``topic coverage``
   Required explanatory topics must also appear in the rendered page.  For the
   yaml_strings page these cover the ``use yaml_strings`` entry point, the
   ``yaml_toa`` generic family, the ``cnv_fmt`` format selector, the string
   operators, parsing helpers, and the ``fortranliteral`` example machinery.

``example coverage``
   Public helpers include examples with ``fortranliteral`` directives taken
   from executable code under ``tests/``.  The same code is compiled and run by
   CI, so the rendered documentation cannot silently drift away from tested
   API behaviour.

The coverage check lives in ``doc/check_yaml_strings_public_api.py`` and should
be extended whenever a new public yaml_strings routine is added.

.. f:currentmodule::