JSON Document Tree¶
Document tree¶
-
class
document_tree
¶ This class stores a parsed JSON document tree structure.
Public Functions
-
document_tree
()¶
-
document_tree
(const document_tree&)¶
-
document_tree
(document_tree &&other)¶
-
document_tree
(string_pool &pool)¶
-
~document_tree
()¶
-
document_tree &
operator=
(std::initializer_list<detail::init::node> vs)¶
-
document_tree &
operator=
(array vs)¶
-
document_tree &
operator=
(object obj)¶
-
void
load
(const std::string &strm, const json_config &config)¶ Load raw string stream containing a JSON structure to populate the document tree.
- Parameters
strm
: stream containing a JSON structure.config
: configuration object.
-
void
load
(const char *p, size_t n, const json_config &config)¶ Load raw string stream containing a JSON structure to populate the document tree.
- Parameters
p
: pointer to the stream containing a JSON structure.n
: size of the stream.config
: configuration object.
-
json::const_node
get_document_root
() const¶ Get the root node of the document.
- Return
- root node of the document.
-
json::node
get_document_root
()¶ Get the root node of the document.
- Return
- root node of the document.
-
std::string
dump
() const¶ Dump the JSON document tree to string.
- Return
- a string representation of the JSON document tree.
-
std::string
dump_xml
() const¶ Dump the JSON document tree to an XML structure.
- Return
- a string containing an XML structure representing the JSON content.
-
void
swap
(document_tree &other)¶ Swap the content of the document with another document instance.
- Parameters
other
: document instance to swap the content with.
-
-
struct
json_config
¶ Public Types
Public Members
-
std::string
input_path
¶ Path of the JSON file being parsed, in case the JSON string originates from a file. This parameter is required if external JSON files need to be resolved. Otherwise it’s optional.
-
std::string
output_path
¶ Path of the file to which output is written to. Used only from the orcus-json command line tool.
-
output_format_type
output_format
¶ Output format type. Used only from the orcus-json command line tool.
-
bool
preserve_object_order
¶ Control whether or not to preserve the order of object’s child name/value pairs. By definition, JSON’s object is an unordered set of name/value pairs, but in some cases preserving the original order may be desirable.
-
bool
resolve_references
¶ Control whether or not to resolve JSON references to external files.
-
bool
persistent_string_values
¶ When true, the document tree should allocate memory and hold copies of string values in the tree. When false, no extra memory is allocated for string values in the tree and the string values simply point to the original json string stream.
In other words, when this option is set to false, the caller must ensure that the json string stream instance stays alive for the entire life cycle of the document tree.
-
std::string
-
class
const_node
¶ Each node instance represents a JSON value stored in the document tree. It’s immutable.
Subclassed by orcus::json::node
Public Functions
-
const_node
()¶
-
const_node
(const const_node &other)¶
-
const_node
(const_node &&rhs)¶
-
~const_node
()¶
-
size_t
child_count
() const¶ Get the number of child nodes if any.
- Return
- number of child nodes.
-
std::vector<pstring>
keys
() const¶ Get a list of keys stored in a JSON object node.
- Return
- a list of keys.
- Exceptions
orcus::json::document_error
: if the node is not of the object type.
-
pstring
key
(size_t index) const¶ Get the key by index in a JSON object node. This method works only when the preserve object order option is set.
- Return
- key value.
- Parameters
index
: 0-based key index.
- Exceptions
orcus::json::document_error
: if the node is not of the object type.std::out_of_range
: if the index is equal to or greater than the number of keys stored in the node.
-
const_node
child
(size_t index) const¶ Get a child node by index.
- Return
- child node instance.
- Parameters
index
: 0-based index of a child node.
- Exceptions
orcus::json::document_error
: if the node is not one of the object or array types.std::out_of_range
: if the index is equal to or greater than the number of child nodes that the node has.
-
const_node
child
(const pstring &key) const¶ Get a child node by textural key value.
- Return
- child node instance.
- Parameters
key
: textural key value to get a child node by.
- Exceptions
orcus::json::document_error
: if the node is not of the object type, or the node doesn’t have the specified key.
-
const_node
parent
() const¶ Get the parent node.
- Return
- parent node instance.
- Exceptions
orcus::json::document_error
: if the node doesn’t have a parent node which implies that the node is a root node.
-
pstring
string_value
() const¶ Get the string value of a JSON string node.
- Return
- string value.
- Exceptions
orcus::json::document_error
: if the node is not of the string type.
-
double
numeric_value
() const¶ Get the numeric value of a JSON number node.
- Return
- numeric value.
- Exceptions
orcus::json::document_error
: if the node is not of the number type.
-
const_node &
operator=
(const const_node &other)¶
-
uintptr_t
identity
() const¶ Return an indentifier of the JSON value object that the node represents. The identifier is derived directly from the memory address of the value object.
- Return
- identifier of the JSON value object.
-
-
class
node
: public orcus::json::const_node¶ Each node instance represents a JSON value stored in the document tree. This class allows mutable operations.
Public Functions
-
node
()¶
-
~node
()¶
-
node
child
(size_t index)¶ Get a child node by index.
- Return
- child node instance.
- Parameters
index
: 0-based index of a child node.
- Exceptions
orcus::json::document_error
: if the node is not one of the object or array types.std::out_of_range
: if the index is equal to or greater than the number of child nodes that the node has.
-
node
child
(const pstring &key)¶ Get a child node by textural key value.
- Return
- child node instance.
- Parameters
key
: textural key value to get a child node by.
- Exceptions
orcus::json::document_error
: if the node is not of the object type, or the node doesn’t have the specified key.
-
node
parent
()¶ Get the parent node.
- Return
- parent node instance.
- Exceptions
orcus::json::document_error
: if the node doesn’t have a parent node which implies that the node is a root node.
-
void
push_back
(const detail::init::node &v)¶ Append a new node value to the end of the array.
- Exceptions
orcus::json::document_error
: if the node is not of array type.
- Parameters
v
: new node value to append to the end of the array.
-
-
class
array
¶ This class represents a JSON array, to be used to explicitly create an array instance during initialization.
Friends
-
friend
orcus::json::array::detail::init::node
-
friend
-
class
object
¶ This class represents a JSON object, primarily to be used to create an empty object instance.
-
class
node
¶ Node to store an initial value during document tree initialization. It’s not meant to be instantiated explicitly. A value passed from the braced initialization list is implicitly converted to an instance of this class.
Public Functions
-
node
(double v)¶
-
node
(int v)¶
-
node
(bool b)¶
-
node
(std::nullptr_t)¶
-
node
(const char *p)¶
-
~node
()¶
Friends
-
friend
orcus::json::detail::init::node::::orcus::json::document_tree
-
friend
orcus::json::detail::init::node::::orcus::json::node
-
-
enum
orcus::json::
node_t
¶ Values:
-
unset
= 0¶ node type is not set.
-
string
= 1¶ JSON string node. A node of this type contains a string value.
-
number
= 2¶ JSON number node. A node of this type contains a numeric value.
-
object
= 3¶ JSON object node. A node of this type contains one or more key-value pairs.
-
array
= 4¶ JSON array node. A node of this type contains one or more child nodes.
-
boolean_true
= 5¶ JSON boolean node containing a value of ‘true’.
-
boolean_false
= 6¶ JSON boolean node containing a value of ‘false’.
-
null
= 7¶ JSON node containing a ‘null’ value.
-
Exceptions¶
-
class
document_error
: public orcus::general_error¶ Exception related to JSON document tree construction.
Subclassed by orcus::json::key_value_error
-
class
key_value_error
: public orcus::json::document_error¶ Exception that gets thrown due to ambiguity when you specify a braced list that can be interpreted either as a key-value pair inside an object or as values of an array.