String Library

Stof's standard string library ("String").

Common Value Functions

String.toString(val: str): str

Returns this string as it would be printed to the console.

String.or(val: str, ...): unknown

Returns the first non-empty (null or void) argument, just like the Standard Library "or" function.

name: "Bob Smith"

#[test("Bob Smith")]
fn test(): str {
    return self.name.or("unknown");
}

String Functions

String.len(val: str): int

Return the length of this string.

#[test(5)]
fn test(): int {
    return String.len("hello"); // "hello".len() works too of course
}

String.at(val: str, index: int): str

Get a character from this string at a specific index. The functions "at" and "len" together enable iteration with for loops as well.

#[test]
fn test() {
    let val = "hello";
    assertEq(val.at(1), "e");
    assertEq(val[3], "l");
    
    for (ch in val) pln(ch); // "hello" one char at a time
}

String.first(val: str): str

Return the first character in the string, or null if the string is empty.

#[test("h")]
fn test(): str {
    return "hello".first();
}

String.last(val: str): str

Return the last character in the string, or null if the string is empty.

#[test("o")]
fn test(): str {
    return "hello".last();
}

String.startsWith(val: str, substr: str): bool

Return true if the string starts with "substr".

#[test]
fn test() {
    let string = "hi there";
    assert(string.startsWith("hi"));
    assertNot(string.startsWith("yo"));
}

String.endsWith(val: str, substr: str): bool

Return true if the string ends with "substr".

#[test]
fn test() {
    let string = "hi there";
    assert(string.endsWith("ere"));
    assertNot(string.endsWith("yo"));
}

String.push(val: str, ...additional: unknown): void

Push additional arguments (turned into strings) to the end of "val".

#[test]
fn test() {
    let val = "hello";
    val.push(", ", "world", "!");
    assertEq(val, "hello, world!");
}

String.contains(val: str, substr: str): bool

Return true if "val" contains the substring.

#[test]
fn test() {
    assert("my name is blah".contains("name is"));
}

String.indexOf(val: str, substr: str): int

Return the index of the first character of "substr" found in "val". If not found, returns -1.

#[test]
fn test() {
    assertEq("hello dude".indexOf("dude"), 6);
    assertEq("blah".indexOf("dne"), -1);
}

String.replace(val: str, from: str, to: str): str

Replace all instances of a substring in this string, returning a new string.

#[test]
fn test() {
    let val = "this.is.a.good.day";
    assertEq(val.replace(".", " "), "this is a good day");
    assertEq(val, "this.is.a.good.day");
}

String.split(val: str, substr: str): vec

Split this string into a vector of strings, separated at every occurrence of "substr".

#[test]
fn test() {
    let val = "this.is.a.good.day";
    assertEq(val.split("."), ["this", "is", "a", "good", "day"]);
}

String.toUpper(val: str): str

Transforms this string to all uppercase letters, returning a new string.

#[test]
fn test() {
    assertEq("hello".toUpper(), "HELLO");
}

String.toLower(val: str): str

Transforms this string to all lowercase letters, returning a new string.

#[test]
fn test() {
    assertEq("HELLO".toLower(), "hello");
}

String.trim(val: str): str

Will trim the whitespace off of the start and end of this string (spaces, newlines, tabs), returning a new string.

#[test]
fn test() {
    assertEq("  trim  ".trim(), "trim");
}

String.trimStart(val: str): str

Will trim the whitespace off of the start of this string (spaces, newlines, tabs), returning a new string.

#[test]
fn test() {
    assertEq("  trim  ".trimStart(), "trim  ");
}

String.trimEnd(val: str): str

Will trim the whitespace off of the end of this string (spaces, newlines, tabs), returning a new string.

#[test]
fn test() {
    assertEq("  trim  ".trimEnd(), "  trim");
}

String.substring(val: str, start: int, end?: int): str

Returns a substring of "val" from a starting index up to (but not including) an optional ending index. If the ending index is omitted, the resulting substring will be from a starting index to the end of "val" (default end is the length of "val").

#[test]
fn test() {
    let val = "hello, world";
    assertEq(val.substring(2, 5), "llo");
    assertEq(val.substring(7), "world");
}