BSONDocument

@dynamicMemberLookup
public struct BSONDocument
extension BSONDocument: Collection
extension BSONDocument: Sequence
extension BSONDocument: ExpressibleByDictionaryLiteral
extension BSONDocument: Hashable
extension BSONDocument: Equatable
extension BSONDocument: CustomStringConvertible

A struct representing the BSON document type.

  • The element type of a document: a tuple containing an individual key-value pair.

    Declaration

    Swift

    public typealias KeyValuePair = (key: String, value: BSON)
  • Initializes a new, empty BSONDocument.

    Declaration

    Swift

    public init()
  • Initializes a new BSONDocument from the provided BSON data.

    Throws

    Throws:

    • InvalidArgumentError if the data passed is invalid BSON

    Declaration

    Swift

    public init(fromBSON bson: Data) throws
  • Initializes a new BSONDocument from the provided BSON data. The buffer must have readableBytes equal to the BSON’s leading size indicator.

    Throws

    Throws:

    • InvalidArgumentError if the data passed is invalid BSON

    Declaration

    Swift

    public init(fromBSON bson: ByteBuffer) throws
  • Initialize a new BSONDocument from the provided BSON data without validating the elements. The first four bytes must accurately reflect the length of the buffer, however.

    If invalid BSON data is provided, undefined behavior or server-side errors may occur when using the resultant BSONDocument.

    Throws

    BSONError.InvalidArgumentError if the provided BSON’s length does not match the encoded length.

    Declaration

    Swift

    public init(fromBSONWithoutValidatingElements bson: ByteBuffer) throws
  • Constructs a new BSONDocument from the provided JSON text.

    Throws

    DecodingError if json is a partial match or is malformed.

    Declaration

    Swift

    public init(fromJSON json: Data) throws

    Parameters

    fromJSON

    a JSON document as Data to parse into a BSONDocument

    Return Value

    the parsed BSONDocument

  • Convenience initializer for constructing a BSONDocument from a String.

    Throws

    DecodingError if json is a partial match or is malformed.

    Declaration

    Swift

    public init(fromJSON json: String) throws
  • Returns the relaxed extended JSON representation of this BSONDocument. On error, an empty string will be returned.

    Declaration

    Swift

    public func toExtendedJSONString() -> String
  • Returns the canonical extended JSON representation of this BSONDocument. On error, an empty string will be returned.

    Declaration

    Swift

    public func toCanonicalExtendedJSONString() -> String
  • The keys in this BSONDocument.

    Declaration

    Swift

    public var keys: [String] { get }
  • The values in this BSONDocument.

    Declaration

    Swift

    public var values: [BSON] { get }
  • The number of (key, value) pairs stored at the top level of this document.

    Declaration

    Swift

    public var count: Int { get }
  • A copy of the ByteBuffer backing this document, containing raw BSON data. As ByteBuffers implement copy-on-write, this copy will share byte storage with this document until either the document or the returned buffer is mutated.

    Declaration

    Swift

    public var buffer: ByteBuffer { get }
  • Returns a Data containing a copy of the raw BSON data backing this document.

    Declaration

    Swift

    public func toData() -> Data
  • Returns a Boolean indicating whether this BSONDocument contains the provided key.

    Declaration

    Swift

    public func hasKey(_ key: String) -> Bool
  • Allows getting and setting values on the document via subscript syntax. For example:

     let d = BSONDocument()
     d["a"] = 1
     print(d["a"]) // prints 1
    

    A nil return value indicates that the key does not exist in the BSONDocument. A true BSON null is returned as BSON.null.

    Declaration

    Swift

    public subscript(key: String) -> BSON? { get set }
  • Looks up the specified key in the document and returns its corresponding value, or returns defaultValue if the key is not present.

    For example:

      let d: BSONDocument = ["hello": "world"]
      print(d["hello", default: "foo"]) // prints "world"
      print(d["a", default: "foo"]) // prints "foo"
    

    Declaration

    Swift

    public subscript(key: String, default defaultValue: @autoclosure () -> BSON) -> BSON { get }
  • Allows getting and setting values on the document using dot-notation syntax. For example:

     let d = BSONDocument()
     d.a = 1
     print(d.a) // prints 1
    

    A nil return value indicates that the key does not exist in the BSONDocument. A true BSON null is returned as BSON.null.

    Declaration

    Swift

    public subscript(dynamicMember member: String) -> BSON? { get set }
  • Returns a copy of this document with an _id element prepended. If the document already contains an _id, returns the document as-is.

    Throws

    BSONError.DocumentTooLargeError if adding the _id would make the document exceed the maximum allowed size for a document.

    Declaration

    Swift

    public func withID() throws -> BSONDocument
  • 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 }
  • Returns the index after the given index for this Document.

    Declaration

    Swift

    public func index(after i: Index) -> Index
  • Allows access to a KeyValuePair from the BSONDocument, given the position of the desired KeyValuePair 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 the BSONDocument, given a range of indices of the desired KeyValuePair‘s held within. This method does not guarantee constant-time (O(1)) access.

    Declaration

    Swift

    public subscript(bounds: Range<Index>) -> BSONDocument { get }
  • The type that is returned from methods such as dropFirst() and split().

    Declaration

    Swift

    public typealias SubSequence = BSONDocument
  • Returns a Bool indicating whether the document is empty.

    Declaration

    Swift

    public var isEmpty: Bool { get }
  • Returns a DocumentIterator over the values in this Document.

    Declaration

    Swift

    public func makeIterator() -> BSONDocumentIterator
  • Declaration

    Swift

    @inlinable
    public func map<T>(
        _ transform: (Element) throws -> T
    ) rethrows -> [T]
  • 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

    Swift

    public func mapValues(_ transform: (BSON) throws -> BSON) rethrows -> BSONDocument

    Parameters

    transform

    A closure that transforms a BSON. transform accepts each value of the document as its parameter and returns a transformed BSON.

    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) -> BSONDocument

    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) -> BSONDocument

    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 -> BSONDocument

    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) -> BSONDocument

    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 -> BSONDocument

    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) -> BSONDocument

    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 -> [BSONDocument]

    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 is Int.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 the isSeparator 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.

  • Initializes a BSONDocument using a dictionary literal where the keys are Strings and the values are BSONs. For example: d: BSONDocument = ["a" : 1 ]

    Declaration

    Swift

    public init(dictionaryLiteral keyValuePairs: (String, BSON)...)

    Parameters

    dictionaryLiteral

    a [String: BSON]

    Return Value

    a new BSONDocument

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)
  • Declaration

    Swift

    public static func == (lhs: BSONDocument, rhs: BSONDocument) -> Bool
  • Declaration

    Swift

    public var description: String { get }
  • Returns whether this BSONDocument contains exactly the same key/value pairs as the provided BSONDocument, regardless of the order of the keys.

    Warning: This method is much less efficient than checking for regular equality since the document is internally ordered.

    Declaration

    Swift

    public func equalsIgnoreKeyOrder(_ other: BSONDocument) -> Bool

    Parameters

    other

    a BSONDocument to compare this document with.

    Return Value

    a Bool indicating whether the two documents are equal.

  • 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 -> BSONDocument

    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.