View on GitHub
Install in Dash
Cursor Protocol Reference
Cursor
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.
-
The type of element traversed by the cursor.
-
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.
-
forEach(_:Default implementation) Calls the given closure on each element in the cursor.
Default Implementation
Calls the given closure on each element in the cursor.
-
isEmptyExtension methodReturns a Boolean value indicating whether the cursor does not contain any element.
Important
This property may consume elements. -
contains(where:Extension method) Returns a Boolean value indicating whether the cursor contains an element that satisfies the given predicate.
-
enumerated()Extension methodReturns 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" -
filter(_:Extension method) Returns the elements of the cursor that satisfy the given predicate.
-
first(where:Extension method) Returns the first element of the cursor that satisfies the given predicate or nil if no such element is found.
-
compactMap(_:Extension method) Returns a cursor over the concatenated non-nil results of mapping transform over this cursor.
-
drop(while:Extension method) Returns a cursor that skips any initial elements that satisfy
predicate. -
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 "[]" -
dropFirst()Extension methodReturns 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.
-
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 "[]" -
dropLast()Extension methodReturns 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.
-
flatMap(_:Extension method) Returns a cursor over the concatenated results of mapping transform over self.
-
map(_:Extension method) Returns a cursor over the results of the transform function applied to this cursor’s elements.
-
max(by:Extension method) Returns the maximum element in the cursor, using the given predicate as the comparison between elements.
-
min(by:Extension method) Returns the minimum element in the cursor, using the given predicate as the comparison between elements.
-
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]" -
prefix(while:Extension method) Returns a cursor of the initial consecutive elements that satisfy
predicate. -
reduce(_:Extension method_: ) Returns the result of calling the given combining closure with each element of this cursor and an accumulating value.
-
reduce(into:Extension method_: ) Returns the result of calling the given combining closure with each element of this cursor and an accumulating value.
-
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]"
-
contains(_:Extension method) Returns a Boolean value indicating whether the cursor contains the given element.
-
joined()Extension methodReturns the elements of this cursor of cursors, concatenated.
-
joined(separator:Extension method) Returns the elements of this cursor of sequences, concatenated.