• source navigation  • diff markup  • identifier search  • freetext search  • 

Sources/json-c/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
240 

This page was automatically generated by LXR 0.3.1.  •  OpenWrt