GraphemesView

public struct GraphemesView { /* private fields */ }

A view over the user-perceived characters (extended grapheme clusters) of a String.

Returned by String.graphemes. Use this — not chars — when you need the unit a user thinks of as a single character: emoji sequences, accented forms, country flags, etc. Both iteration and count() are O(n) because each cluster requires consulting the UAX #29 break tables.

Examples

let flag = "\u{1F1FA}\u{1F1F8}";  // 🇺🇸
flag.chars.count;        // 2 (regional indicators)
flag.graphemes.count;    // 1 (one flag)

Representation

A (ptr, length) pair; iteration is delegated to a wrapped CharsIterator plus the UAX #29 segmenter state machine.

Properties

public var count: Int64 { get }

Number of grapheme clusters. O(n) — walks the entire string through the UAX #29 segmenter. Cache the result if you need it more than once; each access re-walks the string.

public var endIndex: GraphemeIndex { get }

Grapheme index at the end (one past the last byte).

public var first: Grapheme? { get }

The first grapheme cluster, or None if the view is empty.

O(1) in practice — decodes one cluster from the start.

public var isEmpty: Bool { get }

true when the view spans zero bytes (no graphemes).

O(1) — checks byteCount, not count.

public var last: Grapheme? { get }

The last grapheme cluster, or None if the view is empty.

O(n) — walks the entire string through the segmenter.

public var startIndex: GraphemeIndex { get }

Grapheme index at byte 0.

Initializers

public init(slice: StringSlice)

Constructs a graphemes view backed by the given string slice. The view retains shared ownership of the underlying bytes.

Methods

public func firstIndex(where: (Grapheme) -> Bool) -> GraphemeIndex?

Returns the index of the first grapheme matching predicate, or .None.

public func index(at: Int64) -> GraphemeIndex?

Resolves the n-th grapheme cluster to its byte offset. O(n) — walks the segmenter from the start.

public func indexedIter() -> IndexedGraphemesIterator

Returns an iterator yielding (GraphemeIndex, Grapheme) pairs.

public func slice(from: GraphemeIndex, to: GraphemeIndex) -> StringSlice

Returns a StringSlice covering [start, end) by byte offset.

public func substring[__opaque_0](__opaque_0) -> String where __opaque_0: GraphemesSubstringIndex

Convenience: dispatches to a GraphemesSubstringIndex to produce an owned String covering the requested cluster range. Equivalent to self(range).toString() for both Range[Int64] and ClosedRange[Int64].

public func toString() -> String

Materializes the view as an owned String. O(n) — copies bytes.

Subscripts

public subscript[I](checked: I) -> I.GraphemesYield? { get }

Reads at index, returning .None on out-of-bounds.

public subscript[I](clamped: I) -> I.GraphemesClampedYield { get }

Reads at index saturated to [0, count). Single-grapheme indexes yield Grapheme? (.None only when the view is empty); range indexes yield GraphemesView (always valid, possibly empty).

public subscript[I](I) -> I.GraphemesYield { get }

Int64 reads a single cluster; Range[Int64] / ClosedRange[Int64] yield a zero-copy GraphemesView sub-view covering those clusters. O(n) — walks the segmenter from the start. Panics on out-of-bounds.

public subscript[I](wrapped: I) -> I.GraphemesWrappedYield { get }

Reads at index with modulo wrap-around. Negative indices wrap from the end: view.graphemes(wrapped: -1) reads the last grapheme cluster. Returns None on an empty view.

ImplementsIterable

Associated Types

type Item = Grapheme

The element type yielded by iteration — always Grapheme.

type TargetIterator = GraphemesIterator

The iterator type returned by iter().

Methods

public func iter() -> GraphemesIterator

Returns a GraphemesIterator positioned at byte 0.

ImplementsCloneable

Methods

public func clone() -> GraphemesView

Defined in lang/std/text/views.ks