Serialization

Functions
void	sample_fundamental_types ()
	serialize/deserialize fundamental types
void	sample_empty_null_values ()
	serialize/deserialize/query empty or null values
void	sample_formatting ()
	control formatting when serializing/deserializing
void	sample_base64 ()
	encode/decode base64
void	sample_serialize_basic ()
	serialize/deserialize fundamental types
void	sample_user_scalar_types ()
	serialize/deserialize scalar (leaf/scalar) types
void	sample_user_container_types_brief ()
	serialize/deserialize container (map or seq) types: brief version
void	sample_user_container_types ()
	serialize/deserialize container (map or seq) types
void	sample_std_types ()
	serialize/deserialize STL containers
void	sample_deserialize_error ()
	shows error on deserializing nested nodes
void	sample_float_precision ()
	control precision of serialized floats

Detailed Description

Function Documentation

sample_fundamental_types()

void sample_fundamental_types

(

)

serialize/deserialize fundamental types

ryml provides facilities for serializing and deserializing the C++ fundamental types, including boolean and null values; this is provided by the several overloads in to_chars: generalized chars to value and from_chars: generalized chars to value.

To add serialization for user scalar types (ie, those types that should be serialized as strings in leaf nodes), you just need to define the appropriate overloads of to_chars and from_chars for those types; see sample_user_scalar_types for an example on how to achieve this, and see Serialization/deserialization for more information on serialization.

Definition at line 3017 of file quickstart.cpp.

{
    ryml::Tree tree;
    CHECK(tree.arena().empty());
    CHECK(tree.to_arena('a') == "a");               CHECK(tree.arena() == "a");
    CHECK(tree.to_arena("bcde") == "bcde");         CHECK(tree.arena() == "abcde");
    CHECK(tree.to_arena(unsigned(0)) == "0");       CHECK(tree.arena() == "abcde0");
    CHECK(tree.to_arena(int(1)) == "1");            CHECK(tree.arena() == "abcde01");
    CHECK(tree.to_arena(uint8_t(0)) == "0");        CHECK(tree.arena() == "abcde010");
    CHECK(tree.to_arena(uint16_t(1)) ==  "1");      CHECK(tree.arena() == "abcde0101");
    CHECK(tree.to_arena(uint32_t(2)) ==  "2");      CHECK(tree.arena() == "abcde01012");
    CHECK(tree.to_arena(uint64_t(3)) ==  "3");      CHECK(tree.arena() == "abcde010123");
    CHECK(tree.to_arena(int8_t( 4))  ==  "4");      CHECK(tree.arena() == "abcde0101234");
    CHECK(tree.to_arena(int8_t(-4))  == "-4");      CHECK(tree.arena() == "abcde0101234-4");
    CHECK(tree.to_arena(int16_t( 5)) ==  "5");      CHECK(tree.arena() == "abcde0101234-45");
    CHECK(tree.to_arena(int16_t(-5)) == "-5");      CHECK(tree.arena() == "abcde0101234-45-5");
    CHECK(tree.to_arena(int32_t( 6)) ==  "6");      CHECK(tree.arena() == "abcde0101234-45-56");
    CHECK(tree.to_arena(int32_t(-6)) == "-6");      CHECK(tree.arena() == "abcde0101234-45-56-6");
    CHECK(tree.to_arena(int64_t( 7)) ==  "7");      CHECK(tree.arena() == "abcde0101234-45-56-67");
    CHECK(tree.to_arena(int64_t(-7)) == "-7");      CHECK(tree.arena() == "abcde0101234-45-56-67-7");
    CHECK(tree.to_arena((void*)1) == "0x1");        CHECK(tree.arena() == "abcde0101234-45-56-67-70x1");
    CHECK(tree.to_arena(float(0.124)) == "0.124");  CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.124");
    CHECK(tree.to_arena(double(0.234)) == "0.234"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.234");
 
    // write boolean values - see also sample_formatting()
    CHECK(tree.to_arena(bool(true)) == "1");                    CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.2341");
    CHECK(tree.to_arena(bool(false)) == "0");                   CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410");
    CHECK(tree.to_arena(c4::fmt::boolalpha(true)) == "true");   CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410true");
    CHECK(tree.to_arena(c4::fmt::boolalpha(false)) == "false"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse");
 
    // write special float values
    // see also sample_float_precision()
    const float  fnan = std::numeric_limits<float >::quiet_NaN();
    const double dnan = std::numeric_limits<double>::quiet_NaN();
    const float  finf = std::numeric_limits<float >::infinity();
    const double dinf = std::numeric_limits<double>::infinity();
    CHECK(tree.to_arena( finf) ==  ".inf"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse.inf");
    CHECK(tree.to_arena( dinf) ==  ".inf"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse.inf.inf");
    CHECK(tree.to_arena(-finf) == "-.inf"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse.inf.inf-.inf");
    CHECK(tree.to_arena(-dinf) == "-.inf"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse.inf.inf-.inf-.inf");
    CHECK(tree.to_arena( fnan) ==  ".nan"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse.inf.inf-.inf-.inf.nan");
    CHECK(tree.to_arena( dnan) ==  ".nan"); CHECK(tree.arena() == "abcde0101234-45-56-67-70x10.1240.23410truefalse.inf.inf-.inf-.inf.nan.nan");
 
    // read special float values
    // see also sample_float_precision()
    C4_SUPPRESS_WARNING_GCC_CLANG_WITH_PUSH("-Wfloat-equal");
    tree = ryml::parse_in_arena(R"({ninf: -.inf, pinf: .inf, nan: .nan})");
    float f = 0.f;
    double d = 0.;
    CHECK(f == 0.f);
    CHECK(d == 0.);
    tree["ninf"].load(&f); CHECK(f == -finf);
    tree["ninf"].load(&d); CHECK(d == -dinf);
    tree["pinf"].load(&f); CHECK(f ==  finf);
    tree["pinf"].load(&d); CHECK(d ==  dinf);
    tree["nan" ].load(&f); CHECK(std::isnan(f));
    tree["nan" ].load(&d); CHECK(std::isnan(d));
    C4_SUPPRESS_WARNING_GCC_CLANG_POP
 
    // value overflow detection:
    // (for integral types only)
    {
        // we will be detecting errors below, so we use this sample helper
        ScopedErrorHandlerExample err = {};
        ryml::Tree t(err.callbacks()); // instantiate with the error-detecting callbacks
        // create a simple tree with an int value
        ryml::parse_in_arena(R"({val: 258})", &t);
        // by default, overflow is not detected:
        uint8_t valu8 = 0;
        int8_t vali8 = 0;
        ryml::ConstNodeRef n = t["val"];
        n.load(&valu8); CHECK(valu8 == 2); // not 257; it wrapped around
        n.load(&vali8); CHECK(vali8 == 2); // not 257; it wrapped around
        // ...but there are facilities to detect overflow
        CHECK(ryml::overflows<uint8_t>(n.val()));
        CHECK(ryml::overflows<int8_t>(n.val()));
        CHECK( ! ryml::overflows<int16_t>(n.val()));
        // and there is a format helper
        CHECK(err.check_error_occurs([&]{
            n.load(ryml::fmt::overflow_checked(valu8)); // this will cause an error
        }));
        CHECK(err.check_error_occurs([&]{
            n.load(ryml::fmt::overflow_checked(vali8)); // this will cause an error
        }));
    }
}

Referenced by main().

sample_empty_null_values()

void sample_empty_null_values

(

)

serialize/deserialize/query empty or null values

Shows how to deal with empty/null values.

See also c4::yml::Tree::val_is_null

Definition at line 3109 of file quickstart.cpp.

{
    // reading empty/null values - see also sample_formatting()
    ryml::Tree tree = ryml::parse_in_arena(""
        "plain:"                                                  "\n"
        "squoted: ''"                                             "\n"
        "dquoted: \"\""                                           "\n"
        "literal: |"                                              "\n"
        "folded: >"                                               "\n"
        "all_null: [~, null, Null, NULL]"                         "\n"
        "non_null: [nULL, non_null, non null, null it is not]"    "\n"
        "");
    // first, remember that .has_val() is a structural predicate
    // indicating the node is a leaf, and not a container.
    CHECK(tree["plain"].has_val()); // has a val, even if it's empty!
    CHECK(tree["squoted"].has_val());
    CHECK(tree["dquoted"].has_val());
    CHECK(tree["literal"].has_val());
    CHECK(tree["folded"].has_val());
    CHECK( ! tree["all_null"].has_val());
    CHECK( ! tree["non_null"].has_val());
    // In essence, has_val() is the logical opposite of is_container()
    CHECK( ! tree["plain"].is_container());
    CHECK( ! tree["squoted"].is_container());
    CHECK( ! tree["dquoted"].is_container());
    CHECK( ! tree["literal"].is_container());
    CHECK( ! tree["folded"].is_container());
    CHECK(tree["all_null"].is_container());
    CHECK(tree["non_null"].is_container());
    //
    // Right. How about the contents of each val?
    //
    // all of these scalars have zero-length:
    CHECK(tree["plain"].val().len == 0);
    CHECK(tree["squoted"].val().len == 0);
    CHECK(tree["dquoted"].val().len == 0);
    CHECK(tree["literal"].val().len == 0);
    CHECK(tree["folded"].val().len == 0);
    // but only the empty scalar has null string:
    CHECK(tree["plain"].val().str == nullptr);
    CHECK(tree["squoted"].val().str != nullptr);
    CHECK(tree["dquoted"].val().str != nullptr);
    CHECK(tree["literal"].val().str != nullptr);
    CHECK(tree["folded"].val().str != nullptr);
    // likewise, scalar comparison to nullptr has the same results:
    // (remember that .val() gives you the scalar value, node must
    // have a val, ie must be a leaf node, not a container)
    CHECK(tree["plain"].val() == nullptr);
    CHECK(tree["squoted"].val() != nullptr);
    CHECK(tree["dquoted"].val() != nullptr);
    CHECK(tree["literal"].val() != nullptr);
    CHECK(tree["folded"].val() != nullptr);
    // the tree and node classes provide the corresponding predicate
    // functions .key_is_null() and .val_is_null().
    // (note that these functions have the same preconditions as .val(),
    // because they need get the val to look into its contents)
    CHECK(tree["plain"].val_is_null());
    CHECK( ! tree["squoted"].val_is_null());
    CHECK( ! tree["dquoted"].val_is_null());
    CHECK( ! tree["literal"].val_is_null());
    CHECK( ! tree["folded"].val_is_null());
    // matching to null is case-sensitive. only the cases shown here
    // match to null:
    for(ryml::ConstNodeRef child : tree["all_null"].children())
    {
        CHECK(child.val() != nullptr); // it is pointing at a string, so it is not nullptr!
        CHECK(child.val_is_null());
    }
    for(ryml::ConstNodeRef child : tree["non_null"].children())
    {
        CHECK(child.val() != nullptr);
        CHECK( ! child.val_is_null());
    }
    //
    //
    // Because the meaning of null/~/empty will vary from application
    // to application, ryml makes no assumption on what should be
    // serialized as null. It leaves this decision to the user. But
    // it also provides the proper toolbox for the user to implement
    // its intended solution.
    //
    // writing/disambiguating null values:
    ryml::csubstr null = {};
    ryml::csubstr nonnull = "";
    ryml::csubstr strnull = "null";
    ryml::csubstr tilde = "~";
    CHECK(null   .len == 0); CHECK(null   .str == nullptr); CHECK(null    == nullptr);
    CHECK(nonnull.len == 0); CHECK(nonnull.str != nullptr); CHECK(nonnull != nullptr);
    CHECK(strnull.len != 0); CHECK(strnull.str != nullptr); CHECK(strnull != nullptr);
    CHECK(tilde  .len != 0); CHECK(tilde  .str != nullptr); CHECK(tilde   != nullptr);
    tree.clear();
    tree.clear_arena();
    tree.rootref().set_map();
    // serializes as an empty plain scalar:
    tree["empty_null"].set_serialized(null); CHECK(tree.arena() == "");
    // serializes as an empty quoted scalar:
    tree["empty_nonnull"].set_serialized(nonnull); CHECK(tree.arena() == "");
    // serializes as the normal 'null' string:
    tree["str_null"].set_serialized(strnull); CHECK(tree.arena() == "null");
    // serializes as the normal '~' string:
    tree["str_tilde"].set_serialized(tilde); CHECK(tree.arena() == "null~");
    // this is the resulting yaml:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "empty_null: "         "\n"
          "empty_nonnull: ''"    "\n"
          "str_null: null"       "\n"
          "str_tilde: ~"         "\n"
          "");
    // To enforce a particular concept of what is a null string, you
    // can use the appropriate condition based on pointer nullity or
    // other appropriate criteria.
    //
    // As an example, proper comparison to nullptr:
    auto null_if_nullptr = [](ryml::csubstr s) {
        return s.str == nullptr ? "null" : s;
    };
    tree["empty_null"].set_serialized(null_if_nullptr(null));
    tree["empty_nonnull"].set_serialized(null_if_nullptr(nonnull));
    tree["str_null"].set_serialized(null_if_nullptr(strnull));
    tree["str_tilde"].set_serialized(null_if_nullptr(tilde));
    // this is the resulting yaml:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "empty_null: null"    "\n"
          "empty_nonnull: ''"   "\n"
          "str_null: null"      "\n"
          "str_tilde: ~"        "\n"
          "");
    //
    // As another example, nullity check based on the YAML nullity
    // predicate:
    auto null_if_predicate = [](ryml::csubstr s) {
        return ryml::scalar_is_null(s) ? "null" : s;
    };
    tree["empty_null"].set_serialized(null_if_predicate(null));
    tree["empty_nonnull"].set_serialized(null_if_predicate(nonnull));
    tree["str_null"].set_serialized(null_if_predicate(strnull));
    tree["str_tilde"].set_serialized(null_if_predicate(tilde));
    // this is the resulting yaml:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "empty_null: null"    "\n"
          "empty_nonnull: ''"   "\n"
          "str_null: null"      "\n"
          "str_tilde: null"     "\n"
          "");
    //
    // As another example, nullity check based on the YAML nullity
    // predicate, but returning "~" to simbolize nullity:
    auto tilde_if_predicate = [](ryml::csubstr s) {
        return ryml::scalar_is_null(s) ? "~" : s;
    };
    tree["empty_null"].set_serialized(tilde_if_predicate(null));
    tree["empty_nonnull"].set_serialized(tilde_if_predicate(nonnull));
    tree["str_null"].set_serialized(tilde_if_predicate(strnull));
    tree["str_tilde"].set_serialized(tilde_if_predicate(tilde));
    // this is the resulting yaml:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "empty_null: ~"         "\n"
          "empty_nonnull: ''"     "\n"
          "str_null: ~"           "\n"
          "str_tilde: ~"          "\n"
          "");
}

Referenced by main().

sample_formatting()

void sample_formatting

(

)

control formatting when serializing/deserializing

ryml provides facilities for formatting/deformatting (imported from c4core into the ryml namespace).

See Format utilities . These functions are very useful to serialize and deserialize scalar types; see Serialization/deserialization .

Definition at line 3280 of file quickstart.cpp.

{
    // format(), format_sub(), formatrs(): format arguments
    {
        char buf_[256] = {};
        ryml::substr buf = buf_;
        size_t size = ryml::format(buf, "a={} foo {} {} bar {}", 0.1, 10, 11, 12);
        CHECK(size == strlen("a=0.1 foo 10 11 bar 12"));
        CHECK(buf.first(size) == "a=0.1 foo 10 11 bar 12");
        // it is safe to call on an empty buffer:
        // returns the size needed for the result, and no overflow occurs:
        size = ryml::format({} , "a={} foo {} {} bar {}", "this_is_a", 10, 11, 12);
        CHECK(size == ryml::format(buf, "a={} foo {} {} bar {}", "this_is_a", 10, 11, 12));
        CHECK(size == strlen("a=this_is_a foo 10 11 bar 12"));
        // it is also safe to call on an insufficient buffer:
        char smallbuf[8] = {};
        size = ryml::format(smallbuf, "{} is too large {}", "this", "for the buffer");
        CHECK(size == strlen("this is too large for the buffer"));
        // ... and the result is truncated at the buffer size:
        CHECK(ryml::substr(smallbuf, sizeof(smallbuf)) == "this is\0");
 
        // format_sub() directly returns the written string:
        ryml::csubstr result = ryml::format_sub(buf, "b={}, damn it.", 1);
        CHECK(result == "b=1, damn it.");
        CHECK(result.is_sub(buf));
 
        // formatrs() means FORMAT & ReSize:
        //
        // Instead of a substr, it receives any owning linear char container
        // for which to_substr() is defined (using ADL).
        // <ryml_std.hpp> has to_substr() definitions for std::string and
        // std::vector<char>.
        //
        // formatrs() starts by calling format(), and if needed, resizes the container
        // and calls format() again.
        //
        // Note that unless the container is previously sized, this
        // may cause an allocation, which will make your code slower.
        // Make sure to call .reserve() on the container for real
        // production code.
        std::string sbuf;
        ryml::formatrs(&sbuf, "and c={} seems about right", 2);
        CHECK(sbuf == "and c=2 seems about right");
        std::vector<char> vbuf; // works with any linear char container
        ryml::formatrs(&vbuf, "and c={} seems about right", 2);
        CHECK(sbuf == "and c=2 seems about right");
        // with formatrs() it is also possible to append:
        ryml::formatrs_append(&sbuf, ", and finally d={} - done", 3);
        CHECK(sbuf == "and c=2 seems about right, and finally d=3 - done");
    }
 
    // unformat(): read arguments - opposite of format()
    {
        char buf_[256];
 
        int a = 0, b = 1, c = 2;
        ryml::csubstr result = ryml::format_sub(buf_, "{} and {} and {}", a, b, c);
        CHECK(result == "0 and 1 and 2");
        int aa = -1, bb = -2, cc = -3;
        size_t num_characters = ryml::unformat(result, "{} and {} and {}", aa, bb, cc);
        CHECK(num_characters != ryml::csubstr::npos); // if a conversion fails, returns ryml::csubstr::npos
        CHECK(num_characters == result.size());
        CHECK(aa == a);
        CHECK(bb == b);
        CHECK(cc == c);
 
        result = ryml::format_sub(buf_, "{} and {} and {}", 10, 20, 30);
        CHECK(result == "10 and 20 and 30");
        num_characters = ryml::unformat(result, "{} and {} and {}", aa, bb, cc);
        CHECK(num_characters != ryml::csubstr::npos); // if a conversion fails, returns ryml::csubstr::npos
        CHECK(num_characters == result.size());
        CHECK(aa == 10);
        CHECK(bb == 20);
        CHECK(cc == 30);
    }
 
    // cat(), cat_sub(), catrs(): concatenate arguments
    {
        char buf_[256] = {};
        ryml::substr buf = buf_;
        size_t size = ryml::cat(buf, "a=", 0.1, "foo", 10, 11, "bar", 12);
        CHECK(size == strlen("a=0.1foo1011bar12"));
        CHECK(buf.first(size) == "a=0.1foo1011bar12");
        // it is safe to call on an empty buffer:
        // returns the size needed for the result, and no overflow occurs:
        CHECK(ryml::cat({}, "a=", 0) == 3);
        // it is also safe to call on an insufficient buffer:
        char smallbuf[8] = {};
        size = ryml::cat(smallbuf, "this", " is too large ", "for the buffer");
        CHECK(size == strlen("this is too large for the buffer"));
        // ... and the result is truncated at the buffer size:
        CHECK(ryml::substr(smallbuf, sizeof(smallbuf)) == "this is\0");
 
        // cat_sub() directly returns the written string:
        ryml::csubstr result = ryml::cat_sub(buf, "b=", 1, ", damn it.");
        CHECK(result == "b=1, damn it.");
        CHECK(result.is_sub(buf));
 
        // catrs() means CAT & ReSize:
        //
        // Instead of a substr, it receives any owning linear char container
        // for which to_substr() is defined (using ADL).
        // <ryml_std.hpp> has to_substr() definitions for std::string and
        // std::vector<char>.
        //
        // catrs() starts by calling cat(), and if needed, resizes the container
        // and calls cat() again.
        //
        // Note that unless the container is previously sized, this
        // may cause an allocation, which will make your code slower.
        // Make sure to call .reserve() on the container for real
        // production code.
        std::string sbuf;
        ryml::catrs(&sbuf, "and c=", 2, " seems about right");
        CHECK(sbuf == "and c=2 seems about right");
        std::vector<char> vbuf; // works with any linear char container
        ryml::catrs(&vbuf, "and c=", 2, " seems about right");
        CHECK(sbuf == "and c=2 seems about right");
        // with catrs() it is also possible to append:
        ryml::catrs_append(&sbuf, ", and finally d=", 3, " - done");
        CHECK(sbuf == "and c=2 seems about right, and finally d=3 - done");
    }
 
    // uncat(): read arguments - opposite of cat()
    {
        char buf_[256];
 
        int a = 0, b = 1, c = 2;
        ryml::csubstr result = ryml::cat_sub(buf_, a, ' ', b, ' ', c);
        CHECK(result == "0 1 2");
        int aa = -1, bb = -2, cc = -3;
        char sep1 = 'a', sep2 = 'b';
        size_t num_characters = ryml::uncat(result, aa, sep1, bb, sep2, cc);
        CHECK(num_characters == result.size());
        CHECK(aa == a);
        CHECK(bb == b);
        CHECK(cc == c);
        CHECK(sep1 == ' ');
        CHECK(sep2 == ' ');
 
        result = ryml::cat_sub(buf_, 10, ' ', 20, ' ', 30);
        CHECK(result == "10 20 30");
        num_characters = ryml::uncat(result, aa, sep1, bb, sep2, cc);
        CHECK(num_characters == result.size());
        CHECK(aa == 10);
        CHECK(bb == 20);
        CHECK(cc == 30);
        CHECK(sep1 == ' ');
        CHECK(sep2 == ' ');
    }
 
    // catsep(), catsep_sub(), catseprs(): concatenate arguments, with a separator
    {
        char buf_[256] = {};
        ryml::substr buf = buf_;
        // use ' ' as a separator
        size_t size = ryml::catsep(buf, ' ', "a=", 0, "b=", 1, "c=", 2, 45, 67);
        CHECK(buf.first(size) == "a= 0 b= 1 c= 2 45 67");
        // any separator may be used
        // use " and " as a separator
        size = ryml::catsep(buf, " and ", "a=0", "b=1", "c=2", 45, 67);
        CHECK(buf.first(size) == "a=0 and b=1 and c=2 and 45 and 67");
        // use " ... " as a separator
        size = ryml::catsep(buf, " ... ", "a=0", "b=1", "c=2", 45, 67);
        CHECK(buf.first(size) == "a=0 ... b=1 ... c=2 ... 45 ... 67");
        // use '/' as a separator
        size = ryml::catsep(buf, '/', "a=", 0, "b=", 1, "c=", 2, 45, 67);
        CHECK(buf.first(size) == "a=/0/b=/1/c=/2/45/67");
        // use 888 as a separator
        size = ryml::catsep(buf, 888, "a=0", "b=1", "c=2", 45, 67);
        CHECK(buf.first(size) == "a=0888b=1888c=28884588867");
 
        // it is safe to call on an empty buffer:
        // returns the size needed for the result, and no overflow occurs:
        CHECK(size == ryml::catsep({}, 888, "a=0", "b=1", "c=2", 45, 67));
        // it is also safe to call on an insufficient buffer:
        char smallbuf[8] = {};
        CHECK(size == ryml::catsep(smallbuf, 888, "a=0", "b=1", "c=2", 45, 67));
        CHECK(size == strlen("a=0888b=1888c=28884588867"));
        // ... and the result is truncated:
        CHECK(ryml::substr(smallbuf, sizeof(smallbuf)) == "a=0888b\0");
 
        // catsep_sub() directly returns the written substr:
        ryml::csubstr result = ryml::catsep_sub(buf, " and ", "a=0", "b=1", "c=2", 45, 67);
        CHECK(result == "a=0 and b=1 and c=2 and 45 and 67");
        CHECK(result.is_sub(buf));
 
        // catseprs() means CATSEP & ReSize:
        //
        // Instead of a substr, it receives any owning linear char container
        // for which to_substr() is defined (using ADL).
        // <ryml_std.hpp> has to_substr() definitions for std::string and
        // std::vector<char>.
        //
        // catseprs() starts by calling catsep(), and if needed, resizes the container
        // and calls catsep() again.
        //
        // Note that unless the container is previously sized, this
        // may cause an allocation, which will make your code slower.
        // Make sure to call .reserve() on the container for real
        // production code.
        std::string sbuf;
        ryml::catseprs(&sbuf, " and ", "a=0", "b=1", "c=2", 45, 67);
        CHECK(sbuf == "a=0 and b=1 and c=2 and 45 and 67");
        std::vector<char> vbuf; // works with any linear char container
        ryml::catseprs(&vbuf, " and ", "a=0", "b=1", "c=2", 45, 67);
        CHECK(ryml::to_csubstr(vbuf) == "a=0 and b=1 and c=2 and 45 and 67");
 
        // with catseprs() it is also possible to append:
        ryml::catseprs_append(&sbuf, " well ", " --- a=0", "b=11", "c=12", 145, 167);
        CHECK(sbuf == "a=0 and b=1 and c=2 and 45 and 67 --- a=0 well b=11 well c=12 well 145 well 167");
    }
 
    // uncatsep(): read arguments with a separator - opposite of catsep()
    {
        char buf_[256] = {};
 
        int a = 0, b = 1, c = 2;
        ryml::csubstr result = ryml::catsep_sub(buf_, ' ', a, b, c);
        CHECK(result == "0 1 2");
        int aa = -1, bb = -2, cc = -3;
        size_t num_characters = ryml::uncatsep(result, " ", aa, bb, cc);
        CHECK(num_characters == result.size());
        CHECK(aa == a);
        CHECK(bb == b);
        CHECK(cc == c);
 
        result = ryml::catsep_sub(buf_, "--", 10, 20, 30);
        CHECK(result == "10--20--30");
        num_characters = ryml::uncatsep(result, "--", aa, bb, cc);
        CHECK(num_characters == result.size());
        CHECK(aa == 10);
        CHECK(bb == 20);
        CHECK(cc == 30);
    }
 
    // formatting individual arguments
    {
        using namespace ryml;  // all the symbols below are in the ryml namespace.
        char buf_[256] = {};   // all the results below are written in this buffer
        substr buf = buf_;
        // --------------------------------------
        // fmt::boolalpha(): format as true/false
        // --------------------------------------
        // just as with std streams, printing a bool will output the integer value:
        CHECK("0" == cat_sub(buf, false));
        CHECK("1" == cat_sub(buf, true));
        // to force a "true"/"false", use fmt::boolalpha:
        CHECK("false" == cat_sub(buf, fmt::boolalpha(false)));
        CHECK("true" == cat_sub(buf, fmt::boolalpha(true)));
 
        // ---------------------------------
        // fmt::hex(): format as hexadecimal
        // ---------------------------------
        CHECK("0xff"  == cat_sub(buf, fmt::hex(255)));
        CHECK("0x100" == cat_sub(buf, fmt::hex(256)));
        CHECK("-0xff"  == cat_sub(buf, fmt::hex(-255)));
        CHECK("-0x100" == cat_sub(buf, fmt::hex(-256)));
        CHECK("3735928559" == cat_sub(buf,          UINT32_C(0xdeadbeef)));
        CHECK("0xdeadbeef" == cat_sub(buf, fmt::hex(UINT32_C(0xdeadbeef))));
        // ----------------------------
        // fmt::bin(): format as binary
        // ----------------------------
        CHECK("0b1000" == cat_sub(buf, fmt::bin(8)));
        CHECK("0b1001" == cat_sub(buf, fmt::bin(9)));
        CHECK("0b10001" == cat_sub(buf, fmt::bin(17)));
        CHECK("0b11001" == cat_sub(buf, fmt::bin(25)));
        CHECK("-0b1000" == cat_sub(buf, fmt::bin(-8)));
        CHECK("-0b1001" == cat_sub(buf, fmt::bin(-9)));
        CHECK("-0b10001" == cat_sub(buf, fmt::bin(-17)));
        CHECK("-0b11001" == cat_sub(buf, fmt::bin(-25)));
        // ---------------------------
        // fmt::bin(): format as octal
        // ---------------------------
        CHECK("0o77"    == cat_sub(buf, fmt::oct(63)));
        CHECK("0o100"   == cat_sub(buf, fmt::oct(64)));
        CHECK("0o377"   == cat_sub(buf, fmt::oct(255)));
        CHECK("0o400"   == cat_sub(buf, fmt::oct(256)));
        CHECK("0o1000"  == cat_sub(buf, fmt::oct(512)));
        CHECK("-0o77"   == cat_sub(buf, fmt::oct(-63)));
        CHECK("-0o100"  == cat_sub(buf, fmt::oct(-64)));
        CHECK("-0o377"  == cat_sub(buf, fmt::oct(-255)));
        CHECK("-0o400"  == cat_sub(buf, fmt::oct(-256)));
        CHECK("-0o1000" == cat_sub(buf, fmt::oct(-512)));
        // ---------------------------
        // fmt::zpad(): pad with zeros
        // ---------------------------
        CHECK("000063" == cat_sub(buf, fmt::zpad(63, 6)));
        CHECK( "00063" == cat_sub(buf, fmt::zpad(63, 5)));
        CHECK(  "0063" == cat_sub(buf, fmt::zpad(63, 4)));
        CHECK(   "063" == cat_sub(buf, fmt::zpad(63, 3)));
        CHECK(    "63" == cat_sub(buf, fmt::zpad(63, 2)));
        CHECK(    "63" == cat_sub(buf, fmt::zpad(63, 1))); // will never trim the result
        CHECK(    "63" == cat_sub(buf, fmt::zpad(63, 0))); // will never trim the result
        CHECK("0x00003f" == cat_sub(buf, fmt::zpad(fmt::hex(63), 6)));
        CHECK("0o000077" == cat_sub(buf, fmt::zpad(fmt::oct(63), 6)));
        CHECK("0b00011001" == cat_sub(buf, fmt::zpad(fmt::bin(25), 8)));
        // ------------------------------------------------
        // fmt::left(): align left with a given field width
        // ------------------------------------------------
        CHECK("63    " == cat_sub(buf, fmt::left(63, 6)));
        CHECK("63   "  == cat_sub(buf, fmt::left(63, 5)));
        CHECK("63  "   == cat_sub(buf, fmt::left(63, 4)));
        CHECK("63 "    == cat_sub(buf, fmt::left(63, 3)));
        CHECK("63"     == cat_sub(buf, fmt::left(63, 2)));
        CHECK("63"     == cat_sub(buf, fmt::left(63, 1))); // will never trim the result
        CHECK("63"     == cat_sub(buf, fmt::left(63, 0))); // will never trim the result
        // the fill character can be specified (defaults to ' '):
        CHECK("63----" == cat_sub(buf, fmt::left(63, 6, '-')));
        CHECK("63++++" == cat_sub(buf, fmt::left(63, 6, '+')));
        CHECK("63////" == cat_sub(buf, fmt::left(63, 6, '/')));
        CHECK("630000" == cat_sub(buf, fmt::left(63, 6, '0')));
        CHECK("63@@@@" == cat_sub(buf, fmt::left(63, 6, '@')));
        CHECK("0x003f    " == cat_sub(buf, fmt::left(fmt::zpad(fmt::hex(63), 4), 10)));
        // --------------------------------------------------
        // fmt::right(): align right with a given field width
        // --------------------------------------------------
        CHECK("    63" == cat_sub(buf, fmt::right(63, 6)));
        CHECK("   63"  == cat_sub(buf, fmt::right(63, 5)));
        CHECK("  63"   == cat_sub(buf, fmt::right(63, 4)));
        CHECK(" 63"    == cat_sub(buf, fmt::right(63, 3)));
        CHECK("63"     == cat_sub(buf, fmt::right(63, 2)));
        CHECK("63"     == cat_sub(buf, fmt::right(63, 1))); // will never trim the result
        CHECK("63"     == cat_sub(buf, fmt::right(63, 0))); // will never trim the result
        // the fill character can be specified (defaults to ' '):
        CHECK("----63" == cat_sub(buf, fmt::right(63, 6, '-')));
        CHECK("++++63" == cat_sub(buf, fmt::right(63, 6, '+')));
        CHECK("////63" == cat_sub(buf, fmt::right(63, 6, '/')));
        CHECK("000063" == cat_sub(buf, fmt::right(63, 6, '0')));
        CHECK("@@@@63" == cat_sub(buf, fmt::right(63, 6, '@')));
        CHECK("    0x003f" == cat_sub(buf, fmt::right(fmt::zpad(fmt::hex(63), 4), 10)));
 
        // ------------------------------------------
        // fmt::real(): format floating point numbers
        // ------------------------------------------
        // see also sample_float_precision()
        CHECK("0"       == cat_sub(buf, fmt::real(0.01f, 0)));
        CHECK("0.0"     == cat_sub(buf, fmt::real(0.01f, 1)));
        CHECK("0.01"    == cat_sub(buf, fmt::real(0.01f, 2)));
        CHECK("0.010"   == cat_sub(buf, fmt::real(0.01f, 3)));
        CHECK("0.0100"  == cat_sub(buf, fmt::real(0.01f, 4)));
        CHECK("0.01000" == cat_sub(buf, fmt::real(0.01f, 5)));
        CHECK("1"       == cat_sub(buf, fmt::real(1.01f, 0)));
        CHECK("1.0"     == cat_sub(buf, fmt::real(1.01f, 1)));
        CHECK("1.01"    == cat_sub(buf, fmt::real(1.01f, 2)));
        CHECK("1.010"   == cat_sub(buf, fmt::real(1.01f, 3)));
        CHECK("1.0100"  == cat_sub(buf, fmt::real(1.01f, 4)));
        CHECK("1.01000" == cat_sub(buf, fmt::real(1.01f, 5)));
        CHECK("1"       == cat_sub(buf, fmt::real(1.234234234, 0)));
        CHECK("1.2"     == cat_sub(buf, fmt::real(1.234234234, 1)));
        CHECK("1.23"    == cat_sub(buf, fmt::real(1.234234234, 2)));
        CHECK("1.234"   == cat_sub(buf, fmt::real(1.234234234, 3)));
        CHECK("1.2342"  == cat_sub(buf, fmt::real(1.234234234, 4)));
        CHECK("1.23423" == cat_sub(buf, fmt::real(1.234234234, 5)));
        CHECK("1000000.00000" == cat_sub(buf, fmt::real(1000000.000000000, 5)));
        CHECK("1234234.23423" == cat_sub(buf, fmt::real(1234234.234234234, 5)));
        // AKA %f
        CHECK("1000000.00000" == cat_sub(buf, fmt::real(1000000.000000000, 5, FTOA_FLOAT)));  // AKA %f, same as above
        CHECK("1234234.23423" == cat_sub(buf, fmt::real(1234234.234234234, 5, FTOA_FLOAT)));  // AKA %f
        CHECK("1234234.2342"  == cat_sub(buf, fmt::real(1234234.234234234, 4, FTOA_FLOAT)));  // AKA %f
        CHECK("1234234.234"   == cat_sub(buf, fmt::real(1234234.234234234, 3, FTOA_FLOAT)));  // AKA %f
        CHECK("1234234.23"    == cat_sub(buf, fmt::real(1234234.234234234, 2, FTOA_FLOAT)));  // AKA %f
        // AKA %e
        CHECK("1.00000e+06"   == cat_sub(buf, fmt::real(1000000.000000000, 5, FTOA_SCIENT))); // AKA %e
        CHECK("1.23423e+06"   == cat_sub(buf, fmt::real(1234234.234234234, 5, FTOA_SCIENT))); // AKA %e
        CHECK("1.2342e+06"    == cat_sub(buf, fmt::real(1234234.234234234, 4, FTOA_SCIENT))); // AKA %e
        CHECK("1.234e+06"     == cat_sub(buf, fmt::real(1234234.234234234, 3, FTOA_SCIENT))); // AKA %e
        CHECK("1.23e+06"      == cat_sub(buf, fmt::real(1234234.234234234, 2, FTOA_SCIENT))); // AKA %e
        // AKA %g
        CHECK("1e+06"         == cat_sub(buf, fmt::real(1000000.000000000, 5, FTOA_FLEX)));   // AKA %g
        CHECK("1.2342e+06"    == cat_sub(buf, fmt::real(1234234.234234234, 5, FTOA_FLEX)));   // AKA %g
        CHECK("1.234e+06"     == cat_sub(buf, fmt::real(1234234.234234234, 4, FTOA_FLEX)));   // AKA %g
        CHECK("1.23e+06"      == cat_sub(buf, fmt::real(1234234.234234234, 3, FTOA_FLEX)));   // AKA %g
        CHECK("1.2e+06"       == cat_sub(buf, fmt::real(1234234.234234234, 2, FTOA_FLEX)));   // AKA %g
        // FTOA_HEXA: AKA %a (hexadecimal formatting of floats)
        CHECK("0x1.e8480p+19" == cat_sub(buf, fmt::real(1000000.000000000, 5, FTOA_HEXA)));   // AKA %a
        CHECK("0x1.2d53ap+20" == cat_sub(buf, fmt::real(1234234.234234234, 5, FTOA_HEXA)));   // AKA %a
 
        // --------------------------------------------------------------
        // fmt::raw(): dump data in raw (binary) machine format (respecting alignment)
        // --------------------------------------------------------------
        {
            C4_SUPPRESS_WARNING_GCC_CLANG_WITH_PUSH("-Wcast-align")  // we're casting the values directly, so alignment is strictly respected.
            const uint32_t payload[] = {10, 20, 30, 40, UINT32_C(0xdeadbeef)};
            // (package payload as a substr, for comparison only)
            csubstr expected = csubstr((const char *)payload, sizeof(payload));
            csubstr actual = cat_sub(buf, fmt::raw(payload));
            CHECK(!actual.overlaps(expected));
            CHECK(0 == memcmp(expected.str, actual.str, expected.len));
            // also possible with variables:
            for(const uint32_t value : payload)
            {
                // (package payload as a substr, for comparison only)
                expected = csubstr((const char *)&value, sizeof(value));
                actual = cat_sub(buf, fmt::raw(value));
                CHECK(actual.size() == sizeof(uint32_t));
                CHECK(!actual.overlaps(expected));
                CHECK(0 == memcmp(expected.str, actual.str, expected.len));
                // with non-const data, fmt::craw() may be needed for disambiguation:
                actual = cat_sub(buf, fmt::craw(value));
                CHECK(actual.size() == sizeof(uint32_t));
                CHECK(!actual.overlaps(expected));
                CHECK(0 == memcmp(expected.str, actual.str, expected.len));
                //
                // read back:
                uint32_t result = 0;
                auto reader = fmt::raw(result);
                CHECK(uncat(actual, reader));
                // and compare:
                // (vs2017/release/32bit does not reload result from cache, so force it)
                CHECK(result == value); // roundtrip completed successfully
            }
            C4_SUPPRESS_WARNING_GCC_CLANG_POP
        }
 
        // -------------------------
        // fmt::base64(): see below!
        // -------------------------
    }
}

Referenced by main().

sample_base64()

void sample_base64

(

)

encode/decode base64

demonstrates how to read and write base64-encoded blobs.

See also

Base64 encoding/decoding

Definition at line 3706 of file quickstart.cpp.

{
    // let's start by creating a tree with base64 vals and keys
    ryml::Tree tree;
    tree.rootref().set_map();
    struct text_and_base64 { ryml::csubstr text, base64; };
    text_and_base64 cases[] = {
        {{"Hello, World!"}, {"SGVsbG8sIFdvcmxkIQ=="}},
        {{"Brevity is the soul of wit."}, {"QnJldml0eSBpcyB0aGUgc291bCBvZiB3aXQu"}},
        {{"All that glitters is not gold."}, {"QWxsIHRoYXQgZ2xpdHRlcnMgaXMgbm90IGdvbGQu"}},
    };
    // to encode base64 and write the result to val:
    for(text_and_base64 c : cases)
        tree[c.text].set_serialized(ryml::fmt::base64(c.text));
    // to encode base64 and write the result to key:
    for(text_and_base64 c : cases)
    {
        ryml::NodeRef ch = tree.rootref().append_child();
        ch.set_key_serialized(ryml::fmt::base64(c.text));
        ch.set_serialized(c.text);
    }
    // check the result:
    for(text_and_base64 c : cases)
    {
        CHECK(tree[c.text].val() == c.base64);
        CHECK(tree[c.base64].val() == c.text);
    }
    // and this is how the YAML now looks:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "Hello, World!: SGVsbG8sIFdvcmxkIQ=="                                         "\n"
          "Brevity is the soul of wit.: QnJldml0eSBpcyB0aGUgc291bCBvZiB3aXQu"           "\n"
          "All that glitters is not gold.: QWxsIHRoYXQgZ2xpdHRlcnMgaXMgbm90IGdvbGQu"    "\n"
          // note that the keys below are base64-encoded
          "SGVsbG8sIFdvcmxkIQ==: Hello, World!"                                         "\n"
          "QnJldml0eSBpcyB0aGUgc291bCBvZiB3aXQu: Brevity is the soul of wit."           "\n"
          "QWxsIHRoYXQgZ2xpdHRlcnMgaXMgbm90IGdvbGQu: All that glitters is not gold."    "\n"
          "");
    char buf1_[128], buf2_[128];
    ryml::substr buf1 = buf1_;  // this is where we will write the result (using load())
    ryml::substr buf2 = buf2_;  // this is where we will write the result (using deserialize()/deserialize_key())
    // to decode base64 and write the result to buf:
    for(const text_and_base64 c : cases)
    {
        // this decodes base64 and write the decoded result into an
        // existing buffer (buf1):
        size_t len = 0; // the decoded length
        tree[c.text].load(ryml::fmt::base64(buf1, &len));
        // The base64() tag function is used to get the
        // deserialization using c4::decode_base64(). This will
        // respect the limits of the buffer, and fail with an error if
        // the buffer is too small (or if the base64 encoding is
        // wrong). The optional second parameter is set to the decoded
        // size, ie, the length of the decoded result, which is also
        // the size required for the buffer.
        CHECK(len <= buf1.len);
        CHECK(c.text.len == len);
        CHECK(buf1.first(len) == c.text);
        // likewise for keys:
        tree[c.base64].load_key(ryml::fmt::base64(buf2, &len));
        CHECK(len <= buf2.len);
        CHECK(buf2.first(len) == c.text);
        //
        // interop with std::string:
        std::string result;
        tree[c.text].load(ryml::fmt::base64(result));
        CHECK(result == c.text);
        // likewise for keys:
        tree[c.base64].load_key(ryml::fmt::base64(result));
        CHECK(result == c.text);
        //
        // Manual interop with std::string: using substr.
        // This shows how to manually resize the destination
        // buffer, and is similar to the implementation for containers.
        result.clear(); // this is not needed. We do it just to show that the first call can fail.
        len = 0;
        // try to read into the buffer, and get back the required size
        // (in len)
        auto payload = ryml::fmt::base64(ryml::to_substr(result), &len);
        bool ok = tree[c.text].deserialize(payload);
        if(len > result.size()) // the size was not enough; resize and call again
        {
            CHECK(!ok);
            result.resize(len);
            payload = ryml::fmt::base64(ryml::to_substr(result), &len); // reassign
            ok = tree[c.text].deserialize(payload);
        }
        CHECK(ok);
        result.resize(len); // trim to the length of the decoded buffer
        CHECK(result == c.text);
        // likewise for keys
    }
    //
    // ryml base64() serialization uses native endianness. If you're
    // encoding types whose size > 1 byte, the results will vary
    // according to endianess. Let's use a helper here to work around
    // that (in practice, you should use something like htons() before
    // encoding):
    union { uint32_t u; char c[sizeof(uint32_t)]; } endianess_test = {1};
    const bool is_little_endian = endianess_test.c[0] == 1; // NOLINT
    auto endian_select = [is_little_endian](ryml::csubstr little_endian, ryml::csubstr big_endian){
        return is_little_endian ? little_endian : big_endian;
    };
    //
    // directly encode variables: integers
    {
        const uint64_t valin = UINT64_C(0xdeadbeef);
        ryml::NodeRef node = tree["deadbeef"];
        node.set_serialized(c4::fmt::base64(valin), ryml::VAL_PLAIN);
        CHECK(node.val() == endian_select("776t3gAAAAA=", "AAAAAN6tvu8="));
        uint64_t valout = 0;
        size_t len = 0;
        node.load(ryml::fmt::base64(valout, &len));
        CHECK(len == sizeof(valout));
        CHECK(valout == UINT64_C(0xdeadbeef)); // base64 roundtrip is bit-accurate
        // also works without length parameter:
        valout = {};
        node.load(ryml::fmt::base64(valout));
        CHECK(valout == UINT64_C(0xdeadbeef)); // base64 roundtrip is bit-accurate
    }
    // directly encode variables: floating point
    {
        const double valin = 123456.7891011;
        ryml::NodeRef node = tree["float"];
        node.set_serialized(c4::fmt::base64(valin), ryml::VAL_PLAIN);
        CHECK(node.val() == endian_select("nHkooAwk/kA=", "QP4kDKAoeZw="));
        double valout = 0;
        size_t len = 0;
        node.load(ryml::fmt::base64(valout, &len));
        CHECK(len == sizeof(valout));
        CHECK(memcmp(&valout, &valin, sizeof(valout)) == 0); // base64 roundtrip is bit-accurate // NOLINT
        // also works without length parameter:
        valout = {};
        node.load(ryml::fmt::base64(valout));
        CHECK(memcmp(&valout, &valin, sizeof(valout)) == 0); // base64 roundtrip is bit-accurate // NOLINT
    }
    // directly encode memory ranges
    {
        const uint32_t data_in[11] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0xdeadbeef};
        uint32_t data_out[11] = {};
        ryml::NodeRef node = tree["int_data"];
        node.set_serialized(ryml::fmt::base64(data_in, C4_COUNTOF(data_in)), ryml::VAL_PLAIN);
        CHECK(node.val() ==
              endian_select("AAAAAAEAAAACAAAAAwAAAAQAAAAFAAAABgAAAAcAAAAIAAAACQAAAO++rd4=",
                            "AAAAAAAAAAEAAAACAAAAAwAAAAQAAAAFAAAABgAAAAcAAAAIAAAACd6tvu8="));
        CHECK(memcmp(data_in, data_out, sizeof(data_in)) != 0); // before the roundtrip
        size_t len = 0;
        node.load(ryml::fmt::base64(data_out, C4_COUNTOF(data_in), &len));
        CHECK(len == sizeof(data_out));
        CHECK(memcmp(data_in, data_out, sizeof(data_in)) == 0); // after the roundtrip
        // also works without length parameter (because data_out is an
        // array and not a pointer):
        memset(data_out, 0, sizeof(data_out));
        node.load(ryml::fmt::base64(data_out));
        CHECK(memcmp(data_in, data_out, sizeof(data_in)) == 0); // after the roundtrip
    }
}

Referenced by main().

sample_serialize_basic()

void sample_serialize_basic

(

)

serialize/deserialize fundamental types

This sample shows the main user-facing calls triggering (de)serialization.

ryml provides built-ins for all fundamental types. For samples on how to implement other types such as STL containers or user types, see the samples below.

Read also the doxygen intro to using serialization

And likewise, you can use these from the tree as well: c4::yml::Tree::set_serialized() / c4::yml::Tree::set_key_serialized().

For deserialization, use from_chars().

Definition at line 3874 of file quickstart.cpp.

{
    ryml::csubstr yaml = "{0: 0, 10: 10, foo: foo}";
    ryml::Tree tree = ryml::parse_in_arena(yaml);
    //
    //
    // Deserialization is done with .load() and .load_key()
    { int      val = 1; tree[0].load(&val); CHECK(val == 0); }
    { unsigned val = 0; tree[1].load(&val); CHECK(val == 10); }
    { int      key = 1; tree[0].load_key(&key); CHECK(key == 0); }
    { unsigned key = 0; tree[1].load_key(&key); CHECK(key == 10); }
    // also available in the tree:
    { int      val = 1; tree.load(tree[0].id(), &val); CHECK(val == 0); }
    { unsigned val = 0; tree.load(tree[1].id(), &val); CHECK(val == 10); }
    { int      key = 1; tree.load_key(tree[0].id(), &key); CHECK(key == 0); }
    { unsigned key = 0; tree.load_key(tree[1].id(), &key); CHECK(key == 10); }
    // .load() calls the (non returning) error callback when the
    // serialization fails. If you want to avoid the exceptional flow,
    // you can use .deserialize() / .deserialize_key(), and do not forget to
    // check its return status (marked as `[[nodiscard]]`):
    { int      val = 1; CHECK(tree[0].deserialize(&val)); CHECK(val == 0); }
    { unsigned val = 0; CHECK(tree[1].deserialize(&val)); CHECK(val == 10); }
    { int      key = 1; CHECK(tree[0].deserialize_key(&key)); CHECK(key == 0); }
    { unsigned key = 0; CHECK(tree[1].deserialize_key(&key)); CHECK(key == 10); }
    // also available in the tree:
    { int      val = 1; CHECK(tree.deserialize(tree[0].id(), &val)); CHECK(val == 0); }
    { unsigned val = 0; CHECK(tree.deserialize(tree[1].id(), &val)); CHECK(val == 10); }
    { int      key = 1; CHECK(tree.deserialize_key(tree[0].id(), &key)); CHECK(key == 0); }
    { unsigned key = 0; CHECK(tree.deserialize_key(tree[1].id(), &key)); CHECK(key == 10); }
    //
    //
    // Serialization is done with .save() and .save_key(). It is
    // carried out by converting the value to string in the tree's
    // arena (see sample_tree_arena()).
    { int      val = 10; tree[0].save(val); CHECK(tree[0].val() == "10"); }
    { unsigned val = 11; tree[1].save(val); CHECK(tree[1].val() == "11"); }
    { int      key = 12; tree[0].save_key(key); CHECK(tree[0].key() == "12"); }
    { unsigned key = 13; tree[1].save_key(key); CHECK(tree[1].key() == "13"); }
    // also available in the tree:
    { int      val = 20; tree.save(tree[0].id(), val); CHECK(tree[0].val() == "20"); }
    { unsigned val = 21; tree.save(tree[1].id(), val); CHECK(tree[1].val() == "21"); }
    { int      key = 22; tree.save_key(tree[0].id(), key); CHECK(tree[0].key() == "22"); }
    { unsigned key = 23; tree.save_key(tree[1].id(), key); CHECK(tree[1].key() == "23"); }
    //
    //
    // Like .load(), .save() checks the node for write-ability and
    // triggers an error if it failed. Likewise, to avoid the
    // exceptional path, you can use .set_serialized() and
    // .set_key_serialized():
    { int      val = 14; tree[0].set_serialized(val); CHECK(tree[0].val() == "14"); }
    { unsigned val = 15; tree[1].set_serialized(val); CHECK(tree[1].val() == "15"); }
    { int      key = 16; tree[0].set_key_serialized(key); CHECK(tree[0].key() == "16"); }
    { unsigned key = 17; tree[1].set_key_serialized(key); CHECK(tree[1].key() == "17"); }
    /// And likewise, you can use these from the tree as well:
    /// @ref c4::yml::Tree::set_serialized() / @ref c4::yml::Tree::set_key_serialized().
    { int      val = 18; tree.set_serialized(tree[0].id(), val); CHECK(tree[0].val() == "18"); }
    { unsigned val = 19; tree.set_serialized(tree[1].id(), val); CHECK(tree[1].val() == "19"); }
    { int      key = 20; tree.set_key_serialized(tree[0].id(), key); CHECK(tree[0].key() == "20"); }
    { unsigned key = 21; tree.set_key_serialized(tree[1].id(), key); CHECK(tree[1].key() == "21"); }
    //
    //
    // You can also (de)serialize tags and even anchors, if your
    // application requires it. For serialization the trick is to use
    // .to_arena():
    tree[0].set_val_tag(tree[0].to_arena(42)); CHECK(tree[0].val_tag() == "42");
    tree[1].set_key_tag(tree[1].to_arena(43)); CHECK(tree[1].key_tag() == "43");
    tree[0].set_val_anchor(tree[0].to_arena(44)); CHECK(tree[0].val_anchor() == "44");
    tree[1].set_key_anchor(tree[1].to_arena(45)); CHECK(tree[1].key_anchor() == "45");
    /// For deserialization, use from_chars().
    { int      val = 0; CHECK(from_chars(tree[0].val_tag(), &val)); CHECK(val == 42); }
    { unsigned key = 0; CHECK(from_chars(tree[1].key_tag(), &key)); CHECK(key == 43); }
    { int      val = 0; CHECK(from_chars(tree[0].val_anchor(), &val)); CHECK(val == 44); }
    { unsigned key = 0; CHECK(from_chars(tree[1].key_anchor(), &key)); CHECK(key == 45); }
}

Referenced by main().

sample_user_scalar_types()

void sample_user_scalar_types

(

)

serialize/deserialize scalar (leaf/scalar) types

to add scalar types (ie leaf types converting to/from string), define the functions above for those types.

Note

read the doxygen documentation for scalar types at: https://rapidyaml.readthedocs.io/v0.16.0/doxygen/group__doc__serialization__user__types.html

See Serialize/deserialize scalar types.

Definition at line 4018 of file quickstart.cpp.

{
    ryml::Tree t;
    ryml::NodeRef root = t;
    root.set_map();
 
    vec2<int> v2in{10, 11};
    vec2<int> v2out{1, 2};
    root["v2"].save(v2in); // serializes to the tree's arena, and then sets the val
    root["v2"].load(&v2out);
    CHECK(v2in.x == v2out.x);
    CHECK(v2in.y == v2out.y);
    vec3<int> v3in{100, 101, 102};
    vec3<int> v3out{1, 2, 3};
    root["v3"].save(v3in); // serializes to the tree's arena, and then sets the val
    root["v3"].load(&v3out);
    CHECK(v3in.x == v3out.x);
    CHECK(v3in.y == v3out.y);
    CHECK(v3in.z == v3out.z);
    vec4<int> v4in{1000, 1001, 1002, 1003};
    vec4<int> v4out{1, 2, 3, 4};
    root["v4"].save(v4in); // serializes to the tree's arena, and then sets the val
    root["v4"].load(&v4out);
    CHECK(v4in.x == v4out.x);
    CHECK(v4in.y == v4out.y);
    CHECK(v4in.z == v4out.z);
    CHECK(v4in.w == v4out.w);
    CHECK(ryml::emitrs_yaml<std::string>(t) == ""
          "v2: (10,11)"                 "\n"
          "v3: (100,101,102)"           "\n"
          "v4: (1000,1001,1002,1003)"   "\n"
          "");
 
    // note that only the used functions are needed:
    //   - if a type is only parsed, then only from_chars() is needed
    //   - if a type is only emitted, then only to_chars() is needed
    emit_only_vec2<int> eov2in{20, 21}; // only has to_chars()
    parse_only_vec2<int> pov2out{1, 2}; // only has from_chars()
    root["v2"].save(eov2in); // serializes to the tree's arena, and then sets the keyval
    root["v2"].load(&pov2out);
    CHECK(eov2in.x == pov2out.x);
    CHECK(eov2in.y == pov2out.y);
    emit_only_vec3<int> eov3in{30, 31, 32}; // only has to_chars()
    parse_only_vec3<int> pov3out{1, 2, 3}; // only has from_chars()
    root["v3"].save(eov3in); // serializes to the tree's arena, and then sets the keyval
    root["v3"].load(&pov3out);
    CHECK(eov3in.x == pov3out.x);
    CHECK(eov3in.y == pov3out.y);
    CHECK(eov3in.z == pov3out.z);
    emit_only_vec4<int> eov4in{40, 41, 42, 43}; // only has to_chars()
    parse_only_vec4<int> pov4out{1, 2, 3, 4}; // only has from_chars()
    root["v4"].save(eov4in); // serializes to the tree's arena, and then sets the keyval
    root["v4"].load(&pov4out);
    CHECK(eov4in.x == pov4out.x);
    CHECK(eov4in.y == pov4out.y);
    CHECK(eov4in.z == pov4out.z);
    CHECK(ryml::emitrs_yaml<std::string>(t) == ""
          "v2: (20,21)"        "\n"
          "v3: (30,31,32)"     "\n"
          "v4: (40,41,42,43)"  "\n"
          "");
}

Referenced by main().

sample_user_container_types_brief()

void sample_user_container_types_brief

(

)

serialize/deserialize container (map or seq) types: brief version

shows a minimal example of user container types, defined in Serialize container types (brief)

Note

read the doxygen documentation for containers/general types at: https://rapidyaml.readthedocs.io/v0.16.0/doxygen/group__doc__serialization__user__types.html

Definition at line 4143 of file quickstart.cpp.

{
    ryml::Tree tree;
    ryml::NodeRef root = tree;
    Outer outer{{{0,1}, {2,3}}};
    Outer roundtrip;
    // let's do a serialization roundtrip.
    // first serialize:
    root.save(outer);
    // see how the YAML looks:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "- {foo: 0,bar: 1}\n"
          "- {foo: 2,bar: 3}\n");
    // now complete the roundtrip by deserializing:
    root.load(&roundtrip);
    // finally, verify that the result is equal:
    CHECK(0 == memcmp(&outer, &roundtrip, sizeof(Outer)));
}

Referenced by main().

sample_user_container_types()

void sample_user_container_types

(

)

serialize/deserialize container (map or seq) types

shows how to serialize/deserialize container types (defined in Serialize container types).

Note

read the doxygen documentation for containers/general types at: https://rapidyaml.readthedocs.io/v0.16.0/doxygen/group__doc__serialization__user__types.html

See also

Serialize container types

sample_std_types

sample_deserialize_error

Definition at line 4414 of file quickstart.cpp.

{
    // let's do a YAML roundtrip:
    ryml::Tree tree;
    ryml::NodeRef root_node = tree;
    ryml::id_type root_id = tree.root_id();
 
    // here we will be doing a serialization roundtrip with a
    // user-defined container type.
    //
    // the read() and write() functions for this type are defined
    // above.
    const my_type orig{
        {20, 21},
        {30, 31, 32},
        {40, 41, 42, 43},
        {{101, 102, 103, 104, 105, 106, 107}},
        {{{1001, 2001}, {1002, 2002}, {1003, 2003}}},
    };
 
    // serialize to the tree:
    root_node.save(orig);
    // check the YAML:
    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "v2: (20,21)"         "\n"
          "v3: (30,31,32)"      "\n"
          "v4: (40,41,42,43)"   "\n"
          "seq:"                "\n"
          "  - 101"             "\n"
          "  - 102"             "\n"
          "  - 103"             "\n"
          "  - 104"             "\n"
          "  - 105"             "\n"
          "  - 106"             "\n"
          "  - 107"             "\n"
          "map:"                "\n"
          "  1001: 2001"        "\n"
          "  1002: 2002"        "\n"
          "  1003: 2003"        "\n"
          "");
    // and now let's deserialize to this variable.
    // first from a node:
    {
        my_type roundtrip;
        root_node.load(&roundtrip); // picks the node read(), because we wrote one.
                                    // if we didn't, it would then pick the tree read()
        roundtrip.check_eq(orig); // finally, let's compare.
    }
    // let's also deserialize from the tree:
    {
        my_type roundtrip;
        tree.load(root_id, &roundtrip); // will pick the tree read()
        roundtrip.check_eq(orig); // finally, let's compare.
    }
 
    // We created above a my_seq<std::string> specialization showing
    // that we can use write() without serializing the data to the
    // tree's arena. Let's show it working here:
    const my_seq_type<std::string> strseq{{
        "doe",
        "a deer, a female deer",
        "ray",
        "a drop of golden sun"
    }};
    // serialize it to a nested node in the tree:
    tree["not in arena"].save(strseq);
    // check the YAML:
    CHECK(ryml::emitrs_yaml<std::string>(tree["not in arena"]) == ""
          // note the new elements:
          "not in arena:"              "\n"
          "  - doe"                    "\n"
          "  - a deer, a female deer"  "\n"
          "  - ray"                    "\n"
          "  - a drop of golden sun"   "\n"
          "");
    // show how the strings are NOT in the tree's arena
    size_t pos = 0;
    CHECK(strseq.seq_member.size() == tree["not in arena"].num_children());
    for(ryml::ConstNodeRef child : tree["not in arena"].children())
    {
        ryml::csubstr str_orig = ryml::to_csubstr(strseq.seq_member[pos++]);
        CHECK(child.val() == str_orig); // same string
        CHECK(!child.val().is_sub(tree.arena())); // not in the tree's arena
        CHECK(child.val().is_sub(str_orig)); // ... but the original memory
    }
}

Referenced by main().

sample_std_types()

void sample_std_types

(

)

serialize/deserialize STL containers

demonstrates usage with the std implementations provided by ryml in the ryml_std.hpp header

See also

Serialize container types

also the STL section in Serialization/deserialization

Definition at line 4563 of file quickstart.cpp.

{
    // we're using C-strings because doxygen breaks down on raw strings
    std::string yml_std_string = ""
        "- v2: (20,21)"              "\n"
        "  v3: (30,31,32)"           "\n"
        "  v4: (40,41,42,43)"        "\n"
        "  seq:"                     "\n"
        "    - 101"                  "\n"
        "    - 102"                  "\n"
        "    - 103"                  "\n"
        "    - 104"                  "\n"
        "    - 105"                  "\n"
        "    - 106"                  "\n"
        "    - 107"                  "\n"
        "  map:"                     "\n"
        "    1001: 2001"             "\n"
        "    1002: 2002"             "\n"
        "    1003: 2003"             "\n"
        "- v2: (120,121)"            "\n"
        "  v3: (130,131,132)"        "\n"
        "  v4: (140,141,142,143)"    "\n"
        "  seq:"                     "\n"
        "    - 1101"                 "\n"
        "    - 1102"                 "\n"
        "    - 1103"                 "\n"
        "    - 1104"                 "\n"
        "    - 1105"                 "\n"
        "    - 1106"                 "\n"
        "    - 1107"                 "\n"
        "  map:"                     "\n"
        "    11001: 12001"           "\n"
        "    11002: 12002"           "\n"
        "    11003: 12003"           "\n"
        "- v2: (220,221)"            "\n"
        "  v3: (230,231,232)"        "\n"
        "  v4: (240,241,242,243)"    "\n"
        "  seq:"                     "\n"
        "    - 2101"                 "\n"
        "    - 2102"                 "\n"
        "    - 2103"                 "\n"
        "    - 2104"                 "\n"
        "    - 2105"                 "\n"
        "    - 2106"                 "\n"
        "    - 2107"                 "\n"
        "  map:"                     "\n"
        "    21001: 22001"           "\n"
        "    21002: 22002"           "\n"
        "    21003: 22003"           "\n"
        "";
    // parse in-place using the std::string above
    ryml::Tree tree = ryml::parse_in_place(ryml::to_substr(yml_std_string));
    // my_type is a container-of-containers type. see above its
    // definition implementation for ryml.
    std::vector<my_type> vec;
    tree.rootref().load(&vec);
    CHECK(vec.size() == 3);
    ryml::Tree tree_out;
    tree_out.rootref().save(vec);
    CHECK(ryml::emitrs_yaml<std::string>(tree_out) == yml_std_string);
}

Referenced by main().

sample_deserialize_error()

void sample_deserialize_error

(

)

shows error on deserializing nested nodes

shows what happens on deserialization errors

Note

read the doxygen documentation for containers/general types at: https://rapidyaml.readthedocs.io/v0.16.0/doxygen/group__doc__serialization__user__types.html

See also

sample_user_container_types()

sample_error_visit_location()

sample_location_tracking()

Definition at line 4513 of file quickstart.cpp.

{
    // in this example we will be checking errors, so set up a
    // temporary error handler to catch them:
    ScopedErrorHandlerExample errh; // calls ryml::set_callbacks()
    // let's parse this YAML containing an invalid value,
    // with location tracking:
    ryml::EventHandlerTree tree_handler;
    ryml::Parser parser(&tree_handler, ryml::ParserOptions{}.locations(true));
    const ryml::Tree tree = parse_in_arena(&parser,
          "v2: (20,21)"         "\n"
          "v3: (30,31,32)"      "\n"
          "v4: (40,41,42,43)"   "\n"
          "seq:"                "\n"
          "  - 101"             "\n"
          "  - 102"             "\n"
          "  - 103"             "\n"
          "  - 104"             "\n"
          "  - 105"             "\n"
          "  - 106"             "\n"
          "  - 107"             "\n"
          "map:"                "\n"
          "  1001: 2001"        "\n"
          "  1002: not an int"  "\n"  // valid YAML, will cause deserialization error
          "  1003: 2003"        "\n"
          "");
    ryml::ConstNodeRef root = tree;
    // and now let's deserialize to this variable
    my_type var;
    // .deserialize() reports the error but does not trigger an error
    // call:
    ryml::ReadResult result = root.deserialize(&var);
    CHECK(!result);
    CHECK(result.node == tree["map"]["1002"].id()); // this is where the error occurred
    CHECK(tree.location(parser, result.node).line == 13);
    CHECK(tree.location(parser, result.node).col == 2); // this node starts a column 2
    CHECK(parser.val_location(tree.val(result.node).str).col == 8); // its value starts at column 8
    // and .load() will trigger a visit error, reporting the node as
    // well. see sample_error_visit_location() for examples on how to
    // track the location of a visit error
    errh.check_error_occurs([&]{ root.load(&var); });
}

Referenced by main().

sample_float_precision()

void sample_float_precision

(

)

control precision of serialized floats

Definition at line 4629 of file quickstart.cpp.

{
    std::vector<double> reference{1.23234412342131234, 2.12323123143434237, 3.67847983572591234};
    // A safe precision for comparing doubles. May vary depending on
    // compiler flags. Double goes to about 15 digits, so 14 should be
    // safe enough for this test to succeed.
    const double precision_safe = 1.e-14;
    const size_t num_digits_safe = 14;
    const size_t num_digits_original = 17;
    auto get_num_digits = [](ryml::csubstr number){ return number.len - 2u; };
    //
    // no significant precision is lost when reading
    // floating point numbers:
    {
        ryml::Tree tree = ryml::parse_in_arena("[1.23234412342131234, 2.12323123143434237, 3.67847983572591234]");
        std::vector<double> output;
        tree.rootref().load(&output);
        CHECK(output.size() == reference.size());
        for(size_t i = 0; i < reference.size(); ++i)
        {
            CHECK(get_num_digits(tree[(ryml::id_type)i].val()) == num_digits_original);
            CHECK(fabs(output[i] - reference[i]) < precision_safe);
        }
    }
    //
    // However, depending on the compilation settings, there may be a
    // significant precision loss when serializing with the default
    // approach, .save(double):
    {
        ryml::Tree serialized;
        serialized.rootref().save(reference);
        // Without std::to_chars() there is a loss of precision:
        #if (!C4CORE_HAVE_STD_TOCHARS) // check if std::to_chars() is available.
        CHECK((ryml::emitrs_yaml<std::string>(serialized) == ""
              "- 1.23234"   "\n"
              "- 2.12323"   "\n"
              "- 3.67848"   "\n"
              "") || (bool)"this is indicative; the exact results will vary from platform to platform.");
        C4_UNUSED(num_digits_safe);
        // ... but when using C++17 and above, the results are eminently equal:
        #else
        CHECK((ryml::emitrs_yaml<std::string>(serialized) == ""
               "- 1.2323441234213124"   "\n"
               "- 2.1232312314343424"   "\n"
               "- 3.6784798357259123"   "\n"
               "") || (bool)"this is indicative; the exact results will vary from platform to platform.");
        size_t pos = 0;
        for(ryml::ConstNodeRef child : serialized.rootref().children())
        {
            CHECK(get_num_digits(child.val()) >= num_digits_safe);
            double out = {};
            child.load(&out);
            CHECK(fabs(out - reference[pos++]) < precision_safe);
        }
        #endif
    }
    //
    // The difference is explained by the availability of
    // fastfloat::from_chars(), std::from_chars() and std::to_chars().
    //
    // ryml prefers the fastfloat::from_chars() version. Unfortunately
    // fastfloat does not have to_chars() (see
    // https://github.com/fastfloat/fast_float/issues/23).
    //
    // When C++17 is used, ryml uses std::to_chars(), which produces
    // good defaults.
    //
    // However, with earlier standards, or in some library
    // implementations, there's only snprintf() available. Every other
    // std library function will either disrespect the string limits,
    // or more precisely, accept no string size limits. So the
    // implementation of c4core (which ryml uses) falls back to
    // snprintf("%g"), and that picks by default a (low) number of
    // digits.
    //
    // But not all is lost for C++11/C++14 users!
    //
    // To force a particular precision when serializing, you can use
    // c4::fmt::real() (brought into the ryml:: namespace). Or you can
    // serialize the number yourself! The small downside is that you
    // have to build the container.
    //
    // First a function to check the result:
    auto check_precision = [&](ryml::Tree const& serialized){
        std::cout << serialized;
        // now it works!
        CHECK((ryml::emitrs_yaml<std::string>(serialized) == ""
               "- 1.23234412342131239"   "\n"
               "- 2.12323123143434245"   "\n"
               "- 3.67847983572591231"   "\n"
               "") || (bool)"this is indicative; the exact results will vary from platform to platform.");
        size_t pos = 0;
        for(ryml::ConstNodeRef child : serialized.rootref().children())
        {
            CHECK(get_num_digits(child.val()) == num_digits_original);
            double out = {};
            child.load(&out);
            CHECK(fabs(out - reference[pos++]) < precision_safe);
        }
    };
    //
    // Serialization example using fmt::real()
    {
        ryml::Tree serialized;
        ryml::NodeRef root = serialized.rootref();
        root.set_seq();
        for(const double v : reference)
            root.append_child().save(ryml::fmt::real(v, num_digits_original, ryml::FTOA_FLOAT));
        check_precision(serialized); // OK - now within bounds!
    }
    //
    // Serialization example using snprintf
    {
        ryml::Tree serialized;
        ryml::NodeRef root = serialized.rootref();
        root.set_seq();
        char tmp[64];
        for(const double v : reference)
        {
            // reuse a buffer to serialize.
            // add 1 to the significant digits because the %g
            // specifier counts the integral digits.
            (void)snprintf(tmp, sizeof(tmp), "%.18g", v);
            // copy the serialized string to the tree (.save()
            // copies to the arena, .set_val() just assigns the string
            // pointer and would be wrong in this case):
            root.append_child().save(ryml::to_csubstr((const char*)tmp));
        }
        check_precision(serialized); // OK - now within bounds!
    }
}

Referenced by main().