diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 64ab49c515..65574a070e 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -12,8 +12,8 @@ jobs: - name: Install Rust run: | rustup set profile minimal - rustup toolchain install 1.65 -c rust-docs - rustup default 1.65 + rustup toolchain install 1.67 -c rust-docs + rustup default 1.67 - name: Install mdbook run: | mkdir bin diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3c9500687d..a20cb58501 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -38,11 +38,13 @@ that governs all sub-projects, including this one. Please respect it! ## Expectations -Because the book is [printed](https://nostarch.com/rust), and because we want +Because the book is [printed][nostarch], and because we want to keep the online version of the book close to the print version when possible, it may take longer than you're used to for us to address your issue or pull request. +[nostarch]: https://nostarch.com/rust-programming-language-2nd-edition + So far, we've been doing a larger revision to coincide with [Rust Editions](https://doc.rust-lang.org/edition-guide/). Between those larger revisions, we will only be correcting errors. If your issue or pull request @@ -68,4 +70,4 @@ a new language! We're waiting on [mdbook support] for multiple languages before we merge any in, but feel free to start! [Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations -[mdbook support]: https://github.com/rust-lang-nursery/mdBook/issues/5 +[mdbook support]: https://github.com/rust-lang/mdBook/issues/5 diff --git a/COPYRIGHT b/COPYRIGHT index dfe614df93..0fc3ea43fe 100644 --- a/COPYRIGHT +++ b/COPYRIGHT @@ -1,290 +1,3 @@ -Short version for non-lawyers: - -The Rust Project is dual-licensed under Apache 2.0 and MIT -terms. - - -Longer version: - -The Rust Project is copyright 2010, The Rust Project -Developers. - -Licensed under the Apache License, Version 2.0 - or the MIT -license , -at your option. All files in the project carrying such -notice may not be copied, modified, or distributed except -according to those terms. - - -The Rust Project includes packages written by third parties. -The following third party packages are included, and carry -their own copyright notices and license terms: - -* The src/rt/miniz.c file, carrying an implementation of - RFC1950/RFC1951 DEFLATE, by Rich Geldreich - . All uses of this file are - permitted by the embedded "unlicense" notice - (effectively: public domain with warranty disclaimer). - -* LLVM. Code for this package is found in src/llvm. - - Copyright (c) 2003-2013 University of Illinois at - Urbana-Champaign. All rights reserved. - - Developed by: - - LLVM Team - - University of Illinois at Urbana-Champaign - - https://llvm.org - - Permission is hereby granted, free of charge, to any - person obtaining a copy of this software and associated - documentation files (the "Software"), to deal with the - Software without restriction, including without - limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of - the Software, and to permit persons to whom the Software - is furnished to do so, subject to the following - conditions: - - * Redistributions of source code must retain the - above copyright notice, this list of conditions - and the following disclaimers. - - * Redistributions in binary form must reproduce the - above copyright notice, this list of conditions - and the following disclaimers in the documentation - and/or other materials provided with the - distribution. - - * Neither the names of the LLVM Team, University of - Illinois at Urbana-Champaign, nor the names of its - contributors may be used to endorse or promote - products derived from this Software without - specific prior written permission. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF - ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED - TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT - SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE - FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT - OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - OTHER DEALINGS WITH THE SOFTWARE. - -* Additional libraries included in LLVM carry separate - BSD-compatible licenses. See src/llvm/LICENSE.txt for - details. - -* compiler-rt, in src/compiler-rt is dual licensed under - LLVM's license and MIT: - - Copyright (c) 2009-2014 by the contributors listed in - CREDITS.TXT - - All rights reserved. - - Developed by: - - LLVM Team - - University of Illinois at Urbana-Champaign - - https://llvm.org - - Permission is hereby granted, free of charge, to any - person obtaining a copy of this software and associated - documentation files (the "Software"), to deal with the - Software without restriction, including without - limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of - the Software, and to permit persons to whom the Software - is furnished to do so, subject to the following - conditions: - - * Redistributions of source code must retain the - above copyright notice, this list of conditions - and the following disclaimers. - - * Redistributions in binary form must reproduce the - above copyright notice, this list of conditions - and the following disclaimers in the documentation - and/or other materials provided with the - distribution. - - * Neither the names of the LLVM Team, University of - Illinois at Urbana-Champaign, nor the names of its - contributors may be used to endorse or promote - products derived from this Software without - specific prior written permission. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF - ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED - TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT - SHALL THE CONTRIBUTORS OR COPYRIGHT HOLDERS BE LIABLE - FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN - ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT - OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR - OTHER DEALINGS WITH THE SOFTWARE. - - ======================================================== - - Copyright (c) 2009-2014 by the contributors listed in - CREDITS.TXT - - Permission is hereby granted, free of charge, to any - person obtaining a copy of this software and associated - documentation files (the "Software"), to deal in the - Software without restriction, including without - limitation the rights to use, copy, modify, merge, - publish, distribute, sublicense, and/or sell copies of - the Software, and to permit persons to whom the Software - is furnished to do so, subject to the following - conditions: - - The above copyright notice and this permission notice - shall be included in all copies or substantial portions - of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF - ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED - TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A - PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT - SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY - CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION - OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR - IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER - DEALINGS IN THE SOFTWARE. - -* Portions of the FFI code for interacting with the native ABI - is derived from the Clay programming language, which carries - the following license. - - Copyright (C) 2008-2010 Tachyon Technologies. - All rights reserved. - - Redistribution and use in source and binary forms, with - or without modification, are permitted provided that the - following conditions are met: - - 1. Redistributions of source code must retain the above - copyright notice, this list of conditions and the - following disclaimer. - - 2. Redistributions in binary form must reproduce the - above copyright notice, this list of conditions and - the following disclaimer in the documentation and/or - other materials provided with the distribution. - - THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR - IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE - IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A - PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE - DEVELOPERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE - USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY - OF SUCH DAMAGE. - -* libbacktrace, under src/libbacktrace: - - Copyright (C) 2012-2014 Free Software Foundation, Inc. - Written by Ian Lance Taylor, Google. - - Redistribution and use in source and binary forms, with - or without modification, are permitted provided that the - following conditions are met: - - (1) Redistributions of source code must retain the - above copyright notice, this list of conditions and - the following disclaimer. - - (2) Redistributions in binary form must reproduce - the above copyright notice, this list of conditions - and the following disclaimer in the documentation - and/or other materials provided with the - distribution. - - (3) The name of the author may not be used to - endorse or promote products derived from this - software without specific prior written permission. - - THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND - ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT - LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY - AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN - NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, - INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR - CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, - PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF - USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER - CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN - CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE - USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY - OF SUCH DAMAGE. */ - -* jemalloc, under src/jemalloc: - - Copyright (C) 2002-2014 Jason Evans - . All rights reserved. - Copyright (C) 2007-2012 Mozilla Foundation. - All rights reserved. - Copyright (C) 2009-2014 Facebook, Inc. - All rights reserved. - - Redistribution and use in source and binary forms, with or without - modification, are permitted provided that the following conditions are met: - 1. Redistributions of source code must retain the above copyright notice(s), - this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright notice(s), - this list of conditions and the following disclaimer in the documentation - and/or other materials provided with the distribution. - - THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) - ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, - INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF - MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE - DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) - BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, - EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT - LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; - LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) - HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER - IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING - NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE - USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY - OF SUCH DAMAGE. - -* Additional copyright may be retained by contributors other - than Mozilla, the Rust Project Developers, or the parties - enumerated in this file. Such copyright can be determined - on a case-by-case basis by examining the author of each - portion of a file in the revision-control commit records - of the project, or by consulting representative comments - claiming copyright ownership for a file. - - For example, the text: - - "Copyright (c) 2011 Google Inc." - - appears in some files, and these files thereby denote - that their author and copyright-holder is Google Inc. - - In all such cases, the absence of explicit licensing text - indicates that the contributor chose to license their work - for distribution under identical terms to those Mozilla - has chosen for the collective work, enumerated at the top - of this file. The only difference is the retention of - copyright itself, held by the contributor. +This repository is licensed under the Apache License, Version 2.0 + or the MIT +license , at your option. diff --git a/LICENSE-APACHE b/LICENSE-APACHE index 16fe87b06e..38634daab0 100644 --- a/LICENSE-APACHE +++ b/LICENSE-APACHE @@ -186,7 +186,7 @@ APPENDIX: How to apply the Apache License to your work. same "printed page" as the copyright notice for easier identification within third-party archives. -Copyright [yyyy] [name of copyright owner] +Copyright 2010 The Rust Project Developers Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.md b/README.md index daa39f7441..c70c85e727 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,32 @@ -## Changes +# The Rust Programming Language -The original documentation is filled with fluff, this is a shorthand edit -I created for personal use. +![Build Status](https://github.com/rust-lang/book/workflows/CI/badge.svg) + +This repository contains the source of "The Rust Programming Language" book. + +[The book is available in dead-tree form from No Starch Press][nostarch]. + +[nostarch]: https://nostarch.com/rust-programming-language-2nd-edition + +You can also read the book for free online. Please see the book as shipped with +the latest [stable], [beta], or [nightly] Rust releases. Be aware that issues +in those versions may have been fixed in this repository already, as those +releases are updated less frequently. + +[stable]: https://doc.rust-lang.org/stable/book/ +[beta]: https://doc.rust-lang.org/beta/book/ +[nightly]: https://doc.rust-lang.org/nightly/book/ + +See the [releases] to download just the code of all the code listings that appear in the book. + +[releases]: https://github.com/rust-lang/book/releases ## Requirements Building the book requires [mdBook], ideally the same version that rust-lang/rust uses in [this file][rust-mdbook]. To get it: -[mdBook]: https://github.com/rust-lang-nursery/mdBook +[mdBook]: https://github.com/rust-lang/mdBook [rust-mdbook]: https://github.com/rust-lang/rust/blob/master/src/tools/rustbook/Cargo.toml ```bash @@ -26,13 +44,62 @@ $ mdbook build The output will be in the `book` subdirectory. To check it out, open it in your web browser. +_Firefox:_ +```bash +$ firefox book/index.html # Linux +$ open -a "Firefox" book/index.html # OS X +$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell) +$ start firefox.exe .\book\index.html # Windows (Cmd) +``` + +_Chrome:_ +```bash +$ google-chrome book/index.html # Linux +$ open -a "Google Chrome" book/index.html # OS X +$ Start-Process "chrome.exe" .\book\index.html # Windows (PowerShell) +$ start chrome.exe .\book\index.html # Windows (Cmd) +``` + +To run the tests: + +```bash +$ mdbook test +``` + +## Contributing + +We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the +kinds of contributions we're looking for. + +[contrib]: https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md + +Because the book is [printed][nostarch], and because we want +to keep the online version of the book close to the print version when +possible, it may take longer than you're used to for us to address your issue +or pull request. + +So far, we've been doing a larger revision to coincide with [Rust +Editions](https://doc.rust-lang.org/edition-guide/). Between those larger +revisions, we will only be correcting errors. If your issue or pull request +isn't strictly fixing an error, it might sit until the next time that we're +working on a large revision: expect on the order of months or years. Thank you +for your patience! + +### Translations + +We'd love help translating the book! See the [Translations] label to join in +efforts that are currently in progress. Open a new issue to start working on +a new language! We're waiting on [mdbook support] for multiple languages +before we merge any in, but feel free to start! + +[Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations +[mdbook support]: https://github.com/rust-lang/mdBook/issues/5 + ## Spellchecking To scan source files for spelling errors, you can use the `spellcheck.sh` script available in the `ci` directory. It needs a dictionary of valid words, -which is provided in `ci/dictionary.txt`. - -## Contribution - -If you'd like to support this rewrite, remove any unnecessary details or rhetoric -in the documentation. +which is provided in `ci/dictionary.txt`. If the script produces a false +positive (say, you used word `BTreeMap` which the script considers invalid), +you need to add this word to `ci/dictionary.txt` (keep the sorted order for +consistency). diff --git a/ci/dictionary.txt b/ci/dictionary.txt index 9eb695d5b3..a91df4a036 100644 --- a/ci/dictionary.txt +++ b/ci/dictionary.txt @@ -546,6 +546,7 @@ unsafety unsized unsynchronized Unyank +UpperCamelCase URIs UsefulType username diff --git a/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt b/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt index 70a0c930c2..3640c06946 100644 --- a/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt +++ b/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt @@ -18,6 +18,7 @@ error[E0308]: mismatched types = note: expected reference `&String` found reference `&{integer}` note: associated function defined here + --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/cmp.rs:783:8 For more information about this error, try `rustc --explain E0308`. error: could not compile `guessing_game` due to previous error diff --git a/listings/ch02-guessing-game-tutorial/no-listing-02-without-expect/output.txt b/listings/ch02-guessing-game-tutorial/no-listing-02-without-expect/output.txt index 8095bbd8db..9517af95f0 100644 --- a/listings/ch02-guessing-game-tutorial/no-listing-02-without-expect/output.txt +++ b/listings/ch02-guessing-game-tutorial/no-listing-02-without-expect/output.txt @@ -4,10 +4,10 @@ warning: unused `Result` that must be used --> src/main.rs:10:5 | 10 | io::stdin().read_line(&mut guess); - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | - = note: `#[warn(unused_must_use)]` on by default = note: this `Result` may be an `Err` variant, which should be handled + = note: `#[warn(unused_must_use)]` on by default warning: `guessing_game` (bin "guessing_game") generated 1 warning Finished dev [unoptimized + debuginfo] target(s) in 0.59s diff --git a/listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt b/listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt index c0484ea1b4..d27a7fae28 100644 --- a/listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt +++ b/listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt @@ -8,7 +8,7 @@ error[E0308]: mismatched types | | | implicitly returns `()` as its body has no tail or `return` expression 8 | x + 1; - | - help: remove this semicolon + | - help: remove this semicolon to return this value For more information about this error, try `rustc --explain E0308`. error: could not compile `functions` due to previous error diff --git a/listings/ch04-understanding-ownership/no-listing-04-cant-use-after-move/output.txt b/listings/ch04-understanding-ownership/no-listing-04-cant-use-after-move/output.txt index 05987f7c8d..4a53567018 100644 --- a/listings/ch04-understanding-ownership/no-listing-04-cant-use-after-move/output.txt +++ b/listings/ch04-understanding-ownership/no-listing-04-cant-use-after-move/output.txt @@ -12,6 +12,10 @@ error[E0382]: borrow of moved value: `s1` | ^^ value borrowed here after move | = note: this error originates in the macro `$crate::format_args_nl` which comes from the expansion of the macro `println` (in Nightly builds, run with -Z macro-backtrace for more info) +help: consider cloning the value if the performance cost is acceptable + | +3 | let s2 = s1.clone(); + | ++++++++ For more information about this error, try `rustc --explain E0382`. error: could not compile `ownership` due to previous error diff --git a/listings/ch06-enums-and-pattern-matching/no-listing-07-cant-use-option-directly/output.txt b/listings/ch06-enums-and-pattern-matching/no-listing-07-cant-use-option-directly/output.txt index d4a040e8eb..a16dc01807 100644 --- a/listings/ch06-enums-and-pattern-matching/no-listing-07-cant-use-option-directly/output.txt +++ b/listings/ch06-enums-and-pattern-matching/no-listing-07-cant-use-option-directly/output.txt @@ -8,15 +8,10 @@ error[E0277]: cannot add `Option` to `i8` | = help: the trait `Add>` is not implemented for `i8` = help: the following other types implement trait `Add`: - <&'a f32 as Add> - <&'a f64 as Add> - <&'a i128 as Add> - <&'a i16 as Add> - <&'a i32 as Add> - <&'a i64 as Add> <&'a i8 as Add> - <&'a isize as Add> - and 48 others + <&i8 as Add<&i8>> + > + For more information about this error, try `rustc --explain E0277`. error: could not compile `enums` due to previous error diff --git a/listings/ch06-enums-and-pattern-matching/no-listing-10-non-exhaustive-match/output.txt b/listings/ch06-enums-and-pattern-matching/no-listing-10-non-exhaustive-match/output.txt index bec72849aa..75d056f843 100644 --- a/listings/ch06-enums-and-pattern-matching/no-listing-10-non-exhaustive-match/output.txt +++ b/listings/ch06-enums-and-pattern-matching/no-listing-10-non-exhaustive-match/output.txt @@ -7,6 +7,10 @@ error[E0004]: non-exhaustive patterns: `None` not covered | ^ pattern `None` not covered | note: `Option` defined here + --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/option.rs:518:1 + | + = note: +/rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/option.rs:522:5: not covered = note: the matched value is of type `Option` help: ensure that all possible cases are being handled by adding a match arm with a wildcard pattern or an explicit pattern as shown | diff --git a/listings/ch07-managing-growing-projects/listing-07-12/output.txt b/listings/ch07-managing-growing-projects/listing-07-12/output.txt index 39b6505401..1bc89bf322 100644 --- a/listings/ch07-managing-growing-projects/listing-07-12/output.txt +++ b/listings/ch07-managing-growing-projects/listing-07-12/output.txt @@ -1,11 +1,5 @@ $ cargo build Compiling restaurant v0.1.0 (file:///projects/restaurant) -error[E0433]: failed to resolve: use of undeclared crate or module `hosting` - --> src/lib.rs:11:9 - | -11 | hosting::add_to_waitlist(); - | ^^^^^^^ use of undeclared crate or module `hosting` - warning: unused import: `crate::front_of_house::hosting` --> src/lib.rs:7:5 | @@ -14,6 +8,12 @@ warning: unused import: `crate::front_of_house::hosting` | = note: `#[warn(unused_imports)]` on by default +error[E0433]: failed to resolve: use of undeclared crate or module `hosting` + --> src/lib.rs:11:9 + | +11 | hosting::add_to_waitlist(); + | ^^^^^^^ use of undeclared crate or module `hosting` + For more information about this error, try `rustc --explain E0433`. warning: `restaurant` (lib) generated 1 warning error: could not compile `restaurant` due to previous error; 1 warning emitted diff --git a/listings/ch08-common-collections/listing-08-19/output.txt b/listings/ch08-common-collections/listing-08-19/output.txt index 95577772e1..3a682457c6 100644 --- a/listings/ch08-common-collections/listing-08-19/output.txt +++ b/listings/ch08-common-collections/listing-08-19/output.txt @@ -14,7 +14,6 @@ error[E0277]: the type `String` cannot be indexed by `{integer}` >> >> >> - > For more information about this error, try `rustc --explain E0277`. error: could not compile `collections` due to previous error diff --git a/listings/ch11-writing-automated-tests/listing-11-03/output.txt b/listings/ch11-writing-automated-tests/listing-11-03/output.txt index 2fa5cf0774..e8c31e79ec 100644 --- a/listings/ch11-writing-automated-tests/listing-11-03/output.txt +++ b/listings/ch11-writing-automated-tests/listing-11-03/output.txt @@ -10,7 +10,7 @@ test tests::exploration ... ok failures: ---- tests::another stdout ---- -thread 'main' panicked at 'Make this test fail', src/lib.rs:10:9 +thread 'tests::another' panicked at 'Make this test fail', src/lib.rs:10:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch11-writing-automated-tests/listing-11-10/output.txt b/listings/ch11-writing-automated-tests/listing-11-10/output.txt index 681cfbb81a..b0d10deaa8 100644 --- a/listings/ch11-writing-automated-tests/listing-11-10/output.txt +++ b/listings/ch11-writing-automated-tests/listing-11-10/output.txt @@ -11,7 +11,7 @@ failures: ---- tests::this_test_will_fail stdout ---- I got the value 8 -thread 'main' panicked at 'assertion failed: `(left == right)` +thread 'tests::this_test_will_fail' panicked at 'assertion failed: `(left == right)` left: `5`, right: `10`', src/lib.rs:19:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch11-writing-automated-tests/no-listing-03-introducing-a-bug/output.txt b/listings/ch11-writing-automated-tests/no-listing-03-introducing-a-bug/output.txt index 7c62822f76..6fbb5e4966 100644 --- a/listings/ch11-writing-automated-tests/no-listing-03-introducing-a-bug/output.txt +++ b/listings/ch11-writing-automated-tests/no-listing-03-introducing-a-bug/output.txt @@ -10,7 +10,7 @@ test tests::smaller_cannot_hold_larger ... ok failures: ---- tests::larger_can_hold_smaller stdout ---- -thread 'main' panicked at 'assertion failed: larger.can_hold(&smaller)', src/lib.rs:28:9 +thread 'tests::larger_can_hold_smaller' panicked at 'assertion failed: larger.can_hold(&smaller)', src/lib.rs:28:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch11-writing-automated-tests/no-listing-04-bug-in-add-two/output.txt b/listings/ch11-writing-automated-tests/no-listing-04-bug-in-add-two/output.txt index 28e2414bef..00bf63fff6 100644 --- a/listings/ch11-writing-automated-tests/no-listing-04-bug-in-add-two/output.txt +++ b/listings/ch11-writing-automated-tests/no-listing-04-bug-in-add-two/output.txt @@ -9,7 +9,7 @@ test tests::it_adds_two ... FAILED failures: ---- tests::it_adds_two stdout ---- -thread 'main' panicked at 'assertion failed: `(left == right)` +thread 'tests::it_adds_two' panicked at 'assertion failed: `(left == right)` left: `4`, right: `5`', src/lib.rs:11:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch11-writing-automated-tests/no-listing-06-greeter-with-bug/output.txt b/listings/ch11-writing-automated-tests/no-listing-06-greeter-with-bug/output.txt index 3366e3ace7..68d724f118 100644 --- a/listings/ch11-writing-automated-tests/no-listing-06-greeter-with-bug/output.txt +++ b/listings/ch11-writing-automated-tests/no-listing-06-greeter-with-bug/output.txt @@ -9,7 +9,7 @@ test tests::greeting_contains_name ... FAILED failures: ---- tests::greeting_contains_name stdout ---- -thread 'main' panicked at 'assertion failed: result.contains(\"Carol\")', src/lib.rs:12:9 +thread 'tests::greeting_contains_name' panicked at 'assertion failed: result.contains(\"Carol\")', src/lib.rs:12:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch11-writing-automated-tests/no-listing-07-custom-failure-message/output.txt b/listings/ch11-writing-automated-tests/no-listing-07-custom-failure-message/output.txt index cebebdaee9..03d6ad7f13 100644 --- a/listings/ch11-writing-automated-tests/no-listing-07-custom-failure-message/output.txt +++ b/listings/ch11-writing-automated-tests/no-listing-07-custom-failure-message/output.txt @@ -9,7 +9,7 @@ test tests::greeting_contains_name ... FAILED failures: ---- tests::greeting_contains_name stdout ---- -thread 'main' panicked at 'Greeting did not contain name, value was `Hello!`', src/lib.rs:12:9 +thread 'tests::greeting_contains_name' panicked at 'Greeting did not contain name, value was `Hello!`', src/lib.rs:12:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch11-writing-automated-tests/no-listing-09-guess-with-panic-msg-bug/output.txt b/listings/ch11-writing-automated-tests/no-listing-09-guess-with-panic-msg-bug/output.txt index c176e88b88..0b045e8be9 100644 --- a/listings/ch11-writing-automated-tests/no-listing-09-guess-with-panic-msg-bug/output.txt +++ b/listings/ch11-writing-automated-tests/no-listing-09-guess-with-panic-msg-bug/output.txt @@ -9,7 +9,7 @@ test tests::greater_than_100 - should panic ... FAILED failures: ---- tests::greater_than_100 stdout ---- -thread 'main' panicked at 'Guess value must be greater than or equal to 1, got 200.', src/lib.rs:13:13 +thread 'tests::greater_than_100' panicked at 'Guess value must be greater than or equal to 1, got 200.', src/lib.rs:13:13 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace note: panic did not contain expected string panic message: `"Guess value must be greater than or equal to 1, got 200."`, diff --git a/listings/ch11-writing-automated-tests/output-only-01-show-output/output.txt b/listings/ch11-writing-automated-tests/output-only-01-show-output/output.txt index 4ececf245c..bc03145a18 100644 --- a/listings/ch11-writing-automated-tests/output-only-01-show-output/output.txt +++ b/listings/ch11-writing-automated-tests/output-only-01-show-output/output.txt @@ -20,7 +20,7 @@ failures: ---- tests::this_test_will_fail stdout ---- I got the value 8 -thread 'main' panicked at 'assertion failed: `(left == right)` +thread 'tests::this_test_will_fail' panicked at 'assertion failed: `(left == right)` left: `5`, right: `10`', src/lib.rs:19:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch12-an-io-project/listing-12-12/output.txt b/listings/ch12-an-io-project/listing-12-12/output.txt index c18902518e..9870b21255 100644 --- a/listings/ch12-an-io-project/listing-12-12/output.txt +++ b/listings/ch12-an-io-project/listing-12-12/output.txt @@ -4,10 +4,10 @@ warning: unused `Result` that must be used --> src/main.rs:19:5 | 19 | run(config); - | ^^^^^^^^^^^^ + | ^^^^^^^^^^^ | - = note: `#[warn(unused_must_use)]` on by default = note: this `Result` may be an `Err` variant, which should be handled + = note: `#[warn(unused_must_use)]` on by default warning: `minigrep` (bin "minigrep") generated 1 warning Finished dev [unoptimized + debuginfo] target(s) in 0.71s diff --git a/listings/ch12-an-io-project/listing-12-16/output.txt b/listings/ch12-an-io-project/listing-12-16/output.txt index 3c34e39454..be4a97eea2 100644 --- a/listings/ch12-an-io-project/listing-12-16/output.txt +++ b/listings/ch12-an-io-project/listing-12-16/output.txt @@ -9,7 +9,7 @@ test tests::one_result ... FAILED failures: ---- tests::one_result stdout ---- -thread 'main' panicked at 'assertion failed: `(left == right)` +thread 'tests::one_result' panicked at 'assertion failed: `(left == right)` left: `["safe, fast, productive."]`, right: `[]`', src/lib.rs:44:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch13-functional-features/listing-13-14/output.txt b/listings/ch13-functional-features/listing-13-14/output.txt index 228c764ed2..9930379910 100644 --- a/listings/ch13-functional-features/listing-13-14/output.txt +++ b/listings/ch13-functional-features/listing-13-14/output.txt @@ -4,10 +4,10 @@ warning: unused `Map` that must be used --> src/main.rs:4:5 | 4 | v1.iter().map(|x| x + 1); - | ^^^^^^^^^^^^^^^^^^^^^^^^^ + | ^^^^^^^^^^^^^^^^^^^^^^^^ | - = note: `#[warn(unused_must_use)]` on by default = note: iterators are lazy and do nothing unless consumed + = note: `#[warn(unused_must_use)]` on by default warning: `iterators` (bin "iterators") generated 1 warning Finished dev [unoptimized + debuginfo] target(s) in 0.47s diff --git a/listings/ch15-smart-pointers/listing-15-03/output.txt b/listings/ch15-smart-pointers/listing-15-03/output.txt index d5522cd533..04b6976fed 100644 --- a/listings/ch15-smart-pointers/listing-15-03/output.txt +++ b/listings/ch15-smart-pointers/listing-15-03/output.txt @@ -4,11 +4,11 @@ error[E0072]: recursive type `List` has infinite size --> src/main.rs:1:1 | 1 | enum List { - | ^^^^^^^^^ recursive type has infinite size + | ^^^^^^^^^ 2 | Cons(i32, List), | ---- recursive without indirection | -help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to make `List` representable +help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to break the cycle | 2 | Cons(i32, Box), | ++++ + diff --git a/listings/ch15-smart-pointers/listing-15-23/output.txt b/listings/ch15-smart-pointers/listing-15-23/output.txt index 3749c845cb..0ffabf7650 100644 --- a/listings/ch15-smart-pointers/listing-15-23/output.txt +++ b/listings/ch15-smart-pointers/listing-15-23/output.txt @@ -9,7 +9,7 @@ test tests::it_sends_an_over_75_percent_warning_message ... FAILED failures: ---- tests::it_sends_an_over_75_percent_warning_message stdout ---- -thread 'main' panicked at 'already borrowed: BorrowMutError', src/lib.rs:60:53 +thread 'tests::it_sends_an_over_75_percent_warning_message' panicked at 'already borrowed: BorrowMutError', src/lib.rs:60:53 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace diff --git a/listings/ch16-fearless-concurrency/listing-16-14/output.txt b/listings/ch16-fearless-concurrency/listing-16-14/output.txt index 0634b86e52..e8cf21a736 100644 --- a/listings/ch16-fearless-concurrency/listing-16-14/output.txt +++ b/listings/ch16-fearless-concurrency/listing-16-14/output.txt @@ -22,6 +22,9 @@ note: required because it's used within this closure 11 | let handle = thread::spawn(move || { | ^^^^^^^ note: required by a bound in `spawn` + --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/thread/mod.rs:704:8 + | + = note: required by this bound in `spawn` For more information about this error, try `rustc --explain E0277`. error: could not compile `shared-state` due to previous error diff --git a/listings/ch18-patterns-and-matching/listing-18-08/output.txt b/listings/ch18-patterns-and-matching/listing-18-08/output.txt index 0fd5373b82..52efabb5c1 100644 --- a/listings/ch18-patterns-and-matching/listing-18-08/output.txt +++ b/listings/ch18-patterns-and-matching/listing-18-08/output.txt @@ -9,11 +9,19 @@ error[E0005]: refutable pattern in local binding: `None` not covered = note: `let` bindings require an "irrefutable pattern", like a `struct` or an `enum` with only one variant = note: for more information, visit https://doc.rust-lang.org/book/ch18-02-refutability.html note: `Option` defined here + --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/option.rs:518:1 + | + = note: +/rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/core/src/option.rs:522:5: not covered = note: the matched value is of type `Option` help: you might want to use `if let` to ignore the variant that isn't matched | 3 | let x = if let Some(x) = some_option_value { x } else { todo!() }; | ++++++++++ ++++++++++++++++++++++ +help: alternatively, you might want to use let else to handle the variant that isn't matched + | +3 | let Some(x) = some_option_value else { todo!() }; + | ++++++++++++++++ For more information about this error, try `rustc --explain E0005`. error: could not compile `patterns` due to previous error diff --git a/listings/ch18-patterns-and-matching/listing-18-10/output.txt b/listings/ch18-patterns-and-matching/listing-18-10/output.txt index 702d10a23f..6488fb29ca 100644 --- a/listings/ch18-patterns-and-matching/listing-18-10/output.txt +++ b/listings/ch18-patterns-and-matching/listing-18-10/output.txt @@ -6,9 +6,9 @@ warning: irrefutable `if let` pattern 2 | if let x = 5 { | ^^^^^^^^^ | - = note: `#[warn(irrefutable_let_patterns)]` on by default = note: this pattern will always match, so the `if let` is useless = help: consider replacing the `if let` with a `let` + = note: `#[warn(irrefutable_let_patterns)]` on by default warning: `patterns` (bin "patterns") generated 1 warning Finished dev [unoptimized + debuginfo] target(s) in 0.39s diff --git a/listings/ch19-advanced-features/listing-19-20/output.txt b/listings/ch19-advanced-features/listing-19-20/output.txt index a3b281e3fc..5942876044 100644 --- a/listings/ch19-advanced-features/listing-19-20/output.txt +++ b/listings/ch19-advanced-features/listing-19-20/output.txt @@ -11,8 +11,8 @@ error[E0790]: cannot call associated function on trait without specifying the co | help: use the fully-qualified path to the only available implementation | -20 | println!("A baby dog is called a {}", <::Dog as Animal>::baby_name()); - | +++++++++ + +20 | println!("A baby dog is called a {}", ::baby_name()); + | +++++++ + For more information about this error, try `rustc --explain E0790`. error: could not compile `traits-example` due to previous error diff --git a/listings/ch20-web-server/listing-20-22/output.txt b/listings/ch20-web-server/listing-20-22/output.txt index a6c9e8d3b3..342bf9a16d 100644 --- a/listings/ch20-web-server/listing-20-22/output.txt +++ b/listings/ch20-web-server/listing-20-22/output.txt @@ -9,6 +9,7 @@ error[E0507]: cannot move out of `worker.thread` which is behind a mutable refer | move occurs because `worker.thread` has type `JoinHandle<()>`, which does not implement the `Copy` trait | note: this function takes ownership of the receiver `self`, which moves `worker.thread` + --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/thread/mod.rs:1581:17 For more information about this error, try `rustc --explain E0507`. error: could not compile `hello` due to previous error diff --git a/listings/ch20-web-server/no-listing-04-update-worker-definition/output.txt b/listings/ch20-web-server/no-listing-04-update-worker-definition/output.txt index e4c0eeb2aa..fec2377dc2 100644 --- a/listings/ch20-web-server/no-listing-04-update-worker-definition/output.txt +++ b/listings/ch20-web-server/no-listing-04-update-worker-definition/output.txt @@ -7,6 +7,7 @@ error[E0599]: no method named `join` found for enum `Option` in the current scop | ^^^^ method not found in `Option>` | note: the method `join` exists on the type `JoinHandle<()>` + --> /rustc/d5a82bbd26e1ad8b7401f6a718a9c57c96905483/library/std/src/thread/mod.rs:1581:5 help: consider using `Option::expect` to unwrap the `JoinHandle<()>` value, panicking if the value is an `Option::None` | 52 | worker.thread.expect("REASON").join().unwrap(); diff --git a/redirects/compiler-plugins.md b/redirects/compiler-plugins.md index 66061adf5a..67187f5f6b 100644 --- a/redirects/compiler-plugins.md +++ b/redirects/compiler-plugins.md @@ -2,12 +2,5 @@ There is a new edition of the book and this is an old link. -> Compiler plugins are user-provided libraries that extend the compiler's behavior with new syntax extensions, lint checks, etc. - ---- - -This particular chapter has moved to [the Unstable Book][2]. - -* **[In the Unstable Rust Book: `plugin`][2]** - -[2]: ../unstable-book/language-features/plugin.html +> Compiler plugins were user-provided libraries that extended the compiler's behavior in certain ways. +> Support for them has been removed. diff --git a/redirects/using-rust-without-the-standard-library.md b/redirects/using-rust-without-the-standard-library.md index 75145429d4..0fbdfebdd6 100644 --- a/redirects/using-rust-without-the-standard-library.md +++ b/redirects/using-rust-without-the-standard-library.md @@ -7,11 +7,11 @@ --- -This particular chapter has moved to [the Unstable Book][2]. +This particular chapter has moved to [the Rustonomicon][2]. -* **[In the Unstable Rust Book: `lang_items` — Writing an executable without stdlib][2]** +* **[In the Rustonomicon: Beneath std][2]** * [In the first edition: Ch 4.12 — Using Rust without the Standard Library][1] [1]: https://doc.rust-lang.org/1.30.0/book/first-edition/using-rust-without-the-standard-library.html -[2]: ../unstable-book/language-features/lang-items.html#writing-an-executable-without-stdlib +[2]: ../nomicon/beneath-std.html diff --git a/rust-toolchain b/rust-toolchain index 5b6cd6b3cd..9ebd7af328 100644 --- a/rust-toolchain +++ b/rust-toolchain @@ -1 +1 @@ -1.65 +1.67 diff --git a/src/ch00-00-introduction.md b/src/ch00-00-introduction.md index e08f0c84ab..536988cb19 100644 --- a/src/ch00-00-introduction.md +++ b/src/ch00-00-introduction.md @@ -1,7 +1,41 @@ -## Rust Utilities +# Introduction -* Cargo, Rust's dependency manager and build tool, - compiles, and manages dependencies. +> Note: This edition of the book is the same as [The Rust Programming +> Language][nsprust] available in print and ebook format from [No Starch +> Press][nsp]. + +[nsprust]: https://nostarch.com/rust-programming-language-2nd-edition +[nsp]: https://nostarch.com/ + +Welcome to *The Rust Programming Language*, an introductory book about Rust. +The Rust programming language helps you write faster, more reliable software. +High-level ergonomics and low-level control are often at odds in programming +language design; Rust challenges that conflict. Through balancing powerful +technical capacity and a great developer experience, Rust gives you the option +to control low-level details (such as memory usage) without all the hassle +traditionally associated with such control. + +## Who Rust Is For + +Rust is ideal for many people for a variety of reasons. Let’s look at a few of +the most important groups. + +### Teams of Developers + +Rust is proving to be a productive tool for collaborating among large teams of +developers with varying levels of systems programming knowledge. Low-level code +is prone to various subtle bugs, which in most other languages can be caught +only through extensive testing and careful code review by experienced +developers. In Rust, the compiler plays a gatekeeper role by refusing to +compile code with these elusive bugs, including concurrency bugs. By working +alongside the compiler, the team can spend their time focusing on the program’s +logic rather than chasing down bugs. + +Rust also brings contemporary developer tools to the systems programming world: + +* Cargo, the included dependency manager and build tool, makes adding, + compiling, and managing dependencies painless and consistent across the Rust + ecosystem. * The Rustfmt formatting tool ensures a consistent coding style across developers. * The Rust Language Server powers Integrated Development Environment (IDE) @@ -10,37 +44,150 @@ By using these and other tools in the Rust ecosystem, developers can be productive while writing systems-level code. -## Reading Guide +### Students + +Rust is for students and those who are interested in learning about systems +concepts. Using Rust, many people have learned about topics like operating +systems development. The community is very welcoming and happy to answer +student questions. Through efforts such as this book, the Rust teams want to +make systems concepts more accessible to more people, especially those new to +programming. + +### Companies + +Hundreds of companies, large and small, use Rust in production for a variety of +tasks, including command line tools, web services, DevOps tooling, embedded +devices, audio and video analysis and transcoding, cryptocurrencies, +bioinformatics, search engines, Internet of Things applications, machine +learning, and even major parts of the Firefox web browser. + +### Open Source Developers + +Rust is for people who want to build the Rust programming language, community, +developer tools, and libraries. We’d love to have you contribute to the Rust +language. + +### People Who Value Speed and Stability + +Rust is for people who crave speed and stability in a language. By speed, we +mean both how quickly Rust code can run and the speed at which Rust lets you +write programs. The Rust compiler’s checks ensure stability through feature +additions and refactoring. This is in contrast to the brittle legacy code in +languages without these checks, which developers are often afraid to modify. By +striving for zero-cost abstractions, higher-level features that compile to +lower-level code as fast as code written manually, Rust endeavors to make safe +code be fast code as well. + +The Rust language hopes to support many other users as well; those mentioned +here are merely some of the biggest stakeholders. Overall, Rust’s greatest +ambition is to eliminate the trade-offs that programmers have accepted for +decades by providing safety *and* productivity, speed *and* ergonomics. Give +Rust a try and see if its choices work for you. -In concept chapters, you’ll learn about an aspect of Rust. In project +## Who This Book Is For + +This book assumes that you’ve written code in another programming language but +doesn’t make any assumptions about which one. We’ve tried to make the material +broadly accessible to those from a wide variety of programming backgrounds. We +don’t spend a lot of time talking about what programming *is* or how to think +about it. If you’re entirely new to programming, you would be better served by +reading a book that specifically provides an introduction to programming. + +## How to Use This Book + +In general, this book assumes that you’re reading it in sequence from front to +back. Later chapters build on concepts in earlier chapters, and earlier +chapters might not delve into details on a particular topic but will revisit +the topic in a later chapter. + +You’ll find two kinds of chapters in this book: concept chapters and project +chapters. In concept chapters, you’ll learn about an aspect of Rust. In project chapters, we’ll build small programs together, applying what you’ve learned so far. Chapters 2, 12, and 20 are project chapters; the rest are concept chapters. -Chapter 1 for Rust install, a “Hello, world!” program, -and how to use Cargo. Chapter 2 is an intro guessing game program, experienced beginners start here. Chapter 3 covers Rust features -similar to those of other programming languages, and in Chapter 4 -discusses Rust’s ownership system. +Chapter 1 explains how to install Rust, how to write a “Hello, world!” program, +and how to use Cargo, Rust’s package manager and build tool. Chapter 2 is a +hands-on introduction to writing a program in Rust, having you build up a +number guessing game. Here we cover concepts at a high level, and later +chapters will provide additional detail. If you want to get your hands dirty +right away, Chapter 2 is the place for that. Chapter 3 covers Rust features +that are similar to those of other programming languages, and in Chapter 4 +you’ll learn about Rust’s ownership system. If you’re a particularly meticulous +learner who prefers to learn every detail before moving on to the next, you +might want to skip Chapter 2 and go straight to Chapter 3, returning to Chapter +2 when you’d like to work on a project applying the details you’ve learned. + Chapter 5 discusses structs and methods, and Chapter 6 covers enums, `match` -expressions, and the `if let` control flow construct. +expressions, and the `if let` control flow construct. You’ll use structs and +enums to make custom types in Rust. In Chapter 7, you’ll learn about Rust’s module system and about privacy rules -for organizing your code for the API. Chapter 8 discusses vectors, strings, and hash maps. Chapter 9 -explores Rust’s error-handling. +for organizing your code and its public Application Programming Interface +(API). Chapter 8 discusses some common collection data structures that the +standard library provides, such as vectors, strings, and hash maps. Chapter 9 +explores Rust’s error-handling philosophy and techniques. + +Chapter 10 digs into generics, traits, and lifetimes, which give you the power +to define code that applies to multiple types. Chapter 11 is all about testing, +which even with Rust’s safety guarantees is necessary to ensure your program’s +logic is correct. In Chapter 12, we’ll build our own implementation of a subset +of functionality from the `grep` command line tool that searches for text +within files. For this, we’ll use many of the concepts we discussed in the +previous chapters. -Chapter 10 explores generics, traits, and lifetimes. Chapter 11 teaches testing. In Chapter 12, we’ll build an implementation of `grep'. Chapter 13 explores closures and iterators: features of Rust that come from functional programming languages. In Chapter 14, we’ll examine Cargo in more depth and talk about best practices for sharing your libraries with others. -Chapter 15 discusses smart pointers. +Chapter 15 discusses smart pointers that the standard library provides and the +traits that enable their functionality. + +In Chapter 16, we’ll walk through different models of concurrent programming +and talk about how Rust helps you to program in multiple threads fearlessly. +Chapter 17 looks at how Rust idioms compare to object-oriented programming +principles you might be familiar with. + +Chapter 18 is a reference on patterns and pattern matching, which are powerful +ways of expressing ideas throughout Rust programs. Chapter 19 contains a +smorgasbord of advanced topics of interest, including unsafe Rust, macros, and +more about lifetimes, traits, types, functions, and closures. -Chapter 16 explores different models for concurrent programming -and how Rust allows to program in multiple threads. -Chapter 17 compares Rust concepts with object-oriented programming -principles. +In Chapter 20, we’ll complete a project in which we’ll implement a low-level +multithreaded web server! -Appendix A covers Rust’s keywords, Appendix B +Finally, some appendices contain useful information about the language in a +more reference-like format. Appendix A covers Rust’s keywords, Appendix B covers Rust’s operators and symbols, Appendix C covers derivable traits provided by the standard library, Appendix D covers some useful development -tools, and Appendix E explains Rust editions. +tools, and Appendix E explains Rust editions. In Appendix F, you can find +translations of the book, and in Appendix G we’ll cover how Rust is made and +what nightly Rust is. + +There is no wrong way to read this book: if you want to skip ahead, go for it! +You might have to jump back to earlier chapters if you experience any +confusion. But do whatever works for you. + + + +An important part of the process of learning Rust is learning how to read the +error messages the compiler displays: these will guide you toward working code. +As such, we’ll provide many examples that don’t compile along with the error +message the compiler will show you in each situation. Know that if you enter +and run a random example, it may not compile! Make sure you read the +surrounding text to see whether the example you’re trying to run is meant to +error. Ferris will also help you distinguish code that isn’t meant to work: + +| Ferris | Meaning | +|------------------------------------------------------------------------------------------------------------------|--------------------------------------------------| +| Ferris with a question mark | This code does not compile! | +| Ferris throwing up their hands | This code panics! | +| Ferris with one claw up, shrugging | This code does not produce the desired behavior. | + +In most situations, we’ll lead you to the correct version of any code that +doesn’t compile. + +## Source Code + +The source files from which this book is generated can be found on +[GitHub][book]. -Feel free to skip ahead! +[book]: https://github.com/rust-lang/book/tree/main/src diff --git a/src/ch01-02-hello-world.md b/src/ch01-02-hello-world.md index 5a1793d24a..1918d992d6 100644 --- a/src/ch01-02-hello-world.md +++ b/src/ch01-02-hello-world.md @@ -181,4 +181,4 @@ Just compiling with `rustc` is fine for simple programs, but as your project grows, you’ll want to streamline sharing code. Next, we’ll introduce you to Cargo. [troubleshooting]: ch01-01-installation.html#troubleshooting -[devtools]: appendix-04-useful-development-tools.md +[devtools]: appendix-04-useful-development-tools.html diff --git a/src/ch02-00-guessing-game-tutorial.md b/src/ch02-00-guessing-game-tutorial.md index 4f28573333..5e27fb114d 100644 --- a/src/ch02-00-guessing-game-tutorial.md +++ b/src/ch02-00-guessing-game-tutorial.md @@ -930,8 +930,8 @@ discusses structs and method syntax, and Chapter 6 explains how enums work. [randcrate]: https://crates.io/crates/rand [semver]: http://semver.org [cratesio]: https://crates.io/ -[doccargo]: http://doc.crates.io -[doccratesio]: http://doc.crates.io/crates-io.html +[doccargo]: https://doc.rust-lang.org/cargo/ +[doccratesio]: https://doc.rust-lang.org/cargo/reference/publishing.html [match]: ch06-02-match.html [shadowing]: ch03-01-variables-and-mutability.html#shadowing [parse]: ../std/primitive.str.html#method.parse diff --git a/src/ch03-01-variables-and-mutability.md b/src/ch03-01-variables-and-mutability.md index 856f183dff..058f7bb5c4 100644 --- a/src/ch03-01-variables-and-mutability.md +++ b/src/ch03-01-variables-and-mutability.md @@ -2,7 +2,11 @@ As mentioned in the [“Storing Values with Variables”][storing-values-with-variables] section, by default, -variables are immutable. +variables are immutable. This is one of many nudges Rust gives you to write +your code in a way that takes advantage of the safety and easy concurrency that +Rust offers. However, you still have the option to make your variables mutable. +Let’s explore how and why Rust encourages you to favor immutability and why +sometimes you might want to opt out. When a variable is immutable, once a value is bound to a name, you can’t change that value. To illustrate this, generate a new project called *variables* in @@ -25,19 +29,27 @@ regarding an immutability error, as shown in this output: ``` This example shows how the compiler helps you find errors in your programs. -Compiler errors only show that the program isn’t running safely yet; -errors are common. +Compiler errors can be frustrating, but really they only mean your program +isn’t safely doing what you want it to do yet; they do *not* mean that you’re +not a good programmer! Experienced Rustaceans still get compiler errors. You received the error message `` cannot assign twice to immutable variable `x` `` because you tried to assign a second value to the immutable `x` variable. -The Rust compiler guarantees when you state that a value won’t change, it really +It’s important that we get compile-time errors when we attempt to change a +value that’s designated as immutable because this very situation can lead to +bugs. If one part of our code operates on the assumption that a value will +never change and another part of our code changes that value, it’s possible +that the first part of the code won’t do what it was designed to do. The cause +of this kind of bug can be difficult to track down after the fact, especially +when the second piece of code changes the value only *sometimes*. The Rust +compiler guarantees that when you state that a value won’t change, it really won’t change, so you don’t have to keep track of it yourself. Your code is thus -easier to reason through and this helps to prevent bugs. +easier to reason through. But mutability can be very useful, and can make code more convenient to write. -Variables are immutable by default, but can be made mutable by adding `mut` -in front of the variable name like in [Chapter +Although variables are immutable by default, you can make them mutable by +adding `mut` in front of the variable name as you did in [Chapter 2][storing-values-with-variables]. Adding `mut` also conveys intent to future readers of the code by indicating that other parts of the code will be changing this variable’s value. @@ -57,19 +69,21 @@ When we run the program now, we get this: ``` We’re allowed to change the value bound to `x` from `5` to `6` when `mut` is -used. Ultimately, deciding whether to use mutability or not depends on what you -think is clearest in that particular situation. +used. Ultimately, deciding whether to use mutability or not is up to you and +depends on what you think is clearest in that particular situation. ### Constants -Like immutable variables, *constants* are values bound to a name and +Like immutable variables, *constants* are values that are bound to a name and are not allowed to change, but there are a few differences between constants and variables. First, you aren’t allowed to use `mut` with constants. Constants aren’t just immutable by default—they’re always immutable. You declare constants using the `const` keyword instead of the `let` keyword, and the type of the value *must* -be annotated. See [“Data Types”][data-types] for more. +be annotated. We’ll cover types and type annotations in the next section, +[“Data Types”][data-types], so don’t worry about the details +right now. Just know that you must always annotate the type. Constants can be declared in any scope, including the global scope, which makes them useful for values that many parts of code need to know about. @@ -98,7 +112,7 @@ Constants are valid for the entire time a program runs, within the scope in which they were declared. This property makes constants useful for values in your application domain that multiple parts of the program might need to know about, such as the maximum number of points any player of a game is allowed to -earn. +earn, or the speed of light. Naming hardcoded values used throughout your program as constants is useful in conveying the meaning of that value to future maintainers of the code. It also @@ -108,13 +122,14 @@ hardcoded value needed to be updated in the future. ### Shadowing As you saw in the guessing game tutorial in [Chapter -2][comparing-the-guess-to-the-secret-number], you can -declare a new variable with the same name as a previous one. The second -variable is what the compiler will see when you use it again. This -overshadows the first, taking any uses of the variable name to -itself until either it repeats or the scope ends. We can shadow a -variable by using the same variable’s name and repeating the use -of the `let` keyword as follows: +2][comparing-the-guess-to-the-secret-number], you can declare a +new variable with the same name as a previous variable. Rustaceans say that the +first variable is *shadowed* by the second, which means that the second +variable is what the compiler will see when you use the name of the variable. +In effect, the second variable overshadows the first, taking any uses of the +variable name to itself until either it itself is shadowed or the scope ends. +We can shadow a variable by using the same variable’s name and repeating the +use of the `let` keyword as follows: Filename: src/main.rs @@ -141,8 +156,8 @@ on a value but have the variable be immutable after those transformations have been completed. The other difference between `mut` and shadowing is that because we’re -creating a new variable when we use the `let` keyword again, we can -change the type of the value but reuse the same name. For example, a +effectively creating a new variable when we use the `let` keyword again, we can +change the type of the value but reuse the same name. For example, say our program asks a user to show how many spaces they want between some text by inputting space characters, and then we want to store that input as a number: @@ -166,6 +181,9 @@ The error says we’re not allowed to mutate a variable’s type: {{#include ../listings/ch03-common-programming-concepts/no-listing-05-mut-cant-change-types/output.txt}} ``` +Now that we’ve explored how variables work, let’s look at more data types they +can have. + [comparing-the-guess-to-the-secret-number]: ch02-00-guessing-game-tutorial.html#comparing-the-guess-to-the-secret-number [data-types]: ch03-02-data-types.html#data-types diff --git a/src/ch08-02-strings.md b/src/ch08-02-strings.md index 9663d36ab1..f38803ee3b 100644 --- a/src/ch08-02-strings.md +++ b/src/ch08-02-strings.md @@ -244,7 +244,7 @@ encoded UTF-8 example strings from Listing 8-14. First, this one: In this case, `len` will be 4, which means the vector storing the string “Hola” is 4 bytes long. Each of these letters takes 1 byte when encoded in UTF-8. The following line, however, may surprise you. (Note that this string begins with -the capital Cyrillic letter Ze, not the Arabic number 3.) +the capital Cyrillic letter Ze, not the number 3.) ```rust {{#rustdoc_include ../listings/ch08-common-collections/listing-08-14/src/main.rs:russian}} diff --git a/src/ch10-01-syntax.md b/src/ch10-01-syntax.md index c22aef7c36..431dba9667 100644 --- a/src/ch10-01-syntax.md +++ b/src/ch10-01-syntax.md @@ -33,9 +33,9 @@ the duplication by introducing a generic type parameter in a single function. To parameterize the types in a new single function, we need to name the type parameter, just as we do for the value parameters to a function. You can use any identifier as a type parameter name. But we’ll use `T` because, by -convention, type parameter names in Rust are short, often just a letter, and Rust’s -type-naming convention is CamelCase. Short for “type,” `T` is the default -choice of most Rust programmers. +convention, type parameter names in Rust are short, often just a letter, and +Rust’s type-naming convention is UpperCamelCase. Short for “type,” `T` is the +default choice of most Rust programmers. When we use a parameter in the body of the function, we have to declare the parameter name in the signature so the compiler knows what that name means. @@ -274,7 +274,7 @@ method. ### Performance of Code Using Generics You might be wondering whether there is a runtime cost when using generic type -parameters. The good news is that using generic types won't make your program run +parameters. The good news is that using generic types won't make your program run any slower than it would with concrete types. Rust accomplishes this by performing monomorphization of the code using diff --git a/src/ch10-03-lifetime-syntax.md b/src/ch10-03-lifetime-syntax.md index 5229ab74b3..498f01f0b5 100644 --- a/src/ch10-03-lifetime-syntax.md +++ b/src/ch10-03-lifetime-syntax.md @@ -8,13 +8,13 @@ One detail we didn’t discuss in the [“References and Borrowing”][references-and-borrowing] section in Chapter 4 is that every reference in Rust has a *lifetime*, which is the scope for which that reference is valid. Most of the time, lifetimes are implicit and inferred, -just like most of the time, types are inferred. We only must annotate types +just like most of the time, types are inferred. We must only annotate types when multiple types are possible. In a similar way, we must annotate lifetimes when the lifetimes of references could be related in a few different ways. Rust requires us to annotate the relationships using generic lifetime parameters to ensure the actual references used at runtime will definitely be valid. -Annotating lifetimes is not even a concept most other programming languages +Annotating lifetimes is not a concept most other programming languages have, so this is going to feel unfamiliar. Although we won’t cover lifetimes in their entirety in this chapter, we’ll discuss common ways you might encounter lifetime syntax so you can get comfortable with the concept. @@ -44,7 +44,7 @@ The outer scope declares a variable named `r` with no initial value, and the inner scope declares a variable named `x` with the initial value of 5. Inside the inner scope, we attempt to set the value of `r` as a reference to `x`. Then the inner scope ends, and we attempt to print the value in `r`. This code won’t -compile because the value `r` is referring to has gone out of scope before we +compile because what the value `r` is referring to has gone out of scope before we try to use it. Here is the error message: ```console diff --git a/src/ch13-03-improving-our-io-project.md b/src/ch13-03-improving-our-io-project.md index b9ef0b430c..42a5be89d2 100644 --- a/src/ch13-03-improving-our-io-project.md +++ b/src/ch13-03-improving-our-io-project.md @@ -28,7 +28,7 @@ we would remove them in the future. Well, that time is now! We needed `clone` here because we have a slice with `String` elements in the parameter `args`, but the `build` function doesn’t own `args`. To return ownership of a `Config` instance, we had to clone the values from the `query` -and `filename` fields of `Config` so the `Config` instance can own its values. +and `file_path` fields of `Config` so the `Config` instance can own its values. With our new knowledge about iterators, we can change the `build` function to take ownership of an iterator as its argument instead of borrowing a slice. @@ -118,7 +118,7 @@ the program. We want to ignore that and get to the next value, so first we call value we want to put in the `query` field of `Config`. If `next` returns a `Some`, we use a `match` to extract the value. If it returns `None`, it means not enough arguments were given and we return early with an `Err` value. We do -the same thing for the `filename` value. +the same thing for the `file_path` value. ### Making Code Clearer with Iterator Adaptors diff --git a/src/ch15-06-reference-cycles.md b/src/ch15-06-reference-cycles.md index bef289202c..beb2bc2169 100644 --- a/src/ch15-06-reference-cycles.md +++ b/src/ch15-06-reference-cycles.md @@ -84,7 +84,7 @@ If you uncomment the last `println!` and run the program, Rust will try to print this cycle with `a` pointing to `b` pointing to `a` and so forth until it overflows the stack. -Compared to a real-world program, the consequences creating a reference cycle +Compared to a real-world program, the consequences of creating a reference cycle in this example aren’t very dire: right after we create the reference cycle, the program ends. However, if a more complex program allocated lots of memory in a cycle and held onto it for a long time, the program would use more memory diff --git a/src/ch19-05-advanced-functions-and-closures.md b/src/ch19-05-advanced-functions-and-closures.md index 69624f056e..88c46847d5 100644 --- a/src/ch19-05-advanced-functions-and-closures.md +++ b/src/ch19-05-advanced-functions-and-closures.md @@ -17,7 +17,7 @@ The syntax for specifying that a parameter is a function pointer is similar to that of closures, as shown in Listing 19-27, where we’ve defined a function `add_one` that adds one to its parameter. The function `do_twice` takes two parameters: a function pointer to any function that takes an `i32` parameter -and returns an `i32`, and one `i32 value`. The `do_twice` function calls the +and returns an `i32`, and one `i32` value. The `do_twice` function calls the function `f` twice, passing it the `arg` value, then adds the two function call results together. The `main` function calls `do_twice` with the arguments `add_one` and `5`. diff --git a/src/title-page.md b/src/title-page.md index 12d1a65987..5f7a7a680a 100644 --- a/src/title-page.md +++ b/src/title-page.md @@ -2,7 +2,7 @@ *by Steve Klabnik and Carol Nichols, with contributions from the Rust Community* -This version of the text assumes you’re using Rust 1.65 (released 2022-11-03) +This version of the text assumes you’re using Rust 1.67.1 (released 2023-02-09) or later. See the [“Installation” section of Chapter 1][install] to install or update Rust. @@ -18,7 +18,7 @@ Press][nsprust]. [install]: ch01-01-installation.html [editions]: appendix-05-editions.html -[nsprust]: https://nostarch.com/rust +[nsprust]: https://nostarch.com/rust-programming-language-2nd-edition [translations]: appendix-06-translation.html > **🚨 Want a more interactive learning experience? Try out a different version