Documentation / Core packages / Core text

Core text

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

Text helpers

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

Importing

Bring in the functions you need with a grouped import.


    import @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 import.

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

Import roots

Import individual symbols or the whole namespace:


    import @core/text {length, contains}

    import @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.

Implementation gap: the current HTML-JS lowering uses JavaScript String.prototype.length, which counts UTF-16 code units rather than Unicode scalar values. For strings containing characters outside the Basic Multilingual Plane, the JS result is higher than the language-level count. See progress matrix for the recorded drift.

HTML-Wasm lacks a Wasm lowering for these functions. See progress matrix for current target availability.

Unsupported source forms

  • Direct symbol-path imports such as import @core/text/length face rejection. Use grouped or namespace imports.
  • 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