JSON Array: JSON-GLib Reference Manual

## JSON Array JSON Array — a JSON array representation |

## Functions

JsonArray * | json_array_new ()
JsonArray * | json_array_sized_new ()
JsonArray * | json_array_ref ()
void | json_array_unref ()
void | json_array_seal ()
gboolean | json_array_is_immutable ()
guint | json_array_hash ()
gboolean | json_array_equal ()
void | json_array_add_element ()
JsonNode * | json_array_get_element ()
JsonNode * | json_array_dup_element ()
GList * | json_array_get_elements ()
guint | json_array_get_length ()
void | json_array_remove_element ()
void | (*JsonArrayForeach) ()
void | json_array_foreach_element ()
void | json_array_add_array_element ()
JsonArray * | json_array_get_array_element ()
void | json_array_add_boolean_element ()
gboolean | json_array_get_boolean_element ()
void | json_array_add_double_element ()
gdouble | json_array_get_double_element ()
void | json_array_add_int_element ()
gint64 | json_array_get_int_element ()
void | json_array_add_null_element ()
gboolean | json_array_get_null_element ()
void | json_array_add_object_element ()
JsonObject * | json_array_get_object_element ()
void | json_array_add_string_element ()
const gchar * | json_array_get_string_element ()

## Types and Values

| JsonArray

## Object Hierarchy

        GBoxed
        ╰── JsonArray

## Description

JsonArray is the representation of the array type inside JSON. It contains JsonNode elements, which may contain fundamental types, other arrays or objects.

Since arrays can be expensive, they are reference counted. You can control the lifetime of a JsonArray using `json_array_ref()` and `json_array_unref()`.

To append an element, use `json_array_add_element()`. To extract an element at a given index, use `json_array_get_element()`. To retrieve the entire array in list form, use `json_array_get_elements()`. To retrieve the length of the array, use `json_array_get_length()`.

## Functions

### json_array_new ()

    JsonArray *
    json_array_new (void);

Creates a new JsonArray.

[constructor]

#### Returns

the newly created JsonArray.

[transfer full]

### json_array_sized_new ()

    JsonArray *
    json_array_sized_new (guint n_elements);

Creates a new JsonArray with `n_elements` slots already allocated.

[constructor]

#### Parameters

n_elements | number of slots to pre-allocate |

#### Returns

the newly created JsonArray.

[transfer full]

### json_array_ref ()

    JsonArray *
    json_array_ref (JsonArray *array);

Increase by one the reference count of a JsonArray.

#### Parameters

array | a JsonArray |

#### Returns

the passed JsonArray, with the reference count increased by one.

[transfer none]

### json_array_unref ()

    void
    json_array_unref (JsonArray *array);

Decreases by one the reference count of a JsonArray. If the reference count reaches zero, the array is destroyed and all its allocated resources are freed.

#### Parameters

array | a JsonArray |

### json_array_seal ()

    void
    json_array_seal (JsonArray *array);

Seals the JsonArray, making it immutable to further changes. This will recursively seal all elements in the array too.

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

#### Parameters

array | a JsonArray |

Since: 1.2

### json_array_is_immutable ()

    gboolean
    json_array_is_immutable (JsonArray *array);

Check whether the given `array` has been marked as immutable by calling `json_array_seal()` on it.

#### Parameters

array | a JsonArray |

#### Returns

`TRUE` if the `array` is immutable

Since: 1.2

### json_array_hash ()

    guint
    json_array_hash (gconstpointer key);

Calculate a hash value for the given `key` (a JsonArray).

The hash is calculated over the array and all its elements, recursively. If the array is immutable, this is a fast operation; otherwise, it scales proportionally with the length of the array.

#### Parameters

key | a JSON array to hash. | [type JsonArray]

#### Returns

hash value for `key`

Since: 1.2

### json_array_equal ()

    gboolean
    json_array_equal (gconstpointer a,
                      gconstpointer b);

Check whether `a` and `b` are equal JsonArrays, meaning they have the same number of elements, and the values of elements in corresponding positions are equal.

#### Parameters

a | a JSON array. | [type JsonArray]
b | another JSON array. | [type JsonArray]

#### Returns

`TRUE` if `a` and `b` are equal; `FALSE` otherwise

Since: 1.2

### json_array_add_element ()

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

Appends `node` inside `array` . The array will take ownership of the JsonNode.

#### Parameters

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

### json_array_get_element ()

    JsonNode *
    json_array_get_element (JsonArray *array,
                            guint index_);

Retrieves the JsonNode containing the value of the element at `index_` inside a JsonArray.

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

a pointer to the JsonNode at the requested index.

[transfer none]

### json_array_dup_element ()

    JsonNode *
    json_array_dup_element (JsonArray *array,
                            guint index_);

Retrieves a copy of the JsonNode containing the value of the element at `index_` inside a JsonArray

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

a copy of the JsonNode at the requested index. Use `json_node_unref()` when done.

[transfer full]

Since: 0.6

### json_array_get_elements ()

    GList *
    json_array_get_elements (JsonArray *array);

Gets the elements of a JsonArray as a list of JsonNode instances.

#### Parameters

array | a JsonArray |

#### Returns

a GList containing the elements of the array. The contents of the list are owned by the array and should never be modified or freed. Use `g_list_free()` on the returned list when done using it.

[element-type JsonNode][transfer container]

### json_array_get_length ()

    guint
    json_array_get_length (JsonArray *array);

Retrieves the length of a JsonArray

#### Parameters

array | a JsonArray |

#### Returns

the length of the array

### json_array_remove_element ()

    void
    json_array_remove_element (JsonArray *array,
                               guint index_);

Removes the JsonNode inside `array` at `index_` freeing its allocated resources.

#### Parameters

array | a JsonArray |
index_ | the position of the element to be removed |

### JsonArrayForeach ()

    void
    (*JsonArrayForeach) (JsonArray *array,
                         guint index_,
                         JsonNode *element_node,
                         gpointer user_data);

The function to be passed to `json_array_foreach_element()`. You should not add or remove elements to and from `array` within this function. It is safe to change the value of `element_node` .

#### Parameters

array | the iterated JsonArray |
index_ | the index of the element |
element_node | a JsonNode containing the value at `index_` |
user_data | data passed to the function |

Since: 0.8

### json_array_foreach_element ()

    void
    json_array_foreach_element (JsonArray *array,
                                JsonArrayForeach func,
                                gpointer data);

Iterates over all elements of `array` and calls `func` on each one of them.

It is safe to change the value of a JsonNode of the `array` from within the iterator `func` , but it is not safe to add or remove elements from the `array` .

#### Parameters

array | a JsonArray |
func | the function to be called on each element. | [scope call]
data | data to be passed to the function. | [closure]

Since: 0.8

### json_array_add_array_element ()

    void
    json_array_add_array_element (JsonArray *array,
                                  JsonArray *value);

Conveniently adds an array into `array` . The `array` takes ownership of the newly added JsonArray

See also: `json_array_add_element()`, `json_node_take_array()`

#### Parameters

array | a JsonArray |
value | a JsonArray. | [allow-none][transfer full]

Since: 0.8

### json_array_get_array_element ()

    JsonArray *
    json_array_get_array_element (JsonArray *array,
                                  guint index_);

Conveniently retrieves the array from the element at `index_` inside `array`

See also: `json_array_get_element()`, `json_node_get_array()`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

the array.

[transfer none]

Since: 0.8

### json_array_add_boolean_element ()

    void
    json_array_add_boolean_element (JsonArray *array,
                                    gboolean value);

Conveniently adds a boolean `value` into `array`

See also: `json_array_add_element()`, `json_node_set_boolean()`

#### Parameters

array | a JsonArray |
value | a boolean value |

Since: 0.8

### json_array_get_boolean_element ()

    gboolean
    json_array_get_boolean_element (JsonArray *array,
                                    guint index_);

Conveniently retrieves the boolean value of the element at `index_` inside `array`

See also: `json_array_get_element()`, `json_node_get_boolean()`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

the integer value

Since: 0.8

### json_array_add_double_element ()

    void
    json_array_add_double_element (JsonArray *array,
                                   gdouble value);

Conveniently adds a floating point `value` into `array`

See also: `json_array_add_element()`, `json_node_set_double()`

#### Parameters

array | a JsonArray |
value | a floating point value |

Since: 0.8

### json_array_get_double_element ()

    gdouble
    json_array_get_double_element (JsonArray *array,
                                   guint index_);

Conveniently retrieves the floating point value of the element at `index_` inside `array`

See also: `json_array_get_element()`, `json_node_get_double()`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

the floating point value

Since: 0.8

### json_array_add_int_element ()

    void
    json_array_add_int_element (JsonArray *array,
                                gint64 value);

Conveniently adds an integer `value` into `array`

See also: `json_array_add_element()`, `json_node_set_int()`

#### Parameters

array | a JsonArray |
value | an integer value |

Since: 0.8

### json_array_get_int_element ()

    gint64
    json_array_get_int_element (JsonArray *array,
                                guint index_);

Conveniently retrieves the integer value of the element at `index_` inside `array`

See also: `json_array_get_element()`, `json_node_get_int()`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

the integer value

Since: 0.8

### json_array_add_null_element ()

    void
    json_array_add_null_element (JsonArray *array);

Conveniently adds a null element into `array`

See also: `json_array_add_element()`, `JSON_NODE_NULL`

#### Parameters

array | a JsonArray |

Since: 0.8

### json_array_get_null_element ()

    gboolean
    json_array_get_null_element (JsonArray *array,
                                 guint index_);

Conveniently retrieves whether the element at `index_` is set to null

See also: `json_array_get_element()`, `JSON_NODE_TYPE()`, `JSON_NODE_NULL`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

`TRUE` if the element is null

Since: 0.8

### json_array_add_object_element ()

    void
    json_array_add_object_element (JsonArray *array,
                                   JsonObject *value);

Conveniently adds an object into `array` . The `array` takes ownership of the newly added JsonObject

See also: `json_array_add_element()`, `json_node_take_object()`

#### Parameters

array | a JsonArray |
value | a JsonObject. | [transfer full]

Since: 0.8

### json_array_get_object_element ()

    JsonObject *
    json_array_get_object_element (JsonArray *array,
                                   guint index_);

Conveniently retrieves the object from the element at `index_` inside `array`

See also: `json_array_get_element()`, `json_node_get_object()`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

the object.

[transfer none]

Since: 0.8

### json_array_add_string_element ()

    void
    json_array_add_string_element (JsonArray *array,
                                   const gchar *value);

Conveniently adds a string `value` into `array`

See also: `json_array_add_element()`, `json_node_set_string()`

#### Parameters

array | a JsonArray |
value | a string value |

Since: 0.8

### json_array_get_string_element ()

    const gchar *
    json_array_get_string_element (JsonArray *array,
                                   guint index_);

Conveniently retrieves the string value of the element at `index_` inside `array`

See also: `json_array_get_element()`, `json_node_get_string()`

#### Parameters

array | a JsonArray |
index_ | the index of the element to retrieve |

#### Returns

the string value; the returned string is owned by the JsonArray and should not be modified or freed

Since: 0.8

## Types and Values

### JsonArray

    typedef struct _JsonArray JsonArray;

A JSON array type. The contents of the JsonArray structure are private and should only be accessed by the provided API