🔔 Prelude: When writing Rust programs, Result and Option are data structures we can hardly avoid. I believe that rather than understanding their underlying mechanisms, we should first quickly figure out how to handle them.

Gift Wrapping

Actually, we don’t need to think of Option<T> and Result<T,E> as too complicated:

• Option contains the data we want, where the data type is T. However, there might be no data inside (None). But regardless, as long as what we care about is wrapped, it will be an Option.
• Result also contains the data we want, but it comes with another “restless” additional item E (Error). In fact, combinations of Result and Option are very common, such as Result<Option<T>, E>. Result provides a powerful and unified specification for Rust’s error handling.

So, how do we open the gift box…

The moment of unwrapping gifts is always exciting.

Whether it’s Option or Result, we can use unwrap() to open this package.

• If the gift box contains a normal value, everything goes smoothly, and everyone’s happy.
• But if it contains something “weird” (None or Err), the program will immediately panic and crash.

Of course, if we insist on using safer unwrapping methods (like unwrap_or, match, etc.), we can control whether the program crashes ourselves, which is very practical.

What functions do these gift boxes provide?

Let’s quickly go through the methods they provide. Detailed explanations won’t be provided here, as I believe you can look up relevant information through https://doc.rust-lang.org/std/option/ and https://doc.rust-lang.org/std/result/.

Option

Notable methods:

• map(f) provides a way to operate on inner data without unpacking, very commonly used
• expect("Hi") can display error messages when panicking, more practical than unwrap()
• ? can greatly improve code cleanliness
• is_some() and is_none() are also very useful for making decisions

Result

Compared to the intuitive and easy-to-understand Option, Result seems more “convoluted” with an additional type, but essentially it’s almost identical to Option: what to do if we didn’t get the value (possibly due to an error).

Result also has: map(f) and ?, as well as useful is_ok() and is_err()

In Result<T, E>:

• T is the type of value returned on success (e.g., file content, calculation result, etc.).
• E is the type of value returned on error (e.g., std::io::Error, custom error enum, etc.).
• Actually:
  • E can be any type, with no restrictions
  • But to use ?, facilitate debugging and printing, E usually needs to implement Debug, Display, Error, and other traits
  • Yes, E can be very complex types (carrying context, providing helper methods), or very simple error structures (like, a string). Err is just the shell that Result uses to mark “this is the error branch”, with E inside

Examples

// ===== Creating Option =====
let some_value: Option<i32> = Some(42);  // Has value
let none_value: Option<i32> = None;      // No value

// Common usage: returning from functions
fn find_number(flag: bool) -> Option<i32> {
    if flag { Some(7) } else { None }
}

// ===== Creating Result =====
let ok_value: Result<i32, String> = Ok(42);                    // Success
let err_value: Result<i32, String> = Err("Oops".to_string()); // Failure

// Common usage: returning from functions
fn divide(a: i32, b: i32) -> Result<i32, String> {
    if b == 0 {
        Err("Division by zero".to_string())
    } else {
        Ok(a / b)
    }
}

Rather than using C style loop, in Rust, we use ..= to indicate a range:

for i in 1..=5 {
    println!("{}",i);
}

Output:

1
2
3
4
5

Sequences are only allowed for numeric or character types because they can be consecutive.

for i in 'a'..='z' {
    println!("{}",i);
}

Char

Use '' . "" is for the string

fn main() {
    let c = 'z';
    let z = 'ℤ';
    let cat= '😻';
}

Accept Unicode, occupy 4 bytes.

Bool

Only 1 byte.

fn main() {
    let t = true;
    let f: bool = false;
}

Unit type

Literally, it is ().

Yes, the unit type is (), and the value of this type is also, and only ().

It’s similar to void in other languages.

Sometimes, you may come across code like Result<(), String>. This is an example of generic types in Rust. If you’re familiar with C++ generic types, you can figure out that we pass 2 types into the Result, regardless of what the Result actually is.

🔔 Prelude: In the end, all data types in Rust come from these primitive types.

Basic types

• Every value in Rust has a specific data type
• In general, these can be divided into two categories: scalar types and compound types
• Scalar types include:
  • Numbers: Signed integers (i8, i16, i32, i64, isize), unsigned integers (u8, u16, u32, u64, usize), floating-point numbers (f32, f64)
    • The isize and usize types depend on the architecture of the computer the program is running on: if the CPU is 32-bit, these types are 32-bit; similarly, if the CPU is 64-bit, they are
    • Rust’s default integer type is i32
    • Can overflow, and Rust does not check for this by default. If you encounter incorrect values, make sure to check the type of your numbers.
  • Strings: String literals and string slices
  • Booleans: true and false
  • Characters: Representing a single Unicode character, stored as 4 bytes
  • Unit type: Represented by (), with its only value also being ()

Be Careful with floats

See this example:

fn main() {
  assert!(0.1 + 0.2 == 0.3);
}

You might think this would return true , but the truth is, the program will panic and quit.

• Due to binary precision issues, 0.1 + 0.2 is not exactly equal to 0.3
• You can consider using this approach: (0.1_f64 + 0.2 - 0.3).abs() < 0.00001

NaN

• -42.1.sqrt() will produce NaN
• Any operation involving NaN will return NaN
• Comparing NaN will cause the code to panic and crash
• Use is_nan() to determine if a value is NaN

Use as for Type Conversion

In Rust, you can use as to convert one type to another.

fn main() {
    let x: i32 = 10;
    let y: f64 = x as f64; // Convert i32 to f64

    println!("x as f64 is: {}", y);
}

Don’t worry, this will be very easy at the beginning. (Really?)

Function goes first

• Similar to C and C++, there must be a main function as the entry point of the program.
• Use fn to declare a function, so concise.
• Use () for receiving parameters, and {} for the actual logic inside the function.
• Remember to use ; to end a statement. As I said, it’s similar to C and C++.
• Example:

fn main() -> {
    println!("Hello, world!");
    // "ln" means print with a new line after the content
    // What is "!"? Well, it means this function is actually a macro
    // For now, let's just use it as is
    // You don't need to learn everything to start using Rust. Heart.
}

A complete structure of function head in Rust should be:

keyword name(parameter: type ) -> [return type] { body }

fn      myFunction(para : i32) -> i32 { ... }

Define variables

• You must use let to create a variable.
  • let myVar = 3;
  • let myVar: u32 = 3; → Explicitly specifies the type of the variable myVar as u32. u32 is a 32-bit unsigned integer type in Rust.
  • let mut myVar = 3; → Creates a mutable variable.
• What? Mutable?
  • Variables in Rust are immutable by default.(Its value is determined after compilation.)
  • It’s important to understand that in Rust, some_variable = some_value is not just assigning a value, but rather binding the value to the variable.
  • This topic is related to Rust’s Ownership feature, which we will discuss in the next post.
  • Here’s an example:

let myVar = 5;
myVar = 6; // Error

let mut myMutVar = 5;
myMutVar = 6; // Pass

• If you understand that variables are bound to values, it becomes easier to grasp variable destructuring:
  • Basically, destructuring means extracting values from patterns.

fn main() {
    let (a, mut b): (bool,bool) = (true, false);
    println!("a = {:?}, b = {:?}", a, b);
    // You can treat the {} as a placeholder for a or b
    // :? is for "formatting" output and "debugging" output
    // Whatever, it should print the value of a and b

    b = true;
    assert_eq!(a, b);
}

• You can also use const to define a constant value:
  • const MY_CONST_VALUE: i32 = 5;
  • Constants must always have a type annotation, unlike regular variables.

Statement and expression

• In short:

fn add_with_extra(x: i32, y: i32) -> i32  {
    let x = x + 1; // Statement
    let y = y + 5; // Statement
    x + y // Expression. Hey! Attention here! No ";" after the sentence!

    // Also expression is expected to "return" something
    // So we can avoid to write "return" in the end of our fn

    // In other word, statament CANNOT return a value
}

• Interesting facts:
  • In let x = 1;
    • x is an expression
    • 1 is an expression
    • let x = 1; is a statement
    • Bound
• Lastly, if an expression doesn’t return anything, it returns ()
  • () is both a type and a value, and the value is ().
  • You can treat the () as a (), yes, that is it.

These Rust notes are just a collection of my learning records. Since I’m a beginner in Rust, these notes are more like quick references or supplements, rather than a comprehensive Rust tutorial. No matter what, I hope you can still find parts that are useful to you.

Why rust？

Rust’s advantages include memory safety, high performance, and high productivity. To me, Rust appears to be one of the best implementations of C++. If you don’t get into deeper topics and only use prepared libraries, Rust’s syntax is simple and clear. Its built-in compiler cautions are also quite informative, which significantly decreases the amount of thinking required on developers.

However, Rust has been criticized for being “too safe.” If you want to dig deeper and truly utilize Rust, you’ll have to deal with its complex and tedious safety mechanisms. A true dilemma exists: “Why not use the more flexible C++, or Python, which offers quicker speed in development and a more strong ecosystem?”

In my opinion, Rust is a “balanced” choice that addresses some shortcomings of mainstream languages. It is safer than C++ and performs better than Python. However, Rust has obvious drawbacks including an extremely high learning and development cost (which may be more difficult than learning C++). However, Rust is clearly a popular technology right now, and its ecosystem is rapidly expanding. Learning a challenging new language is never a terrible idea.

Environment prep

1. Follow the instructions at https://www.rust-lang.org/learn/get-started to install Rust.
2. Install VS Code.
3. Install the rust-analyzer extension in VS Code.
4. Well done! You’re now ready to write your first Rust program.

Use Google or AI tools to help you do these tasks, you will deal with Google and AI all the time when you’re learning something new.

Hello world

1. In VS Code, open a new folder.
2. Press `Ctrl + `` to open a new terminal, or you can follow the top menu tabs: “Terminal” -> “New Terminal”.
3. Enter cargo new helloworld to create a new project named helloworld.
   1. cargo is like the pip in Python; it manages packages (libraries) in Rust.
4. Go into the src folder, and you will find the main.rs file.
5. Enter cargo run in the terminal to directly run … oops! An error occurs.
   1. You need to first navigate into the helloworld directory because that’s the project’s working directory.
   2. Use cd helloworld, or open the folder again in VS Code, and then create a new terminal.
   3. Enter cargo run.
   4. Congratulations! You’ve run your first Rust program!