Grapheme

public struct Grapheme { /* private fields */ }

An extended grapheme cluster — what users perceive as a single character.

A grapheme may comprise one Char (e.g. 'a') or several (combining marks, regional-indicator country flags, ZWJ-joined emoji sequences). String.graphemes is the canonical producer; iteration uses UAX #29 segmentation. Treat Grapheme as the right unit for any user-visible operation (cursor movement, selection, truncation for display).

Examples

let g = Grapheme(char: 'a');
g.charCount();   // 1
g.isAscii;     // true
g.utf8Length();  // 1

Representation

An Array[Char] of the constituent code points in scalar order.

Properties

public var chars: Array[Char] { get }

The constituent code points in scalar order.

Materializes a fresh Array[Char] on every access.

public var firstChar: Char { get }

Returns the first Char of the cluster.

The first code point of this grapheme cluster.

public var isAscii: Bool { get }

Returns true iff the cluster is exactly one ASCII Char.

A single-Char non-ASCII grapheme (e.g. é as the precomposed U+00E9) returns false. Multi-Char clusters always return false even if every component is ASCII.

Initializers

public init(chars: Array[Char])

Constructs a grapheme from a sequence of Chars.

The caller is responsible for the chars actually forming a single UAX #29 cluster — the constructor does not segment or validate. GraphemesIterator is the canonical producer of valid clusters. Single-char input avoids allocating; multi-char input keeps the trailing code points in a separate array.

Examples

var chars = Array[Char]();
chars.append('e');
chars.append('\u{0301}');  // combining acute
let g = Grapheme(chars: chars);
g.charCount();  // 2

public init(char: Char)

Constructs a one-Char grapheme.

Allocation-free — the common path for ASCII iteration through GraphemesView.

Examples

let g = Grapheme(char: 'a');
g.charCount();  // 1

Methods

public func charCount() -> Int64

Returns the number of Chars in this cluster — 1 for plain ASCII, more for combining sequences and ZWJ-joined emoji.

public func utf8Length() -> Int64

Returns the total UTF-8 byte length of all constituent Chars.

Sum of each Char.utf8Length(). Use this to size a buffer before re-encoding the cluster.

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: Grapheme) -> Bool

Returns true if the two graphemes are the same length and every Char is equal pairwise.

Not Unicode normalization-aware: precomposed é (U+00E9) and decomposed e + U+0301 are not equal under this check even though they represent the same user-perceived character. Normalize both sides first if you need that.

Examples

let a = Grapheme(char: 'a');
let b = Grapheme(char: 'a');
a.isEqual(to: b);  // true

public func notEqual(to: Self) -> Bool

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

ImplementsCloneable

Methods

public func clone() -> Grapheme

Returns a deep copy of this grapheme.

ImplementsComparable

Associated Types

type Output = Bool

Methods

public func compare(Grapheme) -> Ordering

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.

ImplementsHashable

Methods

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

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