JsonReader

JsonReader — A cursor-based parser

Properties

JsonNode * root Read / Write / Construct

Types and Values

Object Hierarchy

    GObject
    ╰── JsonReader

Includes

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

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. This means that if used conditionally, json_reader_end_element() must be called on both code paths:

1
2
3
4
5
6
7
8
9
if (!json_reader_read_element (reader, 1))
  {
    json_reader_end_element (reader);
    g_set_error (error,);
    return FALSE;
  }

str_value = json_reader_get_string_value (reader);
json_reader_end_element (reader);

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. This means that if used conditionally, json_reader_end_member() must be called on both code paths:

1
2
3
4
5
6
7
8
9
if (!json_reader_read_member (reader, "title"))
  {
    json_reader_end_member (reader);
    g_set_error (error,);
    return FALSE;
  }

str_value = json_reader_get_string_value (reader);
json_reader_end_member (reader);

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


JSON_READER_ERROR

#define JSON_READER_ERROR               (json_reader_error_quark ())

Error domain for JsonReader errors

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