elixir-cbson

BSON NIF for Elixir language http://bsonspec.org

THANKS

This library has taken many great ideas and codes from Jiffy to make it fasting and flexible.

The API of elixir-cbson is the same as elixir-bson which I always used in my projects.

WARNING

• At this moment, elixir-cbson only supports Little-endian machine and I will improve it sometime.
• Only support Elixir 1.1.0+

MongoDB Driver

The MongodB driver using this project is here, being changed from elixir-mongo.

Usage

CBson.decode/1,2

• CBson.decode(iodata)
• CBson.decode(iodata, options)

The options for decode are:

• :return_lists - Return objects using the lists data(keywrods) type.
• :return_atom - Return objects using atom keys instead of string. The internal implementation is using String.to_existing_atom/1, if convertion failed, the string key returned.
• {:nil_term, term} - Returns the specified term instead of nil when decoding BSON. This is for people that wish to use undefined instead of nil.
• :use_null - Returns the atom null instead of nil when decoding BSON. This is a short hand for {nil_term, null}.
• :return_josn - Returns objects converted ObjectId, UTC, Bin, Regex and Timestamp to suitable types for easier convert to json
• :return_trailer - If any data is found after the first BSON term is decoded the return value of decode/2 becomes {:has_trailer, first_term, rest_data::iodata()}. This is useful to decode multiple terms in a single binary.
• {:bytes_per_red, n} where n >= 0 - This controls the number of bytes that elixir-cbson will process as an equivalent to a reduction. Each 20 reductions we consume 1% of our allocated time slice for the current process. When the Erlang VM indicates we need to return from the NIF.

CBson.encode/1,2

• CBson.encode(bson_doc)
• CBson.encode(bson_doc, options)

The options for encode are:

• force_utf8 - Force strings to encode as UTF-8 by fixing broken surrogate pairs and/or using the replacement character to remove broken UTF-8 sequences in data.
• {:nil_term, term} - Returns the specified term instead of nil when decoding BSON. This is for people that wish to use undefined instead of nil.
• :use_null - Returns the atom null instead of nil when decoding BSON. This is a short hand for {nil_term, null}.
• {:bytes_per_red, n} - Refer to the decode options

Types

BSON Type | Elixir Type | Notes ———-|——————-|———————– ObjectId | %Bson.ObjectId{} | double | double | string | string | doc | map or keywords | :return_lists array | list | binary | %Bson.Bin{} | bool | atom: true/false | datetime | %Bson.UTC{} | Null | nil | :use_null/:nil_term Regex | %Bson.Regex{} |
JavaScript| | not supported int32 | integer | Timestamp | %Bson.Timestamp{} | int64 | integer | Min key | atom: min_key | Max key | atom: max_key |

Benchmarking

There’re some benchmark cases vs mongodb & elixir-bson

MIX_ENV=bench mix bench