Skip to content

string

Substrings, characters, padding, capitalisation, line splitting, and counting, as methods on strings.

import "std/string";

The import brings the methods in; they are defined in an impl string block (see methods) and sit on top of the built-in string methods and the indexing and slicing operators. The built-in methods (len, split, trim, uppercase, replace, find, and the rest) need no import and are listed in built-in functions.

Indices and lengths count characters, so a four-letter word ending in an accented vowel has a length of 4 and its last index reads the accented vowel whole. A character is a Unicode scalar value, whatever it takes to store.

Slicing raises slice_out_of_bounds when a bound runs past the string. The start and the end may both sit on the end of the string, which yields an empty string; a method that asks for a character there, such as char_at, raises instead.

The module is pure candela, so it compiles into a .cdlb artifact and runs under candela-vm with no dynamic library.

substring

s.substring(start, count)
  • start: the 0-based index to start at.
  • count: how many characters to take.
  • Returns: the substring spanning count characters from start.
  • Raises: slice_out_of_bounds when start + count runs past the end.
import "std/string";

fn main() {
    print("hello world".substring(6, 5));
}

char_at

s.char_at(i)
  • i: the 0-based index.
  • Returns: the character at i, as a one-character string.
  • Raises: slice_out_of_bounds when i reaches the length, or when s is empty.

is_empty

s.is_empty()
  • Returns: a bool, true when s has no characters.

capitalize

s.capitalize()
  • Returns: s with its first character upper-cased and the rest left as it is. An empty string returns unchanged.

chars

s.chars()
  • Returns: a list of the characters of s, each as a one-character string. An empty string returns an empty list.
import "std/string";

fn main() {
    for c in "abc".chars() {
        print(c);
    }
}

chars is split("") under a name that says what it does.

lines

s.lines()
  • Returns: a list of the lines of s, split on newline boundaries. A trailing newline produces a final empty string, and a carriage return stays on the end of the line it belongs to.

pad_left

s.pad_left(width, fill)
  • width: the minimum width, as an int.
  • fill: a one-character string.
  • Returns: s prefixed with fill until it is at least width wide. A string already that wide returns unchanged.
import "std/string";

fn main() {
    print("7".pad_left(3, "0"));
}

A fill longer than one character can overshoot width, because the loop stops at the first length that reaches it.

pad_right

s.pad_right(width, fill)
  • width: the minimum width, as an int.
  • fill: a one-character string.
  • Returns: s followed by fill until it is at least width wide. A string already that wide returns unchanged.

count

s.count(needle)
  • needle: the string to look for.
  • Returns: the number of non-overlapping occurrences of needle in s, as an int. An empty needle returns 0.

Occurrences are counted without overlap, so "aaaa".count("aa") is 2.