Text utilities

The exact v0.3 declarations and focused tests are indexed in the standard-library reference.

Flecha’s standard text modules build on the byte-oriented string and stringv types described in strings. They do not change string indexing or length semantics: both continue to count bytes.

Numeric conversion

The strings module provides fallible integer and floating-point conversion:

integer, integerError := strings::stringv_to_int<i64>("-42");
decimal, decimalError := strings::stringv_to_float<f64>("1.25e2");

integerText, integerFormatError := strings::int_to_string(integer);
decimalText, decimalFormatError := strings::float_to_string(decimal);

Parsing consumes the complete input and never skips whitespace. Integer conversion reports empty input, invalid syntax, and target-width overflow. Floating-point conversion accepts decimal notation plus the canonical non-finite spellings nan, inf, and -inf; overflow and underflow report ParseError.Overflow. The runtime copies the length-delimited input before calling the platform conversion boundary, so allocation failure is reported as AllocationError.OutOfMemory.

format_integer and format_float write into caller-provided byte slices. Failure leaves the destination unchanged. Floating-point formatting is locale-independent and emits the shortest representation that parses back to the same f32 or f64 value. It preserves negative zero and uses lowercase non-finite spellings.

Incremental construction

StringBuilder accumulates byte-oriented text while reporting allocation failure explicitly. Alongside raw text, bytes, Unicode code points, integers, and booleans, it can append deterministic floating-point text:

builder := strings::StringBuilder::init();
err := builder.append("value=");
if err == none {
    err = builder.appendFloat<f64>(1.25);
}

text, copyError := builder.toString();

Failed numeric conversion or allocation preserves the builder’s existing contents. view() borrows the accumulated bytes without allocating, while toString() copies them into an independent owning string and reports AllocationError.OutOfMemory.

When allocation failure is intentionally unrecoverable, a crashable caller can select the paired method:

string finish!(&const strings::StringBuilder builder) {
    return builder.toString!();
}

toString!() returns the same owning copy directly. If the copy cannot be allocated, it emits the standard crash report instead of returning an error.