Simple calculator

Sean Borg January 28, 2025

How to build a simple command line interface (CLI) calculator in Rust

I'm going to assume you already have rustup, if not that's step 0 to install rustup for more details on how to install go to rustup install

Command Line Notation

In this tutorial, we’ll show some commands used in the terminal. Lines that you should enter in a terminal all start with $. You don’t need to type the $ character; it’s the command line prompt shown to indicate the start of each command. Lines that don’t start with $ typically show the output of the previous command.

Step 1, setup

Having installed rustup there should be a command installed called cargo this is going to be our main tool for building our project and helping us get setup

Open a terminal/PowerShell, and move to a directory where you would like your project to live then run

$ cargo init simple-calculator

This will make a new directory called simple-calculator and put the necessary files for cargo to be able to build and run the program, see https://doc.rust-lang.org/book/ch01-03-hello-cargo.html for a better breakdown on all the files. Note: it also makes the folder a git directory adding a .gitingore for typically ignored build files

To run the program cargo has made cd into simple-calculator, run

$ cd simple-calculator
 
$ cargo run

this will build and run our program printing out something like

sean@lenovo-laptop ~/G/G/S/simple-calculator (main)> cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.06s
     Running `target/debug/simple-calculator`
Hello, world!

You have now made your first Rust program! 🥳 You may want to open the simple-calculator directory in your text editor of choice and look around at what files have been made checking out the following link for explanation on the files generated https://doc.rust-lang.org/book/ch01-03-hello-cargo.html

Step 2

Ok so we are going to make quite a leap forwards by adding a crate, for this step it's going to be a bit of a copy/paste job as there is a lot going on behind the scenes, there is more in depth explanation at stage 4 but for now I'll keep the explanation very light. P.S. stage 4 has the same headings as stage 2 so if you're unhappy with just copy and paste, you can jump down to get the explanation as you follow stage 2

Download crate

Getting input from the terminal can be complicated, thankfully there is a crate (Rust name for library) that makes things a lot easier called clap.

Thankfully cargo has a very easy way to download crates ready for our program with cargo add <crate> so to get clap we run

$ cargo add clap --features derive
    Updating crates.io index
      Adding clap v4.5.9 to dependencies.
             Features:
             + color
             + derive
             + error-context
             + help
             + std
             + suggestions
             + usage
             - cargo
             - debug
             - deprecated
             - env
             - string
             - unicode
             - unstable-doc
             - unstable-styles
             - unstable-v5
             - wrap_help
    Updating crates.io index

Amend the code

At this point you probably want to open the directory in your editor of choice

Then we want to edit our src/main.rs file to look like this

use clap::Parser;

/// Simple program to add 2 numbers
#[derive(Parser, Debug)]
#[command(version, about, long_about = None)]
struct Args {
    /// number 1
    num1: f64,

    /// Number 2
    num2: f64,
}

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

    let sum = args.num1 + args.num2;
    println!("The sum is {}", sum);
}

Build/Run the program

Moving back to the Terminal/PowerShell we can now run

$ cargo run 1 2
<a whole lot of build output>
The sum is 3

The <a whole lot of build output> is cargo very helpfully going to the internet to find the clap library, downloading it and putting it in the right places to compile our program

we can change these for any number now so

$ cargo run  3.1 2.5
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/simple-calculator 3.1 2.5`
The sum is 5.6

Awesome we now have a simple-summer where we can run cargo run <num1> <num2> num1 and 2 can be any number and it will add them together. This was a very fast tour of how to add a crate and clap, both extremely useful things that we shall delve into at a later stage

Note: minus numbers are a little weird maybe avoid them for now :)

Step 3

Ok step 2 was mostly getting clap for a way to get some input for our program. In this stage we shall delve into some Rust idioms with more explanation as to what we are doing.

For a real calculator we need 1 more input, the operation, so lets quickly add that to the Args struct so clap will take it as input.

Amend the struct to look like the bellow, adding the operation: char, line

struct Args {
    /// number 1
    num1: f64,

    /// Operator
    operation: char,

    /// Number 2
    num2: f64,
}

Now if we re-run the program as before, we can see a glimpse of the rust type system

$ cargo run  3.1 2.5
    Finished dev [unoptimized + debuginfo] target(s) in 0.19s
     Running `target/debug/simple-calculator 3.1 2.5`
error: invalid value '2.5' for '<OPERATION>': too many characters in string

For more information, try '--help'.

clap attempted to parse the 2.5 as the operation argument, as operation is specified as a char it is expecting a single character not a sequence of characters (string)

lets run the program how we would expect it to be ran

$ cargo run  3.1 + 2.5
    Finished dev [unoptimized + debuginfo] target(s) in 0.18s
     Running `target/debug/simple-calculator 3.1 + 2.5`
The sum is 5.6

Great with a + it works as expected

$ cargo run  3.1 - 2.5
    Finished dev [unoptimized + debuginfo] target(s) in 0.15s
     Running `target/debug/simple-calculator 3.1 - 2.5`
The sum is 5.6

to handle the operation changing we need some way to branch our code, we could use if statements but we want to handle the operator being multiple different things so a better approach is a match statement similar to a switch statement seen in languages like C/JS/Java/and others.

Lets add our match statement to the main function

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

    match args.operation {
        '+' => {
            let result = args.num1 + args.num2;
            println!("The result is {}", result);
        }
        '-' => {
            let result = args.num1 - args.num2;
            println!("The result is {}", result);
        }
    }
}

Unlike switch statement in other languages match has to be exhaustive (all possible values must be covered), which I have personally come to hugely appreciate but can be a pain sometimes

To show what I mean running the code as it currently stands we get a compile error!

$ cargo run  3 - 2
   Compiling simple-calculator v0.1.0 (/home/sean/GitDirs/Gitlab/Seam345/simple-calculator)
error[E0004]: non-exhaustive patterns: `'\0'..='*'`, `','`, `'.'..='\u{d7ff}'` and 1 more not covered
  --> src/main.rs:20:11
   |
20 |     match args.operation {
   |           ^^^^^^^^^^^^^^ patterns `'\0'..='*'`, `','`, `'.'..='\u{d7ff}'` and 1 more not covered
   |
   = note: the matched value is of type `char`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern as shown, or multiple match arms
   |
28 ~         },
29 +         _ => todo!()
   |

For more information about this error, try `rustc --explain E0004`.
error: could not compile `simple-calculator` (bin "simple-calculator") due to 1 previous error

to break down this output a little, first line is

error[E0004]: non-exhaustive patterns: `'\0'..='*'`, `','`, `'.'..='\u{d7ff}'` and 1 more not covered

The Error that happened (not very human understandable)

the next block of lines:

  --> src/main.rs:20:11
   |
20 |     match args.operation {
   |           ^^^^^^^^^^^^^^ patterns `'\0'..='*'`, `','`, `'.'..='\u{d7ff}'` and 1 more not covered
   |

displays the file and line that the error happened on src/main.rs:20:11, then bellow prints out the line with ^^ to indicate where the error is coming from, and again printing out the not very human understandable error.

The next block is what sets the rust compiler out from all other compilers

  = note: the matched value is of type `char`
help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern as shown, or multiple match arms
   |
28 ~         },
29 +         _ => todo!()
   |

For more information about this error, try `rustc --explain E0004`.

We get a human understandable way to fix our issue! Along with places to go to expand on this kind of issue.

I can't stress how useful this has been for me, the compiler has repeatedly acted as my coach while learning rust. And later down the line I have occasionally fallen back to not reading all the compiler output, spent a literal hour staring at a line (googling) trying to fix and issue only to realise the rest of the compiler message told me the fix needed.

So Let's take the suggestion and implement it, ideally with a match statement I would suggest we make a case for every possible variation but every unicode char is too many options.

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

    match args.operation {
        '+' => {
            let result = args.num1 + args.num2;
            println!("The result is {}", result);
        }
        '-' => {
            let result = args.num1 - args.num2;
            println!("The result is {}", result);
        }
        _ => todo!()
    }
}

Running this

$ cargo run  3 + 2
    Finished dev [unoptimized + debuginfo] target(s) in 0.16s
     Running `target/debug/simple-calculator 3 + 2`
The result is 5


$ cargo run  3 - 2
    Finished dev [unoptimized + debuginfo] target(s) in 0.16s
     Running `target/debug/simple-calculator 3 - 2`
The result is 1

We correctly get the result we expect :D

Awesome lets expand it a little for times and divide, our main function is now

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

    match args.operation {
        '+' => {
            let result = args.num1 + args.num2;
            println!("The result is {}", result);
        }
        '-' => {
            let result = args.num1 - args.num2;
            println!("The result is {}", result);
        }
        'x' | 'X' => {
            let result = args.num1 * args.num2;
            println!("The result is {}", result);
        }
        '/' => {
            let result = args.num1 / args.num2;
            println!("The result is {}", result);
        }
        _ => unimplemented!()
    }
}

I would like to point out the 'x' | 'X' => { here the | is an "or" statement so it will run the times block if we type x or X. Also if you wonder why x and not * it's because * on the terminal is a wildcard and gets us into some very sticky situations.

Running all the ways this can run we get

$ cargo run  3 - 2
   Compiling simple-calculator v0.1.0 (/home/sean/GitDirs/Gitlab/Seam345/simple-calculator)
    Finished dev [unoptimized + debuginfo] target(s) in 0.83s
     Running `target/debug/simple-calculator 3 - 2`
The result is 1
$ cargo run  3 + 2
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/simple-calculator 3 + 2`
The result is 5
$ cargo run  3 x 2
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/simple-calculator 3 x 2`
The result is 6
$ cargo run  3 X 2
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/simple-calculator 3 X 2`
The result is 6
$ cargo run  3 / 2
    Finished dev [unoptimized + debuginfo] target(s) in 0.07s
     Running `target/debug/simple-calculator 3 / 2`
The result is 1.5

Step 3.5

Different ways to write the same thing

First is we have repeated the println!("The result is {}", result);, but match statements can return values, so we can lift out the result into a variable using let result = match <variable> <code>

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

    let result = match args.operation {
        '+' => {
            args.num1 + args.num2
        }
        '-' => {
            args.num1 - args.num2
        }
        'x' | 'X' => {
            args.num1 * args.num2
        }
        '/' => {
            args.num1 / args.num2
        }
        _ => unimplemented!()
    };
    println!("The result is {}", result);
}

Things to note:

The end } of the match statement now has a semicolon after it whereas previously it didn't.
All the args.num1 <+-/*> args.num2 lines no-longer have a semicolon after them as they are now returning a value
- The book explains more technically why https://doc.rust-lang.org/book/ch03-03-how-functions-work.html#functions-with-return-values

Single line statements in a match expression don't need {} so long as we put a , at the end so we can reduce the match statement further with:

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

    let result = match args.operation {
        '+' => args.num1 + args.num2,
        '-' => args.num1 - args.num2,
        'x' | 'X' => args.num1 * args.num2,
        '/' => args.num1 / args.num2,
        _ => unimplemented!()
    };
    println!("The result is {}", result);
}

And lastly we can extract the whole match statement into a function

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

    let result = run_calculation(args.num1, args.operation, args.num2);
    println!("The result is {}", result);
}

fn run_calculation(num1: f64, operation: char, num2: f64) -> f64 {
    match operation {
        '+' => num1 + num2,
        '-' => num1 - num2,
        'x' | 'X' => num1 * num2,
        '/' => num1 / num2,
        _ => unimplemented!()
    }
}

Functions have the signature fn <name>(<parameters>) -> <return type>:

return type can be left out if we want to return nothing (technically it's returning -> (), buckets meaning unit).
Parameters, the form of <name>: <type> all parameters must have a type

Step 4

Looking back at step 2 there was a lot unexplained that I would like to go back to and cover. Headings are the same as stage 2 so you can reference what happened in stage 2 with the explanation here

Download crate

A Crate is best describe in the rust book https://doc.rust-lang.org/book/ch07-01-packages-and-crates.html

A crate can come in one of two forms: a binary crate or a library crate. Binary crates are programs you can compile to an executable that you can run, such as a command-line program or a server. Each must have a function called main that defines what happens when the executable runs. All the crates we’ve created so far have been binary crates.

Library crates don’t have a main function, and they don’t compile to an executable. Instead, they define functionality intended to be shared with multiple projects. For example, the rand crate we used in Chapter 2 provides functionality that generates random numbers. Most of the time when Rustaceans say “crate”, they mean library crate, and they use “crate” interchangeably with the general programming concept of a “library".

As mentioned above most crates are really libraries which is exactly what Clap is.

By default cargo gets all its crates from https://crates.io/ better explained here https://doc.rust-lang.org/cargo/guide/dependencies.html

crates.io is the Rust community’s central package registry that serves as a location to discover and download packages. cargo is configured to use it by default to find requested packages.

To depend on a library hosted on crates.io, add it to your Cargo.toml.

"add it to your Cargo.toml" but we didn't do that we ran cargo add clap --features derive cargo add is a helper program/function that saves us the tedious effort of:

going to https://crates.io/
finding clap https://crates.io/crates/clap
finding its latest version and writing the semver incantation in cargo. toml clap = "4.5.9"
- crates.io has a nice copy field for this
Confirming if there are any build features we need (we want derive)
- Build features are quite a complicated thing I'm going to skip them here, but here's a nice link https://doc.rust-lang.org/cargo/reference/features.html
Remembering that now we want a feature clap = "4.5.9" becomes clap = { version = "4.5.9", features = ["derive"] }
entering that into the cargo.toml file under [dependencies]
- if you checked cargo.toml before and after running cargo add clap --features derive you will see it added clap = { version = "4.5.9", features = ["derive"] }

None of this is particularly hard (except maybe the feature hunting, that's caught me out a lot its getting better though) but cargo add is a much simpler process if all you want is the latest version of a crate.

Amend the code (todo this needs some work)

So here we are using claps derive methods clap has a mini tutorial in its documentation, and extensive reference page for all its options.

This allows us to specify all our arguments and stuff in 1 neat struct

Structs are a custom type that you can build to fit various purposes https://doc.rust-lang.org/rust-by-example/custom_types/structs.html?highlight=struct#structures Specifically here this struct what clap will populate from the command line arguments, allowing us to later reference the user supplied data with statements like args.num1 later. Clap does this with the fancy annotations like #[derive(Parser, Debug)]that I really don't have the skill to explain but stuff like #[derive(Debug)] can be really handy for printing things out. This link kinda explains what these fancy things do https://doc.rust-lang.org/reference/attributes/derive.html

Build/Run the program (todo)

I would like to give a bit of an explanation to the <a whole lot of build output>

and also explain all the helper stuff clap has already generated for us like the ability to now run cargo run -- --help and then also explain why there is a -- after cargo run here

Step 5

Going forwards and many of the pitfalls I was dodging you might hit