Learning the Rust Programming Language

Source: The Rust Programming Language by Steve Klabnik and Carol Nichols (pdf) - Rust 1.50 / 2018

Enable Javascript to display Table of Contents.

Introduction

In general, this book assumes that you’re reading it in sequence from front to back.
There are project chapters (2, 12, 20 - doing some programming) and concept chapters (all others - explaining the programming language).
Source code is on GitHub: https://github.com/rust-lang/book/tree/main/src

Getting Started - Installation

Rust can be installed in different ways, this shows the installation with rustup:

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

[...]

1) Proceed with installation (default)
2) Customize installation
3) Cancel installation
>1

[...]

To configure your current shell, run:
source $HOME/.cargo/env
$
$ source $HOME/.cargo/env
$ rustc --version
rustc 1.53.0 (53cb7b09b 2021-06-17)
$

You need to have a C linker installed on your system
During the installation the metadata and toolchain will be installed to $HOME/.rustup
Cargo, rustc, rustup and other commands will be installed to $HOME/.cargo
The installer will modify $HOME/.profile and $HOME/.bashrc
After sourcing the environment file, call rustc --version to verify the installation

$ cp .profile .profile.orig
$ cp .bashrc .bashrc.orig
$
$ # install rust
$
$ diff .profile.orig .profile
27a28
> . "$HOME/.cargo/env"
$ diff .bashrc.orig .bashrc
128a129
> . "$HOME/.cargo/env"
$

The changes to .profile and .bashrc are limited to sourcing the environment file.

Rust can be updated by rustup update and uninstalled by rustup self uninstall. rustup doc will open the documentation in a web browser.

Getting Started - Hello World!

Rust source files end with *.rs
Source files have underscores to separate words - no blanks (e.g. hello_world.rs)

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

Function fn main is the entrance point - like in C/C++
The Rust standard style suggests having the opening curly bracket on the same line as the function declaration, adding once space between. Use rustfmt for automatic formatting.
Rust style indents with 4 spaces - not tabs
println!(...) calls a Rust macro - macros are handled later. println(...) would be a function call.

$ mkdir Projects/playground/hello_rust
$ cd Projects/playground/hello_rust
$ vi main.rs
$ rustc main.rs 
$ ls
main  main.rs
$ ./main 
Hello, world!
$ file main
main: ELF 64-bit LSB shared object, x86-64, version 1 (SYSV),
dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 3.2.0,
BuildID[sha1]=fcf290d46f244d46f80e05c5e5fa97eff197144b, with debug_info, not stripped
$

Write the source code to a *.rs file - in this example main.rs
Compile it with rustc
Get an Linux ELF executable called main

$ cat main.rs 
fn
main()
{
println!(
		"Hello, world!"
	
	);
}
$ rustc main.rs      # compiles !
$ rustfmt main.rs    # format with standard style
$ cat main.rs 
fn main() {
    println!("Hello, world!");
}
$

Rust compiler will (of course) compile any code style
Use rustfmt to format your code to the official style guide

Getting Started - Hello Cargo!

Libraries your code needs are called dependencies
Packages of code are called crates - those can be dependencies as well.
Cargo will build your code and handles it's dependencies
"Because the vast majority of Rust projects use Cargo, the rest of this book assumes that you’re using Cargo too"

Creating a new Rust project can be done with cargo like this:

$ cargo new hello_cargo
     Created binary (application) `hello_cargo` package
$ cd hello_cargo/
$ tree -a
.
├── Cargo.toml
├── .git
│   [...]
├── .gitignore
└── src
    └── main.rs

10 directories, 18 files
$

Creates a empty git repository + .gitignore
Creates Cargo.toml in TOML format (Tom’s Obvious, Minimal Language) - the Cargo configuration
Create a src/main.rs template for source code (hello world)

$ cat Cargo.toml 
[package]
name = "hello_cargo"
version = "0.1.0"
edition = "2018"

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

[dependencies]
$

There are two sections, the package section for configuring the package, the dependencies section for the dependencies.
We can add authors = ["Your Name <you@example.com>"] to the package section.
see https://doc.rust-lang.org/cargo/reference/manifest.html

$ cargo build
   Compiling hello_cargo v0.1.0 (/home/krach/Projects/playground/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.35s
$
$ ./target/debug/hello_cargo 
Hello, world!
$ cargo run
    Finished dev [unoptimized + debuginfo] target(s) in 0.00s
     Running `target/debug/hello_cargo`
Hello, world!
$ 
$ touch src/main.rs 
$ cargo run
   Compiling hello_cargo v0.1.0 (/home/krach/Projects/playground/hello_cargo)
    Finished dev [unoptimized + debuginfo] target(s) in 0.14s
     Running `target/debug/hello_cargo`
Hello, world!
$

cargo build builds the project
cargo build --release builds the project in release mode - which is faster but takes longer to compile
cargo run runs the executable (and also builds it if needed)
New file Cargo.lock keeps track of dependencies (cargo internal)
cargo check checks that the code would compile - is much faster as cargo build - e.g. for IDE

Programming a Guessing Game

First we create a new project...

21:49:26[rust]$ rustc --version
rustc 1.51.0
21:49:34[rust]$ cargo new guessing_game
     Created binary (application) `guessing_game` package
21:49:55[rust]$

And compiling and running the code...

21:49:55[rust]$ cd guessing_game/
21:51:02[guessing_game]$ cargo run
   Compiling guessing_game v0.1.0 (/home/charly/tmp/rust/guessing_game)
    Finished dev [unoptimized + debuginfo] target(s) in 0.70s
     Running `target/debug/guessing_game`
Hello, world!
21:51:18[guessing_game]$

In the next steps we expend the code:

With the keyword using we can bring a library into scope. Without the using std::io term we have to write std::io::stdin() instead of io::stdin(). There is a default set of type in scope - called the prelude.
let foo = 5; creates a constant (immutable) while
let mut bar = 42; creates a variable (mutable).
let mut guess = String::new(); creates a variable guess with a "growable, UTF-8 encoded bit of text".
::new means calling a associated function of the String type - in c++ a static function. The new function creates a empty string and is available on many types.
Passing variables as "call by reference" must be marked with an & - mutable variables with &mut. So calling the method fn read_line(buf: &mut String) looks like that: read_line(&mut guess)
The io::Result is an enumeration which can hold one value of a fix set of values (in our case Ok and Err), called enum's variants.
Results are tuples which hold a (return) value and an error code - e.g. in this case String and io::Error. This allows in the OK-case to work with the return value - and in error case to work with the error code.
io::Result has an expect method which acts like an assert in case of an error. In case of no error, it simply returns the value.
You get an warning, when calling a method which returns a Result but not handling the error code - e.g. with expect().
When using println! you can use {} as placeholder for a value, e.g. println!("x = {} and y = {}", x, y);
Defining a second variable with the same name will shadow the previous one. This is often used, when the type of a variable shall be converted - e.g. from String to i32.

Crates

A crate is a bundle of Rust sources.
There are binary crates (executables) and library crates.
Dependencies to library crates are defined in Cargo.toml. The dependencies are described with name and version.
The version follows SemVer. A version of 0.8.3 means that all crates greater equal 0.8.3 up to (exclusive) 0.9.0 may be used.
The Cargo.lock file specifies which concrete version is used - in this case 0.8.4. It is added to the versioning system. Explicit updates are done with cargo update.
Crates are downloaded from https://crates.io - also the rand library: https://crates.io/crates/rand

Adding the single rand library adds 9 implicit dependencies:

10:48:03[guessing_game]$ cat Cargo.lock | grep package | wc -l
1
10:48:15[guessing_game]$ ls -l target/debug/guessing_game
-rwxrwxr-x 2 charly charly 10794144 Aug 28 22:01 target/debug/guessing_game
10:48:19[guessing_game]$ gvim Cargo.toml 
10:48:25[guessing_game]$ git diff --unified=0 Cargo.toml | tail -n +5
@@ -9,0 +10 @@ edition = "2018"
+rand = "0.8.3"
10:48:45[guessing_game]$ cargo build
    Updating crates.io index
    Finished dev [unoptimized + debuginfo] target(s) in 0.83s
10:48:53[guessing_game]$ ls -l target/debug/guessing_game
-rwxrwxr-x 2 charly charly 10794152 Aug 29 10:39 target/debug/guessing_game
10:48:55[guessing_game]$ 
10:48:58[guessing_game]$ cat Cargo.lock | grep package | wc -l
10
10:49:00[guessing_game]$

Error Handling

When a method returns a value of type Result the compiler generates a warning when the error-code is not checked. This can be done in two ways. When an error is not expected, the expect() method can be used - it works like an assert and crashes the program when an error appears:

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

When it is likely that the method returns an error - e.g. in user-interaction - the error shall be handled:

        let guess: u32 = match guess.trim().parse() {
            Ok(num) => num,
            Err(e) => {
                println!("Got invalid input: {}", e);
                continue
            },
        };

Common Programming Concepts - Variables and Mutability

Variables are by default read-only: let x = 7;
Variables can be made mutable: let mut y = 8;
Constants are like immutable variables but must be annotated, uppercase, and cannot be set to a runtime computed value - e.g. a return code of a function: const Z: i32 = 9; (snake_case)
Shadowing allows to declare a variable more then once in the same scope - e.g. with a different type.

Common Programming Concepts - Data Types

Rust is statically typed, so it must know all types at compile time.
Error error[E0282]: type annotations needed says that Rust cannot figure out the correct type, e.g. in let guess: i32 = "42".parse().expect("Not a number!");
In Rust there are four scalar types: integers, floating-point numbers, Booleans, and characters
There are 12 integer types: i8, u8, i16, u16, i32, u32, i64, u64, i128, u128, isize, usize (where the last two are architecture dependent, e.g. 64 bit on a 64-bit machine)
You can use visual separators, e.g. 12_000 for 12000 (like in C++14 as 12'000)
You can write integers in dec (98_222), hex (0x1_7F_AE), octal (0o27_76_56) and binary (0b0001_0111_1111_1010_1110). Bytes (u8) can be written like this: b'A'
In debug mode a integer overflow causes a panic.
In release mode no checks are performed and on integer overflow a two’s complement wrapping occurs.
The standard library provides methods prefixed with wrapping_ (for explicitly wrapping around), checked_ (returns None on overflow), overflowing_ (provides additional bool) and saturating_ (staying at max/min).
Rust has two floating-point numbers: f32 and f64. f64 is the default because on modern machines they have roughly the same speed as f32.
Rust has a boolean type: bool with true and false as values.
Rust has a character type named char: let heart_eyed_cat = '😻'; It's Unicode and with a size of 4 bytes.
Rust has two primitive compound types: tuples and arrays

Tuples are a way to group together values of various types in fix size structure:

let first_tup = (500, 6.4, 1);
let second_tup: (i32, f64, u8) = (500, 6.4, 1);   // same as first_tup
let (x, y, z) = first_tup;                        // called destructing
let five_hundred = second_tup.0;
let six_point_four = second_tup.1;

Arrays are grouping together values of the same type in a fix size structure:

let a = [1, 2, 3, 4, 5];
let b: [i32; 5] = [1, 2, 3, 4, 5];   // same as array a
let c = [1; 5];                      // creates [1, 1, 1, 1, 1] (value is 1, size is 5)

let first = a[0];
let second = a[1];

Accessing the array outside it's range, Rust will panic.

Common Programming Concepts - Functions

Rust don't cares about the location of the function in the source - like Java, unlike C/C++
The parameter in the function signature must be declared with a type: fn another_function(x: i32) {
Statements are instructions that perform some action and do not return a value
- Creating a variable and assigning a value is a statement: let y = 6;
- A function is a statement
```
fn main() {
    let y = 6;
}
```
Expressions evaluate to a resulting value
- A math operation is an expression: 5 + 6
- Calling a function/macro is an expression
- A block can be an expression:
```
{
    let x = 3;
    x + 1
}
```
- Having a semicolon at the end of an expression, it turns it into a statement: expressions do not have a semicolon at the end
The last expression is the return value of a function:
```
fn plus_one(x: i32) -> i32 {
    x + 1
}
```
You can return early from a function by using the return keyword

Common Programming Concepts - Comments

not worth reading

Common Programming Concepts - Control Flow

Constructs for control flow of execution are if, else, else if, loop, while and for

    if number < 5 {
        println!("small number");
    } else if number > 100 {
        println!("big number");
    } else {
        println!("regular number");
    }

Conditions must be a bool.
If you have more than else if you might refactor your code with the match statement
inline if statement: let number = if value != 7 { 5 } else { 6 }; (both arms must have the same type, e.g. i32)

Infinite loop:

    let mut counter = 0;
    let result = loop {
        counter += 1;
        if counter == 10 {
            break counter * 2;
        }
    };

while loop:

    let a = [10, 20, 30, 40, 50];
    let mut index = 0;
    while index < 5 {
        println!("the value is: {}", a[index]);
        index += 1;
    }

alternative with for loop and iterator:

    let a = [10, 20, 30, 40, 50];
    for element in a.iter() {
        println!("the value is: {}", element);
    }

simple for loop:

    for number in (1..4).rev() {
        println!("{}!", number);
    }