Contents

init(unsafeUninitializedCapacity:initializingUTF8With:)

Creates a new string with the specified capacity in UTF-8 code units, and then calls the given closure with a buffer covering the string’s uninitialized memory.

Declaration

init(unsafeUninitializedCapacity capacity: Int, initializingUTF8With initializer: (UnsafeMutableBufferPointer<UInt8>) throws -> Int) rethrows

Parameters

  • capacity:

    The number of UTF-8 code units worth of memory to allocate for the string (excluding the null terminator).

  • initializer:

    A closure that accepts a buffer covering uninitialized memory with room for capacity UTF-8 code units, initializes that memory, and returns the number of initialized elements.

Discussion

The closure should return the number of initialized code units, or 0 if it couldn’t initialize the buffer (for example if the requested capacity was too small).

This method replaces ill-formed UTF-8 sequences with the Unicode replacement character ("\u{FFFD}"). This may require resizing the buffer beyond its original capacity.

The following examples use this initializer with the contents of two different UInt8 arrays—the first with a well-formed UTF-8 code unit sequence, and the second with an ill-formed sequence at the end.

let validUTF8: [UInt8] = [0x43, 0x61, 0x66, 0xC3, 0xA9]
let invalidUTF8: [UInt8] = [0x43, 0x61, 0x66, 0xC3]

let cafe1 = String(unsafeUninitializedCapacity: validUTF8.count) {
    _ = $0.initialize(from: validUTF8)
    return validUTF8.count
}
// cafe1 == "Café"

let cafe2 = String(unsafeUninitializedCapacity: invalidUTF8.count) {
    _ = $0.initialize(from: invalidUTF8)
    return invalidUTF8.count
}
// cafe2 == "Caf�"

let empty = String(unsafeUninitializedCapacity: 16) { _ in
    // Can't initialize the buffer (e.g. the capacity is too small).
    return 0
}
// empty == ""

See Also

Creating a String