Standard library

Strings

String conversion, text helpers, and number parse.

Introduction

String conversion, text helpers, and number parse. Import std/str to bind the module as str. Call free functions as str.name(...). Struct methods use a receiver value.

/ std/str

This page is the package reference for std/str. Private helpers used only by co-located tests are not listed.

Functions

Free functions on str. Each function has a short description, an example, then parameters and return shape.

from_int

Converts an integer to its decimal string form. Call form: str.from_int(n).

/ std/io
/ std/str

io.print(str.from_int(42))

Parameters: n: integer to convert. Returns: Decimal string for n.

from_float

Converts a float to a string. Call form: str.from_float(n).

/ std/io
/ std/str

io.print(str.from_float(<f64>3.14))

Parameters: n: float to convert. Returns: String form of n.

from_bytes

Decodes a byte sequence as UTF-8 text. Invalid sequences are handled lossily. Call form: str.from_bytes(b).

/ std/io
/ std/str

io.print(str.from_bytes(b'hi'))

Parameters: b: bytes value to decode. Returns: UTF-8 string decoded from b.

from_duration

Formats a duration value as a human-readable unit string. Call form: str.from_duration(d).

/ std/io
/ std/str

io.print(str.from_duration(1s))

Parameters: d: duration value. Returns: Human-readable duration string.

from_locator

Converts a locator (path or URI) to its string form. Call form: str.from_locator(loc).

/ std/io
/ std/str

io.print(str.from_locator(p'/tmp/x'))

Parameters: loc: locator value. Returns: String form of the locator.

from_debug

Returns shallow debug text for any value (REPL bare-expr display and diagnostics). Call form: str.from_debug(v).

/ std/io
/ std/str

io.print(str.from_debug([1, 2]))

Parameters: v: any value. Returns: Debug text string.

len

Returns the length of a string in UTF-8 bytes (same index space as get and slice). Call form: str.len(s).

/ std/io
/ std/str

io.print(str.from_int(str.len("hi")))

Parameters: s: string value. Returns: Byte length of s as an integer.

is_empty

Reports whether a string has length zero. Call form: str.is_empty(s).

/ std/str

$ empty = str.is_empty("")

Parameters: s: string value. Returns: Boolean.

cat

Concatenates two strings. Call form: str.cat(a, b).

/ std/io
/ std/str

io.print(str.cat("hel", "lo"))

Parameters: a: left string. b: right string. Returns: Concatenated string a then b.

contains

Reports whether hay contains needle as a substring. Call form: str.contains(hay, needle).

/ std/str

$ ok = str.contains("hello", "ell")

Parameters: hay: string to search. needle: substring to find. Returns: Boolean.

starts_with

Reports whether s begins with prefix. Call form: str.starts_with(s, prefix).

/ std/str

$ ok = str.starts_with("hello", "he")

Parameters: s: string. prefix: expected prefix. Returns: Boolean.

ends_with

Reports whether s ends with suffix. Call form: str.ends_with(s, suffix).

/ std/str

$ ok = str.ends_with("hello", "lo")

Parameters: s: string. suffix: expected suffix. Returns: Boolean.

get

Result-shaped access: ok is the UTF-8 byte at index i as ui8; error is "out of bounds". Indices match str.len (byte length). Call form: str.get(s, i).

/ std/io
/ std/str

| str.get("AB", 1) {
    $ b {
        io.print(str.from_int(b))
    }
    ! e {
        io.print(e)
    }
}

Parameters: s: string. i: zero-based UTF-8 byte index. Returns: Result. Ok arm: byte as ui8. Err arm: "out of bounds".

slice

Result-shaped half-open UTF-8 byte range [start, end). Error is "out of bounds". Prefer char-safe bounds for non-ASCII. Call form: str.slice(s, start, end).

/ std/io
/ std/str

| str.slice("hello", 1, 4) {
    $ part {
        io.print(part)
    }
    ! e {
        io.print(e)
    }
}

Parameters: s: string. start: inclusive byte index. end: exclusive byte index. Returns: Result. Ok arm: sliced string. Err arm: "out of bounds".

trim

Strips leading and trailing ASCII whitespace. Call form: str.trim(s).

/ std/io
/ std/str

io.print(str.trim("  hi  "))

Parameters: s: string to trim. Returns: Trimmed string.

to_lower

Lowercases ASCII letters in s. Call form: str.to_lower(s).

/ std/io
/ std/str

io.print(str.to_lower("Hi"))

Parameters: s: string. Returns: Lowercased string.

to_upper

Uppercases ASCII letters in s. Call form: str.to_upper(s).

/ std/io
/ std/str

io.print(str.to_upper("Hi"))

Parameters: s: string. Returns: Uppercased string.

split

Splits s on separator sep. Call form: str.split(s, sep).

/ std/str

$ parts = str.split("a,b,c", ",")

Parameters: s: string. sep: separator substring. Returns: List of string parts.

replace

Replaces occurrences of from with to in s. Call form: str.replace(s, from, to).

/ std/io
/ std/str

io.print(str.replace("hello", "l", "L"))

Parameters: s: string. from: substring to replace. to: replacement. Returns: String after replacements.

join

Joins string parts with separator sep. Call form: str.join(parts, sep).

/ std/io
/ std/str

io.print(str.join(["a", "b"], "-"))

Parameters: parts: list of strings. sep: separator between parts. Returns: Joined string.

repeat

Repeats string s exactly n times. Call form: str.repeat(s, n).

/ std/io
/ std/str

io.print(str.repeat("ab", 3))

Parameters: s: string. n: non-negative repeat count. Returns: Repeated string.

parse_int

Parses a decimal integer string. Call form: str.parse_int(s).

/ std/io
/ std/str

| str.parse_int("42") {
    $ n {
        io.print(str.from_int(n))
    }
    ! e {
        io.print(e)
    }
}

Parameters: s: decimal integer text. Returns: Result. Ok arm: integer. Err arm: parse failure message.

parse_float

Parses a floating-point string. Call form: str.parse_float(s).

/ std/str

| str.parse_float("3.14") {
    $ n { }
    ! e { }
}

Parameters: s: float text. Returns: Result. Ok arm: float. Err arm: parse failure message.