json_object_iterator.h

   1 /**
   2 *******************************************************************************
   3 * @file json_object_iterator.h
   4 *
   5 * Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P.
   6 *
   7 * This library is free software; you can redistribute it and/or modify
   8 * it under the terms of the MIT license. See COPYING for details.
   9 *
  10 * @brief  json-c forces clients to use its private data
  11 *         structures for JSON Object iteration.  This API
  12 *         corrects that by abstracting the private json-c
  13 *         details.
  14 *
  15 * API attributes: <br>
  16 *   * Thread-safe: NO<br>
  17 *   * Reentrant: NO
  18 *
  19 *******************************************************************************
  20 */
  21
  22
  23 #ifndef JSON_OBJECT_ITERATOR_H
  24 #define JSON_OBJECT_ITERATOR_H
  25
  26 #include <stddef.h>
  27
  28 #ifdef __cplusplus
  29 extern "C" {
  30 #endif
  31
  32 /**
  33  * Forward declaration for the opaque iterator information.
  34  */
  35 struct json_object_iter_info_;
  36
  37 /**
  38  * The opaque iterator that references a name/value pair within
  39  * a JSON Object instance or the "end" iterator value.
  40  */
  41 struct json_object_iterator {
  42     const void* opaque_;
  43 };
  44
  45
  46 /**
  47  * forward declaration of json-c's JSON value instance structure
  48  */
  49 struct json_object;
  50
  51
  52 /**
  53  * Initializes an iterator structure to a "default" value that
  54  * is convenient for initializing an iterator variable to a
  55  * default state (e.g., initialization list in a class'
  56  * constructor).
  57  *
  58  * @code
  59  * struct json_object_iterator iter = json_object_iter_init_default();
  60  * MyClass() : iter_(json_object_iter_init_default())
  61  * @endcode
  62  *
  63  * @note The initialized value doesn't reference any specific
  64  *       pair, is considered an invalid iterator, and MUST NOT
  65  *       be passed to any json-c API that expects a valid
  66  *       iterator.
  67  *
  68  * @note User and internal code MUST NOT make any assumptions
  69  *       about and dependencies on the value of the "default"
  70  *       iterator value.
  71  *
  72  * @return json_object_iterator
  73  */
  74 struct json_object_iterator
  75 json_object_iter_init_default(void);
  76
  77 /** Retrieves an iterator to the first pair of the JSON Object.
  78  *
  79  * @warning     Any modification of the underlying pair invalidates all
  80  *              iterators to that pair.
  81  *
  82  * @param obj   JSON Object instance (MUST be of type json_object)
  83  *
  84  * @return json_object_iterator If the JSON Object has at
  85  *              least one pair, on return, the iterator refers
  86  *              to the first pair. If the JSON Object doesn't
  87  *              have any pairs, the returned iterator is
  88  *              equivalent to the "end" iterator for the same
  89  *              JSON Object instance.
  90  *
  91  * @code
  92  * struct json_object_iterator it;
  93  * struct json_object_iterator itEnd;
  94  * struct json_object* obj;
  95  *
  96  * obj = json_tokener_parse("{'first':'george', 'age':100}");
  97  * it = json_object_iter_begin(obj);
  98  * itEnd = json_object_iter_end(obj);
  99  *
 100  * while (!json_object_iter_equal(&it, &itEnd)) {
 101  *     printf("%s\n",
 102  *            json_object_iter_peek_name(&it));
 103  *     json_object_iter_next(&it);
 104  * }
 105  *
 106  * @endcode
 107  */
 108 struct json_object_iterator
 109 json_object_iter_begin(struct json_object* obj);
 110
 111 /** Retrieves the iterator that represents the position beyond the
 112  *  last pair of the given JSON Object instance.
 113  *
 114  *  @warning Do NOT write code that assumes that the "end"
 115  *        iterator value is NULL, even if it is so in a
 116  *        particular instance of the implementation.
 117  *
 118  *  @note The reason we do not (and MUST NOT) provide
 119  *        "json_object_iter_is_end(json_object_iterator* iter)"
 120  *        type of API is because it would limit the underlying
 121  *        representation of name/value containment (or force us
 122  *        to add additional, otherwise unnecessary, fields to
 123  *        the iterator structure). The "end" iterator and the
 124  *        equality test method, on the other hand, permit us to
 125  *        cleanly abstract pretty much any reasonable underlying
 126  *        representation without burdening the iterator
 127  *        structure with unnecessary data.
 128  *
 129  *  @note For performance reasons, memorize the "end" iterator prior
 130  *        to any loop.
 131  *
 132  * @param obj JSON Object instance (MUST be of type json_object)
 133  *
 134  * @return json_object_iterator On return, the iterator refers
 135  *              to the "end" of the Object instance's pairs
 136  *              (i.e., NOT the last pair, but "beyond the last
 137  *              pair" value)
 138  */
 139 struct json_object_iterator
 140 json_object_iter_end(const struct json_object* obj);
 141
 142 /** Returns an iterator to the next pair, if any
 143  *
 144  * @warning     Any modification of the underlying pair
 145  *              invalidates all iterators to that pair.
 146  *
 147  * @param iter [IN/OUT] Pointer to iterator that references a
 148  *         name/value pair; MUST be a valid, non-end iterator.
 149  *         WARNING: bad things will happen if invalid or "end"
 150  *         iterator is passed. Upon return will contain the
 151  *         reference to the next pair if there is one; if there
 152  *         are no more pairs, will contain the "end" iterator
 153  *         value, which may be compared against the return value
 154  *         of json_object_iter_end() for the same JSON Object
 155  *         instance.
 156  */
 157 void
 158 json_object_iter_next(struct json_object_iterator* iter);
 159
 160
 161 /** Returns a const pointer to the name of the pair referenced
 162  *  by the given iterator.
 163  *
 164  * @param iter pointer to iterator that references a name/value
 165  *             pair; MUST be a valid, non-end iterator.
 166  *
 167  * @warning     bad things will happen if an invalid or
 168  *              "end" iterator is passed.
 169  *
 170  * @return const char* Pointer to the name of the referenced
 171  *         name/value pair.  The name memory belongs to the
 172  *         name/value pair, will be freed when the pair is
 173  *         deleted or modified, and MUST NOT be modified or
 174  *         freed by the user.
 175  */
 176 const char*
 177 json_object_iter_peek_name(const struct json_object_iterator* iter);
 178
 179
 180 /** Returns a pointer to the json-c instance representing the
 181  *  value of the referenced name/value pair, without altering
 182  *  the instance's reference count.
 183  *
 184  * @param iter  pointer to iterator that references a name/value
 185  *              pair; MUST be a valid, non-end iterator.
 186  *
 187  * @warning     bad things will happen if invalid or
 188  *             "end" iterator is passed.
 189  *
 190  * @return struct json_object* Pointer to the json-c value
 191  *         instance of the referenced name/value pair;  the
 192  *         value's reference count is not changed by this
 193  *         function: if you plan to hold on to this json-c node,
 194  *         take a look at json_object_get() and
 195  *         json_object_put(). IMPORTANT: json-c API represents
 196  *         the JSON Null value as a NULL json_object instance
 197  *         pointer.
 198  */
 199 struct json_object*
 200 json_object_iter_peek_value(const struct json_object_iterator* iter);
 201
 202
 203 /** Tests two iterators for equality.  Typically used to test
 204  *  for end of iteration by comparing an iterator to the
 205  *  corresponding "end" iterator (that was derived from the same
 206  *  JSON Object instance).
 207  *
 208  *  @note The reason we do not (and MUST NOT) provide
 209  *        "json_object_iter_is_end(json_object_iterator* iter)"
 210  *        type of API is because it would limit the underlying
 211  *        representation of name/value containment (or force us
 212  *        to add additional, otherwise unnecessary, fields to
 213  *        the iterator structure). The equality test method, on
 214  *        the other hand, permits us to cleanly abstract pretty
 215  *        much any reasonable underlying representation.
 216  *
 217  * @param iter1 Pointer to first valid, non-NULL iterator
 218  * @param iter2 POinter to second valid, non-NULL iterator
 219  *
 220  * @warning     if a NULL iterator pointer or an uninitialized
 221  *              or invalid iterator, or iterators derived from
 222  *              different JSON Object instances are passed, bad things
 223  *              will happen!
 224  *
 225  * @return json_bool non-zero if iterators are equal (i.e., both
 226  *         reference the same name/value pair or are both at
 227  *         "end"); zero if they are not equal.
 228  */
 229 json_bool
 230 json_object_iter_equal(const struct json_object_iterator* iter1,
 231                        const struct json_object_iterator* iter2);
 232
 233
 234 #ifdef __cplusplus
 235 }
 236 #endif
 237
 238
 239 #endif // JSON_OBJECT_ITERATOR_H