UnicodeScalar

struct UnicodeScalar

A Unicode scalar value.

The UnicodeScalar type, representing a single Unicode scalar value, is the element type of a string's unicodeScalars collection.

You can create a UnicodeScalar instance by using a string literal that contains a single character representing exactly one Unicode scalar value.

let letterK: UnicodeScalar = "K"
let kim: UnicodeScalar = "김"
print(letterK, kim)
// Prints "K 김"

You can also create Unicode scalar values directly from their numeric representation.

let airplane = UnicodeScalar(9992)
print(airplane)
// Prints "✈︎"
Inheritance Comparable, CustomDebugStringConvertible, CustomPlaygroundQuickLookable, CustomReflectable, CustomStringConvertible, Equatable, ExpressibleByUnicodeScalarLiteral, Hashable, LosslessStringConvertible, TextOutputStreamable View Protocol Hierarchy →
Import import Swift

Initializers

init(_: UInt8)

Creates a Unicode scalar with the specified numeric value.

For example, the following code sample creates a UnicodeScalar instance with a value of 7:

let codepoint: UInt8 = 55
let seven = UnicodeScalar(codepoint)
print(seven!)
// Prints "7"

v: The code point to use for the scalar.

Declaration

init(_ v: UInt8)
init(_: UnicodeScalar)

Creates a duplicate of the given Unicode scalar.

Declaration

init(_ v: UnicodeScalar)
init(unicodeScalarLiteral:)

Creates a Unicode scalar with the specified value.

Do not call this initializer directly. It may be used by the compiler when you use a string literal to initialize a UnicodeScalar instance.

let letterK: UnicodeScalar = "K"
print(letterK)
// Prints "K"

In this example, the assignment to the letterK constant is handled by this initializer behind the scenes.

Declaration

init(unicodeScalarLiteral value: UnicodeScalar)
init?(_: Int)

Creates a Unicode scalar with the specified numeric value.

v: The Unicode code point to use for the scalar. v must be a valid Unicode scalar value, in the ranges 0...0xD7FF or 0xE000...0x10FFFF. In case of an invalid unicode scalar value, nil is returned.

For example, the following code sample creates a UnicodeScalar instance with a value of an emoji character:

let codepoint = 127881
let emoji = UnicodeScalar(codepoint)
print(emoji)
// Prints "🎉"

In case an invalid input value, nil is returned.

let codepoint: UInt32 = extValue // This might be an invalid value. 
if let emoji = UnicodeScalar(codepoint) {
  print(emoji)
} else {
  // Do something else
}

Declaration

init?(_ v: Int)
init?(_: String)

Instantiates an instance of the conforming type from a string representation.

Declaration

init?(_ description: String)
init?(_: UInt16)

Creates a Unicode scalar with the specified numeric value.

v: The Unicode code point to use for the scalar. v must be a valid Unicode scalar value, in the range 0...0xD7FF or 0xE000...0xFFFF. In case of an invalid unicode scalar value, nil is returned.

For example, the following code sample creates a UnicodeScalar instance with a value of 밥, the Korean word for rice:

let codepoint: UInt16 = 48165
let bap = UnicodeScalar(codepoint)
print(bap!)
// Prints "밥"

In case an invalid input value, nil is returned.

let codepoint: UInt32 = extValue // This might be an invalid value. 
if let bap = UnicodeScalar(codepoint) {
  print(bap)
} else {
  // Do something else
}

Declaration

init?(_ v: UInt16)
init?(_: UInt32)

Creates a Unicode scalar with the specified numeric value.

v: The Unicode code point to use for the scalar. v must be a valid Unicode scalar value, in the range 0...0xD7FF or 0xE000...0x10FFFF. In case of an invalid unicode scalar value, nil is returned.

For example, the following code sample creates a UnicodeScalar instance with a value of an emoji character:

let codepoint: UInt32 = 127881
let emoji = UnicodeScalar(codepoint)
print(emoji!)
// Prints "🎉"

In case of an invalid input value, nil is returned.

let codepoint: UInt32 = extValue // This might be an invalid value. 
if let emoji = UnicodeScalar(codepoint) {
  print(emoji)
} else {
  // Do something else
}

Declaration

init?(_ v: UInt32)

Instance Variables

var customMirror: Mirror

A mirror that reflects the UnicodeScalar 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

An escaped textual representation of the Unicode scalar, suitable for debugging.

Declaration

var debugDescription: String { get }
var description: String

A textual representation of the Unicode scalar.

Declaration

var description: String { get }
var hashValue: Int

The Unicode scalar'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 isASCII: Bool

A Boolean value indicating whether the Unicode scalar is an ASCII character.

ASCII characters have a scalar value between 0 and 127, inclusive. For example:

let canyon = "Cañón"
for scalar in canyon.unicodeScalars {
    print(scalar, scalar.isASCII, scalar.value)
}
// Prints "C true 67"
// Prints "a true 97"
// Prints "ñ false 241"
// Prints "ó false 243"
// Prints "n true 110"

Declaration

var isASCII: Bool { get }
var value: UInt32

A numeric representation of the Unicode scalar.

Declaration

var value: UInt32 { 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: UnicodeScalar, rhs: UnicodeScalar) -> 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: UnicodeScalar, rhs: UnicodeScalar) -> Bool
func escaped(asASCII:)

Returns a string representation of the Unicode scalar.

Scalar values representing characters that are normally unprintable or that otherwise require escaping are escaped with a backslash.

let tab = UnicodeScalar(9)
print(tab)
// Prints " "
print(tab.escaped(asASCII: false))
// Prints "\t"

When the forceASCII parameter is true, a UnicodeScalar instance with a value greater than 127 is represented using an escaped numeric value; otherwise, non-ASCII characters are represented using their typical string value.

let bap = UnicodeScalar(48165)
print(bap.escaped(asASCII: false))
// Prints "밥"
print(bap.escaped(asASCII: true))
// Prints "\u{BC25}"

forceASCII: Pass true if you need the result to use only ASCII characters; otherwise, pass false. Returns: A string representation of the scalar.

Declaration

func escaped(asASCII forceASCII: Bool) -> String
func write(to:)

Writes the textual representation of the Unicode scalar into the given output stream.

target: An output stream.

Declaration

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