1 Getting Started

1
2
3
4
5
6
7
8
9
10
11

$ cargo new proj

// build
$ cargo build //dev
$ cargo check
// build result
$ ./target/debug/proj
// build + run
$ cargo run	

$ cargo build --release  //prod

3 Common Concepts

1
2
3
4

// Raw identifiers
let r#fn = "this variable is named 'fn' even though that's a keyword";
// call a function named 'match'
r#match();

3-1 Variables and Mutability

1
2

let mut x = 5; // mutable
let x = 5; // imutable

3-1-1 Variables and Constants

• mut is not allowed with constants (always immutable).

• using the const keyword instead of let, and the type of the value must be annotated.

• Constants can be declared in any scope, including the global scope.

• Constants may be set only to a constant expression, not the result of a function call or any other value that could only be computed at runtime.

1

const MAX_POINTS: u32 = 100_000; // 100000

Constants are valid for the entire time a program runs, within the scope they were declared in.

3-1-2 Shadowing

1
2
3
4
5
6
7

fn main() {
    let x = 5;
    let x = x + 1;
    let x = x * 2;
    println!("The value of x is: {}", x);
}
// The value of x is: 12

By using let, we can perform a few transformations on a value but have the variable be immutable after those transformations have been completed.

The other difference between mut and shadowing is that because we’re effectively creating a new variable when we use the let keyword again, we can change the type of the value but reuse the same name.

1
2
3
4
5
6

let spaces = "   ";
let spaces = spaces.len();

// compile-time error
let mut spaces = "   ";
spaces = spaces.len();

3-2 Data Types

Rust is a statically typed language, which means that it must know the types of all variables at compile time.

1
2

let guess: u32 = "42".parse().expect("Not a number!");
// u32 is the type

3-2-1 Scalar

A scalar type represents a single value.

3-2-1-1 Integer

Each signed variant can store numbers from -(2^{n - 1}) to 2^{n - 1} - 1 inclusive, where n is the number of bits that variant uses. Unsigned variants can store numbers from 0 to 2^{n - 1}.

The isize and usize types depend on the kind of computer your program is running on.

3-2-1-2 Numeric

Can not operate two different types of nums.

3-2-1-3 Boolean

1
2
3
4

fn main() {
    let t = true;
    let f: bool = false; // with explicit type annotation
}

3-2-1-4 Character

1
2
3
4
5

fn main() {
    let c = 'z'; // not " "
    let z = 'ℤ';
    let heart_eyed_cat = '😻';
}

Rust’s char type represents a Unicode Scalar Value.

3-2-2 Compound Types

3-2-2-1 Tuple

1
2
3
4
5
6
7
8
9
10

fn main() {
    let tup: (i32, f64, u8) = (500, 6.4, 1);
    let (x, y, z) = tup;
    println!("The value of x y z is: {} {} {}", x, y, z);
    
    let x: (i32, f64, u8) = (500, 6.4, 1);
    let five_hundred = x.0;
    let six_point_four = x.1;
    let one = x.2;
}

3-2-2-2 Array

Unlike a tuple, every element of an array must have the same type. Arrays have a fixed length, like tuples.

1
2
3

fn main() {
    let a = [1, 2, 3, 4, 5];
}

A vector is a similar collection type provided by the standard library that is allowed to grow or shrink in size. If not sure, use a vector.

1
2
3
4

fn main() {
    let a: [i32; 5] = [1, 2, 3, 4, 5];
    let first = a[0];
}

The first (i32) is the type of each element. Since all elements have the same type, just list it once.

After the semicolon, there’s a number that indicates the length of the array.

3-3 Functions

3-3-1 Parameters

1
2
3
4
5
6
7
8

fn main() {
    another_function(5, 6);
}

fn another_function(x: i32, y: i32) {
    println!("The value of x is: {}", x);
    println!("The value of y is: {}", y);
}

must declare the type of each parameter.

3-3-2 Statements and Expressions

Cannot write x = y = 6 .

1
2
3
4
5
6
7
8
9

fn main() {
    let x = 5;
    let y = {
        let x = 3;
        x + 1
    };
    println!("The value of y is: {}", y);
}
// y=4

That value gets bound to y as part of the letstatement. Note the x + 1 line without ; at the end.

Expressions do not include ;. If added it’s a statement, which will then not return a value.

3-3-3 Return Values

Declare their type after an arrow (->). In Rust, the return value of the function is synonymous with the value of the final expression in the block of the body of a function.

You can return early from a function by using the return keyword and specifying a value, but most functions return the last expression implicitly.

1
2
3
4
5
6
7
8

fn five() -> i32 {
    5 // also can be written to: `return 5`, `return 5;`
}

fn main() {
    let x = five();
    println!("The value of x is: {}", x);
}

3-4 Control Flow

3.4.1 if

1
2
3
4
5
6
7
8
9
10

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 {
        println!("number is not divisible by 4 or 3");
    }
}

The condition in this code must be a bool.

Rust only executes the block for the first true condition, and once it finds one, it doesn’t even check the rest.

Using too many else if expressions can clutter the code, so we use match.

1
2
3
4
5
6
7
8
9

fn main() {
    let condition = true;
    let number = if condition {
        5
    } else {
        6
    };
    println!("The value of number is: {}", number);
}

3-4-2 Repetition

3-4-2-1 loop

1
2
3
4
5
6
7
8
9
10

fn main() {
    let mut counter = 0;
    let result = loop {
        counter += 1;
        if counter == 10 {
            break counter * 2;
        }
    };
    assert_eq!(result, 20);
}

3-4-2-2 while

1
2
3
4
5
6
7
8

fn main() {
    let mut number = 3;
    while number != 0 {
        println!("{}!", number);
        number = number - 1;
    }
    println!("LIFTOFF!!!");
}

3-4-2-3 for

1
2
3
4
5
6
7
8

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

This approach is error prone; we could cause the program to panic if the index length is incorrect. It’s also slow, because the compiler adds runtime code to perform the conditional check on every element on every iteration through the loop.

As a more concise alternative, you can use a for loop and execute some code for each item in a collection.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

fn main() {
    for number in (1..4).rev() {
        println!("{}!", number);
    }
    println!("LIFTOFF!!!");
}
// 3!
// 2!
// 1!
// LIFTOFF!!!

4 Understanding Ownership

4-1 What Is Ownership?

Rust uses a third approach: memory is managed through a system of ownership with a set of rules that the compiler checks at compile time. None of the ownership features slow down your program while it’s running.

堆和栈：

• 栈：速度快（最上面的那个），大小固定；函数调用。
• 堆：速度慢（指派空间，指针跳转）；减少堆上数据复制，及时清理未使用的数据。

4-1-1 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.

4-1-2 Variable Scope

1
2
3
4

{                      // s is not valid here, it’s not yet declared
    let s = "hello";   // s is valid from this point forward
    // do stuff with s
}

4-1-3 The String Type

1
2
3
4

let mut s = String::from("hello");
s.push_str(", world!"); // push_str() appends a literal to a String

println!("{}", s); // `hello, world!`

4-1-4 Memory and Allocation

With the String type, in order to support a mutable, growable piece of text, we need to allocate an amount of memory on the heap, unknown at compile time, to hold the contents. This means:

• The memory must be requested from the operating system at runtime: when we call String::from, its implementation requests the memory it needs.
• Returning this memory to the operating system when we’re done with our String: the memory is automatically returned (use a function called drop) once the variable that owns it goes out of scope.

4-1-4-1 Move

1
2

let s1 = String::from("hello");
let s2 = s1;

A String is made up of three parts:

• a pointer to the memory that holds the contents of the string
• a length
• a capacity.

This group of data is stored on the stack. On the right is the memory on the heap that holds the contents.

The length is how much memory, in bytes, the contents of the String is currently using. The capacity is the total amount of memory, in bytes, that the String has received from the operating system.

When we assign s1 to s2, the String data is copied, meaning we copy the pointer, the length, and the capacity that are on the stack. We do not copy the data on the heap that the pointer refers to.

Both data pointers pointing to the same location. This is a problem: when s2 and s1 go out of scope, they will both try to free the same memory. This is known as a double free error and is one of the memory safety bugs. Freeing memory twice can lead to memory corruption, which can potentially lead to security vulnerabilities.

Instead of trying to copy the allocated memory, Rust let s1 invalid, so that we do not need to care s1 any more. That’s a bit like “shallow copy”, but in Rust we call it “move”.

1
2
3
4
5

let s1 = String::from("hello");
let s2 = s1;

println!("{}, world!", s1); // s1 is invalid
// error[E0382]: use of moved value: `s1`

In addition, there’s a design choice that’s implied by this: Rust will never automatically create “deep” copies of your data. Therefore, any automatic copying can be assumed to be inexpensive in terms of runtime performance.

4-1-4-2 Clone

If we do want to deeply copy the heap data of the String, not just the stack data, we can use a common method called clone.

1
2
3
4

let s1 = String::from("hello");
let s2 = s1.clone();

println!("s1 = {}, s2 = {}", s1, s2);

4-1-4-3 Copy

1
2
3
4

let x = 5;
let y = x;

println!("x = {}, y = {}", x, y);

Here, we don’t have a call to clone, but x is still valid and wasn’t moved into y.

The reason is that types such as integers that have a known size at compile time are stored entirely on the stack, so copies of the actual values are quick to make. There’s no difference between deep and shallow copying here, so calling clone wouldn’t do anything different from the usual shallow copying and we can leave it out.

As a general rule, any group of simple scalar values can be Copy, and nothing that requires allocation or is some form of resource is Copy.

• All the integer types, such as u32.
• The Boolean type, bool, with values true and false.
• All the floating point types, such as f64.
• The character type, char.
• Tuples, if they only contain types that are also Copy. For example, (i32, i32) is Copy, but (i32, String) is not.

4-1-5 Ownership and Functions

The semantics for passing a value to a function are similar to those for assigning a value to a variable. Passing a variable to a function will move or copy, just as assignment does.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

fn main() {
    let s = String::from("hello");  // s comes into scope
    takes_ownership(s);             // s's value moves into the function...
                                    // ... and so is no longer valid here

    let x = 5;                      // x comes into scope
    makes_copy(x);                  // x would move into the function,
                                    // but i32 is Copy, so it’s okay to still
                                    // use x afterward
} // Here, x goes out of scope, then s. But because s's value was moved, nothing
  // special happens.

fn takes_ownership(some_string: String) { // some_string comes into scope
    println!("{}", some_string);
} // Here, some_string goes out of scope and `drop` is called. The backing
  // memory is freed.

fn makes_copy(some_integer: i32) { // some_integer comes into scope
    println!("{}", some_integer);
} // Here, some_integer goes out of scope. Nothing special happens.

4-1-6 Return Values and Scope

Returning values can also transfer ownership.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

fn main() {
    let s1 = gives_ownership();         // gives_ownership moves its return
                                        // value into s1
    let s2 = String::from("hello");     // s2 comes into scope
    let s3 = takes_and_gives_back(s2);  // s2 is moved into
                                        // takes_and_gives_back, which also
                                        // moves its return value into s3
} // Here, s3 goes out of scope and is dropped. s2 goes out of scope but was
  // moved, so nothing happens. s1 goes out of scope and is dropped.

fn gives_ownership() -> String {             // gives_ownership will move its
                                             // return value into the function
                                             // that calls it
    let some_string = String::from("hello"); // some_string comes into scope
    some_string                              // some_string is returned and
                                             // moves out to the calling function
}

// takes_and_gives_back will take a String and return one
fn takes_and_gives_back(a_string: String) -> String { // a_string comes into
                                                      // scope
    a_string  // a_string is returned and moves out to the calling function
}

It’s possible to return multiple values using a tuple.

1
2
3
4
5
6
7
8
9
10

fn main() {
    let s1 = String::from("hello");
    let (s2, len) = calculate_length(s1);
    println!("The length of '{}' is {}.", s2, len);
}

fn calculate_length(s: String) -> (String, usize) {
    let length = s.len(); // len() returns the length of a String
    (s, length)
}

But this is too much ceremony and a lot of work for a concept that should be common. Luckily for us, Rust has a feature for this concept, called references.

4-2 References and Borrowing

1
2
3
4
5
6
7
8
9
10

fn main() {
    let s1 = String::from("hello");
    let len = calculate_length(&s1);
    println!("The length of '{}' is {}.", s1, len);
}

fn calculate_length(s: &String) -> usize { // s is a reference to a String
    s.len()
} // Here, s goes out of scope. But because it does not have ownership of what
  // it refers to, nothing happens.

First, notice that all the tuple code in the variable declaration and the function return value is gone. Second, note that we pass &s1 into calculate_length and, in its definition, we take &Stringrather than String. These ampersands are references, and they allow you to refer to some value without taking ownership of it.

The &s1 syntax lets us create a reference that refers to the value of s1 but does not own it. We call having references as function parameters borrowing.

1
2
3
4
5
6
7
8
9
10

fn main() {
    let s = String::from("hello");
    change(&s);
}

fn change(some_string: &String) {
    some_string.push_str(", world");
}

// error[E0596]: cannot borrow immutable borrowed content `*some_string` as mutable

Just as variables are immutable by default, so are references. We’re not allowed to modify something we have a reference to.

4-2-1 Mutable References

1
2
3
4
5
6
7
8

fn main() {
    let mut s = String::from("hello");
    change(&mut s);
}

fn change(some_string: &mut String) {
    some_string.push_str(", world");
}

First, we had to change s to be mut. Then we had to create a mutable reference with &mut s and accept a mutable reference with some_string: &mut String.

But mutable references have one big restriction: you can have only one mutable reference to a particular piece of data in a particular scope.

1
2
3
4
5
6
7
8

let mut s = String::from("hello");

let r1 = &mut s;
let r2 = &mut s;

println!("{}, {}", r1, r2);

// error[E0499]: cannot borrow `s` as mutable more than once at a time

The benefit of having this restriction is that Rust can prevent data races at compile time. A data raceis similar to a race condition and happens when these three behaviors occur:

• Two or more pointers access the same data at the same time.
• At least one of the pointers is being used to write to the data.
• There’s no mechanism being used to synchronize access to the data.

Data races cause undefined behavior and can be difficult to diagnose and fix when you’re trying to track them down at runtime; Rust prevents this problem from happening because it won’t even compile code with data races!

As always, we can use curly brackets to create a new scope, allowing for multiple mutable references, just not simultaneous ones:

1
2
3
4
5
6
7
8

let mut s = String::from("hello");

{
    let r1 = &mut s;

} // r1 goes out of scope here, so we can make a new reference with no problems.

let r2 = &mut s;

A similar rule exists for combining mutable and immutable references. This code results in an error:

1
2
3
4
5
6
7
8
9

let mut s = String::from("hello");

let r1 = &s; // no problem
let r2 = &s; // no problem
let r3 = &mut s; // BIG PROBLEM

println!("{}, {}, and {}", r1, r2, r3);

// error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable

We also cannot have a mutable reference while we have an immutable one. However, multiple immutable references are okay because no one who is just reading the data has the ability to affect anyone else’s reading of the data.

4-2-2 Dangling References

1
2
3
4
5
6
7
8
9
10
11
12
13
14

fn main() {
    let reference_to_nothing = dangle();
}

fn dangle() -> &String { // dangle returns a reference to a String

    let s = String::from("hello"); // s is a new String

    &s // we return a reference to the String, s
} // Here, s goes out of scope, and is dropped. Its memory goes away.
  // Danger!

// this function's return type contains a borrowed value, but there is no value
// for it to be borrowed from.

Because s is created inside dangle, when the code of dangle is finished, s will be deallocated. But we tried to return a reference to it. That means this reference would be pointing to an invalid String.

4-3 The Slice Type

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

fn first_word(s: &String) -> usize {
    let bytes = s.as_bytes();

    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return i;
        }
    }

    s.len()
}

fn main() {
    let mut s = String::from("hello world");
    let word = first_word(&s); // word will get the value 5
    s.clear(); // this empties the String, making it equal to ""

    // word still has the value 5 here, but there's no more string that
    // we could meaningfully use the value 5 with. word is now totally invalid!
}

4-3-1 String Slices

1
2
3
4
5
6
7
8
9
10
11
12
13
14

let s = String::from("hello world");

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

// or
let hello = &s[0..=4];
let world = &s[6..=10];

// or
let hello = &s[..5];
let world = &s[6..];

// One Chinese Character placeholder is 3

The type that signifies “string slice” is written as &str

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

fn first_word(s: &String) -> &str {
    let bytes = s.as_bytes();
    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }
    &s[..]
}

fn main() {
    let mut s = String::from("hello world");
    let word = first_word(&s); // immutable
    s.clear(); // error!, mutable
    println!("the first word is: {}", word);
}

// cannot borrow `s` as mutable because it is also borrowed as immutable

Recall from the borrowing rules that if we have an immutable reference to something, we cannot also take a mutable reference. Because clear needs to truncate the String, it tries to take a mutable reference, which fails.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

fn first_word(s: &mut String) -> &str {
    let bytes = s.as_bytes();
    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }
    &s[..]
}

fn main() {
    let mut s = String::from("hello world");
    let word = first_word(&mut s); // mutable
    s.clear(); // error!, mutable twice
    println!("the first word is: {}", word);
}

//  cannot borrow `s` as mutable more than once at a time

4-3-1-1 String Literals Are Slices

1

let s = "Hello, world!";

The type of s here is &str: it’s a slice pointing to that specific point of the binary. This is also why string literals are immutable; &str is an immutable reference.

4-3-1-2 String Slices as Parameters

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

fn first_word(s: &str) -> &str {
    let bytes = s.as_bytes();
    for (i, &item) in bytes.iter().enumerate() {
        if item == b' ' {
            return &s[0..i];
        }
    }
    &s[..]
}

fn main() {
    let my_string = String::from("hello world");
    
    // first_word works on slices of `String`s
    let word = first_word(&my_string[..]);
    let my_string_literal = "hello world";
    
    // first_word works on slices of string literals
    let word = first_word(&my_string_literal[..]);
    
    // Because string literals *are* string slices already,
    // this works too, without the slice syntax!
    // see String Literals Are Slices
    let word = first_word(my_string_literal);
}

4-3-2 Other Slices

1
2

let a = [1, 2, 3, 4, 5];
let slice = &a[1..3];

This slice has the type &[i32]. It works the same way as string slices do, by storing a reference to the first element and a length.

5 Using Structs to Structure Related Data

5-1 Defining and Instantiating Structs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

struct User {
    username: String,
    email: String,
    sign_in_count: u64,
    active: bool,
}
// create an instance of the User struct, just like struct in C
let user1 = User {
    email: String::from("someone@example.com"),
    username: String::from("someusername123"),
    active: true,
    sign_in_count: 1,
};
// mutable
let mut user1 = User {
    email: String::from("someone@example.com"),
    username: String::from("someusername123"),
    active: true,
    sign_in_count: 1,
};
user1.email = String::from("anotheremail@example.com");

Note that the entire instance must be mutable; Rust doesn’t allow us to mark only certain fields as mutable. As with any expression, we can construct a new instance of the struct as the last expression in the function body to implicitly return that new instance.

1
2
3
4
5
6
7
8

fn build_user(email: String, username: String) -> User {
    User {
        email: email,
        username: username,
        active: true,
        sign_in_count: 1,
    }
}

5-1-1 Using the Field Init Shorthand When Variables and Fields Have the Same Name

1
2
3
4
5
6
7
8

fn build_user(email: String, username: String) -> User {
    User {
        email,
        username,
        active: true,
        sign_in_count: 1,
    }
}

5-1-2 Creating Instances From Other Instances With Struct Update Syntax

1
2
3
4
5
6
7
8
9
10
11

let user2 = User {
    email: String::from("another@example.com"),
    username: String::from("anotherusername567"),
    active: user1.active,
    sign_in_count: user1.sign_in_count,
};
let user2 = User {
    email: String::from("another@example.com"),
    username: String::from("anotherusername567"),
    ..user1
};

The syntax .. specifies that the remaining fields not explicitly set should have the same value as the fields in the given instance.

5-1-3 Using Tuple Structs without Named Fields to Create Different Types

Structs that look similar to tuples, called tuple structs.

typedef int myint; to define a meaningful data type.

1
2
3
4
5

struct Color(i32, i32, i32);
struct Point(i32, i32, i32);

let black = Color(0, 0, 0);
let origin = Point(0, 0, 0);

Each struct you define is its own type, even though the fields within the struct have the same types. Otherwise, tuple struct instances behave like tuples: you can destructure them into their individual pieces, you can use a .followed by the index to access an individual value, and so on.

5-1-4 Unit-Like Structs Without Any Fields

Unit-like structs can be useful in situations in which you need to implement a trait on some type but don’t have any data that you want to store in the type itself.

5-1-5 Ownership of Struct Data

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

struct User {
    username: &str,
    email: &str,
    sign_in_count: u64,
    active: bool,
}

fn main() {
    let user1 = User {
        email: "someone@example.com",
        username: "someusername123",
        active: true,
        sign_in_count: 1,
    };
}

// error[E0106]: missing lifetime specifier
// fix errors using owned types like String instead of references like &str.

5-2 An Example Program Using Structs

1
2
3
4
5
6
7
8
9

fn main() {
    let width1 = 30;
    let height1 = 50;
    println!("The area of the rectangle is {} square pixels.", area(width1, height1));
}

fn area(width: u32, height: u32) -> u32 {
    width * height
}

5-2-1 Refactoring with Tuples

1
2
3
4
5
6
7
8

fn main() {
    let rect1 = (30, 50);
    println!("The area of the rectangle is {} square pixels.", area(rect1));
}

fn area(dimensions: (u32, u32)) -> u32 {
    dimensions.0 * dimensions.1
}

5-2-2 Refactoring with Structs Adding More Meaning

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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

fn main() {
    let rect1 = Rectangle { width: 30, height: 50 };
	// borrow the struct rather than take ownership. 
    println!("The area of the rectangle is {} square pixels.", area(&rect1));
}

fn area(rectangle: &Rectangle) -> u32 {
    rectangle.width * rectangle.height
}

5-2-3 Adding Useful Functionality with Derived Traits

1
2
3
4
5
6
7
8
9
10
11
12
13

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

fn main() {
    let rect1 = Rectangle { width: 30, height: 50 };
    // error: `Rectangle` cannot be formatted with the default formatter
    println!("rect1 is {}", rect1); 
    println!("rect1 is {:?}", rect1);
    println!("rect1 is {:#?}", rect1);
}

5-3 Method Syntax

Methods are different from functions in that they’re defined within the context of a struct (or an enum or a trait object), and their first parameter is always self, which represents the instance of the struct the method is being called on.

5-3-1 Defining Methods

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

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

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

fn main() {
    let rect1 = Rectangle { width: 30, height: 50 };
    println!("The area of the rectangle is {} square pixels.", rect1.area());
}

Rust knows the type of self is Rectangle due to this method’s being inside the impl Rectangle context. Methods can take ownership of self, borrow self immutably as we’ve done here, or borrow self mutably, just as they can any other parameter.

We’ve chosen &self here for the same reason we used &Rectangle in the function version: we don’t want to take ownership, and we just want to read the data in the struct, not write to it. If we wanted to change the instance that we’ve called the method on as part of what the method does, we’d use &mut self as the first parameter.

5-3-2 Methods with More Parameters

1
2
3
4
5
6
7
8
9

impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }

    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

5-3-3 Associated Functions

Another useful feature of impl blocks is that we’re allowed to define functions within impl blocks that don’t take self as a parameter. These are called associated functions because they’re associated with the struct. They’re still functions, not methods, because they don’t have an instance of the struct to work with. You’ve already used the String::from associated function.

Associated functions are often used for constructors that will return a new instance of the struct.

1
2
3
4
5
6

impl Rectangle {
    fn square(size: u32) -> Rectangle {
        Rectangle { width: size, height: size }
    }
}
let sq = Rectangle::square(3);

5-3-4 Multiple impl Blocks

1
2
3
4
5
6
7
8
9
10
11
12

// just like
impl Rectangle {
    fn area(&self) -> u32 {
        self.width * self.height
    }
}

impl Rectangle {
    fn can_hold(&self, other: &Rectangle) -> bool {
        self.width > other.width && self.height > other.height
    }
}

6 Enums and Pattern Matching

6-1 Defining an Enum

That property of IP addresses makes the enum data structure appropriate, because enum values can only be one of the variants.

1
2
3
4

enum IpAddrKind {
    V4,
    V6,
}

6-1-1 Enum Values

1
2

let four = IpAddrKind::V4;
let six = IpAddrKind::V6;

1
2
3
4
5
6
7
8
9
10
11
12
13
14

struct IpAddr {
    kind: IpAddrKind,
    address: String,
}

let home = IpAddr {
    kind: IpAddrKind::V4,
    address: String::from("127.0.0.1"),
};

let loopback = IpAddr {
    kind: IpAddrKind::V6,
    address: String::from("::1"),
};

1
2
3
4
5
6
7

enum IpAddr {
    V4(String),
    V6(String),
}

let home = IpAddr::V4(String::from("127.0.0.1"));
let loopback = IpAddr::V6(String::from("::1"));

There’s another advantage to using an enum rather than a struct: each variant can have different types and amounts of associated data.

1
2
3
4
5
6
7

enum IpAddr {
    V4(u8, u8, u8, u8),
    V6(String),
}

let home = IpAddr::V4(127, 0, 0, 1);
let loopback = IpAddr::V6(String::from("::1"));

This code illustrates that you can put any kind of data inside an enum variant: strings, numeric types, or structs, for example. You can even include another enum!

1
2
3
4
5
6
7
8
9
10
11
12

struct Ipv4Addr {
    // --snip--
}

struct Ipv6Addr {
    // --snip--
}

enum IpAddr {
    V4(Ipv4Addr),
    V6(Ipv6Addr),
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

enum Message {
    Quit,
    Move { x: i32, y: i32 },
    Write(String),
    ChangeColor(i32, i32, i32),
}

struct QuitMessage; // unit struct
struct MoveMessage {
    x: i32,
    y: i32,
}
struct WriteMessage(String); // tuple struct
struct ChangeColorMessage(i32, i32, i32); // tuple struct

impl Message {
    fn call(&self) {
        // method body would be defined here
    }
}

let m = Message::Write(String::from("hello"));
m.call();

6-1-2 The Option Enum and Its Advantages Over Null Vlues

The problem isn’t really with the concept but with the particular implementation. As such, Rust does not have nulls, but it does have an enum that can encode the concept of a value being present or absent.

1
2
3
4
5
6
7
8
9

enum Option<T> {
    Some(T),
    None,
}

let some_number = Some(5);
let some_string = Some("a string");

let absent_number: Option<i32> = None;

If we use None rather than Some, we need to tell Rust what type of Option<T> we have, because the compiler can’t infer the type that the Some variant will hold by looking only at a None value.

So why is having Option<T> any better than having null? In short, because Option<T> and T (where T can be any type) are different types, the compiler won’t let us use an Option<T> value as if it were definitely a valid value.

1
2
3
4
5

let x: i8 = 5;
let y: Option<i8> = Some(5);
// i8 and Option<i8> are different types
let sum = x + y;
// error[E0277]: the trait bound `i8: std::ops::Add<std::option::Option<i8>>` is not satisfied

6-2 The match Control Flow Operator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter,
}

fn value_in_cents(coin: Coin) -> u32 {
    match coin {
        Coin::Penny => {
            println!("Lucky penny!");
            1
        },
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter => 25,
    }
}

6-2-1 Patterns that Bind to Values

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

#[derive(Debug)] // so we can inspect the state in a minute
enum UsState {
    Alabama,
    Alaska,
    // --snip--
}

enum Coin {
    Penny,
    Nickel,
    Dime,
    Quarter(UsState),
}

fn value_in_cents(coin: Coin) -> u32 {
    match coin {
        Coin::Penny => 1,
        Coin::Nickel => 5,
        Coin::Dime => 10,
        Coin::Quarter(state) => {
            println!("State quarter from {:?}!", state);
            25
        },
    }
}

6-2-2 Matching with Option<T>

1
2
3
4
5
6
7
8
9
10

fn plus_one(x: Option<i32>) -> Option<i32> {
    match x {
        None => None,
        Some(i) => Some(i + 1),
    }
}

let five = Some(5);
let six = plus_one(five);
let none = plus_one(None);

Combining match and enums is useful in many situations. You’ll see this pattern a lot in Rust code: match against an enum, bind a variable to the data inside, and then execute code based on it.

6-2-3 Matches Are Exhaustive

Rust knows that we didn’t cover every possible case and even knows which pattern we forgot! Matches in Rust are exhaustive: we must exhaust every last possibility in order for the code to be valid. Especially in the case of Option<T>, when Rust prevents us from forgetting to explicitly handle the None case, it protects us from assuming that we have a value when we might have null, thus making the billion-dollar mistake discussed earlier.

6-2-4 The _ Placeholder

1
2
3
4
5
6
7
8

let some_u8_value = 0u8;
match some_u8_value {
    1 => println!("one"),
    3 => println!("three"),
    5 => println!("five"),
    7 => println!("seven"),
    _ => (),
}

The _ will match all the possible cases that aren’t specified before it. The () is just the unit value, so nothing will happen in the _ case.

6-3 Concise Control Flow with if let

1
2
3
4
5
6
7
8
9

let some_u8_value = Some(0u8);
match some_u8_value {
    Some(3) => println!("three"),
    _ => (),
}

if let Some(3) = some_u8_value {
    println!("three");
}

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.

1
2
3
4
5
6
7
8
9
10
11
12

let mut count = 0;
match coin {
    Coin::Quarter(state) => println!("State quarter from {:?}!", state),
    _ => count += 1,
}

let mut count = 0;
if let Coin::Quarter(state) = coin {
    println!("State quarter from {:?}!", state);
} else {
    count += 1;
}

8 Common Collections

Unlike the built-in array and tuple types, the data 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.

8-1 Storing Lists of Values with Vectors

Vectors can only store values of the same type.

8-1-1 Create a New Vector

1
2

let v: Vec<i32> = Vec::new();
let v = vec![1, 2, 3];

It’s more common to create a Vec<T> that has initial values, and Rust provides the vec! macro for convenience.

8-1-2 Updating a Vector

1
2
3

let mut v = Vec::new();
v.push(5);
v.push(6);

The numbers we place inside are all of type i32, and Rust infers this from the data, so we don’t need the Vec<i32> annotation.

8-1-3 Dropping a Vector Drops Its Elements

1
2
3
4

{
    let v = vec![1, 2, 3, 4];
    // do stuff with v
} // <- v goes out of scope and is freed here

8-1-4 Reading Elements of Vectors

Both methods of accessing a value in a vector, either with indexing syntax or the get method.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

let v = vec![1, 2, 3, 4, 5];

let third: &i32 = &v[2];
println!("The third element is {}", third);
match v.get(2) {
    Some(third_or_other) => println!("The third element is {}", third_or_other),
    None => println!("There is no third element."),
}

let does_not_exist = &v[100]; // will cause panic
let does_not_exist = v.get(100); // return None without panic

let mut v = vec![1, 2, 3, 4, 5];
let first = &v[0];
v.push(6);
println!("The first element is: {}", first);
// error[E0502]: cannot borrow `v` as mutable because it is also borrowed as immutable

Why should a reference to the first element care about what changes at the end of the vector? This error is due to the way vectors work: 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 currently is. 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.

8-1-5 Iterating over the Values in a Vector

1
2
3
4
5
6
7
8
9

let v = vec![100, 32, 57];
for i in &v {
    println!("{}", i);
}

let mut v = vec![100, 32, 57];
for i in &mut v {
    *i += 50;
}

8-1-6 Using an Enum to Store Multiple Types

1
2
3
4
5
6
7
8
9
10
11

enum SpreadsheetCell {
    Int(i32),
    Float(f64),
    Text(String),
}

let row = vec![
    SpreadsheetCell::Int(3),
    SpreadsheetCell::Text(String::from("blue")),
    SpreadsheetCell::Float(10.12),
];

Rust needs to know what types will be in the vector at compile time so it knows exactly how much memory on the heap will be needed to store each element.

8-2 Storing UTF-8 Encoded Text with Strings

8-2-1 What Is a String?

Rust’s standard library also includes a number of other string types, such as OsString, OsStr, CString, and CStr. These string types can store text in different encodings or be represented in memory in a different way.

8-2-2 Creating a New String

1
2
3
4
5
6
7

let mut s = String::new();
let data = "initial contents";
let s = data.to_string();
let s = "initial contents".to_string();

let s = String::from("initial contents");
let hello = String::from("你好");

8-2-3 Updating a String

8-2-3-1 Appending to a String with push_str and push

1
2
3
4
5
6
7
8
9
10

let mut s = String::from("foo");
s.push_str("bar");

let mut s1 = String::from("foo");
let s2 = "bar";
s1.push_str(s2);
println!("s2 is {}", s2);

let mut s = String::from("lo");
s.push('l'); // must be char

The push_str method takes a string slice because we don’t necessarily want to take ownership of the parameter.

8-2-3-2 Concatenation with the + Operator or the format! Macro

1
2
3
4
5

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

fn add(self, s: &str) -> String {

First, s2 has an &, meaning that we’re adding a reference of the second string to the first string because of the s parameter in the add function: we can only add a &str to a String; we can’t add two String values together. But wait—the type of &s2 is &String, not &str, as specified in the second parameter to add. So why does it compile?

The reason we’re able to use &s2 in the call to add is that the compiler can coerce the &Stringargument into a &str. When we call the add method, Rust uses a deref coercion, which here turns &s2 into &s2[..]. Because add does not take ownership of the s parameter, s2 will still be a valid String after this operation.

Second, we can see in the signature that add takes ownership of self, because self does not have an &. This means s1 will be moved into the add call and 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. In other words, it looks like it’s making a lot of copies but isn’t; the implementation is more efficient than copying.

1
2
3
4
5
6

let s1 = String::from("tic");
let s2 = String::from("tac");
let s3 = String::from("toe");
let s = s1 + "-" + &s2 + "-" + &s3; // tic-tac-toe

let s = format!("{}-{}-{}", s1, s2, s3); // tic-tac-toe

8-2-4 Indexing into Strings

Rust strings don’t support indexing.

1
2
3

let s1 = String::from("hello");
let h = s1[0];
// compile error

8-2-4-1 Internal Representation

1
2
3

let hello = "Здравствуйте";
let answer = &hello[0]; // `str` cannot be indexed by `{integer}`
let answer = &hello[0::1]; // 3, [0::3] Зд, д takes two bytes of storage

8-2-4-2 Bytes and Scalar Values and Grapheme Clusters

Another point about UTF-8 is that there are actually three relevant ways to look at strings from Rust’s perspective: as bytes, scalar values, and grapheme clusters (the closest thing to what we would call letters).

Rust 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.

8-2-5 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. Therefore, Rust asks you to be more specific if you really need to use indices to create string slices. To be more specific in your indexing and indicate that you want a string slice, rather than indexing using [] with a single number, you can use [] with a range to create a string slice containing particular bytes:

1
2

let hello = "Здравствуйте";
let s = &hello[0..3];

8-2-6 Methods for Iterating Over Strings

If you need to perform operations on individual Unicode scalar values, the best way to do so is to use the chars method.

1
2
3
4
5
6

for c in "नमस्ते".chars() {
    println!("{}", c);
}
for b in "नमस्ते".bytes() {
    println!("{}", b);
}

8-2-7 Exercise

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

fn string_slice(arg: &str) { println!("{}", arg); }
fn string(arg: String) { println!("{}", arg); }

fn main() {
    string_slice("blue");
    string("red".to_string());
    string(String::from("hi"));
    string("rust is fun!".to_owned());
    string("nice weather".into());
    string(format!("Interpolation {}", "Station"));
    string_slice(&String::from("abc")[0..1]);
    string_slice(&"abc".to_string()[0..1]);
    string_slice("  hello there ".trim());
    string("Happy Monday!".to_string().replace("Mon", "Tues"));
    string("mY sHiFt KeY iS sTiCkY".to_lowercase());
}

8-3 Storing Keys with Associated Values in Hash Maps

8-3-1 Creating a New Hash Map

1
2
3
4
5
6
7
8
9

use std::collections::HashMap;

let mut scores = HashMap::new();
scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Yellow"), 50);

let teams  = vec![String::from("Blue"), String::from("Yellow")];
let initial_scores = vec![10, 50];
let scores: HashMap<_, _> = teams.iter().zip(initial_scores.iter()).collect();

Just like vectors, hash maps store their data on the heap. 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.

The type annotation HashMap<_, _> is needed here because it’s possible to collect into many different data structures and Rust doesn’t know which you want unless you specify. For the parameters for the key and value types, however, we use underscores, and Rust can infer the types that the hash map contains based on the types of the data in the vectors.

8-3-2 Hash Maps and Ownership

1
2
3
4
5
6

let field_name = String::from("Favorite color");
let field_value = String::from("Blue");

let mut map = HashMap::new();
map.insert(field_name, field_value);
// field_name and field_value are invalid at this point,

We aren’t able to use the variables field_name and field_value 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.

8-3-3 Accessing Values in a Hash Map

1
2

let team_name = String::from("Blue");
let score = scores.get(&team_name);

score will have the value that’s associated with the Blue team, and the result will be Some(&10). The result is wrapped in Some because get returns an Option<&V>; if there’s no value for that key in the hash map, get will return None.

1
2
3

for (key, value) in &scores {
    println!("{}: {}", key, value);
}

8-3-4 Updating a Hash Map

8-3-4-1 Overwriting a Value

1
2
3

scores.insert(String::from("Blue"), 10);
scores.insert(String::from("Blue"), 25);
println!("{:?}", scores); // {"Blue": 25}

8-3-4-2 Only Inserting a Value If the Key Has No Value

1
2

scores.entry(String::from("Yellow")).or_insert(50);
scores.entry(String::from("Blue")).or_insert(50);

The or_insert 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, 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.

8-3-4-3 Updating a Value Based on the Old Value

1
2
3
4
5
6
7
8
9

use std::collections::HashMap;

let text = "hello world wonderful world";
let mut map = HashMap::new();
for word in text.split_whitespace() {
    let count = map.entry(word).or_insert(0);
    *count += 1;
}
println!("{:?}", map); // {"world": 2, "hello": 1, "wonderful": 1}

The or_insert method actually returns a mutable reference (&mut V) to the value for this key.

8-3-5 Hashing Functions

By default, HashMap uses a “cryptographically strong”1 hashing function that can provide resistance to Denial of Service (DoS) attacks. 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.

9 Error Handling

Rust doesn’t have exceptions. Instead, it has the type Result<T, E> for recoverable errors and the panic! macro that stops execution when the program encounters an unrecoverable error.

9-1 Unrecoverable Errors with panic!

When the panic! macro executes, your program will print a failure message, unwind and clean up the stack, and then quit. This most commonly occurs when a bug of some kind has been detected and it’s not clear to the programmer how to handle the error.

By default, when a panic occurs, the program starts unwinding, which means Rust walks back up the stack and cleans up the data from each function it encounters. But this walking back and cleanup is a lot of work. The alternative is to immediately abort, 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 resulting 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:

1 2 3

>[profile.release] >panic = 'abort' >

1
2
3
4
5

fn main() {
    panic!("crash and burn");
}
// thread 'main' panicked at 'crash and burn', src/main.rs:2:4
// note: Run with `RUST_BACKTRACE=1` for a backtrace.

9-1-1 Using a panic! Backtrace

1
2
3
4
5
6

fn main() {
    let v = vec![1, 2, 3];
    v[99];
}
// thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', checkout/src/liballoc/vec.rs:1555:10
// note: Run with `RUST_BACKTRACE=1` for a backtrace.

Other languages, like C, will attempt to give you exactly what you asked for in this situation, even though it isn’t what you want: you’ll get whatever is at the location in memory that would correspond to that element in the vector, even though the memory doesn’t belong to the vector. 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 array.

To protect your program from this sort of vulnerability, if you try to read an element at an index that doesn’t exist, Rust will stop execution and refuse to continue.

This error points at a file we didn’t write, vec.rs. That’s the implementation of Vec<T> in the standard library. The code that gets run when we use [] on our vector v is in vec.rs, and that is where the panic! is actually happening.

The next 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 Rust 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 the lines mentioning your files are code that your code called; the lines below are code that called your code. These lines might include core Rust code, standard library code, or crates that you’re using. Let’s try getting a backtrace by setting the RUST_BACKTRACE environment variable to any value except 0.

RUST_BACKTRACE=1 cargo run

Debug symbols are enabled by default when using cargo build or cargo run without the --release flag.

9-2 Recoverable Errors with Result

1
2
3
4
5
6
7
8
9
10
11
12

use std::fs::File;

fn main() {
    let f = File::open("hello.txt");
    
    let f = match f {
    	Ok(file) => file,
        Err(error) => {
        	panic!("There was a problem opening the file: {:?}", error)
        },
    };
}

The return type of the File::open function is a Result<T, E>. The generic parameter T has been filled in here 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.

9-2-1 Matching on Different Errors

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let f = File::open("hello.txt");

    let f = match f {
        Ok(file) => file,
        Err(error) => match error.kind() {
            ErrorKind::NotFound => match File::create("hello.txt") {
                Ok(fc) => fc,
                Err(e) => panic!("Tried to create file but there was a problem: {:?}", e),
            },
            other_error => panic!("There was a problem opening the file: {:?}", other_error),
        },
    };
}

A more seasoned Rustacean might write this code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

use std::fs::File;
use std::io::ErrorKind;

fn main() {
    let f = File::open("hello.txt").unwrap_or_else(|error| {
        if error.kind() == ErrorKind::NotFound {
            File::create("hello.txt").unwrap_or_else(|error| {
                panic!("Tried to create file but there was a problem: {:?}", error);
            })
        } else {
            panic!("There was a problem opening the file: {:?}", error);
        }
    });
}

9-2-2 Shortcuts for Panic on Error unwrap and expect

unwrap is a shortcut method that is implemented just like the matchexpression, 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.

1
2
3
4
5
6

use std::fs::File;

fn main() {
    let f = File::open("hello.txt").unwrap();
}
// thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value:

expect, which is similar to unwrap, 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.

1
2
3
4
5
6

use std::fs::File;

fn main() {
    let f = File::open("hello.txt").expect("Failed to open hello.txt");
}
// thread 'main' panicked at 'Failed to open hello.txt:

9-2-3 Propagating Errors

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

use std::io;
use std::io::Read;
use std::fs::File;

fn read_username_from_file() -> Result<String, io::Error> {
    // returning a value of the type Result<T, E> with String and io::Error
    let f = File::open("hello.txt");

    let mut f = match f {
        Ok(file) => file,
        Err(e) => return Err(e),
    };

    let mut s = String::new();

    match f.read_to_string(&mut s) {
        Ok(_) => Ok(s),
        Err(e) => Err(e),
    }
}

9-2-4 A Shortcut for Propagating Errors the ? Operator

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

use std::io;
use std::io::Read;
use std::fs::File;

fn read_username_from_file() -> Result<String, io::Error> {
    let mut f = File::open("hello.txt")?;
    let mut s = String::new();
    f.read_to_string(&mut s)?;
    Ok(s)
}

fn read_username_from_file() -> Result<String, io::Error> {
    let mut s = String::new();
    File::open("hello.txt")?.read_to_string(&mut s)?;
    Ok(s)
}

use std::fs;

fn read_username_from_file() -> Result<String, io::Error> {
    fs::read_to_string("hello.txt")
}

9-2-5 The ? Operator Can Only Be Used in Functions That Return Result

Because it is defined to work in the same way as the match expression.

1
2
3
4
5
6
7
8
9

use std::fs::File;

fn main() {
    let f = File::open("hello.txt")?; // without mut, return ()
}
"""
error[E0277]: the `?` operator can only be used in a function that returns
`Result` or `Option` (or another type that implements `std::ops::Try`)
"""

However, we can change how we write the main function so that it does return a Result<T, E>:

1
2
3
4
5
6
7

use std::error::Error;
use std::fs::File;

fn main() -> Result<(), Box<dyn Error>> {
    let f = File::open("hello.txt")?;
    Ok(())
}

For now, you can read Box<dyn Error> to mean “any kind of error.”

9-3 To panic! or Not to panic!

When you choose to return a Result value, you give the calling code options rather than making the decision for it. The calling code could choose to attempt to recover in a way that’s appropriate for its situation, or it could decide that an Err value in this case is unrecoverable, so it can call panic! and turn your recoverable error into an unrecoverable one. Therefore, returning Result is a good default choice when you’re defining a function that might fail. In rare situations, it’s more appropriate to write code that panics instead of returning a Result.

9-3-1 Examples Prototype Code and Tests

If a method call fails in a test, you’d want the whole test to fail, even if that method isn’t the functionality under test. Because panic! is how a test is marked as a failure, calling unwrap or expect is exactly what should happen.

9-3-2 Cases in Which You Have More Information Than the Compiler

It would also be appropriate to call unwrap when you have some other logic that ensures the Result will have an Ok value, but the logic isn’t something the compiler understands. You’ll still have a Result value that you need to handle: whatever operation you’re calling still has the possibility of failing in general, even though it’s logically impossible in your particular situation. If you can ensure by manually inspecting the code that you’ll never have an Err variant, it’s perfectly acceptable to call unwrap. Here’s an example:

1
2
3

use std::net::IpAddr;

let home: IpAddr = "127.0.0.1".parse().unwrap();

We’re creating an IpAddr instance by parsing a hardcoded string. We can see that 127.0.0.1 is a valid IP address, so it’s acceptable to use unwrap here. However, having a hardcoded, valid string doesn’t change the return type of the parse method: we still get a Result value, and the compiler will still make us handle the Result as if the Err variant is a possibility because the compiler isn’t smart enough to see that this string is always a valid IP address. If the IP address string came from a user rather than being hardcoded into the program and therefore did have a possibility of failure, we’d definitely want to handle the Result in a more robust way instead.

9-3-3 Guidelines for Error Handling

It’s advisable to have your code panic when it’s possible that your code could end up in a bad state. In this context, a bad state is when some assumption, guarantee, contract, or invariant has been broken, such as when invalid values, contradictory values, or missing values are passed to your code—plus one or more of the following:

• The bad state is not something that’s expected to happen occasionally.
• Your code after this point needs to rely on not being in this bad state.
• There’s not a good way to encode this information in the types you use.

If someone calls your code and passes in values that don’t make sense, the best choice might be to call panic! and alert the person using your library to the bug in their code so they can fix it during development. Similarly, panic! is often appropriate if you’re calling external code that is out of your control and it returns an invalid state that you have no way of fixing.

However, when failure is expected, it’s more appropriate to return a Result than to make a panic!call. Examples include a parser being given malformed data or an HTTP request returning a status that indicates you have hit a rate limit. In these cases, returning a Result indicates that failure is an expected possibility that the calling code must decide how to handle.

When your code performs operations on values, your code should verify the values are valid first and panic if the values aren’t valid. This is mostly for safety reasons: attempting to operate on invalid data can expose your code to vulnerabilities. This is the main reason the standard library will call panic! if you attempt an out-of-bounds memory access: trying to access memory that doesn’t belong to the current data structure is a common security problem. Functions often have contracts: their behavior is only guaranteed if the inputs meet particular requirements. Panicking when the contract is violated makes sense because a contract violation always indicates a caller-side bug and it’s not a kind of error you want the calling code to have to explicitly handle. In fact, there’s no reasonable way for calling code to recover; the calling programmers need to fix the code. Contracts for a function, especially when a violation will cause a panic, should be explained in the API documentation for the function.

However, having lots of error checks in all of your functions would be verbose and annoying. Fortunately, you can use Rust’s type system (and thus the type checking the compiler does) to do many of the checks for you. If your function has a particular type as a parameter, you can proceed with your code’s logic knowing that the compiler has already ensured you have a valid value. For example, if you have a type rather than an Option, your program expects to have something rather than nothing. Your code then doesn’t have to handle two cases for the Some and None variants: it will only have one case for definitely having a value. Code trying to pass nothing to your function won’t even compile, so your function doesn’t have to check for that case at runtime. Another example is using an unsigned integer type such as u32, which ensures the parameter is never negative.

9-3-4 Creating Custom Types for Validation

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

loop {
    // --snip--

    let guess: i32 = match guess.trim().parse() {
        Ok(num) => num,
        Err(_) => continue,
    };

    if guess < 1 || guess > 100 {
        println!("The secret number will be between 1 and 100.");
        continue;
    }

    match guess.cmp(&secret_number) {
    // --snip--
}

However, this is not an ideal solution: if it was absolutely critical that the program only operated on values between 1 and 100, and it had many functions with this requirement, having a check like this in every function would be tedious (and might impact performance).

Instead, we can make a new type and put the validations in a function to create an instance of the type rather than repeating the validations everywhere. That way, it’s safe for functions to use the new type in their signatures and confidently use the values they receive.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

pub struct Guess {
    value: i32,
}

impl Guess {
    pub fn new(value: i32) -> Guess {
        if value < 1 || value > 100 {
            panic!("Guess value must be between 1 and 100, got {}.", value);
        }
		// private, can not be set, only create by new
        Guess {
            value
        }
    }

    pub fn value(&self) -> i32 {
        self.value
    }
}

The panic! macro signals that your program is in a state it can’t handle and lets you tell the process to stop instead of trying to proceed with invalid or incorrect values. The Result enum uses Rust’s type system to indicate that operations might fail in a way that your code could recover from.

10 Generic Types, Traits, and Lifetimes

Generics are abstract stand-ins for concrete types or other properties.

10-1 Generic Data Types

10-1-1 In Function Definitions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

fn largest_i32(list: &[i32]) -> i32 {
    let mut largest = list[0];

    for &item in list.iter() {
        if item > largest {
            largest = item;
        }
    }
    largest
}

fn largest_char(list: &[char]) -> char {
    let mut largest = list[0];

    for &item in list.iter() {
        if item > largest {
            largest = item;
        }
    }
    largest
}

fn largest<T>(list: &[T]) -> T {
    let mut largest = list[0];

    for &item in list.iter() {
        if item > largest {
            largest = item;
        }
    }
    largest
}