JSON Node

JSON Node — Node in a JSON object model

Synopsis

#include <json-glib/json-glib.h>

enum                JsonNodeType;
                    JsonNode;
#define             JSON_NODE_TYPE                      (node)
#define             JSON_NODE_HOLDS                     (node,
                                                         t)
#define             JSON_NODE_HOLDS_VALUE               (node)
#define             JSON_NODE_HOLDS_OBJECT              (node)
#define             JSON_NODE_HOLDS_ARRAY               (node)
#define             JSON_NODE_HOLDS_NULL                (node)
JsonNode *          json_node_alloc                     (void);
JsonNode *          json_node_init                      (JsonNode *node,
                                                         JsonNodeType type);
JsonNode *          json_node_init_int                  (JsonNode *node,
                                                         gint64 value);
JsonNode *          json_node_init_double               (JsonNode *node,
                                                         gdouble value);
JsonNode *          json_node_init_boolean              (JsonNode *node,
                                                         gboolean value);
JsonNode *          json_node_init_string               (JsonNode *node,
                                                         const char *value);
JsonNode *          json_node_init_null                 (JsonNode *node);
JsonNode *          json_node_init_object               (JsonNode *node,
                                                         JsonObject *object);
JsonNode *          json_node_init_array                (JsonNode *node,
                                                         JsonArray *array);
JsonNode *          json_node_new                       (JsonNodeType type);
JsonNode *          json_node_copy                      (JsonNode *node);
void                json_node_free                      (JsonNode *node);
JsonNode *          json_node_ref                       (JsonNode *node);
void                json_node_unref                     (JsonNode *node);
gboolean            json_node_is_immutable              (JsonNode *node);
void                json_node_seal                      (JsonNode *node);
guint               json_node_hash                      (gconstpointer key);
gboolean            json_node_equal                     (gconstpointer a,
                                                         gconstpointer b);

void                json_node_set_array                 (JsonNode *node,
                                                         JsonArray *array);
void                json_node_take_array                (JsonNode *node,
                                                         JsonArray *array);
JsonArray *         json_node_get_array                 (JsonNode *node);
JsonArray *         json_node_dup_array                 (JsonNode *node);

void                json_node_set_object                (JsonNode *node,
                                                         JsonObject *object);
void                json_node_take_object               (JsonNode *node,
                                                         JsonObject *object);
JsonObject *        json_node_get_object                (JsonNode *node);
JsonObject *        json_node_dup_object                (JsonNode *node);

void                json_node_set_value                 (JsonNode *node,
                                                         const GValue *value);
void                json_node_get_value                 (JsonNode *node,
                                                         GValue *value);
void                json_node_set_boolean               (JsonNode *node,
                                                         gboolean value);
gboolean            json_node_get_boolean               (JsonNode *node);
void                json_node_set_double                (JsonNode *node,
                                                         gdouble value);
gdouble             json_node_get_double                (JsonNode *node);
void                json_node_set_int                   (JsonNode *node,
                                                         gint64 value);
gint64              json_node_get_int                   (JsonNode *node);
void                json_node_set_string                (JsonNode *node,
                                                         const gchar *value);
const gchar *       json_node_get_string                (JsonNode *node);
gchar *             json_node_dup_string                (JsonNode *node);

void                json_node_set_parent                (JsonNode *node,
                                                         JsonNode *parent);
JsonNode *          json_node_get_parent                (JsonNode *node);
const gchar *       json_node_type_name                 (JsonNode *node);
GType               json_node_get_value_type            (JsonNode *node);
JsonNodeType        json_node_get_node_type             (JsonNode *node);
gboolean            json_node_is_null                   (JsonNode *node);

guint               json_string_hash                    (gconstpointer key);
gboolean            json_string_equal                   (gconstpointer a,
                                                         gconstpointer b);
gint                json_string_compare                 (gconstpointer a,
                                                         gconstpointer b);

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.

Details

enum JsonNodeType

typedef enum {
  JSON_NODE_OBJECT,
  JSON_NODE_ARRAY,
  JSON_NODE_VALUE,
  JSON_NODE_NULL
} JsonNodeType;

Indicates the content of a JsonNode.

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.


JSON_NODE_TYPE()

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

Evaluates to the JsonNodeType contained by node

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

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

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

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

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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:

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.

node :

a JsonNode

Returns :

the copied JsonNode. [transfer full]

json_node_free ()

void                json_node_free                      (JsonNode *node);

Frees the resources allocated by node.

node :

a JsonNode

json_node_ref ()

JsonNode *          json_node_ref                       (JsonNode *node);

Increment the reference count of node.

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.

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.

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.

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).

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.

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.

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.

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. If the node does not hold an array value, NULL is returned.

node :

a JsonNode

Returns :

the JsonArray. [transfer none][nullable]

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. If the node does not hold an array value, NULL is returned.

node :

a JsonNode

Returns :

the JsonArray with its reference count increased. [transfer full][nullable]

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.

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.

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. If the node does not hold an object value, NULL is returned.

node :

a JsonNode

Returns :

the JsonObject. [transfer none][nullable]

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. If the node does not hold an object value, NULL is returned.

node :

a JsonNode

Returns :

the JsonObject. [transfer full][nullable]

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.

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. If the node does not hold a scalar value, value is not modified.

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.

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. If the node holds an integer or double value which is zero, FALSE is returned; otherwise TRUE is returned. If the node holds a JSON_NODE_NULL value or a value of another non-boolean type, FALSE is returned.

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.

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. If the node holds an integer value, it is returned as a double. If the node holds a FALSE boolean value, `0.0` is returned; otherwise a non-zero double is returned. If the node holds a JSON_NODE_NULL value or a value of another non-double type, `0.0` is returned.

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.

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. If the node holds a double value, its integer component is returned. If the node holds a FALSE boolean value, `0` is returned; otherwise a non-zero integer is returned. If the node holds a JSON_NODE_NULL value or a value of another non-integer type, `0` is returned.

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.

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. If the node does not hold a string value, NULL is returned.

node :

a JsonNode of type JSON_NODE_VALUE

Returns :

a string value. [nullable]

json_node_dup_string ()

gchar *             json_node_dup_string                (JsonNode *node);

Gets a copy of the string value stored inside a JsonNode. If the node does not hold a string value, NULL is returned.

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][nullable]

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.

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.

node :

a JsonNode

Returns :

the parent node, or NULL if node is the root node. [transfer none][nullable]

json_node_type_name ()

const gchar *       json_node_type_name                 (JsonNode *node);

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

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.

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

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.

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.

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.

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.

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