JsonBuilder: JSON-GLib Reference Manual

## JsonBuilder JsonBuilder — Generates JSON trees |

## Functions

JsonBuilder * | json_builder_new ()
JsonBuilder * | json_builder_new_immutable ()
JsonNode * | json_builder_get_root ()
void | json_builder_reset ()
JsonBuilder * | json_builder_begin_array ()
JsonBuilder * | json_builder_end_array ()
JsonBuilder * | json_builder_begin_object ()
JsonBuilder * | json_builder_set_member_name ()
JsonBuilder * | json_builder_end_object ()
JsonBuilder * | json_builder_add_value ()
JsonBuilder * | json_builder_add_int_value ()
JsonBuilder * | json_builder_add_double_value ()
JsonBuilder * | json_builder_add_boolean_value ()
JsonBuilder * | json_builder_add_string_value ()
JsonBuilder * | json_builder_add_null_value ()

## Properties

gboolean | immutable | Read / Write / Construct Only

## Types and Values

struct | JsonBuilder
struct | JsonBuilderClass

## Object Hierarchy

        GObject
        ╰── JsonBuilder

## Description

JsonBuilder provides an object for generating a JSON tree. You can generate only one tree with one JsonBuilder instance.

The root of the JSON tree can be either a JsonObject or a JsonArray. Thus the first call must necessarily be either `json_builder_begin_object()` or `json_builder_begin_array()`.

For convenience to language bindings, JsonBuilder returns itself from most of functions, making it easy to chain function calls.

## Functions

### json_builder_new ()

    JsonBuilder *
    json_builder_new (void);

Creates a new JsonBuilder. You can use this object to generate a JSON tree and obtain the root JsonNode.

#### Returns

the newly created JsonBuilder instance

### json_builder_new_immutable ()

    JsonBuilder *
    json_builder_new_immutable (void);

Creates a new JsonBuilder instance with its “immutable” property set to `TRUE` to create immutable output trees.

#### Returns

a new JsonBuilder.

[transfer full]

Since: 1.2

### json_builder_get_root ()

    JsonNode *
    json_builder_get_root (JsonBuilder *builder);

Returns the root of the current constructed tree, if the build is complete (ie: all opened objects, object members and arrays are being closed).

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonNode, or `NULL` if the build is not complete. Free the returned value with `json_node_unref()`.

[transfer full]

### json_builder_reset ()

    void
    json_builder_reset (JsonBuilder *builder);

Resets the state of the `builder` back to its initial state.

#### Parameters

builder | a JsonBuilder |

### json_builder_begin_array ()

    JsonBuilder *
    json_builder_begin_array (JsonBuilder *builder);

Opens a subarray inside the given `builder` . When done adding members to the subarray, `json_builder_end_array()` must be called.

Can be called for first or only if the call is associated to an object member or an array element.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_end_array ()

    JsonBuilder *
    json_builder_end_array (JsonBuilder *builder);

Closes the subarray inside the given `builder` that was opened by the most recent call to `json_builder_begin_array()`.

Cannot be called after `json_builder_set_member_name()`.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_begin_object ()

    JsonBuilder *
    json_builder_begin_object (JsonBuilder *builder);

Opens a subobject inside the given `builder` . When done adding members to the subobject, `json_builder_end_object()` must be called.

Can be called for first or only if the call is associated to an object member or an array element.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_set_member_name ()

    JsonBuilder *
    json_builder_set_member_name (JsonBuilder *builder,
                                  const gchar *member_name);

Set the name of the next member in an object. The next call must add a value, open an object or an array.

Can be called only if the call is associated to an object.

#### Parameters

builder | a JsonBuilder |
member_name | the name of the member |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_end_object ()

    JsonBuilder *
    json_builder_end_object (JsonBuilder *builder);

Closes the subobject inside the given `builder` that was opened by the most recent call to `json_builder_begin_object()`.

Cannot be called after `json_builder_set_member_name()`.

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_value ()

    JsonBuilder *
    json_builder_add_value (JsonBuilder *builder,
                            JsonNode *node);

If called after `json_builder_set_member_name()`, sets `node` as member of the most recent opened object, otherwise `node` is added as element of the most recent opened array.

The builder will take ownership of the JsonNode.

#### Parameters

builder | a JsonBuilder |
node | the value of the member or element. | [transfer full]

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_int_value ()

    JsonBuilder *
    json_builder_add_int_value (JsonBuilder *builder,
                                gint64 value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_double_value ()

    JsonBuilder *
    json_builder_add_double_value (JsonBuilder *builder,
                                   gdouble value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_boolean_value ()

    JsonBuilder *
    json_builder_add_boolean_value (JsonBuilder *builder,
                                    gboolean value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_string_value ()

    JsonBuilder *
    json_builder_add_string_value (JsonBuilder *builder,
                                   const gchar *value);

If called after `json_builder_set_member_name()`, sets `value` as member of the most recent opened object, otherwise `value` is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |
value | the value of the member or element |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

### json_builder_add_null_value ()

    JsonBuilder *
    json_builder_add_null_value (JsonBuilder *builder);

If called after `json_builder_set_member_name()`, sets null as member of the most recent opened object, otherwise null is added as element of the most recent opened array.

See also: `json_builder_add_value()`

#### Parameters

builder | a JsonBuilder |

#### Returns

the JsonBuilder, or `NULL` if the call was inconsistent.

[transfer none]

## Types and Values

### struct JsonBuilder

    struct JsonBuilder;

The `JsonBuilder` structure contains only private data and should be accessed using the provided API

Since: 0.12

### struct JsonBuilderClass

    struct JsonBuilderClass {
    };

The `JsonBuilderClass` structure contains only private data

Since: 0.12

## Property Details

### The `“immutable”` property

      “immutable”                gboolean

Whether the JsonNode tree built by the JsonBuilder should be immutable when created. Making the output immutable on creation avoids the expense of traversing it to make it immutable later.

Flags: Read / Write / Construct Only

Default value: FALSE

Since: 1.2

## See Also

JsonGenerator