Criar um documento BSON

A estrutura bson_t

Documentos BSON são criados usando o bson_t estrutura. Esta estrutura encapsula a lógica necessária para codificação usando a Especificação BSON. No núcleo, bson_t é um gerenciador de buffer e um conjunto de rotinas de codificação.

Vamos começar criando um novo documento BSON na pilha. Sempre que usar a libbson, certifique-se de #include <bson/bson.h>.

bson_t b;
bson_init (&b);

Isso cria um documento vazio. Em JSON, seria o mesmo que {}.

Agora podemos adicionar itens ao documento BSON. Uma variedade de funções prefixadas com bson_append_ pode ser usada com base no tipo de campo que você deseja anexar. Vamos anexar uma string codificada UTF-8 .

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

Observe os dois parâmetros -1 . A primeira indica que o comprimento de key em bytes deve ser determinado com strlen(). Como alternativa, poderíamos ter passado o número 3. O mesmo vale para o segundo -1, mas para value.

Libbson fornece macros para tornar isso menos entediante ao usar string literais. Os dois apêndices a seguir são idênticos.

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

Agora vejamos um exemplo que adiciona alguns tipos de campo diferentes a um 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 a chamada para bson_init. Ao especificar ,BSON_INITIALIZER podemos remover a necessidade de inicializar a estrutura para um estado base.

Subdocumentos e sub-arrays

Para simplificar a criação de subdocumentos bson_append_document_begin pode ser usado para construir um subdocumento usando a região de memória dos pais como buffer 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 a criação de sub-matriz bson_array_builder_t pode ser usado para construir uma sub-array usando a região de memória dos pais como buffer 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);

Notação de objeto BSON simplificada

Criar documentos BSON manualmente pode ser entediante e consome muito tempo. BCON, ou BSON C Object Notation, foi adicionado para permitir a criação de documentos BSON em um formato que se parece mais com o formato de destino.

O exemplo a seguir mostra o uso do BCON. Observe que os valores dos campos estão envoltos nas macros BCON_* . Eles são necessários para que o processador variado determine o tipo de parâmetro.

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

Cria o seguinte documento

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