Overview

Functions
void	sample_lightning_overview ()
	lightning overview of most common features More...
void	sample_quick_overview ()
	quick overview of most common features More...

Detailed Description

Function Documentation

void sample_lightning_overview

(

)

lightning overview of most common features

a lightning tour over most features see sample_quick_overview

Definition at line 409 of file quickstart.cpp.

Referenced by main().

{
    // Parse YAML code in place, potentially mutating the buffer:
    char yml_buf[] = "{foo: 1, bar: [2, 3], john: doe}";
    ryml::Tree tree = ryml::parse_in_place(yml_buf);

    // read from the tree:
    ryml::NodeRef bar = tree["bar"];
    CHECK(bar[0].val() == "2");
    CHECK(bar[1].val() == "3");
    CHECK(bar[0].val().str == yml_buf + 15); // points at the source buffer
    CHECK(bar[1].val().str == yml_buf + 18);

    // deserializing:
    int bar0 = 0, bar1 = 0;
    bar[0].load(&bar0); // also checks the node is readable, and conversion succeeded
    bar[1].load(&bar1); // see also .deserialize()
    CHECK(bar0 == 2);
    CHECK(bar1 == 3);

    // serializing:
    bar[0].save(10); // creates a string in the tree's arena
    bar[1].save(11); // see also .set_serialized()
    CHECK(bar[0].val() == "10");
    CHECK(bar[1].val() == "11");

    // add nodes
    tree["new"].set_val("node");
    bar.append_child().save(12);
    CHECK(bar[2].val() == "12");

    // emit tree
    std::string expected = "{foo: 1,bar: [10,11,12],john: doe,new: node}";
    // emit tree to std::string
    CHECK(ryml::emitrs_yaml<std::string>(tree) == expected);
    // emit tree to FILE*
    ryml::emit_yaml(tree, stdout); printf("\n");
    // emit tree to ostream
    std::cout << tree << "\n";

    // emit node
    ryml::ConstNodeRef foo = tree["foo"];
    expected = "foo: 1\n";
    // emit node to std::string
    CHECK(ryml::emitrs_yaml<std::string>(foo) == expected);
    // emit node to FILE*
    ryml::emit_yaml(foo, stdout);
    // emit node to ostream
    std::cout << foo;
}

void sample_quick_overview

(

)

quick overview of most common features

a brief tour over most features

Definition at line 464 of file quickstart.cpp.

Referenced by main().

{
    // Parse YAML code in place, potentially mutating the buffer:
    char yml_buf[] = ""
        "foo: 1"         "\n"
        "bar: [2, 3]"    "\n"
        "john: doe"      "\n"
        "";
    ryml::Tree tree = ryml::parse_in_place(yml_buf);

    // The resulting tree contains only views to the parsed string. If
    // the string was parsed in place, then the string must outlive
    // the tree! This works here because both `yml_buf` and `tree`
    // live on the same scope, so have the same lifetime.

    // It is also possible to:
    //
    //   - parse a read-only buffer using parse_in_arena(). This
    //     copies the YAML buffer to the tree's arena, and spares the
    //     headache of the string's lifetime.
    //
    //   - reuse an existing tree (advised)
    //
    //   - reuse an existing parser (advised)
    //
    //   - parse into an existing node deep in a tree
    //
    // Note: it will always be significantly faster to parse in place
    // and reuse tree+parser.
    //
    // Below you will find samples that show how to achieve reuse; but
    // please note that for brevity and clarity, many of the examples
    // here are parsing in the arena, and not reusing tree or parser.


    //------------------------------------------------------------------
    // API overview

    // The ryml tree has a two-level API:
    //
    // The lower level index API is based on the indices of nodes,
    // where the node's id is the node's position in the tree's data
    // array. This API is very efficient, but somewhat difficult to use:
    ryml::id_type root_id = tree.root_id();
    ryml::id_type bar_id = tree.find_child(root_id, "bar"); // need to get the index right
    CHECK(tree.is_map(root_id)); // all of the index methods are in the tree
    CHECK(tree.is_seq(bar_id));  // ... and receive the subject index

    // The node API is a lightweight abstraction sitting on top of the
    // index API, but offering a much more convenient interaction:
    ryml::ConstNodeRef root = tree.rootref();  // a const node reference
    ryml::ConstNodeRef bar = tree["bar"];
    CHECK(root.is_map());
    CHECK(bar.is_seq());

    // A node ref is a lightweight handle to the tree and associated id:
    CHECK(root.tree() == &tree); // a node ref points at its tree, WITHOUT refcount
    CHECK(root.id() == root_id); // a node ref's id is the index of the node
    CHECK(bar.id() == bar_id);   // a node ref's id is the index of the node

    // The node API translates very cleanly to the index API, so most
    // of the code examples below are using the node API.

    // WARNING. A node ref holds a raw pointer to the tree. Care must
    // be taken to ensure the lifetimes match, so that a node will
    // never access the tree after the tree goes out of scope.


    //------------------------------------------------------------------
    // To read the parsed tree

    // ConstNodeRef::operator[] does a lookup, is O(num_children[node]).
    CHECK(tree["foo"].is_keyval());
    CHECK(tree["foo"].val() == "1");   // get the val of a node (must be leaf node, otherwise it is a container and has no val)
    CHECK(tree["foo"].key() == "foo"); // get the key of a node (must be child of a map, otherwise it has no key)
    CHECK(tree["bar"].is_seq());
    CHECK(tree["bar"].has_key());
    CHECK(tree["bar"].key() == "bar");
    // maps use string keys, seqs use index keys:
    CHECK(tree["bar"][0].val() == "2");
    CHECK(tree["bar"][1].val() == "3");
    CHECK(tree["john"].val() == "doe");
    // An index key is the position of the child within its parent,
    // so even maps can also use int keys, if the key position is
    // known.
    CHECK(tree[0].id() == tree["foo"].id());
    CHECK(tree[1].id() == tree["bar"].id());
    CHECK(tree[2].id() == tree["john"].id());
    // Tree::operator[](int) searches a ***root*** child by its position.
    CHECK(tree[0].id() == tree["foo"].id());  // 0: first child of root
    CHECK(tree[1].id() == tree["bar"].id());  // 1: second child of root
    CHECK(tree[2].id() == tree["john"].id()); // 2: third child of root
    // NodeRef::operator[](int) searches a ***node*** child by its position:
    CHECK(bar[0].val() == "2"); // 0 means first child of bar
    CHECK(bar[1].val() == "3"); // 1 means second child of bar
    // NodeRef::operator[](string):
    // A string key is the key of the node: lookup is by name. So it
    // is only available for maps, and it is NOT available for seqs,
    // since seq members do not have keys.
    CHECK(tree["foo"].key() == "foo");
    CHECK(tree["bar"].key() == "bar");
    CHECK(tree["john"].key() == "john");
    CHECK(bar.is_seq());
    // CHECK(bar["BOOM!"].is_seed()); // error, seqs do not have key lookup

    // Note that maps can also use index keys as well as string keys:
    CHECK(root["foo"].id() == root[0].id());
    CHECK(root["bar"].id() == root[1].id());
    CHECK(root["john"].id() == root[2].id());

    // IMPORTANT. The ryml tree uses an index-based linked list for
    // storing children, so the complexity of
    // `Tree::operator[csubstr]` and `Tree::operator[id_type]` is O(n),
    // linear on the number of root children. If you use
    // `Tree::operator[]` with a large tree where the root has many
    // children, you will see a performance hit.
    //
    // To avoid this hit, you can create your own accelerator
    // structure. For example, before doing a lookup, do a single
    // traverse at the root level to fill an `map<csubstr,id_type>`
    // mapping key names to node indices; with a node index, a lookup
    // (via `Tree::get()`) is O(1), so this way you can get O(log n)
    // lookup from a key. (But please do not use `std::map` if you
    // care about performance; use something else like a flat map or
    // sorted vector).
    //
    // As for node refs, the difference from `NodeRef::operator[]` and
    // `ConstNodeRef::operator[]` to `Tree::operator[]` is that the
    // latter refers to the root node, whereas the former are invoked
    // on their target node. But the lookup process works the same for
    // both and their algorithmic complexity is the same: they are
    // both linear in the number of direct children. But of course,
    // depending on the data, that number may be very different from
    // one to another.


    //------------------------------------------------------------------
    // Hierarchy:

    {
        ryml::ConstNodeRef foo = root.first_child();
        ryml::ConstNodeRef john = root.last_child();
        CHECK(tree.size() == 6); // O(1) number of nodes in the tree
        CHECK(root.num_children() == 3); // O(num_children[root])
        CHECK(foo.num_siblings() == 3); // O(num_children[parent(foo)])
        CHECK(foo.parent().id() == root.id()); // parent() is O(1)
        CHECK(root.first_child().id() == root["foo"].id()); // first_child() is O(1)
        CHECK(root.last_child().id() == root["john"].id()); // last_child() is O(1)
        CHECK(john.first_sibling().id() == foo.id());
        CHECK(foo.last_sibling().id() == john.id());
        // prev_sibling(), next_sibling(): (both are O(1))
        CHECK(foo.num_siblings() == root.num_children());
        CHECK(foo.prev_sibling().id() == ryml::NONE); // foo is the first_child()
        CHECK(foo.next_sibling().key() == "bar");
        CHECK(foo.next_sibling().next_sibling().key() == "john");
        CHECK(foo.next_sibling().next_sibling().next_sibling().id() == ryml::NONE); // john is the last_child()
    }


    //------------------------------------------------------------------
    // Iterating:
    {
        ryml::csubstr expected_keys[] = {"foo", "bar", "john"};
        // iterate children using the high-level node API:
        {
            ryml::id_type count = 0;
            for(ryml::ConstNodeRef const& child : root.children())
                CHECK(child.key() == expected_keys[count++]);
        }
        // iterate siblings using the high-level node API:
        {
            ryml::id_type count = 0;
            for(ryml::ConstNodeRef const& child : root["foo"].siblings())
                CHECK(child.key() == expected_keys[count++]);
        }
        // iterate children using the lower-level tree index API:
        {
            ryml::id_type count = 0;
            for(ryml::id_type child_id = tree.first_child(root_id); child_id != ryml::NONE; child_id = tree.next_sibling(child_id))
                CHECK(tree.key(child_id) == expected_keys[count++]);
        }
        // iterate siblings using the lower-level tree index API:
        // (notice the only difference from above is in the loop
        // preamble, which calls tree.first_sibling(bar_id) instead of
        // tree.first_child(root_id))
        {
            ryml::id_type count = 0;
            for(ryml::id_type child_id = tree.first_sibling(bar_id); child_id != ryml::NONE; child_id = tree.next_sibling(child_id))
                CHECK(tree.key(child_id) == expected_keys[count++]);
        }
    }


    //------------------------------------------------------------------
    // Gotchas:

    // ryml uses assertions to prevent you from trying to obtain
    // things that do not exist. For example:

    {
        ryml::ConstNodeRef seq_node = tree["bar"];
        ryml::ConstNodeRef val_node = seq_node[0];

        CHECK(seq_node.is_seq());          // seq is a container
        CHECK(!seq_node.has_val());        // ... so it has no val
        //CHECK(seq_node.val() == BOOM!);  // ... so attempting to get a val is undefined behavior

        CHECK(val_node.parent() == seq_node); // belongs to a seq
        CHECK(!val_node.has_key());           // ... so it has no key
        //CHECK(val_node.key() == BOOM!);     // ... so attempting to get a key is undefined behavior

        CHECK(val_node.is_val());                 // this node is a val
        //CHECK(val_node.first_child() == BOOM!); // ... so attempting to get a child is undefined behavior

        // assertions are also present in methods that /may/ read the val:
        CHECK(seq_node.is_seq());              // seq is a container
        //CHECK(seq_node.val_is_null() BOOM!); // so cannot get the val to check
    }

    // By default, assertions are enabled unless the NDEBUG macro is
    // defined (which happens in release builds).
    //
    // This adheres to the pay-only-for-what-you-use philosophy: if
    // you are sure that your intent is correct, why would you need to
    // pay the runtime cost for the assertions?
    //
    // The downside, of course, is that you may be unsure, or your
    // code may be wrong; and then release builds may end up doing
    // something wrong.
    //
    // So in that case, you can use the appropriate ryml predicates to
    // check your intent (as in the examples above), or you can
    // explicitly enable/disable assertions, by defining the macro
    // RYML_USE_ASSERT to a proper value (see c4/yml/common.hpp). This
    // will make problematic code trigger a call to the appropriate
    // error callback.
    //
    // Also, to be clear, this does not apply to parse errors
    // occurring when the YAML is parsed. Parse errors are always
    // detected by the parser: this is not done through assertions,
    // but through the appropriate error checking mechanism. So
    // checking for these errors is always enabled and cannot be
    // switched off. As for deserialization errors, see below.


    //------------------------------------------------------------------
    // Deserializing:
    //
    //   - use .load(T*)/.load_key(T*) for lazy code with checked reads
    //      - ryml checks preconditions (node readability, etc), or triggers error
    //      - ryml checks deserialization, or triggers error
    //      - more expensive because of all the checks and error marshalling
    //      - optionally, can disable precondition checks with bool parameter
    //
    //   - use .deserialize()/.deserialize_key() for sure reads
    //      - ryml asserts preconditions (readability, etc) (err on debug builds, UB otherwise)
    //      - ryml returns bool for deserialization status, [[nodiscard]]
    //      - cheaper but potentially dangerous
    //
    {
        // fundamental types: ryml provides deserialization facilities
        // .load() checks for readability + conversion errors
        {
            int foo = 0, bar0 = 0, bar1 = 0;
            root["foo"].load(&foo);  // calls err_visit() on failure
            root["bar"][0].load(&bar0);
            root["bar"][1].load(&bar1);
            CHECK(foo == 1);
            CHECK(bar0 == 2);
            CHECK(bar1 == 3);
            // .load() can also be called from the tree
        }
        // .deserialize() asserts readability, user checks conversion errors
        {
            int foo = 0, bar0 = 0, bar1 = 0;
            CHECK(root["foo"].deserialize(&foo));  // user must check return value
            CHECK(root["bar"][0].deserialize(&bar0));
            CHECK(root["bar"][1].deserialize(&bar1));
            CHECK(foo == 1);
            CHECK(bar0 == 2);
            CHECK(bar1 == 3);
            // .deserialize() can also be called from the tree
        }
        // std containers: ryml optionally provides deserialization
        // facilities. see serialization samples below.
        {
            std::string john_str, bar_str;
            root["john"].load(&john_str);
            root["bar"].load_key(&bar_str);
            CHECK(john_str == "doe");
            CHECK(bar_str == "bar");
            std::vector<int> bar_actual, bar_expected{{2, 3}};
            root["bar"].load(&bar_actual);
            CHECK(bar_actual == bar_expected);
        }
    }


    //------------------------------------------------------------------
    // Modifying existing nodes: assigning vs serializing

    // As implied by its name, ConstNodeRef is a reference to a const
    // node. It can be used to read from the node, but not write to it
    // or modify the hierarchy of the node. If any modification is
    // desired then a NodeRef must be used instead:
    ryml::NodeRef wroot = tree.rootref(); // writeable root

    // .set_val() assigns an existing string to the receiving node.
    // The contents are NOT copied, and the string pointer will be in
    // effect until the tree goes out of scope! So BEWARE to only
    // assign from strings outliving the tree.
    wroot["foo"].set_val("says you");
    wroot["bar"][0].set_val("-2");
    wroot["bar"][1].set_val("-3");
    wroot["john"].set_val("ron");
    // Now the tree is _pointing_ at the memory of the strings above.
    // In this case it is OK because those are static strings, located
    // in the executable's static section, and will outlive the tree.
    CHECK(root["foo"].val() == "says you");
    CHECK(root["bar"][0].val() == "-2");
    CHECK(root["bar"][1].val() == "-3");
    CHECK(root["john"].val() == "ron");
    // But WATCHOUT: do not assign from temporary objects:
    // {
    //     std::string bad("will dangle");
    //     root["john"] = bad;
    // }
    // CHECK(root["john"] == "dangling"); // CRASH! the string was deallocated

    // For non-string types, or for strings whose lifetime is
    // problematic WRT the tree, you can create and save a string in
    // the tree using .set_serialized() (or its equivalent .save() if
    // you want to have ryml do the error checking). It first
    // serializes values to a string arena owned by the tree, then
    // assigns the serialized string to the receiving node. This
    // avoids constraints with the lifetime, since the arena lives
    // with the tree.
    CHECK(tree.arena().empty());
    wroot["foo"].set_serialized("says who");  // requires to_chars(). see serialization samples below.
    wroot["bar"][0].set_serialized(20);
    wroot["bar"][1].set_serialized(30);
    wroot["john"].set_serialized("deere");
    CHECK(root["foo"].val() == "says who");
    CHECK(root["bar"][0].val() == "20");
    CHECK(root["bar"][1].val() == "30");
    CHECK(root["john"].val() == "deere");
    CHECK(tree.arena() == "says who2030deere"); // the result of serializations to the tree arena
    // with .set_serialize()/.save(), the crash above is avoided:
    {
        std::string ok("in_scope");
        // root["john"].set_val(ok); // don't, will dangle
        wroot["john"].set_serialized(ok); // OK, copy to the tree's arena
    }
    CHECK(root["john"].val() == "in_scope"); // OK! val is now in the tree's arena
    // serializing floating points:
    wroot["float"].set_serialized(2.4f);
    // to force a particular precision or float format:
    // (see sample_float_precision() and sample_formatting())
    wroot["digits"].set_serialized(ryml::fmt::real(2.4, /*num_digits*/6, ryml::FTOA_FLOAT));
    CHECK(tree.arena() == "says who2030deerein_scope2.42.400000"); // the result of serializations to the tree arena


    //------------------------------------------------------------------
    // Adding new nodes:

    // adding a keyval node to a map:
    CHECK(root.num_children() == 5);
    wroot["newkeyval"].set_val("shiny and new"); // using these strings
    c4::yml::NodeRef chsrl = wroot.append_child();
    chsrl.set_key_serialized("newkeyval (serialized)"); // serializes and assigns the serialization
    chsrl.set_serialized("shiny and new (serialized)"); // serializes and assigns the serialization
    CHECK(root.num_children() == 7);
    CHECK(root["newkeyval"].key() == "newkeyval");
    CHECK(root["newkeyval"].val() == "shiny and new");
    CHECK(root["newkeyval (serialized)"].key() == "newkeyval (serialized)");
    CHECK(root["newkeyval (serialized)"].val() == "shiny and new (serialized)");
    CHECK( ! tree.in_arena(root["newkeyval"].key())); // it's using directly the static string above
    CHECK( ! tree.in_arena(root["newkeyval"].val())); // it's using directly the static string above
    CHECK(   tree.in_arena(root["newkeyval (serialized)"].key())); // it's using a serialization of the string above
    CHECK(   tree.in_arena(root["newkeyval (serialized)"].val())); // it's using a serialization of the string above
    // adding a val node to a seq:
    CHECK(root["bar"].num_children() == 2);
    wroot["bar"][2].set_val("oh so nice");
    wroot["bar"][3].set_serialized("oh so nice (serialized)");
    CHECK(root["bar"].num_children() == 4);
    CHECK(root["bar"][2].val() == "oh so nice");
    CHECK(root["bar"][3].val() == "oh so nice (serialized)");
    // adding a seq node:
    CHECK(root.num_children() == 7);
    wroot["newseq"].set_seq();
    chsrl = wroot.append_child();
    chsrl.set_key_serialized("newseq (serialized)");
    chsrl.set_seq();
    CHECK(root.num_children() == 9);
    CHECK(root["newseq"].num_children() == 0);
    CHECK(root["newseq"].is_seq());
    CHECK(root["newseq (serialized)"].num_children() == 0);
    CHECK(root["newseq (serialized)"].is_seq());
    // adding a map node:
    CHECK(root.num_children() == 9);
    wroot["newmap"].set_map();
    chsrl = wroot.append_child();
    chsrl.set_key_serialized("newmap (serialized)");
    chsrl.set_map();
    CHECK(root.num_children() == 11);
    CHECK(root["newmap"].num_children() == 0);
    CHECK(root["newmap"].is_map());
    CHECK(root["newmap (serialized)"].num_children() == 0);
    CHECK(root["newmap (serialized)"].is_map());
    //
    // When the tree is const, operator[] searches the tree for a
    // matching key/position, and returns it, or raises an error if
    // none is found.
    //
    // When the tree is mutable, operator[] will not mutate the tree
    // until the returned node is written to. operator[] first
    // searches the tree for a node matching the key/position and
    // returns it if it exists; otherwise, the result is a NodeRef
    // object which keeps in itself the required information to write
    // to the proper place in the tree. This is called being in a
    // "seed" state.
    //
    // This means that passing a key/position which does not exist
    // will not mutate the tree, but will instead store (in the
    // returned NodeRef) the proper place of the tree to be able to do
    // so, if and when it is required. This is why the node is said to
    // be in "seed" state - it allows creating the entry in the tree
    // in the future.
    //
    // This is a significant difference from eg, the behavior of
    // std::map, which mutates the map immediately within the call to
    // operator[].
    //
    // All of the points above apply only if the tree is mutable. If
    // the tree is const, then a NodeRef cannot be obtained from it;
    // only a ConstNodeRef, which can never be used to mutate the
    // tree.
    //
    CHECK(!root.has_child("I am not nothing"));
    ryml::NodeRef nothing;
    CHECK(nothing.invalid());    // invalid because it points at nothing
    nothing = wroot["I am nothing"];
    CHECK(!nothing.invalid());   // points at the tree, and a specific place in the tree
    CHECK(nothing.is_seed()); // ... but nothing is there yet.
    CHECK(!root.has_child("I am nothing")); // same as above
    CHECK(!nothing.readable()); // ... and this node cannot be used to
                                // read anything from the tree
    ryml::NodeRef something = wroot["I am something"];
    ryml::ConstNodeRef constsomething = wroot["I am something"];
    CHECK(!root.has_child("I am something")); // same as above
    CHECK(!something.invalid());
    CHECK(something.is_seed()); // same as above
    CHECK(!something.readable()); // same as above
    CHECK(constsomething.invalid()); // NOTE: because a ConstNodeRef cannot be
                                     // used to mutate a tree, it is only valid()
                                     // if it is pointing at an existing node.
    something.set_val("indeed");  // this will commit the seed to the tree, mutating at the proper place
    CHECK(root.has_child("I am something"));
    CHECK(root["I am something"].val() == "indeed");
    CHECK(!something.invalid()); // it was already valid
    CHECK(!something.is_seed()); // now the tree has this node, so the
                                 // ref is no longer a seed
    CHECK(something.readable()); // and it is now readable
    //
    // now the constref is also valid (but it needs to be reassigned):
    ryml::ConstNodeRef constsomethingnew = wroot["I am something"];
    CHECK(!constsomethingnew.invalid());
    CHECK(constsomethingnew.readable());
    // note that the old constref is now stale, because it only keeps
    // the state at creation:
    CHECK(constsomething.invalid());
    CHECK(!constsomething.readable());
    //
    // -----------------------------------------------------------
    // Remember: a seed node cannot be used to read from the tree!
    // -----------------------------------------------------------
    //
    // The seed node needs to be created and become readable first.
    //
    // Trying to invoke any tree-reading method on a node that is not
    // readable will cause an assertion (see RYML_USE_ASSERT).
    //
    // It is your responsibility to verify that the preconditions are
    // met. If you are not sure about the structure of your data,
    // write your code defensively to signify your full intent:
    //
    ryml::NodeRef wbar = wroot["bar"];
    if(wbar.readable() && wbar.is_seq()) // .is_seq() requires .readable()
    {
        CHECK(wbar[0].readable() && wbar[0].val() == "20");
        CHECK( ! wbar[100].readable());
        CHECK( ! wbar[100].readable() || wbar[100].val() == "100"); // <- no crash because it is not .readable(), so never tries to call .val()
        // this would work as well:
        CHECK( ! wbar[0].is_seed() && wbar[0].val() == "20");
        CHECK(wbar[100].is_seed() || wbar[100].val() == "100");
    }


    //------------------------------------------------------------------
    // .operator[]() vs .at()

    // (Const)NodeRef::operator[] is an analogue to std::vector::operator[].
    // (Const)NodeRef::at() is an analogue to std::vector::at()
    //
    // at() will always check the subject node is .readable().
    //
    // [] is meant for the happy path: unverified in Release builds,
    // and asserts .readable() in Debug builds (more specifically when
    // RYML_USE_ASSERT is defined and NDEBUG is not defined).
    {
        // in this example we will be checking errors, so set up a
        // temporary error handler to catch them:
        ScopedErrorHandlerExample errh; // calls ryml::set_callbacks()
        // instantiate the tree after errh
        ryml::Tree err_tree = ryml::parse_in_arena("{foo: bar}");
        // ... so that the tree uses the current callbacks:
        CHECK(err_tree.callbacks() == errh.callbacks());
        // node does not exist, only a seed node
        ryml::NodeRef seed_node = err_tree["this"];
        // ... therefore not .readable()
        CHECK(!seed_node.readable());
        // using .at() reliably produces an error:
        CHECK(errh.check_error_occurs([&]{
            return seed_node.at("is").at("an").at("invalid").at("operation");
            //               ^
            //               error occurs here because it is unreadable
        }));
        // ... but using [] fails only when RYML_USE_ASSERT is
        // defined. otherwise, it's the dreaded Undefined Behavior:
        CHECK(errh.check_assertion_occurs([&]{
            return seed_node["is"]["an"]["invalid"]["operation"];
            //              ^
            //              assertion occurs here because it is unreadable
        }));
    }


    //------------------------------------------------------------------
    // Emitting:

    ryml::csubstr expected_result =
        "foo: says who"                                         "\n"
        "bar: [20,30,oh so nice,oh so nice (serialized)]"       "\n"
        "john: in_scope"                                        "\n"
        "float: 2.4"                                            "\n"
        "digits: 2.400000"                                      "\n"
        "newkeyval: shiny and new"                              "\n"
        "newkeyval (serialized): shiny and new (serialized)"    "\n"
        "newseq: []"                                            "\n"
        "newseq (serialized): []"                               "\n"
        "newmap: {}"                                            "\n"
        "newmap (serialized): {}"                               "\n"
        "I am something: indeed"                                "\n"
        "";

    // emit to a FILE*
    ryml::emit_yaml(tree, stdout);
    // emit to a stream
    // (this is templated on the stream, so it works both with
    // standard streams like std::ostream/std::stringstream, or with
    // user-defined streams not inheriting from ostream)
    std::stringstream ss;
    ss << tree;
    std::string stream_result = ss.str();
    // emit to a buffer:
    std::string str_result = ryml::emitrs_yaml<std::string>(tree);
    // can emit to any given buffer:
    char buf[1024];
    ryml::csubstr buf_result = ryml::emit_yaml(tree, buf);
    // now check
    CHECK(buf_result == expected_result);
    CHECK(str_result == expected_result);
    CHECK(stream_result == expected_result);
    // There are many possibilities to emit to buffer;
    // please look at the emit sample functions below.


    //------------------------------------------------------------------
    // ConstNodeRef vs NodeRef

    ryml::NodeRef noderef = tree["bar"][0];
    ryml::ConstNodeRef constnoderef = tree["bar"][0];

    // ConstNodeRef cannot be used to mutate the tree:
    //constnoderef.set_val("21");  // compile error: method does not exist
    //constnoderef.set_serialized("22"); // compile error
    // ... but a NodeRef can:
    noderef.set_val("21");         // ok, can assign because it's not const
    CHECK(tree["bar"][0].val() == "21");
    noderef.set_serialized("22");        // ok, can serialize and assign because it's not const
    CHECK(tree["bar"][0].val() == "22");

    // it is not possible to obtain a NodeRef from a ConstNodeRef:
    // noderef = constnoderef; // compile error

    // it is always possible to obtain a ConstNodeRef from a NodeRef:
    constnoderef = noderef;    // ok can assign const <- nonconst

    // If a tree is const, then only ConstNodeRef's can be
    // obtained from that tree:
    ryml::Tree const& consttree = tree;
    //noderef = consttree["bar"][0];    // compile error
    noderef = tree["bar"][0];           // ok
    constnoderef = consttree["bar"][0]; // ok

    // ConstNodeRef and NodeRef can be compared for equality.
    // Equality means they point at the same node.
    CHECK(constnoderef == noderef);
    CHECK(!(constnoderef != noderef));


    //------------------------------------------------------------------
    // Getting the location of nodes in the source:
    //
    // Location tracking is opt-in:
    ryml::EventHandlerTree evt_handler = {};
    ryml::Parser parser(&evt_handler, ryml::ParserOptions().locations(true));
    // Now the parser will start by building the accelerator structure:
    ryml::Tree tree2 = parse_in_arena(&parser, "expected.yml", expected_result);
    // ... and use it when querying
    ryml::ConstNodeRef subject_node = tree2["bar"][1];
    CHECK(subject_node.val() == "30");
    ryml::Location loc = subject_node.location(parser);
    CHECK(parser.location_contents(loc).begins_with("30"));
    CHECK(loc.line == 1u);
    CHECK(loc.col == 9u);
    // For further details in location tracking,
    // refer to the sample function below.


    //------------------------------------------------------------------
    // Dealing with UTF8
    ryml::Tree langs = ryml::parse_in_arena(""
        "#"                                                       "\n"
        "# UTF8/16/32 can be placed directly in any scalar:"      "\n"
        "#"                                                       "\n"
        "en: Planet (Gas)"                                        "\n"
        "fr: Planète (Gazeuse)"                                   "\n"
        "ru: Планета (Газ)"                                      "\n"
        "ja: 惑星（ガス）"                                        "\n"
        "zh: 行星（气体）"                                        "\n"
        "#"                                                       "\n"
        "# UTF8 decoding only happens in double-quoted strings,"  "\n"
        "# as per the YAML standard"                              "\n"
        "#"                                                       "\n"
        "decode this: \"\\u263A c\\x61f\\xE9\""                   "\n"
        "and this as well: \"\\u2705 \\U0001D11E\""               "\n"
        "not decoded: '\\u263A \\xE2\\x98\\xBA'"                  "\n"
        "neither this: '\\u2705 \\U0001D11E'"                     "\n");
    // in-place UTF8 just works:
    CHECK(langs["en"].val() == "Planet (Gas)");
    CHECK(langs["fr"].val() == "Planète (Gazeuse)");
    CHECK(langs["ru"].val() == "Планета (Газ)");
    CHECK(langs["ja"].val() == "惑星（ガス）");
    CHECK(langs["zh"].val() == "行星（气体）");
    // and \x \u \U codepoints are decoded, but only when they appear
    // inside double-quoted strings, as dictated by the YAML
    // standard:
    CHECK(langs["decode this"].val() == "☺ café");
    CHECK(langs["and this as well"].val() == "✅ 𝄞");
    CHECK(langs["not decoded"].val() == "\\u263A \\xE2\\x98\\xBA");
    CHECK(langs["neither this"].val() == "\\u2705 \\U0001D11E");
}