## 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

enum | JsonNodeType
| JsonNode

## Object Hierarchy

        GBoxed
        ╰── JsonNode

## Includes

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

## 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:

    1
    json_node_init (json_node_alloc (), type);

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

#### Parameters

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.

#### Parameters

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.

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

#### Parameters

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.

#### Parameters

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.

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

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

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

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

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

#### Parameters

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.

#### 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][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.

#### 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][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` .

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