String conversion utilities: the yaml_strings module

The 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 yaml_toa() interface, which now covers every public ABI kind from 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 cnv_fmt() returns the default write format for each kind and drives the conversion.

Value-to-string conversion

The 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.

Quick access

Types:

f_string

Routines:

yaml_toa()

Needed modules

  • f_precisions: Defines the portable Futile kind policy, undefined sentinels, precision conversion helpers, and low-level address inquiry helpers. Host codes should use these names instead of compiler-specific kind

Types

  • type  yaml_strings/f_string
    Type fields:

    • % msg [character(len=4*max_value_length)]

Subroutines and functions

interface  yaml_strings/yaml_toa()

Convert a supported Futile intrinsic value to its YAML string representation.

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_string with a numeric value of any supported kind, delegating to yaml_toa() for the conversion. The ** operator applies an explicit format string to a value.

Quick access

Routines:

operator(**)()

Needed modules

  • f_precisions: Defines the portable Futile kind policy, undefined sentinels, precision conversion helpers, and low-level address inquiry helpers. Host codes should use these names instead of compiler-specific kind

Subroutines and functions

interface  yaml_strings/operator(//)()
interface  yaml_strings/operator(+)()
interface  yaml_strings/assignment(=)()
interface  yaml_strings/operator(**)()

String utilities

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

Quick access

Routines:

align_message(), buffer_string(), f_strcpy(), operator(.eqv.)(), operator(.neqv.)(), rstrip(), shiftstr()

Needed modules

  • f_precisions: Defines the portable Futile kind policy, undefined sentinels, precision conversion helpers, and low-level address inquiry helpers. Host codes should use these names instead of compiler-specific kind

Subroutines and functions

interface  yaml_strings/f_strcpy(dest, src)
Parameters:

  • dest [character(len=*), out]

  • src [character(len=*), in]

interface  yaml_strings/operator(.eqv.)()
interface  yaml_strings/operator(.neqv.)()
subroutine  yaml_strings/f_strcpy(dest, src)
Parameters:

  • dest [character(len=*), out]

  • src [character(len=*), in]

subroutine  yaml_strings/buffer_string(string_bn, string_lgt, buffer, string_pos[, back, istat])
Parameters:

  • string_bn [character(len=string_lgt), inout]

  • string_lgt [integer, in] :: < Length of the string towrite

  • buffer [character(len=*), in] :: < Buffer to add

  • string_pos [integer, inout] :: < Position to add buffer into string and for the next.

Options:

  • back [logical, in,] :: < Add string from the end

  • istat [integer, out,] :: no errors

Call to:

shiftstr()

subroutine  yaml_strings/align_message(rigid, maxlen, tabval, anchor, message)
Parameters:

  • rigid [logical, in]

  • maxlen [integer, in]

  • tabval [integer, in]

  • anchor [character(len=*), in]

  • message [character(len=maxlen), inout]

Call to:

shiftstr()

subroutine  yaml_strings/rstrip(string_bn, substring)
Parameters:

  • string_bn [character(len=*), inout]

  • substring [character(len=*), in]

subroutine  yaml_strings/shiftstr(str, n)
Parameters:

  • str [character(len=*), inout]

  • n [integer, in]

Called from:

buffer_string(), align_message()

Parsing helpers

Quick access

Routines:

is_atof(), is_atoi(), is_atol(), is_atoli(), read_fraction_string()

Needed modules

  • f_precisions: Defines the portable Futile kind policy, undefined sentinels, precision conversion helpers, and low-level address inquiry helpers. Host codes should use these names instead of compiler-specific kind

Subroutines and functions

function  yaml_strings/is_atoi(str)
Parameters:

str [character(len=*), in]

Return:

yes [logical]

function  yaml_strings/is_atoli(str)
Parameters:

str [character(len=*), in]

Return:

yes [logical]

function  yaml_strings/is_atof(str)
Parameters:

str [character(len=*), in]

Return:

yes [logical]

function  yaml_strings/is_atol(str)
Parameters:

str [character(len=*), in]

Return:

yes [logical]

subroutine  yaml_strings/read_fraction_string(string_bn, var, ierror)
Parameters:

  • string_bn [character(len=*), in]

  • var [real, out]

  • ierror [integer, out]

Terminal and C-interop helpers

Quick access

Routines:

convert_f_char_ptr(), f_char_ptr(), yaml_blink(), yaml_bold(), yaml_date_and_time_toa(), yaml_date_toa(), yaml_time_toa()

Needed modules

  • f_precisions: Defines the portable Futile kind policy, undefined sentinels, precision conversion helpers, and low-level address inquiry helpers. Host codes should use these names instead of compiler-specific kind

Subroutines and functions

function  yaml_strings/yaml_bold(str)
Parameters:

str [character(len=*), in]

Return:

bstr [character(len=max_value_length)]

Parameters:

str [character(len=*), in]

Return:

bstr [character(len=max_value_length)]

function  yaml_strings/yaml_date_and_time_toa([values, zone])
Options:

  • values (8) [integer, in,]

  • zone [logical, in,]

Return:

yaml_date_and_time_toa [character(len=max_value_length)]

function  yaml_strings/yaml_date_toa([values])

Yaml Spaced format for Date

Options:

values (8) [integer, in,]

Return:

yaml_date_toa [character(len=max_value_length)]

function  yaml_strings/yaml_time_toa([values])
Options:

values (8) [integer, in,]

Return:

yaml_time_toa [character(len=max_value_length)]

function  yaml_strings/f_char_ptr(str)
Parameters:

str [character(len=*), in]

Return:

f_char_ptr (1 + len_trim(str) [character]

Called from:

f_char_ptr()

Call to:

f_char_ptr()

subroutine  yaml_strings/convert_f_char_ptr(src, dest)
Parameters:

  • src (*) [character, in]

  • dest [character(len=*), out]

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_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.