Encoding and decoding support for BSON in Rust
Branch: master
Clone or download
Latest commit 31a74d9 Aug 12, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
examples Reformatted with rustfmt Jun 25, 2018
serde-tests Replaced all occurences of `try!(.*)` with `?`. (#93) Jun 16, 2018
src
tests Fix serialization of newtype structs, simplify serialization of newty… Aug 11, 2018
.gitignore Implemented `Default` for `Bson`, `Document`, and `ObjectId` (#82) Sep 30, 2017
.travis.yml Add u2i feature (#94) (#95) Jul 4, 2018
Cargo.toml Bump version to v0.13.0 Aug 11, 2018
LICENSE add license Aug 26, 2015
README.md Updated readme Aug 11, 2018
rustfmt.toml Add rustfmt toml Jun 26, 2018

README.md

bson-rs

Build Status crates.io crates.io

Encoding and decoding support for BSON in Rust

Useful links

Installation

This crate works with Cargo and can be found on crates.io with a Cargo.toml like:

[dependencies]
bson = "0.13"

Usage

Link the library in main.rs:

#[macro_use(bson, doc)]
extern crate bson;

Prepare your struct for Serde serialization:

#[derive(Serialize, Deserialize, Debug)]
pub struct Person {
    #[serde(rename = "_id")]  // Use MongoDB's special primary key field name when serializing 
    pub id: bson::oid::ObjectId,
    pub name: String,
    pub age: i32
}

Serialize the struct:

use bson;

let person = Person {
    id: "12345",
    name: "Emma",
    age: 3
};

let serialized_person = bson::to_bson(&person)?;  // Serialize

if let bson::Bson::Document(document) = serialized_person {
    mongoCollection.insert_one(document, None)?;  // Insert into a MongoDB collection
} else {
    println!("Error converting the BSON object into a MongoDB document");
}

Deserialize the struct:

// Read the document from a MongoDB collection
let person_document = mongoCollection.find_one(Some(doc! { "_id":  bson::oid::ObjectId::with_string("12345").expect("Id not valid") }), None)?
    .expect("Document not found");

// Deserialize the document into a Person instance
let person = bson::from_bson(bson::Bson::Document(person_document))?

Breaking Changes

In the BSON specification, unsigned integer types are unsupported; for example, u32. In the older version of this crate (< v0.8.0), if you uses serde to serialize unsigned integer types into BSON, it will store them with Bson::FloatingPoint type. From v0.8.0, we removed this behavior and simply returned an error when you want to serialize unsigned integer types to BSON. #72

For backward compatibility, we've provided a mod bson::compat::u2f to explicitly serialize unsigned integer types into BSON's floating point value as follows:

#[test]
fn test_compat_u2f() {
    #[derive(Serialize, Deserialize, Eq, PartialEq, Debug)]
    struct Foo {
        #[serde(with = "bson::compat::u2f")]
        x: u32
    }

    let foo = Foo { x: 20 };
    let b = bson::to_bson(&foo).unwrap();
    assert_eq!(b, Bson::Document(doc! { "x": Bson::FloatingPoint(20.0) }));

    let de_foo = bson::from_bson::<Foo>(b).unwrap();
    assert_eq!(de_foo, foo);
}

In this example, we added an attribute #[serde(with = "bson::compat::u2f")] on field x, which will tell serde to use the bson::compat::u2f::serialize and bson::compat::u2f::deserialize methods to process this field.