Character

struct Character

A single extended grapheme cluster that approximates a user-perceived character.

The Character type represents a character made up of one or more Unicode scalar values, grouped by a Unicode boundary algorithm. Generally, a Character instance matches what the reader of a string will perceive as a single character. Strings are collections of Character instances, so the number of visible characters is generally the most natural way to count the length of a string.

let greeting = "Hello! πŸ₯"
print("Length: \(greeting.count)")
// Prints "Length: 8"

Because each character in a string can be made up of one or more Unicode scalar values, the number of characters in a string may not match the length of the Unicode scalar value representation or the length of the string in a particular binary representation.

print("Unicode scalar value count: \(greeting.unicodeScalars.count)")
// Prints "Unicode scalar value count: 15"

print("UTF-8 representation count: \(greeting.utf8.count)")
// Prints "UTF-8 representation count: 18"

Every Character instance is composed of one or more Unicode scalar values that are grouped together as an extended grapheme cluster. The way these scalar values are grouped is defined by a canonical, localized, or otherwise tailored Unicode segmentation algorithm.

For example, a country's Unicode flag character is made up of two regional indicator scalar values that correspond to that country's ISO 3166-1 alpha-2 code. The alpha-2 code for The United States is "US", so its flag character is made up of the Unicode scalar values "\u{1F1FA}" (REGIONAL INDICATOR SYMBOL LETTER U) and "\u{1F1F8}" (REGIONAL INDICATOR SYMBOL LETTER S). When placed next to each other in a string literal, these two scalar values are combined into a single grapheme cluster, represented by a Character instance in Swift.

let usFlag: Character = "\u{1F1FA}\u{1F1F8}"
print(usFlag)
// Prints "πŸ‡ΊπŸ‡Έ"

For more information about the Unicode terms used in this discussion, see the Unicode.org glossary. In particular, this discussion mentions extended grapheme clusters and Unicode scalar values.

Inheritance Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, CustomStringConvertible, Equatable, ExpressibleByExtendedGraphemeClusterLiteral, ExpressibleByUnicodeScalarLiteral, Hashable, LosslessStringConvertible, TextOutputStreamable View Protocol Hierarchy β†’
Nested Types Character.UnicodeScalarView, Character.UnicodeScalarView.Index, Character.UnicodeScalarView.Iterator
Import import Swift

Initializers

init(_: String)

Creates a character from a single-character string.

The following example creates a new character from the uppercase version of a string that only holds one character.

let a = "a"
let capitalA = Character(a.uppercased())

s: The single-character string to convert to a Character instance. s must contain exactly one extended grapheme cluster.

Declaration

init(_ s: String)
init(_: Unicode.Scalar)

Creates a character containing the given Unicode scalar value.

content: The Unicode scalar value to convert into a character.

Declaration

init(_ content: Unicode.Scalar)
init(extendedGraphemeClusterLiteral:)

Creates a character with the specified value.

Do not call this initalizer directly. It is used by the compiler when you use a string literal to initialize a Character instance. For example:

let oBreve: Character = "o\u{306}"
print(oBreve)
// Prints "ŏ"

The assignment to the oBreve constant calls this initializer behind the scenes.

Declaration

init(extendedGraphemeClusterLiteral value: Character)

Instance Variables

var customMirror: Mirror

A mirror that reflects the Character instance.

Declaration

var customMirror: Mirror { get }
var customPlaygroundQuickLook: PlaygroundQuickLook

A custom playground Quick Look for the Character instance.

Deprecated: Character.customPlaygroundQuickLook will be removed in a future Swift version.

Declaration

var customPlaygroundQuickLook: PlaygroundQuickLook { get }
var debugDescription: String

A textual representation of the character, suitable for debugging.

Declaration

var debugDescription: String { get }
var description: String

A textual representation of this instance.

Calling this property directly is discouraged. Instead, convert an instance of any type to a string by using the String(describing:) initializer. This initializer works with any type, and uses the custom description property for types that conform to CustomStringConvertible:

struct Point: CustomStringConvertible {
    let x: Int, y: Int

    var description: String {
        return "(\(x), \(y))"
    }
}

let p = Point(x: 21, y: 30)
let s = String(describing: p)
print(s)
// Prints "(21, 30)"

The conversion of p to a string in the assignment to s uses the Point type's description property.

Declaration

var description: String { get }
var hashValue: Int

The character's hash value.

Hash values are not guaranteed to be equal across different executions of your program. Do not save hash values to use during a future execution.

Declaration

var hashValue: Int { get }
var unicodeScalars: Character.UnicodeScalarView

Declaration

var unicodeScalars: Character.UnicodeScalarView { get }

Instance Methods

func write(to:)

Writes the character into the given output stream.

target: An output stream.

Declaration

func write<Target>(to target: inout Target)

Conditionally Inherited Items

The initializers, methods, and properties listed below may be available on this type under certain conditions (such as methods that are available on Array when its elements are Equatable) or may not ever be available if that determination is beyond SwiftDoc.org's capabilities. Please open an issue on GitHub if you see something out of place!

Where ExtendedGraphemeClusterLiteralType == UnicodeScalarLiteralType

init(unicodeScalarLiteral:)

Creates an instance initialized to the given value.

value: The value of the new instance.

Declaration

init(unicodeScalarLiteral value: Character.ExtendedGraphemeClusterLiteralType)

Declared In

ExpressibleByExtendedGraphemeClusterLiteral