json_object_iterator.h File Reference

An API for iterating over json_type_object objects, styled to be familiar to C++ programmers. Unlike json_object_object_foreach() and json_object_object_foreachC(), this avoids the need to expose json-c internals like lh_entry. More...

## Data Structures

struct | json_object_iterator

## Functions

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

## Detailed Description

An API for iterating over json_type_object objects, styled to be familiar to C++ programmers. Unlike json_object_object_foreach() and json_object_object_foreachC(), this avoids the need to expose json-c internals like lh_entry.

Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P. Copyright (c) 2026 Eric Hawicz

This library is free software; you can redistribute it and/or modify it under the terms of the MIT license. See COPYING for details.

API attributes:

- Thread-safe: NO
- Reentrant: NO

## Function Documentation

## json_object_iter_begin()

JSON_EXPORT struct json_object_iterator json_object_iter_begin | ( | struct json_object * | obj | ) |

Retrieves an iterator to the first key/value pair of the JSON Object.

Warning
  Any modification of the fields present on the object invalidates all iterators on that object, regardless of what key/value pair they are pointing to, other than the end iterator. Modifications include adding or removing any pair, even if set of keys appears unchanged after the modification. Modifying values is allowed, including replacing a value by calling json_object_add(), provided the key already exists. Attempting to use an invalidated iterator in any way, other than comparing it to the end iterator, is undefined behavior. Passing such an iterator to any of the the json_object_iterator functions is not even guaranteed to fail in any consistent way.

Parameters

  obj | JSON 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.

struct json_object_iterator it;
struct json_object_iterator itEnd;
struct json_object* obj;
obj = json_tokener_parse("{'first':'george', 'age':100}");
it = json_object_iter_begin(obj);
itEnd = json_object_iter_end(obj);
while (!json_object_iter_equal(&it, &itEnd)) {
printf("%s\n",
json_object_iter_peek_name(&it));
json_object_iter_next(&it);
}
json_object_iter_end
JSON_EXPORT struct json_object_iterator json_object_iter_end(const struct json_object *obj)
json_object_iter_next
JSON_EXPORT void json_object_iter_next(struct json_object_iterator *iter)
json_object_iter_equal
JSON_EXPORT json_bool json_object_iter_equal(const struct json_object_iterator *iter1, const struct json_object_iterator *iter2)
json_object_iter_peek_name
JSON_EXPORT const char * json_object_iter_peek_name(const struct json_object_iterator *iter)
json_object_iter_begin
JSON_EXPORT struct json_object_iterator json_object_iter_begin(struct json_object *obj)
json_tokener_parse
JSON_EXPORT struct json_object * json_tokener_parse(const char *str)
json_object
struct json_object json_object
The core type for all type of JSON objects handled by json-c.
Definition json_types.h:47
json_object_iterator
Definition json_object_iterator.h:39

References JSON_EXPORT, and json_object_iter_begin().

Referenced by json_object_iter_begin().

## json_object_iter_end()

JSON_EXPORT 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

  obj | JSON 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)

References JSON_EXPORT, and json_object_iter_end().

Referenced by json_object_iter_end().

## json_object_iter_equal()

JSON_EXPORT 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

  iter1 | Pointer to first valid, non-NULL iterator
  iter2 | POinter 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.

References JSON_EXPORT.

## json_object_iter_init_default()

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

struct json_object_iterator iter = json_object_iter_init_default();
MyClass() : iter_(json_object_iter_init_default())
json_object_iter_init_default
JSON_EXPORT struct json_object_iterator json_object_iter_init_default(void)

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

References JSON_EXPORT, and json_object_iter_init_default().

Referenced by json_object_iter_init_default().

## json_object_iter_next()

JSON_EXPORT void json_object_iter_next | ( | struct json_object_iterator * | iter | ) |

Returns an iterator to the next pair, if any

Warning
  Any modification of the fields of the object invalidates the iterator, see the warning on json_object_iter_begin() for details.

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.

References JSON_EXPORT.

## json_object_iter_peek_name()

JSON_EXPORT 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

  iter | pointer 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. See the warning on json_object_iter_begin() for details.

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.

References JSON_EXPORT.

## json_object_iter_peek_value()

JSON_EXPORT 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

  iter | pointer 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. See the warning on json_object_iter_begin() for details.

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.