namespace orcus::json

Enum

node_t

enum class orcus::json::node_t : uint8_t

Values:

enumerator unset

node type is not set.

enumerator string

JSON string node. A node of this type contains a string value.

enumerator number

JSON number node. A node of this type contains a numeric value.

enumerator object

JSON object node. A node of this type contains one or more key-value pairs.

enumerator array

JSON array node. A node of this type contains one or more child nodes.

enumerator boolean_true

JSON boolean node containing a value of ‘true’.

enumerator boolean_false

JSON boolean node containing a value of ‘false’.

enumerator null

JSON node containing a ‘null’ value.

parse_token_t

enum class orcus::json::parse_token_t

Values:

enumerator unknown
enumerator begin_parse
enumerator end_parse
enumerator begin_array
enumerator end_array
enumerator begin_object
enumerator object_key
enumerator end_object
enumerator boolean_true
enumerator boolean_false
enumerator null
enumerator string
enumerator number
enumerator parse_error

Type aliases

parse_tokens_t

typedef std::vector<parse_token> orcus::json::parse_tokens_t

Functions

escape_string

std::string orcus::json::escape_string(std::string_view input)

Properly escape an input string appropriate for json output.

Parameters:

input – string value to escape.

Returns:

escaped string value.

Struct

parse_token

struct parse_token

Public Types

using value_type = std::variant<std::string_view, parse_error_value_t, double>

Public Functions

parse_token()
parse_token(parse_token_t _type)
parse_token(parse_token_t _type, std::string_view s)
parse_token(std::string_view s, std::ptrdiff_t offset)
parse_token(double value)
parse_token(const parse_token &other)
parse_token &operator=(parse_token) = delete
bool operator==(const parse_token &other) const
bool operator!=(const parse_token &other) const

Public Members

parse_token_t type
value_type value

parser_stats

struct parser_stats

Public Members

size_t token_buffer_size_threshold

table_range_t

struct table_range_t

Public Members

std::vector<std::string> paths
std::vector<std::string> row_groups

Classes

array

class array

This class represents a JSON array, to be used to explicitly create an array instance during initialization.

Public Functions

array()
array(const array&) = delete
array(array &&other)
array(std::initializer_list<detail::init::node> vs)
~array()

Friends

friend class detail::init::node

const_node

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()
node_t type() const

Get the type of a node.

Returns:

node type.

size_t child_count() const

Get the number of child nodes if any.

Returns:

number of child nodes.

std::vector<std::string_view> keys() const

Get a list of keys stored in a JSON object node.

Throws:

orcus::json::document_error – if the node is not of the object type.

Returns:

a list of keys.

std::string_view 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.

Parameters:

index – 0-based key index.

Throws:
  • 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.

Returns:

key value.

bool has_key(std::string_view key) const

Query whether or not a particular key exists in a JSON object node.

Parameters:

key – key value.

Returns:

true if this object node contains the specified key, otherwise false. If this node is not of a JSON object type, false is returned.

const_node child(size_t index) const

Get a child node by index.

Parameters:

index – 0-based index of a child node.

Throws:
  • 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.

Returns:

child node instance.

const_node child(std::string_view key) const

Get a child node by textural key value.

Parameters:

key – textural key value to get a child node by.

Throws:

orcus::json::document_error – if the node is not of the object type, or the node doesn’t have the specified key.

Returns:

child node instance.

const_node parent() const

Get the parent node.

Throws:

orcus::json::document_error – if the node doesn’t have a parent node which implies that the node is a root node.

Returns:

parent node instance.

const_node back() const

Get the last child node.

Throws:

orcus::json::document_error – if the node is not of array type or node has no children.

Returns:

last child node instance.

std::string_view string_value() const

Get the string value of a JSON string node.

Throws:

orcus::json::document_error – if the node is not of the string type.

Returns:

string value.

double numeric_value() const

Get the numeric value of a JSON number node.

Throws:

orcus::json::document_error – if the node is not of the number type.

Returns:

numeric value.

const_node &operator=(const const_node &other)
const_node &operator=(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.

Returns:

identifier of the JSON value object.

const_node_iterator begin() const

Get an iterator pointing to the first value of an array if the array is not empty. If the array is empty the iterator equals the end iterator as returned by the end() method.

Throws:

document_error – If this method is called on a non-array node.

Returns:

Iterator pointing to the first value of an array or the end iterator if the array is empty.

const_node_iterator end() const

Get an end iterator for an array node. Use it in conjunction with an iterator returned by the begin() method.

Throws:

document_error – If this method is called on a non-array node.

Returns:

End iterator for an array node.

std::string dump(std::size_t indent) const

Dump the subtree below this node to a string.

Parameters:

indent – Number of whitespace characters to use for one indent level. Note that specifying the indent value of 0 will generate output without line breaks.

Returns:

a string representation of the subtree with this node as the root node.

const_node_iterator

class const_node_iterator

Public Functions

const_node_iterator()
const_node_iterator(const const_node_iterator &other)
~const_node_iterator()
const const_node &operator*() const
const const_node *operator->() const
const_node_iterator &operator++()
const_node_iterator operator++(int)
const_node_iterator &operator--()
const_node_iterator operator--(int)
bool operator==(const const_node_iterator &other) const
bool operator!=(const const_node_iterator &other) const
const_node_iterator &operator=(const const_node_iterator &other)

document_error

class document_error : public orcus::general_error

Exception related to JSON document tree construction.

Subclassed by orcus::json::key_value_error

Public Functions

document_error(const std::string &msg)
virtual ~document_error()

document_tree

class document_tree

This class stores a parsed JSON document tree structure.

Note

Instance of this class is movable but not copyable.

Public Functions

document_tree()
document_tree(const document_tree&) = delete
document_tree(document_tree &&other)
document_tree(document_resource &res)
document_tree(std::initializer_list<detail::init::node> vs)
document_tree(array vs)
document_tree(object obj)
~document_tree()
document_tree &operator=(std::initializer_list<detail::init::node> vs)
document_tree &operator=(array vs)
document_tree &operator=(object obj)
void load(std::string_view stream, const json_config &config)

Load raw string stream containing a JSON structure to populate the document tree.

Parameters:
  • stream – stream containing a JSON structure.

  • config – configuration object.

json::const_node get_document_root() const

Get the root node of the document.

Returns:

root node of the document.

json::node get_document_root()

Get the root node of the document.

Returns:

root node of the document.

std::string dump(std::size_t indent) const

Dump the JSON document tree to string.

Parameters:

indent – Number of whitespace characters to use for one indent level. Note that specifying the indent value of 0 will generate output without line breaks.

Returns:

a string representation of the JSON document tree.

std::string dump_xml() const

Dump the JSON document tree to an XML structure.

Returns:

a string containing an XML structure representing the JSON content.

std::string dump_yaml() const

Dump the JSON document tree as YAML output.

Returns:

string containing a YAML output representing the JSON document tree structure.

void swap(document_tree &other)

Swap the content of the document with another document instance.

Parameters:

other – document instance to swap the content with.

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.

Public Functions

key_value_error(const std::string &msg)
virtual ~key_value_error()

node

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() = delete
node(const node &other)
node(node &&rhs)
~node()
node &operator=(const node &other)
node &operator=(const detail::init::node &v)
node operator[](std::string_view key)
node child(size_t index)

Get a child node by index.

Parameters:

index – 0-based index of a child node.

Throws:
  • 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.

Returns:

child node instance.

node child(std::string_view key)

Get a child node by textural key value.

Parameters:

key – textural key value to get a child node by.

Throws:

orcus::json::document_error – if the node is not of the object type, or the node doesn’t have the specified key.

Returns:

child node instance.

node parent()

Get the parent node.

Throws:

orcus::json::document_error – if the node doesn’t have a parent node which implies that the node is a root node.

Returns:

parent node instance.

node back()

Get the last child node.

Throws:

orcus::json::document_error – if the node is not of array type or node has no children.

Returns:

last child node instance.

void push_back(const detail::init::node &v)

Append a new node value to the end of the array.

Throws:

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.

object

class object

This class represents a JSON object, primarily to be used to create an empty object instance.

Public Functions

object()
object(const object&) = delete
object(object &&other)
~object()

parser_base

class parser_base : public orcus::parser_base

Subclassed by orcus::json_parser< HandlerT >

parser_thread

class parser_thread

Public Functions

parser_thread(const char *p, size_t n, size_t min_token_size)
parser_thread(const char *p, size_t n, size_t min_token_size, size_t max_token_size)
~parser_thread()
void start()
bool next_tokens(parse_tokens_t &tokens)

Wait until new set of tokens becomes available.

Parameters:

tokens – new set of tokens.

Returns:

true if the parsing is still in progress (therefore more tokens to come), false if it’s done i.e. this is the last token set.

parser_stats get_stats() const
void swap_string_pool(string_pool &pool)

structure_tree

class structure_tree

Public Types

enum class node_type : short

Values:

enumerator unknown
enumerator array
enumerator object
enumerator object_key
enumerator value
using range_handler_type = std::function<void(table_range_t&&)>

Public Functions

structure_tree(const structure_tree&) = delete
structure_tree &operator=(const structure_tree&) = delete
structure_tree()
~structure_tree()
void parse(std::string_view stream)
void normalize_tree()

For now, normalizing a tree just means sorting child nodes. We may add other normalization stuff later.

void dump_compact(std::ostream &os) const
walker get_walker() const
void process_ranges(range_handler_type rh) const
struct node_properties

Public Members

node_type type
bool repeat
class walker

Public Functions

walker()
walker(const walker &other)
~walker()
void root()

Set the current position to the root node, and return its properties.

void descend(size_t child_pos)

Move down to a child node at specified position. Call child_count() to get the number of child nodes the current node has. A child node position is 0-based and must be less than the child count.

Parameters:

child_pos – 0-based index of the child node to move down to.

void ascend()

Move up to the parent node of the current node.

size_t child_count() const

Return the number of child nodes the current node has.

Returns:

number of child nodes of the current node.

node_properties get_node() const

Get the properties of the current node.

std::vector<std::string> build_field_paths() const

Build one or more field paths for the current value node. For a value node that is a child of an object, you’ll always get one path, whereas a value node that is a chlid of an array, you may get more than one field paths.

Returns:

one or more field paths built for the current value node.

std::string build_row_group_path() const

Build a path for the parent of the current repeating node. A row group is an anchor to which repeating nodes get anchored to. It is used to determine when to increment row position during mapping.

Returns:

path for the row group of the current repeating node.

subtree

class subtree

References a subtree structure of an existing document_tree instance.

Note

Instance of this class is movable but not copyable.

Note

Instance of this class can only reference the source document; it becomes invalid when the source document is modified or destroyed.

Public Functions

subtree()
subtree(const document_tree &src, std::string_view path)

Creates a subtree reference of a source document.

Parameters:
  • src – Source document instance.

  • path – JSONPath expression referencing the root of a subtree in the source document.

subtree(const subtree&) = delete
subtree(subtree &&other)
~subtree()
subtree &operator=(subtree &&other)
std::string dump(std::size_t indent) const

Dump the subtree to a string.

Parameters:

indent – Number of whitespace characters to use for one indent level. Note that specifying the indent value of 0 will generate output without line breaks.

Returns:

String representation of the subtree.

Child namespaces