json_object_iterator.c

   1 /**
   2 *******************************************************************************
   3 * @file json_object_iterator.c
   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 *         implementation corrects that by abstracting the
  13 *         private json-c details.
  14 *
  15 *******************************************************************************
  16 */
  17
  18 #include <stddef.h>
  19
  20 #include "json.h"
  21 #include "json_object_private.h"
  22
  23 #include "json_object_iterator.h"
  24
  25 /**
  26  * How It Works
  27  *
  28  * For each JSON Object, json-c maintains a linked list of zero
  29  * or more lh_entry (link-hash entry) structures inside the
  30  * Object's link-hash table (lh_table).
  31  *
  32  * Each lh_entry structure on the JSON Object's linked list
  33  * represents a single name/value pair.  The "next" field of the
  34  * last lh_entry in the list is set to NULL, which terminates
  35  * the list.
  36  *
  37  * We represent a valid iterator that refers to an actual
  38  * name/value pair via a pointer to the pair's lh_entry
  39  * structure set as the iterator's opaque_ field.
  40  *
  41  * We follow json-c's current pair list representation by
  42  * representing a valid "end" iterator (one that refers past the
  43  * last pair) with a NULL value in the iterator's opaque_ field.
  44  *
  45  * A JSON Object without any pairs in it will have the "head"
  46  * field of its lh_table structure set to NULL.  For such an
  47  * object, json_object_iter_begin will return an iterator with
  48  * the opaque_ field set to NULL, which is equivalent to the
  49  * "end" iterator.
  50  *
  51  * When iterating, we simply update the iterator's opaque_ field
  52  * to point to the next lh_entry structure in the linked list.
  53  * opaque_ will become NULL once we iterate past the last pair
  54  * in the list, which makes the iterator equivalent to the "end"
  55  * iterator.
  56  */
  57
  58 /// Our current representation of the "end" iterator;
  59 ///
  60 /// @note May not always be NULL
  61 static const void* kObjectEndIterValue = NULL;
  62
  63 /**
  64  * ****************************************************************************
  65  */
  66 struct json_object_iterator
  67 json_object_iter_begin(struct json_object* obj)
  68 {
  69     struct json_object_iterator iter;
  70     struct lh_table* pTable;
  71
  72     /// @note json_object_get_object will return NULL if passed NULL
  73     ///       or a non-json_type_object instance
  74     pTable = json_object_get_object(obj);
  75     JASSERT(NULL != pTable);
  76
  77     /// @note For a pair-less Object, head is NULL, which matches our
  78     ///       definition of the "end" iterator
  79     iter.opaque_ = pTable->head;
  80     return iter;
  81 }
  82
  83 /**
  84  * ****************************************************************************
  85  */
  86 struct json_object_iterator
  87 json_object_iter_end(const struct json_object* obj)
  88 {
  89     struct json_object_iterator iter;
  90
  91     JASSERT(NULL != obj);
  92     JASSERT(json_object_is_type(obj, json_type_object));
  93
  94     iter.opaque_ = kObjectEndIterValue;
  95
  96     return iter;
  97 }
  98
  99 /**
 100  * ****************************************************************************
 101  */
 102 void
 103 json_object_iter_next(struct json_object_iterator* iter)
 104 {
 105     JASSERT(NULL != iter);
 106     JASSERT(kObjectEndIterValue != iter->opaque_);
 107
 108     iter->opaque_ = ((struct lh_entry *)iter->opaque_)->next;
 109 }
 110
 111
 112 /**
 113  * ****************************************************************************
 114  */
 115 const char*
 116 json_object_iter_peek_name(const struct json_object_iterator* iter)
 117 {
 118     JASSERT(NULL != iter);
 119     JASSERT(kObjectEndIterValue != iter->opaque_);
 120
 121     return (const char*)(((struct lh_entry *)iter->opaque_)->k);
 122 }
 123
 124
 125 /**
 126  * ****************************************************************************
 127  */
 128 struct json_object*
 129 json_object_iter_peek_value(const struct json_object_iterator* iter)
 130 {
 131     JASSERT(NULL != iter);
 132     JASSERT(kObjectEndIterValue != iter->opaque_);
 133
 134     return (struct json_object*)(((struct lh_entry *)iter->opaque_)->v);
 135 }
 136
 137
 138 /**
 139  * ****************************************************************************
 140  */
 141 json_bool
 142 json_object_iter_equal(const struct json_object_iterator* iter1,
 143                        const struct json_object_iterator* iter2)
 144 {
 145     JASSERT(NULL != iter1);
 146     JASSERT(NULL != iter2);
 147
 148     return (iter1->opaque_ == iter2->opaque_);
 149 }
 150
 151
 152 /**
 153  * ****************************************************************************
 154  */
 155 struct json_object_iterator
 156 json_object_iter_init_default(void)
 157 {
 158     struct json_object_iterator iter;
 159
 160     /**
 161      * @note Make this a negative, invalid value, such that
 162      *       accidental access to it would likely be trapped by the
 163      *       hardware as an invalid address.
 164      */
 165     iter.opaque_ = NULL;
 166
 167     return iter;
 168 }