"BSON" stands for "binary JSON" - a binary storage format that is JSON inspired.
This is the C++ implementation, developed by http://www.10gen.com/ for http://www.mongodb.org/. This distribution merely rips it out of the mongodb repository into its own.
Other BSON implementations are available for most languages at http://bsonspec.org.
There is no need to build bson-cpp as the library is head-only.
If you want access to the library accross your system, simply move the contents of /src to a directory included in your include_path (e.g. /usr/local/include). It's a good idea to prefix the contents in case you get name-clashes with existing files from mongodb.
You want to include the bson header:
#include <bson/bson.h>
Checkout the file src/bson/bsondemo/bsondemo.cpp for a quick overview.
The following creates a BSON "person" object which contains name and age:
BSONObjBuilder b;
b.append("name", "Joe");
b.append("age", 33);
BSONObj p = b.obj();
Or more concisely:
BSONObj p = BSONObjBuilder().append("name", "Joe").append("age", 33).obj();
We can also create objects with a stream-oriented syntax:
BSONObjBuilder b;
b << "name" << "Joe" << "age" << 33;
BSONObj p = b.obj();
The macro BSON lets us be even more compact:
BSONObj p = BSON( "name" << "Joe" << "age" << 33 );
Objects can be serialized by using the BufBuilder. This allows you to serialize multiple objects at once:
BSONObj p = BSONObjBuilder().append("name", "Joe").append("age", 33).obj();
BSONObj p2 = BSONObjBuilder().append("name", "Jane").append("age", 32).obj();
BufBuilder b;
p.appendSelfToBufBuilder( b );
p2.appendSelfToBufBuilder( b );
saveToFile(b.buf(), b.len());
You can also use the objdata() method of the BSONObj to serialize a single object:
BSONObj p = BSONObjBuilder().append("name", "Joe").append("age", 33).obj();
saveToFile(p.objdata(), p.objsize())
Objects can be deserialized by providing the raw data as the first argument to the construct of BSONObj:
const char* data = readFromFile(filename);
BSONObj p(data);
BSONObj does not copy the data you provide:
std::string data = readFromFileAsString(filename);
BSONObj p(data.c_str());
//e.g. {"my":"data"}
std::cout << p.toString() << std::endl;
//overwrite data variable
data = "";
//{}
std::cout << p.toString() << std::endl;
To make sure that once your variables go out of scope and / or are modified, use the getOwned method. This ensures that the data is actually owned by your BSONObj:
std::string data = readFromFileAsString(filename);
BSONObj p(data.c_str());
if (!p.isOwned()) {
p = p.getOwned();
}
//alternative:
BSONObj p = BSONObj(data.c_str()).getOwned();
The project is license under the very permissive Apache 2.0 license.
- Origin standalone C++ Version: https://github.com/jbenet/bson-cpp
- MongoDB: http://www.mongodb.org/
- Bson Specs: http://www.bsonspec.org/