string

Functions for working with immutable strings. Strings use "..." literal syntax with {expr} interpolation.

Summary

string.char_code

string.char_code(s: String) -> Option(Int)

Returns Some of the Unicode code point of the first character, or None for an empty string.

import string

fn main() {
  println(string.char_code("A")) -- Some(65)
  println(string.char_code("")) -- None
}

string.chars

string.chars(s: String) -> List(String)

Splits the string into a list of single-character strings.

import string

fn main() {
  println(string.chars("hi")) -- [h, i]
}

string.contains

string.contains(s: String, sub: String) -> Bool

Returns true if sub appears anywhere in s.

import string

fn main() {
  println(string.contains("hello world", "world")) -- true
}

string.ends_with

string.ends_with(s: String, suffix: String) -> Bool

Returns true if s ends with suffix.

import string

fn main() {
  println(string.ends_with("hello.silt", ".silt")) -- true
}

string.from

string.from(x: a) -> String where a: Display

Converts any value to its display string representation. This is the programmatic equivalent of string interpolation "{value}".

import string

fn main() {
  println(string.from(42)) -- 42
  println(string.from(2.0)) -- 2.0
  println(string.from(true)) -- true
  println(string.from([1, 2, 3])) -- [1, 2, 3]
}

string.from_char_code

string.from_char_code(code: Int) -> Option(String)

Returns Some of the single-character string of a Unicode code point, or None for a number that is none (a negative one, a surrogate, one above 0x10FFFF).

import string

fn main() {
  println(string.from_char_code(65)) -- Some(A)
  println(string.from_char_code(-1)) -- None
}

string.index_of

string.index_of(s: String, needle: String) -> Option(Int)

Returns Some(index) with the character index of the first occurrence of needle in s, or None if not found.

import string

fn main() {
  println(string.index_of("hello", "ll")) -- Some(2)
  println(string.index_of("hello", "z")) -- None
}

string.last_index_of

string.last_index_of(s: String, needle: String) -> Option(Int)

Returns Some(index) with the character index of the last occurrence of needle in s, or None if not found. Counterpart to string.index_of, using the same character-based indexing convention.

import string

fn main() {
  println(string.last_index_of("banana", "a")) -- Some(5)
  println(string.last_index_of("banana", "z")) -- None
}

string.is_alnum

string.is_alnum(s: String) -> Bool

Returns true if all characters are alphanumeric. Returns false for empty strings.

import string

fn main() {
  println(string.is_alnum("abc123")) -- true
  println(string.is_alnum("abc!")) -- false
  println(string.is_alnum("")) -- false
}

string.is_alpha

string.is_alpha(s: String) -> Bool

Returns true if all characters are alphabetic. Returns false for empty strings.

import string

fn main() {
  println(string.is_alpha("hello")) -- true
  println(string.is_alpha("abc123")) -- false
  println(string.is_alpha("")) -- false
}

string.is_digit

string.is_digit(s: String) -> Bool

Returns true if all characters are ASCII digits (0-9). Returns false for empty strings.

import string

fn main() {
  println(string.is_digit("123")) -- true
  println(string.is_digit("12a")) -- false
  println(string.is_digit("")) -- false
}

string.is_empty

string.is_empty(s: String) -> Bool

Returns true if the string has zero length.

import string

fn main() {
  println(string.is_empty("")) -- true
  println(string.is_empty("hi")) -- false
}

string.is_lower

string.is_lower(s: String) -> Bool

Returns true if all characters are lowercase. Returns false for empty strings.

import string

fn main() {
  println(string.is_lower("hello")) -- true
  println(string.is_lower("Hello")) -- false
  println(string.is_lower("")) -- false
}

string.is_upper

string.is_upper(s: String) -> Bool

Returns true if all characters are uppercase. Returns false for empty strings.

import string

fn main() {
  println(string.is_upper("HELLO")) -- true
  println(string.is_upper("Hello")) -- false
  println(string.is_upper("")) -- false
}

string.is_whitespace

string.is_whitespace(s: String) -> Bool

Returns true if all characters are whitespace. Returns false for empty strings.

import string

fn main() {
  println(string.is_whitespace("  \t")) -- true
  println(string.is_whitespace(" a ")) -- false
  println(string.is_whitespace("")) -- false
}

string.join

string.join(xs: List(String), sep: String) -> String

Joins a list of strings with a separator between each pair.

import string

fn main() {
  let joined = string.join(["a", "b", "c"], ", ")
  println(joined) -- a, b, c
}

string.byte_length

string.byte_length(s: String) -> Int

Returns the length of the string in bytes (UTF-8 encoding). See also string.length which counts characters.

import string

fn main() {
  println(string.byte_length("hello")) -- 5
  println(string.byte_length("café")) -- 5  (é is 2 bytes in UTF-8)
}

string.length

string.length(s: String) -> Int

Returns the number of characters in the string. Use string.byte_length if you need the size in bytes.

import string

fn main() {
  println(string.length("hello")) -- 5
  println(string.length("café")) -- 4  (4 characters, 5 bytes)
}

string.lines

string.lines(s: String) -> List(String)

Splits s on \n newline characters. A trailing newline does not produce an empty final element, so "a\nb\n" yields ["a", "b"]. A trailing \r on each line is stripped, which normalises \r\n line endings from Windows sources.

import string

fn main() {
  println(string.lines("a\nb\nc")) -- [a, b, c]
  println(string.lines("a\nb\n")) -- [a, b]
  println(string.lines("")) -- []
}

Input containing \r\n sequences (Windows line endings) has the trailing \r on each line stripped automatically.

string.pad_left

string.pad_left(s: String, width: Int, pad: String) -> String

Pads s on the left with the first character of pad until it reaches width. Returns s unchanged if already at or beyond width.

import string

fn main() {
  println(string.pad_left("42", 5, "0")) -- 00042
}

string.pad_right

string.pad_right(s: String, width: Int, pad: String) -> String

Pads s on the right with the first character of pad until it reaches width. Returns s unchanged if already at or beyond width.

import string

fn main() {
  println(string.pad_right("hi", 5, ".")) -- hi...
}

string.repeat

string.repeat(s: String, n: Int) -> String

Returns the string repeated n times. n must be non-negative.

import string

fn main() {
  println(string.repeat("ab", 3)) -- ababab
}

string.replace

string.replace(s: String, from: String, to: String) -> String

Replaces all occurrences of from with to.

import string

fn main() {
  println(string.replace("hello world", "world", "silt"))
  -- hello silt
}

string.slice

string.slice(s: String, start: Int, end: Int) -> String

Returns the substring from character index start (inclusive) to end (exclusive). Indices are clamped to the string length. Returns an empty string if start > end. Negative indices are a runtime error.

import string

fn main() {
  println(string.slice("hello", 1, 4)) -- ell
}

string.split

string.split(s: String, separator: String) -> List(String)

Splits the string on every occurrence of separator.

import string

fn main() {
  let parts = string.split("a,b,c", ",")
  println(parts) -- [a, b, c]
}

string.split_at

string.split_at(s: String, idx: Int) -> Option((String, String))

Splits s into Some((left, right)) at character index idx. idx == 0 yields ("", s) and idx == length(s) yields (s, ""). A negative index or one past the end of the string is None.

import string

fn main() {
  println(string.split_at("hello", 2)) -- Some((he, llo))
  println(string.split_at("hello", 0)) -- Some((, hello))
  println(string.split_at("hello", 5)) -- Some((hello, ))
  println(string.split_at("hello", 6)) -- None
}

string.starts_with

string.starts_with(s: String, prefix: String) -> Bool

Returns true if s starts with prefix.

import string

fn main() {
  println(string.starts_with("hello", "hel")) -- true
}

string.starts_with_at

string.starts_with_at(s: String, offset: Int, prefix: String) -> Bool

Returns true if prefix appears in s starting at character offset. The offset is a character index (matching string.index_of and string.slice). Out-of-range offsets (negative, or past the end of the string) return false rather than panicking.

import string

fn main() {
  println(string.starts_with_at("hello", 2, "ll")) -- true
  println(string.starts_with_at("hello", 2, "lx")) -- false
  println(string.starts_with_at("hello", -1, "h")) -- false
  println(string.starts_with_at("hello", 99, "")) -- false
}

string.to_lower

string.to_lower(s: String) -> String

Converts all characters to lowercase.

import string

fn main() {
  println(string.to_lower("HELLO")) -- hello
}

string.to_upper

string.to_upper(s: String) -> String

Converts all characters to uppercase.

import string

fn main() {
  println(string.to_upper("hello")) -- HELLO
}

string.trim

string.trim(s: String) -> String

Removes leading and trailing whitespace.

import string

fn main() {
  println(string.trim("  hello  ")) -- hello
}

string.trim_end

string.trim_end(s: String) -> String

Removes trailing whitespace only.

import string

fn main() {
  println(string.trim_end("hello   ")) -- hello
}

string.trim_start

string.trim_start(s: String) -> String

Removes leading whitespace only.

import string

fn main() {
  println(string.trim_start("   hello")) -- hello
}