std.string

The string operations module. Except for format, all functions take read-only borrows (&String) of their inputs, so the source string remains usable after the call.

When the argument types do not match, all functions degrade to empty-string semantics (rather than reporting an error): split / trim / upper and the like treat non-String inputs as "". This means a wrong argument type will not abort execution, but it will not produce the expected result either — it is recommended that the type checker intercept such errors at compile time.

use std.string

Function Overview

Function	Signature
split	(s: &String, sep: &String) -> Vec(String)
trim	(s: &String) -> String
upper	(s: &String) -> String
lower	(s: &String) -> String
replace	(s: &String, old: &String, new: &String) -> String
contains	(s: &String, sub: &String) -> Bool
starts_with	(s: &String, prefix: &String) -> Bool
ends_with	(s: &String, suffix: &String) -> Bool
index_of	(s: &String, sub: &String) -> Int
substring	(s: &String, start: Int, end: Int) -> String
is_empty	(s: &String) -> Bool
len	(s: &String) -> Int
chars	(s: &String) -> Vec(String)
concat	(s1: &String, s2: &String) -> String
repeat	(s: &String, n: Int) -> String
reverse	(s: &String) -> String
format	(format: &String, ...args) -> String
parse_int	(s: &String) -> Result(Int, Error)
parse_float	(s: &String) -> Result(Float, Error)

Functions

split

split: (s: &String, sep: &String) -> Vec(String)

Splits s by sep and returns a list of substrings.

• s —— the string to be split
• sep —— the separator; when empty, splits character by character

Returns: List(String). When the separator is not found, a single-element list is returned.

use std.assert
use std.list
use std.string

main: () -> Void = {
    parts = string.split("a,b,c", ",")
    assert(list.len(parts) == 3)
    assert(list.get(parts, 0) == "a")

    // Empty separator → character-by-character
    cs = string.split("abc", "")
    assert(list.len(cs) == 3)
}

trim

trim: (s: &String) -> String

Removes leading and trailing Unicode whitespace characters.

Returns: a new string with the leading and trailing whitespace removed (s is not modified).

use std.assert
use std.string

main: () -> Void = {
    assert(string.trim("  hi  ") == "hi")
}

upper

upper: (s: &String) -> String

Converts to uppercase (Unicode-aware).

use std.assert
use std.string

main: () -> Void = {
    assert(string.upper("abc") == "ABC")
}

lower

lower: (s: &String) -> String

Converts to lowercase (Unicode-aware).

use std.assert
use std.string

main: () -> Void = {
    assert(string.lower("ABC") == "abc")
}

replace

replace: (s: &String, old: &String, new: &String) -> String

Replaces all occurrences of old in s with new.

• old —— when empty, s is returned as-is (no insertion performed)

use std.assert
use std.string

main: () -> Void = {
    assert(string.replace("a-b-c", "-", "+") == "a+b+c")
    assert(string.replace("abc", "", "x") == "abc")
}

contains

contains: (s: &String, sub: &String) -> Bool

Whether sub appears in s. Always true for an empty string.

use std.assert
use std.string

main: () -> Void = {
    assert(string.contains("hello", "ell"))
    assert(!string.contains("hello", "xyz"))
}

starts_with

starts_with: (s: &String, prefix: &String) -> Bool

Whether s starts with prefix. Always true for an empty prefix.

use std.assert
use std.string

main: () -> Void = {
    assert(string.starts_with("hello", "he"))
}

ends_with

ends_with: (s: &String, suffix: &String) -> Bool

Whether s ends with suffix. Always true for an empty suffix.

use std.assert
use std.string

main: () -> Void = {
    assert(string.ends_with("hello", "lo"))
}

index_of

index_of: (s: &String, sub: &String) -> Int

The byte index of the first occurrence of sub.

Returns: the index when found; -1 when not found.

The return value is a byte offset. When the string contains multi-byte characters, you can convert with chars first to locate character indices.

use std.assert
use std.string

main: () -> Void = {
    assert(string.index_of("hello", "ll") == 2)
    assert(string.index_of("hello", "xyz") == -1)
}

substring

substring: (s: &String, start: Int, end: Int) -> String

Extracts the [start, end) range by character index.

• start —— starting character index; defaults to 0
• end —— ending character index (exclusive); defaults to the end of the string

Returns: the extracted result. Out-of-range bounds are clamped to the valid range and do not produce an error; when start > end it is clamped to an empty string.

use std.assert
use std.string

main: () -> Void = {
    assert(string.substring("hello", 1, 4) == "ell")
    assert(string.substring("hello", 1, 99) == "ello")   // upper bound clamped
}

is_empty

is_empty: (s: &String) -> Bool

Whether s is an empty string.

use std.assert
use std.string

main: () -> Void = {
    assert(string.is_empty(""))
    assert(!string.is_empty("x"))
}

len

len: (s: &String) -> Int

Returns the UTF-8 byte length, not the number of characters.

use std.assert
use std.string

main: () -> Void = {
    assert(string.len("hello") == 5)
    assert(string.len("中") == 3)   // byte length
}

chars

chars: (s: &String) -> Vec(String)

Splits into a list of single-character strings (by Unicode scalar values).

use std.assert
use std.list
use std.string

main: () -> Void = {
    cs = string.chars("ab")
    assert(list.len(cs) == 2)
    assert(cs[0] == "a")
}

concat

concat: (s1: &String, s2: &String) -> String

Concatenates two strings. The + operator can also be used directly.

use std.assert
use std.string

main: () -> Void = {
    assert(string.concat("a", "b") == "ab")
}

repeat

repeat: (s: &String, n: Int) -> String

Repeats s n times.

• n —— the number of repetitions; when n <= 0 an empty string is returned

use std.assert
use std.string

main: () -> Void = {
    assert(string.repeat("ab", 3) == "ababab")
    assert(string.repeat("ab", 0) == "")
}

reverse

reverse: (s: &String) -> String

Reverses the string by character.

use std.assert
use std.string

main: () -> Void = {
    assert(string.reverse("abc") == "cba")
}

format

format: (format: &String, ...args) -> String

Formats using {index} placeholders, with optional width/alignment specifiers.

Placeholder syntax:

Form	Meaning
{0}	the 0th argument (arguments after format are numbered from 0)
{0:03}	width 3
{0:>3}	width 3, right-aligned (default)
{0:<3}	width 3, left-aligned
{0:^3}	width 3, centered

Literal curly braces are written by doubling: two left braces produce one literal left brace, and the same applies to right braces.

Return value: the formatted string. Arguments are first converted to strings (same as convert.to_string); an out-of-range index yields an empty string, and an illegal width is treated as 0.

use std.assert
use std.string

main: () -> Void = {
    assert(string.format("{0}-{1}", "a", "b") == "a-b")
    assert(string.format("[{0:>5}]", "ab") == "[   ab]")
    assert(string.format("[{0:<5}]", "ab") == "[ab   ]")
}

parse_int

parse_int: (s: &String) -> Result(Int, Error)

Parses a decimal integer (leading and trailing whitespace are removed automatically).

Returns: Result.ok(Int) on success; Result.err(Error) on failure, with code E6010. No error is thrown.

use std.assert
use std.result
use std.string

main: () -> Void = {
    assert(result.is_ok(string.parse_int("42")))
    assert(result.is_err(string.parse_int("abc")))
}

parse_float

parse_float: (s: &String) -> Result(Float, Error)

Parses a float (leading and trailing whitespace are removed automatically).

Returns: Result.ok(Float) on success; Result.err(Error) on failure, with code E6011.

use std.assert
use std.result
use std.string

main: () -> Void = {
    assert(result.is_ok(string.parse_float("3.14")))
    assert(result.is_err(string.parse_float("xxx")))
}

Related

• std.convert —— convert numbers to strings
• std.result —— unpack results from parse_*