Skip to content

Latest commit

 

History

History
99 lines (69 loc) · 3.99 KB

tutorial_cpp_utils.rst

File metadata and controls

99 lines (69 loc) · 3.99 KB
Raw

String Formatting Helpers

fmt

For C++ users, conduit includes a built-in version of the fmt library (https://fmt.dev/). Since other projects also bundle fmt, the conduit version is modified to place everything in the conduit_fmt namespace instead of the default fmt namespace. This is a safe approach to avoid potential confusion and static linking consequences.

When using conduit in C++, you can use its built-in fmt as follows:

.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_utils.cpp
   :start-after: BEGIN_EXAMPLE("using_fmt")
   :end-before:  END_EXAMPLE("using_fmt")
   :language: cpp
   :dedent: 4


.. literalinclude:: t_conduit_docs_tutorial_utils_out.txt
   :start-after: BEGIN_EXAMPLE("using_fmt")
   :end-before:  END_EXAMPLE("using_fmt")

conduit::utils::format

In addition to direct fmt support, conduit utils provides conduit::utils::format methods that enable fmt style string formatting with the arguments are passed as a conduit::Node tree. These simplify use cases such as generating path string, allowing the pattern string and arguments to be stored as part of a conduit hierarchy (and in HDF5, YAML, etc files). This feature is also available in Conduit's Python API (conduit.utils.format).

conduit::utils::format(string, args)

The args case allows named arguments (args passed as object) or ordered args (args passed as list).

conduit::utils::format(string, args) -- object case:

.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_utils.cpp
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_args_obj")
   :end-before:  END_EXAMPLE("using_utils_fmt_args_obj")
   :language: cpp
   :dedent: 4


.. literalinclude:: t_conduit_docs_tutorial_utils_out.txt
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_args_obj")
   :end-before:  END_EXAMPLE("using_utils_fmt_args_obj")

conduit::utils::format(string, args) -- list case:

.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_utils.cpp
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_args_list")
   :end-before:  END_EXAMPLE("using_utils_fmt_args_list")
   :language: cpp
   :dedent: 4


.. literalinclude:: t_conduit_docs_tutorial_utils_out.txt
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_args_list")
   :end-before:  END_EXAMPLE("using_utils_fmt_args_list")

conduit::utils::format(string, maps, map_index)

The maps case also supports named or ordered args and works in conjunction with a map_index. The map_index is used to fetch a value from an array, or list of strings, which is then passed to fmt. The maps style of indexed indirection supports generating path strings for non-trivial domain partition mappings in Blueprint.

conduit::utils::format(string, maps, map_index) -- object case:

.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_utils.cpp
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_maps_obj")
   :end-before:  END_EXAMPLE("using_utils_fmt_maps_obj")
   :language: cpp
   :dedent: 4


.. literalinclude:: t_conduit_docs_tutorial_utils_out.txt
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_maps_obj")
   :end-before:  END_EXAMPLE("using_utils_fmt_maps_obj")

conduit::utils::format(string, maps, map_index ) -- list case:

.. literalinclude:: ../../tests/docs/t_conduit_docs_tutorial_utils.cpp
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_maps_list")
   :end-before:  END_EXAMPLE("using_utils_fmt_maps_list")
   :language: cpp
   :dedent: 4


.. literalinclude:: t_conduit_docs_tutorial_utils_out.txt
   :start-after: BEGIN_EXAMPLE("using_utils_fmt_maps_list")
   :end-before:  END_EXAMPLE("using_utils_fmt_maps_list")