Char

public struct Char { /* private fields */ }

A single Unicode scalar value (code point in 0..=0x10FFFF, surrogates excluded).

Char is the unit yielded by String.chars / CharsView; iterating graphemes (String.graphemes) instead returns Grapheme clusters that may comprise multiple Chars. The character-literal syntax constructs values directly: 'a', '\n', '\u{1F600}'. For the raw byte representation, see utf8Length() and the free encodeUtf8 / decodeUtf8 functions.

Examples

let a: Char = 'a';
a.isAsciiLetter;    // true
a.utf8Length();      // 1
let smile: Char = '\u{1F600}';
smile.utf8Length();  // 4

Representation

A single UInt32 holding the scalar value. Comparison and hashing operate on that integer directly.

Properties

public var isAscii: Bool { get }

Returns true if the scalar is in the ASCII range (< 0x80).

Cheap byte-range test; does not consult Unicode tables. For "alphabetic by Unicode" use unicode.toLowercase round-tripping or the property tables directly.

Examples

'A'.isAscii;          // true
'\u{00E9}'.isAscii;   // false (é)

public var isAsciiAlphanumeric: Bool { get }

Returns true for ASCII letters and ASCII digits.

Composition of isAsciiLetter and isAsciiDigit; same ASCII-only caveats apply.

Examples

'a'.isAsciiAlphanumeric;  // true
'7'.isAsciiAlphanumeric;  // true
'_'.isAsciiAlphanumeric;  // false

public var isAsciiDigit: Bool { get }

Returns true for the ASCII digits 0–9.

ASCII-only. Other Unicode digit categories (Arabic-Indic, Devanagari, etc.) return false. See digitValue() for parsing to numeric value.

Examples

'7'.isAsciiDigit;   // true
'a'.isAsciiDigit;   // false

public var isAsciiLetter: Bool { get }

Returns true for ASCII letters A–Z / a–z.

ASCII-only. Non-ASCII letters (e.g. é, Ω, 日) return false even though they are letters in Unicode. For the full Unicode test, use the property tables in std.text.unicode.

Examples

'A'.isAsciiLetter;         // true
'\u{00E9}'.isAsciiLetter;  // false (é — non-ASCII)
'7'.isAsciiLetter;         // false

public var isAsciiLowercase: Bool { get }

Returns true for ASCII lowercase letters a–z.

ASCII-only. Use unicode.toLowercase round-tripping for general Unicode case tests.

Examples

'a'.isAsciiLowercase;   // true
'A'.isAsciiLowercase;   // false

public var isAsciiUppercase: Bool { get }

Returns true for ASCII uppercase letters A–Z.

ASCII-only. Use unicode.toUppercase round-tripping for general Unicode case tests.

Examples

'A'.isAsciiUppercase;         // true
'a'.isAsciiUppercase;         // false
'\u{00C9}'.isAsciiUppercase;  // false (É — non-ASCII)

public var isControl: Bool { get }

Returns true for the C0 controls (< U+0020) and DEL (U+007F).

Does not include the C1 controls (U+0080–U+009F); add a dedicated test if you need them.

Examples

'\n'.isControl;     // true
'\x7F'.isControl;   // true
'a'.isControl;      // false

public var isWhitespace: Bool { get }

Returns true for the common ASCII whitespace set: space, tab, LF, CR, form feed.

Does not include Unicode whitespace such as U+00A0 (no-break space) or U+2028 (line separator). For Unicode-aware whitespace, consult the property tables.

Examples

' '.isWhitespace;    // true
'\t'.isWhitespace;   // true
'\n'.isWhitespace;   // true
'a'.isWhitespace;    // false

Initializers

public init(charLiteral: lang.i32)

Compiler-emitted constructor for character literals.

Called when you write 'a', '\n', '\u{1F600}'. Not intended for direct use — Char(value:) is the user-facing constructor.

Examples

let c: Char = 'a';  // lowers to Char(charLiteral: ...)

public init(fromDigit: UInt32)

Returns the ASCII digit Char for a numeric value 0–9, null otherwise.

Inverse of digitValue. Values outside 0..=9 return null.

Examples

Char(fromDigit: 7);   // Some('7')
Char(fromDigit: 12);  // None

public init(UInt32)

Returns a Char if the value is a valid Unicode scalar, null otherwise. Rejects values > U+10FFFF and the surrogate range U+D800..U+DFFF.

Examples

let c = Char(65);      // Some('A')
let bad = Char(0xD800); // None (surrogate)

public init(unchecked: UInt32)

Wraps a raw UInt32 scalar value as a Char without validation.

Safety

The caller must ensure value is a valid Unicode scalar (0..=0x10FFFF, excluding surrogates U+D800..U+DFFF).

Methods

public func digitValue() -> UInt32?

Returns the numeric value 0–9 for ASCII digits, otherwise None.

Inverse of fromDigit. Non-ASCII digit characters return None — match isAsciiDigit semantics.

Examples

'7'.digitValue();  // Some(7)
'a'.digitValue();  // None

public func hasLowercaseExpansion() -> Bool

Returns true if the lowercase form is multi-char.

Rare in practice but exists for full Unicode round-tripping.

public func hasTitlecaseExpansion() -> Bool

Returns true if the titlecase form is multi-char.

public func hasUppercaseExpansion() -> Bool

Returns true if the uppercase form is multi-char (e.g. ß → SS).

When true, prefer uppercaseExpansion() over uppercased() to avoid silently dropping characters.

Examples

'\u{00DF}'.hasUppercaseExpansion();  // true (ß)
'a'.hasUppercaseExpansion();         // false

public func lowercaseExpansion() -> String

Returns the multi-char lowercase form as a String.

Empty string if no expansion exists.

public func lowercased() -> Char

Returns the lowercase form, using full Unicode case-mapping tables.

Locale-independent. For characters with multi-char lowercase expansions, see lowercaseExpansion().

Examples

'A'.lowercased();         // 'a'
'\u{0130}'.lowercased();  // 'i' (Turkish dotted I — first char only)

public func titlecaseExpansion() -> String

Returns the multi-char titlecase form as a String.

Empty string if no expansion exists.

public func titlecased() -> Char

Returns the titlecase form, using full Unicode case-mapping tables.

Titlecase differs from uppercase for some characters — e.g. ligatures like ǳ titlecase to ǲ (capital plus small) rather than Ǳ (full uppercase).

Examples

'a'.titlecased();   // 'A'

public func toString() -> String

Converts this code point to an owned String.

public func uppercaseExpansion() -> String

Returns the multi-char uppercase form as a String.

For characters without an expansion this returns the empty string; use hasUppercaseExpansion() first to distinguish.

Examples

'\u{00DF}'.uppercaseExpansion();  // "SS"
'a'.uppercaseExpansion();         // ""

public func uppercased() -> Char

Returns the uppercase form, using full Unicode case-mapping tables.

For characters whose uppercase form is multiple Chars (e.g. German ß → SS), this returns only the first Char. Use hasUppercaseExpansion() plus uppercaseExpansion() to handle those cases correctly. Locale-independent — does not perform Turkish / Azeri tailoring.

Examples

'a'.uppercased();         // 'A'
'\u{00DF}'.uppercased();  // 'S' (first char of "SS"; see hasUppercaseExpansion)

public func utf8Length() -> Int64

Returns how many UTF-8 bytes are required to encode this character (1–4).

Constant time — branches on the scalar value alone. Use this to size buffers before calling encodeUtf8.

Examples

'a'.utf8Length();          // 1
'\u{00E9}'.utf8Length();   // 2 (é)
'\u{20AC}'.utf8Length();   // 3 (€)
'\u{1F600}'.utf8Length();  // 4 (😀)

public func value() -> UInt32

Returns the raw Unicode scalar as a UInt32.

Useful for arithmetic on code points (e.g. digitValue's offset trick) or interop with APIs that take a numeric code point.

Examples

'A'.value();  // 65
'\u{1F600}'.value();  // 128512

ImplementsEquatable

Associated Types

type Output = Bool

Methods

public func equal(to: Self) -> Bool

Bridges Equal.equal(to:) to Equatable.isEqual(to:).

public func isEqual(to: Char) -> Bool

Returns true if both characters are the same Unicode scalar.

Pure scalar-value equality — no case folding, no normalization.

Examples

'a'.isEqual(to: 'a');  // true
'a'.isEqual(to: 'A');  // false

public func notEqual(to: Self) -> Bool

Default !=: delegates to == so there's a single source of truth.

ImplementsComparable

Associated Types

type Output = Bool

Methods

public func compare(Char) -> Ordering

Compares two characters by scalar value.

Yields code-point order, which agrees with byte order in UTF-8 (UTF-8 is order-preserving). Not the same as locale-aware collation.

Examples

'a'.compare('b');  // Less
'b'.compare('a');  // Greater
'a'.compare('a');  // Equal

public func greaterThan(Self) -> Bool

> derived from compare.

public func greaterThanOrEqual(Self) -> Bool

>= derived from compare.

public func isAtLeast(Self) -> Bool

start.. lower-bound check, derived from compare.

public func isAtMost(Self) -> Bool

..=end upper-bound check, derived from compare.

public func isBelow(Self) -> Bool

..<end upper-bound check, derived from compare.

public func lessThan(Self) -> Bool

< derived from compare.

public func lessThanOrEqual(Self) -> Bool

<= derived from compare.

ImplementsMatchable

Methods

public func matches(Char) -> Bool

Pattern-match form of equality — delegates to isEqual.

ImplementsExpressibleByCharLiteral

Initializers

init(charLiteral: lang.i32)

Builds an instance from a character literal.

ImplementsHashable

Methods

public func hash[H](into: mutating H) where H: Hasher

Hashes this character by writing its 4-byte scalar value to the hasher.

Uses native byte order — fine for in-process hash maps; do not use the result for content-addressed storage.

ImplementsRangeMatchable

Methods

public func isAtLeast(Char) -> Bool

Returns true if self >= bound. Used by RangeMatchable for case 'a'...'z'.

public func isAtMost(Char) -> Bool

Returns true if self <= bound. Used by RangeMatchable for case 'a'...'z'.

public func isBelow(Char) -> Bool

Returns true if self < bound. Used by RangeMatchable for half-open patterns.

ImplementsFormattable

Methods

public func format(into: mutating StringBuilder, FormatOptions)

public func formatted(FormatOptions) -> String

Returns this value rendered as a String.

Convenience wrapper: creates a StringBuilder, calls format(into:), and returns the built string. Uses a distinct name to avoid overload-resolution ambiguity with format(into:).

Defined in lang/std/text/char.ks