From 218caa410aa38c29984be31a5229b9fa717560ee Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 17 Apr 2024 14:19:13 +0200 Subject: Merging upstream version 1.68.2+dfsg1. Signed-off-by: Daniel Baumann --- src/doc/rust-by-example/src/SUMMARY.md | 1 + src/doc/rust-by-example/src/custom_types/enum.md | 6 +- .../src/error/option_unwrap/defaults.md | 10 +-- .../rust-by-example/src/flow_control/let_else.md | 60 ++++++++++++++ .../src/fn/closures/closure_examples/iter_any.md | 2 +- src/doc/rust-by-example/src/fn/diverging.md | 4 +- src/doc/rust-by-example/src/hello.md | 14 ++-- src/doc/rust-by-example/src/hello/comment.md | 30 ++++--- src/doc/rust-by-example/src/hello/print.md | 66 ++++++++------- src/doc/rust-by-example/src/hello/print/fmt.md | 13 +-- .../rust-by-example/src/hello/print/print_debug.md | 6 +- .../src/hello/print/print_display.md | 11 ++- .../src/hello/print/print_display/testcase_list.md | 3 +- src/doc/rust-by-example/src/primitives.md | 38 ++++----- src/doc/rust-by-example/src/primitives/array.md | 55 ++++++------- src/doc/rust-by-example/src/primitives/literals.md | 11 ++- src/doc/rust-by-example/src/primitives/tuples.md | 95 +++++++++++----------- src/doc/rust-by-example/src/types/alias.md | 4 +- 18 files changed, 249 insertions(+), 180 deletions(-) create mode 100644 src/doc/rust-by-example/src/flow_control/let_else.md (limited to 'src/doc/rust-by-example') diff --git a/src/doc/rust-by-example/src/SUMMARY.md b/src/doc/rust-by-example/src/SUMMARY.md index 9d7001690..b1bcf223d 100644 --- a/src/doc/rust-by-example/src/SUMMARY.md +++ b/src/doc/rust-by-example/src/SUMMARY.md @@ -59,6 +59,7 @@ - [Guards](flow_control/match/guard.md) - [Binding](flow_control/match/binding.md) - [if let](flow_control/if_let.md) + - [let-else](flow_control/let_else.md) - [while let](flow_control/while_let.md) - [Functions](fn.md) diff --git a/src/doc/rust-by-example/src/custom_types/enum.md b/src/doc/rust-by-example/src/custom_types/enum.md index e861df9bf..b7fb7e419 100644 --- a/src/doc/rust-by-example/src/custom_types/enum.md +++ b/src/doc/rust-by-example/src/custom_types/enum.md @@ -1,7 +1,7 @@ # Enums The `enum` keyword allows the creation of a type which may be one of a few -different variants. Any variant which is valid as a `struct` is also valid as +different variants. Any variant which is valid as a `struct` is also valid in an `enum`. ```rust,editable @@ -10,7 +10,7 @@ an `enum`. // `PageLoad != PageUnload` and `KeyPress(char) != Paste(String)`. // Each is different and independent. enum WebEvent { - // An `enum` may either be `unit-like`, + // An `enum` variant may either be `unit-like`, PageLoad, PageUnload, // like tuple structs, @@ -26,7 +26,7 @@ fn inspect(event: WebEvent) { match event { WebEvent::PageLoad => println!("page loaded"), WebEvent::PageUnload => println!("page unloaded"), - // Destructure `c` from inside the `enum`. + // Destructure `c` from inside the `enum` variant. WebEvent::KeyPress(c) => println!("pressed '{}'.", c), WebEvent::Paste(s) => println!("pasted \"{}\".", s), // Destructure `Click` into `x` and `y`. diff --git a/src/doc/rust-by-example/src/error/option_unwrap/defaults.md b/src/doc/rust-by-example/src/error/option_unwrap/defaults.md index 117333f12..4c1844a20 100644 --- a/src/doc/rust-by-example/src/error/option_unwrap/defaults.md +++ b/src/doc/rust-by-example/src/error/option_unwrap/defaults.md @@ -63,17 +63,17 @@ fn main() { To make sure that an `Option` contains a value, we can use `get_or_insert` to modify it in place with a fallback value, as is shown in the following example. Note that `get_or_insert` eagerly evaluates its parameter, so variable `apple` is moved: ```rust,editable -#[derive(Debug)] +#[derive(Debug)] enum Fruit { Apple, Orange, Banana, Kiwi, Lemon } fn main() { let mut my_fruit: Option = None; let apple = Fruit::Apple; let first_available_fruit = my_fruit.get_or_insert(apple); - println!("my_fruit is: {:?}", first_available_fruit); println!("first_available_fruit is: {:?}", first_available_fruit); - // my_fruit is: Apple + println!("my_fruit is: {:?}", my_fruit); // first_available_fruit is: Apple + // my_fruit is: Some(Apple) //println!("Variable named `apple` is moved: {:?}", apple); // TODO: uncomment the line above to see the compiler error } @@ -94,11 +94,11 @@ fn main() { }; let first_available_fruit = my_fruit .get_or_insert_with(get_lemon_as_fallback); - println!("my_fruit is: {:?}", first_available_fruit); println!("first_available_fruit is: {:?}", first_available_fruit); + println!("my_fruit is: {:?}", my_fruit); // Providing lemon as fallback - // my_fruit is: Lemon // first_available_fruit is: Lemon + // my_fruit is: Some(Lemon) // If the Option has a value, it is left unchanged, and the closure is not invoked let mut my_apple = Some(Fruit::Apple); diff --git a/src/doc/rust-by-example/src/flow_control/let_else.md b/src/doc/rust-by-example/src/flow_control/let_else.md new file mode 100644 index 000000000..bc21723c7 --- /dev/null +++ b/src/doc/rust-by-example/src/flow_control/let_else.md @@ -0,0 +1,60 @@ +# let-else + + +> 🛈 stable since: rust 1.65 + + +With `let`-`else`, a refutable pattern can match and bind variables +in the surrounding scope like a normal `let`, or else diverge (e.g. `break`, +`return`, `panic!`) when the pattern doesn't match. + +```rust +use std::str::FromStr; + +fn get_count_item(s: &str) -> (u64, &str) { + let mut it = s.split(' '); + let (Some(count_str), Some(item)) = (it.next(), it.next()) else { + panic!("Can't segment count item pair: '{s}'"); + }; + let Ok(count) = u64::from_str(count_str) else { + panic!("Can't parse integer: '{count_str}'"); + }; + (count, item) +} + +assert_eq!(get_count_item("3 chairs"), (3, "chairs")); +``` + +The scope of name bindings is the main thing that makes this different from +`match` or `if let`-`else` expressions. You could previously approximate these +patterns with an unfortunate bit of repetition and an outer `let`: + +```rust +# use std::str::FromStr; +# +# fn get_count_item(s: &str) -> (u64, &str) { +# let mut it = s.split(' '); + let (count_str, item) = match (it.next(), it.next()) { + (Some(count_str), Some(item)) => (count_str, item), + _ => panic!("Can't segment count item pair: '{s}'"), + }; + let count = if let Ok(count) = u64::from_str(count_str) { + count + } else { + panic!("Can't parse integer: '{count_str}'"); + }; +# (count, item) +# } +# +# assert_eq!(get_count_item("3 chairs"), (3, "chairs")); +``` + +### See also: + +[option][option], [match][match], [if let][if_let] and the [let-else RFC][let_else_rfc]. + + +[match]: ./match.md +[if_let]: ./if_let.md +[let_else_rfc]: https://rust-lang.github.io/rfcs/3137-let-else.html +[option]: ../std/option.md \ No newline at end of file diff --git a/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_any.md b/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_any.md index fe7fc39f8..4c19caccc 100644 --- a/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_any.md +++ b/src/doc/rust-by-example/src/fn/closures/closure_examples/iter_any.md @@ -27,7 +27,7 @@ fn main() { // `iter()` for vecs yields `&i32`. Destructure to `i32`. println!("2 in vec1: {}", vec1.iter() .any(|&x| x == 2)); // `into_iter()` for vecs yields `i32`. No destructuring required. - println!("2 in vec2: {}", vec2.into_iter().any(| x| x == 2)); + println!("2 in vec2: {}", vec2.into_iter().any(|x| x == 2)); // `iter()` only borrows `vec1` and its elements, so they can be used again println!("vec1 len: {}", vec1.len()); diff --git a/src/doc/rust-by-example/src/fn/diverging.md b/src/doc/rust-by-example/src/fn/diverging.md index 52e1f819a..4bc7c9fea 100644 --- a/src/doc/rust-by-example/src/fn/diverging.md +++ b/src/doc/rust-by-example/src/fn/diverging.md @@ -21,8 +21,8 @@ fn some_fn() { } fn main() { - let a: () = some_fn(); - println!("This function returns and you can see this line.") + let _a: () = some_fn(); + println!("This function returns and you can see this line."); } ``` diff --git a/src/doc/rust-by-example/src/hello.md b/src/doc/rust-by-example/src/hello.md index 2a8d3153f..4aaddeb1f 100644 --- a/src/doc/rust-by-example/src/hello.md +++ b/src/doc/rust-by-example/src/hello.md @@ -3,18 +3,19 @@ This is the source code of the traditional Hello World program. ```rust,editable -// This is a comment, and is ignored by the compiler +// This is a comment, and is ignored by the compiler. // You can test this code by clicking the "Run" button over there -> -// or if you prefer to use your keyboard, you can use the "Ctrl + Enter" shortcut +// or if you prefer to use your keyboard, you can use the "Ctrl + Enter" +// shortcut. // This code is editable, feel free to hack it! // You can always return to the original code by clicking the "Reset" button -> -// This is the main function +// This is the main function. fn main() { - // Statements here are executed when the compiled binary is called + // Statements here are executed when the compiled binary is called. - // Print text to the console + // Print text to the console. println!("Hello World!"); } ``` @@ -38,8 +39,7 @@ Hello World! ### Activity Click 'Run' above to see the expected output. Next, add a new -line with a second `println!` macro so that the output -shows: +line with a second `println!` macro so that the output shows: ```text Hello World! diff --git a/src/doc/rust-by-example/src/hello/comment.md b/src/doc/rust-by-example/src/hello/comment.md index 8cd1ccf55..5027f0a22 100644 --- a/src/doc/rust-by-example/src/hello/comment.md +++ b/src/doc/rust-by-example/src/hello/comment.md @@ -4,30 +4,29 @@ Any program requires comments, and Rust supports a few different varieties: * *Regular comments* which are ignored by the compiler: - * `// Line comments which go to the end of the line.` - * `/* Block comments which go to the closing delimiter. */` -* *Doc comments* which are parsed into HTML library - [documentation][docs]: - * `/// Generate library docs for the following item.` - * `//! Generate library docs for the enclosing item.` + * `// Line comments which go to the end of the line.` + * `/* Block comments which go to the closing delimiter. */` +* *Doc comments* which are parsed into HTML library [documentation][docs]: + * `/// Generate library docs for the following item.` + * `//! Generate library docs for the enclosing item.` ```rust,editable fn main() { - // This is an example of a line comment - // There are two slashes at the beginning of the line - // And nothing written inside these will be read by the compiler + // This is an example of a line comment. + // There are two slashes at the beginning of the line. + // And nothing written inside these will be read by the compiler. // println!("Hello, world!"); // Run it. See? Now try deleting the two slashes, and run it again. - /* + /* * This is another type of comment, a block comment. In general, - * line comments are the recommended comment style. But - * block comments are extremely useful for temporarily disabling - * chunks of code. /* Block comments can be /* nested, */ */ - * so it takes only a few keystrokes to comment out everything - * in this main() function. /*/*/* Try it yourself! */*/*/ + * line comments are the recommended comment style. But block comments + * are extremely useful for temporarily disabling chunks of code. + * /* Block comments can be /* nested, */ */ so it takes only a few + * keystrokes to comment out everything in this main() function. + * /*/*/* Try it yourself! */*/*/ */ /* @@ -41,7 +40,6 @@ fn main() { let x = 5 + /* 90 + */ 5; println!("Is `x` 10 or 100? x = {}", x); } - ``` ### See also: diff --git a/src/doc/rust-by-example/src/hello/print.md b/src/doc/rust-by-example/src/hello/print.md index cce838fc2..55f6ed520 100644 --- a/src/doc/rust-by-example/src/hello/print.md +++ b/src/doc/rust-by-example/src/hello/print.md @@ -1,12 +1,14 @@ # Formatted print -Printing is handled by a series of [`macros`][macros] defined in [`std::fmt`][fmt] -some of which include: +Printing is handled by a series of [`macros`][macros] defined in +[`std::fmt`][fmt] some of which include: * `format!`: write formatted text to [`String`][string] -* `print!`: same as `format!` but the text is printed to the console (io::stdout). +* `print!`: same as `format!` but the text is printed to the console + (io::stdout). * `println!`: same as `print!` but a newline is appended. -* `eprint!`: same as `print!` but the text is printed to the standard error (io::stderr). +* `eprint!`: same as `print!` but the text is printed to the standard error + (io::stderr). * `eprintln!`: same as `eprint!` but a newline is appended. All parse text in the same fashion. As a plus, Rust checks formatting @@ -20,7 +22,7 @@ fn main() { // Positional arguments can be used. Specifying an integer inside `{}` // determines which additional argument will be replaced. Arguments start - // at 0 immediately after the format string + // at 0 immediately after the format string. println!("{0}, this is {1}. {1}, this is {0}", "Alice", "Bob"); // As can named arguments. @@ -29,13 +31,13 @@ fn main() { subject="the quick brown fox", verb="jumps over"); - // Different formatting can be invoked by specifying the format character after a - // `:`. - println!("Base 10: {}", 69420); //69420 - println!("Base 2 (binary): {:b}", 69420); //10000111100101100 - println!("Base 8 (octal): {:o}", 69420); //207454 - println!("Base 16 (hexadecimal): {:x}", 69420); //10f2c - println!("Base 16 (hexadecimal): {:X}", 69420); //10F2C + // Different formatting can be invoked by specifying the format character + // after a `:`. + println!("Base 10: {}", 69420); // 69420 + println!("Base 2 (binary): {:b}", 69420); // 10000111100101100 + println!("Base 8 (octal): {:o}", 69420); // 207454 + println!("Base 16 (hexadecimal): {:x}", 69420); // 10f2c + println!("Base 16 (hexadecimal): {:X}", 69420); // 10F2C // You can right-justify text with a specified width. This will @@ -43,32 +45,31 @@ fn main() { println!("{number:>5}", number=1); // You can pad numbers with extra zeroes, - //and left-adjust by flipping the sign. This will output "10000". + // and left-adjust by flipping the sign. This will output "10000". println!("{number:0<5}", number=1); - // You can use named arguments in the format specifier by appending a `$` + // You can use named arguments in the format specifier by appending a `$`. println!("{number:0>width$}", number=1, width=5); - // Rust even checks to make sure the correct number of arguments are - // used. + // Rust even checks to make sure the correct number of arguments are used. println!("My name is {0}, {1} {0}", "Bond"); // FIXME ^ Add the missing argument: "James" // Only types that implement fmt::Display can be formatted with `{}`. User- - // defined types do not implement fmt::Display by default + // defined types do not implement fmt::Display by default. - #[allow(dead_code)] + #[allow(dead_code)] // disable `dead_code` which warn against unused module struct Structure(i32); // This will not compile because `Structure` does not implement - // fmt::Display + // fmt::Display. //println!("This struct `{}` won't print...", Structure(3)); // TODO ^ Try uncommenting this line // For Rust 1.58 and above, you can directly capture the argument from a // surrounding variable. Just like the above, this will output - // " 1". 4 white spaces and a "1". + // " 1", 4 white spaces and a "1". let number: f64 = 1.0; let width: usize = 5; println!("{number:>width$}"); @@ -80,7 +81,7 @@ of text. The base form of two important ones are listed below: * `fmt::Debug`: Uses the `{:?}` marker. Format text for debugging purposes. * `fmt::Display`: Uses the `{}` marker. Format text in a more elegant, user -friendly fashion. + friendly fashion. Here, we used `fmt::Display` because the std library provides implementations for these types. To print text for custom types, more steps are required. @@ -88,21 +89,22 @@ for these types. To print text for custom types, more steps are required. Implementing the `fmt::Display` trait automatically implements the [`ToString`] trait which allows us to [convert] the type to [`String`][string]. +In *line 46*, `#[allow(dead_code)]` is an [attribute] which only apply to the module after it. + ### Activities - * Fix the issue in the above code (see FIXME) so that it runs without - error. - * Try uncommenting the line that attempts to format the `Structure` struct (see TODO) - * Add a `println!` macro call that prints: `Pi is roughly 3.142` by controlling - the number of decimal places shown. For the purposes of this exercise, - use `let pi = 3.141592` as an estimate for pi. (Hint: you may need to - check the [`std::fmt`][fmt] documentation for setting the number of - decimals to display) +* Fix the issue in the above code (see FIXME) so that it runs without + error. +* Try uncommenting the line that attempts to format the `Structure` struct + (see TODO) +* Add a `println!` macro call that prints: `Pi is roughly 3.142` by controlling + the number of decimal places shown. For the purposes of this exercise, use + `let pi = 3.141592` as an estimate for pi. (Hint: you may need to check the + [`std::fmt`][fmt] documentation for setting the number of decimals to display) ### See also: -[`std::fmt`][fmt], [`macros`][macros], [`struct`][structs], -and [`traits`][traits] +[`std::fmt`][fmt], [`macros`][macros], [`struct`][structs], [`traits`][traits], and [`dead_code`][dead_code] [fmt]: https://doc.rust-lang.org/std/fmt/ [macros]: ../macros.md @@ -111,3 +113,5 @@ and [`traits`][traits] [traits]: https://doc.rust-lang.org/std/fmt/#formatting-traits [`ToString`]: https://doc.rust-lang.org/std/string/trait.ToString.html [convert]: ../conversion/string.md +[attribute]: ../attribute.md +[dead_code]: ../attribute/unused.md diff --git a/src/doc/rust-by-example/src/hello/print/fmt.md b/src/doc/rust-by-example/src/hello/print/fmt.md index 82c3e0145..5332b4903 100644 --- a/src/doc/rust-by-example/src/hello/print/fmt.md +++ b/src/doc/rust-by-example/src/hello/print/fmt.md @@ -3,8 +3,7 @@ We've seen that formatting is specified via a *format string*: * `format!("{}", foo)` -> `"3735928559"` -* `format!("0x{:X}", foo)` -> - [`"0xDEADBEEF"`][deadbeef] +* `format!("0x{:X}", foo)` -> [`"0xDEADBEEF"`][deadbeef] * `format!("0o{:o}", foo)` -> `"0o33653337357"` The same variable (`foo`) can be formatted differently depending on which @@ -26,13 +25,13 @@ struct City { } impl Display for City { - // `f` is a buffer, and this method must write the formatted string into it + // `f` is a buffer, and this method must write the formatted string into it. fn fmt(&self, f: &mut Formatter) -> fmt::Result { let lat_c = if self.lat >= 0.0 { 'N' } else { 'S' }; let lon_c = if self.lon >= 0.0 { 'E' } else { 'W' }; // `write!` is like `format!`, but it will write the formatted string - // into a buffer (the first argument) + // into a buffer (the first argument). write!(f, "{}: {:.3}°{} {:.3}°{}", self.name, self.lat.abs(), lat_c, self.lon.abs(), lon_c) } @@ -69,6 +68,7 @@ You can view a [full list of formatting traits][fmt_traits] and their argument types in the [`std::fmt`][fmt] documentation. ### Activity + Add an implementation of the `fmt::Display` trait for the `Color` struct above so that the output displays as: @@ -79,8 +79,9 @@ RGB (0, 0, 0) 0x000000 ``` Two hints if you get stuck: - * You [may need to list each color more than once][named_parameters], - * You can [pad with zeros to a width of 2][fmt_width] with `:0>2`. + +* You [may need to list each color more than once][named_parameters]. +* You can [pad with zeros to a width of 2][fmt_width] with `:0>2`. ### See also: diff --git a/src/doc/rust-by-example/src/hello/print/print_debug.md b/src/doc/rust-by-example/src/hello/print/print_debug.md index 161b0b772..03b1975ee 100644 --- a/src/doc/rust-by-example/src/hello/print/print_debug.md +++ b/src/doc/rust-by-example/src/hello/print/print_debug.md @@ -43,15 +43,15 @@ fn main() { // `Structure` is printable! println!("Now {:?} will print!", Structure(3)); - + // The problem with `derive` is there is no control over how // the results look. What if I want this to just show a `7`? println!("Now {:?} will print!", Deep(Structure(7))); } ``` -So `fmt::Debug` definitely makes this printable but sacrifices some -elegance. Rust also provides "pretty printing" with `{:#?}`. +So `fmt::Debug` definitely makes this printable but sacrifices some elegance. +Rust also provides "pretty printing" with `{:#?}`. ```rust,editable #[derive(Debug)] diff --git a/src/doc/rust-by-example/src/hello/print/print_display.md b/src/doc/rust-by-example/src/hello/print/print_display.md index fdae9648a..5d8a45b12 100644 --- a/src/doc/rust-by-example/src/hello/print/print_display.md +++ b/src/doc/rust-by-example/src/hello/print/print_display.md @@ -41,7 +41,7 @@ or for any other generic containers. `fmt::Debug` must then be used for these generic cases. This is not a problem though because for any new *container* type which is -*not* generic,`fmt::Display` can be implemented. +*not* generic, `fmt::Display` can be implemented. ```rust,editable use std::fmt; // Import `fmt` @@ -66,7 +66,7 @@ struct Point2D { y: f64, } -// Similarly, implement `Display` for `Point2D` +// Similarly, implement `Display` for `Point2D`. impl fmt::Display for Point2D { fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result { // Customize so only `x` and `y` are denoted. @@ -100,10 +100,9 @@ fn main() { } ``` -So, `fmt::Display` has been implemented but `fmt::Binary` has not, and -therefore cannot be used. `std::fmt` has many such [`traits`][traits] and -each requires its own implementation. This is detailed further in -[`std::fmt`][fmt]. +So, `fmt::Display` has been implemented but `fmt::Binary` has not, and therefore +cannot be used. `std::fmt` has many such [`traits`][traits] and each requires +its own implementation. This is detailed further in [`std::fmt`][fmt]. ### Activity diff --git a/src/doc/rust-by-example/src/hello/print/print_display/testcase_list.md b/src/doc/rust-by-example/src/hello/print/print_display/testcase_list.md index 63e400b6a..d07316b72 100644 --- a/src/doc/rust-by-example/src/hello/print/print_display/testcase_list.md +++ b/src/doc/rust-by-example/src/hello/print/print_display/testcase_list.md @@ -52,7 +52,8 @@ fn main() { ### Activity -Try changing the program so that the index of each element in the vector is also printed. The new output should look like this: +Try changing the program so that the index of each element in the vector is also +printed. The new output should look like this: ```rust,ignore [0: 1, 1: 2, 2: 3] diff --git a/src/doc/rust-by-example/src/primitives.md b/src/doc/rust-by-example/src/primitives.md index 6b579e5ea..6560e99e9 100644 --- a/src/doc/rust-by-example/src/primitives.md +++ b/src/doc/rust-by-example/src/primitives.md @@ -2,28 +2,27 @@ Rust provides access to a wide variety of `primitives`. A sample includes: - ### Scalar Types -* signed integers: `i8`, `i16`, `i32`, `i64`, `i128` and `isize` (pointer size) -* unsigned integers: `u8`, `u16`, `u32`, `u64`, `u128` and `usize` (pointer +* Signed integers: `i8`, `i16`, `i32`, `i64`, `i128` and `isize` (pointer size) +* Unsigned integers: `u8`, `u16`, `u32`, `u64`, `u128` and `usize` (pointer size) -* floating point: `f32`, `f64` +* Floating point: `f32`, `f64` * `char` Unicode scalar values like `'a'`, `'α'` and `'∞'` (4 bytes each) * `bool` either `true` or `false` -* and the unit type `()`, whose only possible value is an empty tuple: `()` +* The unit type `()`, whose only possible value is an empty tuple: `()` -Despite the value of a unit type being a tuple, it is not considered a -compound type because it does not contain multiple values. +Despite the value of a unit type being a tuple, it is not considered a compound +type because it does not contain multiple values. ### Compound Types -* arrays like `[1, 2, 3]` -* tuples like `(1, true)` +* Arrays like `[1, 2, 3]` +* Tuples like `(1, true)` -Variables can always be *type annotated*. Numbers may additionally be -annotated via a *suffix* or *by default*. Integers default to `i32` and -floats to `f64`. Note that Rust can also infer types from context. +Variables can always be *type annotated*. Numbers may additionally be annotated +via a *suffix* or *by default*. Integers default to `i32` and floats to `f64`. +Note that Rust can also infer types from context. ```rust,editable,ignore,mdbook-runnable fn main() { @@ -36,18 +35,18 @@ fn main() { // Or a default will be used. let default_float = 3.0; // `f64` let default_integer = 7; // `i32` - - // A type can also be inferred from context - let mut inferred_type = 12; // Type i64 is inferred from another line + + // A type can also be inferred from context. + let mut inferred_type = 12; // Type i64 is inferred from another line. inferred_type = 4294967296i64; - + // A mutable variable's value can be changed. let mut mutable = 12; // Mutable `i32` mutable = 21; - + // Error! The type of a variable can't be changed. mutable = true; - + // Variables can be overwritten with shadowing. let mutable = true; } @@ -55,7 +54,8 @@ fn main() { ### See also: -[the `std` library][std], [`mut`][mut], [`inference`][inference], and [`shadowing`][shadowing] +[the `std` library][std], [`mut`][mut], [`inference`][inference], and +[`shadowing`][shadowing] [std]: https://doc.rust-lang.org/std/ [mut]: variable_bindings/mut.md diff --git a/src/doc/rust-by-example/src/primitives/array.md b/src/doc/rust-by-example/src/primitives/array.md index 0f56182cd..3811bb6d7 100644 --- a/src/doc/rust-by-example/src/primitives/array.md +++ b/src/doc/rust-by-example/src/primitives/array.md @@ -5,66 +5,65 @@ memory. Arrays are created using brackets `[]`, and their length, which is known at compile time, is part of their type signature `[T; length]`. Slices are similar to arrays, but their length is not known at compile time. -Instead, a slice is a two-word object, the first word is a pointer to the data, -and the second word is the length of the slice. The word size is the same as -usize, determined by the processor architecture e.g. 64 bits on an x86-64. -Slices can be used to borrow a section of an array, and have the type signature -`&[T]`. +Instead, a slice is a two-word object; the first word is a pointer to the data, +the second word the length of the slice. The word size is the same as usize, +determined by the processor architecture, e.g. 64 bits on an x86-64. Slices can +be used to borrow a section of an array and have the type signature `&[T]`. ```rust,editable,ignore,mdbook-runnable use std::mem; -// This function borrows a slice +// This function borrows a slice. fn analyze_slice(slice: &[i32]) { - println!("first element of the slice: {}", slice[0]); - println!("the slice has {} elements", slice.len()); + println!("First element of the slice: {}", slice[0]); + println!("The slice has {} elements", slice.len()); } fn main() { - // Fixed-size array (type signature is superfluous) + // Fixed-size array (type signature is superfluous). let xs: [i32; 5] = [1, 2, 3, 4, 5]; - // All elements can be initialized to the same value + // All elements can be initialized to the same value. let ys: [i32; 500] = [0; 500]; - // Indexing starts at 0 - println!("first element of the array: {}", xs[0]); - println!("second element of the array: {}", xs[1]); + // Indexing starts at 0. + println!("First element of the array: {}", xs[0]); + println!("Second element of the array: {}", xs[1]); - // `len` returns the count of elements in the array - println!("number of elements in array: {}", xs.len()); + // `len` returns the count of elements in the array. + println!("Number of elements in array: {}", xs.len()); - // Arrays are stack allocated - println!("array occupies {} bytes", mem::size_of_val(&xs)); + // Arrays are stack allocated. + println!("Array occupies {} bytes", mem::size_of_val(&xs)); - // Arrays can be automatically borrowed as slices - println!("borrow the whole array as a slice"); + // Arrays can be automatically borrowed as slices. + println!("Borrow the whole array as a slice."); analyze_slice(&xs); - // Slices can point to a section of an array - // They are of the form [starting_index..ending_index] - // starting_index is the first position in the slice - // ending_index is one more than the last position in the slice - println!("borrow a section of the array as a slice"); + // Slices can point to a section of an array. + // They are of the form [starting_index..ending_index]. + // `starting_index` is the first position in the slice. + // `ending_index` is one more than the last position in the slice. + println!("Borrow a section of the array as a slice."); analyze_slice(&ys[1 .. 4]); - // Example of empty slice `&[]` + // Example of empty slice `&[]`: let empty_array: [u32; 0] = []; assert_eq!(&empty_array, &[]); - assert_eq!(&empty_array, &[][..]); // same but more verbose + assert_eq!(&empty_array, &[][..]); // Same but more verbose // Arrays can be safely accessed using `.get`, which returns an // `Option`. This can be matched as shown below, or used with // `.expect()` if you would like the program to exit with a nice // message instead of happily continue. - for i in 0..xs.len() + 1 { // OOPS, one element too far + for i in 0..xs.len() + 1 { // Oops, one element too far! match xs.get(i) { Some(xval) => println!("{}: {}", i, xval), None => println!("Slow down! {} is too far!", i), } } - // Out of bound indexing causes runtime error + // Out of bound indexing causes runtime error. //println!("{}", xs[5]); } ``` diff --git a/src/doc/rust-by-example/src/primitives/literals.md b/src/doc/rust-by-example/src/primitives/literals.md index 4927e6af8..dfe4e3a88 100644 --- a/src/doc/rust-by-example/src/primitives/literals.md +++ b/src/doc/rust-by-example/src/primitives/literals.md @@ -9,12 +9,15 @@ notation using these prefixes respectively: `0x`, `0o` or `0b`. Underscores can be inserted in numeric literals to improve readability, e.g. `1_000` is the same as `1000`, and `0.000_001` is the same as `0.000001`. +Rust also supports scientific [E-notation][enote], e.g. `1e6`, `7.6e-4`. The +associated type is `f64`. + We need to tell the compiler the type of the literals we use. For now, we'll use the `u32` suffix to indicate that the literal is an unsigned 32-bit integer, and the `i32` suffix to indicate that it's a signed 32-bit integer. -The operators available and their precedence [in Rust][rust op-prec] are similar to other -[C-like languages][op-prec]. +The operators available and their precedence [in Rust][rust op-prec] are similar +to other [C-like languages][op-prec]. ```rust,editable fn main() { @@ -25,6 +28,9 @@ fn main() { println!("1 - 2 = {}", 1i32 - 2); // TODO ^ Try changing `1i32` to `1u32` to see why the type is important + // Scientific notation + println!("1e4 is {}, -2.5e-3 is {}", 1e4, -2.5e-3); + // Short-circuiting boolean logic println!("true AND false is {}", true && false); println!("true OR false is {}", true || false); @@ -42,5 +48,6 @@ fn main() { } ``` +[enote]: https://en.wikipedia.org/wiki/Scientific_notation#E_notation [rust op-prec]: https://doc.rust-lang.org/reference/expressions.html#expression-precedence [op-prec]: https://en.wikipedia.org/wiki/Operator_precedence#Programming_languages diff --git a/src/doc/rust-by-example/src/primitives/tuples.md b/src/doc/rust-by-example/src/primitives/tuples.md index f4b59c04b..e745d89be 100644 --- a/src/doc/rust-by-example/src/primitives/tuples.md +++ b/src/doc/rust-by-example/src/primitives/tuples.md @@ -6,9 +6,9 @@ using parentheses `()`, and each tuple itself is a value with type signature use tuples to return multiple values, as tuples can hold any number of values. ```rust,editable -// Tuples can be used as function arguments and as return values +// Tuples can be used as function arguments and as return values. fn reverse(pair: (i32, bool)) -> (bool, i32) { - // `let` can be used to bind the members of a tuple to variables + // `let` can be used to bind the members of a tuple to variables. let (int_param, bool_param) = pair; (bool_param, int_param) @@ -19,38 +19,38 @@ fn reverse(pair: (i32, bool)) -> (bool, i32) { struct Matrix(f32, f32, f32, f32); fn main() { - // A tuple with a bunch of different types + // A tuple with a bunch of different types. let long_tuple = (1u8, 2u16, 3u32, 4u64, -1i8, -2i16, -3i32, -4i64, 0.1f32, 0.2f64, 'a', true); - // Values can be extracted from the tuple using tuple indexing - println!("long tuple first value: {}", long_tuple.0); - println!("long tuple second value: {}", long_tuple.1); + // Values can be extracted from the tuple using tuple indexing. + println!("Long tuple first value: {}", long_tuple.0); + println!("Long tuple second value: {}", long_tuple.1); - // Tuples can be tuple members + // Tuples can be tuple members. let tuple_of_tuples = ((1u8, 2u16, 2u32), (4u64, -1i8), -2i16); - // Tuples are printable + // Tuples are printable. println!("tuple of tuples: {:?}", tuple_of_tuples); - - // But long Tuples (more than 12 elements) cannot be printed - // let too_long_tuple = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13); - // println!("too long tuple: {:?}", too_long_tuple); + + // But long Tuples (more than 12 elements) cannot be printed. + //let too_long_tuple = (1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13); + //println!("Too long tuple: {:?}", too_long_tuple); // TODO ^ Uncomment the above 2 lines to see the compiler error let pair = (1, true); - println!("pair is {:?}", pair); + println!("Pair is {:?}", pair); - println!("the reversed pair is {:?}", reverse(pair)); + println!("Uhe reversed pair is {:?}", reverse(pair)); // To create one element tuples, the comma is required to tell them apart - // from a literal surrounded by parentheses - println!("one element tuple: {:?}", (5u32,)); - println!("just an integer: {:?}", (5u32)); + // from a literal surrounded by parentheses. + println!("One element tuple: {:?}", (5u32,)); + println!("Just an integer: {:?}", (5u32)); - //tuples can be destructured to create bindings + // Tuples can be destructured to create bindings. let tuple = (1, "hello", 4.5, true); let (a, b, c, d) = tuple; @@ -58,40 +58,39 @@ fn main() { let matrix = Matrix(1.1, 1.2, 2.1, 2.2); println!("{:?}", matrix); - } ``` ### Activity - 1. *Recap*: Add the `fmt::Display` trait to the `Matrix` struct in the above example, - so that if you switch from printing the debug format `{:?}` to the display - format `{}`, you see the following output: - - ```text - ( 1.1 1.2 ) - ( 2.1 2.2 ) - ``` - - You may want to refer back to the example for [print display][print_display]. - 2. Add a `transpose` function using the `reverse` function as a template, which - accepts a matrix as an argument, and returns a matrix in which two elements - have been swapped. For example: - - ```rust,ignore - println!("Matrix:\n{}", matrix); - println!("Transpose:\n{}", transpose(matrix)); - ``` - - results in the output: - - ```text - Matrix: - ( 1.1 1.2 ) - ( 2.1 2.2 ) - Transpose: - ( 1.1 2.1 ) - ( 1.2 2.2 ) - ``` +1. *Recap*: Add the `fmt::Display` trait to the `Matrix` struct in the above + example, so that if you switch from printing the debug format `{:?}` to the + display format `{}`, you see the following output: + + ```text + ( 1.1 1.2 ) + ( 2.1 2.2 ) + ``` + + You may want to refer back to the example for [print display][print_display]. +2. Add a `transpose` function using the `reverse` function as a template, which + accepts a matrix as an argument, and returns a matrix in which two elements + have been swapped. For example: + + ```rust,ignore + println!("Matrix:\n{}", matrix); + println!("Transpose:\n{}", transpose(matrix)); + ``` + + Results in the output: + + ```text + Matrix: + ( 1.1 1.2 ) + ( 2.1 2.2 ) + Transpose: + ( 1.1 2.1 ) + ( 1.2 2.2 ) + ``` [print_display]: ../hello/print/print_display.md diff --git a/src/doc/rust-by-example/src/types/alias.md b/src/doc/rust-by-example/src/types/alias.md index 1d004587c..a2e02ac1a 100644 --- a/src/doc/rust-by-example/src/types/alias.md +++ b/src/doc/rust-by-example/src/types/alias.md @@ -24,8 +24,8 @@ fn main() { } ``` -The main use of aliases is to reduce boilerplate; for example the `IoResult` type -is an alias for the `Result` type. +The main use of aliases is to reduce boilerplate; for example the `io::Result` type +is an alias for the `Result` type. ### See also: -- cgit v1.2.3