Structure

String.UTF8View

A view of a string’s contents as a collection of UTF-8 code units.

Overview

You can access a string’s view of UTF-8 code units by using its utf8 property. A string’s UTF-8 view encodes the string’s Unicode scalar values as 8-bit integers.

let flowers = "Flowers 💐"
for v in flowers.utf8 {
    print(v)
}
// 70
// 108
// 111
// 119
// 101
// 114
// 115
// 32
// 240
// 159
// 146
// 144

A string’s Unicode scalar values can be up to 21 bits in length. To represent those scalar values using 8-bit integers, more than one UTF-8 code unit is often required.

let flowermoji = "💐"
for v in flowermoji.unicodeScalars {
    print(v, v.value)
}
// 💐 128144

for v in flowermoji.utf8 {
    print(v)
}
// 240
// 159
// 146
// 144

In the encoded representation of a Unicode scalar value, each UTF-8 code unit after the first is called a continuation byte.

UTF8View Elements Match Encoded C Strings

Swift streamlines interoperation with C string APIs by letting you pass a String instance to a function as an Int8 or UInt8 pointer. When you call a C function using a String, Swift automatically creates a buffer of UTF-8 code units and passes a pointer to that buffer. The code units of that buffer match the code units in the string’s utf8 view.

The following example uses the C strncmp function to compare the beginning of two Swift strings. The strncmp function takes two const char* pointers and an integer specifying the number of characters to compare. Because the strings are identical up to the 14th character, comparing only those characters results in a return value of 0.

let s1 = "They call me 'Bell'"
let s2 = "They call me 'Stacey'"

print(strncmp(s1, s2, 14))
// Prints "0"
print(String(s1.utf8.prefix(14)))
// Prints "They call me '"

Extending the compared character count to 15 includes the differing characters, so a nonzero result is returned.

print(strncmp(s1, s2, 15))
// Prints "-17"
print(String(s1.utf8.prefix(15)))
// Prints "They call me 'B"

Topics

Instance Properties

var count: Int

The number of elements in the collection.

var customMirror: Mirror

Returns a mirror that reflects the UTF-8 view of a string.

var endIndex: String.UTF8View.Index

The “past the end” position—that is, the position one greater than the last valid subscript argument.

var first: Unicode.UTF8.CodeUnit?

The first element of the collection.

var indices: DefaultBidirectionalIndices<String.UTF8View>

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

var isEmpty: Bool

A Boolean value indicating whether the collection is empty.

var last: Unicode.UTF8.CodeUnit?

The last element of the collection.

var lazy: LazySequence<String.UTF8View>

A sequence containing the same elements as this sequence, but on which some operations, such as map and filter, are implemented lazily.

var lazy: LazyCollection<String.UTF8View>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var lazy: LazyBidirectionalCollection<String.UTF8View>

A view onto this collection that provides lazy implementations of normally eager operations, such as map and filter.

var startIndex: String.UTF8View.Index

The position of the first code unit if the UTF-8 view is nonempty.

var underestimatedCount: Int

A value less than or equal to the number of elements in the collection.

var underestimatedCount: Int

Returns a value less than or equal to the number of elements in the sequence, nondestructively.

Instance Methods

func contains(Unicode.UTF8.CodeUnit)

Returns a Boolean value indicating whether the sequence contains the given element.

func contains(where: (Unicode.UTF8.CodeUnit) -> Bool)

Returns a Boolean value indicating whether the sequence contains an element that satisfies the given predicate.

func drop(while: (UInt8) -> Bool)

Returns a subsequence by skipping elements while predicate returns true and returning the remaining elements.

func dropFirst()

Returns a subsequence containing all but the first element of the sequence.

func dropFirst(Int)

Returns a subsequence containing all but the given number of initial elements.

func dropLast()

Returns a subsequence containing all but the last element of the sequence.

func dropLast(Int)

Returns a subsequence containing all but the specified number of final elements.

func elementsEqual<OtherSequence>(OtherSequence)

Returns a Boolean value indicating whether this sequence and another sequence contain the same elements in the same order.

func elementsEqual<OtherSequence>(OtherSequence, by: (Unicode.UTF8.CodeUnit, Unicode.UTF8.CodeUnit) -> 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()

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((Unicode.UTF8.CodeUnit) -> Bool)

Returns an array containing, in order, the elements of the sequence that satisfy the given predicate.

func first(where: (Unicode.UTF8.CodeUnit) -> Bool)

Returns the first element of the sequence that satisfies the given predicate.

func forEach((Unicode.UTF8.CodeUnit) -> Void)

Calls the given closure on each element in the sequence in the same order as a for-in loop.

func index(after: String.UTF8View.Index)

Returns the next consecutive position after i.

func index(of: UInt8)

Returns the first index where the specified value appears in the collection.

func index(where: (UInt8) -> Bool)

Returns the first index in which an element of the collection satisfies the given predicate.

func lexicographicallyPrecedes<OtherSequence>(OtherSequence)

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: (Unicode.UTF8.CodeUnit, Unicode.UTF8.CodeUnit) -> 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>((Unicode.UTF8.CodeUnit) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func map<T>((UInt8) -> T)

Returns an array containing the results of mapping the given closure over the sequence’s elements.

func max()

Returns the maximum element in the sequence.

func max(by: (Unicode.UTF8.CodeUnit, Unicode.UTF8.CodeUnit) -> Bool)

Returns the maximum element in the sequence, using the given predicate as the comparison between elements.

func min()

Returns the minimum element in the sequence.

func min(by: (Unicode.UTF8.CodeUnit, Unicode.UTF8.CodeUnit) -> Bool)

Returns the minimum element in the sequence, using the given predicate as the comparison between elements.

func prefix(Int)

Returns a subsequence, up to the specified maximum length, containing the initial elements of the collection.

func prefix(through: String.Index)

Returns a subsequence from the start of the collection through the specified position.

func prefix(upTo: String.Index)

Returns a subsequence from the start of the collection up to, but not including, the specified position.

func prefix(while: (UInt8) -> Bool)

Returns a subsequence containing the initial elements until predicate returns false and skipping the remaining elements.

func reduce<Result>(Result, (Result, Unicode.UTF8.CodeUnit) -> Result)

Returns the result of combining the elements of the sequence using the given closure.

func reduce<Result>(into: Result, (inout Result, Unicode.UTF8.CodeUnit) -> ())

Returns the result of combining the elements of the sequence using the given closure.

func reversed()

Returns a view presenting the elements of the collection in reverse order.

func sorted()

Returns the elements of the sequence, sorted.

func sorted(by: (Unicode.UTF8.CodeUnit, Unicode.UTF8.CodeUnit) -> Bool)

Returns the elements of the sequence, sorted using the given predicate as the comparison between elements.

func split(maxSplits: Int, omittingEmptySubsequences: Bool, whereSeparator: (UInt8) -> Bool)

Returns the longest possible subsequences of the collection, in order, that don’t contain elements satisfying the given predicate.

func split(separator: UInt8, maxSplits: Int, omittingEmptySubsequences: Bool)

Returns the longest possible subsequences of the collection, in order, around elements equal to the given element.

func starts<PossiblePrefix>(with: PossiblePrefix)

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: (Unicode.UTF8.CodeUnit, Unicode.UTF8.CodeUnit) -> 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)

Returns a subsequence, up to the given maximum length, containing the final elements of the collection.

func suffix(from: String.Index)

Returns a subsequence from the specified position to the end of the collection.

Subscripts

Relationships

From Protocol

See Also

Related String Types

struct Substring

A slice of a string.

protocol StringProtocol

A type that can represent a string as a collection of characters.

struct String.Index

A position of a character or code unit in a string.

struct String.CharacterView

A view of a string’s contents as a collection of characters.

Deprecated
struct String.UnicodeScalarView

A view of a string’s contents as a collection of Unicode scalar values.

struct String.UTF16View

A view of a string’s contents as a collection of UTF-16 code units.