Merge remote-tracking branch 'origin/trunk' into remove-old-expect-logic

crates/compiler/builtins/.gitignore

@@ -0,0 +1 @@
+builtins.ll

crates/compiler/builtins/Cargo.toml

@@ -0,0 +1,22 @@
+[package]
+name = "roc_builtins"
+version = "0.1.0"
+authors = ["The Roc Contributors"]
+license = "UPL-1.0"
+edition = "2021"
+
+[dependencies]
+roc_collections = { path = "../collections" }
+roc_region = { path = "../region" }
+roc_module = { path = "../module" }
+roc_types = { path = "../types" }
+roc_target = { path = "../roc_target" }
+lazy_static = "1.4.0"
+
+[build-dependencies]
+# dunce can be removed once ziglang/zig#5109 is fixed
+dunce = "1.0.2"
+fs_extra = "1.2.0"
+
+[target.'cfg(target_os = "macos")'.build-dependencies]
+tempfile = "3.2.0"

crates/compiler/builtins/README.md

@@ -0,0 +1,110 @@
+# So you want to add a builtin?
+
+Builtins are the functions and modules that are implicitly imported into every module. All of them compile down to llvm, but some are implemented directly as llvm and others in terms of intermediate functions. Either way, making a new builtin means touching many files. Lets make it easy for you and just list out which modules you need to visit to make a builtin. Here is what it takes:
+
+## A builtin written only in Roc
+
+Edit the appropriate `roc/*.roc` file with your new implementation. All normal rules for writing Roc code apply. Be sure to add a declaration, definition, some documentation and add it to the exposes list it in the module head.
+
+Next, look towards the bottom of the  `compiler/builtins/module/src/symbol.rs` file. Inside the `define_builtins!` macro, there is a list for each of the builtin modules and the function or value names it contains. Add a new entry to the appropriate list for your new function.
+
+For each of the builtin modules, there is a file in `compiler/test_gen/src/` like `gen_num.rs`, `gen_str.rs` etc. Add new tests for the module you are changing to the appropriate file here. You can look at the existing test cases for examples and inspiration.
+
+You can run your new tests locally using `cargo test-gen-llvm`. You can add a filter like `cargo test-gen-llvm gen_str` (to only run tests defined in `gen_str.rs`) or `cargo test-gen-llvm gen_str::str_split` (to only run tests defined in `gen_str` whose names start with `str_split`). More details can be found in the README in the `compiler/test_gen` directory.
+
+## A builtin implemented directly as LLVM
+
+### module/src/symbol.rs
+
+Towards the bottom of `symbol.rs` there is a `define_builtins!` macro being used that takes many modules and function names. The first level (`List`, `Int` ..) is the module name, and the second level is the function or value name (`reverse`, `rem` ..). If you wanted to add a `Int` function called `addTwo` go to `2 Int: "Int" => {` and inside that case add to the bottom `38 INT_ADD_TWO: "addTwo"` (assuming there are 37 existing ones).
+
+Some of these have `#` inside their name (`first#list`, `#lt` ..). This is a trick we are doing to hide implementation details from Roc programmers. To a Roc programmer, a name with `#` in it is invalid, because `#` means everything after it is parsed to a comment. We are constructing these functions manually, so we are circumventing the parsing step and dont have such restrictions. We get to make functions and values with `#` which as a consequence are not accessible to Roc programmers. Roc programmers simply cannot reference them.
+
+But we can use these values and some of these are necessary for implementing builtins. For example, `List.get` returns tags, and it is not easy for us to create tags when composing LLVM. What is easier however, is:
+- ..writing `List.#getUnsafe` that has the dangerous signature of `List elem, Nat -> elem` in LLVM
+- ..writing `List elem, Nat -> Result elem [OutOfBounds]*` in a type safe way that uses `getUnsafe` internally, only after it checks if the `elem` at `Nat` index exists.
+
+
+### can/src/builtins.rs
+
+Right at the top of this module is a function called `builtin_defs`. All this is doing is mapping the `Symbol` defined in `module/src/symbol.rs` to its implementation. Some of the builtins are quite complex, such as `list_get`. What makes `list_get` is that it returns tags, and in order to return tags it first has to  defer to lower-level functions via an if statement.
+
+Lets look at `List.repeat : elem, Nat -> List elem`, which is more straight-forward, and points directly to its lower level implementation:
+```
+fn list_repeat(symbol: Symbol, var_store: &mut VarStore) -> Def {
+    let elem_var = var_store.fresh();
+    let len_var = var_store.fresh();
+    let list_var = var_store.fresh();
+
+    let body = RunLowLevel {
+        op: LowLevel::ListRepeat,
+        args: vec![
+            (elem_var, Var(Symbol::ARG_1)),
+            (len_var, Var(Symbol::ARG_2)),
+        ],
+        ret_var: list_var,
+    };
+
+    defn(
+        symbol,
+        vec![(elem_var, Symbol::ARG_1), (len_var, Symbol::ARG_2)],
+        var_store,
+        body,
+        list_var,
+    )
+}
+```
+In these builtin definitions you will need to allocate for and list the arguments. For `List.repeat`, the arguments are the `elem_var` and the `len_var`. So in both the `body` and `defn` we list these arguments in a vector, with the `Symbol::ARG_1` and` Symvol::ARG_2` designating which argument is which.
+
+Since `List.repeat` is implemented entirely as low level functions, its `body` is a `RunLowLevel`, and the `op` is `LowLevel::ListRepeat`. Lets talk about `LowLevel` in the next section.
+
+## Connecting the definition to the implementation
+### module/src/low_level.rs
+This `LowLevel` thing connects the builtin defined in this module to its implementation. It's referenced in `can/src/builtins.rs` and it is used in `gen/src/llvm/build.rs`.
+
+## Bottom level LLVM values and functions
+### gen/src/llvm/build.rs
+This is where bottom-level functions that need to be written as LLVM are created. If the function leads to a tag thats a good sign it should not be written here in `build.rs`. If it's simple fundamental stuff like `INT_ADD` then it certainly should be written here.
+
+## Letting the compiler know these functions exist
+### builtins/src/std.rs
+It's one thing to actually write these functions, it's _another_ thing to let the Roc compiler know they exist as part of the standard library. You have to tell the compiler "Hey, this function exists, and it has this type signature". That happens in `std.rs`.
+
+## Specifying how we pass args to the function
+### builtins/mono/src/borrow.rs
+After we have all of this, we need to specify if the arguments we're passing are owned, borrowed or irrelevant. Towards the bottom of this file, add a new case for your builtin and specify each arg. Be sure to read the comment, as it explains this in more detail.
+
+## Testing it
+### solve/tests/solve_expr.rs
+To make sure that Roc is properly inferring the type of the new builtin, add a test to this file similar to:
+```
+ #[test]
+fn atan() {
+    infer_eq_without_problem(
+        indoc!(
+            r#"
+            Num.atan
+            "#
+        ),
+        "Float -> Float",
+    );
+}
+```
+But replace `Num.atan` and the type signature with the new builtin.
+
+### test_gen/test/*.rs
+In this directory, there are a couple files like `gen_num.rs`, `gen_str.rs`, etc. For the `Str` module builtins, put the test in `gen_str.rs`, etc. Find the one for the new builtin, and add a test like:
+```
+#[test]
+fn atan() {
+    assert_evals_to!("Num.atan 10", 1.4711276743037347, f64);
+}
+```
+But replace `Num.atan`, the return value, and the return type with your new builtin.
+
+# Mistakes that are easy to make!!
+
+When implementing a new builtin, it is often easy to copy and paste the implementation for an existing builtin. This can take you quite far since many builtins are very similar, but it also risks forgetting to change one small part of what you copy and pasted and losing a lot of time later on when you cant figure out why things dont work. So, speaking from experience, even if you are copying an existing builtin, try and implement it manually without copying and pasting. Two recent instances of this (as of September 7th, 2020):
+
+- `List.keepIf` did not work for a long time because in builtins its `LowLevel` was `ListMap`. This was because I copy and pasted the `List.map` implementation in `builtins.rs
+- `List.walkBackwards` had mysterious memory bugs for a little while because in `unique.rs` its return type was `list_type(flex(b))` instead of `flex(b)` since it was copy and pasted from `List.keepIf`.

crates/compiler/builtins/bitcode/.gitignore

@@ -0,0 +1,7 @@
+zig-cache
+src/zig-cache
+benchmark/zig-cache
+builtins.ll
+builtins.bc
+builtins.o
+dec

crates/compiler/builtins/bitcode/README.md

@@ -0,0 +1,35 @@
+# Bitcode for Builtins
+
+## Adding a bitcode builtin
+
+To add a builtin:
+1. Add the function to the relevant module. For `Num` builtin use it in `src/num.zig`, for `Str` builtins use `src/str.zig`, and so on. **For anything you add, you must add tests for it!** Not only does to make the builtins more maintainable, it's the the easiest way to test these functions on Zig. To run the test, run: `zig build test`
+2. Make sure the function is public with the `pub` keyword and uses the C calling convention. This is really easy, just add `pub` and `callconv(.C)` to the function declaration like so: `pub fn atan(num: f64) callconv(.C) f64 { ... }`
+3. In `src/main.zig`, export the function. This is also organized by module. For example, for a `Num` function find the `Num` section and add: `comptime { exportNumFn(num.atan, "atan"); }`. The first argument is the function, the second is the name of it in LLVM.
+4. In `compiler/builtins/src/bitcode.rs`, add a constant for the new function. This is how we use it in Rust. Once again, this is organized by module, so just find the relevant area and add your new function.
+5. You can now use your function in Rust using `call_bitcode_fn` in `llvm/src/build.rs`!
+
+## How it works
+
+Roc's builtins are implemented in the compiler using LLVM only.
+When their implementations are simple enough (e.g. addition), they
+can be implemented directly in Inkwell.
+
+When their implementations are complex enough, it's nicer to
+implement them in a higher-level language like Zig, then compile
+the result to LLVM bitcode, and import that bitcode into the compiler.
+
+Compiling the bitcode happens automatically in a Rust build script at `compiler/builtins/build.rs`.
+Then `builtins/src/bitcode/rs` staticlly imports the compiled bitcode for use in the compiler.
+
+You can find the compiled bitcode in `target/debug/build/roc_builtins-[some random characters]/out/builtins.bc`.
+There will be two directories like `roc_builtins-[some random characters]`, look for the one that has an
+`out` directory as a child.
+
+> The bitcode is a bunch of bytes that aren't particularly human-readable.
+> If you want to take a look at the human-readable LLVM IR, look at
+> `compiler/builtins/bitcode/builtins.ll`
+
+## Calling bitcode functions
+
+use the `call_bitcode_fn` function defined in `llvm/src/build.rs` to call bitcode functions.

crates/compiler/builtins/bitcode/benchmark.sh

@@ -0,0 +1,6 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+zig build-exe benchmark/dec.zig -O ReleaseFast --main-pkg-path .
+./dec

crates/compiler/builtins/bitcode/benchmark/dec.zig

@@ -0,0 +1,174 @@
+const std = @import("std");
+const time = std.time;
+const Timer = time.Timer;
+
+const RocStr = @import("../src/str.zig").RocStr;
+const RocDec = @import("../src/dec.zig").RocDec;
+
+var timer: Timer = undefined;
+
+pub fn main() !void {
+    const stdout = std.io.getStdOut().writer();
+    timer = try Timer.start();
+
+    try stdout.print("7 additions took ", .{});
+    try avg_runs(add7);
+
+    try stdout.print("7 subtractions took ", .{});
+    try avg_runs(sub7);
+
+    try stdout.print("7 multiplications took ", .{});
+    try avg_runs(mul7);
+
+    try stdout.print("7 divisions took ", .{});
+    try avg_runs(div7);
+}
+
+fn avg_runs(func: fn() u64) !void {
+    const stdout = std.io.getStdOut().writer();
+    var first_run = func();
+    var lowest = first_run;
+    var highest = first_run;
+    var sum = first_run;
+
+    // 31 runs
+    var runs = [_]u64{ first_run, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };
+    var next_run: usize = 1; // we already did first_run
+
+    while (next_run < runs.len) {
+        const run = func();
+
+        lowest = std.math.min(lowest, run);
+        highest = std.math.max(highest, run);
+
+        runs[next_run] = run;
+
+        next_run += 1;
+    }
+
+    std.sort.sort(u64, &runs, {}, comptime std.sort.asc(u64));
+
+    const median = runs[runs.len / 2];
+
+    try stdout.print("{}ns (lowest: {}ns, highest: {}ns)\n", .{median, lowest, highest});
+}
+
+fn add7() u64 {
+    var str1 = RocStr.init("1.2", 3);
+    const dec1 = RocDec.fromStr(str1).?;
+
+    var str2 = RocStr.init("3.4", 3);
+    const dec2 = RocDec.fromStr(str2).?;
+
+    timer.reset();
+
+    var a = dec1.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+    a = a.add(dec1);
+    a = a.add(dec2);
+
+    return timer.read();
+}
+
+fn sub7() u64 {
+    var str1 = RocStr.init("1.2", 3);
+    const dec1 = RocDec.fromStr(str1).?;
+
+    var str2 = RocStr.init("3.4", 3);
+    const dec2 = RocDec.fromStr(str2).?;
+
+    timer.reset();
+
+    var a = dec1.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+    a = a.sub(dec1);
+    a = a.sub(dec2);
+
+    return timer.read();
+}
+
+fn mul7() u64 {
+    var str1 = RocStr.init("1.2", 3);
+    const dec1 = RocDec.fromStr(str1).?;
+
+    var str2 = RocStr.init("3.4", 3);
+    const dec2 = RocDec.fromStr(str2).?;
+
+    timer.reset();
+
+    var a = dec1.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+    a = a.mul(dec1);
+    a = a.mul(dec2);
+
+    return timer.read();
+}
+
+fn div7() u64 {
+    var str1 = RocStr.init("1.2", 3);
+    const dec1 = RocDec.fromStr(str1).?;
+
+    var str2 = RocStr.init("3.4", 3);
+    const dec2 = RocDec.fromStr(str2).?;
+
+    timer.reset();
+
+    var a = dec1.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+    a = a.div(dec1);
+    a = a.div(dec2);
+
+    return timer.read();
+}

crates/compiler/builtins/bitcode/build.zig

@@ -0,0 +1,131 @@
+const std = @import("std");
+const mem = std.mem;
+const Builder = std.build.Builder;
+const CrossTarget = std.zig.CrossTarget;
+const Arch = std.Target.Cpu.Arch;
+
+pub fn build(b: *Builder) void {
+    // b.setPreferredReleaseMode(.Debug);
+    b.setPreferredReleaseMode(.ReleaseFast);
+    const mode = b.standardReleaseOptions();
+
+    // Options
+    const fallback_main_path = "./src/main.zig";
+    const main_path_desc = b.fmt("Override path to main.zig. Used by \"ir\" and \"test\". Defaults to \"{s}\". ", .{fallback_main_path});
+    const main_path = b.option([]const u8, "main-path", main_path_desc) orelse fallback_main_path;
+
+    // Tests
+    var main_tests = b.addTest(main_path);
+    main_tests.setBuildMode(mode);
+    main_tests.linkSystemLibrary("c");
+    const test_step = b.step("test", "Run tests");
+    test_step.dependOn(&main_tests.step);
+
+    // Targets
+    const host_target = b.standardTargetOptions(.{
+        .default_target = CrossTarget{
+            .cpu_model = .baseline,
+            // TODO allow for native target for maximum speed
+        },
+    });
+    const linux32_target = makeLinux32Target();
+    const linux64_target = makeLinux64Target();
+    const wasm32_target = makeWasm32Target();
+
+    // LLVM IR
+    generateLlvmIrFile(b, mode, host_target, main_path, "ir", "builtins-host");
+    generateLlvmIrFile(b, mode, linux32_target, main_path, "ir-i386", "builtins-i386");
+    generateLlvmIrFile(b, mode, linux64_target, main_path, "ir-x86_64", "builtins-x86_64");
+    generateLlvmIrFile(b, mode, wasm32_target, main_path, "ir-wasm32", "builtins-wasm32");
+
+    // Generate Object Files
+    generateObjectFile(b, mode, host_target, main_path, "object", "builtins-host");
+    generateObjectFile(b, mode, wasm32_target, main_path, "wasm32-object", "builtins-wasm32");
+
+    removeInstallSteps(b);
+}
+
+// TODO zig 0.9 can generate .bc directly, switch to that when it is released!
+fn generateLlvmIrFile(
+    b: *Builder,
+    mode: std.builtin.Mode,
+    target: CrossTarget,
+    main_path: []const u8,
+    step_name: []const u8,
+    object_name: []const u8,
+) void {
+    const obj = b.addObject(object_name, main_path);
+    obj.setBuildMode(mode);
+    obj.strip = true;
+    obj.emit_llvm_ir = .emit;
+    obj.emit_llvm_bc = .emit;
+    obj.emit_bin = .no_emit;
+    obj.target = target;
+
+    const ir = b.step(step_name, "Build LLVM ir");
+    ir.dependOn(&obj.step);
+}
+
+// Generate Object File
+// TODO: figure out how to get this to emit symbols that are only scoped to linkage (global but hidden).
+// @bhansconnect: I believe anything with global scope will still be preserved by the linker even if it
+// is never called. I think it could theoretically be called by a dynamic lib that links to the executable
+// or something similar.
+fn generateObjectFile(
+    b: *Builder,
+    mode: std.builtin.Mode,
+    target: CrossTarget,
+    main_path: []const u8,
+    step_name: []const u8,
+    object_name: []const u8,
+) void {
+    const obj = b.addObject(object_name, main_path);
+    obj.setBuildMode(mode);
+    obj.linkSystemLibrary("c");
+    obj.setOutputDir(".");
+    obj.strip = true;
+    obj.target = target;
+    obj.link_function_sections = true;
+    const obj_step = b.step(step_name, "Build object file for linking");
+    obj_step.dependOn(&obj.step);
+}
+
+fn makeLinux32Target() CrossTarget {
+    var target = CrossTarget.parse(.{}) catch unreachable;
+
+    target.cpu_arch = std.Target.Cpu.Arch.i386;
+    target.os_tag = std.Target.Os.Tag.linux;
+    target.abi = std.Target.Abi.musl;
+
+    return target;
+}
+
+fn makeLinux64Target() CrossTarget {
+    var target = CrossTarget.parse(.{}) catch unreachable;
+
+    target.cpu_arch = std.Target.Cpu.Arch.x86_64;
+    target.os_tag = std.Target.Os.Tag.linux;
+    target.abi = std.Target.Abi.musl;
+
+    return target;
+}
+
+fn makeWasm32Target() CrossTarget {
+    var target = CrossTarget.parse(.{}) catch unreachable;
+
+    // 32-bit wasm
+    target.cpu_arch = std.Target.Cpu.Arch.wasm32;
+    target.os_tag = std.Target.Os.Tag.freestanding;
+    target.abi = std.Target.Abi.none;
+
+    return target;
+}
+
+fn removeInstallSteps(b: *Builder) void {
+    for (b.top_level_steps.items) |top_level_step, i| {
+        const name = top_level_step.step.name;
+        if (mem.eql(u8, name, "install") or mem.eql(u8, name, "uninstall")) {
+            _ = b.top_level_steps.swapRemove(i);
+        }
+    }
+}

crates/compiler/builtins/bitcode/run-tests.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# Test every zig
+zig build test
+
+# fmt every zig
+find src/*.zig -type f -print0 | xargs -n 1 -0 zig fmt --check || (echo "zig fmt --check FAILED! Check the previous lines to see which files were improperly formatted." && exit 1)

crates/compiler/builtins/bitcode/run-wasm-tests.sh

@@ -0,0 +1,11 @@
+#!/bin/bash
+
+set -euxo pipefail
+
+# Test failures will always point at the _start function
+# Make sure to look at the rest of the stack trace!
+
+# Zig will try to run the test binary it produced, but it is a wasm object and hence your OS won't
+# know how to run it. In the error message, it prints the binary it tried to run. We use some fun
+# unix tools to get that path, then feed it to wasmer
+zig test -target wasm32-wasi-musl -O ReleaseFast src/main.zig --test-cmd wasmer --test-cmd-bin

crates/compiler/builtins/bitcode/src/dict.zig

@@ -0,0 +1,815 @@
+const std = @import("std");
+const testing = std.testing;
+const expectEqual = testing.expectEqual;
+const mem = std.mem;
+const assert = std.debug.assert;
+
+const utils = @import("utils.zig");
+const RocList = @import("list.zig").RocList;
+
+const INITIAL_SEED = 0xc70f6907;
+
+const InPlace = enum(u8) {
+    InPlace,
+    Clone,
+};
+
+const Slot = enum(u8) {
+    Empty,
+    Filled,
+    PreviouslyFilled,
+};
+
+const MaybeIndexTag = enum { index, not_found };
+
+const MaybeIndex = union(MaybeIndexTag) { index: usize, not_found: void };
+
+fn nextSeed(seed: u64) u64 {
+    // TODO is this a valid way to get a new seed? are there better ways?
+    return seed + 1;
+}
+
+fn totalCapacityAtLevel(input: usize) usize {
+    if (input == 0) {
+        return 0;
+    }
+
+    var n = input;
+    var slots: usize = 8;
+
+    while (n > 1) : (n -= 1) {
+        slots = slots * 2 + slots;
+    }
+
+    return slots;
+}
+
+fn capacityOfLevel(input: usize) usize {
+    if (input == 0) {
+        return 0;
+    }
+
+    var n = input;
+    var slots: usize = 8;
+
+    while (n > 1) : (n -= 1) {
+        slots = slots * 2;
+    }
+
+    return slots;
+}
+
+// aligmnent of elements. The number (16 or 8) indicates the maximum
+// alignment of the key and value. The tag furthermore indicates
+// which has the biggest aligmnent. If both are the same, we put
+// the key first
+const Alignment = extern struct {
+    bits: u8,
+
+    const VALUE_BEFORE_KEY_FLAG: u8 = 0b1000_0000;
+
+    fn toU32(self: Alignment) u32 {
+        if (self.bits >= VALUE_BEFORE_KEY_FLAG) {
+            return self.bits ^ Alignment.VALUE_BEFORE_KEY_FLAG;
+        } else {
+            return self.bits;
+        }
+    }
+
+    fn keyFirst(self: Alignment) bool {
+        if (self.bits & Alignment.VALUE_BEFORE_KEY_FLAG > 0) {
+            return false;
+        } else {
+            return true;
+        }
+    }
+};
+
+pub fn decref(
+    bytes_or_null: ?[*]u8,
+    data_bytes: usize,
+    alignment: Alignment,
+) void {
+    return utils.decref(bytes_or_null, data_bytes, alignment.toU32());
+}
+
+pub fn allocateWithRefcount(
+    data_bytes: usize,
+    alignment: Alignment,
+) [*]u8 {
+    return utils.allocateWithRefcount(data_bytes, alignment.toU32());
+}
+
+pub const RocDict = extern struct {
+    dict_bytes: ?[*]u8,
+    dict_entries_len: usize,
+    number_of_levels: usize,
+
+    pub fn empty() RocDict {
+        return RocDict{
+            .dict_entries_len = 0,
+            .number_of_levels = 0,
+            .dict_bytes = null,
+        };
+    }
+
+    pub fn allocate(
+        number_of_levels: usize,
+        number_of_entries: usize,
+        alignment: Alignment,
+        key_size: usize,
+        value_size: usize,
+    ) RocDict {
+        const number_of_slots = totalCapacityAtLevel(number_of_levels);
+        const slot_size = slotSize(key_size, value_size);
+        const data_bytes = number_of_slots * slot_size;
+
+        return RocDict{
+            .dict_bytes = allocateWithRefcount(data_bytes, alignment),
+            .number_of_levels = number_of_levels,
+            .dict_entries_len = number_of_entries,
+        };
+    }
+
+    pub fn reallocate(
+        self: RocDict,
+        alignment: Alignment,
+        key_width: usize,
+        value_width: usize,
+    ) RocDict {
+        const new_level = self.number_of_levels + 1;
+        const slot_size = slotSize(key_width, value_width);
+
+        const old_capacity = self.capacity();
+        const new_capacity = totalCapacityAtLevel(new_level);
+        const delta_capacity = new_capacity - old_capacity;
+
+        const data_bytes = new_capacity * slot_size;
+        const first_slot = allocateWithRefcount(data_bytes, alignment);
+
+        // transfer the memory
+
+        if (self.dict_bytes) |source_ptr| {
+            const dest_ptr = first_slot;
+
+            var source_offset: usize = 0;
+            var dest_offset: usize = 0;
+
+            if (alignment.keyFirst()) {
+                // copy keys
+                @memcpy(dest_ptr + dest_offset, source_ptr + source_offset, old_capacity * key_width);
+
+                // copy values
+                source_offset = old_capacity * key_width;
+                dest_offset = new_capacity * key_width;
+                @memcpy(dest_ptr + dest_offset, source_ptr + source_offset, old_capacity * value_width);
+            } else {
+                // copy values
+                @memcpy(dest_ptr + dest_offset, source_ptr + source_offset, old_capacity * value_width);
+
+                // copy keys
+                source_offset = old_capacity * value_width;
+                dest_offset = new_capacity * value_width;
+                @memcpy(dest_ptr + dest_offset, source_ptr + source_offset, old_capacity * key_width);
+            }
+
+            // copy slots
+            source_offset = old_capacity * (key_width + value_width);
+            dest_offset = new_capacity * (key_width + value_width);
+            @memcpy(dest_ptr + dest_offset, source_ptr + source_offset, old_capacity * @sizeOf(Slot));
+        }
+
+        var i: usize = 0;
+        const first_new_slot_value = first_slot + old_capacity * slot_size + delta_capacity * (key_width + value_width);
+        while (i < (new_capacity - old_capacity)) : (i += 1) {
+            (first_new_slot_value)[i] = @enumToInt(Slot.Empty);
+        }
+
+        const result = RocDict{
+            .dict_bytes = first_slot,
+            .number_of_levels = self.number_of_levels + 1,
+            .dict_entries_len = self.dict_entries_len,
+        };
+
+        // NOTE we fuse an increment of all keys/values with a decrement of the input dict
+        decref(self.dict_bytes, self.capacity() * slotSize(key_width, value_width), alignment);
+
+        return result;
+    }
+
+    pub fn asU8ptr(self: RocDict) [*]u8 {
+        return @ptrCast([*]u8, self.dict_bytes);
+    }
+
+    pub fn len(self: RocDict) usize {
+        return self.dict_entries_len;
+    }
+
+    pub fn isEmpty(self: RocDict) bool {
+        return self.len() == 0;
+    }
+
+    pub fn isUnique(self: RocDict) bool {
+        // the empty dict is unique (in the sense that copying it will not leak memory)
+        if (self.isEmpty()) {
+            return true;
+        }
+
+        // otherwise, check if the refcount is one
+        const ptr: [*]usize = @ptrCast([*]usize, @alignCast(@alignOf(usize), self.dict_bytes));
+        return (ptr - 1)[0] == utils.REFCOUNT_ONE;
+    }
+
+    pub fn capacity(self: RocDict) usize {
+        return totalCapacityAtLevel(self.number_of_levels);
+    }
+
+    pub fn makeUnique(self: RocDict, alignment: Alignment, key_width: usize, value_width: usize) RocDict {
+        if (self.isEmpty()) {
+            return self;
+        }
+
+        if (self.isUnique()) {
+            return self;
+        }
+
+        // unfortunately, we have to clone
+        var new_dict = RocDict.allocate(self.number_of_levels, self.dict_entries_len, alignment, key_width, value_width);
+
+        var old_bytes: [*]u8 = @ptrCast([*]u8, self.dict_bytes);
+        var new_bytes: [*]u8 = @ptrCast([*]u8, new_dict.dict_bytes);
+
+        const number_of_bytes = self.capacity() * (@sizeOf(Slot) + key_width + value_width);
+        @memcpy(new_bytes, old_bytes, number_of_bytes);
+
+        // NOTE we fuse an increment of all keys/values with a decrement of the input dict
+        const data_bytes = self.capacity() * slotSize(key_width, value_width);
+        decref(self.dict_bytes, data_bytes, alignment);
+
+        return new_dict;
+    }
+
+    fn getSlot(self: *const RocDict, index: usize, key_width: usize, value_width: usize) Slot {
+        const offset = self.capacity() * (key_width + value_width) + index * @sizeOf(Slot);
+
+        const ptr = self.dict_bytes orelse unreachable;
+        return @intToEnum(Slot, ptr[offset]);
+    }
+
+    fn setSlot(self: *RocDict, index: usize, key_width: usize, value_width: usize, slot: Slot) void {
+        const offset = self.capacity() * (key_width + value_width) + index * @sizeOf(Slot);
+
+        const ptr = self.dict_bytes orelse unreachable;
+        ptr[offset] = @enumToInt(slot);
+    }
+
+    fn setKey(self: *RocDict, index: usize, alignment: Alignment, key_width: usize, value_width: usize, data: Opaque) void {
+        if (key_width == 0) {
+            return;
+        }
+
+        const offset = blk: {
+            if (alignment.keyFirst()) {
+                break :blk (index * key_width);
+            } else {
+                break :blk (self.capacity() * value_width) + (index * key_width);
+            }
+        };
+
+        const ptr = self.dict_bytes orelse unreachable;
+
+        const source = data orelse unreachable;
+        const dest = ptr + offset;
+        @memcpy(dest, source, key_width);
+    }
+
+    fn getKey(self: *const RocDict, index: usize, alignment: Alignment, key_width: usize, value_width: usize) Opaque {
+        if (key_width == 0) {
+            return null;
+        }
+
+        const offset = blk: {
+            if (alignment.keyFirst()) {
+                break :blk (index * key_width);
+            } else {
+                break :blk (self.capacity() * value_width) + (index * key_width);
+            }
+        };
+
+        const ptr = self.dict_bytes orelse unreachable;
+        return ptr + offset;
+    }
+
+    fn setValue(self: *RocDict, index: usize, alignment: Alignment, key_width: usize, value_width: usize, data: Opaque) void {
+        if (value_width == 0) {
+            return;
+        }
+
+        const offset = blk: {
+            if (alignment.keyFirst()) {
+                break :blk (self.capacity() * key_width) + (index * value_width);
+            } else {
+                break :blk (index * value_width);
+            }
+        };
+
+        const ptr = self.dict_bytes orelse unreachable;
+
+        const source = data orelse unreachable;
+        const dest = ptr + offset;
+        @memcpy(dest, source, value_width);
+    }
+
+    fn getValue(self: *const RocDict, index: usize, alignment: Alignment, key_width: usize, value_width: usize) Opaque {
+        if (value_width == 0) {
+            return null;
+        }
+
+        const offset = blk: {
+            if (alignment.keyFirst()) {
+                break :blk (self.capacity() * key_width) + (index * value_width);
+            } else {
+                break :blk (index * value_width);
+            }
+        };
+
+        const ptr = self.dict_bytes orelse unreachable;
+        return ptr + offset;
+    }
+
+    fn findIndex(self: *const RocDict, alignment: Alignment, key: Opaque, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn) MaybeIndex {
+        if (self.isEmpty()) {
+            return MaybeIndex.not_found;
+        }
+
+        var seed: u64 = INITIAL_SEED;
+
+        var current_level: usize = 1;
+        var current_level_size: usize = 8;
+        var next_level_size: usize = 2 * current_level_size;
+
+        while (true) {
+            if (current_level > self.number_of_levels) {
+                return MaybeIndex.not_found;
+            }
+
+            // hash the key, and modulo by the maximum size
+            // (so we get an in-bounds index)
+            const hash = hash_fn(seed, key);
+            const index = capacityOfLevel(current_level - 1) + @intCast(usize, (hash % current_level_size));
+
+            switch (self.getSlot(index, key_width, value_width)) {
+                Slot.Empty, Slot.PreviouslyFilled => {
+                    return MaybeIndex.not_found;
+                },
+                Slot.Filled => {
+                    // is this the same key, or a new key?
+                    const current_key = self.getKey(index, alignment, key_width, value_width);
+
+                    if (is_eq(key, current_key)) {
+                        return MaybeIndex{ .index = index };
+                    } else {
+                        current_level += 1;
+                        current_level_size *= 2;
+                        next_level_size *= 2;
+
+                        seed = nextSeed(seed);
+                        continue;
+                    }
+                },
+            }
+        }
+    }
+};
+
+// Dict.empty
+pub fn dictEmpty(dict: *RocDict) callconv(.C) void {
+    dict.* = RocDict.empty();
+}
+
+pub fn slotSize(key_size: usize, value_size: usize) usize {
+    return @sizeOf(Slot) + key_size + value_size;
+}
+
+// Dict.len
+pub fn dictLen(dict: RocDict) callconv(.C) usize {
+    return dict.dict_entries_len;
+}
+
+// commonly used type aliases
+const Opaque = ?[*]u8;
+const HashFn = fn (u64, ?[*]u8) callconv(.C) u64;
+const EqFn = fn (?[*]u8, ?[*]u8) callconv(.C) bool;
+
+const Inc = fn (?[*]u8) callconv(.C) void;
+const IncN = fn (?[*]u8, usize) callconv(.C) void;
+const Dec = fn (?[*]u8) callconv(.C) void;
+
+const Caller3 = fn (?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8) callconv(.C) void;
+
+// Dict.insert : Dict k v, k, v -> Dict k v
+pub fn dictInsert(
+    input: RocDict,
+    alignment: Alignment,
+    key: Opaque,
+    key_width: usize,
+    value: Opaque,
+    value_width: usize,
+    hash_fn: HashFn,
+    is_eq: EqFn,
+    dec_key: Dec,
+    dec_value: Dec,
+    output: *RocDict,
+) callconv(.C) void {
+    var seed: u64 = INITIAL_SEED;
+
+    var result = input.makeUnique(alignment, key_width, value_width);
+
+    var current_level: usize = 1;
+    var current_level_size: usize = 8;
+    var next_level_size: usize = 2 * current_level_size;
+
+    while (true) {
+        if (current_level > result.number_of_levels) {
+            result = result.reallocate(alignment, key_width, value_width);
+        }
+
+        const hash = hash_fn(seed, key);
+        const index = capacityOfLevel(current_level - 1) + @intCast(usize, (hash % current_level_size));
+        assert(index < result.capacity());
+
+        switch (result.getSlot(index, key_width, value_width)) {
+            Slot.Empty, Slot.PreviouslyFilled => {
+                result.setSlot(index, key_width, value_width, Slot.Filled);
+                result.setKey(index, alignment, key_width, value_width, key);
+                result.setValue(index, alignment, key_width, value_width, value);
+
+                result.dict_entries_len += 1;
+                break;
+            },
+            Slot.Filled => {
+                // is this the same key, or a new key?
+                const current_key = result.getKey(index, alignment, key_width, value_width);
+
+                if (is_eq(key, current_key)) {
+                    // we will override the old value, but first have to decrement its refcount
+                    const current_value = result.getValue(index, alignment, key_width, value_width);
+                    dec_value(current_value);
+
+                    // we must consume the key argument!
+                    dec_key(key);
+
+                    result.setValue(index, alignment, key_width, value_width, value);
+                    break;
+                } else {
+                    seed = nextSeed(seed);
+
+                    current_level += 1;
+                    current_level_size *= 2;
+                    next_level_size *= 2;
+
+                    continue;
+                }
+            },
+        }
+    }
+
+    // write result into pointer
+    output.* = result;
+}
+
+// Dict.remove : Dict k v, k -> Dict k v
+pub fn dictRemove(input: RocDict, alignment: Alignment, key: Opaque, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn, dec_key: Dec, dec_value: Dec, output: *RocDict) callconv(.C) void {
+    switch (input.findIndex(alignment, key, key_width, value_width, hash_fn, is_eq)) {
+        MaybeIndex.not_found => {
+            // the key was not found; we're done
+            output.* = input;
+            return;
+        },
+        MaybeIndex.index => |index| {
+            var dict = input.makeUnique(alignment, key_width, value_width);
+
+            assert(index < dict.capacity());
+
+            dict.setSlot(index, key_width, value_width, Slot.PreviouslyFilled);
+            const old_key = dict.getKey(index, alignment, key_width, value_width);
+            const old_value = dict.getValue(index, alignment, key_width, value_width);
+
+            dec_key(old_key);
+            dec_value(old_value);
+            dict.dict_entries_len -= 1;
+
+            // if the dict is now completely empty, free its allocation
+            if (dict.dict_entries_len == 0) {
+                const data_bytes = dict.capacity() * slotSize(key_width, value_width);
+                decref(dict.dict_bytes, data_bytes, alignment);
+                output.* = RocDict.empty();
+                return;
+            }
+
+            output.* = dict;
+        },
+    }
+}
+
+// Dict.contains : Dict k v, k -> Bool
+pub fn dictContains(dict: RocDict, alignment: Alignment, key: Opaque, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn) callconv(.C) bool {
+    switch (dict.findIndex(alignment, key, key_width, value_width, hash_fn, is_eq)) {
+        MaybeIndex.not_found => {
+            return false;
+        },
+        MaybeIndex.index => |_| {
+            return true;
+        },
+    }
+}
+
+// Dict.get : Dict k v, k -> { flag: bool, value: Opaque }
+pub fn dictGet(dict: RocDict, alignment: Alignment, key: Opaque, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn, inc_value: Inc) callconv(.C) extern struct { value: Opaque, flag: bool } {
+    switch (dict.findIndex(alignment, key, key_width, value_width, hash_fn, is_eq)) {
+        MaybeIndex.not_found => {
+            return .{ .flag = false, .value = null };
+        },
+        MaybeIndex.index => |index| {
+            var value = dict.getValue(index, alignment, key_width, value_width);
+            inc_value(value);
+            return .{ .flag = true, .value = value };
+        },
+    }
+}
+
+// Dict.elementsRc
+// increment or decrement all dict elements (but not the dict's allocation itself)
+pub fn elementsRc(dict: RocDict, alignment: Alignment, key_width: usize, value_width: usize, modify_key: Inc, modify_value: Inc) callconv(.C) void {
+    const size = dict.capacity();
+
+    var i: usize = 0;
+    while (i < size) : (i += 1) {
+        switch (dict.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                modify_key(dict.getKey(i, alignment, key_width, value_width));
+                modify_value(dict.getValue(i, alignment, key_width, value_width));
+            },
+            else => {},
+        }
+    }
+}
+
+pub fn dictKeys(
+    dict: RocDict,
+    alignment: Alignment,
+    key_width: usize,
+    value_width: usize,
+    inc_key: Inc,
+) callconv(.C) RocList {
+    const size = dict.capacity();
+
+    var length: usize = 0;
+    var i: usize = 0;
+    while (i < size) : (i += 1) {
+        switch (dict.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                length += 1;
+            },
+            else => {},
+        }
+    }
+
+    if (length == 0) {
+        return RocList.empty();
+    }
+
+    const data_bytes = length * key_width;
+    var ptr = allocateWithRefcount(data_bytes, alignment);
+
+    i = 0;
+    var copied: usize = 0;
+    while (i < size) : (i += 1) {
+        switch (dict.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                const key = dict.getKey(i, alignment, key_width, value_width);
+                inc_key(key);
+
+                const key_cast = @ptrCast([*]const u8, key);
+                @memcpy(ptr + (copied * key_width), key_cast, key_width);
+                copied += 1;
+            },
+            else => {},
+        }
+    }
+
+    return RocList{ .bytes = ptr, .length = length, .capacity = length };
+}
+
+pub fn dictValues(
+    dict: RocDict,
+    alignment: Alignment,
+    key_width: usize,
+    value_width: usize,
+    inc_value: Inc,
+) callconv(.C) RocList {
+    const size = dict.capacity();
+
+    var length: usize = 0;
+    var i: usize = 0;
+    while (i < size) : (i += 1) {
+        switch (dict.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                length += 1;
+            },
+            else => {},
+        }
+    }
+
+    if (length == 0) {
+        return RocList.empty();
+    }
+
+    const data_bytes = length * value_width;
+    var ptr = allocateWithRefcount(data_bytes, alignment);
+
+    i = 0;
+    var copied: usize = 0;
+    while (i < size) : (i += 1) {
+        switch (dict.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                const value = dict.getValue(i, alignment, key_width, value_width);
+                inc_value(value);
+
+                const value_cast = @ptrCast([*]const u8, value);
+                @memcpy(ptr + (copied * value_width), value_cast, value_width);
+                copied += 1;
+            },
+            else => {},
+        }
+    }
+
+    return RocList{ .bytes = ptr, .length = length, .capacity = length };
+}
+
+fn doNothing(_: Opaque) callconv(.C) void {
+    return;
+}
+
+pub fn dictUnion(
+    dict1: RocDict,
+    dict2: RocDict,
+    alignment: Alignment,
+    key_width: usize,
+    value_width: usize,
+    hash_fn: HashFn,
+    is_eq: EqFn,
+    inc_key: Inc,
+    inc_value: Inc,
+    output: *RocDict,
+) callconv(.C) void {
+    output.* = dict1.makeUnique(alignment, key_width, value_width);
+
+    var i: usize = 0;
+    while (i < dict2.capacity()) : (i += 1) {
+        switch (dict2.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                const key = dict2.getKey(i, alignment, key_width, value_width);
+
+                switch (output.findIndex(alignment, key, key_width, value_width, hash_fn, is_eq)) {
+                    MaybeIndex.not_found => {
+                        const value = dict2.getValue(i, alignment, key_width, value_width);
+                        inc_value(value);
+
+                        // we need an extra RC token for the key
+                        inc_key(key);
+                        inc_value(value);
+
+                        // we know the newly added key is not a duplicate, so the `dec`s are unreachable
+                        const dec_key = doNothing;
+                        const dec_value = doNothing;
+
+                        dictInsert(output.*, alignment, key, key_width, value, value_width, hash_fn, is_eq, dec_key, dec_value, output);
+                    },
+                    MaybeIndex.index => |_| {
+                        // the key is already in the output dict
+                        continue;
+                    },
+                }
+            },
+            else => {},
+        }
+    }
+}
+
+pub fn dictIntersection(dict1: RocDict, dict2: RocDict, alignment: Alignment, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn, dec_key: Inc, dec_value: Inc, output: *RocDict) callconv(.C) void {
+    output.* = dict1.makeUnique(alignment, key_width, value_width);
+
+    var i: usize = 0;
+    const size = dict1.capacity();
+    while (i < size) : (i += 1) {
+        switch (output.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                const key = dict1.getKey(i, alignment, key_width, value_width);
+
+                switch (dict2.findIndex(alignment, key, key_width, value_width, hash_fn, is_eq)) {
+                    MaybeIndex.not_found => {
+                        dictRemove(output.*, alignment, key, key_width, value_width, hash_fn, is_eq, dec_key, dec_value, output);
+                    },
+                    MaybeIndex.index => |_| {
+                        // keep this key/value
+                        continue;
+                    },
+                }
+            },
+            else => {},
+        }
+    }
+}
+
+pub fn dictDifference(dict1: RocDict, dict2: RocDict, alignment: Alignment, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn, dec_key: Dec, dec_value: Dec, output: *RocDict) callconv(.C) void {
+    output.* = dict1.makeUnique(alignment, key_width, value_width);
+
+    var i: usize = 0;
+    const size = dict1.capacity();
+    while (i < size) : (i += 1) {
+        switch (output.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                const key = dict1.getKey(i, alignment, key_width, value_width);
+
+                switch (dict2.findIndex(alignment, key, key_width, value_width, hash_fn, is_eq)) {
+                    MaybeIndex.not_found => {
+                        // keep this key/value
+                        continue;
+                    },
+                    MaybeIndex.index => |_| {
+                        dictRemove(output.*, alignment, key, key_width, value_width, hash_fn, is_eq, dec_key, dec_value, output);
+                    },
+                }
+            },
+            else => {},
+        }
+    }
+}
+
+pub fn setFromList(list: RocList, alignment: Alignment, key_width: usize, value_width: usize, hash_fn: HashFn, is_eq: EqFn, dec_key: Dec, output: *RocDict) callconv(.C) void {
+    output.* = RocDict.empty();
+
+    var ptr = @ptrCast([*]u8, list.bytes);
+
+    const dec_value = doNothing;
+    const value = null;
+
+    const size = list.length;
+    var i: usize = 0;
+    while (i < size) : (i += 1) {
+        const key = ptr + i * key_width;
+        dictInsert(output.*, alignment, key, key_width, value, value_width, hash_fn, is_eq, dec_key, dec_value, output);
+    }
+
+    // NOTE: decref checks for the empty case
+    const data_bytes = size * key_width;
+    decref(list.bytes, data_bytes, alignment);
+}
+
+pub fn dictWalk(
+    dict: RocDict,
+    caller: Caller3,
+    data: Opaque,
+    inc_n_data: IncN,
+    data_is_owned: bool,
+    accum: Opaque,
+    alignment: Alignment,
+    key_width: usize,
+    value_width: usize,
+    accum_width: usize,
+    output: Opaque,
+) callconv(.C) void {
+    const alignment_u32 = alignment.toU32();
+    // allocate space to write the result of the stepper into
+    // experimentally aliasing the accum and output pointers is not a good idea
+    // TODO handle alloc failing!
+    const bytes_ptr: [*]u8 = utils.alloc(accum_width, alignment_u32) orelse unreachable;
+    var b1 = output orelse unreachable;
+    var b2 = bytes_ptr;
+
+    if (data_is_owned) {
+        inc_n_data(data, dict.len());
+    }
+
+    @memcpy(b2, accum orelse unreachable, accum_width);
+
+    var i: usize = 0;
+    const size = dict.capacity();
+    while (i < size) : (i += 1) {
+        switch (dict.getSlot(i, key_width, value_width)) {
+            Slot.Filled => {
+                const key = dict.getKey(i, alignment, key_width, value_width);
+                const value = dict.getValue(i, alignment, key_width, value_width);
+
+                caller(data, b2, key, value, b1);
+
+                std.mem.swap([*]u8, &b1, &b2);
+            },
+            else => {},
+        }
+    }
+
+    @memcpy(output orelse unreachable, b2, accum_width);
+    utils.dealloc(bytes_ptr, alignment_u32);
+}

crates/compiler/builtins/bitcode/src/hash.zig

@@ -0,0 +1,254 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2015-2021 Zig Contributors
+// This file is part of [zig](https://ziglang.org/), which is MIT licensed.
+// The MIT license requires this copyright notice to be included in all copies
+// and substantial portions of the software.
+const std = @import("std");
+const str = @import("str.zig");
+const mem = std.mem;
+
+pub fn wyhash(seed: u64, bytes: ?[*]const u8, length: usize) callconv(.C) u64 {
+    if (bytes) |nonnull| {
+        const slice = nonnull[0..length];
+        return wyhash_hash(seed, slice);
+    } else {
+        return 42;
+    }
+}
+
+pub fn wyhash_rocstr(seed: u64, input: str.RocStr) callconv(.C) u64 {
+    return wyhash_hash(seed, input.asSlice());
+}
+
+const primes = [_]u64{
+    0xa0761d6478bd642f,
+    0xe7037ed1a0b428db,
+    0x8ebc6af09c88c6e3,
+    0x589965cc75374cc3,
+    0x1d8e4e27c47d124f,
+};
+
+fn read_bytes(comptime bytes: u8, data: []const u8) u64 {
+    const T = std.meta.Int(.unsigned, 8 * bytes);
+    return mem.readIntLittle(T, data[0..bytes]);
+}
+
+fn read_8bytes_swapped(data: []const u8) u64 {
+    return (read_bytes(4, data) << 32 | read_bytes(4, data[4..]));
+}
+
+fn mum(a: u64, b: u64) u64 {
+    var r = std.math.mulWide(u64, a, b);
+    r = (r >> 64) ^ r;
+    return @truncate(u64, r);
+}
+
+fn mix0(a: u64, b: u64, seed: u64) u64 {
+    return mum(a ^ seed ^ primes[0], b ^ seed ^ primes[1]);
+}
+
+fn mix1(a: u64, b: u64, seed: u64) u64 {
+    return mum(a ^ seed ^ primes[2], b ^ seed ^ primes[3]);
+}
+
+// Wyhash version which does not store internal state for handling partial buffers.
+// This is needed so that we can maximize the speed for the short key case, which will
+// use the non-iterative api which the public Wyhash exposes.
+const WyhashStateless = struct {
+    seed: u64,
+    msg_len: usize,
+
+    pub fn init(seed: u64) WyhashStateless {
+        return WyhashStateless{
+            .seed = seed,
+            .msg_len = 0,
+        };
+    }
+
+    fn round(self: *WyhashStateless, b: []const u8) void {
+        std.debug.assert(b.len == 32);
+
+        self.seed = mix0(
+            read_bytes(8, b[0..]),
+            read_bytes(8, b[8..]),
+            self.seed,
+        ) ^ mix1(
+            read_bytes(8, b[16..]),
+            read_bytes(8, b[24..]),
+            self.seed,
+        );
+    }
+
+    pub fn update(self: *WyhashStateless, b: []const u8) void {
+        std.debug.assert(b.len % 32 == 0);
+
+        var off: usize = 0;
+        while (off < b.len) : (off += 32) {
+            @call(.{ .modifier = .always_inline }, self.round, .{b[off .. off + 32]});
+        }
+
+        self.msg_len += b.len;
+    }
+
+    pub fn final(self: *WyhashStateless, b: []const u8) u64 {
+        std.debug.assert(b.len < 32);
+
+        const seed = self.seed;
+        const rem_len = @intCast(u5, b.len);
+        const rem_key = b[0..rem_len];
+
+        self.seed = switch (rem_len) {
+            0 => seed,
+            1 => mix0(read_bytes(1, rem_key), primes[4], seed),
+            2 => mix0(read_bytes(2, rem_key), primes[4], seed),
+            3 => mix0((read_bytes(2, rem_key) << 8) | read_bytes(1, rem_key[2..]), primes[4], seed),
+            4 => mix0(read_bytes(4, rem_key), primes[4], seed),
+            5 => mix0((read_bytes(4, rem_key) << 8) | read_bytes(1, rem_key[4..]), primes[4], seed),
+            6 => mix0((read_bytes(4, rem_key) << 16) | read_bytes(2, rem_key[4..]), primes[4], seed),
+            7 => mix0((read_bytes(4, rem_key) << 24) | (read_bytes(2, rem_key[4..]) << 8) | read_bytes(1, rem_key[6..]), primes[4], seed),
+            8 => mix0(read_8bytes_swapped(rem_key), primes[4], seed),
+            9 => mix0(read_8bytes_swapped(rem_key), read_bytes(1, rem_key[8..]), seed),
+            10 => mix0(read_8bytes_swapped(rem_key), read_bytes(2, rem_key[8..]), seed),
+            11 => mix0(read_8bytes_swapped(rem_key), (read_bytes(2, rem_key[8..]) << 8) | read_bytes(1, rem_key[10..]), seed),
+            12 => mix0(read_8bytes_swapped(rem_key), read_bytes(4, rem_key[8..]), seed),
+            13 => mix0(read_8bytes_swapped(rem_key), (read_bytes(4, rem_key[8..]) << 8) | read_bytes(1, rem_key[12..]), seed),
+            14 => mix0(read_8bytes_swapped(rem_key), (read_bytes(4, rem_key[8..]) << 16) | read_bytes(2, rem_key[12..]), seed),
+            15 => mix0(read_8bytes_swapped(rem_key), (read_bytes(4, rem_key[8..]) << 24) | (read_bytes(2, rem_key[12..]) << 8) | read_bytes(1, rem_key[14..]), seed),
+            16 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed),
+            17 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_bytes(1, rem_key[16..]), primes[4], seed),
+            18 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_bytes(2, rem_key[16..]), primes[4], seed),
+            19 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1((read_bytes(2, rem_key[16..]) << 8) | read_bytes(1, rem_key[18..]), primes[4], seed),
+            20 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_bytes(4, rem_key[16..]), primes[4], seed),
+            21 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1((read_bytes(4, rem_key[16..]) << 8) | read_bytes(1, rem_key[20..]), primes[4], seed),
+            22 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1((read_bytes(4, rem_key[16..]) << 16) | read_bytes(2, rem_key[20..]), primes[4], seed),
+            23 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1((read_bytes(4, rem_key[16..]) << 24) | (read_bytes(2, rem_key[20..]) << 8) | read_bytes(1, rem_key[22..]), primes[4], seed),
+            24 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), primes[4], seed),
+            25 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), read_bytes(1, rem_key[24..]), seed),
+            26 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), read_bytes(2, rem_key[24..]), seed),
+            27 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), (read_bytes(2, rem_key[24..]) << 8) | read_bytes(1, rem_key[26..]), seed),
+            28 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), read_bytes(4, rem_key[24..]), seed),
+            29 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), (read_bytes(4, rem_key[24..]) << 8) | read_bytes(1, rem_key[28..]), seed),
+            30 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), (read_bytes(4, rem_key[24..]) << 16) | read_bytes(2, rem_key[28..]), seed),
+            31 => mix0(read_8bytes_swapped(rem_key), read_8bytes_swapped(rem_key[8..]), seed) ^ mix1(read_8bytes_swapped(rem_key[16..]), (read_bytes(4, rem_key[24..]) << 24) | (read_bytes(2, rem_key[28..]) << 8) | read_bytes(1, rem_key[30..]), seed),
+        };
+
+        self.msg_len += b.len;
+        return mum(self.seed ^ self.msg_len, primes[4]);
+    }
+
+    pub fn hash(seed: u64, input: []const u8) u64 {
+        const aligned_len = input.len - (input.len % 32);
+
+        var c = WyhashStateless.init(seed);
+        @call(.{ .modifier = .always_inline }, c.update, .{input[0..aligned_len]});
+        return @call(.{ .modifier = .always_inline }, c.final, .{input[aligned_len..]});
+    }
+};
+
+/// Fast non-cryptographic 64bit hash function.
+/// See https://github.com/wangyi-fudan/wyhash
+pub const Wyhash = struct {
+    state: WyhashStateless,
+
+    buf: [32]u8,
+    buf_len: usize,
+
+    pub fn init(seed: u64) Wyhash {
+        return Wyhash{
+            .state = WyhashStateless.init(seed),
+            .buf = undefined,
+            .buf_len = 0,
+        };
+    }
+
+    pub fn update(self: *Wyhash, b: []const u8) void {
+        var off: usize = 0;
+
+        if (self.buf_len != 0 and self.buf_len + b.len >= 32) {
+            off += 32 - self.buf_len;
+            mem.copy(u8, self.buf[self.buf_len..], b[0..off]);
+            self.state.update(self.buf[0..]);
+            self.buf_len = 0;
+        }
+
+        const remain_len = b.len - off;
+        const aligned_len = remain_len - (remain_len % 32);
+        self.state.update(b[off .. off + aligned_len]);
+
+        mem.copy(u8, self.buf[self.buf_len..], b[off + aligned_len ..]);
+        self.buf_len += @intCast(u8, b[off + aligned_len ..].len);
+    }
+
+    pub fn final(self: *Wyhash) u64 {
+        // const seed = self.state.seed;
+        // const rem_len = @intCast(u5, self.buf_len);
+        const rem_key = self.buf[0..self.buf_len];
+
+        return self.state.final(rem_key);
+    }
+
+    pub fn hash(seed: u64, input: []const u8) u64 {
+        return WyhashStateless.hash(seed, input);
+    }
+};
+
+fn wyhash_hash(seed: u64, input: []const u8) u64 {
+    return Wyhash.hash(seed, input);
+}
+
+const expectEqual = std.testing.expectEqual;
+
+test "test vectors" {
+    const hash = Wyhash.hash;
+
+    try expectEqual(hash(0, ""), 0x0);
+    try expectEqual(hash(1, "a"), 0xbed235177f41d328);
+    try expectEqual(hash(2, "abc"), 0xbe348debe59b27c3);
+    try expectEqual(hash(3, "message digest"), 0x37320f657213a290);
+    try expectEqual(hash(4, "abcdefghijklmnopqrstuvwxyz"), 0xd0b270e1d8a7019c);
+    try expectEqual(hash(5, "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"), 0x602a1894d3bbfe7f);
+    try expectEqual(hash(6, "12345678901234567890123456789012345678901234567890123456789012345678901234567890"), 0x829e9c148b75970e);
+}
+
+test "test vectors streaming" {
+    var wh = Wyhash.init(5);
+    for ("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789") |e| {
+        wh.update(mem.asBytes(&e));
+    }
+    try expectEqual(wh.final(), 0x602a1894d3bbfe7f);
+
+    const pattern = "1234567890";
+    const count = 8;
+    const result = 0x829e9c148b75970e;
+    try expectEqual(Wyhash.hash(6, pattern ** 8), result);
+
+    wh = Wyhash.init(6);
+    var i: u32 = 0;
+    while (i < count) : (i += 1) {
+        wh.update(pattern);
+    }
+    try expectEqual(wh.final(), result);
+}
+
+test "iterative non-divisible update" {
+    var buf: [8192]u8 = undefined;
+    for (buf) |*e, i| {
+        e.* = @truncate(u8, i);
+    }
+
+    const seed = 0x128dad08f;
+
+    var end: usize = 32;
+    while (end < buf.len) : (end += 32) {
+        const non_iterative_hash = Wyhash.hash(seed, buf[0..end]);
+
+        var wy = Wyhash.init(seed);
+        var i: usize = 0;
+        while (i < end) : (i += 33) {
+            wy.update(buf[i..std.math.min(i + 33, end)]);
+        }
+        const iterative_hash = wy.final();
+
+        try std.testing.expectEqual(iterative_hash, non_iterative_hash);
+    }
+}

crates/compiler/builtins/bitcode/src/list.zig

@@ -0,0 +1,796 @@
+const std = @import("std");
+const utils = @import("utils.zig");
+const RocResult = utils.RocResult;
+const UpdateMode = utils.UpdateMode;
+const mem = std.mem;
+const math = std.math;
+
+const EqFn = fn (?[*]u8, ?[*]u8) callconv(.C) bool;
+const CompareFn = fn (?[*]u8, ?[*]u8, ?[*]u8) callconv(.C) u8;
+const Opaque = ?[*]u8;
+
+const Inc = fn (?[*]u8) callconv(.C) void;
+const IncN = fn (?[*]u8, usize) callconv(.C) void;
+const Dec = fn (?[*]u8) callconv(.C) void;
+const HasTagId = fn (u16, ?[*]u8) callconv(.C) extern struct { matched: bool, data: ?[*]u8 };
+
+pub const RocList = extern struct {
+    bytes: ?[*]u8,
+    length: usize,
+    capacity: usize,
+
+    pub fn len(self: RocList) usize {
+        return self.length;
+    }
+
+    pub fn isEmpty(self: RocList) bool {
+        return self.len() == 0;
+    }
+
+    pub fn empty() RocList {
+        return RocList{ .bytes = null, .length = 0, .capacity = 0 };
+    }
+
+    pub fn eql(self: RocList, other: RocList) bool {
+        if (self.len() != other.len()) {
+            return false;
+        }
+
+        // Their lengths are the same, and one is empty; they're both empty!
+        if (self.isEmpty()) {
+            return true;
+        }
+
+        var index: usize = 0;
+        const self_bytes = self.bytes orelse unreachable;
+        const other_bytes = other.bytes orelse unreachable;
+
+        while (index < self.len()) {
+            if (self_bytes[index] != other_bytes[index]) {
+                return false;
+            }
+
+            index += 1;
+        }
+
+        return true;
+    }
+
+    pub fn fromSlice(comptime T: type, slice: []const T) RocList {
+        if (slice.len == 0) {
+            return RocList.empty();
+        }
+
+        var list = allocate(@alignOf(T), slice.len, @sizeOf(T));
+
+        if (slice.len > 0) {
+            const dest = list.bytes orelse unreachable;
+            const src = @ptrCast([*]const u8, slice.ptr);
+            const num_bytes = slice.len * @sizeOf(T);
+
+            @memcpy(dest, src, num_bytes);
+        }
+
+        return list;
+    }
+
+    pub fn deinit(self: RocList, comptime T: type) void {
+        utils.decref(self.bytes, self.len(), @alignOf(T));
+    }
+
+    pub fn elements(self: RocList, comptime T: type) ?[*]T {
+        return @ptrCast(?[*]T, @alignCast(@alignOf(T), self.bytes));
+    }
+
+    pub fn isUnique(self: RocList) bool {
+        // the empty list is unique (in the sense that copying it will not leak memory)
+        if (self.isEmpty()) {
+            return true;
+        }
+
+        // otherwise, check if the refcount is one
+        const ptr: [*]usize = @ptrCast([*]usize, @alignCast(@alignOf(usize), self.bytes));
+        return (ptr - 1)[0] == utils.REFCOUNT_ONE;
+    }
+
+    pub fn allocate(
+        alignment: u32,
+        length: usize,
+        element_size: usize,
+    ) RocList {
+        const data_bytes = length * element_size;
+
+        return RocList{
+            .bytes = utils.allocateWithRefcount(data_bytes, alignment),
+            .length = length,
+            .capacity = length,
+        };
+    }
+
+    pub fn makeUniqueExtra(self: RocList, alignment: u32, element_width: usize, update_mode: UpdateMode) RocList {
+        if (update_mode == .InPlace) {
+            return self;
+        } else {
+            return self.makeUnique(alignment, element_width);
+        }
+    }
+
+    pub fn makeUnique(self: RocList, alignment: u32, element_width: usize) RocList {
+        if (self.isEmpty()) {
+            return self;
+        }
+
+        if (self.isUnique()) {
+            return self;
+        }
+
+        // unfortunately, we have to clone
+        var new_list = RocList.allocate(alignment, self.length, element_width);
+
+        var old_bytes: [*]u8 = @ptrCast([*]u8, self.bytes);
+        var new_bytes: [*]u8 = @ptrCast([*]u8, new_list.bytes);
+
+        const number_of_bytes = self.len() * element_width;
+        @memcpy(new_bytes, old_bytes, number_of_bytes);
+
+        // NOTE we fuse an increment of all keys/values with a decrement of the input dict
+        const data_bytes = self.len() * element_width;
+        utils.decref(self.bytes, data_bytes, alignment);
+
+        return new_list;
+    }
+
+    pub fn reallocate(
+        self: RocList,
+        alignment: u32,
+        new_length: usize,
+        element_width: usize,
+    ) RocList {
+        if (self.bytes) |source_ptr| {
+            if (self.isUnique()) {
+                const new_source = utils.unsafeReallocate(source_ptr, alignment, self.len(), new_length, element_width);
+
+                return RocList{ .bytes = new_source, .length = new_length, .capacity = new_length };
+            }
+        }
+
+        return self.reallocateFresh(alignment, new_length, element_width);
+    }
+
+    /// reallocate by explicitly making a new allocation and copying elements over
+    fn reallocateFresh(
+        self: RocList,
+        alignment: u32,
+        new_length: usize,
+        element_width: usize,
+    ) RocList {
+        const old_length = self.length;
+        const delta_length = new_length - old_length;
+
+        const data_bytes = new_length * element_width;
+        const first_slot = utils.allocateWithRefcount(data_bytes, alignment);
+
+        // transfer the memory
+
+        if (self.bytes) |source_ptr| {
+            const dest_ptr = first_slot;
+
+            @memcpy(dest_ptr, source_ptr, old_length * element_width);
+            @memset(dest_ptr + old_length * element_width, 0, delta_length * element_width);
+        }
+
+        const result = RocList{
+            .bytes = first_slot,
+            .length = new_length,
+            .capacity = new_length,
+        };
+
+        utils.decref(self.bytes, old_length * element_width, alignment);
+
+        return result;
+    }
+};
+
+const Caller0 = fn (?[*]u8, ?[*]u8) callconv(.C) void;
+const Caller1 = fn (?[*]u8, ?[*]u8, ?[*]u8) callconv(.C) void;
+const Caller2 = fn (?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8) callconv(.C) void;
+const Caller3 = fn (?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8) callconv(.C) void;
+const Caller4 = fn (?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8, ?[*]u8) callconv(.C) void;
+
+pub fn listMap(
+    list: RocList,
+    caller: Caller1,
+    data: Opaque,
+    inc_n_data: IncN,
+    data_is_owned: bool,
+    alignment: u32,
+    old_element_width: usize,
+    new_element_width: usize,
+) callconv(.C) RocList {
+    if (list.bytes) |source_ptr| {
+        const size = list.len();
+        var i: usize = 0;
+        const output = RocList.allocate(alignment, size, new_element_width);
+        const target_ptr = output.bytes orelse unreachable;
+
+        if (data_is_owned) {
+            inc_n_data(data, size);
+        }
+
+        while (i < size) : (i += 1) {
+            caller(data, source_ptr + (i * old_element_width), target_ptr + (i * new_element_width));
+        }
+
+        return output;
+    } else {
+        return RocList.empty();
+    }
+}
+
+fn decrementTail(list: RocList, start_index: usize, element_width: usize, dec: Dec) void {
+    if (list.bytes) |source| {
+        var i = start_index;
+        while (i < list.len()) : (i += 1) {
+            const element = source + i * element_width;
+            dec(element);
+        }
+    }
+}
+
+pub fn listMap2(
+    list1: RocList,
+    list2: RocList,
+    caller: Caller2,
+    data: Opaque,
+    inc_n_data: IncN,
+    data_is_owned: bool,
+    alignment: u32,
+    a_width: usize,
+    b_width: usize,
+    c_width: usize,
+    dec_a: Dec,
+    dec_b: Dec,
+) callconv(.C) RocList {
+    const output_length = std.math.min(list1.len(), list2.len());
+
+    // if the lists don't have equal length, we must consume the remaining elements
+    // In this case we consume by (recursively) decrementing the elements
+    decrementTail(list1, output_length, a_width, dec_a);
+    decrementTail(list2, output_length, b_width, dec_b);
+
+    if (data_is_owned) {
+        inc_n_data(data, output_length);
+    }
+
+    if (list1.bytes) |source_a| {
+        if (list2.bytes) |source_b| {
+            const output = RocList.allocate(alignment, output_length, c_width);
+            const target_ptr = output.bytes orelse unreachable;
+
+            var i: usize = 0;
+            while (i < output_length) : (i += 1) {
+                const element_a = source_a + i * a_width;
+                const element_b = source_b + i * b_width;
+                const target = target_ptr + i * c_width;
+                caller(data, element_a, element_b, target);
+            }
+
+            return output;
+        } else {
+            return RocList.empty();
+        }
+    } else {
+        return RocList.empty();
+    }
+}
+
+pub fn listMap3(
+    list1: RocList,
+    list2: RocList,
+    list3: RocList,
+    caller: Caller3,
+    data: Opaque,
+    inc_n_data: IncN,
+    data_is_owned: bool,
+    alignment: u32,
+    a_width: usize,
+    b_width: usize,
+    c_width: usize,
+    d_width: usize,
+    dec_a: Dec,
+    dec_b: Dec,
+    dec_c: Dec,
+) callconv(.C) RocList {
+    const smaller_length = std.math.min(list1.len(), list2.len());
+    const output_length = std.math.min(smaller_length, list3.len());
+
+    decrementTail(list1, output_length, a_width, dec_a);
+    decrementTail(list2, output_length, b_width, dec_b);
+    decrementTail(list3, output_length, c_width, dec_c);
+
+    if (data_is_owned) {
+        inc_n_data(data, output_length);
+    }
+
+    if (list1.bytes) |source_a| {
+        if (list2.bytes) |source_b| {
+            if (list3.bytes) |source_c| {
+                const output = RocList.allocate(alignment, output_length, d_width);
+                const target_ptr = output.bytes orelse unreachable;
+
+                var i: usize = 0;
+                while (i < output_length) : (i += 1) {
+                    const element_a = source_a + i * a_width;
+                    const element_b = source_b + i * b_width;
+                    const element_c = source_c + i * c_width;
+                    const target = target_ptr + i * d_width;
+
+                    caller(data, element_a, element_b, element_c, target);
+                }
+
+                return output;
+            } else {
+                return RocList.empty();
+            }
+        } else {
+            return RocList.empty();
+        }
+    } else {
+        return RocList.empty();
+    }
+}
+
+pub fn listMap4(
+    list1: RocList,
+    list2: RocList,
+    list3: RocList,
+    list4: RocList,
+    caller: Caller4,
+    data: Opaque,
+    inc_n_data: IncN,
+    data_is_owned: bool,
+    alignment: u32,
+    a_width: usize,
+    b_width: usize,
+    c_width: usize,
+    d_width: usize,
+    e_width: usize,
+    dec_a: Dec,
+    dec_b: Dec,
+    dec_c: Dec,
+    dec_d: Dec,
+) callconv(.C) RocList {
+    const output_length = std.math.min(std.math.min(list1.len(), list2.len()), std.math.min(list3.len(), list4.len()));
+
+    decrementTail(list1, output_length, a_width, dec_a);
+    decrementTail(list2, output_length, b_width, dec_b);
+    decrementTail(list3, output_length, c_width, dec_c);
+    decrementTail(list4, output_length, d_width, dec_d);
+
+    if (data_is_owned) {
+        inc_n_data(data, output_length);
+    }
+
+    if (list1.bytes) |source_a| {
+        if (list2.bytes) |source_b| {
+            if (list3.bytes) |source_c| {
+                if (list4.bytes) |source_d| {
+                    const output = RocList.allocate(alignment, output_length, e_width);
+                    const target_ptr = output.bytes orelse unreachable;
+
+                    var i: usize = 0;
+                    while (i < output_length) : (i += 1) {
+                        const element_a = source_a + i * a_width;
+                        const element_b = source_b + i * b_width;
+                        const element_c = source_c + i * c_width;
+                        const element_d = source_d + i * d_width;
+                        const target = target_ptr + i * e_width;
+
+                        caller(data, element_a, element_b, element_c, element_d, target);
+                    }
+
+                    return output;
+                } else {
+                    return RocList.empty();
+                }
+            } else {
+                return RocList.empty();
+            }
+        } else {
+            return RocList.empty();
+        }
+    } else {
+        return RocList.empty();
+    }
+}
+
+pub fn listWithCapacity(capacity: usize, alignment: u32, element_width: usize) callconv(.C) RocList {
+    var output = RocList.allocate(alignment, capacity, element_width);
+    output.length = 0;
+    return output;
+}
+
+pub fn listAppend(list: RocList, alignment: u32, element: Opaque, element_width: usize, update_mode: UpdateMode) callconv(.C) RocList {
+    const old_length = list.len();
+    var output: RocList = undefined;
+    if (update_mode == .InPlace and list.capacity >= old_length + 1) {
+        output = list;
+        output.length += 1;
+    } else {
+        output = list.reallocate(alignment, old_length + 1, element_width);
+    }
+
+    if (output.bytes) |target| {
+        if (element) |source| {
+            @memcpy(target + old_length * element_width, source, element_width);
+        }
+    }
+
+    return output;
+}
+
+pub fn listPrepend(list: RocList, alignment: u32, element: Opaque, element_width: usize) callconv(.C) RocList {
+    const old_length = list.len();
+    var output = list.reallocate(alignment, old_length + 1, element_width);
+
+    // can't use one memcpy here because source and target overlap
+    if (output.bytes) |target| {
+        var i: usize = old_length;
+
+        while (i > 0) {
+            i -= 1;
+
+            // move the ith element to the (i + 1)th position
+            @memcpy(target + (i + 1) * element_width, target + i * element_width, element_width);
+        }
+
+        // finally copy in the new first element
+        if (element) |source| {
+            @memcpy(target, source, element_width);
+        }
+    }
+
+    return output;
+}
+
+pub fn listSwap(
+    list: RocList,
+    alignment: u32,
+    element_width: usize,
+    index_1: usize,
+    index_2: usize,
+    update_mode: UpdateMode,
+) callconv(.C) RocList {
+    const size = list.len();
+    if (index_1 == index_2 or index_1 >= size or index_2 >= size) {
+        // Either index out of bounds so we just return
+        return list;
+    }
+
+    const newList = blk: {
+        if (update_mode == .InPlace) {
+            break :blk list;
+        } else {
+            break :blk list.makeUnique(alignment, element_width);
+        }
+    };
+
+    const source_ptr = @ptrCast([*]u8, newList.bytes);
+    swapElements(source_ptr, element_width, index_1, index_2);
+
+    return newList;
+}
+
+pub fn listSublist(
+    list: RocList,
+    alignment: u32,
+    element_width: usize,
+    start: usize,
+    len: usize,
+    dec: Dec,
+) callconv(.C) RocList {
+    if (len == 0) {
+        return RocList.empty();
+    }
+
+    if (list.bytes) |source_ptr| {
+        const size = list.len();
+
+        if (start >= size) {
+            return RocList.empty();
+        }
+
+        const keep_len = std.math.min(len, size - start);
+        const drop_start_len = start;
+        const drop_end_len = size - (start + keep_len);
+
+        // Decrement the reference counts of elements before `start`.
+        var i: usize = 0;
+        while (i < drop_start_len) : (i += 1) {
+            const element = source_ptr + i * element_width;
+            dec(element);
+        }
+
+        // Decrement the reference counts of elements after `start + keep_len`.
+        i = 0;
+        while (i < drop_end_len) : (i += 1) {
+            const element = source_ptr + (start + keep_len + i) * element_width;
+            dec(element);
+        }
+
+        if (start == 0 and list.isUnique()) {
+            var output = list;
+            output.length = keep_len;
+            return output;
+        } else {
+            const output = RocList.allocate(alignment, keep_len, element_width);
+            const target_ptr = output.bytes orelse unreachable;
+
+            @memcpy(target_ptr, source_ptr + start * element_width, keep_len * element_width);
+
+            utils.decref(list.bytes, size * element_width, alignment);
+
+            return output;
+        }
+    }
+
+    return RocList.empty();
+}
+
+pub fn listDropAt(
+    list: RocList,
+    alignment: u32,
+    element_width: usize,
+    drop_index: usize,
+    dec: Dec,
+) callconv(.C) RocList {
+    if (list.bytes) |source_ptr| {
+        const size = list.len();
+
+        if (drop_index >= size) {
+            return list;
+        }
+
+        if (drop_index < size) {
+            const element = source_ptr + drop_index * element_width;
+            dec(element);
+        }
+
+        // NOTE
+        // we need to return an empty list explicitly,
+        // because we rely on the pointer field being null if the list is empty
+        // which also requires duplicating the utils.decref call to spend the RC token
+        if (size < 2) {
+            utils.decref(list.bytes, size * element_width, alignment);
+            return RocList.empty();
+        }
+
+        if (list.isUnique()) {
+            var i = drop_index;
+            while (i < size) : (i += 1) {
+                const copy_target = source_ptr + i * element_width;
+                const copy_source = copy_target + element_width;
+                @memcpy(copy_target, copy_source, element_width);
+            }
+
+            var new_list = list;
+
+            new_list.length -= 1;
+            return new_list;
+        }
+
+        const output = RocList.allocate(alignment, size - 1, element_width);
+        const target_ptr = output.bytes orelse unreachable;
+
+        const head_size = drop_index * element_width;
+        @memcpy(target_ptr, source_ptr, head_size);
+
+        const tail_target = target_ptr + drop_index * element_width;
+        const tail_source = source_ptr + (drop_index + 1) * element_width;
+        const tail_size = (size - drop_index - 1) * element_width;
+        @memcpy(tail_target, tail_source, tail_size);
+
+        utils.decref(list.bytes, size * element_width, alignment);
+
+        return output;
+    } else {
+        return RocList.empty();
+    }
+}
+
+fn partition(source_ptr: [*]u8, transform: Opaque, wrapper: CompareFn, element_width: usize, low: isize, high: isize) isize {
+    const pivot = source_ptr + (@intCast(usize, high) * element_width);
+    var i = (low - 1); // Index of smaller element and indicates the right position of pivot found so far
+    var j = low;
+
+    while (j <= high - 1) : (j += 1) {
+        const current_elem = source_ptr + (@intCast(usize, j) * element_width);
+
+        const ordering = wrapper(transform, current_elem, pivot);
+        const order = @intToEnum(utils.Ordering, ordering);
+
+        switch (order) {
+            utils.Ordering.LT => {
+                // the current element is smaller than the pivot; swap it
+                i += 1;
+                swapElements(source_ptr, element_width, @intCast(usize, i), @intCast(usize, j));
+            },
+            utils.Ordering.EQ, utils.Ordering.GT => {},
+        }
+    }
+    swapElements(source_ptr, element_width, @intCast(usize, i + 1), @intCast(usize, high));
+    return (i + 1);
+}
+
+fn quicksort(source_ptr: [*]u8, transform: Opaque, wrapper: CompareFn, element_width: usize, low: isize, high: isize) void {
+    if (low < high) {
+        // partition index
+        const pi = partition(source_ptr, transform, wrapper, element_width, low, high);
+
+        _ = quicksort(source_ptr, transform, wrapper, element_width, low, pi - 1); // before pi
+        _ = quicksort(source_ptr, transform, wrapper, element_width, pi + 1, high); // after pi
+    }
+}
+
+pub fn listSortWith(
+    input: RocList,
+    caller: CompareFn,
+    data: Opaque,
+    inc_n_data: IncN,
+    data_is_owned: bool,
+    alignment: u32,
+    element_width: usize,
+) callconv(.C) RocList {
+    var list = input.makeUnique(alignment, element_width);
+
+    if (data_is_owned) {
+        inc_n_data(data, list.len());
+    }
+
+    if (list.bytes) |source_ptr| {
+        const low = 0;
+        const high: isize = @intCast(isize, list.len()) - 1;
+        quicksort(source_ptr, data, caller, element_width, low, high);
+    }
+
+    return list;
+}
+
+// SWAP ELEMENTS
+
+inline fn swapHelp(width: usize, temporary: [*]u8, ptr1: [*]u8, ptr2: [*]u8) void {
+    @memcpy(temporary, ptr1, width);
+    @memcpy(ptr1, ptr2, width);
+    @memcpy(ptr2, temporary, width);
+}
+
+fn swap(width_initial: usize, p1: [*]u8, p2: [*]u8) void {
+    const threshold: usize = 64;
+
+    var width = width_initial;
+
+    var ptr1 = p1;
+    var ptr2 = p2;
+
+    var buffer_actual: [threshold]u8 = undefined;
+    var buffer: [*]u8 = buffer_actual[0..];
+
+    while (true) {
+        if (width < threshold) {
+            swapHelp(width, buffer, ptr1, ptr2);
+            return;
+        } else {
+            swapHelp(threshold, buffer, ptr1, ptr2);
+
+            ptr1 += threshold;
+            ptr2 += threshold;
+
+            width -= threshold;
+        }
+    }
+}
+
+fn swapElements(source_ptr: [*]u8, element_width: usize, index_1: usize, index_2: usize) void {
+    var element_at_i = source_ptr + (index_1 * element_width);
+    var element_at_j = source_ptr + (index_2 * element_width);
+
+    return swap(element_width, element_at_i, element_at_j);
+}
+
+pub fn listConcat(list_a: RocList, list_b: RocList, alignment: u32, element_width: usize) callconv(.C) RocList {
+    if (list_a.isEmpty()) {
+        return list_b;
+    } else if (list_b.isEmpty()) {
+        return list_a;
+    } else if (!list_a.isEmpty() and list_a.isUnique()) {
+        const total_length: usize = list_a.len() + list_b.len();
+
+        if (list_a.bytes) |source| {
+            const new_source = utils.unsafeReallocate(
+                source,
+                alignment,
+                list_a.len(),
+                total_length,
+                element_width,
+            );
+
+            if (list_b.bytes) |source_b| {
+                @memcpy(new_source + list_a.len() * element_width, source_b, list_b.len() * element_width);
+            }
+
+            return RocList{ .bytes = new_source, .length = total_length, .capacity = total_length };
+        }
+    }
+    const total_length: usize = list_a.len() + list_b.len();
+
+    const output = RocList.allocate(alignment, total_length, element_width);
+
+    if (output.bytes) |target| {
+        if (list_a.bytes) |source| {
+            @memcpy(target, source, list_a.len() * element_width);
+        }
+        if (list_b.bytes) |source| {
+            @memcpy(target + list_a.len() * element_width, source, list_b.len() * element_width);
+        }
+    }
+
+    return output;
+}
+
+pub fn listReplaceInPlace(
+    list: RocList,
+    index: usize,
+    element: Opaque,
+    element_width: usize,
+    out_element: ?[*]u8,
+) callconv(.C) RocList {
+    // INVARIANT: bounds checking happens on the roc side
+    //
+    // at the time of writing, the function is implemented roughly as
+    // `if inBounds then LowLevelListReplace input index item else input`
+    // so we don't do a bounds check here. Hence, the list is also non-empty,
+    // because inserting into an empty list is always out of bounds
+    return listReplaceInPlaceHelp(list, index, element, element_width, out_element);
+}
+
+pub fn listReplace(
+    list: RocList,
+    alignment: u32,
+    index: usize,
+    element: Opaque,
+    element_width: usize,
+    out_element: ?[*]u8,
+) callconv(.C) RocList {
+    // INVARIANT: bounds checking happens on the roc side
+    //
+    // at the time of writing, the function is implemented roughly as
+    // `if inBounds then LowLevelListReplace input index item else input`
+    // so we don't do a bounds check here. Hence, the list is also non-empty,
+    // because inserting into an empty list is always out of bounds
+    return listReplaceInPlaceHelp(list.makeUnique(alignment, element_width), index, element, element_width, out_element);
+}
+
+inline fn listReplaceInPlaceHelp(
+    list: RocList,
+    index: usize,
+    element: Opaque,
+    element_width: usize,
+    out_element: ?[*]u8,
+) RocList {
+    // the element we will replace
+    var element_at_index = (list.bytes orelse undefined) + (index * element_width);
+
+    // copy out the old element
+    @memcpy(out_element orelse undefined, element_at_index, element_width);
+
+    // copy in the new element
+    @memcpy(element_at_index, element orelse undefined, element_width);
+
+    return list;
+}
+
+pub fn listIsUnique(
+    list: RocList,
+) callconv(.C) bool {
+    return list.isEmpty() or list.isUnique();
+}

crates/compiler/builtins/bitcode/src/main.zig

@@ -0,0 +1,313 @@
+const std = @import("std");
+const builtin = @import("builtin");
+const math = std.math;
+const utils = @import("utils.zig");
+
+const ROC_BUILTINS = "roc_builtins";
+const NUM = "num";
+const STR = "str";
+
+// Dec Module
+const dec = @import("dec.zig");
+
+comptime {
+    exportDecFn(dec.fromStr, "from_str");
+    exportDecFn(dec.fromF64C, "from_f64");
+    exportDecFn(dec.eqC, "eq");
+    exportDecFn(dec.neqC, "neq");
+    exportDecFn(dec.negateC, "negate");
+    exportDecFn(dec.divC, "div");
+
+    exportDecFn(dec.addC, "add_with_overflow");
+    exportDecFn(dec.addOrPanicC, "add_or_panic");
+    exportDecFn(dec.addSaturatedC, "add_saturated");
+
+    exportDecFn(dec.subC, "sub_with_overflow");
+    exportDecFn(dec.subOrPanicC, "sub_or_panic");
+    exportDecFn(dec.subSaturatedC, "sub_saturated");
+
+    exportDecFn(dec.mulC, "mul_with_overflow");
+    exportDecFn(dec.mulOrPanicC, "mul_or_panic");
+    exportDecFn(dec.mulSaturatedC, "mul_saturated");
+}
+
+// List Module
+const list = @import("list.zig");
+
+comptime {
+    exportListFn(list.listMap, "map");
+    exportListFn(list.listMap2, "map2");
+    exportListFn(list.listMap3, "map3");
+    exportListFn(list.listMap4, "map4");
+    exportListFn(list.listAppend, "append");
+    exportListFn(list.listPrepend, "prepend");
+    exportListFn(list.listWithCapacity, "with_capacity");
+    exportListFn(list.listSortWith, "sort_with");
+    exportListFn(list.listConcat, "concat");
+    exportListFn(list.listSublist, "sublist");
+    exportListFn(list.listDropAt, "drop_at");
+    exportListFn(list.listReplace, "replace");
+    exportListFn(list.listReplaceInPlace, "replace_in_place");
+    exportListFn(list.listSwap, "swap");
+    exportListFn(list.listIsUnique, "is_unique");
+}
+
+// Dict Module
+const dict = @import("dict.zig");
+const hash = @import("hash.zig");
+
+comptime {
+    exportDictFn(dict.dictLen, "len");
+    exportDictFn(dict.dictEmpty, "empty");
+    exportDictFn(dict.dictInsert, "insert");
+    exportDictFn(dict.dictRemove, "remove");
+    exportDictFn(dict.dictContains, "contains");
+    exportDictFn(dict.dictGet, "get");
+    exportDictFn(dict.elementsRc, "elementsRc");
+    exportDictFn(dict.dictKeys, "keys");
+    exportDictFn(dict.dictValues, "values");
+    exportDictFn(dict.dictUnion, "union");
+    exportDictFn(dict.dictIntersection, "intersection");
+    exportDictFn(dict.dictDifference, "difference");
+    exportDictFn(dict.dictWalk, "walk");
+
+    exportDictFn(dict.setFromList, "set_from_list");
+
+    exportDictFn(hash.wyhash, "hash");
+    exportDictFn(hash.wyhash_rocstr, "hash_str");
+}
+
+// Num Module
+const num = @import("num.zig");
+
+const INTEGERS = [_]type{ i8, i16, i32, i64, i128, u8, u16, u32, u64, u128 };
+const WIDEINTS = [_]type{ i16, i32, i64, i128, i256, u16, u32, u64, u128, u256 };
+const FLOATS = [_]type{ f32, f64 };
+const NUMBERS = INTEGERS ++ FLOATS;
+
+comptime {
+    exportNumFn(num.bytesToU16C, "bytes_to_u16");
+    exportNumFn(num.bytesToU32C, "bytes_to_u32");
+
+    inline for (INTEGERS) |T, i| {
+        num.exportPow(T, ROC_BUILTINS ++ "." ++ NUM ++ ".pow_int.");
+        num.exportDivCeil(T, ROC_BUILTINS ++ "." ++ NUM ++ ".div_ceil.");
+
+        num.exportRoundF32(T, ROC_BUILTINS ++ "." ++ NUM ++ ".round_f32.");
+        num.exportRoundF64(T, ROC_BUILTINS ++ "." ++ NUM ++ ".round_f64.");
+
+        num.exportAddWithOverflow(T, ROC_BUILTINS ++ "." ++ NUM ++ ".add_with_overflow.");
+        num.exportAddOrPanic(T, ROC_BUILTINS ++ "." ++ NUM ++ ".add_or_panic.");
+        num.exportAddSaturatedInt(T, ROC_BUILTINS ++ "." ++ NUM ++ ".add_saturated.");
+
+        num.exportSubWithOverflow(T, ROC_BUILTINS ++ "." ++ NUM ++ ".sub_with_overflow.");
+        num.exportSubOrPanic(T, ROC_BUILTINS ++ "." ++ NUM ++ ".sub_or_panic.");
+        num.exportSubSaturatedInt(T, ROC_BUILTINS ++ "." ++ NUM ++ ".sub_saturated.");
+
+        num.exportMulWithOverflow(T, WIDEINTS[i], ROC_BUILTINS ++ "." ++ NUM ++ ".mul_with_overflow.");
+        num.exportMulOrPanic(T, WIDEINTS[i], ROC_BUILTINS ++ "." ++ NUM ++ ".mul_or_panic.");
+        num.exportMulSaturatedInt(T, WIDEINTS[i], ROC_BUILTINS ++ "." ++ NUM ++ ".mul_saturated.");
+    }
+
+    inline for (INTEGERS) |FROM| {
+        inline for (INTEGERS) |TO| {
+            // We're exporting more than we need here, but that's okay.
+            num.exportToIntCheckingMax(FROM, TO, ROC_BUILTINS ++ "." ++ NUM ++ ".int_to_" ++ @typeName(TO) ++ "_checking_max.");
+            num.exportToIntCheckingMaxAndMin(FROM, TO, ROC_BUILTINS ++ "." ++ NUM ++ ".int_to_" ++ @typeName(TO) ++ "_checking_max_and_min.");
+        }
+    }
+
+    inline for (FLOATS) |T| {
+        num.exportAsin(T, ROC_BUILTINS ++ "." ++ NUM ++ ".asin.");
+        num.exportAcos(T, ROC_BUILTINS ++ "." ++ NUM ++ ".acos.");
+        num.exportAtan(T, ROC_BUILTINS ++ "." ++ NUM ++ ".atan.");
+
+        num.exportSin(T, ROC_BUILTINS ++ "." ++ NUM ++ ".sin.");
+        num.exportCos(T, ROC_BUILTINS ++ "." ++ NUM ++ ".cos.");
+
+        num.exportPow(T, ROC_BUILTINS ++ "." ++ NUM ++ ".pow.");
+        num.exportLog(T, ROC_BUILTINS ++ "." ++ NUM ++ ".log.");
+
+        num.exportAddWithOverflow(T, ROC_BUILTINS ++ "." ++ NUM ++ ".add_with_overflow.");
+        num.exportSubWithOverflow(T, ROC_BUILTINS ++ "." ++ NUM ++ ".sub_with_overflow.");
+        num.exportMulWithOverflow(T, T, ROC_BUILTINS ++ "." ++ NUM ++ ".mul_with_overflow.");
+
+        num.exportIsFinite(T, ROC_BUILTINS ++ "." ++ NUM ++ ".is_finite.");
+    }
+}
+
+// Str Module
+const str = @import("str.zig");
+comptime {
+    exportStrFn(str.init, "init");
+    exportStrFn(str.strToScalarsC, "to_scalars");
+    exportStrFn(str.strSplit, "str_split");
+    exportStrFn(str.strSplitInPlaceC, "str_split_in_place");
+    exportStrFn(str.countSegments, "count_segments");
+    exportStrFn(str.countGraphemeClusters, "count_grapheme_clusters");
+    exportStrFn(str.countUtf8Bytes, "count_utf8_bytes");
+    exportStrFn(str.startsWith, "starts_with");
+    exportStrFn(str.startsWithScalar, "starts_with_scalar");
+    exportStrFn(str.endsWith, "ends_with");
+    exportStrFn(str.strConcatC, "concat");
+    exportStrFn(str.strJoinWithC, "joinWith");
+    exportStrFn(str.strNumberOfBytes, "number_of_bytes");
+    exportStrFn(str.strFromFloatC, "from_float");
+    exportStrFn(str.strEqual, "equal");
+    exportStrFn(str.substringUnsafe, "substring_unsafe");
+    exportStrFn(str.getUnsafe, "get_unsafe");
+    exportStrFn(str.reserve, "reserve");
+    exportStrFn(str.getScalarUnsafe, "get_scalar_unsafe");
+    exportStrFn(str.appendScalar, "append_scalar");
+    exportStrFn(str.strToUtf8C, "to_utf8");
+    exportStrFn(str.fromUtf8C, "from_utf8");
+    exportStrFn(str.fromUtf8RangeC, "from_utf8_range");
+    exportStrFn(str.repeat, "repeat");
+    exportStrFn(str.strTrim, "trim");
+    exportStrFn(str.strTrimLeft, "trim_left");
+    exportStrFn(str.strTrimRight, "trim_right");
+
+    inline for (INTEGERS) |T| {
+        str.exportFromInt(T, ROC_BUILTINS ++ "." ++ STR ++ ".from_int.");
+        num.exportParseInt(T, ROC_BUILTINS ++ "." ++ STR ++ ".to_int.");
+    }
+
+    inline for (FLOATS) |T| {
+        num.exportParseFloat(T, ROC_BUILTINS ++ "." ++ STR ++ ".to_float.");
+    }
+}
+
+// Utils
+comptime {
+    exportUtilsFn(utils.test_panic, "test_panic");
+    exportUtilsFn(utils.increfC, "incref");
+    exportUtilsFn(utils.decrefC, "decref");
+    exportUtilsFn(utils.decrefCheckNullC, "decref_check_null");
+    exportUtilsFn(utils.allocateWithRefcountC, "allocate_with_refcount");
+
+    @export(utils.panic, .{ .name = "roc_builtins.utils." ++ "panic", .linkage = .Weak });
+
+    if (builtin.target.cpu.arch == .aarch64) {
+        @export(__roc_force_setjmp, .{ .name = "__roc_force_setjmp", .linkage = .Weak });
+        @export(__roc_force_longjmp, .{ .name = "__roc_force_longjmp", .linkage = .Weak });
+    }
+}
+
+// Utils continued - SJLJ
+// For tests (in particular test_gen), roc_panic is implemented in terms of
+// setjmp/longjmp. LLVM is unable to generate code for longjmp on AArch64 (https://github.com/rtfeldman/roc/issues/2965),
+// so instead we ask Zig to please provide implementations for us, which is does
+// (seemingly via musl).
+pub extern fn setjmp([*c]c_int) c_int;
+pub extern fn longjmp([*c]c_int, c_int) noreturn;
+pub extern fn _setjmp([*c]c_int) c_int;
+pub extern fn _longjmp([*c]c_int, c_int) noreturn;
+pub extern fn sigsetjmp([*c]c_int, c_int) c_int;
+pub extern fn siglongjmp([*c]c_int, c_int) noreturn;
+pub extern fn longjmperror() void;
+// Zig won't expose the externs (and hence link correctly) unless we force them to be used.
+fn __roc_force_setjmp(it: [*c]c_int) callconv(.C) c_int {
+    return setjmp(it);
+}
+fn __roc_force_longjmp(a0: [*c]c_int, a1: c_int) callconv(.C) noreturn {
+    longjmp(a0, a1);
+}
+
+// Export helpers - Must be run inside a comptime
+fn exportBuiltinFn(comptime func: anytype, comptime func_name: []const u8) void {
+    @export(func, .{ .name = "roc_builtins." ++ func_name, .linkage = .Strong });
+}
+fn exportNumFn(comptime func: anytype, comptime func_name: []const u8) void {
+    exportBuiltinFn(func, "num." ++ func_name);
+}
+fn exportStrFn(comptime func: anytype, comptime func_name: []const u8) void {
+    exportBuiltinFn(func, "str." ++ func_name);
+}
+fn exportDictFn(comptime func: anytype, comptime func_name: []const u8) void {
+    exportBuiltinFn(func, "dict." ++ func_name);
+}
+fn exportListFn(comptime func: anytype, comptime func_name: []const u8) void {
+    exportBuiltinFn(func, "list." ++ func_name);
+}
+fn exportDecFn(comptime func: anytype, comptime func_name: []const u8) void {
+    exportBuiltinFn(func, "dec." ++ func_name);
+}
+
+fn exportUtilsFn(comptime func: anytype, comptime func_name: []const u8) void {
+    exportBuiltinFn(func, "utils." ++ func_name);
+}
+
+// Custom panic function, as builtin Zig version errors during LLVM verification
+pub fn panic(message: []const u8, stacktrace: ?*std.builtin.StackTrace) noreturn {
+    if (builtin.is_test) {
+        std.debug.print("{s}: {?}", .{ message, stacktrace });
+    } else {
+        _ = message;
+        _ = stacktrace;
+    }
+
+    unreachable;
+}
+
+// Run all tests in imported modules
+// https://github.com/ziglang/zig/blob/master/lib/std/std.zig#L94
+test "" {
+    const testing = std.testing;
+
+    testing.refAllDecls(@This());
+}
+
+// For unclear reasons, sometimes this function is not linked in on some machines.
+// Therefore we provide it as LLVM bitcode and mark it as externally linked during our LLVM codegen
+//
+// Taken from
+// https://github.com/ziglang/zig/blob/85755c51d529e7d9b406c6bdf69ce0a0f33f3353/lib/std/special/compiler_rt/muloti4.zig
+//
+// Thank you Zig Contributors!
+
+// Export it as weak incase it is already linked in by something else.
+comptime {
+    @export(__muloti4, .{ .name = "__muloti4", .linkage = .Weak });
+}
+fn __muloti4(a: i128, b: i128, overflow: *c_int) callconv(.C) i128 {
+    // @setRuntimeSafety(std.builtin.is_test);
+
+    const min = @bitCast(i128, @as(u128, 1 << (128 - 1)));
+    const max = ~min;
+    overflow.* = 0;
+
+    const r = a *% b;
+    if (a == min) {
+        if (b != 0 and b != 1) {
+            overflow.* = 1;
+        }
+        return r;
+    }
+    if (b == min) {
+        if (a != 0 and a != 1) {
+            overflow.* = 1;
+        }
+        return r;
+    }
+
+    const sa = a >> (128 - 1);
+    const abs_a = (a ^ sa) -% sa;
+    const sb = b >> (128 - 1);
+    const abs_b = (b ^ sb) -% sb;
+
+    if (abs_a < 2 or abs_b < 2) {
+        return r;
+    }
+
+    if (sa == sb) {
+        if (abs_a > @divTrunc(max, abs_b)) {
+            overflow.* = 1;
+        }
+    } else {
+        if (abs_a > @divTrunc(min, -abs_b)) {
+            overflow.* = 1;
+        }
+    }
+
+    return r;
+}

crates/compiler/builtins/bitcode/src/num.zig

@@ -0,0 +1,462 @@
+const std = @import("std");
+const always_inline = std.builtin.CallOptions.Modifier.always_inline;
+const math = std.math;
+const RocList = @import("list.zig").RocList;
+const RocStr = @import("str.zig").RocStr;
+const WithOverflow = @import("utils.zig").WithOverflow;
+const roc_panic = @import("utils.zig").panic;
+
+pub fn NumParseResult(comptime T: type) type {
+    // on the roc side we sort by alignment; putting the errorcode last
+    // always works out (no number with smaller alignment than 1)
+    return extern struct {
+        value: T,
+        errorcode: u8, // 0 indicates success
+    };
+}
+
+pub const U256 = struct {
+    hi: u128,
+    lo: u128,
+};
+
+pub fn mul_u128(a: u128, b: u128) U256 {
+    var hi: u128 = undefined;
+    var lo: u128 = undefined;
+
+    const bits_in_dword_2: u32 = 64;
+    const lower_mask: u128 = math.maxInt(u128) >> bits_in_dword_2;
+
+    lo = (a & lower_mask) * (b & lower_mask);
+
+    var t = lo >> bits_in_dword_2;
+
+    lo &= lower_mask;
+
+    t += (a >> bits_in_dword_2) * (b & lower_mask);
+
+    lo += (t & lower_mask) << bits_in_dword_2;
+
+    hi = t >> bits_in_dword_2;
+
+    t = lo >> bits_in_dword_2;
+
+    lo &= lower_mask;
+
+    t += (b >> bits_in_dword_2) * (a & lower_mask);
+
+    lo += (t & lower_mask) << bits_in_dword_2;
+
+    hi += t >> bits_in_dword_2;
+
+    hi += (a >> bits_in_dword_2) * (b >> bits_in_dword_2);
+
+    return .{ .hi = hi, .lo = lo };
+}
+
+pub fn exportParseInt(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(buf: RocStr) callconv(.C) NumParseResult(T) {
+            // a radix of 0 will make zig determine the radix from the frefix:
+            //  * A prefix of "0b" implies radix=2,
+            //  * A prefix of "0o" implies radix=8,
+            //  * A prefix of "0x" implies radix=16,
+            //  * Otherwise radix=10 is assumed.
+            const radix = 0;
+            if (std.fmt.parseInt(T, buf.asSlice(), radix)) |success| {
+                return .{ .errorcode = 0, .value = success };
+            } else |_| {
+                return .{ .errorcode = 1, .value = 0 };
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportParseFloat(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(buf: RocStr) callconv(.C) NumParseResult(T) {
+            if (std.fmt.parseFloat(T, buf.asSlice())) |success| {
+                return .{ .errorcode = 0, .value = success };
+            } else |_| {
+                return .{ .errorcode = 1, .value = 0 };
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportPow(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(base: T, exp: T) callconv(.C) T {
+            return std.math.pow(T, base, exp);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportIsFinite(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) bool {
+            return std.math.isFinite(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportAsin(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) T {
+            return std.math.asin(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportAcos(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) T {
+            return std.math.acos(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportAtan(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) T {
+            return std.math.atan(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportSin(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) T {
+            return @sin(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportCos(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) T {
+            return @cos(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportLog(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: T) callconv(.C) T {
+            return @log(input);
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportRoundF32(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: f32) callconv(.C) T {
+            return @floatToInt(T, (@round(input)));
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportRoundF64(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: f64) callconv(.C) T {
+            return @floatToInt(T, (@round(input)));
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportDivCeil(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(a: T, b: T) callconv(.C) T {
+            return math.divCeil(T, a, b) catch @panic("TODO runtime exception for dividing by 0!");
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn ToIntCheckedResult(comptime T: type) type {
+    // On the Roc side we sort by alignment; putting the errorcode last
+    // always works out (no number with smaller alignment than 1).
+    return extern struct {
+        value: T,
+        out_of_bounds: bool,
+    };
+}
+
+pub fn exportToIntCheckingMax(comptime From: type, comptime To: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: From) callconv(.C) ToIntCheckedResult(To) {
+            if (input > std.math.maxInt(To)) {
+                return .{ .out_of_bounds = true, .value = 0 };
+            }
+            return .{ .out_of_bounds = false, .value = @intCast(To, input) };
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(From), .linkage = .Strong });
+}
+
+pub fn exportToIntCheckingMaxAndMin(comptime From: type, comptime To: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(input: From) callconv(.C) ToIntCheckedResult(To) {
+            if (input > std.math.maxInt(To) or input < std.math.minInt(To)) {
+                return .{ .out_of_bounds = true, .value = 0 };
+            }
+            return .{ .out_of_bounds = false, .value = @intCast(To, input) };
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(From), .linkage = .Strong });
+}
+
+pub fn bytesToU16C(arg: RocList, position: usize) callconv(.C) u16 {
+    return @call(.{ .modifier = always_inline }, bytesToU16, .{ arg, position });
+}
+
+fn bytesToU16(arg: RocList, position: usize) u16 {
+    const bytes = @ptrCast([*]const u8, arg.bytes);
+    return @bitCast(u16, [_]u8{ bytes[position], bytes[position + 1] });
+}
+
+pub fn bytesToU32C(arg: RocList, position: usize) callconv(.C) u32 {
+    return @call(.{ .modifier = always_inline }, bytesToU32, .{ arg, position });
+}
+
+fn bytesToU32(arg: RocList, position: usize) u32 {
+    const bytes = @ptrCast([*]const u8, arg.bytes);
+    return @bitCast(u32, [_]u8{ bytes[position], bytes[position + 1], bytes[position + 2], bytes[position + 3] });
+}
+
+fn addWithOverflow(comptime T: type, self: T, other: T) WithOverflow(T) {
+    switch (@typeInfo(T)) {
+        .Int => {
+            var answer: T = undefined;
+            const overflowed = @addWithOverflow(T, self, other, &answer);
+            return .{ .value = answer, .has_overflowed = overflowed };
+        },
+        else => {
+            const answer = self + other;
+            const overflowed = !std.math.isFinite(answer);
+            return .{ .value = answer, .has_overflowed = overflowed };
+        },
+    }
+}
+
+pub fn exportAddWithOverflow(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) WithOverflow(T) {
+            return @call(.{ .modifier = always_inline }, addWithOverflow, .{ T, self, other });
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportAddSaturatedInt(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) T {
+            const result = addWithOverflow(T, self, other);
+            if (result.has_overflowed) {
+                // We can unambiguously tell which way it wrapped, because we have N+1 bits including the overflow bit
+                if (result.value >= 0 and @typeInfo(T).Int.signedness == .signed) {
+                    return std.math.minInt(T);
+                } else {
+                    return std.math.maxInt(T);
+                }
+            } else {
+                return result.value;
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportAddOrPanic(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) T {
+            const result = addWithOverflow(T, self, other);
+            if (result.has_overflowed) {
+                roc_panic("integer addition overflowed!", 1);
+                unreachable;
+            } else {
+                return result.value;
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+fn subWithOverflow(comptime T: type, self: T, other: T) WithOverflow(T) {
+    switch (@typeInfo(T)) {
+        .Int => {
+            var answer: T = undefined;
+            const overflowed = @subWithOverflow(T, self, other, &answer);
+            return .{ .value = answer, .has_overflowed = overflowed };
+        },
+        else => {
+            const answer = self - other;
+            const overflowed = !std.math.isFinite(answer);
+            return .{ .value = answer, .has_overflowed = overflowed };
+        },
+    }
+}
+
+pub fn exportSubWithOverflow(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) WithOverflow(T) {
+            return @call(.{ .modifier = always_inline }, subWithOverflow, .{ T, self, other });
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportSubSaturatedInt(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) T {
+            const result = subWithOverflow(T, self, other);
+            if (result.has_overflowed) {
+                if (@typeInfo(T).Int.signedness == .unsigned) {
+                    return 0;
+                } else if (self < 0) {
+                    return std.math.minInt(T);
+                } else {
+                    return std.math.maxInt(T);
+                }
+            } else {
+                return result.value;
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportSubOrPanic(comptime T: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) T {
+            const result = subWithOverflow(T, self, other);
+            if (result.has_overflowed) {
+                roc_panic("integer subtraction overflowed!", 1);
+                unreachable;
+            } else {
+                return result.value;
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+fn mulWithOverflow(comptime T: type, comptime W: type, self: T, other: T) WithOverflow(T) {
+    switch (@typeInfo(T)) {
+        .Int => {
+            if (T == i128) {
+                const is_answer_negative = (self < 0) != (other < 0);
+                const max = std.math.maxInt(i128);
+                const min = std.math.minInt(i128);
+
+                const self_u128 = @intCast(u128, math.absInt(self) catch {
+                    if (other == 0) {
+                        return .{ .value = 0, .has_overflowed = false };
+                    } else if (other == 1) {
+                        return .{ .value = self, .has_overflowed = false };
+                    } else if (is_answer_negative) {
+                        return .{ .value = min, .has_overflowed = true };
+                    } else {
+                        return .{ .value = max, .has_overflowed = true };
+                    }
+                });
+
+                const other_u128 = @intCast(u128, math.absInt(other) catch {
+                    if (self == 0) {
+                        return .{ .value = 0, .has_overflowed = false };
+                    } else if (self == 1) {
+                        return .{ .value = other, .has_overflowed = false };
+                    } else if (is_answer_negative) {
+                        return .{ .value = min, .has_overflowed = true };
+                    } else {
+                        return .{ .value = max, .has_overflowed = true };
+                    }
+                });
+
+                const answer256: U256 = mul_u128(self_u128, other_u128);
+
+                if (is_answer_negative) {
+                    if (answer256.hi != 0 or answer256.lo > (1 << 127)) {
+                        return .{ .value = min, .has_overflowed = true };
+                    } else if (answer256.lo == (1 << 127)) {
+                        return .{ .value = min, .has_overflowed = false };
+                    } else {
+                        return .{ .value = -@intCast(i128, answer256.lo), .has_overflowed = false };
+                    }
+                } else {
+                    if (answer256.hi != 0 or answer256.lo > @intCast(u128, max)) {
+                        return .{ .value = max, .has_overflowed = true };
+                    } else {
+                        return .{ .value = @intCast(i128, answer256.lo), .has_overflowed = false };
+                    }
+                }
+            } else {
+                const self_wide: W = self;
+                const other_wide: W = other;
+                const answer: W = self_wide * other_wide;
+
+                const max: W = std.math.maxInt(T);
+                const min: W = std.math.minInt(T);
+
+                if (answer > max) {
+                    return .{ .value = max, .has_overflowed = true };
+                } else if (answer < min) {
+                    return .{ .value = min, .has_overflowed = true };
+                } else {
+                    return .{ .value = @intCast(T, answer), .has_overflowed = false };
+                }
+            }
+        },
+        else => {
+            const answer = self * other;
+            const overflowed = !std.math.isFinite(answer);
+            return .{ .value = answer, .has_overflowed = overflowed };
+        },
+    }
+}
+
+pub fn exportMulWithOverflow(comptime T: type, comptime W: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) WithOverflow(T) {
+            return @call(.{ .modifier = always_inline }, mulWithOverflow, .{ T, W, self, other });
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportMulSaturatedInt(comptime T: type, comptime W: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) T {
+            const result = @call(.{ .modifier = always_inline }, mulWithOverflow, .{ T, W, self, other });
+            return result.value;
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}
+
+pub fn exportMulOrPanic(comptime T: type, comptime W: type, comptime name: []const u8) void {
+    comptime var f = struct {
+        fn func(self: T, other: T) callconv(.C) T {
+            const result = @call(.{ .modifier = always_inline }, mulWithOverflow, .{ T, W, self, other });
+            if (result.has_overflowed) {
+                roc_panic("integer multiplication overflowed!", 1);
+                unreachable;
+            } else {
+                return result.value;
+            }
+        }
+    }.func;
+    @export(f, .{ .name = name ++ @typeName(T), .linkage = .Strong });
+}

crates/compiler/builtins/bitcode/src/utils.zig

@@ -0,0 +1,314 @@
+const std = @import("std");
+const always_inline = std.builtin.CallOptions.Modifier.always_inline;
+const Monotonic = std.builtin.AtomicOrder.Monotonic;
+
+pub fn WithOverflow(comptime T: type) type {
+    return extern struct { value: T, has_overflowed: bool };
+}
+
+// If allocation fails, this must cxa_throw - it must not return a null pointer!
+extern fn roc_alloc(size: usize, alignment: u32) callconv(.C) ?*anyopaque;
+
+// This should never be passed a null pointer.
+// If allocation fails, this must cxa_throw - it must not return a null pointer!
+extern fn roc_realloc(c_ptr: *anyopaque, new_size: usize, old_size: usize, alignment: u32) callconv(.C) ?*anyopaque;
+
+// This should never be passed a null pointer.
+extern fn roc_dealloc(c_ptr: *anyopaque, alignment: u32) callconv(.C) void;
+
+// Signals to the host that the program has panicked
+extern fn roc_panic(c_ptr: *const anyopaque, tag_id: u32) callconv(.C) void;
+
+// should work just like libc memcpy (we can't assume libc is present)
+extern fn roc_memcpy(dst: [*]u8, src: [*]u8, size: usize) callconv(.C) void;
+
+comptime {
+    const builtin = @import("builtin");
+    // During tests, use the testing allocators to satisfy these functions.
+    if (builtin.is_test) {
+        @export(testing_roc_alloc, .{ .name = "roc_alloc", .linkage = .Strong });
+        @export(testing_roc_realloc, .{ .name = "roc_realloc", .linkage = .Strong });
+        @export(testing_roc_dealloc, .{ .name = "roc_dealloc", .linkage = .Strong });
+        @export(testing_roc_panic, .{ .name = "roc_panic", .linkage = .Strong });
+        @export(testing_roc_memcpy, .{ .name = "roc_memcpy", .linkage = .Strong });
+    }
+}
+
+fn testing_roc_alloc(size: usize, _: u32) callconv(.C) ?*anyopaque {
+    return @ptrCast(?*anyopaque, std.testing.allocator.alloc(u8, size) catch unreachable);
+}
+
+fn testing_roc_realloc(c_ptr: *anyopaque, new_size: usize, old_size: usize, _: u32) callconv(.C) ?*anyopaque {
+    const ptr = @ptrCast([*]u8, @alignCast(2 * @alignOf(usize), c_ptr));
+    const slice = ptr[0..old_size];
+
+    return @ptrCast(?*anyopaque, std.testing.allocator.realloc(slice, new_size) catch unreachable);
+}
+
+fn testing_roc_dealloc(c_ptr: *anyopaque, _: u32) callconv(.C) void {
+    const ptr = @ptrCast([*]u8, @alignCast(2 * @alignOf(usize), c_ptr));
+
+    std.testing.allocator.destroy(ptr);
+}
+
+fn testing_roc_panic(c_ptr: *anyopaque, tag_id: u32) callconv(.C) void {
+    _ = c_ptr;
+    _ = tag_id;
+
+    @panic("Roc panicked");
+}
+
+fn testing_roc_memcpy(dest: *anyopaque, src: *anyopaque, bytes: usize) callconv(.C) ?*anyopaque {
+    const zig_dest = @ptrCast([*]u8, dest);
+    const zig_src = @ptrCast([*]u8, src);
+
+    @memcpy(zig_dest, zig_src, bytes);
+    return dest;
+}
+
+pub fn alloc(size: usize, alignment: u32) ?[*]u8 {
+    return @ptrCast(?[*]u8, @call(.{ .modifier = always_inline }, roc_alloc, .{ size, alignment }));
+}
+
+pub fn realloc(c_ptr: [*]u8, new_size: usize, old_size: usize, alignment: u32) [*]u8 {
+    return @ptrCast([*]u8, @call(.{ .modifier = always_inline }, roc_realloc, .{ c_ptr, new_size, old_size, alignment }));
+}
+
+pub fn dealloc(c_ptr: [*]u8, alignment: u32) void {
+    return @call(.{ .modifier = always_inline }, roc_dealloc, .{ c_ptr, alignment });
+}
+
+// must export this explicitly because right now it is not used from zig code
+pub fn panic(c_ptr: *const anyopaque, alignment: u32) callconv(.C) void {
+    return @call(.{ .modifier = always_inline }, roc_panic, .{ c_ptr, alignment });
+}
+
+pub fn memcpy(dst: [*]u8, src: [*]u8, size: usize) void {
+    @call(.{ .modifier = always_inline }, roc_memcpy, .{ dst, src, size });
+}
+
+// indirection because otherwise zig creates an alias to the panic function which our LLVM code
+// does not know how to deal with
+pub fn test_panic(c_ptr: *anyopaque, alignment: u32) callconv(.C) void {
+    _ = c_ptr;
+    _ = alignment;
+    // const cstr = @ptrCast([*:0]u8, c_ptr);
+
+    // const stderr = std.io.getStdErr().writer();
+    // stderr.print("Roc panicked: {s}!\n", .{cstr}) catch unreachable;
+
+    // std.c.exit(1);
+}
+
+pub const Inc = fn (?[*]u8) callconv(.C) void;
+pub const IncN = fn (?[*]u8, u64) callconv(.C) void;
+pub const Dec = fn (?[*]u8) callconv(.C) void;
+
+const REFCOUNT_MAX_ISIZE: isize = 0;
+pub const REFCOUNT_ONE_ISIZE: isize = std.math.minInt(isize);
+pub const REFCOUNT_ONE: usize = @bitCast(usize, REFCOUNT_ONE_ISIZE);
+
+pub const IntWidth = enum(u8) {
+    U8 = 0,
+    U16 = 1,
+    U32 = 2,
+    U64 = 3,
+    U128 = 4,
+    I8 = 5,
+    I16 = 6,
+    I32 = 7,
+    I64 = 8,
+    I128 = 9,
+};
+
+const Refcount = enum {
+    none,
+    normal,
+    atomic,
+};
+
+const RC_TYPE = Refcount.normal;
+
+pub fn increfC(ptr_to_refcount: *isize, amount: isize) callconv(.C) void {
+    if (RC_TYPE == Refcount.none) return;
+    var refcount = ptr_to_refcount.*;
+    if (refcount < REFCOUNT_MAX_ISIZE) {
+        switch (RC_TYPE) {
+            Refcount.normal => {
+                ptr_to_refcount.* = std.math.min(refcount + amount, REFCOUNT_MAX_ISIZE);
+            },
+            Refcount.atomic => {
+                var next = std.math.min(refcount + amount, REFCOUNT_MAX_ISIZE);
+                while (@cmpxchgWeak(isize, ptr_to_refcount, refcount, next, Monotonic, Monotonic)) |found| {
+                    refcount = found;
+                    next = std.math.min(refcount + amount, REFCOUNT_MAX_ISIZE);
+                }
+            },
+            Refcount.none => unreachable,
+        }
+    }
+}
+
+pub fn decrefC(
+    bytes_or_null: ?[*]isize,
+    alignment: u32,
+) callconv(.C) void {
+    // IMPORTANT: bytes_or_null is this case is expected to be a pointer to the refcount
+    // (NOT the start of the data, or the start of the allocation)
+
+    // this is of course unsafe, but we trust what we get from the llvm side
+    var bytes = @ptrCast([*]isize, bytes_or_null);
+
+    return @call(.{ .modifier = always_inline }, decref_ptr_to_refcount, .{ bytes, alignment });
+}
+
+pub fn decrefCheckNullC(
+    bytes_or_null: ?[*]u8,
+    alignment: u32,
+) callconv(.C) void {
+    if (bytes_or_null) |bytes| {
+        const isizes: [*]isize = @ptrCast([*]isize, @alignCast(@sizeOf(isize), bytes));
+        return @call(.{ .modifier = always_inline }, decref_ptr_to_refcount, .{ isizes - 1, alignment });
+    }
+}
+
+pub fn decref(
+    bytes_or_null: ?[*]u8,
+    data_bytes: usize,
+    alignment: u32,
+) void {
+    if (data_bytes == 0) {
+        return;
+    }
+
+    var bytes = bytes_or_null orelse return;
+
+    const isizes: [*]isize = @ptrCast([*]isize, @alignCast(@alignOf(isize), bytes));
+
+    decref_ptr_to_refcount(isizes - 1, alignment);
+}
+
+inline fn decref_ptr_to_refcount(
+    refcount_ptr: [*]isize,
+    alignment: u32,
+) void {
+    if (RC_TYPE == Refcount.none) return;
+    const extra_bytes = std.math.max(alignment, @sizeOf(usize));
+    switch (RC_TYPE) {
+        Refcount.normal => {
+            const refcount: isize = refcount_ptr[0];
+            if (refcount == REFCOUNT_ONE_ISIZE) {
+                dealloc(@ptrCast([*]u8, refcount_ptr) - (extra_bytes - @sizeOf(usize)), alignment);
+            } else if (refcount < REFCOUNT_MAX_ISIZE) {
+                refcount_ptr[0] = refcount - 1;
+            }
+        },
+        Refcount.atomic => {
+            if (refcount_ptr[0] < REFCOUNT_MAX_ISIZE) {
+                var last = @atomicRmw(isize, &refcount_ptr[0], std.builtin.AtomicRmwOp.Sub, 1, Monotonic);
+                if (last == REFCOUNT_ONE_ISIZE) {
+                    dealloc(@ptrCast([*]u8, refcount_ptr) - (extra_bytes - @sizeOf(usize)), alignment);
+                }
+            }
+        },
+        Refcount.none => unreachable,
+    }
+}
+
+pub fn allocateWithRefcountC(
+    data_bytes: usize,
+    element_alignment: u32,
+) callconv(.C) [*]u8 {
+    return allocateWithRefcount(data_bytes, element_alignment);
+}
+
+pub fn allocateWithRefcount(
+    data_bytes: usize,
+    element_alignment: u32,
+) [*]u8 {
+    const ptr_width = @sizeOf(usize);
+    const alignment = std.math.max(ptr_width, element_alignment);
+    const length = alignment + data_bytes;
+
+    var new_bytes: [*]u8 = alloc(length, alignment) orelse unreachable;
+
+    const data_ptr = new_bytes + alignment;
+    const refcount_ptr = @ptrCast([*]usize, @alignCast(ptr_width, data_ptr) - ptr_width);
+    refcount_ptr[0] = if (RC_TYPE == Refcount.none) REFCOUNT_MAX_ISIZE else REFCOUNT_ONE;
+
+    return data_ptr;
+}
+
+pub const CSlice = extern struct {
+    pointer: *anyopaque,
+    len: usize,
+};
+
+pub fn unsafeReallocate(
+    source_ptr: [*]u8,
+    alignment: u32,
+    old_length: usize,
+    new_length: usize,
+    element_width: usize,
+) [*]u8 {
+    const align_width: usize = std.math.max(alignment, @sizeOf(usize));
+
+    const old_width = align_width + old_length * element_width;
+    const new_width = align_width + new_length * element_width;
+
+    if (old_width == new_width) {
+        return source_ptr;
+    }
+
+    // TODO handle out of memory
+    // NOTE realloc will dealloc the original allocation
+    const old_allocation = source_ptr - align_width;
+    const new_allocation = realloc(old_allocation, new_width, old_width, alignment);
+
+    const new_source = @ptrCast([*]u8, new_allocation) + align_width;
+    return new_source;
+}
+
+pub const RocResult = extern struct {
+    bytes: ?[*]u8,
+
+    pub fn isOk(self: RocResult) bool {
+        // assumptions
+        //
+        // - the tag is the first field
+        // - the tag is usize bytes wide
+        // - Ok has tag_id 1, because Err < Ok
+        const usizes: [*]usize = @ptrCast([*]usize, @alignCast(@alignOf(usize), self.bytes));
+
+        return usizes[0] == 1;
+    }
+
+    pub fn isErr(self: RocResult) bool {
+        return !self.isOk();
+    }
+};
+
+pub const Ordering = enum(u8) {
+    EQ = 0,
+    GT = 1,
+    LT = 2,
+};
+
+pub const UpdateMode = enum(u8) {
+    Immutable = 0,
+    InPlace = 1,
+};
+
+test "increfC, refcounted data" {
+    var mock_rc: isize = REFCOUNT_ONE_ISIZE + 17;
+    var ptr_to_refcount: *isize = &mock_rc;
+    increfC(ptr_to_refcount, 2);
+    try std.testing.expectEqual(mock_rc, REFCOUNT_ONE_ISIZE + 19);
+}
+
+test "increfC, static data" {
+    var mock_rc: isize = REFCOUNT_MAX_ISIZE;
+    var ptr_to_refcount: *isize = &mock_rc;
+    increfC(ptr_to_refcount, 2);
+    try std.testing.expectEqual(mock_rc, REFCOUNT_MAX_ISIZE);
+}

crates/compiler/builtins/bitcode/tests/bitcode_test.rs

@@ -0,0 +1,64 @@
+#[macro_use]
+extern crate pretty_assertions;
+
+#[cfg(test)]
+mod bitcode {
+    use roc_builtins_bitcode::{count_segments_, str_split_};
+
+    #[test]
+    fn count_segments() {
+        assert_eq!(
+            count_segments_((&"hello there").as_bytes(), (&"hello").as_bytes()),
+            2
+        );
+        assert_eq!(
+            count_segments_((&"a\nb\nc").as_bytes(), (&"\n").as_bytes()),
+            3
+        );
+        assert_eq!(
+            count_segments_((&"str").as_bytes(), (&"delimiter").as_bytes()),
+            1
+        );
+    }
+
+    #[test]
+    fn str_split() {
+        fn splits_to(string: &str, delimiter: &str, expectation: &[&[u8]]) {
+            assert_eq!(
+                str_split_(
+                    &mut [(&"").as_bytes()].repeat(expectation.len()),
+                    &string.as_bytes(),
+                    &delimiter.as_bytes()
+                ),
+                expectation
+            );
+        }
+
+        splits_to(
+            "a!b!c",
+            "!",
+            &[(&"a").as_bytes(), (&"b").as_bytes(), (&"c").as_bytes()],
+        );
+
+        splits_to(
+            "a!?b!?c!?",
+            "!?",
+            &[
+                (&"a").as_bytes(),
+                (&"b").as_bytes(),
+                (&"c").as_bytes(),
+                (&"").as_bytes(),
+            ],
+        );
+
+        splits_to("abc", "!", &[(&"abc").as_bytes()]);
+
+        splits_to(
+            "tttttghittttt",
+            "ttttt",
+            &[(&"").as_bytes(), (&"ghi").as_bytes(), (&"").as_bytes()],
+        );
+
+        splits_to("def", "!!!!!!", &[(&"def").as_bytes()]);
+    }
+}

crates/compiler/builtins/build.rs

@@ -0,0 +1,237 @@
+use std::convert::AsRef;
+use std::env;
+use std::ffi::OsStr;
+use std::fs;
+use std::io;
+use std::path::Path;
+use std::process::Command;
+use std::str;
+
+#[cfg(target_os = "macos")]
+use tempfile::tempdir;
+
+/// To debug the zig code with debug prints, we need to disable the wasm code gen
+const DEBUG: bool = false;
+
+fn zig_executable() -> String {
+    match std::env::var("ROC_ZIG") {
+        Ok(path) => path,
+        Err(_) => "zig".into(),
+    }
+}
+
+fn main() {
+    println!("cargo:rerun-if-changed=build.rs");
+
+    // "." is relative to where "build.rs" is
+    // dunce can be removed once ziglang/zig#5109 is fixed
+    let build_script_dir_path = dunce::canonicalize(Path::new(".")).unwrap();
+    let bitcode_path = build_script_dir_path.join("bitcode");
+
+    // workaround for github.com/ziglang/zig/issues/9711
+    #[cfg(target_os = "macos")]
+    let zig_cache_dir = tempdir().expect("Failed to create temp directory for zig cache");
+    #[cfg(target_os = "macos")]
+    std::env::set_var("ZIG_GLOBAL_CACHE_DIR", zig_cache_dir.path().as_os_str());
+
+    // LLVM .bc FILES
+
+    generate_bc_file(&bitcode_path, "ir", "builtins-host");
+
+    if !DEBUG {
+        generate_bc_file(&bitcode_path, "ir-wasm32", "builtins-wasm32");
+    }
+
+    generate_bc_file(&bitcode_path, "ir-i386", "builtins-i386");
+
+    generate_bc_file(&bitcode_path, "ir-x86_64", "builtins-x86_64");
+
+    // OBJECT FILES
+    #[cfg(windows)]
+    const BUILTINS_HOST_FILE: &str = "builtins-host.obj";
+
+    #[cfg(not(windows))]
+    const BUILTINS_HOST_FILE: &str = "builtins-host.o";
+
+    generate_object_file(
+        &bitcode_path,
+        "BUILTINS_HOST_O",
+        "object",
+        BUILTINS_HOST_FILE,
+    );
+
+    generate_object_file(
+        &bitcode_path,
+        "BUILTINS_WASM32_O",
+        "wasm32-object",
+        "builtins-wasm32.o",
+    );
+
+    copy_zig_builtins_to_target_dir(&bitcode_path);
+
+    get_zig_files(bitcode_path.as_path(), &|path| {
+        let path: &Path = path;
+        println!(
+            "cargo:rerun-if-changed={}",
+            path.to_str().expect("Failed to convert path to str")
+        );
+    })
+    .unwrap();
+
+    #[cfg(target_os = "macos")]
+    zig_cache_dir
+        .close()
+        .expect("Failed to delete temp dir zig_cache_dir.");
+}
+
+fn generate_object_file(
+    bitcode_path: &Path,
+    env_var_name: &str,
+    zig_object: &str,
+    object_file_name: &str,
+) {
+    let out_dir = env::var_os("OUT_DIR").unwrap();
+
+    let dest_obj_path = Path::new(&out_dir).join(object_file_name);
+    let dest_obj = dest_obj_path.to_str().expect("Invalid dest object path");
+
+    // set the variable (e.g. BUILTINS_HOST_O) that is later used in
+    // `compiler/builtins/src/bitcode.rs` to load the object file
+    println!("cargo:rustc-env={}={}", env_var_name, dest_obj);
+
+    let src_obj_path = bitcode_path.join(object_file_name);
+    let src_obj = src_obj_path.to_str().expect("Invalid src object path");
+
+    println!("Compiling zig object `{}` to: {}", zig_object, src_obj);
+
+    if !DEBUG {
+        run_command(
+            &bitcode_path,
+            &zig_executable(),
+            &["build", zig_object, "-Drelease=true"],
+        );
+
+        println!("Moving zig object `{}` to: {}", zig_object, dest_obj);
+
+        // we store this .o file in rust's `target` folder (for wasm we need to leave a copy here too)
+        fs::copy(src_obj, dest_obj).unwrap_or_else(|err| {
+            panic!(
+                "Failed to copy object file {} to {}: {:?}",
+                src_obj, dest_obj, err
+            );
+        });
+    }
+}
+
+fn generate_bc_file(bitcode_path: &Path, zig_object: &str, file_name: &str) {
+    let mut ll_path = bitcode_path.join(file_name);
+    ll_path.set_extension("ll");
+    let dest_ir_host = ll_path.to_str().expect("Invalid dest ir path");
+
+    println!("Compiling host ir to: {}", dest_ir_host);
+
+    let mut bc_path = bitcode_path.join(file_name);
+    bc_path.set_extension("bc");
+    let dest_bc_64bit = bc_path.to_str().expect("Invalid dest bc path");
+    println!("Compiling 64-bit bitcode to: {}", dest_bc_64bit);
+
+    // workaround for github.com/ziglang/zig/issues/9711
+    #[cfg(target_os = "macos")]
+    let _ = fs::remove_dir_all("./bitcode/zig-cache");
+
+    run_command(
+        &bitcode_path,
+        &zig_executable(),
+        &["build", zig_object, "-Drelease=true"],
+    );
+}
+
+fn copy_zig_builtins_to_target_dir(bitcode_path: &Path) {
+    // To enable roc to find the zig biultins, we want them to be moved to a folder next to the roc executable.
+    // So if <roc_folder>/roc is the executable. The zig files will be in <roc_folder>/lib/*.zig
+
+    // Currently we have the OUT_DIR variable which points to `/target/debug/build/roc_builtins-*/out/`.
+    // So we just need to shed a 3 of the outer layers to get `/target/debug/` and then add `lib`.
+    let out_dir = env::var_os("OUT_DIR").unwrap();
+    let target_profile_dir = Path::new(&out_dir)
+        .parent()
+        .and_then(|path| path.parent())
+        .and_then(|path| path.parent())
+        .unwrap()
+        .join("lib");
+
+    let zig_src_dir = bitcode_path.join("src");
+
+    std::fs::create_dir_all(&target_profile_dir).unwrap_or_else(|err| {
+        panic!(
+            "Failed to create output library directory for zig bitcode {:?}: {:?}",
+            target_profile_dir, err
+        );
+    });
+    let mut options = fs_extra::dir::CopyOptions::new();
+    options.content_only = true;
+    options.overwrite = true;
+    fs_extra::dir::copy(&zig_src_dir, &target_profile_dir, &options).unwrap_or_else(|err| {
+        panic!(
+            "Failed to copy zig bitcode files {:?} to {:?}: {:?}",
+            zig_src_dir, target_profile_dir, err
+        );
+    });
+}
+
+fn run_command<S, I: Copy, P: AsRef<Path> + Copy>(path: P, command_str: &str, args: I)
+where
+    I: IntoIterator<Item = S>,
+    S: AsRef<OsStr>,
+{
+    let output_result = Command::new(OsStr::new(&command_str))
+        .current_dir(path)
+        .args(args)
+        .output();
+
+    match output_result {
+        Ok(output) => match output.status.success() {
+            true => (),
+            false => {
+                let error_str = match str::from_utf8(&output.stderr) {
+                    Ok(stderr) => stderr.to_string(),
+                    Err(_) => format!("Failed to run \"{}\"", command_str),
+                };
+
+                // flaky test error that only occurs sometimes inside MacOS ci run
+                if error_str.contains("unable to build stage1 zig object: FileNotFound")
+                    || error_str.contains("unable to save cached ZIR code")
+                {
+                    run_command(path, command_str, args)
+                } else {
+                    panic!("{} failed: {}", command_str, error_str);
+                }
+            }
+        },
+        Err(reason) => panic!("{} failed: {}", command_str, reason),
+    }
+}
+
+fn get_zig_files(dir: &Path, cb: &dyn Fn(&Path)) -> io::Result<()> {
+    if dir.is_dir() {
+        for entry in fs::read_dir(dir)? {
+            let entry = entry?;
+            let path_buf = entry.path();
+            if path_buf.is_dir() {
+                if !path_buf.ends_with("zig-cache") {
+                    get_zig_files(&path_buf, cb).unwrap();
+                }
+            } else {
+                let path = path_buf.as_path();
+
+                match path.extension() {
+                    Some(osstr) if osstr == "zig" => {
+                        cb(path);
+                    }
+                    _ => {}
+                }
+            }
+        }
+    }
+    Ok(())
+}

crates/compiler/builtins/roc/Bool.roc

@@ -0,0 +1,83 @@
+interface Bool
+    exposes [Bool, and, or, not, isEq, isNotEq]
+    imports []
+
+Bool : [True, False]
+
+## Returns `True` when given `True` and `True`, and `False` when either argument is `False`.
+##
+## `a && b` is shorthand for `Bool.and a b`
+##
+## >>> True && True
+##
+## >>> True && False
+##
+## >>> False && True
+##
+## >>> False && False
+##
+## ## Performance Notes
+##
+## In some languages, `&&` and `||` are special-cased in the compiler to skip
+## evaluating the expression after the operator under certain circumstances.
+## For example, in some languages, `enablePets && likesDogs user` would compile
+## to the equivalent of:
+##
+##     if enablePets then
+##         likesDogs user
+##     else
+##         False
+##
+## In Roc, however, `&&` and `||` are not special. They work the same way as
+## other functions. Conditionals like `if` and `when` have a performance cost,
+## and sometimes calling a function like `likesDogs user` can be faster across
+## the board than doing an `if` to decide whether to skip calling it.
+##
+## (Naturally, if you expect the `if` to improve performance, you can always add
+## one explicitly!)
+and : Bool, Bool -> Bool
+
+## Returns `True` when given `True` for either argument, and `False` only when given `False` and `False`.
+##
+## `a || b` is shorthand for `Bool.or a b`.
+##
+## >>> True || True
+##
+## >>> True || False
+##
+## >>> False || True
+##
+## >>> False || False
+##
+## ## Performance Notes
+##
+## In some languages, `&&` and `||` are special-cased in the compiler to skip
+## evaluating the expression after the operator under certain circumstances.
+## In Roc, this is not the case. See the performance notes for [Bool.and] for details.
+or : Bool, Bool -> Bool
+# xor : Bool, Bool -> Bool # currently unimplemented
+## Returns `False` when given `True`, and vice versa.
+not : Bool -> Bool
+
+## Returns `True` if the two values are *structurally equal*, and `False` otherwise.
+##
+## `a == b` is shorthand for `Bool.isEq a b`
+##
+## Structural equality works as follows:
+##
+## 1. Tags are equal if they have the same tag name, and also their contents (if any) are equal.
+## 2. Records are equal if all their fields are equal.
+## 3. Collections ([Str], [List], [Dict], and [Set]) are equal if they are the same length, and also all their corresponding elements are equal.
+## 4. [Num](Num#Num) values are equal if their numbers are equal, with one exception: if both arguments to `isEq` are *NaN*, then `isEq` returns `False`. See `Num.isNaN` for more about *NaN*.
+##
+## Note that `isEq` takes `'val` instead of `val`, which means `isEq` does not
+## accept arguments whose types contain functions.
+isEq : a, a -> Bool
+
+## Calls [isEq] on the given values, then calls [not] on the result.
+##
+## `a != b` is shorthand for `Bool.isNotEq a b`
+##
+## Note that `isNotEq` takes `'val` instead of `val`, which means `isNotEq` does not
+## accept arguments whose types contain functions.
+isNotEq : a, a -> Bool

crates/compiler/builtins/roc/Box.roc

@@ -0,0 +1,15 @@
+interface Box
+    exposes [box, unbox]
+    imports []
+
+box : a -> Box a
+unbox : Box a -> a
+
+# # we'd need reset/reuse for box for this to be efficient
+# # that is currently not implemented
+# map : Box a, (a -> b) -> Box b
+# map = \boxed, transform =
+#     boxed
+#         |> Box.unbox
+#         |> transform
+#         |> Box.box

crates/compiler/builtins/roc/Dict.roc

@@ -0,0 +1,88 @@
+interface Dict
+    exposes
+        [
+            empty,
+            single,
+            get,
+            walk,
+            insert,
+            len,
+            remove,
+            contains,
+            keys,
+            values,
+            union,
+            intersection,
+            difference,
+        ]
+    imports
+        [
+            Bool.{ Bool },
+        ]
+
+## A [dictionary](https://en.wikipedia.org/wiki/Associative_array) that lets you can associate keys with values.
+##
+## ### Inserting
+##
+## The most basic way to use a dictionary is to start with an empty one and then:
+## 1. Call [Dict.insert] passing a key and a value, to associate that key with that value in the dictionary.
+## 2. Later, call [Dict.get] passing the same key as before, and it will return the value you stored.
+##
+## Here's an example of a dictionary which uses a city's name as the key, and its population as the associated value.
+##
+##     populationByCity =
+##         Dict.empty
+##             |> Dict.insert "London" 8_961_989
+##             |> Dict.insert "Philadelphia" 1_603_797
+##             |> Dict.insert "Shanghai" 24_870_895
+##             |> Dict.insert "Delhi" 16_787_941
+##             |> Dict.insert "Amsterdam" 872_680
+##
+## ### Accessing keys or values
+##
+## We can use [Dict.keys] and [Dict.values] functions to get only the keys or only the values.
+##
+## You may notice that these lists have the same order as the original insertion order. This will be true if
+## all you ever do is [insert] and [get] operations on the dictionary, but [remove] operations can change this order.
+## Let's see how that looks.
+##
+## ### Removing
+##
+## We can remove an element from the dictionary, like so:
+##
+##     populationByCity
+##         |> Dict.remove "Philadelphia"
+##         |> Dict.keys
+##         ==
+##         ["London", "Amsterdam", "Shanghai", "Delhi"]
+##
+## Notice that the order changed! Philadelphia has been not only removed from the list, but Amsterdam - the last
+## entry we inserted - has been moved into the spot where Philadelphia was previously. This is exactly what
+## [Dict.remove] does: it removes an element and moves the most recent insertion into the vacated spot.
+##
+## This move is done as a performance optimization, and it lets [remove] have
+## [constant time complexity](https://en.wikipedia.org/wiki/Time_complexity#Constant_time). ##
+##
+## ### Equality
+##
+## When comparing two dictionaries for equality, they are `==` only if their both their contents and their
+## orderings match. This preserves the property that if `dict1 == dict2`, you should be able to rely on
+## `fn dict1 == fn dict2` also being `True`, even if `fn` relies on the dictionary's ordering.
+## An empty dictionary.
+empty : Dict k v
+single : k, v -> Dict k v
+get : Dict k v, k -> Result v [KeyNotFound]*
+walk : Dict k v, state, (state, k, v -> state) -> state
+insert : Dict k v, k, v -> Dict k v
+len : Dict k v -> Nat
+remove : Dict k v, k -> Dict k v
+contains : Dict k v, k -> Bool
+
+## Returns a [List] of the dictionary's keys.
+keys : Dict k v -> List k
+
+## Returns a [List] of the dictionary's values.
+values : Dict k v -> List v
+union : Dict k v, Dict k v -> Dict k v
+intersection : Dict k v, Dict k v -> Dict k v
+difference : Dict k v, Dict k v -> Dict k v

crates/compiler/builtins/roc/Encode.roc

@@ -0,0 +1,69 @@
+interface Encode
+    exposes
+        [
+            Encoder,
+            Encoding,
+            toEncoder,
+            EncoderFormatting,
+            u8,
+            u16,
+            u32,
+            u64,
+            u128,
+            i8,
+            i16,
+            i32,
+            i64,
+            i128,
+            f32,
+            f64,
+            dec,
+            bool,
+            string,
+            list,
+            record,
+            tag,
+            custom,
+            appendWith,
+            append,
+            toBytes,
+        ]
+    imports
+        []
+
+Encoder fmt := List U8, fmt -> List U8 | fmt has EncoderFormatting
+
+Encoding has
+    toEncoder : val -> Encoder fmt | val has Encoding, fmt has EncoderFormatting
+
+EncoderFormatting has
+    u8 : U8 -> Encoder fmt | fmt has EncoderFormatting
+    u16 : U16 -> Encoder fmt | fmt has EncoderFormatting
+    u32 : U32 -> Encoder fmt | fmt has EncoderFormatting
+    u64 : U64 -> Encoder fmt | fmt has EncoderFormatting
+    u128 : U128 -> Encoder fmt | fmt has EncoderFormatting
+    i8 : I8 -> Encoder fmt | fmt has EncoderFormatting
+    i16 : I16 -> Encoder fmt | fmt has EncoderFormatting
+    i32 : I32 -> Encoder fmt | fmt has EncoderFormatting
+    i64 : I64 -> Encoder fmt | fmt has EncoderFormatting
+    i128 : I128 -> Encoder fmt | fmt has EncoderFormatting
+    f32 : F32 -> Encoder fmt | fmt has EncoderFormatting
+    f64 : F64 -> Encoder fmt | fmt has EncoderFormatting
+    dec : Dec -> Encoder fmt | fmt has EncoderFormatting
+    bool : Bool -> Encoder fmt | fmt has EncoderFormatting
+    string : Str -> Encoder fmt | fmt has EncoderFormatting
+    list : List elem, (elem -> Encoder fmt) -> Encoder fmt | fmt has EncoderFormatting
+    record : List { key : Str, value : Encoder fmt } -> Encoder fmt | fmt has EncoderFormatting
+    tag : Str, List (Encoder fmt) -> Encoder fmt | fmt has EncoderFormatting
+
+custom : (List U8, fmt -> List U8) -> Encoder fmt | fmt has EncoderFormatting
+custom = \encoder -> @Encoder encoder
+
+appendWith : List U8, Encoder fmt, fmt -> List U8 | fmt has EncoderFormatting
+appendWith = \lst, @Encoder doEncoding, fmt -> doEncoding lst fmt
+
+append : List U8, val, fmt -> List U8 | val has Encoding, fmt has EncoderFormatting
+append = \lst, val, fmt -> appendWith lst (toEncoder val) fmt
+
+toBytes : val, fmt -> List U8 | val has Encoding, fmt has EncoderFormatting
+toBytes = \val, fmt -> appendWith [] (toEncoder val) fmt

crates/compiler/builtins/roc/Json.roc

@@ -0,0 +1,135 @@
+interface Json
+    exposes
+        [
+            Json,
+            format,
+        ]
+    imports
+        [
+            Encode.{
+                Encoder,
+                custom,
+                appendWith,
+                u8,
+                u16,
+                u32,
+                u64,
+                u128,
+                i8,
+                i16,
+                i32,
+                i64,
+                i128,
+                f32,
+                f64,
+                dec,
+                bool,
+                string,
+                list,
+                record,
+                tag,
+            },
+        ]
+
+Json := {}
+
+format = @Json {}
+
+numToBytes = \n ->
+    n |> Num.toStr |> Str.toUtf8
+
+# impl EncoderFormatting for Json
+u8 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+u16 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+u32 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+u64 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+u128 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+i8 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+i16 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+i32 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+i64 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+i128 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+f32 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+f64 = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+dec = \n -> custom \bytes, @Json {} -> List.concat bytes (numToBytes n)
+
+bool = \b -> custom \bytes, @Json {} ->
+        if
+            b
+        then
+            List.concat bytes (Str.toUtf8 "true")
+        else
+            List.concat bytes (Str.toUtf8 "false")
+
+string = \s -> custom \bytes, @Json {} ->
+        List.append bytes (Num.toU8 '"')
+            |> List.concat (Str.toUtf8 s)
+            |> List.append (Num.toU8 '"')
+
+list = \lst, encodeElem ->
+    custom \bytes, @Json {} ->
+        head = List.append bytes (Num.toU8 '[')
+        withList = List.walk lst head (\bytes1, elem -> appendWith bytes1 (encodeElem elem) (@Json {}))
+
+        List.append withList (Num.toU8 ']')
+
+record = \fields ->
+    custom \bytes, @Json {} ->
+        writeRecord = \{ buffer, fieldsLeft }, { key, value } ->
+            bufferWithKeyValue =
+                List.append buffer (Num.toU8 '"')
+                    |> List.concat (Str.toUtf8 key)
+                    |> List.append (Num.toU8 '"')
+                    |> List.append (Num.toU8 ':')
+                    |> appendWith value (@Json {})
+
+            bufferWithSuffix =
+                if fieldsLeft > 0 then
+                    List.append bufferWithKeyValue (Num.toU8 ',')
+                else
+                    bufferWithKeyValue
+
+            { buffer: bufferWithSuffix, fieldsLeft: fieldsLeft - 1 }
+
+        bytesHead = List.append bytes (Num.toU8 '{')
+        { buffer: bytesWithRecord } = List.walk fields { buffer: bytesHead, fieldsLeft: List.len fields } writeRecord
+
+        List.append bytesWithRecord (Num.toU8 '}')
+
+tag = \name, payload ->
+    custom \bytes, @Json {} ->
+        # Idea: encode `A v1 v2` as `{"A": [v1, v2]}`
+        writePayload = \{ buffer, itemsLeft }, encoder ->
+            bufferWithValue = appendWith buffer encoder (@Json {})
+            bufferWithSuffix =
+                if itemsLeft > 0 then
+                    List.append bufferWithValue (Num.toU8 ',')
+                else
+                    bufferWithValue
+
+            { buffer: bufferWithSuffix, itemsLeft: itemsLeft - 1 }
+
+        bytesHead =
+            List.append bytes (Num.toU8 '{')
+                |> List.append (Num.toU8 '"')
+                |> List.concat (Str.toUtf8 name)
+                |> List.append (Num.toU8 '"')
+                |> List.append (Num.toU8 ':')
+                |> List.append (Num.toU8 '[')
+
+        { buffer: bytesWithPayload } = List.walk payload { buffer: bytesHead, itemsLeft: List.len payload } writePayload
+
+        List.append bytesWithPayload (Num.toU8 ']')
+            |> List.append (Num.toU8 '}')

crates/compiler/builtins/roc/List.roc

@@ -0,0 +1,843 @@
+interface List
+    exposes
+        [
+            isEmpty,
+            get,
+            set,
+            replace,
+            append,
+            map,
+            len,
+            withCapacity,
+            iterate,
+            walkBackwards,
+            concat,
+            first,
+            single,
+            repeat,
+            reverse,
+            prepend,
+            join,
+            keepIf,
+            contains,
+            sum,
+            walk,
+            last,
+            keepOks,
+            keepErrs,
+            mapWithIndex,
+            map2,
+            map3,
+            product,
+            walkUntil,
+            range,
+            sortWith,
+            drop,
+            swap,
+            dropAt,
+            dropLast,
+            min,
+            max,
+            map4,
+            dropFirst,
+            joinMap,
+            any,
+            takeFirst,
+            takeLast,
+            find,
+            findIndex,
+            sublist,
+            intersperse,
+            split,
+            all,
+            dropIf,
+            sortAsc,
+            sortDesc,
+        ]
+    imports
+        [
+            Bool.{ Bool },
+        ]
+
+## Types
+## A sequential list of values.
+##
+## >>> [1, 2, 3] # a list of numbers
+## >>> ["a", "b", "c"] # a list of strings
+## >>> [[1.1], [], [2.2, 3.3]] # a list of lists of numbers
+##
+## The maximum size of a [List] is limited by the amount of heap memory available
+## to the current process. If there is not enough memory available, attempting to
+## create the list could crash. (On Linux, where [overcommit](https://www.etalabs.net/overcommit.html)
+## is normally enabled, not having enough memory could result in the list appearing
+## to be created just fine, but then crashing later.)
+##
+## > The theoretical maximum length for a list created in Roc is half of
+## > `Num.maxNat`. Attempting to create a list bigger than that
+## > in Roc code will always fail, although in practice it is likely to fail
+## > at much smaller lengths due to insufficient memory being available.
+##
+## ## Performance Details
+##
+## Under the hood, a list is a record containing a `len : Nat` field as well
+## as a pointer to a reference count and a flat array of bytes. Unique lists
+## store a capacity #Nat instead of a reference count.
+##
+## ## Shared Lists
+##
+## Shared lists are [reference counted](https://en.wikipedia.org/wiki/Reference_counting).
+##
+## Each time a given list gets referenced, its reference count ("refcount" for short)
+## gets incremented. Each time a list goes out of scope, its refcount count gets
+## decremented. Once a refcount, has been decremented more times than it has been
+## incremented, we know nothing is referencing it anymore, and the list's memory
+## will be immediately freed.
+##
+## Let's look at an example.
+##
+##     ratings = [5, 4, 3]
+##
+##     { foo: ratings, bar: ratings }
+##
+## The first line binds the name `ratings` to the list `[5, 4, 3]`. The list
+## begins with a refcount of 1, because so far only `ratings` is referencing it.
+##
+## The second line alters this refcount. `{ foo: ratings` references
+## the `ratings` list, which will result in its refcount getting incremented
+## from 0 to 1. Similarly, `bar: ratings }` also references the `ratings` list,
+## which will result in its refcount getting incremented from 1 to 2.
+##
+## Let's turn this example into a function.
+##
+##     getRatings = \first ->
+##         ratings = [first, 4, 3]
+##
+##         { foo: ratings, bar: ratings }
+##
+##     getRatings 5
+##
+## At the end of the `getRatings` function, when the record gets returned,
+## the original `ratings =` binding has gone out of scope and is no longer
+## accessible. (Trying to reference `ratings` outside the scope of the
+## `getRatings` function would be an error!)
+##
+## Since `ratings` represented a way to reference the list, and that way is no
+## longer accessible, the list's refcount gets decremented when `ratings` goes
+## out of scope. It will decrease from 2 back down to 1.
+##
+## Putting these together, when we call `getRatings 5`, what we get back is
+## a record with two fields, `foo`, and `bar`, each of which refers to the same
+## list, and that list has a refcount of 1.
+##
+## Let's change the last line to be `(getRatings 5).bar` instead of `getRatings 5`:
+##
+##     getRatings = \first ->
+##         ratings = [first, 4, 3]
+##
+##         { foo: ratings, bar: ratings }
+##
+##     (getRatings 5).bar
+##
+## Now, when this expression returns, only the `bar` field of the record will
+## be returned. This will mean that the `foo` field becomes inaccessible, causing
+## the list's refcount to get decremented from 2 to 1. At this point, the list is back
+## where it started: there is only 1 reference to it.
+##
+## Finally let's suppose the final line were changed to this:
+##
+##     List.first (getRatings 5).bar
+##
+## This call to [List.first] means that even the list in the `bar` field has become
+## inaccessible. As such, this line will cause the list's refcount to get
+## decremented all the way to 0. At that point, nothing is referencing the list
+## anymore, and its memory will get freed.
+##
+## Things are different if this is a list of lists instead of a list of numbers.
+## Let's look at a simpler example using [List.first] - first with a list of numbers,
+## and then with a list of lists, to see how they differ.
+##
+## Here's the example using a list of numbers.
+##
+##     nums = [1, 2, 3, 4, 5, 6, 7]
+##
+##     first = List.first nums
+##     last = List.last nums
+##
+##     first
+##
+## It makes a list, calls [List.first] and [List.last] on it, and then returns `first`.
+##
+## Here's the equivalent code with a list of lists:
+##
+##     lists = [[1], [2, 3], [], [4, 5, 6, 7]]
+##
+##     first = List.first lists
+##     last = List.last lists
+##
+##     first
+##
+## TODO explain how in the former example, when we go to free `nums` at the end,
+## we can free it immediately because there are no other refcounts. However,
+## in the case of `lists`, we have to iterate through the list and decrement
+## the refcounts of each of its contained lists - because they, too, have
+## refcounts! Importantly, because the first element had its refcount incremented
+## because the function returned `first`, that element will actually end up
+## *not* getting freed at the end - but all the others will be.
+##
+## In the `lists` example, `lists = [...]` also creates a list with an initial
+## refcount of 1. Separately, it also creates several other lists - each with
+## their own refcounts - to go inside that list. (The empty list at the end
+## does not use heap memory, and thus has no refcount.)
+##
+## At the end, we once again call [List.first] on the list, but this time
+##
+## * Copying small lists (64 elements or fewer) is typically slightly faster than copying small persistent data structures. This is because, at small sizes, persistent data structures tend to be thin wrappers around flat arrays anyway. They don't have any copying advantage until crossing a certain minimum size threshold.
+## * Even when copying is faster, other list operations may still be slightly slower with persistent data structures. For example, even if it were a persistent data structure, [List.map], [List.walk], and [List.keepIf] would all need to traverse every element in the list and build up the result from scratch. These operations are all
+## * Roc's compiler optimizes many list operations into in-place mutations behind the scenes, depending on how the list is being used. For example, [List.map], [List.keepIf], and [List.set] can all be optimized to perform in-place mutations.
+## * If possible, it is usually best for performance to use large lists in a way where the optimizer can turn them into in-place mutations. If this is not possible, a persistent data structure might be faster - but this is a rare enough scenario that it would not be good for the average Roc program's performance if this were the way [List] worked by default. Instead, you can look outside Roc's standard modules for an implementation of a persistent data structure - likely built using [List] under the hood!
+##  Check if the list is empty.
+##
+## >>> List.isEmpty [1, 2, 3]
+##
+## >>> List.isEmpty []
+isEmpty : List a -> Bool
+isEmpty = \list ->
+    List.len list == 0
+
+# unsafe primitive that does not perform a bounds check
+# but will cause a reference count increment on the value it got out of the list
+getUnsafe : List a, Nat -> a
+
+get : List a, Nat -> Result a [OutOfBounds]*
+get = \list, index ->
+    if index < List.len list then
+        Ok (List.getUnsafe list index)
+    else
+        Err OutOfBounds
+
+# unsafe primitive that does not perform a bounds check
+# but will cause a reference count increment on the value it got out of the list
+replaceUnsafe : List a, Nat, a -> { list : List a, value : a }
+
+replace : List a, Nat, a -> { list : List a, value : a }
+replace = \list, index, newValue ->
+    if index < List.len list then
+        List.replaceUnsafe list index newValue
+    else
+        { list, value: newValue }
+
+## Replaces the element at the given index with a replacement.
+##
+## >>> List.set ["a", "b", "c"] 1 "B"
+##
+## If the given index is outside the bounds of the list, returns the original
+## list unmodified.
+##
+## To drop the element at a given index, instead of replacing it, see [List.dropAt].
+set : List a, Nat, a -> List a
+set = \list, index, value ->
+    (List.replace list index value).list
+
+## Add a single element to the end of a list.
+##
+## >>> List.append [1, 2, 3] 4
+##
+## >>> [0, 1, 2]
+## >>>     |> List.append 3
+append : List a, a -> List a
+
+## Add a single element to the beginning of a list.
+##
+## >>> List.prepend [1, 2, 3] 0
+##
+## >>> [2, 3, 4]
+## >>>     |> List.prepend 1
+prepend : List a, a -> List a
+
+## Returns the length of the list - the number of elements it contains.
+##
+## One [List] can store up to 2,147,483,648 elements (just over 2 billion), which
+## is exactly equal to the highest valid #I32 value. This means the #U32 this function
+## returns can always be safely converted to an #I32 without losing any data.
+len : List a -> Nat
+
+## Create a list with space for at least capacity elements
+withCapacity : Nat -> List a
+
+## Put two lists together.
+##
+## >>> List.concat [1, 2, 3] [4, 5]
+##
+## >>> [0, 1, 2]
+## >>>     |> List.concat [3, 4]
+concat : List a, List a -> List a
+
+## Returns the last element in the list, or `ListWasEmpty` if it was empty.
+last : List a -> Result a [ListWasEmpty]*
+last = \list ->
+    when List.get list (Num.subSaturated (List.len list) 1) is
+        Ok v -> Ok v
+        Err _ -> Err ListWasEmpty
+
+## A list with a single element in it.
+##
+## This is useful in pipelines, like so:
+##
+##     websites =
+##         Str.concat domain ".com"
+##             |> List.single
+##
+single : a -> List a
+single = \x -> [x]
+
+## Returns a list with the given length, where every element is the given value.
+##
+##
+repeat : a, Nat -> List a
+repeat = \value, count ->
+    repeatHelp value count (List.withCapacity count)
+
+repeatHelp : a, Nat, List a -> List a
+repeatHelp = \value, count, accum ->
+    if count > 0 then
+        repeatHelp value (count - 1) (List.append accum value)
+    else
+        accum
+
+## Returns the list with its elements reversed.
+##
+## >>> List.reverse [1, 2, 3]
+reverse : List a -> List a
+reverse = \list ->
+    reverseHelp list 0 (Num.subSaturated (List.len list) 1)
+
+reverseHelp = \list, left, right ->
+    if left < right then
+        reverseHelp (List.swap list left right) (left + 1) (right - 1)
+    else
+        list
+
+## Join the given lists together into one list.
+##
+## >>> List.join [[1, 2, 3], [4, 5], [], [6, 7]]
+##
+## >>> List.join [[], []]
+##
+## >>> List.join []
+join : List (List a) -> List a
+join = \lists ->
+    totalLength =
+        List.walk lists 0 (\state, list -> state + List.len list)
+
+    List.walk lists (List.withCapacity totalLength) (\state, list -> List.concat state list)
+
+contains : List a, a -> Bool
+contains = \list, needle ->
+    List.any list (\x -> x == needle)
+
+## Build a value using each element in the list.
+##
+## Starting with a given `state` value, this walks 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.
+##
+## You can use it in a pipeline:
+##
+##     [2, 4, 8]
+##         |> List.walk { start: 0, step: Num.add }
+##
+## This returns 14 because:
+## * `state` starts at 0 (because of `start: 0`)
+## * Each `step` runs `Num.add state elem`, and the return value becomes the new `state`.
+##
+## Here is a table of how `state` changes as [List.walk] walks over the elements
+## `[2, 4, 8]` using #Num.add as its `step` function to determine the next `state`.
+##
+## `state` | `elem` | `step state elem` (`Num.add state elem`)
+## --------+--------+-----------------------------------------
+## 0       |        |
+## 0       | 2      | 2
+## 2       | 4      | 6
+## 6       | 8      | 14
+##
+## So `state` goes through these changes:
+## 1. `0` (because of `start: 0`)
+## 2. `1` (because of `Num.add state elem` with `state` = 0 and `elem` = 1
+##
+##     [1, 2, 3]
+##         |> List.walk { start: 0, step: Num.sub }
+##
+## This returns -6 because
+##
+## Note that in other languages, `walk` is sometimes called `reduce`,
+## `fold`, `foldLeft`, or `foldl`.
+walk : List elem, state, (state, elem -> state) -> state
+walk = \list, state, func ->
+    walkHelp list state func 0 (len list)
+
+## internal helper
+walkHelp : List elem, state, (state, elem -> state), Nat, Nat -> state
+walkHelp = \list, state, f, index, length ->
+    if index < length then
+        nextState = f state (getUnsafe list index)
+
+        walkHelp list nextState f (index + 1) length
+    else
+        state
+
+## Note that in other languages, `walkBackwards` is sometimes called `reduceRight`,
+## `fold`, `foldRight`, or `foldr`.
+walkBackwards : List elem, state, (state, elem -> state) -> state
+walkBackwards = \list, state, func ->
+    walkBackwardsHelp list state func (len list)
+
+## internal helper
+walkBackwardsHelp : List elem, state, (state, elem -> state), Nat -> state
+walkBackwardsHelp = \list, state, f, indexPlusOne ->
+    if indexPlusOne == 0 then
+        state
+    else
+        index = indexPlusOne - 1
+        nextState = f state (getUnsafe list index)
+
+        walkBackwardsHelp list nextState f index
+
+## Same as [List.walk], except you can stop walking early.
+##
+## ## Performance Details
+##
+## Compared to [List.walk], this can potentially visit fewer elements (which can
+## improve performance) at the cost of making each step take longer.
+## However, the added cost to each step is extremely small, and can easily
+## be outweighed if it results in skipping even a small number of elements.
+##
+## As such, it is typically better for performance to use this over [List.walk]
+## if returning `Break` earlier than the last element is expected to be common.
+walkUntil : List elem, state, (state, elem -> [Continue state, Break state]) -> state
+walkUntil = \list, initial, step ->
+    when List.iterate list initial step is
+        Continue new -> new
+        Break new -> new
+
+sum : List (Num a) -> Num a
+sum = \list ->
+    List.walk list 0 Num.add
+
+product : List (Num a) -> Num a
+product = \list ->
+    List.walk list 1 Num.mul
+
+## Run the given predicate on each element of the list, returning `True` if
+## any of the elements satisfy it.
+any : List a, (a -> Bool) -> Bool
+any = \list, predicate ->
+    looper = \{}, element ->
+        if predicate element then
+            Break {}
+        else
+            Continue {}
+
+    when List.iterate list {} looper is
+        Continue {} -> False
+        Break {} -> True
+
+## Run the given predicate on each element of the list, returning `True` if
+## all of the elements satisfy it.
+all : List a, (a -> Bool) -> Bool
+all = \list, predicate ->
+    looper = \{}, element ->
+        if predicate element then
+            Continue {}
+        else
+            Break {}
+
+    when List.iterate list {} looper is
+        Continue {} -> True
+        Break {} -> False
+
+## Run the given function on each element of a list, and return all the
+## elements for which the function returned `True`.
+##
+## >>> List.keepIf [1, 2, 3, 4] (\num -> num > 2)
+##
+## ## Performance Details
+##
+## [List.keepIf] 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 lis with [List.walk] - one
+## to calculate the precise new size, and another to populate the new list.)
+##
+## If given a unique list, [List.keepIf] 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.
+##
+keepIf : List a, (a -> Bool) -> List a
+keepIf = \list, predicate ->
+    length = List.len list
+
+    keepIfHelp list predicate 0 0 length
+
+keepIfHelp : List a, (a -> Bool), Nat, Nat, Nat -> List a
+keepIfHelp = \list, predicate, kept, index, length ->
+    if index < length then
+        if predicate (List.getUnsafe list index) then
+            keepIfHelp (List.swap list kept index) predicate (kept + 1) (index + 1) length
+        else
+            keepIfHelp list predicate kept (index + 1) length
+    else
+        List.takeFirst list kept
+
+## Run the given function on each element of a list, and return all the
+## elements for which the function returned `False`.
+##
+## >>> List.dropIf [1, 2, 3, 4] (\num -> num > 2)
+##
+## ## Performance Details
+##
+## `List.dropIf` has the same performance characteristics as [List.keepIf].
+## See its documentation for details on those characteristics!
+dropIf : List a, (a -> Bool) -> List a
+dropIf = \list, predicate ->
+    List.keepIf list (\e -> Bool.not (predicate e))
+
+## This works like [List.map], except only the transformed values that are
+## wrapped in `Ok` are kept. Any that are wrapped in `Err` are dropped.
+##
+## >>> List.keepOks [["a", "b"], [], [], ["c", "d", "e"]] List.last
+##
+## >>> fn = \str -> if Str.isEmpty str then Err StrWasEmpty else Ok (Str.len str)
+## >>>
+## >>> List.keepOks ["", "a", "bc", "", "d", "ef", ""]
+keepOks : List before, (before -> Result after *) -> List after
+keepOks = \list, toResult ->
+    walker = \accum, element ->
+        when toResult element is
+            Ok keep -> List.append accum keep
+            Err _drop -> accum
+
+    List.walk list (List.withCapacity (List.len list)) walker
+
+## This works like [List.map], except only the transformed values that are
+## wrapped in `Err` are kept. Any that are wrapped in `Ok` are dropped.
+##
+## >>> List.keepErrs [["a", "b"], [], [], ["c", "d", "e"]] List.last
+##
+## >>> fn = \str -> if Str.isEmpty str then Err StrWasEmpty else Ok (Str.len str)
+## >>>
+## >>> List.keepErrs ["", "a", "bc", "", "d", "ef", ""]
+keepErrs : List before, (before -> Result * after) -> List after
+keepErrs = \list, toResult ->
+    walker = \accum, element ->
+        when toResult element is
+            Ok _drop -> accum
+            Err keep -> List.append accum keep
+
+    List.walk list (List.withCapacity (List.len list)) walker
+
+## 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.
+##
+## > List.map [1, 2, 3] (\num -> num + 1)
+##
+## > List.map ["", "a", "bc"] Str.isEmpty
+map : List a, (a -> b) -> List b
+
+## Run a transformation function on the first element of each list,
+## and use that as the first element in the returned list.
+## Repeat until a list runs out of elements.
+##
+## Some languages have a function named `zip`, which does something similar to
+## calling [List.map2] passing two lists and `Pair`:
+##
+## >>> zipped = List.map2 ["a", "b", "c"] [1, 2, 3] Pair
+map2 : List a, List b, (a, b -> c) -> List c
+
+## Run a transformation function on the first element of each list,
+## and use that as the first element in the returned list.
+## Repeat until a list runs out of elements.
+map3 : List a, List b, List c, (a, b, c -> d) -> List d
+
+## Run a transformation function on the first element of each list,
+## and use that as the first element in the returned list.
+## Repeat until a list runs out of elements.
+map4 : List a, List b, List c, List d, (a, b, c, d -> e) -> List e
+
+## This works like [List.map], except it also passes the index
+## of the element to the conversion function.
+mapWithIndex : List a, (a, Nat -> b) -> List b
+mapWithIndex = \src, func ->
+    length = len src
+    dest = withCapacity length
+
+    mapWithIndexHelp src dest func 0 length
+
+# Internal helper
+mapWithIndexHelp : List a, List b, (a, Nat -> b), Nat, Nat -> List b
+mapWithIndexHelp = \src, dest, func, index, length ->
+    if index < length then
+        elem = getUnsafe src index
+        mappedElem = func elem index
+        newDest = append dest mappedElem
+
+        mapWithIndexHelp src newDest func (index + 1) length
+    else
+        dest
+
+## Returns a list of all the integers between one and another,
+## including both of the given numbers.
+##
+## >>> List.range 2 8
+range : Int a, Int a -> List (Int a)
+range = \start, end ->
+    when Num.compare start end is
+        GT -> []
+        EQ -> [start]
+        LT ->
+            length = Num.intCast (end - start)
+
+            rangeHelp (List.withCapacity length) start end
+
+rangeHelp : List (Int a), Int a, Int a -> List (Int a)
+rangeHelp = \accum, start, end ->
+    if end <= start then
+        accum
+    else
+        rangeHelp (List.append accum start) (start + 1) end
+
+## Sort with a custom comparison function
+sortWith : List a, (a, a -> [LT, EQ, GT]) -> List a
+
+## Sorts a list in ascending order (lowest to highest), using a function which
+## specifies a way to represent each element as a number.
+##
+## To sort in descending order (highest to lowest), use [List.sortDesc] instead.
+sortAsc : List (Num a) -> List (Num a)
+sortAsc = \list -> List.sortWith list Num.compare
+
+## Sorts a list in descending order (highest to lowest), using a function which
+## specifies a way to represent each element as a number.
+##
+## To sort in ascending order (lowest to highest), use [List.sortAsc] instead.
+sortDesc : List (Num a) -> List (Num a)
+sortDesc = \list -> List.sortWith list (\a, b -> Num.compare b a)
+
+swap : List a, Nat, Nat -> List a
+
+## Returns the first element in the list, or `ListWasEmpty` if it was empty.
+first : List a -> Result a [ListWasEmpty]*
+first = \list ->
+    when List.get list 0 is
+        Ok v -> Ok v
+        Err _ -> Err ListWasEmpty
+
+## Remove the first element from the list.
+##
+## Returns the new list (with the removed element missing).
+dropFirst : List elem -> List elem
+dropFirst = \list ->
+    List.dropAt list 0
+
+## Remove the last element from the list.
+##
+## Returns the new list (with the removed element missing).
+dropLast : List elem -> List elem
+dropLast = \list ->
+    List.dropAt list (Num.subSaturated (List.len list) 1)
+
+## Returns the given number of elements from the beginning of the list.
+##
+## >>> List.takeFirst 4 [1, 2, 3, 4, 5, 6, 7, 8]
+##
+## If there are fewer elements in the list than the requested number,
+## returns the entire list.
+##
+## >>> List.takeFirst 5 [1, 2]
+##
+## To *remove* elements from the beginning of the list, use `List.takeLast`.
+##
+## To remove elements from both the beginning and end of the list,
+## use `List.sublist`.
+##
+## To split the list into two lists, use `List.split`.
+##
+## ## Performance Details
+##
+## When given a Unique list, this runs extremely fast. It sets the list's length
+## to the given length value, and frees the leftover elements. This runs very
+## slightly faster than `List.takeLast`.
+##
+## In fact, `List.takeFirst 1 list` runs faster than `List.first list` when given
+## a Unique list, because [List.first] returns the first element as well -
+## which introduces a conditional bounds check as well as a memory load.
+takeFirst : List elem, Nat -> List elem
+takeFirst = \list, outputLength ->
+    List.sublist list { start: 0, len: outputLength }
+
+## Returns the given number of elements from the end of the list.
+##
+## >>> List.takeLast 4 [1, 2, 3, 4, 5, 6, 7, 8]
+##
+## If there are fewer elements in the list than the requested number,
+## returns the entire list.
+##
+## >>> List.takeLast 5 [1, 2]
+##
+## To *remove* elements from the end of the list, use `List.takeFirst`.
+##
+## To remove elements from both the beginning and end of the list,
+## use `List.sublist`.
+##
+## To split the list into two lists, use `List.split`.
+##
+## ## Performance Details
+##
+## When given a Unique list, this runs extremely fast. It moves the list's
+## pointer to the index at the given length value, updates its length,
+## and frees the leftover elements. This runs very nearly as fast as
+## `List.takeFirst` on a Unique list.
+##
+## In fact, `List.takeLast 1 list` runs faster than `List.first list` when given
+## a Unique list, because [List.first] returns the first element as well -
+## which introduces a conditional bounds check as well as a memory load.
+takeLast : List elem, Nat -> List elem
+takeLast = \list, outputLength ->
+    List.sublist list { start: Num.subSaturated (List.len list) outputLength, len: outputLength }
+
+## Drops n elements from the beginning of the list.
+drop : List elem, Nat -> List elem
+
+## Drops the element at the given index from the list.
+##
+## This has no effect if the given index is outside the bounds of the list.
+##
+## To replace the element at a given index, instead of dropping it, see [List.set].
+dropAt : List elem, Nat -> List elem
+
+min : List (Num a) -> Result (Num a) [ListWasEmpty]*
+min = \list ->
+    when List.first list is
+        Ok initial ->
+            Ok (minHelp list initial)
+        Err ListWasEmpty ->
+            Err ListWasEmpty
+
+minHelp : List (Num a), Num a -> Num a
+minHelp = \list, initial ->
+    List.walk list initial \bestSoFar, current ->
+        if current < bestSoFar then
+            current
+        else
+            bestSoFar
+
+max : List (Num a) -> Result (Num a) [ListWasEmpty]*
+max = \list ->
+    when List.first list is
+        Ok initial ->
+            Ok (maxHelp list initial)
+        Err ListWasEmpty ->
+            Err ListWasEmpty
+
+maxHelp : List (Num a), Num a -> Num a
+maxHelp = \list, initial ->
+    List.walk list initial \bestSoFar, current ->
+        if current > bestSoFar then
+            current
+        else
+            bestSoFar
+
+## Like [List.map], except the transformation function wraps the return value
+## in a list. At the end, all the lists get joined together into one list.
+##
+## You may know a similar function named `concatMap` in other languages.
+joinMap : List a, (a -> List b) -> List b
+joinMap = \list, mapper ->
+    List.walk list [] (\state, elem -> List.concat state (mapper elem))
+
+## Returns the first element of the list satisfying a predicate function.
+## If no satisfying element is found, an `Err NotFound` is returned.
+find : List elem, (elem -> Bool) -> Result elem [NotFound]*
+find = \array, pred ->
+    callback = \_, elem ->
+        if pred elem then
+            Break elem
+        else
+            Continue {}
+
+    when List.iterate array {} callback is
+        Continue {} ->
+            Err NotFound
+        Break found ->
+            Ok found
+
+## Returns the index at which the first element in the list
+## satisfying a predicate function can be found.
+## If no satisfying element is found, an `Err NotFound` is returned.
+findIndex : List elem, (elem -> Bool) -> Result Nat [NotFound]*
+findIndex = \list, matcher ->
+    foundIndex = List.iterate list 0 \index, elem ->
+        if matcher elem then
+            Break index
+        else
+            Continue (index + 1)
+
+    when foundIndex is
+        Break index -> Ok index
+        Continue _ -> Err NotFound
+
+## Returns a subsection of the given list, beginning at the `start` index and
+## including a total of `len` elements.
+##
+## If `start` is outside the bounds of the given list, returns the empty list.
+##
+## >>> List.sublist [1, 2, 3] { start: 4, len: 0 }
+##
+## If more elements are requested than exist in the list, returns as many as it can.
+##
+## >>> List.sublist [1, 2, 3, 4, 5] { start: 2, len: 10 }
+##
+## > If you want a sublist which goes all the way to the end of the list, no
+## > matter how long the list is, `List.takeLast` can do that more efficiently.
+##
+## Some languages have a function called **`slice`** which works similarly to this.
+sublist : List elem, { start : Nat, len : Nat } -> List elem
+
+## Intersperses `sep` between the elements of `list`
+## >>> List.intersperse 9 [1, 2, 3]     # [1, 9, 2, 9, 3]
+intersperse : List elem, elem -> List elem
+intersperse = \list, sep ->
+    capacity = 2 * List.len list
+    init = List.withCapacity capacity
+    newList = List.walk list init (\acc, elem -> acc |> List.append elem |> List.append sep)
+
+    List.dropLast newList
+
+## Splits the list into two lists, around the given index.
+##
+## The returned lists are labeled `before` and `others`. The `before` list will
+## contain all the elements whose index in the original list was **less than**
+## than the given index, # and the `others` list will be all the others. (This
+## means if you give an index of 0, the `before` list will be empty and the
+## `others` list will have the same elements as the original list.)
+split : List elem, Nat -> { before : List elem, others : List elem }
+
+## Primitive for iterating over a List, being able to decide at every element whether to continue
+iterate : List elem, s, (s, elem -> [Continue s, Break b]) -> [Continue s, Break b]
+iterate = \list, init, func ->
+    iterHelp list init func 0 (List.len list)
+
+## internal helper
+iterHelp : List elem, s, (s, elem -> [Continue s, Break b]), Nat, Nat -> [Continue s, Break b]
+iterHelp = \list, state, f, index, length ->
+    if index < length then
+        when f state (List.getUnsafe list index) is
+            Continue nextState ->
+                iterHelp list nextState f (index + 1) length
+            Break b ->
+                Break b
+    else
+        Continue state

crates/compiler/builtins/roc/Result.roc

@@ -0,0 +1,94 @@
+interface Result
+    exposes [Result, isOk, isErr, map, mapErr, after, withDefault]
+    imports [Bool.{ Bool }]
+
+## The result of an operation that could fail: either the operation went
+## okay, or else there was an error of some sort.
+Result ok err : [Ok ok, Err err]
+
+## Return True if the result indicates a success, else return False
+##
+## >>> Result.isOk (Ok 5)
+isOk : Result ok err -> Bool
+isOk = \result ->
+    when result is
+        Ok _ ->
+            True
+        Err _ ->
+            False
+
+## Return True if the result indicates a failure, else return False
+##
+## >>> Result.isErr (Err "uh oh")
+isErr : Result ok err -> Bool
+isErr = \result ->
+    when result is
+        Ok _ ->
+            False
+        Err _ ->
+            True
+
+## If the result is `Ok`, return the value it holds. Otherwise, return
+## the given default value.
+##
+## >>> Result.withDefault (Ok 7) 42
+##
+## >>> Result.withDefault (Err "uh oh") 42
+withDefault : Result ok err, ok -> ok
+withDefault = \result, default ->
+    when result is
+        Ok value ->
+            value
+        Err _ ->
+            default
+
+## If the result is `Ok`, transform the value it holds by running a conversion
+## function on it. Then return a new `Ok` holding the transformed value.
+##
+## (If the result is `Err`, this has no effect. Use [mapErr] to transform an `Err`.)
+##
+## >>> Result.map (Ok 12) Num.negate
+##
+## >>> Result.map (Err "yipes!") Num.negate
+##
+## `map` functions like this are common in Roc, and they all work similarly.
+## See for example [List.map], `Set.map`, and `Dict.map`.
+map : Result a err, (a -> b) -> Result b err
+map = \result, transform ->
+    when result is
+        Ok v ->
+            Ok (transform v)
+        Err e ->
+            Err e
+
+## If the result is `Err`, transform the value it holds by running a conversion
+## function on it. Then return a new `Err` holding the transformed value.
+##
+## (If the result is `Ok`, this has no effect. Use [map] to transform an `Ok`.)
+##
+## >>> Result.mapErr (Err "yipes!") Str.isEmpty
+##
+## >>> Result.mapErr (Ok 12) Str.isEmpty
+mapErr : Result ok a, (a -> b) -> Result ok b
+mapErr = \result, transform ->
+    when result is
+        Ok v ->
+            Ok v
+        Err e ->
+            Err (transform e)
+
+## If the result is `Ok`, transform the entire result by running a conversion
+## function on the value the `Ok` holds. Then return that new result.
+##
+## (If the result is `Err`, this has no effect. Use `afterErr` to transform an `Err`.)
+##
+## >>> Result.after (Ok -1) \num -> if num < 0 then Err "negative!" else Ok -num
+##
+## >>> Result.after (Err "yipes!") \num -> if num < 0 then Err "negative!" else Ok -num
+after : Result a err, (a -> Result b err) -> Result b err
+after = \result, transform ->
+    when result is
+        Ok v ->
+            transform v
+        Err e ->
+            Err e

crates/compiler/builtins/roc/Set.roc

@@ -0,0 +1,45 @@
+interface Set
+    exposes
+        [
+            empty,
+            single,
+            walk,
+            insert,
+            len,
+            remove,
+            contains,
+            toList,
+            fromList,
+            union,
+            intersection,
+            difference,
+        ]
+    imports [List, Bool.{ Bool }, Dict.{ values }]
+
+## An empty set.
+empty : Set k
+single : k -> Set k
+
+## Make sure never to insert a *NaN* to a [Set]! Because *NaN* is defined to be
+## unequal to *NaN*, adding a *NaN* results in an entry that can never be
+## retrieved or removed from the [Set].
+insert : Set k, k -> Set k
+len : Set k -> Nat
+
+## Drops the given element from the set.
+remove : Set k, k -> Set k
+contains : Set k, k -> Bool
+
+# toList = \set -> Dict.keys (toDict set)
+toList : Set k -> List k
+fromList : List k -> Set k
+
+union : Set k, Set k -> Set k
+intersection : Set k, Set k -> Set k
+difference : Set k, Set k -> Set k
+
+toDict : Set k -> Dict k {}
+
+walk : Set k, state, (state, k -> state) -> state
+walk = \set, state, step ->
+    Dict.walk (Set.toDict set) state (\s, k, _ -> step s k)

crates/compiler/builtins/roc/Str.roc

@@ -0,0 +1,397 @@
+interface Str
+    exposes
+        [
+            Utf8Problem,
+            Utf8ByteProblem,
+            concat,
+            isEmpty,
+            joinWith,
+            split,
+            repeat,
+            countGraphemes,
+            countUtf8Bytes,
+            startsWithScalar,
+            toUtf8,
+            fromUtf8,
+            fromUtf8Range,
+            startsWith,
+            endsWith,
+            trim,
+            trimLeft,
+            trimRight,
+            toDec,
+            toF64,
+            toF32,
+            toNat,
+            toU128,
+            toI128,
+            toU64,
+            toI64,
+            toU32,
+            toI32,
+            toU16,
+            toI16,
+            toU8,
+            toI8,
+            toScalars,
+            splitFirst,
+            splitLast,
+            walkUtf8WithIndex,
+            reserve,
+            appendScalar,
+            walkScalars,
+            walkScalarsUntil,
+        ]
+    imports [Bool.{ Bool }, Result.{ Result }]
+
+## # Types
+##
+## Dealing with text is a deep topic, so by design, Roc's `Str` module sticks
+## to the basics.
+##
+## ### Unicode
+##
+## Unicode can represent text values which span multiple languages, symbols, and emoji.
+## Here are some valid Roc strings:
+##
+## "Roc!"
+## "鹏"
+## "🕊"
+##
+## Every Unicode string is a sequence of [extended grapheme clusters](http://www.unicode.org/glossary/#extended_grapheme_cluster).
+## An extended grapheme cluster represents what a person reading a string might
+## call a "character" - like "A" or "ö" or "👩‍👩‍👦‍👦".
+## Because the term "character" means different things in different areas of
+## programming, and "extended grapheme cluster" is a mouthful, in Roc we use the
+## term "grapheme" as a shorthand for the more precise "extended grapheme cluster."
+##
+## You can get the number of graphemes in a string by calling [Str.countGraphemes] on it:
+##
+##     Str.countGraphemes "Roc!"
+##     Str.countGraphemes "折り紙"
+##     Str.countGraphemes "🕊"
+##
+## > The `countGraphemes` function walks through the entire string to get its answer,
+## > so if you want to check whether a string is empty, you'll get much better performance
+## > by calling `Str.isEmpty myStr` instead of `Str.countGraphemes myStr == 0`.
+##
+## ### Escape sequences
+##
+## If you put a `\` in a Roc string literal, it begins an *escape sequence*.
+## An escape sequence is a convenient way to insert certain strings into other strings.
+## For example, suppose you write this Roc string:
+##
+##     "I took the one less traveled by,\nAnd that has made all the difference."
+##
+## The `"\n"` in the middle will insert a line break into this string. There are
+## other ways of getting a line break in there, but `"\n"` is the most common.
+##
+## Another way you could insert a newlines is by writing `\u{0x0A}` instead of `\n`.
+## That would result in the same string, because the `\u` escape sequence inserts
+## [Unicode code points](https://unicode.org/glossary/#code_point) directly into
+## the string. The Unicode code point 10 is a newline, and 10 is `0A` in hexadecimal.
+## `0x0A` is a Roc hexadecimal literal, and `\u` escape sequences are always
+## followed by a hexadecimal literal inside `{` and `}` like this.
+##
+## As another example, `"R\u{0x6F}c"` is the same string as `"Roc"`, because
+## `"\u{0x6F}"` corresponds to the Unicode code point for lowercase `o`. If you
+## want to [spice things up a bit](https://en.wikipedia.org/wiki/Metal_umlaut),
+## you can write `"R\u{0xF6}c"` as an alternative way to get the string `"Röc"\.
+##
+## Roc strings also support these escape sequences:
+##
+## * `\\` - an actual backslash (writing a single `\` always begins an escape sequence!)
+## * `\"` - an actual quotation mark (writing a `"` without a `\` ends the string)
+## * `\r` - [carriage return](https://en.wikipedia.org/wiki/Carriage_Return)
+## * `\t` - [horizontal tab](https://en.wikipedia.org/wiki/Tab_key#Tab_characters)
+## * `\v` - [vertical tab](https://en.wikipedia.org/wiki/Tab_key#Tab_characters)
+##
+## You can also use escape sequences to insert named strings into other strings, like so:
+##
+##     name = "Lee"
+##     city = "Roctown"
+##
+##     greeting = "Hello there, \(name)! Welcome to \(city)."
+##
+## Here, `greeting` will become the string `"Hello there, Lee! Welcome to Roctown."`.
+## This is known as [string interpolation](https://en.wikipedia.org/wiki/String_interpolation),
+## and you can use it as many times as you like inside a string. The name
+## between the parentheses must refer to a `Str` value that is currently in
+## scope, and it must be a name - it can't be an arbitrary expression like a function call.
+Utf8ByteProblem :
+    [
+        InvalidStartByte,
+        UnexpectedEndOfSequence,
+        ExpectedContinuation,
+        OverlongEncoding,
+        CodepointTooLarge,
+        EncodesSurrogateHalf,
+    ]
+
+Utf8Problem : { byteIndex : Nat, problem : Utf8ByteProblem }
+
+## Returns `True` if the string is empty, and `False` otherwise.
+##
+## >>> Str.isEmpty "hi!"
+##
+## >>> Str.isEmpty ""
+isEmpty : Str -> Bool
+concat : Str, Str -> Str
+
+## Combine a list of strings into a single string, with a separator
+## string in between each.
+##
+## >>> Str.joinWith ["one", "two", "three"] ", "
+joinWith : List Str, Str -> Str
+
+## Split a string around a separator.
+##
+## >>> Str.split "1,2,3" ","
+##
+## Passing `""` for the separator is not useful; it returns the original string
+## wrapped in a list.
+##
+## >>> Str.split "1,2,3" ""
+##
+## To split a string into its individual graphemes, use `Str.graphemes`
+split : Str, Str -> List Str
+repeat : Str, Nat -> Str
+
+## Count the number of [extended grapheme clusters](http://www.unicode.org/glossary/#extended_grapheme_cluster)
+## in the string.
+##
+##     Str.countGraphemes "Roc!"   # 4
+##     Str.countGraphemes "七巧板" # 3
+##     Str.countGraphemes "üïä"     # 1
+countGraphemes : Str -> Nat
+
+## If the string begins with a [Unicode code point](http://www.unicode.org/glossary/#code_point)
+## equal to the given [U32], return `True`. Otherwise return `False`.
+##
+## If the given [Str] is empty, or if the given [U32] is not a valid
+## code point, this will return `False`.
+##
+## **Performance Note:** This runs slightly faster than [Str.startsWith], so
+## if you want to check whether a string begins with something that's representable
+## in a single code point, you can use (for example) `Str.startsWithScalar '鹏'`
+## instead of `Str.startsWithScalar "鹏"`. ('鹏' evaluates to the [U32]
+## value `40527`.) This will not work for graphemes which take up multiple code
+## points, however; `Str.startsWithScalar '👩‍👩‍👦‍👦'` would be a compiler error
+## because 👩‍👩‍👦‍👦 takes up multiple code points and cannot be represented as a
+## single [U32]. You'd need to use `Str.startsWithScalar "🕊"` instead.
+startsWithScalar : Str, U32 -> Bool
+
+## Return a [List] of the [unicode scalar values](https://unicode.org/glossary/#unicode_scalar_value)
+## in the given string.
+##
+## (Strings contain only scalar values, not [surrogate code points](https://unicode.org/glossary/#surrogate_code_point),
+## so this is equivalent to returning a list of the string's [code points](https://unicode.org/glossary/#code_point).)
+toScalars : Str -> List U32
+
+## Return a [List] of the string's [U8] UTF-8 [code units](https://unicode.org/glossary/#code_unit).
+## (To split the string into a [List] of smaller [Str] values instead of [U8] values,
+## see [Str.split].)
+##
+## >>> Str.toUtf8 "👩‍👩‍👦‍👦"
+##
+## >>> Str.toUtf8 "Roc"
+##
+## >>> Str.toUtf8 "鹏"
+##
+## >>> Str.toUtf8 "🐦"
+toUtf8 : Str -> List U8
+
+# fromUtf8 : List U8 -> Result Str [BadUtf8 Utf8Problem]*
+# fromUtf8Range : List U8 -> Result Str [BadUtf8 Utf8Problem Nat, OutOfBounds]*
+fromUtf8 : List U8 -> Result Str [BadUtf8 Utf8ByteProblem Nat]*
+fromUtf8Range : List U8, { start : Nat, count : Nat } -> Result Str [BadUtf8 Utf8ByteProblem Nat, OutOfBounds]*
+
+startsWith : Str, Str -> Bool
+endsWith : Str, Str -> Bool
+
+## Return the string with any blank spaces removed from both the beginning
+## as well as the end.
+trim : Str -> Str
+trimLeft : Str -> Str
+trimRight : Str -> Str
+
+toDec : Str -> Result Dec [InvalidNumStr]*
+toF64 : Str -> Result F64 [InvalidNumStr]*
+toF32 : Str -> Result F32 [InvalidNumStr]*
+toNat : Str -> Result Nat [InvalidNumStr]*
+toU128 : Str -> Result U128 [InvalidNumStr]*
+toI128 : Str -> Result I128 [InvalidNumStr]*
+toU64 : Str -> Result U64 [InvalidNumStr]*
+toI64 : Str -> Result I64 [InvalidNumStr]*
+toU32 : Str -> Result U32 [InvalidNumStr]*
+toI32 : Str -> Result I32 [InvalidNumStr]*
+toU16 : Str -> Result U16 [InvalidNumStr]*
+toI16 : Str -> Result I16 [InvalidNumStr]*
+toU8 : Str -> Result U8 [InvalidNumStr]*
+toI8 : Str -> Result I8 [InvalidNumStr]*
+
+## Gets the byte at the given index, without performing a bounds check
+getUnsafe : Str, Nat -> U8
+
+## gives the number of string bytes
+countUtf8Bytes : Str -> Nat
+
+## string slice that does not do bounds checking or utf-8 verification
+substringUnsafe : Str, Nat, Nat -> Str
+
+## Returns the string before the first occurrence of a delimiter, as well as the
+## rest of the string after that occurrence. If the delimiter is not found, returns `Err`.
+##
+##     Str.splitFirst "foo/bar/baz" "/" == Ok { before: "foo", after: "bar/baz" }
+splitFirst : Str, Str -> Result { before : Str, after : Str } [NotFound]*
+splitFirst = \haystack, needle ->
+    when firstMatch haystack needle is
+        Some index ->
+            remaining = Str.countUtf8Bytes haystack - Str.countUtf8Bytes needle - index
+
+            before = Str.substringUnsafe haystack 0 index
+            after = Str.substringUnsafe haystack (index + Str.countUtf8Bytes needle) remaining
+
+            Ok { before, after }
+        None ->
+            Err NotFound
+
+firstMatch : Str, Str -> [Some Nat, None]
+firstMatch = \haystack, needle ->
+    haystackLength = Str.countUtf8Bytes haystack
+    needleLength = Str.countUtf8Bytes needle
+    lastPossible = Num.subSaturated haystackLength needleLength
+
+    firstMatchHelp haystack needle 0 lastPossible
+
+firstMatchHelp : Str, Str, Nat, Nat -> [Some Nat, None]
+firstMatchHelp = \haystack, needle, index, lastPossible ->
+    if index < lastPossible then
+        if matchesAt haystack index needle then
+            Some index
+        else
+            firstMatchHelp haystack needle (index + 1) lastPossible
+    else
+        None
+
+## Returns the string before the last occurrence of a delimiter, as well as the
+## rest of the string after that occurrence. If the delimiter is not found, returns `Err`.
+##
+##     Str.splitLast "foo/bar/baz" "/" == Ok { before: "foo/bar", after: "baz" }
+splitLast : Str, Str -> Result { before : Str, after : Str } [NotFound]*
+splitLast = \haystack, needle ->
+    when lastMatch haystack needle is
+        Some index ->
+            remaining = Str.countUtf8Bytes haystack - Str.countUtf8Bytes needle - index
+
+            before = Str.substringUnsafe haystack 0 index
+            after = Str.substringUnsafe haystack (index + Str.countUtf8Bytes needle) remaining
+
+            Ok { before, after }
+        None ->
+            Err NotFound
+
+lastMatch : Str, Str -> [Some Nat, None]
+lastMatch = \haystack, needle ->
+    haystackLength = Str.countUtf8Bytes haystack
+    needleLength = Str.countUtf8Bytes needle
+    lastPossibleIndex = Num.subSaturated haystackLength (needleLength + 1)
+
+    lastMatchHelp haystack needle lastPossibleIndex
+
+lastMatchHelp : Str, Str, Nat -> [Some Nat, None]
+lastMatchHelp = \haystack, needle, index ->
+    if matchesAt haystack index needle then
+        Some index
+    else
+        when Num.subChecked index 1 is
+            Ok nextIndex ->
+                lastMatchHelp haystack needle nextIndex
+            Err _ ->
+                None
+
+min = \x, y -> if x < y then x else y
+
+matchesAt : Str, Nat, Str -> Bool
+matchesAt = \haystack, haystackIndex, needle ->
+    haystackLength = Str.countUtf8Bytes haystack
+    needleLength = Str.countUtf8Bytes needle
+    endIndex = min (haystackIndex + needleLength) haystackLength
+
+    matchesAtHelp haystack haystackIndex needle 0 endIndex
+
+matchesAtHelp : Str, Nat, Str, Nat, Nat -> Bool
+matchesAtHelp = \haystack, haystackIndex, needle, needleIndex, endIndex ->
+    if haystackIndex < endIndex then
+        if Str.getUnsafe haystack haystackIndex == Str.getUnsafe needle needleIndex then
+            matchesAtHelp haystack (haystackIndex + 1) needle (needleIndex + 1) endIndex
+        else
+            False
+    else
+        True
+
+## Walks over the string's UTF-8 bytes, calling a function which updates a state using each
+## UTF-8 `U8` byte as well as the index of that byte within the string.
+walkUtf8WithIndex : Str, state, (state, U8, Nat -> state) -> state
+walkUtf8WithIndex = \string, state, step ->
+    walkUtf8WithIndexHelp string state step 0 (Str.countUtf8Bytes string)
+
+walkUtf8WithIndexHelp : Str, state, (state, U8, Nat -> state), Nat, Nat -> state
+walkUtf8WithIndexHelp = \string, state, step, index, length ->
+    if index < length then
+        byte = Str.getUnsafe string index
+        newState = step state byte index
+
+        walkUtf8WithIndexHelp string newState step (index + 1) length
+    else
+        state
+
+## Make sure at least some number of bytes fit in this string without reallocating
+reserve : Str, Nat -> Str
+
+## is UB when the scalar is invalid
+appendScalarUnsafe : Str, U32 -> Str
+
+appendScalar : Str, U32 -> Result Str [InvalidScalar]*
+appendScalar = \string, scalar ->
+    if isValidScalar scalar then
+        Ok (appendScalarUnsafe string scalar)
+    else
+        Err InvalidScalar
+
+isValidScalar : U32 -> Bool
+isValidScalar = \scalar ->
+    scalar <= 0xD7FF || (scalar >= 0xE000 && scalar <= 0x10FFFF)
+
+getScalarUnsafe : Str, Nat -> { scalar : U32, bytesParsed : Nat }
+
+walkScalars : Str, state, (state, U32 -> state) -> state
+walkScalars = \string, init, step ->
+    walkScalarsHelp string init step 0 (Str.countUtf8Bytes string)
+
+walkScalarsHelp : Str, state, (state, U32 -> state), Nat, Nat -> state
+walkScalarsHelp = \string, state, step, index, length ->
+    if index < length then
+        { scalar, bytesParsed } = getScalarUnsafe string index
+        newState = step state scalar
+
+        walkScalarsHelp string newState step (index + bytesParsed) length
+    else
+        state
+
+walkScalarsUntil : Str, state, (state, U32 -> [Break state, Continue state]) -> state
+walkScalarsUntil = \string, init, step ->
+    walkScalarsUntilHelp string init step 0 (Str.countUtf8Bytes string)
+
+walkScalarsUntilHelp : Str, state, (state, U32 -> [Break state, Continue state]), Nat, Nat -> state
+walkScalarsUntilHelp = \string, state, step, index, length ->
+    if index < length then
+        { scalar, bytesParsed } = getScalarUnsafe string index
+
+        when step state scalar is
+            Continue newState ->
+                walkScalarsUntilHelp string newState step (index + bytesParsed) length
+            Break newState ->
+                newState
+    else
+        state

crates/compiler/builtins/src/bitcode.rs

@@ -0,0 +1,445 @@
+use roc_module::symbol::Symbol;
+use roc_target::TargetInfo;
+use std::ops::Index;
+
+pub const BUILTINS_HOST_OBJ_PATH: &str = env!(
+    "BUILTINS_HOST_O",
+    "Env var BUILTINS_HOST_O not found. Is there a problem with the build script?"
+);
+
+pub const BUILTINS_WASM32_OBJ_PATH: &str = env!(
+    "BUILTINS_WASM32_O",
+    "Env var BUILTINS_WASM32_O not found. Is there a problem with the build script?"
+);
+
+#[derive(Debug, Default, Copy, Clone)]
+pub struct IntrinsicName {
+    pub options: [&'static str; 14],
+}
+
+impl IntrinsicName {
+    pub const fn default() -> Self {
+        Self { options: [""; 14] }
+    }
+}
+
+#[repr(u8)]
+pub enum DecWidth {
+    Dec,
+}
+
+#[repr(u8)]
+#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug, PartialOrd, Ord)]
+pub enum FloatWidth {
+    F32,
+    F64,
+    F128,
+}
+
+impl FloatWidth {
+    pub const fn stack_size(&self) -> u32 {
+        use FloatWidth::*;
+
+        // NOTE: this must never use mem::size_of, because that returns the size
+        // for the target of *the compiler itself* (e.g. this Rust code), not what
+        // the compiler is targeting (e.g. what the Roc code will be compiled to).
+        match self {
+            F32 => 4,
+            F64 => 8,
+            F128 => 16,
+        }
+    }
+
+    pub const fn alignment_bytes(&self, target_info: TargetInfo) -> u32 {
+        use roc_target::Architecture;
+        use FloatWidth::*;
+
+        // NOTE: this must never use mem::align_of, because that returns the alignment
+        // for the target of *the compiler itself* (e.g. this Rust code), not what
+        // the compiler is targeting (e.g. what the Roc code will be compiled to).
+        match self {
+            F32 => 4,
+            F64 | F128 => match target_info.architecture {
+                Architecture::X86_64 | Architecture::Aarch64 | Architecture::Wasm32 => 8,
+                Architecture::X86_32 | Architecture::Aarch32 => 4,
+            },
+        }
+    }
+
+    pub const fn try_from_symbol(symbol: Symbol) -> Option<Self> {
+        match symbol {
+            Symbol::NUM_F64 | Symbol::NUM_BINARY64 => Some(FloatWidth::F64),
+            Symbol::NUM_F32 | Symbol::NUM_BINARY32 => Some(FloatWidth::F32),
+            _ => None,
+        }
+    }
+}
+
+#[repr(u8)]
+#[derive(Copy, Clone, PartialEq, Eq, Hash, Debug, PartialOrd, Ord)]
+pub enum IntWidth {
+    U8 = 0,
+    U16 = 1,
+    U32 = 2,
+    U64 = 3,
+    U128 = 4,
+    I8 = 5,
+    I16 = 6,
+    I32 = 7,
+    I64 = 8,
+    I128 = 9,
+}
+
+impl IntWidth {
+    pub const fn is_signed(&self) -> bool {
+        use IntWidth::*;
+
+        matches!(self, I8 | I16 | I32 | I64 | I128)
+    }
+
+    pub const fn stack_size(&self) -> u32 {
+        use IntWidth::*;
+
+        // NOTE: this must never use mem::size_of, because that returns the size
+        // for the target of *the compiler itself* (e.g. this Rust code), not what
+        // the compiler is targeting (e.g. what the Roc code will be compiled to).
+        match self {
+            U8 | I8 => 1,
+            U16 | I16 => 2,
+            U32 | I32 => 4,
+            U64 | I64 => 8,
+            U128 | I128 => 16,
+        }
+    }
+
+    pub const fn alignment_bytes(&self, target_info: TargetInfo) -> u32 {
+        use roc_target::Architecture;
+        use IntWidth::*;
+
+        // NOTE: this must never use mem::align_of, because that returns the alignment
+        // for the target of *the compiler itself* (e.g. this Rust code), not what
+        // the compiler is targeting (e.g. what the Roc code will be compiled to).
+        match self {
+            U8 | I8 => 1,
+            U16 | I16 => 2,
+            U32 | I32 => 4,
+            U64 | I64 => match target_info.architecture {
+                Architecture::X86_64
+                | Architecture::Aarch64
+                | Architecture::Aarch32
+                | Architecture::Wasm32 => 8,
+                Architecture::X86_32 => 4,
+            },
+            U128 | I128 => {
+                // the C ABI defines 128-bit integers to always be 16B aligned,
+                // according to https://reviews.llvm.org/D28990#655487
+                16
+            }
+        }
+    }
+
+    pub const fn try_from_symbol(symbol: Symbol) -> Option<Self> {
+        match symbol {
+            Symbol::NUM_I128 | Symbol::NUM_SIGNED128 => Some(IntWidth::I128),
+            Symbol::NUM_I64 | Symbol::NUM_SIGNED64 => Some(IntWidth::I64),
+            Symbol::NUM_I32 | Symbol::NUM_SIGNED32 => Some(IntWidth::I32),
+            Symbol::NUM_I16 | Symbol::NUM_SIGNED16 => Some(IntWidth::I16),
+            Symbol::NUM_I8 | Symbol::NUM_SIGNED8 => Some(IntWidth::I8),
+            Symbol::NUM_U128 | Symbol::NUM_UNSIGNED128 => Some(IntWidth::U128),
+            Symbol::NUM_U64 | Symbol::NUM_UNSIGNED64 => Some(IntWidth::U64),
+            Symbol::NUM_U32 | Symbol::NUM_UNSIGNED32 => Some(IntWidth::U32),
+            Symbol::NUM_U16 | Symbol::NUM_UNSIGNED16 => Some(IntWidth::U16),
+            Symbol::NUM_U8 | Symbol::NUM_UNSIGNED8 => Some(IntWidth::U8),
+            _ => None,
+        }
+    }
+
+    pub const fn type_name(&self) -> &'static str {
+        match self {
+            Self::I8 => "i8",
+            Self::I16 => "i16",
+            Self::I32 => "i32",
+            Self::I64 => "i64",
+            Self::I128 => "i128",
+            Self::U8 => "u8",
+            Self::U16 => "u16",
+            Self::U32 => "u32",
+            Self::U64 => "u64",
+            Self::U128 => "u128",
+        }
+    }
+}
+
+impl Index<DecWidth> for IntrinsicName {
+    type Output = str;
+
+    fn index(&self, _: DecWidth) -> &Self::Output {
+        self.options[0]
+    }
+}
+
+impl Index<FloatWidth> for IntrinsicName {
+    type Output = str;
+
+    fn index(&self, index: FloatWidth) -> &Self::Output {
+        match index {
+            FloatWidth::F32 => self.options[1],
+            FloatWidth::F64 => self.options[2],
+            FloatWidth::F128 => self.options[3],
+        }
+    }
+}
+
+impl Index<IntWidth> for IntrinsicName {
+    type Output = str;
+
+    fn index(&self, index: IntWidth) -> &Self::Output {
+        match index {
+            IntWidth::U8 => self.options[4],
+            IntWidth::U16 => self.options[5],
+            IntWidth::U32 => self.options[6],
+            IntWidth::U64 => self.options[7],
+            IntWidth::U128 => self.options[8],
+            IntWidth::I8 => self.options[9],
+            IntWidth::I16 => self.options[10],
+            IntWidth::I32 => self.options[11],
+            IntWidth::I64 => self.options[12],
+            IntWidth::I128 => self.options[13],
+        }
+    }
+}
+
+#[macro_export]
+macro_rules! float_intrinsic {
+    ($name:literal) => {{
+        let mut output = IntrinsicName::default();
+
+        output.options[1] = concat!($name, ".f32");
+        output.options[2] = concat!($name, ".f64");
+        output.options[3] = concat!($name, ".f128");
+
+        output
+    }};
+}
+
+#[macro_export]
+macro_rules! llvm_int_intrinsic {
+    ($signed_name:literal, $unsigned_name:literal) => {{
+        let mut output = IntrinsicName::default();
+
+        // The indeces align with the `Index` impl for `IntrinsicName`.
+        // LLVM uses the same types for both signed and unsigned integers.
+        output.options[4] = concat!($unsigned_name, ".i8");
+        output.options[5] = concat!($unsigned_name, ".i16");
+        output.options[6] = concat!($unsigned_name, ".i32");
+        output.options[7] = concat!($unsigned_name, ".i64");
+        output.options[8] = concat!($unsigned_name, ".i128");
+
+        output.options[9] = concat!($signed_name, ".i8");
+        output.options[10] = concat!($signed_name, ".i16");
+        output.options[11] = concat!($signed_name, ".i32");
+        output.options[12] = concat!($signed_name, ".i64");
+        output.options[13] = concat!($signed_name, ".i128");
+
+        output
+    }};
+
+    ($name:literal) => {
+        int_intrinsic!($name, $name)
+    };
+}
+
+#[macro_export]
+macro_rules! int_intrinsic {
+    ($name:expr) => {{
+        let mut output = IntrinsicName::default();
+
+        // The indices align with the `Index` impl for `IntrinsicName`.
+        output.options[4] = concat!($name, ".u8");
+        output.options[5] = concat!($name, ".u16");
+        output.options[6] = concat!($name, ".u32");
+        output.options[7] = concat!($name, ".u64");
+        output.options[8] = concat!($name, ".u128");
+
+        output.options[9] = concat!($name, ".i8");
+        output.options[10] = concat!($name, ".i16");
+        output.options[11] = concat!($name, ".i32");
+        output.options[12] = concat!($name, ".i64");
+        output.options[13] = concat!($name, ".i128");
+
+        output
+    }};
+}
+
+pub const NUM_SIN: IntrinsicName = float_intrinsic!("roc_builtins.num.sin");
+pub const NUM_COS: IntrinsicName = float_intrinsic!("roc_builtins.num.cos");
+pub const NUM_ASIN: IntrinsicName = float_intrinsic!("roc_builtins.num.asin");
+pub const NUM_ACOS: IntrinsicName = float_intrinsic!("roc_builtins.num.acos");
+pub const NUM_ATAN: IntrinsicName = float_intrinsic!("roc_builtins.num.atan");
+pub const NUM_IS_FINITE: IntrinsicName = float_intrinsic!("roc_builtins.num.is_finite");
+pub const NUM_LOG: IntrinsicName = float_intrinsic!("roc_builtins.num.log");
+pub const NUM_POW: IntrinsicName = float_intrinsic!("roc_builtins.num.pow");
+
+pub const NUM_POW_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.pow_int");
+pub const NUM_DIV_CEIL: IntrinsicName = int_intrinsic!("roc_builtins.num.div_ceil");
+pub const NUM_ROUND_F32: IntrinsicName = int_intrinsic!("roc_builtins.num.round_f32");
+pub const NUM_ROUND_F64: IntrinsicName = int_intrinsic!("roc_builtins.num.round_f64");
+
+pub const NUM_ADD_OR_PANIC_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.add_or_panic");
+pub const NUM_ADD_SATURATED_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.add_saturated");
+pub const NUM_ADD_CHECKED_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.add_with_overflow");
+pub const NUM_ADD_CHECKED_FLOAT: IntrinsicName =
+    float_intrinsic!("roc_builtins.num.add_with_overflow");
+
+pub const NUM_SUB_OR_PANIC_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.sub_or_panic");
+pub const NUM_SUB_SATURATED_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.sub_saturated");
+pub const NUM_SUB_CHECKED_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.sub_with_overflow");
+pub const NUM_SUB_CHECKED_FLOAT: IntrinsicName =
+    float_intrinsic!("roc_builtins.num.sub_with_overflow");
+
+pub const NUM_MUL_OR_PANIC_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.mul_or_panic");
+pub const NUM_MUL_SATURATED_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.mul_saturated");
+pub const NUM_MUL_CHECKED_INT: IntrinsicName = int_intrinsic!("roc_builtins.num.mul_with_overflow");
+pub const NUM_MUL_CHECKED_FLOAT: IntrinsicName =
+    float_intrinsic!("roc_builtins.num.mul_with_overflow");
+
+pub const NUM_BYTES_TO_U16: &str = "roc_builtins.num.bytes_to_u16";
+pub const NUM_BYTES_TO_U32: &str = "roc_builtins.num.bytes_to_u32";
+
+pub const STR_INIT: &str = "roc_builtins.str.init";
+pub const STR_COUNT_SEGMENTS: &str = "roc_builtins.str.count_segments";
+pub const STR_CONCAT: &str = "roc_builtins.str.concat";
+pub const STR_JOIN_WITH: &str = "roc_builtins.str.joinWith";
+pub const STR_STR_SPLIT: &str = "roc_builtins.str.str_split";
+pub const STR_STR_SPLIT_IN_PLACE: &str = "roc_builtins.str.str_split_in_place";
+pub const STR_TO_SCALARS: &str = "roc_builtins.str.to_scalars";
+pub const STR_COUNT_GRAPEHEME_CLUSTERS: &str = "roc_builtins.str.count_grapheme_clusters";
+pub const STR_COUNT_UTF8_BYTES: &str = "roc_builtins.str.count_utf8_bytes";
+pub const STR_STARTS_WITH: &str = "roc_builtins.str.starts_with";
+pub const STR_STARTS_WITH_SCALAR: &str = "roc_builtins.str.starts_with_scalar";
+pub const STR_ENDS_WITH: &str = "roc_builtins.str.ends_with";
+pub const STR_NUMBER_OF_BYTES: &str = "roc_builtins.str.number_of_bytes";
+pub const STR_FROM_INT: IntrinsicName = int_intrinsic!("roc_builtins.str.from_int");
+pub const STR_FROM_FLOAT: &str = "roc_builtins.str.from_float";
+pub const STR_TO_INT: IntrinsicName = int_intrinsic!("roc_builtins.str.to_int");
+pub const STR_TO_FLOAT: IntrinsicName = float_intrinsic!("roc_builtins.str.to_float");
+pub const STR_TO_DECIMAL: &str = "roc_builtins.str.to_decimal";
+pub const STR_EQUAL: &str = "roc_builtins.str.equal";
+pub const STR_SUBSTRING_UNSAFE: &str = "roc_builtins.str.substring_unsafe";
+pub const STR_TO_UTF8: &str = "roc_builtins.str.to_utf8";
+pub const STR_FROM_UTF8: &str = "roc_builtins.str.from_utf8";
+pub const STR_FROM_UTF8_RANGE: &str = "roc_builtins.str.from_utf8_range";
+pub const STR_REPEAT: &str = "roc_builtins.str.repeat";
+pub const STR_TRIM: &str = "roc_builtins.str.trim";
+pub const STR_TRIM_LEFT: &str = "roc_builtins.str.trim_left";
+pub const STR_TRIM_RIGHT: &str = "roc_builtins.str.trim_right";
+pub const STR_GET_UNSAFE: &str = "roc_builtins.str.get_unsafe";
+pub const STR_RESERVE: &str = "roc_builtins.str.reserve";
+pub const STR_APPEND_SCALAR: &str = "roc_builtins.str.append_scalar";
+pub const STR_GET_SCALAR_UNSAFE: &str = "roc_builtins.str.get_scalar_unsafe";
+
+pub const DICT_HASH: &str = "roc_builtins.dict.hash";
+pub const DICT_HASH_STR: &str = "roc_builtins.dict.hash_str";
+pub const DICT_LEN: &str = "roc_builtins.dict.len";
+pub const DICT_EMPTY: &str = "roc_builtins.dict.empty";
+pub const DICT_INSERT: &str = "roc_builtins.dict.insert";
+pub const DICT_REMOVE: &str = "roc_builtins.dict.remove";
+pub const DICT_CONTAINS: &str = "roc_builtins.dict.contains";
+pub const DICT_GET: &str = "roc_builtins.dict.get";
+pub const DICT_ELEMENTS_RC: &str = "roc_builtins.dict.elementsRc";
+pub const DICT_KEYS: &str = "roc_builtins.dict.keys";
+pub const DICT_VALUES: &str = "roc_builtins.dict.values";
+pub const DICT_UNION: &str = "roc_builtins.dict.union";
+pub const DICT_DIFFERENCE: &str = "roc_builtins.dict.difference";
+pub const DICT_INTERSECTION: &str = "roc_builtins.dict.intersection";
+pub const DICT_WALK: &str = "roc_builtins.dict.walk";
+
+pub const SET_FROM_LIST: &str = "roc_builtins.dict.set_from_list";
+
+pub const LIST_MAP: &str = "roc_builtins.list.map";
+pub const LIST_MAP2: &str = "roc_builtins.list.map2";
+pub const LIST_MAP3: &str = "roc_builtins.list.map3";
+pub const LIST_MAP4: &str = "roc_builtins.list.map4";
+pub const LIST_APPEND: &str = "roc_builtins.list.append";
+pub const LIST_PREPEND: &str = "roc_builtins.list.prepend";
+pub const LIST_SUBLIST: &str = "roc_builtins.list.sublist";
+pub const LIST_DROP_AT: &str = "roc_builtins.list.drop_at";
+pub const LIST_SWAP: &str = "roc_builtins.list.swap";
+pub const LIST_WITH_CAPACITY: &str = "roc_builtins.list.with_capacity";
+pub const LIST_SORT_WITH: &str = "roc_builtins.list.sort_with";
+pub const LIST_CONCAT: &str = "roc_builtins.list.concat";
+pub const LIST_REPLACE: &str = "roc_builtins.list.replace";
+pub const LIST_REPLACE_IN_PLACE: &str = "roc_builtins.list.replace_in_place";
+pub const LIST_IS_UNIQUE: &str = "roc_builtins.list.is_unique";
+
+pub const DEC_FROM_STR: &str = "roc_builtins.dec.from_str";
+pub const DEC_FROM_F64: &str = "roc_builtins.dec.from_f64";
+pub const DEC_EQ: &str = "roc_builtins.dec.eq";
+pub const DEC_NEQ: &str = "roc_builtins.dec.neq";
+pub const DEC_NEGATE: &str = "roc_builtins.dec.negate";
+pub const DEC_MUL_WITH_OVERFLOW: &str = "roc_builtins.dec.mul_with_overflow";
+pub const DEC_DIV: &str = "roc_builtins.dec.div";
+pub const DEC_ADD_WITH_OVERFLOW: &str = "roc_builtins.dec.add_with_overflow";
+pub const DEC_ADD_OR_PANIC: &str = "roc_builtins.dec.add_or_panic";
+pub const DEC_ADD_SATURATED: &str = "roc_builtins.dec.add_saturated";
+pub const DEC_SUB_WITH_OVERFLOW: &str = "roc_builtins.dec.sub_with_overflow";
+pub const DEC_SUB_OR_PANIC: &str = "roc_builtins.dec.sub_or_panic";
+pub const DEC_SUB_SATURATED: &str = "roc_builtins.dec.sub_saturated";
+pub const DEC_MUL_OR_PANIC: &str = "roc_builtins.dec.mul_or_panic";
+pub const DEC_MUL_SATURATED: &str = "roc_builtins.dec.mul_saturated";
+
+pub const UTILS_TEST_PANIC: &str = "roc_builtins.utils.test_panic";
+pub const UTILS_ALLOCATE_WITH_REFCOUNT: &str = "roc_builtins.utils.allocate_with_refcount";
+pub const UTILS_INCREF: &str = "roc_builtins.utils.incref";
+pub const UTILS_DECREF: &str = "roc_builtins.utils.decref";
+pub const UTILS_DECREF_CHECK_NULL: &str = "roc_builtins.utils.decref_check_null";
+
+pub const UTILS_LONGJMP: &str = "longjmp";
+pub const UTILS_SETJMP: &str = "setjmp";
+
+#[derive(Debug, Default)]
+pub struct IntToIntrinsicName {
+    pub options: [IntrinsicName; 10],
+}
+
+impl IntToIntrinsicName {
+    pub const fn default() -> Self {
+        Self {
+            options: [IntrinsicName::default(); 10],
+        }
+    }
+}
+
+impl Index<IntWidth> for IntToIntrinsicName {
+    type Output = IntrinsicName;
+
+    fn index(&self, index: IntWidth) -> &Self::Output {
+        &self.options[index as usize]
+    }
+}
+
+#[macro_export]
+macro_rules! int_to_int_intrinsic {
+    ($name_prefix:literal, $name_suffix:literal) => {{
+        let mut output = IntToIntrinsicName::default();
+
+        output.options[0] = int_intrinsic!(concat!($name_prefix, "u8", $name_suffix));
+        output.options[1] = int_intrinsic!(concat!($name_prefix, "u16", $name_suffix));
+        output.options[2] = int_intrinsic!(concat!($name_prefix, "u32", $name_suffix));
+        output.options[3] = int_intrinsic!(concat!($name_prefix, "u64", $name_suffix));
+        output.options[4] = int_intrinsic!(concat!($name_prefix, "u128", $name_suffix));
+
+        output.options[5] = int_intrinsic!(concat!($name_prefix, "i8", $name_suffix));
+        output.options[6] = int_intrinsic!(concat!($name_prefix, "i16", $name_suffix));
+        output.options[7] = int_intrinsic!(concat!($name_prefix, "i32", $name_suffix));
+        output.options[8] = int_intrinsic!(concat!($name_prefix, "i64", $name_suffix));
+        output.options[9] = int_intrinsic!(concat!($name_prefix, "i128", $name_suffix));
+
+        output
+    }};
+}
+
+pub const NUM_INT_TO_INT_CHECKING_MAX: IntToIntrinsicName =
+    int_to_int_intrinsic!("roc_builtins.num.int_to_", "_checking_max");
+pub const NUM_INT_TO_INT_CHECKING_MAX_AND_MIN: IntToIntrinsicName =
+    int_to_int_intrinsic!("roc_builtins.num.int_to_", "_checking_max_and_min");

crates/compiler/builtins/src/lib.rs

@@ -0,0 +1,6 @@
+#![warn(clippy::dbg_macro)]
+// See github.com/rtfeldman/roc/issues/800 for discussion of the large_enum_variant check.
+#![allow(clippy::large_enum_variant)]
+pub mod bitcode;
+pub mod roc;
+pub mod std;

crates/compiler/builtins/src/roc.rs

@@ -0,0 +1,32 @@
+use roc_module::symbol::ModuleId;
+
+#[inline(always)]
+pub fn module_source(module_id: ModuleId) -> &'static str {
+    match module_id {
+        ModuleId::RESULT => RESULT,
+        ModuleId::NUM => NUM,
+        ModuleId::STR => STR,
+        ModuleId::LIST => LIST,
+        ModuleId::DICT => DICT,
+        ModuleId::SET => SET,
+        ModuleId::BOX => BOX,
+        ModuleId::BOOL => BOOL,
+        ModuleId::ENCODE => ENCODE,
+        ModuleId::JSON => JSON,
+        _ => panic!(
+            "ModuleId {:?} is not part of the standard library",
+            module_id
+        ),
+    }
+}
+
+const RESULT: &str = include_str!("../roc/Result.roc");
+const NUM: &str = include_str!("../roc/Num.roc");
+const STR: &str = include_str!("../roc/Str.roc");
+const LIST: &str = include_str!("../roc/List.roc");
+const DICT: &str = include_str!("../roc/Dict.roc");
+const SET: &str = include_str!("../roc/Set.roc");
+const BOX: &str = include_str!("../roc/Box.roc");
+const BOOL: &str = include_str!("../roc/Bool.roc");
+const ENCODE: &str = include_str!("../roc/Encode.roc");
+const JSON: &str = include_str!("../roc/Json.roc");