Instance Method

index(_:offsetBy:limitedBy:)

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

Declaration

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

Parameters

i

A valid index of the collection.

n

The distance to offset i.

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.

Return Value

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.

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.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 bounds of the collection, unless the index passed as limit prevents offsetting beyond those bounds.

Complexity: O(n), where n is the absolute value of n.

Relationships

From Protocol

See Also

Manipulating Indices

var startIndex: String.Index

The position of the first character in a nonempty string.

var endIndex: String.Index

A string’s “past the end” position—that is, the position one greater than the last valid subscript argument.

func index(after: String.Index)

Returns the position immediately after the given index.

func index(String.Index, offsetBy: String.IndexDistance)

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

func distance(from: String.Index, to: String.Index)

Returns the distance between two indices.

var indices: DefaultBidirectionalIndices<String>

The indices that are valid for subscripting the collection, in ascending order.