RandomAccessIndexable

protocol RandomAccessIndexable

A collection that supports efficient random-access index traversal.

In most cases, it's best to ignore this protocol and use the RandomAccessCollection protocol instead, because it has a more complete interface.

Deprecated: it will be removed in Swift 4.0. Please use 'RandomAccessCollection' instead.

Inheritance BidirectionalIndexable, Indexable, IndexableBase View Protocol Hierarchy →
Associated Types
IndexDistance : SignedInteger = Int

A type used to represent the number of steps between two indices, where one value is reachable from the other.

In Swift, reachability refers to the ability to produce one value from the other through zero or more applications of index(after:).

Index : Comparable

A type that represents a position in the collection.

Valid indices consist of the position of every element and a "past the end" position that's not valid for use as a subscript argument.

See Also: endIndex

SubSequence

A sequence that can represent a contiguous subrange of the collection's elements.
Import import Swift

Instance Variables

var endIndex: Self.Index Required

The collection's "past the end" position---that is, the position one greater than the last valid subscript argument.

When you need a range that includes the last element of a collection, use the half-open range operator (..<) with endIndex. The ..< operator creates a range that doesn't include the upper bound, so it's always safe to use with endIndex. For example:

let numbers = [10, 20, 30, 40, 50]
if let index = numbers.index(of: 30) {
    print(numbers[index ..< numbers.endIndex])
}
// Prints "[30, 40, 50]"

If the collection is empty, endIndex is equal to startIndex.

Declaration

var endIndex: Self.Index { get }

Declared In

IndexableBase
var startIndex: Self.Index Required

The position of the first element in a nonempty collection.

If the collection is empty, startIndex is equal to endIndex.

Declaration

var startIndex: Self.Index { get }

Declared In

IndexableBase

Subscripts

subscript(_: Self.Index) Required

Accesses the element at the specified position.

The following example accesses an element of an array through its subscript to print its value:

var streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
print(streets[1])
// Prints "Bryant"

You can subscript a collection with any valid index other than the collection's end index. The end index refers to the position one past the last element of a collection, so it doesn't correspond with an element.

position: The position of the element to access. position must be a valid index of the collection that is not equal to the endIndex property.

Declaration

subscript(position: Self.Index) -> Self._Element { get }

Declared In

IndexableBase
subscript(_: Range<Self.Index>) Required

Accesses the subsequence bounded by the given range.

bounds: A range of the collection's indices. The upper and lower bounds of the bounds range must be valid indices of the collection.

Declaration

subscript(bounds: Range<Self.Index>) -> Self.SubSequence { get }

Declared In

IndexableBase

Instance Methods

func distance(from:to:)

Returns the distance between two indices.

Unless the collection conforms to the BidirectionalCollection protocol, start must be less than or equal to end.

Parameters: start: A valid index of the collection. end: Another valid index of the collection. If end is equal to start, the result is zero. Returns: The distance between start and end. The result can be negative only if the collection conforms to the BidirectionalCollection protocol.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the resulting distance.

Declaration

func distance(from start: Self.Index, to end: Self.Index) -> Self.IndexDistance

Declared In

Indexable
func formIndex(_:offsetBy:)

Offsets the given index by the specified distance.

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol.

See Also: index(_:offsetBy:), formIndex(_:offsetBy:limitedBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func formIndex(_ i: inout Self.Index, offsetBy n: Self.IndexDistance)

Declared In

Indexable
func formIndex(_:offsetBy:limitedBy:)

Offsets the given index by the specified distance, or so that it equals the given limiting index.

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. Returns: true if i has been offset by exactly n steps without going beyond limit; otherwise, false. When the return value is false, the value of i is equal to limit.

See Also: index(_:offsetBy:), formIndex(_:offsetBy:limitedBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func formIndex(_ i: inout Self.Index, offsetBy n: Self.IndexDistance, limitedBy limit: Self.Index) -> Bool

Declared In

Indexable
func formIndex(after:)

Replaces the given index with its successor.

i: A valid index of the collection. i must be less than endIndex.

Declaration

func formIndex(after i: inout Self.Index)

Declared In

IndexableBase
func formIndex(before:)

Replaces the given index with its predecessor.

i: A valid index of the collection. i must be greater than startIndex.

Declaration

func formIndex(before i: inout Self.Index)

Declared In

BidirectionalIndexable
func index(_:offsetBy:)

Returns an index that is the specified distance from the given index.

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position.

let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. Returns: An index offset by n from the index i. If n is positive, this is the same value as the result of n calls to index(after:). If n is negative, this is the same value as the result of -n calls to index(before:).

See Also: index(_:offsetBy:limitedBy:), formIndex(_:offsetBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func index(_ i: Self.Index, offsetBy n: Self.IndexDistance) -> Self.Index

Declared In

Indexable
func index(_:offsetBy:limitedBy:)

Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position. The operation doesn't require going beyond the limiting s.endIndex value, so it succeeds.

let s = "Swift"
if let i = s.index(s.startIndex, offsetBy: 4, limitedBy: s.endIndex) {
    print(s[i])
}
// Prints "t"

The next example attempts to retrieve an index six positions from s.startIndex but fails, because that distance is beyond the index passed as limit.

let j = s.index(s.startIndex, offsetBy: 6, limitedBy: s.endIndex)
print(j)
// Prints "nil"

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. limit: A valid index of the collection to use as a limit. If n > 0, a limit that is less than i has no effect. Likewise, if n < 0, a limit that is greater than i has no effect. Returns: An index offset by n from the index i, unless that index would be beyond limit in the direction of movement. In that case, the method returns nil.

See Also: index(_:offsetBy:), formIndex(_:offsetBy:limitedBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func index(_ i: Self.Index, offsetBy n: Self.IndexDistance, limitedBy limit: Self.Index) -> Self.Index?

Declared In

Indexable
func index(after:) Required

Returns the position immediately after the given index.

i: A valid index of the collection. i must be less than endIndex. Returns: The index value immediately after i.

Declaration

func index(after i: Self.Index) -> Self.Index

Declared In

IndexableBase
func index(before:) Required

Returns the position immediately before the given index.

i: A valid index of the collection. i must be greater than startIndex. Returns: The index value immediately before i.

Declaration

func index(before i: Self.Index) -> Self.Index

Declared In

BidirectionalIndexable

Default Implementations

subscript(_: ClosedRange<Self.Index>)

Accesses a contiguous subrange of the collection's elements.

The accessed slice uses the same indices for the same elements as the original collection. Always use the slice's startIndex property instead of assuming that its indices start at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"

let index = streetsSlice.index(of: "Evarts")    // 4
print(streets[index!])
// Prints "Evarts"

bounds: A range of the collection's indices. The bounds of the range must be valid indices of the collection.

Declaration

subscript(bounds: ClosedRange<Self.Index>) -> Self.SubSequence { get }

Declared In

BidirectionalIndexable, Indexable
func distance(from:to:)

Returns the distance between two indices.

Unless the collection conforms to the BidirectionalCollection protocol, start must be less than or equal to end.

Parameters: start: A valid index of the collection. end: Another valid index of the collection. If end is equal to start, the result is zero. Returns: The distance between start and end. The result can be negative only if the collection conforms to the BidirectionalCollection protocol.

Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the resulting distance.

Declaration

func distance(from start: Self.Index, to end: Self.Index) -> Self.IndexDistance

Declared In

BidirectionalIndexable, Indexable
func formIndex(_:offsetBy:)

Offsets the given index by the specified distance.

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol.

See Also: index(_:offsetBy:), formIndex(_:offsetBy:limitedBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func formIndex(_ i: inout Self.Index, offsetBy n: Self.IndexDistance)

Declared In

BidirectionalIndexable, Indexable
func formIndex(_:offsetBy:limitedBy:)

Offsets the given index by the specified distance, or so that it equals the given limiting index.

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. Returns: true if i has been offset by exactly n steps without going beyond limit; otherwise, false. When the return value is false, the value of i is equal to limit.

See Also: index(_:offsetBy:), formIndex(_:offsetBy:limitedBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func formIndex(_ i: inout Self.Index, offsetBy n: Self.IndexDistance, limitedBy limit: Self.Index) -> Bool

Declared In

BidirectionalIndexable, Indexable
func formIndex(after:)

Replaces the given index with its successor.

i: A valid index of the collection. i must be less than endIndex.

Declaration

func formIndex(after i: inout Self.Index)

Declared In

BidirectionalIndexable, Indexable
func formIndex(before:)

Replaces the given index with its predecessor.

i: A valid index of the collection. i must be greater than startIndex.

Declaration

func formIndex(before i: inout Self.Index)

Declared In

BidirectionalIndexable
func index(_:offsetBy:)

Returns an index that is the specified distance from the given index.

The following example obtains an index advanced four positions from a string's starting index and then prints the character at that position.

let s = "Swift"
let i = s.index(s.startIndex, offsetBy: 4)
print(s[i])
// Prints "t"

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection.

Parameters: i: A valid index of the collection. n: The distance to offset i. n must not be negative unless the collection conforms to the BidirectionalCollection protocol. Returns: An index offset by n from the index i. If n is positive, this is the same value as the result of n calls to index(after:). If n is negative, this is the same value as the result of -n calls to index(before:).

See Also: index(_:offsetBy:limitedBy:), formIndex(_:offsetBy:) Complexity: O(1) if the collection conforms to RandomAccessCollection; otherwise, O(n), where n is the absolute value of n.

Declaration

func index(_ i: Self.Index, offsetBy n: Self.IndexDistance) -> Self.Index

Declared In

BidirectionalIndexable, Indexable
func index(_:offsetBy:limitedBy:)

Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.

The following example obtains an index advanced four positions from an array's starting index and then prints the element at that position. The operation doesn't require going beyond the limiting numbers.endIndex value, so it succeeds.

let numbers = [10, 20, 30, 40, 50]
let i = numbers.index(numbers.startIndex, offsetBy: 4)
print(numbers[i])
// Prints "50"

The next example attempts to retrieve an index ten positions from numbers.startIndex, but fails, because that distance is beyond the index passed as limit.

let j = numbers.index(numbers.startIndex,
                      offsetBy: 10,
                      limitedBy: numbers.endIndex)
print(j)
// Prints "nil"

The value passed as n must not offset i beyond the endIndex or before the startIndex of this collection, unless the index passed as limit prevents offsetting beyond those bounds.

Parameters: i: A valid index of the array. n: The distance to offset i. limit: A valid index of the collection to use as a limit. If n > 0, limit should be greater than i to have any effect. Likewise, if n < 0, limit should be less than i to have any effect. Returns: An index offset by n from the index i, unless that index would be beyond limit in the direction of movement. In that case, the method returns nil.

Complexity: O(1)

Declaration

func index(_ i: Self.Index, offsetBy n: Self.IndexDistance, limitedBy limit: Self.Index) -> Self.Index?

Declared In

RandomAccessIndexable, BidirectionalIndexable, Indexable

Where Index : Strideable, Index.Stride : SignedInteger

subscript(_: CountableClosedRange<Self.Index>)

Accesses a contiguous subrange of the collection's elements.

The accessed slice uses the same indices for the same elements as the original collection. Always use the slice's startIndex property instead of assuming that its indices start at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"

let index = streetsSlice.index(of: "Evarts")    // 4
print(streets[index!])
// Prints "Evarts"

bounds: A range of the collection's indices. The bounds of the range must be valid indices of the collection.

Declaration

subscript(bounds: CountableClosedRange<Self.Index>) -> Self.SubSequence { get }

Declared In

BidirectionalIndexable, Indexable
subscript(_: CountableRange<Self.Index>)

Accesses a contiguous subrange of the collection's elements.

The accessed slice uses the same indices for the same elements as the original collection. Always use the slice's startIndex property instead of assuming that its indices start at a particular value.

This example demonstrates getting a slice of an array of strings, finding the index of one of the strings in the slice, and then using that index in the original array.

let streets = ["Adams", "Bryant", "Channing", "Douglas", "Evarts"]
let streetsSlice = streets[2 ..< streets.endIndex]
print(streetsSlice)
// Prints "["Channing", "Douglas", "Evarts"]"

let index = streetsSlice.index(of: "Evarts")    // 4
print(streets[index!])
// Prints "Evarts"

bounds: A range of the collection's indices. The bounds of the range must be valid indices of the collection.

Declaration

subscript(bounds: CountableRange<Self.Index>) -> Self.SubSequence { get }

Declared In

BidirectionalIndexable, Indexable