Text Domain API Guidelines

Core Semantics

character = Unicode code point, not grapheme, glyph, or byte
native position = UTF-8 byte, UTF-16 code-unit, or UTF-32 code-point index or length
signal = explicit non-character result from tolerant character access
ASCII folding = case-insensitive comparison limited to ASCII letters
Unicode folding = case-insensitive comparison using Unicode mapping

Primary Types

String, U8String, U16String, U32String // owning read-only strings for each supported width
Char // Unicode code-point value with explicit signal states

Processing Types

AnyString, AnyStringEditor, AnyStringBuilder // runtime-width text values and builder
StringEditor, U8StringEditor, U16StringEditor, U32StringEditor // local mutable editing and construction values
StringLiteral, U8StringLiteral, U16StringLiteral, U32StringLiteral // compile-time string literals
StringCharReader, StringCharReaderState // sequential decoded-character reader and retained state
StringSplitter, U8StringSplitter, U16StringSplitter, U32StringSplitter // owning sequential splitters
CharRange, CharSet, CombinedChar, CharSignal // code-point range, set, combined value, and access signal
UnicodeCategory, UnicodeCategoryGroup, AsciiCategory // character classifications
NormalizationForm // NFC, NFD, NFKC, and NFKD Unicode normalization selection
StringKind, StringSide, StringSplitMode, CaseSensitivity // width, position, splitting, and comparison policies
StringConverter // explicit Erbsland Core and standard string conversion entry point
StringDecoder, StringEncoder, StringDecodeBuffer // byte codecs and bounded incremental decoding
StringEncoding, EncodingMode, StringBomMode // encoding, error, and byte-order-mark policies

Formatting and Parsing Types

StringFormat, U8Format, U16Format, U32Format // typed formatters for each output width
FormatArgument, FormatArgumentKind, FormatAs // erased arguments and text formatting adapters
BooleanFormat, ByteFormat, IntegerFormat, FloatFormat // scalar formatting policies
IntegerParseOptions, FloatParseOptions // numeric parsing policies
ReadIntegerResult, ReadNumberStatus // incremental numeric parsing result and status
IntegerBase, IntegerSignMode, LetterCase, Capitalization // numeric and text presentation values
EscapeFormat, EscapeAmount, SafeStringFlags, TruncateMode // escaping and bounded-display policies
FormatError, ParseNumberError // typed formatting and numeric parsing failures
EncodingError, U8EncodingError, U16EncodingError, U32EncodingError // width-specific encoding failures

Collection and Pattern Types

StringList, U8StringList, U16StringList, U32StringList // read-only string lists
StringEditorList, U8StringEditorList, U16StringEditorList, U32StringEditorList // mutable string lists
StringMap, StringHashMap, StringSet, StringHashSet // ordered and hashed UTF-8 collections
StringCIMap, StringCIHashMap, StringCISet, StringCIHashSet // ASCII-case-insensitive UTF-8 collections
U❮width❯StringMap, U❮width❯StringHashMap // width-specific ordered and hashed maps
U❮width❯StringSet, U❮width❯StringHashSet // width-specific ordered and hashed sets
StringPattern // lightweight decoded-character matcher
fuzzy::Matcher, fuzzy::Match, fuzzy::MatchList // ranked decoded-code-point edit-distance matching
StringTree // dot-separated string-key hierarchy

Document Types

TextDocument, TextNode, TextNodeData // mutable semantic document tree
TextNodeType, TextWalkStatus, TextWalkResult // node classification and traversal control
PlainTextRenderer // semantic document to plain-text renderer
CodeSnippet, CodeSnippetMarker // indexed source excerpt and annotation
html::HtmlParser // tolerant HTML-to-document parser
json::JsonValue, json::JsonType // copy-on-write JSON value tree and semantic type
json::JsonArray, json::JsonObject // ordered JSON containers
json::JsonParseOptions, json::JsonFormatOptions // JSON limits and output controls

Layout Renderer Types

render::Environment, render::EnvironmentOptions, render::RenderLimits // renderer configuration and limits
render::Loader, render::FileSystemLoader, render::ResourceLoader // logical-layout source providers
render::LayoutSource // source text, diagnostic origin, and opaque revision
render::Context // concrete named values passed to a render
render::Value, render::ValueType // immutable shared render values and their semantic type
render::FilterFn // callback receiving the piped value and up to two arguments in one immutable value list
render::RenderError, render::RenderErrorContext // structured user-facing render failures
render::RenderErrorCategory // stable failure classification

Codec Types

base_n::BaseNFormat // alphabet, padding, whitespace, and line-wrapping policy
base_n::BaseNEncoder, base_n::BaseNDecoder // binary-to-text and text-to-binary codecs
base_n::BaseNFormatFlag, base_n::BaseNFormatFlags // padding and wrapping flags
punycode::PunycodeEncoder, punycode::PunycodeDecoder // Unicode/Punycode and optional strict IDNA2008 conversion
punycode::PunycodeOptions, punycode::PunycodeMode // pure, label, or domain processing policy

Pattern Definitions

E = StringEditor/U❮width❯StringEditor // mutable string for the selected width
I = unit::❮Index❯ // native or code-point string index
S = String/U❮width❯String // read-only string for the selected width

String Value Patterns

o.length()/characterLength()/isEmpty() -> T // inspect native-unit and code-point bounds
o.charAt(index-or-side) -> Char // access a decoded character or signal
o.indexAt(cpIndex-or-side)/toCharIndex(nativeIndex) -> I // convert between native and code-point positions
o.slice(range-or-side)/copy() -> S // create a shared slice or compact independent value
o.compare(text[, comparison]) -> std::strong_ordering // compare decoded text
o.find/findLast(text[, start, comparison]) -> I // locate text using native indexes
o.startsWith/endsWith/contains(text[, comparison]) -> bool // test text membership
o.containsOnly(set-or-ascii-category) -> bool // validate decoded character membership
o.forEach(function) -> util::LoopResult // visit decoded code points
o.splitAt(index) -> std::pair❮S❯ // split into read-only values
o.trimmed/transformed([arguments]) -> S // return processed read-only text
o.normalized(form) -> S // explicitly normalize and share storage when already normalized
o.toEscaped/toSafeString([options]) -> S // create escaped or bounded diagnostic text

String Editing Patterns

T(string-or-literal) // create explicit editable storage
o.append/insert/replace(position, text) -> E& // add or replace text in place
o.remove/trim(range-or-characters) -> E& // remove text in place
o.slice/trimmed(range-or-characters) -> E // return an editable result
o.normalize(form) -> E& // normalize in place
o.normalized(form) -> E // return an editable normalized result
o.clear()/reset() // empty while retaining or releasing storage
o.reserve(capacity)/detach() // prepare storage or ensure exclusive ownership
o.toString/takeString() -> String // copy or move completed UTF-8 text
o.toStringEditor/takeStringEditor() -> StringEditor // copy or move mutable UTF-8 storage

Reader and Split Patterns

T(text[, separator, mode]) // create an owning reader or splitter
o.isAtEnd()/position()/remaining() -> T // inspect sequential state
o.next()/peek() -> T // consume or inspect the next character or slice
o.advanceIf(character-or-string[, compare]) -> bool // transactionally skip an optional token
o.advanceWhile/advanceUntil(set-or-ascii-category[, maximum]) -> unit::CpLength // skip and inspect the count
o.readWhile/readUntil(function, set-or-ascii-category[, maximum]) -> util::LoopResult // decoded scan
o.skip() // discard the next splitter part without creating a slice
o.reset([state]) // restart or restore retained reader state

Conversion and Encoding Patterns

T(input[, encoding]) // create a conversion, decoder, or encoder operation
o.toString/toU❮width❯String/toStdString([mode]) -> T // convert with tolerant or strict decoding
o.toAnyString() -> AnyString // preserve runtime-selected width
o.decode([mode]) -> S // decode owned bytes to the requested width
o.validateOrThrow(encoding[, bom-mode]) // strictly validate encoded bytes without creating a string
o.encode() -> mem::ByteBlock // tolerantly encode text into owned bytes
o.encodedLength() -> unit::ByteLength // calculate encoded byte length
o.encodeTo(ring) -> util::Result // atomically encode into a byte ring
o.peek❮Width❯String/take❮Width❯String(maximum) -> S // inspect or consume bounded decoded text
o.setSensitive(enabled) // configure StringDecodeBuffer storage and UTF-8 result marking

Formatting and Parsing Patterns

T(pattern) // create a typed formatter
o.format(arguments) -> S // format checked runtime arguments
T::format(pattern, arguments) -> S // format without retaining a formatter
o.toBoolean/toInteger/toFloat([fallback-or-options]) -> T // parse with a fallback
o.toBooleanOrThrow/toIntegerOrThrow/toFloatOrThrow([options]) -> T // parse or throw
o.toString() -> String // create a canonical option or policy representation
T::fromString/fromStringOrThrow(text) -> T // parse a canonical option or policy representation

Sensitive UTF-8 Patterns

o.isSensitive() -> bool // inspect the shared UTF-8 allocation mark
o.markAsSensitive() // irreversibly mark the complete shared UTF-8 allocation
o.copy/slice/trimmed/transformed(...) -> S // preserve the source mark for same-width results
o.reset() // release this alias; erase marked storage after the final alias releases it

Document Patterns

T() // create an empty document with a valid root
o.root()/add❮Element❯(arguments) -> TextNodePtr // access or extend the document tree
o.walk(callback) -> TextWalkResult // traverse semantic nodes
o.toString() -> String // render completed plain text
o.appendTo(builder) -> AnyStringBuilder& // append completed plain text
T(document) // create a plain-text renderer for a document
o.build() -> String // explicitly render a document

JSON Value Patterns

T() // create JSON null
T(primitive-or-array-or-object) // create a JSON value
o.type()/is(type)/isPrimitive() -> T // inspect the semantic type
o.get(index-or-key)/getOrThrow(index-or-key) -> JsonValue // access a child value
o.get<U>([fallback])/getOrThrow<U>() -> U // access a checked native representation
o.set(index-or-key, value)/append(value) -> T& // detach and mutate an array or object
o.toString([options]) -> String // serialize deterministic JSON
T::fromString(text[, options]) -> optional<T> // parse with empty failure reporting
T::fromStringOrThrow(text[, options]) -> T // parse or throw ParseError

Layout Renderer Patterns

T::create([options]) -> EnvironmentPtr // create a setup-phase environment
o.addLayoutLoader(loader[, priority])/addFilter(name, filter)/enableAutoReload() // configure before first render
o.setGlobalContext(context) // atomically replace the global fallback snapshot
o.render(layout[, context]) -> String // compile/cache and render a logical layout
o.load(layout) -> optional<LayoutSource> // return one source generation or report missing
o.contains/get/set(name[, value]) -> T // inspect or change named local values
o.type()/isTruthy()/itemCount() -> T // inspect immutable value semantics
o.get(index-or-name) -> Value // tolerant child lookup returning null when missing
o.as❮Scalar❯() -> T // checked scalar access

Base-N Codec Patterns

T::base16/base32/base64❮Variant❯() -> base_n::BaseNFormat // create a standard format
T(input[, format]) // create an encoder from bytes or decoder from text
o.encode() -> AnyString // encode into the configured output width
o.decode/decodeOrThrow() -> mem::ByteBlock // decode with empty or throwing failure reporting

Punycode and IDNA Patterns

T(text[, options]) // create a Punycode encoder or decoder
o.encode() -> std::optional<String> // encode with empty failure reporting
o.decode() -> std::optional<String> // decode with empty failure reporting
o.encodeOrThrow() -> String // encode or throw err::ParseError
o.decodeOrThrow() -> String // decode or throw err::ParseError
T() // create pure RFC 3492 options without prefix, domain, normalization, or filtering policy
T::idna2008Label() -> PunycodeOptions // create strict IDNA2008 label options
T::idna2008Domain() -> PunycodeOptions // create strict IDNA2008 domain options
T::network() -> PunycodeOptions // create the strict network-domain policy