Class GraphemeString

Segment string into grapheme clusters once, up front. Every operation on the result reuses that work rather than re-segmenting.

Number of grapheme clusters. Mirrors String.prototype.length in graphemes.

Iterate the grapheme clusters, so Array.from(...) and spreading behave the way they do on a native string — with clusters as the unit. Without this an instance would read as array-like, and Array.from would silently produce a run of undefined instead of failing.

Mirrors String.prototype.at. The grapheme at index, or undefined if out of bounds. Negative indexes count back from the end.

Mirrors String.prototype.charAt. The grapheme at index, or '' if out of bounds. Like native — and unlike at — a negative index is out of bounds rather than counted from the end.

Mirrors String.prototype.codePointAt, indexed by grapheme. For a grapheme built from several code points this reports only the first one.

Mirrors String.prototype.endsWith: whether an occurrence of searchString ends exactly at endPosition (default: the end of the string). A negative endPosition clamps to 0 and an empty needle returns true. The match must begin on a grapheme boundary.

formatReplacementToArray with every part coerced to a string and joined.

Replace each {key} in this string with replacers[key] and unescape \{/\}. An unknown key is replaced by the key text itself. Adjacent strings are concatenated, so a replacer that is not a string stays its own entry — which is how a React element survives being substituted in.

No native counterpart, but it walks the string character by character, so it belongs here rather than beside the plain string helpers: an instance built once from a template can be formatted repeatedly without re-segmenting it.

Mirrors String.prototype.includes. See indexOf for position and boundary rules.

Mirrors String.prototype.indexOf: the first grapheme index at or after position where searchString occurs, or -1. A negative position clamps to 0, and an empty needle reports the clamped position itself. Only a hit that begins and ends on a grapheme boundary counts, so searching for a single emoji that forms part of a larger cluster reports -1 rather than matching inside it.

Accepts a raw string or a GraphemeString; the needle is used raw and is never segmented.

Mirrors String.prototype.lastIndexOf: the last grapheme index at or before position where searchString occurs, or -1. As in native, an omitted or NaN position searches the whole string while a negative one clamps to 0. See indexOf for the boundary rule.

Mirrors String.prototype.padEnd. See padStart, including the RangeError ceiling and why this returns text rather than a GraphemeString.

Mirrors String.prototype.padStart, choosing whole graphemes as filler so the result is targetLength graphemes long — where native fills UTF-16 slots and can leave a broken half of a cluster at the seam. Throws RangeError above MAX_PADDING_LENGTH, a lower ceiling than native's and the class's one deliberate departure from native behavior.

Returns text rather than a GraphemeString, unlike the range methods. Those only ever remove clusters, so a range of an honest segmentation is still honest and can be carried into the result for free. Padding adds text at a seam, and added text can fuse with what is already there — a filler ending in a combining mark joins the character it lands against — so there is no segmentation to carry. Constructing one here would mean either re-segmenting on every call or handing back an instance whose cluster array disagrees with its own text.

Mirrors String.prototype.slice. Negative indexes count back from the end and a backwards range yields an empty result.

Mirrors String.prototype.split, including the parts that surprise people: a splitLimit discards everything past the limit rather than keeping it as a final piece, the limit is converted with ToUint32 (so -1 means "no limit" while NaN and Infinity mean "empty result"), an omitted separator yields the whole string, and a regular expression's capture groups are interleaved into the result.

The grapheme substitutions: an empty separator splits into graphemes rather than UTF-16 units, and a separator only matches where it begins and ends on grapheme boundaries.

PERF: an empty separator wraps every grapheme in its own instance. When the text is all that is wanted, toArray produces the same clusters as plain strings and skips that entirely.

Entries are undefined exactly where native produces undefined — a capture group that did not participate in the match.

Splitting on a regular expression. See the string overload for the shared rules.

Splitting on a separator whose kind is not known statically — a string | RegExp union, which is what the free split in string-util declares. TypeScript matches a union argument against one overload at a time rather than distributing it, so without this a caller holding that union gets TS2769 and has to narrow at every call.

Mirrors String.prototype.startsWith: whether an occurrence of searchString begins at position. A negative position clamps to 0 and an empty needle returns true. The match must end on a grapheme boundary, so a prefix ending mid-cluster is rejected.

Mirrors String.prototype.substring. Negative indexes clamp to 0 rather than counting from the end, and — as in native — the arguments are swapped when begin is greater than end.

The grapheme clusters as an array. Returns a fresh copy, so mutating it cannot corrupt this instance. Equivalent to spreading this instance, and to spreading a native string except that native yields code points rather than clusters.

The text, for JSON.stringify. Without this an instance would serialize its internals — the raw string and the grapheme array beside it — at roughly twice the size of the text, and the result would not read back as anything useful.

Note that this makes serialization one-way: what comes off the wire is a plain string, not a GraphemeString. The class is a local segmentation cache rather than a transferable value, so a receiver that wants one constructs it from the text.

The original raw string. Named toString rather than exposed as a property so an instance drops straight into a template literal or String(...) without an accessor.