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