Trabajando con BSON

Valores y vistas de BSON

Muchos métodos de controlador de C++ aceptan un documento BSON como argumento. La biblioteca bsoncxx proporciona dos tipos de datos que se pueden usar para representar un documento BSON: bsoncxx::document::value y bsoncxx:document::view.

Un objeto document::value representa un documento BSON que posee su búfer de datos subyacente. Al pasar un objeto document::value a un método controlador de C++, este recibe una copia de los datos del documento BSON. Cuando un objeto document::value queda fuera de alcance, se libera su búfer subyacente.

Un objeto document::view proporciona una vista no propietaria de un document::value. Este tipo te permite leer e interactuar con el contenido de un documento BSON sin poseer los datos subyacentes del documento. Cuando se pasa un objeto document::view a un método de controlador en C++, el método puede utilizar los datos del documento subyacente sin copiarlos. Puede crear una vista llamando al método view() en un objeto document::value.

Algunos métodos de controlador de C++ aceptan argumentos de tipo.document::view_or_value Puede pasar un document::view document::value objeto o a estos métodos. Debe pasar document::value argumentos por referencia rvalue para transferir la propiedad del documento al método.

Constructor de listas

La interfaz builder::list es un generador tipo JSON para crear documentos y matrices. Para crear un documento BSON mediante el generador de listas, se construye un objeto bsoncxx::builder::list y se pasa una lista de pares clave-valor al constructor. El generador de listas crea un documento BSON si la lista clave-valor cumple los siguientes requisitos:

• La lista tiene un número par de elementos.

• Cada clave es de tipo string y cada valor es de tipo bson_value::value o es implícitamente convertible a uno.

Si no se cumplen los requisitos anteriores, el generador de listas crea una matriz.

Este ejemplo utiliza el generador de listas para realizar las siguientes acciones:

• Crear un documento

• Construir una matriz

• Convertir el documento del constructor en un 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};

Constructor básico

La interfaz builder::basic es una interfaz de tipo constructor para crear un documento BSON. Para crear un documento BSON con el constructor básico, especifique los datos del documento en una lista de objetos de pares clave-valor. Puede crear estos objetos de pares clave-valor pasando una clave y un valor al método builder::basic::kvp(). La clave debe ser de tipo string y el valor de tipo bson_value::value o convertible implícitamente a uno.

Puedes usar el método make_document() del generador básico para crear un documento y convertirlo en un bsoncxx::document::value en una sola instrucción, como se muestra en el siguiente código:

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, puede crear un documento BSON con varias instrucciones añadiendo pares clave-valor a un objeto de generador básico. Este ejemplo utiliza el generador básico para realizar las siguientes acciones:

• Inicializar un objeto builder::basic::document

• Almacenar datos en el documento utilizando el método append()

• Convertir el documento del constructor en un 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()};

Generador de transmisiones

La interfaz builder::stream es una interfaz de transmisión para construir objetos BSON complejos. Para crear un documento BSON con el generador de secuencias, inicialice un objeto builder::stream::document. A continuación, puede usar el operador << para transmitir claves y valores a su generador.

El siguiente código muestra cómo utilizar el generador de transmisiones para realizar las siguientes acciones:

• Crear un documento

• Convertir el documento en un 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()};

También puedes convertir la transmisión a un bsoncxx::document::value utilizando el token builder::stream::finalize, como se muestra en el siguiente ejemplo:

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

Documentación de la API

Para obtener más información sobre los tipos y métodos mencionados en esta guía, consulte la siguiente documentación de API:

• bsoncxx::constructor::lista

• bsoncxx::builder::basic::document

• bsoncxx::builder::stream::document

• bsoncxx::documento::valor

• bsoncxx::documento::vista

• bsoncxx::a_json()