SwiftDoc.org

Creates a new index at the specified UTF-16 offset.

offset: An offset in UTF-16 code units.

Declaration

init(encodedOffset offset: Int)

Creates an index in the given string that corresponds exactly to the specified position.

If the index passed as sourcePosition represents the start of an extended grapheme cluster---the element type of a string---then the initializer succeeds.

The following example converts the position of the Unicode scalar "e" into its corresponding position in the string. The character at that position is the composed "é" character.

let cafe = "Cafe\u{0301}"
print(cafe)
// Prints "Café"

let scalarsIndex = cafe.unicodeScalars.firstIndex(of: "e")!
let stringIndex = String.Index(scalarsIndex, within: cafe)!

print(cafe[...stringIndex])
// Prints "Café"

If the index passed as sourcePosition doesn't have an exact corresponding position in target, the result of the initializer is nil. For example, an attempt to convert the position of the combining acute accent ("\u{0301}") fails. Combining Unicode scalars do not have their own position in a string.

let nextScalarsIndex = cafe.unicodeScalars.index(after: scalarsIndex)
let nextStringIndex = String.Index(nextScalarsIndex, within: cafe)

print(nextStringIndex)
// Prints "nil"

Parameters: sourcePosition: A position in a view of the target parameter. sourcePosition must be a valid index of at least one of the views of target. target: The string referenced by the resulting index.

Declaration

init?(_ sourcePosition: String.Index, within target: String)

Creates an index in the given UTF-8 view that corresponds exactly to the specified UTF16View position.

The following example finds the position of a space in a string's utf16 view and then converts that position to an index in the string's utf8 view.

let cafe = "Café 🍵"

let utf16Index = cafe.utf16.firstIndex(of: 32)!
let utf8Index = String.UTF8View.Index(utf16Index, within: cafe.utf8)!

print(Array(cafe.utf8[..<utf8Index]))
// Prints "[67, 97, 102, 195, 169]"

If the position passed in utf16Index doesn't have an exact corresponding position in utf8, the result of the initializer is nil. For example, because UTF-8 and UTF-16 represent high Unicode code points differently, an attempt to convert the position of the trailing surrogate of a UTF-16 surrogate pair fails.

The next example attempts to convert the indices of the two UTF-16 code points that represent the teacup emoji ("🍵"). The index of the lead surrogate is successfully converted to a position in utf8, but the index of the trailing surrogate is not.

let emojiHigh = cafe.utf16.index(after: utf16Index)
print(String.UTF8View.Index(emojiHigh, within: cafe.utf8))
// Prints "Optional(String.Index(...))"

let emojiLow = cafe.utf16.index(after: emojiHigh)
print(String.UTF8View.Index(emojiLow, within: cafe.utf8))
// Prints "nil"

Parameters: sourcePosition: A position in a String or one of its views. target: The UTF8View in which to find the new position.

Declaration

init?(_ sourcePosition: String.Index, within target: String.UTF8View)

Creates an index in the given UTF-16 view that corresponds exactly to the specified string position.

If the index passed as sourcePosition represents either the start of a Unicode scalar value or the position of a UTF-16 trailing surrogate, then the initializer succeeds. If sourcePosition does not have an exact corresponding position in target, then the result is nil. For example, an attempt to convert the position of a UTF-8 continuation byte results in nil.

The following example finds the position of a space in a string and then converts that position to an index in the string's utf16 view.

let cafe = "Café 🍵"

let stringIndex = cafe.firstIndex(of: "é")!
let utf16Index = String.Index(stringIndex, within: cafe.utf16)!

print(cafe.utf16[...utf16Index])
// Prints "Café"

Parameters: sourcePosition: A position in at least one of the views of the string shared by target. target: The UTF16View in which to find the new position.

Declaration

init?(_ sourcePosition: String.Index, within target: String.UTF16View)

Creates an index in the given Unicode scalars view that corresponds exactly to the specified UTF16View position.

The following example finds the position of a space in a string's utf16 view and then converts that position to an index in the string's unicodeScalars view:

let cafe = "Café 🍵"

let utf16Index = cafe.utf16.firstIndex(of: 32)!
let scalarIndex = String.Index(utf16Index, within: cafe.unicodeScalars)!

print(String(cafe.unicodeScalars[..<scalarIndex]))
// Prints "Café"

If the index passed as sourcePosition doesn't have an exact corresponding position in unicodeScalars, the result of the initializer is nil. For example, an attempt to convert the position of the trailing surrogate of a UTF-16 surrogate pair results in nil.

Parameters: sourcePosition: A position in the utf16 view of a string. utf16Index must be an element of String(unicodeScalars).utf16.indices. unicodeScalars: The UnicodeScalarView in which to find the new position.

Declaration

init?(_ sourcePosition: String.UTF16Index, within unicodeScalars: String.UnicodeScalarView)

The offset into a string's UTF-16 encoding for this index.

Declaration

var encodedOffset: Int { get }

Hashes the essential components of this value by feeding them into the given hasher.

hasher: The hasher to use when combining the components of this instance.

Declaration

var hashValue: Int { get }

Returns the position in the given string that corresponds exactly to this index.

This example first finds the position of a space (UTF-8 code point 32) in a string's utf8 view and then uses this method find the same position in the string.

let cafe = "Café 🍵"
let i = cafe.unicodeScalars.firstIndex(of: "🍵")
let j = i.samePosition(in: cafe)!
print(cafe[j...])
// Prints "🍵"

characters: The string to use for the index conversion. This index must be a valid index of at least one view of characters. Returns: The position in characters that corresponds exactly to this index. If this index does not have an exact corresponding position in characters, this method returns nil. For example, an attempt to convert the position of a UTF-8 continuation byte returns nil.

Declaration

func samePosition(in characters: String) -> String.Index?

Returns the position in the given UTF-8 view that corresponds exactly to this index.

This example first finds the position of the character "é", and then uses this method find the same position in the string's utf8 view.

let cafe = "Café"
if let i = cafe.firstIndex(of: "é") {
    let j = i.samePosition(in: cafe.utf8)!
    print(Array(cafe.utf8[j...]))
}
// Prints "[195, 169]"

utf8: The view to use for the index conversion. This index must be a valid index of at least one view of the string shared by utf8. Returns: The position in utf8 that corresponds exactly to this index. If this index does not have an exact corresponding position in utf8, this method returns nil. For example, an attempt to convert the position of a UTF-16 trailing surrogate returns nil.

Declaration

func samePosition(in utf8: String.UTF8View) -> String.UTF8View.Index?

Returns the position in the given UTF-16 view that corresponds exactly to this index.

The index must be a valid index of String(utf16).

This example first finds the position of the character "é" and then uses this method find the same position in the string's utf16 view.

let cafe = "Café"
if let i = cafe.firstIndex(of: "é") {
    let j = i.samePosition(in: cafe.utf16)!
    print(cafe.utf16[j])
}
// Prints "233"

utf16: The view to use for the index conversion. This index must be a valid index of at least one view of the string shared by utf16. Returns: The position in utf16 that corresponds exactly to this index. If this index does not have an exact corresponding position in utf16, this method returns nil. For example, an attempt to convert the position of a UTF-8 continuation byte returns nil.

Declaration

func samePosition(in utf16: String.UTF16View) -> String.UTF16View.Index?

Returns the position in the given view of Unicode scalars that corresponds exactly to this index.

This index must be a valid index of String(unicodeScalars).utf16.

This example first finds the position of a space (UTF-16 code point 32) in a string's utf16 view and then uses this method to find the same position in the string's unicodeScalars view.

let cafe = "Café 🍵"
let i = cafe.utf16.firstIndex(of: 32)!
let j = i.samePosition(in: cafe.unicodeScalars)!
print(cafe.unicodeScalars[..<j])
// Prints "Café"

unicodeScalars: The view to use for the index conversion. This index must be a valid index of at least one view of the string shared by unicodeScalars. Returns: The position in unicodeScalars that corresponds exactly to this index. If this index does not have an exact corresponding position in unicodeScalars, this method returns nil. For example, an attempt to convert the position of a UTF-16 trailing surrogate returns nil.

Declaration

func samePosition(in unicodeScalars: String.UnicodeScalarView) -> String.UnicodeScalarIndex?