JsonReader

JsonReader — A cursor-based parser

Synopsis

struct              JsonReader;
struct              JsonReaderClass;
JsonReader *        json_reader_new                     (JsonNode *node);
void                json_reader_set_root                (JsonReader *reader,
                                                         JsonNode *root);

gboolean            json_reader_read_element            (JsonReader *reader,
                                                         guint index_);
void                json_reader_end_element             (JsonReader *reader);
gboolean            json_reader_is_array                (JsonReader *reader);
gint                json_reader_count_elements          (JsonReader *reader);

gboolean            json_reader_read_member             (JsonReader *reader,
                                                         const gchar *member_name);
void                json_reader_end_member              (JsonReader *reader);
gboolean            json_reader_is_object               (JsonReader *reader);
gint                json_reader_count_members           (JsonReader *reader);
gchar **            json_reader_list_members            (JsonReader *reader);
const gchar *       json_reader_get_member_name         (JsonReader *reader);

gboolean            json_reader_is_value                (JsonReader *reader);
JsonNode *          json_reader_get_value               (JsonReader *reader);
gint64              json_reader_get_int_value           (JsonReader *reader);
gdouble             json_reader_get_double_value        (JsonReader *reader);
const gchar *       json_reader_get_string_value        (JsonReader *reader);
gboolean            json_reader_get_boolean_value       (JsonReader *reader);
gboolean            json_reader_get_null_value          (JsonReader *reader);

enum                JsonReaderError;
#define             JSON_READER_ERROR
const GError *      json_reader_get_error               (JsonReader *reader);

Object Hierarchy

  GObject
   +----JsonReader

Properties

  "root"                     JsonNode*             : Read / Write / Construct

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
11
12
 
/* 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
8
 
/* 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.

Details

struct JsonReader

struct JsonReader;

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

Since 0.12

struct JsonReaderClass

struct JsonReaderClass {
};

The JsonReaderClass structure contains only private data

Since 0.12

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

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.

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.

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

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

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

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_element (reader);

json_reader_read_element (reader, "title");
title = json_reader_get_string_value (reader);
json_reader_end_element (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.

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

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

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

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.

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.

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

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

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

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

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

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

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'

reader :

 a JsonReader

Returns :

 TRUE if 'null' is set, and FALSE otherwise

Since 0.12

enum JsonReaderError

typedef enum {
  JSON_READER_ERROR_NO_ARRAY,
  JSON_READER_ERROR_INVALID_INDEX,
  JSON_READER_ERROR_NO_OBJECT,
  JSON_READER_ERROR_INVALID_MEMBER,
  JSON_READER_ERROR_INVALID_NODE,
  JSON_READER_ERROR_NO_VALUE,
  JSON_READER_ERROR_INVALID_TYPE
} JsonReaderError;

Error codes enumeration for JsonReader errors

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

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

reader :

 a JsonReader

Returns :

 the pointer to the error, or NULL. [transfer none]

Since 0.12

Property Details

The "root" property

  "root"                     JsonNode*             : Read / Write / Construct

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

Since 0.12

Generated by GTK-Doc V1.18.1