JSON Node

JSON Node — Node in a JSON object model

Functions

Types and Values

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.

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.

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:

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 then the reference count of the objects is increased.

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_set_array ()

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

Sets array inside node and increases the JsonArray reference count

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.

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.

Parameters

node

a JsonNode initialized to JSON_NODE_OBJECT

 

object

a JsonObject

 

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.

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

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.

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.

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.

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.

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

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

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.