Starting with an embedded "Hello World" equivalent, and advancing to a text-to-morse-code translator, this article will walk you through the process.

• How to Set Up the Pi
  • Format the SD Card
  • Flash the Distribution
    • Configure Wifi and SSH
  • Complete the Circuit
• How to Set Up Cross Compilation
  • Install the Target
  • Specify the Linker
• How to Program an Embedded "Hello World"
  • Successfully Exit the Program
• How to Cross Compile the Program
• How to Transfer the Binary to the Pi
• How to SSH into the Pi
  • Run the Program
• How to Code a Text-to-Morse-Code Translator
• Appendix
  • Targets

How to Set Up the Pi

Format the SD Card

Use the Raspberry Pi Imager which can be downloaded from the Raspberry Pi Software Webpage.

Flash the Distribution

A distribution I'd suggest is Raspberry Pi OS Lite. This is a headless distribution, which means it does not come with a GUI.

Configure Wifi and SSH

Once that is done, you can insert the SD card into the Raspberry Pi, and power it up.

Complete the Circuit

Circuit Diagram

Pi Pinout

Connect negative to ground, and positive to BCM pin 17 as shown below:

The pinout can be seen here: https://pinout.xyz/

How to Set Up Cross Compilation

Install the Target

Use rustup to install the necessary target for your Raspberry Pi:

my-pc$ rustup add target arm-unknown-linux-gnueabihf

Appendix for more information about targets in Rust.

Specify the Linker

Download the raspberrypi/tools repository into a directory named rpi_tools:

my-pc:~ $ git clone https://github.com/raspberrypi/tools $HOME/rpi_tools

Edit the ~/.cargo/config file using your favourite text editor:

my_pc:~ $ sudo nano ~/.cargo/config

Tell Cargo to use a specific linker version for your target:

[target.arm-unknown-linux-gnueabihf]
linker = "/rpi_tools/arm-bcm2708/arm-rpi-4.9.3-linux-gnueabihf/bin/arm-linux-gnueabihf-gcc"

How to Program an Embedded "Hello World"

Start by creating a new Rust project, and opening the main.rs file in your favourite text editor:

my-pc:~ $ cargo new blink
my-pc:~ $ cd blink
my-pc:~/blink $ nano src/main.rs

Import the rust_gpiozero crate, and program an LED to alternate between on and off every second:

use rust_gpiozero::*;

fn main() {
    // Create a new LED attached to Pin 17
    let mut led = LED::new(17);

    led.blink(1.0, 1.0);

    led.wait();
}

Be sure to add the dependency to the Cargo.toml file:

[dependencies]
rust-gpiozero = "0.2.1"

Successfully Exit the Program

Since rustc 1.61.0 ^[1], you can use the std::process::ExitCode struct to specify the status code returned to the process' parent:

use std::process::ExitCode;
fn main() -> ExitCode {
    // ...
    if error {
      return ExitCode::from(1);
    }
    ExitCode::SUCCESS
}

Otherwise, you can simply return a Result:

fn main() -> Result<(), std::io::Error> {
  // ...
  Ok(())
}

How to Cross Compile the Program

Build a release of your program, targeting the required architecture:

my-pc:~/blink $ cargo build --release --target=arm-unknown-linux-gnueabihf

How to Transfer the Binary to the Pi

Use scp to transfer the compiled binary from your host computer to the Raspberry Pi over SSH:

my-pc:~/blink $ scp target/arm-unknown-linux-gnueabihf/release/blink pi@192.168.1.199:~/blink

Note: The local IP of your Pi will likely be different.

How to SSH into the Pi

SSH and log in to the Raspberry Pi via its local IP address:

my-pc:~ $ ssh pi@192.168.1.199

Run the Program

From the Raspberry Pi, run the compiled binary:

pi:~ $ ./blink

How to Code a Text-to-Morse-Code Translator

Here is an example of an application that reads the stdin line by line, translates the input into Morse Code, and toggles the LED on and off based on the Morse Code for the characters.

use rust_gpiozero::*;
use std::io::{BufRead, self};
use std::collections::HashMap;
use std::thread::sleep;
use std::time::Duration;

fn main() -> Result<(), std::io::Error> {
    println!("Starting...\n- Type in text to turn into Morse Code\n- Type `quit()` to quit\n");
    // Create a new LED attached to Pin 17
    let led = LED::new(17);

    /// Length of a dot in milliseconds
    const DOT_DELAY: u64 = 80;
    /// Length of a dash in milliseconds
    const DASH_DELAY: u64 = DOT_DELAY * 3;
    /// Delay between inputs in milliseconds
    const PUSH_DELAY: u64 = DOT_DELAY;
    /// Delay between letters in milliseconds
    const LETTER_DELAY: u64 = DOT_DELAY * 3;
    /// Delay between words in milliseconds
    const WORD_DELAY: u64 = DOT_DELAY * 7;

    let morse_code_alphabet: HashMap<char, &'static str> =
    [
        ('a', ".-"),
        ('b', "-..."),
        ('c', "-.-."),
        ('d', "-.."),
        ('e', "."),
        ('f', "..-."),
        ('g', "--."),
        ('h', "...."),
        ('i', ".."),
        ('j', ".---"),
        ('k', "-.-"),
        ('l', ".-.."),
        ('m', "--"),
        ('n', "-."),
        ('o', "---"),
        ('p', ".--."),
        ('q', "--.-"),
        ('r', ".-."),
        ('s', "..."),
        ('t', "-"),
        ('u', "..-"),
        ('v', "...-"),
        ('w', ".--"),
        ('x', "-..-"),
        ('y', "-.--"),
        ('z', "--.."),
        ('1', ".----"),
        ('2', "..---"),
        ('3', "...--"),
        ('4', "....-"),
        ('5', "....."),
        ('6', "-...."),
        ('7', "--..."),
        ('8', "---.."),
        ('9', "----."),
        ('0', "-----"),
        ('.', ".-.-.-"),
        (',', "--..--"),
        ('?', "..--.."),
        ('\'', ".----."),
        ('!', "-.-.--"),
        ('/', "-..-."),
        ('(', "-.--."),
        (')', "-.--.-"),
        ('&', ".-..."),
        (':', "---..."),
        (';', "-.-.-."),
        ('=', "-...-"),
        ('+', ".-.-."),
        ('-', "-....-"),
        ('_', "..--.-"),
        ('"', ".-..-."),
        ('$', "...-..-"),
        ('@', ".--.-."),
        (' ', " "),
    ].iter().cloned().collect();

    // Read standard input per line
    for line_res in io::stdin().lock().lines() {
        let line = line_res?;
        if line == "quit()" {
            break;
        }
        // Turn line into morse code
        let mut morse = String::new();
        for c in line.chars() {
            if let Some(morse_code_char) = morse_code_alphabet.get(&c) {
                morse.push_str(morse_code_char);
                // Separate characters with a comma
                morse.push_str(",");
            }
        }
        // Blink LED based on characters
        for c in morse.chars() {
            match c {
                '.' => {
                    led.on();
                    sleep(Duration::from_millis(DOT_DELAY));
                    led.off();
                    sleep(Duration::from_millis(PUSH_DELAY));
                },
                '-' => {
                    led.on();
                    sleep(Duration::from_millis(DASH_DELAY));
                    led.off();
                    sleep(Duration::from_millis(PUSH_DELAY));
                },
                ',' => {
                    sleep(Duration::from_millis(LETTER_DELAY));
                },
                ' ' => {
                    sleep(Duration::from_millis(WORD_DELAY));
                },
                _ => {
                    println!("Unknown character: {}", c);
                    break;
                }
            }
        }
        sleep(Duration::from_millis(WORD_DELAY));
    }

    // Free the variable and associated resources
    led.close();

    Ok(())
}

Appendix

Targets

In Rust, the target is the platform (architecture) the program is compiled for. Cargo automatically detects the target, based on the file system layout ^[2].

You can see the list of built-in targets, by running:

rustc --print target-list
# OR
rustup target list

From here you can add a new target to your project, by running:

rustup target add <target>

The given target is often in the form of a triple ^[3]:

• The architecture
• The vendor
• The operating system type
• The environment type

This is refered to as a 'target triple', because the fourth part is optional.

Here's the full Project Euler Rust GitHub repository.

If you do not know Rust, and want to learn it, you can start with freeCodeCamp's interactive Rust course.

All right. Let's see how to get started working through Project Euler in Rust.

How to Run the Project Euler Problems Locally in VSCode

First, you'll need to download and install the freeCodeCamp Courses VSCode extension.

Also, ensure you have the Microsoft Dev Containers VSCode extension.

Then, in an empty workspace, open the VSCode command palette with Ctrl/Cmd + Shift + P.

Select the command freeCodeCamp: Open Course.

Next, choose the Project Euler: Rust option.

Once the course is cloned, open the command palette again and select Dev Containers: Rebuild and Reopen in Container.

How to Run the Project Euler Problems Locally without the Extension

If you would prefer to run these without the VS Code extension, you'll need to fork the repository:

Then clone your fork to your local machine.

git clone https://github.com/<your_username>/euler-rust.git
cd euler-rust

Build and open the Docker container like this:

docker build -f Dockerfile -t euler-rust .

And then start the course:

npm i && npm run start

Optionally, you can also clone and build the container with Docker like this:

docker build github.com/<your_username>/euler-rust

How to Run the Project Euler Problems Using Gitpod

GitPod is a popular tool for running a VM in your browser, and is yet another way you can solve these Project Euler problems. First, fork the repository:

Then open your fork in Gitpod: https://gitpod.io/#https://github.com/<your_user_name>/euler-rust

Optionally, if you have the Gitpod browser extension installed, you can click the Gitpod button it adds to GitHub:

Useful Information

NOTE: If you are using any of the above methods with Docker, you will need to have Docker installed on your machine, and have the Daemon running.

You should need to only edit the src/lib.rs file within each project-euler-problems-... directory, and you can follow the example code there to get started.

To compile your code, before running the tests, run:

wasm-pack build

If at any point you get stuck, I recommend that you check out more information about Rust with WASM. Otherwise, feel free to open a new topic on the freeCodeCamp forum.

How the Project Works

First, taking your Rust code in src/lib.rs:

use wasm_bindgen::prelude::*;

// Example format to write functions:
#[wasm_bindgen(js_name = camelCaseName)] // js_name must equal function name tested on client
pub fn snake_case_name(num: i32) -> i32 { // Function must be public
    // All numbers in JS are 32-bit
    num
}

The Rust is transpiled into JavaScript code using wasm-pack:

import * as wasm from "./curriculum_bg.wasm";

/**
 * @param {number} n
 * @returns {number}
 */
export function camelCaseName(num) {
  var ret = wasm.camelCaseName(num);
  return ret;
}

Frequently Asked Questions (FAQ)

Will these Project Euler problems be made available in other programming languages?

We welcome any and all well-intended contributions to the freeCodeCamp community. So, if you are interested in developing on a fork of the repository, please do so!

Can I save my progress on my freeCodeCamp.org account?

Not yet, but it is something that we can look into further.

The Docker step takes such a long time. Is there a quicker way to get started?

Well, provided you have the tenacity to install all the necessary tooling on your local machine, you can simple run the following commands within the project:

npm ci
npm run start

cd project-euler-problems-1-to-100
wasm-pack build

Now, you should be able to open a browser and navigate to http://localhost:8080/, and begin.

So if you're ready to learn this popular programming language, this course will introduce you to Rust so you can start using it in your projects.

You will be working entirely within your browser by using the Replit interactive programming environment. freeCodeCamp has partnered with Replit who has made this course possible.

There is also a video version of this course on the freeCodeCamp YouTube channel.

To get the most out of this course, you should have intermediate knowledge of at least one other programming language. If you are new to programming, you should try out freeCodeCamp's interactive curriculum and then come back to this course.

To help you learn Rust, we will create two projects:

1. A calculator for the command line
2. A command line tool which takes two images and combines their pixels

Table of Contents

Here are the sections and topics we'll cover in this course. You can click through the table of contents below to jump to particular parts, or you can just go through from start to finish.

• Rust Overview
• How to Use Rust in Replit
• Basics of Rust
  • Variables in Rust
  • Functions in Rust
  • Strings and Slices in Rust
  • The char Type in Rust
  • Number Types in Rust
  • Structs in Rust
  • Enums in Rust
  • Macros in Rust
  • Ownership in Rust
• Project #1 - Build a CLI Calculator in Rust
  • Project Outcome
  • CLI Calculator Project Methodology
    • Step 1 - Create a New Project
    • Step 2 - Understand the Syntax
    • Step 3 - Run the Project
    • Step 4 - Command Line Arguments
    • Step 5 - Parse Strings into Numbers
    • Step 6 - Perform Basic Arithmetic Operations
    • Step 7 - Format the Output
    • Step 8 - Bring It All Together
• Project #2 - Build an Image Combiner in Rust
  • Project Outcome
  • Image Combiner Project Methodology
    • Step 1 - Create a New Project
    • Step 2 - Add a New Module for Args
    • Step 3 - Import and Use the args Module
    • Step 4 - Add an External Crate
    • Step 5 - Read an Image File
    • Step 6 - Handle Errors with Result
    • Step 7 - Resize the Images to Match
    • Step 8 - Create a Floating Image
    • Step 9 - Create the Combined Image Data
    • Step 10 - Attach the Combined Data to the Floating Image
    • Step 11 - Write the Image to a File
    • Step 12 - Bring It All Together
• Conclusion

Rust Overview

Rust is a systems-level programming language.

"[Rust] deals with low-level details of memory management, data representation, and concurrency."

"... the language is designed to guide you naturally towards reliable code that is efficient in terms of speed and memory usage." (Source: Rust docs)

The main tooling within the Rust ecosystem is:

• rustc – The compiler which takes your Rust code and compiles it into binary (machine readable code)
• rustup – The command line utility to install and update Rust
• cargo – The Rust build system and package manager

How to Use Rust in Replit

For this course, you will be using this GitHub repository as a boilerplate.

To begin, click the following link to create a new REPL from the boilerplate:

Then in the Import from GitHub modal, open the Language dropdown and select Bash:

Then click the Import from GitHub button in the lower right to import the boilerplate code into Replit.

Finally, to start the course, click the Run button at the top of the screen and follow the instructions in the console on the right:

Basics of Rust

Variables in Rust

You can declare variables using the let, const, or static keywords:

let my_variable = 0;
const MY_CONSTANT: u8 = 0;
static MY_STATIC: u8 = 0;

By default, all variables are immutable. You can make a variable mutable by using the mut keyword:

let mut my_mutable_variable = 0;

Rust convention relies on the following casing conventions:

Since Rust is statically typed, you'll need to explicitly type variables – unless the variable is declared with let and the type can be inferred.

Functions in Rust

You declare functions using the fn keyword:

fn main() {
  // This is a code comment
}

Functions return using the return keyword, and you need to explicitly specify the return type of a function, unless the return type is an empty tuple ():

fn main() -> () { // Unnecessary return type
  my_func();
}

fn my_func() -> u8 {
  return 0;
}

Functions also return an expression missing the semi-colon:

fn my_func() -> u8 {
  0
}

Function parameters are typed using the : syntax:

fn main() {
  let _unused_variable = my_func(10);
}

fn my_func(x: u8) -> i32 {
  x as i32
}

The underscore before a variable name is a convention to indicate that the variable is unused. The as keyword asserts the type of the expression, provided the type conversion is valid.

Strings and Slices in Rust

A common point of confusion for beginner Rustacians is the difference between the String struct and the str type.

let my_str: &str = "Hello, world!";

let my_string: String = String::from("Hello, world!");

In the above example, my_str is a reference to a string literal, and my_string is an instance of the String struct.

An important distinction between the two is that my_str is stack stored, and my_string is heap allocated. This means my_str's value cannot change, and its size is fixed, whilst my_string can have an unknown size at compile time.

The string literal is also known as a string slice. This is because a &str refers to part of a string. Generally, this is how arrays and strings are similar:

let my_string = String::from("The quick brown fox");
let my_str: &str = &my_string[4..9]; // "quick"

let my_arr: [usize; 5] = [1, 2, 3, 4, 5];
let my_arr_slice: &[usize] = &my_arr[0..3]; // [1, 2, 3]

The [T; n] notation is used to create an array of n elements of type T.

The char Type in Rust

A char is a USV (Unicode Scalar Value), which is represented in unicode with values like U+221E – the unicode for '∞'. You can think of a collection or array of chars as a string:

let my_str: &str = "Hello, world!";

let collection_of_chars: &str = my_str.chars().as_str();

Number Types in Rust

There are many types of numbers in Rust:

• Unsigned Integers: u8, u16, u32, u64, u128
• Signed Integers: i8, i16, i32, i64, i128
• Floating Point Numbers: f32, f64

Unsigned integers only represent positive whole numbers.

Signed integers represent both positive and negative whole numbers.

And floats only represent positive and negative fractions.

Structs in Rust

A struct is a custom data type used to group related data. You have already come across a struct in the Strings and Slices section:

struct String {
  vec: Vec<u8>,
}

The String struct consists of a vec field, which is a Vec of u8s. The Vec is a dynamically-sized array.

An instance of a struct is then declared by giving values to the fields:

struct MyStruct {
  field_1: u8,
}

let my_struct = MyStruct { field_1: 0, };

Previously, the String struct was used with its from function to create a String from a &str. This is possible, because the from function is implemented for String:

impl String {
  fn from(s: &str) -> Self {
    String {
      vec: Vec::from(s.as_bytes()),
    }
  }
}

You use the Self keyword in place of the type of the struct.

Structs can also take other variants:

struct MyUnitStruct;
struct MyTupleStruct(u8, u8);

Enums in Rust

Similar to other languages, enums are useful for acting as types and as values.

enum MyErrors {
  BrainTooTired,
  TimeOfDay(String)
  CoffeeCupEmpty,
}

fn work() -> Result<(), MyErrors> { // Result is also an enum
  if state == "missing semi-colon" {
    Err(MyErrors::BrainTooTired)
  } else if state == "06:00" {
    Err(MyErrors::TImeOfDay("It's too early to work".to_string()))
  } else if state == "22:00" {
    Err(MyErrors::TimeOfDay("It's too late to work".to_string()))
  } else if state == "empty" {
    Err(MyErrors::CoffeeCupEmpty)
  } else {
    Ok(())
  }
}

Macros in Rust

A macro is similar to a function, but you can think of it as a piece of code which writes other code. For now, the main differences between a function and a macro to keep in mind are:

• Macros are called using a bang (!)
• Macros can take a variable number of arguments, while functions in Rust cannot

One of the most common macros is the println! macro, which prints to the console:

let my_str = "Hello, world!";
println!("{}", my_str);

You use the {} syntax to insert a variable into a string.

Another common macro is panic!. Panicking is Rust's way of 'erroring out'. It is wise to think of a panic in Rust as a poorly-handled error. The macro accepts a string literal, and panics with that message.

let am_i_an_error = true;

if (am_i_an_error) {
  panic!("There was an error");
}

$ cargo run
   Compiling fcc-rust-in-replit v0.1.0 (/home/runner/Rust-in-Replit)
    Finished dev [unoptimized + debuginfo] target(s) in 1.66s
     Running `target/debug/calculator`
thread 'main' panicked at 'There was an error', src/main.rs
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace

Ownership in Rust

An important concept in Rust is ownership. There are three main ownership rules:

• Each value in Rust has a variable that's called its owner.
• There can only be one owner at a time.
• When the owner goes out of scope, the value will be dropped.
  (Source: The Rust Book)

This is how Rust gets away with not having a typical garbage collector, whilst also not requiring the programmer to explicitly manage memory. Here is an example of ownership:

fn main() { // first_string is not declared yet -> has no value
  let first_string = String::from("freeCodeCamp"); // first_string is now owner of the value "freeCodeCamp"
  let second_string = first_string; // second_string takes ownership of the value "freeCodeCamp"

  println!("Hello, {}!", first_string); // first_string is NOT valid, because the value was moved to second_string
}

As the println! macro tries to refer to an invalid variable, this code does not compile. To fix this, instead of moving the value of first_string into second_string, second_string can be assigned a reference to first_string:

fn main() {
  let first_string: String = String::from("freeCodeCamp");
  let second_string: &String = &first_string; // first_string is still the owner of the value "freeCodeCamp"

  println!("Hello, {}!", first_string);
}

The ampersand (&) indicates that the value is a reference. That is, second_string no longer takes ownership of "freeCodeCamp", but, instead, points to the same point in memory as first_string.

Project #1 – Build a CLI Calculator in Rust

Project Outcome

At the end of this project, you will be able to perform basic arithmetic operations on numbers using the command line.

Examples of expected input and output look like this:

$ calculator 1 + 1
$ 1 + 1 = 2

$ calculator 138 / 4
$ 138 / 4 = 34.5

CLI Calculator Project Methodology

Step 1 – Create a New Project

Use Cargo to create a new project named calculator:

$ cargo new calculator

This creates a new directory named calculator, initialises it as a Git repository, and adds useful boilerplate for your project.

The boilerplate includes:

• Cargo.toml – The manifest file used by Cargo to manage your project's metadata
• src/ – The directory where your project code should live
• src/main.rs – The default file Cargo uses as your application entrypoint

Step 2 – Understand the Syntax

The calculator/Cargo.toml file contains the following:

[package]
name = "calculator"
version = "0.1.0"
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

The [package] denotes your project's metadata.

The [dependencies] heading denotes the crates your project depends on. Crates are like external libraries.

The calculator/src/main.rs file contains the following:

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

This file contains a function declaration with the handle main. By default, rustc calls the main function first whenever the executable is run.

println! is a built-in macro which prints to the console.

Step 3 – Run the Project

You can either use Cargo to run your project code:

# Within the calculator/ directory
$ cargo run
   Compiling fcc-rust-in-replit v0.1.0 (/home/runner/Rust-in-Replit-1)
    Finished dev [unoptimized + debuginfo] target(s) in 0.80s
     Running `target/debug/calculator`
Hello, world!

Or, you can use rustc to compile your project, then you can run the binary:

# Within the calculator/ directory
$ rustc src/main.rs
$ ./main
Hello, world!

Step 4 – Command Line Arguments

The Rust standard library comes with an env module, which allows access to the command line arguments passed when calling the program.

The necessary exports from the env module are the args function, and the Args struct. The args function returns an instance of the Args struct, and is imported into the file scope with:

use std::env::{args, Args};

To get an idea of what the Args struct looks like, the args variable is printed to the console:

fn main() {
  let args: Args = args();
  println!("{:?}", args);
}

$ cargo run -- fCC
   Compiling calculator v0.1.0 (/home/runner/Rust-in-Replit/calculator)
    Finished dev [unoptimized + debuginfo] target(s) in 1.71s
     Running `target/debug/calculator`
Args { inner: ["target/debug/toto", "fCC"] }

The above shows that the Args struct contains a field called inner which consists of the location of the compiled binary, and the command line arguments passed to the program.

To access the argument values, you can use the nth method on the args variable. The nth method takes an index argument, and returns the value at that index wrapped in an Option. So, the value needs to be unwrapped.

fn main() {
  let mut args: Args = args();

  let first: String = args.nth(1).unwrap();
}

The args variable needs to be declared as mutable, because the nth method mutable iterates over the elements, and removes the element accessed.

fn main() {
  let mut args: Args = args();

  // The first argument is the location of the compiled binary, so skip it
  let first: String = args.nth(1).unwrap();
  // After accessing the second argument, the iterator's next element becomes the first
  let operator: String = args.nth(0).unwrap();
  let second: String = args.nth(0).unwrap();

  println!("{} {} {}", first, operator, second);
}

$ cargo run -- 1 + 1
   Compiling calculator v0.1.0 (/home/runner/Rust-in-Replit/calculator)
    Finished dev [unoptimized + debuginfo] target(s) in 1.71s
     Running `target/debug/calculator`
1 + 1

Step 5 – Parse Strings into Numbers

The first and second variables are strings, and you need to parse them into numbers. The String struct implements the parse method, which takes a type annotation, and returns a Result containing the parsed value.

use std::env::{args, Args};

fn main() {
  let mut args: Args = args();

  let first: String = args.nth(1).unwrap();
  let operator: String = args.nth(0).unwrap();
  let second: String = args.nth(0).unwrap();

  let first_number = first.parse::<f32>().unwrap();
  let second_number = second.parse::<f32>().unwrap();

  println!("{} {} {}", first_number, operator, second_number);
}

The above parse method uses the turbofish syntax to specify the type to try to parse the string into.

Step 6 – Perform Basic Arithmetic Operations

Rust uses the standard operators for addition, subtraction, multiplication, and division.

To handle the operations, you define a function named operate which will take three arguments: the operator as a char, and the two numbers as f32s. The function should also return an f32 representing the outcome of the operation.

fn operate(operator: char, first_number: f32, second_number: f32) -> f32 {
  match operator {
    '+' => first_number + second_number,
    '-' => first_number - second_number,
    '/' => first_number / second_number,
    '*' | 'X' | 'x' => first_number * second_number,
    _ => panic!("Invalid operator used."),
  }
}

The match expression works similarly to a switch statement in other languages. The match expression takes a value, and a list of arms. Each arm is a pattern and block. The pattern is a value to match against, and the block is the code to execute if the pattern matches. The _ pattern is a wildcard, acting like an else clause.

The multiplication arm includes the OR comparison to allow cases for X and x to be handled.

Now, to call operate with the operator, you need to converted it into a char first. You do this with the chars method on the String struct which returns an iterator over the characters in the string. Then, the first character is unwrapped:

fn main() {
  let mut args: Args = args();

  let first: String = args.nth(1).unwrap();
  let operator: char = args.nth(0).unwrap().chars().next().unwrap();
  let second: String = args.nth(0).unwrap();

  let first_number = first.parse::<f32>().unwrap();
  let second_number = second.parse::<f32>().unwrap();
  let result = operate(operator, first_number, second_number);

  println!("{} {} {}", first_number, operator, second_number);
}

The return of operate is stored in the result variable.

Step 7 – Format the Output

To get the desired output, the first_number, second_number, operator, and result variables need to be formatted. You can use the format! macro to create a String from a format string and a list of arguments:

fn output(first_number: f32, operator: char, second_number: f32, result: f32) -> String {
  format!(
    "{} {} {} = {}",
    first_number, operator, second_number, result
  )
}

Step 8 – Bring It All Together

use std::env::{args, Args};

fn main() {
  let mut args: Args = args();

  let first: String = args.nth(1).unwrap();
  let operator: char = args.nth(0).unwrap().chars().next().unwrap();
  let second: String = args.nth(0).unwrap();

  let first_number = first.parse::<f32>().unwrap();
  let second_number = second.parse::<f32>().unwrap();
  let result = operate(operator, first_number, second_number);

  println!("{}", output(first_number, operator, second_number, result));
}

fn output(first_number: f32, operator: char, second_number: f32, result: f32) -> String {
  format!(
    "{} {} {} = {}",
    first_number, operator, second_number, result
  )
}

fn operate(operator: char, first_number: f32, second_number: f32) -> f32 {
  match operator {
    '+' => first_number + second_number,
    '-' => first_number - second_number,
    '/' => first_number / second_number,
    '*' | 'X' | 'x' => first_number * second_number,
    _ => panic!("Invalid operator used."),
  }
}

To build the code into an executable binary, run the following command:

$ cargo build --release
   Compiling calculator v0.1.0 (/home/runner/Rust-in-Replit/calculator)
    Finished release [optimized] target(s) in 3.26s

The --release flag tells Cargo to build the binary in release mode. This will reduce the size of the binary, and will also remove any debugging information.

The binary is built in the target/release directory. To run the binary, and test your application, run the following command:

$ target/release/calculator 1 + 1
1 + 1 = 2

Project #2 – Build an Image Combiner in Rust

Project Outcome

At the end of this project, you will be able to combine two images using the command line.

Here is an example of an expected input:

$ combiner ./image1.png ./image2.png ./output.png

For an example of the output, look no further than the first image in this article ☝️

Image Combiner Project Methodology

Step 1 - Create a New Project

Use Cargo to create a new project named combiner:

$ cargo new combiner

Step 2 - Add a New Module for Args

To prevent the main.rs file from becoming too overwhelming, create a new file named args.rs in the src directory.

Within args.rs, create a function named get_nth_arg which takes a usize, n, and returns a String. Then, from the std::env module, call the args function, and chain the nth method to get the nth argument, unwrapping the value:

fn get_nth_arg(n: usize) -> String {
  std::env::args().nth(n).unwrap()
}

Define a public struct named Args which consists of three public fields of type String: image_1, image_2, and output:

pub struct Args {
  pub image_1: String,
  pub image_2: String,
  pub output: String,
}

Declare the struct and its fields as public with the pub keyword so you can access them from outside the args.rs file.

Lastly, you can use the get_nth_arg function to create a new Args struct in a new function:

impl Args {
  pub fn new() -> Self {
    Args {
      image_1: get_nth_arg(1),
      image_2: get_nth_arg(2),
      output: get_nth_arg(3),
    }
  }
}

All together, the args.rs file looks like this:

pub struct Args {
  pub image_1: String,
  pub image_2: String,
  pub output: String,
}

impl Args {
  pub fn new() -> Self {
    Args {
      image_1: get_nth_arg(1),
      image_2: get_nth_arg(2),
      output: get_nth_arg(3),
    }
  }
}

fn get_nth_arg(n: usize) -> String {
  std::env::args().nth(n).unwrap()
}

Step 3 – Import and Use the args Module

Within main.rs, you need to declare the args.rs file as a module. Then, to use the Args struct, you need to import it:

mod args;
use args::Args;

fn main() {
  let args = Args::new();
  println!("{:?}", args);
}

But testing the code reveals an error:

$ cargo run -- arg1 arg2 arg3
   Compiling combiner v0.1.0 (/home/runner/Rust-in-Replit/combiner)
error[E0277]: `args::Args` doesn't implement `Debug`
  --> src/main.rs:12:20
   |
12 |   println!("{:?}", args);
   |                    ^^^^ `args::Args` cannot be formatted using `{:?}`
   |
   = help: the trait `Debug` is not implemented for `args::Args`
   = note: add `#[derive(Debug)]` or manually implement `Debug`
   = note: required by `std::fmt::Debug::fmt`
   = note: this error originates in a macro (in Nightly builds, run with -Z macro-backtrace for more info)

error: aborting due to previous error

For more information about this error, try `rustc --explain E0277`.
error: could not compile `combiner`

To learn more, run the command again with --verbose.

Similarly to how functions are implemented for structs, traits can be implemented for structs. However, the Debug trait is special in that it can be implemented using attributes:

#[derive(Debug)]
pub struct Args {
  pub image_1: String,
  pub image_2: String,
  pub output: String,
}

The Debug trait has been derived for the Args struct. This means that the Debug trait is automatically implemented for the struct, without you having to manually implement it 🚀.

Now, running the code works:

$ cargo run -- arg1 arg2 arg3
    Finished dev [unoptimized + debuginfo] target(s) in 0.01s
     Running `target/debug/combiner arg1 arg2 arg3`
Args { image_1: "arg1", image_2: "arg2", output: "arg3" }

Step 4 – Add an External Crate

In much the same way other languages have libraries or packages, Rust has crates. In order to encode and decode images, you can use the image crate.

Add the image crate with version 0.23.14 to the Cargo.toml file:

[package]
name = "combiner"
version = "0.1.0"
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
image = "0.23.14"

Now, when cargo run is next called, Cargo will fetch and install the image crate.

Step 5 – Read an Image File

The image crate comes with an io module including a Reader struct. This struct implements an open function which takes a path to an image file, and returns a Result containing a reader. You can format and decode this reader to yield the image format (for example PNG, JGP, and so on) and the image data.

Create a function named find_image_from_path to open the image file from a path argument:

fn find_image_from_path(path: String) -> (DynamicImage, ImageFormat) {
  let image_reader: Reader<BufReader<File>> = Reader::open(path).unwrap();
  let image_format: ImageFormat = image_reader.format().unwrap();
  let image: DynamicImage = image_reader.decode().unwrap();
  (image, image_format)
}

The image and image_format variables are returned as a tuple.

Include the necessary imports at the top of the file:

use image::{ io::Reader, DynamicImage, ImageFormat };

fn main() {
  // ...
  let (image_1, image_1_format) = find_image_from_path(args.image_1);
  let (image_2, image_2_format) = find_image_from_path(args.image_2);
}

Within main, the returned tuple can be destructured into two new variables for each image path.

Step 6 – Handle Errors with Result

It is important to be able to handle errors that come up. For example, you might have a case where two images of different formats are given as arguments to combine.

A semantic way of handling such an error is to return a Result which can consist of either an Ok or an Err.

fn main() -> Result<(), ImageDataErrors> {
  let args = Args::new();
  println!("{:?}", args);

  let (image_1, image_1_format) = find_image_from_path(args.image_1);
  let (image_2, image_2_format) = find_image_from_path(args.image_2);

  if image_1_format != image_2_format {
    return Err(ImageDataErrors::DifferentImageFormats);
  }
  Ok(())
}

The main function returns an Err containing an enum with unit variant DifferentImageFormats if the two image formats are not equal. Otherwise, it returns an Ok with an empty tuple.

The enum is defined as:

enum ImageDataErrors {
  DifferentImageFormats,
}

Step 7 – Resize the Images to Match

To make combining the images easier, you resize the largest image to match the smallest image.

First, you can find the smallest image using the dimensions method which returns the width and height of the image as a tuple. These tuples can be compared, and the smallest returned:

fn get_smallest_dimensions(dim_1: (u32, u32), dim_2: (u32, u32)) -> (u32, u32) {
  let pix_1 = dim_1.0 * dim_1.1;
  let pix_2 = dim_2.0 * dim_2.1;
  return if pix_1 < pix_2 { dim_1 } else { dim_2 };
}

The tuple values are accessed using dot-notation from zero-based indexing.

If image_2 is the smallest image, then image_1 needs to be resized to match the smallest dimensions. Otherwise, image_2 needs to be resized.

fn standardise_size(image_1: DynamicImage, image_2: DynamicImage) -> (DynamicImage, DynamicImage) {
  let (width, height) = get_smallest_dimensions(image_1.dimensions(), image_2.dimensions());
  println!("width: {}, height: {}\n", width, height);

  if image_2.dimensions() == (width, height) {
    (image_1.resize_exact(width, height, Triangle), image_2)
  } else {
    (image_1, image_2.resize_exact(width, height, Triangle))
  }
}

The resize_exact method implemented on the DynamicImage struct mutably borrows the image, and, using the width, height, and FilterType arguments, resizes the image.

Using the return of the standardise_size function, you can redeclare the image_1 and image_2 variables:

use image::{ io::Reader, DynamicImage, ImageFormat, imageops::FilterType::Triangle };

fn main() -> Result<(), ImageDataErrors> {
  // ...
  let (image_1, image_2) = standardise_size(image_1, image_2);
  Ok(())
}

Step 8 – Create a Floating Image

To handle the output, create a temporary struct to hold the metadata for the output image.

Define a struct named FloatingImage to hold the width, height, and data of the image, as well as the name of the output file:

struct FloatingImage {
  width: u32,
  height: u32,
  data: Vec<u8>,
  name: String,
}

Next, implement a new function for FloatingImage which takes values for the width, height, and name of the output image:

impl FloatingImage {
  fn new(width: u32, height: u32, name: String) -> Self {
    let buffer_capacity = 3_655_744;
    let buffer: Vec<u8> = Vec::with_capacity(buffer_capacity);
    FloatingImage {
      width,
      height,
      data: buffer,
      name,
    }
  }
}

As you haven't created the data for the image yet, create a buffer in the form of a Vec of u8s with a capacity of 3,655,744 (956 x 956 x 4). The <number>_<number> syntax is Rust's easy-to-read numbering which separates the number into groups or three digits.

Use the image_1 variable's width and height values to create an instance of the FloatingImage, and use the third argument stored in args to set the name of the FloatingImage:

fn main() -> Result<(), ImageDataErrors> {
  // ...
  let mut output = FloatingImage::new(image_1.width(), image_1.height(), args.output);
  Ok(())
}

Declare the output variables as mutable so you can modify the data field later.

Step 9 – Create the Combined Image Data

In order to process the images, you need to convert them into a vector of RGBA pixels. The pixels are stored as u8s, because their values are between 0 and 255.

The DynamicImage struct implements the to_rgba8 method, which returns an ImageBuffer containing a Vec<u8>, and the ImageBuffer implements the into_vec method, which returns the Vec<u8>:

fn combine_images(image_1: DynamicImage, image_2: DynamicImage) -> Vec<u8> {
  let vec_1 = image_1.to_rgba8().into_vec();
  let vec_2 = image_2.to_rgba8().into_vec();

  alternate_pixels(vec_1, vec_2)
}

Next, the vec_1 and vec_2 variables are passed to the alternate_pixels function which returns the combined image data by alternating the RGBA pixel sets of the two images:

fn alternate_pixels(vec_1: Vec<u8>, vec_2: Vec<u8>) -> Vec<u8> {
  // A Vec<u8> is created with the same length as vec_1
  let mut combined_data = vec![0u8; vec_1.len()];

  let mut i = 0;
  while i < vec_1.len() {
    if i % 8 == 0 {
      combined_data.splice(i..=i + 3, set_rgba(&vec_1, i, i + 3));
    } else {
      combined_data.splice(i..=i + 3, set_rgba(&vec_2, i, i + 3));
    }
    i += 4;
  }

  combined_data
}

The set_rgba function takes a reference to a Vec<u8>, and returns the RGBA pixel set for that Vec<u8> starting and ending at a given index:

fn set_rgba(vec: &Vec<u8>, start: usize, end: usize) -> Vec<u8> {
  let mut rgba = Vec::new();
  for i in start..=end {
    let val = match vec.get(i) {
      Some(d) => *d,
      None => panic!("Index out of bounds"),
    };
    rgba.push(val);
  }
  rgba
}

The ..= syntax is Rust's range syntax which allows the range to be inclusive of the end value. The * symbol before a variable is Rust's dereferencing operator, which allows the value of the variable to be accessed.

Then, assign the return of combine_images to the combined_data variable:

fn main() -> Result<(), ImageDataErrors> {
  // ...
  let combined_data = combine_images(image_1, image_2);
  Ok(())
}

Step 10 – Attach the Combined Data to the Floating Image

To set the data of combined_data into the output image, a method on FloatingImage is defined to set the data field of output to the value of combined_data.

So far, you've only implemented functions on structs. Methods are defined in a similar way, but they take an instance of the struct as their first argument:

struct MyStruct {
  name: String,
}
impl MyStruct {
  fn change_name(&mut self, new_name: &str) {
    self.name = new_name.to_string();
  }
}

let mut my_struct = MyStruct { name: String::from("Shaun") };
// my_struct.name == "Shaun"
my_struct.change_name("Tom");
// my_struct.name == "Tom"

Since you need to change the value of the instance of FloatingImage, the method set_data takes a mutable reference to the instance as its first argument.

impl FloatingImage {
  // ...
  fn set_data(&mut self, data: Vec<u8>) -> Result<(), ImageDataErrors> {
    // If the previously assigned buffer is too small to hold the new data
    if data.len() > self.data.capacity() {
      return Err(ImageDataErrors::BufferTooSmall);
    }
    self.data = data;
    Ok(())
  }
}

The enum needs to be extended to include the new unit variant BufferTooSmall:

enum ImageDataErrors {
  // ...
  BufferTooSmall,
}

Notice: The method is still only called with one argument:

fn main() -> Result<(), ImageDataErrors> {
  // ...
  output.set_data(combined_data)?;
  Ok(())
}

The ? syntax at the end of an expression is a shorthand way of handling the result of a function call. If the function call returns an error, the error propagation operator will return the error from the function call.

Step 11 – Write the Image to a File

Finally, save the new image to a file. The image crate has a save_buffer_with_format function taking the following form:

fn save_buffer_with_format(
    path: AsRef<Path>,
    buf: &[u8],
    width: u32,
    height: u32,
    color: image::ColorType,
    format: image::ImageFormat
  ) -> image::ImageResult<()>;

Seeing as AsRef is implemented for String, you can use an argument of type String for the path.

fn main() -> Result<(), ImageDataErrors> {
  // ...
  image::save_buffer_with_format(
    output.name,
    &output.data,
    output.width,
    output.height,
    image::ColorType::Rgba8,
    image_1_format,
  )
  .unwrap();
  Ok(())
}

Step 12 – Bring It All Together

Here's the final code:

mod args;

use args::Args;
use image::{
  imageops::FilterType::Triangle, io::Reader, DynamicImage, GenericImageView, ImageFormat,
};

fn main() -> Result<(), ImageDataErrors> {
  let args = Args::new();
  println!("{:?}", args);

  let (image_1, image_1_format) = find_image_from_path(args.image_1);
  let (image_2, image_2_format) = find_image_from_path(args.image_2);

  if image_1_format != image_2_format {
    return Err(ImageDataErrors::DifferentImageFormats);
  }

  let (image_1, image_2) = standardise_size(image_1, image_2);
  let mut output = FloatingImage::new(image_1.width(), image_1.height(), args.output);

  let combined_data = combine_images(image_1, image_2);

  output.set_data(combined_data)?;

  image::save_buffer_with_format(
    output.name,
    &output.data,
    output.width,
    output.height,
    image::ColorType::Rgba8,
    image_1_format,
  )
  .unwrap();
  Ok(())
}

enum ImageDataErrors {
  BufferTooSmall,
  DifferentImageFormats,
}

struct FloatingImage {
  width: u32,
  height: u32,
  data: Vec<u8>,
  name: String,
}

impl FloatingImage {
  fn new(width: u32, height: u32, name: String) -> Self {
    let buffer_capacity = 3_655_744;
    let buffer: Vec<u8> = Vec::with_capacity(buffer_capacity);
    FloatingImage {
      width,
      height,
      data: buffer,
      name,
    }
  }
  fn set_data(&mut self, data: Vec<u8>) -> Result<(), ImageDataErrors> {
    if data.len() > self.data.capacity() {
      return Err(ImageDataErrors::BufferTooSmall);
    }
    self.data = data;
    Ok(())
  }
}

fn find_image_from_path(path: String) -> (DynamicImage, ImageFormat) {
  let image_reader = Reader::open(path).unwrap();
  let image_format = image_reader.format().unwrap();
  let image = image_reader.decode().unwrap();
  (image, image_format)
}

fn standardise_size(image_1: DynamicImage, image_2: DynamicImage) -> (DynamicImage, DynamicImage) {
  let (width, height) = get_smallest_dimensions(image_1.dimensions(), image_2.dimensions());
  println!("width: {}, height: {}\n", width, height);
  if image_2.dimensions() == (width, height) {
    (image_1.resize_exact(width, height, Triangle), image_2)
  } else {
    (image_1, image_2.resize_exact(width, height, Triangle))
  }
}

fn get_smallest_dimensions(dim_1: (u32, u32), dim_2: (u32, u32)) -> (u32, u32) {
  let pix_1 = dim_1.0 * dim_1.1;
  let pix_2 = dim_2.0 * dim_2.1;
  return if pix_1 < pix_2 { dim_1 } else { dim_2 };
}

fn combine_images(image_1: DynamicImage, image_2: DynamicImage) -> Vec<u8> {
  let vec_1 = image_1.to_rgba8().into_vec();
  let vec_2 = image_2.to_rgba8().into_vec();

  alternate_pixels(vec_1, vec_2)
}

fn alternate_pixels(vec_1: Vec<u8>, vec_2: Vec<u8>) -> Vec<u8> {
  let mut combined_data = vec![0u8; vec_1.len()];

  let mut i = 0;
  while i < vec_1.len() {
    if i % 8 == 0 {
      combined_data.splice(i..=i + 3, set_rgba(&vec_1, i, i + 3));
    } else {
      combined_data.splice(i..=i + 3, set_rgba(&vec_2, i, i + 3));
    }
    i += 4;
  }

  combined_data
}

fn set_rgba(vec: &Vec<u8>, start: usize, end: usize) -> Vec<u8> {
  let mut rgba = Vec::new();
  for i in start..=end {
    let val = match vec.get(i) {
      Some(d) => *d,
      None => panic!("Index out of bounds"),
    };
    rgba.push(val);
  }
  rgba
}

Building the binary:

$ cargo build --release

Creating a combined image, using the images in freeCodeCamp/Rust-In-Replit:

$ ./target/release/combiner images/pro.png images/fcc_glyph.png images/output.png

And here's the result in images/output.png:

Conclusion

With that, you now know the basics of Rust.

There is still a lot to learn. So, watch this space for more content 😉.