# Str

{/* Generated from types/std.Rtypes by `just docs-std`. Do not edit this file. */}

Functions over single strings. Patterns and separators are matched literally, never as regular
expressions.

| Function | Summary |
| --- | --- |
| [`Str.is_empty`](#stris_empty) | Whether the string is `""`. |
| [`Str.concat`](#strconcat) | `first` followed by `second`. |
| [`Str.join_with`](#strjoin_with) | Joins a list of strings with `separator` between them. |
| [`Str.split_on`](#strsplit_on) | Splits at every occurrence of `separator`. |
| [`Str.repeat`](#strrepeat) | `count` copies of the string. |
| [`Str.starts_with`](#strstarts_with) | Whether the string begins with `prefix`. |
| [`Str.ends_with`](#strends_with) | Whether the string ends with `suffix`. |
| [`Str.contains`](#strcontains) | Whether `part` occurs in the string, matched literally. |
| [`Str.trim`](#strtrim) | Removes leading and trailing whitespace. |
| [`Str.trim_start`](#strtrim_start) | Removes leading whitespace. |
| [`Str.trim_end`](#strtrim_end) | Removes trailing whitespace. |
| [`Str.drop_prefix`](#strdrop_prefix) | Removes `prefix` if the string begins with it. |
| [`Str.drop_suffix`](#strdrop_suffix) | Removes `suffix` if the string ends with it. |
| [`Str.with_prefix`](#strwith_prefix) | Puts `prefix` in front of the string. |
| [`Str.replace_each`](#strreplace_each) | Replaces every occurrence of `pattern`, matched literally. |
| [`Str.replace_first`](#strreplace_first) | Replaces the first occurrence of `pattern`. |
| [`Str.replace_last`](#strreplace_last) | Replaces the last occurrence of `pattern`. |
| [`Str.split_first`](#strsplit_first) | Splits at the first `separator` into `before` and `after`, or `:Err(:NotFound)`. |
| [`Str.split_last`](#strsplit_last) | Splits at the last `separator`. |
| [`Str.count_utf8_bytes`](#strcount_utf8_bytes) | The number of bytes in the string's UTF-8 encoding. |
| [`Str.to_utf8`](#strto_utf8) | The bytes of the string's UTF-8 encoding. |
| [`Str.from_utf8`](#strfrom_utf8) | The string a list of bytes encodes, or `:Err(:BadUtf8)`. |
| [`Str.from_utf8_lossy`](#strfrom_utf8_lossy) | Decodes UTF-8 bytes, replacing each invalid sequence with U+FFFD. |
| [`Str.to_integer`](#strto_integer) | Parses a whole number that fits an `integer`, or `:Err(:InvalidNumStr)`. |
| [`Str.to_double`](#strto_double) | Parses a decimal number, or `:Err(:InvalidNumStr)`; `NA` and `NaN` are not numbers. |
| [`Str.with_ascii_lowercased`](#strwith_ascii_lowercased) | Lowercases the ASCII letters and leaves every other character alone. |
| [`Str.with_ascii_uppercased`](#strwith_ascii_uppercased) | Uppercases the ASCII letters. |
| [`Str.caseless_ascii_equals`](#strcaseless_ascii_equals) | Whether two strings are equal when ASCII case is ignored. |
| [`Str.walk_utf8`](#strwalk_utf8) | Folds the string's UTF-8 bytes: `f(state, byte)` gives the next state. |
| [`Str.walk_utf8_with_index`](#strwalk_utf8_with_index) | Folds the string's UTF-8 bytes, passing `f` each byte's 1-based position too. |
| [`Str.to_utf16`](#strto_utf16) | The string's UTF-16 code units, each an integer from 0 to 65535. |
| [`Str.from_utf16`](#strfrom_utf16) | Decodes UTF-16 code units, or `:Err(:BadUtf16)` for an unpaired surrogate or a zero unit, which an R string cannot hold. |
| [`Str.from_utf16_lossy`](#strfrom_utf16_lossy) | Decodes UTF-16 code units, replacing each unpaired surrogate and each zero unit with U+FFFD. |
| [`Str.to_utf32`](#strto_utf32) | The string's Unicode code points, one per character. |
| [`Str.from_utf32`](#strfrom_utf32) | Builds a string from Unicode code points, or `:Err(:BadUtf32)` for a number that is not one (a surrogate, a negative number, or one above 1114111) and for zero. |
| [`Str.from_utf32_lossy`](#strfrom_utf32_lossy) | Builds a string from Unicode code points, replacing each number that is not one with U+FFFD. |

## `Str.is_empty`

### Inline

```r
Str.is_empty <- function(string: character) -> logical
```

### Comments

```r
#: fn(string: character) -> logical
Str.is_empty <- function(string)
```

Whether the string is `""`.

```r
Str.is_empty("")
#> TRUE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L829)

## `Str.concat`

### Inline

```r
Str.concat <- function(first: character, second: character) -> character
```

### Comments

```r
#: fn(first: character, second: character) -> character
Str.concat <- function(first, second)
```

`first` followed by `second`.

```r
Str.concat("snake", "_case")
#> "snake_case"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L837)

## `Str.join_with`

### Inline

```r
Str.join_with <- function(strings: list[character], separator: character) -> character
```

### Comments

```r
#: fn(strings: list[character], separator: character) -> character
Str.join_with <- function(strings, separator)
```

Joins a list of strings with `separator` between them.

```r
Str.join_with(list("a", "b", "c"), ", ")
#> "a, b, c"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L845)

## `Str.split_on`

### Inline

```r
Str.split_on <- function(string: character, separator: character) -> list[character]
```

### Comments

```r
#: fn(string: character, separator: character) -> list[character]
Str.split_on <- function(string, separator)
```

Splits at every occurrence of `separator`.

```r
Str.split_on("a,b,,c", ",")
#> list("a", "b", "", "c")
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L853)

## `Str.repeat`

### Inline

```r
Str.repeat <- function(string: character, count: integer) -> character
```

### Comments

```r
#: fn(string: character, count: integer) -> character
Str.repeat <- function(string, count)
```

`count` copies of the string.

```r
Str.repeat("ab", 3L)
#> "ababab"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L861)

## `Str.starts_with`

### Inline

```r
Str.starts_with <- function(string: character, prefix: character) -> logical
```

### Comments

```r
#: fn(string: character, prefix: character) -> logical
Str.starts_with <- function(string, prefix)
```

Whether the string begins with `prefix`.

```r
Str.starts_with("report.csv", "report")
#> TRUE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L869)

## `Str.ends_with`

### Inline

```r
Str.ends_with <- function(string: character, suffix: character) -> logical
```

### Comments

```r
#: fn(string: character, suffix: character) -> logical
Str.ends_with <- function(string, suffix)
```

Whether the string ends with `suffix`.

```r
Str.ends_with("report.csv", ".R")
#> FALSE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L877)

## `Str.contains`

### Inline

```r
Str.contains <- function(string: character, part: character) -> logical
```

### Comments

```r
#: fn(string: character, part: character) -> logical
Str.contains <- function(string, part)
```

Whether `part` occurs in the string, matched literally.

```r
Str.contains("a.b", ".")
#> TRUE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L885)

## `Str.trim`

### Inline

```r
Str.trim <- function(string: character) -> character
```

### Comments

```r
#: fn(string: character) -> character
Str.trim <- function(string)
```

Removes leading and trailing whitespace.

```r
Str.trim("  hi  ")
#> "hi"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L893)

## `Str.trim_start`

### Inline

```r
Str.trim_start <- function(string: character) -> character
```

### Comments

```r
#: fn(string: character) -> character
Str.trim_start <- function(string)
```

Removes leading whitespace.

```r
Str.trim_start("  hi  ")
#> "hi  "
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L901)

## `Str.trim_end`

### Inline

```r
Str.trim_end <- function(string: character) -> character
```

### Comments

```r
#: fn(string: character) -> character
Str.trim_end <- function(string)
```

Removes trailing whitespace.

```r
Str.trim_end("  hi  ")
#> "  hi"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L909)

## `Str.drop_prefix`

### Inline

```r
Str.drop_prefix <- function(string: character, prefix: character) -> character
```

### Comments

```r
#: fn(string: character, prefix: character) -> character
Str.drop_prefix <- function(string, prefix)
```

Removes `prefix` if the string begins with it.

```r
Str.drop_prefix("v1.2", "v")
#> "1.2"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L917)

## `Str.drop_suffix`

### Inline

```r
Str.drop_suffix <- function(string: character, suffix: character) -> character
```

### Comments

```r
#: fn(string: character, suffix: character) -> character
Str.drop_suffix <- function(string, suffix)
```

Removes `suffix` if the string ends with it.

```r
Str.drop_suffix("data.csv", ".csv")
#> "data"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L925)

## `Str.with_prefix`

### Inline

```r
Str.with_prefix <- function(string: character, prefix: character) -> character
```

### Comments

```r
#: fn(string: character, prefix: character) -> character
Str.with_prefix <- function(string, prefix)
```

Puts `prefix` in front of the string.

```r
Str.with_prefix("world", "hello ")
#> "hello world"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L933)

## `Str.replace_each`

### Inline

```r
Str.replace_each <- function(string: character, pattern: character, replacement: character) -> character
```

### Comments

```r
#: fn(string: character, pattern: character, replacement: character) -> character
Str.replace_each <- function(string, pattern, replacement)
```

Replaces every occurrence of `pattern`, matched literally.

```r
Str.replace_each("a.b.c", ".", "-")
#> "a-b-c"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L941)

## `Str.replace_first`

### Inline

```r
Str.replace_first <- function(string: character, pattern: character, replacement: character) -> character
```

### Comments

```r
#: fn(string: character, pattern: character, replacement: character) -> character
Str.replace_first <- function(string, pattern, replacement)
```

Replaces the first occurrence of `pattern`.

```r
Str.replace_first("a.b.c", ".", "-")
#> "a-b.c"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L949)

## `Str.replace_last`

### Inline

```r
Str.replace_last <- function(string: character, pattern: character, replacement: character) -> character
```

### Comments

```r
#: fn(string: character, pattern: character, replacement: character) -> character
Str.replace_last <- function(string, pattern, replacement)
```

Replaces the last occurrence of `pattern`.

```r
Str.replace_last("a.b.c", ".", "-")
#> "a.b-c"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L957)

## `Str.split_first`

### Inline

```r
Str.split_first <- function(string: character, separator: character) -> Result<Record{before: character, after: character}, :NotFound>
```

### Comments

```r
#: fn(string: character, separator: character) -> Result<Record{before: character, after: character}, :NotFound>
Str.split_first <- function(string, separator)
```

Splits at the first `separator` into `before` and `after`, or `:Err(:NotFound)`.

```r
Str.split_first("key=value=more", "=")
#> :Ok((after = "value=more", before = "key"))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L965)

## `Str.split_last`

### Inline

```r
Str.split_last <- function(string: character, separator: character) -> Result<Record{before: character, after: character}, :NotFound>
```

### Comments

```r
#: fn(string: character, separator: character) -> Result<Record{before: character, after: character}, :NotFound>
Str.split_last <- function(string, separator)
```

Splits at the last `separator`.

```r
Str.split_last("key=value=more", "=")
#> :Ok((after = "more", before = "key=value"))
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L973)

## `Str.count_utf8_bytes`

### Inline

```r
Str.count_utf8_bytes <- function(string: character) -> integer
```

### Comments

```r
#: fn(string: character) -> integer
Str.count_utf8_bytes <- function(string)
```

The number of bytes in the string's UTF-8 encoding.

```r
Str.count_utf8_bytes("hé")
#> 3L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L981)

## `Str.to_utf8`

### Inline

```r
Str.to_utf8 <- function(string: character) -> list[integer]
```

### Comments

```r
#: fn(string: character) -> list[integer]
Str.to_utf8 <- function(string)
```

The bytes of the string's UTF-8 encoding.

```r
Str.to_utf8("hé")
#> list(104L, 195L, 169L)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L989)

## `Str.from_utf8`

### Inline

```r
Str.from_utf8 <- function(bytes: list[integer]) -> Result<character, :BadUtf8>
```

### Comments

```r
#: fn(bytes: list[integer]) -> Result<character, :BadUtf8>
Str.from_utf8 <- function(bytes)
```

The string a list of bytes encodes, or `:Err(:BadUtf8)`.

```r
Str.from_utf8(list(104L, 105L))
#> :Ok("hi")
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L997)

## `Str.from_utf8_lossy`

### Inline

```r
Str.from_utf8_lossy <- function(bytes: list[integer]) -> character
```

### Comments

```r
#: fn(bytes: list[integer]) -> character
Str.from_utf8_lossy <- function(bytes)
```

Decodes UTF-8 bytes, replacing each invalid sequence with U+FFFD.

```r
Str.from_utf8_lossy(list(104L, 255L, 105L))
#> "h�i"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1005)

## `Str.to_integer`

### Inline

```r
Str.to_integer <- function(string: character) -> Result<integer, :InvalidNumStr>
```

### Comments

```r
#: fn(string: character) -> Result<integer, :InvalidNumStr>
Str.to_integer <- function(string)
```

Parses a whole number that fits an `integer`, or `:Err(:InvalidNumStr)`.

```r
Str.to_integer("4.2")
#> :Err(:InvalidNumStr)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1013)

## `Str.to_double`

### Inline

```r
Str.to_double <- function(string: character) -> Result<double, :InvalidNumStr>
```

### Comments

```r
#: fn(string: character) -> Result<double, :InvalidNumStr>
Str.to_double <- function(string)
```

Parses a decimal number, or `:Err(:InvalidNumStr)`; `NA` and `NaN` are not numbers.

```r
Str.to_double("4.5e1")
#> :Ok(45)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1021)

## `Str.with_ascii_lowercased`

### Inline

```r
Str.with_ascii_lowercased <- function(string: character) -> character
```

### Comments

```r
#: fn(string: character) -> character
Str.with_ascii_lowercased <- function(string)
```

Lowercases the ASCII letters and leaves every other character alone.

```r
Str.with_ascii_lowercased("Straße ABC")
#> "straße abc"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1029)

## `Str.with_ascii_uppercased`

### Inline

```r
Str.with_ascii_uppercased <- function(string: character) -> character
```

### Comments

```r
#: fn(string: character) -> character
Str.with_ascii_uppercased <- function(string)
```

Uppercases the ASCII letters.

```r
Str.with_ascii_uppercased("straße abc")
#> "STRAßE ABC"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1037)

## `Str.caseless_ascii_equals`

### Inline

```r
Str.caseless_ascii_equals <- function(first: character, second: character) -> logical
```

### Comments

```r
#: fn(first: character, second: character) -> logical
Str.caseless_ascii_equals <- function(first, second)
```

Whether two strings are equal when ASCII case is ignored.

```r
Str.caseless_ascii_equals("Content-Type", "content-type")
#> TRUE
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1045)

## `Str.walk_utf8`

### Inline

```r
Str.walk_utf8 <- function<S>(string: character, state: S, f: fn(S, integer) -> S) -> S
```

### Comments

```r
#: <S> fn(string: character, state: S, f: fn(S, integer) -> S) -> S
Str.walk_utf8 <- function(string, state, f)
```

Folds the string's UTF-8 bytes: `f(state, byte)` gives the next state.

```r
Str.walk_utf8("abc", 0L, function(total, byte) total + byte)
#> 294L
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1053)

## `Str.walk_utf8_with_index`

### Inline

```r
Str.walk_utf8_with_index <- function<S>(string: character, state: S, f: fn(S, integer, integer) -> S) -> S
```

### Comments

```r
#: <S> fn(string: character, state: S, f: fn(S, integer, integer) -> S) -> S
Str.walk_utf8_with_index <- function(string, state, f)
```

Folds the string's UTF-8 bytes, passing `f` each byte's 1-based position too.

```r
Str.walk_utf8_with_index("ab", list(), function(seen, byte, i) List.append(seen, byte * i))
#> list(97L, 196L)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1061)

## `Str.to_utf16`

### Inline

```r
Str.to_utf16 <- function(string: character) -> list[integer]
```

### Comments

```r
#: fn(string: character) -> list[integer]
Str.to_utf16 <- function(string)
```

The string's UTF-16 code units, each an integer from 0 to 65535. A character outside the Basic
Multilingual Plane takes two units, a surrogate pair.

```r
Str.to_utf16("h\U0001F600")
#> list(104L, 55357L, 56832L)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1070)

## `Str.from_utf16`

### Inline

```r
Str.from_utf16 <- function(units: list[integer]) -> Result<character, :BadUtf16>
```

### Comments

```r
#: fn(units: list[integer]) -> Result<character, :BadUtf16>
Str.from_utf16 <- function(units)
```

Decodes UTF-16 code units, or `:Err(:BadUtf16)` for an unpaired surrogate or a zero unit, which
an R string cannot hold. A number outside 0 to 65535 is an error.

```r
Str.from_utf16(list(104L, 55357L))
#> :Err(:BadUtf16)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1079)

## `Str.from_utf16_lossy`

### Inline

```r
Str.from_utf16_lossy <- function(units: list[integer]) -> character
```

### Comments

```r
#: fn(units: list[integer]) -> character
Str.from_utf16_lossy <- function(units)
```

Decodes UTF-16 code units, replacing each unpaired surrogate and each zero unit with U+FFFD.

```r
Str.from_utf16_lossy(list(104L, 105L))
#> "hi"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1087)

## `Str.to_utf32`

### Inline

```r
Str.to_utf32 <- function(string: character) -> list[integer]
```

### Comments

```r
#: fn(string: character) -> list[integer]
Str.to_utf32 <- function(string)
```

The string's Unicode code points, one per character.

```r
Str.to_utf32("h\u00e9")
#> list(104L, 233L)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1095)

## `Str.from_utf32`

### Inline

```r
Str.from_utf32 <- function(code_points: list[integer]) -> Result<character, :BadUtf32>
```

### Comments

```r
#: fn(code_points: list[integer]) -> Result<character, :BadUtf32>
Str.from_utf32 <- function(code_points)
```

Builds a string from Unicode code points, or `:Err(:BadUtf32)` for a number that is not one (a
surrogate, a negative number, or one above 1114111) and for zero.

```r
Str.from_utf32(list(55296L))
#> :Err(:BadUtf32)
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1104)

## `Str.from_utf32_lossy`

### Inline

```r
Str.from_utf32_lossy <- function(code_points: list[integer]) -> character
```

### Comments

```r
#: fn(code_points: list[integer]) -> character
Str.from_utf32_lossy <- function(code_points)
```

Builds a string from Unicode code points, replacing each number that is not one with U+FFFD.

```r
Str.from_utf32_lossy(list(82L, 121L))
#> "Ry"
```

[Source](https://github.com/felix-andreas/ry/blob/main/types/std.Rtypes#L1112)