diff --git a/courses/comprehensive_rust_training/020_hello_world/03_playground.rst b/courses/comprehensive_rust_training/020_hello_world/03_playground.rst index da3d73dc2..f3b75add9 100644 --- a/courses/comprehensive_rust_training/020_hello_world/03_playground.rst +++ b/courses/comprehensive_rust_training/020_hello_world/03_playground.rst @@ -8,17 +8,17 @@ Playground The :url:`Rust Playground ` provides an easy way to run short Rust programs, and is the basis for the examples and -exercises in this course. Try running the "hello-world" program it +exercises in this course. Try running the :command:`hello-world` program it starts with. It comes with a few handy features: -- Under "Tools", use the :rust:`rustfmt` option to format your code in the +- Under :menu:`Tools`, use the :menu:`rustfmt` option to format your code in the "standard" way. -- Rust has two main "profiles" for generating code: Debug (extra - runtime checks, less optimization) and Release (fewer runtime checks, - lots of optimization). These are accessible under "Debug" at the top. +- Rust has two main :dfn:`profiles` for generating code: **Debug** (extra + runtime checks, less optimization) and **Release** (fewer runtime checks, + lots of optimization). These are accessible under :menu:`Debug` at the top. -- If you're interested, use "ASM" under "..." to see the generated +- If you're interested, use :menu:`ASM` under :menu:`...` to see the generated assembly code. --------- diff --git a/courses/comprehensive_rust_training/040_control_flow_basics/01_if.rst b/courses/comprehensive_rust_training/040_control_flow_basics/01_if.rst index c9d16e17f..0297af5dc 100644 --- a/courses/comprehensive_rust_training/040_control_flow_basics/01_if.rst +++ b/courses/comprehensive_rust_training/040_control_flow_basics/01_if.rst @@ -1,10 +1,10 @@ -==================== -"if" expressions -==================== +======================== +:rust:`if` expressions +======================== --------------------- -"if" expressions --------------------- +------------------------ +:rust:`if` expressions +------------------------ You use :url:`if expressions ` diff --git a/courses/comprehensive_rust_training/040_control_flow_basics/02_match.rst b/courses/comprehensive_rust_training/040_control_flow_basics/02_match.rst index 2846f0a82..d7dfed67b 100644 --- a/courses/comprehensive_rust_training/040_control_flow_basics/02_match.rst +++ b/courses/comprehensive_rust_training/040_control_flow_basics/02_match.rst @@ -1,10 +1,10 @@ -======================= -"match" Expressions -======================= +=========================== +:rust:`match` Expressions +=========================== ------------------------ -"match" Expressions ------------------------ +--------------------------- +:rust:`match` Expressions +--------------------------- :rust:`match` can be used to check a value against one or more options: diff --git a/courses/comprehensive_rust_training/040_control_flow_basics/03_loops.rst b/courses/comprehensive_rust_training/040_control_flow_basics/03_loops.rst index 8dbd42d8e..7e49044c1 100644 --- a/courses/comprehensive_rust_training/040_control_flow_basics/03_loops.rst +++ b/courses/comprehensive_rust_training/040_control_flow_basics/03_loops.rst @@ -9,9 +9,9 @@ Loops There are three looping keywords in Rust: :rust:`while`, :rust:`loop`, and :rust:`for`: ------------ -"while" ------------ +--------------- +:rust:`while` +--------------- The :url:`while keyword ` @@ -28,9 +28,9 @@ the condition is true. println!("Final x: {x}"); } -------------- -"for" -------------- +----------------- +:rust:`for` +----------------- The :rust:`for` `loop `__ iterates over ranges of values or the items in a collection: @@ -47,9 +47,9 @@ iterates over ranges of values or the items in a collection: } } ---------------- -"for" Details ---------------- +------------------- +:rust:`for` Details +------------------- - Under the hood :rust:`for` loops use a concept called :dfn:`iterators` to handle iterating over different kinds of ranges/collections. @@ -57,9 +57,9 @@ iterates over ranges of values or the items in a collection: - Note that the first :rust:`for` loop only iterates to :rust:`4`. Show the :rust:`1..=5` syntax for an inclusive range. --------------- -"loop" --------------- +------------------ +:rust:`loop` +------------------ The :rust:`loop` `statement `__ just @@ -78,9 +78,9 @@ loops forever, until a :rust:`break`. } } ----------------- -"loop" Details ----------------- +-------------------- +:rust:`loop` Details +-------------------- - The :rust:`loop` statement works like a :rust:`while true` loop. Use it for things like servers which will serve connections forever. diff --git a/courses/comprehensive_rust_training/040_control_flow_basics/04_break_continue.rst b/courses/comprehensive_rust_training/040_control_flow_basics/04_break_continue.rst index b53bc5822..cf15575ef 100644 --- a/courses/comprehensive_rust_training/040_control_flow_basics/04_break_continue.rst +++ b/courses/comprehensive_rust_training/040_control_flow_basics/04_break_continue.rst @@ -1,10 +1,10 @@ -============================ -"break" and "continue" -============================ +==================================== +:rust:`break` and :rust:`continue` +==================================== ----------------------------- -"break" and "continue" ----------------------------- +------------------------------------ +:rust:`break` and :rust:`continue` +------------------------------------ If you want to immediately start the next iteration use :url:`continue `. diff --git a/courses/comprehensive_rust_training/050_tuples_and_arrays/02_tuples.rst b/courses/comprehensive_rust_training/050_tuples_and_arrays/02_tuples.rst index 7fcb167fb..9ae4d05c6 100644 --- a/courses/comprehensive_rust_training/050_tuples_and_arrays/02_tuples.rst +++ b/courses/comprehensive_rust_training/050_tuples_and_arrays/02_tuples.rst @@ -25,6 +25,6 @@ Details - Fields of a tuple can be accessed by the period and the index of the value, e.g. :rust:`t.0`, :rust:`t.1`. -- The empty tuple :rust:`()` is referred to as the "unit type" and +- The empty tuple :rust:`()` is referred to as the :dfn:`unit type` and signifies absence of a return value, akin to :rust:`void` in other languages. diff --git a/courses/comprehensive_rust_training/050_tuples_and_arrays/04_destructuring.rst b/courses/comprehensive_rust_training/050_tuples_and_arrays/04_destructuring.rst index 21ff863f5..9a5113946 100644 --- a/courses/comprehensive_rust_training/050_tuples_and_arrays/04_destructuring.rst +++ b/courses/comprehensive_rust_training/050_tuples_and_arrays/04_destructuring.rst @@ -32,7 +32,7 @@ larger value into its constituent parts: Details --------- -- The patterns used here are "irrefutable", meaning that the compiler +- The patterns used here are :dfn:`irrefutable`, meaning that the compiler can statically verify that the value on the right of :rust:`=` has the same structure as the pattern. - A variable name is an irrefutable pattern that always matches any diff --git a/courses/comprehensive_rust_training/060_references/01_shared.rst b/courses/comprehensive_rust_training/060_references/01_shared.rst index fca3aa92e..6bb5ff4de 100644 --- a/courses/comprehensive_rust_training/060_references/01_shared.rst +++ b/courses/comprehensive_rust_training/060_references/01_shared.rst @@ -7,7 +7,7 @@ Shared References ------------------- A reference provides a way to access another value without taking -ownership of the value, and is also called "borrowing". Shared +ownership of the value, and is also called :dfn:`borrowing`. Shared references are read-only, and the referenced data cannot change. .. code:: rust @@ -22,7 +22,7 @@ references are read-only, and the referenced data cannot change. } A shared reference to a type :rust:`T` has type :rust:`&T`. A reference value is -made with the :rust:`&` operator. The :rust:`*` operator "dereferences" a +made with the :rust:`&` operator. The :rust:`*` operator :dfn:`dereferences` a reference, yielding its value. --------- @@ -32,9 +32,9 @@ Details - References can never be null in Rust, so null checking is not necessary. -- A reference is said to "borrow" the value it refers to, and this is a +- A reference is said to **borrow** the value it refers to, and this is a good model for students not familiar with pointers: code can use the - reference to access the value, but is still "owned" by the original + reference to access the value, but is still **owned** by the original variable. The course will get into more detail on ownership in day 3. - References are implemented as pointers, and a key advantage is that diff --git a/courses/comprehensive_rust_training/060_references/02_exclusive.rst b/courses/comprehensive_rust_training/060_references/02_exclusive.rst index a8b8c6b50..8c87dd13b 100644 --- a/courses/comprehensive_rust_training/060_references/02_exclusive.rst +++ b/courses/comprehensive_rust_training/060_references/02_exclusive.rst @@ -24,7 +24,7 @@ Details Key points: -- "Exclusive" means that only this reference can be used to access the +- :dfn:`Exclusive` means that only this reference can be used to access the value. No other references (shared or exclusive) can exist at the same time, and the referenced value cannot be accessed while the exclusive reference exists. Try making an :rust:`&point.0` or changing diff --git a/courses/comprehensive_rust_training/070_user_defined_types/05_const.rst b/courses/comprehensive_rust_training/070_user_defined_types/05_const.rst index f00459838..4d9f44f4c 100644 --- a/courses/comprehensive_rust_training/070_user_defined_types/05_const.rst +++ b/courses/comprehensive_rust_training/070_user_defined_types/05_const.rst @@ -1,10 +1,10 @@ -=========== -"const" -=========== +=============== +:rust:`const` +=============== ------------ -"const" ------------ +--------------- +:rust:`const` +--------------- Constants are evaluated at compile time and their values are inlined wherever they are used: diff --git a/courses/comprehensive_rust_training/070_user_defined_types/06_static.rst b/courses/comprehensive_rust_training/070_user_defined_types/06_static.rst index 2347f451d..91b7b26bb 100644 --- a/courses/comprehensive_rust_training/070_user_defined_types/06_static.rst +++ b/courses/comprehensive_rust_training/070_user_defined_types/06_static.rst @@ -1,10 +1,10 @@ -============ -"static" -============ +================ +:rust:`static` +================ ------------- -"static" ------------- +---------------- +:rust:`static` +---------------- Static variables will live during the whole execution of the program, and therefore will not move: diff --git a/courses/comprehensive_rust_training/080_pattern_matching/04_let_control_flow.rst b/courses/comprehensive_rust_training/080_pattern_matching/04_let_control_flow.rst index 134693c34..4cfea176b 100644 --- a/courses/comprehensive_rust_training/080_pattern_matching/04_let_control_flow.rst +++ b/courses/comprehensive_rust_training/080_pattern_matching/04_let_control_flow.rst @@ -13,9 +13,9 @@ languages. They are used for pattern matching: - :rust:`let else` expressions - :rust:`while let` expressions ------------------------- -"if let" expressions ------------------------- +---------------------------- +:rust:`if let` expressions +---------------------------- The :url:`if let expression ` @@ -38,14 +38,14 @@ pattern: sleep_for(0.8); } --------------------------- -"let else" expressions --------------------------- +------------------------------ +:rust:`let else` expressions +------------------------------ For the common case of matching a pattern and returning from the function, use :url:`let else `. -The "else" case must diverge (:rust:`return`, :rust:`break`, or panic - anything +The :rust:`else` case must diverge (:rust:`return`, :rust:`break`, or panic - anything but falling off the end of the block). .. code:: rust @@ -91,9 +91,9 @@ returns :rust:`Some(c)` until the string is empty, after which it will return :rust:`None`. The :rust:`while let` lets us keep iterating through all items. --------- -if-let --------- +---------------- +:rust:`if-let` +---------------- - Unlike :rust:`match`, :rust:`if let` does not have to cover all branches. This can make it more concise than :rust:`match`. @@ -102,9 +102,9 @@ if-let - Unlike :rust:`match`, :rust:`if let` does not support guard clauses for pattern matching. ----------- -let-else ----------- +------------------ +:rust:`let-else` +------------------ :rust:`if-let` can pile up, as shown. The :rust:`let-else` construct supports flattening this nested code. Rewrite the awkward version for students, @@ -130,9 +130,9 @@ The rewritten version is: return Ok(digit); } ------------ -while-let ------------ +------------------- +:rust:`while-let` +------------------- - Point out that the :rust:`while let` loop will keep going as long as the value matches the pattern. diff --git a/courses/comprehensive_rust_training/080_pattern_matching/05_exercise.rst b/courses/comprehensive_rust_training/080_pattern_matching/05_exercise.rst index 536f6be95..0a63fc98d 100644 --- a/courses/comprehensive_rust_training/080_pattern_matching/05_exercise.rst +++ b/courses/comprehensive_rust_training/080_pattern_matching/05_exercise.rst @@ -52,7 +52,7 @@ In code, we will represent the tree with two types: {{#include exercise.rs:Expression}} The :rust:`Box` type here is a smart pointer, and will be covered in detail -later in the course. An expression can be "boxed" with :rust:`Box::new` as +later in the course. An expression can be :dfn:`boxed` with :rust:`Box::new` as seen in the tests. To evaluate a boxed expression, use the deref operator (:rust:`*`) to "unbox" it: :rust:`eval(*boxed_expr)`. diff --git a/courses/comprehensive_rust_training/090_methods_and_traits/01_methods.rst b/courses/comprehensive_rust_training/090_methods_and_traits/01_methods.rst index e81f4b4a7..3d0815340 100644 --- a/courses/comprehensive_rust_training/090_methods_and_traits/01_methods.rst +++ b/courses/comprehensive_rust_training/090_methods_and_traits/01_methods.rst @@ -54,7 +54,7 @@ with an :rust:`impl` block: // race.add_lap(42); } -The :rust:`self` arguments specify the "receiver" - the object the method +The :rust:`self` arguments specify the :dfn:`receiver` - the object the method acts on. There are several common receivers for a method: - :rust:`&self`: borrows the object from the caller using a shared and diff --git a/courses/comprehensive_rust_training/090_methods_and_traits/02_traits.rst b/courses/comprehensive_rust_training/090_methods_and_traits/02_traits.rst index ac09b597e..034d34355 100644 --- a/courses/comprehensive_rust_training/090_methods_and_traits/02_traits.rst +++ b/courses/comprehensive_rust_training/090_methods_and_traits/02_traits.rst @@ -26,7 +26,7 @@ Traits Details - A trait defines a number of methods that types must have in order to implement the trait. -- In the "Generics" segment, next, we will see how to build +- In the *Generics* segment, next, we will see how to build functionality that is generic over all types implementing a trait. --------------------- diff --git a/courses/comprehensive_rust_training/100_generics/03_generic_traits.rst b/courses/comprehensive_rust_training/100_generics/03_generic_traits.rst index d916b717a..bfb81b7f1 100644 --- a/courses/comprehensive_rust_training/100_generics/03_generic_traits.rst +++ b/courses/comprehensive_rust_training/100_generics/03_generic_traits.rst @@ -44,8 +44,8 @@ Details parameters. Here, :rust:`Foo::from("hello")` would not compile because there is no :rust:`From<&str>` implementation for :rust:`Foo`. -- Generic traits take types as "input", while associated types are a - kind of "output" type. A trait can have multiple implementations for +- Generic traits take types as *input*, while associated types are a + kind of *output* type. A trait can have multiple implementations for different input types. - In fact, Rust requires that at most one implementation of a trait diff --git a/courses/comprehensive_rust_training/100_generics/04_trait_bounds.rst b/courses/comprehensive_rust_training/100_generics/04_trait_bounds.rst index 724dfe5f2..90e590c62 100644 --- a/courses/comprehensive_rust_training/100_generics/04_trait_bounds.rst +++ b/courses/comprehensive_rust_training/100_generics/04_trait_bounds.rst @@ -49,7 +49,7 @@ Details - It has additional features making it more powerful. - If someone asks, the extra feature is that the type on the left - of ":" can be arbitrary, like :rust:`Option`. + of :rust:`:` can be arbitrary, like :rust:`Option`. - Note that Rust does not (yet) support specialization. For example, given the original :rust:`duplicate`, it is invalid to add a specialized diff --git a/courses/comprehensive_rust_training/100_generics/05_impl_trait.rst b/courses/comprehensive_rust_training/100_generics/05_impl_trait.rst index ad19c6c54..aa5e535e0 100644 --- a/courses/comprehensive_rust_training/100_generics/05_impl_trait.rst +++ b/courses/comprehensive_rust_training/100_generics/05_impl_trait.rst @@ -1,10 +1,10 @@ -================ -"impl Trait" -================ +==================== +:rust:`impl Trait` +==================== ----------------- -"impl Trait" ----------------- +-------------------- +:rust:`impl Trait` +-------------------- Similar to trait bounds, an :rust:`impl Trait` syntax can be used in function arguments and return values: diff --git a/courses/comprehensive_rust_training/100_generics/06_dyn_trait.rst b/courses/comprehensive_rust_training/100_generics/06_dyn_trait.rst index 2cb3fd180..6d979145c 100644 --- a/courses/comprehensive_rust_training/100_generics/06_dyn_trait.rst +++ b/courses/comprehensive_rust_training/100_generics/06_dyn_trait.rst @@ -1,10 +1,10 @@ -=============== -"dyn Trait" -=============== +=================== +:rust:`dyn Trait` +=================== ---------------- -"dyn Trait" ---------------- +------------------- +:rust:`dyn Trait` +------------------- In addition to using traits for static dispatch via generics, Rust also supports using them for type-erased, dynamic dispatch via trait objects: @@ -77,7 +77,7 @@ Details pointer types like :rust:`Box` can also be used (this will be demonstrated on day 3). -- At runtime, a :rust:`&dyn Pet` is represented as a "fat pointer", i.e. a +- At runtime, a :rust:`&dyn Pet` is represented as a :dfn:`fat pointer`, i.e. a pair of two pointers: One pointer points to the concrete object that implements :rust:`Pet`, and the other points to the vtable for the trait implementation for that type. When calling the :rust:`talk` method on @@ -86,5 +86,5 @@ Details the :rust:`Dog` or :rust:`Cat` into that function. The compiler doesn't need to know the concrete type of the :rust:`Pet` in order to do this. -- A :rust:`dyn Trait` is considered to be "type-erased", because we no +- A :rust:`dyn Trait` is considered to be :dfn:`type-erased`, because we no longer have compile-time knowledge of what the concrete type is. diff --git a/courses/comprehensive_rust_training/100_generics/07_exercise.rst b/courses/comprehensive_rust_training/100_generics/07_exercise.rst index 859bbc689..8bdd5a346 100644 --- a/courses/comprehensive_rust_training/100_generics/07_exercise.rst +++ b/courses/comprehensive_rust_training/100_generics/07_exercise.rst @@ -1,10 +1,10 @@ -=========================== -Exercise: Generic "min" -=========================== +=============================== +Exercise: Generic :rust:`min` +=============================== ---------------------------- -Exercise: Generic "min" ---------------------------- +------------------------------- +Exercise: Generic :rust:`min` +------------------------------- In this short exercise, you will implement a generic :rust:`min` function that determines the minimum of two values, using the diff --git a/courses/comprehensive_rust_training/110_std_types/02_docs.rst b/courses/comprehensive_rust_training/110_std_types/02_docs.rst index 8e64f9ce3..b540e1af8 100644 --- a/courses/comprehensive_rust_training/110_std_types/02_docs.rst +++ b/courses/comprehensive_rust_training/110_std_types/02_docs.rst @@ -40,7 +40,7 @@ tool. It is idiomatic to document all public items in an API using this pattern. To document an item from inside the item (such as inside a module), use -:rust:`//!` or :rust:`/*! .. */`, called "inner doc comments": +:rust:`//!` or :rust:`/*! .. */`, called :dfn:`inner doc comments`: .. code:: rust diff --git a/courses/comprehensive_rust_training/110_std_types/03_option.rst b/courses/comprehensive_rust_training/110_std_types/03_option.rst index 8cc8b5395..9acb755c2 100644 --- a/courses/comprehensive_rust_training/110_std_types/03_option.rst +++ b/courses/comprehensive_rust_training/110_std_types/03_option.rst @@ -37,7 +37,7 @@ Details hacking something together, but production code typically handles :rust:`None` in a nicer fashion. -- The "niche optimization" means that :rust:`Option` often has the same +- The :dfn:`niche optimization` means that :rust:`Option` often has the same size in memory as :rust:`T`, if there is some representation that is not a valid value of T. For example, a reference cannot be NULL, so :rust:`Option<&T>` automatically uses NULL to represent the :rust:`None` diff --git a/courses/comprehensive_rust_training/110_std_types/06_vec.rst b/courses/comprehensive_rust_training/110_std_types/06_vec.rst index 40d19a5a4..84be8e651 100644 --- a/courses/comprehensive_rust_training/110_std_types/06_vec.rst +++ b/courses/comprehensive_rust_training/110_std_types/06_vec.rst @@ -1,10 +1,10 @@ -========= -"Vec" -========= +============= +:rust:`Vec` +============= ---------- -"Vec" ---------- +------------- +:rust:`Vec` +------------- :url:`Vec ` is the standard resizable heap-allocated buffer: diff --git a/courses/comprehensive_rust_training/110_std_types/07_hashmap.rst b/courses/comprehensive_rust_training/110_std_types/07_hashmap.rst index ee11e5a3b..71529d5d7 100644 --- a/courses/comprehensive_rust_training/110_std_types/07_hashmap.rst +++ b/courses/comprehensive_rust_training/110_std_types/07_hashmap.rst @@ -1,10 +1,10 @@ -============= -"HashMap" -============= +================= +:rust:`HashMap` +================= -------------- -"HashMap" -------------- +----------------- +:rust:`HashMap` +----------------- Standard hash map with protection against HashDoS attacks: @@ -80,7 +80,7 @@ Details - Alternatively HashMap can be built from any :rust:`Iterator` which yields key-value tuples. -- This type has several "method-specific" return types, such as +- This type has several *method-specific* return types, such as :rust:`std::collections::hash_map::Keys`. These types often appear in searches of the Rust docs. Show students the docs for this type, and the helpful link back to the :rust:`keys` method. diff --git a/courses/comprehensive_rust_training/120_std_traits/01_comparisons.rst b/courses/comprehensive_rust_training/120_std_traits/01_comparisons.rst index 0354ac9c0..8161bc04b 100644 --- a/courses/comprehensive_rust_training/120_std_traits/01_comparisons.rst +++ b/courses/comprehensive_rust_training/120_std_traits/01_comparisons.rst @@ -9,9 +9,9 @@ Comparisons These traits support comparisons between values. All traits can be derived for types containing fields that implement these traits. --------------------------- -"PartialEq" and "Eq" --------------------------- +---------------------------------- +:rust:`PartialEq` and :rust:`Eq` +---------------------------------- :rust:`PartialEq` is a partial equivalence relation, with required method :rust:`eq` and provided method :rust:`ne`. The :rust:`==` and :rust:`!=` operators will @@ -33,9 +33,9 @@ call these methods. transitive) and implies :rust:`PartialEq`. Functions that require full equivalence will use :rust:`Eq` as a trait bound. ----------------------------- -"PartialOrd" and "Ord" ----------------------------- +------------------------------------ +:rust:`PartialOrd` and :rust:`Ord` +------------------------------------ :rust:`PartialOrd` defines a partial ordering, with a :rust:`partial_cmp` method. It is used to implement the :rust:`<`, :rust:`<=`, :rust:`>=`, and :rust:`>` diff --git a/courses/comprehensive_rust_training/120_std_traits/03_from_and_into.rst b/courses/comprehensive_rust_training/120_std_traits/03_from_and_into.rst index cb749bb6e..30ff19381 100644 --- a/courses/comprehensive_rust_training/120_std_traits/03_from_and_into.rst +++ b/courses/comprehensive_rust_training/120_std_traits/03_from_and_into.rst @@ -1,10 +1,10 @@ -======================= -"From" and "Into" -======================= +=============================== +:rust:`From` and :rust:`Into` +=============================== ------------------------ -"From" and "Into" ------------------------ +------------------------------- +:rust:`From` and :rust:`Into` +------------------------------- Types implement :url:`From ` and diff --git a/courses/comprehensive_rust_training/120_std_traits/05_read_and_write.rst b/courses/comprehensive_rust_training/120_std_traits/05_read_and_write.rst index 23f4d6531..7d8f8ad68 100644 --- a/courses/comprehensive_rust_training/120_std_traits/05_read_and_write.rst +++ b/courses/comprehensive_rust_training/120_std_traits/05_read_and_write.rst @@ -1,10 +1,10 @@ -======================== -"Read" and "Write" -======================== +================================ +:rust:`Read` and :rust:`Write` +================================ ------------------------- -"Read" and "Write" ------------------------- +-------------------------------- +:rust:`Read` and :rust:`Write` +-------------------------------- Using :url:`Read ` and diff --git a/courses/comprehensive_rust_training/120_std_traits/06_default.rst b/courses/comprehensive_rust_training/120_std_traits/06_default.rst index ddf610336..3bec135cc 100644 --- a/courses/comprehensive_rust_training/120_std_traits/06_default.rst +++ b/courses/comprehensive_rust_training/120_std_traits/06_default.rst @@ -1,10 +1,10 @@ -======================= -The "Default" Trait -======================= +=========================== +The :rust:`Default` Trait +=========================== ------------------------ -The "Default" Trait ------------------------ +--------------------------- +The :rust:`Default` Trait +--------------------------- :url:`Default ` trait produces a default value for a type. diff --git a/courses/comprehensive_rust_training/130_memory_management/03_ownership.rst b/courses/comprehensive_rust_training/130_memory_management/03_ownership.rst index 976548aff..0937f89c5 100644 --- a/courses/comprehensive_rust_training/130_memory_management/03_ownership.rst +++ b/courses/comprehensive_rust_training/130_memory_management/03_ownership.rst @@ -32,5 +32,5 @@ Details --------- Students familiar with garbage-collection implementations will know that -a garbage collector starts with a set of "roots" to find all reachable -memory. Rust's "single owner" principle is a similar idea. +a garbage collector starts with a set of *roots* to find all reachable +memory. Rust's :dfn:`single owner` principle is a similar idea. diff --git a/courses/comprehensive_rust_training/130_memory_management/07_drop.rst b/courses/comprehensive_rust_training/130_memory_management/07_drop.rst index f12bc7dcd..634deb55a 100644 --- a/courses/comprehensive_rust_training/130_memory_management/07_drop.rst +++ b/courses/comprehensive_rust_training/130_memory_management/07_drop.rst @@ -1,10 +1,10 @@ -==================== -The "Drop" Trait -==================== +======================== +The :rust:`Drop` Trait +======================== --------------------- -The "Drop" Trait --------------------- +------------------------ +The :rust:`Drop` Trait +------------------------ Values which implement :url:`Drop ` can diff --git a/courses/comprehensive_rust_training/130_memory_management/08_exercise.rst b/courses/comprehensive_rust_training/130_memory_management/08_exercise.rst index 0c2838624..f79e80010 100644 --- a/courses/comprehensive_rust_training/130_memory_management/08_exercise.rst +++ b/courses/comprehensive_rust_training/130_memory_management/08_exercise.rst @@ -7,7 +7,7 @@ Exercise: Builder Type ------------------------ In this example, we will implement a complex data type that owns all of -its data. We will use the "builder pattern" to support building a new +its data. We will use the *builder pattern* to support building a new value piece-by-piece, using convenience functions. Fill in the missing pieces. diff --git a/courses/comprehensive_rust_training/140_smart_pointers/01_box.rst b/courses/comprehensive_rust_training/140_smart_pointers/01_box.rst index 470a8470a..14bdaf31c 100644 --- a/courses/comprehensive_rust_training/140_smart_pointers/01_box.rst +++ b/courses/comprehensive_rust_training/140_smart_pointers/01_box.rst @@ -1,10 +1,10 @@ -============ -"Box" -============ +================ +:rust:`Box` +================ ------------- -"Box" ------------- +---------------- +:rust:`Box` +---------------- :url:`Box ` is an owned pointer to data on the heap: @@ -90,11 +90,10 @@ Details heap. - Remove the :rust:`Box` in the List definition and show the compiler - error. We get the message "recursive without indirection", because + error. We get the message :command:`recursive without indirection`, because for data recursion, we have to use indirection, a :rust:`Box` or reference of some kind, instead of storing the value directly. - Though :rust:`Box` looks like :rust:`std::unique_ptr` in C++, it cannot be empty/null. This makes :rust:`Box` one of the types that allow the - compiler to optimize storage of some enums (the "niche - optimization"). + compiler to optimize storage of some enums (the :dfn:`niche optimization`). diff --git a/courses/comprehensive_rust_training/140_smart_pointers/02_rc.rst b/courses/comprehensive_rust_training/140_smart_pointers/02_rc.rst index b4eb4f032..4990a0146 100644 --- a/courses/comprehensive_rust_training/140_smart_pointers/02_rc.rst +++ b/courses/comprehensive_rust_training/140_smart_pointers/02_rc.rst @@ -1,10 +1,10 @@ -======== -"Rc" -======== +============ +:rust:`Rc` +============ --------- -"Rc" --------- +------------ +:rust:`Rc` +------------ :url:`Rc ` is a reference-counted shared pointer. Use this when you need to refer to the diff --git a/courses/comprehensive_rust_training/150_borrowing/02_borrowck.rst b/courses/comprehensive_rust_training/150_borrowing/02_borrowck.rst index ff1526a51..50315ee1d 100644 --- a/courses/comprehensive_rust_training/150_borrowing/02_borrowck.rst +++ b/courses/comprehensive_rust_training/150_borrowing/02_borrowck.rst @@ -45,7 +45,7 @@ There's also a second main rule that the borrow checker enforces: The Details --------- -- The "outlives" rule was demonstrated previously when we first looked +- The :dfn:`outlives` rule was demonstrated previously when we first looked at references. We review it here to show students that the borrow checking is following a few different rules to validate borrowing. - Note that the requirement is that conflicting references not *exist* @@ -57,7 +57,7 @@ Details introduces :rust:`c` to make the code compile. - After that change, the compiler realizes that :rust:`b` is only ever used before the new mutable borrow of :rust:`a` through :rust:`c`. This is a - feature of the borrow checker called "non-lexical lifetimes". + feature of the borrow checker called :dfn:`non-lexical lifetimes`. - The exclusive reference constraint is quite strong. Rust uses it to ensure that data races do not occur. Rust also *relies* on this constraint to optimize code. For example, a value behind a shared diff --git a/courses/comprehensive_rust_training/150_borrowing/04_interior_mutability.rst b/courses/comprehensive_rust_training/150_borrowing/04_interior_mutability.rst index bed5a88d5..915c9399e 100644 --- a/courses/comprehensive_rust_training/150_borrowing/04_interior_mutability.rst +++ b/courses/comprehensive_rust_training/150_borrowing/04_interior_mutability.rst @@ -10,7 +10,7 @@ In some situations, it's necessary to modify data behind a shared (read-only) reference. For example, a shared data structure might have an internal cache, and wish to update that cache from read-only methods. -The "interior mutability" pattern allows exclusive (mutable) access +The :dfn:`interior mutability` pattern allows exclusive (mutable) access behind a shared reference. The standard library provides several ways to do this, all while still ensuring safety, typically by performing a runtime check. @@ -25,7 +25,7 @@ ways to ensure that safety, and the next sub-slides present a few of them. -------------- -"Cell" +:rust:`Cell` -------------- :rust:`Cell` wraps a value and allows getting or setting the value using @@ -45,16 +45,16 @@ rules cannot be broken. println!("{}", cell.get()); } ----------------- -"Cell" Details ----------------- +---------------------- +:rust:`Cell` Details +---------------------- - :rust:`Cell` is a simple means to ensure safety: it has a :rust:`set` method that takes :rust:`&self`. This needs no runtime check, but requires moving values, which can have its own cost. ----------------- -"RefCell" +:rust:`RefCell` ----------------- :rust:`RefCell` allows accessing and mutating a wrapped value by providing @@ -88,9 +88,9 @@ escape. println!("{cell:?}"); } -------------------- -"RefCell" Details -------------------- +------------------------- +:rust:`RefCell` Details +------------------------- - :rust:`RefCell` enforces Rust's usual borrowing rules (either multiple shared references or a single exclusive reference) with a runtime diff --git a/courses/comprehensive_rust_training/160_lifetimes/01_lifetime_annotations.rst b/courses/comprehensive_rust_training/160_lifetimes/01_lifetime_annotations.rst index 22fea7ef0..cddb0ac61 100644 --- a/courses/comprehensive_rust_training/160_lifetimes/01_lifetime_annotations.rst +++ b/courses/comprehensive_rust_training/160_lifetimes/01_lifetime_annotations.rst @@ -6,7 +6,7 @@ Lifetime Annotations Lifetime Annotations ---------------------- -A reference has a *lifetime*, which must not "outlive" the value it +A reference has a *lifetime*, which must not :dfn:`outlive` the value it refers to. This is verified by the borrow checker. The lifetime can be implicit - this is what we have seen so far. @@ -60,7 +60,7 @@ Add :rust:`'a` appropriately to :rust:`left_most`: fn left_most<'a>(p1: &'a Point, p2: &'a Point) -> &'a Point { This says, "given p1 and p2 which both outlive :rust:`'a`, the return value -lives for at least :rust:`'a`. +lives for at least :rust:`'a`." In common cases, lifetimes can be elided, as described on the next slide. diff --git a/courses/comprehensive_rust_training/160_lifetimes/04_exercise.rst b/courses/comprehensive_rust_training/160_lifetimes/04_exercise.rst index 2bcf17e59..975b08667 100644 --- a/courses/comprehensive_rust_training/160_lifetimes/04_exercise.rst +++ b/courses/comprehensive_rust_training/160_lifetimes/04_exercise.rst @@ -37,7 +37,7 @@ Messages ---------- A proto message is encoded as a series of fields, one after the next. -Each is implemented as a "tag" followed by the value. The tag contains a +Each is implemented as a :dfn:`tag` followed by the value. The tag contains a field number (e.g., :rust:`2` for the :rust:`id` field of a :rust:`Person` message) and a wire type defining how the payload should be determined from the byte stream. These are combined into a single integer, as decoded in diff --git a/courses/comprehensive_rust_training/170_iterators/01_motivation.rst b/courses/comprehensive_rust_training/170_iterators/01_motivation.rst index 1facf9371..609275f7c 100644 --- a/courses/comprehensive_rust_training/170_iterators/01_motivation.rst +++ b/courses/comprehensive_rust_training/170_iterators/01_motivation.rst @@ -24,7 +24,7 @@ In a C-style for loop you declare these things directly: } In Rust we bundle this state and logic together into an object known as -an "iterator". +an :dfn:`iterator`. --------- Details diff --git a/courses/comprehensive_rust_training/170_iterators/02_iterator.rst b/courses/comprehensive_rust_training/170_iterators/02_iterator.rst index af2d64505..791b7fb7a 100644 --- a/courses/comprehensive_rust_training/170_iterators/02_iterator.rst +++ b/courses/comprehensive_rust_training/170_iterators/02_iterator.rst @@ -1,10 +1,10 @@ -==================== -"Iterator" Trait -==================== +======================== +:rust:`Iterator` Trait +======================== --------------------- -"Iterator" Trait --------------------- +------------------------ +:rust:`Iterator` Trait +------------------------ The :url:`Iterator ` diff --git a/courses/comprehensive_rust_training/170_iterators/03_helpers.rst b/courses/comprehensive_rust_training/170_iterators/03_helpers.rst index b57fe1c1b..616e3c4d6 100644 --- a/courses/comprehensive_rust_training/170_iterators/03_helpers.rst +++ b/courses/comprehensive_rust_training/170_iterators/03_helpers.rst @@ -1,10 +1,10 @@ -============================= -"Iterator" Helper Methods -============================= +================================= +:rust:`Iterator` Helper Methods +================================= ------------------------------ -"Iterator" Helper Methods ------------------------------ +--------------------------------- +:rust:`Iterator` Helper Methods +--------------------------------- In addition to the :rust:`next` method that defines how an iterator behaves, the :rust:`Iterator` trait provides 70+ helper methods that can be used to @@ -29,8 +29,8 @@ Details about them. - Many of these helper methods take the original iterator and produce a - new iterator with different behavior. These are know as "iterator - adapter methods". + new iterator with different behavior. These are know as + :dfn:`iterator adapter methods`. - Some methods, like :rust:`sum` and :rust:`count`, consume the iterator and pull all of the elements out of it. diff --git a/courses/comprehensive_rust_training/170_iterators/04_collect.rst b/courses/comprehensive_rust_training/170_iterators/04_collect.rst index d283a399a..c94cf3aa2 100644 --- a/courses/comprehensive_rust_training/170_iterators/04_collect.rst +++ b/courses/comprehensive_rust_training/170_iterators/04_collect.rst @@ -1,10 +1,10 @@ -============= -"collect" -============= +================= +:rust:`collect` +================= -------------- -"collect" -------------- +----------------- +:rust:`collect` +----------------- The :url:`collect ` diff --git a/courses/comprehensive_rust_training/170_iterators/05_intoiterator.rst b/courses/comprehensive_rust_training/170_iterators/05_intoiterator.rst index cc0ffbcd3..f9fe36bdf 100644 --- a/courses/comprehensive_rust_training/170_iterators/05_intoiterator.rst +++ b/courses/comprehensive_rust_training/170_iterators/05_intoiterator.rst @@ -1,10 +1,10 @@ -================== -"IntoIterator" -================== +====================== +:rust:`IntoIterator` +====================== ------------------- -"IntoIterator" ------------------- +---------------------- +:rust:`IntoIterator` +---------------------- The :rust:`Iterator` trait tells you how to *iterate* once you have created an iterator. The related trait diff --git a/courses/comprehensive_rust_training/180_modules/02_filesystem.rst b/courses/comprehensive_rust_training/180_modules/02_filesystem.rst index f0627aabf..35b892844 100644 --- a/courses/comprehensive_rust_training/180_modules/02_filesystem.rst +++ b/courses/comprehensive_rust_training/180_modules/02_filesystem.rst @@ -22,8 +22,8 @@ The :rust:`crate` root is in: - :rust:`src/lib.rs` (for a library crate) - :rust:`src/main.rs` (for a binary crate) -Modules defined in files can be documented, too, using "inner doc -comments". These document the item that contains them - in this case, a +Modules defined in files can be documented, too, using :dfn:`inner doc comments`. +These document the item that contains them - in this case, a module. .. code:: rust diff --git a/courses/comprehensive_rust_training/180_modules/05_paths.rst b/courses/comprehensive_rust_training/180_modules/05_paths.rst index 766be8c14..53e8259ac 100644 --- a/courses/comprehensive_rust_training/180_modules/05_paths.rst +++ b/courses/comprehensive_rust_training/180_modules/05_paths.rst @@ -34,7 +34,7 @@ Paths are resolved as follows: Details --------- -- It is common to "re-export" symbols at a shorter path. For example, +- It is common to *re-export* symbols at a shorter path. For example, the top-level :rust:`lib.rs` in a crate might have .. code:: rust diff --git a/courses/comprehensive_rust_training/200_error_handling/01_panics.rst b/courses/comprehensive_rust_training/200_error_handling/01_panics.rst index a1d0dc7d1..72535fa5d 100644 --- a/courses/comprehensive_rust_training/200_error_handling/01_panics.rst +++ b/courses/comprehensive_rust_training/200_error_handling/01_panics.rst @@ -6,7 +6,7 @@ Panics Panics -------- -Rust handles fatal errors with a "panic". +Rust handles fatal errors with a :dfn:`panic`. Rust will trigger a panic if a fatal error happens at runtime: @@ -24,7 +24,7 @@ Rust will trigger a panic if a fatal error happens at runtime: - Assertions (such as :rust:`assert!`) panic on failure - Purpose-specific panics can use the :rust:`panic!` macro. -- A panic will "unwind" the stack, dropping values just as if the +- A panic will :dfn:`unwind` the stack, dropping values just as if the functions had returned. - Use non-panicking APIs (such as :rust:`Vec::get`) if crashing is not acceptable. diff --git a/courses/comprehensive_rust_training/200_error_handling/02_result.rst b/courses/comprehensive_rust_training/200_error_handling/02_result.rst index 108f324df..f3e8655d8 100644 --- a/courses/comprehensive_rust_training/200_error_handling/02_result.rst +++ b/courses/comprehensive_rust_training/200_error_handling/02_result.rst @@ -1,10 +1,10 @@ -============ -"Result" -============ +================ +:rust:`Result` +================ ------------- -"Result" ------------- +---------------- +:rust:`Result` +---------------- Our primary mechanism for error handling in Rust is the :url:`Result ` diff --git a/courses/comprehensive_rust_training/200_error_handling/06_thiserror.rst b/courses/comprehensive_rust_training/200_error_handling/06_thiserror.rst index e93f6986d..9b1b1ad65 100644 --- a/courses/comprehensive_rust_training/200_error_handling/06_thiserror.rst +++ b/courses/comprehensive_rust_training/200_error_handling/06_thiserror.rst @@ -1,10 +1,10 @@ -=============== -"thiserror" -=============== +=================== +:rust:`thiserror` +=================== ---------------- -"thiserror" ---------------- +------------------- +:rust:`thiserror` +------------------- The :url:`thiserror ` crate provides macros to help avoid boilerplate when defining error types. It provides derive diff --git a/courses/comprehensive_rust_training/200_error_handling/07_anyhow.rst b/courses/comprehensive_rust_training/200_error_handling/07_anyhow.rst index df8228792..297e06b0c 100644 --- a/courses/comprehensive_rust_training/200_error_handling/07_anyhow.rst +++ b/courses/comprehensive_rust_training/200_error_handling/07_anyhow.rst @@ -1,10 +1,10 @@ -============ -"anyhow" -============ +================ +:rust:`anyhow` +================ ------------- -"anyhow" ------------- +---------------- +:rust:`anyhow` +---------------- The :url:`anyhow ` crate provides a rich error type with support for carrying additional contextual information, which diff --git a/courses/comprehensive_rust_training/210_unsafe_rust/02_dereferencing.rst b/courses/comprehensive_rust_training/210_unsafe_rust/02_dereferencing.rst index 76bb73716..c34a54303 100644 --- a/courses/comprehensive_rust_training/210_unsafe_rust/02_dereferencing.rst +++ b/courses/comprehensive_rust_training/210_unsafe_rust/02_dereferencing.rst @@ -59,7 +59,7 @@ i.e.: In most cases the pointer must also be properly aligned. -The "NOT SAFE" section gives an example of a common kind of UB bug: +The *NOT SAFE* section gives an example of a common kind of UB bug: :rust:`*r1` has the :rust:`'static` lifetime, so :rust:`r3` has type :rust:`&'static String`, and thus outlives :rust:`s`. Creating a reference from a pointer requires *great care*.