JsonArray

## JsonArray JsonArray — a JSON array representation |

## Synopsis

                        JsonArray;
    JsonArray*          json_array_new                      (void);
    JsonArray*          json_array_sized_new                (guint n_elements);
    JsonArray*          json_array_ref                      (JsonArray *array);
    void                json_array_unref                    (JsonArray *array);

    void                json_array_add_element              (JsonArray *array,
                                                             JsonNode *node);
    JsonNode*           json_array_get_element              (JsonArray *array,
                                                             guint index_);
    JsonNode*           json_array_dup_element              (JsonArray *array,
                                                             guint index_);
    GList*              json_array_get_elements             (JsonArray *array);
    guint               json_array_get_length               (JsonArray *array);
    void                json_array_remove_element           (JsonArray *array,
                                                             guint index_);

## Description

JsonArray is the representation of the array type inside JSON. It contains JsonNodes, 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()`.

## Details

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

### json_array_new ()

    JsonArray*          json_array_new                      (void);

Creates a new JsonArray.

Returns : | the newly created JsonArray

### json_array_sized_new ()

    JsonArray*          json_array_sized_new                (guint n_elements);

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

`n_elements` : | number of slots to pre-allocate
Returns : | the newly created JsonArray

### json_array_ref ()

    JsonArray*          json_array_ref                      (JsonArray *array);

Increase by one the reference count of a JsonArray.

`array` : | a JsonArray
Returns : | the passed JsonArray, with the reference count increased by one.

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

`array` : | a JsonArray

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

`array` : | a JsonArray
`node` : | a JsonNode

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

`array` : | a JsonArray
`index_` : | the index of the element to retrieve
Returns : | a pointer to the JsonNode at the requested index

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

`array` : | a JsonArray
`index_` : | the index of the element to retrieve
Returns : | a copy of the JsonNode at the requested index. Use `json_node_free()` when done.

Since 0.6

### json_array_get_elements ()

    GList*              json_array_get_elements             (JsonArray *array);

Gets the elements of a JsonArray as a list of JsonNodes.

`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

### json_array_get_length ()

    guint               json_array_get_length               (JsonArray *array);

Retrieves the length of a JsonArray

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

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