Reading notes - The Rust Programming Language_a) write out (using angle brackets and labels bint

Getting started

• Install rust
• Program hello world
• The package manager: cargo

Installation

• Rust versions manager: rustup
• Install rustup:
  • $ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
• Linker
  • which is a program that Rust uses to join its compiled outputs into one file
• A C compiler is also useful
  • because some common Rust packages depend on C code and will need a C compiler.
  • Mac:  $ xcode-select --install
  • Ubuntu: build-essential package
• Update and uninstall rustup
  • Update: $ rustup update
  • Uninstall: $ rustup self uninstall
• Check rust installation
  • $ rustc --version
• Documentation
  • rustup doc

Hello world

• we suggest making a projects directory in your home directory and keeping all your projects there.
• Rust files always end with the .rs extension
• underscore to separate worlds
  • use hello_world.rs rather than helloworld.rs.
• 
• Run it
  • 
  • On Windows, enter the command .\main.exe instead of ./main:
• Anatomy
  • Define function
    • 
    • Entry point: main function
    • Fomatter: rustfmt (included with rustc)
    • Indent with 4 spaces, not a tab.
      • 2 spaces works too
    • Macro: <name>!
      • Not same as functions
  • Compiling and running are separate steps
    • Compile with rustc
      • 2 files on linux vs. 3  files on windows

Hello, cargo

• Cargo is Rust’s build system and package manager.
• Check it installed: $ cargo --version
• Create projects with cargo
  • 

• Cargo.toml
  • 
  • This file is in the TOML (Tom’s Obvious, Minimal Language) format, which is Cargo’s configuration format.
  • [package]
    • Info about you app
  • [dependencies]
    • For you deps
    • packages of code are referred to as crates
• Cargo.lock
  • Deps lock file
  • Generated on first build
• Cargo expects your source files to live inside the src directory
• Build and run
  • Build
    • 
    • his command creates an executable file in target/debug/hello_cargo
  • One step build and run
    • 
  • Check only
    • cargo check
  • Build for release
    • 
    • This command will create an executable in target/release instead of target/debug.
    • Two modes (profiles): dev and release

Functions

• Snake case: lower case + underscore
• How to define and call
• Position not matters
• Parameters
  • Parameter(def) vs. argument(call)
  • you must declare the type of each parameter
• Statements and expressions
  • What is the different
  • No: x = (y = 6)
  • Calling a macro is an expression.
  • A new scope block created with curly brackets is an expression
  • 
• Return values
  • You must declare return type: -> <type>
  • The 'return' keyword
  • Last expression for return value
  • 
  • () for no return value

Comments

• Normal: //
• Doc comments, see chap 14

Control flows

• If expression
  • 
  • Condition need no (), must be type of bool
  • ==, !=
  • combining if and else in an else if expression
  • a powerful Rust branching construct called match
  • If expression, return same type
  • 
• Repeating
  • 3 types: loop, while, for
  • Loop
    • 
    • Key words: break, continue
    • Break for returning value
    • 
    • Loop labels
      • If you have loops within loops, break and continue apply to the innermost loop at that point
      • Loop labels must begin with a single quote
      • 
  • While
    • 
    •  compiler adds runtime code to perform the conditional check of whether the index is within the bounds of the array
  • For
    • 
    • For Range
    • 

What is ownership

• Ownership is Rust’s most unique feature and has deep implications for the rest of the language. It enables Rust to make memory safety guarantees without needing a garbage collector
• Rust uses a third approach: memory is managed through a system of ownership with a set of rules that the compiler checks. If any of the rules are violated, the program won’t compile. None of the features of ownership will slow down your program while it’s running.
• The stack and the heap
  • Stack
    • Last in, first out
    • Push, pop
    •  known, fixed size
  • Heap
    • Allocating on the heap
    • Pointer can store on the stack
  • summary
    • Accessing data in the heap is slower than accessing data on the stack
    • Function and stack
    • the main purpose of ownership is to manage heap data
• Ownership rules
  • Each value in Rust has an owner.
  • There can only be one owner at a time.
  • When the owner goes out of scope, the value will be dropped.
• Variable scope
  • Similar to other languages
• The String type
  • String is immutable
  • create a String from a string literal using the from function
  • 
  • Op :: for namespace
  • String be mutated but literals cannot
  • 
• Memory and allocation
  •  string literals are fast and efficient, because of fixed size and immutability
  • 2 steps
    • The memory must be requested from the memory allocator at runtime.
    • We need a way of returning this memory to the allocator when we’re done
  • No Garbage collector
    • Rust takes a different path: the memory is automatically returned once the variable that owns it goes out of scope
    • When a variable goes out of scope, Rust calls a special function for us. This function is called drop, and it’s where the author of String can put the code to return the memory. Rust calls drop automatically at the closing curly bracket.
    • Like C++ Resource Acquisition Is Initialization (RAII)

• Ways variables and data interact: move
  • 
  • Two value(5) on the stack
  • 
  • Stack and heap
  • 
  • The difference between length and capacity matters
    • 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 allocator.
  • After copying
  • 
  • To ensure memory safety, after the line let s2 = s1, Rust considers s1 as no longer valid.
  • 
  • You will get an error
  • it’s known as a move
  • 

• Ways variables and data interact: clone
  • If we do want to deeply copy the heap data of the String, we can use a common method called clone. 
  • 
  • It’s a visual indicator that something different is going on
  • Stack-only data: copy
    • Rust has a special annotation called the Copy trait that we can place on types that are stored on the stack, as integers are
    • With copy trait, assignment for copy, not for moving
    • Rust won’t let us annotate a type with Copy if the type, or any of its parts, has implemented the Drop trait. 
    • Here are some of the types that implement Copy:
    • 

• Ownership and functions
  • Passing a variable to a function will move or copy, just as assignment does.
  • 
• Return values and scope
  • Returning values can also transfer ownership
  • 
• Summary
  • The ownership of a variable follows the same pattern every time: assigning a value to another variable moves it. When a variable that includes data on the heap goes out of scope, the value will be cleaned up by drop unless ownership of the data has been moved to another variable.
  • What if we want to let a function use a value but not take ownership
    • Rust has a feature for using a value without transferring ownership, called references.

5.3. Method Syntax

• Unlike functions, methods are 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.
• 
• The &self is actually short for self: &Self
• Methods must have a parameter named self of type Self for their first parameter
• Having a method that takes ownership of the instance by using just self is rare:
  • this technique is usually used when the method transforms self into something else and you want to prevent the caller from using the original instance after the transformation.
• The main reason for using methods instead of functions is for organization
• we can choose to give a method the same name as one of the struct’s fields
• 
• Methods like this are called getters
  • etters are useful because you can make the field private but the method public
• Where’s the -> Operator?
  • In C and C++, two different operators are used for calling methods: you use . if you’re calling a method on the object directly and -> if you’re calling the method on a pointer to the object and need to dereference the pointer first. In other words, if object is a pointer, object->something() is similar to (*object).something().
  • Rust doesn’t have an equivalent to the -> operator; instead, Rust has a feature called automatic referencing and dereferencing
  • 
  • Here’s how it works: when you call a method with object.something(), Rust automatically adds in &, &mut, or * so object matches the signature of the method.
• Methods with More Parameters
  • Add a new method: can_hold
  • 

• Associated Functions
  • All functions defined within an impl block are called associated functions because they’re associated with the type named after the impl. 
  • Like static (type) methods, e.g. String::from
  • 
  • To call this associated function, we use the :: syntax with the struct name
• Multiple impl Blocks
• 

6.1. defining an enum

• How to define
• 
• How to use
• 

• 
• Enum with data
• 

• 
• Standard lib definition
• 
• Enum vs. struct
• 

• 
• Enum methods
• 
• The Option enum
  • Rust has no null feature
  • “Null References: The Billion Dollar Mistake,”
  • 
  • included in the prelude, need no import
  • you can use Some and None directly without the Option:: prefix. 
  • 
  • Force right usage
  • 
  • The Option<T> enum has a large number of methods 
  • The match expression is a control flow construct that does just this when used with enums: it will run different code depending on which variant of the enum it has, and that code can use the data inside the matching value.

Chap 7: Managing Growing Projects with Packages, Crates, and Modules

• A package can contain multiple binary crates and optionally one library crate
• As a package grows, you can extract parts into separate crates that become external dependencies
• A related concept is scope
  • name conflicts
• module system
  • Packages
  • Crates
  • Modules, use
  • Paths

7.1. Packages and Crates

• A package is one or more crates that provide a set of functionality
• A package contains a Cargo.toml file that describes how to build those crates.
• A crate can be a binary crate or a library crate
• Library crates don’t have a main function
• The crate root is a source file that the Rust compiler starts from and makes up the root module of your crate
• Several rules:
  • A package can contain at most one library crate
  • It can contain as many binary crates as you’d like
  • but it must contain at least one crate (either library or binary).
• When we cargo new <project-name>:
  • Cargo created a Cargo.toml file, giving us a package
  • Cargo follows a convention that src/main.rs is the crate root of a binary crate with the same name as the package.
  • Cargo knows that if the package directory contains src/lib.rs, the package contains a library
  • If a package contains src/main.rs and src/lib.rs, it has two crates
  • A package can have multiple binary crates by placing files in the src/bin directory

7.2. Defining Modules to Control Scope and Privacy

• Modules Quick Reference
  • Start from the crate root
  • Declaring submodules
    • In any file other than crate root
    • Places of module (mod vegetables) code
      • Inline
      • In the file src/garden/vegetables.rs
      • In the file src/garden/vegetables/mod.rs
  • Paths to code in modules
    • crate::garden::vegetables::Asparagus
  • Private vs. public
    • Public module: pub mod
    • Pub item
  • The use keyword
    • the use keyword creates shortcuts to items to reduce repetition of long paths
  • Module example
  • 

• 
• The pub mod garden; tells the compiler includes the code
• 

• Grouping Related Code in Modules
  • Module for code grouping, privacy control
  • Create a new library named restaurant by running cargo new --lib restaurant
  • 

• Notice that the entire module tree is rooted under the implicit module named crate.

7.3. Paths for Referring to an Item in the Module Tree

• A path can take two forms:
  • An absolute path starts from a crate root by using a crate name (for code from an external crate) or a literal crate (for code from the current crate).
  • A relative path starts from the current module and uses self, super, or an identifier in the current module.
• <path>::<identifier>
• Path examples, not work
• 

• we can use the crate keyword to start an absolute path
• Start from 'crate' like '/'
• Absolute vs. relative
  • Relative for: consumer together with module
  • Absolute for: otherwise
• Module for privacy boundary
  • All items of module are private by default
  • Items in child module can use parent items
• Exposing Paths with the pub Keyword
• 
  • Make 'pub' all the way to the item
  • Can ref siblings
  • The Rust API Guidelines

• Best Practices for Packages with a Binary and a Library
  • 2 crate: bin + lib
  • 'lib' used by bin, and other projects as well
• Starting Relative Paths with super
  • 'super' like '..', for parent module
• Making Structs and Enums Public
  • 'pub' for struct and its fields
  • 
  • A struct has a private field, need a public function for constructing instances
  • In contrast, if we make an enum public, all of its variants are then public. We only need the pub before the enum keyword,
  • 

7.4. Bringing Paths Into Scope with the use Keyword

• 'use' keyword for shorter module ref
  • 
  • Also check privacy
  • Only valid in same scope, below not work
  • 

• How to fix:
  • move the use within the customer module
  • super::hosting

• Creating Idiomatic use Paths
  • Idiomatic: 'use all::the::way::to::module'
  • unidiomatic: 'use all::the::way::to::module::item'
  • Idiomatic make it clear where items from
  • Idiomatic for fns, unidiomatic for struct, enum, etc.
  • Idiomatic for items with same names
  • 
• Providing New Names with the as Keyword
  • 
• Re-exporting Names with pub use
  • 
  • Re-exporting is useful when the internal structure of your code is different from how programmers calling your code would think about
• Using External Packages
  • To use a external package
  • 
  • Download deps from crates.io, make it usable
  • 
  • Intermedia modules are also available
  • The 'std' starndard lib
  • Package > crate > module > item
• Using Nested Paths to Clean Up Large use Lists
  • 
  • Use 'self'
  • 
• The Glob Operator
  • 
  • Note: Glob can make it harder to tell what names are in scope
  • often used when testing to bring everything under test into the tests module

7.5. Separating Modules into Different Files

• Before, we have all the modules in the crate root file, src/lib.rs
• We can put them in multiple files, so do the binary crate, src/main.rs
• How to do
  • 
  • The compiler knows to look in this file because of the module declaration
  • 
  • Using 'mod' declaration to load file, 'mod' is not an 'include'
  • One 'mod', many 'use'
  • Module should be place in where named for its place in the module tree
  • Module: crate::front_of_house::hosting
  • 
  • file path for modules
    • 'src/my_module.rs (idiomatic)
    • 'src/my_module/mod.rs (also support)
    • Use both will get error
    • 'mod.rs' is not good for open multiple
• 'mod', 'use', 'pub'

Chapter 9. Error Handling

• Some errors are reported before compiling
• 2 error category
  • Recoverable
    • Like file not found
    • Report the problem to users
  • Unrecoverable
    • Like out of array index
    • Stop the program
• Rust do not have exceptions
  • Has type Result<T, E> for the recoverable
  • The panic! Macro for the unrecoverable

9.1. Unrecoverable Errors with panic!

• What panic! Do
  • Print a failure message
  • Clean up the stack
  • Quit the app
• Response to a panic
  • Unwinding
    • Clean up
    • A lot of works
  • Aborting
    • Clean up by the OS
    • Config in 'Cargo.toml'
    • 
• Have a try
  • 
• Using a panic! Backtrace
  • Try: reading an invalid index
    • 
    • In C, buffer overread
    • Rust will stop execute
  • How to read backtrace
    • From the top util your file
  • Get backtrace
    • 
    • Debug symbols must be enable
      • By default when 'cargo build' or 'cargo run' without --release

9.2. Recoverable Errors with Result

• The 'Result' enum
  • 
• Example
  • 

• Matching on different errors
  • 
• Shortcuts for panic on error: unwrap and expect
  • 

• Propagating errors
  • return the error to the calling code, they might have more info
  • 
• The ? Operator
  • 
  • Use the 'from' function
  • 

• 
• Where to use it
  • The ? operator can only be used in functions whose return type is compatible with the value the ? is used on
  • Don't do this
  • 
  • Type implement trait 'FromResidual'
• Use '?' with Option<T>
  • 
  • The ? extracts the string slice, and we can call chars on that string slice
• Luckily, main can also return a Result<(), E>
• 
• Box<dyn Error> for all error types
• Main fn return 0 for success, otherwise for failure

9.3. To panic! Or Not to panic!

• Returning 'Result' is a good default choice
• Use panic! For examples, prototype, tests
• When you have more info than compiler
  • 
• Guidelines for error handling
  • 'panic' for bad state
  • 'Result<T>' for expected error
  • 'panic' for function contracts violations
  • Use types for check by compiler
  •