Contents

decodeCString(_:as:repairingInvalidCodeUnits:)

Creates a new string by copying the null-terminated data referenced by the given pointer using the specified encoding.

Declaration

static func decodeCString<Encoding>(_ cString: UnsafePointer<Encoding.CodeUnit>?, as encoding: Encoding.Type, repairingInvalidCodeUnits isRepairing: Bool = true) -> (result: String, repairsMade: Bool)? where Encoding : _UnicodeEncoding

Parameters

  • cString:

    A pointer to a null-terminated sequence of code units encoded in encoding.

  • encoding:

    The Unicode encoding of the data referenced by cString.

  • isRepairing:

    Pass true to create a new string, even when the data referenced by cString contains ill-formed sequences. Ill-formed sequences are replaced with the Unicode replacement character ("\u{FFFD}"). Pass false to interrupt the creation of the new string if an ill-formed sequence is detected.

Return Value

A tuple with the new string and a Boolean value that indicates whether any repairs were made. If isRepairing is false and an ill-formed sequence is detected, this method returns nil.

Discussion

When you pass true as isRepairing, this method replaces ill-formed sequences with the Unicode replacement character ("\u{FFFD}"); otherwise, an ill-formed sequence causes this method to stop decoding and return nil.

The following example calls this method with pointers to the contents of two different CChar arrays—the first with well-formed UTF-8 code unit sequences and the second with an ill-formed sequence at the end.

let validUTF8: [UInt8] = [67, 97, 102, 195, 169, 0]
validUTF8.withUnsafeBufferPointer { ptr in
    let s = String.decodeCString(ptr.baseAddress,
                                 as: UTF8.self,
                                 repairingInvalidCodeUnits: true)
    print(s)
}
// Prints "Optional((result: "Café", repairsMade: false))"

let invalidUTF8: [UInt8] = [67, 97, 102, 195, 0]
invalidUTF8.withUnsafeBufferPointer { ptr in
    let s = String.decodeCString(ptr.baseAddress,
                                 as: UTF8.self,
                                 repairingInvalidCodeUnits: true)
    print(s)
}
// Prints "Optional((result: "Caf�", repairsMade: true))"

See Also

Converting a C String