# String Library (Str)

### Example Usage

```rust
#[main]
fn main() {
    assert_eq("hello, world".split(", "), ['hello', 'world']);
}
```

## Str.at(val: str, index: int) -> str

Returns a character at the given index within the string, or the last character if the index is out of bounds.

```rust
const val = "hello";
assert_eq(val[1], "e");
```

## Str.contains(val: str, seq: str) -> bool

Return true if the sequence is found at least once anywhere in this string.

```rust
const val = "hello, world";
assert(val.contains(", w"));
```

## Str.ends\_with(val: str, seq: str) -> bool

Does this string end with the given string sequence?

```rust
const val = "hello";
assert(val.ends_with("llo"));
```

## Str.first(val: str) -> str

Return the first char (as a string) in this string.

```rust
const val = "hello";
assert_eq(val.first(), "h");
```

## Str.index\_of(val: str, seq: str) -> int

Find the first occurrance of the given sequence in this string, returning the index of the first char. If not found, returns -1.

```rust
const val = "hello, world";
assert_eq(val.index_of(", w"), 5);
```

## Str.last(val: str) -> str

Return the last char (as a string) in this string.

```rust
const val = "hello";
assert_eq(val.last(), "o");
```

## Str.len(val: str) -> int

Returns the length (number of characters) in this string.

```rust
assert_eq("hello".len(), 5);
```

## Str.lower(val: str) -> str

Return a new string with all characters converted to lowercase.

```rust
const val = "HELLO";
assert_eq(val.lower(), "hello");
```

## Str.push(val: str, other: str) -> void

Pushes another string to the back of this string, leaving the other string unmodified.

```rust
const val = "hello";
val.push(", world");
assert_eq(val, "hello, world");
```

## Str.replace(val: str, find: str, replace: str = "") -> str

Replace all occurrances of a find string with a replace string (default removes all occurrances). This will return a new string, without modifying the original.

```rust
const val = "hello john";
assert_eq(val.replace(" ", ", "), "hello, john");
```

## Str.split(val: str, sep: str = " ") -> list

Splits a string into a list at the given separator.

```rust
const val = "hello, world";
assert_eq(val.split(", "), ["hello", "world"]);
```

## Str.starts\_with(val: str, seq: str) -> bool

Does this string start with the given string sequence?

```rust
const val = "hello";
assert(val.starts_with("he"));
```

## Str.substring(val: str, start: int = 0, end: int = -1) -> str

Return a new string that is the substring of the given value from a start index up to, but not including an end index. Default start is the beginning of the string and the default end is the entire length of the string.

```rust
const val = "hello, world";
assert_eq(val.substring(), "hello, world");
assert_eq(val.substring(7), "world");
assert_eq(val.substring(3, 8), "lo, w");
```

## Str.trim(val: str) -> str

Return a new string with the whitespace (newlines, tabs, and space characters) removed from the front and back.

```rust
const val = "\n\thello\t\n";
assert_eq(val.trim(), "hello");
```

## Str.trim\_end(val: str) -> str

Return a new string with the whitespace (newlines, tabs, and space characters) removed from the back only.

```rust
const val = "\n\thello\t\n";
assert_eq(val.trim_end(), "\n\thello");
```

## Str.trim\_start(val: str) -> str

Return a new string with the whitespace (newlines, tabs, and space characters) removed from the front only.

```rust
const val = "\n\thello\t\n";
assert_eq(val.trim_start(), "hello\t\n");
```

## Str.upper(val: str) -> str

Return a new string with all characters converted to uppercase.

```rust
const val = "hello";
assert_eq(val.upper(), "HELLO");
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.stof.dev/libraries/type-libraries/string-library-str.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.