Implementation overview

Note: If you are implementing serialization functions for your type, you should first skim over the info here, and then remember to return to this if you're in trouble.

This describes how ryml implements the serialization pipeline. This is useful to understand how the user-provided read() and write() functions fit and interact with ryml's implementation.

Note also that in a pinch, you can override any non-member function mentioned below; however, there shouldn't be any reason to do so unless explicitly noted. If you do feel the need to override other functions, please submit also an issue at https://github.com/biojppm/rapidyaml/issues to discuss whether this is an API oversight or maybe a misunderstanding, and hopefully this documentation can be improved.

Serialization (write)

ryml implements serialization in the following way:

The user-facing NodeRef functions are c4::yml::NodeRef::save( ".save()") and c4::yml::NodeRef::save_key( ".save_key()") (where the node is checked), and c4::yml::NodeRef::set_serialized( ".set_serialized()") and c4::yml::NodeRef::set_key_serialized( ".set_key_serialized()") (where the node is merely asserted). After the validity check/assert, these functions then call...
... the node write() overloads. These functions can be overrided for user types. The default implementations (provided by ryml) merely forward to...:
... the user-facing Tree functions, which are c4::yml::Tree::save( ".save()") and c4::yml::Tree::save_key( ".save_key()"), as well as c4::yml::Tree::set_serialized( ".set_serialized()") and c4::yml::Tree::set_key_serialized( ".set_key_serialized()"). Like their node counterparts, these do a value existence check and then call...
... the tree write()/write_key() overloads, which again can be overrided for user types. The default implementations of these functions now get into the nitty-gritty of serialization by choosing a style flag with scalar_flags_val( "scalar_flags_val()") / scalar_flags_key( "scalar_flags_key()") (these functions can also be overrided for user types) and then calling...
- c4::yml::serialize_to_arena( "serialize_to_arena()") which uses trait c4::is_string<T> to dispatch to...
  - either c4::yml::serialize_to_arena_str( "serialize_to_arena_str()") for strings, which grows the arena and copies the string to the arena
  - or c4::yml::serialize_to_arena_scalar( "serialize_to_arena_scalar()"), which grows the arena and calls...
    - c4::yml::scalar_serialize( "scalar_serialize()") to dispatch to...
      - either c4::yml::to_chars( "to_chars()") for non-floating scalar types, including user scalar types. **This function can be overrided for scalar user-types **
      - or c4::yml::to_chars_float( "to_chars_float()") for floating scalar types, which trims leading +, checks for special YAML value strings eg .nan or .inf, and then dispatches to c4::ftoa() or c4::dtoa()

Deserialization (read)

ryml implements deserialization in the following way:

User facing ConstNodeRef functions c4::yml::ConstNodeRef::load( ".load()") and c4::yml::ConstNodeRef::load_key( ".load_key()") (which check node and deserialization), and c4::yml::ConstNodeRef::deserialize( ".deserialize()") and c4::yml::ConstNodeRef::deserialize_key( ".deserialize_key()") (which assert node and check serialization). After the validity check/assert, these functions call...
... the node read() overloads. These functions can be overrided for user types. The default implementations (provided by ryml) merely forward to...:
... the user-facing Tree functions, which are c4::yml::Tree::load( ".load()") and c4::yml::Tree::load_key( ".load_key()") (which check node and deserialization), as well as c4::yml::Tree::deserialize( ".deserialize()") and c4::yml::Tree::deserialize_key( ".deserialize_key()") (which assert node and check serialization). Like their node counterparts, these do a value existence check and then call...
... the tree read()/read_key() overloads, which again can be overrided for user types. The default implementations of these functions first check that the node c4::yml::Tree::has_val( ".has_val()") (or key) and then get into the nitty-gritty off deserialization by calling...
- c4::yml::scalar_deserialize( "scalar_deserialize()") for standard scalars passed as pointers to read(), which is a dispatcher to...
  - either c4::yml::from_chars_float( "from_chars_float()") for floating types, which trims leading + and compares against special YAML float strings such as .nan or .inf, and finally calls c4::from_chars() which dispatches to either c4::atoi() or c4::atof(), or ...
  - c4::yml::from_chars_integral( "from_chars_integral()") for integral (arithmetic, non-float) types, which trims leading + and finally calls c4::from_chars() wrapping either c4::atoi() or c4::atou()
  - and for all other types call from_chars(). This function can be overrided for scalar user-types.
- or from_chars( "from_chars()") directly for wrapper types like eg c4::fmt::base64() that wrap the destination with some meta-info related with deserialization. This function can be overrided for wrapper user-types.