Cursor

public protocol Cursor : AnyObject

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 Sequence protocol: contains, dropFirst, dropLast, drop(while:), enumerated, filter, first, flatMap, forEach, joined, joined(separator:), max, max(by:), min, min(by:), map, prefix, prefix(while:), reduce, reduce(into:), suffix.

Show on GitHub

  • The type of element traversed by the cursor.

    Declaration

    Swift

    associatedtype Element
    Show on GitHub

  • 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?
    Show on GitHub

Cursor

  • isEmpty() Extension method

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

    Declaration

    Swift

    public func isEmpty() throws -> Bool
    Show on GitHub
  • 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.

    Show on GitHub
  • 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, sql: "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>
    Show on GitHub
  • 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>
    Show on GitHub
  • 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?
    Show on GitHub
  • compactMap(_:) Extension method

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

    Declaration

    Swift

    public func compactMap<ElementOfResult>(_ transform: @escaping (Element) throws -> ElementOfResult?)
-> MapCursor<FilterCursor<MapCursor<Self, ElementOfResult?>>, ElementOfResult>
    Show on GitHub
  • drop(while:) Extension method

    Returns a cursor that skips any initial elements that satisfy predicate.

    Declaration

    Swift

    public func drop(while predicate: @escaping (Element) throws -> Bool) -> DropWhileCursor<Self>

    Parameters

    predicate

    A closure that takes an element of the cursir as its argument and returns true if the element should be skipped or false otherwise. Once predicate returns false it will not be called again.
    Show on GitHub
  • dropFirst(_:) Extension method

    Returns a cursor containing all but the given number of initial elements.

    If the number of elements to drop exceeds the number of elements in the cursor, the result is an empty cursor.

    let numbers = AnyCursor([1, 2, 3, 4, 5])
try print(numbers.dropFirst(2))
// Prints "[3, 4, 5]"
try print(numbers.dropFirst(10))
// Prints "[]"

    Declaration

    Swift

    public func dropFirst(_ n: Int) -> DropFirstCursor<Self>

    Parameters

    n

    The number of elements to drop from the beginning of the cursor. n must be greater than or equal to zero.

    Return Value

    A cursor starting after the specified number of elements.

    Show on GitHub
  • dropFirst() Extension method

    Returns a cursor containing all but the first element of the cursor.

    The following example drops the first element from a cursor of integers.

    let numbers = AnyCursor([1, 2, 3, 4, 5])
try print(numbers.dropFirst())
// Prints "[2, 3, 4, 5]"

    If the cursor has no elements, the result is an empty cursor.

    Declaration

    Swift

    public func dropFirst() -> DropFirstCursor<Self>

    Return Value

    A cursor starting after the first element of the cursor.

    Show on GitHub
  • dropLast(_:) Extension method

    Returns an array containing all but the given number of final elements.

    The cursor must be finite. If the number of elements to drop exceeds the number of elements in the cursor, the result is an empty array.

    let numbers = AnyCursor([1, 2, 3, 4, 5])
try print(numbers.dropLast(2))
// Prints "[1, 2, 3]"
try print(numbers.dropLast(10))
// Prints "[]"

    Declaration

    Swift

    public func dropLast(_ n: Int) throws -> [Element]

    Parameters

    n

    The number of elements to drop off the end of the cursor. n must be greater than or equal to zero.

    Return Value

    An array leaving off the specified number of elements.

    Show on GitHub
  • dropLast() Extension method

    Returns an array containing all but the last element of the cursor.

    The following example drops the last element from a cursor of integers.

    let numbers = AnyCursor([1, 2, 3, 4, 5])
try print(numbers.dropLast())
// Prints "[1, 2, 3, 4]"

    If the cursor has no elements, the result is an empty cursor.

    Declaration

    Swift

    public func dropLast() throws -> [Element]

    Return Value

    An array leaving off the last element of the cursor.

    Show on GitHub
  • flatMap(_:) Extension method

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

    Declaration

    Swift

    public func flatMap<SegmentOfResult>(_ transform: @escaping (Element) throws -> SegmentOfResult)
-> FlattenCursor<MapCursor<Self, AnyCursor<SegmentOfResult.Element>>>
where SegmentOfResult: Sequence
    Show on GitHub
  • flatMap(_:) Extension method

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

    Declaration

    Swift

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

    Calls the given closure on each element in the cursor.

    Declaration

    Swift

    public func forEach(_ body: (Element) throws -> Void) throws
    Show on GitHub
  • 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>
    Show on GitHub
  • max(by:) Extension method

    Returns the maximum element in the cursor, using the given predicate as the comparison between elements.

    Declaration

    Swift

    public func max(by areInIncreasingOrder: (Element, Element) throws -> Bool) throws -> Element?

    Parameters

    areInIncreasingOrder

    A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false.

    Return Value

    The cursor’s maximum element, according to areInIncreasingOrder. If the cursor has no elements, returns nil.

    Show on GitHub
  • min(by:) Extension method

    Returns the minimum element in the cursor, using the given predicate as the comparison between elements.

    Declaration

    Swift

    public func min(by areInIncreasingOrder: (Element, Element) throws -> Bool) throws -> Element?

    Parameters

    areInIncreasingOrder

    A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false.

    Return Value

    The cursor’s minimum element, according to areInIncreasingOrder. If the cursor has no elements, returns nil.

    Show on GitHub
  • prefix(_:) Extension method

    Returns a cursor, up to the specified maximum length, containing the initial elements of the cursor.

    If the maximum length exceeds the number of elements in the cursor, the result contains all the elements in the cursor.

    let numbers = AnyCursor([1, 2, 3, 4, 5])
try print(numbers.prefix(2))
// Prints "[1, 2]"
try print(numbers.prefix(10))
// Prints "[1, 2, 3, 4, 5]"

    Declaration

    Swift

    public func prefix(_ maxLength: Int) -> PrefixCursor<Self>

    Parameters

    maxLength

    The maximum number of elements to return. The value of maxLength must be greater than or equal to zero.

    Return Value

    A cursor starting at the beginning of this cursor with at most maxLength elements.

    Show on GitHub
  • prefix(while:) Extension method

    Returns a cursor of the initial consecutive elements that satisfy predicate.

    Declaration

    Swift

    public func prefix(while predicate: @escaping (Element) throws -> Bool) -> PrefixWhileCursor<Self>

    Parameters

    predicate

    A closure that takes an element of the cursor as its argument and returns true if the element should be included or false otherwise. Once predicate returns false it will not be called again.
    Show on GitHub
  • reduce(_:_:) Extension method

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

    Declaration

    Swift

    public func reduce<Result>(
    _ initialResult: Result,
    _ nextPartialResult: (Result, Element) throws -> Result)
throws -> Result
    Show on GitHub
  • reduce(into:_:) Extension method

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

    Declaration

    Swift

    public func reduce<Result>(
    into initialResult: Result,
    _ updateAccumulatingResult: (inout Result, Element) throws -> Void)
throws -> Result
    Show on GitHub
  • suffix(_:) Extension method

    Returns an array, up to the given maximum length, containing the final elements of the cursor.

    The cursor must be finite. If the maximum length exceeds the number of elements in the cursor, the result contains all the elements in the cursor.

    let numbers = AnyCursor([1, 2, 3, 4, 5])
try print(numbers.suffix(2))
// Prints "[4, 5]"
try print(numbers.suffix(10))
// Prints "[1, 2, 3, 4, 5]"

    Declaration

    Swift

    public func suffix(_ maxLength: Int) throws -> [Element]

    Parameters

    maxLength

    The maximum number of elements to return. The value of maxLength must be greater than or equal to zero.
    Show on GitHub

Available where Element: Equatable

  • contains(_:) Extension method

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

    Declaration

    Swift

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

Available where Element: Comparable

  • max() Extension method

    Returns the maximum element in the cursor.

    Declaration

    Swift

    public func max() throws -> Element?

    Parameters

    areInIncreasingOrder

    A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false.

    Return Value

    The cursor’s maximum element, according to areInIncreasingOrder. If the cursor has no elements, returns nil.

    Show on GitHub
  • min() Extension method

    Returns the minimum element in the cursor.

    Declaration

    Swift

    public func min() throws -> Element?

    Parameters

    areInIncreasingOrder

    A predicate that returns true if its first argument should be ordered before its second argument; otherwise, false.

    Return Value

    The cursor’s minimum element, according to areInIncreasingOrder. If the cursor has no elements, returns nil.

    Show on GitHub

Available where Element: Cursor

  • joined() Extension method

    Returns the elements of this cursor of cursors, concatenated.

    Declaration

    Swift

    public func joined() -> FlattenCursor<Self>
    Show on GitHub

Available where Element: Sequence

Available where Element: StringProtocol

  • joined(separator:) Extension method

    Returns the elements of this cursor of sequences, concatenated.

    Declaration

    Swift

    public func joined(separator: String = "") throws -> String
    Show on GitHub