Document

@dynamicMemberLookup
public struct Document

A struct representing the BSON document type.

  • 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 decoding Dates, because of limitations of decoding to AnyBSONValues. See AnyBSONValue.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 }
  • 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 Document, 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 Document, 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>) -> 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() and split().

    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 this Document.

    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

    Swift

    public func mapValues(_ transform: (BSONValue) throws -> BSONValue) rethrows -> Document

    Parameters

    transform

    A closure that transforms a BSONValue. transform accepts each value of the document as its parameter and returns a transformed BSONValue of the same or of a different type.

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

  • 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 this Document.

    Declaration

    Swift

    public var keys: [String] { get }
  • Returns a [BSONValue] containing the values stored in this Document.

    Declaration

    Swift

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

    Declaration

    Swift

    public var count: Int { 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 as Data.

    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 a Document

    Return Value

    the parsed Document

  • Convenience initializer for constructing a Document from a String.

    Throws

    • A UserError.invalidArgumentError if the string passed in is invalid JSON.

    Declaration

    Swift

    public init(fromJSON json: String) throws
  • Constructs a Document from raw BSON Data.

    Declaration

    Swift

    public init(fromBSON: Data)
  • Returns a Boolean indicating whether this Document 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 a BSONNull.

    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"
    

    Declaration

    Swift

    public subscript(key: String, default defaultValue: @autoclosure () -> BSONValue) -> BSONValue
  • 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 a BSONNull.

    Only available in Swift 4.2+.

    Declaration

    Swift

    @available(swift 4.2)
    public subscript(dynamicMember member: String) -> BSONValue? { get set }
  • 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 are Strings and the values are BSONValues. 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 are BSONValues. 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