Returns an index that is the specified distance from the given index, unless that distance is beyond a given limiting index.
Required. Default implementation provided.
SDK
- Xcode 10.0+
Framework
- Swift Standard Library
Declaration
func index(_ i: Self.Index, offsetBy distance: Int, limitedBy limit: Self.Index) -> Self.Index?
Parameters
iA valid index of the collection.
distanceThe distance to offset
i.distancemust not be negative unless the collection conforms to theBidirectionalprotocol.Collection limitA valid index of the collection to use as a limit. If
distance > 0, a limit that is less thanihas no effect. Likewise, ifdistance < 0, a limit that is greater thanihas no effect.
Return Value
An index offset by distance from the index i, unless that index would be beyond limit in the direction of movement. In that case, the method returns nil.
Discussion
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 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 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 distance must not offset i beyond the bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.
Complexity: O(1) if the collection conforms to Random; otherwise, O(k), where k is the absolute value of distance.