Tree

Functions
void	sample_iterate_tree ()
	visit individual nodes and iterate through trees More...
void	sample_location_tracking ()
	track node YAML source locations in the parsed tree More...
void	sample_create_tree ()
	programatically create trees More...
void	sample_create_tree_style ()
	set node styles while creating trees More...
void	sample_tree_arena ()
	interact with the tree's serialization arena More...

Detailed Description

Function Documentation

void sample_iterate_tree

(

)

visit individual nodes and iterate through trees

shows how to programatically iterate through trees

See also

Tree utilities

Node classes

Definition at line 2398 of file quickstart.cpp.

Referenced by main().

{
    const ryml::Tree tree = ryml::parse_in_arena(
        "doe: a deer, a female deer"      "\n"
        "ray: a drop of golden sun"       "\n"
        "pi: 3.14159"                     "\n"
        "xmas: true"                      "\n"
        "french-hens: 3"                  "\n"
        "calling-birds:"                  "\n"
        "   - huey"                       "\n"
        "   - dewey"                      "\n"
        "   - louie"                      "\n"
        "   - fred"                       "\n"
        "xmas-fifth-day:"                 "\n"
        "  calling-birds: four"           "\n"
        "  french-hens: 3"                "\n"
        "  golden-rings: 5"               "\n"
        "  partridges:"                   "\n"
        "    count: 1"                    "\n"
        "    location: a pear tree"       "\n"
        "  turtle-doves: two"             "\n"
        "cars: GTO"                       "\n"
        "");
    ryml::ConstNodeRef root = tree.crootref();

    // iterate children
    {
        std::vector<ryml::csubstr> keys, vals; // to store all the root-level keys, vals
        for(ryml::ConstNodeRef n : root.children())
        {
            keys.emplace_back(n.key());
            vals.emplace_back(n.has_val() ? n.val() : ryml::csubstr{});
        }
        CHECK(keys.size() >= 6);
        CHECK(vals.size() >= 6);
        if(keys.size() >= 6 && vals.size() >= 6)
        {
            CHECK(keys[0] == "doe");
            CHECK(vals[0] == "a deer, a female deer");
            CHECK(keys[1] == "ray");
            CHECK(vals[1] == "a drop of golden sun");
            CHECK(keys[2] == "pi");
            CHECK(vals[2] == "3.14159");
            CHECK(keys[3] == "xmas");
            CHECK(vals[3] == "true");
            CHECK(root[5].has_key());
            CHECK(root[5].is_seq());
            CHECK(root[5].key() == "calling-birds");
            CHECK(!root[5].has_val()); // it is a map, so not a val
            //CHECK(root[5].val() == ""); // ERROR! node does not have a val.
            CHECK(keys[5] == "calling-birds");
            CHECK(vals[5] == "");
        }
    }

    // iterate siblings
    {
        size_t count = 0;
        ryml::csubstr calling_birds[] = {"huey", "dewey", "louie", "fred"};
        for(ryml::ConstNodeRef n : root["calling-birds"][2].siblings())
            CHECK(n.val() == calling_birds[count++]);
        CHECK(count == 4u);
    }
}

void sample_location_tracking

(

)

track node YAML source locations in the parsed tree

demonstrates how to obtain the (zero-based) location of a node from a recently parsed tree

See also

RYML_LOCATIONS_SMALL_THRESHOLD

Definition at line 2471 of file quickstart.cpp.

Referenced by main().

{
    // NOTE: locations are zero-based. If you intend to show the
    // location to a human user, you may want to pre-increment the line
    // and column by 1.
    ryml::csubstr yaml = ""
        "{"                          "\n"
        "aa: contents,"              "\n"
        "foo: [one, [two, three]]"   "\n"
        "}"                          "\n"
        "";
    // A parser is needed to track locations, and it has to be
    // explicitly set to do it. Location tracking is disabled by
    // default.
    ryml::ParserOptions opts = {};
    opts.locations(true); // enable locations, default is false
    ryml::EventHandlerTree evt_handler = {};
    ryml::Parser parser(&evt_handler, opts);
    CHECK(parser.options().locations());
    // When locations are enabled, the first task while parsing will
    // consist of building and caching (in the parser) a
    // source-to-node lookup structure to accelerate location lookups.
    //
    // The cost of building the location accelerator is linear in the
    // size of the source buffer. This increased cost is the reason
    // for the opt-in requirement. When locations are disabled there
    // is no cost.
    //
    // Building the location accelerator may trigger an allocation,
    // but this can and should be avoided by reserving prior to
    // parsing:
    parser.reserve_locations(50u); // reserve for 50 lines of YAML code
    // Now the structure will be built during parsing:
    ryml::Tree tree = parse_in_arena(&parser, "source.yml", yaml);
    // After this, we are ready to query the location from the parser:
    ryml::Location loc = tree.rootref().location(parser);
    // As for the complexity of the query: for large buffers it is
    // O(log(numlines)). For short source buffers
    // (RYML_LOCATIONS_SMALL_THRESHOLD lines and less), it is
    // O(numlines), as a plain linear search is faster in this case.
    CHECK(parser.location_contents(loc).begins_with("{"));
    CHECK(loc.offset == 0u);
    CHECK(loc.line == 0u);
    CHECK(loc.col == 0u);
    // on the next call, we only pay O(log(numlines)) because the
    // rebuild is already available:
    loc = tree["aa"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("aa"));
    CHECK(loc.offset == 2u);
    CHECK(loc.line == 1u);
    CHECK(loc.col == 0u);
    // KEYSEQ in flow style: points at the key
    loc = tree["foo"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("foo"));
    CHECK(loc.offset == 16u);
    CHECK(loc.line == 2u);
    CHECK(loc.col == 0u);
    loc = tree["foo"][0].location(parser);
    CHECK(parser.location_contents(loc).begins_with("one"));
    CHECK(loc.line == 2u);
    CHECK(loc.col == 6u);
    // SEQ in flow style: location points at the opening '[' (there's no key)
    loc = tree["foo"][1].location(parser);
    CHECK(parser.location_contents(loc).begins_with("["));
    CHECK(loc.line == 2u);
    CHECK(loc.col == 11u);
    loc = tree["foo"][1][0].location(parser);
    CHECK(parser.location_contents(loc).begins_with("two"));
    CHECK(loc.line == 2u);
    CHECK(loc.col == 12u);
    loc = tree["foo"][1][1].location(parser);
    CHECK(parser.location_contents(loc).begins_with("three"));
    CHECK(loc.line == 2u);
    CHECK(loc.col == 17u);
    // NOTE. The parser locations always point at the latest buffer to
    // be parsed with the parser object, so they must be queried using
    // the corresponding latest tree to be parsed. This means that if
    // the parser is reused, earlier trees will loose the possibility
    // of querying for location. It is undefined behavior to query the
    // parser for the location of a node from an earlier tree:
    ryml::Tree docval = parse_in_arena(&parser, "docval.yaml", "this is a docval");
    // From now on, none of the locations from the previous tree can
    // be queried:
    //loc = tree.rootref().location(parser); // ERROR, undefined behavior
    loc = docval.rootref().location(parser); // OK. this is the latest tree from this parser
    CHECK(parser.location_contents(loc).begins_with("this is a docval"));
    CHECK(loc.line == 0u);
    CHECK(loc.col == 0u);

    // NOTES ABOUT CONTAINER LOCATIONS
    ryml::Tree tree2 = parse_in_arena(&parser, "containers.yaml",
        ""                            "\n"
        "a new: buffer"               "\n"
        "to: be parsed"               "\n"
        "map with key:"               "\n"
        "  first: value"              "\n"
        "  second: value"             "\n"
        "seq with key:"               "\n"
        "  - first value"             "\n"
        "  - second value"            "\n"
        "  -"                         "\n"
        "    - nested first value"    "\n"
        "    - nested second value"   "\n"
        "  -"                         "\n"
        "    nested first: value"     "\n"
        "    nested second: value"    "\n"
        "");
    // (Likewise, the docval tree can no longer be used to query.)
    //
    // For key-less block-style maps, the location of the container
    // points at the first child's key. For example, in this case
    // the root does not have a key, so its location is taken
    // to be at the first child:
    loc = tree2.rootref().location(parser);
    CHECK(parser.location_contents(loc).begins_with("a new"));
    CHECK(loc.offset == 1u);
    CHECK(loc.line == 1u);
    CHECK(loc.col == 0u);
    // note the first child points exactly at the same place:
    loc = tree2["a new"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("a new"));
    CHECK(loc.offset == 1u);
    CHECK(loc.line == 1u);
    CHECK(loc.col == 0u);
    loc = tree2["to"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("to"));
    CHECK(loc.line == 2u);
    CHECK(loc.col == 0u);
    // but of course, if the block-style map is a KEYMAP, then the
    // location is the map's key, and not the first child's key:
    loc = tree2["map with key"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("map with key"));
    CHECK(loc.line == 3u);
    CHECK(loc.col == 0u);
    loc = tree2["map with key"]["first"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("first"));
    CHECK(loc.line == 4u);
    CHECK(loc.col == 2u);
    loc = tree2["map with key"]["second"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("second"));
    CHECK(loc.line == 5u);
    CHECK(loc.col == 2u);
    // same thing for KEYSEQ:
    loc = tree2["seq with key"].location(parser);
    CHECK(parser.location_contents(loc).begins_with("seq with key"));
    CHECK(loc.line == 6u);
    CHECK(loc.col == 0u);
    loc = tree2["seq with key"][0].location(parser);
    CHECK(parser.location_contents(loc).begins_with("first value"));
    CHECK(loc.line == 7u);
    CHECK(loc.col == 4u);
    loc = tree2["seq with key"][1].location(parser);
    CHECK(parser.location_contents(loc).begins_with("second value"));
    CHECK(loc.line == 8u);
    CHECK(loc.col == 4u);
    // SEQ nested in SEQ: container location points at the first child's "- " dash
    loc = tree2["seq with key"][2].location(parser);
    CHECK(parser.location_contents(loc).begins_with("- nested first value"));
    CHECK(loc.line == 10u);
    CHECK(loc.col == 4u);
    loc = tree2["seq with key"][2][0].location(parser);
    CHECK(parser.location_contents(loc).begins_with("nested first value"));
    CHECK(loc.line == 10u);
    CHECK(loc.col == 6u);
    // MAP nested in SEQ: same as above: point to key
    loc = tree2["seq with key"][3].location(parser);
    CHECK(parser.location_contents(loc).begins_with("nested first: "));
    CHECK(loc.line == 13u);
    CHECK(loc.col == 4u);
    loc = tree2["seq with key"][3][0].location(parser);
    CHECK(parser.location_contents(loc).begins_with("nested first: "));
    CHECK(loc.line == 13u);
    CHECK(loc.col == 4u);
}

void sample_create_tree

(

)

programatically create trees

shows how to programatically create trees

See also

Tree utilities

Node classes

sample_create_tree_style()

Definition at line 2654 of file quickstart.cpp.

Referenced by main().

{
    ryml::NodeRef doe;
    CHECK(doe.invalid()); // it's pointing at nowhere

    ryml::Tree tree;
    ryml::NodeRef root = tree.rootref();
    root.set_map(); // mark root as a map
    doe = root["doe"];
    CHECK(!doe.invalid()); // it's now pointing at the tree
    CHECK(doe.is_seed()); // but the tree has nothing there, so this is only a seed

    // set the value of the node
    const char a_deer[] = "a deer, a female deer";
    doe.set_val(a_deer);
    // now the node really exists in the tree, and this ref is no
    // longer a seed:
    CHECK(!doe.is_seed());
    // WATCHOUT for lifetimes:
    CHECK(doe.val().str == a_deer); // it is pointing at the initial string
    // If you need to avoid lifetime dependency, serialize the data:
    {
        std::string a_drop = "a drop of golden sun";
        // this will copy the string to the tree's arena:
        // (see the serialization samples below)
        root["ray"].set_serialized(a_drop);
        // and now you can modify the original string without changing
        // the tree:
        a_drop[0] = 'Z';
        a_drop[1] = 'Z';
    }
    CHECK(root["ray"].val() == "a drop of golden sun");

    // etc.
    root["pi"].set_serialized(ryml::fmt::real(3.141592654, 5));
    root["xmas"].set_serialized(ryml::fmt::boolalpha(true));
    root["french-hens"].set_serialized(3);
    ryml::NodeRef calling_birds = root["calling-birds"];
    calling_birds.set_seq();
    calling_birds.append_child().set_val("huey");
    calling_birds.append_child().set_val("dewey");
    calling_birds.append_child().set_val("louie");
    calling_birds.append_child().set_val("fred");
    ryml::NodeRef xmas5 = root["xmas-fifth-day"];
    xmas5.set_map();
    xmas5["calling-birds"].set_val("four");
    xmas5["french-hens"].set_serialized(3);
    xmas5["golden-rings"].set_serialized(5);
    xmas5["partridges"].set_map();
    xmas5["partridges"]["count"].set_serialized(1);
    xmas5["partridges"]["location"].set_val("a pear tree");
    xmas5["turtle-doves"].set_val("two");
    root["cars"].set_val("GTO");

    CHECK(ryml::emitrs_yaml<std::string>(tree) == ""
          "doe: a deer, a female deer"       "\n"
          "ray: a drop of golden sun"        "\n"
          "pi: 3.14159"                      "\n"
          "xmas: true"                       "\n"
          "french-hens: 3"                   "\n"
          "calling-birds:"                   "\n"
          "  - huey"                         "\n"
          "  - dewey"                        "\n"
          "  - louie"                        "\n"
          "  - fred"                         "\n"
          "xmas-fifth-day:"                  "\n"
          "  calling-birds: four"            "\n"
          "  french-hens: 3"                 "\n"
          "  golden-rings: 5"                "\n"
          "  partridges:"                    "\n"
          "    count: 1"                     "\n"
          "    location: a pear tree"        "\n"
          "  turtle-doves: two"              "\n"
          "cars: GTO"                        "\n"
          "");

    // NOTE: it is good practice to set scalar styles when building
    // the tree. See the sample_create_tree_style() below.
}

void sample_create_tree_style

(

)

set node styles while creating trees

Shows how to set styles when building a tree: this may be needed because you want to control the emitted YAML, but for scalars there is also a performance reason to do this.

Note

You can and should set the style when creating a tree for emitting later. This is because YAML has constraints on which styles can be used for a particular scalar (eg, a plain scalar have leading or trailing whitespace, or if in flow mode it cannot have comma followed by space).

When the scalar is not marked with an explicit style, the ryml emitter adheres to these constraints by scanning each scalar to choose a style for it. On the other hand, if the scalar is marked with an explicit style, the emitter will honor that style, and not do the scan.

So explicitly setting the style for scalars saves the emitter from having to scan each scalar while emitting.

For containers, setting the style does not offer an emit performance improvement like with scalars. Nevertheless, you may still find it useful to control the emitted YAML.

Following this recommendation, ryml also explicitly sets the styles while parsing.

Definition at line 2764 of file quickstart.cpp.

Referenced by main().

{
    ryml::Tree tree;
    ryml::NodeRef root = tree;
    root.set_map(ryml::BLOCK);
    // with .set_*() we should use explicit styles (because .set_*()
    // only takes csubstr arguments)
    root["not plain"].set_val("  with whitespace  "); // no style set
    root["doe"].set_val("a deer, a female deer", ryml::VAL_PLAIN);
    root["ray"].set_val("a drop of golden sun", ryml::VAL_SQUO);
    root["me"].set_val("a name I call myself", ryml::VAL_DQUO);
    root["far"].set_val("a long long way to go", ryml::VAL_LITERAL);
    root["sow"].set_val("a needle pulling thread", ryml::VAL_FOLDED);
    root["seq"].set_seq(ryml::FLOW_SL|ryml::FLOW_SPC); // flow, single-line, with spaces after commas
    root["map1"].set_map(ryml::FLOW_ML1); // flow, multiline, 1 value per line
    root["mapn"].set_map(ryml::FLOW_MLN); // flow, multiline, N values per line, wrapped
    // likewise for all of set_serialized(), set_key(),
    // set_key_serialized(), save(), save_key(): all these accept the
    // style as an extra argument. But when serializing there's a
    // nice feature: ryml will automatically set the scalar style to
    // VAL_PLAIN / KEY_PLAIN when its type verifies std::is_arithmetic<T>.
    for(int i : {0, 1, 2, 3})
    {
        ryml::NodeRef childseq = root["seq"].append_child();
        ryml::NodeRef childmap1 = root["map1"].append_child();
        ryml::NodeRef childmapn = root["mapn"].append_child();
        // Note how we're NOT setting the style:
        childseq.set_serialized(i);
        childmap1.set_key_serialized(i + 1);
        childmapn.set_key_serialized(i + 1);
        childmap1.set_serialized((i + 1) * 10);
        childmapn.set_serialized((i + 1) * 10);
        // ... and yet ryml has set it to plain:
        CHECK(childseq.is_val_plain());
        CHECK(childmap1.is_key_plain());
        CHECK(childmapn.is_key_plain());
        CHECK(childmap1.is_val_plain());
        CHECK(childmapn.is_val_plain());
    }
    // let's see the styles now:
    CHECK(ryml::emitrs_yaml<std::string>(tree) ==
          // note how this is quoted, without having explicit style
          // set. That is because plain scalars cannot have
          // leading/trailing whitespace characters. This scalar did
          // not have a style set, so during emitting it was scanned
          // to determine its style, and so VAL_SQUO was chosen:
          "not plain: '  with whitespace  '"  "\n"
          // as for the rest, the style is honored, and the scalars
          // are not scanned by the emitter, resulting in a
          // performance increase:
          "doe: a deer, a female deer"        "\n"
          "ray: 'a drop of golden sun'"       "\n"
          "me: \"a name I call myself\""      "\n"
          "far: |-"                           "\n"
          "  a long long way to go"           "\n"
          "sow: >-"                           "\n"
          "  a needle pulling thread"         "\n"
          "seq: [0, 1, 2, 3]"                 "\n"
          "map1: {"                           "\n"
          "    1: 10,"                        "\n"
          "    2: 20,"                        "\n"
          "    3: 30,"                        "\n"
          "    4: 40"                         "\n"
          "  }"                               "\n"
          "mapn: {"                           "\n"
          "    1: 10,2: 20,3: 30,4: 40"       "\n"
          "  }"                               "\n"
          "");
    // Note that it would be an error to set a scalar style
    // incompatible with the scalar contents. ryml always honor the
    // node style, so it will blindly emit roundtrip-unstable YAML if
    // the style is incompatible.
    //
    // For example, this is incorrect because a plain scalar cannot
    // have leading or trailing whitespace:
    root["plain"].set_val("  with whitespace  ", ryml::VAL_PLAIN); // incorrect.
    // note how the whitespace will be lost when parsed:
    CHECK(ryml::emitrs_yaml<std::string>(root["plain"]) ==
          "plain:   with whitespace  "         "\n"
          "");
}

void sample_tree_arena

(

)

interact with the tree's serialization arena

demonstrates explicit and implicit interaction with the tree's string arena.

Note that ryml only holds strings in the tree's nodes.

Definition at line 2852 of file quickstart.cpp.

Referenced by main().

{
    // mutable buffers are parsed in place:
    {
        char buf[] = "[a, b, c, d]";
        ryml::substr yml = buf;
        ryml::Tree tree = ryml::parse_in_place(yml);
        // notice the arena is empty:
        CHECK(tree.arena().empty());
        // and the tree is pointing at the original buffer:
        ryml::NodeRef root = tree.rootref();
        CHECK(root[0].val().is_sub(yml));
        CHECK(root[1].val().is_sub(yml));
        CHECK(root[2].val().is_sub(yml));
        CHECK(root[3].val().is_sub(yml));
        CHECK(yml.is_super(root[0].val()));
        CHECK(yml.is_super(root[1].val()));
        CHECK(yml.is_super(root[2].val()));
        CHECK(yml.is_super(root[3].val()));
    }

    // when parsing immutable buffers, the buffer is first copied to the
    // tree's arena; the copy in the arena is then the buffer which is
    // actually parsed
    {
        ryml::csubstr yml = "[a, b, c, d]";
        ryml::Tree tree = ryml::parse_in_arena(yml);
        // notice the buffer was copied to the arena:
        CHECK(tree.arena().data() != yml.data());
        CHECK(tree.arena() == yml);
        // and the tree is pointing at the arena instead of to the
        // original buffer:
        ryml::NodeRef root = tree.rootref();
        ryml::csubstr arena = tree.arena();
        CHECK(root[0].val().is_sub(arena));
        CHECK(root[1].val().is_sub(arena));
        CHECK(root[2].val().is_sub(arena));
        CHECK(root[3].val().is_sub(arena));
        CHECK(arena.is_super(root[0].val()));
        CHECK(arena.is_super(root[1].val()));
        CHECK(arena.is_super(root[2].val()));
        CHECK(arena.is_super(root[3].val()));
    }

    // the arena is also used when the data is serialized to the tree.
    // first example: parse in place
    {
        char buf[] = "[a, b, c, d]"; // mutable
        ryml::substr yml = buf;
        ryml::Tree tree = ryml::parse_in_place(yml);
        // notice the arena is empty:
        CHECK(tree.arena().empty());
        ryml::NodeRef root = tree.rootref();

        // serialize an integer, and mutate the tree
        CHECK(root[2].val() == "c");
        CHECK(root[2].val().is_sub(yml)); // val is first pointing at the buffer
        root[2].set_serialized(12345);
        CHECK(root[2].val() == "12345");
        CHECK(root[2].val().is_sub(tree.arena())); // now val is pointing at the arena
        // notice the serialized string was appended to the tree's arena:
        CHECK(tree.arena() == "12345");

        // serialize an integer, and mutate the tree
        CHECK(root[3].val() == "d");
        CHECK(root[3].val().is_sub(yml)); // val is first pointing at the buffer
        root[3].set_serialized(67890);
        CHECK(root[3].val() == "67890");
        CHECK(root[3].val().is_sub(tree.arena())); // now val is pointing at the arena
        // notice the serialized string was appended to the tree's arena:
        CHECK(tree.arena() == "1234567890");
    }
    // the arena is also used when the data is serialized to string
    // second example: parse in arena
    {
        ryml::csubstr yml = "[a, b, c, d]"; // immutable
        ryml::Tree tree = ryml::parse_in_arena(yml);
        // notice the buffer was copied to the arena:
        CHECK(tree.arena().data() != yml.data());
        CHECK(tree.arena() == yml);
        ryml::NodeRef root = tree.rootref();

        // serialize an integer, and mutate the tree
        CHECK(root[2].val() == "c");
        root[2].set_serialized(12345); // serialize an integer
        CHECK(root[2].val() == "12345");
        // notice the serialized string was appended to the tree's arena:
        // notice also the previous values remain there.
        // RYML DOES NOT KEEP TRACK OF REFERENCES TO THE ARENA.
        CHECK(tree.arena() == "[a, b, c, d]12345");
        // old values:  --------------^

        // serialize an integer, and mutate the tree
        root[3].set_serialized(67890);
        CHECK(root[3].val() == "67890");
        // notice the serialized string was appended to the tree's arena:
        // notice also the previous values remain there.
        // RYML DOES NOT KEEP TRACK OF REFERENCES TO THE ARENA.
        CHECK(tree.arena() == "[a, b, c, d]1234567890");
        // old values:  --------------^ ---^^^^^
    }

    // to_arena(): directly serialize values to the arena:
    {
        ryml::Tree tree = ryml::parse_in_arena("{a: b}");
        ryml::csubstr c10 = tree.to_arena(10101010);
        CHECK(c10 == "10101010");
        CHECK(c10.is_sub(tree.arena()));
        CHECK(tree.arena() == "{a: b}10101010");
        CHECK(tree.key(1) == "a");
        CHECK(tree.val(1) == "b");
        tree.set_val(1, c10);
        CHECK(tree.val(1) == c10);
        // and you can also do it through a node:
        ryml::NodeRef root = tree.rootref();
        root["a"].set_serialized(2222);
        CHECK(root["a"].val() == "2222");
        CHECK(tree.arena() == "{a: b}101010102222");
    }

    // copy_to_arena(): manually copy a string to the arena:
    {
        ryml::Tree tree = ryml::parse_in_arena("{a: b}");
        ryml::csubstr mystr = "Gosset Grande Reserve";
        ryml::csubstr copied = tree.copy_to_arena(mystr);
        CHECK(!copied.overlaps(mystr));
        CHECK(copied == mystr);
        CHECK(tree.arena() == "{a: b}Gosset Grande Reserve");
    }

    // alloc_arena(): allocate a buffer from the arena:
    {
        ryml::Tree tree = ryml::parse_in_arena("{a: b}");
        ryml::csubstr mystr = "Gosset Grande Reserve";
        ryml::substr copied = tree.alloc_arena(mystr.size());
        CHECK(!copied.overlaps(mystr));
        memcpy(copied.str, mystr.str, mystr.len);
        CHECK(copied == mystr);
        CHECK(tree.arena() == "{a: b}Gosset Grande Reserve");
    }

    // reserve_arena(): ensure the arena has a certain size to avoid reallocations
    {
        ryml::Tree tree = ryml::parse_in_arena("{a: b}");
        CHECK(tree.arena().size() == strlen("{a: b}"));
        tree.reserve_arena(100);
        CHECK(tree.arena_capacity() >= 100);
        CHECK(tree.arena().size() == strlen("{a: b}"));
        tree.to_arena(123456);
        CHECK(tree.arena().first(12) == "{a: b}123456");
    }
}