XB Library: xb::document

The XB document class is first-level element of XB node trees. It is similar to XB node but does not have a name, value or properties.

Interface:


            namespace xb {

                class document {

                    public:

                        xb::node::props_type    header;

                        xb::node::subnodes_type nodes;

            

                    public:

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

                        const xb::node & operator [] (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::node construct_header () const;

                        bool parse_header_node (const xb::node &);

            

                        xb::size_type binary_size () const;

                        void serialize (xb::alias &,
            const xb::codec & = xb::null_codec);

                        void serialize (xb::alias &,
            const xb::codec & = xb::null_codec) const;

                        void parse (xb::const_alias &,
            const xb::codec & = xb::null_codec);

                };

            };

xb::document::header

The .header map contain names and values of properties of the header node. Currently following properties are defined by specification:

"version" - value consists of single byte with major XB format version number in its upper 4 bits and minor version number in lower 4 bits.
"codec" - value describes the codec used to encode the rest of the document
"branch" - describes name of deviation from base XB format specification

xb::document::recode
xb::document::encode
xb::document::decode
xb::document::binary_size

This member functions works the same as they xb::node counterparts. See xb::node for details.

xb::document::serialize

The .serialize () member function serializes the document into target represented by an object of class that implements the xb::alias interface. Provide such object as first parameter to this member function. Upon exiting, the alias points to first byte after the serialized node.

The second parameter is a codec that is used to encode whole document. If const version of the member function is called, this codec's .id () member function must return the same element as set to the .codec member variable of the document. Otherwise the std::runtime_error exception is thrown. If the non-const version of this member function is called, the .codec member variable is assigned the codec's .id () value and then serialized using that codec.

xb::document::parse

The .parse () member function parses as much data from the source (first parameter) as needed to construct a node tree. The source is an object of class that implements the xb::const_alias interface. This function parses the entire source for as many nodes as it can read.

Second parameter to this member function may specify a codec. If the serialized document is not encodec, the codec is ignored. If the document's encoding match the codec, it is used to decode the data, otherwise the std::runtime_error is thrown. The std::runtime_error is also thrown when the codec fails to decode the document.

xb::document::construct_header

The .construct_header () member function returns assembled XB header node describing the document. This node is automaticaly added to the beginning of the document when serializing.

xb::document::parse_header_node

The .parse_header_node () member function parses the provided node, determines if it is a header node, and if true it loads its content into document description (.header map). Note that this member function is merely for internal use. The return value is true if the node is a header node.

Examples:

See xb::node for serialization example. The xb::document can be serialized in the same way.

Remarks:

None.

[index]