The Oxide Programming Language

Oxide is an alternative syntax for Rust that compiles to identical binaries via the Rust toolchain. It keeps Rust's performance, safety, and ecosystem while offering a more approachable, Swift/Kotlin-inspired surface syntax.

This book teaches Oxide from first principles. If you already know Rust, you will recognize the concepts and semantics, but the syntax will feel different. If you are new to systems programming, this book is designed to be friendly, incremental, and practical.

What You Will Learn

• The core language constructs: variables, types, functions, and control flow
• Ownership, borrowing, and lifetimes (the same rules as Rust)
• Structs, enums, pattern matching, and traits
• Error handling with Result, ?, and Oxide's nullability operators
• Modules, packages, and the Cargo build system
• Concurrency and async programming
• How to build real programs in Oxide

How to Use This Book

The chapters build on each other. Follow them in order if you are new to Rust or systems programming. If you are experienced, you can jump to the chapters you care about most.

Throughout the book, you will see Oxide examples and occasional Rust equivalents to highlight syntax differences. The semantics are the same unless explicitly stated otherwise.

Foreword

Oxide exists to make Rust more approachable without compromising what makes Rust powerful. It is not a new runtime or a new ecosystem; it is a different syntax for the same language and compiler.

This book is adapted from The Rust Programming Language and follows its structure, examples, and teaching philosophy while presenting everything in Oxide syntax. Rust's core ideas - ownership, borrowing, lifetimes, and fearless concurrency - remain intact. Oxide simply presents those ideas with syntax that many developers already find familiar.

If you are a Rustacean, we hope this book feels like a friendly translation. If you are new to Rust, we hope the Oxide syntax helps you get to the ideas faster. In either case, thank you for exploring Oxide with us.

The Oxide Programming Language

Welcome to The Oxide Programming Language, an introductory book about Oxide.

Oxide is an alternative syntax for Rust that provides familiar Swift/Kotlin-inspired conventions while producing identical binary output to equivalent Rust code. It maintains all of Rust's safety guarantees, ownership model, and performance while making systems programming more accessible.

Who This Book Is For

This book is for developers transitioning from Swift, Kotlin, TypeScript, or C# who want to leverage Rust's performance and safety guarantees without navigating its unfamiliar syntax.

How to Use This Book

This book follows the same structure as The Rust Programming Language book. If you're already familiar with Rust, you can skip to the specific chapters that cover Oxide's syntax differences.

Rust Syntax Fallbacks (Important)

Oxide intentionally changes parts of Rust's grammar. Those Rust spellings are syntax errors in Oxide code (for example, ::, =>, and let mut). However, when there is no Oxide-specific alternative and no conflict with Oxide syntax, Oxide accepts Rust syntax as a compatibility fallback. Examples include try { }, const { }, impl Trait in return position, async move { }, and Rust-style macros like format!.

Rust's Option<T>, Some, and None are also accepted for interop, but idiomatic Oxide uses T? and null.

Getting Started

This chapter helps you set up the Oxide toolchain and write your first programs. You'll install the compiler, print a classic greeting, and use Cargo to create and manage a project.

What You'll Learn

• How to install the Oxide compiler and toolchain
• How to compile and run a simple .ox program
• How to use Cargo to create and build a project

Chapter Roadmap

1. Installation - Install the toolchain and verify your setup
2. Hello, World! - Write and run a tiny Oxide program
3. Hello, Cargo! - Create a project with Cargo and run it

If you already have the toolchain installed, feel free to skip ahead to the Hello World section.

Installation

Let's get Oxide set up on your computer! We'll install the necessary tools to compile and run Oxide programs.

What is Oxide?

Oxide is an alternative syntax for Rust that compiles to identical binary output via a rustc fork. If you're coming from Swift, Kotlin, TypeScript, or C#, Oxide's syntax will feel familiar while giving you access to Rust's powerful safety guarantees and performance.

Key points about Oxide:

• Rust with familiar syntax: Oxide uses Swift/Kotlin-inspired conventions as an alternative to Rust's conventions
• 100% compatible with Rust: Both .ox files (Oxide) and .rs files (Rust) can coexist in the same project
• Same performance: Oxide compiles to the exact same machine code as Rust—zero runtime overhead
• All of Rust's power: You get ownership, borrowing, the type system, traits, generics, and everything else that makes Rust safe

Let's look at a quick example of what Oxide looks like:

// Oxide: familiar and readable
fn greet(name: &str): String {
    "Hello, \(name)!"
}

Compared to equivalent Rust:

#![allow(unused)]
fn main() {
// Rust: using Rust's conventions
fn greet(name: &str) -> String {
    format!("Hello, {}", name)
}
}

Both compile to identical code. The difference is the syntax.

Prerequisites

Before installing Oxide, you'll need:

1. Rust toolchain - The Rust compiler (rustc), Cargo package manager, and Rust standard library
2. A text editor or IDE - Any editor works; VS Code with Rust Analyzer is recommended
3. A terminal - Oxide development happens on the command line

Since Oxide compiles via a rustc fork, having the standard Rust toolchain installed is essential, even though you'll primarily use Oxide syntax.

Installation

Step 1: Install Rust

First, install Rust using rustup. Open your terminal and run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

This downloads and installs rustup, which manages your Rust toolchain. Follow the on-screen prompts.

On Windows, download and run rustup-init.exe from https://rustup.rs.

After installation, verify Rust is installed:

rustc --version
cargo --version

You should see version numbers for both.

Step 2: Install Oxide (Future Reference)

Note: The Oxide compiler is currently in development. This section describes how you'll install it once it's released.

Once available, you'll install the Oxide compiler via Cargo:

cargo install oxide-compiler

This installs the oxide-compiler command, which is the Oxide compiler. It's a wrapper around the rustc fork that handles .ox files transparently.

Verify the installation:

oxide-compiler --version

You should see the Oxide compiler version.

For Now: Setting Up Your First Project

While the compiler is under development, you can explore Oxide syntax and concepts by:

1. Reading this book and the examples
2. Experimenting with the ideas in Rust code
3. Preparing your workflow for when Oxide releases

Setting Up an Oxide Project

Creating a new Oxide project is straightforward using Cargo with the --oxide flag:

cargo new --oxide hello_oxide
cd hello_oxide

This creates an Oxide project with src/main.ox containing:

fn main() {
    println!("Hello, world!")
}

Development Status: Oxide v1.0 is currently in development. The Oxide compiler (a fork of rustc) and the --oxide flag for Cargo are being implemented and will be available when the Oxide toolchain is released. For early testing before the release, you can manually create a project with cargo new and rename src/main.rs to src/main.ox.

Here's what a basic project structure looks like:

hello_oxide/
├── Cargo.toml
└── src/
    ├── main.ox       # Your Oxide code
    └── lib.rs        # Optional: Rust library code (can coexist)

When you run cargo build or cargo run, Oxide files (.ox) and Rust files (.rs) work together seamlessly. Both compile to identical machine code.

Building and Running

Build and run your Oxide project:

cargo build
cargo run

The Oxide compiler processes your .ox files and compiles them via the rustc fork.

Troubleshooting

"command not found: oxide-compiler"

Ensure you've installed the Oxide compiler with cargo install oxide-compiler and that ~/.cargo/bin is in your PATH.

"Can't find Rust toolchain"

The Oxide compiler requires the Rust toolchain. Verify Rust is installed with rustc --version. If not, follow Step 1 above.

"Unknown file extension: .ox"

Make sure your file has the .ox extension (lowercase). Oxide files must use this specific extension to be recognized.

IDE/Editor support

If your editor doesn't recognize .ox files:

• VS Code: Install the Oxide extension (coming soon)
• Other editors: Configure them to treat .ox files as Rust for syntax highlighting until Oxide support is available

Moving Forward

You're now ready to start learning Oxide! The next chapter will guide you through writing your first program. Whether you're new to systems programming or transitioning from another language, Oxide provides syntax that may feel familiar while giving you access to Rust's excellent type system and safety guarantees.

If you get stuck, remember:

• The examples in this book are all valid Oxide code
• You can always reference the Rust equivalent to understand the underlying semantics
• Rust's extensive ecosystem documentation applies directly to Oxide code
• Both Oxide and Rust are valid choices—Oxide simply offers an alternative syntax

Happy coding!

Hello, World!

It's traditional to begin learning a new programming language by writing a little program that prints the text "Hello, world!" to the screen, so we'll do that here! You'll also write your first Oxide program.

Creating a Project Directory

First, create a directory where you'll store your Oxide code. It doesn't matter to Oxide where your code lives, but for the exercises and projects in this book, we suggest creating a projects directory in your home directory and keeping all your projects there.

Open a terminal and run the following commands to create a projects directory and a helloWorld project within it.

On Linux, macOS, and PowerShell on Windows, enter this:

$ mkdir ~/projects
$ cd ~/projects
$ mkdir hello_world
$ cd hello_world

On Windows CMD, enter this:

> mkdir %USERPROFILE%\projects
> cd /d %USERPROFILE%\projects
> mkdir hello_world
> cd hello_world

Writing and Running the Program

Next, make a new source file and call it main.ox. Oxide files always end with the .ox extension. If you're using more than one word in your filename, the convention is to use an underscore to separate them. For example, you'd use hello_world.ox rather than helloworld.ox.

Now open the main.ox file you just created and enter the code in Listing 1-1:

Filename: main.ox

fn main() {
    println!("Hello, world!")
}

Listing 1-1: A program that prints "Hello, world!"

Save the file and go back to your terminal window in the ~/projects/hello_world directory. On Linux or macOS, enter the following commands to compile and run the file:

$ oxide-compiler main.ox
$ ./main
Hello, world!

On Windows, enter:

> oxide-compiler main.ox
> .\main.exe
Hello, world!

Regardless of your operating system, the string Hello, world! should print to the terminal. If you didn't see this output, refer to the Troubleshooting section for ways to get help.

Anatomy of an Oxide Program

Let's review this "Hello, world!" program in detail. Here's the first piece:

fn main() {

}

These lines define a function named main. The main function is special: it's always the first code that runs in every executable Oxide program. We declare it using the keyword fn, and it takes no parameters and returns nothing. If there were parameters, they would go inside the parentheses (). Also notice that the function body is wrapped in curly brackets {}. Oxide requires curly brackets around all function bodies.

Next is this line:

    println!("Hello, world!")

This line does all the work in this little program. It calls the println! macro with the string "Hello, world!" as an argument. The ! indicates that println! is a macro rather than a normal function. (We'll learn more about macros in detail in Chapter 19.) The macro prints the string to the screen.

Semicolons and Optional Syntax

You might notice this program doesn't have a semicolon at the end of the println! line. In Oxide, semicolons are optional in most contexts. They're not required at the end of function calls or statements, so we'll omit them unless we need to separate two expressions on a single line:

fn main() {
    println!("Hello, world!")
}

Comparison with Rust

If you're familiar with Rust, you might notice some differences. In Rust, you would write:

fn main() {
    println!("Hello, world!");
}

The key differences between Oxide and Rust in this example:

1. File extension: Oxide uses .ox instead of .rs
2. Semicolons: Oxide makes them optional; Rust requires them
3. Compiler: Oxide uses oxide-compiler (the Oxide compiler, which is a rustc fork); Rust uses rustc

Everything else—the function syntax, the println! macro, and the overall program structure—is identical to Rust. This is because Oxide is fundamentally Rust with a different surface syntax.

Compiling and Running Are Separate Steps

You've just seen how to run a new program, but let me explain the process more fully.

Before running an Oxide program, you must compile it using the Oxide compiler, even for simple programs. The command is oxide-compiler followed by your source filename:

$ oxide-compiler main.ox

If you're on Windows, use:

> oxide-compiler main.ox

This command compiles your main.ox file and creates an executable called main (or main.exe on Windows). You can then run the executable:

On Linux or macOS:

$ ./main
Hello, world!

On Windows:

> .\main.exe
Hello, world!

Even for one-line programs, you need to explicitly compile before running. This follows Rust's ahead-of-time compilation approach, which differs from interpreted languages like Python or JavaScript where you can run code directly. The benefit is performance: compiled code runs much faster than interpreted code, and you catch errors at compile time rather than runtime.

Troubleshooting

The most common problems beginners encounter:

Command not found: oxide-compiler

This usually means the Oxide compiler isn't installed or isn't in your system's PATH. Refer to the Installation chapter to properly install Oxide.

Compilation errors

If you see errors when running oxide-compiler, double-check that:

• Your file is saved as main.ox (or another .ox filename)
• You're running the command from the directory containing your source file
• Your code matches Listing 1-1 exactly, including the curly brackets and parentheses

Program output doesn't appear

• On macOS or Linux, make sure you're using ./main (with the dot-slash) to run the executable
• On Windows, make sure you're using .\main.exe (with the backslash)
• If the window closes immediately on Windows, try running it from PowerShell or Command Prompt directly

Congratulations! You've officially written your first Oxide program. Next, we'll look at Oxide's package manager and build system, Cargo, which makes creating more complex programs much easier.

Hello, Cargo!

Cargo is Rust's excellent build system and package manager, and it makes Rust projects much easier to manage. You can use Cargo to create new projects, build them, test them, and distribute them. The good news is that Cargo works seamlessly with Oxide—.ox files are treated identically to .rs files. Oxide benefits directly from Cargo's powerful tooling and ecosystem.

What is Cargo?

Cargo handles several important tasks for you:

• Building your code with cargo build
• Running your code with cargo run
• Testing your code with cargo test
• Generating documentation with cargo doc
• Publishing libraries to crates.io
• Managing dependencies through Cargo.toml

Without Cargo, you'd need to manually compile your code with rustc, manage compilation flags, handle dependencies by hand, and coordinate all these tasks yourself. With Cargo, everything is automated and standardized.

Creating an Oxide Project

To create a new Oxide project, use Cargo with the --oxide flag:

$ cargo new --oxide hello_oxide
     Created binary (application) `hello_oxide` package
$ cd hello_oxide

This generates an Oxide project with src/main.ox containing:

fn main() {
    println!("Hello, world!")
}

Development Status: Oxide v1.0 is currently in development. The --oxide flag will be available in Cargo once the Oxide toolchain is released. For early testing before the release, you can manually create a project with cargo new and rename src/main.rs to src/main.ox.

Let's see what Cargo generated:

$ cd hello_oxide
$ ls -la

drwxr-xr-x  .git
drwxr-xr-x  .gitignore
-rw-r--r--  Cargo.toml
drwxr-xr-x  src

Let's look at the directory structure:

$ tree .

.
├── Cargo.toml
└── src
    └── main.ox

Understanding Cargo.toml

The Cargo.toml file is the manifest for your project. It contains metadata about your package and its dependencies. Here's what was created for us:

[package]
name = "hello_oxide"
version = "0.1.0"
edition = "2021"

[dependencies]

The [package] section contains metadata:

• name: The name of your project
• version: The current version of your code
• edition: The Rust edition (Oxide projects use the same editions as Rust)

The [dependencies] section is where you'd list any external crates your project depends on. We don't have any dependencies yet.

Understanding the src Directory

Cargo expects your source files to be in the src directory. With the --oxide flag, Cargo creates main.ox with a simple "Hello, World!" program:

fn main() {
    println!("Hello, world!")
}

This is valid Oxide code that compiles and runs just like Rust. Let's make it feel more Oxide-like by using string interpolation:

fn main() {
    let language = "Oxide"
    println!("Hello from \(language)!")
}

The differences from the original:

• Added a variable to demonstrate Oxide's string interpolation: "\(language)"
• Omitted semicolons (optional in Oxide)
• The fn main() and println!() syntax work identically in both Oxide and Rust

Building and Running Your Oxide Project

Now let's build the project using Cargo:

$ cargo build
   Compiling hello_oxide v0.1.0
    Finished dev [unoptimized + debuginfo] target/debug/hello_oxide

Congratulations! You've successfully compiled your first Oxide program with Cargo. The executable has been created in target/debug/hello_oxide (or target/debug/hello_oxide.exe on Windows).

To run it, use cargo run:

$ cargo run
   Compiling hello_oxide v0.1.0
    Finished dev [unoptimized + debuginfo] target/debug/hello_oxide
     Running `target/debug/hello_oxide`
Hello, Oxide!

The cargo run command compiles the code and then runs the resulting executable—all in one command. It's very convenient for projects you're actively working on.

A Note About Cargo.lock

When you first build your project, Cargo creates a Cargo.lock file. This file keeps track of the exact versions of dependencies you've built with. For binary projects (like this one), you should commit Cargo.lock to version control so everyone working on the project uses the same dependency versions. For libraries, it's typically not committed.

Cargo Check

If you want to verify that your code compiles without actually producing an executable, you can use cargo check:

$ cargo check
   Checking hello_oxide v0.1.0
    Finished dev [unoptimized + debuginfo] target/debug/hello_oxide

This command is much faster than cargo build because it stops after type-checking and doesn't generate code. It's perfect for getting quick feedback as you're writing code.

Using Cargo with Mixed Oxide and Rust

One powerful feature of Oxide is that you can freely mix .ox and .rs files in the same Cargo project. Cargo doesn't care which extension you use—both are compiled and linked together seamlessly.

For example, if you have existing Rust code you want to reuse, or if you're gradually migrating a project to Oxide, you can simply keep both file types in the same src/ directory:

src/
├── main.ox          # Oxide code
├── utils.rs         # Rust code
├── lib.ox           # Oxide library code
└── integrations.rs  # Rust integrations

Cargo will compile all of them together:

$ cargo build
   Compiling hello_oxide v0.1.0
    Finished dev [unoptimized + debuginfo] target/debug/hello_oxide

You can call Rust functions from Oxide and vice versa—they're compiled to the same intermediate representation and linked together. This makes it easy to adopt Oxide incrementally.

Thinking in Terms of Cargo

As you work with Rust and Oxide projects, here's a mental model for Cargo:

Cargo is to systems programming as npm is to Node.js or pip is to Python. It's the standard way projects are organized, built, and distributed. Rust's community designed Cargo exceptionally well, and Oxide benefits from this thoughtful tooling.

Every Rust and Oxide project you'll encounter follows the same structure:

• Source code in src/
• Dependencies listed in Cargo.toml
• Binaries in target/debug/ or target/release/
• Tests alongside your source code

Learning Cargo now means you'll immediately understand the structure of any Rust or Oxide project you encounter. This standardization is one of Rust's great strengths.

Building for Release

So far, we've been building in development mode with cargo build. This mode is great for development because compilation is fast and includes debug information. However, it doesn't optimize your code, so the resulting executable is slower.

When you're ready to ship your code, or when you care about performance, use the --release flag:

$ cargo build --release
   Compiling hello_oxide v0.1.0
    Finished release [optimized] target/release/hello_oxide

The executable will be in target/release/hello_oxide. Release builds take longer to compile but run much faster. You can also use:

$ cargo run --release
   Compiling hello_oxide v0.1.0
    Finished release [optimized] target/release/hello_oxide
     Running `target/release/hello_oxide`
Hello, Oxide!

For benchmarking or production deployment, always use --release.

Summary

Congratulations! You've learned the basics of working with Cargo and Oxide:

• Cargo new creates a new project structure
• Cargo build compiles your project
• Cargo run compiles and runs your project
• Cargo check quickly verifies your code compiles
• .ox files work seamlessly with Cargo just like .rs files
• Mixed projects are fully supported—use both .ox and .rs files in the same crate
• Release builds provide optimizations for production use

You now have everything you need to start building Oxide projects. In the next chapter, we'll explore the fundamental concepts of the language itself.

Programming a Guessing Game

Let's jump into Oxide by working through a hands-on project together! This chapter introduces several common Oxide concepts by showing you how to use them in a real program. You'll learn about var, input/output, string interpolation, match expressions, and more!

The project is a classic beginner programming problem: we'll implement a guessing game. Here's how it works: the program generates a random integer between 1 and 100, then prompts you to enter a guess. After you enter a guess, the program indicates whether the guess is too low or too high. If your guess is correct, the game prints a congratulatory message and exits.

Setting Up a New Project

Let's set up a new Oxide project using Cargo with the --oxide flag:

$ cargo new --oxide guessing_game
$ cd guessing_game

This creates a new Oxide project with src/main.ox ready to go.

Development Status: Oxide v1.0 is currently in development. The --oxide flag will be available in Cargo once the Oxide toolchain is released. For early testing before the release, you can manually create a project with cargo new and rename src/main.rs to src/main.ox.

Now let's look at what Cargo generated. Open Cargo.toml:

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"

[dependencies]

And here's the initial src/main.ox:

fn main() {
    println!("Hello, world!")
}

Let's test it with cargo run:

$ cargo run
   Compiling guessing_game v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 1.23s
     Running `target/debug/guessing_game`
Hello, world!

Great! The cargo run command compiles and runs the project in one step. Now let's make it into a guessing game.

Processing a Guess

The first part of the guessing game program will ask for user input, process that input, and check that the input is in the expected form. To start, we'll allow the player to input a guess.

Filename: src/main.ox

import std.io

fn main() {
    println!("Guess the number!")

    println!("Please input your guess.")

    var guess = String.new()

    io.stdin()
        .readLine(&mut guess)
        .expect("Failed to read line")

    println!("You guessed: \(guess)")
}

This code contains a lot of information, so let's go through it line by line.

Getting User Input

To obtain user input and then print the result, we need the io library from the standard library:

import std.io

In Oxide, we use import with dot notation. This replaces Rust's use std::io; syntax. Note that :: does not exist in Oxide - dot notation is the only path separator.

The main function is the entry point:

fn main() {

Next, we use println! to print a prompt:

println!("Guess the number!")
println!("Please input your guess.")

Storing Values with Variables

Now we'll create a variable to store the user input:

var guess = String.new()

In Oxide, we use var to create a mutable variable. This is equivalent to Rust's let mut. The variable guess is bound to a new, empty String. In Oxide, String is the same type as in Rust—a growable, UTF-8 encoded text type.

Receiving User Input

Next, we call readLine on the standard input handle:

io.stdin()
    .readLine(&mut guess)

The stdin function returns an instance of std.io.Stdin, a type representing a handle to the standard input. The .readLine(&mut guess) method reads user input into the string we pass to it.

We pass &mut guess as an argument. The & indicates this is a reference, which gives you a way to let multiple parts of your code access one piece of data without copying it into memory multiple times. References are immutable by default, so we need &mut to make it mutable.

Handling Potential Failure with Result

We're still working on this line:

    .expect("Failed to read line")

The readLine method returns a Result value. Result is an enum with variants Ok and Err. The Ok variant indicates the operation was successful, and inside Ok is the successfully generated value. The Err variant means the operation failed, and contains information about how or why the operation failed.

The expect method will cause the program to crash and display the message you passed to it if the Result is an Err value. If you don't call expect, the program will compile with a warning.

Printing Values with String Interpolation

Finally, we print the guess:

println!("You guessed: \(guess)")

Oxide supports string interpolation using \(expression) syntax. This is one of Oxide's ergonomic features that makes string formatting more concise. It's equivalent to Rust's format! macro.

Let's test this code:

$ cargo run
   Compiling guessing_game v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 2.34s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
6
You guessed: 6

Great! The first part is working.

Generating a Secret Number

Next, we need to generate a secret number that the user will try to guess. The secret number should be different every time so the game is fun to play more than once. Let's use a random number between 1 and 100.

Rust's standard library doesn't include random number functionality, so we'll use the rand crate. Add it to Cargo.toml:

Filename: Cargo.toml

[dependencies]
rand = "0.8.5"

Now update src/main.ox:

Filename: src/main.ox

import std.io
import rand.Rng

fn main() {
    println!("Guess the number!")

    let secretNumber = rand.threadRng().genRange(1..=100)

    println!("The secret number is: \(secretNumber)")

    println!("Please input your guess.")

    var guess = String.new()

    io.stdin()
        .readLine(&mut guess)
        .expect("Failed to read line")

    println!("You guessed: \(guess)")
}

We add import rand.Rng. The Rng trait defines methods that random number generators implement.

We call rand.threadRng() to get a random number generator, then call genRange with the range 1..=100 (inclusive on both ends).

Note that we use let (not var) for secretNumber because we won't be changing it.

Let's run it:

$ cargo run
   Compiling rand v0.8.5
   Compiling guessing_game v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 3.45s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 42
Please input your guess.
25
You guessed: 25

You should see a different random number, and it should change each time you run the program.

Comparing the Guess to the Secret Number

Now that we have user input and a random number, we can compare them:

Filename: src/main.ox

import std.io
import std.cmp.Ordering
import rand.Rng

fn main() {
    println!("Guess the number!")

    let secretNumber = rand.threadRng().genRange(1..=100)

    println!("The secret number is: \(secretNumber)")

    println!("Please input your guess.")

    var guess = String.new()

    io.stdin()
        .readLine(&mut guess)
        .expect("Failed to read line")

    let guess: Int = guess.trim().parse().expect("Please type a number!")

    println!("You guessed: \(guess)")

    match guess.cmp(&secretNumber) {
        Ordering.Less -> println!("Too small!"),
        Ordering.Greater -> println!("Too big!"),
        Ordering.Equal -> println!("You win!"),
    }
}

We import Ordering, which is an enum with variants Less, Greater, and Equal.

We convert the guess string to a number:

let guess: Int = guess.trim().parse().expect("Please type a number!")

We create a new variable also named guess. Oxide, like Rust, allows us to shadow the previous value. The trim method removes whitespace, and parse converts the string to a number. We specify the type as Int (Oxide's alias for i32).

Then we use a match expression to compare the guess to the secret number:

match guess.cmp(&secretNumber) {
    Ordering.Less -> println!("Too small!"),
    Ordering.Greater -> println!("Too big!"),
    Ordering.Equal -> println!("You win!"),
}

In Oxide, we use -> for match arms (Rust's => is invalid in Oxide), and dot notation for enum variants (Ordering.Less). Rust's double colon syntax (Ordering::Less) does not exist in Oxide - it will cause a syntax error.

Let's try it:

$ cargo run
   Compiling guessing_game v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 1.23s
     Running `target/debug/guessing_game`
Guess the number!
The secret number is: 58
Please input your guess.
76
You guessed: 76
Too big!

Nice! But we can only make one guess. Let's fix that with a loop.

Allowing Multiple Guesses with Looping

The loop keyword creates an infinite loop:

Filename: src/main.ox

import std.io
import std.cmp.Ordering
import rand.Rng

fn main() {
    println!("Guess the number!")

    let secretNumber = rand.threadRng().genRange(1..=100)

    loop {
        println!("Please input your guess.")

        var guess = String.new()

        io.stdin()
            .readLine(&mut guess)
            .expect("Failed to read line")

        let guess: Int = guess.trim().parse().expect("Please type a number!")

        println!("You guessed: \(guess)")

        match guess.cmp(&secretNumber) {
            Ordering.Less -> println!("Too small!"),
            Ordering.Greater -> println!("Too big!"),
            Ordering.Equal -> {
                println!("You win!")
                break
            },
        }
    }
}

We've moved everything after the secret number generation into a loop. When the guess equals the secret number, we print "You win!" and break to exit the loop.

$ cargo run
   Compiling guessing_game v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 1.45s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
50
You guessed: 50
Too small!
Please input your guess.
75
You guessed: 75
Too big!
Please input your guess.
62
You guessed: 62
You win!

Excellent! Now it loops until you guess correctly.

Handling Invalid Input

Let's make the game more robust by handling invalid input gracefully:

Filename: src/main.ox

import std.io
import std.cmp.Ordering
import rand.Rng

fn main() {
    println!("Guess the number!")

    let secretNumber = rand.threadRng().genRange(1..=100)

    loop {
        println!("Please input your guess.")

        var guess = String.new()

        io.stdin()
            .readLine(&mut guess)
            .expect("Failed to read line")

        let guess: Int = match guess.trim().parse() {
            Ok(num) -> num,
            Err(_) -> {
                println!("Please type a number!")
                continue
            },
        }

        println!("You guessed: \(guess)")

        match guess.cmp(&secretNumber) {
            Ordering.Less -> println!("Too small!"),
            Ordering.Greater -> println!("Too big!"),
            Ordering.Equal -> {
                println!("You win!")
                break
            },
        }
    }
}

Instead of crashing with expect, we now use a match expression to handle the Result from parse. If parse returns Ok, we extract the number. If it returns Err, we print a message and continue to the next iteration of the loop.

Let's test it:

$ cargo run
   Compiling guessing_game v0.1.0
    Finished dev [unoptimized + debuginfo] target(s) in 1.23s
     Running `target/debug/guessing_game`
Guess the number!
Please input your guess.
abc
Please type a number!
Please input your guess.
50
You guessed: 50
Too small!
Please input your guess.
62
You guessed: 62
You win!

Perfect! Now let's remove the debug line that prints the secret number:

Filename: src/main.ox

import std.io
import std.cmp.Ordering
import rand.Rng

fn main() {
    println!("Guess the number!")

    let secretNumber = rand.threadRng().genRange(1..=100)

    loop {
        println!("Please input your guess.")

        var guess = String.new()

        io.stdin()
            .readLine(&mut guess)
            .expect("Failed to read line")

        let guess: Int = match guess.trim().parse() {
            Ok(num) -> num,
            Err(_) -> {
                println!("Please type a number!")
                continue
            },
        }

        println!("You guessed: \(guess)")

        match guess.cmp(&secretNumber) {
            Ordering.Less -> println!("Too small!"),
            Ordering.Greater -> println!("Too big!"),
            Ordering.Equal -> {
                println!("You win!")
                break
            },
        }
    }
}

Summary

This project was a hands-on way to introduce you to many new Oxide concepts: var, match, functions, external crates, and more. In the next chapters, you'll learn about these concepts in more detail.

This project demonstrated Oxide's practical syntax while building on Rust's excellent type system and error handling. The guessing game uses the same robust foundation as any Rust program—ownership, borrowing, and the type system—but with syntax that may feel more familiar if you're coming from languages like Swift, Kotlin, or TypeScript.

In Chapter 3, you'll learn about concepts that most programming languages have, such as variables, data types, and functions, and see how they work in Oxide.

Common Programming Concepts

This chapter introduces the core building blocks of Oxide. If you have used other languages, many of these ideas will feel familiar, but the syntax and rules are tailored to Oxide and Rust's safety model.

What You'll Learn

• Immutable and mutable bindings with let and var
• Core scalar and compound data types
• How to define and call functions
• Comment styles and documentation basics
• Control flow with if, match, and loops

A Quick Tour

Here is a small program that touches several of the concepts in this chapter:

fn main() {
    let name = "Oxide"
    var counter = 0

    while counter < 3 {
        println!("Hello, \(name)! Count = \(counter)")
        counter = counter + 1
    }

    let grade = 92
    let letter = match grade {
        90..=100 -> "A",
        80..=89 -> "B",
        70..=79 -> "C",
        60..=69 -> "D",
        _ -> "F",
    }

    println!("Final grade: \(letter)")
}

We'll unpack each of these pieces in the sections that follow.

Variables and Mutability

Variables are fundamental to any programming language. In Oxide, every variable binding follows clear rules about mutability that help prevent bugs and make your code easier to reason about. If you're familiar with Rust, you'll find Oxide's approach very similar, but with syntax inspired by languages like Swift and Kotlin.

Immutable Bindings with let

When you declare a variable with let, it creates an immutable binding. This means once you assign a value, you cannot change it:

fn main() {
    let x = 5
    println!("The value of x is: \(x)")
}

If you try to reassign an immutable variable, the compiler will stop you:

fn main() {
    let x = 5
    println!("The value of x is: \(x)")
    x = 6  // Error: cannot assign twice to immutable variable
}

This might seem restrictive at first, but immutability is a powerful feature. When a value cannot change, you can trust that it stays the same throughout your program. This eliminates entire categories of bugs and makes code easier to understand, especially in larger projects.

Rust comparison: The let keyword works identically to Rust. The only visible difference is that semicolons are optional in Oxide.

#![allow(unused)]
fn main() {
// Rust
let x = 5;
println!("The value of x is: {}", x);
}

Mutable Bindings with var

Of course, sometimes you need values that can change. Oxide uses the var keyword for mutable bindings:

fn main() {
    var x = 5
    println!("The value of x is: \(x)")
    x = 6
    println!("The value of x is: \(x)")
}

This outputs:

The value of x is: 5
The value of x is: 6

With var, you can modify the value as many times as needed. Use var when you know a value will change, like a counter in a loop or an accumulator.

Rust comparison: Oxide's var is equivalent to Rust's let mut. The choice of var is intentional, as it's a familiar keyword from Swift, Kotlin, JavaScript, and many other languages.

#![allow(unused)]
fn main() {
// Rust equivalent
let mut x = 5;
x = 6;
}

Constants

Constants are values that are bound to a name and cannot change throughout the entire program. Unlike let bindings, constants:

• Must always have a type annotation
• Must be set to a constant expression (evaluated at compile time)
• Can be declared in any scope, including the global scope
• Use the const keyword and SCREAMING_SNAKE_CASE by convention

const THREE_HOURS_IN_SECONDS: Int = 60 * 60 * 3

fn main() {
    println!("Three hours is \(THREE_HOURS_IN_SECONDS) seconds")
}

Constants are useful for values that many parts of your code need to know about, like the maximum number of players in a game or the speed of light. Naming hardcoded values as constants helps future readers understand the significance of the value.

Rust comparison: Constants work identically to Rust. The only difference is using Oxide's type aliases (Int instead of i32).

#![allow(unused)]
fn main() {
// Rust
const THREE_HOURS_IN_SECONDS: i32 = 60 * 60 * 3;
}

Shadowing

You can declare a new variable with the same name as a previous variable. This is called shadowing, and the new variable shadows the previous one:

fn main() {
    let x = 5

    let x = x + 1

    {
        let x = x * 2
        println!("The value of x in the inner scope is: \(x)")
    }

    println!("The value of x is: \(x)")
}

This outputs:

The value of x in the inner scope is: 12
The value of x is: 6

Shadowing is different from marking a variable as mutable with var. If we try to reassign without let, we get a compile-time error. By using let, we can perform transformations on a value but have the variable be immutable after those transformations.

Another advantage of shadowing is that you can change the type of a value while reusing the same name:

fn main() {
    let spaces = "   "
    let spaces = spaces.len()
    println!("Number of spaces: \(spaces)")
}

The first spaces is a &str, and the second spaces is a UIntSize (the return type of .len()). This is allowed because we're creating a new variable with let.

If we tried to use var and reassign, we'd get a type mismatch error:

fn main() {
    var spaces = "   "
    spaces = spaces.len()  // Error: mismatched types
}

Type Annotations

Oxide can usually infer the type of a variable from its value, but you can also be explicit:

fn main() {
    let count: Int = 42
    let name: String = "Alice".toString()
    let active: Bool = true

    var score: Float = 0.0
    score = 99.5
}

Type annotations use a colon followed by the type, consistent with languages like TypeScript, Kotlin, and Swift. Oxide provides intuitive type aliases for primitives:

We'll explore all the available types in the next section.

Rust comparison: The annotation syntax is the same as Rust, just with Oxide's type names.

#![allow(unused)]
fn main() {
// Rust
let count: i32 = 42;
let active: bool = true;
}

When to Use let vs var

As a general guideline:

• Default to let: Start with immutable bindings. This makes your code safer and easier to reason about.
• Use var when needed: If you find you need to modify a value, change it to var.

The compiler will tell you if you've marked something as immutable but try to change it. Following this approach helps you take advantage of the safety that Oxide provides while still having the flexibility to use mutable state when appropriate.

Summary

• Use let for immutable bindings that cannot change after initialization
• Use var for mutable bindings that you need to modify
• Use const for compile-time constants with global scope
• Shadowing allows reusing names while keeping immutability benefits
• Type annotations use the format name: Type

Now that you understand how variables work, let's look at the different data types available in Oxide.

Data Types

Every value in Oxide has a data type, which tells the compiler what kind of data is being specified so it knows how to work with that data. Oxide is statically typed, meaning the compiler must know the types of all variables at compile time. The compiler can usually infer types from values and how we use them, but when many types are possible, we must add a type annotation.

Scalar Types

A scalar type represents a single value. Oxide has four primary scalar types: integers, floating-point numbers, Booleans, and characters. Oxide provides intuitive type aliases that will feel familiar if you're coming from Swift, Kotlin, or TypeScript.

Integer Types

An integer is a number without a fractional component. Oxide provides signed and unsigned integers of various sizes:

The Int type (which maps to Rust's i32) is the default choice for integers and is generally the fastest, even on 64-bit systems. Use UIntSize when indexing collections, as it matches the size of memory addresses on your system.

fn main() {
    let age: Int = 30
    let temperature: Int = -15
    let count: UIntSize = 1000

    // Type inference works too
    let inferred = 42  // Defaults to Int
}

Integer Literals

You can write integer literals in various forms:

Note that underscores can be inserted for readability: 1_000_000 is the same as 1000000.

Floating-Point Types

Oxide has two floating-point types for numbers with decimal points:

The Float type (which maps to Rust's f64) is the default because modern CPUs handle double-precision floats nearly as fast as single-precision, and it provides more accuracy.

fn main() {
    let pi: Float = 3.14159
    let temperature = 98.6  // Inferred as Float
    let precise: Float64 = 2.718281828459045

    // Scientific notation
    let avogadro: Float = 6.022e23
}

Numeric Operations

Oxide supports the standard mathematical operations: addition, subtraction, multiplication, division, and remainder:

fn main() {
    // Addition
    let sum = 5 + 10

    // Subtraction
    let difference = 95.5 - 4.3

    // Multiplication
    let product = 4 * 30

    // Division
    let quotient = 56.7 / 32.2
    let truncated = 5 / 3  // Results in 1 (integer division)

    // Remainder
    let remainder = 43 % 5
}

The Boolean Type

Oxide's Boolean type has two possible values: true and false. Booleans are one byte in size and are specified using the Bool type:

fn main() {
    let isActive: Bool = true
    let isComplete = false  // Inferred as Bool

    // Booleans are often the result of comparisons
    let isGreater = 5 > 3  // true
}

Rust comparison: Oxide uses Bool instead of bool, following the convention of capitalizing type names.

The Character Type

The char type represents a single Unicode scalar value. Character literals use single quotes:

fn main() {
    let letter = 'a'
    let emoji = '😀'
    let heart = '❤'
}

The char type is four bytes and represents a Unicode Scalar Value, which means it can represent much more than just ASCII.

Compound Types

Compound types can group multiple values into one type. Oxide has two primitive compound types: tuples and arrays.

Tuples

A tuple groups together values of different types into one compound type. Tuples have a fixed length; once declared, they cannot grow or shrink.

fn main() {
    let tup: (Int, Float, Bool) = (500, 6.4, true)

    // Destructuring
    let (x, y, z) = tup
    println!("The value of y is: \(y)")

    // Access by index
    let fiveHundred = tup.0
    let sixPointFour = tup.1
    let isTrue = tup.2
}

The tuple without any values, (), is called the unit type and represents an empty value or empty return type.

Arrays

Arrays contain multiple values of the same type with a fixed length. Use square brackets for array literals:

fn main() {
    let numbers: [Int; 5] = [1, 2, 3, 4, 5]
    let months: [&str; 12] = [
        "January", "February", "March", "April",
        "May", "June", "July", "August",
        "September", "October", "November", "December"
    ]

    // Initialize with same value
    let zeros: [Int; 5] = [0; 5]  // [0, 0, 0, 0, 0]

    // Accessing elements
    let first = numbers[0]
    let second = numbers[1]
}

Arrays are useful when you want data on the stack rather than the heap, or when you need a fixed number of elements. For a collection that can grow or shrink, use Vec<T> instead.

The String Type

Oxide has two string types:

• str: A string slice, usually seen as &str. This is an immutable reference to string data.
• String: A growable, heap-allocated string.

fn main() {
    // String literal (type is &str)
    let greeting = "Hello, world!"

    // Create an owned String
    let name: String = "Alice".toString()

    // String with interpolation
    let message = "Hello, \(name)!"
    println!("\(message)")
}

String interpolation with \(expression) is a key Oxide feature. Any expression inside \() is evaluated and converted to a string:

fn main() {
    let count = 42
    let price = 19.99

    println!("Count: \(count), Price: $\(price)")
    println!("Total: $\(count as Float * price)")
}

Rust comparison: Rust uses format!("{}", x) for string formatting. Oxide's \(x) syntax is inspired by Swift and is more concise.

#![allow(unused)]
fn main() {
// Rust
println!("Count: {}, Price: ${}", count, price);
}

Nullable Types

Oxide has first-class support for nullable (optional) types using the ? suffix. A T? type can hold either a value of type T or null:

fn main() {
    let maybeNumber: Int? = 42
    let nothing: String? = null

    // Check if value exists
    if let number = maybeNumber {
        println!("Got number: \(number)")
    }

    // Provide a default with ??
    let value = maybeNumber ?? 0

    // Force unwrap with !! (use carefully!)
    let forced = maybeNumber!!
}

When a context expects T?, you can assign or return a T directly and Oxide will implicitly wrap it in Some(...). You can still write Some(...) explicitly when you want to be clear.

The T? syntax is equivalent to Rust's Option<T>, and null is equivalent to None:

fn findUser(id: Int): User? {
    if id == 1 {
        User { name: "Alice".toString() }
    } else {
        null
    }
}

fn main() {
    let user = findUser(1) ?? User { name: "Guest".toString() }
    println!("Hello, \(user.name)")
}

Collection Types

Oxide uses Rust's standard collection types directly:

Vectors

Vec<T> is a growable array type:

fn main() {
    // Create a vector with the vec! macro
    var numbers: Vec<Int> = vec![1, 2, 3]

    // Add elements
    numbers.push(4)
    numbers.push(5)

    // Access elements
    let first = numbers[0]
    let maybeTenth: Int? = numbers.get(10).copied()

    // Iterate
    for num in numbers.iter() {
        println!("\(num)")
    }
}

HashMaps

HashMap<K, V> stores key-value pairs:

import std.collections.HashMap

fn main() {
    var scores: HashMap<String, Int> = HashMap.new()

    scores.insert("Blue".toString(), 10)
    scores.insert("Red".toString(), 50)

    let blueScore = scores.get(&"Blue".toString())

    for (team, score) in scores.iter() {
        println!("\(team): \(score)")
    }
}

Note: Oxide v1.0 uses Rust's collection names directly (Vec, HashMap) rather than providing aliases like Array or Dict. This helps you learn the actual Rust types you'll encounter in the ecosystem.

Type Inference

Oxide has strong type inference. The compiler can usually figure out types from context:

fn main() {
    let x = 5          // Int
    let y = 3.14       // Float
    let z = true       // Bool
    let s = "hello"    // &str

    var items = vec![] // Vec<???> - needs annotation or usage
    items.push(1)      // Now compiler knows it's Vec<Int>
}

When the compiler cannot infer the type, you need to provide an annotation:

fn main() {
    // Compiler needs help here
    let guess: Int = "42".parse().unwrap()

    // Or specify the type in the turbofish
    let guess = "42".parse<Int>().unwrap()
}

Summary

Oxide provides intuitive type names that feel familiar to developers from many language backgrounds while mapping directly to Rust's type system:

• Integers: Int, Int64, UInt, UIntSize, etc.
• Floats: Float, Float32, Float64
• Boolean: Bool
• Character: char
• Tuples: (T, U, V)
• Arrays: [T; N]
• Strings: &str, String with \(expr) interpolation
• Nullable: T? with null, ??, and !! operators
• Collections: Vec<T>, HashMap<K, V>

Since Oxide types ARE Rust types (just with different names), you get full compatibility with the entire Rust ecosystem.

Functions

Functions are pervasive in Oxide code. You've already seen the main function, which is the entry point of many programs. The fn keyword allows you to declare new functions.

Oxide uses camelCase for function and variable names, in contrast to Rust's snake_case. This follows the conventions of Swift, Kotlin, and TypeScript. When you call Rust code from Oxide, name conversion happens automatically.

Defining Functions

Functions are defined with fn, followed by a name, parameters in parentheses, and a body in curly braces:

fn main() {
    println!("Hello, world!")
    anotherFunction()
}

fn anotherFunction() {
    println!("Another function.")
}

Functions can be defined before or after main; Oxide doesn't care where you define them, as long as they're in scope.

Parameters

Functions can have parameters, which are special variables that are part of the function's signature. When a function has parameters, you provide concrete values (called arguments) when you call it.

fn main() {
    greet("Alice")
    printSum(5, 3)
}

fn greet(name: &str) {
    println!("Hello, \(name)!")
}

fn printSum(a: Int, b: Int) {
    println!("\(a) + \(b) = \(a + b)")
}

Parameters must have type annotations. This is a deliberate design decision; requiring types in function signatures means the compiler rarely needs type annotations elsewhere.

Rust comparison: The syntax is identical, except Oxide uses camelCase for function names and its own type aliases.

#![allow(unused)]
fn main() {
// Rust
fn print_sum(a: i32, b: i32) {
    println!("{} + {} = {}", a, b, a + b);
}
}

Return Values

Functions can return values. Declare the return type after a colon (:) following the parameter list:

fn five(): Int {
    5
}

fn add(a: Int, b: Int): Int {
    a + b
}

fn main() {
    let x = five()
    let sum = add(10, 20)
    println!("x = \(x), sum = \(sum)")
}

The return value is the final expression in the function body. You can also return early using the return keyword:

fn absoluteValue(x: Int): Int {
    if x < 0 {
        return -x
    }
    x
}

Rust comparison: Oxide uses : for return types instead of Rust's ->. This aligns with TypeScript, Kotlin, and Swift conventions.

#![allow(unused)]
fn main() {
// Rust
fn add(a: i32, b: i32) -> i32 {
    a + b
}
}

Statements and Expressions

Function bodies are made up of a series of statements optionally ending in an expression. Understanding the difference is important:

• Statements perform actions but don't return a value
• Expressions evaluate to a resulting value

fn main() {
    // This is a statement (variable declaration)
    let y = 6

    // This block is an expression that evaluates to 4
    let x = {
        let temp = 3
        temp + 1  // No semicolon - this is the block's value
    }

    println!("x = \(x)")  // Prints: x = 4
}

Note that temp + 1 has no semicolon. Adding a semicolon would turn it into a statement, and the block would return () (the unit type) instead.

Visibility

By default, functions are private to their module. Use public to make them accessible from other modules:

public fn createUser(name: &str): User {
    User { name: name.toString() }
}

fn helperFunction() {
    // This is only accessible within this module
}

Rust comparison: Oxide uses public instead of pub. The word is spelled out for clarity.

#![allow(unused)]
fn main() {
// Rust
pub fn create_user(name: &str) -> User {
    User { name: name.to_string() }
}
}

Generic Functions

Functions can be generic over types:

import std.fmt.Display

fn identity<T>(value: T): T {
    value
}

fn printPair<T, U>(first: T, second: U)
where
    T: Display,
    U: Display,
{
    println!("(\(first), \(second))")
}

fn main() {
    let x = identity(42)
    let s = identity("hello")
    printPair(1, "one")
}

Generic constraints can be specified inline or with a where clause, just like in Rust.

Functions That Return Nothing

Functions that don't return a value implicitly return (), the unit type. You can omit the return type:

fn greet(name: &str) {
    println!("Hello, \(name)!")
}

// This is equivalent:
fn greetExplicit(name: &str): () {
    println!("Hello, \(name)!")
}

Functions That Never Return

Some functions never return, like those that always panic or loop forever. Use the Never type for these:

fn diverges(): Never {
    panic!("This function never returns!")
}

fn infiniteLoop(): Never {
    loop {
        // Do something forever
    }
}

Closures

Closures are anonymous functions you can store in variables or pass as arguments. Oxide uses a Swift-inspired syntax with curly braces:

fn main() {
    // No parameters
    let sayHello = { println!("Hello!") }

    // One parameter
    let double = { x -> x * 2 }

    // Multiple parameters
    let add = { x, y -> x + y }

    // With type annotations
    let parse = { s: &str -> s.parse<Int>().unwrap() }

    sayHello()
    println!("Double 5: \(double(5))")
    println!("3 + 4: \(add(3, 4))")
}

Rust comparison: Oxide uses { params -> body } instead of Rust's |params| body.

#![allow(unused)]
fn main() {
// Rust
let double = |x| x * 2;
let add = |x, y| x + y;
}

Implicit it Parameter

In trailing closures (closures passed as the last argument to a function), you can use the implicit it parameter for single-argument closures:

fn main() {
    let numbers = vec![1, 2, 3, 4, 5]

    // Using implicit `it`
    let doubled = numbers.iter().map { it * 2 }.collect<Vec<Int>>()

    // Equivalent with explicit parameter
    let doubled = numbers.iter().map { x -> x * 2 }.collect<Vec<Int>>()

    // Filter with `it`
    let evens = numbers.iter().filter { it % 2 == 0 }

    // More complex usage
    let users = vec![user1, user2, user3]
    let activeNames = users
        .iter()
        .filter { it.isActive }
        .map { it.name.clone() }
        .collect<Vec<String>>()
}

Important: The implicit it is only available in trailing closure position. You cannot use it in variable bindings:

// NOT allowed - it only works in trailing closures
let f = { it * 2 }  // Error!

// Use explicit parameter instead
let f = { x -> x * 2 }  // OK

Trailing Closure Syntax

When the last argument to a function is a closure, you can write it outside the parentheses:

fn main() {
    let numbers = vec![1, 2, 3, 4, 5]

    // Trailing closure syntax
    numbers.forEach { println!("\(it)") }

    // Equivalent to:
    numbers.forEach({ println!("\(it)") })

    // With other arguments
    numbers.iter().fold(0, { acc, x -> acc + x })
}

Multi-Statement Closures

Closures can contain multiple statements:

fn main() {
    let process = { item ->
        let validated = validate(item)
        let transformed = transform(validated)
        transformed
    }

    let result = process(myItem)
}

Async Functions

Async functions allow non-blocking I/O operations. Oxide uses prefix await instead of Rust's postfix .await:

async fn fetchData(url: &str): Result<String, Error> {
    let response = await client.get(url).send()?
    let body = await response.text()?
    Ok(body)
}

async fn main(): Result<(), Error> {
    let data = await fetchData("https://example.com")?
    println!("Got: \(data)")
    Ok(())
}

Rust comparison: Oxide uses await expr (prefix) instead of Rust's expr.await (postfix).

#![allow(unused)]
fn main() {
// Rust
async fn fetch_data(url: &str) -> Result<String, Error> {
    let response = client.get(url).send().await?;
    let body = response.text().await?;
    Ok(body)
}
}

The prefix await reads naturally left-to-right and matches the convention in Swift, Kotlin, JavaScript, and Python.

Function Pointers

You can store functions in variables and pass them around:

fn add(a: Int, b: Int): Int {
    a + b
}

fn multiply(a: Int, b: Int): Int {
    a * b
}

fn applyOperation(a: Int, b: Int, op: (Int, Int) -> Int): Int {
    op(a, b)
}

fn main() {
    let result1 = applyOperation(5, 3, add)
    let result2 = applyOperation(5, 3, multiply)

    println!("5 + 3 = \(result1)")
    println!("5 * 3 = \(result2)")
}

Rust comparison: Function pointer types use (T) -> U just like Rust. Only function declarations use : for return types.

#![allow(unused)]
fn main() {
// Rust
fn apply_operation(a: i32, b: i32, op: fn(i32, i32) -> i32) -> i32 {
    op(a, b)
}
}

Summary

• Functions are declared with fn and use camelCase names
• Parameters require type annotations
• Return types follow : (not ->)
• Use public (not pub) for public visibility
• Closures use { params -> body } syntax
• The implicit it parameter works in trailing closures
• Async functions use prefix await

Functions in Oxide are designed to be familiar to developers from modern language backgrounds while maintaining full compatibility with Rust's function system.

Comments

Comments are essential for documenting your code. Good comments explain why code exists, not just what it does. Oxide's comment syntax is identical to Rust's, which will be familiar if you've used C, C++, Java, or JavaScript.

Line Comments

The most common comment form is the line comment, which starts with // and continues to the end of the line:

fn main() {
    // This is a line comment
    let x = 5  // This comment follows code

    // Comments can span
    // multiple lines
    // like this

    let y = 10
}

Use line comments liberally to explain non-obvious logic:

fn calculateDiscount(price: Float, memberYears: Int): Float {
    // Base discount for all members
    var discount = 0.05

    // Long-term members get additional rewards
    // The formula was approved by marketing in Q3 2024
    if memberYears >= 5 {
        discount += 0.02 * (memberYears - 4).min(5) as Float
    }

    price * discount
}

Block Comments

For longer explanations, use block comments that start with /* and end with */:

fn main() {
    /* This is a block comment.
       It can span multiple lines
       and is useful for longer explanations. */

    let x = 5

    /*
     * Some developers prefer to format
     * block comments with asterisks
     * on each line for readability.
     */
}

Block comments can also be nested, which is useful when commenting out code that already contains comments:

fn main() {
    /*
    This outer comment contains:
    /* An inner comment */
    And continues after it.
    */
    println!("Hello!")
}

In practice, line comments (//) are more commonly used than block comments.

Documentation Comments

Oxide supports special documentation comments that can be processed by documentation tools. These come in two forms.

Outer Documentation Comments (///)

Use /// to document the item that follows (functions, structs, enums, etc.):

/// Calculates the factorial of a non-negative integer.
///
/// # Arguments
///
/// * `n` - The number to calculate factorial for
///
/// # Returns
///
/// The factorial of `n`, or `null` if `n` is negative
///
/// # Examples
///
/// ```oxide
/// let result = factorial(5)
/// assertEq!(result, Some(120))
/// ```
public fn factorial(n: Int): Int? {
    if n < 0 {
        return null
    }
    if n <= 1 {
        return Some(1)
    }
    Some(n * factorial(n - 1)?)
}

Documentation comments support Markdown formatting, so you can include:

• Headers with #
• Code blocks with triple backticks
• Lists with * or -
• Bold with **text**
• Links with [text](url)

Inner Documentation Comments (//!)

Use //! at the beginning of a file or module to document the module itself:

//! # String Utilities
//!
//! This module provides helper functions for string manipulation.
//!
//! ## Features
//!
//! - Case conversion
//! - Trimming and padding
//! - Search and replace
//!
//! ## Example
//!
//! ```oxide
//! import mylib.strings
//!
//! let result = strings.toTitleCase("hello world")
//! assertEq!(result, "Hello World")
//! ```

public fn toTitleCase(s: &str): String {
    // Implementation here
    s.toString()
}

public fn capitalize(s: &str): String {
    // Implementation here
    s.toString()
}

Inner documentation comments are typically placed at the very top of a file, before any code.

Common Documentation Sections

By convention, documentation for public APIs follows a standard structure:

/// Brief one-line description of the function.
///
/// More detailed explanation if needed. This can span multiple
/// paragraphs and include any relevant background information.
///
/// # Arguments
///
/// * `param1` - Description of the first parameter
/// * `param2` - Description of the second parameter
///
/// # Returns
///
/// Description of what the function returns.
///
/// # Errors
///
/// Description of when this function returns an error.
///
/// # Panics
///
/// Description of when this function might panic.
///
/// # Safety
///
/// For unsafe functions, describe safety requirements.
///
/// # Examples
///
/// ```oxide
/// let result = myFunction(arg1, arg2)
/// ```
public fn myFunction(param1: Int, param2: &str): Result<String, Error> {
    // Implementation
}

Not all sections are needed for every function. Use the sections that are relevant:

• # Arguments - When parameters aren't self-explanatory
• # Returns - For non-obvious return values
• # Errors - For functions returning Result
• # Panics - When the function can panic
• # Safety - Required for unsafe functions
• # Examples - Highly recommended for public APIs

Documenting Structs and Enums

Document each field or variant:

/// Represents a user in the system.
///
/// Users are the primary actors in our application and
/// can perform various actions based on their role.
#[derive(Debug, Clone)]
public struct User {
    /// Unique identifier for the user.
    id: Int,

    /// Display name shown in the UI.
    name: String,

    /// Email address for notifications.
    /// Must be verified before the user can post.
    email: String,

    /// Whether the user has admin privileges.
    isAdmin: Bool,
}

/// Possible states for an order.
public enum OrderStatus {
    /// Order has been placed but not yet processed.
    Pending,

    /// Order is being prepared for shipment.
    Processing,

    /// Order has been shipped to the customer.
    /// Contains the tracking number.
    Shipped { trackingNumber: String },

    /// Order has been delivered successfully.
    Delivered,

    /// Order was cancelled.
    /// Contains the reason for cancellation.
    Cancelled { reason: String },
}

Best Practices

Write Comments for Your Future Self

Code that seems obvious today might be confusing in six months:

// BAD: States what the code does (obvious from reading it)
// Increment counter by 1
counter += 1

// GOOD: Explains why
// We count from 1 because the API expects 1-indexed results
counter += 1

Keep Comments Up to Date

Outdated comments are worse than no comments. When you change code, update the corresponding comments:

// BAD: Comment doesn't match code
// Returns the user's full name
fn getUsername(user: &User): String {
    user.email.clone()  // Actually returns email!
}

// GOOD: Comment matches code
// Returns the user's email as their display identifier
fn getUsername(user: &User): String {
    user.email.clone()
}

Use Comments to Explain "Why", Not "What"

// BAD: Describes what the code does
// Loop through users and filter by active status
let activeUsers = users.iter().filter { it.isActive }

// GOOD: Explains the business reason
// Only active users should receive the weekly newsletter
let activeUsers = users.iter().filter { it.isActive }

Document Public APIs Thoroughly

Internal code can have lighter documentation, but public APIs deserve comprehensive docs:

/// Parses a date string in ISO 8601 format.
///
/// Accepts dates in the format `YYYY-MM-DD`. The time component
/// is optional and defaults to midnight UTC if not provided.
///
/// # Arguments
///
/// * `input` - A string slice containing the date to parse
///
/// # Returns
///
/// A `DateTime` if parsing succeeds, or `null` if the input
/// is not a valid ISO 8601 date string.
///
/// # Examples
///
/// ```oxide
/// let date = parseIsoDate("2024-03-15")
/// assert!(date.isSome())
///
/// let invalid = parseIsoDate("not a date")
/// assert!(invalid.isNone())
/// ```
public fn parseIsoDate(input: &str): DateTime? {
    // Implementation
}

Summary

• Use // for line comments (most common)
• Use /* */ for block comments (can be nested)
• Use /// to document the following item
• Use //! to document the containing module
• Documentation comments support Markdown
• Follow standard sections: Arguments, Returns, Errors, Panics, Examples
• Comment the "why", not the "what"
• Keep comments synchronized with code

Good documentation makes your code more maintainable and helps others (including your future self) understand your intent.

Control Flow

Control flow constructs let you run code conditionally or repeatedly. Oxide provides several ways to control execution: if expressions, match expressions, guard statements, and various loops. While the semantics match Rust exactly, some syntax is designed to be more approachable.

if Expressions

An if expression lets you branch your code based on conditions:

fn main() {
    let number = 7

    if number < 5 {
        println!("condition was true")
    } else {
        println!("condition was false")
    }
}

The condition must be a Bool. Unlike some languages, Oxide won't automatically convert non-Boolean types:

fn main() {
    let number = 3

    // This won't compile!
    if number {  // Error: expected Bool, found Int
        println!("number was three")
    }

    // This works:
    if number != 0 {
        println!("number was not zero")
    }
}

Multiple Conditions with else if

Chain conditions with else if:

fn main() {
    let number = 6

    if number % 4 == 0 {
        println!("number is divisible by 4")
    } else if number % 3 == 0 {
        println!("number is divisible by 3")
    } else if number % 2 == 0 {
        println!("number is divisible by 2")
    } else {
        println!("number is not divisible by 4, 3, or 2")
    }
}

Using if in a let Statement

Because if is an expression, you can use it on the right side of a let:

fn main() {
    let condition = true
    let number = if condition { 5 } else { 6 }

    println!("The value of number is: \(number)")
}

Both branches must return the same type:

fn main() {
    let condition = true

    // This won't compile!
    let number = if condition { 5 } else { "six" }  // Error: incompatible types
}

if let for Pattern Matching

The if let syntax combines pattern matching with conditionals. It's especially useful for nullable types:

fn main() {
    let maybeNumber: Int? = 42

    // Auto-unwrap: the Some() wrapper is implicit for T?
    if let number = maybeNumber {
        println!("Got number: \(number)")
    }

    // Explicit Some() also works
    if let Some(number) = maybeNumber {
        println!("Got number: \(number)")
    }

    // With else branch
    if let value = maybeNumber {
        println!("Value: \(value)")
    } else {
        println!("No value present")
    }
}

Rust comparison: In Oxide, if let x = nullable automatically wraps the pattern in Some() when the right-hand side is a nullable type. In Rust, you must always write if let Some(x) = nullable.

#![allow(unused)]
fn main() {
// Rust requires explicit Some()
if let Some(number) = maybe_number {
    println!("Got number: {}", number);
}
}

guard Statements

The guard statement is for early returns when conditions aren't met. The else block must diverge (return, break, continue, or panic):

fn processUser(user: User?): Result<String, Error> {
    guard let user = user else {
        return Err(anyhow!("User not found"))
    }
    // `user` is now available and non-null

    guard user.isActive else {
        return Err(anyhow!("User is not active"))
    }
    // We know user is active here

    Ok("Processing \(user.name)")
}

guard is particularly useful for validation at the start of functions:

fn divide(a: Int, b: Int): Result<Int, String> {
    guard b != 0 else {
        return Err("Cannot divide by zero".toString())
    }

    Ok(a / b)
}

fn processItems(items: Vec<Item>): Result<Summary, Error> {
    guard !items.isEmpty() else {
        return Err(anyhow!("No items to process"))
    }

    // Continue with non-empty items...
    Ok(summarize(items))
}

Rust comparison: Oxide's guard let x = expr else { } is equivalent to Rust's let Some(x) = expr else { }. The guard condition else { } form is similar to an inverted if.

#![allow(unused)]
fn main() {
// Rust
let Some(user) = user else {
    return Err(anyhow!("User not found"));
};

// Or for conditions:
if items.is_empty() {
    return Err(anyhow!("No items"));
}
}

match Expressions

The match expression compares a value against a series of patterns. Oxide uses -> for match arms (instead of Rust's =>) and _ as the wildcard:

fn main() {
    let number = 3

    match number {
        1 -> println!("one"),
        2 -> println!("two"),
        3 -> println!("three"),
        _ -> println!("something else"),
    }
}

Matching Multiple Patterns

Use | to match multiple values:

fn main() {
    let number = 2

    match number {
        1 | 2 -> println!("one or two"),
        3 -> println!("three"),
        _ -> println!("other"),
    }
}

Matching Ranges

Use ..= for inclusive ranges:

fn main() {
    let number = 7

    match number {
        1..=5 -> println!("one through five"),
        6..=10 -> println!("six through ten"),
        _ -> println!("something else"),
    }
}

Matching with Guards

Add conditions to patterns with if:

fn main() {
    let pair = (2, -2)

    match pair {
        (x, y) if x == y -> println!("twins"),
        (x, y) if x + y == 0 -> println!("opposites"),
        (x, _) if x % 2 == 0 -> println!("first is even"),
        _ -> println!("no match"),
    }
}

Matching Enums

Match is essential for working with enums:

enum Status {
    Active,
    Inactive,
    Pending { reason: String },
}

fn describeStatus(status: Status): String {
    match status {
        Status.Active -> "User is active".toString(),
        Status.Inactive -> "User is inactive".toString(),
        Status.Pending { reason: r } -> "Pending: \(r)".toString(),
    }
}

Rust comparison: Oxide uses dot notation (Status.Active) for enum variants. Rust's double colon syntax (Status::Active) does not exist in Oxide and will cause a syntax error.

Matching Nullable Types

Use null in pattern position to match None:

fn describe(value: Int?): String {
    match value {
        Some(n) if n > 0 -> "positive: \(n)".toString(),
        Some(n) if n < 0 -> "negative: \(n)".toString(),
        Some(0) -> "zero".toString(),
        null -> "no value".toString(),
    }
}

Match as Expression

Like if, match is an expression and returns a value:

fn main() {
    let number = 3

    let description = match number {
        1 -> "one",
        2 -> "two",
        3 -> "three",
        _ -> "many",
    }

    println!("Number is \(description)")
}

Multi-Statement Arms

Use blocks for complex match arms:

fn process(value: Int): String {
    match value {
        0 -> "zero".toString(),
        n if n > 0 -> {
            let doubled = n * 2
            let squared = n * n
            "positive: doubled=\(doubled), squared=\(squared)".toString()
        },
        _ -> {
            println!("Warning: negative value")
            "negative".toString()
        },
    }
}

Loops

Oxide provides three loop constructs: loop, while, and for.

Infinite Loops with loop

The loop keyword creates an infinite loop:

fn main() {
    var counter = 0

    loop {
        counter += 1
        println!("Count: \(counter)")

        if counter >= 5 {
            break
        }
    }
}

Returning Values from Loops

You can return a value from a loop using break:

fn main() {
    var counter = 0

    let result = loop {
        counter += 1

        if counter == 10 {
            break counter * 2
        }
    }

    println!("Result: \(result)")  // Prints: Result: 20
}

Loop Labels

Use labels to break or continue outer loops:

fn main() {
    var count = 0

    'outer: loop {
        println!("count = \(count)")
        var remaining = 10

        loop {
            println!("remaining = \(remaining)")

            if remaining == 9 {
                break
            }
            if count == 2 {
                break 'outer
            }
            remaining -= 1
        }

        count += 1
    }

    println!("End count = \(count)")
}

Conditional Loops with while

Execute code while a condition is true:

fn main() {
    var number = 3

    while number != 0 {
        println!("\(number)!")
        number -= 1
    }

    println!("LIFTOFF!")
}

while let for Conditional Pattern Matching

Similar to if let, but loops while the pattern matches:

fn main() {
    var stack: Vec<Int> = vec![1, 2, 3]

    while let value = stack.pop() {
        println!("Popped: \(value)")
    }
}

Iterating with for

The for loop iterates over collections:

fn main() {
    let numbers = [10, 20, 30, 40, 50]

    for number in numbers {
        println!("Value: \(number)")
    }
}

Iterating with Ranges

fn main() {
    // 1 to 4 (exclusive end)
    for i in 1..5 {
        println!("\(i)")
    }

    // 1 to 5 (inclusive end)
    for i in 1..=5 {
        println!("\(i)")
    }

    // Reverse order
    for i in (1..=5).rev() {
        println!("\(i)")
    }
}

Iterating with Index

Use enumerate() to get both index and value:

fn main() {
    let names = vec!["Alice", "Bob", "Charlie"]

    for (index, name) in names.iter().enumerate() {
        println!("\(index): \(name)")
    }
}

Loop Control

Use break and continue to control loop execution:

fn main() {
    for i in 1..=10 {
        if i == 3 {
            continue  // Skip 3
        }
        if i == 8 {
            break  // Stop at 8
        }
        println!("\(i)")
    }
}

Combining Control Flow

Control flow constructs can be combined for complex logic:

fn processUsers(users: Vec<User>): Vec<String> {
    var results: Vec<String> = vec![]

    for user in users.iter() {
        // Skip inactive users
        guard user.isActive else {
            continue
        }

        // Handle different user types
        let message = match user.role {
            Role.Admin -> "Admin: \(user.name)".toString(),
            Role.Moderator -> "Mod: \(user.name)".toString(),
            Role.User -> {
                if let email = user.email {
                    "User: \(user.name) <\(email)>".toString()
                } else {
                    "User: \(user.name)".toString()
                }
            },
        }

        results.push(message)
    }

    results
}

Summary

Key Oxide differences from Rust:

• Match arms use -> (Rust's => is invalid in Oxide)
• Match wildcard arm is _
• guard provides clean early-return syntax
• if let x = nullable auto-unwraps without Some()
• Enum variants use dot notation (Enum.Variant); Rust's :: syntax does not exist in Oxide

These constructs give you precise control over program flow while maintaining Oxide's goal of being approachable and readable.

Understanding Ownership

Ownership is the feature that makes Rust (and therefore Oxide) both safe and fast without a garbage collector. It determines when values are created, moved, borrowed, and dropped.

What You'll Learn

• The ownership rules and how moves work
• Borrowing with references and the rules that keep them safe
• The slice type for working with parts of collections

A First Look

fn main() {
    let name = String.from("Oxide")

    // `name` moves into `owner`
    let owner = name

    // name is no longer valid here
    // println!("\(name)")

    let greeting = String.from("Hello")
    let length = stringLength(&greeting)
    println!("'\(greeting)' has length \(length)")
}

fn stringLength(text: &String): Int {
    text.len()
}

Ownership errors can feel strict at first, but they prevent entire classes of bugs at compile time. The next sections explain the rules in detail and show how to design programs around them.

What is Ownership?

Ownership is the defining feature of Oxide. It's the system that allows Oxide to make memory safety guarantees without needing a garbage collector. Understanding ownership is crucial to becoming proficient in Oxide. In this chapter, we'll explore ownership and related features that help manage memory automatically.

Oxide inherits Rust's brilliant ownership system with one simple observation: Rust was right. Rather than reinvent the wheel, Oxide provides Oxide's familiar syntax while keeping ownership semantics identical to Rust. This means you get the same safety guarantees, the same zero-cost abstractions, and the same performance—just with a syntax that feels more natural if you're coming from Swift, Kotlin, or TypeScript.

The Ownership Rules

Oxide has three fundamental ownership rules:

1. Each value in Oxide has a variable that is its owner
2. There can only be one owner at a time
3. When the owner goes out of scope, the value is dropped (freed)

These rules prevent memory leaks and use-after-free bugs at compile time. Let's explore each with examples.

Variable Scope

A scope is the range within a program where an item is valid. Consider this example:

fn main() {
    {  // s is not yet declared
        let s = "hello"  // s is valid from this point forward
        println!("\(s)")  // s is still valid
    }  // this scope is now over, and s is no longer valid
    // println!("\(s)")  // Error: s is out of scope
}

When s comes into scope, it is valid. It remains valid until it goes out of scope. At that point, the string's memory is automatically freed.

The String Type and the Move Semantic

Let's look at how ownership works with dynamically allocated data. We'll use String as our example because it's more interesting than the &str literals we've seen so far:

fn main() {
    let s1 = String.from("hello")
    let s2 = s1  // s1's data is MOVED to s2

    // println!("\(s1)")  // Error: s1 no longer owns the data
    println!("\(s2)")     // OK: s2 owns the data
}

When we assign s1 to s2, the ownership transfers. This is different from copying the data—it's moving ownership. s1 is no longer valid, and s2 owns the string data.

Why move instead of copy? Moving is Oxide's way of ensuring that only one owner exists at a time. This prevents multiple parts of your code from trying to manage the same memory, which would be a recipe for bugs.

Here's what happens in memory:

1. s1 is created and points to allocated memory containing "hello"
2. s2 = s1 moves the pointer, length, and capacity from s1 to s2
3. s1 is invalidated (its ownership is lost)
4. When s2 goes out of scope, the memory is freed

This is sometimes called a "shallow copy" in other languages, but Oxide goes further by making the original binding invalid. There's no risk of both variables trying to free the same memory.

Ownership and Functions

The same ownership rules apply when passing values to functions:

fn main() {
    let s = String.from("hello")
    takesOwnership(s)
    // println!("\(s)")  // Error: s has been moved into the function
}

fn takesOwnership(someString: String) {
    println!("\(someString)")
}  // someString goes out of scope and the string is dropped

When s is passed to takesOwnership, ownership of the string is transferred to the function's parameter. Once the function returns, the string is dropped.

If you want to use s after calling the function, you need to get the ownership back:

fn main() {
    let s = String.from("hello")
    let s = takesAndReturnsOwnership(s)
    println!("\(s)")  // OK: we got ownership back
}

fn takesAndReturnsOwnership(someString: String): String {
    someString  // ownership is returned
}

This pattern—taking ownership and returning it—is cumbersome. This is why Oxide has references and borrowing, which we'll explore in the next section. For now, understand that ownership follows these simple rules everywhere in your code.

Ownership and Copying

Some types in Oxide are simple enough that their values can be copied bit-by-bit without issues. These types implement the Copy trait. If a type implements Copy, ownership is not moved—the value is copied instead:

fn main() {
    let x = 5
    let y = x  // x is COPIED, not moved

    println!("x = \(x), y = \(y)")  // Both are valid!
}

Integer types, floating-point numbers, booleans, and characters all implement Copy because they're small and live on the stack. More complex types like String do not implement Copy because their data lives on the heap.

As a rule of thumb:

• Stack types (integers, floats, bools, chars) implement Copy
• Heap types (strings, vectors, collections) do NOT implement Copy

Implicit Returns and Ownership

In Oxide, the last expression in a function is the return value. This interacts with ownership in an important way:

fn createString(): String {
    let s = String.from("hello")
    s  // ownership is transferred to the caller
}

fn main() {
    let result = createString()
    println!("\(result)")  // OK: createString returned ownership
}

The value s goes out of scope at the end of createString, but because it's being returned, ownership is transferred to the caller. The memory is not dropped.

Why Ownership Matters

Oxide's ownership system provides several critical benefits:

1. Memory Safety: Ownership prevents use-after-free and double-free bugs
2. No Garbage Collector: Memory is freed automatically without runtime overhead
3. No Runtime Errors: Memory errors are caught at compile time, not in production
4. Zero-Cost Abstractions: The safety checks have no runtime cost

The elegance of Rust's ownership system is that it aligns with how we actually think about resources. When a function takes ownership, it's clear that the function is responsible for that resource. When it returns something, it transfers responsibility to the caller. This natural model prevents accidental resource leaks.

Rust's Ownership: The Gold Standard

Rust's ownership system is considered one of the greatest achievements in programming language design. It solved a problem that plagued systems programming for decades: how to provide memory safety without garbage collection. Oxide embraces this system completely.

If you've used languages with garbage collectors, this might feel unfamiliar at first. But once you understand the rules, you'll find that ownership makes code clearer and safer. You're not fighting the language—the language is helping you express your intent precisely.

Summary

• Each value has one owner at a time
• Ownership transfers when assigning to a new variable or passing to a function
• When the owner goes out of scope, the value is dropped (memory is freed)
• Types that implement Copy are copied instead of moved
• The ownership rules are the same as Rust—we kept what worked perfectly

The ownership system might seem strict, but it's what makes Oxide safe by default. In the next section, we'll learn about references and borrowing, which lets you use data without taking ownership of it.

References and Borrowing

Ownership is powerful, but constantly moving values in and out of functions gets tedious. Fortunately, Oxide has a feature for using values without transferring ownership: references.

A reference allows you to refer to a value without taking ownership of it. Instead of passing the value itself, you pass a reference to it. When the function returns, ownership remains with the original owner.

Creating and Using References

You create a reference using the ampersand (&) operator:

fn main() {
    let s = String.from("hello")

    let length = calculateLength(&s)

    println!("'{}' has length {}", s, length)  // s is still valid!
}

fn calculateLength(s: &String): UIntSize {
    s.len()
}  // s goes out of scope, but it doesn't own the String, so nothing happens

The &s syntax creates a reference to s. The calculateLength function receives a reference (&String) instead of the string itself. Since calculateLength doesn't own the string, the string is not dropped when the function returns.

Notice that we can still use s after calling calculateLength. The original owner retains ownership; we only loaned it to the function.

Mutable References

By default, references are immutable. If you try to modify the data through a reference, the compiler stops you:

fn main() {
    let s = String.from("hello")

    // changeString(&s)  // Error: cannot mutate through immutable reference
    changeString(&mut s)  // Error: s is immutable
}

fn changeString(s: &String) {
    // s.pushStr(" world")  // Error: cannot mutate through immutable reference
}

To modify data through a reference, you need a mutable reference, declared with &mut:

fn main() {
    var s = String.from("hello")

    changeString(&mut s)

    println!("\(s)")  // "hello world"
}

fn changeString(s: &mut String) {
    s.pushStr(" world")
}

Important: The original binding must be mutable (var s) to allow mutable references. You cannot create a mutable reference to an immutable binding.

The Rules of Borrowing

Oxide's borrow checker enforces two critical rules:

1. Either multiple immutable references OR one mutable reference at a time
2. References must always be valid (no use-after-free)

Let's explore these rules with examples.

Multiple Immutable References

You can have multiple immutable references to the same data:

fn main() {
    let s = String.from("hello")

    let r1 = &s
    let r2 = &s
    let r3 = &s

    println!("\(r1), \(r2), \(r3)")  // All three references work fine
}

This is safe because all readers are immutable. Multiple readers cannot corrupt data.

Immutable and Mutable References Cannot Coexist

Once you create a mutable reference, you cannot have any immutable references:

fn main() {
    var s = String.from("hello")

    let r1 = &s
    let r2 = &s
    // var r3 = &mut s  // Error: cannot borrow as mutable while already borrowed as immutable

    println!("\(r1), \(r2)")
}

The compiler prevents the mutable reference because r1 and r2 are still in use. If we allowed &mut s, code using r1 or r2 might suddenly see the data change, which would be surprising and dangerous.

Using Scope to Release Borrows

A borrow ends when the reference is last used, not necessarily when it goes out of scope:

fn main() {
    var s = String.from("hello")

    let r1 = &s
    let r2 = &s
    println!("\(r1), \(r2)")  // Last use of r1 and r2

    // r1 and r2 are no longer needed after this point
    var r3 = &mut s  // OK: r1 and r2's borrows have ended
    r3.pushStr(" world")

    println!("\(r3)")
}

This is called non-lexical lifetimes (NLL). Rust introduced this feature to make borrowing less restrictive. Oxide inherits it, which means you often get mutable access sooner than you might expect.

Mutable References Are Exclusive

Only one mutable reference can exist at a time:

fn main() {
    var s = String.from("hello")

    var r1 = &mut s
    // var r2 = &mut s  // Error: cannot have two mutable references

    r1.pushStr(" world")
    println!("\(r1)")
}

This rule prevents data races and ensures that if you modify data, no other code can see it in an inconsistent state.

The &str Lightweight Reference

We've seen &str in function parameters. This is a reference to a string slice, which we'll explore in the next section. For now, understand that &str borrows a string—it's lighter weight than &String because it doesn't own any heap allocation:

fn main() {
    let s = String.from("hello world")

    let word = firstWord(&s)

    println!("\(word)")  // "hello"
}

fn firstWord(s: &str): &str {
    let bytes = s.asBytes()

    for (i, &item) in bytes.iter().enumerate() {
        if item == ' ' {
            return &s[0..i]
        }
    }

    &s[..]
}

Using &str is more flexible than &String because it accepts both String references and string literals.

Why Borrowing Matters

The borrowing system solves the ownership problem we encountered earlier. Instead of constantly moving values and returning them, you can borrow them:

// Without borrowing: tedious
fn main() {
    let s1 = String.from("hello")
    let (s1, len) = calculateLength(s1)
    println!("'{}' has length {}", s1, len)
}

fn calculateLength(s: String): (String, UIntSize) {
    let length = s.len()
    (s, length)
}

// With borrowing: clean
fn main() {
    let s1 = String.from("hello")
    let len = calculateLength(&s1)
    println!("'{}' has length {}", s1, len)
}

fn calculateLength(s: &String): UIntSize {
    s.len()
}

Borrowing lets functions use data without taking responsibility for it.

Mutable References Enable Controlled Mutation

Mutable references are Oxide's way of saying "this function needs to modify this data." They make your code's intent clear:

fn main() {
    var user = User { name: "Alice".toString() }
    updateUserName(&mut user, "Bob")
    println!("\(user.name)")  // "Bob"
}

fn updateUserName(user: &mut User, newName: &str) {
    user.name = newName.toString()
}

The &mut syntax makes it obvious that the function will modify the argument. This is much clearer than passing a regular parameter and having side effects.

Lifetime Annotations

Sometimes the compiler needs you to explicitly specify how long a reference is valid. This is called a lifetime. We'll explore lifetimes in depth in a later chapter, but here's a simple example:

fn longest<'a>(x: &'a str, y: &'a str): &'a str {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

fn main() {
    let s1 = "short"
    let s2 = "a much longer string"
    let result = longest(s1, s2)
    println!("\(result)")
}

The 'a notation tells the compiler that the returned reference lives as long as both input references. This ensures the return value is always valid.

You don't need to understand lifetimes yet. Just know that Oxide sometimes requires you to be explicit about how long references live, which is another safety feature.

Rust Comparison

The referencing and borrowing system is identical to Rust. The same &T and &mut T syntax, the same rules, the same benefits:

#![allow(unused)]
fn main() {
// Rust - identical to Oxide
fn calculate_length(s: &String) -> usize {
    s.len()
}

fn change_string(s: &mut String) {
    s.push_str(" world");
}
}

Summary

• References allow using values without taking ownership
• Immutable references (&T) are the default
• Mutable references (&mut T) allow modification, with restrictions
• Oxide enforces: either many immutable references OR one mutable reference
• Borrows end when the reference is no longer used (non-lexical lifetimes)
• References prevent data races and use-after-free bugs at compile time
• Lifetime annotations sometimes explicit about how long references live

Borrowing is one of Oxide's most powerful features. It lets you express ownership clearly while remaining flexible about how data flows through your program. Combined with ownership, it enables memory safety without garbage collection—the same achievement Rust pioneered.

In the next section, we'll explore a special kind of reference: slices.

The Slice Type

A slice is a reference to a contiguous sequence of elements in a collection. Unlike references to the whole collection, slices let you reference a specific portion of it. Slices are incredibly useful and appear throughout Oxide code.

String Slices

A string slice is a reference to part of a String:

fn main() {
    let s = String.from("hello world")

    let hello = &s[0..5]
    let world = &s[6..11]

    println!("\(hello)")  // "hello"
    println!("\(world)")  // "world"
}

Rather than taking a reference to the entire string, &s[0..5] creates a reference to a portion of the string. The range syntax [startingIndex..endingIndex] includes startingIndex but excludes endingIndex.

Rust comparison: String slices work identically to Rust. The type annotation is &str.

#![allow(unused)]
fn main() {
// Rust - identical syntax
let s = String::from("hello world");
let hello = &s[0..5];
let world = &s[6..11];
}

Slice Shorthand Syntax

You can omit the starting index if it's 0 or the ending index if it's the length:

fn main() {
    let s = String.from("hello")

    let slice1 = &s[0..2]  // "he"
    let slice2 = &s[..2]   // "he" - same, omit start

    let slice3 = &s[3..5]  // "lo"
    let slice4 = &s[3..]   // "lo" - same, omit end

    let slice5 = &s[..]    // "hello" - entire string
}

This shorthand makes slice syntax less verbose for common cases.

Using Slices in Functions

Slices are particularly useful in function parameters because they're more flexible than &String:

fn firstWord(s: &str): &str {
    let bytes = s.asBytes()

    for (i, &item) in bytes.iter().enumerate() {
        if item == ' ' as UInt8 {
            return &s[0..i]
        }
    }

    &s[..]
}

fn main() {
    let myString = String.from("hello world")
    let word = firstWord(&myString)
    println!("\(word)")  // "hello"

    // Also works with string literals
    let word = firstWord("hello world")
    println!("\(word)")  // "hello"
}

Notice that firstWord takes &str, not &String. This makes it more flexible. We can pass:

• A reference to a String: &myString (automatically coerced to &str)
• A string literal: "hello world" (which is already &str)

If the function required &String, we couldn't pass string literals directly.

The Power of &str Over &String

Using &str in your API makes your code more flexible:

// Restrictive: only accepts String references
fn processBad(s: &String): UIntSize {
    s.len()
}

// Flexible: accepts string slices and String references
fn processGood(s: &str): UIntSize {
    s.len()
}

fn main() {
    let myString = String.from("hello")
    let literal = "world"

    // processBad(literal)  // Error: literal is &str, not &String
    processGood(&myString)  // OK: &String coerces to &str
    processGood(literal)    // OK: already &str
}

This is a key principle in Oxide and Rust: prefer &str over &String, &[T] over &Vec<T>, etc. Your APIs are more useful when they accept slices rather than owned collections.

Array Slices

Slices work with arrays and vectors, not just strings:

fn main() {
    let arr = [1, 2, 3, 4, 5]

    // Slice part of the array
    let slice = &arr[1..4]  // [2, 3, 4]

    // Iterate over the slice
    for item in slice {
        println!("\(item)")
    }
}

With vectors, slices are even more useful:

fn main() {
    let v = vec![1, 2, 3, 4, 5]

    let slice = &v[2..]  // [3, 4, 5]

    println!("Length of slice: \(slice.len())")

    for &item in slice {
        println!("\(item)")
    }
}

Slices and Borrowing

Slices respect the borrowing rules. You cannot create a mutable reference to a collection while slices exist:

fn main() {
    var s = String.from("hello world")

    let word = firstWord(&s)  // immutable borrow

    // s.clear()  // Error: cannot borrow as mutable while borrowed as immutable

    println!("\(word)")  // word's borrow ends here

    s.clear()  // OK now: word is no longer used
}

fn firstWord(s: &str): &str {
    let bytes = s.asBytes()

    for (i, &item) in bytes.iter().enumerate() {
        if item == ' ' as UInt8 {
            return &s[0..i]
        }
    }

    &s[..]
}

This prevents a common bug: modifying a collection while holding a reference to its contents. The slice is only valid as long as the underlying data doesn't change.

The Slice Type Syntax

The type of a slice is &[T], where T is the element type:

fn main() {
    let s = String.from("hello")
    let slice: &str = &s[..]  // &str is shorthand for &[char] (roughly)

    let arr = [1, 2, 3]
    let slice: &[Int] = &arr[..]  // &[Int] slice

    let v = vec![1, 2, 3]
    let slice: &[Int] = &v[..]  // &[Int] slice from vector
}

The syntax &[T] represents "a reference to a contiguous sequence of T". Notice that &str is special—it's the slice type for strings, optimized for UTF-8 text.

Practical Example: Splitting Words

Let's build something practical. A function that splits a string into words and returns an array of slices:

fn splitWords(s: &str): Vec<&str> {
    var words = vec![]
    var start = 0

    for (i, &c) in s.asBytes().iter().enumerate() {
        if c == ' ' as UInt8 {
            words.push(&s[start..i])
            start = i + 1
        }
    }

    if start < s.len() {
        words.push(&s[start..])
    }

    words
}

fn main() {
    let sentence = "the quick brown fox"
    let words = splitWords(sentence)

    for word in words {
        println!("Word: \(word)")
    }
}

Output:

Word: the
Word: quick
Word: brown
Word: fox

This function takes a string slice, and returns a vector of slices pointing into the original string. No data is copied—only references are created.

Why Slices Are Important

Slices embody three key principles:

1. Zero-Cost Abstractions: Slices have no runtime overhead. They're just a pointer and length.
2. Safety: Slices prevent out-of-bounds access at compile time.
3. Flexibility: Functions accepting slices work with owned collections, string literals, and stack arrays.

Because of these properties, slices appear everywhere in Oxide code. They're the idiomatic way to work with sequences.

Common Slice Methods

Slices provide useful methods for working with sequences:

fn main() {
    let v = vec![1, 2, 3, 4, 5]
    let slice = &v[1..4]  // [2, 3, 4]

    // Length
    println!("Length: \(slice.len())")  // 3

    // Access elements
    println!("First: \(slice[0])")      // 2
    println!("Last: \(slice[2])")       // 4

    // Iteration
    for &item in slice {
        println!("Item: \(item)")
    }

    // Check if empty
    if slice.isEmpty() {
        println!("Empty slice")
    } else {
        println!("Not empty")
    }
}

Summary

• Slices are references to contiguous portions of collections
• String slices are denoted &str; array/vector slices are &[T]
• Create slices with range syntax: &collection[start..end]
• Use shorthand: &s[..] for the whole collection, &s[..n] to omit end, etc.
• Slices are more flexible than references to whole collections; prefer them in APIs
• Slices respect borrowing rules: no modification while slices exist
• Slices have zero runtime cost and no bounds checking overhead

Slices combine safety with flexibility. They're one of the features that makes Oxide (and Rust) pleasant to use. By understanding ownership, references, and slices, you now have the foundation to write safe, efficient code.

The ownership system—ownership itself, borrowing, and slices—is complete. These three concepts form the bedrock of Oxide's memory safety story.

Using Structs to Structure Related Data

Structs let you group related data into a single type. In Oxide, structs look similar to Rust, but methods are implemented using extension blocks.

What You'll Learn

• How to define and instantiate structs
• How to use field shorthand and update syntax
• How to add methods with extension

A Simple Example

public struct User {
    public username: String,
    public email: String,
    public active: Bool,
}

extension User {
    public static fn new(username: String, email: String): User {
        User {
            username,
            email,
            active: true,
        }
    }

    public mutating fn deactivate() {
        self.active = false
    }
}

In the next sections, we'll explore how struct syntax works and how to build methods that make your types easier to use.

Defining and Instantiating Structs

Structs are one of the fundamental ways to create custom types in Oxide. A struct, short for "structure," lets you package together related values under a single name. If you're coming from object-oriented languages, a struct is similar to a class's data attributes.

Defining Structs

To define a struct, use the struct keyword followed by the struct name and curly braces containing the field definitions. Each field has a name and a type, using Oxide's camelCase naming convention for field names.

struct User {
    active: Bool,
    username: String,
    email: String,
    signInCount: UInt64,
}

Notice that:

• Field names use camelCase (e.g., signInCount, not signInCount)
• Types use Oxide's type aliases (Bool, UInt64) or standard types (String)
• The struct body uses curly braces, just like Rust

Public Structs and Fields

To make a struct accessible from other modules, use the public keyword:

public struct User {
    public active: Bool,
    public username: String,
    email: String,           // Private by default
    signInCount: UInt64,     // Private by default
}

The public keyword replaces Rust's pub for visibility. You can apply it to both the struct itself and individual fields.

Creating Instances

To create an instance of a struct, specify the struct name followed by curly braces containing the field values:

fn main() {
    let user = User {
        active: true,
        username: "alice123".toString(),
        email: "alice@example.com".toString(),
        signInCount: 1,
    }
}

The order of fields doesn't matter when creating an instance, but all fields must be provided (unless they have default values through other mechanisms).

Mutable Instances

If you need to modify a struct instance after creation, use var instead of let:

fn main() {
    var user = User {
        active: true,
        username: "alice123".toString(),
        email: "alice@example.com".toString(),
        signInCount: 1,
    }

    // Now we can modify fields
    user.email = "newemail@example.com".toString()
    user.signInCount += 1
}

Note that in Oxide, the entire instance must be mutable to change any field. You cannot mark only certain fields as mutable.

Accessing Field Values

Use dot notation to access struct fields:

fn main() {
    let user = User {
        active: true,
        username: "alice123".toString(),
        email: "alice@example.com".toString(),
        signInCount: 1,
    }

    println!("Username: \(user.username)")
    println!("Email: \(user.email)")
    println!("Sign-in count: \(user.signInCount)")
}

Oxide's string interpolation with \(expression) makes it easy to embed field values directly in output strings.

Field Init Shorthand

When variable names match field names, you can use the shorthand syntax:

fn createUser(username: String, email: String): User {
    User {
        active: true,
        username,   // Same as username: username
        email,      // Same as email: email
        signInCount: 1,
    }
}

This shorthand reduces repetition when the parameter names match the field names.

Struct Update Syntax

When creating a new instance that reuses most values from an existing instance, use the struct update syntax with ..:

fn main() {
    let user1 = User {
        active: true,
        username: "alice123".toString(),
        email: "alice@example.com".toString(),
        signInCount: 1,
    }

    let user2 = User {
        email: "bob@example.com".toString(),
        ..user1  // Use remaining fields from user1
    }

    // user2 has bob's email but alice's username, active status, and signInCount
}

The ..user1 must come last in the struct literal. It copies all remaining fields from the source instance.

Important ownership note: The struct update syntax moves data from the source. After the update, user1 cannot be used if any of its fields were moved (like String fields). However, if only copyable types (like Bool or UInt64) are transferred, the source remains valid.

Tuple Structs

Oxide supports tuple structs, which are structs without named fields. These are useful when you want to give a tuple a distinct type name:

struct Color(Int, Int, Int)
struct Point(Int, Int, Int)

fn main() {
    let black = Color(0, 0, 0)
    let origin = Point(0, 0, 0)

    // Access fields by index
    let red = black.0
    let green = black.1
    let blue = black.2
}

Even though Color and Point have the same field types, they are different types. A function expecting a Color won't accept a Point.

Unit-Like Structs

You can also define structs with no fields, called unit-like structs:

struct AlwaysEqual

fn main() {
    let subject = AlwaysEqual
}

Unit-like structs are useful when you need to implement a trait on a type but don't need to store any data.

Adding Attributes

Structs commonly use derive attributes to automatically implement traits:

#[derive(Debug, Clone, PartialEq)]
public struct User {
    active: Bool,
    username: String,
    email: String,
    signInCount: UInt64,
}

The #[derive(...)] attribute automatically generates implementations for common traits:

• Debug: Enables printing with {:?} format specifier
• Clone: Enables creating deep copies with .clone()
• PartialEq: Enables comparison with == and !=

Complete Example

Here's a complete example showing struct definition and usage:

#[derive(Debug, Clone)]
public struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let rect = Rectangle {
        width: 30,
        height: 50,
    }

    println!("Rectangle: {:?}", rect)
    println!("Width: \(rect.width)")
    println!("Height: \(rect.height)")

    // Create a modified copy
    let wider = Rectangle {
        width: 60,
        ..rect
    }

    println!("Wider rectangle: {:?}", wider)
}

Rust Comparison

The underlying semantics are identical. Oxide structs are Rust structs with different naming conventions and type aliases. The compiled binary is exactly the same as equivalent Rust code.

Summary

Structs let you create custom types that package related data together:

• Use struct with curly braces for named fields
• Use camelCase for field names
• Use public for visibility
• Create instances with struct literals
• Use var for mutable instances
• Derive common traits with #[derive(...)]

In the next section, we'll build a complete program using structs to see how they work in practice.

An Example Program Using Structs

To understand when structs are useful, let's build a program that calculates the area of a rectangle. We'll start with simple variables and progressively refactor to use structs, demonstrating how they improve code organization and clarity.

Starting with Simple Variables

Here's a basic approach using individual variables:

fn main() {
    let width = 30
    let height = 50

    println!(
        "The area of the rectangle is \(area(width, height)) square pixels."
    )
}

fn area(width: Int, height: Int): Int {
    width * height
}

This works, but the area function has two parameters that conceptually belong together. The relationship between width and height isn't explicit in the code.

Refactoring with Tuples

We can group the dimensions using a tuple:

fn main() {
    let rect = (30, 50)

    println!(
        "The area of the rectangle is \(area(rect)) square pixels."
    )
}

fn area(dimensions: (Int, Int)): Int {
    dimensions.0 * dimensions.1
}

This groups the data, but now we've lost meaning. Is dimensions.0 the width or the height? The tuple doesn't convey this information, making the code harder to understand.

Refactoring with Structs

Structs solve this by giving meaningful names to both the type and its fields:

struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let rect = Rectangle {
        width: 30,
        height: 50,
    }

    println!(
        "The area of the rectangle is \(area(&rect)) square pixels."
    )
}

fn area(rectangle: &Rectangle): Int {
    rectangle.width * rectangle.height
}

Now the code clearly shows that width and height are dimensions of a Rectangle. The function signature area(rectangle: &Rectangle) immediately conveys what the function operates on.

Notice that area takes a reference &Rectangle. This means:

• The function borrows the rectangle rather than taking ownership
• The original rect remains valid after the function call
• No data is copied, just a reference to the existing rectangle

Adding Debug Output

When developing, you often want to print struct values for debugging. Let's see what happens if we try to print our rectangle:

struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let rect = Rectangle {
        width: 30,
        height: 50,
    }

    println!("rect is \(rect)")  // This won't compile!
}

This fails because Rectangle doesn't implement the Display trait that string interpolation requires. For debugging purposes, we can use the Debug trait:

#[derive(Debug)]
struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let rect = Rectangle {
        width: 30,
        height: 50,
    }

    // Use {:?} for Debug formatting
    println!("rect is {:?}", rect)

    // Use {:#?} for pretty-printed Debug output
    println!("rect is {:#?}", rect)
}

Output:

rect is Rectangle { width: 30, height: 50 }
rect is Rectangle {
    width: 30,
    height: 50,
}

The #[derive(Debug)] attribute automatically generates an implementation of the Debug trait, enabling the {:?} and {:#?} format specifiers.

Using dbg! Macro

For quick debugging, the dbg! macro is even more convenient:

#[derive(Debug)]
struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let scale = 2
    let rect = Rectangle {
        width: dbg!(30 * scale),
        height: 50,
    }

    dbg!(&rect)
}

Output:

[src/main.ox:9:16] 30 * scale = 60
[src/main.ox:13:5] &rect = Rectangle {
    width: 60,
    height: 50,
}

The dbg! macro:

• Prints the file and line number
• Shows the expression being evaluated
• Returns ownership of the value (so it can be used inline)
• Outputs to stderr rather than stdout

Notice that we use dbg!(&rect) with a reference to avoid moving ownership.

Complete Working Example

Here's the complete program with all improvements:

#[derive(Debug)]
struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let rect = Rectangle {
        width: 30,
        height: 50,
    }

    let area = calculateArea(&rect)

    println!("Rectangle: {:#?}", rect)
    println!("Area: \(area) square pixels")

    // Example with multiple rectangles
    let rectangles = vec![
        Rectangle { width: 10, height: 20 },
        Rectangle { width: 30, height: 50 },
        Rectangle { width: 5, height: 15 },
    ]

    println!("\nAll rectangles:")
    for rect in rectangles.iter() {
        println!("  {:?} -> area: \(calculateArea(rect))", rect)
    }
}

fn calculateArea(rectangle: &Rectangle): Int {
    rectangle.width * rectangle.height
}

Output:

Rectangle: Rectangle {
    width: 30,
    height: 50,
}
Area: 1500 square pixels

All rectangles:
  Rectangle { width: 10, height: 20 } -> area: 200
  Rectangle { width: 30, height: 50 } -> area: 1500
  Rectangle { width: 5, height: 15 } -> area: 75

Deriving Multiple Traits

In practice, you'll often derive several traits together:

#[derive(Debug, Clone, PartialEq, Eq)]
struct Rectangle {
    width: Int,
    height: Int,
}

fn main() {
    let rect1 = Rectangle { width: 30, height: 50 }
    let rect2 = rect1.clone()  // Create a copy
    let rect3 = Rectangle { width: 40, height: 50 }

    println!("rect1 == rect2: \(rect1 == rect2)")  // true
    println!("rect1 == rect3: \(rect1 == rect3)")  // false
}

Common derivable traits:

• Debug: Enables {:?} formatting for debugging
• Clone: Enables .clone() for deep copying
• PartialEq: Enables == and != comparison
• Eq: Indicates that equality is reflexive, symmetric, and transitive
• Hash: Enables use as a key in HashMap

Why Use Structs?

This example demonstrates several benefits of structs:

1. Semantic clarity: Rectangle is more meaningful than (Int, Int)
2. Self-documenting code: Field names like width and height explain themselves
3. Type safety: A Rectangle can't be confused with other (Int, Int) tuples
4. Extensibility: Easy to add more fields or functionality later
5. Maintainability: Changes to the struct definition are centralized

Moving Toward Methods

The calculateArea function works, but it's disconnected from the Rectangle type. Conceptually, calculating area is something a rectangle does, not something done to a rectangle.

In the next section, we'll learn about methods, which let us define functions that are directly associated with a struct:

extension Rectangle {
    fn area(): Int {
        self.width * self.height
    }
}

fn main() {
    let rect = Rectangle { width: 30, height: 50 }
    println!("Area: \(rect.area())")  // More natural!
}

This syntax, using extension blocks and implicit self, is one of Oxide's major features and is covered in detail in the next section.

Summary

In this section, we saw how to:

• Refactor code to use structs for better organization
• Derive the Debug trait for printing struct values
• Use dbg! for quick debugging
• Access struct fields through references
• Appreciate the benefits of structured data

Next, we'll explore method syntax to make our struct-related functions even more intuitive and powerful.

Method Syntax

Methods are functions defined within the context of a type. In Oxide, we define methods using extension blocks, which associate functions with a struct, enum, or trait. This is one of Oxide's major features that differs significantly from Rust's impl blocks.

Defining Methods with Extension Blocks

Let's transform our calculateArea function from the previous section into a method on Rectangle:

#[derive(Debug)]
struct Rectangle {
    width: Int,
    height: Int,
}

extension Rectangle {
    fn area(): Int {
        self.width * self.height
    }
}

fn main() {
    let rect = Rectangle {
        width: 30,
        height: 50,
    }

    println!("Area: \(rect.area()) square pixels")
}

Key points:

• extension Rectangle { } replaces Rust's impl Rectangle { }
• Methods have implicit access to self
• No self parameter is written in the method signature
• Call methods with dot notation: rect.area()

Understanding self in Oxide Methods

In Oxide, self is implicit in non-static methods. The method modifier determines how self is accessed:

This is a fundamental difference from Rust, where you explicitly write &self, &mut self, or self as the first parameter.

Default Methods: Immutable Borrow

When you define a method without any modifier, it receives an immutable borrow of self:

extension Rectangle {
    // Default: borrows self immutably (&self)
    fn area(): Int {
        self.width * self.height
    }

    fn perimeter(): Int {
        2 * (self.width + self.height)
    }

    fn isSquare(): Bool {
        self.width == self.height
    }
}

These methods can read from self but cannot modify it. This is the most common method type and makes sense for any operation that doesn't change the object's state.

Rust Equivalent

The Oxide code above translates to this Rust code:

#![allow(unused)]
fn main() {
impl Rectangle {
    fn area(&self) -> i32 {
        self.width * self.height
    }

    fn perimeter(&self) -> i32 {
        2 * (self.width + self.height)
    }

    fn is_square(&self) -> bool {
        self.width == self.height
    }
}
}

Mutating Methods: Mutable Borrow

Use the mutating modifier when a method needs to modify self:

extension Rectangle {
    mutating fn scale(factor: Int) {
        self.width *= factor
        self.height *= factor
    }

    mutating fn setWidth(newWidth: Int) {
        self.width = newWidth
    }

    mutating fn setHeight(newHeight: Int) {
        self.height = newHeight
    }

    mutating fn double() {
        self.scale(2)  // Can call other mutating methods
    }
}

fn main() {
    var rect = Rectangle { width: 10, height: 20 }
    println!("Before: {:?}", rect)

    rect.scale(3)
    println!("After scale(3): {:?}", rect)

    rect.setWidth(100)
    println!("After setWidth(100): {:?}", rect)
}

Output:

Before: Rectangle { width: 10, height: 20 }
After scale(3): Rectangle { width: 30, height: 60 }
After setWidth(100): Rectangle { width: 100, height: 60 }

Important notes:

• You can only call mutating methods on mutable bindings (var, not let)
• The mutating keyword clearly signals that the method modifies state
• This pattern is inspired by Swift's mutating keyword

Rust Equivalent

#![allow(unused)]
fn main() {
impl Rectangle {
    fn scale(&mut self, factor: i32) {
        self.width *= factor;
        self.height *= factor;
    }

    fn set_width(&mut self, new_width: i32) {
        self.width = new_width;
    }
}
}

Consuming Methods: Taking Ownership

Use the consuming modifier when a method takes ownership of self:

extension Rectangle {
    consuming fn intoSquare(): Rectangle {
        let size = (self.width + self.height) / 2
        Rectangle { width: size, height: size }
    }

    consuming fn decompose(): (Int, Int) {
        (self.width, self.height)
    }

    consuming fn destroy() {
        // self is dropped at the end of this method
        println!("Rectangle destroyed!")
    }
}

fn main() {
    let rect = Rectangle { width: 30, height: 50 }
    let (w, h) = rect.decompose()
    println!("Width: \(w), Height: \(h)")

    // rect can no longer be used - ownership was consumed
    // println!("{:?}", rect)  // ERROR: value moved
}

Consuming methods are used when:

• Transforming a value into something else
• Extracting owned data from a struct
• Intentionally consuming a resource (like closing a file handle)

The naming convention often uses "into" prefix (like intoSquare) to signal that the original value will be consumed.

Rust Equivalent

#![allow(unused)]
fn main() {
impl Rectangle {
    fn into_square(self) -> Rectangle {
        let size = (self.width + self.height) / 2;
        Rectangle { width: size, height: size }
    }

    fn decompose(self) -> (i32, i32) {
        (self.width, self.height)
    }
}
}

Static Methods: No Self Parameter

Use the static modifier for functions that don't operate on an instance:

extension Rectangle {
    static fn new(width: Int, height: Int): Rectangle {
        Rectangle { width, height }
    }

    static fn square(size: Int): Rectangle {
        Rectangle { width: size, height: size }
    }

    static fn zero(): Rectangle {
        Rectangle { width: 0, height: 0 }
    }

    static fn fromDimensions(dimensions: (Int, Int)): Rectangle {
        Rectangle {
            width: dimensions.0,
            height: dimensions.1,
        }
    }
}

fn main() {
    let rect1 = Rectangle.new(30, 50)
    let rect2 = Rectangle.square(25)
    let rect3 = Rectangle.zero()

    println!("rect1: {:?}", rect1)
    println!("rect2: {:?}", rect2)
    println!("rect3: {:?}", rect3)
}

Static methods are called on the type itself using dot notation: Rectangle.new(30, 50) rather than rect.new(30, 50).

Common uses for static methods:

• Constructors (like new, default, fromXxx)
• Factory methods that create instances
• Utility functions related to the type

Using Self in Static Methods

Inside an extension block, Self (capital S) refers to the type being extended:

extension Rectangle {
    static fn square(size: Int): Self {
        Self { width: size, height: size }
    }

    static fn default(): Self {
        Self.zero()  // Can call other static methods
    }
}

Rust Equivalent

#![allow(unused)]
fn main() {
impl Rectangle {
    fn new(width: i32, height: i32) -> Rectangle {
        Rectangle { width, height }
    }

    fn square(size: i32) -> Self {
        Self { width: size, height: size }
    }
}
}

Note: In Rust, these are called "associated functions" when they don't take self. Oxide uses static to make this explicit.

Methods with Additional Parameters

Methods can take additional parameters beyond the implicit self:

extension Rectangle {
    fn canHold(other: &Rectangle): Bool {
        self.width > other.width && self.height > other.height
    }

    mutating fn resizeTo(width: Int, height: Int) {
        self.width = width
        self.height = height
    }

    fn areaRatio(other: &Rectangle): Float {
        self.area() as Float / other.area() as Float
    }
}

fn main() {
    let rect1 = Rectangle { width: 30, height: 50 }
    let rect2 = Rectangle { width: 10, height: 20 }

    println!("rect1 can hold rect2: \(rect1.canHold(&rect2))")
    println!("Area ratio: \(rect1.areaRatio(&rect2))")
}

Multiple Extension Blocks

You can split methods across multiple extension blocks:

struct Rectangle {
    width: Int,
    height: Int,
}

// Constructors
extension Rectangle {
    static fn new(width: Int, height: Int): Self {
        Self { width, height }
    }

    static fn square(size: Int): Self {
        Self { width: size, height: size }
    }
}

// Geometry calculations
extension Rectangle {
    fn area(): Int {
        self.width * self.height
    }

    fn perimeter(): Int {
        2 * (self.width + self.height)
    }
}

// Mutations
extension Rectangle {
    mutating fn scale(factor: Int) {
        self.width *= factor
        self.height *= factor
    }
}

This helps organize methods by category, though it's also fine to keep everything in a single block.

Implementing Traits with Extension Blocks

Extension blocks also implement traits using the syntax extension Type: Trait:

import std.fmt.{ Display, Formatter, Result }

#[derive(Clone)]
struct Rectangle {
    width: Int,
    height: Int,
}

extension Rectangle: Display {
    fn fmt(f: &mut Formatter): Result {
        write!(f, "Rectangle(\(self.width) x \(self.height))")
    }
}

fn main() {
    let rect = Rectangle { width: 30, height: 50 }
    println!("\(rect)")  // Uses Display implementation
}

This replaces Rust's impl Trait for Type syntax. The colon reads naturally: "extend Rectangle with Display capability."

Multiple Trait Implementations

import std.fmt.{ Display, Formatter, Result }
import std.cmp.{ Ord, Ordering }

extension Rectangle: Display {
    fn fmt(f: &mut Formatter): Result {
        write!(f, "\(self.width)x\(self.height)")
    }
}

extension Rectangle: PartialOrd {
    fn partialCmp(other: &Self): Ordering? {
        self.area().partialCmp(&other.area())
    }
}

Visibility in Extension Blocks

Use public to make methods accessible from other modules:

public struct Rectangle {
    public width: Int,
    public height: Int,
}

extension Rectangle {
    public static fn new(width: Int, height: Int): Self {
        Self { width, height }
    }

    public fn area(): Int {
        self.width * self.height
    }

    // Private helper method
    fn validate(): Bool {
        self.width > 0 && self.height > 0
    }

    public mutating fn scale(factor: Int) {
        if self.validate() {
            self.width *= factor
            self.height *= factor
        }
    }
}

Complete Example: A Point Struct

Here's a comprehensive example showing all method modifiers:

#[derive(Debug, Clone, PartialEq)]
public struct Point {
    x: Float,
    y: Float,
}

extension Point {
    // Static: constructors
    public static fn new(x: Float, y: Float): Self {
        Self { x, y }
    }

    public static fn origin(): Self {
        Self { x: 0.0, y: 0.0 }
    }

    public static fn fromAngle(angle: Float, distance: Float): Self {
        Self {
            x: distance * angle.cos(),
            y: distance * angle.sin(),
        }
    }

    // Default (&self): read-only operations
    public fn distanceFromOrigin(): Float {
        (self.x * self.x + self.y * self.y).sqrt()
    }

    public fn distanceTo(other: &Point): Float {
        let dx = self.x - other.x
        let dy = self.y - other.y
        (dx * dx + dy * dy).sqrt()
    }

    public fn midpointTo(other: &Point): Point {
        Point {
            x: (self.x + other.x) / 2.0,
            y: (self.y + other.y) / 2.0,
        }
    }

    // Mutating (&mut self): modifications
    public mutating fn translate(dx: Float, dy: Float) {
        self.x += dx
        self.y += dy
    }

    public mutating fn scale(factor: Float) {
        self.x *= factor
        self.y *= factor
    }

    public mutating fn normalize() {
        let dist = self.distanceFromOrigin()
        if dist != 0.0 {
            self.x /= dist
            self.y /= dist
        }
    }

    // Consuming (self): ownership transfer
    public consuming fn intoPolar(): (Float, Float) {
        let r = self.distanceFromOrigin()
        let theta = self.y.atan2(self.x)
        (r, theta)
    }

    public consuming fn add(other: Point): Point {
        Point {
            x: self.x + other.x,
            y: self.y + other.y,
        }
    }
}

fn main() {
    // Using static methods
    var point = Point.new(3.0, 4.0)
    let origin = Point.origin()

    // Using default (immutable) methods
    println!("Distance from origin: \(point.distanceFromOrigin())")
    println!("Distance to origin: \(point.distanceTo(&origin))")

    // Using mutating methods
    point.translate(1.0, 1.0)
    println!("After translate: {:?}", point)

    point.scale(2.0)
    println!("After scale: {:?}", point)

    // Using consuming method
    let polar = point.intoPolar()
    println!("Polar coordinates: r=\(polar.0), theta=\(polar.1)")

    // point is now consumed and cannot be used
}

Summary of Method Modifiers

Comparison with Rust

Note: Rust's :: path separator does not exist in Oxide. Using Type::method() in Oxide code will cause a syntax error. Oxide uses . as its only path separator.

The key insight is that Oxide makes the method's relationship to self explicit through modifiers rather than through the first parameter. This makes the intent clearer when reading method signatures.

Summary

Extension blocks are Oxide's way of adding methods to types:

• Use extension Type { } for inherent methods
• Use extension Type: Trait { } for trait implementations
• Method modifiers (mutating, consuming, static) replace explicit self parameters
• Default methods borrow immutably (&self)
• mutating methods can modify state (&mut self)
• consuming methods take ownership (self)
• static methods have no self and are called on the type
• Use public for visibility, just like with structs

This syntax makes method signatures more readable and the relationship between methods and their data more explicit, while compiling to exactly the same code as equivalent Rust.

Enums and Pattern Matching

Enums let you define a type by enumerating its possible variants. They are a core tool for modeling state and making illegal states unrepresentable. Oxide uses match with -> arms and _ as the wildcard.

What You'll Learn

• How to define enums and attach data to variants
• How to use match to branch on variants
• How to write concise control flow with if let

A Quick Example

public enum Message {
    Quit,
    Move { x: Int, y: Int },
    Write(String),
}

fn describe(msg: Message): String {
    match msg {
        Message.Quit -> "Quit message",
        Message.Move { x, y } -> "Move to \(x), \(y)",
        Message.Write(text) -> "Text: \(text)",
        _ -> "Unknown message",
    }
}

In the following sections, you'll see how enums and pattern matching work together to express rich, safe control flow.

Defining an Enum

Enums allow you to define a type by enumerating its possible variants. Where structs give you a way of grouping together related fields and data, enums give you a way of saying a value is one of a possible set of values. For example, we may want to say that Shape is one of a set of possible shapes that also includes Circle and Triangle. Oxide lets us express these possibilities as an enum.

Let's look at a situation we might want to express in code and see why enums are useful and more appropriate than structs in this case. Say we need to work with IP addresses. Currently, two major standards are used for IP addresses: version four and version six. Because these are the only possibilities for an IP address that our program will come across, we can enumerate all possible variants, which is where enumeration gets its name.

Any IP address can be either a version four or a version six address, but not both at the same time. That property of IP addresses makes the enum data structure appropriate because an enum value can only be one of its variants. Both version four and version six addresses are still fundamentally IP addresses, so they should be treated as the same type when the code is handling situations that apply to any kind of IP address.

We can express this concept in code by defining an IpAddrKind enumeration and listing the possible kinds an IP address can be, V4 and V6. These are the variants of the enum:

enum IpAddrKind {
    V4,
    V6,
}

IpAddrKind is now a custom data type that we can use elsewhere in our code.

Enum Values

We can create instances of each of the two variants of IpAddrKind like this:

let four = IpAddrKind.V4
let six = IpAddrKind.V6

Note that the variants of the enum are namespaced under its identifier using dot notation: IpAddrKind.V4 and IpAddrKind.V6. This is useful because now both values are of the same type: IpAddrKind. We can then, for instance, define a function that takes any IpAddrKind:

fn route(ipKind: IpAddrKind) {
    // handle routing
}

And we can call this function with either variant:

route(IpAddrKind.V4)
route(IpAddrKind.V6)

Using enums has even more advantages. Thinking more about our IP address type, at the moment we don't have a way to store the actual IP address data; we only know what kind it is. Given that you just learned about structs, you might be tempted to tackle this problem with structs:

enum IpAddrKind {
    V4,
    V6,
}

struct IpAddr {
    kind: IpAddrKind,
    address: String,
}

let home = IpAddr {
    kind: IpAddrKind.V4,
    address: "127.0.0.1".toString(),
}

let loopback = IpAddr {
    kind: IpAddrKind.V6,
    address: "::1".toString(),
}

Here, we've defined a struct IpAddr that has two fields: a kind field that is of type IpAddrKind (the enum we defined previously) and an address field of type String. We have two instances of this struct.

However, representing the same concept using just an enum is more concise: rather than an enum inside a struct, we can put data directly into each enum variant. This new definition of the IpAddr enum says that both V4 and V6 variants will have associated String values:

enum IpAddr {
    V4(String),
    V6(String),
}

let home = IpAddr.V4("127.0.0.1".toString())
let loopback = IpAddr.V6("::1".toString())

We attach data to each variant of the enum directly, so there is no need for an extra struct. Here, it's also easier to see another detail of how enums work: the name of each enum variant that we define also becomes a function that constructs an instance of the enum. That is, IpAddr.V4() is a function call that takes a String argument and returns an instance of the IpAddr type.

There's another advantage to using an enum rather than a struct: each variant can have different types and amounts of associated data. Version four IP addresses will always have four numeric components that will have values between 0 and 255. If we wanted to store V4 addresses as four UInt8 values but still express V6 addresses as one String value, we wouldn't be able to with a struct. Enums handle this case with ease:

enum IpAddr {
    V4(UInt8, UInt8, UInt8, UInt8),
    V6(String),
}

let home = IpAddr.V4(127, 0, 0, 1)
let loopback = IpAddr.V6("::1".toString())

We've shown several different ways to define data structures to store version four and version six IP addresses. However, as it turns out, wanting to store IP addresses and encode which kind they are is so common that the standard library has a definition we can use! Let's look at how the standard library defines IpAddr: it has the exact enum and variants that we've defined and used, but it embeds the address data inside the variants in the form of two different structs, which are defined differently for each variant.

Enums with Named Fields

Enum variants can also have named fields, similar to structs:

#[derive(Debug, Clone)]
public enum Message {
    Quit,
    Move { x: Int, y: Int },
    Write(String),
    ChangeColor(Int, Int, Int),
}

This enum has four variants with different types:

• Quit has no data associated with it at all.
• Move has named fields, like a struct.
• Write includes a single String.
• ChangeColor includes three Int values.

Defining an enum with variants such as the ones above is similar to defining different kinds of struct definitions, except the enum doesn't use the struct keyword and all the variants are grouped together under the Message type.

Creating instances of these variants:

let quit = Message.Quit
let moveMsg = Message.Move { x: 10, y: 20 }
let write = Message.Write("hello".toString())
let color = Message.ChangeColor(255, 128, 0)

Defining Methods on Enums

We're also able to define methods on enums using extension blocks. Here's a method named call that we could define on our Message enum:

extension Message {
    fn call() {
        match self {
            Message.Quit -> println!("Quit"),
            Message.Move { x, y } -> println!("Move to (\(x), \(y))"),
            Message.Write(text) -> println!("Write: \(text)"),
            Message.ChangeColor(r, g, b) -> println!("Color: (\(r), \(g), \(b))"),
        }
    }
}

let m = Message.Write("hello".toString())
m.call()

The body of the method uses self to get the value that we called the method on. In this example, we've created a variable m that has the value Message.Write("hello".toString()), and that is what self will be in the body of the call method when m.call() runs.

The Nullable Type: Using T? Instead of Option

Oxide provides a built-in way to express the concept of a value being present or absent using nullable types. Instead of writing Option<T> as you would in Rust, Oxide uses the more concise T? syntax. This is so common and useful that it's built into the language itself.

The nullable type encodes the very common scenario in which a value could be something or it could be nothing. For example, if you request the first item of a non-empty list, you would get a value. If you request the first item of an empty list, you would get nothing.

Expressing this concept in terms of the type system means the compiler can check whether you've handled all the cases you should be handling; this functionality can prevent bugs that are extremely common in other programming languages.

Here's how you use nullable types in Oxide:

let someNumber: Int? = Some(5)
let someString: String? = Some("a string".toString())

let absentNumber: Int? = null
let absentString: String? = null

The type of someNumber is Int?. The type of someString is String?. Because we've specified a type annotation, Oxide knows these are nullable types.

When we have a Some value, we know that a value is present and the value is held within the Some. When we have a null value, in some sense it means the same thing as null in other languages: we don't have a valid value.

So why is T? any better than having null? In short, because Int? and Int are different types, the compiler won't let us use an Int? value as if it were definitely an Int. For example, this code won't compile because it's trying to add an Int? to an Int:

let x: Int = 5
let y: Int? = Some(5)

let sum = x + y  // Error! Can't add Int and Int?

When we have a value of a type like Int in Oxide, the compiler will ensure we always have a valid value. We can proceed confidently without having to check for null before using that value. Only when we have a Int? do we have to worry about possibly not having a value, and the compiler will make sure we handle that case before using the value.

In other words, you have to convert a T? to a T before you can perform T operations with it. Generally, this helps catch one of the most common issues with null: assuming that something isn't null when it actually is.

Eliminating the risk of incorrectly assuming a not-null value helps you to be more confident in your code. In order to have a value that can possibly be null, you must explicitly opt in by making the type of that value T?. Then, when you use that value, you are required to explicitly handle the case when the value is null. Everywhere that a value has a type that isn't a T?, you can safely assume that the value isn't null.

So how do you get the T value out of a Some variant when you have a value of type T? so that you can use that value? The T? type has a large number of methods that are useful in a variety of situations; you can find them in the Rust documentation for Option<T>. Becoming familiar with the methods on Option<T> will be extremely useful in your journey with Oxide.

In general, in order to use a T? value, you want to have code that will handle each variant. You want some code that will run only when you have a Some(T) value, and this code is allowed to use the inner T. You want some other code to run only if you have a null value, and that code doesn't have a T value available. The match expression is a control flow construct that does just this when used with enums: it will run different code depending on which variant of the enum it has, and that code can use the data inside the matching variant.

The match Expression

Oxide has an extremely powerful control flow construct called match that allows you to compare a value against a series of patterns and then execute code based on which pattern matches. Patterns can be made up of literal values, variable names, wildcards, and many other things. The power of match comes from the expressiveness of the patterns and the fact that the compiler confirms that all possible cases are handled.

Think of a match expression as being like a coin-sorting machine: coins slide down a track with variously sized holes along it, and each coin falls through the first hole it encounters that it fits into. In the same way, values go through each pattern in a match, and at the first pattern the value "fits," the value falls into the associated code block to be used during execution.

Speaking of coins, let's use them as an example using match! We can write a function that takes an unknown US coin and, in a similar way as the counting machine, determines which coin it is and returns its value in cents:

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn valueInCents(coin: Coin): Int {
    match coin {
        Coin.Penny -> 1,
        Coin.Nickel -> 5,
        Coin.Dime -> 10,
        Coin.Quarter -> 25,
    }
}

Let's break down the match in the valueInCents function. First we list the match keyword followed by an expression, which in this case is the value coin. This seems very similar to a conditional expression used with if, but there's a big difference: with if, the condition needs to evaluate to a Boolean value, but here it can be any type. The type of coin in this example is the Coin enum that we defined.

Next are the match arms. An arm has two parts: a pattern and some code. The first arm here has a pattern that is the value Coin.Penny and then the -> that separates the pattern and the code to run. The code in this case is just the value 1. Each arm is separated from the next with a comma.

When the match expression executes, it compares the resultant value against the pattern of each arm, in order. If a pattern matches the value, the code associated with that pattern is executed. If that pattern doesn't match the value, execution continues to the next arm, much as in a coin-sorting machine.

The code associated with each arm is an expression, and the resultant value of the expression in the matching arm is the value that gets returned for the entire match expression.

We don't typically use curly brackets if the match arm code is short, as it is in the previous example where each arm just returns a value. If you want to run multiple lines of code in a match arm, you must use curly brackets, and the comma following the arm is then optional:

fn valueInCents(coin: Coin): Int {
    match coin {
        Coin.Penny -> {
            println!("Lucky penny!")
            1
        },
        Coin.Nickel -> 5,
        Coin.Dime -> 10,
        Coin.Quarter -> 25,
    }
}

Patterns That Bind to Values

Another useful feature of match arms is that they can bind to the parts of the values that match the pattern. This is how we can extract values out of enum variants.

As an example, let's change one of our enum variants to hold data inside it. From 1999 through 2008, the United States minted quarters with different designs for each of the 50 states on one side. No other coins got state designs, so only quarters have this extra value. We can add this information to our enum by changing the Quarter variant to include a UsState value stored inside it:

#[derive(Debug, Clone, Copy)]
enum UsState {
    Alabama,
    Alaska,
    Arizona,
    Arkansas,
    California,
    // ... etc
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

Let's imagine that a friend is trying to collect all 50 state quarters. While we sort our loose change by coin type, we'll also call out the name of the state associated with each quarter so that if it's one our friend doesn't have, they can add it to their collection.

In the match expression for this code, we add a variable called state to the pattern that matches values of the variant Coin.Quarter. When a Coin.Quarter matches, the state variable will bind to the value of that quarter's state. Then we can use state in the code for that arm:

fn valueInCents(coin: Coin): Int {
    match coin {
        Coin.Penny -> 1,
        Coin.Nickel -> 5,
        Coin.Dime -> 10,
        Coin.Quarter(state) -> {
            println!("State quarter from \(state:?)")
            25
        },
    }
}

If we were to call valueInCents(Coin.Quarter(UsState.Alaska)), coin would be Coin.Quarter(UsState.Alaska). When we compare that value with each of the match arms, none of them match until we reach Coin.Quarter(state). At that point, the binding for state will be the value UsState.Alaska. We can then use that binding in the println! expression, thus getting the inner state value out of the Coin enum variant for Quarter.

Matching with Nullable Types

In the previous section, we wanted to get the inner T value out of the Some case when using T?; we can also handle T? using match, as we did with the Coin enum! Instead of comparing coins, we'll compare the variants of T?, but the way the match expression works remains the same.

Let's say we want to write a function that takes a Int? and, if there's a value inside, adds 1 to that value. If there isn't a value inside, the function should return the null value and not attempt to perform any operations.

This function is very easy to write, thanks to match:

fn plusOne(x: Int?): Int? {
    match x {
        null -> null,
        Some(i) -> Some(i + 1),
    }
}

let five: Int? = Some(5)
let six = plusOne(five)
let none = plusOne(null)

Let's examine the first execution of plusOne in more detail. When we call plusOne(five), the variable x in the body of plusOne will have the value Some(5). We then compare that against each match arm:

null -> null,

The Some(5) value doesn't match the pattern null, so we continue to the next arm:

Some(i) -> Some(i + 1),

Does Some(5) match Some(i)? It does! We have the same variant. The i binds to the value contained in Some, so i takes the value 5. The code in the match arm is then executed, so we add 1 to the value of i and create a new Some value with our total 6 inside.

Now let's consider the second call of plusOne, where x is null. We enter the match and compare to the first arm:

null -> null,

It matches! There's no value to add to, so the program stops and returns the null value on the right side of ->. Because the first arm matched, no other arms are compared.

Combining match and enums is useful in many situations. You'll see this pattern a lot in Oxide code: match against an enum, bind a variable to the data inside, and then execute code based on it. It's a bit tricky at first, but once you get used to it, you'll wish you had it in all languages. It's consistently a user favorite.

Matches Are Exhaustive

There's one other aspect of match we need to discuss: the arms' patterns must cover all possibilities. Consider this version of our plusOne function, which has a bug and won't compile:

fn plusOne(x: Int?): Int? {
    match x {
        Some(i) -> Some(i + 1),
    }
}

We didn't handle the null case, so this code will cause a bug. Luckily, it's a bug the compiler knows how to catch. If we try to compile this code, we'll get an error indicating that we haven't handled all possible cases.

Matches in Oxide are exhaustive: we must exhaust every last possibility in order for the code to be valid. Especially in the case of T?, when the compiler ensures we explicitly handle the null case, it protects us from assuming we have a value when we might have null, thus making the mistake discussed earlier impossible.

Catch-all Patterns with _

Using enums, we can also take special actions for a few particular values, but for all other values take one default action. Let's look at an example where we want to implement game logic for a dice roll:

fn handleDiceRoll(diceRoll: Int) {
    match diceRoll {
        3 -> addFancyHat(),
        7 -> removeFancyHat(),
        _ -> reroll(),
    }
}

fn addFancyHat() {}
fn removeFancyHat() {}
fn reroll() {}

For the first two arms, the patterns are the literal values 3 and 7. For the last arm that covers every other possible value, the pattern is the wildcard _. The code that runs for the wildcard arm calls the reroll function.

This code compiles, even though we haven't listed all the possible values an Int can have, because the _ pattern will match all values not specifically listed. The catch-all pattern meets the requirement that match must be exhaustive. Note that we have to put the catch-all arm last because the patterns are evaluated in order. If we put the catch-all arm earlier, the other arms would never run.

Catch-all with a Bound Variable

Sometimes you want to use the matched value in your catch-all arm. You can bind the value to a variable by using a name other than _:

fn handleDiceRoll(diceRoll: Int) {
    match diceRoll {
        3 -> addFancyHat(),
        7 -> removeFancyHat(),
        other -> movePlayer(other),
    }
}

fn movePlayer(spaces: Int) {
    println!("Moving \(spaces) spaces")
}

Here, we're using the variable other to capture all values that don't match 3 or 7, and we use that value in the arm's code.

Ignoring Values with _

When you want a catch-all but don't need the value, use _:

fn handleDiceRoll(diceRoll: Int) {
    match diceRoll {
        3 -> addFancyHat(),
        7 -> removeFancyHat(),
        _ -> {},  // Do nothing
    }
}

Here, we're telling the compiler explicitly that we aren't going to use any other value, by using _ with an empty block.

Matching Multiple Patterns

You can match multiple patterns in a single arm using the | operator:

fn describeLetter(letter: char): String {
    match letter {
        'a' | 'e' | 'i' | 'o' | 'u' -> "vowel".toString(),
        'a'..='z' -> "consonant".toString(),
        _ -> "not a lowercase letter".toString(),
    }
}

Matching with Guards

Sometimes pattern matching alone isn't expressive enough. Match guards allow you to add an additional condition to a pattern:

fn checkNumber(x: Int?) {
    match x {
        Some(n) if n < 0 -> println!("Negative: \(n)"),
        Some(n) if n > 0 -> println!("Positive: \(n)"),
        Some(n) -> println!("Zero"),
        null -> println!("No value"),
    }
}

The if n < 0 part is called a match guard. It's an additional condition on a match arm that must also be true for that arm to be chosen. Match guards are useful for expressing more complex ideas than a pattern alone allows.

Destructuring Enums with Named Fields

When matching enums with named fields, you can destructure them using struct-like syntax:

enum Message {
    Quit,
    Move { x: Int, y: Int },
    Write(String),
    ChangeColor(Int, Int, Int),
}

fn processMessage(msg: Message) {
    match msg {
        Message.Quit -> {
            println!("Quit received")
        },
        Message.Move { x, y } -> {
            println!("Moving to x=\(x), y=\(y)")
        },
        Message.Write(text) -> {
            println!("Text message: \(text)")
        },
        Message.ChangeColor(r, g, b) -> {
            println!("Changing color to RGB(\(r), \(g), \(b))")
        },
    }
}

You can also rename the bound variables:

match msg {
    Message.Move { x: horizontal, y: vertical } -> {
        println!("Moving horizontally: \(horizontal), vertically: \(vertical)")
    },
    _ -> {},
}

Nested Patterns

Patterns can be nested to match complex data structures:

enum Color {
    Rgb(Int, Int, Int),
    Hsv(Int, Int, Int),
}

enum Message {
    Quit,
    ChangeColor(Color),
}

fn processMessage(msg: Message) {
    match msg {
        Message.ChangeColor(Color.Rgb(r, g, b)) -> {
            println!("RGB: \(r), \(g), \(b)")
        },
        Message.ChangeColor(Color.Hsv(h, s, v)) -> {
            println!("HSV: \(h), \(s), \(v)")
        },
        Message.Quit -> println!("Quit"),
    }
}

The match expression is one of Oxide's most powerful features. It's used extensively throughout Oxide code for control flow, error handling, and working with optional values. As you become more familiar with pattern matching, you'll find yourself reaching for match whenever you need to handle multiple cases based on the structure of your data.

if let and while let

The if let syntax lets you combine if and let into a less verbose way to handle values that match one pattern while ignoring the rest. Consider the following program that matches on a Int? value in the configMax variable but only wants to execute code if the value is a Some variant:

let configMax: Int? = 3

match configMax {
    Some(max) -> println!("The maximum is configured to be \(max)"),
    null -> {},
}

If the value is Some, we print out the value in the Some variant by binding the value to the variable max in the pattern. We don't want to do anything with the null value. To satisfy the match expression, we have to add null -> {} after processing just one variant, which is annoying boilerplate code to add.

Instead, we could write this in a shorter way using if let. The following code behaves the same as the match above:

let configMax: Int? = 3

if let Some(max) = configMax {
    println!("The maximum is configured to be \(max)")
}

The syntax if let takes a pattern and an expression separated by an equal sign. It works the same way as a match, where the expression is given to the match and the pattern is its first arm. In this case, the pattern is Some(max), and the max binds to the value inside the Some. We can then use max in the body of the if let block in the same way we used max in the corresponding match arm. The code in the if let block isn't run if the value doesn't match the pattern.

Using if let means less typing, less indentation, and less boilerplate code. However, you lose the exhaustive checking that match enforces. Choosing between match and if let depends on what you're doing in your particular situation and whether gaining conciseness is an appropriate trade-off for losing exhaustive checking.

In other words, you can think of if let as syntax sugar for a match that runs code when the value matches one pattern and then ignores all other values.

Auto-Unwrapping for Nullable Types

Oxide provides a powerful feature for working with nullable types: automatic unwrapping in if let expressions. When the right-hand side of an if let is a nullable type (T?), you don't need to explicitly write Some(...) in your pattern. Oxide will automatically unwrap the value for you.

Consider this code:

let maybeUser: User? = findUser(id)

// Traditional way with explicit Some
if let Some(user) = maybeUser {
    println!("Hello, \(user.name)")
}

// Oxide auto-unwrap - simpler and more readable
if let user = maybeUser {
    println!("Hello, \(user.name)")
}

Both forms are equivalent and compile to the same code. The auto-unwrap syntax (if let user = maybeUser) is more concise and reads naturally: "if there's a user, use it."

This is particularly useful when working with function return values:

fn findUserById(id: Int): User? {
    // ... lookup logic
    null
}

fn processUser(id: Int) {
    if let user = findUserById(id) {
        println!("Found user: \(user.name)")
        sendWelcomeEmail(user)
    }
}

The auto-unwrap also works with chained method calls:

if let email = user.profile?.email {
    sendNotification(email)
}

Using else with if let

We can include an else with an if let. The block of code that goes with the else is the same as the block of code that would go with the null case in the match expression:

let coin = Coin.Quarter(UsState.Alaska)

if let Coin.Quarter(state) = coin {
    println!("State quarter from \(state:?)")
} else {
    println!("Not a quarter")
}

This is equivalent to:

match coin {
    Coin.Quarter(state) -> println!("State quarter from \(state:?)"),
    _ -> println!("Not a quarter"),
}

Combining if let with else if

You can chain if let expressions with else if and else if let:

fn describeValue(value: Int?) {
    if let n = value {
        if n > 100 {
            println!("Large number: \(n)")
        } else if n > 0 {
            println!("Positive number: \(n)")
        } else if n < 0 {
            println!("Negative number: \(n)")
        } else {
            println!("Zero")
        }
    } else {
        println!("No value")
    }
}

Or matching against multiple nullable types:

fn processCoordinates(x: Int?, y: Int?) {
    if let xVal = x {
        if let yVal = y {
            println!("Point: (\(xVal), \(yVal))")
        } else {
            println!("Only X coordinate: \(xVal)")
        }
    } else if let yVal = y {
        println!("Only Y coordinate: \(yVal)")
    } else {
        println!("No coordinates")
    }
}

if let with Conditions

You can combine if let with additional conditions using &&:

let user: User? = findUser(id)

if let user = user && user.isActive {
    greet(user)
}

This is equivalent to:

if let Some(user) = user {
    if user.isActive {
        greet(user)
    }
}

The combined syntax is more concise and clearly expresses the intent: "if we have a user AND they are active, greet them."

while let

Similar to if let, Oxide provides while let for looping as long as a pattern continues to match. This is particularly useful when working with iterators or any sequence that returns nullable values.

var stack: Vec<Int> = vec![1, 2, 3]

while let Some(top) = stack.pop() {
    println!("Popped: \(top)")
}

This code pops values from the stack and prints them until the stack is empty. The pop method returns Int?, returning Some(value) when there's a value and null when the stack is empty.

With auto-unwrap syntax:

var stack: Vec<Int> = vec![1, 2, 3]

while let top = stack.pop() {
    println!("Popped: \(top)")
}

Practical Examples

Working with Configuration

struct Config {
    databaseUrl: String?,
    maxConnections: Int?,
    timeout: Int?,
}

fn loadConfig(): Config {
    Config {
        databaseUrl: Some("postgres://localhost/db".toString()),
        maxConnections: Some(10),
        timeout: null,
    }
}

fn initializeDatabase() {
    let config = loadConfig()

    if let url = config.databaseUrl {
        println!("Connecting to: \(url)")

        let connections = config.maxConnections ?? 5
        println!("Max connections: \(connections)")

        if let timeout = config.timeout {
            println!("Timeout: \(timeout)s")
        } else {
            println!("No timeout configured, using default")
        }
    } else {
        println!("No database URL configured!")
    }
}

Processing Results from a Search

struct SearchResult {
    title: String,
    url: String,
    snippet: String?,
}

fn search(query: &str): SearchResult? {
    // ... search logic
    Some(SearchResult {
        title: "Example".toString(),
        url: "https://example.com".toString(),
        snippet: Some("An example result".toString()),
    })
}

fn displaySearchResult(query: &str) {
    if let result = search(query) {
        println!("Found: \(result.title)")
        println!("URL: \(result.url)")

        if let snippet = result.snippet {
            println!("Snippet: \(snippet)")
        }
    } else {
        println!("No results found for '\(query)'")
    }
}

Iterating with while let

struct Node {
    value: Int,
    next: Box<Node>?,
}

fn sumLinkedList(head: Box<Node>?): Int {
    var sum = 0
    var current = head

    while let node = current {
        sum += node.value
        current = node.next.clone()
    }

    sum
}

Handling User Input

fn readValidNumber(): Int? {
    // Simulating user input
    Some(42)
}

fn processInput() {
    while let number = readValidNumber() {
        if number == 0 {
            println!("Exiting...")
            break
        }
        println!("Processing: \(number)")
    }
}

When to Use if let vs match

Use if let when:

• You only care about one specific pattern
• You want concise code for simple cases
• The "else" case is trivial or can be ignored

Use match when:

• You need to handle multiple patterns explicitly
• You want the compiler to ensure you've handled all cases
• The logic for different patterns is complex

// Good use of if let - only care about Some case
if let user = findUser(id) {
    greet(user)
}

// Good use of match - need to handle all cases explicitly
match command {
    Command.Start -> startServer(),
    Command.Stop -> stopServer(),
    Command.Restart -> {
        stopServer()
        startServer()
    },
    Command.Status -> printStatus(),
}

The if let and while let constructs provide a more ergonomic way to work with nullable types and pattern matching when you don't need the full power of match. Combined with Oxide's auto-unwrap feature for nullable types, they make working with optional values concise and readable.

Packages, Crates, and Modules

As your programs grow larger, you'll find it essential to organize your code into logical units. Oxide (like Rust) provides a powerful module system that lets you:

• Break your code into reusable pieces
• Keep related functionality together
• Control which parts of your code are public and which are private
• Avoid naming conflicts

In this chapter, we'll explore:

• Packages and crates: The containers for your code
• Modules: How to organize code within crates
• import statements: How to bring names into scope
• Visibility: Controlling what parts of your API are public

These features form the foundation of larger Oxide projects and libraries. Whether you're organizing a single crate or distributing code across multiple crates, mastering modules will make your code more maintainable and your intentions clearer.

Overview

Before diving into syntax, let's clarify the key concepts:

• Package: A Cargo feature that contains one or more crates
• Crate: A tree of modules that produces a library or executable
• Module: A way to organize code into logical hierarchies with control over privacy
• Path: A way to name an item in the module tree (e.g., restaurant.food.appetizers.Appetizer)

We'll start with packages and crates, then move to modules and visibility, and finally explore how to construct paths to access items.

Let's begin!

Packages and Crates

Packages and crates are closely related concepts, but they serve different purposes. Understanding the distinction is crucial for organizing larger Oxide projects.

What is a Crate?

A crate is the smallest amount of code that the Oxide compiler considers at a time. When you run oxc (the Oxide compiler), it treats the input as a single crate. Similarly, Cargo treats your project as a crate.

A crate can be in one of two forms:

• Binary crate: A standalone executable program
• Library crate: A collection of code meant to be used by other programs

Each crate has a root module that defines the structure of the entire crate:

• For binary crates: The root module is typically src/main.ox
• For library crates: The root module is typically src/lib.ox

When you compile a crate, the compiler starts at the root module and looks for code that needs to be compiled, including any code referenced through module declarations or imports.

What is a Package?

A package is one or more crates that work together. It contains a Cargo.toml file that describes how to build those crates.

A package can contain:

• At most one library crate: If present, it's named after the package
• Any number of binary crates: These are placed in src/bin/

Package Structure

Here's a typical package structure:

my_oxide_project/
├── Cargo.toml
├── src/
│   ├── main.ox       (binary crate root)
│   └── lib.ox        (library crate root)
└── src/bin/
    ├── tool1.ox      (another binary crate)
    └── tool2.ox      (another binary crate)

The Cargo.toml file at the package root is the manifest that describes the entire package.

Creating a Package

When you create a new package with Cargo, it automatically sets up the structure:

$ cargo new my_oxide_project
     Created binary (application) package

This creates:

my_oxide_project/
├── Cargo.toml
└── src/
    └── main.ox

The package name in Cargo.toml defaults to the directory name. This package contains only a binary crate (because of main.ox).

To create a package with a library crate, use the --lib flag:

$ cargo new --lib my_oxide_lib
     Created library package

This creates:

my_oxide_lib/
├── Cargo.toml
└── src/
    └── lib.ox

Binary and Library Crates in One Package

You can have both binary and library crates in a single package. For example:

$ cargo new my_oxide_project
$ cargo new --lib my_oxide_project  # This would overwrite, so instead:

Simply add a lib.ox file alongside your main.ox:

my_oxide_project/
├── Cargo.toml
├── src/
│   ├── lib.ox        (library crate)
│   └── main.ox       (binary crate)

Now you have both. The binary can import and use code from the library crate because they're in the same package.

Multiple Binary Crates

If you need multiple binary crates beyond the default main.ox, place them in src/bin/:

my_oxide_project/
├── Cargo.toml
├── src/
│   ├── lib.ox
│   └── main.ox       (default binary)
└── src/bin/
    ├── tool1.ox
    └── tool2.ox

Build a specific binary:

$ cargo build --bin tool1

Run a specific binary:

$ cargo run --bin tool2

Library Crates vs. Binary Crates

Library Crates

Use a library crate when you're building code meant to be used by other programs:

• Contains reusable functionality
• Has a lib.ox root
• Publishes code with public visibility for others to use
• Cannot be run directly with cargo run

Example: A math library that others can import and use in their projects.

Binary Crates

Use a binary crate for executable programs:

• Has a main.ox root with a main() function
• Typically uses code from library crates
• Can be run with cargo run
• Can be installed with cargo install

Example: A command-line tool that users can run.

Separating Concerns: bin and lib

A common pattern is to have both:

• lib.ox: Contains the core logic and reusable functionality
• main.ox: Contains the command-line interface or user-facing code

This separation makes testing easier and allows the library to be reused by other programs.

For example, a search tool might have:

// lib.ox - Core search logic (reusable)
public fn searchFiles(directory: &str, pattern: &str): Vec<String> {
    // Implementation
    []
}

// main.ox - CLI interface
import lib

fn main() {
    let args = getCommandLineArgs()
    let results = lib.searchFiles(args[0], args[1])
    for result in results {
        println!("\(result)")
    }
}

Other programs can import and use searchFiles from the library, while the binary provides a command-line interface.

Rust Comparison

In Rust:

• The default root module for a binary is src/main.rs
• The default root module for a library is src/lib.rs
• Binary files in src/bin/ follow the same pattern
• Package structure is identical to Oxide

The main difference is file extensions (.rs vs .ox) and Oxide's syntax for imports and visibility.

Summary

• Crates are the unit of compilation, either binary or library
• Packages contain crates and are managed with Cargo.toml
• Binary crates have main.ox and can be executed
• Library crates have lib.ox and provide reusable code
• Multiple binaries go in src/bin/
• Separating core logic in lib.ox and interface in main.ox is a best practice

Now that you understand packages and crates, let's explore how to organize code within a crate using modules.

Defining and Organizing Modules

Modules allow you to organize code within a crate into logical, hierarchical groups. They provide a namespace for your code and allow you to control what's public and what's private.

Module Basics

A module is declared with the module keyword (not mod as in Rust). It creates a namespace that can contain functions, structs, traits, and other items:

module restaurant {
    fn prepareFood() {
        println!("Preparing food")
    }
}

fn main() {
    restaurant.prepareFood()
}

In this example, prepareFood is defined inside the restaurant module and accessed using dot notation: restaurant.prepareFood().

Nested Modules

Modules can be nested inside other modules, creating a hierarchy:

module restaurant {
    module food {
        module appetizers {
            public fn bruschetta() {
                println!("Making bruschetta")
            }
        }

        module mains {
            public fn pasta() {
                println!("Making pasta")
            }
        }
    }

    module house {
        fn greet() {
            println!("Welcome!")
        }
    }
}

fn main() {
    restaurant.food.appetizers.bruschetta()
    restaurant.food.mains.pasta()
}

Paths use dot notation, just like accessing nested objects or properties in other languages.

Module Organization Conventions

While Oxide allows you to nest modules deeply, it's often clearer to organize them in files:

Single-File Organization

For small projects, keep everything in src/main.ox or src/lib.ox:

// src/main.ox
module restaurant {
    module food {
        public fn appetizer() { }
        public fn mainCourse() { }
    }

    module house {
        public fn greet() { }
    }
}

fn main() {
    restaurant.food.appetizer()
}

Multi-File Organization

For larger projects, split modules into separate files. The conventional approach is:

src/
├── lib.ox           (declares modules, defines some items)
├── restaurant.ox    (or restaurant/mod.ox)
└── restaurant/
    ├── food.ox
    ├── house.ox
    └── payment.ox

In src/lib.ox:

external module restaurant

The external module keyword tells Oxide that the module is defined in an external file, not inline.

In src/restaurant.ox (or src/restaurant/mod.ox):

public module food {
    public fn appetizer() {
        println!("Appetizer")
    }
}

public module house {
    public fn greet() {
        println!("Welcome")
    }
}

In src/restaurant/food.ox:

public fn appetizer() {
    println!("Appetizer served")
}

public fn dessert() {
    println!("Dessert served")
}

Then import and use:

import restaurant.food

fn main() {
    food.appetizer()
}

File Naming and Location

When you declare external module foo, Oxide looks for:

1. A file named foo.ox in the same directory, or
2. A directory named foo/ with a mod.ox file inside

For nested modules, you can either:

Option 1: Inline with dots

external module restaurant.food.appetizers

Option 2: Nested directories

src/
├── restaurant.ox
└── restaurant/
    ├── food.ox
    └── food/
        ├── appetizers.ox

Both approaches work. Choose the one that feels most natural for your project structure.

Public and Private Items

By default, all items in a module are private:

module restaurant {
    fn secret() {
        println!("Secret recipe")
    }
}

fn main() {
    restaurant.secret()  // Error: secret is private
}

Use the public keyword to make items available outside the module:

public module restaurant {
    public fn greeting() {
        println!("Welcome!")
    }

    fn secret() {
        println!("Secret recipe")  // Private, not accessible from outside
    }
}

fn main() {
    restaurant.greeting()  // OK
    restaurant.secret()    // Error: private
}

Note: A module can be public at the declaration, but items inside it are still private by default:

public module restaurant {
    // This module itself is public
    fn secret() { }        // But this item is private
    public fn welcome() { } // This item is public
}

Re-exporting with public import

Sometimes you want to reorganize your internal module structure without breaking the public API. Use public import to re-export items:

// src/lib.ox
external module internals

public import internals.helpers.createMessage

// Now users can do:
// import myLib.createMessage
// Instead of:
// import myLib.internals.helpers.createMessage

This is useful for:

• Simplifying the public API
• Reorganizing internal code without breaking user code
• Grouping related functionality under a simple name

Privacy Rules

Oxide's privacy model is hierarchical:

1. Private by default: Items are private unless marked public
2. Public items only at boundaries: You can only make items public that are directly in a public module
3. Public all the way down: To access a deeply nested public item, all parent modules must also be public

Example:

module restaurant {                    // Private module (default)
    public module food {               // Public submodule
        public fn appetizer() { }      // Public function
    }
}

// In another file:
import restaurant.food.appetizer      // Error! restaurant is private
// The rule: parent must be public too

To fix:

public module restaurant {             // Make parent public
    public module food {
        public fn appetizer() { }
    }
}

// Now it works!
import restaurant.food.appetizer

Best Practices

1. Use Modules to Group Related Functionality

public module httpServer {
    public module handlers {
        public fn handleRequest() { }
        public fn handleError() { }
    }

    public module middleware {
        public fn logRequest() { }
        public fn validateAuth() { }
    }
}

2. Keep Public APIs Simple

Use public import to flatten your public interface:

// Organize internally
external module internals.utils
external module internals.validators

// Expose cleanly
public import internals.utils.createConfig
public import internals.validators.validateInput

3. Use Consistent Naming

Module names should be descriptive but concise:

// Good
public module user_management { }
public module payment { }
public module notifications { }

// Avoid overly nested or redundant names
public module users.user_management.user_utils { }

Comparison with Rust

In Rust:

• Modules are declared with mod, not module
• External modules are declared with mod foo; (with semicolon)
• File organization is similar but uses .rs extension
• Snake_case is used for module names (Oxide follows the same convention)

Oxide syntax:

• module foo { } for inline modules
• external module foo for file-based modules
• Dot notation for paths instead of :: or ::
• snake_case for module names by convention

Summary

• Modules organize code into hierarchical namespaces
• Inline modules are defined with module keyword
• External modules are file-based and declared with external module
• Public modules and items use the public keyword
• Privacy is hierarchical: parent modules must be public to access nested public items
• Dot notation accesses paths: restaurant.food.appetizers
• public import re-exports items to simplify the public API

Now that you understand how to organize code with modules, let's explore how to bring those items into scope with import statements.

Paths for Referring to Items in the Module Tree

A path is a way to refer to an item in the module tree. Paths can take two forms: absolute and relative.

Absolute Paths

An absolute path starts from the crate root and uses the full path to an item:

public module restaurant {
    public module food {
        public module appetizers {
            public fn bruschetta() {
                println!("Making bruschetta")
            }
        }
    }
}

fn main() {
    // Absolute path
    restaurant.food.appetizers.bruschetta()
}

This is the most explicit and clear form. It tells readers exactly where the item comes from.

Relative Paths

A relative path starts from the current module and builds from there. You can reference items without writing the full path:

module restaurant {
    module food {
        public fn appetizer() {
            println!("Appetizer")
        }

        public fn describe() {
            // Relative path - within the same module
            appetizer()
        }
    }

    module house {
        fn greet() {
            // This won't work - food is a sibling, not parent
            // food.appetizer()  // Error!
        }
    }
}

Within a module, you can call other items in the same module directly. However, sibling modules require you to use their full name relative to a common parent.

Understanding the Module Hierarchy

Think of the module tree like a filesystem:

crate_root
├── restaurant          (module)
│   ├── food           (module)
│   │   ├── appetizers (module)
│   │   │   └── bruschetta (function)
│   │   └── mains      (module)
│   │       └── pasta  (function)
│   └── house          (module)
│       └── greet      (function)
└── main               (function)

To access an item, you navigate this tree. For example:

• restaurant.food.appetizers.bruschetta - Start at root, go to restaurant, then food, then appetizers, then call bruschetta
• restaurant.house.greet - Start at root, go to restaurant, then house, then call greet

Public vs. Private in Paths

Paths work only for public items. If an item or any parent module is private, you can't access it from outside:

module restaurant {                  // Private (not marked public)
    public fn greeting() { }
}

fn main() {
    restaurant.greeting()  // Error! restaurant is private
}

To fix:

public module restaurant {           // Make parent public
    public fn greeting() { }
}

fn main() {
    restaurant.greeting()  // OK
}

This is the public visibility rule: all ancestors in the path must be public for you to access an item.

Paths in Imports

When you import, you're creating a new name binding using a path:

import restaurant.food.appetizers as starters

fn main() {
    starters.bruschetta()  // starters is the imported name
}

The import statement says: "Follow the path restaurant.food.appetizers and bind the result to the name starters."

Paths with Generics and Complex Types

When dealing with generic types or trait objects, paths can include type information:

import std.collections.HashMap

fn main() {
    // HashMap is a path referring to a generic type
    let map: HashMap[String, Int] = HashMap()
}

The path std.collections.HashMap refers to the type itself, which can be instantiated with type arguments.

Documenting Paths

When you document your code, include paths in comments and doc comments:

/// Represents a restaurant's menu.
///
/// The `Restaurant` struct is found at `restaurant.Restaurant`.
/// To add items, use the `addItem` method from `restaurant.menu.Menu`.
public struct Restaurant {
    name: String,
}

This helps users understand how to navigate your module structure.

Common Path Patterns

Pattern 1: Accessing Sibling Modules

module server {
    module http {
        fn handleRequest() { }
    }

    module websocket {
        fn handleConnection() {
            // To call sibling module, use full path from parent
            http.handleRequest()  // This won't work!
            // Instead:
        }
    }
}

From within websocket, you need to reference http as a sibling. The safest approach is to use the full path:

module server {
    module http {
        public fn handleRequest() { }
    }

    module websocket {
        fn handleConnection() {
            // Use the full path (but this requires http to be public)
            server.http.handleRequest()
        }
    }
}

Or more simply, within the same crate, you can use the parent module:

public module server {
    public module http {
        public fn handleRequest() { }
    }

    public module websocket {
        fn handleConnection() {
            // Within the same public parent, access via dot notation
            http.handleRequest()  // This works within the server module
        }
    }
}

Pattern 2: Accessing Parent Items

public module restaurant {
    public module kitchen {
        fn cook() {
            // You can't easily reference parent items
            // Instead, structure code to avoid this need
        }
    }

    public fn announceReady() {
        println!("Food is ready!")
    }
}

fn main() {
    // You access via the full path
    restaurant.announceReady()
}

If you need parent functionality in a child module, consider:

1. Passing it as a parameter
2. Creating a shared utility module
3. Restructuring to avoid the parent dependency

Pattern 3: Items in the Same Module

public module restaurant {
    public fn appetizer() {
        println!("Appetizer")
    }

    public fn mainCourse() {
        // Within the same module, call directly
        appetizer()  // This works
    }
}

Re-exports and Path Visibility

When you re-export an item, you create an alternative path to it:

// src/lib.ox
external module internals

public import internals.helpers.createMessage

// Now there are two paths to the same item:
// 1. internals.helpers.createMessage (private, internal only)
// 2. createMessage (public, preferred)

Users see the shorter path, while your internal structure remains hidden.

Full Paths in Error Messages

When the compiler reports an error, it uses paths to tell you about items:

error: cannot find function `bruschetta` in module `restaurant::food::appetizers`
 --> main.ox:3:5
  |
3 |     bruschetta()
  |     ^^^^^^^^^^ not found in this scope
  |
help: consider using the full path with the item's type
  |
3 |     restaurant.food.appetizers.bruschetta()
  |     ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The compiler shows the full path and suggests how to fix it.

Comparison with Rust

In Rust:

• Absolute paths start with crate::
• Relative paths use self:: or super::
• Paths use :: not .
• You can use super to reference parent modules

Rust example:

#![allow(unused)]
fn main() {
// Absolute path
crate::restaurant::food::appetizers::bruschetta();

// Relative path with super
super::other_module::do_something();

use crate::restaurant::food::appetizers as starters;
}

Oxide equivalent:

// Absolute path
restaurant.food.appetizers.bruschetta()

// Relative path (within same module)
otherModule.doSomething()

import restaurant.food.appetizers as starters

Oxide's simpler path syntax (no ::, crate::, or super::) makes navigation more intuitive, especially for those familiar with object-oriented languages.

Summary

• Paths refer to items in the module tree using dot notation
• Absolute paths start from the crate root
• Relative paths navigate from the current module
• Privacy rules: all ancestors in a path must be public
• Paths are clear: they explicitly show where items come from
• Importing creates shorter names for paths
• Re-exports create alternative paths to the same items
• Oxide uses simple dot notation, unlike Rust's :: syntax

Now that you understand paths, let's look at practical file organization strategies.

Import Statements and Bringing Names Into Scope

Once you've organized your code into modules, you need a way to bring those items into scope so you can use them without always writing the full path. This is where import statements come in.

Basic Import

The simplest form of an import brings an item directly into scope:

import restaurant.food.appetizers

fn main() {
    appetizers.bruschetta()  // Can use appetizers without the full path
}

Without the import, you'd need to write:

fn main() {
    restaurant.food.appetizers.bruschetta()  // Full path
}

Importing Specific Items

Import a single function or struct directly:

import restaurant.food.appetizers.bruschetta

fn main() {
    bruschetta()  // No prefix needed
}

This brings just bruschetta into scope.

Importing Multiple Items

Import multiple items from the same module using braces:

import restaurant.food.appetizers.{bruschetta, calamari, soup}

fn main() {
    bruschetta()
    calamari()
    soup()
}

Importing an Entire Module

Import a module and access its contents with dot notation:

import restaurant.food

fn main() {
    food.appetizers.bruschetta()
    food.mains.pasta()
    food.desserts.tiramisu()
}

Nested Imports

You can nest imports to bring multiple modules from a parent:

import restaurant.{food, payment, house}

fn main() {
    food.appetizer()      // Via imported module
    payment.process()     // Via imported module
    house.greet()         // Via imported module
}

This is equivalent to:

import restaurant.food
import restaurant.payment
import restaurant.house

Wildcard Imports

Import everything from a module using *:

import restaurant.food.*

fn main() {
    appetizers.bruschetta()
    mains.pasta()
}

Note: While wildcard imports are convenient, they can make code harder to read because it's not clear where appetizers comes from. Use them sparingly and mainly in tests or small scopes.

Renaming Imports

If two modules export items with the same name, or if you just prefer a different name, use as to rename:

import restaurant.food.appetizers as starters

fn main() {
    starters.bruschetta()
}

Multiple renames in one import:

import restaurant.{
    food.appetizers as starters,
    payment.creditCard as cardPayment,
}

fn main() {
    starters.bruschetta()
    cardPayment.process()
}

Relative Paths

Within the same file or module, you can use relative paths:

module restaurant {
    module food {
        public fn appetizer() { }
    }

    module house {
        fn greet() {
            // Access sibling module using dot notation
            let name = "appetizer"
            // Can access food.appetizer() here
            food.appetizer()
        }
    }
}

Importing from External Crates

If your project depends on other crates, import from them using the crate name:

# In Cargo.toml
[dependencies]
serde = "1.0"

import serde.json  // Import from the serde crate

fn main() {
    let data = json.parse("{\"key\": \"value\"}")
}

Import Styles

There are several valid import styles. Choose the one that makes sense for your code:

Style 1: Import Functions Directly

Use when you call the function many times:

import myLib.math.fibonacci

fn main() {
    println!("\(fibonacci(10))")
    println!("\(fibonacci(20))")
}

Style 2: Import the Module

Use when you need multiple items from the same module:

import myLib.math

fn main() {
    println!("\(math.fibonacci(10))")
    println!("\(math.add(5, 3))")
}

Style 3: Import with Alias

Use when dealing with naming conflicts:

import myLib.v1.process as processV1
import myLib.v2.process as processV2

fn main() {
    processV1.handle()
    processV2.handle()
}

Style 4: Full Paths

Use for rare or library items:

fn main() {
    let result = myLib.math.fibonacci(10)
}

Scoped Imports

Imports can be declared at any scope level, not just the top of a file:

fn processData() {
    import utils.math
    let result = math.fibonacci(10)
}

fn formatOutput() {
    import utils.formatting
    let text = formatting.indent("Text")
}

This can help keep imports close to where they're used, though top-level imports are more common.

Circular Imports

Oxide, like Rust, prevents circular dependencies at the crate level. However, within a crate, you can have modules that reference each other:

// src/lib.ox
module a {
    public fn callB() {
        b.doSomething()
    }
}

module b {
    public fn doSomething() {
        println!("B does something")
    }
}

This works because both modules are in the same compilation unit. The key is that you can't have circular dependencies between crates.

Re-exporting

When you import something in a public scope, it becomes available to your module's users:

// internal/utils.ox
public fn createConfig() { }

// src/lib.ox
import internal.utils.createConfig

// Users of this library can now do:
// import myLib.createConfig

To make this explicit, use public import:

public import internal.utils.createConfig

This makes it clear that createConfig is part of your public API.

Organizing Imports

A common convention is to organize imports into groups:

// Standard library imports (if any)
import io
import collections

// Internal imports
import utils.math
import utils.formatting

// Re-exports
public import math.fibonacci
public import formatting.indent

fn main() {
    let fib = fibonacci(10)
}

Comparison with Rust

In Rust:

• Modules are brought into scope with use, not import
• Paths use :: not .
• Wildcard imports use use module::*;
• pub use re-exports (same as Oxide)

Rust example:

#![allow(unused)]
fn main() {
use restaurant::food::appetizers::bruschetta;
use restaurant::food::*;
use restaurant::food::appetizers as starters;

pub use internal::utils::createMessage;
}

Oxide equivalent:

import restaurant.food.appetizers.bruschetta
import restaurant.food.*
import restaurant.food.appetizers as starters

public import internal.utils.createMessage

Summary

• Basic imports bring items into scope to avoid writing full paths
• Selective imports bring only what you need using braces
• Module imports let you access items with dot notation
• Wildcard imports bring everything into scope (use sparingly)
• Renaming with as helps avoid conflicts and improve clarity
• Nested imports import multiple items from the same parent
• Relative paths work within modules without explicit imports
• Scoped imports can be declared at any level
• Re-exports with public import make items part of your public API

Now that you understand imports, let's explore paths and how to understand the full module hierarchy.

File Organization and Directory Hierarchy

As your project grows, you'll want to split your code into multiple files organized in a directory structure. Oxide provides flexible conventions for organizing files and modules.

Converting Inline Modules to Files

When an inline module becomes large, you can move it to a separate file.

Starting with Inline Modules

// src/lib.ox
module restaurant {
    public fn greet() {
        println!("Welcome!")
    }

    public fn serve() {
        println!("Your food is ready")
    }
}

Extracting to a File

Create a new file src/restaurant.ox:

// src/restaurant.ox
public fn greet() {
    println!("Welcome!")
}

public fn serve() {
    println!("Your food is ready")
}

Then update src/lib.ox to declare the external module:

// src/lib.ox
external module restaurant

Now your module is in a separate file, but the module structure is identical.

Module Organization Patterns

Pattern 1: Flat Structure (For Small Projects)

Use one file for all modules:

src/
└── lib.ox  (contains all modules inline)

When to use: Projects with < 500 lines of code in a single logical unit.

Pattern 2: One Module Per File

Each module gets its own file:

src/
├── lib.ox          (declares modules)
├── restaurant.ox   (restaurant module)
├── menu.ox         (menu module)
└── payment.ox      (payment module)

src/lib.ox:

external module restaurant
external module menu
external module payment

When to use: Most projects. Clear one-to-one mapping between modules and files.

Pattern 3: Nested Modules in Directories

Create a directory for complex modules:

src/
├── lib.ox
├── restaurant.ox
└── restaurant/
    ├── mod.ox      (or just named as directory marker)
    ├── food.ox
    ├── payment.ox
    └── house.ox

src/lib.ox:

external module restaurant

src/restaurant.ox:

external module food
external module payment
external module house

public fn welcome() {
    println!("Welcome to our restaurant!")
}

Or alternatively, use a mod.ox file:

src/
├── lib.ox
└── restaurant/
    ├── mod.ox       (equivalent to restaurant.ox)
    ├── food.ox
    ├── payment.ox
    └── house.ox

src/restaurant/mod.ox:

external module food
external module payment
external module house

public fn welcome() {
    println!("Welcome!")
}

When to use: When a module has several sub-modules and related code.

Pattern 4: Deeply Nested Structure

For complex projects with many sub-modules:

src/
├── lib.ox
└── server/
    ├── mod.ox
    ├── http/
    │   ├── mod.ox
    │   ├── handlers.ox
    │   ├── middleware.ox
    │   └── routing.ox
    ├── websocket/
    │   ├── mod.ox
    │   ├── connection.ox
    │   └── protocol.ox
    └── common.ox

src/lib.ox:

external module server

src/server/mod.ox:

external module http
external module websocket
external module common

src/server/http/mod.ox:

external module handlers
external module middleware
external module routing

public fn startServer() {
    // Implementation
}

When to use: Large projects with multiple subsystems. Keep nesting to 2-3 levels max for clarity.

File Naming Conventions

Naming Rules

• File names use snake_case to match module names
• Directory names match module names
• For mod.ox files, the directory name is the module name

Examples

Absolute vs. Relative File Declarations

Absolute Declaration

Declare the full path from the crate root:

// src/lib.ox
external module restaurant.food.appetizers

Oxide will look for: src/restaurant/food/appetizers.ox

Hierarchical Declaration

Declare modules at each level:

// src/lib.ox
external module restaurant

// src/restaurant.ox (or src/restaurant/mod.ox)
external module food

// src/restaurant/food.ox
external module appetizers

// src/restaurant/food/appetizers.ox
// Contains the actual items
public fn bruschetta() { }

Both approaches are valid. The hierarchical approach is more common because it keeps each file focused.

Practical Example: A Complete Project Structure

Let's build a restaurant management library:

Directory Structure

my_restaurant/
├── Cargo.toml
└── src/
    ├── lib.ox
    ├── restaurant.ox
    └── restaurant/
        ├── menu.ox
        ├── kitchen.ox
        ├── payment.ox
        └── users.ox

src/lib.ox

/// Restaurant management library
external module restaurant

// Re-export public API
public import restaurant.menu.Menu
public import restaurant.menu.MenuItem
public import restaurant.kitchen.startCooking
public import restaurant.payment.processPayment

src/restaurant.ox

external module menu
external module kitchen
external module payment
external module users

public fn createRestaurant(name: &str): Restaurant {
    Restaurant {
        name: String.from(name),
        menu: menu.createMenu(),
        users: [],
    }
}

public struct Restaurant {
    public name: String,
    public menu: menu.Menu,
    public users: Vec<users.Employee>,
}

src/restaurant/menu.ox

public struct Menu {
    public items: Vec<MenuItem>,
}

public struct MenuItem {
    public name: String,
    public price: Float,
    public description: String,
}

public fn createMenu(): Menu {
    Menu {
        items: [],
    }
}

public fn addItem(menu: &mut Menu, item: MenuItem) {
    menu.items.push(item)
}

src/restaurant/kitchen.ox

public fn startCooking(order: Order): Dish {
    println!("Chef is cooking: \(order.item.name)")
    Dish {
        name: order.item.name,
        preparedAt: getCurrentTime(),
    }
}

public struct Dish {
    public name: String,
    public preparedAt: UInt64,
}

src/restaurant/payment.ox

public fn processPayment(amount: Float, method: PaymentMethod): Result[String] {
    match method {
        PaymentMethod.Credit -> {
            println!("Processing credit card payment: $\(amount)")
            Ok("Payment successful".toString())
        },
        PaymentMethod.Cash -> {
            println!("Received cash payment: $\(amount)")
            Ok("Payment successful".toString())
        },
    }
}

public enum PaymentMethod {
    Credit,
    Cash,
    Check,
}

src/restaurant/users.ox

public struct Employee {
    public id: String,
    public name: String,
    public role: Role,
}

public enum Role {
    Waiter,
    Chef,
    Manager,
}

public fn hireEmployee(id: String, name: String, role: Role): Employee {
    Employee { id, name, role }
}

Directory Conventions

Key Principles

1. One module per file (usually): Makes it easy to find code
2. Match directory structure to module structure: module a.b.c lives in a/b/c.ox
3. Use mod.ox for module hubs: If a directory contains sub-modules
4. Keep nesting shallow: No more than 3-4 levels deep for readability
5. Group related functionality: Put related modules in the same directory

When NOT to Create Separate Files

• For very small modules (< 50 lines)
• For internal helper modules
• In test modules

Circular Dependencies

Oxide prevents circular dependencies between modules:

module a imports module b
module b imports module a  // Error!

To fix circular dependencies:

1. Extract shared code: Create a third module both depend on

// Before (circular)
module a { ... }  // imports b
module b { ... }  // imports a

// After (acyclic)
module shared { ... }
module a { ... }  // imports shared
module b { ... }  // imports shared

2. Reorganize module hierarchy: Move items to appropriate levels

module parent {
    module child1 { ... }  // child1 can reference child2 via parent
    module child2 { ... }
}

Public Item Visibility in Files

When items are in separate files, visibility rules still apply:

// src/restaurant.ox
public fn publicFunction() { }  // Public
fn privateFunction() { }        // Private

Users can only access publicFunction. The file organization doesn't change privacy rules.

Comparison with Rust

In Rust:

• Modules use mod keyword
• File-based modules use mod name;
• The conventional file for a mod server is server.rs or server/mod.rs
• Paths use :: not .
• Snake_case is used for module and file names

Rust example:

#![allow(unused)]
fn main() {
// src/lib.rs
mod restaurant;

// src/restaurant.rs
pub fn greet() { }
}

Oxide equivalent:

// src/lib.ox
external module restaurant

// src/restaurant.ox
public fn greet() { }

Best Practices

For Small Projects (< 1000 lines)

src/
└── lib.ox  (inline modules)

For Medium Projects (1000-10000 lines)

src/
├── lib.ox
├── users.ox
├── products.ox
├── orders.ox
└── payment.ox

For Large Projects (> 10000 lines)

src/
├── lib.ox
├── auth/
│   ├── mod.ox
│   ├── login.ox
│   ├── permission.ox
│   └── encryption.ox
├── api/
│   ├── mod.ox
│   ├── handlers.ox
│   ├── middleware.ox
│   └── routing.ox
└── data/
    ├── mod.ox
    ├── models.ox
    ├── database.ox
    └── cache.ox

Summary

• Inline modules are useful for small, related functionality
• External modules in files scale better for larger projects
• File names match module names in snake_case
• Directories organize nested modules: module.submodule lives in module/submodule.ox
• Keep nesting shallow: Maximum 3-4 levels for clarity
• Use mod.ox as a hub for modules in a directory
• Privacy rules apply regardless of file organization
• Extract shared code to prevent circular dependencies
• Cargo handles compilation: No need to manually include files

You now understand the full module system—from crates and packages, through module organization, imports, and file hierarchies. These tools will help you structure even the largest Oxide projects into clean, maintainable code!

Common Collections

Oxide's standard library includes a number of very useful data structures called collections. Most other data types represent one specific value, but collections can contain multiple values. Unlike the built-in array and tuple types, the data that these collections point to is stored on the heap, which means the amount of data does not need to be known at compile time and can grow or shrink as the program runs. Each kind of collection has different capabilities and costs, and choosing an appropriate one for your current situation is a skill you'll develop over time. In this chapter, we'll discuss three collections that are used very often in Oxide programs:

• A vector allows you to store a variable number of values next to each other.
• A string is a collection of characters. We've mentioned the String type previously, but in this chapter we'll talk about it in depth.
• A hash map allows you to associate a value with a specific key. It's a particular implementation of the more general data structure called a map.

To learn about the other kinds of collections provided by the standard library, see the standard library documentation.

We'll discuss how to create and update vectors, strings, and hash maps, as well as what makes each special.

Collection Types in Oxide

Oxide uses Rust's standard collection types directly. There are no type aliases for collections in Oxide v1.0:

This design keeps things simple and ensures you learn Rust's actual collection types, which is essential for reading documentation and understanding how your code works under the hood.

Rust comparison: The collection types are identical to Rust. Oxide uses the same Vec<T>, String, and HashMap<K, V> types.

#![allow(unused)]
fn main() {
// Rust - identical syntax
use std::collections::HashMap;
let v: Vec<i32> = Vec::new();
let s: String = String::new();
let h: HashMap<String, i32> = HashMap::new();
}

Storing Lists of Values with Vectors

The first collection type we'll look at is Vec<T>, also known as a vector. Vectors allow you to store more than one value in a single data structure that puts all the values next to each other in memory. Vectors can only store values of the same type. They are useful when you have a list of items, such as the lines of text in a file or the prices of items in a shopping cart.

Creating a New Vector

To create a new, empty vector, we call the Vec.new function:

fn main() {
    let v: Vec<Int> = Vec.new()
}

Note that we added a type annotation here. Because we aren't inserting any values into this vector, Oxide doesn't know what kind of elements we intend to store. This is an important point. Vectors are implemented using generics; we'll cover how to use generics with your own types in a later chapter. For now, know that the Vec<T> type provided by the standard library can hold any type. When we create a vector to hold a specific type, we can specify the type within angle brackets. In the example above, we've told Oxide that the Vec<T> in v will hold elements of the Int type.

More often, you'll create a Vec<T> with initial values, and Oxide will infer the type of value you want to store, so you rarely need to do this type annotation. Oxide provides the vec! macro, which will create a new vector that holds the values you give it:

fn main() {
    let v = vec![1, 2, 3]
}

Because we've given initial Int values, Oxide can infer that the type of v is Vec<Int>, and the type annotation isn't necessary. Next, we'll look at how to modify a vector.

Rust comparison: The main syntax difference is using dot notation for the constructor: Vec.new() instead of Vec::new(). The vec! macro works identically.

#![allow(unused)]
fn main() {
// Rust
let v: Vec<i32> = Vec::new();
let v = vec![1, 2, 3];
}

Updating a Vector

To create a vector and then add elements to it, we can use the push method:

fn main() {
    var v: Vec<Int> = Vec.new()
    v.push(5)
    v.push(6)
    v.push(7)
    v.push(8)
}

As with any variable, if we want to be able to change its value, we need to make it mutable using the var keyword. The numbers we place inside are all of type Int, and Oxide infers this from the data, so we don't need the Vec<Int> annotation.

Rust comparison: Oxide uses var instead of let mut for mutable bindings.

#![allow(unused)]
fn main() {
// Rust
let mut v: Vec<i32> = Vec::new();
v.push(5);
v.push(6);
}

Reading Elements of Vectors

There are two ways to reference a value stored in a vector: via indexing or by using the get method. In the following examples, we've annotated the types of the values that are returned from these functions for extra clarity.

fn main() {
    let v = vec![1, 2, 3, 4, 5]

    let third: &Int = &v[2]
    println!("The third element is \(third)")

    let third: Int? = v.get(2).copied()
    match third {
        Some(value) -> println!("The third element is \(value)"),
        null -> println!("There is no third element."),
    }
}

Note a few details here. We use the index value of 2 to get the third element because vectors are indexed by number, starting at zero. Using & and [] gives us a reference to the element at the index value. When we use the get method with the index passed as an argument, we get an Option<&T> (which in Oxide we can think of as (&T)?) that we can use with match.

Oxide provides these two ways to reference an element so that you can choose how the program behaves when you try to use an index value outside the range of existing elements. As an example, let's see what happens when we have a vector of five elements and then we try to access an element at index 100 with each technique:

fn main() {
    let v = vec![1, 2, 3, 4, 5]

    let doesNotExist = &v[100]        // This will panic!
    let doesNotExist = v.get(100)     // This returns null
}

When we run this code, the first [] method will cause the program to panic because it references a nonexistent element. This method is best used when you want your program to crash if there's an attempt to access an element past the end of the vector.

When the get method is passed an index that is outside the vector, it returns null without panicking. You would use this method if accessing an element beyond the range of the vector may happen occasionally under normal circumstances. Your code will then have logic to handle having either Some(&element) or null.

Ownership and Borrowing with Vectors

When the program has a valid reference, the borrow checker enforces the ownership and borrowing rules to ensure that this reference and any other references to the contents of the vector remain valid. Recall the rule that states you can't have mutable and immutable references in the same scope. That rule applies here, where we hold an immutable reference to the first element in a vector and try to add an element to the end. This program won't work if we also try to refer to that element later in the function:

fn main() {
    var v = vec![1, 2, 3, 4, 5]

    let first = &v[0]

    v.push(6)  // Error! Cannot borrow `v` as mutable

    println!("The first element is: \(first)")
}

Compiling this code will result in an error:

error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable

The code might look like it should work: Why should a reference to the first element care about changes at the end of the vector? This error is due to the way vectors work: Because vectors put the values next to each other in memory, adding a new element onto the end of the vector might require allocating new memory and copying the old elements to the new space, if there isn't enough room to put all the elements next to each other where the vector is currently stored. In that case, the reference to the first element would be pointing to deallocated memory. The borrowing rules prevent programs from ending up in that situation.

Iterating Over the Values in a Vector

To access each element in a vector in turn, we would iterate through all of the elements rather than use indices to access one at a time. Here's how to use a for loop to get immutable references to each element in a vector of Int values and print them:

fn main() {
    let v = vec![100, 32, 57]
    for i in &v {
        println!("\(i)")
    }
}

We can also iterate over mutable references to each element in a mutable vector in order to make changes to all the elements. The following for loop will add 50 to each element:

fn main() {
    var v = vec![100, 32, 57]
    for i in &mut v {
        *i += 50
    }
}

To change the value that the mutable reference refers to, we have to use the * dereference operator to get to the value in i before we can use the += operator. We'll talk more about the dereference operator in a later chapter.

Iterating over a vector, whether immutably or mutably, is safe because of the borrow checker's rules. If we attempted to insert or remove items in the for loop body, we would get a compiler error. The reference to the vector that the for loop holds prevents simultaneous modification of the whole vector.

Using an Enum to Store Multiple Types

Vectors can only store values that are of the same type. This can be inconvenient; there are definitely use cases for needing to store a list of items of different types. Fortunately, the variants of an enum are defined under the same enum type, so when we need one type to represent elements of different types, we can define and use an enum!

For example, say we want to get values from a row in a spreadsheet in which some of the columns in the row contain integers, some floating-point numbers, and some strings. We can define an enum whose variants will hold the different value types, and all the enum variants will be considered the same type: that of the enum. Then we can create a vector to hold that enum and so, ultimately, hold different types:

fn main() {
    enum SpreadsheetCell {
        IntValue(Int),
        FloatValue(Float),
        Text(String),
    }

    let row = vec![
        SpreadsheetCell.IntValue(3),
        SpreadsheetCell.FloatValue(10.12),
        SpreadsheetCell.Text("blue".toString()),
    ]
}

Oxide needs to know what types will be in the vector at compile time so that it knows exactly how much memory on the heap will be needed to store each element. We must also be explicit about what types are allowed in this vector. If Oxide allowed a vector to hold any type, there would be a chance that one or more of the types would cause errors with the operations performed on the elements of the vector. Using an enum plus a match expression means that Oxide will ensure at compile time that every possible case is handled.

If you don't know the exhaustive set of types a program will get at runtime to store in a vector, the enum technique won't work. Instead, you can use a trait object, which we'll cover in a later chapter.

Common Vector Methods

Now that we've discussed some of the most common ways to use vectors, here are some additional useful methods defined on Vec<T>:

fn main() {
    var v = vec![1, 2, 3]

    // Add an element to the end
    v.push(4)

    // Remove and return the last element
    let last: Int? = v.pop()  // Returns Some(4)

    // Get the length
    let len = v.len()  // Returns 3

    // Check if empty
    let empty = v.isEmpty()  // Returns false

    // Clear all elements
    v.clear()

    // Create with capacity (optimization)
    let withCapacity: Vec<Int> = Vec.withCapacity(10)
}

Rust comparison: Method names are generally the same, but Oxide uses camelCase for method names like isEmpty instead of is_empty. Also note Vec.withCapacity uses dot notation instead of Vec::with_capacity.

#![allow(unused)]
fn main() {
// Rust
let mut v = vec![1, 2, 3];
v.push(4);
let last = v.pop();
let len = v.len();
let empty = v.is_empty();
v.clear();
let with_capacity: Vec<i32> = Vec::with_capacity(10);
}

Dropping a Vector Drops Its Elements

Like any other value, a vector is freed when it goes out of scope:

fn main() {
    {
        let v = vec![1, 2, 3, 4]

        // do stuff with v
    } // <- v goes out of scope and is freed here
}

When the vector gets dropped, all of its contents are also dropped, meaning the integers it holds will be cleaned up. The borrow checker ensures that any references to contents of a vector are only used while the vector itself is valid.

Let's move on to the next collection type: String!

Storing UTF-8 Encoded Text with Strings

We talked about strings in the ownership chapter, but we'll look at them in more depth now. New programmers commonly get stuck on strings for a combination of three reasons: the language's propensity for exposing possible errors, strings being a more complicated data structure than many programmers give them credit for, and UTF-8. These factors combine in a way that can seem difficult when you're coming from other programming languages.

We discuss strings in the context of collections because strings are implemented as a collection of bytes, plus some methods to provide useful functionality when those bytes are interpreted as text. In this section, we'll talk about the operations on String that every collection type has, such as creating, updating, and reading. We'll also discuss the ways in which String is different from the other collections, namely how indexing into a String is complicated by the differences between how people and computers interpret String data.

What Is a String?

Oxide has only one string type in the core language, which is the string slice str that is usually seen in its borrowed form, &str. We talked about string slices in the ownership chapter, which are references to some UTF-8 encoded string data stored elsewhere. String literals, for example, are stored in the program's binary and are therefore string slices.

The String type, which is provided by the standard library rather than coded into the core language, is a growable, mutable, owned, UTF-8 encoded string type. When we refer to "strings" in Oxide, we might be referring to either the String or the string slice &str types, not just one of those types. Although this section is largely about String, both types are used heavily in the standard library, and both String and string slices are UTF-8 encoded.

Creating a New String

Many of the same operations available with Vec<T> are available with String as well because String is actually implemented as a wrapper around a vector of bytes with some extra guarantees, restrictions, and capabilities. An example of a function that works the same way with Vec<T> and String is the new function to create an instance:

fn main() {
    let s = String.new()
}

This line creates a new, empty string called s, into which we can then load data. Often, we'll have some initial data with which we want to start the string. For that, we use the toString method, which is available on any type that implements the Display trait, as string literals do:

fn main() {
    let data = "initial contents"
    let s = data.toString()

    // Or more directly:
    let s = "initial contents".toString()
}

This code creates a string containing initial contents.

We can also use the function String.from to create a String from a string literal:

fn main() {
    let s = String.from("initial contents")
}

Because strings are used for so many things, we can use many different APIs for strings, providing us with a lot of options. In this case, String.from and toString do the same thing, so which one you choose is a matter of style and readability.

Rust comparison: Oxide uses dot notation (String.new(), String.from()) instead of path notation (String::new(), String::from()). Also, Oxide uses toString() in camelCase instead of to_string().

#![allow(unused)]
fn main() {
// Rust
let s = String::new();
let s = "initial contents".to_string();
let s = String::from("initial contents");
}

Remember that strings are UTF-8 encoded, so we can include any properly encoded data in them:

fn main() {
    let hello = String.from("Hola")
    let hello = String.from("Hello")
    let hello = String.from("Zdravstvuyte")
    let hello = String.from("Bonjour")
    let hello = String.from("Hallo")
    let hello = String.from("Ciao")
    let hello = String.from("Olá")
}

All of these are valid String values.

String Interpolation

One of Oxide's most convenient features for working with strings is string interpolation. Instead of using the format! macro with placeholders, you can embed expressions directly in string literals using \(expression) syntax:

fn main() {
    let name = "Alice"
    let age = 30

    // String interpolation
    let greeting = "Hello, \(name)! You are \(age) years old."
    println!("\(greeting)")

    // Expressions work too
    let message = "Next year you'll be \(age + 1)."
    println!("\(message)")
}

This is much more readable than the equivalent code using format!:

fn main() {
    let name = "Alice"
    let age = 30

    // Using format! macro (also works)
    let greeting = format!("Hello, {}! You are {} years old.", name, age)
}

Rust comparison: Rust requires the format! macro for string formatting. Oxide's \(expr) syntax is inspired by Swift and provides a cleaner alternative.

#![allow(unused)]
fn main() {
// Rust
let name = "Alice";
let age = 30;
let greeting = format!("Hello, {}! You are {} years old.", name, age);
}

Updating a String

A String can grow in size and its contents can change, just like the contents of a Vec<T>, if you push more data into it. In addition, you can conveniently use the + operator or string interpolation to concatenate String values.

Appending with pushStr and push

We can grow a String by using the pushStr method to append a string slice:

fn main() {
    var s = String.from("foo")
    s.pushStr("bar")
    println!("\(s)")  // Prints: foobar
}

After these two lines, s will contain foobar. The pushStr method takes a string slice because we don't necessarily want to take ownership of the parameter. For example, in the following code, we want to be able to use s2 after appending its contents to s1:

fn main() {
    var s1 = String.from("foo")
    let s2 = "bar"
    s1.pushStr(s2)
    println!("s2 is \(s2)")  // s2 is still valid!
}

If the pushStr method took ownership of s2, we wouldn't be able to print its value on the last line. However, this code works as we'd expect!

The push method takes a single character as a parameter and adds it to the String:

fn main() {
    var s = String.from("lo")
    s.push('l')
    println!("\(s)")  // Prints: lol
}

Rust comparison: Oxide uses camelCase method names: pushStr instead of push_str.

#![allow(unused)]
fn main() {
// Rust
let mut s = String::from("foo");
s.push_str("bar");
s.push('l');
}

Concatenating with + or String Interpolation

Often, you'll want to combine two existing strings. One way to do so is to use the + operator:

fn main() {
    let s1 = String.from("Hello, ")
    let s2 = String.from("world!")
    let s3 = s1 + &s2  // Note: s1 has been moved here and can no longer be used
}

The string s3 will contain Hello, world!. The reason s1 is no longer valid after the addition, and the reason we used a reference to s2, has to do with the signature of the method that's called when we use the + operator. The + operator uses the add method, whose signature looks something like this:

consuming fn add(s: &str): String

This means s1 will be moved into the add call and will no longer be valid after that. So, although let s3 = s1 + &s2; looks like it will copy both strings and create a new one, this statement actually takes ownership of s1, appends a copy of the contents of s2, and then returns ownership of the result.

If we need to concatenate multiple strings, the behavior of the + operator gets unwieldy:

fn main() {
    let s1 = String.from("tic")
    let s2 = String.from("tac")
    let s3 = String.from("toe")

    let s = s1 + "-" + &s2 + "-" + &s3
}

At this point, s will be tic-tac-toe. With all of the + and " characters, it's difficult to see what's going on. For combining strings in more complicated ways, we can instead use string interpolation:

fn main() {
    let s1 = String.from("tic")
    let s2 = String.from("tac")
    let s3 = String.from("toe")

    let s = "\(s1)-\(s2)-\(s3)"
}

This code also sets s to tic-tac-toe. String interpolation is much easier to read, and unlike the + operator, it doesn't take ownership of any of its parameters because it uses references internally.

Indexing into Strings

In many other programming languages, accessing individual characters in a string by referencing them by index is a valid and common operation. However, if you try to access parts of a String using indexing syntax in Oxide, you'll get an error:

fn main() {
    let s1 = String.from("hello")
    let h = s1[0]  // Error! Strings cannot be indexed by integers
}

The error tells the story: Oxide strings don't support indexing. But why not? To answer that question, we need to discuss how Oxide stores strings in memory.

Internal Representation

A String is a wrapper over a Vec<UInt8>. Let's look at some of our properly encoded UTF-8 example strings. First, this one:

let hello = String.from("Hola")

In this case, len will be 4, which means the vector storing the string "Hola" is 4 bytes long. Each of these letters takes 1 byte when encoded in UTF-8. The following line, however, may surprise you (note that this string begins with the capital Cyrillic letter Ze, not the number 3):

let hello = String.from("Zdravstvuyte")  // Russian greeting

If you were asked how long the string is, you might say 12. In fact, Oxide's answer is 24: That's the number of bytes it takes to encode "Zdravstvuyte" in UTF-8, because each Unicode scalar value in that string takes 2 bytes of storage. Therefore, an index into the string's bytes will not always correlate to a valid Unicode scalar value.

You already know that answer will not be Z, the first letter. When encoded in UTF-8, the first byte of Z is 208 and the second is 151, so it would seem that answer should in fact be 208, but 208 is not a valid character on its own. Returning 208 is likely not what a user would want if they asked for the first letter of this string; however, that's the only data that Oxide has at byte index 0.

The answer, then, is that to avoid returning an unexpected value and causing bugs that might not be discovered immediately, Oxide doesn't compile this code at all and prevents misunderstandings early in the development process.

Bytes, Scalar Values, and Grapheme Clusters

Another point about UTF-8 is that there are actually three relevant ways to look at strings from Oxide's perspective: as bytes, scalar values, and grapheme clusters (the closest thing to what we would call letters).

If we look at the Hindi word "namaste" written in the Devanagari script, it is stored as a vector of UInt8 values that looks like this:

[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164, 224, 165, 135]

That's 18 bytes and is how computers ultimately store this data. If we look at them as Unicode scalar values, which are what Oxide's Char type is, those bytes look like this:

['n', 'm', 's', '्', 't', 'े']

There are six Char values here, but the fourth and sixth are not letters: They're diacritics that don't make sense on their own. Finally, if we look at them as grapheme clusters, we'd get what a person would call the four letters that make up the Hindi word.

Oxide provides different ways of interpreting the raw string data that computers store so that each program can choose the interpretation it needs, no matter what human language the data is in.

A final reason Oxide doesn't allow us to index into a String to get a character is that indexing operations are expected to always take constant time (O(1)). But it isn't possible to guarantee that performance with a String, because Oxide would have to walk through the contents from the beginning to the index to determine how many valid characters there were.

Slicing Strings

Indexing into a string is often a bad idea because it's not clear what the return type of the string-indexing operation should be: a byte value, a character, a grapheme cluster, or a string slice. If you really need to use indices to create string slices, Oxide asks you to be more specific.

Rather than indexing using [] with a single number, you can use [] with a range to create a string slice containing particular bytes:

let hello = "Zdravstvuyte"  // Russian greeting in Cyrillic

let s = &hello[0..4]

Here, s will be a &str that contains the first 4 bytes of the string. Earlier, we mentioned that each of these characters was 2 bytes, which means s will be the first two Cyrillic characters.

If we were to try to slice only part of a character's bytes with something like &hello[0..1], Oxide would panic at runtime in the same way as if an invalid index were accessed in a vector:

thread 'main' panicked at 'byte index 1 is not a char boundary'

You should use caution when creating string slices with ranges, because doing so can crash your program.

Iterating Over Strings

The best way to operate on pieces of strings is to be explicit about whether you want characters or bytes. For individual Unicode scalar values, use the chars method. Calling chars on a Cyrillic string separates out and returns values of type Char, and you can iterate over the result to access each element:

fn main() {
    for c in "Hello".chars() {
        println!("\(c)")
    }
}

This code will print:

H
e
l
l
o

Alternatively, the bytes method returns each raw byte, which might be appropriate for your domain:

fn main() {
    for b in "Hello".bytes() {
        println!("\(b)")
    }
}

This code will print the bytes that make up this string:

72
101
108
108
111

But be sure to remember that valid Unicode scalar values may be made up of more than 1 byte.

Getting grapheme clusters from strings is complex, so this functionality is not provided by the standard library. Crates are available on crates.io if this is the functionality you need.

Common String Methods

Here are some commonly used methods on String and &str:

fn main() {
    let s = String.from("Hello, World!")

    // Check if empty
    let empty = s.isEmpty()  // false

    // Get length in bytes
    let len = s.len()  // 13

    // Check if string contains a substring
    let hasWorld = s.contains("World")  // true

    // Replace occurrences
    let replaced = s.replace("World", "Oxide")  // "Hello, Oxide!"

    // Convert to uppercase/lowercase
    let upper = s.toUppercase()  // "HELLO, WORLD!"
    let lower = s.toLowercase()  // "hello, world!"

    // Trim whitespace
    let padded = "  hello  "
    let trimmed = padded.trim()  // "hello"

    // Split into parts
    let csv = "a,b,c"
    for part in csv.split(',') {
        println!("\(part)")
    }
}

Rust comparison: Method names use camelCase in Oxide: isEmpty instead of is_empty, toUppercase instead of to_uppercase.

#![allow(unused)]
fn main() {
// Rust
let s = String::from("Hello, World!");
let empty = s.is_empty();
let upper = s.to_uppercase();
let lower = s.to_lowercase();
}

Strings Are Not So Simple

To summarize, strings are complicated. Different programming languages make different choices about how to present this complexity to the programmer. Oxide has chosen to make the correct handling of String data the default behavior for all Oxide programs, which means programmers have to put more thought into handling UTF-8 data up front. This trade-off exposes more of the complexity of strings than is apparent in other programming languages, but it prevents you from having to handle errors involving non-ASCII characters later in your development life cycle.

The good news is that the standard library offers a lot of functionality built off the String and &str types to help handle these complex situations correctly. Be sure to check out the documentation for useful methods like contains for searching in a string and replace for substituting parts of a string with another string.

Let's switch to something a bit less complex: hash maps!

Storing Keys with Associated Values in Hash Maps

The last of our common collections is the hash map. The type HashMap<K, V> stores a mapping of keys of type K to values of type V using a hashing function, which determines how it places these keys and values into memory. Many programming languages support this kind of data structure, but they often use a different name, such as hash, map, object, hash table, dictionary, or associative array, just to name a few.

Hash maps are useful when you want to look up data not by using an index, as you can with vectors, but by using a key that can be of any type. For example, in a game, you could keep track of each team's score in a hash map in which each key is a team's name and the values are each team's score. Given a team name, you can retrieve its score.

We'll go over the basic API of hash maps in this section, but many more goodies are hiding in the functions defined on HashMap<K, V> by the standard library. As always, check the standard library documentation for more information.

Creating a New Hash Map

One way to create an empty hash map is to use new and to add elements with insert. In the following example, we're keeping track of the scores of two teams whose names are Blue and Yellow. The Blue team starts with 10 points, and the Yellow team starts with 50:

import std.collections.HashMap

fn main() {
    var scores: HashMap<String, Int> = HashMap.new()

    scores.insert("Blue".toString(), 10)
    scores.insert("Yellow".toString(), 50)
}

Note that we need to first import the HashMap from the collections portion of the standard library. Of our three common collections, this one is the least often used, so it's not included in the features brought into scope automatically in the prelude. Hash maps also have less support from the standard library; there's no built-in macro to construct them, for example.

Just like vectors, hash maps store their data on the heap. This HashMap has keys of type String and values of type Int. Like vectors, hash maps are homogeneous: All of the keys must have the same type, and all of the values must have the same type.

Rust comparison: Oxide uses dot notation (HashMap.new()) instead of path notation (HashMap::new()), and imports use dot notation (std.collections.HashMap) instead of std::collections::HashMap.

// Rust
use std::collections::HashMap;

fn main() {
    let mut scores: HashMap<String, i32> = HashMap::new();
    scores.insert(String::from("Blue"), 10);
    scores.insert(String::from("Yellow"), 50);
}

Accessing Values in a Hash Map

We can get a value out of the hash map by providing its key to the get method:

import std.collections.HashMap

fn main() {
    var scores: HashMap<String, Int> = HashMap.new()

    scores.insert("Blue".toString(), 10)
    scores.insert("Yellow".toString(), 50)

    let teamName = "Blue".toString()
    let score: Int = scores.get(&teamName).copied().unwrapOr(0)

    println!("Blue team score: \(score)")
}

Here, score will have the value that's associated with the Blue team, and the result will be 10. The get method returns an Option<&V> (or (&V)? in Oxide terms); if there's no value for that key in the hash map, get will return null. This program handles the Option by calling copied to get an Option<Int> rather than an Option<&Int>, then unwrapOr to set score to zero if scores doesn't have an entry for the key.

We can iterate over each key-value pair in a hash map in a similar manner as we do with vectors, using a for loop:

import std.collections.HashMap

fn main() {
    var scores: HashMap<String, Int> = HashMap.new()

    scores.insert("Blue".toString(), 10)
    scores.insert("Yellow".toString(), 50)

    for (key, value) in &scores {
        println!("\(key): \(value)")
    }
}

This code will print each pair in an arbitrary order:

Yellow: 50
Blue: 10

Rust comparison: Oxide uses camelCase for method names: unwrapOr instead of unwrap_or.

#![allow(unused)]
fn main() {
// Rust
let score = scores.get(&team_name).copied().unwrap_or(0);
}

Hash Maps and Ownership

For types that implement the Copy trait, like Int, the values are copied into the hash map. For owned values like String, the values will be moved and the hash map will be the owner of those values:

import std.collections.HashMap

fn main() {
    let fieldName = "Favorite color".toString()
    let fieldValue = "Blue".toString()

    var map: HashMap<String, String> = HashMap.new()
    map.insert(fieldName, fieldValue)

    // fieldName and fieldValue are invalid at this point!
    // println!("\(fieldName)")  // Error: value has been moved
}

We aren't able to use the variables fieldName and fieldValue after they've been moved into the hash map with the call to insert.

If we insert references to values into the hash map, the values won't be moved into the hash map. The values that the references point to must be valid for at least as long as the hash map is valid. We'll talk more about these issues in the chapter on lifetimes.

Updating a Hash Map

Although the number of key and value pairs is growable, each unique key can only have one value associated with it at a time (but not vice versa: for example, both the Blue team and the Yellow team could have the value 10 stored in the scores hash map).

When you want to change the data in a hash map, you have to decide how to handle the case when a key already has a value assigned. You could replace the old value with the new value, completely disregarding the old value. You could keep the old value and ignore the new value, only adding the new value if the key doesn't already have a value. Or you could combine the old value and the new value. Let's look at how to do each of these!

Overwriting a Value

If we insert a key and a value into a hash map and then insert that same key with a different value, the value associated with that key will be replaced. Even though the following code calls insert twice, the hash map will only contain one key-value pair because we're inserting the value for the Blue team's key both times:

import std.collections.HashMap

fn main() {
    var scores: HashMap<String, Int> = HashMap.new()

    scores.insert("Blue".toString(), 10)
    scores.insert("Blue".toString(), 25)

    println!("\(scores)")  // Prints: {"Blue": 25}
}

This code will print {"Blue": 25}. The original value of 10 has been overwritten.

Adding a Key and Value Only If a Key Isn't Present

It's common to check whether a particular key already exists in the hash map with a value and then to take the following actions: If the key does exist in the hash map, the existing value should remain the way it is; if the key doesn't exist, insert it and a value for it.

Hash maps have a special API for this called entry that takes the key you want to check as a parameter. The return value of the entry method is an enum called Entry that represents a value that might or might not exist. Let's say we want to check whether the key for the Yellow team has a value associated with it. If it doesn't, we want to insert the value 50, and the same for the Blue team:

import std.collections.HashMap

fn main() {
    var scores: HashMap<String, Int> = HashMap.new()
    scores.insert("Blue".toString(), 10)

    scores.entry("Yellow".toString()).orInsert(50)
    scores.entry("Blue".toString()).orInsert(50)

    println!("\(scores)")
}

The orInsert method on Entry is defined to return a mutable reference to the value for the corresponding Entry key if that key exists, and if not, it inserts the parameter as the new value for this key and returns a mutable reference to the new value. This technique is much cleaner than writing the logic ourselves and, in addition, plays more nicely with the borrow checker.

Running this code will print {"Yellow": 50, "Blue": 10}. The first call to entry will insert the key for the Yellow team with the value 50 because the Yellow team doesn't have a value already. The second call to entry will not change the hash map, because the Blue team already has the value 10.

Rust comparison: Oxide uses camelCase: orInsert instead of or_insert.

#![allow(unused)]
fn main() {
// Rust
scores.entry(String::from("Yellow")).or_insert(50);
}

Updating a Value Based on the Old Value

Another common use case for hash maps is to look up a key's value and then update it based on the old value. For instance, the following code counts how many times each word appears in some text. We use a hash map with the words as keys and increment the value to keep track of how many times we've seen that word. If it's the first time we've seen a word, we'll first insert the value 0:

import std.collections.HashMap

fn main() {
    let text = "hello world wonderful world"

    var map: HashMap<String, Int> = HashMap.new()

    for word in text.splitWhitespace() {
        let count = map.entry(word.toString()).orInsert(0)
        *count += 1
    }

    println!("\(map)")
}

This code will print {"world": 2, "hello": 1, "wonderful": 1}. You might see the same key-value pairs printed in a different order: Recall that iterating over a hash map happens in an arbitrary order.

The splitWhitespace method returns an iterator over subslices, separated by whitespace, of the value in text. The orInsert method returns a mutable reference (&mut V) to the value for the specified key. Here, we store that mutable reference in the count variable, so in order to assign to that value, we must first dereference count using the asterisk (*). The mutable reference goes out of scope at the end of the for loop, so all of these changes are safe and allowed by the borrowing rules.

Rust comparison: Oxide uses splitWhitespace in camelCase instead of split_whitespace.

#![allow(unused)]
fn main() {
// Rust
for word in text.split_whitespace() {
    let count = map.entry(String::from(word)).or_insert(0);
    *count += 1;
}
}

Hashing Functions

By default, HashMap uses a hashing function called SipHash that can provide resistance to denial-of-service (DoS) attacks involving hash tables. This is not the fastest hashing algorithm available, but the trade-off for better security that comes with the drop in performance is worth it. If you profile your code and find that the default hash function is too slow for your purposes, you can switch to another function by specifying a different hasher. A hasher is a type that implements the BuildHasher trait. We'll talk about traits and how to implement them in a later chapter. You don't necessarily have to implement your own hasher from scratch; crates.io has libraries shared by other users that provide hashers implementing many common hashing algorithms.

A Complete Example

Let's put together a more complete example that demonstrates working with hash maps. This program tracks player scores in a game:

import std.collections.HashMap

public struct GameScores {
    scores: HashMap<String, Int>,
}

extension GameScores {
    public static fn new(): GameScores {
        GameScores { scores: HashMap.new() }
    }

    public mutating fn addPlayer(name: String) {
        self.scores.entry(name).orInsert(0)
    }

    public mutating fn addPoints(name: &str, points: Int) {
        if let Some(score) = self.scores.getMut(&name.toString()) {
            *score += points
        }
    }

    public fn getScore(name: &str): Int {
        self.scores.get(&name.toString()).copied().unwrapOr(0)
    }

    public fn displayScores() {
        println!("Current Scores:")
        for (name, score) in &self.scores {
            println!("  \(name): \(score)")
        }
    }
}

fn main() {
    var game = GameScores.new()

    game.addPlayer("Alice".toString())
    game.addPlayer("Bob".toString())

    game.addPoints("Alice", 10)
    game.addPoints("Alice", 5)
    game.addPoints("Bob", 20)

    game.displayScores()

    let aliceScore = game.getScore("Alice")
    println!("Alice's final score: \(aliceScore)")
}

This example demonstrates:

• Creating and initializing a HashMap
• Using the entry API for safe insertions
• Iterating over key-value pairs
• Getting mutable references to update values
• Working with hash maps inside a struct

Summary

Vectors, strings, and hash maps will provide a large amount of functionality necessary in programs when you need to store, access, and modify data. Here are some exercises you should now be equipped to solve:

1. Given a list of integers, use a vector and return the median (when sorted, the value in the middle position) and mode (the value that occurs most often; a hash map will be helpful here) of the list.

2. Convert strings to pig latin. The first consonant of each word is moved to the end of the word and -ay is added, so first becomes irst-fay. Words that start with a vowel have -hay added to the end instead (apple becomes apple-hay). Keep in mind the details about UTF-8 encoding!

3. Using a hash map and vectors, create a text interface to allow a user to add employee names to a department in a company; for example, "Add Sally to Engineering" or "Add Amir to Sales." Then, let the user retrieve a list of all people in a department or all people in the company by department, sorted alphabetically.

The standard library API documentation describes methods that vectors, strings, and hash maps have that will be helpful for these exercises!

We're getting into more complex programs in which operations can fail, so it's a perfect time to discuss error handling. We'll do that next!

Error Handling

Errors are a fact of life in software, so Oxide has a number of features for handling situations in which something goes wrong. In many cases, Oxide requires you to acknowledge the possibility of an error and take some action before your code will compile. This requirement makes your program more robust by ensuring that you'll discover errors and handle them appropriately before deploying your code to production!

Oxide groups errors into two major categories: recoverable and unrecoverable errors. For a recoverable error, such as a file not found error, we most likely just want to report the problem to the user and retry the operation. Unrecoverable errors are always symptoms of bugs, such as trying to access a location beyond the end of an array, and so we want to immediately stop the program.

Most languages don't distinguish between these two kinds of errors and handle both in the same way, using mechanisms such as exceptions. Oxide doesn't have exceptions. Instead, it has:

• The type Result<T, E> for recoverable errors
• The panic! macro that stops execution when the program encounters an unrecoverable error
• Nullable types T? for values that may or may not exist
• Ergonomic operators ?? and !! for working with nullable values

This chapter covers:

1. Unrecoverable Errors with panic! - When to stop the program entirely
2. Recoverable Errors with Result - When to give callers a chance to handle failure
3. Working with Nullable Types - Using T?, ??, and !! effectively
4. To panic! or Not to panic! - Guidelines for choosing the right approach

Oxide's Error Handling Philosophy

Oxide inherits Rust's philosophy of making error handling explicit and type-safe. However, Oxide adds ergonomic operators that make common patterns more concise:

These operators make error handling more readable while maintaining the same safety guarantees as Rust.

Unrecoverable Errors with panic!

Sometimes bad things happen in your code, and there's nothing you can do about it. In these cases, Oxide has the panic! macro. There are two ways to cause a panic in practice: by taking an action that causes our code to panic (such as accessing an array past the end) or by explicitly calling the panic! macro. In both cases, we cause a panic in our program. By default, these panics will print a failure message, unwind, clean up the stack, and quit. Via an environment variable, you can also have Oxide display the call stack when a panic occurs to make it easier to track down the source of the panic.

Unwinding the Stack or Aborting in Response to a Panic

By default, when a panic occurs, the program starts unwinding, which means Oxide walks back up the stack and cleans up the data from each function it encounters. However, walking back and cleaning up is a lot of work. Oxide therefore allows you to choose the alternative of immediately aborting, which ends the program without cleaning up.

Memory that the program was using will then need to be cleaned up by the operating system. If in your project you need to make the resultant binary as small as possible, you can switch from unwinding to aborting upon a panic by adding panic = 'abort' to the appropriate [profile] sections in your Cargo.toml file. For example, if you want to abort on panic in release mode, add this:

[profile.release]
panic = 'abort'

Let's try calling panic! in a simple program:

fn main() {
    panic!("crash and burn")
}

When you run the program, you'll see something like this:

thread 'main' panicked at src/main.ox:2:5:
crash and burn
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

The call to panic! causes the error message contained in the last two lines. The first line shows our panic message and the place in our source code where the panic occurred: src/main.ox:2:5 indicates that it's the second line, fifth character of our src/main.ox file.

In this case, the line indicated is part of our code, and if we go to that line, we see the panic! macro call. In other cases, the panic! call might be in code that our code calls, and the filename and line number reported by the error message will be someone else's code where the panic! macro is called, not the line of our code that eventually led to the panic! call.

Using a panic! Backtrace

We can use the backtrace of the functions the panic! call came from to figure out the part of our code that is causing the problem. To understand how to use a panic! backtrace, let's look at another example and see what it's like when a panic! call comes from a library because of a bug in our code instead of from our code calling the macro directly. Here's some code that attempts to access an index in a vector beyond the range of valid indexes:

fn main() {
    let v = vec![1, 2, 3]

    v[99]
}

Here, we're attempting to access the 100th element of our vector (which is at index 99 because indexing starts at zero), but the vector has only three elements. In this situation, Oxide will panic. Using [] is supposed to return an element, but if you pass an invalid index, there's no element that Oxide could return here that would be correct.

In C, attempting to read beyond the end of a data structure is undefined behavior. You might get whatever is at the location in memory that would correspond to that element in the data structure, even though the memory doesn't belong to that structure. This is called a buffer overread and can lead to security vulnerabilities if an attacker is able to manipulate the index in such a way as to read data they shouldn't be allowed to that is stored after the data structure.

To protect your program from this sort of vulnerability, if you try to read an element at an index that doesn't exist, Oxide will stop execution and refuse to continue. Let's try it and see:

thread 'main' panicked at src/main.ox:4:5:
index out of bounds: the len is 3 but the index is 99
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

This error points at line 4 of our main.ox where we attempt to access index 99 of the vector in v.

The note: line tells us that we can set the RUST_BACKTRACE environment variable to get a backtrace of exactly what happened to cause the error. A backtrace is a list of all the functions that have been called to get to this point. Backtraces in Oxide work as they do in other languages: The key to reading the backtrace is to start from the top and read until you see files you wrote. That's the spot where the problem originated. The lines above that spot are code that your code has called; the lines below are code that called your code.

Let's try getting a backtrace by setting the RUST_BACKTRACE environment variable to any value except 0:

$ RUST_BACKTRACE=1 cargo run
thread 'main' panicked at src/main.ox:4:5:
index out of bounds: the len is 3 but the index is 99
stack backtrace:
   0: rust_begin_unwind
   1: core::panicking::panic_fmt
   2: core::panicking::panic_bounds_check
   3: <usize as core::slice::index::SliceIndex<[T]>>::index
   4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index
   5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index
   6: panic::main
             at ./src/main.ox:4:5
   7: core::ops::function::FnOnce::call_once
note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace.

That's a lot of output! The exact output you see might be different depending on your operating system and Oxide version. In order to get backtraces with this information, debug symbols must be enabled. Debug symbols are enabled by default when using cargo build or cargo run without the --release flag, as we have here.

In the output above, line 6 of the backtrace points to the line in our project that's causing the problem: line 4 of src/main.ox. If we don't want our program to panic, we should start our investigation at the location pointed to by the first line mentioning a file we wrote. The way to fix the panic is to not request an element beyond the range of the vector indexes. When your code panics in the future, you'll need to figure out what action the code is taking with what values to cause the panic and what the code should do instead.

We'll come back to panic! and when we should and should not use panic! to handle error conditions in the "To panic! or Not to panic!" section later in this chapter. Next, we'll look at how to recover from an error using Result.

Recoverable Errors with Result

Most errors aren't serious enough to require the program to stop entirely. Sometimes when a function fails, it's for a reason that you can easily interpret and respond to. For example, if you try to open a file and that operation fails because the file doesn't exist, you might want to create the file instead of terminating the process.

The Result enum is defined as having two variants, Ok and Err, as follows:

enum Result<T, E> {
    Ok(T),
    Err(E),
}

The T and E are generic type parameters. T represents the type of the value that will be returned in a success case within the Ok variant, and E represents the type of the error that will be returned in a failure case within the Err variant.

Let's call a function that returns a Result value because the function could fail. Here we try to open a file:

import std.fs.File

fn main() {
    let greetingFileResult = File.open("hello.txt")
}

The return type of File.open is a Result<T, E>. The generic parameter T has been filled in by the implementation of File.open with the type of the success value, std.fs.File, which is a file handle. The type of E used in the error value is std.io.Error. This return type means the call to File.open might succeed and return a file handle that we can read from or write to. The function call also might fail: For example, the file might not exist, or we might not have permission to access the file.

We need to add code to take different actions depending on the value File.open returns. Here's one way to handle the Result using a match expression:

import std.fs.File

fn main() {
    let greetingFileResult = File.open("hello.txt")

    let greetingFile = match greetingFileResult {
        Ok(file) -> file,
        Err(error) -> panic!("Problem opening the file: \(error)"),
    }
}

Note that, like nullable types, the Result enum and its variants have been brought into scope by the prelude, so we don't need to specify Result. before the Ok and Err variants in the match arms.

When the result is Ok, this code will return the inner file value out of the Ok variant, and we then assign that file handle value to the variable greetingFile. After the match, we can use the file handle for reading or writing.

The other arm of the match handles the case where we get an Err value from File.open. In this example, we've chosen to call the panic! macro. If there's no file named hello.txt in our current directory and we run this code, we'll see the following output from the panic! macro:

thread 'main' panicked at src/main.ox:9:23:
Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Matching on Different Errors

The code above will panic! no matter why File.open failed. However, we want to take different actions for different failure reasons. If File.open failed because the file doesn't exist, we want to create the file and return the handle to the new file. If File.open failed for any other reason--for example, because we didn't have permission to open the file--we still want the code to panic!. For this, we add an inner match expression:

import std.fs.File
import std.io.ErrorKind

fn main() {
    let greetingFileResult = File.open("hello.txt")

    let greetingFile = match greetingFileResult {
        Ok(file) -> file,
        Err(error) -> match error.kind() {
            ErrorKind.NotFound -> match File.create("hello.txt") {
                Ok(fc) -> fc,
                Err(e) -> panic!("Problem creating the file: \(e)"),
            },
            _ -> panic!("Problem opening the file: \(error)"),
        },
    }
}

The type of the value that File.open returns inside the Err variant is io.Error, which is a struct provided by the standard library. This struct has a method, kind, that we can call to get an io.ErrorKind value. The enum io.ErrorKind is provided by the standard library and has variants representing the different kinds of errors that might result from an io operation. The variant we want to use is ErrorKind.NotFound, which indicates the file we're trying to open doesn't exist yet.

Alternatives to Using match with Result<T, E>

That's a lot of match! The match expression is very useful but also very much a primitive. In Chapter 13, you'll learn about closures, which are used with many of the methods defined on Result<T, E>. These methods can be more concise than using match when handling Result<T, E> values in your code.

For example, here's another way to write the same logic using closures and the unwrapOrElse method:

import std.fs.File
import std.io.ErrorKind

fn main() {
    let greetingFile = File.open("hello.txt").unwrapOrElse { error ->
        if error.kind() == ErrorKind.NotFound {
            File.create("hello.txt").unwrapOrElse { error ->
                panic!("Problem creating the file: \(error)")
            }
        } else {
            panic!("Problem opening the file: \(error)")
        }
    }
}

Although this code has the same behavior as the nested match, it doesn't contain any match expressions and is cleaner to read.

Shortcuts for Panic on Error

Using match works well enough, but it can be a bit verbose and doesn't always communicate intent well. The Result<T, E> type has many helper methods defined on it to do various, more specific tasks.

The unwrap Method

The unwrap method is a shortcut method implemented just like the match expression we wrote earlier. If the Result value is the Ok variant, unwrap will return the value inside the Ok. If the Result is the Err variant, unwrap will call the panic! macro for us:

import std.fs.File

fn main() {
    let greetingFile = File.open("hello.txt").unwrap()
}

If we run this code without a hello.txt file, we'll see an error message from the panic! call that the unwrap method makes:

thread 'main' panicked at src/main.ox:4:49:
called `Result.unwrap()` on an `Err` value: Os { code: 2, kind: NotFound, message: "No such file or directory" }

The expect Method

Similarly, the expect method lets us also choose the panic! error message. Using expect instead of unwrap and providing good error messages can convey your intent and make tracking down the source of a panic easier:

import std.fs.File

fn main() {
    let greetingFile = File.open("hello.txt")
        .expect("hello.txt should be included in this project")
}

We use expect in the same way as unwrap: to return the file handle or call the panic! macro. The error message used by expect in its call to panic! will be the parameter that we pass to expect, rather than the default panic! message that unwrap uses:

thread 'main' panicked at src/main.ox:5:10:
hello.txt should be included in this project: Os { code: 2, kind: NotFound, message: "No such file or directory" }

In production-quality code, most developers choose expect rather than unwrap and give more context about why the operation is expected to always succeed. That way, if your assumptions are ever proven wrong, you have more information to use in debugging.

Propagating Errors

When a function's implementation calls something that might fail, instead of handling the error within the function itself, you can return the error to the calling code so that it can decide what to do. This is known as propagating the error and gives more control to the calling code, where there might be more information or logic that dictates how the error should be handled than what you have available in the context of your code.

For example, here's a function that reads a username from a file. If the file doesn't exist or can't be read, this function will return those errors to the code that called the function:

import std.fs.File
import std.io
import std.io.Read

fn readUsernameFromFile(): Result<String, io.Error> {
    let usernameFileResult = File.open("hello.txt")

    var usernameFile = match usernameFileResult {
        Ok(file) -> file,
        Err(e) -> return Err(e),
    }

    var username = String.new()

    match usernameFile.readToString(&mut username) {
        Ok(_) -> Ok(username),
        Err(e) -> Err(e),
    }
}

This function can be written in a much shorter way, but we're going to start by doing a lot of it manually in order to explore error handling; at the end, we'll show the shorter way.

The return type of the function is Result<String, io.Error>. This means the function is returning a value of the type Result<T, E>, where the generic parameter T has been filled in with the concrete type String and the generic type E has been filled in with the concrete type io.Error.

If this function succeeds without any problems, the code that calls this function will receive an Ok value that holds a String--the username that this function read from the file. If this function encounters any problems, the calling code will receive an Err value that holds an instance of io.Error that contains more information about what the problems were.

This pattern of propagating errors is so common that Oxide provides the question mark operator ? to make this easier.

The ? Operator Shortcut

Here's an implementation of readUsernameFromFile that has the same functionality, but this implementation uses the ? operator:

import std.fs.File
import std.io
import std.io.Read

fn readUsernameFromFile(): Result<String, io.Error> {
    var usernameFile = File.open("hello.txt")?
    var username = String.new()
    usernameFile.readToString(&mut username)?
    Ok(username)
}

The ? placed after a Result value is defined to work in almost the same way as the match expressions that we defined to handle the Result values earlier. If the value of the Result is an Ok, the value inside the Ok will get returned from this expression, and the program will continue. If the value is an Err, the Err will be returned from the whole function as if we had used the return keyword so that the error value gets propagated to the calling code.

There is a difference between what the match expression does and what the ? operator does: Error values that have the ? operator called on them go through the from function, defined in the From trait in the standard library, which is used to convert values from one type into another. When the ? operator calls the from function, the error type received is converted into the error type defined in the return type of the current function. This is useful when a function returns one error type to represent all the ways a function might fail, even if parts might fail for many different reasons.

The ? operator eliminates a lot of boilerplate and makes this function's implementation simpler. We could even shorten this code further by chaining method calls immediately after the ?:

import std.fs.File
import std.io
import std.io.Read

fn readUsernameFromFile(): Result<String, io.Error> {
    var username = String.new()
    File.open("hello.txt")?.readToString(&mut username)?
    Ok(username)
}

Or even more concisely using std.fs.readToString:

import std.fs

fn readUsernameFromFile(): Result<String, io.Error> {
    fs.readToString("hello.txt")
}

Reading a file into a string is a fairly common operation, so the standard library provides the convenient fs.readToString function that opens the file, creates a new String, reads the contents of the file, puts the contents into that String, and returns it.

Where to Use the ? Operator

The ? operator can only be used in functions whose return type is compatible with the value the ? is used on. This is because the ? operator is defined to perform an early return of a value out of the function.

Let's look at the error we'll get if we use the ? operator in a main function with a return type that is incompatible:

import std.fs.File

fn main() {
    let greetingFile = File.open("hello.txt")?
}

This code opens a file, which might fail. The ? operator follows the Result value returned by File.open, but this main function has the return type of (), not Result. When we compile this code, we get an error message:

error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option`
 --> src/main.ox:4:48
  |
3 | fn main() {
  | --------- this function should return `Result` or `Option` to accept `?`
4 |     let greetingFile = File.open("hello.txt")?
  |                                               ^ cannot use the `?` operator in a function that returns `()`

To fix the error, you have two choices. One choice is to change the return type of your function to be compatible with the value you're using the ? operator on. The other choice is to use a match or one of the Result<T, E> methods to handle the Result<T, E> in whatever way is appropriate.

The ? operator can also be used with nullable types (T?). The behavior is similar: If the value is null, the null will be returned early from the function at that point. If the value is Some, the value inside the Some is the resultant value of the expression, and the function continues:

fn lastCharOfFirstLine(text: &str): Char? {
    text.lines().next()?.chars().last()
}

This function returns Char? because it's possible that there is a character there, but it's also possible that there isn't. This code takes the text string slice argument and calls the lines method on it, which returns an iterator over the lines in the string. Because this function wants to examine the first line, it calls next on the iterator to get the first value from the iterator. If text is the empty string, this call to next will return null, in which case we use ? to stop and return null from lastCharOfFirstLine.

Note that you can use the ? operator on a Result in a function that returns Result, and you can use the ? operator on a nullable type in a function that returns a nullable type, but you can't mix and match. The ? operator won't automatically convert a Result to a nullable type or vice versa; in those cases, you can use methods like the ok method on Result or the okOr method on nullable types to do the conversion explicitly.

main Can Return Result

The main function can also return a Result<(), E>:

import std.error.Error
import std.fs.File

fn main(): Result<(), Box<dyn Error>> {
    let greetingFile = File.open("hello.txt")?

    Ok(())
}

The Box<dyn Error> type is a trait object. For now, you can read Box<dyn Error> to mean "any kind of error." Using ? on a Result value in a main function with the error type Box<dyn Error> is allowed because it allows any Err value to be returned early.

When a main function returns a Result<(), E>, the executable will exit with a value of 0 if main returns Ok(()) and will exit with a nonzero value if main returns an Err value.

Now that we've discussed the details of calling panic! or returning Result, let's look at Oxide's ergonomic operators for working with nullable types.

Nullable Operators (?? and !!)

Oxide provides two ergonomic operators for working with nullable types (T?) that make common patterns more concise and readable. These operators complement the ? try operator and give you fine-grained control over how you handle the absence of values.

The Null Coalescing Operator (??)

The null coalescing operator ?? provides a default value when the left-hand side is null. This is one of the most common patterns when working with optional values.

Basic Usage

let username = maybeUsername ?? "Guest"
let port = configPort ?? 8080
let config = Config.load() ?? Config.default()

When maybeUsername contains a value, that value is used. When it's null, the right-hand side ("Guest") is used instead.

How It Works

The ?? operator desugars to method calls on the underlying type:

// Oxide
let name = optionalName ?? "Anonymous"

// Desugars to (conceptually):
let name = optionalName.unwrapOr("Anonymous")

For complex right-hand side expressions, Oxide uses lazy evaluation:

// Oxide
let config = loadConfig() ?? computeExpensiveDefault()

// Desugars to:
let config = loadConfig().unwrapOrElse { computeExpensiveDefault() }

This means computeExpensiveDefault() is only called if loadConfig() returns null.

Chaining ??

You can chain multiple ?? operators to provide a sequence of fallbacks:

let username = primaryName ?? secondaryName ?? "Guest"

This tries primaryName first, then secondaryName, and finally falls back to "Guest" if both are null.

?? with Different Types

The right-hand side of ?? must be the same type as the value inside the nullable type:

let count: Int? = Some(5)
let value = count ?? 0  // OK: Int? ?? Int -> Int

let maybeString: String? = null
let text = maybeString ?? "default".toString()  // OK: String? ?? String -> String

CRITICAL: ?? works with T? (Option) ONLY, NOT Result<T, E>

This is an intentional design decision. Result<T, E> contains typed error information that should not be silently discarded:

// This will NOT compile:
let value: Result<Int, Error> = Err(someError)
let result = value ?? 0  // ERROR: ?? only works with T?

Why? If ?? worked with Result, it would silently discard error information, making debugging difficult and hiding potential issues in your code.

For Result, use explicit methods:

// Provide a default value (discards the error)
let value = riskyOperation().unwrapOr(default)

// Handle the error with a closure
let value = riskyOperation().unwrapOrElse { err ->
    log("Error occurred: \(err)")
    computeDefault()
}

// Convert Result to nullable (discards error info)
let maybeValue: Int? = riskyOperation().ok()
let value = maybeValue ?? default

Practical Examples

Configuration with defaults:

struct ServerConfig {
    host: String,
    port: Int,
    maxConnections: Int,
}

fn loadServerConfig(env: &Environment): ServerConfig {
    ServerConfig {
        host: env.get("HOST") ?? "localhost".toString(),
        port: env.get("PORT")?.parse().ok() ?? 3000,
        maxConnections: env.get("MAX_CONN")?.parse().ok() ?? 100,
    }
}

Safe dictionary access:

fn getUserDisplayName(users: &HashMap<String, User>, id: &str): String {
    let user = users.get(id)
    let displayName = user?.displayName ?? user?.username ?? "Unknown User".toString()
    displayName
}

Combining with if let:

fn processItem(item: Item?): String {
    // Use ?? when you just need a value
    let name = item?.name ?? "unnamed".toString()

    // Use if let when you need to do more complex processing
    if let item = item {
        processFullItem(item)
    } else {
        processDefault()
    }
}

The Force Unwrap Operator (!!)

The force unwrap operator !! extracts the value from a nullable type, panicking if the value is null. Use this when you are certain a value exists and want to express that certainty explicitly.

Basic Usage

let user = findUser(id)!!  // Panics if null
let first = nonEmptyList.first()!!  // Panics if null

How It Works

The !! operator desugars to an unwrap call:

// Oxide
let user = findUser(id)!!

// Desugars to:
let user = findUser(id).unwrap()

When to Use !!

Use !! when:

1. You have verified the value exists:

let items = vec![1, 2, 3]
if !items.isEmpty() {
    // We KNOW this won't be null because we checked isEmpty()
    let first = items.first()!!
    println!("First item: \(first)")
}

2. In tests where you want to fail fast:

#[test]
fn testUserCreation() {
    let user = createUser("test@example.com")!!
    assertEq!(user.email, "test@example.com")
}

3. In prototypes where proper error handling is deferred:

// Quick prototype - will add proper error handling later
fn main() {
    let config = Config.loadFromFile("config.toml")!!
    let server = Server.new(config)!!
    server.run()!!
}

4. When the value being null would indicate a bug:

// If we reach this code, currentUser MUST be set by the auth middleware
let user = getCurrentUser()!!

Warning: Use !! Sparingly

The !! operator is a clear signal that "if this is null, something has gone fundamentally wrong." Overuse of !! defeats the purpose of nullable types:

// BAD: Using !! everywhere
fn processUser(id: String): String {
    let user = findUser(id)!!  // What if user doesn't exist?
    let profile = user.profile()!!  // What if profile is incomplete?
    let address = profile.address()!!  // What if address is optional?
    format!("User lives at \(address)")
}

// BETTER: Handle the nullable cases appropriately
fn processUser(id: String): String? {
    let user = findUser(id)?
    let profile = user.profile()?
    let address = profile.address()?
    Some(format!("User lives at \(address)"))
}

// Or using ?? for defaults
fn processUser(id: String): String {
    let user = findUser(id) ?? return "Unknown user".toString()
    let address = user.profile()?.address() ?? "No address".toString()
    format!("User lives at \(address)")
}

Combining ??, !!, and ?

These three operators serve different purposes and can be combined effectively:

Example: User Authentication Flow

fn authenticateAndLoadProfile(token: String?): Result<UserProfile, AuthError> {
    // Use ? to propagate - caller handles missing token
    let token = token.okOr(AuthError.MissingToken)?

    // Use ? to propagate - caller handles invalid token
    let userId = validateToken(token)?

    // Use ?? for default - missing profile is OK, use default
    let profile = loadProfile(userId) ?? UserProfile.default()

    Ok(profile)
}

fn loadUserDashboard(user: User): Dashboard {
    // Use !! - user MUST have a primary account after login
    let primaryAccount = user.primaryAccount()!!

    // Use ?? - optional secondary accounts
    let secondaryAccounts = user.secondaryAccounts() ?? vec![]

    Dashboard {
        main: AccountView.new(primaryAccount),
        others: secondaryAccounts.map { AccountView.new(it) },
    }
}

Operator Precedence

Understanding precedence is important when combining these operators:

This means:

// a?.b ?? c is parsed as (a?.b) ?? c
let value = user?.name ?? "Anonymous"

// a!! ?? b would be unusual but parses as (a!!) ?? b
// (If a!! succeeds, ?? never evaluates; if a!! panics, we never reach ??)

// await and ?? interact predictably
let data = await fetchData() ?? defaultData  // (await fetchData()) ?? defaultData

Best Practices

1. Prefer ?? over !! when a default makes sense:

// Good
let timeout = configuredTimeout ?? Duration.fromSecs(30)

// Avoid if null is actually possible
let timeout = configuredTimeout!!  // Panic if not configured!

2. Use ? to propagate, ?? to provide defaults:

fn loadConfig(path: String?): Result<Config, Error> {
    let path = path ?? "config.toml".toString()  // Default path
    let content = fs.readToString(&path)?  // Propagate file errors
    parseConfig(&content)  // Propagate parse errors
}

3. Document why you're using !!:

// The auth middleware guarantees currentUser is set for all authenticated routes
let user = getCurrentUser()!!

4. In libraries, prefer returning T? or Result over panicking:

// Library code - let the caller decide
public fn findById(id: &str): User? {
    self.users.get(id).cloned()
}

// Application code - can use !! when appropriate
let user = db.findById(requiredId)!!

Summary

Oxide's ?? and !! operators make working with nullable types more ergonomic:

Remember:

• ?? only works with nullable types (T?), not Result<T, E>
• !! should be used sparingly and indicates "null here is a bug"
• ? propagates the absence to the caller

These operators, combined with guard let, if let, and pattern matching, give you complete control over how to handle values that might be absent.

To Panic or Not to Panic

Now that we've covered how to use panic!, Result<T, E>, nullable types T?, and the operators ??, !!, and ?, we need to discuss when to use each approach. This is a critical design decision that impacts both the robustness and usability of your code.

The Core Decision

When you have a situation that could fail, you face a choice:

1. Panic - Stop execution immediately (unrecoverable error)
2. Return Result - Let the caller decide what to do (recoverable error)
3. Use T? - Let the caller handle absence of values (nullable types)

The key principle is: Returning Result is the default choice for library code. Use panic! only when you're certain the situation is truly unrecoverable or when panic would serve debugging better than error handling.

Why Result is the Default

When you return Result<T, E>, you're saying to the caller: "This operation can fail, and I'm giving you the information you need to decide how to handle it." This respects the caller's knowledge of their own situation:

// Bad: Making the decision for the caller
fn loadConfig(): Config {
    File.open("config.toml")!!  // Panics if file missing
}

// Good: Letting the caller decide
fn loadConfig(): Result<Config, Error> {
    let content = fs.readToString("config.toml")?
    parseConfig(&content)
}

// Now the caller can choose:
fn main(): Result<(), Box<dyn Error>> {
    // Option 1: Propagate the error
    let config = loadConfig()?

    // Option 2: Use a default
    let config = loadConfig().unwrapOr(Config.default())

    // Option 3: Custom handling
    let config = match loadConfig() {
        Ok(cfg) -> cfg,
        Err(e) -> {
            eprintln!("Warning: {}", e)
            Config.default()
        }
    }

    Ok(())
}

When to Use panic!

Use panic! in these specific situations:

1. Examples and Prototypes

When writing example code or prototyping, panicking makes sense because your focus is on illustrating the happy path, not writing production-grade error handling:

// Example code - clarity is the goal
fn demonstrateStringParsing() {
    let numbers = vec!["1", "2", "3"]
    let parsed: Vec<Int> = numbers.iter()
        .map { Int.parse(it)!! }
        .collect()

    println!("Numbers: {:?}", parsed)
}

The !! here signals to readers: "In this example, we know these conversions will succeed. In real code, you'd handle errors."

2. Tests

In tests, panic indicates test failure. Using !! or .expect() is exactly right:

#[test]
fn testUserCreation() {
    let user = User.new("alice@example.com")!!
    assertEq!(user.email, "alice@example.com")
}

If user creation fails, the test should fail. There's no recovery.

3. When You Have More Information Than the Compiler

Sometimes you know something the compiler doesn't. You've verified through logic that a value will be present, but the type system can't express that guarantee. In these cases, use expect() with a detailed message explaining your reasoning:

fn parseIpAddress(): IpAddr {
    // We hardcoded this address, so we know it's valid
    "127.0.0.1".parse()
        .expect("Hardcoded IP address is always valid")
}

fn loadAuthenticatedUser(currentUserId: UserId?): User {
    // The auth middleware guarantees currentUserId is set after authentication
    let userId = currentUserId!!

    // This should never fail in a correctly functioning system
    database.findUser(userId)
        .expect("User must exist; auth middleware verifies this")
}

The message is crucial—it explains why you believe the panic can't happen, helping future maintainers understand the assumption.

4. Invalid State That Violates Contracts

When your function has a contract (documented preconditions), breaking that contract indicates a programmer error that should be caught immediately:

/// Creates a Guess from a value.
///
/// # Panics
///
/// Panics if the value is less than 1 or greater than 100.
struct Guess {
    value: Int,
}

extension Guess {
    public fn new(value: Int): Guess {
        guard value >= 1 && value <= 100 else {
            panic!("Guess must be between 1 and 100, got {}", value)
        }

        Guess { value }
    }
}

// Client code violation leads to panic during development
let guess = Guess.new(150)  // Panics - contract violation caught immediately

This is different from recoverable errors like "file not found"—it's a programming mistake.

5. External Code in Unexpected State

When calling external code that's out of your control and it returns an invalid state you can't fix:

fn processWebResponse(response: HttpResponse): Result<Data, Error> {
    // HttpStatus is supposed to be one of a defined set
    // If we get an undefined status, that's a library bug, not our error
    let status = match response.status() {
        HttpStatus.Ok -> HttpStatus.Ok,
        HttpStatus.NotFound -> HttpStatus.NotFound,
        HttpStatus.ServerError -> HttpStatus.ServerError,
        unknown -> panic!("HTTP library returned undefined status: {}", unknown),
    }

    // ... continue processing
    Ok(Data {})
}

6. Security-Critical Operations

When operating on invalid data would compromise security, panic rather than silently continuing:

fn processBuffer(buffer: &[UInt8], maxSize: UIntSize): Result<Vec<UInt8>, Error> {
    guard buffer.len() <= maxSize else {
        panic!("Buffer size {} exceeds maximum {}", buffer.len(), maxSize)
    }

    // Panic happened during development, not at runtime in production
    // because this contract violation is a security issue
    Ok(process(buffer))
}

When to Return Result

Use Result<T, E> in these situations:

1. Expected Failure

When failure is an expected part of normal operation, return Result:

// File might not exist - this is expected
fn readConfigFile(path: String): Result<String, Error> {
    fs.readToString(path)
}

// Network request might fail - this is expected
fn fetchUserData(id: String): Result<UserData, HttpError> {
    http.get(&format!("/users/{}", id))?.json()
}

// User input might be invalid - this is expected
fn parseUserInput(input: String): Result<Command, ParseError> {
    Command.parse(&input)
}

2. Errors You Can't Control

When the error comes from outside your code and you can't prevent it, return Result:

fn downloadFile(url: String): Result<Vec<UInt8>, DownloadError> {
    let response = http.get(&url)?  // Network failure
    let bytes = response.bytes()?    // Response reading failure
    Ok(bytes)
}

The caller can retry, use a fallback, or notify the user.

3. Library Code

Libraries should return Result to give callers maximum flexibility. Application code can panic; libraries can't know the right error handling strategy:

// Good library code
public fn findUserById(id: String): Result<User, NotFoundError> {
    self.database.find(id)
        .okOr(NotFoundError { id })
}

// Caller decides:
// - In a CLI tool: panic to stop
// - In a web server: return HTTP 404
// - In a batch job: log and continue

4. Recoverable State Issues

When continuing with a reasonable fallback makes sense:

fn loadServerConfig(env: &Environment): Result<Config, ConfigError> {
    // User might not set these - use defaults
    let host = env.get("HOST").unwrapOr("localhost".toString())
    let port = env.get("PORT")
        ?.parse()
        .unwrapOr(8080)
    let workers = env.get("WORKERS")
        ?.parse()
        .unwrapOr(4)

    Ok(Config { host, port, workers })
}

5. Parsing and Validation

When converting user input or external data:

fn parseJson(data: String): Result<JsonValue, ParseError> {
    // User data is inherently unreliable
    // Return error, don't panic
    JsonParser.parse(&data)
}

fn parseDate(dateStr: String): Result<Date, ParseError> {
    // User might enter invalid date - expected failure
    Date.parse(&dateStr)
}

Using Nullable Types (T?)

The nullable type T? represents values that might be absent, and it's useful for:

1. Optional Data

When a value might not exist but absence isn't an error:

struct UserProfile {
    name: String,
    email: String,
    phoneNumber: String?,  // Not everyone provides a phone
    bio: String?,           // Bio is optional
}

fn getDisplayName(user: UserProfile): String {
    user.bio ?? "No bio provided".toString()
}

2. Collection Operations

Getting values from collections that might not contain them:

fn getFirstElement<T>(items: Vec<T>): T? {
    items.first()
}

fn getByKey<K, V>(map: HashMap<K, V>, key: K): V? {
    map.get(&key)
}

// Using it:
let users: Vec<User> = vec![...]
if let firstUser = users.first() {
    println!("First user: {}", firstUser.name)
}

3. Graceful Degradation

When you can continue with a default:

fn getUserPreference(userId: String, key: String): String {
    let value = database.getUserPref(userId, key)
    value ?? "default_preference".toString()
}

Decision Tree

Here's a practical decision tree:

Is the error unexpected or indicates a programming bug?
├─ Yes, and continuing would be unsafe/incorrect
│  └─ Use panic! or !!
├─ Yes, but caller should know about it
│  └─ Use Result<T, E>
└─ No, absence is normal and expected
   └─ Use T? or Result/Option

More specifically:

Can callers handle this situation better than you can?
├─ Yes (they have more context)
│  └─ Return Result or use T?
└─ No (it's a fundamental programming error)
   ├─ Is the value missing, or is the entire operation wrong?
   │  ├─ Just missing → Use T?
   │  └─ Operation invalid → Use panic!
   └─ Are you in library code?
      ├─ Yes → Always return Result or T?
      └─ No → panic! is OK if it simplifies code

Pattern: Graceful Error Handling with Three Levels

Many applications use three levels of error handling:

fn main(): Result<(), Box<dyn Error>> {
    let config = loadConfigOrDefault()  // Level 1: Defaults
    let client = createClient(&config)?  // Level 2: Return error
    client.run()                          // Level 3: Panic on unexpected
}

// Level 1: Use ?? for optional configuration
fn loadConfigOrDefault(): Config {
    let configPath = env.var("CONFIG").okOr(()).ok() ?? "config.toml".toString()
    fs.readToString(configPath)
        .ok()
        .flatMap { parseConfig(it) }
        .ok()
        ?? Config.default()
}

// Level 2: Return errors from operations that can fail
fn createClient(config: &Config): Result<Client, Error> {
    let database = Database.connect(&config.dbUrl)?
    let cache = Cache.new(&config.cacheUrl)?
    Ok(Client { database, cache })
}

// Level 3: Panic if invariants are violated
extension Client {
    fn run(): Result<()> {
        guard self.database.isConnected() else {
            panic!("Database connection lost during operation")
        }

        // ... continue
        Ok(())
    }
}

Guidelines Summary

Real-World Examples

Web Server - Mixed Strategies

fn handleRequest(req: HttpRequest): Result<HttpResponse, Box<dyn Error>> {
    // Level 1: Optional headers - use ??
    let contentType = req.header("Content-Type") ?? "application/octet-stream".toString()

    // Level 2: Expected failures - use Result
    let userId = parseUserId(&req.body())?

    // Level 3: Invariants - use expect
    let user = database.findUser(userId)
        .okOr(UserNotFound)?

    // Level 3: Contract violations - panic
    guard user.isActive else {
        panic!("Attempting to process inactive user {}", userId)
    }

    Ok(HttpResponse.ok().body(format!("Hello {}", user.name)))
}

Data Processing - Graceful Degradation

fn processData(input: Vec<DataPoint>): Result<Summary, ProcessError> {
    // Return error if no data - expected failure
    guard !input.isEmpty() else {
        return Err(ProcessError.EmptyInput)
    }

    let results: Vec<Int> = input.iter()
        .map { it.parse() }
        .collect<Result<Vec<Int>, ProcessError>>()?  // Propagate parse errors

    let avg = results.iter().sum<Int>() / results.len() as Int
    let maxValue = results.iter().max()  // Returns Option
        .copied()
        ?? 0  // Default if empty (shouldn't happen after guard, but defensive)

    Ok(Summary { average: avg, maximum: maxValue })
}

Configuration - All Three Levels

struct AppConfig {
    database: String,
    port: Int,
    logLevel: LogLevel,
}

fn loadAppConfig(): AppConfig {
    let dbUrl = env.var("DATABASE_URL")  // Returns Result
        .ok()  // Convert to Option
        ?? "sqlite:memory:".toString()  // Level 1: Default

    let port = env.var("PORT")
        .ok()
        .flatMap { it.parse().ok() }
        ?? 8080  // Level 1: Default

    let logLevel = env.var("LOG_LEVEL")
        .ok()
        .flatMap { LogLevel.parse(it) }
        ?? LogLevel.Info  // Level 1: Default

    AppConfig { database: dbUrl, port, logLevel }
}

fn initializeApp(config: AppConfig): Result<App, Error> {
    let db = Database.connect(&config.database)?  // Level 2: Return error
    let cache = Cache.new()?  // Level 2: Return error
    Ok(App { db, cache, config })
}

extension App {
    fn run(): Result<(), Error> {
        guard self.db.isHealthy() else {
            panic!("Database failed health check before main loop")
        }

        // ... continue with main event loop
        Ok(())
    }
}

Summary

The decision between panic!, Result, and T? is fundamental to Rust/Oxide's error handling philosophy:

1. Default to Result - Especially in library code and functions that can fail for external reasons
2. Use T? - For values that might not exist but absence isn't an error
3. Panic for contracts - When callers violate documented preconditions
4. Expect with explanation - When you know better than the compiler but need to document why
5. Minimize !! - It should be rare in production code

Remember: The goal is to write code that's both safe and clear about what can go wrong and how to handle it. Your error handling strategy is part of your API's contract with users.

Generic Types, Traits, and Lifetimes

Every programming language has tools for effectively handling the duplication of concepts. In Oxide, one such tool is generics: abstract stand-ins for concrete types or other properties. We can express the behavior of generics or how they relate to other generics without knowing what will be in their place when compiling and running the code.

Functions can take parameters of some generic type, instead of a concrete type like Int or String, in the same way they take parameters with unknown values to run the same code on multiple concrete values. In fact, we already used generics in Chapter 6 with Option<T> (written as T? in Oxide), in Chapter 8 with Vec<T> and HashMap<K, V>, and in Chapter 9 with Result<T, E>. In this chapter, you will explore how to define your own types, functions, and methods with generics!

First, we will review how to extract a function to reduce code duplication. We will then use the same technique to make a generic function from two functions that differ only in the types of their parameters. We will also explain how to use generic types in struct and enum definitions.

Then, you will learn how to use traits to define behavior in a generic way. You can combine traits with generic types to constrain a generic type to accept only those types that have a particular behavior, as opposed to just any type.

Finally, we will discuss lifetimes: a variety of generics that give the compiler information about how references relate to each other. Lifetimes allow us to give the compiler enough information about borrowed values so that it can ensure that references will be valid in more situations than it could without our help.

Oxide Syntax vs. Rust

Since Oxide compiles to Rust, the generic syntax is largely the same:

The key difference in Oxide is the extension syntax for implementing traits, which reads more naturally than Rust's impl Trait for Type.

Chapter Structure

We'll take the same approach that the Rust Book does:

1. First, we'll see how to extract functions to reduce duplication
2. Then we'll learn about generic data types for functions, structs, enums, and methods
3. Next, we'll explore traits to define shared behavior
4. We'll use trait bounds to constrain generics
5. Finally, we'll tackle lifetimes and how they interact with generics

Let's dive in!

Removing Duplication by Extracting a Function

Generics allow us to replace specific types with a placeholder that represents multiple types to remove code duplication. Before diving into generics syntax, let's first look at how to remove duplication in a way that doesn't involve generic types by extracting a function that replaces specific values with a placeholder that represents multiple values. Then, we will apply the same technique to extract a generic function! By looking at how to recognize duplicated code you can extract into a function, you will start to recognize duplicated code that can use generics.

We will begin with a short program that finds the largest number in a list:

fn main() {
    let numberList = vec![34, 50, 25, 100, 65]

    var largest = &numberList[0]

    for number in &numberList {
        if number > largest {
            largest = number
        }
    }

    println!("The largest number is \(largest)")
}

We store a list of integers in the variable numberList and place a reference to the first number in the list in a variable named largest. We then iterate through all the numbers in the list, and if the current number is greater than the number stored in largest, we replace the reference in that variable. However, if the current number is less than or equal to the largest number seen so far, the variable doesn't change, and the code moves on to the next number in the list. After considering all the numbers in the list, largest should refer to the largest number, which in this case is 100.

We have now been tasked with finding the largest number in two different lists of numbers. To do so, we can choose to duplicate the code and use the same logic at two different places in the program:

fn main() {
    let numberList = vec![34, 50, 25, 100, 65]

    var largest = &numberList[0]

    for number in &numberList {
        if number > largest {
            largest = number
        }
    }

    println!("The largest number is \(largest)")

    let numberList = vec![102, 34, 6000, 89, 54, 2, 43, 8]

    var largest = &numberList[0]

    for number in &numberList {
        if number > largest {
            largest = number
        }
    }

    println!("The largest number is \(largest)")
}

Although this code works, duplicating code is tedious and error-prone. We also have to remember to update the code in multiple places when we want to change it.

To eliminate this duplication, we will create an abstraction by defining a function that operates on any list of integers passed in as a parameter. This solution makes our code clearer and lets us express the concept of finding the largest number in a list abstractly.

We extract the code that finds the largest number into a function named largest. Then, we call the function to find the largest number in the two lists:

fn largest(list: &[Int]): &Int {
    var largest = &list[0]

    for item in list {
        if item > largest {
            largest = item
        }
    }

    largest
}

fn main() {
    let numberList = vec![34, 50, 25, 100, 65]
    let result = largest(&numberList)
    println!("The largest number is \(result)")

    let numberList = vec![102, 34, 6000, 89, 54, 2, 43, 8]
    let result = largest(&numberList)
    println!("The largest number is \(result)")
}

The largest function has a parameter called list, which represents any concrete slice of Int values we might pass into the function. As a result, when we call the function, the code runs on the specific values that we pass in.

In summary, here are the steps we took to change the code:

1. Identify duplicate code.
2. Extract the duplicate code into the body of the function, and specify the inputs and return values of that code in the function signature.
3. Update the two instances of duplicated code to call the function instead.

Next, we will use these same steps with generics to reduce code duplication. In the same way that the function body can operate on an abstract list instead of specific values, generics allow code to operate on abstract types.

For example, say we had two functions: one that finds the largest item in a slice of Int values and one that finds the largest item in a slice of Char values. How would we eliminate that duplication? Let's find out!

Generic Data Types

We use generics to create definitions for items like function signatures or structs, which we can then use with many different concrete data types. Let's first look at how to define functions, structs, enums, and methods using generics. Then, we will discuss how generics affect code performance.

In Function Definitions

When defining a function that uses generics, we place the generics in the signature of the function where we would usually specify the data types of the parameters and return value. Doing so makes our code more flexible and provides more functionality to callers of our function while preventing code duplication.

Continuing with our largest function, here are two functions that both find the largest value in a slice. We will then combine these into a single function that uses generics.

fn largestInt(list: &[Int]): &Int {
    var largest = &list[0]

    for item in list {
        if item > largest {
            largest = item
        }
    }

    largest
}

fn largestChar(list: &[Char]): &Char {
    var largest = &list[0]

    for item in list {
        if item > largest {
            largest = item
        }
    }

    largest
}

fn main() {
    let numberList = vec![34, 50, 25, 100, 65]
    let result = largestInt(&numberList)
    println!("The largest number is \(result)")

    let charList = vec!['y', 'm', 'a', 'q']
    let result = largestChar(&charList)
    println!("The largest char is \(result)")
}

The largestInt function is the one we extracted previously that finds the largest Int in a slice. The largestChar function finds the largest Char in a slice. The function bodies have the same code, so let's eliminate the duplication by introducing a generic type parameter in a single function.

To parameterize the types in a new single function, we need to name the type parameter, just as we do for the value parameters to a function. You can use any identifier as a type parameter name. But we will use T because, by convention, type parameter names are short, often just one letter, and the type-naming convention is UpperCamelCase. Short for type, T is the default choice of most programmers.

When we use a parameter in the body of the function, we have to declare the parameter name in the signature so that the compiler knows what that name means. Similarly, when we use a type parameter name in a function signature, we have to declare the type parameter name before we use it. To define the generic largest function, we place type name declarations inside angle brackets, <>, between the name of the function and the parameter list, like this:

fn largest<T>(list: &[T]): &T {
    // ...
}

We read this definition as "The function largest is generic over some type T." This function has one parameter named list, which is a slice of values of type T. The largest function will return a reference to a value of the same type T.

Here is the combined largest function definition using the generic data type in its signature. The listing also shows how we can call the function with either a slice of Int values or Char values. Note that this code won't compile yet:

fn largest<T>(list: &[T]): &T {
    var largest = &list[0]

    for item in list {
        if item > largest {
            largest = item
        }
    }

    largest
}

fn main() {
    let numberList = vec![34, 50, 25, 100, 65]
    let result = largest(&numberList)
    println!("The largest number is \(result)")

    let charList = vec!['y', 'm', 'a', 'q']
    let result = largest(&charList)
    println!("The largest char is \(result)")
}

If we compile this code right now, we will get an error:

error[E0369]: binary operation `>` cannot be applied to type `&T`
 --> src/main.rs:5:17
  |
5 |         if item > largest {
  |            ---- ^ ------- &T
  |            |
  |            &T
  |
help: consider restricting type parameter `T`
  |
1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]): &T {
  |             ++++++++++++++++++++++

The help text mentions std.cmp.PartialOrd, which is a trait, and we are going to talk about traits in the next section. For now, know that this error states that the body of largest won't work for all possible types that T could be. Because we want to compare values of type T in the body, we can only use types whose values can be ordered. To enable comparisons, the standard library has the std.cmp.PartialOrd trait that you can implement on types. By restricting T to only those types that implement PartialOrd, the code will compile because the standard library implements PartialOrd on both Int and Char.

In Struct Definitions

We can also define structs to use a generic type parameter in one or more fields using the <> syntax. Here is a Point<T> struct to hold x and y coordinate values of any type:

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let integer = Point { x: 5, y: 10 }
    let float = Point { x: 1.0, y: 4.0 }
}

The syntax for using generics in struct definitions is similar to that used in function definitions. First, we declare the name of the type parameter inside angle brackets just after the name of the struct. Then, we use the generic type in the struct definition where we would otherwise specify concrete data types.

Note that because we have used only one generic type to define Point<T>, this definition says that the Point<T> struct is generic over some type T, and the fields x and y are both that same type, whatever that type may be. If we create an instance of a Point<T> that has values of different types, our code won't compile:

struct Point<T> {
    x: T,
    y: T,
}

fn main() {
    let wontWork = Point { x: 5, y: 4.0 }
}

In this example, when we assign the integer value 5 to x, we let the compiler know that the generic type T will be an integer for this instance of Point<T>. Then, when we specify 4.0 for y, which we have defined to have the same type as x, we will get a type mismatch error like this:

error[E0308]: mismatched types
 --> src/main.rs:7:38
  |
7 |     let wontWork = Point { x: 5, y: 4.0 }
  |                                      ^^^ expected integer, found floating-point number

To define a Point struct where x and y are both generics but could have different types, we can use multiple generic type parameters. For example, we change the definition of Point to be generic over types T and U where x is of type T and y is of type U:

struct Point<T, U> {
    x: T,
    y: U,
}

fn main() {
    let bothInteger = Point { x: 5, y: 10 }
    let bothFloat = Point { x: 1.0, y: 4.0 }
    let integerAndFloat = Point { x: 5, y: 4.0 }
}

Now all the instances of Point shown are allowed! You can use as many generic type parameters in a definition as you want, but using more than a few makes your code hard to read. If you find you need lots of generic types in your code, it could indicate that your code needs restructuring into smaller pieces.

In Enum Definitions

As we did with structs, we can define enums to hold generic data types in their variants. Let's take another look at the Option<T> enum that the standard library provides, which we use through Oxide's T? syntax:

#![allow(unused)]
fn main() {
// This is what Option<T> looks like in Rust
enum Option<T> {
    Some(T),
    None,
}
}

This definition should now make more sense to you. As you can see, the Option<T> enum is generic over type T and has two variants: Some, which holds one value of type T, and a None variant that doesn't hold any value. By using the Option<T> enum (or T? in Oxide), we can express the abstract concept of an optional value, and because Option<T> is generic, we can use this abstraction no matter what the type of the optional value is.

In Oxide, we typically write this using the nullable type syntax:

fn findFirst<T>(items: &[T], predicate: (&T) -> Bool): T? {
    for item in items {
        if predicate(item) {
            return Some(item.clone())
        }
    }
    null
}

Enums can use multiple generic types as well. The definition of the Result enum that we used in Chapter 9 is one example:

enum Result<T, E> {
    Ok(T),
    Err(E),
}

The Result enum is generic over two types, T and E, and has two variants: Ok, which holds a value of type T, and Err, which holds a value of type E. This definition makes it convenient to use the Result enum anywhere we have an operation that might succeed (return a value of some type T) or fail (return an error of some type E). In fact, this is what we used to open a file in Chapter 9, where T was filled in with the type std.fs.File when the file was opened successfully and E was filled in with the type std.io.Error when there were problems opening the file.

When you recognize situations in your code with multiple struct or enum definitions that differ only in the types of the values they hold, you can avoid duplication by using generic types instead.

In Method Definitions

We can implement methods on structs and enums and use generic types in their definitions too. Here is the Point<T> struct with a method named x implemented on it:

struct Point<T> {
    x: T,
    y: T,
}

extension Point<T> {
    fn x(): &T {
        &self.x
    }
}

fn main() {
    let p = Point { x: 5, y: 10 }
    println!("p.x = \(p.x())")
}

Here, we have defined a method named x on Point<T> that returns a reference to the data in the field x.

Note that we have to declare T just after extension so that we can use T to specify that we are implementing methods on the type Point<T>. By declaring T as a generic type after extension, Oxide can identify that the type in the angle brackets in Point is a generic type rather than a concrete type. We could have chosen a different name for this generic parameter than the generic parameter declared in the struct definition, but using the same name is conventional.

Rust Equivalent

The Oxide code above translates to this Rust code:

#![allow(unused)]
fn main() {
struct Point<T> {
    x: T,
    y: T,
}

impl<T> Point<T> {
    fn x(&self) -> &T {
        &self.x
    }
}
}

We can also specify constraints on generic types when defining methods on the type. We could, for example, implement methods only on Point<Float> instances rather than on Point<T> instances with any generic type. Here we use the concrete type Float, meaning we don't declare any types after extension:

extension Point<Float> {
    fn distanceFromOrigin(): Float {
        (self.x.powi(2) + self.y.powi(2)).sqrt()
    }
}

This code means the type Point<Float> will have a distanceFromOrigin method; other instances of Point<T> where T is not of type Float will not have this method defined. The method measures how far our point is from the point at coordinates (0.0, 0.0) and uses mathematical operations that are available only for floating-point types.

Generic type parameters in a struct definition aren't always the same as those you use in that same struct's method signatures. Here is an example that uses the generic types X1 and Y1 for the Point struct and X2 and Y2 for the mixup method signature to make the example clearer:

struct Point<X1, Y1> {
    x: X1,
    y: Y1,
}

extension Point<X1, Y1> {
    fn mixup<X2, Y2>(other: Point<X2, Y2>): Point<X1, Y2> {
        Point {
            x: self.x,
            y: other.y,
        }
    }
}

fn main() {
    let p1 = Point { x: 5, y: 10.4 }
    let p2 = Point { x: "Hello", y: 'c' }

    let p3 = p1.mixup(p2)

    println!("p3.x = \(p3.x), p3.y = \(p3.y)")
}

In main, we have defined a Point that has an Int for x (with value 5) and a Float for y (with value 10.4). The p2 variable is a Point struct that has a string slice for x (with value "Hello") and a Char for y (with value 'c'). Calling mixup on p1 with the argument p2 gives us p3, which will have an Int for x because x came from p1. The p3 variable will have a Char for y because y came from p2. The println! macro call will print p3.x = 5, p3.y = c.

The purpose of this example is to demonstrate a situation in which some generic parameters are declared with extension and some are declared with the method definition. Here, the generic parameters X1 and Y1 are declared after extension because they go with the struct definition. The generic parameters X2 and Y2 are declared after fn mixup because they are only relevant to the method.

Performance of Code Using Generics

You might be wondering whether there is a runtime cost when using generic type parameters. The good news is that using generic types won't make your program run any slower than it would with concrete types.

Oxide and Rust accomplish this by performing monomorphization of the code using generics at compile time. Monomorphization is the process of turning generic code into specific code by filling in the concrete types that are used when compiled. In this process, the compiler does the opposite of the steps we used to create the generic function: The compiler looks at all the places where generic code is called and generates code for the concrete types the generic code is called with.

Let's look at how this works by using the standard library's generic Option<T> enum:

let integer: Int? = Some(5)
let float: Float? = Some(5.0)

When Oxide compiles this code, it performs monomorphization. During that process, the compiler reads the values that have been used in Option<T> instances and identifies two kinds of Option<T>: One is Int and the other is Float. As such, it expands the generic definition of Option<T> into two definitions specialized to Int and Float, thereby replacing the generic definition with the specific ones.

The monomorphized version of the code looks similar to the following (the compiler uses different names than what we're using here for illustration):

enum OptionInt {
    Some(Int),
    None,
}

enum OptionFloat {
    Some(Float),
    None,
}

fn main() {
    let integer = OptionInt.Some(5)
    let float = OptionFloat.Some(5.0)
}

The generic Option<T> is replaced with the specific definitions created by the compiler. Because Oxide compiles generic code into code that specifies the type in each instance, we pay no runtime cost for using generics. When the code runs, it performs just as it would if we had duplicated each definition by hand. The process of monomorphization makes generics extremely efficient at runtime.

Traits: Defining Shared Behavior

A trait defines the functionality a particular type has and can share with other types. We can use traits to define shared behavior in an abstract way. We can use trait bounds to specify that a generic type can be any type that has certain behavior.

Note: Traits are similar to a feature often called interfaces in other languages, although with some differences.

Defining a Trait

A type's behavior consists of the methods we can call on that type. Different types share the same behavior if we can call the same methods on all of those types. Trait definitions are a way to group method signatures together to define a set of behaviors necessary to accomplish some purpose.

For example, let's say we have multiple structs that hold various kinds and amounts of text: a NewsArticle struct that holds a news story filed in a particular location and a SocialPost that can have, at most, 280 characters along with metadata that indicates whether it was a new post, a repost, or a reply to another post.

We want to make a media aggregator library crate named aggregator that can display summaries of data that might be stored in a NewsArticle or SocialPost instance. To do this, we need a summary from each type, and we will request that summary by calling a summarize method on an instance. Here is the definition of a public Summary trait that expresses this behavior:

public trait Summary {
    fn summarize(): String
}

Here, we declare a trait using the trait keyword and then the trait's name, which is Summary in this case. We also declare the trait as public so that crates depending on this crate can make use of this trait too, as we will see in a few examples. Inside the curly brackets, we declare the method signatures that describe the behaviors of the types that implement this trait, which in this case is fn summarize(): String.

After the method signature, instead of providing an implementation within curly brackets, we use a semicolon. Each type implementing this trait must provide its own custom behavior for the body of the method. The compiler will enforce that any type that has the Summary trait will have the method summarize defined with this signature exactly.

A trait can have multiple methods in its body: The method signatures are listed one per line, and each line ends in a semicolon.

Rust Equivalent

The Oxide trait definition above translates to this Rust code:

#![allow(unused)]
fn main() {
pub trait Summary {
    fn summarize(&self) -> String;
}
}

Note that in Oxide, trait methods use the same receiver modifiers as methods in extension blocks: fn implies &self, mutating fn implies &mut self, consuming fn implies self, and static fn has no receiver.

Implementing a Trait on a Type

Now that we have defined the desired signatures of the Summary trait's methods, we can implement it on the types in our media aggregator. In Oxide, we use extension Type: Trait syntax to implement a trait on a type:

public struct NewsArticle {
    public headline: String,
    public location: String,
    public author: String,
    public content: String,
}

extension NewsArticle: Summary {
    fn summarize(): String {
        "\(self.headline), by \(self.author) (\(self.location))"
    }
}

public struct SocialPost {
    public username: String,
    public content: String,
    public reply: Bool,
    public repost: Bool,
}

extension SocialPost: Summary {
    fn summarize(): String {
        "\(self.username): \(self.content)"
    }
}

Implementing a trait on a type is similar to implementing regular methods. The difference is that after extension, we put the type name, then a colon, then the trait name we want to implement. Within the extension block, we put the method signatures that the trait definition has defined and fill in the method body with the specific behavior that we want the methods of the trait to have for the particular type.

Now that the library has implemented the Summary trait on NewsArticle and SocialPost, users of the crate can call the trait methods on instances of NewsArticle and SocialPost in the same way we call regular methods. The only difference is that the user must bring the trait into scope as well as the types. Here is an example of how a binary crate could use our aggregator library crate:

import aggregator.{ Summary, SocialPost }

fn main() {
    let post = SocialPost {
        username: "horse_ebooks".toString(),
        content: "of course, as you probably already know, people".toString(),
        reply: false,
        repost: false,
    }

    println!("1 new post: \(post.summarize())")
}

This code prints 1 new post: horse_ebooks: of course, as you probably already know, people.

Rust Equivalent

The Oxide trait implementation above translates to this Rust code:

#![allow(unused)]
fn main() {
impl Summary for NewsArticle {
    fn summarize(&self) -> String {
        format!("{}, by {} ({})", self.headline, self.author, self.location)
    }
}

impl Summary for SocialPost {
    fn summarize(&self) -> String {
        format!("{}: {}", self.username, self.content)
    }
}
}

Note that in Rust, the syntax is impl Trait for Type, while in Oxide it's extension Type: Trait. The Oxide syntax reads naturally as "extend Type with Trait capability."

Coherence and the Orphan Rule

One restriction to note is that we can implement a trait on a type only if either the trait or the type, or both, are local to our crate. For example, we can implement standard library traits like Display on a custom type like SocialPost as part of our aggregator crate functionality because the type SocialPost is local to our aggregator crate. We can also implement Summary on Vec<T> in our aggregator crate because the trait Summary is local to our aggregator crate.

But we can't implement external traits on external types. For example, we can't implement the Display trait on Vec<T> within our aggregator crate, because Display and Vec<T> are both defined in the standard library and aren't local to our aggregator crate. This restriction is part of a property called coherence, and more specifically the orphan rule, so named because the parent type is not present. This rule ensures that other people's code can't break your code and vice versa. Without the rule, two crates could implement the same trait for the same type, and the compiler wouldn't know which implementation to use.

Default Implementations

Sometimes it's useful to have default behavior for some or all of the methods in a trait instead of requiring implementations for all methods on every type. Then, as we implement the trait on a particular type, we can keep or override each method's default behavior.

Here we specify a default string for the summarize method of the Summary trait instead of only defining the method signature:

public trait Summary {
    fn summarize(): String {
        "(Read more...)".toString()
    }
}

To use a default implementation to summarize instances of NewsArticle, we specify an empty extension block with extension NewsArticle: Summary {}.

Even though we are no longer defining the summarize method on NewsArticle directly, we have provided a default implementation and specified that NewsArticle implements the Summary trait. As a result, we can still call the summarize method on an instance of NewsArticle, like this:

let article = NewsArticle {
    headline: "Penguins win the Stanley Cup Championship!".toString(),
    location: "Pittsburgh, PA, USA".toString(),
    author: "Iceburgh".toString(),
    content: "The Pittsburgh Penguins once again are the best \
              hockey team in the NHL.".toString(),
}

println!("New article available! \(article.summarize())")

This code prints New article available! (Read more...).

Creating a default implementation doesn't require us to change anything about the implementation of Summary on SocialPost. The reason is that the syntax for overriding a default implementation is the same as the syntax for implementing a trait method that doesn't have a default implementation.

Default implementations can call other methods in the same trait, even if those other methods don't have a default implementation. In this way, a trait can provide a lot of useful functionality and only require implementors to specify a small part of it. For example, we could define the Summary trait to have a summarizeAuthor method whose implementation is required, and then define a summarize method that has a default implementation that calls the summarizeAuthor method:

public trait Summary {
    fn summarizeAuthor(): String

    fn summarize(): String {
        "(Read more from \(self.summarizeAuthor())...)".toString()
    }
}

To use this version of Summary, we only need to define summarizeAuthor when we implement the trait on a type:

extension SocialPost: Summary {
    fn summarizeAuthor(): String {
        "@\(self.username)".toString()
    }
}

After we define summarizeAuthor, we can call summarize on instances of the SocialPost struct, and the default implementation of summarize will call the definition of summarizeAuthor that we have provided:

let post = SocialPost {
    username: "horse_ebooks".toString(),
    content: "of course, as you probably already know, people".toString(),
    reply: false,
    repost: false,
}

println!("1 new post: \(post.summarize())")

This code prints 1 new post: (Read more from @horseEbooks...).

Note that it isn't possible to call the default implementation from an overriding implementation of that same method.

Traits as Parameters

Now that you know how to define and implement traits, we can explore how to use traits to define functions that accept many different types. We will use the Summary trait we implemented on the NewsArticle and SocialPost types to define a notify function that calls the summarize method on its item parameter, which is of some type that implements the Summary trait. In Oxide, we express this using a trait bound on a generic type:

public fn notify<T: Summary>(item: &T) {
    println!("Breaking news! \(item.summarize())")
}

This parameter accepts any type that implements the specified trait. In the body of notify, we can call any methods on item that come from the Summary trait, such as summarize. We can call notify and pass in any instance of NewsArticle or SocialPost. Code that calls the function with any other type, such as a String or an Int, won't compile because those types don't implement Summary.

Trait Bound Syntax

Trait bounds can also express more complex cases. For example, we can have two parameters that each implement Summary but are allowed to be different types:

public fn notify<T: Summary, U: Summary>(item1: &T, item2: &U) {
    // ...
}

If we want to force both parameters to have the same type, we use a single generic parameter:

public fn notify<T: Summary>(item1: &T, item2: &T) {
    // ...
}

The generic type T specified as the type of the item1 and item2 parameters constrains the function such that the concrete type of the value passed as an argument for item1 and item2 must be the same.

Specifying Multiple Trait Bounds with the + Syntax

We can also specify more than one trait bound. Say we wanted notify to use display formatting as well as summarize on item: We specify in the notify definition that item must implement both Display and Summary. We do so using the + syntax on the trait bound:

public fn notify<T: Summary + Display>(item: &T) {
    // ...
}

With the two trait bounds specified, the body of notify can call summarize and use {} to format item.

Clearer Trait Bounds with where Clauses

Using too many trait bounds has its downsides. Each generic has its own trait bounds, so functions with multiple generic type parameters can contain lots of trait bound information between the function's name and its parameter list, making the function signature hard to read. For this reason, Oxide (like Rust) has alternate syntax for specifying trait bounds inside a where clause after the function signature. So, instead of writing this:

fn someFunction<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U): Int {
    // ...
}

we can use a where clause, like this:

fn someFunction<T, U>(t: &T, u: &U): Int
where
    T: Display + Clone,
    U: Clone + Debug,
{
    // ...
}

This function's signature is less cluttered: The function name, parameter list, and return type are close together, similar to a function without lots of trait bounds.

Returning Types That Implement Traits

In Oxide, you can hide a concrete return type with impl Trait when the function always returns a single concrete type:

fn returnsSummarizable(): impl Summary {
    SocialPost {
        username: "horse_ebooks".toString(),
        content: "of course, as you probably already know, people".toString(),
        reply: false,
        repost: false,
    }
}

When you need to return different concrete types, use a trait object. A trait object is a value like Box<dyn Summary> that can hold any type implementing the trait.

fn returnsSummarizable(switch: Bool): Box<dyn Summary> {
    if switch {
        Box.new(NewsArticle {
            headline: "Penguins win the Stanley Cup Championship!".toString(),
            location: "Pittsburgh, PA, USA".toString(),
            author: "Iceburgh".toString(),
            content: "The Pittsburgh Penguins once again are the best \
                      hockey team in the NHL.".toString(),
        })
    } else {
        Box.new(SocialPost {
            username: "horse_ebooks".toString(),
            content: "of course, as you probably already know, people".toString(),
            reply: false,
            repost: false,
        })
    }
}

Because the return type is a trait object, the caller does not need to know the concrete type. This is especially useful for closures and iterators, which often have compiler-generated types that are difficult to name.

We will cover trait objects in detail in Chapter 18.

Using Trait Bounds to Conditionally Implement Methods

By using a trait bound with an extension block that uses generic type parameters, we can implement methods conditionally for types that implement the specified traits. For example, the type Pair<T> always implements the new function to return a new instance of Pair<T>. But Pair<T> only implements the cmpDisplay method if its inner type T implements the PartialOrd trait that enables comparison and the Display trait that enables printing:

struct Pair<T> {
    x: T,
    y: T,
}

extension Pair<T> {
    static fn new(x: T, y: T): Self {
        Self { x, y }
    }
}

extension Pair<T>
where
    T: Display + PartialOrd,
{
    fn cmpDisplay() {
        if self.x >= self.y {
            println!("The largest member is x = \(self.x)")
        } else {
            println!("The largest member is y = \(self.y)")
        }
    }
}

We can also conditionally implement a trait for any type that implements another trait. Implementations of a trait on any type that satisfies the trait bounds are called blanket implementations and are used extensively in the standard library. For example, the standard library implements the ToString trait on any type that implements the Display trait. The extension block in the standard library looks similar to this code:

extension<T: Display> T: ToString {
    // --snip--
}

Because the standard library has this blanket implementation, we can call the toString method defined by the ToString trait on any type that implements the Display trait. For example, we can turn integers into their corresponding String values like this because integers implement Display:

let s = 3.toString()

Blanket implementations appear in the documentation for the trait in the "Implementors" section.

Traits and trait bounds let us write code that uses generic type parameters to reduce duplication but also specify to the compiler that we want the generic type to have particular behavior. The compiler can then use the trait bound information to check that all the concrete types used with our code provide the correct behavior. In dynamically typed languages, we would get an error at runtime if we called a method on a type that didn't define the method. But Oxide moves these errors to compile time so that we are forced to fix the problems before our code is even able to run. Additionally, we don't have to write code that checks for behavior at runtime because we have already checked at compile time. Doing so improves performance without having to give up the flexibility of generics.

Lifetimes: Validating References with Lifetimes

One detail we didn't discuss in Chapter 4 is that every reference in Oxide has a lifetime, which is the scope for which that reference is valid. Most of the time, lifetimes are implicit and inferred, just like most of the time, types are inferred. But just as we sometimes must annotate types when multiple types are possible, we must annotate lifetimes when the lifetimes of references could be related in a few different ways.

Oxide requires us to annotate the relationships using generic lifetime parameters to ensure the actual references used at runtime will definitely be valid.

Preventing Dangling References with Lifetimes

The main aim of lifetimes is to prevent dangling references, which cause a program to reference data other than the data it's intended to reference. Consider this pseudocode, where we explicitly show the lifetime of a reference:

{
    let r: &Int // lifetime must satisfy: 'a

    {
        let x = 5
        r = &x // x has lifetime 'b
    } // x is dropped here, ending 'b

    println!("{}", r) // r still tries to use x here, but x no longer exists!
}

In this example, r tries to reference an Int (x) that goes out of scope before we try to use the reference. The variable x doesn't live long enough. The reason is that x will be dropped when the inner scope ends, but r will still be referring to that location in memory.

Oxide's borrow checker prevents this problem from compiling. Let's look at how lifetimes help us write valid code.

The Borrow Checker

Oxide's compiler has a borrow checker that compares scopes to determine whether all borrows are valid. Here's the logic:

1. Each reference has a lifetime that corresponds to the scope of the code it's being used in
2. You cannot borrow a value for a lifetime that outlives the value
3. The compiler will reject your code if it violates these rules

Let's look at an example where the borrow checker catches a dangling reference:

fn main() {
    let r: &Int

    {
        let x = 5
        r = &x
    }

    println!("r: {}", r) // error: `x` does not live long enough
}

When we compile this code, Oxide will give us an error:

error[E0597]: `x` does not live long enough
 --> src/main.rs:8:13
  |
7 |         r = &x;
  |             ^^ borrowed value does not live long enough
8 |     }
  |     - `x` dropped here while still borrowed
9 |
10 |     println!("r: {}", r);
       |                     - borrow later used here

The variable r has a reference to x, but x goes out of scope right away. So r will be referencing memory that no longer contains valid data. This is a classic memory safety issue that Oxide prevents at compile time.

Lifetime Annotations in Function Signatures

In most cases, lifetimes are implicit. However, when a function returns a reference, we need to specify which input parameter's lifetime the returned reference is tied to. We do this with lifetime annotations.

Lifetime annotations use the syntax 'a (pronounced "lifetime a"). Let's look at an example:

fn longest<'a>(x: &'a String, y: &'a String): &'a String {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

This function compares two string slices and returns the longer one. The lifetime annotation 'a tells the compiler:

• The function takes two parameters that are references with lifetime 'a
• The function returns a reference with the same lifetime 'a
• The returned reference will be valid as long as both input references are valid

Let's examine what happens without the lifetime annotations:

fn longest(x: &String, y: &String): &String {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

The compiler can't tell which input parameter the return reference relates to. It could be x or y. So we get an error:

error[E0106]: missing lifetime specifier
 --> src/main.rs:1:33
  |
1 | fn longest(x: &String, y: &String): &String {
  |               -------       -------          ^ expected lifetime parameter
  |

Let's use our annotated version correctly:

fn longest<'a>(x: &'a String, y: &'a String): &'a String {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

fn main() {
    let string1 = "abracadabra".toString()
    let string2 = "xyz".toString()
    let result = longest(&string1, &string2)
    println!("The longest string is '{}'", result)
}

This code compiles because:

• Both string1 and string2 are in the main function's scope
• We return a reference to one of them
• That reference will be valid as long as both input references are valid
• When we print result, both string1 and string2 still exist

But this wouldn't work:

fn longest<'a>(x: &'a String, y: &'a String): &'a String {
    if x.len() > y.len() {
        x
    } else {
        y
    }
}

fn main() {
    let string1 = "long string".toString()

    let result: &String
    {
        let string2 = "xyz".toString()
        result = longest(&string1, &string2)
    }

    println!("The longest string is '{}'", result)
}

The problem is:

• string2 goes out of scope at the end of the inner block
• But result might reference string2
• The lifetime annotation says the return reference must be valid as long as both inputs
• Since string2 becomes invalid before we use result, this is an error

Lifetime Annotations in Struct Definitions

We can also use lifetime annotations in struct definitions when a struct holds references:

struct ImportantExcerpt<'a> {
    part: &'a String,
}

fn main() {
    let novel = "Call me Ishmael. Some years ago...".toString()
    let firstSentence = novel.split('.').next() ?? ""
    let excerpt = ImportantExcerpt { part: &firstSentence }
}

The lifetime annotation 'a means that the ImportantExcerpt struct can hold a reference to a String, and that reference must live at least as long as the ImportantExcerpt instance.

This struct can't outlive the reference it holds:

struct ImportantExcerpt<'a> {
    part: &'a String,
}

fn main() {
    let excerpt: ImportantExcerpt

    {
        let novel = "Call me Ishmael. Some years ago...".toString()
        excerpt = ImportantExcerpt { part: &novel }
    }

    println!("{}", excerpt.part) // error: `novel` does not live long enough
}

The Three Lifetime Rules

The borrow checker uses three rules to determine whether borrows are valid.

Rule 1: Each reference has its own lifetime

Each time you have a reference, it has an associated lifetime. For example:

fn foo<'a>(x: &'a Int) { }
fn bar<'a, 'b>(x: &'a Int, y: &'b Int) { }

Each parameter gets its own lifetime variable.

Rule 2: Return lifetimes must relate to input lifetimes

If a function takes references as parameters and returns a reference, the return type's lifetime must relate to the lifetimes of the input parameters:

fn foo<'a>(x: &'a Int, y: &Int): &'a Int { }

Here, the return value's lifetime is tied to x's lifetime, not y's. This means the returned reference is valid as long as x is valid.

Rule 3: Methods use &self's lifetime

For methods (in extension blocks), the returned reference's lifetime is implicitly tied to &self:

extension ImportantExcerpt<'a> {
    fn announceAuthor() {
        println!("Attention please: {}", self.part)
    }
}

This is equivalent to:

extension ImportantExcerpt<'a> {
    fn announceAuthor() {
        println!("Attention please: {}", self.part)
    }
}

Lifetime Elision

Because the rules are common, Oxide (like Rust) allows you to omit lifetime annotations in many cases. This is called lifetime elision. The compiler will infer the lifetimes for you automatically in these situations:

Elision works for input references

If there's only one input reference, its lifetime is automatically used for all outputs:

// You can write this...
fn firstWord(s: &String): &String {
    let bytes = s.asBytes()
    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i]
        }
    }
    &s[..]
}

// Without specifying: fn firstWord<'a>(s: &'a String): &'a String { }
// The compiler figures it out!

Elision works for methods

Methods always have an implicit &self lifetime:

struct Excerpt {
    text: String,
}

extension Excerpt {
    fn returnText(): &String {
        &self.text
    }
}

// Implicit: fn returnText<'a>(&'a self): &'a String { }

Combining Lifetimes with Generics and Traits

You can combine lifetimes with generic type parameters and trait bounds:

fn longest<'a, T: PartialOrd + Display>(x: &'a T, y: &'a T): &'a T {
    if x > y {
        println!("x is larger: {}", x)
        x
    } else {
        println!("y is larger: {}", y)
        y
    }
}

This function takes two generic parameters with the same lifetime, compares them, and returns a reference with that lifetime.

Here's a more complex example with trait bounds and lifetimes:

struct Pair<'a, T> {
    items: &'a [T],
}

extension<'a, T> Pair<'a, T> {
    fn first(): T? {
        self.items.first().cloned()
    }
}

Static Lifetime

The 'static lifetime is a special lifetime that means the reference is valid for the entire duration of the program. All string literals have the 'static lifetime:

let s: &'static String = "Hello, world!"

String literals are baked directly into the program's binary, so they're always available.

You'll often see 'static bounds on types when you want to ensure they own their data:

fn printIt<T: std.fmt.Display + 'static>(t: T) {
    println!("{}", t)
}

This says T must implement Display and must not contain any borrowed references.

Advanced Lifetime Patterns

Higher-Ranked Trait Bounds

Sometimes you need to specify that a function accepts references with any lifetime. This uses for<'a> syntax:

fn acceptAnyLifetime<F>(f: F)
where
    F: for<'a> Fn(&'a Int) -> &'a Int,
{
    // f works with references of any lifetime
}

Lifetime Subtyping

A longer lifetime is a subtype of a shorter lifetime:

fn demo<'a, 'b>(x: &'a Int): &'b Int
where
    'a: 'b, // 'a outlives 'b
{
    x
}

The constraint 'a: 'b means 'a outlives 'b, so we can treat a &'a Int as a &'b Int.

Common Lifetime Mistakes

Mistake 1: Returning a reference to a local variable

fn badFunction(): &String {
    let s = "hello".toString()
    &s // Error: `s` does not live long enough
}

Solution: Return owned data instead:

fn goodFunction(): String {
    let s = "hello".toString()
    s
}

Mistake 2: Mismatching input and output lifetimes

fn problem<'a, 'b>(x: &'a String): &'b String {
    x // Error: lifetime mismatch
}

Solution: Make sure the output lifetime matches an input:

fn fixed<'a>(x: &'a String): &'a String {
    x
}

Summary

Lifetimes are Oxide's way of ensuring that references are always valid. While the syntax can seem intimidating at first, the rules are logical:

1. Every reference has a lifetime
2. Function signatures must make the relationship between input and output lifetimes explicit
3. The compiler will reject code where references might outlive the data they point to

In practice, you'll rarely need to write lifetime annotations because:

• Single input references automatically determine output lifetime
• Methods automatically use &self's lifetime
• The compiler will tell you exactly where you need them

With lifetimes, Oxide ensures memory safety without garbage collection or runtime overhead. This is one of the most powerful features of the language!

Comparison with Rust

Oxide's lifetime syntax is identical to Rust's because lifetimes are a fundamental part of the compiler's borrow checking algorithm. The only difference is in how method syntax works, but the lifetime rules remain exactly the same.

Both Oxide and Rust use the same three rules for lifetime elision and the same mechanisms for explicit annotation. If you understand lifetimes in Oxide, you understand them in Rust as well!

Writing Automated Tests

Testing in Oxide follows Rust's model: you write test functions annotated with #[test] and run them with cargo test. Assertions are provided by the standard library.

What You'll Learn

• How to write and run tests
• How to organize tests within a crate
• How to use common assertions

A Small Example

fn addTwo(value: Int): Int {
    value + 2
}

#[test]
fn addsTwo() {
    let result = addTwo(40)
    assertEq!(result, 42)
}

The next sections dig into test organization, runtime options, and best practices for building reliable code.

How to Write Tests

Rust includes first-class support for writing automated tests, and Oxide inherits this capability with the same syntax. Tests are Oxide functions annotated with the #[test] attribute that verify your code behaves as expected.

The Anatomy of a Test Function

A test in Oxide is a function annotated with #[test]. When you run cargo test, Cargo builds a test runner binary that runs all functions marked with this attribute and reports whether each test passes or fails.

Let's create a new library project to explore testing:

cargo new adder --lib
cd adder

Cargo automatically generates a test module in src/lib.ox:

public fn add(left: UIntSize, right: UIntSize): UIntSize {
    left + right
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn itWorks() {
        let result = add(2, 2)
        assertEq!(result, 4)
    }
}

Let's examine this code:

• The #[test] attribute marks itWorks as a test function
• The #[cfg(test)] attribute tells Oxide to compile this module only when running tests
• Inside tests, we import everything from the parent module with import super.*
• The assertEq! macro checks that two values are equal

Run the tests with:

cargo test

Output:

running 1 test
test tests.itWorks ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Note that even though we named our function itWorks in camelCase, Oxide will map it to snake_case when crossing into Rust. This is Oxide's automatic case conversion at work.

Adding More Tests

Let's add more tests to understand how test failures work:

public fn add(left: UIntSize, right: UIntSize): UIntSize {
    left + right
}

public fn multiply(a: Int, b: Int): Int {
    a * b
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn itWorks() {
        let result = add(2, 2)
        assertEq!(result, 4)
    }

    #[test]
    fn multiplicationWorks() {
        let result = multiply(3, 4)
        assertEq!(result, 12)
    }

    #[test]
    fn anotherTest() {
        let result = add(10, 5)
        assertEq!(result, 15)
    }
}

Running cargo test:

running 3 tests
test tests.anotherTest ... ok
test tests.itWorks ... ok
test tests.multiplicationWorks ... ok

test result: ok. 3 passed; 0 failed; 0 ignored

What Happens When Tests Fail

Tests fail when the test function panics. Each test runs in its own thread, and when the main thread sees that a test thread has died, the test is marked as failed.

Let's add a failing test:

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn thisFails() {
        let expected = 5
        let actual = 2 + 2
        assertEq!(expected, actual, "Math is broken!")
    }
}

Output:

running 1 test
test tests.thisFails ... FAILED

failures:

---- tests.thisFails stdout ----
thread 'tests.thisFails' panicked at src/lib.ox:15:9:
assertion `left == right` failed: Math is broken!
  left: 5
 right: 4

failures:
    tests.thisFails

test result: FAILED. 0 passed; 1 failed; 0 ignored

The output shows exactly where the assertion failed and what values were compared.

Checking Results with assert! Macros

The standard library provides several assertion macros for testing.

assert! Macro

The assert! macro checks that a condition is true. If false, it panics:

#[derive(Debug)]
struct Rectangle {
    width: Int,
    height: Int,
}

extension Rectangle {
    fn canHold(other: &Rectangle): Bool {
        self.width > other.width && self.height > other.height
    }
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn largerCanHoldSmaller() {
        let larger = Rectangle { width: 8, height: 7 }
        let smaller = Rectangle { width: 5, height: 1 }

        assert!(larger.canHold(&smaller))
    }

    #[test]
    fn smallerCannotHoldLarger() {
        let larger = Rectangle { width: 8, height: 7 }
        let smaller = Rectangle { width: 5, height: 1 }

        assert!(!smaller.canHold(&larger))
    }
}

assertEq! and assertNe! Macros

These macros compare two values for equality or inequality:

public fn addTwo(a: Int): Int {
    a + 2
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn itAddsTwoEqual() {
        assertEq!(4, addTwo(2))
    }

    #[test]
    fn itAddsTwoNotEqual() {
        assertNe!(5, addTwo(2))
    }
}

When these assertions fail, they print both values, making it easy to see what went wrong:

assertion `left == right` failed
  left: 4
 right: 5

Important: Values compared with assertEq! and assertNe! must implement the PartialEq and Debug traits. For custom types, derive these traits:

#[derive(Debug, PartialEq)]
struct Point {
    x: Int,
    y: Int,
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn pointsAreEqual() {
        let p1 = Point { x: 3, y: 4 }
        let p2 = Point { x: 3, y: 4 }
        assertEq!(p1, p2)
    }
}

Adding Custom Failure Messages

You can add custom messages to assertion macros:

public fn greeting(name: &str): String {
    format!("Hello, \(name)!")
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn greetingContainsName() {
        let result = greeting("Carol")
        assert!(
            result.contains("Carol"),
            "Greeting did not contain name, value was `\(result)`"
        )
    }
}

If the test fails, the custom message appears:

thread 'tests.greetingContainsName' panicked at src/lib.ox:14:9:
Greeting did not contain name, value was `Hello, Carol!`

Testing for Panics with #[shouldPanic]

Sometimes you want to verify that code panics under certain conditions. Use the #[shouldPanic] attribute:

public struct Guess {
    value: Int,
}

extension Guess {
    public static fn new(value: Int): Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got \(value)")
        }
        Guess { value }
    }
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    #[should_panic]
    fn greaterThan100() {
        Guess.new(200)
    }
}

This test passes because the code panics as expected.

Expected Panic Messages

To ensure tests don't pass for the wrong reason, add an expected parameter:

extension Guess {
    public static fn new(value: Int): Guess {
        if value < 1 {
            panic!("Guess value must be greater than or equal to 1, got \(value)")
        } else if value > 100 {
            panic!("Guess value must be less than or equal to 100, got \(value)")
        }
        Guess { value }
    }
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    #[should_panic(expected = "less than or equal to 100")]
    fn greaterThan100() {
        Guess.new(200)
    }
}

The test passes only if the panic message contains the expected substring.

Using Result<T, E> in Tests

Tests can also return Result<T, E>, which lets you use the ? operator:

#[cfg(test)]
module tests {
    #[test]
    fn itWorks(): Result<(), String> {
        if 2 + 2 == 4 {
            Ok(())
        } else {
            Err("two plus two does not equal four".toString())
        }
    }
}

With Result, you can write more ergonomic tests:

#[cfg(test)]
module tests {
    import std.num.ParseIntError

    #[test]
    fn parseAndAdd(): Result<(), ParseIntError> {
        let a = "10".parse<Int>()?
        let b = "20".parse<Int>()?
        assertEq!(a + b, 30)
        Ok(())
    }
}

Note: You cannot use #[shouldPanic] on tests that return Result<T, E>. To assert that an operation returns an Err, use assert!(result.isErr()) instead.

Testing Optional Values

Oxide's nullable types integrate naturally with tests:

fn findItem(items: &Vec<Int>, target: Int): Int? {
    for item in items.iter() {
        if *item == target {
            return Some(*item)
        }
    }
    null
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn findsExistingItem() {
        let items = vec![1, 2, 3, 4, 5]
        let result = findItem(&items, 3)

        assert!(result.isSome())
        assertEq!(result!!, 3)
    }

    #[test]
    fn returnsNullForMissing() {
        let items = vec![1, 2, 3]
        let result = findItem(&items, 10)

        assert!(result.isNone())
    }

    #[test]
    fn usesNullCoalescing() {
        let items = vec![1, 2, 3]
        let result = findItem(&items, 10) ?? -1

        assertEq!(result, -1)
    }
}

Summary

Oxide tests use the same testing infrastructure as Rust:

• Mark test functions with #[test]
• Use #[cfg(test)] to compile test modules only during testing
• Use assert!, assertEq!, and assertNe! for assertions
• Add custom messages to explain failures
• Use #[shouldPanic] to test for expected panics
• Return Result<T, E> to use the ? operator in tests
• Derive Debug and PartialEq for types you want to compare

The next section covers how to control test execution.

Controlling How Tests Are Run

Just as cargo run compiles and runs your code, cargo test compiles your code in test mode and runs the resulting test binary. The default behavior is to run all tests in parallel and capture output. You can customize this behavior with command line options.

Command Line Options

Some options go to cargo test, and some go to the test binary. To separate them, use --:

cargo test --help        # Options for cargo test
cargo test -- --help     # Options for the test binary

Running Tests in Parallel or Consecutively

By default, tests run in parallel using threads. This makes tests complete faster but means they should not depend on each other or share mutable state.

If your tests depend on shared state, run them consecutively:

cargo test -- --test-threads=1

This sets the number of test threads to 1, running tests one at a time.

Showing Function Output

By default, successful tests capture any println! output. If a test passes, you won't see its printed output. Only failing tests show their output.

To see output from passing tests:

cargo test -- --show-output

Example:

fn printsAndReturnsValue(a: Int): Int {
    println!("I got the value \(a)")
    a
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn thisPasses() {
        let value = printsAndReturnsValue(4)
        assertEq!(value, 4)
    }

    #[test]
    fn thisFails() {
        let value = printsAndReturnsValue(8)
        assertEq!(value, 5)
    }
}

Running cargo test:

running 2 tests
test tests.thisPasses ... ok
test tests.thisFails ... FAILED

failures:

---- tests.thisFails stdout ----
I got the value 8
thread 'tests.thisFails' panicked at src/lib.ox:17:9:
assertion `left == right` failed
  left: 8
 right: 5

Notice only the failing test shows its println! output.

Running cargo test -- --show-output:

running 2 tests
test tests.thisFails ... FAILED
test tests.thisPasses ... ok

successes:

---- tests.thisPasses stdout ----
I got the value 4


successes:
    tests.thisPasses

failures:

---- tests.thisFails stdout ----
I got the value 8
thread 'tests.thisFails' panicked at src/lib.ox:17:9:
assertion `left == right` failed
  left: 8
 right: 5

Now both tests show their output.

Running a Subset of Tests by Name

Running the full test suite takes time. You can run specific tests by name.

Running Single Tests

Pass the test name to cargo test:

cargo test thisPasses

Output:

running 1 test
test tests.thisPasses ... ok

test result: ok. 1 passed; 0 filtered out

Note: You can use either the Oxide camelCase name (thisPasses) or the Rust snake_case name (this_passes).

Filtering to Run Multiple Tests

Specify part of a test name to run all matching tests:

public fn addTwo(a: Int): Int {
    a + 2
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn addTwoAndTwo() {
        assertEq!(4, addTwo(2))
    }

    #[test]
    fn addThreeAndTwo() {
        assertEq!(5, addTwo(3))
    }

    #[test]
    fn oneHundred() {
        assertEq!(102, addTwo(100))
    }
}

Running all tests:

cargo test

running 3 tests
test tests.addThreeAndTwo ... ok
test tests.addTwoAndTwo ... ok
test tests.oneHundred ... ok

Running only the "add" tests:

cargo test add

running 2 tests
test tests.addThreeAndTwo ... ok
test tests.addTwoAndTwo ... ok

Running Tests by Module Name

You can also filter by module name:

cargo test tests::

This runs all tests in the tests module.

Ignoring Tests Unless Specifically Requested

Some tests are expensive and you want to skip them in normal runs. Use the #[ignore] attribute:

#[cfg(test)]
module tests {
    #[test]
    fn itWorks() {
        assertEq!(2 + 2, 4)
    }

    #[test]
    #[ignore]
    fn expensiveTest() {
        // This test takes a long time to run
        // Code that takes an hour to run...
    }
}

Running cargo test:

running 2 tests
test tests.expensiveTest ... ignored
test tests.itWorks ... ok

test result: ok. 1 passed; 0 failed; 1 ignored

To run only the ignored tests:

cargo test -- --ignored

To run all tests including ignored ones:

cargo test -- --include-ignored

Running Tests by Type

Cargo can run different types of tests:

cargo test --lib          # Run library tests only
cargo test --doc          # Run documentation tests only
cargo test --bins         # Run binary tests only
cargo test --tests        # Run integration tests only

Running a Specific Test File

For integration tests, run tests from a specific file:

cargo test --test integration_test

This runs tests only from tests/integration_test.rs (or tests/integration_test.ox).

Useful Test Options

Here are commonly used test options:

Exact Matching

By default, test name matching is a substring match. For exact matching:

cargo test thisPasses -- --exact

Skipping Tests

Skip tests matching a pattern:

cargo test -- --skip expensive

Summary

• Use cargo test to run all tests
• Add -- to pass options to the test binary
• Control parallelism with --test-threads
• See output with --show-output
• Filter tests by name with cargo test <pattern>
• Use #[ignore] for expensive tests
• Run ignored tests with --ignored
• Use --exact for exact name matching
• Skip patterns with --skip

The next section covers how to organize your tests into unit tests and integration tests.

Test Organization

The Oxide and Rust community thinks about tests in terms of two main categories: unit tests and integration tests. Unit tests are small and focused, testing one module in isolation and can test private interfaces. Integration tests are external to your library and use your code the same way external code would, using only the public interface.

Unit Tests

The purpose of unit tests is to test each unit of code in isolation to quickly pinpoint where code is or isn't working as expected. Unit tests go in the src directory in each file with the code they're testing.

The Tests Module and #[cfg(test)]

The #[cfg(test)] annotation tells Oxide to compile and run the test code only when you run cargo test, not when you run cargo build. This saves compile time and reduces the binary size.

public fn add(left: UIntSize, right: UIntSize): UIntSize {
    left + right
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn itWorks() {
        let result = add(2, 2)
        assertEq!(result, 4)
    }
}

The #[cfg(test)] attribute on the tests module means:

• The module is only compiled during cargo test
• All code inside is test-only, including helper functions
• The module is stripped from release builds

Testing Private Functions

Unlike some languages, Oxide allows you to test private functions directly. Since tests are in the same file as the code, they have access to private items:

fn internalAdd(a: Int, b: Int): Int {
    a + b
}

public fn publicAdd(a: Int, b: Int): Int {
    internalAdd(a, b)
}

#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn testInternalAdd() {
        // We can test the private function directly
        assertEq!(internalAdd(2, 3), 5)
    }

    #[test]
    fn testPublicAdd() {
        assertEq!(publicAdd(2, 3), 5)
    }
}

Whether you choose to test private functions is a matter of opinion. Oxide makes it possible, but you're not required to do so.

Organizing Unit Tests

For larger modules, you might organize tests into submodules:

public struct Calculator {
    value: Int,
}

extension Calculator {
    public static fn new(): Calculator {
        Calculator { value: 0 }
    }

    public fn add(amount: Int): Int {
        self.value + amount
    }

    public fn multiply(factor: Int): Int {
        self.value * factor
    }
}

#[cfg(test)]
module tests {
    import super.*

    module additionTests {
        import super.*

        #[test]
        fn addsPositiveNumbers() {
            let calc = Calculator { value: 5 }
            assertEq!(calc.add(3), 8)
        }

        #[test]
        fn addsNegativeNumbers() {
            let calc = Calculator { value: 5 }
            assertEq!(calc.add(-3), 2)
        }
    }

    module multiplicationTests {
        import super.*

        #[test]
        fn multipliesPositiveNumbers() {
            let calc = Calculator { value: 5 }
            assertEq!(calc.multiply(3), 15)
        }

        #[test]
        fn multipliesByZero() {
            let calc = Calculator { value: 5 }
            assertEq!(calc.multiply(0), 0)
        }
    }
}

Integration Tests

Integration tests are entirely external to your library. They use your library in the same way any other code would, which means they can only call public functions. Their purpose is to test that multiple parts of your library work together correctly.

The tests Directory

To create integration tests, create a tests directory at the top level of your project, next to src:

adder/
  Cargo.toml
  src/
    lib.ox
  tests/
    integration_test.ox

Let's create tests/integration_test.ox:

import adder

#[test]
fn itAddsTwo() {
    assertEq!(4, adder.add(2, 2))
}

Key differences from unit tests:

1. No #[cfg(test)] needed - Cargo knows the tests directory contains tests
2. External perspective - We import our crate with import adder
3. Public API only - We can only use public functions and types

Run integration tests with:

cargo test --test integration_test

Or run all tests:

cargo test

Output:

running 1 test
test tests.itWorks ... ok

     Running tests/integration_test.ox (target/debug/deps/integration_test-...)

running 1 test
test itAddsTwo ... ok

test result: ok. 1 passed; 0 failed

Each file in tests is compiled as a separate crate.

Submodules in Integration Tests

As you add more integration tests, you might want to organize them. Each file in tests compiles as its own crate, so they don't share behavior like modules in src.

For shared helper code, create a subdirectory with a mod.ox file:

tests/
  common/
    mod.ox
  integration_test.ox

In tests/common/mod.ox:

public fn setup(): String {
    // Setup code that might be needed by multiple tests
    "test_database".toString()
}

public struct TestConfig {
    public name: String,
    public debug: Bool,
}

extension TestConfig {
    public static fn default(): TestConfig {
        TestConfig {
            name: "test".toString(),
            debug: true,
        }
    }
}

In tests/integration_test.ox:

external module common

import adder
import crate.common.{ setup, TestConfig }

#[test]
fn itAddsTwo() {
    let _config = TestConfig.default()
    let _db = setup()
    assertEq!(4, adder.add(2, 2))
}

#[test]
fn itAddsLargeNumbers() {
    assertEq!(1000000002, adder.add(1000000000, 2))
}

Files in subdirectories of tests don't get compiled as separate test crates. The common/mod.ox pattern prevents Cargo from treating common as a test file while allowing other tests to import it.

Integration Tests for Binary Crates

If your project only contains a src/main.ox and no src/lib.ox, you can't create integration tests in the tests directory and import functions with import cratename.

This is one reason Oxide projects with a binary have a straightforward src/main.ox that calls logic in src/lib.ox. The library can be tested with integration tests while the main file remains minimal.

Multiple Integration Test Files

For larger projects, organize integration tests by feature:

tests/
  common/
    mod.ox
  api_tests.ox
  database_tests.ox
  user_tests.ox

Each file runs as its own test suite. Run a specific one:

cargo test --test api_tests

Test Organization Best Practices

Unit Test Guidelines

1. Keep tests close to code - Tests in the same file as the code they test
2. Test one thing - Each test should verify a single behavior
3. Use descriptive names - testAddWithNegativeNumbers not test1
4. Arrange-Act-Assert - Structure tests clearly

#[test]
fn userCanChangeName() {
    // Arrange
    var user = User.new("Alice")

    // Act
    user.setName("Bob")

    // Assert
    assertEq!(user.name, "Bob")
}

Integration Test Guidelines

1. Test the public interface - Don't try to access private internals
2. Test realistic scenarios - Combine operations as users would
3. Share setup code - Use the common module pattern
4. One concern per file - Organize by feature or subsystem

When to Use Each

Documentation Tests

Oxide also runs code examples in documentation comments as tests:

/// Adds two numbers together.
///
/// # Examples
///
/// ```oxide
/// let result = adder.add(2, 2)
/// assertEq!(result, 4)
/// ```
public fn add(left: UIntSize, right: UIntSize): UIntSize {
    left + right
}

Run documentation tests with:

cargo test --doc

Documentation tests ensure your examples stay correct as code evolves.

Summary

Oxide's testing features help you write and organize tests effectively:

Unit Tests:

• Placed in #[cfg(test)] modules alongside code
• Can test private functions
• Fast to compile and run
• Use for isolated, focused tests

Integration Tests:

• Placed in the tests directory
• Use your library as an external consumer would
• Test only the public API
• Use for testing feature workflows

Best Practices:

• Keep tests close to the code they test
• Test one behavior per test
• Use descriptive test names
• Share setup code through common modules
• Run tests frequently during development

Testing is a skill that improves with practice. Start with simple tests and grow your test suite as your codebase grows.

Chapter 12: An I/O Project - Building a CLI Program

In this chapter, we'll build a practical command-line program that demonstrates several concepts we've learned: file I/O, handling command-line arguments, error handling with the ? operator, and testing. We'll create a grep-like tool called oxgrep that searches for a query string in a file and prints matching lines.

Project Overview

Our oxgrep program will:

1. Accept a search query and a filename as command-line arguments
2. Read the file
3. Find and print lines containing the query
4. Handle errors gracefully with custom error types and the ? operator
5. Include comprehensive tests

This is an excellent opportunity to practice:

• Command-line argument parsing - Processing user input
• File I/O - Reading files efficiently
• Error handling - Creating custom error types and using the ? operator
• Code organization - Separating concerns into modules
• Testing - Writing tests for different scenarios
• Refactoring - Improving code quality and maintainability

Getting Started

Let's create a new binary project:

cargo new oxgrep
cd oxgrep

This creates a project with the following structure:

oxgrep/
├── Cargo.toml
└── src/
    └── main.ox

Throughout this chapter, we'll build up the program incrementally, explaining each piece as we go. We'll start with the simplest working version and then add features and improve the design.

What We'll Build

By the end of this chapter, you'll have a working program that can be used like this:

cargo run -- to sample.txt
cargo run -- is poem.txt
cargo run -- CASE_INSENSITIVE sample.txt -- -i

The program will output matching lines and handle missing files, invalid arguments, and other error conditions gracefully.

Let's dive in!

Next Steps

1. Accepting Command Line Arguments - Parse user input
2. Reading a File - Learn how to work with the file system
3. Refactoring to Improve Modularity and Error Handling - Build better error handling
4. Adding Functionality with Test Driven Development - Ensure your code works correctly
5. Working with Environment Variables - Handle case-insensitive search
6. Redirecting Errors to Standard Error - Keep stdout clean
7. Improving Our I/O Project (Chapter 13) - Polish your implementation

Accepting Command-Line Arguments

A good command-line program needs to parse and validate arguments correctly. In this section, we'll improve how our program handles user input.

The Problem with Raw Arguments

Our current approach directly accesses args[1] and args[2], which is error-prone:

let args = std.env.args().collect<Vec<String>>()

if args.len() < 3 {
    eprintln!("usage: oxgrep <query> <filename>")
    std.process.exit(1)
}

let query = args[1].clone()
let filename = args[2].clone()

This works, but it's hard to maintain and extend. As we add features (like case-insensitive search), the argument parsing becomes messier.

Refactoring into a Config Struct

Let's create a Config struct to encapsulate argument parsing:

import std.fs
import std.env
import std.error.Error

struct Config {
    query: String,
    filename: String,
    ignoreCase: Bool,
}

extension Config {
    static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 3 {
            return Err("not enough arguments".toString())
        }

        let query = args[1].clone()
        let filename = args[2].clone()
        let ignoreCase = args.len() > 3 && args[3] == "--ignore-case"

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    let config = Config.new(&args)
        .unwrapOrElse { err ->
            eprintln!("Problem parsing arguments: {}", err)
            std.process.exit(1)
        }?

    run(config)
}

fn run(config: Config): Result<(), Box<dyn Error>> {
    let contents = std.fs.readToString(&config.filename)?

    for line in contents.lines() {
        if line.contains(&config.query) {
            println!("{}", line)
        }
    }

    Ok(())
}

Now the argument parsing is isolated in the Config struct, making it easy to test and modify.

Improving Error Messages

The generic "not enough arguments" message could be more helpful:

extension Config {
    static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 3 {
            return Err(
                "not enough arguments\n\
                 usage: oxgrep <query> <filename> [--ignore-case]".toString()
            )
        }

        let query = args[1].clone()
        let filename = args[2].clone()
        let ignoreCase = args.len() > 3 && args[3] == "--ignore-case"

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

Handling Invalid Options

What if the user passes an unrecognized flag? Let's validate:

extension Config {
    static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 3 {
            return Err(
                "not enough arguments\n\
                 usage: oxgrep <query> <filename> [--ignore-case]".toString()
            )
        }

        let query = args[1].clone()
        let filename = args[2].clone()
        var ignoreCase = false

        // Parse remaining arguments
        for i in 3..args.len() {
            match args[i].asStr() {
                "--ignore-case" -> {
                    ignoreCase = true
                },
                _ -> {
                    return Err(format!("Unknown option: {}", args[i]))
                }
            }
        }

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

Iterator-Based Parsing

For more complex programs, you might use iterators for elegant argument parsing:

extension Config {
    static fn new(var args: Vec<String>): Result<Config, String> {
        args.remove(0) // Remove program name

        if args.isEmpty() {
            return Err("not enough arguments".toString())
        }

        let query = args.remove(0)

        if args.isEmpty() {
            return Err("filename required".toString())
        }

        let filename = args.remove(0)
        let ignoreCase = args.contains(&"--ignore-case".toString())

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

Using Environment for Options

Some tools allow configuration via environment variables. For example, you might set OXGREP_IGNORE_CASE:

extension Config {
    static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 3 {
            return Err("not enough arguments".toString())
        }

        let query = args[1].clone()
        let filename = args[2].clone()

        // Check both command-line flag and environment variable
        let ignoreCase =
            args.len() > 3 && args[3] == "--ignore-case"
            || std.env.var("OXGREP_IGNORE_CASE").isOk()

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

Adding Help Text

A professional CLI tool includes help documentation:

extension Config {
    static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 2 {
            return Err(Self.helpText())
        }

        // Check for help flag first
        if args[1] == "--help" || args[1] == "-h" {
            println!("{}", Self.helpText())
            std.process.exit(0)
        }

        if args.len() < 3 {
            return Err(Self.helpText())
        }

        let query = args[1].clone()
        let filename = args[2].clone()
        let ignoreCase = args.len() > 3 && args[3] == "--ignore-case"

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }

    static fn helpText(): String {
        "oxgrep - A simple text search tool\n\n\
         USAGE:\n    \
         oxgrep <QUERY> <FILENAME> [OPTIONS]\n\n\
         OPTIONS:\n    \
         --ignore-case    Case-insensitive search\n    \
         --help, -h       Show this help message".toString()
    }
}

Summary

Good argument parsing leads to better user experience:

• Encapsulation - Use structs to group related arguments
• Validation - Check arguments early and provide helpful error messages
• Flexibility - Support both command-line flags and environment variables
• Documentation - Include helpful error messages and help text
• Extensibility - Make it easy to add new options without refactoring the entire program

Next, we'll improve error handling with custom error types.

Reading and Writing Files

In Oxide (like Rust), working with the file system requires the std.fs module. This section covers reading files, a fundamental operation for our grep-like program.

Reading a File

Let's start with the most basic operation: reading a file's contents into a string.

Create a sample file named poem.txt:

I'm nobody! Who are you?
Are you nobody too?
Then there's a pair of us!
Don't tell! they'd banish us, you know.

How dreary to be somebody!
How public, like a Frog
To tell one's name the livelong June
To an admiring Bog!

Now, let's write code to read this file. Update src/main.ox:

import std.fs

fn main() {
    let filename = "poem.txt"
    let contents = std.fs.readToString(filename)

    println!("File contents:\n\(contents)")
}

Run the program:

cargo run

Output:

File contents:
I'm nobody! Who are you?
Are you nobody too?
...

Handling Errors with Result

What happens if the file doesn't exist? The readToString function returns a Result<String, Error>, which means it can fail. We need to handle this using the ? operator.

import std.fs

fn main() {
    let filename = "poem.txt"
    let contents = std.fs.readToString(filename)?

    println!("File contents:\n\(contents)")
}

But wait—main doesn't return Result, it returns nothing. We need to change that:

import std.fs

fn main(): Result<(), Box<dyn Error>> {
    let filename = "poem.txt"
    let contents = std.fs.readToString(filename)?

    println!("File contents:\n\(contents)")
    Ok(())
}

Now if the file doesn't exist, the error message will be printed by Rust's error handling system:

Error: Os { code: 2, kind: NotFound, message: "No such file or directory" }

Using Variables from Arguments

In a real program, the filename shouldn't be hardcoded. Let's accept it as a command-line argument.

First, let's use std.env to get command-line arguments:

import std.fs
import std.env
import std.error.Error

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    if args.len() < 2 {
        eprintln!("usage: oxgrep <query> <filename>")
        std.process.exit(1)
    }

    let query = args[1].clone()
    let filename = args[2].clone()

    let contents = std.fs.readToString(&filename)?

    println!("In file \(filename)")
    println!("Contents: \(contents)")

    Ok(())
}

Now you can run:

cargo run -- to poem.txt

Output:

In file poem.txt
Contents:
I'm nobody! Who are you?
...

Processing File Contents

Now that we can read files, let's search for matching lines. We'll create a function to do the heavy lifting:

import std.fs
import std.env
import std.error.Error

fn search(query: &str, contents: &str): Vec<String> {
    var results = Vec.new()

    for line in contents.lines() {
        if line.contains(query) {
            results.push(line.toString())
        }
    }

    results
}

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    if args.len() < 3 {
        eprintln!("usage: oxgrep <query> <filename>")
        std.process.exit(1)
    }

    let query = args[1].clone()
    let filename = args[2].clone()

    let contents = std.fs.readToString(&filename)?

    let results = search(&query, &contents)

    for line in results {
        println!("{}", line)
    }

    Ok(())
}

Let's test it:

cargo run -- is poem.txt

Output:

I'm nobody! Who are you?
Are you nobody too?
Then there's a pair of us!
How public, like a Frog

Perfect! But this approach is inefficient for large files because it stores all matching lines in memory. For a real grep tool, we'd print lines as we find them. However, for learning purposes, this demonstrates the concept clearly.

Improving Efficiency

For large files, a better approach is to print directly without storing results:

import std.fs
import std.env
import std.error.Error

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    if args.len() < 3 {
        eprintln!("usage: oxgrep <query> <filename>")
        std.process.exit(1)
    }

    let query = args[1].clone()
    let filename = args[2].clone()

    let contents = std.fs.readToString(&filename)?

    for line in contents.lines() {
        if line.contains(&query) {
            println!("{}", line)
        }
    }

    Ok(())
}

This version is simpler and more memory-efficient—perfect for real applications.

Writing Files

While our grep tool only reads files, it's useful to know how to write files. Use std.fs.write:

import std.fs

fn main(): Result<(), Box<dyn Error>> {
    let content = "Hello, World!"
    std.fs.write("output.txt", content)?

    println!("File written successfully")
    Ok(())
}

For more complex file operations (appending, seeking), use OpenOptions:

import std.fs

fn main(): Result<(), Box<dyn Error>> {
    // Append to a file
    var file = std.fs.OpenOptions.new()
        .append(true)
        .open("log.txt")?

    std.io.Write.writeAll(&mut file, b"Log entry\n")?

    Ok(())
}

Summary

File I/O in Oxide follows Rust's patterns:

• std.fs.readToString - Read an entire file into a String
• std.fs.write - Write content to a file
• std.fs.OpenOptions - For more control over how files are opened
• Result-based errors - Always handle potential failures with ? or match
• Iterating over lines - Use .lines() to process files line-by-line

Next, we'll make our program more user-friendly by handling command-line arguments better.

Improving Error Handling with Custom Error Types

As our program grows, generic String errors become problematic. Oxide (following Rust) allows us to create custom error types for better error handling.

The Problem with String Errors

Currently, we're returning Result<Config, String>. This has issues:

1. Loss of context - A string doesn't tell us what kind of error occurred
2. Difficult error handling - Callers can't distinguish between different errors
3. Hard to extend - Adding new error types requires refactoring

// Current approach - hard to work with
let config = Config.new(&args)
    .unwrapOrElse { err ->
        eprintln!("Error: {}", err)
        std.process.exit(1)
    }?

Creating a Custom Error Type

Let's define an AppError enum that represents the different errors our program can encounter:

import std.fmt
import std.error.Error
import std.io

enum AppError {
    ArgumentError(String),
    FileError(io.Error),
    SearchError(String),
}

Now we need to implement Display and Error traits for proper error handling:

extension AppError: fmt.Display {
    fn fmt(f: &mut fmt.Formatter): fmt.Result {
        match self {
            AppError.ArgumentError(msg) -> {
                write!(f, "Argument error: {}", msg)
            },
            AppError.FileError(err) -> {
                write!(f, "File error: {}", err)
            },
            AppError.SearchError(msg) -> {
                write!(f, "Search error: {}", msg)
            },
        }
    }
}

extension AppError: fmt.Debug {
    fn fmt(f: &mut fmt.Formatter): fmt.Result {
        write!(f, "{:?}", self)
    }
}

extension AppError: From<io.Error> {
    static fn from(err: io.Error): Self {
        AppError.FileError(err)
    }
}

Using the Custom Error Type

Now update Config to return our custom error:

extension Config {
    static fn new(args: &Vec<String>): Result<Config, AppError> {
        if args.len() < 3 {
            return Err(AppError.ArgumentError(
                "not enough arguments\nusage: oxgrep <query> <filename>".toString()
            ))
        }

        let query = args[1].clone()
        let filename = args[2].clone()
        let ignoreCase = args.len() > 3 && args[3] == "--ignore-case"

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

Update the main function:

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    let config = Config.new(&args)
        .unwrapOrElse { err ->
            eprintln!("Problem parsing arguments: {}", err)
            std.process.exit(1)
        }?

    run(config)
}

fn run(config: Config): Result<(), Box<dyn Error>> {
    let contents = std.fs.readToString(&config.filename)?

    for line in contents.lines() {
        if line.contains(&config.query) {
            println!("{}", line)
        }
    }

    Ok(())
}

The From<io.Error> implementation allows automatic conversion. When readToString returns an IO error, it's automatically converted to our AppError.

Detailed Error Messages

With custom error types, we can provide context-specific messages:

enum AppError {
    ArgumentError {
        message: String,
        usage: String,
    },
    FileNotFound(String),
    PermissionDenied(String),
    InvalidEncoding,
}

extension AppError: fmt.Display {
    fn fmt(f: &mut fmt.Formatter): fmt.Result {
        match self {
            AppError.ArgumentError { message, usage } -> {
                write!(
                    f,
                    "Error: {}\n\n{}",
                    message, usage
                )
            },
            AppError.FileNotFound(path) -> {
                write!(f, "File not found: {}", path)
            },
            AppError.PermissionDenied(path) -> {
                write!(f, "Permission denied reading: {}", path)
            },
            AppError.InvalidEncoding -> {
                write!(f, "File is not valid UTF-8")
            },
        }
    }
}

The ?? Operator

Oxide provides a convenient ?? operator for working with Option types. This null-coalescing operator provides a default value when an Option is None:

fn findValue(data: Vec<String>, key: String): String? {
    for item in data.iter() {
        if item.contains(&key) {
            return Some(item.clone())
        }
    }
    null
}

fn main(): Result<(), Box<dyn Error>> {
    let data = vec!["key:value".toString(), "other:data".toString()]

    // Using ?? to provide a default value
    let value = findValue(data, "key".toString()) ?? "default".toString()

    println!("Value: {}", value)
    Ok(())
}

The ?? operator:

• Returns the inner value if Some
• Uses the right-hand default value if None
• Makes code more concise than unwrapOr

Error Handling in Functions

When functions can fail, propagate errors with ?:

fn search(
    query: &str,
    contents: &str
): Result<Vec<String>, AppError> {
    var results = Vec.new()

    for line in contents.lines() {
        if line.contains(query) {
            results.push(line.toString())
        }
    }

    if results.isEmpty() {
        // Optionally return an error if nothing found
        // Err(AppError.SearchError("No matches found".toString()))
    }

    Ok(results)
}

Summary

Custom error types improve error handling:

• Better semantics - Error types reflect actual problems
• Composability - Use From to convert between error types
• Easier debugging - Detailed context helps find issues
• Type safety - Match on specific error variants
• Operator support - Use ? and ?? for elegant error propagation

Next, we'll add support for case-insensitive searching using environment variables.

Writing Tests for Our CLI Program

Testing CLI programs requires special techniques. We need to test file I/O, argument parsing, and search logic in isolation. Let's write comprehensive tests for our grep clone.

Organizing Code for Testing

First, let's restructure our code to be testable. Create src/lib.ox alongside src/main.ox:

// src/lib.ox
import std.fs
import std.env
import std.error.Error

public struct Config {
    public query: String,
    public filename: String,
    public ignoreCase: Bool,
}

extension Config {
    public static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 3 {
            return Err("not enough arguments".toString())
        }

        let query = args[1].clone()
        let filename = args[2].clone()

        let commandLineFlag = args.len() > 3 && args[3] == "--ignore-case"
        let envVariable = std.env.var("OXGREP_IGNORE_CASE").isOk()

        let ignoreCase = commandLineFlag || envVariable

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

public fn search(config: &Config, contents: &str): Vec<String> {
    var results = Vec.new()

    let query = if config.ignoreCase {
        config.query.toLowercase()
    } else {
        config.query.clone()
    }

    for line in contents.lines() {
        let searchLine = if config.ignoreCase {
            line.toLowercase()
        } else {
            line.toString()
        }

        if searchLine.contains(&query) {
            results.push(line.toString())
        }
    }

    results
}

public fn run(config: &Config): Result<(), Box<dyn Error>> {
    let contents = std.fs.readToString(&config.filename)?
    let results = search(config, &contents)

    for line in results {
        println!("{}", line)
    }

    Ok(())
}

Now src/main.ox just handles argument parsing and calls run:

// src/main.ox
import std.env
import std.error.Error
import oxgrep.*

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    let config = Config.new(&args)
        .unwrapOrElse { err ->
            eprintln!("Problem parsing arguments: {}", err)
            std.process.exit(1)
        }?

    run(&config)
}

Testing the Search Function

Now we can test the core search logic:

// In src/lib.ox
#[cfg(test)]
module tests {
    import super.*

    #[test]
    fn caseInsensitive() {
        let query = "duct".toString()
        let contents = "Rust:\nsafe, fast, productive.\nPick three.".toString()

        var config = Config {
            query,
            filename: "test.txt".toString(),
            ignoreCase: true,
        }

        let results = search(&config, &contents)

        assertEq!(results.len(), 1)
        assertEq!(results[0], "safe, fast, productive.".toString())
    }

    #[test]
    fn caseSensitive() {
        let query = "duct".toString()
        let contents = "Rust:\nsafe, fast, productive.\nPick three.".toString()

        var config = Config {
            query,
            filename: "test.txt".toString(),
            ignoreCase: false,
        }

        let results = search(&config, &contents)

        assertEq!(results.len(), 1)
        assertEq!(results[0], "safe, fast, productive.".toString())
    }

    #[test]
    fn noMatches() {
        let query = "xyz".toString()
        let contents = "Rust:\nsafe, fast, productive.\nPick three.".toString()

        var config = Config {
            query,
            filename: "test.txt".toString(),
            ignoreCase: false,
        }

        let results = search(&config, &contents)

        assertEq!(results.len(), 0)
    }

    #[test]
    fn multipleMatches() {
        let query = "a".toString()
        let contents = "apple\napricot\navocado".toString()

        var config = Config {
            query,
            filename: "test.txt".toString(),
            ignoreCase: false,
        }

        let results = search(&config, &contents)

        assertEq!(results.len(), 3)
        assertEq!(results[0], "apple".toString())
        assertEq!(results[1], "apricot".toString())
        assertEq!(results[2], "avocado".toString())
    }
}

Testing Argument Parsing

Test the Config struct:

#[cfg(test)]
module configTests {
    import super.*

    #[test]
    fn requiredArguments() {
        let args = vec!["oxgrep".toString()]
        let result = Config.new(&args)

        assert!(result.isErr())
    }

    #[test]
    fn parsesQueryAndFilename() {
        let args = vec![
            "oxgrep".toString(),
            "test".toString(),
            "file.txt".toString(),
        ]
        let result = Config.new(&args)

        assert!(result.isOk())

        let config = result.unwrap()
        assertEq!(config.query, "test".toString())
        assertEq!(config.filename, "file.txt".toString())
        assert!(!config.ignoreCase)
    }

    #[test]
    fn parsesIgnoreCaseFlag() {
        let args = vec![
            "oxgrep".toString(),
            "test".toString(),
            "file.txt".toString(),
            "--ignore-case".toString(),
        ]
        let result = Config.new(&args)

        assert!(result.isOk())

        let config = result.unwrap()
        assert!(config.ignoreCase)
    }
}

Testing With Temporary Files

For more integration-like tests, use temporary files:

import std.fs
import std.path.PathBuf
import std.env

fn createTempFile(contents: &str): Result<PathBuf, Box<dyn Error>> {
    let tempDir = std.env.tempDir()
    let filename = tempDir.join("oxgrep_test.txt")

    std.fs.write(&filename, contents)?

    Ok(filename)
}

#[cfg(test)]
module integrationTests {
    import super.*

    #[test]
    fn searchesRealFile(): Result<(), Box<dyn Error>> {
        let filename = createTempFile("apple\napricot\navocado")?

        var config = Config {
            query: "a".toString(),
            filename: filename.toString(),
            ignoreCase: false,
        }

        let contents = std.fs.readToString(&config.filename)?
        let results = search(&config, &contents)

        assertEq!(results.len(), 3)

        // Cleanup
        std.fs.removeFile(&filename)?

        Ok(())
    }

    #[test]
    fn handlesNonExistentFile(): Result<(), Box<dyn Error>> {
        var config = Config {
            query: "test".toString(),
            filename: "nonexistent.txt".toString(),
            ignoreCase: false,
        }

        let result = run(&config)

        assert!(result.isErr())

        Ok(())
    }
}

Running Tests

Run all tests:

cargo test

Output:

running 7 tests
test configTests.parsesIgnoreCaseFlag ... ok
test configTests.parsesQueryAndFilename ... ok
test configTests.requiredArguments ... ok
test integrationTests.handlesNonExistentFile ... ok
test integrationTests.searchesRealFile ... ok
test tests.caseInsensitive ... ok
test tests.caseSensitive ... ok
test tests.multipleMatches ... ok
test tests.noMatches ... ok

test result: ok. 9 passed; 0 failed

Testing Error Conditions

Test that errors are handled gracefully:

#[test]
fn invalidArguments() {
    let args = vec!["oxgrep".toString(), "query".toString()]
    let result = Config.new(&args)

    assert!(result.isErr())

    match result {
        Err(msg) -> {
            assert!(msg.contains("not enough arguments"))
        },
        _ -> panic!("Expected error"),
    }
}

#[test]
fn emptySearch() {
    let query = "".toString()
    let contents = "Line 1\nLine 2\nLine 3".toString()

    var config = Config {
        query,
        filename: "test.txt".toString(),
        ignoreCase: false,
    }

    let results = search(&config, &contents)

    // Empty query matches all lines (contains("") is true)
    assertEq!(results.len(), 3)
}

#[test]
fn emptyFile() {
    let query = "test".toString()
    let contents = "".toString()

    var config = Config {
        query,
        filename: "test.txt".toString(),
        ignoreCase: false,
    }

    let results = search(&config, &contents)

    assertEq!(results.len(), 0)
}

Test Organization Best Practices

1. Group related tests - Use modules to organize test functions
2. Descriptive names - Make test purpose clear from the name
3. Test one thing - Each test should verify one behavior
4. Use fixtures - Create helper functions for common setup
5. Test edge cases - Empty input, large input, invalid input
6. Integration tests - Test the complete flow
7. Document assumptions - Explain why tests work as they do

Running Specific Tests

# Run tests matching a name
cargo test case_insensitive

# Run tests in a specific module
cargo test configTests

# Run with output
cargo test -- --nocapture

# Run one test per thread (slower but shows output in order)
cargo test -- --test-threads=1

Summary

Effective testing for CLI programs:

• Separate concerns - Move logic into a library for easier testing
• Unit tests - Test individual functions with test data
• Integration tests - Test complete workflows with real files
• Error cases - Verify graceful failure handling
• Assertions - Use assert!, assertEq!, and assertNe!
• Organization - Group tests logically in modules

Next, we'll refactor our code for better performance and maintainability.

Working with Environment Variables

Many CLI programs allow configuration through environment variables. Let's add case-insensitive search support using OXGREP_IGNORE_CASE.

Reading Environment Variables

The std.env module provides functions to read environment variables:

import std.env

fn main() {
    // Get a variable - returns String?
    let debugMode = std.env.var("DEBUG")

    match debugMode {
        Ok(value) -> println!("DEBUG is set to: \(value)"),
        Err(_) -> println!("DEBUG is not set"),
    }
}

Checking for a Flag

To check if an environment variable exists, just see if the result is Ok:

import std.env

fn main() {
    let ignoreCase = std.env.var("OXGREP_IGNORE_CASE").isOk()

    if ignoreCase {
        println!("Case-insensitive search enabled")
    }
}

Updating Our Config Struct

Let's integrate environment variable support into our Config struct:

import std.env

struct Config {
    query: String,
    filename: String,
    ignoreCase: Bool,
}

extension Config {
    static fn new(args: &Vec<String>): Result<Config, String> {
        if args.len() < 3 {
            return Err(
                "not enough arguments\nusage: oxgrep <query> <filename>".toString()
            )
        }

        let query = args[1].clone()
        let filename = args[2].clone()

        // Check both command-line flag and environment variable
        let commandLineFlag = args.len() > 3 && args[3] == "--ignore-case"
        let envVariable = std.env.var("OXGREP_IGNORE_CASE").isOk()

        let ignoreCase = commandLineFlag || envVariable

        Ok(Config {
            query,
            filename,
            ignoreCase,
        })
    }
}

Implementing Case-Insensitive Search

Now update the search function to use the ignoreCase field:

fn search(config: &Config, contents: &str): Vec<String> {
    var results = Vec.new()

    for line in contents.lines() {
        if config.ignoreCase {
            if line.toLowercase().contains(&config.query.toLowercase()) {
                results.push(line.toString())
            }
        } else {
            if line.contains(&config.query) {
                results.push(line.toString())
            }
        }
    }

    results
}

Or more concisely:

fn search(config: &Config, contents: &str): Vec<String> {
    var results = Vec.new()

    let query = if config.ignoreCase {
        config.query.toLowercase()
    } else {
        config.query.clone()
    }

    for line in contents.lines() {
        let searchLine = if config.ignoreCase {
            line.toLowercase()
        } else {
            line.toString()
        }

        if searchLine.contains(&query) {
            results.push(line.toString())
        }
    }

    results
}

Updated Main Function

Update main and run to pass the config around:

import std.fs
import std.env
import std.error.Error

fn main(): Result<(), Box<dyn Error>> {
    let args = std.env.args().collect<Vec<String>>()

    let config = Config.new(&args)
        .unwrapOrElse { err ->
            eprintln!("Problem parsing arguments: {}", err)
            std.process.exit(1)
        }?

    run(&config)
}

fn run(config: &Config): Result<(), Box<dyn Error>> {
    let contents = std.fs.readToString(&config.filename)?

    let results = search(config, &contents)

    for line in results {
        println!("{}", line)
    }

    Ok(())
}

Testing Environment Variable Behavior

You can test environment variable behavior from the command line:

# Case-sensitive (default)
cargo run -- "is" poem.txt
# Output: Lines containing "is" (lowercase)

# Case-insensitive via environment variable
OXGREP_IGNORE_CASE=1 cargo run -- "is" poem.txt
# Output: Lines containing "is" or "IS" or "Is"

# Case-insensitive via command-line flag
cargo run -- "is" poem.txt --ignore-case
# Output: Same as above

Getting Multiple Values

For more complex configuration, you might read multiple environment variables:

import std.env

struct AppConfig {
    query: String,
    filename: String,
    ignoreCase: Bool,
    maxResults: UInt,
    verbose: Bool,
}

extension AppConfig {
    static fn fromEnv(): Self {
        let ignoreCase = std.env.var("OXGREP_IGNORE_CASE").isOk()

        let maxResults = std.env.var("OXGREP_MAX_RESULTS")
            .ok()
            .andThen { s -> s.parse<UInt>().ok() }
            .unwrapOr(1000)

        let verbose = std.env.var("OXGREP_VERBOSE").isOk()

        AppConfig {
            query: String.new(),
            filename: String.new(),
            ignoreCase,
            maxResults,
            verbose,
        }
    }
}

Environment Variables in Tests

When writing tests, you can set environment variables programmatically:

#[test]
fn testIgnoreCaseFromEnv() {
    // In real tests, you'd need to set the environment before creating Config
    // This is more complex due to test concurrency
}

Important Notes About Environment Variables

1. Thread Safety - Reading environment variables is thread-safe, but setting them is not. Set variables before spawning threads.

2. Performance - Environment variable lookups are relatively expensive. Cache values if you use them frequently.

3. Naming Conventions - Use UPPERCASE_WITH_UNDERSCORES for environment variable names.

4. Documentation - Always document which environment variables your program recognizes.

5. Security - Be careful with sensitive data in environment variables (passwords, API keys). They're visible in process listings.