XB Library: xb::node

The XB node class represents nodes in XB trees. The XB node have a node type identifier, can have a name, a value, any number of additional base elements, any number of properties, any number of sub-nodes and optionally padding data.


Interface:

namespace xb {
    class node {
        public:
            typedef std::vector <xb::element>           baseplus_type;
            typedef std::list <xb::node>                subnodes_type;
            typedef std::map <xb::element, xb::element> props_type;

        public:
            xb::node_type   type;
            xb::element     ns;
            xb::element     name;
            xb::value       value;
            xb::element     offset;

            baseplus_type   base;
            props_type      props;
            subnodes_type   nodes;

            xb::element     padding;

        public:
            node (const xb::element & = xb::element (),
                  const xb::value & = xb::value ());

            node & operator = (const xb::value &);

            xb::node & operator [] (const xb::element &);
            const xb::node & operator [] (const xb::element &) const;

            xb::element & property (const xb::element &);
            const xb::element & property (const xb::element &) const;

        public:
            bool recode (const xb::codec &, const xb::codec &, int * = 0);
            bool encode (const xb::codec &, int * = 0);
            bool decode (const xb::codec &, int * = 0);

            xb::size_type binary_size () const;
            void serialize (xb::alias &) const;
            void parse (xb::const_alias &, xb::size_type * = 0);
    };

    bool operator == (const node &, const node &);
    bool operator != (const node &, const node &);
    bool operator <  (const node &, const node &);
    bool operator <= (const node &, const node &);
    bool operator >  (const node &, const node &);
    bool operator >= (const node &, const node &);
};

xb::node constructor

The xb::node is default-constructible thus can be constructed as empty, then assigned an another node or value.

The xb::node constructor can take one or two parameteres. First one is always node name (xb::element), the second one is the value of the node (xb::value).

xb::value assignment operator

You can assign a xb::value to a xb::node. This operator simply assigns the xb::value parameter to .value member of the node.

array-access operator

The array-access operators provide transparent interface to sub-nodes of the node. Both operators take a xb::element as a parameter. This specifies the name of a node that is searched for. The first found node of such name is returned. If no node of this name is found, a new node with that name is created, inserted into subnodes and reference to this new node is returned. The const version of this operator cannot modify the node so std::invalid_argument is thrown instead.

Note that array-access operator is provided solely for simplicity as .nodes member is public accessible from outside of the xb::node class. Also note that this operator works with first sub-node of the name only and the sub-node list is not a map.

xb::node::property

The .property () member function is used to access node properties. The behavior is very similar to xb::node array-access operator.

Note that .property () is provided solely for simplicity as .props member is public accessible from outside of the xb::node class.

xb::node::recode

Use this member function to change encoding of the value and all sub-nodes. The first parameter specifies a codec that is used to decode the data, the second parameter specifies a codec to encode the data with. If third parameter is not a null pointer, the value that it points to is provided with an error code (if there was an error). The function returns true if successfull, false otherwise.

The .encode () and .decode () member functions are implemented in terms of this member function as small inline functions.

xb::node::binary_size

The .binary_size () returns exact number of bytes that will the serialized node use.

xb::node::serialize

The .serialize () member function serializes the content of the node into target represented by an object of class that implements the xb::alias interface. Provide such object as a parameter to this member function.

Upon exiting, the alias points to first byte after the serialized node.

xb::node::parse

The .parse () member function parses as much data from the input (first parameter) as needed to construct a node tree. Note that, although complete tree is recreated if node contains one or more sub-nodes, only one node is parsed at the base level.

The first parameter must specify an object of class that implements the xb::const_alias interface. Upon returning the alias is updated to point to first byte after the node. If the second parameter is used (not null), the variable it points to is incremented of number of bytes parsed by this function.

Examples:

// ...

xb::node setup_node ("setup");

setup_node ["protocol"] = "tcp";
setup_node ["port"] = 23;
setup_node ["verbose"] = true;

setup_node ["aaaa"] = 123.0f;
setup_node [0x61616161] = 456.0f; // overwrites "aaaa" !!!

xb::size_type length = setup_node.binary_size ();
unsigned char * buffer = new unsigned char [length];
xb::buffer_alias output (buffer, length);

setup_node.serialize (output);

// ...

Remarks:

See xb::node_type for list of predefined values for .type member.

The .offset member is a unsigned number (whose default value is 0) used to specify a byte-wise position of current node inside parent node value. Read the .offset member into an unsigned integer using the xb::extend template function. Write unsigned integer values into the .offset member using the xb::compact template function.


[index]