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 An API for iterating over json_type_object objects, 11 * styled to be familiar to C++ programmers. 12 * Unlike json_object_object_foreach() and 13 * json_object_object_foreachC(), this avoids the need to expose 14 * json-c internals like lh_entry. 15 * 16 * API attributes: <br> 17 * * Thread-safe: NO<br> 18 * * Reentrant: NO 19 * 20 ******************************************************************************* 21 */ 22 23 #ifndef JSON_OBJECT_ITERATOR_H 24 #define JSON_OBJECT_ITERATOR_H 25 26 #include "json_types.h" 27 #include <stddef.h> 28 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 /** 34 * Forward declaration for the opaque iterator information. 35 */ 36 struct json_object_iter_info_; 37 38 /** 39 * The opaque iterator that references a name/value pair within 40 * a JSON Object instance or the "end" iterator value. 41 */ 42 struct json_object_iterator 43 { 44 const void *opaque_; 45 }; 46 47 /** 48 * forward declaration of json-c's JSON value instance structure 49 */ 50 struct json_object; 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 JSON_EXPORT struct json_object_iterator json_object_iter_init_default(void); 75 76 /** Retrieves an iterator to the first pair of the JSON Object. 77 * 78 * @warning Any modification of the underlying pair invalidates all 79 * iterators to that pair. 80 * 81 * @param obj JSON Object instance (MUST be of type json_object) 82 * 83 * @return json_object_iterator If the JSON Object has at 84 * least one pair, on return, the iterator refers 85 * to the first pair. If the JSON Object doesn't 86 * have any pairs, the returned iterator is 87 * equivalent to the "end" iterator for the same 88 * JSON Object instance. 89 * 90 * @code 91 * struct json_object_iterator it; 92 * struct json_object_iterator itEnd; 93 * struct json_object* obj; 94 * 95 * obj = json_tokener_parse("{'first':'george', 'age':100}"); 96 * it = json_object_iter_begin(obj); 97 * itEnd = json_object_iter_end(obj); 98 * 99 * while (!json_object_iter_equal(&it, &itEnd)) { 100 * printf("%s\n", 101 * json_object_iter_peek_name(&it)); 102 * json_object_iter_next(&it); 103 * } 104 * 105 * @endcode 106 */ 107 JSON_EXPORT struct json_object_iterator json_object_iter_begin(struct json_object *obj); 108 109 /** Retrieves the iterator that represents the position beyond the 110 * last pair of the given JSON Object instance. 111 * 112 * @warning Do NOT write code that assumes that the "end" 113 * iterator value is NULL, even if it is so in a 114 * particular instance of the implementation. 115 * 116 * @note The reason we do not (and MUST NOT) provide 117 * "json_object_iter_is_end(json_object_iterator* iter)" 118 * type of API is because it would limit the underlying 119 * representation of name/value containment (or force us 120 * to add additional, otherwise unnecessary, fields to 121 * the iterator structure). The "end" iterator and the 122 * equality test method, on the other hand, permit us to 123 * cleanly abstract pretty much any reasonable underlying 124 * representation without burdening the iterator 125 * structure with unnecessary data. 126 * 127 * @note For performance reasons, memorize the "end" iterator prior 128 * to any loop. 129 * 130 * @param obj JSON Object instance (MUST be of type json_object) 131 * 132 * @return json_object_iterator On return, the iterator refers 133 * to the "end" of the Object instance's pairs 134 * (i.e., NOT the last pair, but "beyond the last 135 * pair" value) 136 */ 137 JSON_EXPORT struct json_object_iterator json_object_iter_end(const struct json_object *obj); 138 139 /** Returns an iterator to the next pair, if any 140 * 141 * @warning Any modification of the underlying pair 142 * invalidates all iterators to that pair. 143 * 144 * @param iter [IN/OUT] Pointer to iterator that references a 145 * name/value pair; MUST be a valid, non-end iterator. 146 * WARNING: bad things will happen if invalid or "end" 147 * iterator is passed. Upon return will contain the 148 * reference to the next pair if there is one; if there 149 * are no more pairs, will contain the "end" iterator 150 * value, which may be compared against the return value 151 * of json_object_iter_end() for the same JSON Object 152 * instance. 153 */ 154 JSON_EXPORT void json_object_iter_next(struct json_object_iterator *iter); 155 156 /** Returns a const pointer to the name of the pair referenced 157 * by the given iterator. 158 * 159 * @param iter pointer to iterator that references a name/value 160 * pair; MUST be a valid, non-end iterator. 161 * 162 * @warning bad things will happen if an invalid or 163 * "end" iterator is passed. 164 * 165 * @return const char* Pointer to the name of the referenced 166 * name/value pair. The name memory belongs to the 167 * name/value pair, will be freed when the pair is 168 * deleted or modified, and MUST NOT be modified or 169 * freed by the user. 170 */ 171 JSON_EXPORT const char *json_object_iter_peek_name(const struct json_object_iterator *iter); 172 173 /** Returns a pointer to the json-c instance representing the 174 * value of the referenced name/value pair, without altering 175 * the instance's reference count. 176 * 177 * @param iter pointer to iterator that references a name/value 178 * pair; MUST be a valid, non-end iterator. 179 * 180 * @warning bad things will happen if invalid or 181 * "end" iterator is passed. 182 * 183 * @return struct json_object* Pointer to the json-c value 184 * instance of the referenced name/value pair; the 185 * value's reference count is not changed by this 186 * function: if you plan to hold on to this json-c node, 187 * take a look at json_object_get() and 188 * json_object_put(). IMPORTANT: json-c API represents 189 * the JSON Null value as a NULL json_object instance 190 * pointer. 191 */ 192 JSON_EXPORT struct json_object * 193 json_object_iter_peek_value(const struct json_object_iterator *iter); 194 195 /** Tests two iterators for equality. Typically used to test 196 * for end of iteration by comparing an iterator to the 197 * corresponding "end" iterator (that was derived from the same 198 * JSON Object instance). 199 * 200 * @note The reason we do not (and MUST NOT) provide 201 * "json_object_iter_is_end(json_object_iterator* iter)" 202 * type of API is because it would limit the underlying 203 * representation of name/value containment (or force us 204 * to add additional, otherwise unnecessary, fields to 205 * the iterator structure). The equality test method, on 206 * the other hand, permits us to cleanly abstract pretty 207 * much any reasonable underlying representation. 208 * 209 * @param iter1 Pointer to first valid, non-NULL iterator 210 * @param iter2 POinter to second valid, non-NULL iterator 211 * 212 * @warning if a NULL iterator pointer or an uninitialized 213 * or invalid iterator, or iterators derived from 214 * different JSON Object instances are passed, bad things 215 * will happen! 216 * 217 * @return json_bool non-zero if iterators are equal (i.e., both 218 * reference the same name/value pair or are both at 219 * "end"); zero if they are not equal. 220 */ 221 JSON_EXPORT json_bool json_object_iter_equal(const struct json_object_iterator *iter1, 222 const struct json_object_iterator *iter2); 223 224 #ifdef __cplusplus 225 } 226 #endif 227 228 #endif /* JSON_OBJECT_ITERATOR_H */ 229
This page was automatically generated by LXR 0.3.1. • OpenWrt