StructureSwift5.9.0

Character

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

@frozen struct 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: 8"

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

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.

Citizens in Swift

Conformances

protocol Comparable
A type that can be compared using the relational operators <, <=, >=, and >.
protocol CustomDebugStringConvertible
A type with a customized textual representation suitable for debugging purposes.
protocol CustomReflectable
A type that explicitly supplies its own mirror.
protocol CustomStringConvertible
A type with a customized textual representation.
protocol Equatable
A type that can be compared for value equality.
protocol ExpressibleByExtendedGraphemeClusterLiteral
A type that can be initialized with a string literal containing a single extended grapheme cluster.
protocol ExpressibleByUnicodeScalarLiteral
A type that can be initialized with a string literal containing a single Unicode scalar value.
protocol Hashable
A type that can be hashed into a Hasher to produce an integer hash value.
protocol LosslessStringConvertible
A type that can be represented as a string in a lossless, unambiguous way.
protocol Sendable
A type whose values can safely be passed across concurrency domains by copying.
protocol TextOutputStreamable
A source of text-streaming operations.

Members

init(String)
Creates a character from a single-character string.
init(Unicode.Scalar)
Creates a character containing the given Unicode scalar value.
init(extendedGraphemeClusterLiteral: Character)
Creates a character with the specified value.
var asciiValue: UInt8?
The ASCII encoding value of this character, if it is an ASCII character.
var customMirror: Mirror
A mirror that reflects the Character instance.
var debugDescription: String
A textual representation of the character, suitable for debugging.
var description: String
var hexDigitValue: Int?
The numeric value this character represents, if it is a hexadecimal digit.
var isASCII: Bool
A Boolean value indicating whether this is an ASCII character.
var isCased: Bool
A Boolean value indicating whether this character changes under any form of case conversion.
var isCurrencySymbol: Bool
A Boolean value indicating whether this character represents a currency symbol.
var isHexDigit: Bool
A Boolean value indicating whether this character represents a hexadecimal digit.
var isLetter: Bool
A Boolean value indicating whether this character is a letter.
var isLowercase: Bool
A Boolean value indicating whether this character is considered lowercase.
var isMathSymbol: Bool
A Boolean value indicating whether this character represents a symbol that naturally appears in mathematical contexts.
var isNewline: Bool
A Boolean value indicating whether this character represents a newline.
var isNumber: Bool
A Boolean value indicating whether this character represents a number.
var isPunctuation: Bool
A Boolean value indicating whether this character represents punctuation.
var isSymbol: Bool
A Boolean value indicating whether this character represents a symbol.
var isUppercase: Bool
A Boolean value indicating whether this character is considered uppercase.
var isWhitespace: Bool
A Boolean value indicating whether this character represents whitespace, including newlines.
var isWholeNumber: Bool
A Boolean value indicating whether this character represents a whole number.
var unicodeScalars: Character.UnicodeScalarView
var utf16: Character.UTF16View
A UTF-16 encoding of self.
var utf8: Character.UTF8View
A UTF-8 encoding of self.
var wholeNumberValue: Int?
The numeric value this character represents, if it represents a whole number.
static func < (Character, Character) -> Bool
static func == (Character, Character) -> Bool
func hash(into: inout Hasher)
Hashes the essential components of this value by feeding them into the given hasher.
func lowercased() -> String
Returns a lowercased version of this character.
func uppercased() -> String
Returns an uppercased version of this character.
func write<Target>(to: inout Target)
Writes the character into the given output stream.
typealias UTF16View
A view of a character’s contents as a collection of UTF-16 code units. See String.UTF16View for more information
typealias UTF8View
A view of a character’s contents as a collection of UTF-8 code units. See String.UTF8View for more information
typealias UnicodeScalarView
var customPlaygroundQuickLook: _PlaygroundQuickLook
A custom playground Quick Look for the Character instance.

Features

static func != (Self, Self) -> Bool
static func ... (Self) -> PartialRangeFrom<Self>
Returns a partial range extending upward from a lower bound.
static func ... (Self) -> PartialRangeThrough<Self>
Returns a partial range up to, and including, its upper bound.
static func ... (Self, Self) -> ClosedRange<Self>
Returns a closed range that contains both of its bounds.
static func ..< (Self) -> PartialRangeUpTo<Self>
Returns a partial range up to, but not including, its upper bound.
static func ..< (Self, Self) -> Range<Self>
Returns a half-open range that contains its lower bound but not its upper bound.

Available in _RegexParser

Members

var hasExactlyOneScalar: Bool
Whether this character is made up of exactly one Unicode scalar value.
var isOctalDigit: Bool
Whether this character represents an octal (base 8) digit, for the purposes of pattern parsing.
var isPatternWhitespace: Bool
Whether this character represents whitespace, for the purposes of pattern parsing.
var isWordCharacter: Bool
Whether this character represents a word character, for the purposes of pattern parsing.

Available in RegexBuilder

Conformances

protocol RegexComponent
A type that represents a regular expression.

Members

Extension in JSONDecoding

Conformances

protocol JSONDecodable
A type that can be decoded from a JSON variant value.
protocol JSONStringDecodable
A type that can be decoded from a JSON UTF-8 string. This protocol exists to allow types that also conform to LosslessStringConvertible to opt-in to automatic JSONDecodable conformance as well.

Members

init(json: JSON) throws
Witnesses Character’s JSONStringDecodable conformance, throwing a JSON.ValueError instead of trapping on multi-character input.

Extension in JSONEncoding

Conformances

protocol JSONEncodable
A type that can be encoded to a JSON variant value.

Members

func encoded(as: JSON.Type) -> JSON

Extension in BSONDecoding

Conformances

protocol BSONDecodable
A type that can be decoded from a BSON variant value backed by some type of storage not particular to the decoded type.
protocol BSONStringDecodable
A type that can be decoded from a BSON UTF-8 string. Javascript sources count as UTF-8 strings, from the perspective of this protocol. This protocol exists to allow types that also conform to LosslessStringConvertible to opt-in to automatic BSONDecodable conformance as well.

Members

init(bson: BSON.UTF8View<some BidirectionalCollection<UInt8>>) throws
Witnesses Character’s BSONStringDecodable conformance, throwing a BSON.ValueError instead of trapping on multi-character input.

Extension in BSONEncoding

Conformances

protocol BSONEncodable
A type that can be encoded to a BSON variant value.

Members

func encode(to: inout BSON.Field)

Extension in HTMLStreaming

Conformances

Members

Extension in JSONDecoding

Conformances

protocol JSONDecodable
A type that can be decoded from a JSON variant value.
protocol JSONStringDecodable
A type that can be decoded from a JSON UTF-8 string. This protocol exists to allow types that also conform to LosslessStringConvertible to opt-in to automatic JSONDecodable conformance as well.

Members

init(json: JSON.Node) throws
Witnesses Character’s JSONStringDecodable conformance, throwing a JSON.ValueError instead of trapping on multi-character input.

Extension in JSONEncoding

Conformances

protocol JSONEncodable
protocol JSONStringEncodable
A type that can be encoded to a JSON string. This protocol exists to allow types that also conform to LosslessStringConvertible to opt-in to automatic JSONEncodable conformance as well.