Generic Instance Method

decode(_:)

Starts or continues decoding a UTF-16 sequence.

Declaration

mutating func decode<I>(_ input: inout I) -> UnicodeDecodingResult where I : IteratorProtocol, I.Element == Unicode.UTF16.CodeUnit

Parameters

input

An iterator of code units to be decoded. input must be the same iterator instance in repeated calls to this method. Do not advance the iterator or any copies of the iterator outside this method.

Return Value

A UnicodeDecodingResult instance, representing the next Unicode scalar, an indication of an error, or an indication that the UTF sequence has been fully decoded.

Discussion

To decode a code unit sequence completely, call this method repeatedly until it returns UnicodeDecodingResult.emptyInput. Checking that the iterator was exhausted is not sufficient, because the decoder can store buffered data from the input iterator.

Because of buffering, it is impossible to find the corresponding position in the iterator for a given returned Unicode.Scalar or an error.

The following example decodes the UTF-16 encoded bytes of a string into an array of Unicode.Scalar instances. This is a demonstration only—if you need the Unicode scalar representation of a string, use its unicodeScalars view.

let str = "✨Unicode✨"
print(Array(str.utf16))
// Prints "[10024, 85, 110, 105, 99, 111, 100, 101, 10024]"

var codeUnitIterator = str.utf16.makeIterator()
var scalars: [Unicode.Scalar] = []
var utf16Decoder = UTF16()
Decode: while true {
    switch utf16Decoder.decode(&codeUnitIterator) {
    case .scalarValue(let v): scalars.append(v)
    case .emptyInput: break Decode
    case .error:
        print("Decoding error")
        break Decode
    }
}
print(scalars)
// Prints "["\u{2728}", "U", "n", "i", "c", "o", "d", "e", "\u{2728}"]"

Relationships

From Protocol