Builtin Type Module

Concatenates two strings together.

expect "ab".concat("cd") == "abcd"
expect "hello".concat("") == "hello"
expect "".concat("") == ""

Determines whether or not the first Str contains the second.

expect "foobarbaz".contains("bar")
expect !"apple".contains("orange")
expect "anything".contains("")

Return the Str with all whitespace removed from both the beginning as well as the end.

expect "   Hello      \n\n".trim() == "Hello"

Return the Str with all whitespace removed from the beginning.

expect "   Hello      \n\n".trim_start() == "Hello      \n\n"

Return the Str with all whitespace removed from the end.

expect "   Hello      \n\n".trim_end() == "   Hello"

Returns True if all the ASCII characters in both strings are the same, ignoring differences in capitalization. Non-ASCII characters must all be exactly the same, including capitalization. For example:

 expect "café".caseless_ascii_equals("CAFé")

 expect !"café".caseless_ascii_equals("CAFÉ")

The first call returns True because all the ASCII characters are the same when ignoring differences in capitalization, and the only non-ASCII character (é) is the same in both strings. The second call returns False because é and É are not ASCII characters, and they are different.

This function is useful for things like command-line flags and environment variable names where you know in advance that you're dealing with a string containing only ASCII characters. It has better performance than lowercasing operations which take Unicode into account.

That said, strings received from user input can always contain non-ASCII Unicode characters, and lowercasing Unicode works differently in different languages. For example, the string "I" lowercases to "i" in English and to "ı" (a dotless i) in Turkish. These rules can also change in each Unicode release, so we have separate unicode package for Unicode capitalization that can be upgraded independently from the language's builtins.

To convert a string's ASCII characters to uppercase or lowercase, you can use Str.with_ascii_uppercased or Str.with_ascii_lowercased.

Returns a version of the string with all ASCII characters lowercased. Non-ASCII characters are left unmodified. For example:

expect "CALFÉ".with_ascii_lowercased() == "calfÉ"

This function is useful for things like command-line flags and environment variable names where you know in advance that you're dealing with a string containing only ASCII characters. It has better performance than lowercasing operations which take Unicode into account.

That said, strings received from user input can always contain non-ASCII Unicode characters, and lowercasing Unicode works differently in different languages. For example, the string "I" lowercases to "i" in English and to "ı" (a dotless i) in Turkish. These rules can also change in each Unicode release, so we have separate unicode package for Unicode capitalization that can be upgraded independently from the language's builtins.

To do a case-insensitive comparison of the ASCII characters in a string, you can use Str.caseless_ascii_equals.

Returns a version of the string with all ASCII characters uppercased. Non-ASCII characters are left unmodified. For example:

 expect "café".with_ascii_uppercased() == "CAFé"

This function is useful for things like command-line flags and environment variable names where you know in advance that you're dealing with a string containing only ASCII characters. It has better performance than uppercasing operations which take Unicode into account.

That said, strings received from user input can always contain non-ASCII Unicode characters, and uppercasing Unicode works differently in different languages. For example, the string "i" uppercases to "I" in English and to "İ" (a dotted I) in Turkish. These rules can also change in each Unicode release, so we have a separate unicode package for Unicode capitalization that can be upgraded independently from the language's builtins.

To do a case-insensitive comparison of the ASCII characters in a string, you can use Str.caseless_ascii_equals.

Check if the given Str starts with a value.

expect "ABC".starts_with("A") == Bool.True
expect "ABC".starts_with("X") == Bool.False

Check if the given Str ends with a value.

expect "ABC".ends_with("C") == Bool.True
expect "ABC".ends_with("X") == Bool.False

Repeats a string the given number of times.

expect "z".repeat(3) == "zzz"
expect "na".repeat(8) == "nananananananana"

Returns "" when given "" for the string or 0 for the count.

expect "".repeat(10) == ""
expect "anything".repeat(0) == ""

Adds a prefix to the given Str.

expect "Awesome".with_prefix("Roc") == "RocAwesome"

Drops the given prefix Str from the start of a Str If the prefix is not found, returns the original string.

expect "bar".drop_prefix("foo") == "bar"
expect "foobar".drop_prefix("foo") == "bar"

Drops the given suffix Str from the end of a Str If the suffix is not found, returns the original string.

expect "bar".drop_suffix("foo") == "bar"
expect "barfoo".drop_suffix("foo") == "bar"

Gives the number of bytes in a Str value.

expect "Hello World".count_utf8_bytes() == 11

Returns a string of the specified capacity without any content.

This is like calling Str.reserve on an empty string. It's intended for building up a string incrementally, for example by calling Str.concat on it:

greeting = "Hello and welcome to Roc"
subject = "Awesome Programmer"

# Evaluates to "Hello and welcome to Roc, Awesome Programmer!"
# Note that string interpolation with "${greeting}, ${subject}!" would be preferred here,
# this is just a simple example to demonstrate `Str.with_capacity`.
hello_world =
    Str.with_capacity(45)
        .concat(greeting)
        .concat(", ")
        .concat(subject)
        .concat("!")

When the final size is known up front, Str.with_capacity guarantees that subsequent calls to Str.concat will not need to reallocate. Whether this is faster than starting from "" depends on the system allocator: many allocators can extend an existing allocation in place, making the difference small or negligible. The benefit is most pronounced when reallocation would otherwise force a full copy of the string.

If you don't know the exact capacity, passing a value larger than necessary still avoids reallocation, at the cost of using more memory than is needed.

For more details, see Str.reserve.

Increase a string's capacity by at least the given number of additional bytes.

When you plan to append more bytes onto a string, Str.reserve can help avoid intermediate reallocations during a chain of Str.concat calls. Consider the following example, which does not use Str.reserve:

greeting = "Hello and welcome to Roc"
subject = "Awesome Programmer"

# Evaluates to "Hello and welcome to Roc, Awesome Programmer!"
hello_world =
    greeting
        .concat(", ")
        .concat(subject)
        .concat("!")

In this example: 1. We start with greeting, which has both a length and capacity of 24 bytes. 2. .concat(", ") sees there isn't enough capacity for 2 more bytes, so it allocates a new 26-byte buffer, copies the existing 24 bytes into it, and writes ", " at the end. The old allocation is deallocated. 3. .concat(subject) repeats the process: allocate a 44-byte buffer, copy the 26 existing bytes, write "Awesome Programmer". 4. .concat("!") repeats once more: allocate 45 bytes, copy 44, write "!".

With Str.reserve, the chain only needs one allocation up front:

hello_world =
    greeting
        .reserve(21)
        .concat(", ")
        .concat(subject)
        .concat("!")

Here, .reserve(21) ensures there is room for an additional 21 bytes (", " + "Awesome Programmer" + "!"), allocating a 45-byte buffer and copying greeting into it. The subsequent Str.concat calls all fit in that capacity and do not need to reallocate.

Whether this is actually faster depends on the system allocator: many allocators can extend an existing allocation in place, in which case the per-concat reallocation is cheap and Str.reserve makes little observable difference. The benefit is most pronounced when reallocation would otherwise force a full copy of the string.

Str.reserve is not free — when more capacity is needed, it always performs a heap allocation. Only use it when you actually expect to make use of the extra capacity.

When you don't know exactly how many bytes you'll need, choosing a value somewhat higher than necessary is usually safe; a value that's too low may force later reallocation, while a value much higher than necessary just wastes memory.

If you plan to use Str.reserve on an empty string, use Str.with_capacity instead.

Shrink the memory footprint of a str such that its capacity and length are equal. Note: This will also convert seamless slices to regular lists.

Returns a List of the string's U8 UTF-8 code units. (To split the string into a List of smaller Str values instead of U8 values, see Str.split_on.)

expect "Roc".to_utf8() == [82, 111, 99]
expect "鹏".to_utf8() == [233, 185, 143]
expect "சி".to_utf8() == [224, 174, 154, 224, 174, 191]
expect "🐦".to_utf8() == [240, 159, 144, 166]

Converts a List of U8 UTF-8 code units to a string. Any grouping of invalid byte sequences are replaced with a single unicode replacement character '�'.

An invalid byte sequence is defined as - a 2-byte-sequence starting byte, followed by less than 1 continuation byte - a 3-byte-sequence starting byte, followed by less than 2 continuation bytes - a 4-byte-sequence starting byte, followed by less than 3 continuation bytes - an invalid codepoint from the surrogate pair block - an invalid codepoint greater than 0x110000 encoded as a 4-byte sequence - any valid codepoint encoded as an incorrect sequence, for instance a codepoint that should be a 2-byte sequence encoded as a 3- or 4-byte sequence

expect Str.from_utf8_lossy([82, 111, 99, 240, 159, 144, 166]) == "Roc🐦"
expect Str.from_utf8_lossy([82, 255, 99]) == "R�c"
expect Str.from_utf8_lossy([82, 0xED, 0xA0, 0xBD, 99]) == "R�c"

Converts a List of U8 UTF-8 code units to a string.

Returns Err if the given bytes are invalid UTF-8, and returns Ok("") when given [].

expect Str.from_utf8([82, 111, 99]) == Ok("Roc")
expect Str.from_utf8([233, 185, 143]) == Ok("鹏")
expect Str.from_utf8([224, 174, 154, 224, 174, 191]) == Ok("சி")
expect Str.from_utf8([240, 159, 144, 166]) == Ok("🐦")
expect Str.from_utf8([]) == Ok("")
expect Str.from_utf8([255]).is_err()

Split a string around a separator.

Passing "" for the separator is not useful; it returns the original string wrapped in a List.

expect "1,2,3".split_on(",") == ["1","2","3"]
expect "1,2,3".split_on("") == ["1,2,3"]

Combines a List of strings into a single string, with a separator string in between each.

expect Str.join_with(["one", "two", "three"], ", ") == "one, two, three"
expect Str.join_with(["1", "2", "3", "4"], ".") == "1.2.3.4"

Returns True if the two strings are exactly the same.

Returns a human-readable representation of a value, useful for debugging.

Encode a string using a format that provides encode_str

Decode a string using a format that provides decode_str

Returns the length of the list, which is equal to the number of elements it contains.

One List can store up to Num.max_i64 (TODO update for current max function) elements on 64-bit targets and Num.max_i32 (TODO update for current max function) on 32-bit targets like wasm. This means the #U64 this function returns can always be safely converted to #I64 or #I32, depending on the target.

Check if the list is empty.

[1, 2, 3].is_empty()

[].is_empty()

Put two lists together.

[1, 2, 3].concat([4, 5])

[0, 1, 2].concat([3, 4])

Create a list with space for at least capacity elements

Sort a list using a custom comparison function. The comparator receives two elements and returns LT, EQ, or GT to indicate their relative order.

expect [3, 1, 2].sort_with(|a, b| if a < b LT else if a > b GT else EQ) == [1, 2, 3]

# Sort in descending order by swapping the LT and GT
expect [3, 1, 2].sort_with(|a, b| if a > b LT else if a < b GT else EQ) == [3, 2, 1]

Returns True if the two lists have the same length and their elements are pairwise equal.

Add a single element to the end of a list.

[1, 2, 3].append(4)

[0, 1, 2].append(3)

Returns the first element in the list, or ListWasEmpty if it was empty.

expect [1, 2, 3].first() == Ok(1)
expect [].first() == Err(ListWasEmpty)

Returns an element from a list at the given index.

Returns Err OutOfBounds if the given index exceeds the List's length

expect [100, 200, 300].get(1) == Ok(200)
expect [100, 200, 300].get(5) == Err(OutOfBounds)

Returns the reversed list.

expect [1, 2, 3].rev() == [3, 2, 1]
expect [].rev() == []

Convert each element in the list to something new, by calling a conversion function on each of them. Then return a new list of the converted values.

expect [1, 2, 3].map(|num| num + 1) == [2, 3, 4]

expect ["", "a", "bc"].map(Str.is_empty) == [Bool.True, Bool.False, Bool.False]

Run the given function on each element of a list, and return all the elements for which the function returned Bool.True.

[1, 2, 3, 4].keep_if(|num| num > 2)

## Performance Details

List.keep_if always returns a list that takes up exactly the same amount of memory as the original, even if its length decreases. This is because it can't know in advance exactly how much space it will need, and if it guesses a length that's too low, it would have to re-allocate.

(If you want to do an operation like this which reduces the memory footprint of the resulting list, you can do two passes over the list with List.fold - one to calculate the precise new size, and another to populate the new list.)

If given a unique list, List.keep_if will mutate it in place to assemble the appropriate list. If that happens, this function will not allocate any new memory on the heap. If all elements in the list end up being kept, Roc will return the original list unaltered.

Run the given function on each element of a list, and return all the elements for which the function returned Bool.False.

[1, 2, 3, 4].drop_if(|num| num > 2)

## Performance Details

List.drop_if has the same performance characteristics as List.keep_if. See its documentation for details on those characteristics!

Run the given function on each element of a list, and return the number of elements for which the function returned Bool.True.

expect [1, -2, -3].count_if(I64.is_negative) == 2
expect [1, 2, 3].count_if(|num| num > 1) == 2

Build a value using each element in the list.

Starting with a given state value, this folds through each element in the list from first to last, running a given step function on that element which updates the state. It returns the final state at the end.

[2, 4, 8].fold(0, U64.plus)

This returns 14 because: * state starts at 0 * Each step runs state.plus(elem), and the return value becomes the new state.

Here is a table of how state changes as List.fold folds over the elements [2, 4, 8] using U64.plus as its step function to determine the next state.

state | elem | U64.plus(state, elem) :---: | :---: | :----------------: 0 | | 0 | 2 | 2 2 | 4 | 6 6 | 8 | 14

The following returns -6:

[1, 2, 3].fold(0, I64.minus)

Note that in other languages, fold is sometimes called reduce, fold_left, or foldl.

Like List.fold, but walks the list from last to first. The step function receives the element first and the current state second.

expect [1, 2, 3].fold_rev(0, I64.minus) == 2

Here is a table of how state changes as List.fold_rev folds over the elements [1, 2, 3] using I64.minus as its step function.

state | elem | I64.minus(elem, state) :---: | :---: | :-------------------: 0 | | 0 | 3 | 3 3 | 2 | -1 -1 | 1 | 2

Note that in other languages, fold_rev is sometimes called reduce_right, fold_right, or foldr.

Run the given predicate on each element of the list, returning Bool.True if any of the elements satisfy it.

expect [1, 2, 3].any(|n| n % 2 == 0)

expect ![1, 2, 3].any(|n| n < 0)

Returns Bool.True if the list contains an element equal to the given value.

expect [1, 2, 3].contains(2)

expect ![1, 2, 3].contains(4)

Run the given predicate on each element of the list, returning Bool.True if all of the elements satisfy it.

expect [2, 4, 6].all(|n| n % 2 == 0)

expect ![1, 2, 3].all(|n| n % 2 == 0)

Returns the last element in the list, or ListWasEmpty if it was empty.

expect [1, 2, 3].last() == Ok(3.0)
expect [].last() == Err(ListWasEmpty)

Create a list with a single element in it.

expect List.single(42) == [42.0]

Remove the element at the given index. If the index is out of bounds, the list is returned unchanged.

expect [10, 20, 30, 40].drop_at(1) == [10, 30, 40]

expect [10, 20, 30].drop_at(5) == [10, 20, 30]

Return a sublist of the list starting at start and containing up to len elements. Out-of-bounds ranges are clamped, producing a shorter or empty list.

expect [1, 2, 3, 4, 5].sublist({ start: 1, len: 3 }) == [2, 3, 4]

expect [1, 2, 3].sublist({ start: 1, len: 10 }) == [2, 3]

expect [1, 2, 3].sublist({ start: 10, len: 2 }) == []

Return the first n elements of the list. If the list has fewer than n elements, the entire list is returned.

expect [1, 2, 3, 4, 5].take_first(3) == [1, 2, 3]

expect [1, 2].take_first(10) == [1, 2]

Returns the given number of elements from the end of the list.

expect [1, 2, 3, 4, 5, 6, 7, 8].take_last(4) == [5, 6, 7, 8]

If there are fewer elements in the list than the requested number, the entire list is returned.

expect [1, 2].take_last(5) == [1, 2]

To *remove* elements from the end of the list, use List.take_first.

To remove elements from both the beginning and end of the list, use List.sublist.

Drops n elements from the beginning of the list. If n is larger than the list length, an empty list is returned.

expect [1, 2, 3, 4, 5].drop_first(2) == [3, 4, 5]

expect [1, 2, 3].drop_first(10) == []

Drops n elements from the end of the list. If n is larger than the list length, an empty list is returned.

expect [1, 2, 3, 4, 5].drop_last(2) == [1, 2, 3]

expect [1, 2, 3].drop_last(10) == []

Join a list of items into a single item, inserting the given separator between each pair. Works for any type that implements a join_with method, such as Str.

expect ["a", "b", "c"].join_with(", ") == "a, b, c"

expect [].join_with(", ") == ""

Build a list by repeating the given value n times.

expect List.repeat(0, 3) == [0, 0, 0]

expect List.repeat("hi", 0) == []

Sum the elements of a list. Works for any type that implements plus and default methods, such as the numeric types.

expect List.sum([1.I64, 2, 3, 4]) == 10

expect List.sum([]) == 0.I64

Encode a list using a format that provides encode_list

Decode a list using a format that provides decode_list

Returns Bool.False when given Bool.True, and vice versa. This is equivalent to the logic NOT gate. The operator ! can also be used as shorthand for Bool.not.

expect Bool.not(Bool.False) == Bool.True
expect !Bool.False == Bool.True

Returns Bool.True if the two booleans are the same, and Bool.False if they are different.

Encode a bool using a format that provides encode_bool

Decode a bool using a format that provides decode_bool

Wraps a value in a generic, opaque representation (box) that can easily be passed to the platform. Boxing is an expensive process because it copies the value from the stack to the heap. This may provide a performance optimization for advanced use cases with large values.

Unwraps a value from a box. This is the inverse of Box.box, and is also an expensive operation.

Returns Bool.True if the result indicates a success, else returns Bool.False.

expect Try.Ok(5).is_ok()

Returns Bool.True if the result indicates a failure, else returns Bool.False.

expect Try.Err("uh oh").is_err()

If the result is Ok, returns the value it holds. Otherwise, returns the given default value.

Note: This function should be used sparingly, because it hides that an error happened, which will make debugging harder. Prefer using ? to forward errors or handle them explicitly with match.

expect Try.Err("uh oh").ok_or(42) == 42

expect Try.Ok(7).ok_or(42) == 7

If the result is Err, returns the value it holds. Otherwise, returns the given default value.

expect Try.Err("uh oh").err_or("fallback") == "uh oh"

expect Try.Ok(7).err_or("fallback") == "fallback"

If the result is Ok, transforms the value it holds by running a conversion function on it. Then returns a new Ok holding the transformed value. If the result is Err, this has no effect. Use map_err to transform an Err.

expect Try.Ok(12.I64).map_ok(|n| -n) == Ok(-12)

expect {
	err : Try(I64, Str)
	err = Err("yipes!")
	err.map_ok(|n| -n) == Err("yipes!")
}

Functions like map are common in Roc; see for example List.map and Set.map.

Like map_ok, but the transform function is effectful. If the argument is an Ok, the effect is run and its return value is wrapped in a new Ok. If the result is Err, the effect is not run and the Err is returned unchanged.

artist_try.map_ok!(|a| SQL.query!("SELECT * FROM albums WHERE artist_id = ?", [a.id]))

If the result is Err, transforms the value it holds by running a conversion function on it. Then returns a new Err holding the transformed value. If the result is Ok, this has no effect. Use map_ok to transform an Ok.

expect [].last().map_err(|_| ProvidedListIsEmpty) == Err(ProvidedListIsEmpty)

expect [4].last().map_err(|_| ProvidedListIsEmpty) == Ok(4.0)

Like map_err, but the transform function is effectful. If the argument is an Err, the effect is run and its return value is wrapped in a new Err. If the result is Ok, the effect is not run and the Ok is returned unchanged.

# Log the failure to the database only when the request errored.
request.map_err!(|e| SQL.execute!("INSERT INTO errors (message) VALUES (?)", [e.message]))

Returns Bool.True if the two Try values are the same variant (Ok or Err) and their contents are pairwise equal. Otherwise, returns Bool.False.