JSON Node

JSON Node — Node in a JSON object model

Functions

#define JSON_NODE_TYPE()
#define JSON_NODE_HOLDS()
#define JSON_NODE_HOLDS_VALUE()
#define JSON_NODE_HOLDS_OBJECT()
#define JSON_NODE_HOLDS_ARRAY()
#define JSON_NODE_HOLDS_NULL()
JsonNode * json_node_alloc ()
JsonNode * json_node_init ()
JsonNode * json_node_init_int ()
JsonNode * json_node_init_double ()
JsonNode * json_node_init_boolean ()
JsonNode * json_node_init_string ()
JsonNode * json_node_init_null ()
JsonNode * json_node_init_object ()
JsonNode * json_node_init_array ()
JsonNode * json_node_new ()
JsonNode * json_node_copy ()
void json_node_free ()
JsonNode * json_node_ref ()
void json_node_unref ()
gboolean json_node_is_immutable ()
void json_node_seal ()
guint json_node_hash ()
gboolean json_node_equal ()
void json_node_set_array ()
void json_node_take_array ()
JsonArray * json_node_get_array ()
JsonArray * json_node_dup_array ()
void json_node_set_object ()
void json_node_take_object ()
JsonObject * json_node_get_object ()
JsonObject * json_node_dup_object ()
void json_node_set_value ()
void json_node_get_value ()
void json_node_set_boolean ()
gboolean json_node_get_boolean ()
void json_node_set_double ()
gdouble json_node_get_double ()
void json_node_set_int ()
gint64 json_node_get_int ()
void json_node_set_string ()
const gchar * json_node_get_string ()
gchar * json_node_dup_string ()
void json_node_set_parent ()
JsonNode * json_node_get_parent ()
const gchar * json_node_type_name ()
GType json_node_get_value_type ()
JsonNodeType json_node_get_node_type ()
gboolean json_node_is_null ()
guint json_string_hash ()
gboolean json_string_equal ()
gint json_string_compare ()

Types and Values

Object Hierarchy

    GBoxed
    ╰── JsonNode

Description

A JsonNode is a generic container of elements inside a JSON stream. It can contain fundamental types (integers, booleans, floating point numbers, strings) and complex types (arrays and objects).

When parsing a JSON data stream you extract the root node and walk the node tree by retrieving the type of data contained inside the node with the JSON_NODE_TYPE macro. If the node contains a fundamental type you can retrieve a copy of the GValue holding it with the json_node_get_value() function, and then use the GValue API to extract the data; if the node contains a complex type you can retrieve the JsonObject or the JsonArray using json_node_get_object() or json_node_get_array() respectively, and then retrieve the nodes they contain.

A JsonNode may be marked as immutable using json_node_seal(). This marks the node and all its descendents as read-only, and means that subsequent calls to setter functions (such as json_node_set_array()) on them will abort as a programmer error. By marking a node tree as immutable, it may be referenced in multiple places and its hash value cached for fast lookups, without the possibility of a value deep within the tree changing and affecting hash values. Immutable JsonNodes may be passed to functions which retain a reference to them without needing to take a copy.

JsonNode supports two types of memory management: alloc/free semantics, and ref/unref semantics. The two may be mixed to a limited extent: nodes may be allocated (which gives them a reference count of 1), referenced zero or more times, unreferenced exactly that number of times (using json_node_unref()), then either unreferenced exactly once more or freed (using json_node_free()) to destroy them. json_node_free() must not be used when a node might have a reference count not equal to 1. To this end, json-glib uses json_node_copy() and json_node_unref() internally.

Functions

JSON_NODE_TYPE()

#define JSON_NODE_TYPE(node)    (json_node_get_node_type ((node)))

Evaluates to the JsonNodeType contained by node

Parameters

node

a JsonNode

 

JSON_NODE_HOLDS()

#define JSON_NODE_HOLDS(node,t)         (json_node_get_node_type ((node)) == (t))

Evaluates to TRUE if the node holds type t

Parameters

node

a JsonNode

 

t

a JsonNodeType

 

Since: 0.10


JSON_NODE_HOLDS_VALUE()

#define JSON_NODE_HOLDS_VALUE(node)     (JSON_NODE_HOLDS ((node), JSON_NODE_VALUE))

Evaluates to TRUE if node holds a JSON_NODE_VALUE

Parameters

node

a JsonNode

 

Since: 0.10


JSON_NODE_HOLDS_OBJECT()

#define JSON_NODE_HOLDS_OBJECT(node)    (JSON_NODE_HOLDS ((node), JSON_NODE_OBJECT))

Evaluates to TRUE if node holds a JSON_NODE_OBJECT

Parameters

node

a JsonNode

 

Since: 0.10


JSON_NODE_HOLDS_ARRAY()

#define JSON_NODE_HOLDS_ARRAY(node)     (JSON_NODE_HOLDS ((node), JSON_NODE_ARRAY))

Evaluates to TRUE if node holds a JSON_NODE_ARRAY

Parameters

node

a JsonNode

 

Since: 0.10


JSON_NODE_HOLDS_NULL()

#define JSON_NODE_HOLDS_NULL(node)      (JSON_NODE_HOLDS ((node), JSON_NODE_NULL))

Evaluates to TRUE if node holds a JSON_NODE_NULL

Parameters

node

a JsonNode

 

Since: 0.10


json_node_alloc ()

JsonNode *
json_node_alloc (void);

Allocates a new JsonNode. Use json_node_init() and its variants to initialize the returned value.

[constructor]

Returns

the newly allocated JsonNode. Use json_node_free() to free the resources allocated by this function.

[transfer full]

Since: 0.16


json_node_init ()

JsonNode *
json_node_init (JsonNode *node,
                JsonNodeType type);

Initializes a node to a specific type .

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

type

the type of JSON node to initialize node to

 

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_int ()

JsonNode *
json_node_init_int (JsonNode *node,
                    gint64 value);

Initializes node to JSON_NODE_VALUE and sets value into it.

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

value

an integer

 

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_double ()

JsonNode *
json_node_init_double (JsonNode *node,
                       gdouble value);

Initializes node to JSON_NODE_VALUE and sets value into it.

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

value

a floating point value

 

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_boolean ()

JsonNode *
json_node_init_boolean (JsonNode *node,
                        gboolean value);

Initializes node to JSON_NODE_VALUE and sets value into it.

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

value

a boolean value

 

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_string ()

JsonNode *
json_node_init_string (JsonNode *node,
                       const char *value);

Initializes node to JSON_NODE_VALUE and sets value into it.

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

value

a string value.

[allow-none]

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_null ()

JsonNode *
json_node_init_null (JsonNode *node);

Initializes node to JSON_NODE_NULL.

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_object ()

JsonNode *
json_node_init_object (JsonNode *node,
                       JsonObject *object);

Initializes node to JSON_NODE_OBJECT and sets object into it.

This function will take a reference on object .

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

object

the JsonObject to initialize node with, or NULL.

[allow-none]

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_init_array ()

JsonNode *
json_node_init_array (JsonNode *node,
                      JsonArray *array);

Initializes node to JSON_NODE_ARRAY and sets array into it.

This function will take a reference on array .

If the node has already been initialized once, it will be reset to the given type, and any data contained will be cleared.

Parameters

node

the JsonNode to initialize

 

array

the JsonArray to initialize node with, or NULL.

[allow-none]

Returns

the initialized JsonNode.

[transfer none]

Since: 0.16


json_node_new ()

JsonNode *
json_node_new (JsonNodeType type);

Creates a new JsonNode of type .

This is a convenience function for json_node_alloc() and json_node_init(), and it's the equivalent of:

[constructor]

Parameters

type

a JsonNodeType

 

Returns

the newly created JsonNode.

[transfer full]


json_node_copy ()

JsonNode *
json_node_copy (JsonNode *node);

Copies node . If the node contains complex data types, their reference counts are increased, regardless of whether the node is mutable or immutable.

The copy will be immutable if, and only if, node is immutable. However, there should be no need to copy an immutable node.

Parameters

node

a JsonNode

 

Returns

the copied JsonNode.

[transfer full]


json_node_free ()

void
json_node_free (JsonNode *node);

Frees the resources allocated by node .

Parameters

node

a JsonNode

 

json_node_ref ()

JsonNode *
json_node_ref (JsonNode *node);

Increment the reference count of node .

Parameters

node

a JsonNode

 

Returns

a pointer to node .

[transfer full]

Since: 1.2


json_node_unref ()

void
json_node_unref (JsonNode *node);

Decrement the reference count of node . If it reaches zero, the node is freed.

Parameters

node

a JsonNode.

[transfer full]

Since: 1.2


json_node_is_immutable ()

gboolean
json_node_is_immutable (JsonNode *node);

Check whether the given node has been marked as immutable by calling json_node_seal() on it.

Parameters

node

a JsonNode

 

Returns

TRUE if the node is immutable

Since: 1.2


json_node_seal ()

void
json_node_seal (JsonNode *node);

Seals the JsonNode, making it immutable to further changes. In order to be sealed, the node must have a type and value set. The value will be recursively sealed — if the node holds an object, that JsonObject will be sealed, etc.

If the node is already immutable, this is a no-op.

Parameters

node

a JsonNode

 

Since: 1.2


json_node_hash ()

guint
json_node_hash (gconstpointer key);

Calculate a hash value for the given key (a JsonNode).

The hash is calculated over the node and its value, recursively. If the node is immutable, this is a fast operation; otherwise, it scales proportionally with the size of the node’s value (for example, with the number of members in the JsonObject if this node contains an object).

Parameters

key

a JSON node to hash.

[type JsonNode]

Returns

hash value for key

Since: 1.2


json_node_equal ()

gboolean
json_node_equal (gconstpointer a,
                 gconstpointer b);

Check whether a and b are equal JsonNodes, meaning they have the same type and same values (checked recursively). Note that integer values are compared numerically, ignoring type, so a double value 4.0 is equal to the integer value 4.

Parameters

a

a JSON node.

[type JsonNode]

b

another JSON node.

[type JsonNode]

Returns

TRUE if a and b are equal; FALSE otherwise

Since: 1.2


json_node_set_array ()

void
json_node_set_array (JsonNode *node,
                     JsonArray *array);

Sets array inside node and increases the JsonArray reference count.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode initialized to JSON_NODE_ARRAY

 

array

a JsonArray

 

json_node_take_array ()

void
json_node_take_array (JsonNode *node,
                      JsonArray *array);

Sets array into node without increasing the JsonArray reference count.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode initialized to JSON_NODE_ARRAY

 

array

a JsonArray.

[transfer full]

json_node_get_array ()

JsonArray *
json_node_get_array (JsonNode *node);

Retrieves the JsonArray stored inside a JsonNode

Parameters

node

a JsonNode

 

Returns

the JsonArray.

[transfer none]


json_node_dup_array ()

JsonArray *
json_node_dup_array (JsonNode *node);

Retrieves the JsonArray stored inside a JsonNode and returns it with its reference count increased by one.

Parameters

node

a JsonNode

 

Returns

the JsonArray with its reference count increased.

[transfer full]


json_node_set_object ()

void
json_node_set_object (JsonNode *node,
                      JsonObject *object);

Sets objects inside node . The reference count of object is increased.

If object is NULL, the node’s existing object is cleared.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode initialized to JSON_NODE_OBJECT

 

object

a JsonObject.

[nullable]

json_node_take_object ()

void
json_node_take_object (JsonNode *node,
                       JsonObject *object);

Sets object inside node . The reference count of object is not increased.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode initialized to JSON_NODE_OBJECT

 

object

a JsonObject.

[transfer full]

json_node_get_object ()

JsonObject *
json_node_get_object (JsonNode *node);

Retrieves the JsonObject stored inside a JsonNode

Parameters

node

a JsonNode

 

Returns

the JsonObject.

[transfer none]


json_node_dup_object ()

JsonObject *
json_node_dup_object (JsonNode *node);

Retrieves the JsonObject inside node . The reference count of the returned object is increased.

Parameters

node

a JsonNode

 

Returns

the JsonObject.

[transfer full]


json_node_set_value ()

void
json_node_set_value (JsonNode *node,
                     const GValue *value);

Sets value inside node . The passed GValue is copied into the JsonNode.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode initialized to JSON_NODE_VALUE

 

value

the GValue to set

 

json_node_get_value ()

void
json_node_get_value (JsonNode *node,
                     GValue *value);

Retrieves a value from a JsonNode and copies into value . When done using it, call g_value_unset() on the GValue.

Parameters

node

a JsonNode

 

value

return location for an uninitialized value.

[out caller-allocates]

json_node_set_boolean ()

void
json_node_set_boolean (JsonNode *node,
                       gboolean value);

Sets value as the boolean content of the node , replacing any existing content.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

value

a boolean value

 

json_node_get_boolean ()

gboolean
json_node_get_boolean (JsonNode *node);

Gets the boolean value stored inside a JsonNode

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

Returns

a boolean value.


json_node_set_double ()

void
json_node_set_double (JsonNode *node,
                      gdouble value);

Sets value as the double content of the node , replacing any existing content.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

value

a double value

 

json_node_get_double ()

gdouble
json_node_get_double (JsonNode *node);

Gets the double value stored inside a JsonNode

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

Returns

a double value.


json_node_set_int ()

void
json_node_set_int (JsonNode *node,
                   gint64 value);

Sets value as the integer content of the node , replacing any existing content.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

value

an integer value

 

json_node_get_int ()

gint64
json_node_get_int (JsonNode *node);

Gets the integer value stored inside a JsonNode

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

Returns

an integer value.


json_node_set_string ()

void
json_node_set_string (JsonNode *node,
                      const gchar *value);

Sets value as the string content of the node , replacing any existing content.

It is an error to call this on an immutable node.

Parameters

node

a JsonNode initialized to JSON_NODE_VALUE

 

value

a string value

 

json_node_get_string ()

const gchar *
json_node_get_string (JsonNode *node);

Gets the string value stored inside a JsonNode

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

Returns

a string value.


json_node_dup_string ()

gchar *
json_node_dup_string (JsonNode *node);

Gets a copy of the string value stored inside a JsonNode

Parameters

node

a JsonNode of type JSON_NODE_VALUE

 

Returns

a newly allocated string containing a copy of the JsonNode contents. Use g_free() to free the allocated resources.

[transfer full]


json_node_set_parent ()

void
json_node_set_parent (JsonNode *node,
                      JsonNode *parent);

Sets the parent JsonNode of node .

It is an error to call this with an immutable parent . node may be immutable.

Parameters

node

a JsonNode

 

parent

the parent JsonNode of node .

[transfer none]

Since: 0.8


json_node_get_parent ()

JsonNode *
json_node_get_parent (JsonNode *node);

Retrieves the parent JsonNode of node .

Parameters

node

a JsonNode

 

Returns

the parent node, or NULL if node is the root node.

[transfer none]


json_node_type_name ()

const gchar *
json_node_type_name (JsonNode *node);

Retrieves the user readable name of the data type contained by node .

Parameters

node

a JsonNode

 

Returns

a string containing the name of the type. The returned string is owned by the node and should never be modified or freed


json_node_get_value_type ()

GType
json_node_get_value_type (JsonNode *node);

Returns the GType of the payload of the node.

Parameters

node

a JsonNode

 

Returns

a GType for the payload.

Since: 0.4


json_node_get_node_type ()

JsonNodeType
json_node_get_node_type (JsonNode *node);

Retrieves the JsonNodeType of node

Parameters

node

a JsonNode

 

Returns

the type of the node

Since: 0.8


json_node_is_null ()

gboolean
json_node_is_null (JsonNode *node);

Checks whether node is a JSON_NODE_NULL.

A JSON_NODE_NULL node is not the same as a NULL JsonNode; a JSON_NODE_NULL represents a 'null' value in the JSON tree.

Parameters

node

a JsonNode

 

Returns

TRUE if the node is null

Since: 0.8


json_string_hash ()

guint
json_string_hash (gconstpointer key);

Calculate a hash value for the given key (a UTF-8 JSON string).

Note: Member names are compared byte-wise, without applying any Unicode decomposition or normalisation. This is not explicitly mentioned in the JSON standard (ECMA-404), but is assumed.

Parameters

key

a JSON string to hash.

[type utf8]

Returns

hash value for key

Since: 1.2


json_string_equal ()

gboolean
json_string_equal (gconstpointer a,
                   gconstpointer b);

Check whether a and b are equal UTF-8 JSON strings.

Parameters

a

a JSON string.

[type utf8]

b

another JSON string.

[type utf8]

Returns

TRUE if a and b are equal; FALSE otherwise

Since: 1.2


json_string_compare ()

gint
json_string_compare (gconstpointer a,
                     gconstpointer b);

Check whether a and b are equal UTF-8 JSON strings and return an ordering over them in strcmp() style.

Parameters

a

a JSON string.

[type utf8]

b

another JSON string.

[type utf8]

Returns

an integer less than zero if a < b , equal to zero if a == b , and greater than zero if a > b

Since: 1.2

Types and Values

enum JsonNodeType

Indicates the content of a JsonNode.

Members

JSON_NODE_OBJECT

The node contains a JsonObject

 

JSON_NODE_ARRAY

The node contains a JsonArray

 

JSON_NODE_VALUE

The node contains a fundamental type

 

JSON_NODE_NULL

Special type, for nodes containing null

 

JsonNode

typedef struct _JsonNode JsonNode;

A generic container of JSON data types. The contents of the JsonNode structure are private and should only be accessed via the provided functions and never directly.