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
61static const void* kObjectEndIterValue = NULL;
62
63/**
64 * ****************************************************************************
65 */
66struct json_object_iterator
67json_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 */
86struct json_object_iterator
87json_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 */
102void
103json_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 */
115const char*
116json_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 */
128struct json_object*
129json_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 */
141json_bool
142json_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 */
155struct json_object_iterator
156json_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