Document
@dynamicMemberLookup
public struct Document
A struct representing the BSON document type.
-
Returns the number of (key, value) pairs stored at the top level of this
Document
.Declaration
Swift
public var count: Int
-
Declaration
Swift
public func encode(to encoder: Encoder) throws
-
This method will work with any
Decoder
, but for non-BSON decoders, we do not support decodingDate
s, because of limitations of decoding toAnyBSONValue
s. SeeAnyBSONValue.init(from:)
for more information.Declaration
Swift
public init(from decoder: Decoder) throws
-
The index type of a document.
Declaration
Swift
public typealias Index = Int
-
Returns the start index of the Document.
Declaration
Swift
public var startIndex: Index { get }
-
Returns the end index of the Document.
Declaration
Swift
public var endIndex: Index { get }
-
Allows access to a
KeyValuePair
from theDocument
, given the position of the desiredKeyValuePair
held within. This method does not guarantee constant-time (O(1)) access.Declaration
Swift
public subscript(position: Index) -> KeyValuePair { get }
-
Allows access to a
KeyValuePair
from theDocument
, given a range of indices of the desiredKeyValuePair
‘s held within. This method does not guarantee constant-time (O(1)) access.Declaration
Swift
public subscript(bounds: Range<Index>) -> Document { get }
-
The element type of a document: a tuple containing an individual key-value pair.
Declaration
Swift
public typealias KeyValuePair = (key: String, value: BSONValue)
-
The type that is returned from methods such as
dropFirst()
andsplit()
.Declaration
Swift
public typealias SubSequence = Document
-
Returns a
Bool
indicating whether the document is empty.Declaration
Swift
public var isEmpty: Bool { get }
-
Returns a
DocumentIterator
over the values in thisDocument
.Declaration
Swift
public func makeIterator() -> DocumentIterator
-
Returns a new document containing the keys of this document with the values transformed by the given closure.
Throws
An error if
transform
throws an error.Declaration
Parameters
transform
Return Value
A document containing the keys and transformed values of this document.
-
Returns a document containing all but the given number of initial key-value pairs.
Declaration
Swift
public func dropFirst(_ n: Int) -> Document
Parameters
k
The number of key-value pairs to drop from the beginning of the document. k must be > 0.
Return Value
A document starting after the specified number of key-value pairs.
-
Returns a document containing all but the given number of final key-value pairs.
Declaration
Swift
public func dropLast(_ n: Int) -> Document
Parameters
k
The number of key-value pairs to drop from the end of the document. Must be greater than or equal to zero.
Return Value
A document leaving off the specified number of final key-value pairs.
-
Returns a document by skipping the initial, consecutive key-value pairs that satisfy the given predicate.
Throws
An error if
predicate
throws an error.Declaration
Swift
public func drop(while predicate: (KeyValuePair) throws -> Bool) rethrows -> Document
Parameters
predicate
A closure that takes a key-value pair as its argument and returns a boolean indicating whether the key-value pair should be included in the result.
Return Value
A document starting after the initial, consecutive key-value pairs that satisfy
predicate
. -
Returns a document, up to the specified maximum length, containing the initial key-value pairs of the document.
Declaration
Swift
public func prefix(_ maxLength: Int) -> Document
Parameters
maxLength
The maximum length for the returned document. Must be greater than or equal to zero.
Return Value
A document starting at the beginning of this document with at most
maxLength
key-value pairs. -
Returns a document containing the initial, consecutive key-value pairs that satisfy the given predicate.
Throws
An error if
predicate
throws an error.Declaration
Swift
public func prefix(while predicate: (KeyValuePair) throws -> Bool) rethrows -> Document
Parameters
predicate
A closure that takes a key-value pair as its argument and returns a boolean indicating whether the key-value pair should be included in the result.
Return Value
A document containing the initial, consecutive key-value pairs that satisfy
predicate
. -
Returns a document, up to the specified maximum length, containing the final key-value pairs of the document.
Declaration
Swift
public func suffix(_ maxLength: Int) -> Document
Parameters
maxLength
The maximum length for the returned document. Must be greater than or equal to zero.
Return Value
A document ending at the end of this document with at most
maxLength
key-value pairs. -
Returns the longest possible subsequences of the document, in order, that don’t contain key-value pairs satisfying the given predicate. Key-value pairs that are used to split the document are not returned as part of any subsequence.
Declaration
Swift
public func split(maxSplits: Int = Int.max, omittingEmptySubsequences: Bool = true, whereSeparator isSeparator: (KeyValuePair) throws -> Bool) rethrows -> [Document]
Parameters
maxSplits
The maximum number of times to split the document, or one less than the number of subsequences to return. If
maxSplits
+ 1 subsequences are returned, the last one is a suffix of the original document containing the remaining key-value pairs.maxSplits
must be greater than or equal to zero. The default value isInt.max
.omittingEmptySubsequences
If false, an empty document is returned in the result for each pair of consecutive key-value pairs satisfying the
isSeparator
predicate and for each key-value pair at the start or end of the document satisfying theisSeparator
predicate. If true, only nonempty documents are returned. The default value is true.isSeparator
A closure that returns true if its argument should be used to split the document and otherwise returns false.
Return Value
An array of documents, split from this document’s key-value pairs.
-
Returns a new document containing the elements of the document that satisfy the given predicate.
Throws
An error if
isIncluded
throws an error.Declaration
Swift
public func filter(_ isIncluded: (KeyValuePair) throws -> Bool) rethrows -> Document
Parameters
isIncluded
A closure that takes a key-value pair as its argument and returns a
Bool
indicating whether the pair should be included in the returned document.Return Value
A document containing the key-value pairs that
isIncluded
allows.
-
Returns a
[String]
containing the keys in thisDocument
.Declaration
Swift
public var keys: [String] { get }
-
Returns a
[BSONValue]
containing the values stored in thisDocument
.Declaration
Swift
public var values: [BSONValue] { get }
-
Returns the relaxed extended JSON representation of this
Document
. On error, an empty string will be returned.Declaration
Swift
public var extendedJSON: String { get }
-
Returns the canonical extended JSON representation of this
Document
. On error, an empty string will be returned.Declaration
Swift
public var canonicalExtendedJSON: String { get }
-
Returns a copy of the raw BSON data for this
Document
, represented asData
.Declaration
Swift
public var rawBSON: Data { get }
-
Initializes a new, empty
Document
.Declaration
Swift
public init()
-
Constructs a new
Document
from the provided JSON text.Throws
Throws:
- A
UserError.invalidArgumentError
if the data passed in is invalid JSON.
Declaration
Swift
public init(fromJSON: Data) throws
Parameters
fromJSON
a JSON document as
Data
to parse into aDocument
Return Value
the parsed
Document
- A
-
Convenience initializer for constructing a
Document
from aString
.Throws
- A
UserError.invalidArgumentError
if the string passed in is invalid JSON.
Declaration
Swift
public init(fromJSON json: String) throws
- A
-
Constructs a
Document
from raw BSONData
.Declaration
Swift
public init(fromBSON: Data)
-
Returns a
Boolean
indicating whether thisDocument
contains the provided key.Declaration
Swift
public func hasKey(_ key: String) -> Bool
-
Allows setting values and retrieving values using subscript syntax. For example:
let d = Document() d["a"] = 1 print(d["a"]) // prints 1
A nil return suggests that the subscripted key does not exist in the
Document
. A true BSON null is returned as aBSONNull
.Declaration
Swift
public subscript(key: String) -> BSONValue? { get set }
-
An implementation identical to subscript(key: String), but offers the ability to choose a default value if the key is missing. For example:
let d: Document = ["hello": "world"] print(d["hello", default: "foo"]) // prints "world" print(d["a", default: "foo"]) // prints "foo"
-
Allows setting values and retrieving values using dot-notation syntax. For example:
let d = Document() d.a = 1 print(d.a) // prints 1
A nil return suggests that the key does not exist in the
Document
. A true BSON null is returned as aBSONNull
.Only available in Swift 4.2+.
Declaration
Swift
@available(swift 4.2) public subscript(dynamicMember member: String) -> BSONValue? { get set }
-
Declaration
Swift
public var bsonType: BSONType { get }
-
Declaration
Swift
public func encode(to storage: DocumentStorage, forKey key: String) throws
-
Declaration
Swift
public static func from(iterator iter: DocumentIterator) throws -> Document
-
Declaration
Swift
public static func == (lhs: Document, rhs: Document) -> Bool
-
Returns the relaxed extended JSON representation of this
Document
. On error, an empty string will be returned.Declaration
Swift
public var description: String { get }
-
Initializes a
Document
using a dictionary literal where the keys areString
s and the values areBSONValue
s. For example:d: Document = ["a" : 1 ]
Declaration
Swift
public init(dictionaryLiteral keyValuePairs: (String, BSONValue)...)
Parameters
dictionaryLiteral
a [String: BSONValue]
Return Value
a new
Document
-
Initializes a
Document
using an array literal where the values areBSONValue
s. Values are stored under a string of their index in the array. For example:d: Document = ["a", "b"]
will become["0": "a", "1": "b"]
Declaration
Swift
public init(arrayLiteral elements: BSONValue...)
Parameters
arrayLiteral
a
[BSONValue]
Return Value
a new
Document