Trabalhando com BSON

Valores e visualizações de JSON

Muitos métodos de driver C++ aceitam um documento BSON como argumento. A biblioteca do bsoncxx fornece dois tipos de dados que você pode utilizar para representar um documento BSON : bsoncxx::document::value e bsoncxx:document::view.

Um objeto document::value representa um documento BSON que possui seu buffer subjacente de dados. Quando você passa um objeto document::value para um método de driver C++ , o método recebe uma cópia dos dados do documento BSON. Quando um objeto document::value sai do escopo, seu buffer subjacente é liberado.

Um objeto document::view fornece uma visualização não própria de um document::value. Esse tipo permite ler e interagir com o conteúdo de um documento BSON sem possuir os dados subjacentes do documento. Quando você passa um objeto document::view para um método de driver C++ , o método pode usar dados do documento subjacente sem copiá-los. Você pode criar uma visualização chamando o método view() em um objeto document::value.

Alguns métodos de driver C++ aceitam argumentos do document::view_or_value tipo. Você pode passar um document::view document::value objeto ou para estes métodos. Você deve passar document::value argumentos por referência de rvalue para transferir a propriedade do documento para o método.

Construtor de listas

A interface do builder::list é um construtor semelhante a JSON para construir documentos e arrays. Para criar um documento BSON usando o construtor de listas, construa um objeto bsoncxx::builder::list , passando uma lista de pares de valores-chave para o construtor. O construtor de listas criará um documento BSON se a lista de valores-chave atender aos seguintes requisitos:

• A lista tem um número par de elementos.

• Cada chave é um tipo string e cada valor é um tipo bson_value::value ou é implicitamente convertível em um.

Se os requisitos anteriores não forem atendidos, o construtor de lista criará uma array.

Este exemplo utiliza o construtor de lista para executar as seguintes ações:

• Construir um documento

• Construir uma array

• Converter o documento do construtor em um objeto bsoncxx::document::value

bsoncxx::builder::list course_doc = { "title", "Poetry",
                                      "department", "English" };
bsoncxx::builder::list courses_array = { "Poetry", "Literature",
                                         "Creative Writing" };
bsoncxx::document::value course{course_doc.view().get_document().value};

Construtor básico

A interface do builder::basic é uma interface de estilo de construtor para construir um documento BSON. Para criar um documento BSON usando o construtor básico, especifique os dados do documento em uma lista de objetos de par de chave-valor. Você pode criar esses objetos de par de chave-valor passando uma chave e um valor para o método builder::basic::kvp(). A chave deve ser do tipo string e o valor deve ser do tipo bson_value::value ou implicitamente convertível em um.

Você pode usar o método make_document() do construtor básico para criar um documento e convertê-lo em bsoncxx::document::value em uma única instrução, conforme mostrado no código a seguir:

using bsoncxx::builder::basic::make_document; 
using bsoncxx::builder::basic::kvp;
bsoncxx::document::value course = make_document(
    kvp("title","Poetry"),
    kvp("department","English"));

Como alternativa, você pode criar um documento BSON em várias declarações anexando pares de valor-chave a um objeto de construtor básico. Este exemplo usa o construtor básico para executar as seguintes ações:

• Inicialize um objeto builder::basic::document

• Armazene dados no documento usando o método append()

• Converter o documento do construtor em um objeto bsoncxx::document::value

using bsoncxx::builder::basic::kvp;
auto course_builder = bsoncxx::builder::basic::document{};
course_builder.append(kvp("title", "Literature"),
                      kvp("department", "English"));
                      
bsoncxx::document::value course{course_builder.extract()};

Construtor de Streams

A interface builder::stream é uma interface de streaming para construir objetos BSON complexos. Para criar um documento BSON usando o construtor de fluxo, inicialize um objeto builder::stream::document . Em seguida, você pode usar o operador << para transmitir chaves e valores para o seu construtor.

O código a seguir mostra como usar o construtor de stream para executar as seguintes ações:

• Construir um documento

• Converter o documento em um objeto bsoncxx::document::value

auto course_builder = bsoncxx::builder::stream::document{};
course_builder << "title" << "Creative Writing" << "credits" << bsoncxx::types::b_int32{4};
bsoncxx::document::value course{course_builder.extract()};

Você também pode converter o stream em um bsoncxx::document::value usando o token builder::stream::finalize, conforme mostrado no exemplo a seguir:

using bsoncxx::builder::stream::document;
using bsoncxx::builder::stream::finalize;
bsoncxx::document::value doc = document{} << "title" << "Literature" << finalize;

Documentação da API

Para saber mais sobre os tipos e métodos mencionados neste guia, consulte a seguinte documentação da API:

• bsoncxx::builder::list

• bsoncxx::builder::basic::document

• bsoncxx::builder::stream::document

• bsoncxx::document::value

• bsoncxx::document::view

• bsoncxx::to_json()