Documentation / Core packages / Core text

Core text

@core/text provides checks for String length, emptiness and substrings. Length counts Unicode scalar values rather than UTF-16 code units, which keeps the result aligned with Moth's Char model across backends.

Text helpers

@core/text gives you helper functions for String values. Bind it when you need to check length, emptiness or substrings.

Binding

Bind the functions you need with a direct-selection clause.

@core/text length, contains

name = "Priya"
count = length(name)
has_stalk = contains(name, "stalk")

io.line([:count=[count] has_stalk=[has_stalk]])

Available functions

  • length(text) returns the number of Unicode scalar values as Int
  • is_empty(text) returns Bool
  • contains(text, substring) returns Bool
  • starts_with(text, prefix) returns Bool
  • ends_with(text, suffix) returns Bool

All functions take String values and return Int or Bool. For the full function contract, backend behaviour and deferred surfaces, see Core text advanced.

@core/text provides helper functions for String values. It belongs to the binding-backed Core package family with no prelude alias, so it requires an explicit dependency clause.

@core/text carries Core origin with ExternalBinding backing. See Package origins and backing for origin and backing rules.

Dependency roots

Bind individual symbols or the whole namespace:

@core/text length, contains

@core/text

name = "Priya"
count = text.length(name)

Functions

All functions take String parameters with shared access. Parameters stay positional-only. Named arguments lack support because binding-backed packages do not expose source-function features.

Function

Parameters

Returns

length(text)

String

Int

is_empty(text)

String

Bool

contains(text, substring)

String, String

Bool

starts_with(text, prefix)

String, String

Bool

ends_with(text, suffix)

String, String

Bool

All functions stay infallible at the Moth level. They do not return through Error!.

Access and return contracts

All parameters use shared access. No function requires mutable access. length returns a fresh Int. The predicate functions return fresh Bool values.

Length unit

text.length returns the number of Unicode scalar values in the string. A Unicode scalar value is a Unicode code point excluding surrogate code points. This is the same unit Char represents.

A string of N Char values reports text.length of N. Surrogate pairs in the runtime encoding do not inflate the count.

HTML-JS implements this contract with scalar-value iteration, so BMP and non-BMP characters each contribute one count. The return type remains Int and the package stays infallible. HTML-Wasm still lacks a lowering for this package; see progress matrix for current target availability.

Unsupported source forms

  • Direct symbol-path clauses such as @core/text/length face rejection. Use direct selections or a namespace clause.
  • Named arguments lack support. Binding-backed calls stay positional-only.
  • The package does not expose receiver methods, opaque types or Error! channels.
  • Receiver-method forms on String values remain deferred. Use the free functions.

Deferred surfaces

Deferred text surfaces include receiver-method forms, string splitting and joining, case conversion, trimming, replacement, regular expressions, character iteration, Unicode normalisation and non-JS lowerings. See progress matrix for current status.

Related concepts