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