The type for glyph pools.

create () is a new empty pool with initial capacity for 4096 glyphs.

clear pool resets pool, invalidating all existing glyph references. Does not free memory, only resets internal cursors for reuse.

Warning. Glyphs must not be used after clear. Because clear can recycle IDs with the same generation, behaviour is undefined for previously issued IDs.

incref pool g increments the reference count of g in pool. No-op for simple glyphs or stale complex glyphs whose generation does not match.

decref pool g decrements the reference count of g in pool. When the count reaches zero the slot is recycled and its generation is incremented. No-op for simple glyphs or stale complex glyphs.

See also incref.

intern pool str is a glyph for the contents of str.

The result is empty for control characters or zero-width sequences. width_method defaults to `Unicode. tab_width defaults to 2.

Note. The entire string is stored as a single glyph with cumulative width. For example, intern pool "ab" produces one glyph with width 2. Use encode when per-character segmentation is needed.

Note. Invalid UTF-8 byte sequences are replaced with U+FFFD (replacement character).

Raises Failure if pool exceeds 262K interned graphemes.

See also intern_sub and encode.

intern_sub pool ~width_method ~tab_width str ~pos ~len ~width is like intern but operates on the substring str.[pos] .. str.[pos + len - 1] with precomputed display width, avoiding redundant width calculation and String.sub allocation.

Raises Failure if pool exceeds 262K interned graphemes.

encode pool ~width_method ~tab_width f str segments str into glyphs and calls f for each one, in string order.

Multi-column characters emit one start glyph followed by width - 1 continuation glyphs. Control characters and zero-width sequences are skipped. Single codepoints become simple glyphs; multi-codepoint grapheme clusters are interned.

Note. Invalid UTF-8 byte sequences are replaced with U+FFFD (replacement character). Each invalid byte consumes exactly one byte and produces one replacement glyph.

Raises Failure if pool exceeds 262K interned graphemes.

See also intern.

length pool g is the UTF-8 byte length of g. The result is 1 for simple glyphs (including empty, encoded as U+0000), the actual byte length for complex glyphs, and 0 for stale complex IDs.

blit pool g buf ~pos copies the UTF-8 bytes of g into buf starting at pos and returns the number of bytes written. empty is encoded as U+0000 (1 byte). The result is 0 for stale complex IDs or insufficient buffer space.

copy ~src g ~dst transfers g from src to dst.

Simple glyphs are returned unchanged. Complex glyphs are interned in dst and a new glyph is returned. Stale IDs return empty.

Warning. A glyph obtained from one pool must not be used with a different pool. Use copy to transfer between pools.

to_string pool g is a freshly allocated string containing the UTF-8 sequence of g. Simple glyphs produce a single-character string ("\000" for empty). Stale complex IDs produce "".