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.

Element
The type of element traversed by the cursor.
Declaration
Swift

associatedtype Element
Show on GitHub
next()
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

Equatable elements

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

Comparable elements


                    
                    
                    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

Cursor elements

joined() Extension method
Returns the elements of this cursor of cursors, concatenated.
Declaration
Swift

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

Sequence elements

joined() Extension method
Returns the elements of this cursor of sequences, concatenated.
Declaration
Swift

public func joined() -> FlattenCursor<MapCursor<Self, AnyCursor<Element.Element>>>
Show on GitHub

String elements

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