BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
There are several ways to create a new BSON object:
As an empty BSON object
let bsonEmpty = BSON()
Specifying a bytes parameter creates a new BSON doc structure using the data provided. The bytes array contains a serialized BSON document.
let bsonBytes = BSON(bytes: [UInt8])
With a JSON parameter, a new BSON document will be created from the JSON structure provided.
let bsonJSON = BSON(json: String)
When specifying a document parameter containing BSON data, a new document will be created with the specified BSON data.
let bsonBSON = BSON(document: BSON)
To close, destroy and release the current BSON document:
let bson = BSON()
defer {
bson.close()
}
Use the asString
method to convert the BSON document to an extended JSON string.
See http://docs.mongodb.org/manual/reference/mongodb-extended-json/ for more information on extended JSON.
let bson.close = BSON(document: <BSON>)
defer {
bson.close()
}
print(bson.asString())
Use asArrayString
for outermost arrays:
print(bson.asArrayString())
Use the asBytes
method to convert the BSON document to a [UInt8]
byte array.
let bytesArray = bson.asBytes()
Using the append
method, data can be added to the BSON document.
The append
method uses the @discardableResult
property. The result of the operation can be returned or ignored.
If the result of the append
operation is returned:
- true: successful append
- false: append would overflow max size
Appends a new field to the BSON document of type BSON_TYPE_OID
using the contents of oid.
bson.append(key: <String>, oid: <bson_oid_t>)
Appends a new field to the BSON document of type BSON_TYPE_DATE_TIME
using the contents of dateTime.
bson.append(key: <String>, dateTime: <Int64>)
Appends a new field to the BSON document of type BSON_TYPE_DATE_TIME
using the contents of time, a time_t @value for the number of seconds since UNIX epoch in UTC.
bson.append(key: <String>, time: <time_t>)
Appends a new field to the BSON document of type BSON_TYPE_DOUBLE
using the contents of double.
bson.append(key: <String>, double: <Double>)
Appends a new field to the BSON document of type BSON_TYPE_BOOL
using the contents of bool.
bson.append(key: <String>, bool: <Bool>)
Appends a new field to the BSON document of type UTF-8 encoded string using the contents of string.
bson.append(key: <String>, string: <String>)
Appends a bytes buffer to the BSON document
bson.append(key: <String>, bytes: <[UInt8]>)
Appends a new field to self.doc of type BSON_TYPE_REGEX
. @regex should be the regex string. @options should contain the options for the regex.
Valid options for @options are:
- 'i' for case-insensitive
- 'm' for multiple matching
- 'x' for verbose mode
- 'l' to make \w and \W locale dependent
- 's' for dotall mode ('.' matches everything)
- 'u' to make \w and \W match unicode
For more information on what comprimises a BSON regex, see www.bsonspec.org.
- key: The key of the field
- regex: The regex to append to the BSON
- options: Options for @regex
bson.append(key: <String>, regex: <String>, options: <String>)
The appendArray
method will append a complete array to the BSON document. BSON arrays are like documents where the key is the string version of the index. For example, the first item of the array would have the key "0". The second item would have the index "1".
bson.appendArray(key: <String>, array: <BSON>)
It is also possible to begin an array append operation, then finish it after further processing, using appendArrayBegin
and appendArrayEnd
.
appendArrayBegin
appends a new field named key to the BSON document; the field is, however, incomplete. @child will be initialized so that you may add fields to the child array. Child will use a memory buffer owned by BSON document, and therefore, grow the parent buffer as additional space is used. This allows a single malloc'd buffer to be used when building arrays which can help reduce memory fragmentation.
The type of @child will be BSON_TYPE_ARRAY
, and therefore, the keys inside of it MUST be "0", "1", etc.
bson.appendArrayBegin(key: <String>, child: <BSON>)
appendArrayEnd
finishes the appending of an array to the BSON dcoument. Child is considered disposed after this call and should not be used any further.
bson.appendArrayEnd(key: <String>, child: <BSON>)
Use concat
to concatenate the src
paramenter contents with the BSON document.
bson.concat(src: <BSON>)
Returns the number of elements found in the BSON document.
bson.countKeys()
This function is case-sensitive. Returns true
if the key was found, otherwise false
.
let hasKey = bson.hasField(key: <String>)
guard let bson == bson2 else {
return false
}
Returns true
if lhs sorts above rhs, false
otherwise.
guard let bson < bson2 else {
return false
}