JSON-GLib Reference Manual: JsonReader

## JsonReader JsonReader — A cursor-based parser |

## Functions

JsonReader * | json_reader_new ()
void | json_reader_set_root ()
gboolean | json_reader_read_element ()
void | json_reader_end_element ()
gboolean | json_reader_is_array ()
gint | json_reader_count_elements ()
gboolean | json_reader_read_member ()
void | json_reader_end_member ()
gboolean | json_reader_is_object ()
gint | json_reader_count_members ()
gchar ** | json_reader_list_members ()
const gchar * | json_reader_get_member_name ()
gboolean | json_reader_is_value ()
JsonNode * | json_reader_get_value ()
gint64 | json_reader_get_int_value ()
gdouble | json_reader_get_double_value ()
const gchar * | json_reader_get_string_value ()
gboolean | json_reader_get_boolean_value ()
gboolean | json_reader_get_null_value ()
#define | JSON_READER_ERROR
const GError * | json_reader_get_error ()

## Properties

JsonNode * | root | Read / Write / Construct

## Types and Values

struct | JsonReader
struct | JsonReaderClass
enum | JsonReaderError

## Object Hierarchy

        GObject
        ╰── JsonReader

## Description

JsonReader provides a simple, cursor-based API for parsing a JSON DOM. It is similar, in spirit, to the XML Reader API.

In case of error, JsonReader will be set in an error state; all subsequent calls will simply be ignored until a function that resets the error state is called, e.g.:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    // ask for the 7th element; if the element does not exist, the
    // reader will be put in an error state
    json_reader_read_element (reader, 6);

    // in case of error, this will return NULL, otherwise it will
    // return the value of the element
    str = json_reader_get_string_value (value);

    // this function resets the error state if any was set
    json_reader_end_element (reader);

If you want to detect the error state as soon as possible, you can use `json_reader_get_error()`:

    1
    2
    3
    4
    5
    6
    7
    // like the example above, but in this case we print out the
    // error immediately
    if (!json_reader_read_element (reader, 6))
      {
        const GError *error = json_reader_get_error (reader);
        g_print ("Unable to read the element: %s", error->message);
      }

JsonReader is available since JSON-GLib 0.12.

## Functions

### json_reader_new ()

    JsonReader *
    json_reader_new (JsonNode *node);

Creates a new JsonReader. You can use this object to read the contents of the JSON tree starting from `node`

#### Parameters

node | a JsonNode, or `NULL`. | [allow-none]

#### Returns

the newly created JsonReader. Use `g_object_unref()` to release the allocated resources when done

Since 0.12

### json_reader_set_root ()

    void
    json_reader_set_root (JsonReader *reader,
                          JsonNode *root);

Sets the root JsonNode to be read by `reader` . The `reader` will take a copy of `root`

If another JsonNode is currently set as root, it will be replaced.

#### Parameters

reader | a JsonReader |
root | a JsonNode. | [allow-none]

Since 0.12

### json_reader_read_element ()

    gboolean
    json_reader_read_element (JsonReader *reader,
                              guint index_);

Advances the cursor of `reader` to the element `index_` of the array or the object at the current position.

You can use the json_reader_get_value* family of functions to retrieve the value of the element; for instance:

    1
    2
    json_reader_read_element (reader, 0);
    int_value = json_reader_get_int_value (reader);

After reading the value, `json_reader_end_element()` should be called to reposition the cursor inside the JsonReader, e.g.:

    1
    2
    3
    4
    5
    6
    7
    json_reader_read_element (reader, 1);
    str_value = json_reader_get_string_value (reader);
    json_reader_end_element (reader);

    json_reader_read_element (reader, 2);
    str_value = json_reader_get_string_value (reader);
    json_reader_end_element (reader);

If `reader` is not currently on an array or an object, or if the `index_` is bigger than the size of the array or the object, the JsonReader will be put in an error state until `json_reader_end_element()` is called.

#### Parameters

reader | a JsonReader |
index_ | the index of the element |

#### Returns

`TRUE` on success, and `FALSE` otherwise

Since 0.12

### json_reader_end_element ()

    void
    json_reader_end_element (JsonReader *reader);

Moves the cursor back to the previous node after being positioned inside an array

This function resets the error state of `reader` , if any was set

#### Parameters

reader | a JsonReader |

Since 0.12

### json_reader_is_array ()

    gboolean
    json_reader_is_array (JsonReader *reader);

Checks whether the `reader` is currently on an array

#### Parameters

reader | a JsonReader |

#### Returns

`TRUE` if the JsonReader is on an array, and `FALSE` otherwise

Since 0.12

### json_reader_count_elements ()

    gint
    json_reader_count_elements (JsonReader *reader);

Counts the elements of the current position, if `reader` is positioned on an array

#### Parameters

reader | a JsonReader |

#### Returns

the number of elements, or -1. In case of failure the JsonReader is set in an error state

Since 0.12

### json_reader_read_member ()

    gboolean
    json_reader_read_member (JsonReader *reader,
                             const gchar *member_name);

Advances the cursor of `reader` to the `member_name` of the object at the current position.

You can use the json_reader_get_value* family of functions to retrieve the value of the member; for instance:

    1
    2
    json_reader_read_member (reader, "width");
    width = json_reader_get_int_value (reader);

After reading the value, `json_reader_end_member()` should be called to reposition the cursor inside the JsonReader, e.g.:

    1
    2
    3
    4
    5
    6
    7
    json_reader_read_member (reader, "author");
    author = json_reader_get_string_value (reader);
    json_reader_end_member (reader);

    json_reader_read_member (reader, "title");
    title = json_reader_get_string_value (reader);
    json_reader_end_member (reader);

If `reader` is not currently on an object, or if the `member_name` is not defined in the object, the JsonReader will be put in an error state until `json_reader_end_member()` is called.

#### Parameters

reader | a JsonReader |
member_name | the name of the member to read |

#### Returns

`TRUE` on success, and `FALSE` otherwise

Since 0.12

### json_reader_end_member ()

    void
    json_reader_end_member (JsonReader *reader);

Moves the cursor back to the previous node after being positioned inside an object

This function resets the error state of `reader` , if any was set

#### Parameters

reader | a JsonReader |

Since 0.12

### json_reader_is_object ()

    gboolean
    json_reader_is_object (JsonReader *reader);

Checks whether the `reader` is currently on an object

#### Parameters

reader | a JsonReader |

#### Returns

`TRUE` if the JsonReader is on an object, and `FALSE` otherwise

Since 0.12

### json_reader_count_members ()

    gint
    json_reader_count_members (JsonReader *reader);

Counts the members of the current position, if `reader` is positioned on an object

#### Parameters

reader | a JsonReader |

#### Returns

the number of members, or -1. In case of failure the JsonReader is set in an error state

Since 0.12

### json_reader_list_members ()

    gchar **
    json_reader_list_members (JsonReader *reader);

Retrieves a list of member names from the current position, if `reader` is positioned on an object.

#### Parameters

reader | a JsonReader |

#### Returns

a newly allocated, `NULL`-terminated array of strings holding the members name. Use `g_strfreev()` when done.

[transfer full]

Since 0.14

### json_reader_get_member_name ()

    const gchar *
    json_reader_get_member_name (JsonReader *reader);

Retrieves the name of the current member.

#### Parameters

reader | a JsonReader |

#### Returns

the name of the member, or `NULL`.

[transfer none]

Since 0.14

### json_reader_is_value ()

    gboolean
    json_reader_is_value (JsonReader *reader);

Checks whether the `reader` is currently on a value

#### Parameters

reader | a JsonReader |

#### Returns

`TRUE` if the JsonReader is on a value, and `FALSE` otherwise

Since 0.12

### json_reader_get_value ()

    JsonNode *
    json_reader_get_value (JsonReader *reader);

Retrieves the JsonNode of the current position of `reader`

#### Parameters

reader | a JsonReader |

#### Returns

a JsonNode, or `NULL`. The returned node is owned by the JsonReader and it should not be modified or freed directly.

[transfer none]

Since 0.12

### json_reader_get_int_value ()

    gint64
    json_reader_get_int_value (JsonReader *reader);

Retrieves the integer value of the current position of `reader`

#### Parameters

reader | a JsonReader |

#### Returns

the integer value

Since 0.12

### json_reader_get_double_value ()

    gdouble
    json_reader_get_double_value (JsonReader *reader);

Retrieves the floating point value of the current position of `reader`

#### Parameters

reader | a JsonReader |

#### Returns

the floating point value

Since 0.12

### json_reader_get_string_value ()

    const gchar *
    json_reader_get_string_value (JsonReader *reader);

Retrieves the string value of the current position of `reader`

#### Parameters

reader | a JsonReader |

#### Returns

the string value

Since 0.12

### json_reader_get_boolean_value ()

    gboolean
    json_reader_get_boolean_value (JsonReader *reader);

Retrieves the boolean value of the current position of `reader`

#### Parameters

reader | a JsonReader |

#### Returns

the boolean value

Since 0.12

### json_reader_get_null_value ()

    gboolean
    json_reader_get_null_value (JsonReader *reader);

Checks whether the value of the current position of `reader` is 'null'

#### Parameters

reader | a JsonReader |

#### Returns

`TRUE` if 'null' is set, and `FALSE` otherwise

Since 0.12

### JSON_READER_ERROR

    #define JSON_READER_ERROR               (json_reader_error_quark ())

Error domain for JsonReader errors

Since 0.12

### json_reader_get_error ()

    const GError *
    json_reader_get_error (JsonReader *reader);

Retrieves the GError currently set on `reader` , if the JsonReader is in error state

#### Parameters

reader | a JsonReader |

#### Returns

the pointer to the error, or `NULL`.

[transfer none]

Since 0.12

## Types and Values

### struct JsonReader

    struct JsonReader;

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

Since 0.12

### struct JsonReaderClass

    struct JsonReaderClass {
    };

The `JsonReaderClass` structure contains only private data

Since 0.12

### enum JsonReaderError

Error codes enumeration for JsonReader errors

#### Members

JSON_READER_ERROR_NO_ARRAY | No array found at the current position |
JSON_READER_ERROR_INVALID_INDEX | Index out of bounds |
JSON_READER_ERROR_NO_OBJECT | No object found at the current position |
JSON_READER_ERROR_INVALID_MEMBER | Member not found |
JSON_READER_ERROR_INVALID_NODE | No valid node found at the current position |
JSON_READER_ERROR_NO_VALUE | The node at the current position does not hold a value |
JSON_READER_ERROR_INVALID_TYPE | The node at the current position does not hold a value of the desired type |

Since 0.12

## Property Details

### The `“root”` property

      “root”                     JsonNode *

The root of the JSON tree that the JsonReader should read.

Flags: Read / Write / Construct

Since 0.12