doc/html/json__object__iterator_8h.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
   5 <title>json-c: json_object_iterator.h File Reference</title>
   6 <link href="tabs.css" rel="stylesheet" type="text/css"/>
   7 <link href="doxygen.css" rel="stylesheet" type="text/css"/>
   8 </head>
   9 <body>
  10 <!-- Generated by Doxygen 1.6.3 -->
  11 <div class="navigation" id="top">
  12   <div class="tabs">
  13     <ul>
  14       <li><a href="index.html"><span>Main&nbsp;Page</span></a></li>
  15       <li><a href="pages.html"><span>Related&nbsp;Pages</span></a></li>
  16       <li><a href="annotated.html"><span>Data&nbsp;Structures</span></a></li>
  17       <li class="current"><a href="files.html"><span>Files</span></a></li>
  18     </ul>
  19   </div>
  20   <div class="tabs">
  21     <ul>
  22       <li><a href="files.html"><span>File&nbsp;List</span></a></li>
  23       <li><a href="globals.html"><span>Globals</span></a></li>
  24     </ul>
  25   </div>
  26 </div>
  27 <div class="contents">
  28 <h1>json_object_iterator.h File Reference</h1>
  29 <p>json-c forces clients to use its private data structures for JSON Object iteration. This API corrects that by abstracting the private json-c details.
  30 <a href="#_details">More...</a></p>
  31 <table border="0" cellpadding="0" cellspacing="0">
  32 <tr><td colspan="2"><h2>Data Structures</h2></td></tr>
  33 <tr><td class="memItemLeft" align="right" valign="top">struct &nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="structjson__object__iterator.html">json_object_iterator</a></td></tr>
  34 <tr><td colspan="2"><h2>Functions</h2></td></tr>
  35 <tr><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#af30f56ca510d59da42e5592f9a436c10">json_object_iter_init_default</a> (void)</td></tr>
  36 <tr><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#a925eb97b5aa5b64986a0f663f53cf0fa">json_object_iter_begin</a> (struct <a class="el" href="structjson__object.html">json_object</a> *obj)</td></tr>
  37 <tr><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#a1fa3784395fb14496e3f1a1633028fd4">json_object_iter_end</a> (const struct <a class="el" href="structjson__object.html">json_object</a> *obj)</td></tr>
  38 <tr><td class="memItemLeft" align="right" valign="top">void&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#aa98a310c340f6d9b4eeecb673aa5e240">json_object_iter_next</a> (struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *iter)</td></tr>
  39 <tr><td class="memItemLeft" align="right" valign="top">const char *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#af17775b9b812a4206a84e4d3fb5774ab">json_object_iter_peek_name</a> (const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *iter)</td></tr>
  40 <tr><td class="memItemLeft" align="right" valign="top">struct <a class="el" href="structjson__object.html">json_object</a> *&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#a47b0af7f1722c10475dffd29efc0b89d">json_object_iter_peek_value</a> (const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *iter)</td></tr>
  41 <tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="json__object_8h.html#a81f02022906fafc71eb9197049f07f73">json_bool</a>&nbsp;</td><td class="memItemRight" valign="bottom"><a class="el" href="json__object__iterator_8h.html#a878ca25f72b339882aa2607ac938e79c">json_object_iter_equal</a> (const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *iter1, const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *iter2)</td></tr>
  42 </table>
  43 <hr/><a name="_details"></a><h2>Detailed Description</h2>
  44 <p>json-c forces clients to use its private data structures for JSON Object iteration. This API corrects that by abstracting the private json-c details. </p>
  45 <p>Copyright (c) 2009-2012 Hewlett-Packard Development Company, L.P.</p>
  46 <p>This library is free software; you can redistribute it and/or modify it under the terms of the MIT license. See COPYING for details.</p>
  47 <p>API attributes: <br/>
  48  * Thread-safe: NO<br/>
  49  * Reentrant: NO </p>
  50 <hr/><h2>Function Documentation</h2>
  51 <a class="anchor" id="a925eb97b5aa5b64986a0f663f53cf0fa"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_begin" ref="a925eb97b5aa5b64986a0f663f53cf0fa" args="(struct json_object *obj)" -->
  52 <div class="memitem">
  53 <div class="memproto">
  54       <table class="memname">
  55         <tr>
  56           <td class="memname">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> json_object_iter_begin </td>
  57           <td>(</td>
  58           <td class="paramtype">struct <a class="el" href="structjson__object.html">json_object</a> *&nbsp;</td>
  59           <td class="paramname"> <em>obj</em></td>
  60           <td>&nbsp;)&nbsp;</td>
  61           <td><code> [read]</code></td>
  62         </tr>
  63       </table>
  64 </div>
  65 <div class="memdoc">
  66 <p>Retrieves an iterator to the first pair of the JSON Object.</p>
  67 <dl class="warning"><dt><b>Warning:</b></dt><dd>Any modification of the underlying pair invalidates all iterators to that pair.</dd></dl>
  68 <dl><dt><b>Parameters:</b></dt><dd>
  69   <table border="0" cellspacing="2" cellpadding="0">
  70     <tr><td valign="top"></td><td valign="top"><em>obj</em>&nbsp;</td><td>JSON Object instance (MUST be of type <a class="el" href="structjson__object.html">json_object</a>)</td></tr>
  71   </table>
  72   </dd>
  73 </dl>
  74 <dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="structjson__object__iterator.html">json_object_iterator</a> 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.</dd></dl>
  75 <div class="fragment"><pre class="fragment"> <span class="keyword">struct </span><a class="code" href="structjson__object__iterator.html">json_object_iterator</a> it;
  76  <span class="keyword">struct </span><a class="code" href="structjson__object__iterator.html">json_object_iterator</a> itEnd;
  77  <span class="keyword">struct </span><a class="code" href="structjson__object.html">json_object</a>* obj;
  78
  79  obj = <a class="code" href="json__tokener_8h.html#abf031fdf1e5caab71e2225a99588c6bb">json_tokener_parse</a>(<span class="stringliteral">&quot;{&#39;first&#39;:&#39;george&#39;, &#39;age&#39;:100}&quot;</span>);
  80  it = <a class="code" href="json__object__iterator_8h.html#a925eb97b5aa5b64986a0f663f53cf0fa">json_object_iter_begin</a>(obj);
  81  itEnd = <a class="code" href="json__object__iterator_8h.html#a1fa3784395fb14496e3f1a1633028fd4">json_object_iter_end</a>(obj);
  82
  83  <span class="keywordflow">while</span> (!<a class="code" href="json__object__iterator_8h.html#a878ca25f72b339882aa2607ac938e79c">json_object_iter_equal</a>(&amp;it, &amp;itEnd)) {
  84      printf(<span class="stringliteral">&quot;%s\n&quot;</span>,
  85             <a class="code" href="json__object__iterator_8h.html#af17775b9b812a4206a84e4d3fb5774ab">json_object_iter_peek_name</a>(&amp;it));
  86      <a class="code" href="json__object__iterator_8h.html#aa98a310c340f6d9b4eeecb673aa5e240">json_object_iter_next</a>(&amp;it);
  87  }
  88 </pre></div>
  89 </div>
  90 </div>
  91 <a class="anchor" id="a1fa3784395fb14496e3f1a1633028fd4"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_end" ref="a1fa3784395fb14496e3f1a1633028fd4" args="(const struct json_object *obj)" -->
  92 <div class="memitem">
  93 <div class="memproto">
  94       <table class="memname">
  95         <tr>
  96           <td class="memname">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> json_object_iter_end </td>
  97           <td>(</td>
  98           <td class="paramtype">const struct <a class="el" href="structjson__object.html">json_object</a> *&nbsp;</td>
  99           <td class="paramname"> <em>obj</em></td>
 100           <td>&nbsp;)&nbsp;</td>
 101           <td><code> [read]</code></td>
 102         </tr>
 103       </table>
 104 </div>
 105 <div class="memdoc">
 106 <p>Retrieves the iterator that represents the position beyond the last pair of the given JSON Object instance.</p>
 107 <dl class="warning"><dt><b>Warning:</b></dt><dd>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.</dd></dl>
 108 <dl class="note"><dt><b>Note:</b></dt><dd>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.</dd>
 109 <dd>
 110 For performance reasons, memorize the "end" iterator prior to any loop.</dd></dl>
 111 <dl><dt><b>Parameters:</b></dt><dd>
 112   <table border="0" cellspacing="2" cellpadding="0">
 113     <tr><td valign="top"></td><td valign="top"><em>obj</em>&nbsp;</td><td>JSON Object instance (MUST be of type <a class="el" href="structjson__object.html">json_object</a>)</td></tr>
 114   </table>
 115   </dd>
 116 </dl>
 117 <dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="structjson__object__iterator.html">json_object_iterator</a> On return, the iterator refers to the "end" of the Object instance's pairs (i.e., NOT the last pair, but "beyond the last
 118               pair" value) </dd></dl>
 119
 120 </div>
 121 </div>
 122 <a class="anchor" id="a878ca25f72b339882aa2607ac938e79c"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_equal" ref="a878ca25f72b339882aa2607ac938e79c" args="(const struct json_object_iterator *iter1, const struct json_object_iterator *iter2)" -->
 123 <div class="memitem">
 124 <div class="memproto">
 125       <table class="memname">
 126         <tr>
 127           <td class="memname"><a class="el" href="json__object_8h.html#a81f02022906fafc71eb9197049f07f73">json_bool</a> json_object_iter_equal </td>
 128           <td>(</td>
 129           <td class="paramtype">const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *&nbsp;</td>
 130           <td class="paramname"> <em>iter1</em>, </td>
 131         </tr>
 132         <tr>
 133           <td class="paramkey"></td>
 134           <td></td>
 135           <td class="paramtype">const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *&nbsp;</td>
 136           <td class="paramname"> <em>iter2</em></td><td>&nbsp;</td>
 137         </tr>
 138         <tr>
 139           <td></td>
 140           <td>)</td>
 141           <td></td><td></td><td></td>
 142         </tr>
 143       </table>
 144 </div>
 145 <div class="memdoc">
 146 <p>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).</p>
 147 <dl class="note"><dt><b>Note:</b></dt><dd>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.</dd></dl>
 148 <dl><dt><b>Parameters:</b></dt><dd>
 149   <table border="0" cellspacing="2" cellpadding="0">
 150     <tr><td valign="top"></td><td valign="top"><em>iter1</em>&nbsp;</td><td>Pointer to first valid, non-NULL iterator </td></tr>
 151     <tr><td valign="top"></td><td valign="top"><em>iter2</em>&nbsp;</td><td>POinter to second valid, non-NULL iterator</td></tr>
 152   </table>
 153   </dd>
 154 </dl>
 155 <dl class="warning"><dt><b>Warning:</b></dt><dd>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!</dd></dl>
 156 <dl class="return"><dt><b>Returns:</b></dt><dd>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. </dd></dl>
 157
 158 </div>
 159 </div>
 160 <a class="anchor" id="af30f56ca510d59da42e5592f9a436c10"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_init_default" ref="af30f56ca510d59da42e5592f9a436c10" args="(void)" -->
 161 <div class="memitem">
 162 <div class="memproto">
 163       <table class="memname">
 164         <tr>
 165           <td class="memname">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> json_object_iter_init_default </td>
 166           <td>(</td>
 167           <td class="paramtype">void&nbsp;</td>
 168           <td class="paramname"></td>
 169           <td>&nbsp;)&nbsp;</td>
 170           <td><code> [read]</code></td>
 171         </tr>
 172       </table>
 173 </div>
 174 <div class="memdoc">
 175 <p>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).</p>
 176 <div class="fragment"><pre class="fragment"> <span class="keyword">struct </span><a class="code" href="structjson__object__iterator.html">json_object_iterator</a> iter = <a class="code" href="json__object__iterator_8h.html#af30f56ca510d59da42e5592f9a436c10">json_object_iter_init_default</a>();
 177  MyClass() : iter_(<a class="code" href="json__object__iterator_8h.html#af30f56ca510d59da42e5592f9a436c10">json_object_iter_init_default</a>())
 178 </pre></div><dl class="note"><dt><b>Note:</b></dt><dd>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.</dd>
 179 <dd>
 180 User and internal code MUST NOT make any assumptions about and dependencies on the value of the "default" iterator value.</dd></dl>
 181 <dl class="return"><dt><b>Returns:</b></dt><dd><a class="el" href="structjson__object__iterator.html">json_object_iterator</a> </dd></dl>
 182
 183 </div>
 184 </div>
 185 <a class="anchor" id="aa98a310c340f6d9b4eeecb673aa5e240"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_next" ref="aa98a310c340f6d9b4eeecb673aa5e240" args="(struct json_object_iterator *iter)" -->
 186 <div class="memitem">
 187 <div class="memproto">
 188       <table class="memname">
 189         <tr>
 190           <td class="memname">void json_object_iter_next </td>
 191           <td>(</td>
 192           <td class="paramtype">struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *&nbsp;</td>
 193           <td class="paramname"> <em>iter</em></td>
 194           <td>&nbsp;)&nbsp;</td>
 195           <td></td>
 196         </tr>
 197       </table>
 198 </div>
 199 <div class="memdoc">
 200 <p>Returns an iterator to the next pair, if any</p>
 201 <dl class="warning"><dt><b>Warning:</b></dt><dd>Any modification of the underlying pair invalidates all iterators to that pair.</dd></dl>
 202 <dl><dt><b>Parameters:</b></dt><dd>
 203   <table border="0" cellspacing="2" cellpadding="0">
 204     <tr><td valign="top"></td><td valign="top"><em>iter</em>&nbsp;</td><td>[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 <a class="el" href="json__object__iterator_8h.html#a1fa3784395fb14496e3f1a1633028fd4">json_object_iter_end()</a> for the same JSON Object instance. </td></tr>
 205   </table>
 206   </dd>
 207 </dl>
 208
 209 </div>
 210 </div>
 211 <a class="anchor" id="af17775b9b812a4206a84e4d3fb5774ab"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_peek_name" ref="af17775b9b812a4206a84e4d3fb5774ab" args="(const struct json_object_iterator *iter)" -->
 212 <div class="memitem">
 213 <div class="memproto">
 214       <table class="memname">
 215         <tr>
 216           <td class="memname">const char* json_object_iter_peek_name </td>
 217           <td>(</td>
 218           <td class="paramtype">const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *&nbsp;</td>
 219           <td class="paramname"> <em>iter</em></td>
 220           <td>&nbsp;)&nbsp;</td>
 221           <td></td>
 222         </tr>
 223       </table>
 224 </div>
 225 <div class="memdoc">
 226 <p>Returns a const pointer to the name of the pair referenced by the given iterator.</p>
 227 <dl><dt><b>Parameters:</b></dt><dd>
 228   <table border="0" cellspacing="2" cellpadding="0">
 229     <tr><td valign="top"></td><td valign="top"><em>iter</em>&nbsp;</td><td>pointer to iterator that references a name/value pair; MUST be a valid, non-end iterator.</td></tr>
 230   </table>
 231   </dd>
 232 </dl>
 233 <dl class="warning"><dt><b>Warning:</b></dt><dd>bad things will happen if an invalid or "end" iterator is passed.</dd></dl>
 234 <dl class="return"><dt><b>Returns:</b></dt><dd>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. </dd></dl>
 235
 236 </div>
 237 </div>
 238 <a class="anchor" id="a47b0af7f1722c10475dffd29efc0b89d"></a><!-- doxytag: member="json_object_iterator.h::json_object_iter_peek_value" ref="a47b0af7f1722c10475dffd29efc0b89d" args="(const struct json_object_iterator *iter)" -->
 239 <div class="memitem">
 240 <div class="memproto">
 241       <table class="memname">
 242         <tr>
 243           <td class="memname">struct <a class="el" href="structjson__object.html">json_object</a>* json_object_iter_peek_value </td>
 244           <td>(</td>
 245           <td class="paramtype">const struct <a class="el" href="structjson__object__iterator.html">json_object_iterator</a> *&nbsp;</td>
 246           <td class="paramname"> <em>iter</em></td>
 247           <td>&nbsp;)&nbsp;</td>
 248           <td><code> [read]</code></td>
 249         </tr>
 250       </table>
 251 </div>
 252 <div class="memdoc">
 253 <p>Returns a pointer to the json-c instance representing the value of the referenced name/value pair, without altering the instance's reference count.</p>
 254 <dl><dt><b>Parameters:</b></dt><dd>
 255   <table border="0" cellspacing="2" cellpadding="0">
 256     <tr><td valign="top"></td><td valign="top"><em>iter</em>&nbsp;</td><td>pointer to iterator that references a name/value pair; MUST be a valid, non-end iterator.</td></tr>
 257   </table>
 258   </dd>
 259 </dl>
 260 <dl class="warning"><dt><b>Warning:</b></dt><dd>bad things will happen if invalid or "end" iterator is passed.</dd></dl>
 261 <dl class="return"><dt><b>Returns:</b></dt><dd>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 <a class="el" href="json__object_8h.html#acc3628d97c6308dc967006e4268c4e7f">json_object_get()</a> and <a class="el" href="json__object_8h.html#accc34b38e15e46357d64a0beed3d0150">json_object_put()</a>. IMPORTANT: json-c API represents the JSON Null value as a NULL <a class="el" href="structjson__object.html">json_object</a> instance pointer. </dd></dl>
 262
 263 </div>
 264 </div>
 265 </div>
 266 <hr class="footer"/><address style="text-align: right;"><small>Generated on Sat Apr 28 15:52:47 2012 for json-c by&nbsp;
 267 <a href="http://www.doxygen.org/index.html">
 268 <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.6.3 </small></address>
 269 </body>
 270 </html>