string¶

Substrings, characters, padding, capitalisation, line splitting, and counting, as methods on strings. The module is part of the prelude, so they need no import.

The methods 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, index_of, and the rest) 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.

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.

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.

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.