# index.md

<!-- futile documentation master file, created by
sphinx-quickstart on Tue Aug 21 16:29:15 2018.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive. -->

<a id="futile-index"></a>

# Welcome to futile’s documentation!

# Modules:

* [Control of the precision `f_precisions`](f_prec.md)
  * [Address inquiry](f_prec.md#address-inquiry)
  * [Precision helpers](f_prec.md#precision-helpers)
  * [Documentation coverage](f_prec.md#documentation-coverage)
* [Structured error handling: the `dictionaries` and `exception_callbacks` modules](errors.md)
  * [Raising and inspecting errors from `dictionaries`](errors.md#f/dictionaries)
  * [Callback and severe-error policy from `exception_callbacks`](errors.md#f/exception_callbacks)
  * [Examples](errors.md#examples)
  * [Documentation coverage](errors.md#documentation-coverage)
* [String conversion utilities: the `yaml_strings` module](yaml_strings.md)
  * [Value-to-string conversion](yaml_strings.md#f/yaml_strings)
  * [String/number operators](yaml_strings.md#f/yaml_strings)
  * [String utilities](yaml_strings.md#f/yaml_strings)
  * [Parsing helpers](yaml_strings.md#parsing-helpers)
  * [Terminal and C-interop helpers](yaml_strings.md#terminal-and-c-interop-helpers)
  * [Examples](yaml_strings.md#examples)
  * [Documentation coverage](yaml_strings.md#documentation-coverage)
* [Mapping and lists: the `dictionaries` module](yaml_str.md)
  * [Core storage and lifecycle API from `dictionaries_base`](yaml_str.md#f/dictionaries_base)
  * [High-level constructors and iterators from `dictionaries`](yaml_str.md#high-level-constructors-and-iterators-from-dictionaries)
  * [Constructor syntax](yaml_str.md#constructor-syntax)
  * [Examples from the Futile tests](yaml_str.md#examples-from-the-futile-tests)
* [Automatic definition of the input dictionary the `f_input_file` module](inputfile.md)
* [Memory handling](memory.md)
  * [Dynamic allocation / deallocation](memory.md#dynamic-allocation-deallocation)
  * [Memory initialisers](memory.md#memory-initialisers)
* [YAML handling](yaml.md)
  * [Automatic definition of arguments `yaml_parse`](yaml.md#automatic-definition-of-arguments-yaml-parse)
  * [YAML emitter in Fortran: the `yaml_output` module](yaml.md#yaml-emitter-in-fortran-the-yaml-output-module)
  * [Convenient string functions: the `yaml_strings` module](yaml.md#convenient-string-functions-the-yaml-strings-module)
* [Python modules](pyfutile.md)
  * [Utils module](pyfutile.md#module-futile.Utils)
  * [YamlIO module](pyfutile.md#module-futile.YamlIO)
  * [Inputvars module](pyfutile.md#module-futile.Inputvars)
  * [ArgParse module](pyfutile.md#module-futile.YamlArgparse)
  * [Figures module](pyfutile.md#module-futile.Figures)
  * [Time module](pyfutile.md#module-futile.Time)

# Indices and tables

* [Index](genindex.md)
* [Module Index](py-modindex.md)
* [Search Page](search.md)
* [Full Markdown documentation for LLM/skill consumers](futile-full.md)

## Continuous integration

[![image](https://gitlab.com/l_sim/futile/badges/devel/pipeline.svg)](https://gitlab.com/l_sim/futile/-/commits/devel)[![image](https://gitlab.com/l_sim/futile/badges/devel/coverage.svg)](https://l_sim.gitlab.io/futile/report)


# errors.md

# Structured error handling: the [`dictionaries`](yaml_str.md#f/dictionaries) and [`exception_callbacks`](errors.md#f/exception_callbacks) modules

Futile provides a single, structured error-handling API.  In ordinary client
code the public routines are reached by writing:

```default
use dictionaries
```

which re-exports the raising, inspection, try/catch and query routines together
with the dictionary types they operate on.  The callback and severe-error
policy routines are public through the companion module
[`exception_callbacks`](errors.md#f/exception_callbacks); when they are needed the explicit
`use exception_callbacks` line can be added.  The two modules are documented
separately below only to keep the source locations visible, but they describe
the same error pipeline and are meant to be used together.

## Raising and inspecting errors from [`dictionaries`](yaml_str.md#f/dictionaries)

The routines below are implemented in the `error_handling.f90` include file
and made public through [`dictionaries`](yaml_str.md#f/dictionaries).  Client code obtains them with
`use dictionaries`; a separate `use error_handling` is never needed.

### Description

High-level dictionary API used throughout Futile and BigDFT.  A dictionary
is a pointer-based tree that can represent scalars, ordered mappings, and
lists.  It maps directly to YAML data and is manipulated with constructors
such as dict_new and list_new, the // navigation operator, and set/add
routines.

This module use-associates dictionaries_base and re-exports its core public
routines and types, including dictionary, dict_init, dict_free, dict_len,
dict_size, dict_key, dict_item, and dict_value.  Client code should normally
write use dictionaries; a separate use dictionaries_base is needed only
for low-level code that intentionally avoids the higher-level dependencies.

### Quick access

* **Routines:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### Needed modules

- [`exception_callbacks`](errors.md#f/exception_callbacks)
- [`dictionaries_base`](yaml_str.md#f/dictionaries_base): Low-level dictionary storage and lifecycle routines.  Applications normally use the higher-level dictionaries module, which re-exports this public API.
- [`f_precisions`](f_prec.md#f/f_precisions) ([`f_address()`](f_prec.md#f/f_precisions/f_address), [`f_loc()`](f_prec.md#f/f_precisions/f_loc), [`f_double()`](f_prec.md#f/f_precisions/f_double)): 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
- [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`read_fraction_string()`](yaml_strings.md#f/yaml_strings/read_fraction_string), [`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy))

### Subroutines and functions

### *interface*  dictionaries/f_err_throw(message)

* **Options:**
  * **err_msg** *[**character(len=\*)* *,* *in,* *]* :: < error message
  * **err_id** *[**integer* *,* *in,* *]* :: < The code of the error to be raised.
  * **err_name** *[**character(len=\*)* *,* *in,* *]* :: < error name
  * **callback** *[**external* *]*
  * **callback_data** *[**integer* *,* *in,* *]* :: < ??? not really sure
* **Parameters:**
  **message** *[*[*f_string*](yaml_strings.md#f/yaml_strings/f_string) *,* *in* *]* :: < error message
* **Called from:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise)

### *interface*  dictionaries/f_err_raise(condition, err_msg)

* **Options:**
  * **condition** *[**logical* *,* *in,* *]* :: < the condition which raise the error
  * **err_msg** *[**character(len=\*)* *,* [*f_string*](yaml_strings.md#f/yaml_strings/f_string) *,* *in,* *]* :: < error message
  * **err_id** *[**integer* *,* *in,* *]* :: < the code of the error to be raised.
  * **err_name** *[**character(len=\*)* *,* *in,* *]* :: < error name
  * **callback** *[**external* *]* :: < action to be performed ???
  * **callback_data** *[**integer* *,* *in,* *]* :: < ??? not really sure

### *subroutine*  dictionaries/f_err_define(err_name, err_msg, err_id)

* **Parameters:**
  * **err_name** *[**character(len=\*)* *,* *in* *]*
  * **err_msg** *[**character(len=\*)* *,* *in* *]*
  * **err_id** *[**integer* *,* *out* *]*
* **Options:**
  * **err_action** *[**character(len=\*)* *,* *in,* *]*
  * **callback** *[**external* *]*
  * **callback_data** *[**integer* *,* *in,* *]*

### *function*  dictionaries/f_err_check()

* **Options:**
  * **err_id** *[**integer* *,* *in,* *]*
  * **err_name** *[**character(len=\*)* *,* *in,* *]*
* **Return:**
  **f_err_check** *[**logical* *]*

### *function*  dictionaries/f_err_raise()

* **Options:**
  * **condition** *[**logical* *,* *in,* *]*
  * **err_msg** *[**character(len=\*)* *,* *in,* *]*
  * **err_id** *[**integer* *,* *in,* *]*
  * **err_name** *[**character(len=\*)* *,* *in,* *]*
  * **callback** *[**external* *]*
  * **callback_data** *[**integer* *,* *in,* *]*
* **Return:**
  **f_err_raise** *[**logical* *]*
* **Use:** 
  [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa))

### *function*  dictionaries/f_get_error_dict()

* **Options:**
  **ierror** *[**integer* *,* *in,* *]*
* **Return:**
  **f_get_error_dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*

### *function*  dictionaries/f_get_no_of_errors()

* **Return:**
  **f_get_no_of_errors** *[**integer* *]*

### *function*  dictionaries/f_get_past_error(ierr_num)

* **Parameters:**
  **ierr_num** *[**integer* *,* *in* *]*
* **Options:**
  **add_msg** *[**character(len=\*)* *]*
* **Return:**
  **f_get_past_error** *[**integer* *]*

### *function*  dictionaries/f_get_last_error()

* **Options:**
  **add_msg** *[**character(len=\*)* *,* *out,* *]*
* **Return:**
  **f_get_last_error** *[**integer* *]*

### *subroutine*  dictionaries/f_err_clean()

### *function*  dictionaries/f_err_pop()

* **Options:**
  * **err_id** *[**integer* *,* *in,* *]*
  * **err_name** *[**character(len=\*)* *,* *in,* *]*
  * **add_msg** *[**character(len=\*)* *,* *out,* *]*
* **Return:**
  **f_err_pop** *[**integer* *]*

### *subroutine*  dictionaries/f_err_open_try()

### *subroutine*  dictionaries/f_err_close_try()

* **Options:**
  **exceptions** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *out,pointer* *]*

### *function*  dictionaries/f_err_trying()

* **Return:**
  **f_err_trying** *[**logical* *]*

### *function*  dictionaries/f_get_error_definitions()

* **Return:**
  **f_get_error_definitions** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*

### Defining a new error

New error families are registered with [`f_err_define()`](errors.md#f/dictionaries/f_err_define), which returns a
stable integer code (`err_id`) that can be reused for subsequent raises and
checks.  An optional per-error callback and action string may be attached at
definition time.  Errors should be defined once, at library startup, together
with the dictionary errors registered by
`dictionaries_errors()`.

### Raising and checking

[`f_err_raise()`](errors.md#f/dictionaries/f_err_raise) is the primary idiom for conditional errors: it returns
`.true.` when the condition holds so it can be used inline as:

```default
if (f_err_raise(condition, 'message', err_id=MY_ERR)) return
```

[`f_err_throw()`](errors.md#f/dictionaries/f_err_throw) raises an error unconditionally (for example inside a
routine that has already detected the failure).  The raised error is then
inspected with [`f_err_check()`](yaml_str.md#f/dictionaries/f_err_check), which accepts an optional `err_id` or
`err_name` to query a specific family, or no argument to ask whether *any*
error is pending.  Pending errors are cleared with [`f_err_clean()`](errors.md#f/dictionaries/f_err_clean).

### Try/catch environment

[`f_err_open_try()`](errors.md#f/dictionaries/f_err_open_try) and [`f_err_close_try()`](errors.md#f/dictionaries/f_err_close_try) delimit a nested
try/catch region.  Inside such a region callbacks are suppressed (errors are
simply accumulated) and a stack of pending-error dictionaries is kept so that
regions can nest.  [`f_err_check()`](yaml_str.md#f/dictionaries/f_err_check) should be called *before*
[`f_err_close_try()`](errors.md#f/dictionaries/f_err_close_try), and [`f_err_close_try()`](errors.md#f/dictionaries/f_err_close_try) optionally returns the
pending exceptions as a dictionary for inspection.  [`f_err_trying()`](errors.md#f/dictionaries/f_err_trying)
reports whether the code is currently inside a try environment.

### Inspecting the error record

Each raised error is stored as a dictionary entry, so the introspection API is
dictionary-based:

- [`f_get_last_error()`](errors.md#f/dictionaries/f_get_last_error) returns the id of the most recent error and
  optionally its additional message;
- [`f_get_no_of_errors()`](errors.md#f/dictionaries/f_get_no_of_errors) returns how many errors are currently pending;
- [`f_get_past_error()`](errors.md#f/dictionaries/f_get_past_error) returns the id of a pending error by its position
  in the stack;
- [`f_get_error_dict()`](errors.md#f/dictionaries/f_get_error_dict) returns the dictionary describing a given error
  (by default the last one);
- [`f_get_error_definitions()`](errors.md#f/dictionaries/f_get_error_definitions) returns the global dictionary of all
  defined error families, useful for diagnostics.

## Callback and severe-error policy from [`exception_callbacks`](errors.md#f/exception_callbacks)

These routines govern what happens when an error is raised outside a try
environment.  They live in [`exception_callbacks`](errors.md#f/exception_callbacks) (source file
`callbacks.f90`) and are made available alongside the dictionaries API;
client code that overrides the default behaviour adds
`use exception_callbacks` explicitly.

### Quick access

* **Routines:**
  [`f_dump_last_error()`](errors.md#f/exception_callbacks/f_dump_last_error), [`f_dump_possible_errors()`](errors.md#f/exception_callbacks/f_dump_possible_errors), [`f_err_ignore()`](errors.md#f/exception_callbacks/f_err_ignore), [`f_err_set_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_set_all_errors_callback), [`f_err_set_callback()`](errors.md#f/exception_callbacks/f_err_set_callback), [`f_err_set_last_error_callback()`](errors.md#f/exception_callbacks/f_err_set_last_error_callback), [`f_err_severe()`](errors.md#f/exception_callbacks/f_err_severe), [`f_err_severe_override()`](errors.md#f/exception_callbacks/f_err_severe_override), [`f_err_severe_restore()`](errors.md#f/exception_callbacks/f_err_severe_restore), [`f_err_unset_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_unset_all_errors_callback), [`f_err_unset_callback()`](errors.md#f/exception_callbacks/f_err_unset_callback), [`f_err_unset_last_error_callback()`](errors.md#f/exception_callbacks/f_err_unset_last_error_callback)

### Needed modules

- [`f_precisions`](f_prec.md#f/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*  exception_callbacks/f_err_set_callback()

Generic interface to install a global error callback.

The simple overload takes the callback procedure; the advanced overload
also forwards a data address to it.  The callback is invoked for every
error raised outside a try environment.  Clear it with
[`f_err_unset_callback()`](errors.md#f/exception_callbacks/f_err_unset_callback).

```fortran
subroutine example_f_err_set_callback()
  external :: counting_callback

  callback_count = 0
  call f_err_set_callback(counting_callback)
  call f_err_clean()
  call f_err_throw('error triggering the callback', err_name='GENERIC_ERROR')
  call f_err_clean()
  call f_err_unset_callback()
  call require(callback_count == 1, &
       'f_err_set_callback callback was not invoked once')
end subroutine example_f_err_set_callback
```

### *subroutine*  exception_callbacks/f_err_unset_callback()

Remove the global error callback.

Resets the callback and its data address, restoring the default behaviour
for errors raised outside a try environment.

### *subroutine*  exception_callbacks/f_err_severe_override(callback)

Redirect the severe-error policy.

Installs a custom routine to be called by [`f_err_severe()`](errors.md#f/exception_callbacks/f_err_severe) instead
of the default hard `stop`.  Restore the default with
[`f_err_severe_restore()`](errors.md#f/exception_callbacks/f_err_severe_restore).

* **Parameters:**
  **callback** *[**external* *]*

### *subroutine*  exception_callbacks/f_err_severe_restore()

Restore the default severe-error policy.

Undoes a previous [`f_err_severe_override()`](errors.md#f/exception_callbacks/f_err_severe_override).

### *subroutine*  exception_callbacks/f_err_ignore()

No-op callback that silently ignores errors.

Convenience callback for [`f_err_set_callback()`](errors.md#f/exception_callbacks/f_err_set_callback) when errors should be
swallowed without any output.

### *subroutine*  exception_callbacks/f_err_severe()

Routine of last resort for unrecoverable errors.

Calls the overridden severe callback when one has been installed with
[`f_err_severe_override()`](errors.md#f/exception_callbacks/f_err_severe_override), otherwise calls the internal routine that
dumps the last error and stops execution.

### *subroutine*  exception_callbacks/f_dump_last_error()

Dump information about the last raised error.

Invokes the callback installed with
[`f_err_set_last_error_callback()`](errors.md#f/exception_callbacks/f_err_set_last_error_callback), if any.

### *subroutine*  exception_callbacks/f_dump_possible_errors(msg)

Dump the catalogue of all defined error families.

Invokes the callback installed with
[`f_err_set_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_set_all_errors_callback), passing a descriptive message.
Used internally to help diagnose unknown error names or ids.

* **Parameters:**
  **msg** (\*) *[**character* *,* *in* *]*

### *subroutine*  exception_callbacks/f_err_set_last_error_callback(callback)

Install the last-error dump callback.

The callback is invoked by [`f_dump_last_error()`](errors.md#f/exception_callbacks/f_dump_last_error).  Clear it with
[`f_err_unset_last_error_callback()`](errors.md#f/exception_callbacks/f_err_unset_last_error_callback).

* **Parameters:**
  **callback** *[**external* *]* :: < Error routine which will be called

### *subroutine*  exception_callbacks/f_err_unset_last_error_callback()

Remove the last-error dump callback.

### *subroutine*  exception_callbacks/f_err_unset_all_errors_callback()

Remove the all-errors dump callback.

### *subroutine*  exception_callbacks/f_err_set_all_errors_callback(callback)

Install the all-errors dump callback.

The callback is invoked by [`f_dump_possible_errors()`](errors.md#f/exception_callbacks/f_dump_possible_errors) with a
descriptive message.  Clear it with
[`f_err_unset_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_unset_all_errors_callback).

* **Parameters:**
  **callback** *[**external* *]*

### Global callbacks

[`f_err_set_callback()`](errors.md#f/exception_callbacks/f_err_set_callback) installs a routine invoked each time an error is
raised outside a try environment; the advanced overload also accepts a data
address to forward to the callback.  The callback is cleared with
[`f_err_unset_callback()`](errors.md#f/exception_callbacks/f_err_unset_callback), which restores the default behaviour.  A
convenience no-op callback [`f_err_ignore()`](errors.md#f/exception_callbacks/f_err_ignore) is provided to silently
swallow errors.

### Severe-error policy

[`f_err_severe()`](errors.md#f/exception_callbacks/f_err_severe) is the routine of last resort, called internally when
the library cannot proceed (for example when the error pipeline is used before
`f_lib_initialize()`).  Its behaviour can be redirected with
[`f_err_severe_override()`](errors.md#f/exception_callbacks/f_err_severe_override) (useful to turn a hard `stop` into a custom
cleanup path) and restored with [`f_err_severe_restore()`](errors.md#f/exception_callbacks/f_err_severe_restore).

### Error-dump callbacks

Two separate callback hooks control how errors are reported:

- [`f_err_set_last_error_callback()`](errors.md#f/exception_callbacks/f_err_set_last_error_callback) / [`f_err_unset_last_error_callback()`](errors.md#f/exception_callbacks/f_err_unset_last_error_callback)
  drive [`f_dump_last_error()`](errors.md#f/exception_callbacks/f_dump_last_error), which prints information about the most
  recent error;
- [`f_err_set_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_set_all_errors_callback) / [`f_err_unset_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_unset_all_errors_callback)
  drive [`f_dump_possible_errors()`](errors.md#f/exception_callbacks/f_dump_possible_errors), which prints the full catalogue of
  defined errors and is used internally to help diagnose unknown error names or
  ids.

## Examples

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

A larger, integration-style example exercising error definition, conditional
raising, nested try/catch and callbacks together is available in the
regression test.  The `Use` block shows the module imports needed by client
code:

```fortran
  use dictionaries
  use yaml_strings, only: f_char_ptr
```

The `Error Define` block shows how to register error families with
[`f_err_define()`](errors.md#f/dictionaries/f_err_define) and attach per-error callbacks:

```fortran
  call f_err_define(err_name='ERR_TOTO',&
       err_msg='This is the error message for the error of kind 1 and it is written extensively'//&
       ' on purpose to see whether yaml module prints it',&
       err_action='For this error, contact the routine developer at mail at univ dot gov',&
       err_id=ERR_TOTO,callback=abort_toto)

  call f_err_define(err_name='ERR_TITI',err_msg='test2',err_id=ERR_TITI,&
       callback=abort_titi,callback_data=f_loc(ival))

  call f_err_define(err_name='ERR_GRAVE',err_msg='test2',err_id=ERR_GRAVE,&
       callback=f_err_severe)
```

## Documentation coverage

The CI documentation contract for this page mirrors the one described for
[`f_precisions`](f_prec.md#f/f_precisions) and checks three complementary notions of coverage:

`symbol coverage`
: Every expected public error-handling entry must appear in the rendered HTML
  page.  This catches missing raise/throw/check/try/callback symbols when the
  parser or the source changes.

`topic coverage`
: Required explanatory topics must also appear in the rendered page.  For the
  error-handling page these cover the `use dictionaries` entry point, the
  `error_handling.f90` source location, error definition, raising and
  checking, the try/catch environment, error-record inspection, the callback
  and severe-error policy from [`exception_callbacks`](errors.md#f/exception_callbacks), 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.  For parsed helpers and interfaces the directive lives in the
  Fortran source comment next to the public API.  If a public routine has no
  runnable example the page and source comment should explain why, and the
  coverage check should make that exception explicit.

The coverage check lives in `doc/check_errors_public_api.py` and should be
extended whenever a new public error-handling routine is added.


# f_prec.md

# Control of the precision [`f_precisions`](f_prec.md#f/f_precisions)

The [`f_precisions`](f_prec.md#f/f_precisions) module defines the portable Futile kind policy and
the public sentinel helpers used by host codes.

### Description

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
constants when exposing Futile-compatible public APIs.

Public items are grouped into four families:

* ABI kind parameters such as f_integer, f_double, and f_byte.
* Semantic kind parameters such as f_quadruple, f_address, and f_size_t.
* Undefined sentinel constants and generic sentinel helper interfaces.
* Low-level portability helpers such as f_loc, f_sizeof, and f_simplify.

### Quick access

* **Types:**
  [`f_parameter`](f_prec.md#f/f_precisions/f_parameter)
* **Variables:**
  [`f_0`](f_prec.md#f/f_precisions/f_0), [`f_1`](f_prec.md#f/f_precisions/f_1), [`f_address`](f_prec.md#f/f_precisions/f_address), [`f_backslash`](f_prec.md#f/f_precisions/f_backslash), [`f_byte`](f_prec.md#f/f_precisions/f_byte), [`f_cr`](f_prec.md#f/f_precisions/f_cr), [`f_double`](f_prec.md#f/f_precisions/f_double), [`f_f`](f_prec.md#f/f_precisions/f_f), [`f_int8`](f_prec.md#f/f_precisions/f_int8), [`f_integer`](f_prec.md#f/f_precisions/f_integer), [`f_logical`](f_prec.md#f/f_precisions/f_logical), [`f_long`](f_prec.md#f/f_precisions/f_long), [`f_long_double`](f_prec.md#f/f_precisions/f_long_double), [`f_quadruple`](f_prec.md#f/f_precisions/f_quadruple), [`f_short`](f_prec.md#f/f_precisions/f_short), [`f_simple`](f_prec.md#f/f_precisions/f_simple), [`f_size_t`](f_prec.md#f/f_precisions/f_size_t), [`f_t`](f_prec.md#f/f_precisions/f_t), [`undefined_f_double`](f_prec.md#f/f_precisions/undefined_f_double), [`undefined_f_int8`](f_prec.md#f/f_precisions/undefined_f_int8), [`undefined_f_integer`](f_prec.md#f/f_precisions/undefined_f_integer), [`undefined_f_long`](f_prec.md#f/f_precisions/undefined_f_long), [`undefined_f_long_double`](f_prec.md#f/f_precisions/undefined_f_long_double), [`undefined_f_short`](f_prec.md#f/f_precisions/undefined_f_short), [`undefined_f_simple`](f_prec.md#f/f_precisions/undefined_f_simple)
* **Routines:**
  [`f_is_defined()`](f_prec.md#f/f_precisions/f_is_defined), [`f_is_undefined()`](f_prec.md#f/f_precisions/f_is_undefined), [`f_undefine()`](f_prec.md#f/f_precisions/f_undefine), [`f_undefined()`](f_prec.md#f/f_precisions/f_undefined)

### ABI kind parameters

Futile public APIs should use these names when exposing data whose binary
representation must be stable across Fortran/C boundaries or across
BigDFT components.

- ### f_precisions/f_int8 *[**integer* *,**public/parameter/default=c_int8_t* *]*

  C-compatible signed 8-bit integer kind.
- ### f_precisions/f_short *[**integer* *,**public/parameter/default=c_int16_t* *]*

  C-compatible signed 16-bit integer kind.
- ### f_precisions/f_integer *[**integer* *,**public/parameter/default=c_int32_t* *]*

  C-compatible signed 32-bit integer kind; canonical Futile integer.
- ### f_precisions/f_long *[**integer* *,**public/parameter/default=c_int64_t* *]*

  C-compatible signed 64-bit integer kind.
- ### f_precisions/f_simple *[**integer* *,**public/parameter/default=c_float* *]*

  C float-compatible real kind.
- ### f_precisions/f_double *[**integer* *,**public/parameter/default=c_double* *]*

  C double-compatible real kind; canonical Futile real.
- ### f_precisions/f_long_double *[**integer* *,**public/parameter/default=c_long_double* *]*

  C long double-compatible real kind when supported.
- ### f_precisions/f_byte *[**integer* *,**public/parameter/default=c_bool* *]*

  C bool-compatible logical kind; not an integer byte kind.
- ### f_precisions/f_logical *[**integer* *,**public/parameter/default=kind(.false.)* *]*

### Semantic kind parameters

These names describe host-code intent and should not be used to define
required overload families without first checking that the compiler and
platform support the requested representation.

- ### f_precisions/f_quadruple *[**integer* *,**public/parameter/default=selected_real_kind(33* *,**4931)* *]*
- ### f_precisions/f_address *[**integer* *,**public/parameter/default=c_intptr_t* *]*

  Integer kind large enough to store a C address.
- ### f_precisions/f_size_t *[**integer* *,**public/parameter/default=c_size_t* *]*

  Integer kind compatible with C size_t values.

### Preferred undefined sentinel constants

These constants define the public sentinel values used by f_undefined,
f_undefine, and f_is_undefined. Integer sentinels use the lowest
representable value for the corresponding Futile kind. Real sentinels
use quiet NaN bit patterns where portable initialization expressions are
available.

- ### f_precisions/undefined_f_int8 *[**integer* *,**public/parameter/default=-huge(0_f_int8)* *]*
- ### f_precisions/undefined_f_short *[**integer* *,**public/parameter/default=-huge(0_f_short)* *]*
- ### f_precisions/undefined_f_integer *[**integer* *,**public/parameter/default=-huge(0_f_integer)* *]*
- ### f_precisions/undefined_f_long *[**integer* *,**public/parameter/default=-huge(0_f_long)* *]*
- ### f_precisions/undefined_f_simple *[**real* *,**public/parameter/default=transfer(f_quiet_nan_simple_words* *,**0.0_f_simple)* *]*
- ### f_precisions/undefined_f_double *[**real* *,**public/parameter/default=transfer(f_quiet_nan_double_words* *,**0.0_f_double)* *]*
- ### f_precisions/undefined_f_long_double *[**real* *,**public/parameter/default=-huge(0.0_f_long_double)* *]*

### Assignment token constants

These parameter values are used by the assignment generic to initialize
common scalar values without repeating literal constants at call sites.

- ### f_precisions/f_0 *[*[*f_parameter*](f_prec.md#f/f_precisions/f_parameter) *,**public/parameter/default=f_parameter(c_0)* *]*
- ### f_precisions/f_1 *[*[*f_parameter*](f_prec.md#f/f_precisions/f_parameter) *,**public/parameter/default=f_parameter(c_1)* *]*

### C-compatible logical constants

Use these constants only where the ABI requires logical(f_byte); use
ordinary .true. and .false. for default Fortran logic.

- ### f_precisions/f_t *[**logical* *,**public/parameter/default=.true._f_byte* *]*

  C-compatible true value.
- ### f_precisions/f_f *[**logical* *,**public/parameter/default=.false._f_byte* *]*

  C-compatible false value.

### Types

- ### *type*  f_precisions/f_parameter

  * **Type fields:**
    * % val *[**character(len=num_size)* *]*

### Variables

- ### f_precisions/f_backslash *[**character(len=\*)* *,**public/parameter/default=char(92)* *]*
- ### f_precisions/f_cr *[**character(len=\*)* *,**public/parameter/default=char(13)//char(10)* *]*

### Subroutines and functions

### *interface*  f_precisions/assignment(=)(val, par)

* **Parameters:**
  * **val** *[**real* *,* *integer* *,* *character(len=\*)* *,* *out* *]*
  * **par** *[*[*f_parameter*](f_prec.md#f/f_precisions/f_parameter) *,* *in* *]*

### *interface*  f_precisions/f_undefined(one)

Return an undefined sentinel value with the same intrinsic kind as the mold argument.

This is the constructor-like entry point of the undefined sentinel API.
Preferred usage is to obtain a sentinel with x = f_undefined(x), assign
one in place with call f_undefine(x), and test values with
f_is_undefined(x) or f_is_defined(x).

Do not compare sentinel values with == or /= in client code. The real
and complex sentinels may use quiet NaN bit patterns, for which ordinary
numerical comparison is neither portable nor semantically correct.
Logical kinds are intentionally unsupported because there is no portable
sentinel value distinct from true and false.

* **Parameters:**
  **one** *[**complex* *,* *in* *]*

### *interface*  f_precisions/f_undefine(value)

Assign the undefined sentinel to a scalar variable in place.

This is the in-place form of f_undefined: after the call, the scalar
value carries the Futile undefined representation for its intrinsic kind.
Test the result with f_is_undefined or f_is_defined rather than with
direct equality comparisons.

* **Parameters:**
  **value** *[**complex* *,* *out* *]*

### *interface*  f_precisions/f_is_undefined(value)

Test whether a scalar value has the Futile undefined sentinel representation.

This predicate is the portable way to recognize undefined values produced
by f_undefined or f_undefine, including real and complex sentinels
represented with quiet NaN bit patterns.

* **Parameters:**
  **value** *[**complex* *,* *in* *]*

### *interface*  f_precisions/f_is_defined(value)

Test whether a scalar value is different from the Futile undefined sentinel representation.

This is the logical complement of f_is_undefined and is preferred over
direct comparisons with the sentinel constants, so generic code remains
safe when the intrinsic kind changes.

* **Parameters:**
  **value** *[**complex* *,* *in* *]*

The page intentionally relies on the default public-only behavior of
`f:automodule`.  Public generic interfaces such as [`f_sizeof()`](f_prec.md#f/f_precisions/f_sizeof),
[`f_undefined()`](f_prec.md#f/f_precisions/f_undefined), [`f_undefine()`](f_prec.md#f/f_precisions/f_undefine), [`f_is_undefined()`](f_prec.md#f/f_precisions/f_is_undefined), and
[`f_is_defined()`](f_prec.md#f/f_precisions/f_is_defined) are rendered as interface entries.  Their private
implementation procedures are not part of the public documentation contract.

## Address inquiry

### *function*  f_precisions/f_loc(x)

Return the memory address associated with a scalar object as an
`integer(f_address)` value.  This is Futile’s portable wrapper around the
non-standard `loc` functionality traditionally provided by GNU Fortran.

Use this routine only for low-level interoperability or storage-layout
inquiries.  The argument may be an intrinsic scalar, a derived-type object, or
a procedure target, but it must not be a nullified pointer.

* **Parameters:**
  **x** *[**in* *]* :: scalar object whose address is queried.
* **Return:**
  **f_loc** *[**integer(f_address)* *]* :: address of `x`.

CI-covered example:

```fortran
subroutine example_f_loc()
  integer(f_address) :: address
  real(f_double), target :: value

  value = 1.0_f_double
  address = f_loc(value)
  call require(address /= 0_f_address, 'f_loc returned a null address')
end subroutine example_f_loc
```

## Precision helpers

The helper APIs below are rendered from the Fortran source with constrained
`f:automodule` directives.  The surrounding prose and examples stay close to
the page, while signatures, argument lists, return values, and interface
membership remain source-driven.

### Storage-size inquiry

### Subroutines and functions

### *interface*  f_precisions/f_sizeof(av)

Return the storage size in bytes of a scalar Futile intrinsic kind.
This generic is implemented by private kind-specific procedures and is
exposed as the public API entry.

```fortran
subroutine example_f_sizeof()
  real(f_double) :: x
  integer(f_integer) :: i

  call require(f_sizeof(x) > 0, 'f_sizeof failed for real(f_double)')
  call require(f_sizeof(i) > 0, 'f_sizeof failed for integer(f_integer)')
end subroutine example_f_sizeof
```

* **Parameters:**
  **av** *[**real* *,* *integer* *,* *logical* *,* *in* *]*

The public API is the generic interface above.  It returns the storage size in
bytes of a scalar Futile intrinsic value and is implemented by private
kind-specific procedures.

Use it for low-level portability checks, binary layout diagnostics, and code
that must reason about the storage occupied by Futile ABI kinds.

### Precision reduction

### Subroutines and functions

### *function*  f_precisions/f_simplify(d)

Convert a double-precision value to simple precision while saturating
values outside the simple-precision representable range.

```fortran
subroutine example_f_simplify()
  real(f_double) :: x
  real(f_simple) :: y

  x = 1.0_f_double / 3.0_f_double
  y = f_simplify(x)
  call require(abs(real(y, f_double) - x) < 1.0e-6_f_double, &
       'f_simplify changed a representable value too much')
end subroutine example_f_simplify
```

* **Parameters:**
  **d** *[**real* *,* *in* *]* :: Input double-precision value.
* **Return:**
  **r** *[**real* *]* :: Simple-precision value after range protection.

Use this helper when reducing precision intentionally, so the conversion policy
is explicit at the call site.  Values outside the simple-precision range are
saturated instead of relying on compiler-dependent overflow or underflow
behavior.

### Tolerance-based greater-than comparison

### Subroutines and functions

### *function*  f_precisions/gt_with_tol(a, b)

Compare two double-precision values with an optional tolerance.

```fortran
subroutine example_gt_with_tol()
  real(f_double) :: a

  a = 1.0_f_double
  call require(gt_with_tol(a + 2.0_f_double * epsilon(a), a), &
       'gt_with_tol did not detect a significant positive difference')
  call require(.not. gt_with_tol(a + 0.5_f_double * epsilon(a), a), &
       'gt_with_tol treated a roundoff-level difference as significant')
end subroutine example_gt_with_tol
```

* **Parameters:**
  * **a** *[**real* *,* *in* *]*
  * **b** *[**real* *,* *in* *]* :: Values to compare.
* **Options:**
  **tol** *[**real* *,* *in,* *]* :: Comparison tolerance; defaults to machine epsilon.
* **Return:**
  **yes** *[**logical* *]* :: True when a is larger than b by more than the tolerance.

Use this elemental helper when a strict greater-than comparison should ignore
roundoff-level differences.

### Tolerance-based equality comparison

### Subroutines and functions

### *function*  f_precisions/eq_with_tol(a, b)

Compare two double-precision values for equality with an optional tolerance.

```fortran
subroutine example_eq_with_tol()
  real(f_double) :: a

  a = 1.0_f_double
  call require(eq_with_tol(a + 0.5_f_double * epsilon(a), a), &
       'eq_with_tol rejected a roundoff-level difference')
  call require(.not. eq_with_tol(a + 2.0_f_double * epsilon(a), a), &
       'eq_with_tol accepted a significant difference')
end subroutine example_eq_with_tol
```

* **Parameters:**
  * **a** *[**real* *,* *in* *]*
  * **b** *[**real* *,* *in* *]* :: Values to compare.
* **Options:**
  **tol** *[**real* *,* *in,* *]* :: Comparison tolerance; defaults to machine epsilon.
* **Return:**
  **yes** *[**logical* *]* :: True when the absolute difference is smaller than the tolerance.

Use this elemental helper when equality should be interpreted with a numerical
tolerance instead of exact bitwise equality.

## Documentation coverage

The CI documentation contract for this page checks two complementary notions of
coverage:

`symbol coverage`
: Every expected public [`f_precisions`](f_prec.md#f/f_precisions) entry must appear in the rendered
  HTML page.  This catches missing public constants, interfaces, and helper
  functions when the parser or the source changes.

`topic coverage`
: Required explanatory topics must also appear in the rendered page.  For this
  module the required topics cover ABI kinds, semantic kinds, undefined
  sentinels, address inquiry, storage-size inquiry, precision conversion, and
  tolerance-based comparisons.

`example coverage`
: Public helpers should 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 behavior.  For parsed helpers and interfaces, the directive should
  live in the Fortran source comment next to the public API.  Manual objects
  such as the external `f_loc` wrapper may keep the directive in the page
  until sphinxfortran can render them directly from source.  If a public
  function has no runnable example, the page and source comment should explain
  why and the coverage check should make that exception explicit.

This is intentionally stricter than checking that Sphinx exits successfully: a
page can build while still being unhelpful to users.  The coverage check lives in
`doc/check_sphinxfortran_public_api.py` and should be extended whenever a new
public API family is added.


# inputfile.md

# Automatic definition of the input dictionary the [`f_input_file`](inputfile.md#f/f_input_file) module

In a Fortran program it is often useful to have a high-level handling of the input
variables. The Fortran specification provides the `namelist` approach, which is
relatively easy to use. However such an approach presents few drawbacks of portability
and code-intrusivity, which limit its usage in a multi-language context.
With this module we provide a set of rules to automatically parse, inspect, verify and
convert a input file from the `yaml` format into a `futile` dictionary.
With the usage of the [`f_input_file`](inputfile.md#f/f_input_file) module developers might easily
write \_specifications_ for their program input file.

Such module is in tight connection with its python counterpart, [`futile.Inputvars`](pyfutile.md#module-futile.Inputvars), which
employs the same conventions and make possible a full interplay between a `yaml` input file and
a python dictionary.

<a id="f/f_input_file"></a>

### Quick access

* **Routines:**
  [`input_file_complete()`](inputfile.md#f/f_input_file/input_file_complete), [`input_file_dump()`](inputfile.md#f/f_input_file/input_file_dump), [`input_file_errors()`](inputfile.md#f/f_input_file/input_file_errors), [`input_file_minimal()`](inputfile.md#f/f_input_file/input_file_minimal), [`input_keys_get_profile()`](inputfile.md#f/f_input_file/input_keys_get_profile), [`input_value_is_default()`](inputfile.md#f/f_input_file/input_value_is_default)

### Needed modules

- [`dictionaries`](yaml_str.md#f/dictionaries): High-level dictionary API used throughout Futile and BigDFT.  A dictionary is a pointer-based tree that can represent scalars, ordered mappings, and lists.  It maps directly to YAML data and is manipulated with constructors
- [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`operator(.eqv.)()`](yaml_strings.md#f/yaml_strings/operator(.eqv.)), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy))
- [`f_utils`](memory.md#f/f_utils) ([`f_zero()`](memory.md#f/f_utils/f_zero))

### Subroutines and functions

### *subroutine*  f_input_file/input_file_errors()

* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries) ([`f_err_define()`](errors.md#f/dictionaries/f_err_define))
* **Called from:**
  `initialize_flib_errors()`
* **Call to:**
  [`f_err_define()`](errors.md#f/dictionaries/f_err_define)

### *subroutine*  f_input_file/input_file_complete(inputdef, dict)

* **Parameters:**
  * **inputdef** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
* **Options:**
  * **imports** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **nocheck** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **verbose** *[**logical* *,* *in,* *]*
* **Use:** 
  `dynamic_memory`, [`yaml_output`](yaml.md#f/yaml_output)
* **Call to:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), `dict_update()`, [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), `dict_copy()`, `dict_remove()`, [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine)

### *function*  f_input_file/input_keys_get_profile(dict, key, user_defined)

* **Parameters:**
  * **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **key** *[**character(len=\*)* *,* *in* *]*
  * **user_defined** *[**logical* *,* *out* *]*
* **Return:**
  **input_keys_get_profile** *[**character(len=max_field_length)* *]*
* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries)
* **Called from:**
  [`input_value_is_default()`](inputfile.md#f/f_input_file/input_value_is_default)
* **Call to:**
  [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy)

### *function*  f_input_file/input_value_is_default(dict, key)

* **Parameters:**
  * **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **key** *[**character(len=\*)* *,* *in* *]*
* **Return:**
  **yes** *[**logical* *]*
* **Call to:**
  [`input_keys_get_profile()`](inputfile.md#f/f_input_file/input_keys_get_profile)

### *subroutine*  f_input_file/input_file_minimal(inputdef, dict, minimal, nested, as_is)

* **Parameters:**
  * **inputdef** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]* :: < Dictionary of the input definitions
  * **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]* :: < User input file
  * **minimal** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *out,pointer* *]* :: < List of keys in dict that remain which require special treatments
  * **nested** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]* :: < Add other keys (extracted by subcategories of nested elements)
  * **as_is** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]* :: < Add keys in as_is and not in inputdef
* **Use:** 
  `dynamic_memory`, [`dictionaries`](yaml_str.md#f/dictionaries), [`yaml_output`](yaml.md#f/yaml_output)
* **Call to:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), `has_key()`, [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), `set()`, [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), `dict_copy()`, [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine)

### *subroutine*  f_input_file/input_file_dump(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]* :: < Dictionary to dump
* **Options:**
  * **useronly** *[**logical* *,* *in,* *]*
  * **nodump_list** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]* :: <list containing keys not to dump
  * **msg** *[**character(len=\*)* *,* *in,* *]*
* **Use:** 
  [`yaml_output`](yaml.md#f/yaml_output)
* **Call to:**
  [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key)


# memory.md

# Memory handling

## Dynamic allocation / deallocation

<a id="f/module_f_malloc"></a>

### Quick access

* **Routines:**
  [`f_malloc()`](memory.md#f/module_f_malloc/f_malloc), [`f_malloc0()`](memory.md#f/module_f_malloc/f_malloc0), [`f_malloc0_buf()`](memory.md#f/module_f_malloc/f_malloc0_buf), [`f_malloc0_ptr()`](memory.md#f/module_f_malloc/f_malloc0_ptr), [`f_malloc0_str()`](memory.md#f/module_f_malloc/f_malloc0_str), [`f_malloc0_str_ptr()`](memory.md#f/module_f_malloc/f_malloc0_str_ptr), [`f_malloc_buf()`](memory.md#f/module_f_malloc/f_malloc_buf), [`f_malloc_ptr()`](memory.md#f/module_f_malloc/f_malloc_ptr), [`f_malloc_str()`](memory.md#f/module_f_malloc/f_malloc_str), [`f_malloc_str_ptr()`](memory.md#f/module_f_malloc/f_malloc_str_ptr), [`f_map_ptr()`](memory.md#f/module_f_malloc/f_map_ptr), [`operator(.plus.)()`](memory.md#f/module_f_malloc/operator(.plus.)), [`operator(.to.)()`](memory.md#f/module_f_malloc/operator(.to.)), [`remap_bounds_i2()`](memory.md#f/module_f_malloc/remap_bounds_i2)

### Needed modules

- [`f_precisions`](f_prec.md#f/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
- [`dictionaries`](yaml_str.md#f/dictionaries) ([`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), [`dictionary`](yaml_str.md#f/dictionaries/dictionary)): High-level dictionary API used throughout Futile and BigDFT.  A dictionary is a pointer-based tree that can represent scalars, ordered mappings, and lists.  It maps directly to YAML data and is manipulated with constructors
- [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), [`operator(+)()`](yaml_strings.md#f/yaml_strings/operator(+)))

### Subroutines and functions

### *interface*  module_f_malloc/operator(.to.)()

### *interface*  module_f_malloc/operator(.plus.)()

### *interface*  module_f_malloc/f_map_ptr()

* **Called from:**
  `f_map_ptr_addr_d0()`, `f_map_ptr_addr_l0()`, `f_map_ptr_addr_i0()`, `f_map_ptr_addr_li0()`

### *interface*  module_f_malloc/f_malloc()

### *interface*  module_f_malloc/f_malloc0()

### *interface*  module_f_malloc/f_malloc_ptr()

### *interface*  module_f_malloc/f_malloc0_ptr()

### *interface*  module_f_malloc/f_malloc_str()

### *interface*  module_f_malloc/f_malloc0_str()

### *interface*  module_f_malloc/f_malloc_str_ptr()

### *interface*  module_f_malloc/f_malloc0_str_ptr()

### *subroutine*  module_f_malloc/remap_bounds_i2(lb, lu, heap, ptr)

* **Parameters:**
  * **lb** (2) *[**integer* *,* *in,required* *]*
  * **lu** (2) *[**integer* *,* *in,required* *]*
  * **heap** (1 - lb(1) + lu(1,1 - lb(2) + lu(2) *[**integer* *,* *in,target* *]*
  * **ptr** (,) *[**integer* *,* *out,pointer* *]*

### *function*  module_f_malloc/f_malloc()

* **Options:**
  * **sizes** (\*) *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine_id** *[**character(len=\*)* *,* *in,* *]*
  * **lbounds** (\*) *[**integer* *,* *in,* *]*
  * **ubounds** (\*) *[**integer* *,* *in,* *]*
  * **profile** *[**logical* *,* *in,* *]*
  * **info** *[**character(len=\*)* *,* *in,* *]*
  * **src** (\*) *[**integer* *,* *in,* *]*
  * **src_ptr** (\*) *[**integer* *,* *in,pointer* *]*
* **Return:**
  **m** *[**malloc_information_all* *]*

### *function*  module_f_malloc/f_malloc0()

* **Options:**
  * **sizes** (\*) *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine_id** *[**character(len=\*)* *,* *in,* *]*
  * **lbounds** (\*) *[**integer* *,* *in,* *]*
  * **ubounds** (\*) *[**integer* *,* *in,* *]*
  * **profile** *[**logical* *,* *in,* *]*
  * **info** *[**character(len=\*)* *,* *in,* *]*
* **Return:**
  **m** *[**malloc_information_all* *]*

### *function*  module_f_malloc/f_malloc_ptr()

* **Options:**
  * **sizes** (\*) *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine_id** *[**character(len=\*)* *,* *in,* *]*
  * **lbounds** (\*) *[**integer* *,* *in,* *]*
  * **ubounds** (\*) *[**integer* *,* *in,* *]*
  * **profile** *[**logical* *,* *in,* *]*
  * **info** *[**character(len=\*)* *,* *in,* *]*
  * **src** (\*) *[**integer* *,* *in,* *]*
  * **src_ptr** (\*) *[**integer* *,* *in,pointer* *]*
* **Return:**
  **m** *[**malloc_information_ptr* *]*

### *function*  module_f_malloc/f_malloc0_ptr()

* **Options:**
  * **sizes** (\*) *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine_id** *[**character(len=\*)* *,* *in,* *]*
  * **lbounds** (\*) *[**integer* *,* *in,* *]*
  * **ubounds** (\*) *[**integer* *,* *in,* *]*
  * **profile** *[**logical* *,* *in,* *]*
  * **info** *[**character(len=\*)* *,* *in,* *]*
* **Return:**
  **m** *[**malloc_information_ptr* *]*

### *function*  module_f_malloc/f_malloc_buf()

* **Options:**
  * **sizes** *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine_id** *[**character(len=\*)* *,* *in,* *]*
  * **profile** *[**logical* *,* *in,* *]*
  * **info** *[**character(len=\*)* *,* *in,* *]*
  * **src** (\*) *[**integer* *,* *in,* *]*
* **Return:**
  **m** *[**malloc_information_buf* *]*

### *function*  module_f_malloc/f_malloc0_buf()

* **Options:**
  * **sizes** *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine_id** *[**character(len=\*)* *,* *in,* *]*
  * **profile** *[**logical* *,* *in,* *]*
  * **info** *[**character(len=\*)* *,* *in,* *]*
* **Return:**
  **m** *[**malloc_information_buf* *]*

<a id="f/dynamic_memory_base"></a>

### Quick access

* **Variables:**
  `operator(.plus.)`, `operator(.to.)`
* **Routines:**
  [`dynamic_memory_errors()`](memory.md#f/dynamic_memory_base/dynamic_memory_errors), [`f_free()`](memory.md#f/dynamic_memory_base/f_free), [`f_free_ptr()`](memory.md#f/dynamic_memory_base/f_free_ptr), [`f_free_str()`](memory.md#f/dynamic_memory_base/f_free_str), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`f_malloc_initialize()`](memory.md#f/dynamic_memory_base/f_malloc_initialize), [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), [`f_maxdiff()`](memory.md#f/dynamic_memory_base/f_maxdiff), [`f_memcpy()`](memory.md#f/dynamic_memory_base/f_memcpy), [`f_purge_database()`](memory.md#f/dynamic_memory_base/f_purge_database), [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`f_subptr()`](memory.md#f/dynamic_memory_base/f_subptr), [`f_subptr2()`](memory.md#f/dynamic_memory_base/f_subptr2), [`f_update_database()`](memory.md#f/dynamic_memory_base/f_update_database), [`free_validate()`](memory.md#f/dynamic_memory_base/free_validate), [`malloc_validate()`](memory.md#f/dynamic_memory_base/malloc_validate), [`update_allocation_database()`](memory.md#f/dynamic_memory_base/update_allocation_database)

### Needed modules

- `memory_profiling`
- [`dictionaries`](yaml_str.md#f/dictionaries) (`max_field_length` => `info_length()`): High-level dictionary API used throughout Futile and BigDFT.  A dictionary is a pointer-based tree that can represent scalars, ordered mappings, and lists.  It maps directly to YAML data and is manipulated with constructors
- [`yaml_strings`](yaml_strings.md#f/yaml_strings)
- [`module_f_malloc`](memory.md#f/module_f_malloc)
- [`f_precisions`](f_prec.md#f/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
- `yaml_parse_base` (`yaml_load()`)
- [`yaml_output`](yaml.md#f/yaml_output) ([`yaml_map()`](yaml.md#f/yaml_output/yaml_map))
- [`f_utils`](memory.md#f/f_utils) ([`f_time()`](memory.md#f/f_utils/f_time), [`f_zero()`](memory.md#f/f_utils/f_zero), [`f_sizeof()`](memory.md#f/f_utils/f_sizeof), [`f_get_option()`](memory.md#f/f_utils/f_get_option), [`f_size()`](memory.md#f/f_utils/f_size))
- `iso_c_binding`
- `smpi_shared`
- `f_environment`

### Variables

- ### dynamic_memory_base/operator (.plus.) *[**public* *]*
- ### dynamic_memory_base/operator (.to.) *[**public* *]*

### Subroutines and functions

### *interface*  dynamic_memory_base/assignment(=)(array, m)

* **Parameters:**
  * **array** (\*) *[**character(len=m%len)* *,* *inout,pointer* *]*
  * **m** *[**malloc_information_str_ptr* *,* *in* *]*

### *interface*  dynamic_memory_base/f_free(array)

* **Parameters:**
  **array** (various shapes) *[**integer* *,* *inout,allocatable* *]*
* **Options:**
  **cptr** *[**logical* *,* *in,* *]*

### *interface*  dynamic_memory_base/f_free_str(length, array)

* **Parameters:**
  * **length** *[**integer* *,* *in* *]* :: < need to specify length for the declaration below (sometimes fortran runtime error)
  * **array** (various shapes) *[**character(len=length)* *,* *inout,allocatable* *]*
* **Options:**
  **cptr** *[**logical* *,* *in,* *]*
* **Called from:**
  [`yaml_parse_from_file()`](yaml.md#f/yaml_parse/yaml_parse_from_file)

### *interface*  dynamic_memory_base/f_free_ptr(array)

* **Parameters:**
  **array** (various shapes) *[**double_complex* *,* *inout,pointer* *]*
* **Options:**
  **cptr** *[**logical* *,* *in,* *]*

### *interface*  dynamic_memory_base/f_memcpy(dest, src)

* **Parameters:**
  * **dest** (various shapes) *[**integer* *,* *character* *,* *complex* *,* *inout* *]* :: <destination buffer
  * **src** (various shapes) *[**character* *,* *integer* *,* *complex* *,* *in* *]* :: <source buffer

### *interface*  dynamic_memory_base/f_maxdiff(a, b)

* **Parameters:**
  * **a** (various shapes) *[**character* *,* *in* *]*
  * **b** (\*) *[**integer* *,* *in* *]*
* **Options:**
  **n** *[**integer* *,* *in,* *]*

### *interface*  dynamic_memory_base/f_subptr()

### *interface*  dynamic_memory_base/f_subptr2()

### *interface*  dynamic_memory_base/malloc_validate()

### *interface*  dynamic_memory_base/update_allocation_database(address, size_bn, kind, m)

* **Parameters:**
  * **address** *[**integer* *,* *in* *]*
  * **size_bn** *[**integer* *,* *in* *]*
  * **kind** *[**integer* *,* *in* *]*
  * **m** *[**malloc_information_all* *,* *in* *]*

### *subroutine*  dynamic_memory_base/update_allocation_database(address, size_bn, kind, m)

* **Parameters:**
  * **address** *[**integer* *,* *in* *]*
  * **size_bn** *[**integer* *,* *in* *]*
  * **kind** *[**integer* *,* *in* *]*
  * **m** *[**malloc_information_all* *,* *in* *]*
* **Call to:**
  [`f_update_database()`](memory.md#f/dynamic_memory_base/f_update_database)

### *function*  dynamic_memory_base/free_validate(ierror)

* **Parameters:**
  **ierror** *[**integer* *,* *in* *]*
* **Return:**
  **ok** *[**logical* *]*
* **Call to:**
  `f_timer_resume()`, [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  dynamic_memory_base/f_routine()

* **Options:**
  * **id** *[**character(len=\*)* *,* *in,* *]* :: < name of the subprogram
  * **profile** *[**logical* *,* *in,* *]* :: < ???
* **Use:** 
  [`yaml_output`](yaml.md#f/yaml_output) ([`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document), [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open)), [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa))
* **Called from:**
  [`f_malloc_initialize()`](memory.md#f/dynamic_memory_base/f_malloc_initialize), [`input_file_complete()`](inputfile.md#f/f_input_file/input_file_complete), [`input_file_minimal()`](inputfile.md#f/f_input_file/input_file_minimal)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`f_time()`](memory.md#f/f_utils/f_time), `f_timer_interrupt()`, `prepend()`, `f_zero()`, [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa), [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document), `f_timer_resume()`

### *subroutine*  dynamic_memory_base/f_release_routine()

* **Options:**
  **performance_info** *[**f_perf* *,* *in,* *]*
* **Use:** 
  `f_perfs`, [`yaml_output`](yaml.md#f/yaml_output) ([`yaml_dict_dump()`](yaml.md#f/yaml_output/yaml_dict_dump), [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment)), [`f_utils`](memory.md#f/f_utils) ([`f_rewind()`](memory.md#f/f_utils/f_rewind)), [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa))
* **Called from:**
  [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`input_file_complete()`](inputfile.md#f/f_input_file/input_file_complete), [`input_file_minimal()`](inputfile.md#f/f_input_file/input_file_minimal)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), `f_timer_interrupt()`, `prepend()`, [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close), [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document), `f_timer_resume()`, [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), `has_key()`, [`yaml_dict_dump()`](yaml.md#f/yaml_output/yaml_dict_dump), [`f_rewind()`](memory.md#f/f_utils/f_rewind), `dump_status_line()`

### *subroutine*  dynamic_memory_base/f_update_database(size_bn, kind, rank_bn, address, id, routine, info)

* **Parameters:**
  * **size_bn** *[**integer* *,* *in* *]*
  * **kind** *[**integer* *,* *in* *]*
  * **rank_bn** *[**integer* *,* *in* *]*
  * **address** *[**integer* *,* *in* *]*
  * **id** *[**character(len=\*)* *,* *in* *]*
  * **routine** *[**character(len=\*)* *,* *in* *]*
  * **info** *[**character(len=\*)* *,* *in* *]*
* **Use:** 
  `metadata_interfaces` (`long_toa()`), [`yaml_output`](yaml.md#f/yaml_output) ([`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document)), [`dictionaries`](yaml_str.md#f/dictionaries)
* **Called from:**
  [`update_allocation_database()`](memory.md#f/dynamic_memory_base/update_allocation_database)
* **Call to:**
  [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), `set()`, `long_toa()`, `memstate_update()`, `dump_status_line()`, [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document)

### *subroutine*  dynamic_memory_base/f_purge_database(size_bn, kind)

* **Parameters:**
  * **size_bn** *[**integer* *,* *in* *]*
  * **kind** *[**integer* *,* *in* *]*
* **Options:**
  * **address** *[**integer* *,* *in,* *]*
  * **id** *[**character(len=\*)* *,* *in,* *]*
  * **routine** *[**character(len=\*)* *,* *in,* *]*
  * **info** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
* **Use:** 
  `metadata_interfaces` (`long_toa()`), [`yaml_output`](yaml.md#f/yaml_output) ([`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document)), [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy))
* **Call to:**
  `find_key()`, `long_toa()`, [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), `yaml_load()`, `dict_copy()`, [`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), `dict_remove()`, [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), `memstate_update()`, `dump_status_line()`, [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document)

### *subroutine*  dynamic_memory_base/dynamic_memory_errors()

* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries) ([`f_err_define()`](errors.md#f/dictionaries/f_err_define))
* **Called from:**
  `initialize_flib_errors()`
* **Call to:**
  [`f_err_define()`](errors.md#f/dictionaries/f_err_define)

### *subroutine*  dynamic_memory_base/f_malloc_initialize()

* **Use:** 
  `f_environment`
* **Called from:**
  `f_lib_initialize()`
* **Call to:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), `memstate_init()`, `set()`, [`yaml_date_and_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_date_and_time_toa), [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), `f_set_memory_limit()`

### *subroutine*  dynamic_memory_base/f_malloc_set_status()

* **Options:**
  * **output_level** *[**integer* *,* *in,* *]* :: < Level of output for memocc
  * **logfile_name** *[**character(len=\*)* *,* *in,* *]* :: < Name of the logfile
  * **iproc** *[**integer* *,* *in,* *]* :: < Process Id (used to dump, by default 0)
* **Use:** 
  [`yaml_output`](yaml.md#f/yaml_output), [`f_utils`](memory.md#f/f_utils), [`yaml_strings`](yaml_strings.md#f/yaml_strings)
* **Call to:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`yaml_close_stream()`](yaml.md#f/yaml_output/yaml_close_stream), [`f_file_unit()`](memory.md#f/f_utils/f_file_unit), [`f_close()`](memory.md#f/f_utils/f_close), [`f_get_free_unit()`](memory.md#f/f_utils/f_get_free_unit), [`yaml_set_stream()`](yaml.md#f/yaml_output/yaml_set_stream), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), [`yaml_sequence_open()`](yaml.md#f/yaml_output/yaml_sequence_open), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), `set()`

### *subroutine*  dynamic_memory_base/f_malloc_finalize()

* **Options:**
  * **dump** *[**logical* *,* *in,* *]* :: < Dump always information,
  * **process_id** *[**integer* *,* *out,* *]* :: < retrieve the process_id
* **Use:** 
  [`yaml_output`](yaml.md#f/yaml_output), [`f_utils`](memory.md#f/f_utils)
* **Called from:**
  `f_lib_finalize()`, `f_lib_finalize_noreport()`
* **Call to:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), `prepend()`, [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), [`yaml_warning()`](yaml.md#f/yaml_output/yaml_warning), [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close), [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), `memstate_report()`, [`yaml_sequence_close()`](yaml.md#f/yaml_output/yaml_sequence_close), [`yaml_close_stream()`](yaml.md#f/yaml_output/yaml_close_stream), [`f_delete_file()`](memory.md#f/f_utils/f_delete_file), `memstate_init()`

### *subroutine*  dynamic_memory_base/f_malloc_dump_status()

* **Options:**
  * **filename** *[**character(len=\*)* *,* *in,* *]* :: < file to which the memory should be dumped
  * **dict_summary** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *inout,pointer* *]*
* **Use:** 
  [`yaml_output`](yaml.md#f/yaml_output)
* **Call to:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), `set()`, [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`yaml_get_default_stream()`](yaml.md#f/yaml_output/yaml_get_default_stream), [`yaml_set_stream()`](yaml.md#f/yaml_output/yaml_set_stream), [`yaml_newline()`](yaml.md#f/yaml_output/yaml_newline), [`yaml_warning()`](yaml.md#f/yaml_output/yaml_warning), `f_dump_all_errors()`, [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close), [`yaml_close_stream()`](yaml.md#f/yaml_output/yaml_close_stream)

### *subroutine*  dynamic_memory_base/f_free_str_ptr(length, array)

* **Parameters:**
  * **length** *[**integer* *,* *in* *]*
  * **array** (\*) *[**character(len=length)* *,* *inout,pointer* *]*
* **Options:**
  **cptr** *[**logical* *,* *in,* *]*
* **Use:** 
  `metadata_interfaces` (`getc1ptr` => `metadata_address()`)

## Memory initialisers

<a id="f/f_utils"></a>

### Quick access

* **Types:**
  [`f_dump_buffer`](memory.md#f/f_utils/f_dump_buffer), [`f_none_object`](memory.md#f/f_utils/f_none_object), [`f_progress_bar`](memory.md#f/f_utils/f_progress_bar)
* **Variables:**
  [`f_zero`](memory.md#f/f_utils/f_zero)
* **Routines:**
  [`assignment(=)()`](memory.md#f/f_utils/assignment(=)), [`f_assert()`](memory.md#f/f_utils/f_assert), [`f_close()`](memory.md#f/f_utils/f_close), [`f_delete_file()`](memory.md#f/f_utils/f_delete_file), [`f_diff()`](memory.md#f/f_utils/f_diff), [`f_file_exists()`](memory.md#f/f_utils/f_file_exists), [`f_file_unit()`](memory.md#f/f_utils/f_file_unit), [`f_get_free_unit()`](memory.md#f/f_utils/f_get_free_unit), [`f_get_option()`](memory.md#f/f_utils/f_get_option), [`f_getpid()`](memory.md#f/f_utils/f_getpid), [`f_humantime()`](memory.md#f/f_utils/f_humantime), [`f_increment()`](memory.md#f/f_utils/f_increment), [`f_mkdir()`](memory.md#f/f_utils/f_mkdir), [`f_move_file()`](memory.md#f/f_utils/f_move_file), [`f_none()`](memory.md#f/f_utils/f_none), [`f_open_file()`](memory.md#f/f_utils/f_open_file), [`f_pause()`](memory.md#f/f_utils/f_pause), [`f_progress_bar_new()`](memory.md#f/f_utils/f_progress_bar_new), [`f_rewind()`](memory.md#f/f_utils/f_rewind), [`f_savetxt()`](memory.md#f/f_utils/f_savetxt), [`f_size()`](memory.md#f/f_utils/f_size), [`f_sizeof()`](memory.md#f/f_utils/f_sizeof), [`f_system()`](memory.md#f/f_utils/f_system), [`f_time()`](memory.md#f/f_utils/f_time), [`f_tty()`](memory.md#f/f_utils/f_tty), [`f_utils_errors()`](memory.md#f/f_utils/f_utils_errors), [`f_utils_recl()`](memory.md#f/f_utils/f_utils_recl), [`update_progress_bar()`](memory.md#f/f_utils/update_progress_bar)

### Needed modules

- [`dictionaries`](yaml_str.md#f/dictionaries) ([`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`f_err_define()`](errors.md#f/dictionaries/f_err_define), [`dictionary`](yaml_str.md#f/dictionaries/dictionary), [`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), `max_field_length()`): High-level dictionary API used throughout Futile and BigDFT.  A dictionary is a pointer-based tree that can represent scalars, ordered mappings, and lists.  It maps directly to YAML data and is manipulated with constructors
- [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa))
- [`f_precisions`](f_prec.md#f/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
- `f_zero_module`

### Types

- ### *type*  f_utils/f_dump_buffer

  * **Type fields:**
    * % buf (\*) *[**character(len=1)* *,* *pointer* *]*
    * % ipos *[**integer* *]*
- ### *type*  f_utils/f_none_object

  * **Type fields:**
    * % none *[**character(len=len(null))* *]*
- ### *type*  f_utils/f_progress_bar

  * **Type fields:**
    * % message *[**character(len=90)* *]* :: < Message of the progress bar to be updated
    * % ncall *[**integer* *]* :: < number of times the progress bar is called
    * % nstep *[**integer* *]* :: < number of steps for the progress
    * % t0 *[**integer* *]* :: < creation time of the progress bar

### Variables

- ### f_utils/f_zero *[**public* *]*

### Subroutines and functions

### *interface*  f_utils/f_diff()

### *interface*  f_utils/f_sizeof()

### *interface*  f_utils/f_size()

### *interface*  f_utils/f_increment()

### *interface*  f_utils/f_humantime(ns)

* **Parameters:**
  **ns** *[**real* *,* *in* *]* :: <nanoseconds
* **Options:**
  **short_bn** *[**logical* *,* *in,* *]*

### *interface*  f_utils/f_assert(condition, id)

* **Parameters:**
  * **condition** *[**logical* *,* *in* *]*
  * **id** *[**character(len=\*)* *,* *in* *]*
* **Options:**
  * **err_id** *[**integer* *,* *in,* *]*
  * **err_name** *[**character(len=\*)* *,* *in,* *]*

### *interface*  f_utils/f_savetxt()

### *interface*  f_utils/f_get_option()

### *interface*  f_utils/assignment(=)()

### *subroutine*  f_utils/f_utils_errors()

* **Called from:**
  `initialize_flib_errors()`
* **Call to:**
  [`f_err_define()`](errors.md#f/dictionaries/f_err_define)

### *function*  f_utils/f_none()

* **Return:**
  **f_none** *[*[*f_none_object*](memory.md#f/f_utils/f_none_object) *]*

### *function*  f_utils/f_time()

* **Return:**
  **f_time** *[**integer* *]*
* **Called from:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`f_progress_bar_new()`](memory.md#f/f_utils/f_progress_bar_new), [`update_progress_bar()`](memory.md#f/f_utils/update_progress_bar), `f_clock()`, `f_timing_reset()`, `f_timing_checkpoint()`, `f_timing_stop()`, `f_timing()`, `f_profile()`

### *subroutine*  f_utils/f_assert(condition, id)

* **Parameters:**
  * **condition** *[**logical* *,* *in* *]*
  * **id** *[**character(len=\*)* *,* *in* *]*
* **Options:**
  * **err_id** *[**integer* *,* *in,* *]*
  * **err_name** *[**character(len=\*)* *,* *in,* *]*
* **Use:** 
  [`module_f_malloc`](memory.md#f/module_f_malloc) (`f_malloc_routine_name()`), [`yaml_strings`](yaml_strings.md#f/yaml_strings), [`dictionaries`](yaml_str.md#f/dictionaries)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *function*  f_utils/f_progress_bar_new()

* **Options:**
  **nstep** *[**integer* *,* *in,* *]*
* **Return:**
  **bar** *[*[*f_progress_bar*](memory.md#f/f_utils/f_progress_bar) *]*
* **Call to:**
  [`f_time()`](memory.md#f/f_utils/f_time), `f_zero()`

### *subroutine*  f_utils/update_progress_bar(bar, istep)

* **Parameters:**
  * **bar** *[*[*f_progress_bar*](memory.md#f/f_utils/f_progress_bar) *,* *inout* *]*
  * **istep** *[**integer* *,* *in* *]*
* **Use:** 
  [`yaml_strings`](yaml_strings.md#f/yaml_strings)
* **Called from:**
  [`dump_progress_bar()`](yaml.md#f/yaml_output/dump_progress_bar)
* **Call to:**
  [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), `f_zero()`, [`f_time()`](memory.md#f/f_utils/f_time), [`f_humantime()`](memory.md#f/f_utils/f_humantime), [`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa)

### *function*  f_utils/f_humantime(ns)

* **Parameters:**
  **ns** *[**real* *,* *in* *]* :: <nanoseconds
* **Options:**
  **short_bn** *[**logical* *,* *in,* *]*
* **Return:**
  **time** *[**character(len=95)* *]*
* **Use:** 
  [`yaml_strings`](yaml_strings.md#f/yaml_strings)
* **Called from:**
  [`update_progress_bar()`](memory.md#f/f_utils/update_progress_bar), `f_profile()`, `f_lib_finalize()`
* **Call to:**
  [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy)

### *function*  f_utils/f_tty(unit)

* **Parameters:**
  **unit** *[**integer* *,* *in* *]*
* **Return:**
  **f_tty** *[**logical* *]*
* **Called from:**
  [`dump_progress_bar()`](yaml.md#f/yaml_output/dump_progress_bar)

### *subroutine*  f_utils/f_pause(sec)

* **Parameters:**
  **sec** *[**integer* *,* *in* *]* :: < seconds to be waited

### *subroutine*  f_utils/f_utils_recl(unt, recl_max, recl)

* **Parameters:**
  * **unt** *[**integer* *,* *in* *]* :: < unit to be checked for record length
  * **recl_max** *[**integer* *,* *in* *]* :: < maximum value for record length
  * **recl** *[**integer* *,* *out* *]*
* **Called from:**
  [`yaml_set_stream()`](yaml.md#f/yaml_output/yaml_set_stream)

### *subroutine*  f_utils/f_file_exists(file, exists)

* **Parameters:**
  * **file** *[**character(len=\*)* *,* *in* *]*
  * **exists** *[**logical* *,* *out* *]*
* **Called from:**
  [`f_file_unit()`](memory.md#f/f_utils/f_file_unit), [`f_delete_file()`](memory.md#f/f_utils/f_delete_file), `get_proc_status_dict()`, [`yaml_parse_from_file()`](yaml.md#f/yaml_parse/yaml_parse_from_file)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_close(unit)

* **Parameters:**
  **unit** *[**integer* *,* *in* *]*
* **Called from:**
  [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), [`f_delete_file()`](memory.md#f/f_utils/f_delete_file), [`yaml_cite()`](yaml.md#f/yaml_output/yaml_cite)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_file_unit(file, unit)

* **Parameters:**
  * **file** *[**character(len=\*)* *,* *in* *]*
  * **unit** *[**integer* *,* *out* *]*
* **Called from:**
  [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), [`f_delete_file()`](memory.md#f/f_utils/f_delete_file), [`f_open_file()`](memory.md#f/f_utils/f_open_file)
* **Call to:**
  [`f_file_exists()`](memory.md#f/f_utils/f_file_exists), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *function*  f_utils/f_get_free_unit()

* **Options:**
  **unit** *[**integer* *,* *in,* *]*
* **Return:**
  **unt2** *[**integer* *]*
* **Called from:**
  [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), `f_iostream_from_file()`, [`f_open_file()`](memory.md#f/f_utils/f_open_file), [`yaml_set_stream()`](yaml.md#f/yaml_output/yaml_set_stream)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_mkdir(dir, path)

* **Parameters:**
  * **dir** *[**character(len=\*)* *,* *in* *]* :: < Directory to be created
  * **path** *[**character(len=\*)* *,* *out* *]* :: < Path of the created directory (trailing slash added)
* **Use:** 
  [`f_precisions`](f_prec.md#f/f_precisions) ([`f_integer()`](f_prec.md#f/f_precisions/f_integer))
* **Call to:**
  `f_zero()`, [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_delete_file(file)

* **Parameters:**
  **file** *[**character(len=\*)* *,* *in* *]*
* **Called from:**
  [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize)
* **Call to:**
  [`f_file_exists()`](memory.md#f/f_utils/f_file_exists), [`f_file_unit()`](memory.md#f/f_utils/f_file_unit), [`f_close()`](memory.md#f/f_utils/f_close), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_move_file(src, dest)

* **Parameters:**
  * **src** *[**character(len=\*)* *,* *in* *]*
  * **dest** *[**character(len=\*)* *,* *in* *]*
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *function*  f_utils/f_getpid()

* **Return:**
  **f_getpid** *[**integer* *]*
* **Called from:**
  `get_proc_status_dict()`

### *subroutine*  f_utils/f_system(command)

* **Parameters:**
  **command** *[**character(len=\*)* *,* *in* *]*
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_rewind(unit)

* **Parameters:**
  **unit** *[**integer* *,* *in* *]*
* **Called from:**
  [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)

### *subroutine*  f_utils/f_open_file(unit, file)

* **Parameters:**
  * **unit** *[**integer* *,* *inout* *]*
  * **file** *[**character(len=\*)* *,* *in* *]*
* **Options:**
  * **status** *[**character(len=\*)* *,* *in,* *]*
  * **position** *[**character(len=\*)* *,* *in,* *]*
  * **action** *[**character(len=\*)* *,* *in,* *]*
  * **binary** *[**logical* *,* *in,* *]*
* **Use:** 
  [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy))
* **Called from:**
  [`yaml_set_stream()`](yaml.md#f/yaml_output/yaml_set_stream), [`yaml_cite()`](yaml.md#f/yaml_output/yaml_cite)
* **Call to:**
  [`f_file_unit()`](memory.md#f/f_utils/f_file_unit), [`f_get_free_unit()`](memory.md#f/f_utils/f_get_free_unit), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw)


# pyfutile.md

# Python modules

This modules are provided with the library to ease the interoperability between I/O
of the Fortran library with python scripting

## Utils module

This file contains some low-level useful functions

### *class* futile.Utils.Node(obj, valid_if=None)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

An object that is associated to a queue.
Has a requirement and a validity function as well as a generation function
that is triggered in case the node is not valid.

* **Parameters:**
  **obj** ([*object*](https://docs.python.org/3/builtins/functions.html#object)) – a generic object

#### requires(node, generator)

Set the dependency between two nodes.

* **Parameters:**
  * **node** ([*Node*](pyfutile.md#futile.Utils.Node)) – the node from which this one depends.
    If this is a valid node, and the present is not, it should employ
    the generator function for creating the node.
  * **generator** (*func*) – function which should be called to make the
    node valid. Should have as arguments the two objects associated
    the node (the current one is the first argument)

#### *property* valid

#### valid_if(func)

Set the function as callback to check the validity of the node.

* **Parameters:**
  **func** (*func*) – function that has the node object as a the first
  argument and returns a boolean which assess the validity
  of the function.

#### validate()

This function makes the node valid by validating its dependency
and by calling the generator function if this is not the case.

* **Returns:**
  the value of self.valid. Should be true.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### *class* futile.Utils.ObjectSerialization(obj=None, files=None, version=None)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Serialization of a class into an archive.

This class can be employed each time that we would like to identify the
minimal set of files needed to instantiate an object.
Files and objects are put in an archive that can in this way be used
to retrieve and reinstantiate the object.

* **Parameters:**
  * **obj** ([*object*](https://docs.python.org/3/builtins/functions.html#object)) – a instance of the object to be serailized. Necessary
    in case some attributes of it have to be included in the
    serialization.
  * **version** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the version of the desired serialization.
    If absent, the default is considered.
  * **files** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary of the files to be included.
    The dictionary should be of the form {<filename>: <abspath>}
    or rather {<filename>: {‘archive’:<archive_path>, ‘file’:<member>}}
    in which case the file <member> of the archive <archive_path>
    will be included. The file will be included in the serialization
    as <filename>.

#### cached_attributes *= {'1.0': {}}*

#### dump(archive, extra_encoder_functions=[])

Create an archive with the entire set of information of the
Serialization. Such a tarfile should be such that the same
analysis of the object is possible

* **Parameters:**
  * **archive** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the archive to serialize the object to.
  * **extra_encoder_functions** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – see :py:func:serialize_objects.

#### *classmethod* load(archive, init_function, tmpdir_prefix='', load_functions={}, serialization_version=None, \*\*kwargs)

Create a class instance from a serialized archive.

* **Parameters:**
  * **archive** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the path of the archive
  * **init_function** (*func*) – function that should be called at the
    class instantiation
  * **load_functions** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary of load functions per
    cached attribute. The function signature is the class instance,
    the files list, and the attribute.
  * **serialization_version** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – version of the load
  * **tmpdir_prefix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – prefix to be added to the temporary directory
  * **\*\*kwargs** – other arguments that have to be passed to the
  * **init_function**
* **Returns:**
  Instance of the class

#### version *= '1.0'*

version of the serialization

### futile.Utils.create_tarball(filename, files, objects={})

Assemble files and objects in a tarball

* **Parameters:**
  * **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the name of the archive. Determine the tarball
    compression method from its extension.
  * **files** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *,*[*set*](https://docs.python.org/3/builtins/stdtypes.html#set)) – file paths that have to be included in the tarball.
    If it is a dict, it should be in the form “{arcname : file}”,
    where file is the path of the file to be put, and arcname
    is the name of thefile that would be used in the archive.
    If it is a set, the file will preserve its name in the archive
  * **objects** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary ‘{arcname: buffer}’ of the buffers that
    will have to be serialized in the arcname position
    the buffers are given as class::io.BytesIO instance,
    following specification of the func:serialize_objects function.

### futile.Utils.data_path(archive, dest='.', path='datalake', branch='main', github_repo='BigDFT-group/resources')

### futile.Utils.dict_diff(d1, d2)

Returns the part of two dictionaries which is not common between the two.

### futile.Utils.dict_get(inp, \*subfields)

Find the value of the provided sequence of keys in the dictionary,
if available.

Retrieve the value of the dictionary in a sequence of keys if it is
available. Otherwise it provides as default value the last item of the
sequence `subfields`.

* **Parameters:**
  * **inp** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the top-level dictionary. Unchanged on exit.
  * **subfields** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,*[*object*](https://docs.python.org/3/builtins/functions.html#object)) – keys, ordered by level, that have to be
    retrieved from topmost level of `inp`. The last item correspond
    to the value to be set.
* **Returns:**
  The value provided by the sequence of subfields if available,
  otherwise the default value given as the last item of the `subfields`
  sequence.

### futile.Utils.dict_merge(dest, src)

Recursive dict merge. Inspired by [`dict.update()`](https://docs.python.org/3/builtins/stdtypes.html#dict.update), instead of
updating only top-level keys, dict_merge recurses down into dicts nested
to an arbitrary depth, updating keys. The `src` is merged into
`dest`.  From angstwad/dict-merge.py

* **Parameters:**
  * **dest** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dict onto which the merge is executed
  * **src** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dict merged into dest

### futile.Utils.dict_set(inp, \*subfields)

Ensure the provided fields and set the value

Provide a entry point to the dictionary.
Useful to define a key in a dictionary that may not have the
previous keys already defined.

* **Parameters:**
  * **inp** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the top-level dictionary
  * **subfields** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,*[*object*](https://docs.python.org/3/builtins/functions.html#object)) – keys, ordered by level, that have to be
    retrieved from topmost level of `inp`.
    The last item correspond to the value to be set .

### Example

```pycon
>>> inp={}
>>> dict_set(inp,'dft','nspin','mpol',2)
>>> print (inp)
{'dft': {'nspin': {'mpol': 2}}}
```

### futile.Utils.ensure_copy(src, dest)

Copy src into dest.

Guarantees that the file `dest` is a copy of the file `src`.

* **Parameters:**
  * **src** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the source file. Should be valid.
  * **dest** (*src*) – path of the destination file
* **Returns:**
  `True` if the file needed to be copied, `False` if `src`
  : and `dest` are identical
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### futile.Utils.ensure_dir(file_path)

Guarantees the existance on the directory given by the (relative) file_path

* **Parameters:**
  **file_path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the directory to be created
* **Returns:**
  True if the directory needed to be created,
  : False if it existed already or if an error happened during the
    creation.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### futile.Utils.ensure_object(filename, code_if_obj_not_found=None, glob=None, loc=None)

Identify a pickle file to save a given object on it.
In case this file is present, read the object from it.
Otherwise, assume that the object is ready to be dumped and write
it in the file.

* **Parameters:**
  * **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the path of the file in which the object is
    saved/loaded.
  * **code_if_obj_not_found** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the code to be evaluated if the object has
  * **found.** (*not been*)
  * **globals** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the global variables dictionary
  * **locals** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the local variables dictionary
* **Returns:**
  The result from the pickle file or from the code to be executed
* **Return type:**
  [object](https://docs.python.org/3/builtins/functions.html#object)

### futile.Utils.execute(\*args)

### futile.Utils.execute_code_if(condition, code, glob=None, loc=None)

Execute code if condition is true

* **Parameters:**
  * **condition** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – if true the code is executed
  * **code_if_obj_not_found** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the code to be evaluated if the object has
    not been found.
  * **globals** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the global variables dictionary
  * **locals** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the local variables dictionary
* **Returns:**
  the object returned from the code executed, None otherwise

### futile.Utils.file_list(directory='.', suffix=None, prefix=None, exclude=None, include_directory_path=False)

Return the list of the files inside a given directory

* **Parameters:**
  * **directory** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the directory to search into
  * **suffix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the suffix that the files should have
  * **prefix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the prefix that the files should have
  * **exclude** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – exclude the files which matches this string from the list
  * **include_directory_path** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – if True includes the path of
    the directory in the list.
* **Returns:**
  list of the files that matches the requirements.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

### futile.Utils.file_time(filename)

Determine the time of the last modification of a file.

* **Parameters:**
  **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the file to inspect.
* **Returns:**
  time of the modified file. Returns 0 if the file does not exist.
* **Return type:**
  [float](https://docs.python.org/3/builtins/functions.html#float)

### futile.Utils.fill_dictionary_in_parallel(nthreads, keys, func, \*\*kwargs)

Fill a dictionary of a given set of keys with the return value
of a function which accept this key as a first argument

* **Parameters:**
  * **nthreads** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – the number of threads of the pool
  * **keys** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – the arguments of the function. Will be the list of the
    dictionary
  * **func** (*func*) – the python function that has the key as a last argument
  * **\*\*kwargs** – further arguments of the function, if needed
* **Returns:**
  the key-> obj dictionary with the obj the return value of func
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)

### futile.Utils.find_files(regexp, archive=None)

Returns a list of the paths to the files that follow the regular expression
regexp. They are searched from the current working directory or from an
archive given as optional argument.

* **Parameters:**
  * **regexp** (*string*) – A regular expression
  * **archive** – an opened tarfile archive (optional)
* **Returns:**
  a list of all the paths that agree with the regexp
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list) of strings
* **Raises:**
  ValueError if the regexp does not find a single path.

Example:

```default
#Find all python files in the current working directory
find_files('*py')

#An exmple outside of the current working directory
find_files('*/log-*.yaml')

#Example using a tarfile
import tarfile
my_archive = tarfile.open('archive.tar.gz')
find_files('*/*/log-*.yaml', archive=my_archive)
```

### futile.Utils.floatify(scalar)

Useful to make float from strings compatible from fortran or yaml

* **Parameters:**
  **scalar** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* [*float*](https://docs.python.org/3/builtins/functions.html#float)) – When string representing a float that might be
  given in fortran notation, otherwise it might be a floating point
* **Returns:**
  float. The value associated to scalar as a floating point number

### Example

```pycon
>>> # this would be the same with "1.e-4" or with 0.0001
>>> floatify('1.d-4')
1.e-4
>>> floatify('.inf') == float('inf')
True
```

### futile.Utils.function_signature_regenerator(target_kwargs_function, fun_name='', fun_docstring='', \*\*kwargs)

Generate the function of the name provided by fun_name,
with signature provided by the kwargs dictionary.

* **Parameters:**
  * **target_kwargs_function** (*func*) – keyword arguments function that will be
    used for the generated function.
  * **fun_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – name of the regenerated function. If empty it will be
    the `target_kwargs_functon.__name__` prefixed by `regenerated`,
    which will be copied in the docstring of the regenerated function.
  * **fun_docstring** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – docstring of the generated function, if empty it
    will take the docstring from `target_kwargs_function`.
  * **\*\*kwargs** – keyword arguments which will represent the signature of the
    generated function.

### Example

```pycon
>>> def write_kwargs(**kwargs):
>>>     """
>>>     Convert keyword arguments into a string
>>>     """
>>>     return str(kwargs)
>>> write_opts=function_signature_regenerator(write_kwargs,
>>>                                           fun_name='write_opts',
>>>                                           opt1='default1',
>>>                                           opt2='default2')
>>> help(write_opts)
>>> print (write_opts())
Help on function write_opts:
```

write_opts(opt1=’default1’, opt2=’default2’)
: Convert keyword arguments into a string

{‘opt1’: ‘default1’, ‘opt2’: ‘default2’}

### futile.Utils.get_curl_command(sha, size, repo)

### futile.Utils.get_sha_and_size(filename)

### futile.Utils.kw_pop(\*args, \*\*kwargs)

Treatment of kwargs. Eliminate from kwargs the tuple in args.

### Example

```pycon
>>> kwargs = {'one': 1, 'two': 2, 'three': 3}
>>> # Existing value, default ignored
>>> kw2, two_maybe = kw_pop('two', 100, **kwargs)
>>> print (kw2, two_maybe)
{'one': 1, 'three': 3}, 2
>>> # Not, existing value, default considered
>>> kw2, four_maybe = kw_pop('four', 4, **kwargs)
>>> print (kw2, four_maybe)
{'one': 1, 'two': 2, 'three': 3}, 4
```

### futile.Utils.make_dict(inp)

Transform the instance `inp` into a python dictionary.
If inp is already a dictionary, it performs a copy.

* **Parameters:**
  **inp** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – a instance of a Class which inherits from dict
* **Returns:**
  the copy of the class, converted as a dictionary
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)

### futile.Utils.merge_two_dicts(x, y)

### futile.Utils.more_recent_than_parent(filename, parent)

Filename should be more recent than parent

### futile.Utils.non_null_size(filename)

Control if the file has nonzero size and exists

### futile.Utils.option_line_generator(separator='--', \*\*kwargs)

Associate to each of the keyword arguments a command line argument.

* **Parameters:**
  * **separator** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – The string needed to separate the options.
  * **arguments** (*Might be '--' for command-line*)
  * **'** (*but also*)
  * **'**
  * **signatures.** (*for function*)

#### WARNING
The separator comes **before** the first argument therefore pay
attention to lstrip it in case you want to use it as a function
signature string.

### Example

```pycon
>>> option_line_generator(arg1='val1',arg2='val2')
'--arg1=val1 --arg2=val2'
```

### futile.Utils.property_attribute(self, attribute, code_if_not_found)

### futile.Utils.push_path(inp, \*keys)

Follow in the dictionary inp the path indicated by the keys.
If this path does not exists creates it.

* **Parameters:**
  * **inp** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary
  * **keys** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – keys of the path to follow
* **Returns:**
  (`branch`,\`\`key\`\`) tuple, where
  * `branch` (dict): the dictionary of the second-last item of the path
  * `key` (str): the last item of the path

### Example

```pycon
>>> inp={}
>>> d,key=push_path(inp,'dft','nspin','mpol')
>>> print (d,key)
>>> print (inp)
{},'mpol'
{'dft': {'nspin': {}}}
```

```pycon
>>> inp={'dft': {'nspin': {'mpol': 2}}}
>>> d,key=push_path(inp,'dft','nspin','mpol')
>>> print (d,key)
>>> print (inp)
{'mpol': 2},'mpol'
{'dft': {'nspin': {'mpol': 2}}}
```

### futile.Utils.serialize_objects(objects, extra_encoder_functions=[])

Convert a dictionary of objects into buffers.
Employs json serialization into StringIO instances

* **Parameters:**
  * **objects** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary of key/value pair of objects to be serialized
  * **extra_encoder_functions** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *)*) – list of dictionaries of the format
    {‘cls’: Class, ‘func’: function} which is employed in the
    serialization
* **Returns:**
  dictionary of key/buffer pairs
* **Return type:**
  [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)

### futile.Utils.sort_lists(sort_by, ascending, \*lists)

Sort lists altogether following the lists indicated by the `sort_by`
index.

* **Parameters:**
  * **sort_by** ([*int*](https://docs.python.org/3/builtins/functions.html#int)) – the index of the list which has to be taken as reference
    for sorting
  * **ascending** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – Sort is performed in ascending order if True
  * **\*lists** – sequence of lists to be mutually sorted.
    They have to be of the same length.
* **Returns:**
  tuple of sorted lists

Example:
>>> l1=[5,3,4]
>>> l2=[‘c’,’t’,’q’]
>>> l3=[6,3,7]
>>> print (sort_lists(0,True,l1,l2,l3))
>>> print (sort_lists(2,True,l1,l2,l3))
[(3, 4, 5), (‘t’, ‘q’, ‘c’), (3, 7, 6)]
[(3, 5, 4), (‘t’, ‘c’, ‘q’), (3, 6, 7)]

### futile.Utils.split_contiguous(lst)

Splits a sorted list of integers into sublists of contiguous integers.

This function takes a sorted list of integers and splits it into multiple
sublists, where each sublist contains contiguous integers. A new sublist
starts whenever a gap between integers is detected.

* **Parameters:**
  **lst** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *of* [*int*](https://docs.python.org/3/builtins/functions.html#int)) – A sorted list of integers.
* **Returns:**
  A list of sublists, where each sublist contains
  contiguous integers.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list) of [list](https://docs.python.org/3/builtins/stdtypes.html#list) of [int](https://docs.python.org/3/builtins/functions.html#int)

### Example

```pycon
>>> split_contiguous([1, 2, 3, 5, 6, 10, 11, 12, 15])
[[1, 2, 3], [5, 6], [10, 11, 12], [15]]
>>> split_contiguous([1, 3, 4, 5, 8])
[[1], [3, 4, 5], [8]]
>>> split_contiguous([])
[]
```

#### NOTE
This function has been generated by ChatGPT on Jan 20, 2025 with the
following prompt: “I have a python list whose elements are sorted
integers. I would like to  write a program which splits this list
into multiple sublists as soon as the elements are not anymore contiguous.
Can you write me this function with a prper docstring according
to sphinx napoleon extension syntax?”

### futile.Utils.split_kwargs(kwargs, sub_kwargs)

Split a dictionary of kwargs from a subset.

* **Parameters:**
  * **kwargs** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – the original dictionary.
  * **sub_kwargs** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary providing the {‘key’: default}
    set of arguments which should be splitted from kwargs.
* **Returns:**
  (new_kw, sub_kw) the splitted dictionaries
* **Return type:**
  [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)

### futile.Utils.tarfile_is_coherent(filename)

Checks the coherency of the tarfile.

* **Parameters:**
  **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the tarfile.
* **Returns:**
  True if the tarfile is good to go.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)
* **Raises:**
  **Exception if the tarfile is not valid.** – 

### futile.Utils.to_list(obj)

Convert an object to a list in a safe, generalized way.

This function converts any iterable object into a list, except for
strings and bytes, which are treated as atomic values and wrapped
into a single-element list. Non-iterable objects are also wrapped
into a single-element list.

* **Parameters:**
  **obj** – The object to convert. Can be any type, including iterable
  objects (lists, tuples, sets, generators, NumPy arrays,
  pandas Series), or atomic values.
* **Returns:**
  A list representation of `obj`. If `obj` is a string
  or bytes, returns `[obj]`. If `obj` is any other iterable,
  returns `list(obj)`. Otherwise, returns `[obj]`.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

### Examples

```pycon
>>> to_list("foo")
['foo']
>>> to_list(["a", "b"])
['a', 'b']
>>> to_list((1, 2))
[1, 2]
>>> to_list(5)
[5]
>>> to_list(None)
[None]
>>> to_list({"x", "y"})
['x', 'y']  # order not guaranteed for sets
```

### futile.Utils.unique_filename(prefix)

Provides a filename with a unique id appended

* **Parameters:**
  **prefix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the prefix of the file
* **Returns:**
  filename
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

### futile.Utils.unpack_tarball(archive, tmpdir_prefix='tmp_')

Open an archive in a temporary directory

* **Parameters:**
  * **archive** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the path of th archive to open
  * **tmpdir_prefix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – prefix of the temporary directory to untar the
    archive to.
* **Returns:**
  tmpdir, files path of the temporary directory and names of
  : the files extracted by the tarfile
* **Return type:**
  [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)

### futile.Utils.untar_archive(archive, dest='.')

Untar the archive in the destination directory.

* **Parameters:**
  * **archive** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the file to untar.
  * **dest** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – destination directory. Create if not exists.
* **Returns:**
  list of the files contained in the tarball.
* **Return type:**
  [list](https://docs.python.org/3/builtins/stdtypes.html#list)

### futile.Utils.uri_file(filename, path, branch=None, github_repo=None, gitlab_repo=None, dest=None)

Retrieve a file from a uri, a github repo, or a gitlab repo.

This commodity function indicates a file from a given path on a branch of a git
instance in gitlab or github, or on a local disk.

* **Parameters:**
  * **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the name of the file to search
  * **path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the directory in which the filename is supposed to be.
    Can be indicated in a relative way from the local disk or the
    remote repo.
  * **branch** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the branch of the remote repo to look after.
  * **github_repo** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – namespace and project name of the repo in which the file
    is supposed to be. Github version. Alternative to gitlab_repo.
  * **gitlab_repo** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – namespace and project name of the repo in which the file
    is supposed to be. Gitlab version. Alternative to github_repo.
  * **dest** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – if provided, path of the destination file.
* **Returns:**
  absolute path of the retrieved file.
* **Return type:**
  [str](https://docs.python.org/3/builtins/stdtypes.html#str)

### futile.Utils.version_is_compatible(desired_version, present_version)

Assess the compatibility of a version id with a reference.

* **Parameters:**
  * **desired_version** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the version which is used as the reference,
    in the format “x.y”, “x.y.z”, “x.y.z.w”, …
  * **present_version** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the version to be tested against.
* **Returns:**
  True if all the version numbers of the present version are
  : of lower number than the desired one.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### futile.Utils.write(\*args, \*\*kwargs)

Wrapper for print function or print to ensure compatibility with python 2
The arguments are used similarly as the print_function
They can also be generalized to python 2 cases

## YamlIO module

### futile.YamlIO.clean_logfile(logfile_lines, to_remove)

Remove yaml fields from a list of lines.

Removes from a set of lines the yaml_fields contained in the to_remove list.

* **Parameters:**
  **logfile_lines** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – list of the lines of the logfile.

:param Generated from a file by e.g. [`readlines()`](https://docs.python.org/3/library/io.html#io.IOBase.readlines).:
:param to_remove: list of keys to remove from logfile_lines
:type to_remove: list

* **Returns:**
  list of lines where the removed keys have as values the “<folded>” string

### futile.YamlIO.dump(data, filename=None, raw=False, tar=False)

Encapsulate the dumping of dictionaries.

This function is useful to dump a dictionary in yaml or json form.
This may be used as an alternative to the usual
`yaml.dump` method,
especially when the dictionary to be dump’ed is heavy.
No particular attention is paid in human readability of the output.
The dumped information can then be parsed either from json or yaml
interpreter.

* **Parameters:**
  * **data** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *,*[*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – the information to be dumped
  * **filename** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the file in which the information will
    be stored.
    If absent, the information is written on `sys.stdout()`.
  * **raw** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – if `True` the output is in json-style, otherwise it is
    pre-processed by :py:meth:yaml.dump,
    but `None` is passed to `default_flow_style`.
  * **tar** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – if `True` the filename is assumed to be a compressed
    tarfile. The [`tarfile`](https://docs.python.org/3/library/tarfile.html#module-tarfile) module is used to create and
    append information.

### futile.YamlIO.load(file=None, stream=None, doc_lists=True, safe_mode=False, archive=None, member=None)

Encapsulate the loading of yaml documents.

Provides a dictionary, or a list of dictionaries, which
represents the structure of the stream to be loaded.
It also wraps the yaml loader to perform a optimized parsing when the
minloader of PyYaml 3.13 is available.
This wrapper ensures to extract from the stream the maximum possible
information by choosing the best loader available.

* **Parameters:**
  * **file** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the yaml-compliant file containing the stream
    to be loaded
  * **stream** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – the stream to load, overrides the `file` argument
    if present
  * **archive** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – path of the archive to be used for the retrieval
    of the stream
  * **member** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – name of the file to be extracted from the archive.
    the entire archive is parsed if absent
  * **doc_lists** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – if True, ensures that the results is always in a form
    of lists of documents, even in the case of a single doc
    When False, the return type is either a dictionary or a generator
    according to the specifications of yaml.load and
    yaml.load_all respectively.
  * **safe_mode** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool)) – When true, in the case of multiple documents
    in the stream, it loads the document one after another.
    This is useful to avoid losing of all the document list
    in the case when one of the document is
    not yaml compliant, like in the case of a broken logfile.
    It may works only when the separation of the
    documents is indicated by the usual syntax `"---\n"`
    (i.e. no yaml tags between documents)
* **Returns:**
  * a list of dictionaries, if `doc_lists` is set to `True`;
  * a dictionary, if the stream or the file, or the archive contains a
    : single yaml document;
  * a generator if the parsed stream is made of multiple
    : documents *and* `safe_mode` = `False`;
  * a list of dictionaries if the stream is made of multiple documents
    : and `safe_mode` is `True`.

## Inputvars module

Handle the input variable specifications.

This module is the python complement to the specification of the input variables of a
file as provided by the [`f_input_file`](inputfile.md#f/f_input_file) module. It uses the same syntax as defined there
and make possible the interplay between a python-based serialization of the input dictionary
and the construction of

### *class* futile.Inputvars.InputVariable(name, spec)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Define a input variable of a library.
Such object can be initialized and inspected from the dictionary used by futile
and then initialized according to the provided specification.

#### is_valid()

#### set(val)

Set the value of the input variable

#### set_dependent_variable(var)

Set the dependent variable from which impose the profile

#### set_master_variable(var)

Set the variable which is activated when the present has suitable values or profiles

## ArgParse module

Handle and automatize the parsing of input arguments

This module uses the same convention of the [`yaml_parse`](yaml.md#f/yaml_parse) fortran module to define the command line arguments.
Such module can be used to define command line arguments of python scripts that follows the same conventions
or to generate python functions that have the same signature than the provided command arguments.

### futile.YamlArgparse.get_python_function(target_kwargs_function, func_name, func_spec)

Convert a argparse spec into a python function

This function provides a python function with a signature indicated by the `fun_spec` dictionary
With the conventions of the `yaml_argparse` modules.
The [`futile.Utils.function_signature_regenerator()`](pyfutile.md#futile.Utils.function_signature_regenerator) function is used for the conversion

* **Parameters:**
  * **target_kwargs_function** (*func*) – the keyword arguments function we want to give the signature to.
  * **func_name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the function, usually the key of the dictionary whose `func_spec` is the value
  * **func_spec** ([*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict)) – dictionary of the function specifications to be provided to the
    [`futile.Utils.function_signature_regenerator()`](pyfutile.md#futile.Utils.function_signature_regenerator) function.
* **Returns:**
  the genreated function with signature given by the arguments of `func_spec`
  : defaulting to their default value.
* **Return type:**
  func

## Figures module

### *class* futile.Figures.AxisSet(fig, \*args, facecolor=None, frameon=True, sharex=None, sharey=None, label='', xscale=None, yscale=None, box_aspect=None, forward_navigation_events='auto', \*\*kwargs)

Bases: `Axes`

#### cla()

Clear the Axes.

#### create_twin()

#### set(\*, adjustable=<UNSET>, agg_filter=<UNSET>, alpha=<UNSET>, anchor=<UNSET>, animated=<UNSET>, aspect=<UNSET>, autoscale_on=<UNSET>, autoscalex_on=<UNSET>, autoscaley_on=<UNSET>, axes_locator=<UNSET>, axisbelow=<UNSET>, box_aspect=<UNSET>, clip_box=<UNSET>, clip_on=<UNSET>, clip_path=<UNSET>, facecolor=<UNSET>, forward_navigation_events=<UNSET>, frame_on=<UNSET>, gid=<UNSET>, in_layout=<UNSET>, label=<UNSET>, mouseover=<UNSET>, navigate=<UNSET>, path_effects=<UNSET>, picker=<UNSET>, position=<UNSET>, prop_cycle=<UNSET>, rasterization_zorder=<UNSET>, rasterized=<UNSET>, sketch_params=<UNSET>, snap=<UNSET>, subplotspec=<UNSET>, title=<UNSET>, transform=<UNSET>, url=<UNSET>, visible=<UNSET>, xbound=<UNSET>, xlabel=<UNSET>, xlim=<UNSET>, xmargin=<UNSET>, xscale=<UNSET>, xticklabels=<UNSET>, xticks=<UNSET>, ybound=<UNSET>, ylabel=<UNSET>, ylim=<UNSET>, ymargin=<UNSET>, yscale=<UNSET>, yticklabels=<UNSET>, yticks=<UNSET>, zorder=<UNSET>)

Set multiple properties at once.

Supported properties are

Properties:
: adjustable: {‘box’, ‘datalim’}
  agg_filter: a filter function, which takes a (m, n, 3) float array and a dpi value, and returns a (m, n, 3) array and two offsets from the bottom left corner of the image
  alpha: float or None
  anchor: (float, float) or {‘C’, ‘SW’, ‘S’, ‘SE’, ‘E’, ‘NE’, …}
  animated: bool
  aspect: {‘auto’, ‘equal’} or float
  autoscale_on: bool
  autoscalex_on: unknown
  autoscaley_on: unknown
  axes_locator: Callable[[Axes, Renderer], Bbox]
  axisbelow: bool or ‘line’
  box_aspect: float or None
  clip_box: ~matplotlib.transforms.BboxBase or None
  clip_on: bool
  clip_path: Patch or (Path, Transform) or None
  facecolor or fc: 
  <br/>
  ```
  :mpltype:`color`
  ```
  <br/>
  <br/>
  figure: ~matplotlib.figure.Figure or ~matplotlib.figure.SubFigure
  forward_navigation_events: bool or “auto”
  frame_on: bool
  gid: str
  in_layout: bool
  label: object
  mouseover: bool
  navigate: bool
  navigate_mode: unknown
  path_effects: list of .AbstractPathEffect
  picker: None or bool or float or callable
  position: [left, bottom, width, height] or ~matplotlib.transforms.Bbox
  prop_cycle: ~cycler.Cycler
  rasterization_zorder: float or None
  rasterized: bool
  sketch_params: (scale: float, length: float, randomness: float)
  snap: bool or None
  subplotspec: unknown
  title: str
  transform: ~matplotlib.transforms.Transform
  url: str
  visible: bool
  xbound: (lower: float, upper: float)
  xlabel: str
  xlim: (left: float, right: float)
  xmargin: float greater than -0.5
  xscale: unknown
  xticklabels: unknown
  xticks: unknown
  ybound: (lower: float, upper: float)
  ylabel: str
  ylim: (bottom: float, top: float)
  ymargin: float greater than -0.5
  yscale: unknown
  yticklabels: unknown
  yticks: unknown
  zorder: float

#### *classmethod* twinify(ax)

Include the axis provided as a radix of the set

### *class* futile.Figures.FigureSet(\*\*kwargs)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

Container for multiple figures.

Define a container for a plot with the possiblity to switch between simple and gnuplot plotting

Arguments:
title: The title of the master figure

```
**
```

kwargs: arguments for the axis instance

#### add(\*\*kwargs)

#### exists(figname)

True if the Figure exists in the Set

#### invoke(idx)

#### show(figname=None)

### *class* futile.Figures.VertSlider(ax, label, valmin, valmax, valinit=0.5, valfmt='%1.2f', closedmin=True, closedmax=True, slidermin=None, slidermax=None, dragging=True, \*\*kwargs)

Bases: `AxesWidget`

A slider representing a floating point range.

For the slider to remain responsive you must maintain a
reference to it.

### \\\*ax\*

the slider `matplotlib.axes.Axes` instance

### \\\*val\*

the current slider value

### \\\*hline\*

a `matplotlib.lines.Line2D` instance
representing the initial value of the slider

### \\\*poly\*

A `matplotlib.patches.Polygon` instance
which is the slider knob

### \\\*valfmt\*

the format string for formatting the slider text

### \\\*label\*

a `matplotlib.text.Text` instance
for the slider label

### \\\*closedmin\*

whether the slider is closed on the minimum

### \\\*closedmax\*

whether the slider is closed on the maximum

### \\\*slidermin\*

another slider - if not *None*, this slider must be
greater than *slidermin*

### \\\*slidermax\*

another slider - if not *None*, this slider must be
less than *slidermax*

### \\\*dragging\*

allow for mouse dragging on slider

Call [`on_changed()`](pyfutile.md#futile.Figures.VertSlider.on_changed) to connect to the slider event

#### disconnect(cid)

remove the observer with connection id *cid*

#### on_changed(func)

When the slider value is changed, call *func* with the new
slider position

A connection id is returned which can be used to disconnect

#### reset()

reset the slider to the initial value if needed

#### set_val(val)

### futile.Figures.axis_from_data(fig, ax, data)

Transform a data tuple into axis coordinates

### futile.Figures.data_from_data(fig, dst, src, data)

Transform a data tuple of anothe axis in the figure into data of another axis

### futile.Figures.show_image(imgfile, title=None)

Show image file using matplotlib imgread. Useful to bypass the
Jupyter bug for converting a notebook into a pdf file

## Time module

### *class* futile.Time.TimeData(\*filenames, \*\*kwargs)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

#### barwidth *= 0.9*

#### collect_categories(dict_list, vals)

Collect all the categories which belong to all the dictionaries

#### counters()

Inspect the available counters

#### draw_barfigure(fig, axis, data, title)

#### draw_lineplot(ax, data, label)

#### find_items(category, dict_list)

For a given category find the items which have them

#### find_unbalanced(data)

Determine lookup array of unbalanced categories

#### gnuplot_figure(lookup=None, epsfile=None, aggregate=None, select_category=None)

Create a figure to be plotted with gnuplot

Create a gnuplot histogram that can be plotted for production results.

* **Parameters:**
  * **lookup** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – A list of the items of the TimeData instance that will be considered for the histogram
  * **epsfile** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the eps file in which the data will be plot
  * **aggregate** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list)) – list of tuples of the categories to aggregate, accoding to the convention
    (newkey ,[list of oldkeys]) between the original keys and the desired keys
  * **select_category** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str)) – Name of the category to be plot, if specified the internal items of the category will be plot.

#### ignored_counters *= ['CPU parallelism', 'Routines timing and number of calls', 'SUMMARY', 'Report timestamp', 'Hostnames']*

#### inspect_category(cat)

#### inspect_counter(counter, unit=None)

#### load_unbalancing(ax, dict, hosts)

Extract the data for plotting the hostname balancings between different categories in bar chart

#### replot(label)

#### routines_plot(index, event=None)

Draw the plot of the routines level for the run identified by index

#### show()

#### unbalanced(val)

Criterion for unbalancing

#### workload_plot(index, event=None)

Draw the plot of the workload of different classes for the run identified by index

### futile.Time.aggregate_names(data, list_agg)

Aggregate the names of the plot in some different categories
the structure of dict_agg should ba a list of tuples
(newkey ,[list of oldkeys])
between the original keys and the desired keys

### *class* futile.Time.polar_axis(fig, ax, data)

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object)

#### draw_polarplot()

#### dump_timing_level(level, starting_point=None, ilev=0, theta=0, data=None)

Inspect the first level of the given dictionary and dump the profile subroutines at this level

#### step *= 5*


# yaml.md

# YAML handling

## Automatic definition of arguments `yaml_parse`

This module deals with the parsing of yaml streams and their conversion into FUTILE dictionaries.

Anyone which uses python knows how practical it the usage of the `argparse` module.
This FORTRAN module is an attempt to combine the ideas of the argparse approach with the yaml syntax.

<a id="f/yaml_parse"></a>

### Quick access

* **Routines:**
  [`yaml_argparse()`](yaml.md#f/yaml_parse/yaml_argparse), [`yaml_cl_errors()`](yaml.md#f/yaml_parse/yaml_cl_errors), [`yaml_cl_parse_cmd_line()`](yaml.md#f/yaml_parse/yaml_cl_parse_cmd_line), [`yaml_cl_parse_free()`](yaml.md#f/yaml_parse/yaml_cl_parse_free), [`yaml_cl_parse_null()`](yaml.md#f/yaml_parse/yaml_cl_parse_null), [`yaml_cl_parse_option()`](yaml.md#f/yaml_parse/yaml_cl_parse_option), [`yaml_parse_from_file()`](yaml.md#f/yaml_parse/yaml_parse_from_file)

### Needed modules

- [`dictionaries`](yaml_str.md#f/dictionaries) ([`dictionary`](yaml_str.md#f/dictionaries/dictionary), `max_field_length()`): High-level dictionary API used throughout Futile and BigDFT.  A dictionary is a pointer-based tree that can represent scalars, ordered mappings, and lists.  It maps directly to YAML data and is manipulated with constructors
- `yaml_parse_base` (`yaml_load()`, `yaml_parse_database()`, `yaml_parse_from_string()`)

### Subroutines and functions

### *interface*  yaml_parse/yaml_cl_parse_option(parser, name, default_bn, help_string)

* **Parameters:**
  * **parser** *[**yaml_cl_parse* *,* *inout* *]*
  * **name** *[**character(len=\*)* *,* *in* *]*
  * **default_bn** *[**character(len=\*)* *,* *in* *]*
  * **help_string** *[**character(len=\*)* *,* *in* *]*
* **Options:**
  * **shortname** *[**character(len=1)* *,* *in,* *]*
  * **help_dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **first_option** *[**logical* *,* *in,* *]*
  * **conflicts** *[**character(len=\*)* *,* *in,* *]*

### *function*  yaml_parse/yaml_cl_parse_null()

* **Return:**
  **parser** *[**yaml_cl_parse* *]*
* **Called from:**
  [`yaml_cl_parse_free()`](yaml.md#f/yaml_parse/yaml_cl_parse_free), [`yaml_argparse()`](yaml.md#f/yaml_parse/yaml_argparse)

### *subroutine*  yaml_parse/yaml_cl_parse_free(parser)

* **Parameters:**
  **parser** *[**yaml_cl_parse* *,* *inout* *]*
* **Use:** 
  [`dictionaries_base`](yaml_str.md#f/dictionaries_base) ([`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free))
* **Called from:**
  [`yaml_argparse()`](yaml.md#f/yaml_parse/yaml_argparse), [`yaml_cl_parse_cmd_line()`](yaml.md#f/yaml_parse/yaml_cl_parse_cmd_line)
* **Call to:**
  [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`yaml_cl_parse_null()`](yaml.md#f/yaml_parse/yaml_cl_parse_null)

### *subroutine*  yaml_parse/yaml_cl_errors()

* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries)
* **Called from:**
  `initialize_flib_errors()`
* **Call to:**
  [`f_err_define()`](errors.md#f/dictionaries/f_err_define)

### *subroutine*  yaml_parse/yaml_cl_parse_option(parser, name, default_bn, help_string)

* **Parameters:**
  * **parser** *[**yaml_cl_parse* *,* *inout* *]*
  * **name** *[**character(len=\*)* *,* *in* *]*
  * **default_bn** *[**character(len=\*)* *,* *in* *]*
  * **help_string** *[**character(len=\*)* *,* *in* *]*
* **Options:**
  * **shortname** *[**character(len=1)* *,* *in,* *]*
  * **help_dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **first_option** *[**logical* *,* *in,* *]*
  * **conflicts** *[**character(len=\*)* *,* *in,* *]*
* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries), [`yaml_strings`](yaml_strings.md#f/yaml_strings), `yaml_parse_base`
* **Called from:**
  [`yaml_argparse()`](yaml.md#f/yaml_parse/yaml_argparse)
* **Call to:**
  [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`dict_new()`](yaml_str.md#f/dictionaries/dict_new), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), `set()`, `yaml_load()`, `dict_update()`, [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy)

### *subroutine*  yaml_parse/yaml_argparse(options, string_bn)

* **Parameters:**
  * **options** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **string_bn** *[**character(len=\*)* *,* *in* *]*
* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries), [`f_utils`](memory.md#f/f_utils) ([`f_zero()`](memory.md#f/f_utils/f_zero))
* **Call to:**
  [`yaml_cl_parse_null()`](yaml.md#f/yaml_parse/yaml_cl_parse_null), [`yaml_cl_parse_option()`](yaml.md#f/yaml_parse/yaml_cl_parse_option), [`yaml_cl_parse_cmd_line()`](yaml.md#f/yaml_parse/yaml_cl_parse_cmd_line), [`yaml_cl_parse_free()`](yaml.md#f/yaml_parse/yaml_cl_parse_free)

### *subroutine*  yaml_parse/yaml_cl_parse_cmd_line(parser)

* **Parameters:**
  **parser** *[**yaml_cl_parse* *,* *inout* *]*
* **Options:**
  **args** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *out,pointer* *]*
* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries), [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy)), [`yaml_output`](yaml.md#f/yaml_output)
* **Called from:**
  [`yaml_argparse()`](yaml.md#f/yaml_parse/yaml_argparse)
* **Call to:**
  [`f_err_check()`](yaml_str.md#f/dictionaries/f_err_check), `dict_update()`, [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), `dict_copy()`, [`yaml_cl_parse_free()`](yaml.md#f/yaml_parse/yaml_cl_parse_free), `f_lib_finalize_noreport()`, [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), `yaml_load()`

### *subroutine*  yaml_parse/yaml_parse_from_file(dict, fname)

* **Parameters:**
  * **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **fname** *[**character(len=\*)* *,* *in* *]*
* **Options:**
  * **tags** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **mpi_env** *[**mpi_environment* *]*
* **Use:** 
  [`dictionaries`](yaml_str.md#f/dictionaries), `wrapper_mpi`, [`f_utils`](memory.md#f/f_utils), `dynamic_memory`, `yaml_parse_base` (`yaml_parse_from_file` => `parse_from_file()`)
* **Called from:**
  `get_proc_status_dict()`
* **Call to:**
  [`f_file_exists()`](memory.md#f/f_utils/f_file_exists), `yaml_parse_from_char_array()`, [`f_free_str()`](memory.md#f/dynamic_memory_base/f_free_str)

## YAML emitter in Fortran: the [`yaml_output`](yaml.md#f/yaml_output) module

<a id="f/yaml_output"></a>

### Quick access

* **Routines:**
  [`dump_progress_bar()`](yaml.md#f/yaml_output/dump_progress_bar), [`yaml_bib_dump()`](yaml.md#f/yaml_output/yaml_bib_dump), [`yaml_cite()`](yaml.md#f/yaml_output/yaml_cite), [`yaml_close_all_streams()`](yaml.md#f/yaml_output/yaml_close_all_streams), [`yaml_close_stream()`](yaml.md#f/yaml_output/yaml_close_stream), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), [`yaml_dict_dump()`](yaml.md#f/yaml_output/yaml_dict_dump), [`yaml_dict_dump_all()`](yaml.md#f/yaml_output/yaml_dict_dump_all), [`yaml_dict_inspect()`](yaml.md#f/yaml_output/yaml_dict_inspect), [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document), [`yaml_get_default_stream()`](yaml.md#f/yaml_output/yaml_get_default_stream), [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close), [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), [`yaml_new_document()`](yaml.md#f/yaml_output/yaml_new_document), [`yaml_newline()`](yaml.md#f/yaml_output/yaml_newline), [`yaml_output_errors()`](yaml.md#f/yaml_output/yaml_output_errors), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document), [`yaml_scalar()`](yaml.md#f/yaml_output/yaml_scalar), [`yaml_sequence()`](yaml.md#f/yaml_output/yaml_sequence), [`yaml_sequence_close()`](yaml.md#f/yaml_output/yaml_sequence_close), [`yaml_sequence_open()`](yaml.md#f/yaml_output/yaml_sequence_open), [`yaml_set_default_stream()`](yaml.md#f/yaml_output/yaml_set_default_stream), [`yaml_set_stream()`](yaml.md#f/yaml_output/yaml_set_stream), [`yaml_stream_attributes()`](yaml.md#f/yaml_output/yaml_stream_attributes), [`yaml_stream_connected()`](yaml.md#f/yaml_output/yaml_stream_connected), [`yaml_swap_stream()`](yaml.md#f/yaml_output/yaml_swap_stream), [`yaml_warning()`](yaml.md#f/yaml_output/yaml_warning)

### Needed modules

- [`yaml_strings`](yaml_strings.md#f/yaml_strings)
- [`dictionaries`](yaml_str.md#f/dictionaries): High-level dictionary API used throughout Futile and BigDFT.  A dictionary is a pointer-based tree that can represent scalars, ordered mappings, and lists.  It maps directly to YAML data and is manipulated with constructors
- [`f_precisions`](f_prec.md#f/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_output/yaml_map()

general scalar

* **Called from:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), `dump_f_matrix_ptr()`, `memstate_report()`, `f_profile()`, [`yaml_stream_attributes()`](yaml.md#f/yaml_output/yaml_stream_attributes), [`yaml_dict_inspect()`](yaml.md#f/yaml_output/yaml_dict_inspect), [`yaml_bib_dump()`](yaml.md#f/yaml_output/yaml_bib_dump), `f_dump_all_errors()`, `f_lib_finalize()`

### *interface*  yaml_output/yaml_warning()

* **Called from:**
  [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), [`yaml_new_document()`](yaml.md#f/yaml_output/yaml_new_document), [`yaml_cite()`](yaml.md#f/yaml_output/yaml_cite)

### *interface*  yaml_output/yaml_comment()

* **Called from:**
  [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), [`input_file_dump()`](inputfile.md#f/f_input_file/input_file_dump), [`dump_progress_bar()`](yaml.md#f/yaml_output/dump_progress_bar), [`yaml_dict_dump_all()`](yaml.md#f/yaml_output/yaml_dict_dump_all), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document), `f_lib_finalize()`

### *subroutine*  yaml_output/yaml_swap_stream(new_unit, old_unit, ierr)

* **Parameters:**
  * **new_unit** *[**integer* *,* *in* *]* :: < new unit
  * **old_unit** *[**integer* *,* *out* *]* :: < old unit
  * **ierr** *[**integer* *,* *out* *]* :: < error code
* **Call to:**
  [`yaml_get_default_stream()`](yaml.md#f/yaml_output/yaml_get_default_stream), [`yaml_set_default_stream()`](yaml.md#f/yaml_output/yaml_set_default_stream)

### *subroutine*  yaml_output/yaml_output_errors()

* **Use:** 
  [`exception_callbacks`](errors.md#f/exception_callbacks) ([`f_err_set_last_error_callback()`](errors.md#f/exception_callbacks/f_err_set_last_error_callback), [`f_err_set_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_set_all_errors_callback))
* **Called from:**
  `initialize_flib_errors()`
* **Call to:**
  [`f_err_define()`](errors.md#f/dictionaries/f_err_define), [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), [`f_err_set_last_error_callback()`](errors.md#f/exception_callbacks/f_err_set_last_error_callback), [`f_err_set_all_errors_callback()`](errors.md#f/exception_callbacks/f_err_set_all_errors_callback)

### *subroutine*  yaml_output/yaml_set_default_stream(unit, ierr)

* **Parameters:**
  * **unit** *[**integer* *,* *in* *]* :: < stream unit
  * **ierr** *[**integer* *,* *out* *]* :: < error code
* **Called from:**
  [`yaml_swap_stream()`](yaml.md#f/yaml_output/yaml_swap_stream)

### *subroutine*  yaml_output/yaml_get_default_stream(unit)

* **Parameters:**
  **unit** *[**integer* *,* *out* *]*
* **Called from:**
  [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), [`yaml_swap_stream()`](yaml.md#f/yaml_output/yaml_swap_stream), `f_dump_all_errors()`

### *subroutine*  yaml_output/yaml_stream_connected(filename, unit)

* **Parameters:**
  * **filename** *[**character(len=\*)* *,* *in* *]* :: < Filename of the stream to inquire
  * **unit** *[**integer* *,* *out* *]* :: < File unit specified by the user.(by default 6) Returns a error code if the unit
* **Options:**
  **istat** *[**integer* *,* *out,* *]* :: so far
* **Call to:**
  `has_key()`

### *subroutine*  yaml_output/yaml_set_stream()

* **Options:**
  * **unit** *[**integer* *,* *in,* *]* :: < File unit specified by the user.(by default 6) Returns a error code if the unit
  * **filename** *[**character(len=\*)* *,* *in,* *]* :: < Filename of the stream
  * **istat** *[**integer* *,* *out,* *]* :: so far
  * **tabbing** *[**integer* *,* *in,* *]* :: < Indicate a tabbing for the stream (0 no tabbing, default)
  * **record_length** *[**integer* *,* *in,* *]* :: int(record_length,kind=8)
  * **position** *[**character(len=\*)* *,* *in,* *]*
  * **setdefault** *[**logical* *,* *in,* *]* :: < decide if the new stream will be set as default stream. True if absent
* **Use:** 
  [`f_utils`](memory.md#f/f_utils) ([`f_utils_recl()`](memory.md#f/f_utils/f_utils_recl), [`f_get_free_unit()`](memory.md#f/f_utils/f_get_free_unit), [`f_open_file()`](memory.md#f/f_utils/f_open_file))
* **Called from:**
  [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status)
* **Call to:**
  `has_key()`, [`f_get_free_unit()`](memory.md#f/f_utils/f_get_free_unit), [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), [`f_err_throw()`](errors.md#f/dictionaries/f_err_throw), [`f_err_open_try()`](errors.md#f/dictionaries/f_err_open_try), [`f_open_file()`](memory.md#f/f_utils/f_open_file), [`f_get_last_error()`](errors.md#f/dictionaries/f_get_last_error), [`f_err_close_try()`](errors.md#f/dictionaries/f_err_close_try), [`f_utils_recl()`](memory.md#f/f_utils/f_utils_recl), `set()`

### *subroutine*  yaml_output/yaml_stream_attributes()

* **Options:**
  * **unit** *[**integer* *,* *in,* *]* :: < File unit to display
  * **stream_unit** *[**integer* *,* *in,* *]* :: < Stream Id
  * **icursor** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::icursor
  * **flowrite** *[**logical* *,* *out,* *]* :: < @copydoc yaml_stream::flowrite
  * **itab_active** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::itab_active
  * **iflowlevel** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::iflowlevel
  * **ilevel** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::ilevel
  * **ilast** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::ilast
  * **indent** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::indent
  * **indent_previous** *[**integer* *,* *out,* *]* :: < @copydoc yaml_stream::indent_previous
  * **record_length** *[**integer* *,* *out,* *]* :: < Maximum number of columns of the stream (default @link yaml_output::yaml_stream::tot_max_record_length @endlink)
* **Call to:**
  [`yaml_newline()`](yaml.md#f/yaml_output/yaml_newline), [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close)

### *subroutine*  yaml_output/yaml_new_document()

* **Options:**
  **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  `f_timing_reset()`, [`yaml_dict_dump_all()`](yaml.md#f/yaml_output/yaml_dict_dump_all)
* **Call to:**
  [`yaml_warning()`](yaml.md#f/yaml_output/yaml_warning)

### *subroutine*  yaml_output/yaml_flush_document()

* **Options:**
  **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`f_update_database()`](memory.md#f/dynamic_memory_base/f_update_database), [`f_purge_database()`](memory.md#f/dynamic_memory_base/f_purge_database), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document)
* **Call to:**
  `f_utils_flush()`

### *subroutine*  yaml_output/yaml_close_stream()

* **Options:**
  * **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
  * **istat** *[**integer* *,* *out,* *]* :: <error code, zero if suceeded
* **Called from:**
  [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), [`yaml_close_all_streams()`](yaml.md#f/yaml_output/yaml_close_all_streams)
* **Call to:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), `dict_remove()`, [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next)

### *subroutine*  yaml_output/yaml_close_all_streams()

* **Called from:**
  `f_lib_finalize()`, `f_lib_finalize_noreport()`
* **Call to:**
  [`yaml_close_stream()`](yaml.md#f/yaml_output/yaml_close_stream), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document), [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free)

### *subroutine*  yaml_output/yaml_dict_inspect(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
* **Call to:**
  [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close)

### *subroutine*  yaml_output/dump_progress_bar(bar)

* **Parameters:**
  **bar** *[*[*f_progress_bar*](memory.md#f/f_utils/f_progress_bar) *,* *inout* *]*
* **Options:**
  * **step** *[**integer* *,* *in,* *]*
  * **unit** *[**integer* *,* *in,* *]*
* **Use:** 
  [`f_precisions`](f_prec.md#f/f_precisions), [`f_utils`](memory.md#f/f_utils)
* **Call to:**
  [`yaml_newline()`](yaml.md#f/yaml_output/yaml_newline), [`update_progress_bar()`](memory.md#f/f_utils/update_progress_bar), [`f_tty()`](memory.md#f/f_utils/f_tty), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), `f_utils_flush()`

### *subroutine*  yaml_output/yaml_cite(paper)

* **Parameters:**
  **paper** *[**character(len=\*)* *,* *in* *]* :: <the item to be cited in the bibliography
* **Options:**
  **unit** *[**integer* *,* *in,* *]*
* **Use:** 
  `f_bibliography`, [`f_utils`](memory.md#f/f_utils)
* **Call to:**
  `f_bib_item_exists()`, [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), `get_bib_filename()`, [`f_open_file()`](memory.md#f/f_utils/f_open_file), [`f_close()`](memory.md#f/f_utils/f_close), `add()`, `f_bib_get_item()`, [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), [`yaml_warning()`](yaml.md#f/yaml_output/yaml_warning)

### *subroutine*  yaml_output/yaml_bib_dump(citations)

* **Parameters:**
  **citations** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
* **Options:**
  **unit** *[**integer* *,* *in,* *]* :: < yaml stream associated
* **Use:** 
  `f_bibliography`, [`f_utils`](memory.md#f/f_utils)
* **Call to:**
  [`yaml_mapping_open()`](yaml.md#f/yaml_output/yaml_mapping_open), `f_bib_get_item()`, [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), [`yaml_map()`](yaml.md#f/yaml_output/yaml_map), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), [`yaml_mapping_close()`](yaml.md#f/yaml_output/yaml_mapping_close)

### *subroutine*  yaml_output/yaml_scalar(message)

* **Parameters:**
  **message** *[**character(len=\*)* *,* *in* *]* :: < the message to be printed
* **Options:**
  * **advance** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::advance
  * **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
  * **hfill** *[**character(len=\*)* *,* *in,* *]* :: < If present fill the line with the given character

### *subroutine*  yaml_output/yaml_mapping_open()

* **Options:**
  * **mapname** *[**character(len=\*)* *,* *in,* *]* :: < Key of the sequence. @copydoc doc::mapname
  * **label** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::label
  * **tag** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::tag
  * **flow** *[**logical* *,* *in,* *]* :: < @copydoc doc::flow
  * **tabbing** *[**integer* *,* *in,* *]* :: < @copydoc doc::tabbing
  * **advance** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::advance
  * **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), `f_tree_dump()`, `memstate_report()`, `f_profile()`, [`yaml_stream_attributes()`](yaml.md#f/yaml_output/yaml_stream_attributes), [`yaml_dict_inspect()`](yaml.md#f/yaml_output/yaml_dict_inspect), [`yaml_bib_dump()`](yaml.md#f/yaml_output/yaml_bib_dump)

### *subroutine*  yaml_output/yaml_mapping_close()

* **Options:**
  * **advance** *[**character(len=\*)* *,* *in,* *]* :: <@copydoc doc::advance
  * **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), `f_tree_dump()`, `memstate_report()`, `f_profile()`, [`yaml_stream_attributes()`](yaml.md#f/yaml_output/yaml_stream_attributes), [`yaml_dict_inspect()`](yaml.md#f/yaml_output/yaml_dict_inspect), [`yaml_bib_dump()`](yaml.md#f/yaml_output/yaml_bib_dump)

### *subroutine*  yaml_output/yaml_sequence_open()

* **Options:**
  * **mapname** *[**character(len=\*)* *,* *in,* *]* :: < Key of the sequence. @copydoc doc::mapname
  * **label** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::label
  * **tag** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::tag
  * **flow** *[**logical* *,* *in,* *]* :: < @copydoc doc::flow
  * **tabbing** *[**integer* *,* *in,* *]* :: < @copydoc doc::tabbing
  * **advance** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::advance
  * **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), `dump_status_line()`

### *subroutine*  yaml_output/yaml_sequence_close()

* **Options:**
  * **advance** *[**character(len=\*)* *,* *in,* *]*
  * **unit** *[**integer* *,* *in,* *]*
* **Called from:**
  [`f_malloc_finalize()`](memory.md#f/dynamic_memory_base/f_malloc_finalize), `dump_status_line()`

### *subroutine*  yaml_output/yaml_newline()

* **Options:**
  **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  [`f_malloc_dump_status()`](memory.md#f/dynamic_memory_base/f_malloc_dump_status), [`yaml_stream_attributes()`](yaml.md#f/yaml_output/yaml_stream_attributes), [`dump_progress_bar()`](yaml.md#f/yaml_output/dump_progress_bar), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document)

### *subroutine*  yaml_output/yaml_sequence()

* **Options:**
  * **seqvalue** *[**character(len=\*)* *,* *in,* *]* :: < value of the sequence
  * **label** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::label
  * **advance** *[**character(len=\*)* *,* *in,* *]* :: < @copydoc doc::advance
  * **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
  * **padding** *[**integer* *,* *in,* *]* :: < pad the seqvalue with blanks to have more readable output
* **Called from:**
  `dump_status_line()`
* **Call to:**
  [`buffer_string()`](yaml_strings.md#f/yaml_strings/buffer_string)

### *subroutine*  yaml_output/yaml_dict_dump(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]* :: < Dictionary to dump
* **Options:**
  * **unit** *[**integer* *,* *in,* *]* :: < unit in which the dump has to be
  * **flow** *[**logical* *,* *in,* *]* :: < @copydoc doc::flow
  * **verbatim** *[**logical* *,* *in,* *]* :: < if .true. print as comments the calls performed
* **Called from:**
  [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), `f_tree_dump()`, [`yaml_dict_dump_all()`](yaml.md#f/yaml_output/yaml_dict_dump_all), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document), `f_dump_all_errors()`
* **Call to:**
  [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value), [`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), [`dict_item()`](yaml_str.md#f/dictionaries_base/dict_item), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key)

### *subroutine*  yaml_output/yaml_dict_dump_all(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]* :: < Dictionary to dump
* **Options:**
  * **unit** *[**integer* *,* *in,* *]* :: < unit in which the dump has to be
  * **flow** *[**logical* *,* *in,* *]* :: < if .true. inline
  * **verbatim** *[**logical* *,* *in,* *]* :: < if .true. print as comments the calls performed
* **Call to:**
  [`f_err_raise()`](errors.md#f/dictionaries/f_err_raise), [`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), [`yaml_new_document()`](yaml.md#f/yaml_output/yaml_new_document), [`yaml_dict_dump()`](yaml.md#f/yaml_output/yaml_dict_dump), [`yaml_release_document()`](yaml.md#f/yaml_output/yaml_release_document)

### *subroutine*  yaml_output/yaml_release_document()

* **Options:**
  **unit** *[**integer* *,* *in,* *]* :: < @copydoc doc::unit
* **Called from:**
  [`yaml_close_stream()`](yaml.md#f/yaml_output/yaml_close_stream), [`yaml_close_all_streams()`](yaml.md#f/yaml_output/yaml_close_all_streams), [`yaml_dict_dump_all()`](yaml.md#f/yaml_output/yaml_dict_dump_all)
* **Call to:**
  [`yaml_newline()`](yaml.md#f/yaml_output/yaml_newline), [`yaml_comment()`](yaml.md#f/yaml_output/yaml_comment), [`yaml_dict_dump()`](yaml.md#f/yaml_output/yaml_dict_dump), [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`yaml_flush_document()`](yaml.md#f/yaml_output/yaml_flush_document)

## Convenient string functions: the [`yaml_strings`](yaml_strings.md#f/yaml_strings) module

<a id="f/yaml_strings"></a>

### Quick access

* **Types:**
  [`f_string`](yaml_strings.md#f/yaml_strings/f_string)
* **Routines:**
  [`align_message()`](yaml_strings.md#f/yaml_strings/align_message), [`buffer_string()`](yaml_strings.md#f/yaml_strings/buffer_string), [`convert_f_char_ptr()`](yaml_strings.md#f/yaml_strings/convert_f_char_ptr), [`f_char_ptr()`](yaml_strings.md#f/yaml_strings/f_char_ptr), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), [`is_atof()`](yaml_strings.md#f/yaml_strings/is_atof), [`is_atoi()`](yaml_strings.md#f/yaml_strings/is_atoi), [`is_atol()`](yaml_strings.md#f/yaml_strings/is_atol), [`is_atoli()`](yaml_strings.md#f/yaml_strings/is_atoli), [`operator(**)()`](yaml_strings.md#f/yaml_strings/operator(**)), [`operator(.eqv.)()`](yaml_strings.md#f/yaml_strings/operator(.eqv.)), [`operator(.neqv.)()`](yaml_strings.md#f/yaml_strings/operator(.neqv.)), [`read_fraction_string()`](yaml_strings.md#f/yaml_strings/read_fraction_string), [`rstrip()`](yaml_strings.md#f/yaml_strings/rstrip), [`shiftstr()`](yaml_strings.md#f/yaml_strings/shiftstr), [`yaml_blink()`](yaml_strings.md#f/yaml_strings/yaml_blink), [`yaml_bold()`](yaml_strings.md#f/yaml_strings/yaml_bold), [`yaml_date_and_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_date_and_time_toa), [`yaml_date_toa()`](yaml_strings.md#f/yaml_strings/yaml_date_toa), [`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa), [`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa)

### Needed modules

- [`f_precisions`](f_prec.md#f/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.

### *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.)()

### *interface*  yaml_strings/operator(//)()

### *interface*  yaml_strings/operator(+)()

### *interface*  yaml_strings/assignment(=)()

### *interface*  yaml_strings/operator(\*\*)()

### *subroutine*  yaml_strings/f_strcpy(dest, src)

* **Parameters:**
  * **dest** *[**character(len=\*)* *,* *out* *]*
  * **src** *[**character(len=\*)* *,* *in* *]*
* **Called from:**
  `set_elem()`, `storage_data()`, `stored_key()`, `stored_value()`, [`f_purge_database()`](memory.md#f/dynamic_memory_base/f_purge_database), [`f_malloc_set_status()`](memory.md#f/dynamic_memory_base/f_malloc_set_status), `nullify_f_enum()`, [`input_keys_get_profile()`](inputfile.md#f/f_input_file/input_keys_get_profile), [`f_humantime()`](memory.md#f/f_utils/f_humantime), [`update_progress_bar()`](memory.md#f/f_utils/update_progress_bar), [`f_open_file()`](memory.md#f/f_utils/f_open_file), `memstate_report()`, `dump_status_line()`, `get_proc_status_dict()`, [`yaml_cl_parse_option()`](yaml.md#f/yaml_parse/yaml_cl_parse_option), [`yaml_cl_parse_cmd_line()`](yaml.md#f/yaml_parse/yaml_cl_parse_cmd_line)

### *function*  yaml_strings/yaml_bold(str)

* **Parameters:**
  **str** *[**character(len=\*)* *,* *in* *]*
* **Return:**
  **bstr** *[**character(len=max_value_length)* *]*

### *function*  yaml_strings/yaml_blink(str)

* **Parameters:**
  **str** *[**character(len=\*)* *,* *in* *]*
* **Return:**
  **bstr** *[**character(len=max_value_length)* *]*

### *subroutine*  yaml_strings/buffer_string(string_bn, string_lgt, buffer, string_pos)

* **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
* **Called from:**
  [`yaml_sequence()`](yaml.md#f/yaml_output/yaml_sequence)
* **Call to:**
  [`shiftstr()`](yaml_strings.md#f/yaml_strings/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()`](yaml_strings.md#f/yaml_strings/shiftstr)

### *function*  yaml_strings/yaml_date_and_time_toa()

* **Options:**
  * **values** (8) *[**integer* *,* *in,* *]*
  * **zone** *[**logical* *,* *in,* *]*
* **Return:**
  **yaml_date_and_time_toa** *[**character(len=max_value_length)* *]*
* **Called from:**
  [`f_malloc_initialize()`](memory.md#f/dynamic_memory_base/f_malloc_initialize)

### *function*  yaml_strings/yaml_date_toa()

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()

* **Options:**
  **values** (8) *[**integer* *,* *in,* *]*
* **Return:**
  **yaml_time_toa** *[**character(len=max_value_length)* *]*
* **Called from:**
  [`f_routine()`](memory.md#f/dynamic_memory_base/f_routine), [`f_release_routine()`](memory.md#f/dynamic_memory_base/f_release_routine), [`update_progress_bar()`](memory.md#f/f_utils/update_progress_bar)

### *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* *]*

### *subroutine*  yaml_strings/rstrip(string_bn, substring)

* **Parameters:**
  * **string_bn** *[**character(len=\*)* *,* *inout* *]*
  * **substring** *[**character(len=\*)* *,* *in* *]*
* **Called from:**
  `get_bib_filename()`

### *subroutine*  yaml_strings/shiftstr(str, n)

* **Parameters:**
  * **str** *[**character(len=\*)* *,* *inout* *]*
  * **n** *[**integer* *,* *in* *]*
* **Called from:**
  [`buffer_string()`](yaml_strings.md#f/yaml_strings/buffer_string), [`align_message()`](yaml_strings.md#f/yaml_strings/align_message)

### *function*  yaml_strings/f_char_ptr(str)

* **Parameters:**
  **str** *[**character(len=\*)* *,* *in* *]*
* **Return:**
  **f_char_ptr** (1 + len_trim(str) *[**character* *]*
* **Called from:**
  `f_err_throw_c()`, [`f_char_ptr()`](yaml_strings.md#f/yaml_strings/f_char_ptr)
* **Call to:**
  [`f_char_ptr()`](yaml_strings.md#f/yaml_strings/f_char_ptr)

### *subroutine*  yaml_strings/convert_f_char_ptr(src, dest)

* **Parameters:**
  * **src** (\*) *[**character* *,* *in* *]*
  * **dest** *[**character(len=\*)* *,* *out* *]*
* **Called from:**
  `bind_dict_set_string()`, `bind_dict_add_char()`


# yaml_str.md

# Mapping and lists: the [`dictionaries`](yaml_str.md#f/dictionaries) module

The [`dictionaries`](yaml_str.md#f/dictionaries) module is Futile’s YAML-like tree container.  User
code declares dictionaries as pointers, initializes them with [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init)
or the constructors [`dict_new()`](yaml_str.md#f/dictionaries/dict_new) and [`list_new()`](yaml_str.md#f/dictionaries/list_new), navigates with the
`//` operator, and releases storage with [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free).

The API descriptions below are extracted from the Fortran source.  This page
keeps only the narrative and runnable examples needed to understand the public
contract.

Several lifecycle and query routines are implemented in
[`dictionaries_base`](yaml_str.md#f/dictionaries_base), but they are also public through [`dictionaries`](yaml_str.md#f/dictionaries).
For ordinary client code, `use dictionaries` is sufficient to access
[`dictionary`](yaml_str.md#f/dictionaries_base/dictionary), [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free),
[`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key),
[`dict_item()`](yaml_str.md#f/dictionaries_base/dict_item), and [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value).

## Core storage and lifecycle API from [`dictionaries_base`](yaml_str.md#f/dictionaries_base)

These objects are implemented in [`dictionaries_base`](yaml_str.md#f/dictionaries_base) and re-exported by
[`dictionaries`](yaml_str.md#f/dictionaries).  They are shown with their implementation module so the
source location remains clear.

### Description

Low-level dictionary storage and lifecycle routines.  Applications normally
use the higher-level dictionaries module, which re-exports this public API.

### Quick access

* **Types:**
  [`dictionary`](yaml_str.md#f/dictionaries_base/dictionary)
* **Routines:**
  [`dict_free()`](yaml_str.md#f/dictionaries_base/dict_free), [`dict_init()`](yaml_str.md#f/dictionaries_base/dict_init), [`dict_item()`](yaml_str.md#f/dictionaries_base/dict_item), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key), [`dict_len()`](yaml_str.md#f/dictionaries_base/dict_len), [`dict_size()`](yaml_str.md#f/dictionaries_base/dict_size), [`dict_value()`](yaml_str.md#f/dictionaries_base/dict_value)

### Needed modules

- [`f_precisions`](f_prec.md#f/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*  dictionaries_base/dictionary

  Opaque dictionary node used to serialize, store, and traverse YAML-like data.
  User code must declare dictionary objects as pointers and initialize them
  with dict_init, dict_new, or list_new before use.
  * **Type fields:**
    * % child *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer/optional/default=>* *]*
    * % data *[**storage* *]* :: Internal key, value, and list/mapping counters.
    * % next *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer/optional/default=>* *]*
    * % null *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
    * % parent *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer/optional/default=>* *]*
    * % previous *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer/optional/default=>* *]*

### Subroutines and functions

### *interface*  dictionaries_base/dict_free(dict, dict0, dict1)

* **Parameters:**
  * **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]* :: Dictionary to be freed and nullified.
  * **dict0** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict1** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
* **Options:**
  * **dict2** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict3** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict4** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict5** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict6** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict7** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict8** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*
  * **dict9** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]*

### *subroutine*  dictionaries_base/dict_init(dict)

Initialize a dictionary node and make it ready for use.
The dictionary may be undefined on input; free an already initialized
instance before calling dict_init again.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]* :: Dictionary pointer associated on output.

### *subroutine*  dictionaries_base/dict_free(dict)

Free a dictionary tree recursively and nullify the pointer.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *pointer* *]* :: Dictionary to be freed and nullified.

### *function*  dictionaries_base/dict_len(dict)

Return the length of a dictionary used as a list of objects.
Returns 0 for mappings and scalar nodes, and -1 if the dictionary is
nullified. Use dict_size for mappings.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]*
* **Return:**
  **dict_len** *[**integer* *]* :: Number of list items, 0 for mappings/scalars, -1 if nullified.

### *function*  dictionaries_base/dict_size(dict)

Return the number of keys in a dictionary used as a mapping.
Returns 0 for lists and scalar nodes, and -1 if the dictionary is
nullified. Use dict_len for lists.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]*
* **Return:**
  **dict_size** *[**integer* *]* :: Number of mapping keys, 0 for lists/scalars, -1 if nullified.

### *function*  dictionaries_base/dict_key(dict)

Return the mapping key of a dictionary node.  This is commonly used when
iterating over a mapping with dict_iter and dict_next.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]*
* **Return:**
  **dict_key** *[**character(len=max_field_length)* *]* :: Key of dict, or an empty string if nullified.

### *function*  dictionaries_base/dict_item(dict)

Return the list index of a dictionary node.  This is commonly used when
iterating over a list with dict_iter and dict_next.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]*
* **Return:**
  **dict_item** *[**integer* *]* :: Zero-based list item index, or -1 if nullified/not a list item.

### *function*  dictionaries_base/dict_value(dict)

Return the scalar value stored in a dictionary node.  For nested mappings
and lists the result is TYPE_DICT or TYPE_LIST.
If the value is not a scalar, it returns either :f:var\`TYPE_DICT\` or `TYPE_LIST`.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries_base/dictionary) *,* *in,pointer* *]*
* **Return:**
  **dict_value** *[**character(len=max_field_length)* *]* :: Scalar value, TYPE_DICT, TYPE_LIST, or empty if nullified.

## High-level constructors and iterators from [`dictionaries`](yaml_str.md#f/dictionaries)

<a id="f/dictionaries"></a>

### Description

High-level dictionary API used throughout Futile and BigDFT.  A dictionary
is a pointer-based tree that can represent scalars, ordered mappings, and
lists.  It maps directly to YAML data and is manipulated with constructors
such as dict_new and list_new, the // navigation operator, and set/add
routines.

This module use-associates dictionaries_base and re-exports its core public
routines and types, including dictionary, dict_init, dict_free, dict_len,
dict_size, dict_key, dict_item, and dict_value.  Client code should normally
write use dictionaries; a separate use dictionaries_base is needed only
for low-level code that intentionally avoids the higher-level dependencies.

### Quick access

* **Types:**
  [`dictionary_container`](yaml_str.md#f/dictionaries/dictionary_container), [`list_container`](yaml_str.md#f/dictionaries/list_container)
* **Variables:**
  [`dict_key`](yaml_str.md#f/dictionaries/dict_key), [`dictionary`](yaml_str.md#f/dictionaries/dictionary)
* **Routines:**
  [`dict_get()`](yaml_str.md#f/dictionaries/dict_get), [`dict_isdict()`](yaml_str.md#f/dictionaries/dict_isdict), [`dict_islist()`](yaml_str.md#f/dictionaries/dict_islist), [`dict_isscalar()`](yaml_str.md#f/dictionaries/dict_isscalar), [`dict_iter()`](yaml_str.md#f/dictionaries/dict_iter), [`dict_keys()`](yaml_str.md#f/dictionaries/dict_keys), [`dict_new()`](yaml_str.md#f/dictionaries/dict_new), [`dict_next()`](yaml_str.md#f/dictionaries/dict_next), [`list_new()`](yaml_str.md#f/dictionaries/list_new)

### Needed modules

- [`exception_callbacks`](errors.md#f/exception_callbacks)
- [`dictionaries_base`](yaml_str.md#f/dictionaries_base): Low-level dictionary storage and lifecycle routines.  Applications normally use the higher-level dictionaries module, which re-exports this public API.
- [`f_precisions`](f_prec.md#f/f_precisions) ([`f_address()`](f_prec.md#f/f_precisions/f_address), [`f_loc()`](f_prec.md#f/f_precisions/f_loc), [`f_double()`](f_prec.md#f/f_precisions/f_double)): 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
- [`yaml_strings`](yaml_strings.md#f/yaml_strings) ([`read_fraction_string()`](yaml_strings.md#f/yaml_strings/read_fraction_string), [`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy))

### Types

- ### *type*  dictionaries/list_container

  Container produced by the .item. operator and consumed by list_new.
  * **Type fields:**
    * % dict *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer/optional/default=>* *]*
    * % null *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*
    * % val *[**character(len=max_field_length)* *,* *optional/default=’ ‘* *]* :: Scalar value serialized as text.
- ### *type*  dictionaries/dictionary_container

  Container produced by the .is. operator and consumed by dict_new.
  * **Type fields:**
    * % child *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer/optional/default=>* *]*
    * % key *[**character(len=max_field_length)* *,* *optional/default=’ ‘* *]* :: Mapping key.
    * % null *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*
    * % value *[**character(len=max_field_length)* *,* *optional/default=’ ‘* *]* :: Scalar mapping value serialized as text.

### Variables

- ### dictionaries/dict_key *[**public* *]*
- ### dictionaries/dictionary *[**public* *]*

### Subroutines and functions

### *interface*  dictionaries/dict_get()

### *interface*  dictionaries/dict_iter(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *in,pointer* *]* :: Dictionary whose children are inspected.

### *interface*  dictionaries/list_new(dicts)

Create a dictionary tree interpreted as an ordered list.  Items are
usually passed with the .item. operator.

* **Parameters:**
  **dicts** (\*) *[*[*list_container*](yaml_str.md#f/dictionaries/list_container) *]*

### *interface*  dictionaries/dict_new(dicts)

Create a dictionary tree interpreted as an ordered mapping.  Entries are
usually passed with the .is. operator.

* **Parameters:**
  **dicts** (\*) *[*[*dictionary_container*](yaml_str.md#f/dictionaries/dictionary_container) *,* *in* *]* :: Key/value entries, usually produced with .is.

### *function*  dictionaries/dict_islist(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*
* **Return:**
  **ok** *[**logical* *]*

### *function*  dictionaries/dict_isdict(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*
* **Return:**
  **ok** *[**logical* *]*

### *function*  dictionaries/dict_isscalar(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*
* **Return:**
  **ok** *[**logical* *]*

### *function*  dictionaries/dict_new(dicts)

Build a mapping dictionary from an array of dictionary_container entries.

* **Parameters:**
  **dicts** (\*) *[*[*dictionary_container*](yaml_str.md#f/dictionaries/dictionary_container) *,* *in* *]* :: Key/value entries, usually produced with .is.
* **Return:**
  **dict_new** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]* :: Newly allocated mapping dictionary.

### *function*  dictionaries/dict_iter(dict)

Return the first child node for iterating over a list or mapping.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *in,pointer* *]* :: Dictionary whose children are inspected.
* **Return:**
  **dict_iter** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]* :: First child node, or null if dict is not associated.

### *function*  dictionaries/dict_next(dict)

Return the next sibling node during dictionary/list iteration.

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *in,pointer* *]* :: Current node.
* **Return:**
  **dict_next** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]* :: Next sibling node, first child, or null.

### *function*  dictionaries/dict_keys(dict)

* **Parameters:**
  **dict** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *in* *]* :: <the dictionary must be associated
* **Return:**
  **dict_keys** (dict%data%nelems) *[**character(len=max_field_length)* *]*
* **Called from:**
  [`dict_keys()`](yaml_str.md#f/dictionaries/dict_keys)
* **Call to:**
  [`dict_keys()`](yaml_str.md#f/dictionaries/dict_keys), [`dict_key()`](yaml_str.md#f/dictionaries_base/dict_key)

### *function*  dictionaries/list_new(dicts)

* **Parameters:**
  **dicts** (\*) *[*[*list_container*](yaml_str.md#f/dictionaries/list_container) *]*
* **Return:**
  **list_new** *[*[*dictionary*](yaml_str.md#f/dictionaries/dictionary) *,* *pointer* *]*

### *function*  dictionaries/f_err_check()

* **Options:**
  * **err_id** *[**integer* *,* *in,* *]*
  * **err_name** *[**character(len=\*)* *,* *in,* *]*
* **Return:**
  **f_err_check** *[**logical* *]*

## Constructor syntax

Lists are built from `.item.` entries:

```default
list => list_new([.item. 'first', .item. 'second'])
```

Mappings are built from `.is.` entries:

```default
dict => dict_new(['key1' .is. 'value1', 'key2' .is. 'value2'])
```

Values may be intrinsic scalars, one-dimensional intrinsic arrays, or nested
`type(dictionary), pointer` objects.  Array values become ordered list items.

## Examples from the Futile tests

The examples below are included from the regression tests so the documentation
and tested behavior remain synchronized.

```fortran
  dict_tmp => list_new([.item. 'one',.item. '4',.item. '1.1'])
```

```fortran
  dict1=>dict_new()
```

```fortran
  dictA=>dict_new('Key' .is. 'Scalar')
```

```fortran
  dict1=>dict_new(['Key1' .is. 'One',&
       'Key2' .is. 'Two','Key3' .is. 'Three'])
```


# yaml_strings.md

# String conversion utilities: the [`yaml_strings`](yaml_strings.md#f/yaml_strings) module

The [`yaml_strings`](yaml_strings.md#f/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:

```default
use yaml_strings
```

All conversion routines are grouped behind the generic [`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa)
interface, which now covers every public ABI kind from [`f_precisions`](f_prec.md#f/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()`](yaml_strings.md#f/yaml_strings/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`](yaml_strings.md#f/yaml_strings/f_string)
* **Routines:**
  [`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa)

### Needed modules

- [`f_precisions`](f_prec.md#f/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`](yaml_strings.md#f/yaml_strings/f_string)
with a numeric value of any supported kind, delegating to [`yaml_toa()`](yaml_strings.md#f/yaml_strings/yaml_toa)
for the conversion.  The `**` operator applies an explicit format string to a
value.

### Quick access

* **Routines:**
  [`operator(**)()`](yaml_strings.md#f/yaml_strings/operator(**))

### Needed modules

- [`f_precisions`](f_prec.md#f/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()`](yaml_strings.md#f/yaml_strings/align_message), [`buffer_string()`](yaml_strings.md#f/yaml_strings/buffer_string), [`f_strcpy()`](yaml_strings.md#f/yaml_strings/f_strcpy), [`operator(.eqv.)()`](yaml_strings.md#f/yaml_strings/operator(.eqv.)), [`operator(.neqv.)()`](yaml_strings.md#f/yaml_strings/operator(.neqv.)), [`rstrip()`](yaml_strings.md#f/yaml_strings/rstrip), [`shiftstr()`](yaml_strings.md#f/yaml_strings/shiftstr)

### Needed modules

- [`f_precisions`](f_prec.md#f/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)

* **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()`](yaml_strings.md#f/yaml_strings/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()`](yaml_strings.md#f/yaml_strings/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()`](yaml_strings.md#f/yaml_strings/buffer_string), [`align_message()`](yaml_strings.md#f/yaml_strings/align_message)

## Parsing helpers

<a id="f/yaml_strings"></a>

### Quick access

* **Routines:**
  [`is_atof()`](yaml_strings.md#f/yaml_strings/is_atof), [`is_atoi()`](yaml_strings.md#f/yaml_strings/is_atoi), [`is_atol()`](yaml_strings.md#f/yaml_strings/is_atol), [`is_atoli()`](yaml_strings.md#f/yaml_strings/is_atoli), [`read_fraction_string()`](yaml_strings.md#f/yaml_strings/read_fraction_string)

### Needed modules

- [`f_precisions`](f_prec.md#f/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()`](yaml_strings.md#f/yaml_strings/convert_f_char_ptr), [`f_char_ptr()`](yaml_strings.md#f/yaml_strings/f_char_ptr), [`yaml_blink()`](yaml_strings.md#f/yaml_strings/yaml_blink), [`yaml_bold()`](yaml_strings.md#f/yaml_strings/yaml_bold), [`yaml_date_and_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_date_and_time_toa), [`yaml_date_toa()`](yaml_strings.md#f/yaml_strings/yaml_date_toa), [`yaml_time_toa()`](yaml_strings.md#f/yaml_strings/yaml_time_toa)

### Needed modules

- [`f_precisions`](f_prec.md#f/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)* *]*

### *function*  yaml_strings/yaml_blink(str)

* **Parameters:**
  **str** *[**character(len=\*)* *,* *in* *]*
* **Return:**
  **bstr** *[**character(len=max_value_length)* *]*

### *function*  yaml_strings/yaml_date_and_time_toa()

* **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()

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()

* **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()`](yaml_strings.md#f/yaml_strings/f_char_ptr)
* **Call to:**
  [`f_char_ptr()`](yaml_strings.md#f/yaml_strings/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`](f_prec.md#f/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.