Character

struct Character

A single extended grapheme cluster, which 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. The number of visible characters is generally the most natural way to count the length of a string.

let greeting = "Hello! 🐥"
print("Character count: \(greeting.characters.count)")
// Prints "Character count: 8"

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

print("Unicode code point count: \(greeting.unicodeScalars.count)")
// Prints "Unicode code point 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 code points that are grouped together as an extended grapheme cluster. The way these code points 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 code points 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 code points "\u{1F1FA}" (REGIONAL INDICATOR SYMBOL LETTER U) and "\u{1F1F8}" (REGIONAL INDICATOR SYMBOL LETTER S). When placed next to each other in a Swift string literal, these two code points 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 →
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(_: UnicodeScalar)

Creates a character containing the given Unicode scalar value.

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

Declaration

init(_ scalar: UnicodeScalar)
init(extendedGraphemeClusterLiteral:)

Creates a character with the specified value.

Don't call this initializer 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)
init(unicodeScalarLiteral:)

Creates a character with the specified value.

Don't call this initializer directly. It is used by the compiler when you use a string literal to initialize a Character instance. For example:

let snowflake: Character = "❄︎"
print(snowflake)
// Prints "❄︎"

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

Declaration

init(unicodeScalarLiteral 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 this instance.

If this type has value semantics, the PlaygroundQuickLook instance should be unaffected by subsequent mutations.

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.

Instead of accessing this property directly, convert an instance of any type to a string by using the String(describing:) initializer. For example:

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 }

Instance Methods

func <(_:rhs:)

Returns a Boolean value indicating whether the value of the first argument is less than that of the second argument.

This function is the only requirement of the Comparable protocol. The remainder of the relational operator functions are implemented by the standard library for any type that conforms to Comparable.

Parameters: lhs: A value to compare. rhs: Another value to compare.

Declaration

func <(lhs: Character, rhs: Character) -> Bool
func ==(_:rhs:)

Returns a Boolean value indicating whether two values are equal.

Equality is the inverse of inequality. For any values a and b, a == b implies that a != b is false.

Parameters: lhs: A value to compare. rhs: Another value to compare.

Declaration

func ==(lhs: Character, rhs: Character) -> Bool
func write(to:)

Writes the character into the given output stream.

target: An output stream.

Declaration

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