String.UTF16View.Index

struct String.UTF16View.Index

A position in a string's collection of UTF-16 code units.

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-16 view.

let hearts = "Hearts <3 ♥︎ 💘"
if let i = hearts.characters.index(of: " ") {
    let j = i.samePosition(in: hearts.utf16)
    print(Array(hearts.utf16.suffix(from: j)))
    print(hearts.utf16.suffix(from: j))
}
// Prints "[32, 60, 51, 32, 9829, 65038, 32, 55357, 56472]"
// Prints " <3 ♥︎ 💘"
Inheritance Comparable, Equatable, Strideable View Protocol Hierarchy →
Import import Swift

Initializers

init(_:)

[Foundation] Construct from an integer offset.

Declaration

init(_ offset: Int)
init(_: String.Index, within: String.UTF16View)

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

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

let cafe = "Café 🍵"

let characterIndex = cafe.characters.index(of: "é")!
let utf16Index = String.UTF16View.Index(characterIndex, within: cafe.utf16)

print(cafe.utf16.prefix(through: utf16Index))
// Prints "Café"

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

Declaration

init(_ characterIndex: String.Index, within utf16: String.UTF16View)
init(_: String.UnicodeScalarIndex, within: String.UTF16View)

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

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

let cafe = "Café 🍵"

let scalarIndex = cafe.unicodeScalars.index(of: "é")!
let utf16Index = String.UTF16View.Index(scalarIndex, within: cafe.utf16)

print(cafe.utf16.prefix(through: utf16Index))
// Prints "Café"

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

Declaration

init(_ unicodeScalarIndex: String.UnicodeScalarIndex, within utf16: String.UTF16View)
init?(_:within:)

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

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

let cafe = "Café 🍵"

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

print(cafe.utf16.prefix(upTo: utf16Index))
// Prints "Café"

If the position passed as utf8Index doesn't have an exact corresponding position in utf16, 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 a UTF-8 continuation byte fails.

Parameters: utf8Index: A position in a UTF8View instance. utf8Index must be an element in String(utf16).utf8.indices. utf16: The UTF16View in which to find the new position.

Declaration

init?(_ utf8Index: String.UTF8Index, within utf16: String.UTF16View)

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.UTF16View.Index, rhs: String.UTF16View.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.UTF16View.Index, rhs: String.UTF16View.Index) -> Bool
func advanced(by:)

[Foundation] Returns a Self x such that self.distance(to: x) approximates n.

If Stride conforms to Integer, then self.distance(to: x) == n.

Complexity: O(1).

Declaration

func advanced(by n: Int) -> String.UTF16View.Index
func distance(to:)

[Foundation] Returns a stride x such that self.advanced(by: x) approximates other.

If Stride conforms to Integer, then self.advanced(by: x) == other.

Complexity: O(1).

Declaration

func distance(to other: String.UTF16View.Index) -> Int
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.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 find the same position in the string.

let cafe = "Café 🍵"
let i = cafe.utf16.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-16 trailing surrogate returns nil.

Declaration

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

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

The index must be a valid index of String(utf8).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 utf8 view.

let cafe = "Café 🍵"
let i = cafe.utf16.index(of: 32)!
let j = i.samePosition(in: cafe.utf8)!
print(Array(cafe.utf8.prefix(upTo: j)))
// Prints "[67, 97, 102, 195, 169]"

utf8: The view to use for the index conversion. 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?
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).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.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-16 trailing surrogate returns nil.

Declaration

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