JSON Node

## JSON Node JSON Node — Node in a JSON object model |

## Synopsis

    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_new                       (JsonNodeType type);
    JsonNode *          json_node_copy                      (JsonNode *node);
    void                json_node_free                      (JsonNode *node);

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

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

## 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_new ()

    JsonNode *          json_node_new                       (JsonNodeType type);

Creates a new JsonNode of `type`.

`type` : | a JsonNodeType
Returns : | the newly created JsonNode

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

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

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

Sets `array` inside `node` and increases the JsonArray reference count

`node` : | a JsonNode
`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.

`node` : | a JsonNode
`array` : | a JsonArray. [transfer full]

### json_node_get_array ()

    JsonArray *         json_node_get_array                 (JsonNode *node);

Retrieves the JsonArray stored inside a JsonNode

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

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

`node` : | a JsonNode
`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.

`node` : | a JsonNode
`object` : | a JsonObject. [transfer full]

### json_node_get_object ()

    JsonObject *        json_node_get_object                (JsonNode *node);

Retrieves the JsonObject stored inside a JsonNode

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

`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

`node` : | a JsonNode
`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.

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

`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

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

`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

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

`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

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

`node` : | a JsonNode of type `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

`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

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

`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]

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

### Note

A null node is not the same as a `NULL` JsonNode

`node` : | a JsonNode
Returns : | `TRUE` if the node is null

Since 0.8