UTF16View
A view of a string’s contents as a collection of UTF-16 code units.
@frozen struct UTF16View
You can access a string’s view of UTF-16 code units by using its utf16
property. A string’s UTF-16 view encodes the string’s Unicode scalar values as 16-bit integers.
let flowers = "Flowers 💐"
for v in flowers.utf16 {
print(v)
}
// 70
// 108
// 111
// 119
// 101
// 114
// 115
// 32
// 55357
// 56464
Unicode scalar values that make up a string’s contents can be up to 21 bits long. The longer scalar values may need two UInt16
values for storage. Those “pairs” of code units are called surrogate pairs.
let flowermoji = "💐"
for v in flowermoji.unicodeScalars {
print(v, v.value)
}
// 💐 128144
for v in flowermoji.utf16 {
print(v)
}
// 55357
// 56464
To convert a String.UTF16View
instance back into a string, use the String
type’s init(_:)
initializer.
let favemoji = "My favorite emoji is 🎉"
if let i = favemoji.utf16.firstIndex(where: { $0 >= 128 }) {
let asciiPrefix = String(favemoji.utf16[..<i])!
print(asciiPrefix)
}
// Prints "My favorite emoji is "
UTF16View Elements Match NSString Characters
The UTF-16 code units of a string’s utf16
view match the elements accessed through indexed NSString
APIs.
print(flowers.utf16.count)
// Prints "10"
let nsflowers = flowers as NSString
print(nsflowers.length)
// Prints "10"
Unlike NSString
, however, String.UTF16View
does not use integer indices. If you need to access a specific position in a UTF-16 view, use Swift’s index manipulation methods. The following example accesses the fourth code unit in both the flowers
and nsflowers
strings:
print(nsflowers.character(at: 3))
// Prints "119"
let i = flowers.utf16.index(flowers.utf16.startIndex, offsetBy: 3)
print(flowers.utf16[i])
// Prints "119"
Although the Swift overlay updates many Objective-C methods to return native Swift indices and index ranges, some still return instances of NSRange
. To convert an NSRange
instance to a range of String.Index
, use the Range(_:in:)
initializer, which takes an NSRange
and a string as arguments.
let snowy = "❄️ Let it snow! ☃️"
let nsrange = NSRange(location: 3, length: 12)
if let range = Range(nsrange, in: snowy) {
print(snowy[range])
}
// Prints "Let it snow!"
Citizens in Swift
Conformances
protocol BidirectionalCollection
A collection that supports backward as well as forward traversal.
protocol Collection
A sequence whose elements can be traversed multiple times, nondestructively, and accessed by an indexed subscript.
protocol CustomDebugStringConvertible
A type with a customized textual representation suitable for debugging purposes.
protocol CustomReflectable
A type that explicitly supplies its own mirror.
protocol CustomStringConvertible
A type with a customized textual representation.
protocol Sendable
A type whose values can safely be passed across concurrency domains by copying.
protocol Sequence
A type that provides sequential, iterated access to its elements.
Members
var count: Int
var customMirror: Mirror
Returns a mirror that reflects the UTF-16 view of a string.
var debugDescription: String
var description: String
var endIndex: String.UTF16View.Index
The “past the end” position—that is, the position one greater than the last valid subscript argument.
var startIndex: String.UTF16View.Index
The position of the first code unit if the
String
is nonempty; identical toendIndex
otherwise.subscript(Range
<String.UTF16View.Index>) -> Substring.UTF16View subscript(String
.UTF16View.Index) -> UTF16.CodeUnit Accesses the code unit at the given position.
func distance(from: String.UTF16View.Index, to: String.UTF16View.Index
) -> Int func index(String
.UTF16View.Index, offsetBy: Int) -> String.UTF16View.Index func index(String
.UTF16View.Index, offsetBy: Int, limitedBy: String.UTF16View.Index) -> String.UTF16View.Index? func index(after: String.UTF16View.Index
) -> String.UTF16View.Index func index(before: String.UTF16View.Index
) -> String.UTF16View.Index func makeIterator(
) -> String.UTF16View.Iterator struct Iterator
typealias Index
typealias SubSequence
var customPlaygroundQuickLook: _PlaygroundQuickLook
Features
var first: Self.Element?
The first element of the collection.
var last: Self.Element?
The last element of the collection.
var lazy: LazySequence<Self>
A sequence containing the same elements as this sequence, but on which some operations, such as
map
andfilter
, are implemented lazily.func allSatisfy((Self.Element) throws -> Bool
) rethrows -> Bool Returns a Boolean value indicating whether every element of a sequence satisfies a given predicate.
func compactMap<ElementOfResult>((Self.Element) throws -> ElementOfResult?
) rethrows -> [ElementOfResult] Returns an array containing the non-
nil
results of calling the given transformation with each element of this sequence.func contains(Self
.Element) -> Bool Returns a Boolean value indicating whether the sequence contains the given element.
func contains(where: (Self.Element) throws -> Bool
) rethrows -> Bool Returns a Boolean value indicating whether the sequence contains an element that satisfies the given predicate.
func difference<C>(from: C
) -> CollectionDifference<Self.Element> Returns the difference needed to produce this collection’s ordered elements from the given collection.
func difference<C>(from: C, by: (C.Element, Self.Element) -> Bool
) -> CollectionDifference<Self.Element> Returns the difference needed to produce this collection’s ordered elements from the given collection, using the given predicate as an equivalence test.
func drop(while: (Self.Element) throws -> Bool
) rethrows -> Self.SubSequence Returns a subsequence by skipping elements while
predicate
returnstrue
and returning the remaining elements.func dropFirst(Int
) -> Self.SubSequence Returns a subsequence containing all but the given number of initial elements.
func dropLast(Int
) -> Self.SubSequence Returns a subsequence containing all but the specified number of final elements.
func elementsEqual<OtherSequence>(OtherSequence
) -> Bool Returns a Boolean value indicating whether this sequence and another sequence contain the same elements in the same order.
func elementsEqual<OtherSequence>(OtherSequence, by: (Self.Element, OtherSequence.Element) throws -> Bool
) rethrows -> Bool Returns a Boolean value indicating whether this sequence and another sequence contain equivalent elements in the same order, using the given predicate as the equivalence test.
func enumerated(
) -> EnumeratedSequence<Self> Returns a sequence of pairs (n, x), where n represents a consecutive integer starting at zero and x represents an element of the sequence.
func filter((Self.Element) throws -> Bool
) rethrows -> [Self.Element] Returns an array containing, in order, the elements of the sequence that satisfy the given predicate.
func first(where: (Self.Element) throws -> Bool
) rethrows -> Self.Element? Returns the first element of the sequence that satisfies the given predicate.
func firstIndex(of: Self.Element
) -> Self.Index? Returns the first index where the specified value appears in the collection.
func firstIndex(where: (Self.Element) throws -> Bool
) rethrows -> Self.Index? Returns the first index in which an element of the collection satisfies the given predicate.
func flatMap<SegmentOfResult>((Self.Element) throws -> SegmentOfResult
) rethrows -> [SegmentOfResult.Element] Returns an array containing the concatenated results of calling the given transformation with each element of this sequence.
func forEach((Self.Element) throws -> Void
) rethrows Calls the given closure on each element in the sequence in the same order as a
for
-in
loop.func formIndex(inout Self
.Index, offsetBy: Int) Offsets the given index by the specified distance.
func formIndex(inout Self
.Index, offsetBy: Int, limitedBy: Self.Index) -> Bool Offsets the given index by the specified distance, or so that it equals the given limiting index.
func last(where: (Self.Element) throws -> Bool
) rethrows -> Self.Element? Returns the last element of the sequence that satisfies the given predicate.
func lastIndex(of: Self.Element
) -> Self.Index? Returns the last index where the specified value appears in the collection.
func lastIndex(where: (Self.Element) throws -> Bool
) rethrows -> Self.Index? Returns the index of the last element in the collection that matches the given predicate.
func lexicographicallyPrecedes<OtherSequence>(OtherSequence
) -> Bool Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the less-than operator (
<
) to compare elements.func lexicographicallyPrecedes<OtherSequence>(OtherSequence, by: (Self.Element, Self.Element) throws -> Bool
) rethrows -> Bool Returns a Boolean value indicating whether the sequence precedes another sequence in a lexicographical (dictionary) ordering, using the given predicate to compare elements.
func map<T>((Self.Element) throws -> T
) rethrows -> [T] Returns an array containing the results of mapping the given closure over the sequence’s elements.
func map<T>((Self.Element) throws -> T
) rethrows -> [T] Returns an array containing the results of mapping the given closure over the sequence’s elements.
func max(
) -> Self.Element? Returns the maximum element in the sequence.
func max(by: (Self.Element, Self.Element) throws -> Bool
) rethrows -> Self.Element? Returns the maximum element in the sequence, using the given predicate as the comparison between elements.
func min(
) -> Self.Element? Returns the minimum element in the sequence.
func min(by: (Self.Element, Self.Element) throws -> Bool
) rethrows -> Self.Element? Returns the minimum element in the sequence, using the given predicate as the comparison between elements.
func prefix(Int
) -> Self.SubSequence Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.
func prefix(through: Self.Index
) -> Self.SubSequence Returns a subsequence from the start of the collection through the specified position.
func prefix(upTo: Self.Index
) -> Self.SubSequence Returns a subsequence from the start of the collection up to, but not including, the specified position.
func prefix(while: (Self.Element) throws -> Bool
) rethrows -> Self.SubSequence Returns a subsequence containing the initial elements until
predicate
returnsfalse
and skipping the remaining elements.func randomElement(
) -> Self.Element? Returns a random element of the collection.
func randomElement<T>(using: inout T
) -> Self.Element? Returns a random element of the collection, using the given generator as a source for randomness.
func reduce<Result>(Result, (Result, Self.Element) throws -> Result
) rethrows -> Result Returns the result of combining the elements of the sequence using the given closure.
func reduce<Result>(into: Result, (inout Result, Self.Element) throws -> ()
) rethrows -> Result Returns the result of combining the elements of the sequence using the given closure.
func reversed(
) -> ReversedCollection<Self> Returns a view presenting the elements of the collection in reverse order.
func shuffled(
) -> [Self.Element] Returns the elements of the sequence, shuffled.
func shuffled<T>(using: inout T
) -> [Self.Element] Returns the elements of the sequence, shuffled using the given generator as a source for randomness.
func sorted(
) -> [Self.Element] Returns the elements of the sequence, sorted.
func sorted(by: (Self.Element, Self.Element) throws -> Bool
) rethrows -> [Self.Element] Returns the elements of the sequence, sorted using the given predicate as the comparison between elements.
func split(maxSplits: Int, omittingEmptySubsequences: Bool, whereSeparator: (Self.Element) throws -> Bool
) rethrows -> [Self.SubSequence] Returns the longest possible subsequences of the collection, in order, that don’t contain elements satisfying the given predicate.
func split(separator: Self.Element, maxSplits: Int, omittingEmptySubsequences: Bool
) -> [Self.SubSequence] Returns the longest possible subsequences of the collection, in order, around elements equal to the given element.
func starts<PossiblePrefix>(with: PossiblePrefix
) -> Bool Returns a Boolean value indicating whether the initial elements of the sequence are the same as the elements in another sequence.
func starts<PossiblePrefix>(with: PossiblePrefix, by: (Self.Element, PossiblePrefix.Element) throws -> Bool
) rethrows -> Bool Returns a Boolean value indicating whether the initial elements of the sequence are equivalent to the elements in another sequence, using the given predicate as the equivalence test.
func suffix(Int
) -> Self.SubSequence Returns a subsequence, up to the given maximum length, containing the final elements of the collection.
func suffix(from: Self.Index
) -> Self.SubSequence Returns a subsequence from the specified position to the end of the collection.
func flatMap<ElementOfResult>((Self.Element) throws -> ElementOfResult?
) rethrows -> [ElementOfResult] func index(of: Self.Element
) -> Self.Index? Returns the first index where the specified value appears in the collection.