MACSio  0.9
Multi-purpose, Application-Centric, Scalable I/O Proxy App
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
json_object_iterator.h File Reference
#include <stddef.h>

Go to the source code of this file.

Data Structures

struct  json_object_iterator
 

Functions

struct json_object_iterator json_object_iter_init_default (void)
 
struct json_object_iterator json_object_iter_begin (struct json_object *obj)
 
struct json_object_iterator json_object_iter_end (const struct json_object *obj)
 
void json_object_iter_next (struct json_object_iterator *iter)
 
const char * json_object_iter_peek_name (const struct json_object_iterator *iter)
 
struct json_objectjson_object_iter_peek_value (const struct json_object_iterator *iter)
 
json_bool json_object_iter_equal (const struct json_object_iterator *iter1, const struct json_object_iterator *iter2)
 

Data Structure Documentation

struct json_object_iterator

The opaque iterator that references a name/value pair within a JSON Object instance or the "end" iterator value.

Definition at line 41 of file json_object_iterator.h.

Data Fields
const void * opaque_

Function Documentation

struct json_object_iterator json_object_iter_init_default ( void  )

Initializes an iterator structure to a "default" value that is convenient for initializing an iterator variable to a default state (e.g., initialization list in a class' constructor).

1 struct json_object_iterator iter = json_object_iter_init_default();
2 MyClass() : iter_(json_object_iter_init_default())
Note
The initialized value doesn't reference any specific pair, is considered an invalid iterator, and MUST NOT be passed to any json-c API that expects a valid iterator.
User and internal code MUST NOT make any assumptions about and dependencies on the value of the "default" iterator value.
Returns
json_object_iterator

Note
Make this a negative, invalid value, such that accidental access to it would likely be trapped by the hardware as an invalid address.

Definition at line 156 of file json_object_iterator.c.

struct json_object_iterator json_object_iter_begin ( struct json_object obj)

Retrieves an iterator to the first pair of the JSON Object.

Warning
Any modification of the underlying pair invalidates all iterators to that pair.
Parameters
objJSON Object instance (MUST be of type json_object)
Returns
json_object_iterator If the JSON Object has at least one pair, on return, the iterator refers to the first pair. If the JSON Object doesn't have any pairs, the returned iterator is equivalent to the "end" iterator for the same JSON Object instance.
1 struct json_object_iterator it;
2 struct json_object_iterator itEnd;
3 struct json_object* obj;
4 
5 obj = json_tokener_parse("{'first':'george', 'age':100}");
6 it = json_object_iter_begin(obj);
7 itEnd = json_object_iter_end(obj);
8 
9 while (!json_object_iter_equal(&it, &itEnd)) {
10  printf("%s\n",
11  json_object_iter_peek_name(&it));
12  json_object_iter_next(&it);
13 }

Note
json_object_get_object will return NULL if passed NULL or a non-json_type_object instance
For a pair-less Object, head is NULL, which matches our definition of the "end" iterator

Definition at line 67 of file json_object_iterator.c.

struct json_object_iterator json_object_iter_end ( const struct json_object obj)

Retrieves the iterator that represents the position beyond the last pair of the given JSON Object instance.

Warning
Do NOT write code that assumes that the "end" iterator value is NULL, even if it is so in a particular instance of the implementation.
Note
The reason we do not (and MUST NOT) provide "json_object_iter_is_end(json_object_iterator* iter)" type of API is because it would limit the underlying representation of name/value containment (or force us to add additional, otherwise unnecessary, fields to the iterator structure). The "end" iterator and the equality test method, on the other hand, permit us to cleanly abstract pretty much any reasonable underlying representation without burdening the iterator structure with unnecessary data.
For performance reasons, memorize the "end" iterator prior to any loop.
Parameters
objJSON Object instance (MUST be of type json_object)
Returns
json_object_iterator On return, the iterator refers to the "end" of the Object instance's pairs (i.e., NOT the last pair, but "beyond the last pair" value)

Definition at line 87 of file json_object_iterator.c.

void json_object_iter_next ( struct json_object_iterator iter)

Returns an iterator to the next pair, if any

Warning
Any modification of the underlying pair invalidates all iterators to that pair.
Parameters
iter[IN/OUT] Pointer to iterator that references a name/value pair; MUST be a valid, non-end iterator. WARNING: bad things will happen if invalid or "end" iterator is passed. Upon return will contain the reference to the next pair if there is one; if there are no more pairs, will contain the "end" iterator value, which may be compared against the return value of json_object_iter_end() for the same JSON Object instance.

Definition at line 103 of file json_object_iterator.c.

const char* json_object_iter_peek_name ( const struct json_object_iterator iter)

Returns a const pointer to the name of the pair referenced by the given iterator.

Parameters
iterpointer to iterator that references a name/value pair; MUST be a valid, non-end iterator.
Warning
bad things will happen if an invalid or "end" iterator is passed.
Returns
const char* Pointer to the name of the referenced name/value pair. The name memory belongs to the name/value pair, will be freed when the pair is deleted or modified, and MUST NOT be modified or freed by the user.

Definition at line 116 of file json_object_iterator.c.

struct json_object* json_object_iter_peek_value ( const struct json_object_iterator iter)

Returns a pointer to the json-c instance representing the value of the referenced name/value pair, without altering the instance's reference count.

Parameters
iterpointer to iterator that references a name/value pair; MUST be a valid, non-end iterator.
Warning
bad things will happen if invalid or "end" iterator is passed.
Returns
struct json_object* Pointer to the json-c value instance of the referenced name/value pair; the value's reference count is not changed by this function: if you plan to hold on to this json-c node, take a look at json_object_get() and json_object_put(). IMPORTANT: json-c API represents the JSON Null value as a NULL json_object instance pointer.

Definition at line 129 of file json_object_iterator.c.

json_bool json_object_iter_equal ( const struct json_object_iterator iter1,
const struct json_object_iterator iter2 
)

Tests two iterators for equality. Typically used to test for end of iteration by comparing an iterator to the corresponding "end" iterator (that was derived from the same JSON Object instance).

Note
The reason we do not (and MUST NOT) provide "json_object_iter_is_end(json_object_iterator* iter)" type of API is because it would limit the underlying representation of name/value containment (or force us to add additional, otherwise unnecessary, fields to the iterator structure). The equality test method, on the other hand, permits us to cleanly abstract pretty much any reasonable underlying representation.
Parameters
iter1Pointer to first valid, non-NULL iterator
iter2POinter to second valid, non-NULL iterator
Warning
if a NULL iterator pointer or an uninitialized or invalid iterator, or iterators derived from different JSON Object instances are passed, bad things will happen!
Returns
json_bool non-zero if iterators are equal (i.e., both reference the same name/value pair or are both at "end"); zero if they are not equal.

Definition at line 142 of file json_object_iterator.c.