Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 1 | /** |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 2 | ******************************************************************************* |
| 3 | * @file json_object_iterator.h |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 4 | * |
| 5 | * Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P. |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 9 | * |
| 10 | * @brief json-c forces clients to use its private data |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 11 | * structures for JSON Object iteration. This API |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 12 | * corrects that by abstracting the private json-c |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 13 | * details. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 14 | * |
| 15 | * API attributes: <br> |
| 16 | * * Thread-safe: NO<br> |
| 17 | * * Reentrant: NO |
| 18 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 19 | ******************************************************************************* |
| 20 | */ |
| 21 | |
| 22 | |
| 23 | #ifndef JSON_OBJECT_ITERATOR_H |
| 24 | #define JSON_OBJECT_ITERATOR_H |
| 25 | |
| 26 | #include <stddef.h> |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 27 | |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 28 | #ifdef __cplusplus |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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 |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 39 | * a JSON Object instance or the "end" iterator value. |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 40 | */ |
| 41 | struct json_object_iterator { |
| 42 | const void* opaque_; |
| 43 | }; |
| 44 | |
| 45 | |
| 46 | /** |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 47 | * forward declaration of json-c's JSON value instance structure |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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). |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 57 | * |
| 58 | * @code |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 59 | * struct json_object_iterator iter = json_object_iter_init_default(); |
| 60 | * MyClass() : iter_(json_object_iter_init_default()) |
| 61 | * @endcode |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 62 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 63 | * @note The initialized value doesn't reference any specific |
| 64 | * pair, is considered an invalid iterator, and MUST NOT |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 65 | * be passed to any json-c API that expects a valid |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 66 | * iterator. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 67 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 68 | * @note User and internal code MUST NOT make any assumptions |
| 69 | * about and dependencies on the value of the "default" |
| 70 | * iterator value. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 71 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 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) |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 90 | * |
| 91 | * @code |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 92 | * struct json_object_iterator it; |
| 93 | * struct json_object_iterator itEnd; |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 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 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 113 | * |
| 114 | * @warning Do NOT write code that assumes that the "end" |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 115 | * iterator value is NULL, even if it is so in a |
| 116 | * particular instance of the implementation. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 117 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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 | * |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 129 | * @note For performance reasons, memorize the "end" iterator prior |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 130 | * to any loop. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 131 | * |
| 132 | * @param obj JSON Object instance (MUST be of type json_object) |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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 |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 143 | * |
| 144 | * @warning Any modification of the underlying pair |
| 145 | * invalidates all iterators to that pair. |
| 146 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 163 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 164 | * @param iter pointer to iterator that references a name/value |
| 165 | * pair; MUST be a valid, non-end iterator. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 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 |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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 | |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 180 | /** Returns a pointer to the json-c instance representing the |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 181 | * value of the referenced name/value pair, without altering |
| 182 | * the instance's reference count. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 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 |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 188 | * "end" iterator is passed. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 189 | * |
| 190 | * @return struct json_object* Pointer to the json-c value |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 191 | * instance of the referenced name/value pair; the |
| 192 | * value's reference count is not changed by this |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 193 | * function: if you plan to hold on to this json-c node, |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 194 | * take a look at json_object_get() and |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 195 | * json_object_put(). IMPORTANT: json-c API represents |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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). |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 207 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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. |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 216 | * |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 217 | * @param iter1 Pointer to first valid, non-NULL iterator |
| 218 | * @param iter2 POinter to second valid, non-NULL iterator |
Keith Derrick | ded667a | 2012-04-23 15:34:44 -0700 | [diff] [blame] | 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 | * |
Eric Haszlakiewicz | 4e000a6 | 2012-04-24 21:54:07 -0500 | [diff] [blame] | 225 | * @return json_bool non-zero if iterators are equal (i.e., both |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 226 | * reference the same name/value pair or are both at |
| 227 | * "end"); zero if they are not equal. |
| 228 | */ |
Eric Haszlakiewicz | 4e000a6 | 2012-04-24 21:54:07 -0500 | [diff] [blame] | 229 | json_bool |
Keith Derrick | bcfd1f5 | 2012-04-12 09:54:21 -0700 | [diff] [blame] | 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 | |
Eric Haszlakiewicz | e48a25c | 2013-04-30 09:47:19 -0500 | [diff] [blame] | 239 | #endif /* JSON_OBJECT_ITERATOR_H */ |