JSON Object: JSON-GLib Reference Manual

## JSON Object JSON Object — a JSON object representation |

## Functions

JsonObject * | json_object_new ()
JsonObject * | json_object_ref ()
void | json_object_unref ()
void | json_object_seal ()
gboolean | json_object_is_immutable ()
guint | json_object_hash ()
gboolean | json_object_equal ()
void | json_object_add_member ()
void | json_object_set_member ()
gboolean | json_object_has_member ()
JsonNode * | json_object_get_member ()
JsonNode * | json_object_dup_member ()
GList * | json_object_get_members ()
GList * | json_object_get_values ()
guint | json_object_get_size ()
void | json_object_remove_member ()
void | (*JsonObjectForeach) ()
void | json_object_foreach_member ()
void | json_object_iter_init ()
gboolean | json_object_iter_next ()
void | json_object_set_array_member ()
JsonArray * | json_object_get_array_member ()
void | json_object_set_boolean_member ()
gboolean | json_object_get_boolean_member ()
void | json_object_set_double_member ()
gdouble | json_object_get_double_member ()
void | json_object_set_int_member ()
gint64 | json_object_get_int_member ()
void | json_object_set_null_member ()
gboolean | json_object_get_null_member ()
void | json_object_set_object_member ()
JsonObject * | json_object_get_object_member ()
void | json_object_set_string_member ()
const gchar * | json_object_get_string_member ()

## Types and Values

| JsonObject
| JsonObjectIter

## Object Hierarchy

        GBoxed
        ╰── JsonObject

## Description

JsonObject is the representation of the object type inside JSON. It contains JsonNodes, which may contain fundamental types, arrays or other objects; each node inside an object, or "member", is accessed using a unique string, or "name".

Since objects can be expensive, they are reference counted. You can control the lifetime of a JsonObject using `json_object_ref()` and `json_object_unref()`.

To add or overwrite a member with a given name, use `json_object_set_member()`. To extract a member with a given name, use `json_object_get_member()`. To retrieve the list of members, use `json_object_get_members()`. To retrieve the size of the object (that is, the number of members it has), use `json_object_get_size()`.

## Functions

### json_object_new ()

    JsonObject *
    json_object_new (void);

Creates a new JsonObject, an JSON object type representation.

[constructor]

#### Returns

the newly created JsonObject.

[transfer full]

### json_object_ref ()

    JsonObject *
    json_object_ref (JsonObject *object);

Increase by one the reference count of a JsonObject.

#### Parameters

object | a JsonObject |

#### Returns

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

[transfer none]

### json_object_unref ()

    void
    json_object_unref (JsonObject *object);

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

#### Parameters

object | a JsonObject |

### json_object_seal ()

    void
    json_object_seal (JsonObject *object);

Seals the JsonObject, making it immutable to further changes. This will recursively seal all members of the object too.

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

#### Parameters

object | a JsonObject |

Since: 1.2

### json_object_is_immutable ()

    gboolean
    json_object_is_immutable (JsonObject *object);

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

#### Parameters

object | a JsonObject |

#### Returns

`TRUE` if the `object` is immutable

Since: 1.2

### json_object_hash ()

    guint
    json_object_hash (gconstpointer key);

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

The hash is calculated over the object and all its members, recursively. If the object is immutable, this is a fast operation; otherwise, it scales proportionally with the number of members in the object.

#### Parameters

key | a JSON object to hash. | [type JsonObject]

#### Returns

hash value for `key`

Since: 1.2

### json_object_equal ()

    gboolean
    json_object_equal (gconstpointer a,
                       gconstpointer b);

Check whether `a` and `b` are equal JsonObjects, meaning they have the same set of members, and the values of corresponding members are equal.

#### Parameters

a | a JSON object. | [type JsonObject]
b | another JSON object. | [type JsonObject]

#### Returns

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

Since: 1.2

### json_object_add_member ()

    void
    json_object_add_member (JsonObject *object,
                            const gchar *member_name,
                            JsonNode *node);

`json_object_add_member` has been deprecated since version 0.8 and should not be used in newly-written code.

Use `json_object_set_member()` instead

Adds a member named `member_name` and containing `node` into a JsonObject. The object will take ownership of the JsonNode.

This function will return if the `object` already contains a member `member_name` .

#### Parameters

object | a JsonObject |
member_name | the name of the member |
node | the value of the member. | [transfer full]

### json_object_set_member ()

    void
    json_object_set_member (JsonObject *object,
                            const gchar *member_name,
                            JsonNode *node);

Sets `node` as the value of `member_name` inside `object` .

If `object` already contains a member called `member_name` then the member's current value is overwritten. Otherwise, a new member is added to `object` .

#### Parameters

object | a JsonObject |
member_name | the name of the member |
node | the value of the member. | [transfer full]

Since: 0.8

### json_object_has_member ()

    gboolean
    json_object_has_member (JsonObject *object,
                            const gchar *member_name);

Checks whether `object` has a member named `member_name` .

#### Parameters

object | a JsonObject |
member_name | the name of a JSON object member |

#### Returns

`TRUE` if the JSON object has the requested member

### json_object_get_member ()

    JsonNode *
    json_object_get_member (JsonObject *object,
                            const gchar *member_name);

Retrieves the JsonNode containing the value of `member_name` inside a JsonObject.

#### Parameters

object | a JsonObject |
member_name | the name of the JSON object member to access |

#### Returns

a pointer to the node for the requested object member, or `NULL`.

[transfer none]

### json_object_dup_member ()

    JsonNode *
    json_object_dup_member (JsonObject *object,
                            const gchar *member_name);

Retrieves a copy of the JsonNode containing the value of `member_name` inside a JsonObject

#### Parameters

object | a JsonObject |
member_name | the name of the JSON object member to access |

#### Returns

a copy of the node for the requested object member or `NULL`. Use `json_node_unref()` when done.

[transfer full]

Since: 0.6

### json_object_get_members ()

    GList *
    json_object_get_members (JsonObject *object);

Retrieves all the names of the members of a JsonObject. You can obtain the value for each member using `json_object_get_member()`.

#### Parameters

object | a JsonObject |

#### Returns

a GList of member names. The content of the list is owned by the JsonObject and should never be modified or freed. When you have finished using the returned list, use `g_list_free()` to free the resources it has allocated.

[element-type utf8][transfer container]

### json_object_get_values ()

    GList *
    json_object_get_values (JsonObject *object);

Retrieves all the values of the members of a JsonObject.

#### Parameters

object | a JsonObject |

#### Returns

a GList of JsonNodes. The content of the list is owned by the JsonObject and should never be modified or freed. When you have finished using the returned list, use `g_list_free()` to free the resources it has allocated.

[element-type JsonNode][transfer container]

### json_object_get_size ()

    guint
    json_object_get_size (JsonObject *object);

Retrieves the number of members of a JsonObject.

#### Parameters

object | a JsonObject |

#### Returns

the number of members

### json_object_remove_member ()

    void
    json_object_remove_member (JsonObject *object,
                               const gchar *member_name);

Removes `member_name` from `object` , freeing its allocated resources.

#### Parameters

object | a JsonObject |
member_name | the name of the member to remove |

### JsonObjectForeach ()

    void
    (*JsonObjectForeach) (JsonObject *object,
                          const gchar *member_name,
                          JsonNode *member_node,
                          gpointer user_data);

The function to be passed to `json_object_foreach_member()`. You should not add or remove members to and from `object` within this function. It is safe to change the value of `member_node` .

#### Parameters

object | the iterated JsonObject |
member_name | the name of the member |
member_node | a JsonNode containing the `member_name` value |
user_data | data passed to the function |

Since: 0.8

### json_object_foreach_member ()

    void
    json_object_foreach_member (JsonObject *object,
                                JsonObjectForeach func,
                                gpointer data);

Iterates over all members of `object` and calls `func` on each one of them.

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

#### Parameters

object | a JsonObject |
func | the function to be called on each member. | [scope call]
data | data to be passed to the function. | [closure]

Since: 0.8

### json_object_iter_init ()

    void
    json_object_iter_init (JsonObjectIter *iter,
                           JsonObject *object);

Initialise the `iter` and associate it with `object` .

    1
    2
    3
    4
    5
    6
    7
    8
    9
    JsonObjectIter iter;
    const gchar *member_name;
    JsonNode *member_node;

    json_object_iter_init (&iter, some_object);
    while (json_object_iter_next (&iter, &member_name, &member_node))
      {
        // Do something with @member_name and @member_node.
      }

#### Parameters

iter | an uninitialised JsonObjectIter |
object | the JsonObject to iterate over |

Since: 1.2

### json_object_iter_next ()

    gboolean
    json_object_iter_next (JsonObjectIter *iter,
                           const gchar **member_name,
                           JsonNode **member_node);

Advance `iter` and retrieve the next member in the object. If the end of the object is reached, `FALSE` is returned and `member_name` and `member_node` are set to invalid values. After that point, the `iter` is invalid.

The order in which members are returned by the iterator is undefined. The iterator is invalidated if its JsonObject is modified during iteration.

#### Parameters

iter | a JsonObjectIter |
member_name | return location for the member name, or `NULL` to ignore. | [out callee-allocates][transfer none][optional]
member_node | return location for the member value, or `NULL` to ignore. | [out callee-allocates][transfer none][optional]

#### Returns

`TRUE` if `member_name` and `member_node` are valid; `FALSE` if the end of the object has been reached

Since: 1.2

### json_object_set_array_member ()

    void
    json_object_set_array_member (JsonObject *object,
                                  const gchar *member_name,
                                  JsonArray *value);

Convenience function for setting an array `value` of `member_name` inside `object` .

The `object` will take ownership of the passed JsonArray

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |
value | the value of the member. | [transfer full]

Since: 0.8

### json_object_get_array_member ()

    JsonArray *
    json_object_get_array_member (JsonObject *object,
                                  const gchar *member_name);

Convenience function that retrieves the array stored in `member_name` of `object`

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

the array inside the object's member.

[transfer none]

Since: 0.8

### json_object_set_boolean_member ()

    void
    json_object_set_boolean_member (JsonObject *object,
                                    const gchar *member_name,
                                    gboolean value);

Convenience function for setting a boolean `value` of `member_name` inside `object` .

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |
value | the value of the member |

Since: 0.8

### json_object_get_boolean_member ()

    gboolean
    json_object_get_boolean_member (JsonObject *object,
                                    const gchar *member_name);

Convenience function that retrieves the boolean value stored in `member_name` of `object`

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

the boolean value of the object's member

Since: 0.8

### json_object_set_double_member ()

    void
    json_object_set_double_member (JsonObject *object,
                                   const gchar *member_name,
                                   gdouble value);

Convenience function for setting a floating point `value` of `member_name` inside `object` .

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |
value | the value of the member |

Since: 0.8

### json_object_get_double_member ()

    gdouble
    json_object_get_double_member (JsonObject *object,
                                   const gchar *member_name);

Convenience function that retrieves the floating point value stored in `member_name` of `object`

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

the floating point value of the object's member

Since: 0.8

### json_object_set_int_member ()

    void
    json_object_set_int_member (JsonObject *object,
                                const gchar *member_name,
                                gint64 value);

Convenience function for setting an integer `value` of `member_name` inside `object` .

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |
value | the value of the member |

Since: 0.8

### json_object_get_int_member ()

    gint64
    json_object_get_int_member (JsonObject *object,
                                const gchar *member_name);

Convenience function that retrieves the integer value stored in `member_name` of `object`

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

the integer value of the object's member

Since: 0.8

### json_object_set_null_member ()

    void
    json_object_set_null_member (JsonObject *object,
                                 const gchar *member_name);

Convenience function for setting a null `value` of `member_name` inside `object` .

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

Since: 0.8

### json_object_get_null_member ()

    gboolean
    json_object_get_null_member (JsonObject *object,
                                 const gchar *member_name);

Convenience function that checks whether the value stored in `member_name` of `object` is null

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

`TRUE` if the value is null

Since: 0.8

### json_object_set_object_member ()

    void
    json_object_set_object_member (JsonObject *object,
                                   const gchar *member_name,
                                   JsonObject *value);

Convenience function for setting an object `value` of `member_name` inside `object` .

The `object` will take ownership of the passed JsonObject

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |
value | the value of the member. | [transfer full]

Since: 0.8

### json_object_get_object_member ()

    JsonObject *
    json_object_get_object_member (JsonObject *object,
                                   const gchar *member_name);

Convenience function that retrieves the object stored in `member_name` of `object` . It is an error to specify a `member_name` which does not exist.

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

the object inside the object’s member, or `NULL` if the value for the member is `null`.

[transfer none][nullable]

Since: 0.8

### json_object_set_string_member ()

    void
    json_object_set_string_member (JsonObject *object,
                                   const gchar *member_name,
                                   const gchar *value);

Convenience function for setting a string `value` of `member_name` inside `object` .

See also: `json_object_set_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |
value | the value of the member |

Since: 0.8

### json_object_get_string_member ()

    const gchar *
    json_object_get_string_member (JsonObject *object,
                                   const gchar *member_name);

Convenience function that retrieves the string value stored in `member_name` of `object`

See also: `json_object_get_member()`

#### Parameters

object | a JsonObject |
member_name | the name of the member |

#### Returns

the string value of the object's member

Since: 0.8

## Types and Values

### JsonObject

    typedef struct _JsonObject JsonObject;

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

### JsonObjectIter

    typedef struct {
    } JsonObjectIter;

An iterator used to iterate over the members of a JsonObject. This must be allocated on the stack and initialised using `json_object_iter_init()`. The order in which members are returned by the iterator is undefined. The iterator is invalidated if its JsonObject is modified during iteration.

All the fields in the JsonObjectIter structure are private and should never be accessed directly.

Since: 1.2