Creación de un documento BSON

La estructura bson_t

Los documentos BSON se crean utilizando el Estructura bson_t. Esta estructura encapsula la lógica necesaria para codificar utilizando la especificación BSON. En esencia, bson_t es un gestor de búfer y un conjunto de rutinas de codificación.

Comencemos creando un nuevo documento BSON en la pila. Al usar libbson, asegúrese de... #include <bson/bson.h>.

bson_t b;
bson_init (&b);

Esto crea un documento vacío. En JSON, equivaldría a {}.

Ahora podemos añadir elementos al documento BSON. Se pueden usar diversas funciones con el prefijo bson_append_ según el tipo de campo que se desee añadir. Añadamos una cadena con codificación UTF-8.

bson_append_utf8 (&b, "key", -1, "value", -1);

Observe los dos parámetros -1. El primero indica que la longitud de key en bytes debe determinarse con strlen(). Alternativamente, podríamos haber pasado el número 3. Lo mismo ocurre con el segundo -1, pero para value.

Libbson proporciona macros para simplificar el uso de literales de cadena. Las dos siguientes adiciones son idénticas.

bson_append_utf8 (&b, "key", -1, "value", -1);
BSON_APPEND_UTF8 (&b, "key", "value");

Ahora veamos un ejemplo que agrega algunos tipos de campos diferentes a un documento BSON.

bson_t b = BSON_INITIALIZER;
BSON_APPEND_INT32 (&b, "a", 1);
BSON_APPEND_UTF8 (&b, "hello", "world");
BSON_APPEND_BOOL (&b, "bool", true);

Observe que omitimos la llamada a bson_init. Al especificar,BSON_INITIALIZER podemos eliminar la necesidad de inicializar la estructura a un estado base.

Subdocumentos y submatrices

Para simplificar la creación de subdocumentos, bson_append_document_begin puede usarse para compilar un subdocumento utilizando la región de memoria del padre como búfer de destino.

bson_t parent = BSON_INITIALIZER;
bson_t child;
bson_append_document_begin (&parent, "foo", 3, &child);
bson_append_int32 (&child, "baz", 3, 1);
bson_append_document_end (&parent, &child);
char *str = bson_as_relaxed_extended_json (&parent, NULL);
printf ("%s\n", str); // Prints: { "foo" : { "baz" : 1 } }
bson_free (str);
bson_destroy (&parent);

Para simplificar la creación de submatrices, se puede utilizar bson_array_builder_t para construir una submatriz utilizando la región de memoria del padre como búfer de destino.

bson_t parent = BSON_INITIALIZER;
bson_array_builder_t *bab;
bson_append_array_builder_begin (&parent, "foo", 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 ("%s\n", str); // Prints: { "foo" : [ 9, 8, 7 ] }
bson_free (str);
bson_destroy (&parent);

Notación de objetos C BSON simplificada

Crear documentos BSON manualmente puede ser tedioso y consumir mucho tiempo. BCON, o Notación de Objetos BSON C, se añadió para permitir la creación de documentos BSON en un formato más similar al formato de destino.

El siguiente ejemplo muestra el uso de BCON. Observe que los valores de los campos se encapsulan en las macros BCON_*. Estas son necesarias para que el procesador variádico determine el tipo de parámetro.

bson_t *doc;
doc = BCON_NEW ("foo",
                "{",
                "int",
                BCON_INT32 (1),
                "array",
                "[",
                BCON_INT32 (100),
                "{",
                "sub",
                BCON_UTF8 ("value"),
                "}",
                "]",
                "}");

Crea el siguiente documento

{ "foo" : { "int" : 1, "array" : [ 100, { "sub" : "value" } ] } }