Cursor

public protocol Cursor : class

A type that supplies the values of some external resource, one at a time.

Overview

The most common way to iterate over the elements of a cursor is to use a while loop:

let cursor = ...
while let element = try cursor.next() {
    ...
}

Relationship with standard Sequence and IteratorProtocol

Cursors share traits with lazy sequences and iterators from the Swift standard library. Differences are:

  • Cursor types are classes, and have a lifetime.
  • Cursor iteration may throw errors.
  • A cursor can not be repeated.

The protocol comes with default implementations for many operations similar to those defined by Swift’s LazySequenceProtocol:

  • func contains(Self.Element)
  • func contains(where: (Self.Element) throws -> Bool)
  • func enumerated()
  • func filter((Self.Element) throws -> Bool)
  • func first(where: (Self.Element) throws -> Bool)
  • func flatMap<ElementOfResult>((Self.Element) throws -> ElementOfResult?)
  • func flatMap<SegmentOfResult>((Self.Element) throws -> SegmentOfResult)
  • func forEach((Self.Element) throws -> Void)
  • func joined()
  • func map<T>((Self.Element) throws -> T)
  • func reduce<Result>(Result, (Result, Self.Element) throws -> Result)
  • The type of element traversed by the cursor.

    Declaration

    Swift

    associatedtype Element
  • Advances to the next element and returns it, or nil if no next element exists. Once nil has been returned, all subsequent calls return nil.

    Declaration

    Swift

    func next() throws -> Element?
  • contains(where:) Extension method

    Returns a Boolean value indicating whether the cursor contains an element that satisfies the given predicate.

    Declaration

    Swift

    public func contains(where predicate: (Element) throws -> Bool) throws -> Bool

    Parameters

    predicate

    A closure that takes an element of the cursor as its argument and returns a Boolean value that indicates whether the passed element represents a match.

    Return Value

    true if the cursor contains an element that satisfies predicate; otherwise, false.

  • enumerated() Extension method

    Returns a cursor of pairs (n, x), where n represents a consecutive integer starting at zero, and x represents an element of the cursor.

    let cursor = try String.fetchCursor(db, "SELECT 'foo' UNION ALL SELECT 'bar'")
    let c = cursor.enumerated()
    while let (n, x) = c.next() {
        print("\(n): \(x)")
    }
    // Prints: "0: foo"
    // Prints: "1: bar"
    

    Declaration

    Swift

    public func enumerated() -> EnumeratedCursor<Self>
  • filter(_:) Extension method

    Returns the elements of the cursor that satisfy the given predicate.

    Declaration

    Swift

    public func filter(_ isIncluded: @escaping (Element) throws -> Bool) -> FilterCursor<Self>
  • first(where:) Extension method

    Returns the first element of the cursor that satisfies the given predicate or nil if no such element is found.

    Declaration

    Swift

    public func first(where predicate: (Element) throws -> Bool) throws -> Element?
  • flatMap(_:) Extension method

    Returns a cursor over the concatenated non-nil results of mapping transform over this cursor.

    Declaration

    Swift

    public func flatMap<ElementOfResult>(_ transform: @escaping (Element) throws -> ElementOfResult?) -> MapCursor<FilterCursor<MapCursor<Self, ElementOfResult?>>, ElementOfResult>
  • flatMap(_:) Extension method

    Returns a cursor over the concatenated results of mapping transform over self.

    Declaration

    Swift

    public func flatMap<SegmentOfResult: Sequence>(_ transform: @escaping (Element) throws -> SegmentOfResult) -> FlattenCursor<MapCursor<Self, IteratorCursor<SegmentOfResult.Iterator>>>
  • flatMap(_:) Extension method

    Returns a cursor over the concatenated results of mapping transform over self.

    Declaration

    Swift

    public func flatMap<SegmentOfResult: Cursor>(_ transform: @escaping (Element) throws -> SegmentOfResult) -> FlattenCursor<MapCursor<Self, SegmentOfResult>>
  • forEach(_:) Extension method

    Calls the given closure on each element in the cursor.

    Declaration

    Swift

    public func forEach(_ body: (Element) throws -> Void) throws
  • map(_:) Extension method

    Returns a cursor over the results of the transform function applied to this cursor’s elements.

    Declaration

    Swift

    public func map<T>(_ transform: @escaping (Element) throws -> T) -> MapCursor<Self, T>
  • reduce(_:_:) Extension method

    Returns the result of calling the given combining closure with each element of this sequence and an accumulating value.

    Declaration

    Swift

    public func reduce<Result>(_ initialResult: Result, _ nextPartialResult: (Result, Element) throws -> Result) throws -> Result
  • contains(_:) Extension method

    Returns a Boolean value indicating whether the cursor contains the given element.

    Declaration

    Swift

    public func contains(_ element: Element) throws -> Bool