JsonBuilder

JsonBuilder — Generates JSON trees

Synopsis

#include <json-glib/json-glib.h>

struct              JsonBuilder;
struct              JsonBuilderClass;
JsonBuilder *       json_builder_new                    (void);
JsonBuilder *       json_builder_new_immutable          (void);
JsonNode *          json_builder_get_root               (JsonBuilder *builder);
void                json_builder_reset                  (JsonBuilder *builder);

JsonBuilder *       json_builder_begin_array            (JsonBuilder *builder);
JsonBuilder *       json_builder_end_array              (JsonBuilder *builder);
JsonBuilder *       json_builder_begin_object           (JsonBuilder *builder);
JsonBuilder *       json_builder_set_member_name        (JsonBuilder *builder,
                                                         const gchar *member_name);
JsonBuilder *       json_builder_end_object             (JsonBuilder *builder);

JsonBuilder *       json_builder_add_value              (JsonBuilder *builder,
                                                         JsonNode *node);
JsonBuilder *       json_builder_add_int_value          (JsonBuilder *builder,
                                                         gint64 value);
JsonBuilder *       json_builder_add_double_value       (JsonBuilder *builder,
                                                         gdouble value);
JsonBuilder *       json_builder_add_boolean_value      (JsonBuilder *builder,
                                                         gboolean value);
JsonBuilder *       json_builder_add_string_value       (JsonBuilder *builder,
                                                         const gchar *value);
JsonBuilder *       json_builder_add_null_value         (JsonBuilder *builder);

Object Hierarchy

  GObject
   +----JsonBuilder

Properties

  "immutable"                gboolean              : Read / Write / Construct Only

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.

Details

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


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

builder :

a JsonBuilder

Returns :

the JsonNode, or NULL if the build is not complete. Free the returned value with json_node_unref(). [nullable][transfer full]

json_builder_reset ()

void                json_builder_reset                  (JsonBuilder *builder);

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

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.

builder :

a JsonBuilder

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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().

builder :

a JsonBuilder

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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.

builder :

a JsonBuilder

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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.

builder :

a JsonBuilder

member_name :

the name of the member

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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().

builder :

a JsonBuilder

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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.

builder :

a JsonBuilder

node :

the value of the member or element. [transfer full]

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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()

builder :

a JsonBuilder

value :

the value of the member or element

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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()

builder :

a JsonBuilder

value :

the value of the member or element

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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()

builder :

a JsonBuilder

value :

the value of the member or element

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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()

builder :

a JsonBuilder

value :

the value of the member or element

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][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()

builder :

a JsonBuilder

Returns :

the JsonBuilder, or NULL if the call was inconsistent. [nullable][transfer none]

Property Details

The "immutable" property

  "immutable"                gboolean              : Read / Write / Construct Only

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.

Default value: FALSE

Since 1.2

See Also

JsonGenerator