String.UTF8View.Index

struct String.UTF8View.Index

A position in a string's UTF8View instance.

You can convert between indices of the different string views by using conversion initializers and the samePosition(in:) method overloads. For example, the following code sample finds the index of the first space in the string's character view and then converts that to the same position in the UTF-8 view.

let hearts = "Hearts <3 ♥︎ 💘"
if let i = hearts.characters.index(of: " ") {
    let j = i.samePosition(in: hearts.utf8)
    print(Array(hearts.utf8.prefix(upTo: j)))
    print(hearts.utf8.prefix(upTo: j))
}
// Prints "[72, 101, 97, 114, 116, 115]"
// Prints "Hearts"
Inheritance Comparable, Equatable View Protocol Hierarchy →
Import import Swift

Initializers

init(_: String.Index, within: String.UTF8View)

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

The following example converts the position of the teacup emoji ("🍵") into its corresponding position in the string's utf8 view.

let cafe = "Café 🍵"
let characterIndex = cafe.characters.index(of: "🍵")!
let utf8Index = String.UTF8View.Index(characterIndex, within: cafe.utf8)

print(Array(cafe.utf8.suffix(from: utf8Index)))
// Prints "[240, 159, 141, 181]"

Parameters: characterIndex: A position in a CharacterView instance. characterIndex must be an element of String(utf8).characters.indices. utf8: The UTF8View in which to find the new position.

Declaration

init(_ characterIndex: String.Index, within utf8: String.UTF8View)
init(_: String.UnicodeScalarIndex, within: String.UTF8View)

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

The following example converts the position of the Unicode scalar "e" into its corresponding position in the string's utf8 view.

let cafe = "Cafe\u{0301}"
let scalarsIndex = cafe.unicodeScalars.index(of: "e")!
let utf8Index = String.UTF8View.Index(scalarsIndex, within: cafe.utf8)

print(Array(cafe.utf8.prefix(through: utf8Index)))
// Prints "[67, 97, 102, 101]"

Parameters: unicodeScalarIndex: A position in a UnicodeScalarView instance. unicodeScalarIndex must be an element of String(utf8).unicodeScalars.indices. utf8: The UTF8View in which to find the new position.

Declaration

init(_ unicodeScalarIndex: String.UnicodeScalarIndex, within utf8: String.UTF8View)
init?(_:within:)

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.index(of: 32)!
let utf8Index = String.UTF8View.Index(utf16Index, within: cafe.utf8)!

print(Array(cafe.utf8.prefix(upTo: 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: utf16Index: A position in a UTF16View instance. utf16Index must be an element in String(utf8).utf16.indices. utf8: The UTF8View in which to find the new position.

Declaration

init?(_ utf16Index: String.UTF16Index, within utf8: String.UTF8View)

Instance Methods

func <(_:rhs:)

Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.

This function is the only requirement of the Comparable protocol. The remainder of the relational operator functions are implemented by the standard library for any type that conforms to Comparable.

Parameters: lhs: A value to compare. rhs: Another value to compare.

Declaration

func <(lhs: String.UTF8View.Index, rhs: String.UTF8View.Index) -> Bool
func ==(_:rhs:)

Returns a Boolean value indicating whether two values are equal.

Equality is the inverse of inequality. For any values a and b, a == b implies that a != b is false.

Parameters: lhs: A value to compare. rhs: Another value to compare.

Declaration

func ==(lhs: String.UTF8View.Index, rhs: String.UTF8View.Index) -> Bool
func samePosition(in: String)

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

This index must be a valid index of characters.utf8.

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.utf8.index(of: 32)!
let j = i.samePosition(in: cafe)!
print(cafe[cafe.startIndex ..< j])
// Prints "Café"

characters: The string to use for the index conversion. 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?
func samePosition(in: String.UTF16View)

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).utf8.

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 to find the same position in the string's utf16 view.

let cafe = "Café 🍵"
let i = cafe.utf8.index(of: 32)!
let j = i.samePosition(in: cafe.utf16)!
print(cafe.utf16.prefix(upTo: j))
// Prints "Café"

utf16: The view to use for the index conversion. 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?
func samePosition(in: String.UnicodeScalarView)

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).utf8.

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 to find the same position in the string's unicodeScalars view.

let cafe = "Café 🍵"
let i = cafe.utf8.index(of: 32)!
let j = i.samePosition(in: cafe.unicodeScalars)!
print(cafe.unicodeScalars.prefix(upTo: j))
// Prints "Café"

unicodeScalars: The view to use for the index conversion. 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-8 continuation byte returns nil.

Declaration

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