使用 BSON

在此页面上

Overview

BSON 数据格式
BSON值和视图
构建BSON文档
列表生成器
基本生成器
Stream Builder
打印BSON文档
更多信息
API 文档

Overview

在本指南中，您可以学习；了解如何通过 bsoncxx 库使用C++驾驶员存储BSON数据并交互。

BSON 数据格式

MongoDB使用BSON （二进制JSON）数据格式来存储文档和进行远程过程调用。此数据格式包括所有JSON数据结构类型并支持其他类型，包括日期、不同大小的整数、ObjectId 值和二进制数据。有关支持类型的完整列表，请参阅MongoDB Server手册中的 BSON类型页面。

BSON值和视图

许多C++驾驶员方法接受BSON文档作为参数。 bsoncxx 库提供两种可用于表示BSON文档的数据类型：bsoncxx::document::value 和 bsoncxx:document::view。

document::value对象表示拥有其根本的数据缓冲区的BSON文档。当您将 document::value对象传递给C++驾驶员方法时，该方法会收到BSON文档数据的副本。当 document::value对象超出范围时，将释放其根本的缓冲区。

提示

您可以通过在构建器上调用辅助方法，将构建器类型转换为document::value 类型。要学习；了解有关构建器类型的更多信息，请参阅本指南中的“构建BSON文档”部分。

document::view对象提供了 document::value 的非所有视图。这种类型允许您读取BSON文档的内容并交互，而无需拥有该文档的根本的数据。当您将 document::view对象传递给C++驾驶员方法时，该方法可以使用根本的文档中的数据，而无需复制数据。您可以通过对 document::value对象调用 view() 方法来创建视图。

提示

为了避免过度复制，我们建议尽可能通过视图传递文档。

某些C++驾驶员方法接受document::view_or_value 类型的参数。您可以将document::view 或document::value 对象传递给这些方法。必须通过右值document::value 引用传递参数，才能将文档的所有权转移给该方法。

重要

document::view 的寿命不得超过其引用的任何 document::value。如果 document::view 在释放其根本的缓冲区后使用 document::value，则该视图将包含一个悬空指针。访问悬空指针可能会导致应用程序崩溃、数据损坏和其他不可预测的行为。

构建BSON文档

本节介绍如何使用以下接口创建BSON文档：

列表生成器
基本生成器
Stream Builder

列表生成器

builder::list 接口是一个类似JSON的构建器，用于构建文档和数组。要使用列表构建器创建BSON文档，请构造一个 bsoncxx::builder::list对象，将键值对列表传递给构造函数。如果键值列表满足以下要求，列表构建器将创建BSON文档：

该列表有偶数个元素。
每个键都是 string 类型，每个值都是 bson_value::value 类型，或者可以隐式转换为类型。

如果不满足上述要求，列表构建器将创建一个大量。

此示例使用列表生成器来执行以下操作：

构建文档
构建大量
将构建器文档转换为 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};

基本生成器

builder::basic 接口是一个构建器风格的接口，用于构建BSON文档。要使用基本构建器创建BSON文档，请在键值对对象列表中指定文档的数据。您可以通过将键和值传递给 builder::basic::kvp() 方法来创建这些键值对对象。键必须是 string 类型，值必须是 bson_value::value 类型或可隐式转换为类型。

您可以使用基本构建器的 make_document() 方法创建文档，并在一条声明中将其转换为 bsoncxx::document::value，如以下代码所示：

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

或者，您可以通过将键值对附加到基本构建器对象来跨多个语句创建BSON文档。此示例使用基本构建器来执行以下操作：

初始化 builder::basic::document对象
使用 append() 方法将数据存储在文档中
将构建器文档转换为 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()};

Stream Builder

重要

我们建议使用基本构建器而不是流构建器。

要正确追加每个新值，流构建器必须追踪当前文档的状态。在此状态更改后，您无法重复使用初始流构建器。因此，如果跨多个语句构建文档，则所有中间值都必须存储在新变量中。由于这种复杂性，不鼓励使用流构建器。

builder::stream 接口是用于构造复杂BSON对象的流媒体接口。要使用流构建器创建BSON文档，请初始化 builder::stream::document对象。然后，您可以使用 <<操作符将键和值流到构建器中。

以下代码展示了如何使用流构建器来执行以下操作：

构建文档
将文档转换为 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()};

您还可以使用 builder::stream::finalize 令牌将该流转换为 bsoncxx::document::value，如以下示例所示：

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

打印BSON文档

BSON是JSON文档的二进制编码序列化，不适合人类阅读。要以人类可读的格式预览BSON文档的内容，可以使用 bsoncxx::to_json() 方法将文档转换为扩展JSON格式。

扩展JSON格式是标准JSON的扩展，其中包括BSON数据类型的字符串表示形式。要学习；了解更多信息，请参阅MongoDB Server手册中的MongoDB扩展JSON指南。

bsoncxx::to_json() 方法接受要转换的BSON文档的 bsoncxx::document::view。此方法返回一个 std::string对象，以扩展JSON格式表示BSON文档。

以下代码展示了如何将BSON文档转换为扩展JSON格式并打印结果：

bsoncxx::document::value course = make_document(
    kvp("title","Screenwriting"),
    kvp("department","English"));
std::cout << bsoncxx::to_json(course.view()) << std::endl;

{ "title" : "Screenwriting", "department" : "English" }