1:man_page: bson_iter_t
2
3bson_iter_t
4===========
5
6BSON Document Iterator
7
8Synopsis
9--------
10
11.. code-block:: c
12
13  #include <bson.h>
14
15  #define BSON_ITER_HOLDS_DOUBLE(iter) /* ... */
16
17  #define BSON_ITER_HOLDS_UTF8(iter) /* ... */
18
19  #define BSON_ITER_HOLDS_DOCUMENT(iter) /* ... */
20
21  #define BSON_ITER_HOLDS_ARRAY(iter) /* ... */
22
23  #define BSON_ITER_HOLDS_BINARY(iter) /* ... */
24
25  #define BSON_ITER_HOLDS_UNDEFINED(iter) /* ... */
26
27  #define BSON_ITER_HOLDS_OID(iter) /* ... */
28
29  #define BSON_ITER_HOLDS_BOOL(iter) /* ... */
30
31  #define BSON_ITER_HOLDS_DATE_TIME(iter) /* ... */
32
33  #define BSON_ITER_HOLDS_NULL(iter) /* ... */
34
35  #define BSON_ITER_HOLDS_REGEX(iter) /* ... */
36
37  #define BSON_ITER_HOLDS_DBPOINTER(iter) /* ... */
38
39  #define BSON_ITER_HOLDS_CODE(iter) /* ... */
40
41  #define BSON_ITER_HOLDS_SYMBOL(iter) /* ... */
42
43  #define BSON_ITER_HOLDS_CODEWSCOPE(iter) /* ... */
44
45  #define BSON_ITER_HOLDS_INT32(iter) /* ... */
46
47  #define BSON_ITER_HOLDS_TIMESTAMP(iter) /* ... */
48
49  #define BSON_ITER_HOLDS_INT64(iter) /* ... */
50
51  #define BSON_ITER_HOLDS_DECIMAL128(iter) /* ... */
52
53  #define BSON_ITER_HOLDS_MAXKEY(iter) /* ... */
54
55  #define BSON_ITER_HOLDS_MINKEY(iter) /* ... */
56
57  #define BSON_ITER_HOLDS_INT(iter) \
58     (BSON_ITER_HOLDS_INT32 (iter) || BSON_ITER_HOLDS_INT64 (iter))
59
60  #define BSON_ITER_HOLDS_NUMBER(iter) \
61     (BSON_ITER_HOLDS_INT (iter) || BSON_ITER_HOLDS_DOUBLE (iter))
62
63  #define BSON_ITER_IS_KEY(iter, key) \
64     (0 == strcmp ((key), bson_iter_key ((iter))))
65
66  typedef struct {
67     /*< private >*/
68  } bson_iter_t;
69
70Description
71-----------
72
73:symbol:`bson_iter_t` is a structure used to iterate through the elements of a :symbol:`bson_t`. It is meant to be used on the stack and can be discarded at any time as it contains no external allocation. The contents of the structure should be considered private and may change between releases, however the structure size will not change.
74
75The :symbol:`bson_t` *MUST* be valid for the lifetime of the iter and it is an error to modify the :symbol:`bson_t` while using the iter.
76
77.. only:: html
78
79  Functions
80  ---------
81
82  .. toctree::
83    :titlesonly:
84    :maxdepth: 1
85
86    bson_iter_array
87    bson_iter_as_bool
88    bson_iter_as_double
89    bson_iter_as_int64
90    bson_iter_binary
91    bson_iter_bool
92    bson_iter_code
93    bson_iter_codewscope
94    bson_iter_date_time
95    bson_iter_dbpointer
96    bson_iter_decimal128
97    bson_iter_document
98    bson_iter_double
99    bson_iter_dup_utf8
100    bson_iter_find
101    bson_iter_find_case
102    bson_iter_find_descendant
103    bson_iter_init
104    bson_iter_init_find
105    bson_iter_init_find_case
106    bson_iter_init_from_data
107    bson_iter_int32
108    bson_iter_int64
109    bson_iter_key
110    bson_iter_next
111    bson_iter_oid
112    bson_iter_overwrite_bool
113    bson_iter_overwrite_decimal128
114    bson_iter_overwrite_double
115    bson_iter_overwrite_int32
116    bson_iter_overwrite_int64
117    bson_iter_recurse
118    bson_iter_regex
119    bson_iter_symbol
120    bson_iter_time_t
121    bson_iter_timestamp
122    bson_iter_timeval
123    bson_iter_type
124    bson_iter_utf8
125    bson_iter_value
126    bson_iter_visit_all
127
128Examples
129--------
130
131.. code-block:: c
132
133  bson_iter_t iter;
134
135  if (bson_iter_init (&iter, my_bson_doc)) {
136     while (bson_iter_next (&iter)) {
137        printf ("Found a field named: %s\n", bson_iter_key (&iter));
138     }
139  }
140
141.. code-block:: c
142
143  bson_iter_t iter;
144
145  if (bson_iter_init (&iter, my_bson_doc) && bson_iter_find (&iter, "my_field")) {
146     printf ("Found the field named: %s\n", bson_iter_key (&iter));
147  }
148
149.. code-block:: c
150
151  bson_iter_t iter;
152  bson_iter_t sub_iter;
153
154  if (bson_iter_init_find (&iter, my_bson_doc, "mysubdoc") &&
155      (BSON_ITER_HOLDS_DOCUMENT (&iter) || BSON_ITER_HOLDS_ARRAY (&iter)) &&
156      bson_iter_recurse (&iter, &sub_iter)) {
157     while (bson_iter_next (&sub_iter)) {
158        printf ("Found key \"%s\" in sub document.\n", bson_iter_key (&sub_iter));
159     }
160  }
161
162.. code-block:: c
163
164  bson_iter_t iter;
165
166  if (bson_iter_init (&iter, my_doc) &&
167      bson_iter_find_descendant (&iter, "a.b.c.d", &sub_iter)) {
168     printf ("The type of a.b.c.d is: %d\n", (int) bson_iter_type (&sub_iter));
169  }
170
171