.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "BSON_ARRAY_BUILDER_T" "3" "Feb 25, 2024" "1.26.0" "libbson"
.INDENT 0.0
.INDENT 3.5
.sp
.EX
typedef struct _bson_array_builder_t bson_array_builder_t;
.EE
.UNINDENT
.UNINDENT
.sp
\fBbson_array_builder_t\fP may be used to build BSON arrays. \fBbson_array_builder_t\fP internally tracks and uses the array index as a key (\(dq0\(dq, \(dq1\(dq, \(dq2\(dq, ...) when appending elements.
.SH APPENDING AN ARRAY VALUE
.INDENT 0.0
.INDENT 3.5
.sp
.EX
typedef struct _bson_array_builder_t bson_array_builder_t;

bool
bson_append_array_builder_begin (bson_t *bson,
                                 const char *key,
                                 int key_length,
                                 bson_array_builder_t **child);

bool
bson_append_array_builder_end (bson_t *bson, bson_array_builder_t *child);

#define BSON_APPEND_ARRAY_BUILDER_BEGIN(b, key, child) \e
  bson_append_array_builder_begin (b, key, (int) strlen (key), child)
.EE
.UNINDENT
.UNINDENT
.sp
\fBbson_append_array_builder_begin\fP may be used to append an array as a value. Example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t parent = BSON_INITIALIZER;
bson_array_builder_t *bab;

bson_append_array_builder_begin (&parent, \(dqfoo\(dq, 3, &bab);
bson_array_builder_append_int32 (bab, 9);
bson_array_builder_append_int32 (bab, 8);
bson_array_builder_append_int32 (bab, 7);
bson_append_array_builder_end (&parent, bab);

char *str = bson_as_relaxed_extended_json (&parent, NULL);
printf (\(dq%s\en\(dq, str); // Prints: { \(dqfoo\(dq : [ 9, 8, 7 ] }
bson_free (str);

bson_destroy (&parent);

.EE
.UNINDENT
.UNINDENT
.SH CREATING A TOP-LEVEL ARRAY
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_array_builder_t * bson_array_builder_new (void);

bool
bson_array_builder_build (bson_array_builder_t *bab, bson_t *out);

BSON_EXPORT (void)
bson_array_builder_destroy (bson_array_builder_t *bab);
.EE
.UNINDENT
.UNINDENT
.sp
\fBbson_array_builder_new\fP and \fBbson_array_builder_build\fP may be used to build a top\-level BSON array. \fBbson_array_builder_build\fP initializes and moves BSON data to \fBout\fP\&. The \fBbson_array_builder_t\fP may be reused and will start appending a new array at index \(dq0\(dq:
.sp
Example:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bson_t out;
bson_array_builder_t *bab = bson_array_builder_new ();

bson_array_builder_append_int32 (bab, 9);
bson_array_builder_append_int32 (bab, 8);
bson_array_builder_append_int32 (bab, 7);
bson_array_builder_build (bab, &out);

char *str = bson_array_as_relaxed_extended_json (&out, NULL);
printf (\(dq%s\en\(dq, str); // Prints: [ 9, 8, 7 ]
bson_free (str);

bson_array_builder_destroy (bab);

.EE
.UNINDENT
.UNINDENT
.SH APPENDING VALUES TO AN ARRAY
.sp
\fBbson_array_builder_append_*\fP functions are provided to append values to a BSON array. The \fBbson_array_builder_append_*\fP functions internally use \fBbson_append_*\fP and provide the array index as a key:
.INDENT 0.0
.INDENT 3.5
.sp
.EX
bool
bson_array_builder_append_value (bson_array_builder_t *bab,
                                 const bson_value_t *value);


bool
bson_array_builder_append_array (bson_array_builder_t *bab,
                                 const bson_t *array);


bool
bson_array_builder_append_binary (bson_array_builder_t *bab,
                                  bson_subtype_t subtype,
                                  const uint8_t *binary,
                                  uint32_t length);

bool
bson_array_builder_append_bool (bson_array_builder_t *bab, bool value);


bool
bson_array_builder_append_code (bson_array_builder_t *bab,
                                const char *javascript);


bool
bson_array_builder_append_code_with_scope (bson_array_builder_t *bab,
                                           const char *javascript,
                                           const bson_t *scope);


bool
bson_array_builder_append_dbpointer (bson_array_builder_t *bab,
                                     const char *collection,
                                     const bson_oid_t *oid);


bool
bson_array_builder_append_double (bson_array_builder_t *bab, double value);


bool
bson_array_builder_append_document (bson_array_builder_t *bab,
                                    const bson_t *value);


bool
bson_array_builder_append_document_begin (bson_array_builder_t *bab,
                                          bson_t *child);


bool
bson_array_builder_append_document_end (bson_array_builder_t *bab,
                                        bson_t *child);

bool
bson_array_builder_append_int32 (bson_array_builder_t *bab, int32_t value);


bool
bson_array_builder_append_int64 (bson_array_builder_t *bab, int64_t value);


bool
bson_array_builder_append_decimal128 (bson_array_builder_t *bab,
                                      const bson_decimal128_t *value);


bool
bson_array_builder_append_iter (bson_array_builder_t *bab,
                                const bson_iter_t *iter);


bool
bson_array_builder_append_minkey (bson_array_builder_t *bab);


bool
bson_array_builder_append_maxkey (bson_array_builder_t *bab);


bool
bson_array_builder_append_null (bson_array_builder_t *bab);


bool
bson_array_builder_append_oid (bson_array_builder_t *bab,
                               const bson_oid_t *oid);


bool
bson_array_builder_append_regex (bson_array_builder_t *bab,
                                 const char *regex,
                                 const char *options);


bool
bson_array_builder_append_regex_w_len (bson_array_builder_t *bab,
                                      const char *regex,
                                      int regex_length,
                                      const char *options);

bool
bson_array_builder_append_utf8 (bson_array_builder_t *bab,
                                const char *value,
                                int length);

bool
bson_array_builder_append_symbol (bson_array_builder_t *bab,
                                  const char *value,
                                  int length);

bool
bson_array_builder_append_time_t (bson_array_builder_t *bab, time_t value);


bool
bson_array_builder_append_timeval (bson_array_builder_t *bab,
                                   struct timeval *value);


bool
bson_array_builder_append_date_time (bson_array_builder_t *bab, int64_t value);


bool
bson_array_builder_append_now_utc (bson_array_builder_t *bab);


bool
bson_array_builder_append_timestamp (bson_array_builder_t *bab,
                                     uint32_t timestamp,
                                     uint32_t increment);

bool
bson_array_builder_append_undefined (bson_array_builder_t *bab);

bool
bson_array_builder_append_array_builder_begin (bson_array_builder_t *bab,
                                               bson_array_builder_t **child);

bool
bson_array_builder_append_array_builder_end (bson_array_builder_t *bab,
                                             bson_array_builder_t *child);
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
MongoDB, Inc
.SH COPYRIGHT
2017-present, MongoDB, Inc
.\" Generated by docutils manpage writer.
.