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 } 169
