diff options
| author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-17 12:11:38 +0000 |
|---|---|---|
| committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-17 12:13:23 +0000 |
| commit | 20431706a863f92cb37dc512fef6e48d192aaf2c (patch) | |
| tree | 2867f13f5fd5437ba628c67d7f87309ccadcd286 /src/doc | |
| parent | Releasing progress-linux version 1.65.0+dfsg1-2~progress7.99u1. (diff) | |
| download | rustc-20431706a863f92cb37dc512fef6e48d192aaf2c.tar.xz rustc-20431706a863f92cb37dc512fef6e48d192aaf2c.zip | |
Merging upstream version 1.66.0+dfsg1.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'src/doc')
226 files changed, 9994 insertions, 7334 deletions
diff --git a/src/doc/book/ADMIN_TASKS.md b/src/doc/book/ADMIN_TASKS.md index 7c152577f..2a92eefd2 100644 --- a/src/doc/book/ADMIN_TASKS.md +++ b/src/doc/book/ADMIN_TASKS.md @@ -113,7 +113,12 @@ To check, say, updating `mdbook` or changing the way files get included: ## Produce markdown from docx for diffing -- TODO Carol to document this next time she does it +- Save the docx file to `tmp/chapterXX.docx`. +- In Word, go to the review tab, choose "Accept all changes and stop tracking" +- Save the docx again and close Word +- Run `./tools/doc-to-md.sh` +- This should write `nostarch/chapterXX.md`. Adjust the XSL in + `tools/doc-to-md.xsl` and run `./tools/doc-to-md.sh` again if needed. ## Generate Graphviz dot diff --git a/src/doc/book/TODO.md b/src/doc/book/TODO.md new file mode 100644 index 000000000..b61f85314 --- /dev/null +++ b/src/doc/book/TODO.md @@ -0,0 +1,17 @@ +# In each chapter + +- [ ] Manual regeneration +- [ ] Check for upstream changes from last snapshot +- [ ] Propagate updated output to docx +- [ ] Extract docx and check diff +- [ ] Answer all comments +- [ ] Check cross references +- [ ] Check indentation of --snip-- +- [ ] Numbered lines, Gray out unchanged lines +- [ ] Check line wrapping +- [ ] Check for unneeded command/compiling/running output +- [ ] Check println style and error messages +- [ ] Add alt text to images +- [ ] Index tags + - [ ] search for "convention" conventions:naming:of blah + - [ ] check for double spaces, spaces at the end of paragraphs diff --git a/src/doc/book/ci/dictionary.txt b/src/doc/book/ci/dictionary.txt index 3fe25ff52..9eb695d5b 100644 --- a/src/doc/book/ci/dictionary.txt +++ b/src/doc/book/ci/dictionary.txt @@ -537,6 +537,7 @@ uncommenting unevaluated Uninstalling uninstall +unittests unix unpopulated unoptimized diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.lock index 0a2f222c2..edc20385b 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -8,9 +10,9 @@ checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd" [[package]] name = "getrandom" -version = "0.2.2" +version = "0.2.7" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c9495705279e7140bf035dde1f6e750c162df8b625267cd52cc44e0b156732c8" +checksum = "4eb1a864a501629691edf6c15a593b7a51eebaa1e8468e9ddc623de7c9b58ec6" dependencies = [ "cfg-if", "libc", @@ -26,33 +28,32 @@ dependencies = [ [[package]] name = "libc" -version = "0.2.86" +version = "0.2.127" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "b7282d924be3275cec7f6756ff4121987bc6481325397dde6ba3e7802b1a8b1c" +checksum = "505e71a4706fa491e9b1b55f51b95d4037d0821ee40131190475f692b35b009b" [[package]] name = "ppv-lite86" -version = "0.2.10" +version = "0.2.16" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" +checksum = "eb9f9e6e233e5c4a35559a617bf40a4ec447db2e84c20b55a6f83167b7e57872" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] name = "rand_chacha" -version = "0.3.0" +version = "0.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "e12735cf05c9e10bf21534da50a147b924d555dc7a547c42e6bb2d5b6017ae0d" +checksum = "e6c10a63a0fa32252be49d21e7709d4d4baf8d231c2dbce1eaa8141b9b127d88" dependencies = [ "ppv-lite86", "rand_core", @@ -60,24 +61,15 @@ dependencies = [ [[package]] name = "rand_core" -version = "0.6.2" +version = "0.6.3" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "34cf66eb183df1c5876e2dcf6b13d57340741e8dc255b48e40a26de954d06ae7" +checksum = "d34f1408f55294453790c48b2f1ebbb1c5b4b7563eb1f418bcfcfdbb06ebb4e7" dependencies = [ "getrandom", ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" -version = "0.10.2+wasi-snapshot-preview1" +version = "0.11.0+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "fd6fbd9a79829dd1ad0cc20627bf1ed606756a7f77edff7b66b7064f9cb327c6" +checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-03/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt index 62fe8327f..fbc0cec33 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-04/output.txt @@ -5,7 +5,7 @@ $ cargo build Compiling ppv-lite86 v0.2.10 Compiling rand_core v0.6.2 Compiling rand_chacha v0.3.0 - Compiling rand v0.8.3 + Compiling rand v0.8.5 Compiling guessing_game v0.1.0 (file:///projects/guessing_game) error[E0308]: mismatched types --> src/main.rs:22:21 diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-05/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/listing-02-06/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-04-looping/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.lock b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.lock +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.toml b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.toml +++ b/src/doc/book/listings/ch02-guessing-game-tutorial/no-listing-05-quitting/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch03-common-programming-concepts/no-listing-07-numeric-operations/src/main.rs b/src/doc/book/listings/ch03-common-programming-concepts/no-listing-07-numeric-operations/src/main.rs index 9d3b4813b..77c716c14 100644 --- a/src/doc/book/listings/ch03-common-programming-concepts/no-listing-07-numeric-operations/src/main.rs +++ b/src/doc/book/listings/ch03-common-programming-concepts/no-listing-07-numeric-operations/src/main.rs @@ -10,7 +10,7 @@ fn main() { // division let quotient = 56.7 / 32.2; - let floored = 2 / 3; // Results in 0 + let truncated = -5 / 3; // Results in -1 // remainder let remainder = 43 % 5; diff --git a/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.lock b/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.lock +++ b/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.toml b/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.toml index 15b3fffca..d508e9578 100644 --- a/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.toml +++ b/src/doc/book/listings/ch07-managing-growing-projects/listing-07-18/Cargo.toml @@ -4,4 +4,4 @@ version = "0.1.0" edition = "2021" [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.lock b/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.lock +++ b/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.toml b/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.toml index cc63f6f02..7eda67aea 100644 --- a/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.toml +++ b/src/doc/book/listings/ch07-managing-growing-projects/no-listing-01-use-std-unnested/Cargo.toml @@ -6,4 +6,4 @@ edition = "2021" # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch08-common-collections/listing-08-04/src/main.rs b/src/doc/book/listings/ch08-common-collections/listing-08-04/src/main.rs index fa4e090d5..fca332de6 100644 --- a/src/doc/book/listings/ch08-common-collections/listing-08-04/src/main.rs +++ b/src/doc/book/listings/ch08-common-collections/listing-08-04/src/main.rs @@ -3,11 +3,11 @@ fn main() { let v = vec![1, 2, 3, 4, 5]; let third: &i32 = &v[2]; - println!("The third element is {}", third); + println!("The third element is {third}"); let third: Option<&i32> = v.get(2); match third { - Some(third) => println!("The third element is {}", third), + Some(third) => println!("The third element is {third}"), None => println!("There is no third element."), } // ANCHOR_END: here diff --git a/src/doc/book/listings/ch08-common-collections/listing-08-06/src/main.rs b/src/doc/book/listings/ch08-common-collections/listing-08-06/src/main.rs index 1b42274a6..653ac27b0 100644 --- a/src/doc/book/listings/ch08-common-collections/listing-08-06/src/main.rs +++ b/src/doc/book/listings/ch08-common-collections/listing-08-06/src/main.rs @@ -6,6 +6,6 @@ fn main() { v.push(6); - println!("The first element is: {}", first); + println!("The first element is: {first}"); // ANCHOR_END: here } diff --git a/src/doc/book/listings/ch08-common-collections/listing-08-07/src/main.rs b/src/doc/book/listings/ch08-common-collections/listing-08-07/src/main.rs index 38b97784b..aebf855a9 100644 --- a/src/doc/book/listings/ch08-common-collections/listing-08-07/src/main.rs +++ b/src/doc/book/listings/ch08-common-collections/listing-08-07/src/main.rs @@ -2,7 +2,7 @@ fn main() { // ANCHOR: here let v = vec![100, 32, 57]; for i in &v { - println!("{}", i); + println!("{i}"); } // ANCHOR_END: here } diff --git a/src/doc/book/listings/ch08-common-collections/listing-08-16/src/main.rs b/src/doc/book/listings/ch08-common-collections/listing-08-16/src/main.rs index 8938dc143..db57cddba 100644 --- a/src/doc/book/listings/ch08-common-collections/listing-08-16/src/main.rs +++ b/src/doc/book/listings/ch08-common-collections/listing-08-16/src/main.rs @@ -3,6 +3,6 @@ fn main() { let mut s1 = String::from("foo"); let s2 = "bar"; s1.push_str(s2); - println!("s2 is {}", s2); + println!("s2 is {s2}"); // ANCHOR_END: here } diff --git a/src/doc/book/listings/ch08-common-collections/no-listing-02-format/src/main.rs b/src/doc/book/listings/ch08-common-collections/no-listing-02-format/src/main.rs index 4a38e63d2..db408e2b7 100644 --- a/src/doc/book/listings/ch08-common-collections/no-listing-02-format/src/main.rs +++ b/src/doc/book/listings/ch08-common-collections/no-listing-02-format/src/main.rs @@ -4,6 +4,6 @@ fn main() { let s2 = String::from("tac"); let s3 = String::from("toe"); - let s = format!("{}-{}-{}", s1, s2, s3); + let s = format!("{s1}-{s2}-{s3}"); // ANCHOR_END: here } diff --git a/src/doc/book/listings/ch08-common-collections/no-listing-03-iterate-over-hashmap/src/main.rs b/src/doc/book/listings/ch08-common-collections/no-listing-03-iterate-over-hashmap/src/main.rs index 2e7dc02e6..bb13c86f1 100644 --- a/src/doc/book/listings/ch08-common-collections/no-listing-03-iterate-over-hashmap/src/main.rs +++ b/src/doc/book/listings/ch08-common-collections/no-listing-03-iterate-over-hashmap/src/main.rs @@ -8,7 +8,7 @@ fn main() { scores.insert(String::from("Yellow"), 50); for (key, value) in &scores { - println!("{}: {}", key, value); + println!("{key}: {value}"); } // ANCHOR_END: here } diff --git a/src/doc/book/listings/ch09-error-handling/listing-09-07/src/main.rs b/src/doc/book/listings/ch09-error-handling/listing-09-07/src/main.rs index f4564f670..0295949d2 100644 --- a/src/doc/book/listings/ch09-error-handling/listing-09-07/src/main.rs +++ b/src/doc/book/listings/ch09-error-handling/listing-09-07/src/main.rs @@ -1,7 +1,6 @@ // ANCHOR: here use std::fs::File; -use std::io; -use std::io::Read; +use std::io::{self, Read}; fn read_username_from_file() -> Result<String, io::Error> { let mut username_file = File::open("hello.txt")?; diff --git a/src/doc/book/listings/ch09-error-handling/listing-09-08/src/main.rs b/src/doc/book/listings/ch09-error-handling/listing-09-08/src/main.rs index c3c6e23ef..ca672caad 100644 --- a/src/doc/book/listings/ch09-error-handling/listing-09-08/src/main.rs +++ b/src/doc/book/listings/ch09-error-handling/listing-09-08/src/main.rs @@ -1,7 +1,6 @@ // ANCHOR: here use std::fs::File; -use std::io; -use std::io::Read; +use std::io::{self, Read}; fn read_username_from_file() -> Result<String, io::Error> { let mut username = String::new(); diff --git a/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.lock b/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.lock +++ b/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.toml b/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.toml index 15b3fffca..d508e9578 100644 --- a/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.toml +++ b/src/doc/book/listings/ch09-error-handling/listing-09-13/Cargo.toml @@ -4,4 +4,4 @@ version = "0.1.0" edition = "2021" [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.lock b/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.lock index 0a2f222c2..2ae9e459e 100644 --- a/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.lock +++ b/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "cfg-if" version = "1.0.0" @@ -38,14 +40,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -68,15 +69,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.toml b/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.toml index 15b3fffca..d508e9578 100644 --- a/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.toml +++ b/src/doc/book/listings/ch09-error-handling/no-listing-09-guess-out-of-range/Cargo.toml @@ -4,4 +4,4 @@ version = "0.1.0" edition = "2021" [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.lock b/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.lock index d37189b33..8b8c69d33 100644 --- a/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.lock +++ b/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.lock @@ -1,6 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "adder" version = "0.1.0" - diff --git a/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.toml b/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.toml index e61cb12e3..b7d36d44c 100644 --- a/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.toml +++ b/src/doc/book/listings/ch11-writing-automated-tests/listing-11-01/Cargo.toml @@ -3,4 +3,6 @@ name = "adder" version = "0.1.0" edition = "2021" +# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html + [dependencies] diff --git a/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/Cargo.lock b/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/Cargo.lock index eec3a9e4b..bf6974b58 100644 --- a/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/Cargo.lock +++ b/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "add_one" version = "0.1.0" @@ -45,14 +47,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -75,15 +76,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/add_one/Cargo.toml b/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/add_one/Cargo.toml index fd4942ace..bc758bd88 100644 --- a/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/add_one/Cargo.toml +++ b/src/doc/book/listings/ch14-more-about-cargo/no-listing-03-workspace-with-external-dependency/add/add_one/Cargo.toml @@ -4,4 +4,4 @@ version = "0.1.0" edition = "2021" [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/Cargo.lock b/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/Cargo.lock index eec3a9e4b..bf6974b58 100644 --- a/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/Cargo.lock +++ b/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/Cargo.lock @@ -1,5 +1,7 @@ # This file is automatically @generated by Cargo. # It is not intended for manual editing. +version = 3 + [[package]] name = "add_one" version = "0.1.0" @@ -45,14 +47,13 @@ checksum = "ac74c624d6b2d21f425f752262f42188365d7b8ff1aff74c82e45136510a4857" [[package]] name = "rand" -version = "0.8.3" +version = "0.8.5" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "0ef9e7e66b4468674bfcb0c81af8b7fa0bb154fa9f28eb840da5c447baeb8d7e" +checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404" dependencies = [ "libc", "rand_chacha", "rand_core", - "rand_hc", ] [[package]] @@ -75,15 +76,6 @@ dependencies = [ ] [[package]] -name = "rand_hc" -version = "0.3.0" -source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3190ef7066a446f2e7f42e239d161e905420ccab01eb967c9eb27d21b2322a73" -dependencies = [ - "rand_core", -] - -[[package]] name = "wasi" version = "0.10.2+wasi-snapshot-preview1" source = "registry+https://github.com/rust-lang/crates.io-index" diff --git a/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/add_one/Cargo.toml b/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/add_one/Cargo.toml index fd4942ace..bc758bd88 100644 --- a/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/add_one/Cargo.toml +++ b/src/doc/book/listings/ch14-more-about-cargo/output-only-03-use-rand/add/add_one/Cargo.toml @@ -4,4 +4,4 @@ version = "0.1.0" edition = "2021" [dependencies] -rand = "0.8.3" +rand = "0.8.5" diff --git a/src/doc/book/listings/ch18-patterns-and-matching/listing-18-14/src/main.rs b/src/doc/book/listings/ch18-patterns-and-matching/listing-18-14/src/main.rs index 8d445d9b9..b71da9a37 100644 --- a/src/doc/book/listings/ch18-patterns-and-matching/listing-18-14/src/main.rs +++ b/src/doc/book/listings/ch18-patterns-and-matching/listing-18-14/src/main.rs @@ -8,9 +8,11 @@ fn main() { let p = Point { x: 0, y: 7 }; match p { - Point { x, y: 0 } => println!("On the x axis at {}", x), - Point { x: 0, y } => println!("On the y axis at {}", y), - Point { x, y } => println!("On neither axis: ({}, {})", x, y), + Point { x, y: 0 } => println!("On the x axis at {x}"), + Point { x: 0, y } => println!("On the y axis at {y}"), + Point { x, y } => { + println!("On neither axis: ({x}, {y})"); + } } } // ANCHOR_END: here diff --git a/src/doc/book/listings/ch18-patterns-and-matching/listing-18-15/src/main.rs b/src/doc/book/listings/ch18-patterns-and-matching/listing-18-15/src/main.rs index 9b8dac193..4ddef0aaf 100644 --- a/src/doc/book/listings/ch18-patterns-and-matching/listing-18-15/src/main.rs +++ b/src/doc/book/listings/ch18-patterns-and-matching/listing-18-15/src/main.rs @@ -10,18 +10,18 @@ fn main() { match msg { Message::Quit => { - println!("The Quit variant has no data to destructure.") + println!("The Quit variant has no data to destructure."); } Message::Move { x, y } => { println!( - "Move in the x direction {} and in the y direction {}", - x, y + "Move in the x direction {x} and in the y direction {y}" ); } - Message::Write(text) => println!("Text message: {}", text), + Message::Write(text) => { + println!("Text message: {text}"); + } Message::ChangeColor(r, g, b) => println!( - "Change the color to red {}, green {}, and blue {}", - r, g, b + "Change the color to red {r}, green {g}, and blue {b}", ), } } diff --git a/src/doc/book/listings/ch18-patterns-and-matching/listing-18-16/src/main.rs b/src/doc/book/listings/ch18-patterns-and-matching/listing-18-16/src/main.rs index ed6a20bf4..4c958601b 100644 --- a/src/doc/book/listings/ch18-patterns-and-matching/listing-18-16/src/main.rs +++ b/src/doc/book/listings/ch18-patterns-and-matching/listing-18-16/src/main.rs @@ -14,13 +14,11 @@ fn main() { let msg = Message::ChangeColor(Color::Hsv(0, 160, 255)); match msg { - Message::ChangeColor(Color::Rgb(r, g, b)) => println!( - "Change the color to red {}, green {}, and blue {}", - r, g, b - ), + Message::ChangeColor(Color::Rgb(r, g, b)) => { + println!("Change color to red {r}, green {g}, and blue {b}"); + } Message::ChangeColor(Color::Hsv(h, s, v)) => println!( - "Change the color to hue {}, saturation {}, and value {}", - h, s, v + "Change color to hue {h}, saturation {s}, value {v}" ), _ => (), } diff --git a/src/doc/book/nostarch/acknowledgments.md b/src/doc/book/nostarch/acknowledgments.md index 89d4adffc..c29cb712a 100644 --- a/src/doc/book/nostarch/acknowledgments.md +++ b/src/doc/book/nostarch/acknowledgments.md @@ -12,8 +12,6 @@ Karen Rustad Tölva for the cover art. Thank you to our team at No Starch, including Bill Pollock, Liz Chadwick, and Janelle Ludowise, for improving this book and bringing it to print. -<!--Insert Steve's acknowledgements here --> - Carol is grateful for the opportunity to work on this book. She thanks her family for their constant love and support, especially her husband Jake Goulding and her daughter Vivian. diff --git a/src/doc/book/nostarch/appendix.md b/src/doc/book/nostarch/appendix.md index 1722a9345..98432a1da 100644 --- a/src/doc/book/nostarch/appendix.md +++ b/src/doc/book/nostarch/appendix.md @@ -8,77 +8,67 @@ directory, so all fixes need to be made in `/src/`. ## Appendix A: Keywords -The following list contains keywords that are reserved for current or future +The following lists contain keywords that are reserved for current or future use by the Rust language. As such, they cannot be used as identifiers (except -as raw identifiers as we’ll discuss in the “Raw Identifiers†section). -Identifiers are names of functions, variables, parameters, struct fields, +as raw identifiers, as we’ll discuss in “Raw Identifiers†on page XX). +*Identifiers* are names of functions, variables, parameters, struct fields, modules, crates, constants, macros, static values, attributes, types, traits, or lifetimes. -### Keywords Currently in Use +## Keywords Currently in Use The following is a list of keywords currently in use, with their functionality described. -* `as` - perform primitive casting, disambiguate the specific trait containing - an item, or rename items in `use` statements - -<!-- `extern crate` is a bit old. Not sure if it needs a mention -/JT --> -<!-- good call, took it out /Carol --> - -* `async` - return a `Future` instead of blocking the current thread -* `await` - suspend execution until the result of a `Future` is ready -* `break` - exit a loop immediately -* `const` - define constant items or constant raw pointers -* `continue` - continue to the next loop iteration -* `crate` - in a module path, refers to the crate root -<!-- these days `crate` is mostly just used as part of the module path -/JT --> -<!-- fixed! /Carol --> - -* `dyn` - dynamic dispatch to a trait object -* `else` - fallback for `if` and `if let` control flow constructs -* `enum` - define an enumeration -* `extern` - link an external function or variable -<!-- `extern crate` is a bit out of date -/JT --> -<!-- fixed! /Carol --> - -* `false` - Boolean false literal -* `fn` - define a function or the function pointer type -* `for` - loop over items from an iterator, implement a trait, or specify a - higher-ranked lifetime -* `if` - branch based on the result of a conditional expression -* `impl` - implement inherent or trait functionality -* `in` - part of `for` loop syntax -* `let` - bind a variable -* `loop` - loop unconditionally -* `match` - match a value to patterns -* `mod` - define a module -* `move` - make a closure take ownership of all its captures -* `mut` - denote mutability in references, raw pointers, or pattern bindings -* `pub` - denote public visibility in struct fields, `impl` blocks, or modules -* `ref` - bind by reference -* `return` - return from function -* `Self` - a type alias for the type we are defining or implementing -* `self` - method subject or current module -* `static` - global variable or lifetime lasting the entire program execution -* `struct` - define a structure -* `super` - parent module of the current module -* `trait` - define a trait -* `true` - Boolean true literal -* `type` - define a type alias or associated type -* `union` - define a union; is only a keyword when used in a union declaration -* `unsafe` - denote unsafe code, functions, traits, or implementations -* `use` - bring symbols into scope -* `where` - denote clauses that constrain a type -* `while` - loop conditionally based on the result of an expression - -### Keywords Reserved for Future Use +* **`as` **: perform primitive casting, disambiguate the specific trait +containing an item, or rename items in `use` statements +* **`async` **: return a `Future` instead of blocking the current thread +* **`await` **: suspend execution until the result of a `Future` is ready +* **`break` **: exit a loop immediately +* **`const` **: define constant items or constant raw pointers +* **`continue` **: continue to the next loop iteration +* **`crate` **: in a module path, refers to the crate root +* **`dyn` **: dynamic dispatch to a trait object +* **`else` **: fallback for `if` and `if let` control flow constructs +* **`enum` **: define an enumeration +* **`extern` **: link an external function or variable +* **`false` **: Boolean false literal +* **`fn` **: define a function or the function pointer type +* **`for` **: loop over items from an iterator, implement a trait, or specify a +higher-ranked lifetime +* **`if` **: branch based on the result of a conditional expression +* **`impl` **: implement inherent or trait functionality +* **`in` **: part of `for` loop syntax +* **`let` **: bind a variable +* **`loop` **: loop unconditionally +* **`match` **: match a value to patterns +* **`mod` **: define a module +* **`move` **: make a closure take ownership of all its captures +* **`mut` **: denote mutability in references, raw pointers, or pattern bindings +* **`pub` **: denote public visibility in struct fields, `impl` blocks, or +modules +* **`ref` **: bind by reference +* **`return` **: return from function +* **`Self` **: a type alias for the type we are defining or implementing +* **`self` **: method subject or current module +* **`static` **: global variable or lifetime lasting the entire program +execution +* **`struct` **: define a structure +* **`super` **: parent module of the current module +* **`trait` **: define a trait +* **`true` **: Boolean true literal +* **`type` **: define a type alias or associated type +* **`union` **: define a union; is a keyword only when used in a union +declaration +* **`unsafe` **: denote unsafe code, functions, traits, or implementations +* **`use` **: bring symbols into scope +* **`where` **: denote clauses that constrain a type +* **`while` **: loop conditionally based on the result of an expression + +## Keywords Reserved for Future Use The following keywords do not yet have any functionality but are reserved by -Rust for potential future use. +Rust for potential future use: * `abstract` * `become` @@ -94,7 +84,7 @@ Rust for potential future use. * `virtual` * `yield` -### Raw Identifiers +## Raw Identifiers *Raw identifiers* are the syntax that lets you use keywords where they wouldn’t normally be allowed. You use a raw identifier by prefixing a keyword with `r#`. @@ -145,10 +135,10 @@ choose identifier names, as well as lets us integrate with programs written in a language where these words aren’t keywords. In addition, raw identifiers allow you to use libraries written in a different Rust edition than your crate uses. For example, `try` isn’t a keyword in the 2015 edition but is in the 2018 -edition. If you depend on a library that’s written using the 2015 edition and -has a `try` function, you’ll need to use the raw identifier syntax, `r#try` in -this case, to call that function from your 2018 edition code. See Appendix E -for more information on editions. +and 2021 editions. If you depend on a library that is written using the 2015 +edition and has a `try` function, you’ll need to use the raw identifier syntax, +`r#try` in this case, to call that function from your 2021 edition code. See +Appendix E for more information on editions. ## Appendix B: Operators and Symbols @@ -156,7 +146,7 @@ This appendix contains a glossary of Rust’s syntax, including operators and other symbols that appear by themselves or in the context of paths, generics, trait bounds, macros, attributes, comments, tuples, and brackets. -### Operators +## Operators Table B-1 contains the operators in Rust, an example of how the operator would appear in context, a short explanation, and whether that operator is @@ -166,66 +156,72 @@ overload that operator is listed. Table B-1: Operators | Operator | Example | Explanation | Overloadable? | -|----------|---------|-------------|---------------| -| `!` | `ident!(...)`, `ident!{...}`, `ident![...]` | Macro expansion | | +|---|---|---|---| +| `!` | `ident!(...)`, `ident!{...}`, `ident![...]` | Macro expansion | | | `!` | `!expr` | Bitwise or logical complement | `Not` | | `!=` | `expr != expr` | Nonequality comparison | `PartialEq` | -| `%` | `expr % expr` | Arithmetic remainder | `Rem` | +| `% | `expr % expr` | Arithmetic remainder | `Rem` | | `%=` | `var %= expr` | Arithmetic remainder and assignment | `RemAssign` | -| `&` | `&expr`, `&mut expr` | Borrow | | -| `&` | `&type`, `&mut type`, `&'a type`, `&'a mut type` | Borrowed pointer type | | +| `& | `&expr`, `&mut expr` | Borrow | | +| `&` | `&type`, `&mut type`, `&'a type`, `&'a mut type` | Borrowed pointer +type | | | `&` | `expr & expr` | Bitwise AND | `BitAnd` | | `&=` | `var &= expr` | Bitwise AND and assignment | `BitAndAssign` | -| `&&` | `expr && expr` | Short-circuiting logical AND | | -| `*` | `expr * expr` | Arithmetic multiplication | `Mul` | -| `*=` | `var *= expr` | Arithmetic multiplication and assignment | `MulAssign` | +| `&&` | `expr && expr` | Short-circuiting logical AND | | +| `* | `expr * expr` | Arithmetic multiplication | `Mul` | +| `*=` | `var *= expr` | Arithmetic multiplication and assignment | `MulAssign` +| | `*` | `*expr` | Dereference | `Deref` | -| `*` | `*const type`, `*mut type` | Raw pointer | | -| `+` | `trait + trait`, `'a + trait` | Compound type constraint | | -| `+` | `expr + expr` | Arithmetic addition | `Add` | +| `*` | `*const type`, `*mut type | Raw pointer | | +| `+ | `trait + trait`, `'a + trait` | Compound type constraint | | +| `+ | `expr + expr` | Arithmetic addition | `Add` | | `+=` | `var += expr` | Arithmetic addition and assignment | `AddAssign` | -| `,` | `expr, expr` | Argument and element separator | | -| `-` | `- expr` | Arithmetic negation | `Neg` | -| `-` | `expr - expr` | Arithmetic subtraction | `Sub` | +| `,` | `expr, expr` | Argument and element separator | | +| `- | `- expr` | Arithmetic negation | `Neg` | +| `- | `expr - expr` | Arithmetic subtraction | `Sub` | | `-=` | `var -= expr` | Arithmetic subtraction and assignment | `SubAssign` | -| `->` | `fn(...) -> type`, <code>|...| -> type</code> | Function and closure return type | | -| `.` | `expr.ident` | Member access | | -| `..` | `..`, `expr..`, `..expr`, `expr..expr` | Right-exclusive range literal | `PartialOrd` | -| `..=` | `..=expr`, `expr..=expr` | Right-inclusive range literal | `PartialOrd` | -| `..` | `..expr` | Struct literal update syntax | | -| `..` | `variant(x, ..)`, `struct_type { x, .. }` | “And the rest†pattern binding | | -| `...` | `expr...expr` | (Deprecated, use `..=` instead) In a pattern: inclusive range pattern | | -| `/` | `expr / expr` | Arithmetic division | `Div` | +| `-> | `fn(...) -> type`, `|…| -> type` | Function and closure return type | | +| `. | `expr.ident` | Member access | | +| `..` | `..`, `expr..`, `..expr`, `expr..expr` | Right-exclusive range literal +| `PartialOrd` | +| `..=` | `..=expr`, `expr..=expr` | Right-inclusive range literal | +`PartialOrd` | +| `..` | `..expr` | Struct literal update syntax | | +| `..` | `variant(x, ..)`, `struct_type { x, .. }` | “And the rest†pattern +binding | | +| `...` | `expr...expr` | (Deprecated, use `..=` instead) In a pattern: +inclusive range pattern | | +| `/ | `expr / expr` | Arithmetic division | `Div` | | `/=` | `var /= expr` | Arithmetic division and assignment | `DivAssign` | -| `:` | `pat: type`, `ident: type` | Constraints | | -| `:` | `ident: expr` | Struct field initializer | | -| `:` | `'a: loop {...}` | Loop label | | -| `;` | `expr;` | Statement and item terminator | | -| `;` | `[...; len]` | Part of fixed-size array syntax | | +| `: | `pat: type`, `ident: type` | Constraints | | +| `:` | `ident: expr` | Struct field initializer | | +| `:` | `'a: loop {...}` | Loop label | | +| `; | `expr;` | Statement and item terminator | | +| `;` | `[...; len]` | Part of fixed-size array syntax | | | `<<` | `expr << expr` | Left-shift | `Shl` | | `<<=` | `var <<= expr` | Left-shift and assignment | `ShlAssign` | | `<` | `expr < expr` | Less than comparison | `PartialOrd` | | `<=` | `expr <= expr` | Less than or equal to comparison | `PartialOrd` | -| `=` | `var = expr`, `ident = type` | Assignment/equivalence | | +| `=` | `var = expr`, `ident = type` | Assignment/equivalence | | | `==` | `expr == expr` | Equality comparison | `PartialEq` | -| `=>` | `pat => expr` | Part of match arm syntax | | +| `=>` | `pat => expr` | Part of match arm syntax | | | `>` | `expr > expr` | Greater than comparison | `PartialOrd` | | `>=` | `expr >= expr` | Greater than or equal to comparison | `PartialOrd` | | `>>` | `expr >> expr` | Right-shift | `Shr` | | `>>=` | `var >>= expr` | Right-shift and assignment | `ShrAssign` | -| `@` | `ident @ pat` | Pattern binding | | +| `@ | `ident @ pat` | Pattern binding | | | `^` | `expr ^ expr` | Bitwise exclusive OR | `BitXor` | | `^=` | `var ^= expr` | Bitwise exclusive OR and assignment | `BitXorAssign` | -| <code>|</code> | <code>pat | pat</code> | Pattern alternatives | | -| <code>|</code> | <code>expr | expr</code> | Bitwise OR | `BitOr` | -| <code>|=</code> | <code>var |= expr</code> | Bitwise OR and assignment | `BitOrAssign` | -| <code>||</code> | <code>expr || expr</code> | Short-circuiting logical OR | | -| `?` | `expr?` | Error propagation | | +| `| | `pat | pat` | Pattern alternatives | | +| `|` | `expr | expr` | Bitwise OR | `BitOr` | +| `|=` | `var |= expr` | Bitwise OR and assignment | `BitOrAssign` | +| `||` | `expr || expr` | Short-circuiting logical OR | | +| `? | `expr?` | Error propagation | | -### Non-operator Symbols +## Non-operator Symbols -The following list contains all symbols that don’t function as operators; -that is, they don’t behave like a function or method call. +The following tables contain all symbols that don’t function as operators; that +is, they don’t behave like a function or method call. Table B-2 shows symbols that appear on their own and are valid in a variety of locations. @@ -233,18 +229,22 @@ locations. Table B-2: Stand-Alone Syntax | Symbol | Explanation | -|--------|-------------| -| `'ident` | Named lifetime or loop label | -| `...u8`, `...i32`, `...f64`, `...usize`, etc. | Numeric literal of specific type | -| `"..."` | String literal | -| `r"..."`, `r#"..."#`, `r##"..."##`, etc. | Raw string literal, escape characters not processed | -| `b"..."` | Byte string literal; constructs an array of bytes instead of a string | -| `br"..."`, `br#"..."#`, `br##"..."##`, etc. | Raw byte string literal, combination of raw and byte string literal | -| `'...'` | Character literal | -| `b'...'` | ASCII byte literal | -| <code>|...| expr</code> | Closure | -| `!` | Always empty bottom type for diverging functions | -| `_` | “Ignored†pattern binding; also used to make integer literals readable | +|---|---| +| `'ident | Named lifetime or loop label | +| `...u8`, `...i32`, `...f64`, `...usize`, and so on | Numeric literal of +specific type | +| `"..." | String literal | +| `r"..."`, `r#"..."#`, `r##"..."##`, and so on | Raw string literal; escape +characters not processed | +| `b"..."` | Byte string literal; constructs an array of bytes instead of a +string | +| `br"..."`, `br#"..."#`, `br##"..."##`, and so on | Raw byte string literal; +combination of raw and byte string literal | +| `'...' | Character literal | +| `b'...' | ASCII byte literal | +| `|…| expr | Closure | +| `! | Always-empty bottom type for diverging functions | +| `_ | “Ignored†pattern binding; also used to make integer literals readable | Table B-3 shows symbols that appear in the context of a path through the module hierarchy to an item. @@ -252,16 +252,23 @@ hierarchy to an item. Table B-3: Path-Related Syntax | Symbol | Explanation | -|--------|-------------| -| `ident::ident` | Namespace path | -| `::path` | Path relative to the crate root (i.e., an explicitly absolute path) | -| `self::path` | Path relative to the current module (i.e., an explicitly relative path). +|---|---| +| `ident::ident | Namespace path | +| `::path` | Path relative to the crate root (that is, an explicitly absolute +path) | +| `self::path` | Path relative to the current module (that is, an explicitly +relative path) | | `super::path` | Path relative to the parent of the current module | -| `type::ident`, `<type as trait>::ident` | Associated constants, functions, and types | -| `<type>::...` | Associated item for a type that cannot be directly named (e.g., `<&T>::...`, `<[T]>::...`, etc.) | -| `trait::method(...)` | Disambiguating a method call by naming the trait that defines it | -| `type::method(...)` | Disambiguating a method call by naming the type for which it’s defined | -| `<type as trait>::method(...)` | Disambiguating a method call by naming the trait and type | +| `type::ident`, `<type as trait>::ident | Associated constants, functions, and +types | +| `<type>::...` | Associated item for a type that cannot be directly named (for +example, `<&T>::...`, `<[T]>::...`, and so on) | +| `trait::method(...)` | Disambiguating a method call by naming the trait that +defines it | +| `type::method(...)` | Disambiguating a method call by naming the type for +which it’s defined | +| `<type as trait>::method(...)` | Disambiguating a method call by naming the +trait and type | Table B-4 shows symbols that appear in the context of using generic type parameters. @@ -269,15 +276,19 @@ parameters. Table B-4: Generics | Symbol | Explanation | -|--------|-------------| -| `path<...>` | Specifies parameters to generic type in a type (e.g., `Vec<u8>`) | -| `path::<...>`, `method::<...>` | Specifies parameters to generic type, function, or method in an expression; often referred to as turbofish (e.g., `"42".parse::<i32>()`) | +|---|---| +| `path<...>` | Specifies parameters to a generic type in a type (for example, +`Vec<u8>`) | +| `path::<...>, method::<...>` | Specifies parameters to a generic type, +function, or method in an expression; often referred to as turbofish (for +example, `"42".parse::<i32>()`) | | `fn ident<...> ...` | Define generic function | | `struct ident<...> ...` | Define generic structure | | `enum ident<...> ...` | Define generic enumeration | | `impl<...> ...` | Define generic implementation | | `for<...> type` | Higher-ranked lifetime bounds | -| `type<ident=type>` | A generic type where one or more associated types have specific assignments (e.g., `Iterator<Item=T>`) | +| `type<ident=type>` | A generic type where one or more associated types have +specific assignments (for example, `Iterator<Item=T>`) | Table B-5 shows symbols that appear in the context of constraining generic type parameters with trait bounds. @@ -285,10 +296,12 @@ parameters with trait bounds. Table B-5: Trait Bound Constraints | Symbol | Explanation | -|--------|-------------| -| `T: U` | Generic parameter `T` constrained to types that implement `U` | -| `T: 'a` | Generic type `T` must outlive lifetime `'a` (meaning the type cannot transitively contain any references with lifetimes shorter than `'a`) | -| `T: 'static` | Generic type `T` contains no borrowed references other than `'static` ones | +|---|---| +| T: U` | Generic parameter `T` constrained to types that implement `U` | +| `T: 'a` | Generic type `T` must outlive lifetime `'a` (meaning the type +cannot transitively contain any references with lifetimes shorter than `'a`) | +| `T: 'static` | Generic type `T` contains no borrowed references other than +`'static` ones | | `'b: 'a` | Generic lifetime `'b` must outlive lifetime `'a` | | `T: ?Sized` | Allow generic type parameter to be a dynamically sized type | | `'a + trait`, `trait + trait` | Compound type constraint | @@ -299,7 +312,7 @@ macros and specifying attributes on an item. Table B-6: Macros and Attributes | Symbol | Explanation | -|--------|-------------| +|---|---| | `#[meta]` | Outer attribute | | `#![meta]` | Inner attribute | | `$ident` | Macro substitution | @@ -312,7 +325,7 @@ Table B-7 shows symbols that create comments. Table B-7: Comments | Symbol | Explanation | -|--------|-------------| +|---|---| | `//` | Line comment | | `//!` | Inner line doc comment | | `///` | Outer line doc comment | @@ -325,22 +338,23 @@ Table B-8 shows symbols that appear in the context of using tuples. Table B-8: Tuples | Symbol | Explanation | -|--------|-------------| -| `()` | Empty tuple (aka unit), both literal and type | +|---|---| +| `() | Empty tuple (aka unit), both literal and type | | `(expr)` | Parenthesized expression | | `(expr,)` | Single-element tuple expression | | `(type,)` | Single-element tuple type | | `(expr, ...)` | Tuple expression | | `(type, ...)` | Tuple type | -| `expr(expr, ...)` | Function call expression; also used to initialize tuple `struct`s and tuple `enum` variants | -| `expr.0`, `expr.1`, etc. | Tuple indexing | +| `expr(expr, ...)` | Function call expression; also used to initialize tuple +`struct`s and tuple `enum` variants | +| `expr.0`, `expr.1`, and so on | Tuple indexing | -Table B-9 shows the contexts in which curly braces are used. +Table B-9 shows the contexts in which curly brackets are used. Table B-9: Curly Brackets | Context | Explanation | -|---------|-------------| +|---|---| | `{...}` | Block expression | | `Type {...}` | `struct` literal | @@ -349,12 +363,14 @@ Table B-10 shows the contexts in which square brackets are used. Table B-10: Square Brackets | Context | Explanation | -|---------|-------------| +|---|---| | `[...]` | Array literal | | `[expr; len]` | Array literal containing `len` copies of `expr` | | `[type; len]` | Array type containing `len` instances of `type` | -| `expr[expr]` | Collection indexing. Overloadable (`Index`, `IndexMut`) | -| `expr[..]`, `expr[a..]`, `expr[..b]`, `expr[a..b]` | Collection indexing pretending to be collection slicing, using `Range`, `RangeFrom`, `RangeTo`, or `RangeFull` as the “index†| +| `expr[expr]` | Collection indexing; overloadable (`Index`, `IndexMut`) | +| `expr[..]`, `expr[a..]`, `expr[..b]`, `expr[a..b]` | Collection indexing +pretending to be collection slicing, using `Range`, `RangeFrom`, `RangeTo`, or +`RangeFull` as the “index†| ## Appendix C: Derivable Traits @@ -373,14 +389,13 @@ library that you can use with `derive`. Each section covers: * Examples of operations that require the trait If you want different behavior from that provided by the `derive` attribute, -consult the standard library documentation for each trait for details of how to +consult the standard library documentation for each trait for details on how to manually implement them. -These traits listed here are the only ones defined by the standard library that -can be implemented on your types using `derive`. -Other traits defined in the standard library don’t have sensible default -behavior, so it’s up to you to implement them in the way that makes sense for -what you’re trying to accomplish. +The traits listed here are the only ones defined by the standard library that +can be implemented on your types using `derive`. Other traits defined in the +standard library don’t have sensible default behavior, so it’s up to you to +implement them in the way that makes sense for what you’re trying to accomplish. An example of a trait that can’t be derived is `Display`, which handles formatting for end users. You should always consider the appropriate way to @@ -391,11 +406,10 @@ it can’t provide appropriate default behavior for you. The list of derivable traits provided in this appendix is not comprehensive: libraries can implement `derive` for their own traits, making the list of -traits you can use `derive` with truly open-ended. Implementing `derive` -involves using a procedural macro, which is covered in the -“Macros†section of Chapter 19. +traits you can use `derive` with truly open ended. Implementing `derive` +involves using a procedural macro, which is covered in “Macros†on page XX. -### `Debug` for Programmer Output +## Debug for Programmer Output The `Debug` trait enables debug formatting in format strings, which you indicate by adding `:?` within `{}` placeholders. @@ -404,11 +418,12 @@ The `Debug` trait allows you to print instances of a type for debugging purposes, so you and other programmers using your type can inspect an instance at a particular point in a program’s execution. -The `Debug` trait is required, for example, in use of the `assert_eq!` macro. -This macro prints the values of instances given as arguments if the equality -assertion fails so programmers can see why the two instances weren’t equal. +The `Debug` trait is required, for example, in the use of the `assert_eq!` +macro. This macro prints the values of instances given as arguments if the +equality assertion fails so programmers can see why the two instances weren’t +equal. -### `PartialEq` and `Eq` for Equality Comparisons +## PartialEq and Eq for Equality Comparisons The `PartialEq` trait allows you to compare instances of a type to check for equality and enables use of the `==` and `!=` operators. @@ -425,14 +440,14 @@ for equality. The `Eq` trait has no methods. Its purpose is to signal that for every value of the annotated type, the value is equal to itself. The `Eq` trait can only be applied to types that also implement `PartialEq`, although not all types that -implement `PartialEq` can implement `Eq`. One example of this is floating point -number types: the implementation of floating point numbers states that two +implement `PartialEq` can implement `Eq`. One example of this is floating-point +number types: the implementation of floating-point numbers states that two instances of the not-a-number (`NaN`) value are not equal to each other. -An example of when `Eq` is required is for keys in a `HashMap<K, V>` so the -`HashMap<K, V>` can tell whether two keys are the same. +An example of when `Eq` is required is for keys in a `HashMap<K, V>` so that +the `HashMap<K, V>` can tell whether two keys are the same. -### `PartialOrd` and `Ord` for Ordering Comparisons +## PartialOrd and Ord for Ordering Comparisons The `PartialOrd` trait allows you to compare instances of a type for sorting purposes. A type that implements `PartialOrd` can be used with the `<`, `>`, @@ -443,8 +458,8 @@ Deriving `PartialOrd` implements the `partial_cmp` method, which returns an `Option<Ordering>` that will be `None` when the values given don’t produce an ordering. An example of a value that doesn’t produce an ordering, even though most values of that type can be compared, is the not-a-number (`NaN`) floating -point value. Calling `partial_cmp` with any floating point number and the `NaN` -floating point value will return `None`. +point value. Calling `partial_cmp` with any floating-point number and the `NaN` +floating-point value will return `None`. When derived on structs, `PartialOrd` compares two instances by comparing the value in each field in the order in which the fields appear in the struct @@ -466,12 +481,12 @@ implementation for `partial_cmp` does with `PartialOrd`. An example of when `Ord` is required is when storing values in a `BTreeSet<T>`, a data structure that stores data based on the sort order of the values. -### `Clone` and `Copy` for Duplicating Values +## Clone and Copy for Duplicating Values The `Clone` trait allows you to explicitly create a deep copy of a value, and the duplication process might involve running arbitrary code and copying heap -data. See the “Ways Variables and Data Interact: Clone†section in Chapter 4 -for more information on `Clone`. +data. See “Variables and Data Interacting with Clone†on page XX for more +information on `Clone`. Deriving `Clone` implements the `clone` method, which when implemented for the whole type, calls `clone` on each of the parts of the type. This means all the @@ -480,11 +495,11 @@ fields or values in the type must also implement `Clone` to derive `Clone`. An example of when `Clone` is required is when calling the `to_vec` method on a slice. The slice doesn’t own the type instances it contains, but the vector returned from `to_vec` will need to own its instances, so `to_vec` calls -`clone` on each item. Thus, the type stored in the slice must implement `Clone`. +`clone` on each item. Thus the type stored in the slice must implement `Clone`. The `Copy` trait allows you to duplicate a value by only copying bits stored on -the stack; no arbitrary code is necessary. See the “Stack-Only Data: Copy†-section in Chapter 4 for more information on `Copy`. +the stack; no arbitrary code is necessary. See “Stack-Only Data: Copy†on page +XX for more information on `Copy`. The `Copy` trait doesn’t define any methods to prevent programmers from overloading those methods and violating the assumption that no arbitrary code @@ -492,7 +507,7 @@ is being run. That way, all programmers can assume that copying a value will be very fast. You can derive `Copy` on any type whose parts all implement `Copy`. A type that -implements `Copy` must also implement `Clone`, because a type that implements +implements `Copy` must also implement `Clone` because a type that implements `Copy` has a trivial implementation of `Clone` that performs the same task as `Copy`. @@ -503,7 +518,7 @@ the code more concise. Everything possible with `Copy` you can also accomplish with `Clone`, but the code might be slower or have to use `clone` in places. -### `Hash` for Mapping a Value to a Value of Fixed Size +## Hash for Mapping a Value to a Value of Fixed Size The `Hash` trait allows you to take an instance of a type of arbitrary size and map that instance to a value of fixed size using a hash function. Deriving @@ -514,7 +529,7 @@ meaning all fields or values must also implement `Hash` to derive `Hash`. An example of when `Hash` is required is in storing keys in a `HashMap<K, V>` to store data efficiently. -### `Default` for Default Values +## Default for Default Values The `Default` trait allows you to create a default value for a type. Deriving `Default` implements the `default` function. The derived implementation of the @@ -523,9 +538,9 @@ meaning all fields or values in the type must also implement `Default` to derive `Default`. The `Default::default` function is commonly used in combination with the struct -update syntax discussed in the “Creating Instances From Other Instances With -Struct Update Syntax†section in Chapter 5. You can customize a few fields of a -struct and then set and use a default value for the rest of the fields by using +update syntax discussed in “Creating Instances from Other Instances with Struct +Update Syntax†on page XX. You can customize a few fields of a struct and then +set and use a default value for the rest of the fields by using `..Default::default()`. The `Default` trait is required when you use the method `unwrap_or_default` on @@ -533,26 +548,23 @@ The `Default` trait is required when you use the method `unwrap_or_default` on `unwrap_or_default` will return the result of `Default::default` for the type `T` stored in the `Option<T>`. -## Appendix D - Useful Development Tools +## Appendix D: Useful Development Tools In this appendix, we talk about some useful development tools that the Rust project provides. We’ll look at automatic formatting, quick ways to apply warning fixes, a linter, and integrating with IDEs. -### Automatic Formatting with `rustfmt` +## Automatic Formatting with rustfmt The `rustfmt` tool reformats your code according to the community code style. Many collaborative projects use `rustfmt` to prevent arguments about which style to use when writing Rust: everyone formats their code using the tool. -To install `rustfmt`, enter the following: - -``` -$ rustup component add rustfmt -``` - -This command gives you `rustfmt` and `cargo-fmt`, similar to how Rust gives you -both `rustc` and `cargo`. To format any Cargo project, enter the following: +Rust installations include `rustfmt` by default, so you should already have the +programs `rustfmt` and `cargo-fmt` on your system. These two commands are +analagous to `rustc` and `cargo` in that `rustfmt` allows finer-grained control +and `cargo-fmt` understands conventions of a project that uses Cargo. To format +any Cargo project, enter the following: ``` $ cargo fmt @@ -562,13 +574,12 @@ Running this command reformats all the Rust code in the current crate. This should only change the code style, not the code semantics. For more information on `rustfmt`, see its documentation at *https://github.com/rust-lang/rustfmt*. +## Fix Your Code with rustfix -### Fix Your Code with `rustfix` - -The rustfix tool is included with Rust installations and can automatically fix -compiler warnings that have a clear way to correct the problem that’s likely -what you want. It’s likely you’ve seen compiler warnings before. For example, -consider this code: +The `rustfix` tool is included with Rust installations and can automatically +fix compiler warnings that have a clear way to correct the problem that’s +likely what you want. You’ve probably seen compiler warnings before. For +example, consider this code: Filename: src/main.rs @@ -631,16 +642,11 @@ The `for` loop variable is now named `_i`, and the warning no longer appears. You can also use the `cargo fix` command to transition your code between different Rust editions. Editions are covered in Appendix E. -### More Lints with Clippy +## More Lints with Clippy The Clippy tool is a collection of lints to analyze your code so you can catch -common mistakes and improve your Rust code. - -To install Clippy, enter the following: - -``` -$ rustup component add clippy -``` +common mistakes and improve your Rust code. Clippy is included with standard +Rust installations. To run Clippy’s lints on any Cargo project, enter the following: @@ -664,14 +670,16 @@ fn main() { Running `cargo clippy` on this project results in this error: ``` -error: approximate value of `f{32, 64}::consts::PI` found. Consider using it directly +error: approximate value of `f{32, 64}::consts::PI` found --> src/main.rs:2:13 | 2 | let x = 3.1415; | ^^^^^^ | - = note: #[deny(clippy::approx_constant)] on by default - = help: for further information visit https://rust-lang-nursery.github.io/rust-clippy/master/index.html#approx_constant + = note: `#[deny(clippy::approx_constant)]` on by default + = help: consider using the constant directly + = help: for further information visit https://rust-lang.github.io/rust- +clippy/master/index.html#approx_constant ``` This error lets you know that Rust already has a more precise `PI` constant @@ -690,23 +698,24 @@ fn main() { } ``` -For more information on Clippy, see its documentation at *https://github.com/rust-lang/rust-clippy*. +For more information on Clippy, see its documentation at +*https://github.com/rust-lang/rust-clippy**.* -### IDE Integration Using `rust-analyzer` +## IDE Integration Using rust-analyzer -To help IDE integration, the Rust community recommends using `rust-analyzer`. -This tool is a set of compiler-centric utilities that speaks the Language -Server Protocol, which is a specification for IDEs and programming languages to -communicate with each other. Different clients can use `rust-analyzer`, such as -the Rust analyzer plug-in for Visual Studio Code at +To help with IDE integration, the Rust community recommends using +`rust-analyzer`. This tool is a set of compiler-centric utilities that speak +Language Server Protocol, which is a specification for IDEs and programming +languages to communicate with each other. Different clients can use +`rust-analyzer`, such as the Rust analyzer plug-in for Visual Studio Code at *https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer*. Visit the `rust-analyzer` project’s home page at *https://rust-analyzer.github.io* for installation instructions, then install the language server support in your particular IDE. Your IDE will gain -abilities such as autocompletion, jump to definition, and inline errors. +capabilities such as autocompletion, jump to definition, and inline errors -## Appendix E - Editions +## Appendix E: Editions In Chapter 1, you saw that `cargo new` adds a bit of metadata to your *Cargo.toml* file about an edition. This appendix talks about what that means! @@ -726,11 +735,11 @@ six-week release process. Editions serve different purposes for different people: * For active Rust users, a new edition brings together incremental changes into - an easy-to-understand package. +an easy-to-understand package. * For non-users, a new edition signals that some major advancements have - landed, which might make Rust worth another look. +landed, which might make Rust worth another look. * For those developing Rust, a new edition provides a rallying point for the - project as a whole. +project as a whole. At the time of this writing, three Rust editions are available: Rust 2015, Rust 2018, and Rust 2021. This book is written using Rust 2021 edition idioms. @@ -759,7 +768,8 @@ made. However, in some cases, mainly when new keywords are added, some new features might only be available in later editions. You will need to switch editions if you want to take advantage of such features. -For more details, the *Edition -Guide* at *https://doc.rust-lang.org/stable/edition-guide/* is a complete book -about editions that enumerates the differences between editions and explains -how to automatically upgrade your code to a new edition via `cargo fix`. +For more details, *The* *Edition Guide* at +*https://doc.rust-lang.org/stable/edition-guide* is a complete book about +editions that enumerates the differences between editions and explains how to +automatically upgrade your code to a new edition via `cargo fix`. + diff --git a/src/doc/book/nostarch/appendix_a.md b/src/doc/book/nostarch/appendix_a.md new file mode 100644 index 000000000..ca3883be4 --- /dev/null +++ b/src/doc/book/nostarch/appendix_a.md @@ -0,0 +1,142 @@ +<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +--> + +[TOC] + +## Appendix A: Keywords + +The following lists contain keywords that are reserved for current or future +use by the Rust language. As such, they cannot be used as identifiers (except +as raw identifiers, as we’ll discuss in “Raw Identifiers†on page XX). +*Identifiers* are names of functions, variables, parameters, struct fields, +modules, crates, constants, macros, static values, attributes, types, traits, +or lifetimes. + +## Keywords Currently in Use + +The following is a list of keywords currently in use, with their functionality +described. + +* **`as` **: perform primitive casting, disambiguate the specific trait +containing an item, or rename items in `use` statements +* **`async` **: return a `Future` instead of blocking the current thread +* **`await` **: suspend execution until the result of a `Future` is ready +* **`break` **: exit a loop immediately +* **`const` **: define constant items or constant raw pointers +* **`continue` **: continue to the next loop iteration +* **`crate` **: in a module path, refers to the crate root +* **`dyn` **: dynamic dispatch to a trait object +* **`else` **: fallback for `if` and `if let` control flow constructs +* **`enum` **: define an enumeration +* **`extern` **: link an external function or variable +* **`false` **: Boolean false literal +* **`fn` **: define a function or the function pointer type +* **`for` **: loop over items from an iterator, implement a trait, or specify a +higher-ranked lifetime +* **`if` **: branch based on the result of a conditional expression +* **`impl` **: implement inherent or trait functionality +* **`in` **: part of `for` loop syntax +* **`let` **: bind a variable +* **`loop` **: loop unconditionally +* **`match` **: match a value to patterns +* **`mod` **: define a module +* **`move` **: make a closure take ownership of all its captures +* **`mut` **: denote mutability in references, raw pointers, or pattern bindings +* **`pub` **: denote public visibility in struct fields, `impl` blocks, or +modules +* **`ref` **: bind by reference +* **`return` **: return from function +* **`Self` **: a type alias for the type we are defining or implementing +* **`self` **: method subject or current module +* **`static` **: global variable or lifetime lasting the entire program +execution +* **`struct` **: define a structure +* **`super` **: parent module of the current module +* **`trait` **: define a trait +* **`true` **: Boolean true literal +* **`type` **: define a type alias or associated type +* **`union` **: define a union; is a keyword only when used in a union +declaration +* **`unsafe` **: denote unsafe code, functions, traits, or implementations +* **`use` **: bring symbols into scope +* **`where` **: denote clauses that constrain a type +* **`while` **: loop conditionally based on the result of an expression + +## Keywords Reserved for Future Use + +The following keywords do not yet have any functionality but are reserved by +Rust for potential future use: + +* `abstract` +* `become` +* `box` +* `do` +* `final` +* `macro` +* `override` +* `priv` +* `try` +* `typeof` +* `unsized` +* `virtual` +* `yield` + +## Raw Identifiers + +*Raw identifiers* are the syntax that lets you use keywords where they wouldn’t +normally be allowed. You use a raw identifier by prefixing a keyword with `r#`. + +For example, `match` is a keyword. If you try to compile the following function +that uses `match` as its name: + +Filename: src/main.rs + +``` +fn match(needle: &str, haystack: &str) -> bool { + haystack.contains(needle) +} +``` + +you’ll get this error: + +``` +error: expected identifier, found keyword `match` + --> src/main.rs:4:4 + | +4 | fn match(needle: &str, haystack: &str) -> bool { + | ^^^^^ expected identifier, found keyword +``` + +The error shows that you can’t use the keyword `match` as the function +identifier. To use `match` as a function name, you need to use the raw +identifier syntax, like this: + +Filename: src/main.rs + +``` +fn r#match(needle: &str, haystack: &str) -> bool { + haystack.contains(needle) +} + +fn main() { + assert!(r#match("foo", "foobar")); +} +``` + +This code will compile without any errors. Note the `r#` prefix on the function +name in its definition as well as where the function is called in `main`. + +Raw identifiers allow you to use any word you choose as an identifier, even if +that word happens to be a reserved keyword. This gives us more freedom to +choose identifier names, as well as lets us integrate with programs written in +a language where these words aren’t keywords. In addition, raw identifiers +allow you to use libraries written in a different Rust edition than your crate +uses. For example, `try` isn’t a keyword in the 2015 edition but is in the 2018 +and 2021 editions. If you depend on a library that is written using the 2015 +edition and has a `try` function, you’ll need to use the raw identifier syntax, +`r#try` in this case, to call that function from your 2021 edition code. See +Appendix E for more information on editions. + diff --git a/src/doc/book/nostarch/appendix_b.md b/src/doc/book/nostarch/appendix_b.md new file mode 100644 index 000000000..236608b6d --- /dev/null +++ b/src/doc/book/nostarch/appendix_b.md @@ -0,0 +1,241 @@ +<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +--> + +[TOC] + +## Appendix B: Operators and Symbols + +This appendix contains a glossary of Rust’s syntax, including operators and +other symbols that appear by themselves or in the context of paths, generics, +trait bounds, macros, attributes, comments, tuples, and brackets. + +## Operators + +Table B-1 contains the operators in Rust, an example of how the operator would +appear in context, a short explanation, and whether that operator is +overloadable. If an operator is overloadable, the relevant trait to use to +overload that operator is listed. + +Table B-1: Operators + +| Operator | Example | Explanation | Overloadable? | +|---|---|---|---| +| `!` | `ident!(...)`, `ident!{...}`, `ident![...]` | Macro expansion | | +| `!` | `!expr` | Bitwise or logical complement | `Not` | +| `!=` | `expr != expr` | Nonequality comparison | `PartialEq` | +| `%` | `expr % expr` | Arithmetic remainder | `Rem` | +| `%=` | `var %= expr` | Arithmetic remainder and assignment | `RemAssign` | +| `&` | `&expr`, `&mut expr` | Borrow | | +| `&` | `&type`, `&mut type`, `&'a type`, `&'a mut type` | Borrowed pointer +type | | +| `&` | `expr & expr` | Bitwise AND | `BitAnd` | +| `&=` | `var &= expr` | Bitwise AND and assignment | `BitAndAssign` | +| `&&` | `expr && expr` | Short-circuiting logical AND | | +| `*` | `expr * expr` | Arithmetic multiplication | `Mul` | +| `*=` | `var *= expr` | Arithmetic multiplication and assignment | `MulAssign` +| +| `*` | `*expr` | Dereference | `Deref` | +| `*` | `*const type`, `*mut type` | Raw pointer | | +| `+` | `trait + trait`, `'a + trait` | Compound type constraint | | +| `+` | `expr + expr` | Arithmetic addition | `Add` | +| `+=` | `var += expr` | Arithmetic addition and assignment | `AddAssign` | +| `,` | `expr, expr` | Argument and element separator | | +| `-` | `- expr` | Arithmetic negation | `Neg` | +| `-` | `expr - expr` | Arithmetic subtraction | `Sub` | +| `-=` | `var -= expr` | Arithmetic subtraction and assignment | `SubAssign` | +| `->` | `fn(...) -> type`, `|…| -> type` | Function and closure return type | +| +| `. | `expr.ident` | Member access | | +| `..` | `..`, `expr..`, `..expr`, `expr..expr` | Right-exclusive range literal +| `PartialOrd` | +| `..=` | `..=expr`, `expr..=expr` | Right-inclusive range literal | +`PartialOrd` | +| `..` | `..expr` | Struct literal update syntax | | +| `..` | `variant(x, ..)`, `struct_type { x, .. }` | “And the rest†pattern +binding | | +| `...` | `expr...expr` | (Deprecated, use `..=` instead) In a pattern: +inclusive range pattern | | +| `/` | `expr / expr` | Arithmetic division | `Div` | +| `/=` | `var /= expr` | Arithmetic division and assignment | `DivAssign` | +| `: | `pat: type`, `ident: type` | Constraints | | +| `:` | `ident: expr` | Struct field initializer | | +| `:` | `'a: loop {...}` | Loop label | | +| `;` | `expr;` | Statement and item terminator | | +| `;` | `[...; len]` | Part of fixed-size array syntax | | +| `<<` | `expr << expr` | Left-shift | `Shl` | +| `<<=` | `var <<= expr` | Left-shift and assignment | `ShlAssign` | +| `<` | `expr < expr` | Less than comparison | `PartialOrd` | +| `<=` | `expr <= expr` | Less than or equal to comparison | `PartialOrd` | +| `=` | `var = expr`, `ident = type` | Assignment/equivalence | | +| `==` | `expr == expr` | Equality comparison | `PartialEq` | +| `=>` | `pat => expr` | Part of match arm syntax | | +| `>` | `expr > expr` | Greater than comparison | `PartialOrd` | +| `>=` | `expr >= expr` | Greater than or equal to comparison | `PartialOrd` | +| `>>` | `expr >> expr` | Right-shift | `Shr` | +| `>>=` | `var >>= expr` | Right-shift and assignment | `ShrAssign` | +| `@` | `ident @ pat` | Pattern binding | | +| `^` | `expr ^ expr` | Bitwise exclusive OR | `BitXor` | +| `^=` | `var ^= expr` | Bitwise exclusive OR and assignment | `BitXorAssign` | +| `|` | `pat | pat` | Pattern alternatives | | +| `|` | `expr | expr` | Bitwise OR | `BitOr` | +| `|=` | `var |= expr` | Bitwise OR and assignment | `BitOrAssign` | +| `||` | `expr || expr` | Short-circuiting logical OR | | +| `?` | `expr?` | Error propagation | | + +## Non-operator Symbols + +The following tables contain all symbols that don’t function as operators; that +is, they don’t behave like a function or method call. + +Table B-2 shows symbols that appear on their own and are valid in a variety of +locations. + +Table B-2: Stand-Alone Syntax + +| Symbol | Explanation | +|---|---| +| `'ident` | Named lifetime or loop label | +| `...u8`, `...i32`, `...f64`, `...usize`, and so on | Numeric literal of +specific type | +| `"..."` | String literal | +| `r"..."`, `r#"..."#`, `r##"..."##`, and so on | Raw string literal; escape +characters not processed | +| `b"..."` | Byte string literal; constructs an array of bytes instead of a +string | +| `br"..."`, `br#"..."#`, `br##"..."##`, and so on | Raw byte string literal; +combination of raw and byte string literal | +| `'...'` | Character literal | +| `b'...'` | ASCII byte literal | +| `|…| expr` | Closure | +| `!` | Always-empty bottom type for diverging functions | +| `_` | “Ignored†pattern binding; also used to make integer literals readable | + +Table B-3 shows symbols that appear in the context of a path through the module +hierarchy to an item. + +Table B-3: Path-Related Syntax + +| Symbol | Explanation | +|---|---| +| `ident::ident` | Namespace path | +| `::path` | Path relative to the crate root (that is, an explicitly absolute +path) | +| `self::path` | Path relative to the current module (that is, an explicitly +relative path) | +| `super::path` | Path relative to the parent of the current module | +| `type::ident`, `<type as trait>::ident` | Associated constants, functions, +and types | +| `<type>::...` | Associated item for a type that cannot be directly named (for +example, `<&T>::...`, `<[T]>::...`, and so on) | +| `trait::method(...)` | Disambiguating a method call by naming the trait that +defines it | +| `type::method(...)` | Disambiguating a method call by naming the type for +which it’s defined | +| `<type as trait>::method(...)` | Disambiguating a method call by naming the +trait and type | + +Table B-4 shows symbols that appear in the context of using generic type +parameters. + +Table B-4: Generics + +| Symbol | Explanation | +|---|---| +| `path<...>` | Specifies parameters to a generic type in a type (for example, +`Vec<u8>`) | +| `path::<...>, method::<...>` | Specifies parameters to a generic type, +function, or method in an expression; often referred to as turbofish (for +example, `"42".parse::<i32>()`) | +| `fn ident<...> ...` | Define generic function | +| `struct ident<...> ...` | Define generic structure | +| `enum ident<...> ...` | Define generic enumeration | +| `impl<...> ...` | Define generic implementation | +| `for<...> type` | Higher-ranked lifetime bounds | +| `type<ident=type>` | A generic type where one or more associated types have +specific assignments (for example, `Iterator<Item=T>`) | + +Table B-5 shows symbols that appear in the context of constraining generic type +parameters with trait bounds. + +Table B-5: Trait Bound Constraints + +| Symbol | Explanation | +|---|---| +| T: U` | Generic parameter `T` constrained to types that implement `U` | +| `T: 'a` | Generic type `T` must outlive lifetime `'a` (meaning the type +cannot transitively contain any references with lifetimes shorter than `'a`) | +| `T: 'static` | Generic type `T` contains no borrowed references other than +`'static` ones | +| `'b: 'a` | Generic lifetime `'b` must outlive lifetime `'a` | +| `T: ?Sized` | Allow generic type parameter to be a dynamically sized type | +| `'a + trait`, `trait + trait` | Compound type constraint | + +Table B-6 shows symbols that appear in the context of calling or defining +macros and specifying attributes on an item. + +Table B-6: Macros and Attributes + +| Symbol | Explanation | +|---|---| +| `#[meta]` | Outer attribute | +| `#![meta]` | Inner attribute | +| `$ident` | Macro substitution | +| `$ident:kind` | Macro capture | +| `$(…)…` | Macro repetition | +| `ident!(...)`, `ident!{...}`, `ident![...]` | Macro invocation | + +Table B-7 shows symbols that create comments. + +Table B-7: Comments + +| Symbol | Explanation | +|---|---| +| `//` | Line comment | +| `//!` | Inner line doc comment | +| `///` | Outer line doc comment | +| `/*...*/` | Block comment | +| `/*!...*/` | Inner block doc comment | +| `/**...*/` | Outer block doc comment | + +Table B-8 shows symbols that appear in the context of using tuples. + +Table B-8: Tuples + +| Symbol | Explanation | +|---|---| +| `()` | Empty tuple (aka unit), both literal and type | +| `(expr)` | Parenthesized expression | +| `(expr,)` | Single-element tuple expression | +| `(type,)` | Single-element tuple type | +| `(expr, ...)` | Tuple expression | +| `(type, ...)` | Tuple type | +| `expr(expr, ...)` | Function call expression; also used to initialize tuple +`struct`s and tuple `enum` variants | +| `expr.0`, `expr.1`, and so on | Tuple indexing | + +Table B-9 shows the contexts in which curly brackets are used. + +Table B-9: Curly Brackets + +| Context | Explanation | +|---|---| +| `{...}` | Block expression | +| `Type {...}` | `struct` literal | + +Table B-10 shows the contexts in which square brackets are used. + +Table B-10: Square Brackets + +| Context | Explanation | +|---|---| +| `[...]` | Array literal | +| `[expr; len]` | Array literal containing `len` copies of `expr` | +| `[type; len]` | Array type containing `len` instances of `type` | +| `expr[expr]` | Collection indexing; overloadable (`Index`, `IndexMut`) | +| `expr[..]`, `expr[a..]`, `expr[..b]`, `expr[a..b]` | Collection indexing +pretending to be collection slicing, using `Range`, `RangeFrom`, `RangeTo`, or +`RangeFull` as the “index†| + diff --git a/src/doc/book/nostarch/appendix_c.md b/src/doc/book/nostarch/appendix_c.md new file mode 100644 index 000000000..53131eb5f --- /dev/null +++ b/src/doc/book/nostarch/appendix_c.md @@ -0,0 +1,184 @@ +<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +--> + +[TOC] + +## Appendix C: Derivable Traits + +In various places in the book, we’ve discussed the `derive` attribute, which +you can apply to a struct or enum definition. The `derive` attribute generates +code that will implement a trait with its own default implementation on the +type you’ve annotated with the `derive` syntax. + +In this appendix, we provide a reference of all the traits in the standard +library that you can use with `derive`. Each section covers: + +* What operators and methods deriving this trait will enable +* What the implementation of the trait provided by `derive` does +* What implementing the trait signifies about the type +* The conditions in which you’re allowed or not allowed to implement the trait +* Examples of operations that require the trait + +If you want different behavior from that provided by the `derive` attribute, +consult the standard library documentation for each trait for details on how to +manually implement them. + +The traits listed here are the only ones defined by the standard library that +can be implemented on your types using `derive`. Other traits defined in the +standard library don’t have sensible default behavior, so it’s up to you to +implement them in the way that makes sense for what you’re trying to accomplish. + +An example of a trait that can’t be derived is `Display`, which handles +formatting for end users. You should always consider the appropriate way to +display a type to an end user. What parts of the type should an end user be +allowed to see? What parts would they find relevant? What format of the data +would be most relevant to them? The Rust compiler doesn’t have this insight, so +it can’t provide appropriate default behavior for you. + +The list of derivable traits provided in this appendix is not comprehensive: +libraries can implement `derive` for their own traits, making the list of +traits you can use `derive` with truly open ended. Implementing `derive` +involves using a procedural macro, which is covered in “Macros†on page XX. + +## Debug for Programmer Output + +The `Debug` trait enables debug formatting in format strings, which you +indicate by adding `:?` within `{}` placeholders. + +The `Debug` trait allows you to print instances of a type for debugging +purposes, so you and other programmers using your type can inspect an instance +at a particular point in a program’s execution. + +The `Debug` trait is required, for example, in the use of the `assert_eq!` +macro. This macro prints the values of instances given as arguments if the +equality assertion fails so programmers can see why the two instances weren’t +equal. + +## PartialEq and Eq for Equality Comparisons + +The `PartialEq` trait allows you to compare instances of a type to check for +equality and enables use of the `==` and `!=` operators. + +Deriving `PartialEq` implements the `eq` method. When `PartialEq` is derived on +structs, two instances are equal only if *all* fields are equal, and the +instances are not equal if any fields are not equal. When derived on enums, +each variant is equal to itself and not equal to the other variants. + +The `PartialEq` trait is required, for example, with the use of the +`assert_eq!` macro, which needs to be able to compare two instances of a type +for equality. + +The `Eq` trait has no methods. Its purpose is to signal that for every value of +the annotated type, the value is equal to itself. The `Eq` trait can only be +applied to types that also implement `PartialEq`, although not all types that +implement `PartialEq` can implement `Eq`. One example of this is floating-point +number types: the implementation of floating-point numbers states that two +instances of the not-a-number (`NaN`) value are not equal to each other. + +An example of when `Eq` is required is for keys in a `HashMap<K, V>` so that +the `HashMap<K, V>` can tell whether two keys are the same. + +## PartialOrd and Ord for Ordering Comparisons + +The `PartialOrd` trait allows you to compare instances of a type for sorting +purposes. A type that implements `PartialOrd` can be used with the `<`, `>`, +`<=`, and `>=` operators. You can only apply the `PartialOrd` trait to types +that also implement `PartialEq`. + +Deriving `PartialOrd` implements the `partial_cmp` method, which returns an +`Option<Ordering>` that will be `None` when the values given don’t produce an +ordering. An example of a value that doesn’t produce an ordering, even though +most values of that type can be compared, is the not-a-number (`NaN`) floating +point value. Calling `partial_cmp` with any floating-point number and the `NaN` +floating-point value will return `None`. + +When derived on structs, `PartialOrd` compares two instances by comparing the +value in each field in the order in which the fields appear in the struct +definition. When derived on enums, variants of the enum declared earlier in the +enum definition are considered less than the variants listed later. + +The `PartialOrd` trait is required, for example, for the `gen_range` method +from the `rand` crate that generates a random value in the range specified by a +range expression. + +The `Ord` trait allows you to know that for any two values of the annotated +type, a valid ordering will exist. The `Ord` trait implements the `cmp` method, +which returns an `Ordering` rather than an `Option<Ordering>` because a valid +ordering will always be possible. You can only apply the `Ord` trait to types +that also implement `PartialOrd` and `Eq` (and `Eq` requires `PartialEq`). When +derived on structs and enums, `cmp` behaves the same way as the derived +implementation for `partial_cmp` does with `PartialOrd`. + +An example of when `Ord` is required is when storing values in a `BTreeSet<T>`, +a data structure that stores data based on the sort order of the values. + +## Clone and Copy for Duplicating Values + +The `Clone` trait allows you to explicitly create a deep copy of a value, and +the duplication process might involve running arbitrary code and copying heap +data. See “Variables and Data Interacting with Clone†on page XX for more +information on `Clone`. + +Deriving `Clone` implements the `clone` method, which when implemented for the +whole type, calls `clone` on each of the parts of the type. This means all the +fields or values in the type must also implement `Clone` to derive `Clone`. + +An example of when `Clone` is required is when calling the `to_vec` method on a +slice. The slice doesn’t own the type instances it contains, but the vector +returned from `to_vec` will need to own its instances, so `to_vec` calls +`clone` on each item. Thus the type stored in the slice must implement `Clone`. + +The `Copy` trait allows you to duplicate a value by only copying bits stored on +the stack; no arbitrary code is necessary. See “Stack-Only Data: Copy†on page +XX for more information on `Copy`. + +The `Copy` trait doesn’t define any methods to prevent programmers from +overloading those methods and violating the assumption that no arbitrary code +is being run. That way, all programmers can assume that copying a value will be +very fast. + +You can derive `Copy` on any type whose parts all implement `Copy`. A type that +implements `Copy` must also implement `Clone` because a type that implements +`Copy` has a trivial implementation of `Clone` that performs the same task as +`Copy`. + +The `Copy` trait is rarely required; types that implement `Copy` have +optimizations available, meaning you don’t have to call `clone`, which makes +the code more concise. + +Everything possible with `Copy` you can also accomplish with `Clone`, but the +code might be slower or have to use `clone` in places. + +## Hash for Mapping a Value to a Value of Fixed Size + +The `Hash` trait allows you to take an instance of a type of arbitrary size and +map that instance to a value of fixed size using a hash function. Deriving +`Hash` implements the `hash` method. The derived implementation of the `hash` +method combines the result of calling `hash` on each of the parts of the type, +meaning all fields or values must also implement `Hash` to derive `Hash`. + +An example of when `Hash` is required is in storing keys in a `HashMap<K, V>` +to store data efficiently. + +## Default for Default Values + +The `Default` trait allows you to create a default value for a type. Deriving +`Default` implements the `default` function. The derived implementation of the +`default` function calls the `default` function on each part of the type, +meaning all fields or values in the type must also implement `Default` to +derive `Default`. + +The `Default::default` function is commonly used in combination with the struct +update syntax discussed in “Creating Instances from Other Instances with Struct +Update Syntax†on page XX. You can customize a few fields of a struct and then +set and use a default value for the rest of the fields by using +`..Default::default()`. + +The `Default` trait is required when you use the method `unwrap_or_default` on +`Option<T>` instances, for example. If the `Option<T>` is `None`, the method +`unwrap_or_default` will return the result of `Default::default` for the type +`T` stored in the `Option<T>`. + diff --git a/src/doc/book/nostarch/appendix_d.md b/src/doc/book/nostarch/appendix_d.md new file mode 100644 index 000000000..96b73e954 --- /dev/null +++ b/src/doc/book/nostarch/appendix_d.md @@ -0,0 +1,175 @@ +<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +--> + +[TOC] + +## Appendix D: Useful Development Tools + +In this appendix, we talk about some useful development tools that the Rust +project provides. We’ll look at automatic formatting, quick ways to apply +warning fixes, a linter, and integrating with IDEs. + +## Automatic Formatting with rustfmt + +The `rustfmt` tool reformats your code according to the community code style. +Many collaborative projects use `rustfmt` to prevent arguments about which +style to use when writing Rust: everyone formats their code using the tool. + +Rust installations include `rustfmt` by default, so you should already have the +programs `rustfmt` and `cargo-fmt` on your system. These two commands are +analagous to `rustc` and `cargo` in that `rustfmt` allows finer-grained control +and `cargo-fmt` understands conventions of a project that uses Cargo. To format +any Cargo project, enter the following: + +``` +$ cargo fmt +``` + +Running this command reformats all the Rust code in the current crate. This +should only change the code style, not the code semantics. For more information +on `rustfmt`, see its documentation at *https://github.com/rust-lang/rustfmt*. + +## Fix Your Code with rustfix + +The `rustfix` tool is included with Rust installations and can automatically +fix compiler warnings that have a clear way to correct the problem that’s +likely what you want. You’ve probably seen compiler warnings before. For +example, consider this code: + +Filename: src/main.rs + +``` +fn do_something() {} + +fn main() { + for i in 0..100 { + do_something(); + } +} +``` + +Here, we’re calling the `do_something` function 100 times, but we never use the +variable `i` in the body of the `for` loop. Rust warns us about that: + +``` +$ cargo build + Compiling myprogram v0.1.0 (file:///projects/myprogram) +warning: unused variable: `i` + --> src/main.rs:4:9 + | +4 | for i in 0..100 { + | ^ help: consider using `_i` instead + | + = note: #[warn(unused_variables)] on by default + + Finished dev [unoptimized + debuginfo] target(s) in 0.50s +``` + +The warning suggests that we use `_i` as a name instead: the underscore +indicates that we intend for this variable to be unused. We can automatically +apply that suggestion using the `rustfix` tool by running the command `cargo +fix`: + +``` +$ cargo fix + Checking myprogram v0.1.0 (file:///projects/myprogram) + Fixing src/main.rs (1 fix) + Finished dev [unoptimized + debuginfo] target(s) in 0.59s +``` + +When we look at *src/main.rs* again, we’ll see that `cargo fix` has changed the +code: + +Filename: src/main.rs + +``` +fn do_something() {} + +fn main() { + for _i in 0..100 { + do_something(); + } +} +``` + +The `for` loop variable is now named `_i`, and the warning no longer appears. + +You can also use the `cargo fix` command to transition your code between +different Rust editions. Editions are covered in Appendix E. + +## More Lints with Clippy + +The Clippy tool is a collection of lints to analyze your code so you can catch +common mistakes and improve your Rust code. Clippy is included with standard +Rust installations. + +To run Clippy’s lints on any Cargo project, enter the following: + +``` +$ cargo clippy +``` + +For example, say you write a program that uses an approximation of a +mathematical constant, such as pi, as this program does: + +Filename: src/main.rs + +``` +fn main() { + let x = 3.1415; + let r = 8.0; + println!("the area of the circle is {}", x * r * r); +} +``` + +Running `cargo clippy` on this project results in this error: + +``` +error: approximate value of `f{32, 64}::consts::PI` found + --> src/main.rs:2:13 + | +2 | let x = 3.1415; + | ^^^^^^ + | + = note: `#[deny(clippy::approx_constant)]` on by default + = help: consider using the constant directly + = help: for further information visit https://rust-lang.github.io/rust- +clippy/master/index.html#approx_constant +``` + +This error lets you know that Rust already has a more precise `PI` constant +defined, and that your program would be more correct if you used the constant +instead. You would then change your code to use the `PI` constant. + +The following code doesn’t result in any errors or warnings from Clippy: + +Filename: src/main.rs + +``` +fn main() { + let x = std::f64::consts::PI; + let r = 8.0; + println!("the area of the circle is {}", x * r * r); +} +``` + +For more information on Clippy, see its documentation at +*https://github.com/rust-lang/rust-clippy**.* + +## IDE Integration Using rust-analyzer + +To help with IDE integration, the Rust community recommends using +`rust-analyzer`. This tool is a set of compiler-centric utilities that speak +Language Server Protocol, which is a specification for IDEs and programming +languages to communicate with each other. Different clients can use +`rust-analyzer`, such as the Rust analyzer plug-in for Visual Studio Code at +*https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer*. + +Visit the `rust-analyzer` project’s home page at +*https://rust-analyzer.github.io* for installation instructions, then install +the language server support in your particular IDE. Your IDE will gain +capabilities such as autocompletion, jump to definition, and inline errors + diff --git a/src/doc/book/nostarch/appendix_e.md b/src/doc/book/nostarch/appendix_e.md new file mode 100644 index 000000000..ddb12b782 --- /dev/null +++ b/src/doc/book/nostarch/appendix_e.md @@ -0,0 +1,66 @@ +<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +--> + +[TOC] + +## Appendix E: Editions + +In Chapter 1, you saw that `cargo new` adds a bit of metadata to your +*Cargo.toml* file about an edition. This appendix talks about what that means! + +The Rust language and compiler have a six-week release cycle, meaning users get +a constant stream of new features. Other programming languages release larger +changes less often; Rust releases smaller updates more frequently. After a +while, all of these tiny changes add up. But from release to release, it can be +difficult to look back and say, “Wow, between Rust 1.10 and Rust 1.31, Rust has +changed a lot!†+ +Every two or three years, the Rust team produces a new Rust *edition*. Each +edition brings together the features that have landed into a clear package with +fully updated documentation and tooling. New editions ship as part of the usual +six-week release process. + +Editions serve different purposes for different people: + +* For active Rust users, a new edition brings together incremental changes into +an easy-to-understand package. +* For non-users, a new edition signals that some major advancements have +landed, which might make Rust worth another look. +* For those developing Rust, a new edition provides a rallying point for the +project as a whole. + +At the time of this writing, three Rust editions are available: Rust 2015, Rust +2018, and Rust 2021. This book is written using Rust 2021 edition idioms. + +The `edition` key in *Cargo.toml* indicates which edition the compiler should +use for your code. If the key doesn’t exist, Rust uses `2015` as the edition +value for backward compatibility reasons. + +Each project can opt in to an edition other than the default 2015 edition. +Editions can contain incompatible changes, such as including a new keyword that +conflicts with identifiers in code. However, unless you opt in to those +changes, your code will continue to compile even as you upgrade the Rust +compiler version you use. + +All Rust compiler versions support any edition that existed prior to that +compiler’s release, and they can link crates of any supported editions +together. Edition changes only affect the way the compiler initially parses +code. Therefore, if you’re using Rust 2015 and one of your dependencies uses +Rust 2018, your project will compile and be able to use that dependency. The +opposite situation, where your project uses Rust 2018 and a dependency uses +Rust 2015, works as well. + +To be clear: most features will be available on all editions. Developers using +any Rust edition will continue to see improvements as new stable releases are +made. However, in some cases, mainly when new keywords are added, some new +features might only be available in later editions. You will need to switch +editions if you want to take advantage of such features. + +For more details, *The* *Edition Guide* at +*https://doc.rust-lang.org/stable/edition-guide* is a complete book about +editions that enumerates the differences between editions and explains how to +automatically upgrade your code to a new edition via `cargo fix`. + diff --git a/src/doc/book/nostarch/bio.md b/src/doc/book/nostarch/bio.md index cbb2bd4bb..38b0508bc 100644 --- a/src/doc/book/nostarch/bio.md +++ b/src/doc/book/nostarch/bio.md @@ -1,5 +1,6 @@ # About the Authors -<!--Insert Steve's bio here --> - -Carol Nichols is a member of the Rust Crates.io Team and a former member of the Rust Core Team. She’s a co-founder of Integer 32, LLC, the world’s first Rust-focused software consultancy. Nichols has also organized the Rust Belt Rust Conference.
\ No newline at end of file +Carol Nichols is a member of the Rust Crates.io Team and a former member of the +Rust Core Team. She’s a co-founder of Integer 32, LLC, the world’s first +Rust-focused software consultancy. Nichols has also organized the Rust Belt +Rust Conference. diff --git a/src/doc/book/nostarch/chapter01.md b/src/doc/book/nostarch/chapter01.md index 87848b66f..3379b14f2 100644 --- a/src/doc/book/nostarch/chapter01.md +++ b/src/doc/book/nostarch/chapter01.md @@ -21,28 +21,28 @@ The first step is to install Rust. We’ll download Rust through `rustup`, a command line tool for managing Rust versions and associated tools. You’ll need an internet connection for the download. -> Note: If you prefer not to use `rustup` for some reason, please see the -> Other Rust Installation Methods page at -> *https://forge.rust-lang.org/infra/other-installation-methods.html* for more -> options. +> Note: If you prefer not to use `rustup` for some reason, please see the Other +Rust Installation Methods page at +*https://forge.rust-lang.org/infra/other-installation-methods.html* for more +options. The following steps install the latest stable version of the Rust compiler. Rust’s stability guarantees ensure that all the examples in the book that compile will continue to compile with newer Rust versions. The output might -differ slightly between versions, because Rust often improves error messages -and warnings. In other words, any newer, stable version of Rust you install -using these steps should work as expected with the content of this book. +differ slightly between versions because Rust often improves error messages and +warnings. In other words, any newer, stable version of Rust you install using +these steps should work as expected with the content of this book. > ### Command Line Notation > > In this chapter and throughout the book, we’ll show some commands used in the -> terminal. Lines that you should enter in a terminal all start with `$`. You -> don’t need to type in the `$` character; it’s the command line prompt shown -> to indicate the start of each command. Lines that don’t start with `$` -> typically show the output of the previous command. Additionally, -> PowerShell-specific examples will use `>` rather than `$`. +terminal. Lines that you should enter in a terminal all start with `$`. You +don’t need to type the `$` character; it’s the command line prompt shown to +indicate the start of each command. Lines that don’t start with `$` typically +show the output of the previous command. Additionally, PowerShell-specific +examples will use `>` rather than `$`. -### Installing `rustup` on Linux or macOS +### Installing rustup on Linux or macOS If you’re using Linux or macOS, open a terminal and enter the following command: @@ -74,7 +74,7 @@ Linux users should generally install GCC or Clang, according to their distribution’s documentation. For example, if you use Ubuntu, you can install the `build-essential` package. -### Installing `rustup` on Windows +### Installing rustup on Windows On Windows, go to *https://www.rust-lang.org/tools/install* and follow the instructions for installing Rust. At some point in the installation, you’ll @@ -82,18 +82,13 @@ receive a message explaining that you’ll also need the MSVC build tools for Visual Studio 2013 or later. To acquire the build tools, you’ll need to install Visual Studio 2022 from -*https://visualstudio.microsoft.com/downloads/*. When asked which workloads to +*https://visualstudio.microsoft.com/downloads*. When asked which workloads to install, include: -- “Desktop Development with C++†-- The Windows 10 or 11 SDK -- The English language pack component, along with any other language pack of - your choosing - -<!-- Liz: We do want to recommend the English language pack along with whatever -other languages the reader speaks-- otherwise, sometimes error messages are -printed strangely -https://github.com/rust-lang/rust/issues/35785#issuecomment-735051657 /Carol --> +* “Desktop Development with C++†+* The Windows 10 or 11 SDK +* The English language pack component, along with any other language pack of +your choosing The rest of this book uses commands that work in both *cmd.exe* and PowerShell. If there are specific differences, we’ll explain which to use. @@ -108,7 +103,7 @@ $ rustc --version ``` You should see the version number, commit hash, and commit date for the latest -stable version that has been released in the following format: +stable version that has been released, in the following format: ``` rustc x.y.z (abcabcabc yyyy-mm-dd) @@ -133,25 +128,18 @@ In PowerShell, use: In Linux and macOS, use: ``` -echo $PATH +$ echo $PATH ``` If that’s all correct and Rust still isn’t working, there are a number of -places you can get help. The easiest is the #beginners channel on the official -Rust Discord at *https://discord.gg/rust-lang*. There, you can chat with other -Rustaceans (a silly nickname we call ourselves) who can help you out. Other -great resources include the Users forum at *https://users.rust-lang.org/* and -Stack Overflow at *https://stackoverflow.com/questions/tagged/rust*. - -<!-- `echo %PATH%` will work for cmd. PowerShell would use `echo $env:Path`. -Bash would use `echo $PATH` /JT --> -<!-- I've added these instructions above /Carol --> +places you can get help. Find out how to get in touch with other Rustaceans (a +silly nickname we call ourselves) on the community page at +*https://www.rust-lang.org/community*. ### Updating and Uninstalling -Once Rust is installed via `rustup`, when a new version of Rust is released, -updating to the latest version is easy. From your shell, run the following -update script: +Once Rust is installed via `rustup`, updating to a newly released version is +easy. From your shell, run the following update script: ``` $ rustup update @@ -166,9 +154,9 @@ $ rustup self uninstall ### Local Documentation -The installation of Rust also includes a local copy of the documentation, so -you can read it offline. Run `rustup doc` to open the local documentation in -your browser. +The installation of Rust also includes a local copy of the documentation so +that you can read it offline. Run `rustup doc` to open the local documentation +in your browser. Any time a type or function is provided by the standard library and you’re not sure what it does or how to use it, use the application programming interface @@ -176,17 +164,17 @@ sure what it does or how to use it, use the application programming interface ## Hello, World! -Now that you’ve installed Rust, let’s write your first Rust program. It’s -traditional when learning a new language to write a little program that prints -the text `Hello, world!` to the screen, so we’ll do the same here! +Now that you’ve installed Rust, it’s time to write your first Rust program. +It’s traditional when learning a new language to write a little program that +prints the text `Hello, world!` to the screen, so we’ll do the same here! > Note: This book assumes basic familiarity with the command line. Rust makes -> no specific demands about your editing or tooling or where your code lives, so -> if you prefer to use an integrated development environment (IDE) instead of -> the command line, feel free to use your favorite IDE. Many IDEs now have some -> degree of Rust support; check the IDE’s documentation for details. The Rust -> team has been focusing on enabling great IDE support via `rust-analyzer`. See -> Appendix D for more details! +no specific demands about your editing or tooling or where your code lives, so +if you prefer to use an integrated development environment (IDE) instead of the +command line, feel free to use your favorite IDE. Many IDEs now have some +degree of Rust support; check the IDE’s documentation for details. The Rust +team has been focusing on enabling great IDE support via `rust-analyzer`. See +Appendix D for more details. ### Creating a Project Directory @@ -254,8 +242,8 @@ Hello, world! ``` Regardless of your operating system, the string `Hello, world!` should print to -the terminal. If you don’t see this output, refer back to the “Troubleshooting†-part of the Installation section for ways to get help. +the terminal. If you don’t see this output, refer back to “Troubleshooting†on +page XX for ways to get help. If `Hello, world!` did print, congratulations! You’ve officially written a Rust program. That makes you a Rust programmer—welcome! @@ -281,10 +269,10 @@ function bodies. It’s good style to place the opening curly bracket on the sam line as the function declaration, adding one space in between. > Note: If you want to stick to a standard style across Rust projects, you can -> use an automatic formatter tool called `rustfmt` to format your code in a -> particular style (more on `rustfmt` in Appendix D). The Rust team has -> included this tool with the standard Rust distribution, like `rustc`, so it -> should already be installed on your computer! +use an automatic formatter tool called `rustfmt` to format your code in a +particular style (more on `rustfmt` in Appendix D). The Rust team has included +this tool with the standard Rust distribution, as `rustc` is, so it should +already be installed on your computer! The body of the `main` function holds the following code: @@ -300,7 +288,7 @@ First, Rust style is to indent with four spaces, not a tab. Second, `println!` calls a Rust macro. If it had called a function instead, it would be entered as `println` (without the `!`). We’ll discuss Rust macros in more detail in Chapter 19. For now, you just need to know that using a `!` -means that you’re calling a macro instead of a normal function, and that macros +means that you’re calling a macro instead of a normal function and that macros don’t always follow the same rules as functions. Third, you see the `"Hello, world!"` string. We pass this string as an argument @@ -327,16 +315,16 @@ If you have a C or C++ background, you’ll notice that this is similar to `gcc` or `clang`. After compiling successfully, Rust outputs a binary executable. On Linux, macOS, and PowerShell on Windows, you can see the executable by -entering the `ls` command in your shell. On Linux and macOS, you’ll see two -files. With PowerShell on Windows, you’ll see the same three files that you -would see using CMD. +entering the `ls` command in your shell: ``` $ ls main main.rs ``` -With CMD on Windows, you would enter the following: +On Linux and macOS, you’ll see two files. With PowerShell on Windows, you’ll +see the same three files that you would see using CMD. With CMD on Windows, you +would enter the following: ``` > dir /B %= the /B option says to only show the file names =% @@ -387,9 +375,9 @@ using Cargo, adding dependencies will be much easier to do. Because the vast majority of Rust projects use Cargo, the rest of this book assumes that you’re using Cargo too. Cargo comes installed with Rust if you -used the official installers discussed in the “Installation†section. If you +used the official installers discussed in “Installation†on page XX. If you installed Rust through some other means, check whether Cargo is installed by -entering the following into your terminal: +entering the following in your terminal: ``` $ cargo --version @@ -402,9 +390,9 @@ determine how to install Cargo separately. ### Creating a Project with Cargo Let’s create a new project using Cargo and look at how it differs from our -original “Hello, world!†project. Navigate back to your *projects* directory (or -wherever you decided to store your code). Then, on any operating system, run -the following: +original “Hello, world!†project. Navigate back to your *projects* directory +(or wherever you decided to store your code). Then, on any operating system, +run the following: ``` $ cargo new hello_cargo @@ -424,8 +412,8 @@ Git files won’t be generated if you run `cargo new` within an existing Git repository; you can override this behavior by using `cargo new --vcs=git`. > Note: Git is a common version control system. You can change `cargo new` to -> use a different version control system or no version control system by using -> the `--vcs` flag. Run `cargo new --help` to see the available options. +use a different version control system or no version control system by using +the `--vcs` flag. Run `cargo new --help` to see the available options. Open *Cargo.toml* in your text editor of choice. It should look similar to the code in Listing 1-2. @@ -471,7 +459,7 @@ fn main() { Cargo has generated a “Hello, world!†program for you, just like the one we wrote in Listing 1-1! So far, the differences between our project and the -project Cargo generated are that Cargo placed the code in the *src* directory, +project Cargo generated are that Cargo placed the code in the *src* directory and we have a *Cargo.toml* configuration file in the top directory. Cargo expects your source files to live inside the *src* directory. The @@ -499,21 +487,6 @@ $ cargo build This command creates an executable file in *target/debug/hello_cargo* (or *target\debug\hello_cargo.exe* on Windows) rather than in your current -<!-- why does it put it in a debug folder? Interesting to know, because it seems -laborious to have to enter the whole path to run the executable /LC --> -<!-- Because `build` uses debug settings by default, and the compiler tries to -make it clear that this isn't a release build by storing it in the `debug` -path. Most people use `cargo run` instead, which is what we show in a few -paragraphs. We talk about building for release mode in the next section; do you -think it needs to be mentioned here too? I think it would be somewhat -distracting and repetitive to get into that right here... /Carol --> -<!-- JT, what do you think? I don't want to get into the weeds... but will the -reader be wondering? /LC --> -<!-- I think we could quickly mention that because the default build is a debug -build, cargo will put the binary in the debug directory. If we created a release -build, it would put it in the release directory. Looks like we do mention this -later /JT --> -<!-- I've added a sentence here along the lines of what JT suggested /Carol --> directory. Because the default build is a debug build, Cargo puts the binary in a directory named *debug*. You can run the executable with this command: @@ -531,7 +504,7 @@ manages its contents for you. We just built a project with `cargo build` and ran it with `./target/debug/hello_cargo`, but we can also use `cargo run` to compile the -code and then run the resulting executable all in one command: +code and then run the resultant executable all in one command: ``` $ cargo run @@ -568,7 +541,7 @@ $ cargo check ``` Why would you not want an executable? Often, `cargo check` is much faster than -`cargo build`, because it skips the step of producing an executable. If you’re +`cargo build` because it skips the step of producing an executable. If you’re continually checking your work while writing the code, using `cargo check` will speed up the process of letting you know if your project is still compiling! As such, many Rustaceans run `cargo check` periodically as they write their @@ -581,9 +554,9 @@ Let’s recap what we’ve learned so far about Cargo: * We can build a project using `cargo build`. * We can build and run a project in one step using `cargo run`. * We can build a project without producing a binary to check for errors using - `cargo check`. +`cargo check`. * Instead of saving the result of the build in the same directory as our code, - Cargo stores it in the *target/debug* directory. +Cargo stores it in the *target/debug* directory. An additional advantage of using Cargo is that the commands are the same no matter which operating system you’re working on. So, at this point, we’ll no @@ -609,10 +582,6 @@ With simple projects, Cargo doesn’t provide a lot of value over just using Once programs grow to multiple files or need a dependency, it’s much easier to let Cargo coordinate the build. -<!-- I think once you go add a second file or add a single dependency, you -already want to move to cargo imho. /JT --> -<!-- Updated above! /Carol --> - Even though the `hello_cargo` project is simple, it now uses much of the real tooling you’ll use in the rest of your Rust career. In fact, to work on any existing projects, you can use the following commands to check out the code @@ -624,7 +593,8 @@ $ cd someproject $ cargo build ``` -For more information about Cargo, check out its documentation at *https://doc.rust-lang.org/cargo/*. +For more information about Cargo, check out its documentation at +*https://doc.rust-lang.org/cargo*. ## Summary @@ -642,8 +612,3 @@ and writing Rust code. So, in Chapter 2, we’ll build a guessing game program. If you would rather start by learning how common programming concepts work in Rust, see Chapter 3 and then return to Chapter 2. -<!-- Question for Carol: Do we want to mention IDE support? Rust Analyzer is -pretty good these days. /JT --> -<!-- I don't want to make the reader feel like they *have* to stop at this -point and set up their IDE (or use an unfamiliar IDE); I did add a sentence to -the note about IDEs pointing to Appendix D for more info on Rust Analyzer. --> diff --git a/src/doc/book/nostarch/chapter02.md b/src/doc/book/nostarch/chapter02.md index b7986c0de..b01770dc5 100644 --- a/src/doc/book/nostarch/chapter02.md +++ b/src/doc/book/nostarch/chapter02.md @@ -11,8 +11,8 @@ directory, so all fixes need to be made in `/src/`. Let’s jump into Rust by working through a hands-on project together! This chapter introduces you to a few common Rust concepts by showing you how to use them in a real program. You’ll learn about `let`, `match`, methods, associated -functions, using external crates, and more! In the following chapters, we’ll -explore these ideas in more detail. In this chapter, you’ll practice the +functions, external crates, and more! In the following chapters, we’ll explore +these ideas in more detail. In this chapter, you’ll just practice the fundamentals. We’ll implement a classic beginner programming problem: a guessing game. Here’s @@ -45,14 +45,12 @@ name = "guessing_game" version = "0.1.0" edition = "2021" -# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html +# See more keys and their definitions at +https://doc.rust-lang.org/cargo/reference/manifest.html [dependencies] ``` -<!--- We should move to the 2021 edition. /JT ---> -<!-- Totally right, done! /Carol --> - As you saw in Chapter 1, `cargo new` generates a “Hello, world!†program for you. Check out the *src/main.rs* file: @@ -108,27 +106,21 @@ fn main() { } ``` -<!--- Style question, should we switch to the more recent style of: -``` - println!("You guessed: {guess}"); -``` -/JT ---> -<!-- Good call, I'll switch these throughout as I edit after TR. /Carol --> - Listing 2-1: Code that gets a guess from the user and prints it This code contains a lot of information, so let’s go over it line by line. To obtain user input and then print the result as output, we need to bring the -`io` input/output library into scope. The `io` library comes from the -standard library, known as `std`: +`io` input/output library into scope. The `io` library comes from the standard +library, known as `std`: ``` use std::io; ``` -By default, Rust has a set of items defined in the standard library that it brings -into the scope of every program. This set is called the *prelude*, and you can -see everything in it at *https://doc.rust-lang.org/std/prelude/index.html*. +By default, Rust has a set of items defined in the standard library that it +brings into the scope of every program. This set is called the *prelude*, and +you can see everything in it at +*https://doc.rust-lang.org/std/prelude/index.html*. If a type you want to use isn’t in the prelude, you have to bring that type into scope explicitly with a `use` statement. Using the `std::io` library @@ -142,21 +134,16 @@ program: fn main() { ``` -The `fn` syntax declares a new function, the parentheses, `()`, indicate there -are no parameters, and the curly bracket, `{`, starts the body of the function. +The `fn` syntax declares a new function; the parentheses, `()`, indicate there +are no parameters; and the curly bracket, `{`, starts the body of the function. As you also learned in Chapter 1, `println!` is a macro that prints a string to the screen: -<!--- Not sure if we want to go into it just yet, but `println!` formats a string -and then prints the resulting string to stdout (which is often, but not always -the screen). /JT ---> -<!-- Yeah, I want to gloss over that for now. Leaving this as-is. /Carol --> - ``` - println!("Guess the number!"); +println!("Guess the number!"); - println!("Please input your guess."); +println!("Please input your guess."); ``` This code is printing a prompt stating what the game is and requesting input @@ -167,7 +154,7 @@ from the user. Next, we’ll create a *variable* to store the user input, like this: ``` - let mut guess = String::new(); +let mut guess = String::new(); ``` Now the program is getting interesting! There’s a lot going on in this little @@ -179,15 +166,9 @@ let apples = 5; This line creates a new variable named `apples` and binds it to the value 5. In Rust, variables are immutable by default, meaning once we give the variable a -value, the value won't change. We’ll be discussing this concept in detail in -the “Variables and Mutability†section in Chapter 3. To make a variable -mutable, we add `mut` before the variable name: - -<!--- Do we want to give a quick word about what "mutable" means? Folks who grab -this book but aren't familiar with some of the technical programming language terms -might need something like "variable are immutable by default, meaning once we give -the variable its value, it won't change". /JT ---> -<!-- Sounds good, made that change /Carol --> +value, the value won’t change. We’ll be discussing this concept in detail in +“Variables and Mutability†on page XX. To make a variable mutable, we add `mut` +before the variable name: ``` let apples = 5; // immutable @@ -195,12 +176,12 @@ let mut bananas = 5; // mutable ``` > Note: The `//` syntax starts a comment that continues until the end of the -> line. Rust ignores everything in comments. We’ll discuss comments in more -> detail in Chapter 3. +line. Rust ignores everything in comments. We’ll discuss comments in more +detail in Chapter 3. Returning to the guessing game program, you now know that `let mut guess` will introduce a mutable variable named `guess`. The equal sign (`=`) tells Rust we -want to bind something to the variable now. On the right of the equals sign is +want to bind something to the variable now. On the right of the equal sign is the value that `guess` is bound to, which is the result of calling `String::new`, a function that returns a new instance of a `String`. `String` is a string type provided by the standard library that is a growable, UTF-8 @@ -209,15 +190,9 @@ encoded bit of text. The `::` syntax in the `::new` line indicates that `new` is an associated function of the `String` type. An *associated function* is a function that’s implemented on a type, in this case `String`. This `new` function creates a -new, empty string. You’ll find a `new` function on many types, because it’s a +new, empty string. You’ll find a `new` function on many types because it’s a common name for a function that makes a new value of some kind. -<!--- For some readers, we might want to say "If you've used languages with -static methods, associated function work very similarly" or something along -those lines. /JT ---> -<!-- I don't think that's helpful enough for all readers to include here, given -that we're trying to make the book mostly background-agnostic. /Carol --> - In full, the `let mut guess = String::new();` line has created a mutable variable that is currently bound to a new, empty instance of a `String`. Whew! @@ -229,11 +204,11 @@ the `stdin` function from the `io` module, which will allow us to handle user input: ``` - io::stdin() - .read_line(&mut guess) +io::stdin() + .read_line(&mut guess) ``` -If we hadn’t imported the `io` library with `use std::io` at the beginning of +If we hadn’t imported the `io` library with `use std::io;` at the beginning of the program, we could still use the function by writing this function call as `std::io::stdin`. The `stdin` function returns an instance of `std::io::Stdin`, which is a type that represents a handle to the standard input for your @@ -252,27 +227,19 @@ let multiple parts of your code access one piece of data without needing to copy that data into memory multiple times. References are a complex feature, and one of Rust’s major advantages is how safe and easy it is to use references. You don’t need to know a lot of those details to finish this -program. For now, all you need to know is that like variables, references are +program. For now, all you need to know is that, like variables, references are immutable by default. Hence, you need to write `&mut guess` rather than `&guess` to make it mutable. (Chapter 4 will explain references more thoroughly.) -### Handling Potential Failure with the `Result` Type +### Handling Potential Failure with Result We’re still working on this line of code. We’re now discussing a third line of text, but note that it’s still part of a single logical line of code. The next part is this method: -<!--- in the program this is the second line of code -- do you mean the third -section of this line? --> -<!-- This is still discussing the code in Listing 2-1, and is going to talk -about the third line, if you're counting the lines of the page, of this logical -line of code, where logical lines of code are ended with semicolons. Do you -have suggestions on how to make that clearer? /Carol --> -<!--- Ashley, does this all track now? /LC ---> - ``` - .expect("Failed to read line"); +.expect("Failed to read line"); ``` We could have written this code as: @@ -291,17 +258,10 @@ we pass to it, but it also returns a `Result` value. `Result` is an *enumeration*, often called an *enum*, which is a type that can be in one of multiple possible states. We call each possible state a *variant*. -<!--- Typo above: possibilities /JT ---> -<!--- Personally, I think the above paragraph might be introducing a little too -much all at once. You might be able to shorten it to: "`Result` is an *enumeration*, -often called an *enum*, which is a type that can be in one of multiple possible -states. We call each possible state a *variant*. /JT ---> -<!-- I like it, made that change /Carol --> - Chapter 6 will cover enums in more detail. The purpose of these `Result` types is to encode error-handling information. -`Result`'s variants are `Ok` and `Err`. The `Ok` variant indicates the +`Result`’s variants are `Ok` and `Err`. The `Ok` variant indicates the operation was successful, and inside `Ok` is the successfully generated value. The `Err` variant means the operation failed, and `Err` contains information about how or why the operation failed. @@ -337,38 +297,36 @@ warning: `guessing_game` (bin "guessing_game") generated 1 warning Rust warns that you haven’t used the `Result` value returned from `read_line`, indicating that the program hasn’t handled a possible error. -The right way to suppress the warning is to actually write error handling, but -in our case we just want to crash this program when a problem occurs, so we can -use `expect`. You’ll learn about recovering from errors in Chapter 9. +The right way to suppress the warning is to actually write error-handling code, +but in our case we just want to crash this program when a problem occurs, so we +can use `expect`. You’ll learn about recovering from errors in Chapter 9. -### Printing Values with `println!` Placeholders +### Printing Values with println! Placeholders Aside from the closing curly bracket, there’s only one more line to discuss in the code so far: ``` - println!("You guessed: {guess}"); +println!("You guessed: {guess}"); ``` -<!--- Ditto with using the `{guess}` style in this line. /JT ---> - This line prints the string that now contains the user’s input. The `{}` set of curly brackets is a placeholder: think of `{}` as little crab pincers that hold -a value in place. You can print more than one value using curly brackets: the -first set of curly brackets holds the first value listed after the format -string, the second set holds the second value, and so on. Printing multiple -values in one call to `println!` would look like this: +a value in place. When printing the value of a variable, the variable name can +go inside the curly brackets. When printing the result of evaluating an +expression, place empty curly brackets in the format string, then follow the +format string with a comma-separated list of expressions to print in each empty +curly bracket placeholder in the same order. Printing a variable and the result +of an expression in one call to `println!` would look like this: ``` let x = 5; let y = 10; -println!("x = {x} and y = {y}"); +println!("x = {x} and y + 2 = {}", y + 2); ``` -<!--- And `println!("x = {x} and y = {y}");` in this example. /JT ---> -<!-- Done! /Carol --> -This code would print `x = 5 and y = 10`. +This code would print `x = 5 and y = 12`. ### Testing the First Part @@ -401,43 +359,36 @@ library. However, the Rust team does provide a `rand` crate at Remember that a crate is a collection of Rust source code files. The project we’ve been building is a *binary crate*, which is an executable. The `rand` -crate is a *library crate*, which contains code intended to be used in other -programs and can't be executed on its own. - -<!--- Nit: ", and" followed by incomplete sentence. /JT ---> -<!-- Fixed /Carol --> +crate is a *library crate*, which contains code that is intended to be used in +other programs and can’t be executed on its own. Cargo’s coordination of external crates is where Cargo really shines. Before we can write code that uses `rand`, we need to modify the *Cargo.toml* file to include the `rand` crate as a dependency. Open that file now and add the -following line to the bottom beneath the `[dependencies]` section header that +following line to the bottom, beneath the `[dependencies]` section header that Cargo created for you. Be sure to specify `rand` exactly as we have here, with -this version number, or the code examples in this tutorial may not work. +this version number, or the code examples in this tutorial may not work: Filename: Cargo.toml ``` -rand = "0.8.3" +[dependencies] +rand = "0.8.5" ``` -<!--- 0.8.5 is the current latest. /JT ---> -<!-- I will update this version to whatever is latest once we're in Word; there -could be another version between now and then. If it's another 0.8.x version, -it doesn't really matter in any case. /Carol --> In the *Cargo.toml* file, everything that follows a header is part of that section that continues until another section starts. In `[dependencies]` you tell Cargo which external crates your project depends on and which versions of those crates you require. In this case, we specify the `rand` crate with the -semantic version specifier `0.8.3`. Cargo understands Semantic Versioning +semantic version specifier `0.8.5`. Cargo understands Semantic Versioning (sometimes called *SemVer*), which is a standard for writing version numbers. -The number `0.8.3` is actually shorthand for `^0.8.3`, which means any version -that is at least `0.8.3` but below `0.9.0`. +The specifier `0.8.5` is actually shorthand for `^0.8.5`, which means any +version that is at least 0.8.5 but below 0.9.0. Cargo considers these versions to have public APIs compatible with version -`0.8.3`, and this specification ensures you’ll get the latest patch release -that will still compile with the code in this chapter. Any version `0.9.0` or -greater is not guaranteed to have the same API as what the following examples -use. +0.8.5, and this specification ensures you’ll get the latest patch release that +will still compile with the code in this chapter. Any version 0.9.0 or greater +is not guaranteed to have the same API as what the following examples use. Now, without changing any of the code, let’s build the project, as shown in Listing 2-2. @@ -445,48 +396,34 @@ Listing 2-2. ``` $ cargo build Updating crates.io index - Downloaded rand v0.8.3 - Downloaded libc v0.2.86 - Downloaded getrandom v0.2.2 + Downloaded rand v0.8.5 + Downloaded libc v0.2.127 + Downloaded getrandom v0.2.7 Downloaded cfg-if v1.0.0 - Downloaded ppv-lite86 v0.2.10 - Downloaded rand_chacha v0.3.0 - Downloaded rand_core v0.6.2 - Compiling rand_core v0.6.2 - Compiling libc v0.2.86 - Compiling getrandom v0.2.2 - Compiling cfg-if v1.0.0 - Compiling ppv-lite86 v0.2.10 - Compiling rand_chacha v0.3.0 - Compiling rand v0.8.3 - Compiling guessing_game v0.1.0 (file:///projects/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 2.53s -``` -<!--- If we feel like refreshing this, here's what I saw today: - + Downloaded ppv-lite86 v0.2.16 + Downloaded rand_chacha v0.3.1 + Downloaded rand_core v0.6.3 + Compiling rand_core v0.6.3 + Compiling libc v0.2.127 + Compiling getrandom v0.2.7 Compiling cfg-if v1.0.0 Compiling ppv-lite86 v0.2.16 - Compiling libc v0.2.120 - Compiling getrandom v0.2.5 - Compiling rand_core v0.6.3 Compiling rand_chacha v0.3.1 Compiling rand v0.8.5 - Compiling guessing_game v0.1.0 (/Users/jt/Source/book/guessing_game) - Finished dev [unoptimized + debuginfo] target(s) in 1.50s - -/JT ---> -<!-- I will refresh this when we're in Word /Carol --> + Compiling guessing_game v0.1.0 (file:///projects/guessing_game) + Finished dev [unoptimized + debuginfo] target(s) in 2.53s +``` -Listing 2-2: The output from running `cargo build` after adding the rand crate -as a dependency +Listing 2-2: The output from running `cargo build` after adding the `rand` +crate as a dependency You may see different version numbers (but they will all be compatible with the -code, thanks to SemVer!), different lines (depending on the operating system), -and the lines may be in a different order. +code, thanks to SemVer!) and different lines (depending on the operating +system), and the lines may be in a different order. When we include an external dependency, Cargo fetches the latest versions of everything that dependency needs from the *registry*, which is a copy of data -from Crates.io at *https://crates.io/*. Crates.io is where people in the Rust +from Crates.io at *https://crates.io*. Crates.io is where people in the Rust ecosystem post their open source Rust projects for others to use. After updating the registry, Cargo checks the `[dependencies]` section and @@ -502,8 +439,8 @@ about them in your *Cargo.toml* file. Cargo also knows that you haven’t change anything about your code, so it doesn’t recompile that either. With nothing to do, it simply exits. -If you open up the *src/main.rs* file, make a trivial change, and then save it -and build again, you’ll only see two lines of output: +If you open the *src/main.rs* file, make a trivial change, and then save it and +build again, you’ll only see two lines of output: ``` $ cargo build @@ -511,42 +448,30 @@ $ cargo build Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs ``` -These lines show Cargo only updates the build with your tiny change to the +These lines show that Cargo only updates the build with your tiny change to the *src/main.rs* file. Your dependencies haven’t changed, so Cargo knows it can reuse what it has already downloaded and compiled for those. -#### Ensuring Reproducible Builds with the *Cargo.lock* File +#### Ensuring Reproducible Builds with the Cargo.lock File Cargo has a mechanism that ensures you can rebuild the same artifact every time you or anyone else builds your code: Cargo will use only the versions of the dependencies you specified until you indicate otherwise. For example, say that -next week version 0.8.4 of the `rand` crate comes out, and that version +next week version 0.8.6 of the `rand` crate comes out, and that version contains an important bug fix, but it also contains a regression that will break your code. To handle this, Rust creates the *Cargo.lock* file the first time you run `cargo build`, so we now have this in the *guessing_game* directory. -<!--- If we bump version numbers, we should bump above and below also. /JT ---> -<!-- Yup, will do in Word! /Carol --> - -When you build a project for the first time, Cargo figures out all the -versions of the dependencies that fit the criteria and then writes them to -the *Cargo.lock* file. When you build your project in the future, Cargo will -see that the *Cargo.lock* file exists and use the versions specified there +When you build a project for the first time, Cargo figures out all the versions +of the dependencies that fit the criteria and then writes them to the +*Cargo.lock* file. When you build your project in the future, Cargo will see +that the *Cargo.lock* file exists and will use the versions specified there rather than doing all the work of figuring out versions again. This lets you have a reproducible build automatically. In other words, your project will -remain at `0.8.3` until you explicitly upgrade, thanks to the *Cargo.lock* -file. Because the *Cargo.lock* file is important for reproducible builds, it's -often checked into source control with the rest of the code in your project. - -<!--- We could mention that because Cargo.lock is important for reproducible -builds, they're often checked into source control alongside the Cargo.toml and -the rest of the code of your project. /JT ---> -<!-- Liz, is this sentence ok even though we don't really talk about source -control or what it is anywhere else in the book? I don't really want to get -into it, but at this point I think it's a fair assumption that developers know -what "source control" is. If you disagree, this sentence can come back out. -/Carol --> +remain at 0.8.5 until you explicitly upgrade, thanks to the *Cargo.lock* file. +Because the *Cargo.lock* file is important for reproducible builds, it’s often +checked into source control with the rest of the code in your project. #### Updating a Crate to Get a New Version @@ -554,24 +479,20 @@ When you *do* want to update a crate, Cargo provides the command `update`, which will ignore the *Cargo.lock* file and figure out all the latest versions that fit your specifications in *Cargo.toml*. Cargo will then write those versions to the *Cargo.lock* file. Otherwise, by default, Cargo will only look -for versions greater than `0.8.3` and less than `0.9.0`. If the `rand` crate -has released the two new versions `0.8.4` and `0.9.0` you would see the -following if you ran `cargo update`: +for versions greater than 0.8.5 and less than 0.9.0. If the `rand` crate has +released the two new versions 0.8.6 and 0.9.0, you would see the following if +you ran `cargo update`: ``` $ cargo update Updating crates.io index - Updating rand v0.8.3 -> v0.8.4 + Updating rand v0.8.5 -> v0.8.6 ``` -Cargo ignores the `0.9.0` release. At this point, you would also notice a -change in your *Cargo.lock* file noting that the version of the `rand` crate -you are now using is `0.8.4`. To use `rand` version `0.9.0` or any version in -the `0.9.x` series, you’d have to update the *Cargo.toml* file to look like -this instead: - -<!--- Typo first line: release. /JT ---> -<!-- Fixed /Carol --> +Cargo ignores the 0.9.0 release. At this point, you would also notice a change +in your *Cargo.lock* file noting that the version of the `rand` crate you are +now using is 0.8.6. To use `rand` version 0.9.0 or any version in the 0.9.*x* +series, you’d have to update the *Cargo.toml* file to look like this instead: ``` [dependencies] @@ -582,7 +503,7 @@ The next time you run `cargo build`, Cargo will update the registry of crates available and reevaluate your `rand` requirements according to the new version you have specified. -There’s a lot more to say about Cargo and its ecosystem which we’ll discuss in +There’s a lot more to say about Cargo and its ecosystem, which we’ll discuss in Chapter 14, but for now, that’s all you need to know. Cargo makes it very easy to reuse libraries, so Rustaceans are able to write smaller projects that are assembled from a number of packages. @@ -596,14 +517,14 @@ Filename: src/main.rs ``` use std::io; -[1]use rand::Rng; +1 use rand::Rng; fn main() { println!("Guess the number!"); - [2] let secret_number = rand::thread_rng().gen_range(1..=100); + 2 let secret_number = rand::thread_rng().gen_range(1..=100); - [3] println!("The secret number is: {secret_number}"); + 3 println!("The secret number is: {secret_number}"); println!("Please input your guess."); @@ -617,50 +538,35 @@ fn main() { } ``` -<!--- Same style suggestion re: `{secret_number}`. /JT ---> -<!--- Thought: for first-time readability, we could use `1..=100` in the above -and let people know later this is equivalent to `1..101` later. We say a number -between 1 and 100, so we could show the syntax equivalent of that description. -/JT ---> -<!-- I'm into both these suggestions! /Carol --> - Listing 2-3: Adding code to generate a random number -<!--- I can't remember how we handled wingdings in markdown before... I don't -have those files on this machine. I've just used [x] for now, does that work? -Then we'll replace them when we convert to Word /LC ---> -<!-- I don't think we added the wingdings at all until we moved to Word. For -code listings that are the same as the last printing version, I'd definitely -like to keep the wingdings the way they were. Using the brackets with numbers -as you have here works fine! /Carol --> - -First, we add the line `use rand::Rng` [1]. The `Rng` trait defines methods +First we add the line `use rand::Rng;` [1]. The `Rng` trait defines methods that random number generators implement, and this trait must be in scope for us to use those methods. Chapter 10 will cover traits in detail. Next, we’re adding two lines in the middle. In the first line [2], we call the `rand::thread_rng` function that gives us the particular random number -generator that we’re going to use: one that is local to the current thread of -execution and seeded by the operating system. Then we call the `gen_range` +generator we’re going to use: one that is local to the current thread of +execution and is seeded by the operating system. Then we call the `gen_range` method on the random number generator. This method is defined by the `Rng` -trait that we brought into scope with the `use rand::Rng` statement. The +trait that we brought into scope with the `use rand::Rng;` statement. The `gen_range` method takes a range expression as an argument and generates a random number in the range. The kind of range expression we’re using here takes the form `start..=end` and is inclusive on the lower and upper bounds, so we need to specify `1..=100` to request a number between 1 and 100. > Note: You won’t just know which traits to use and which methods and functions -> to call from a crate, so each crate has documentation with instructions for -> using it. Another neat feature of Cargo is that running the `cargo -> doc --open` command will build documentation provided by all of your -> dependencies locally and open it in your browser. If you’re interested in -> other functionality in the `rand` crate, for example, run `cargo doc --open` -> and click `rand` in the sidebar on the left. - -The second new line [3] prints the secret number. This is useful while -we’re developing the program to be able to test it, but we’ll delete it from -the final version. It’s not much of a game if the program prints the answer as -soon as it starts! +to call from a crate, so each crate has documentation with instructions for +using it. Another neat feature of Cargo is that running the `cargo doc --open` +command will build documentation provided by all your dependencies locally and +open it in your browser. If you’re interested in other functionality in the +`rand` crate, for example, run `cargo doc --open` and click `rand` in the +sidebar on the left. + +The second new line [3] prints the secret number. This is useful while we’re +developing the program to be able to test it, but we’ll delete it from the +final version. It’s not much of a game if the program prints the answer as soon +as it starts! Try running the program a few times: @@ -691,22 +597,22 @@ You should get different random numbers, and they should all be numbers between ## Comparing the Guess to the Secret Number Now that we have user input and a random number, we can compare them. That step -is shown in Listing 2-4. Note that this code won’t compile quite yet, as we -will explain. +is shown in Listing 2-4. Note that this code won’t compile just yet, as we will +explain. Filename: src/main.rs ``` use rand::Rng; -[1]use std::cmp::Ordering; +1 use std::cmp::Ordering; use std::io; fn main() { - // --snip-- + --snip-- println!("You guessed: {guess}"); - match[2] guess.cmp(&secret_number)[3] { + 2 match guess.3 cmp(&secret_number) { Ordering::Less => println!("Too small!"), Ordering::Greater => println!("Too big!"), Ordering::Equal => println!("You win!"), @@ -724,7 +630,7 @@ the three outcomes that are possible when you compare two values. Then we add five new lines at the bottom that use the `Ordering` type. The `cmp` method [3] compares two values and can be called on anything that can be compared. It takes a reference to whatever you want to compare with: here it’s -comparing the `guess` to the `secret_number`. Then it returns a variant of the +comparing `guess` to `secret_number`. Then it returns a variant of the `Ordering` enum we brought into scope with the `use` statement. We use a `match` expression [2] to decide what to do next based on which variant of `Ordering` was returned from the call to `cmp` with the values in `guess` and @@ -734,14 +640,16 @@ A `match` expression is made up of *arms*. An arm consists of a *pattern* to match against, and the code that should be run if the value given to `match` fits that arm’s pattern. Rust takes the value given to `match` and looks through each arm’s pattern in turn. Patterns and the `match` construct are -powerful Rust features that let you express a variety of situations your code -might encounter and make sure that you handle them all. These features will be +powerful Rust features: they let you express a variety of situations your code +might encounter and they make sure you handle them all. These features will be covered in detail in Chapter 6 and Chapter 18, respectively. Let’s walk through an example with the `match` expression we use here. Say that the user has guessed 50 and the randomly generated secret number this time is -38. When the code compares 50 to 38, the `cmp` method will return -`Ordering::Greater`, because 50 is greater than 38. The `match` expression gets +38. + +When the code compares 50 to 38, the `cmp` method will return +`Ordering::Greater` because 50 is greater than 38. The `match` expression gets the `Ordering::Greater` value and starts checking each arm’s pattern. It looks at the first arm’s pattern, `Ordering::Less`, and sees that the value `Ordering::Greater` does not match `Ordering::Less`, so it ignores the code in @@ -751,11 +659,6 @@ code in that arm will execute and print `Too big!` to the screen. The `match` expression ends after the first successful match, so it won’t look at the last arm in this scenario. -<!--- Since `match` always ends after the first successful match, we might want -to just say that directly: "The `match` expression ends after the first successful -match, so it won't look at the last arm in this scenario". /JT ---> -<!-- Sounds good, done! /Carol --> - However, the code in Listing 2-4 won’t compile yet. Let’s try it: ``` @@ -782,85 +685,79 @@ an `i32`, which is the type of `secret_number` unless you add type information elsewhere that would cause Rust to infer a different numerical type. The reason for the error is that Rust cannot compare a string and a number type. -<!--- Typo: Unless otherwise specified. /JT ---> -<!-- Fixed /Carol --> - Ultimately, we want to convert the `String` the program reads as input into a -real number type so we can compare it numerically to the secret number. We do so -by adding this line to the `main` function body: +real number type so we can compare it numerically to the secret number. We do +so by adding this line to the `main` function body: Filename: src/main.rs ``` - // --snip-- +--snip-- - let mut guess = String::new(); +let mut guess = String::new(); - io::stdin() - .read_line(&mut guess) - .expect("Failed to read line"); +io::stdin() + .read_line(&mut guess) + .expect("Failed to read line"); - let guess: u32 = guess.trim().parse().expect("Please type a number!"); +let guess: u32 = guess + .trim() + .parse() + .expect("Please type a number!"); - println!("You guessed: {guess}"); +println!("You guessed: {guess}"); - match guess.cmp(&secret_number) { - Ordering::Less => println!("Too small!"), - Ordering::Greater => println!("Too big!"), - Ordering::Equal => println!("You win!"), - } +match guess.cmp(&secret_number) { + Ordering::Less => println!("Too small!"), + Ordering::Greater => println!("Too big!"), + Ordering::Equal => println!("You win!"), +} ``` We create a variable named `guess`. But wait, doesn’t the program already have -a variable named `guess`? It does, but helpfully Rust allows us to *shadow* the -previous value of `guess` with a new one. Shadowing lets us reuse the `guess` +a variable named `guess`? It does, but helpfully Rust allows us to shadow the +previous value of `guess` with a new one. *Shadowing* lets us reuse the `guess` variable name rather than forcing us to create two unique variables, such as -`guess_str` and `guess` for example. We’ll cover this in more detail in Chapter -3, but for now know that this feature is often used when you want to convert a -value from one type to another type. +`guess_str` and `guess`, for example. We’ll cover this in more detail in +Chapter 3, but for now, know that this feature is often used when you want to +convert a value from one type to another type. We bind this new variable to the expression `guess.trim().parse()`. The `guess` in the expression refers to the original `guess` variable that contained the input as a string. The `trim` method on a `String` instance will eliminate any whitespace at the beginning and end, which we must do to be able to compare the string to the `u32`, which can only contain numerical data. The user must press -<span class="keystroke">enter</span> to satisfy `read_line` and input their -guess, which adds a newline character to the string. For example, if the user -types <span class="keystroke">5</span> and presses <span -class="keystroke">enter</span>, `guess` looks like this: `5\n`. The `\n` -represents “newlineâ€. (On Windows, pressing <span -class="keystroke">enter</span> results in a carriage return and a newline, -`\r\n`). The `trim` method eliminates `\n` or `\r\n`, resulting in just `5`. +enter to satisfy `read_line` and input their guess, which adds a newline +character to the string. For example, if the user types `5` and presses enter, +`guess` looks like this: `5\n`. The `\n` represents “newline.†(On Windows, +pressing enter results in a carriage return and a newline, `\r\n`.) The `trim` +method eliminates `\n` or `\r\n`, resulting in just `5`. The `parse` method on strings converts a string to another type. Here, we use it to convert from a string to a number. We need to tell Rust the exact number type we want by using `let guess: u32`. The colon (`:`) after `guess` tells Rust we’ll annotate the variable’s type. Rust has a few built-in number types; the `u32` seen here is an unsigned, 32-bit integer. It’s a good default choice -for a small positive number. You’ll learn about other number types in Chapter -3. Additionally, the `u32` annotation in this example program and the -comparison with `secret_number` means that Rust will infer that `secret_number` -should be a `u32` as well. So now the comparison will be between two values of -the same type! +for a small positive number. You’ll learn about other number types in Chapter 3. -<!--- More correct to say "The `parse` method converts a string to another type. -Here, we use it to convert from a string to a number." You can use `parse` to -convert to non-numeric types also. /JT ---> -<!-- Great catch, fixed! /Carol --> +Additionally, the `u32` annotation in this example program and the comparison +with `secret_number` means Rust will infer that `secret_number` should be a +`u32` as well. So now the comparison will be between two values of the same +type! The `parse` method will only work on characters that can logically be converted into numbers and so can easily cause errors. If, for example, the string -contained `AðŸ‘%`, there would be no way to convert that to a number. Because it -might fail, the `parse` method returns a `Result` type, much as the `read_line` -method does (discussed earlier in “Handling Potential Failure with the `Result` -Typeâ€). We’ll treat this `Result` the same way by using the `expect` method -again. If `parse` returns an `Err` `Result` variant because it couldn’t create -a number from the string, the `expect` call will crash the game and print the -message we give it. If `parse` can successfully convert the string to a number, -it will return the `Ok` variant of `Result`, and `expect` will return the -number that we want from the `Ok` value. +contained `A`ðŸ‘`%`, there would be no way to convert that to a number. Because +it might fail, the `parse` method returns a `Result` type, much as the +`read_line` method does (discussed earlier in “Handling Potential Failure with +Result†on page XX). We’ll treat this `Result` the same way by using the +`expect` method again. If `parse` returns an `Err` `Result` variant because it +couldn’t create a number from the string, the `expect` call will crash the game +and print the message we give it. If `parse` can successfully convert the +string to a number, it will return the `Ok` variant of `Result`, and `expect` +will return the number that we want from the `Ok` value. -Let’s run the program now! +Let’s run the program now: ``` $ cargo run @@ -891,20 +788,19 @@ more chances at guessing the number: Filename: src/main.rs ``` - // --snip-- +--snip-- - println!("The secret number is: {secret_number}"); +println!("The secret number is: {secret_number}"); - loop { - println!("Please input your guess."); +loop { + println!("Please input your guess."); - // --snip-- + --snip-- - match guess.cmp(&secret_number) { - Ordering::Less => println!("Too small!"), - Ordering::Greater => println!("Too big!"), - Ordering::Equal => println!("You win!"), - } + match guess.cmp(&secret_number) { + Ordering::Less => println!("Too small!"), + Ordering::Greater => println!("Too big!"), + Ordering::Equal => println!("You win!"), } } ``` @@ -915,11 +811,10 @@ and run the program again. The program will now ask for another guess forever, which actually introduces a new problem. It doesn’t seem like the user can quit! The user could always interrupt the program by using the keyboard shortcut -<span class="keystroke">ctrl-c</span>. But there’s another way to escape this -insatiable monster, as mentioned in the `parse` discussion in “Comparing the -Guess to the Secret Numberâ€: if the user enters a non-number answer, the -program will crash. We can take advantage of that to allow the user to quit, as -shown here: +ctrl-C. But there’s another way to escape this insatiable monster, as mentioned +in the `parse` discussion in “Comparing the Guess to the Secret Number†on page +XX: if the user enters a non-number answer, the program will crash. We can take +advantage of that to allow the user to quit, as shown here: ``` $ cargo run @@ -942,12 +837,13 @@ You guessed: 59 You win! Please input your guess. quit -thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidDigit }', src/main.rs:28:47 +thread 'main' panicked at 'Please type a number!: ParseIntError +{ kind: InvalidDigit }', src/main.rs:28:47 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` -Typing `quit` will quit the game, but as you’ll notice so will entering any -other non-number input. This is suboptimal to say the least; we want the game +Typing `quit` will quit the game, but as you’ll notice, so will entering any +other non-number input. This is suboptimal, to say the least; we want the game to also stop when the correct number is guessed. ### Quitting After a Correct Guess @@ -957,16 +853,14 @@ Let’s program the game to quit when the user wins by adding a `break` statemen Filename: src/main.rs ``` - // --snip-- +--snip-- - match guess.cmp(&secret_number) { - Ordering::Less => println!("Too small!"), - Ordering::Greater => println!("Too big!"), - Ordering::Equal => { - println!("You win!"); - break; - } - } +match guess.cmp(&secret_number) { + Ordering::Less => println!("Too small!"), + Ordering::Greater => println!("Too big!"), + Ordering::Equal => { + println!("You win!"); + break; } } ``` @@ -985,20 +879,20 @@ is converted from a `String` to a `u32`, as shown in Listing 2-5. Filename: src/main.rs ``` - // --snip-- +--snip-- - io::stdin() - .read_line(&mut guess) - .expect("Failed to read line"); +io::stdin() + .read_line(&mut guess) + .expect("Failed to read line"); - let guess: u32 = match guess.trim().parse() { - Ok(num) => num, - Err(_) => continue, - }; +let guess: u32 = match guess.trim().parse() { + Ok(num) => num, + Err(_) => continue, +}; - println!("You guessed: {guess}"); +println!("You guessed: {guess}"); - // --snip-- +--snip-- ``` Listing 2-5: Ignoring a non-number guess and asking for another guess instead @@ -1011,7 +905,7 @@ a `match` expression here, as we did with the `Ordering` result of the `cmp` method. If `parse` is able to successfully turn the string into a number, it will -return an `Ok` value that contains the resulting number. That `Ok` value will +return an `Ok` value that contains the resultant number. That `Ok` value will match the first arm’s pattern, and the `match` expression will just return the `num` value that `parse` produced and put inside the `Ok` value. That number will end up right where we want it in the new `guess` variable we’re creating. @@ -1098,10 +992,10 @@ fn main() { Listing 2-6: Complete guessing game code -## Summary - At this point, you’ve successfully built the guessing game. Congratulations! +## Summary + This project was a hands-on way to introduce you to many new Rust concepts: `let`, `match`, functions, the use of external crates, and more. In the next few chapters, you’ll learn about these concepts in more detail. Chapter 3 @@ -1109,3 +1003,4 @@ covers concepts that most programming languages have, such as variables, data types, and functions, and shows how to use them in Rust. Chapter 4 explores ownership, a feature that makes Rust different from other languages. Chapter 5 discusses structs and method syntax, and Chapter 6 explains how enums work. + diff --git a/src/doc/book/nostarch/chapter03.md b/src/doc/book/nostarch/chapter03.md index 281f31d33..249032fd7 100644 --- a/src/doc/book/nostarch/chapter03.md +++ b/src/doc/book/nostarch/chapter03.md @@ -18,19 +18,19 @@ Specifically, you’ll learn about variables, basic types, functions, comments, and control flow. These foundations will be in every Rust program, and learning them early will give you a strong core to start from. -> #### Keywords +> ### Keywords > -> The Rust language has a set of *keywords* that are reserved for use by -> the language only, much as in other languages. Keep in mind that you cannot -> use these words as names of variables or functions. Most of the keywords have -> special meanings, and you’ll be using them to do various tasks in your Rust -> programs; a few have no current functionality associated with them but have -> been reserved for functionality that might be added to Rust in the future. You -> can find a list of the keywords in Appendix A. +> The Rust language has a set of *keywords* that are reserved for use by the +language only, much as in other languages. Keep in mind that you cannot use +these words as names of variables or functions. Most of the keywords have +special meanings, and you’ll be using them to do various tasks in your Rust +programs; a few have no current functionality associated with them but have +been reserved for functionality that might be added to Rust in the future. You +can find a list of the keywords in Appendix A. ## Variables and Mutability -As mentioned in the “Storing Values with Variables†section, by default +As mentioned in “Storing Values with Variables†on page XX, by default, 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. @@ -38,12 +38,11 @@ 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, let’s generate a new project called *variables* -in your *projects* directory by using `cargo new variables`. +that value. To illustrate this, generate a new project called *variables* in +your *projects* directory by using `cargo new variables`. Then, in your new *variables* directory, open *src/main.rs* and replace its -code with the following code. This code won’t compile just yet, we’ll first -examine the immutability error. +code with the following code, which won’t compile just yet: Filename: src/main.rs @@ -56,8 +55,8 @@ fn main() { } ``` -Save and run the program using `cargo run`. You should receive an error -message, as shown in this output: +Save and run the program using `cargo run`. You should receive an error message +regarding an immutability error, as shown in this output: ``` $ cargo run @@ -80,9 +79,8 @@ 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. -The error message indicates that the cause of the error is that you `` cannot -assign twice to immutable variable `x` ``, because you tried to assign a second -value to the immutable `x` variable. +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. 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 @@ -91,15 +89,15 @@ 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 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 +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. But mutability can be very useful, and can make code more convenient to write. -Variables are immutable only by default; as you did in Chapter 2, you can make -them mutable by adding `mut` in front of the variable name. 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. +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. 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. For example, let’s change *src/main.rs* to the following: @@ -125,18 +123,10 @@ The value of x is: 5 The value of x is: 6 ``` -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 is up to you and +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 is up to you and depends on what you think is clearest in that particular situation. -<!--- Just to voice some thoughts here: there's a kind of bad pattern I see sometimes -with the Rust dev mindset around performance. In my experience it happens maybe less -often than you'd think that cloning shows up in the profile as a performance hit. I -wonder if we should maybe tone down or remove the discussion of performance above -because it's far stronger for the developer to pick a clear representation for their -program and then improve performance after they've found that model. /JT ---> -<!-- Ok, I've removed the discussion of performance here. Good call. /Carol --> - ### Constants Like immutable variables, *constants* are values that are bound to a name and @@ -146,9 +136,9 @@ 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. We’re about to cover types and type annotations in the next -section, “Data Types,†so don’t worry about the details right now. Just know -that you must always annotate the type. +be annotated. We’ll cover types and type annotations in “Data Types†on page +XX, 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. @@ -169,15 +159,15 @@ program). Rust’s naming convention for constants is to use all uppercase with underscores between words. The compiler is able to evaluate a limited set of operations at compile time, which lets us choose to write out this value in a way that’s easier to understand and verify, rather than setting this constant -to the value 10,800. See the Rust Reference’s section on constant evaluation at -*https://doc.rust-lang.org/reference/const_eval.html* for more information on -what operations can be used when declaring constants. +to the value `10,800`. See the Rust Reference’s section on constant evaluation +at *https://doc.rust-lang.org/reference/const_eval.html* for more information +on what operations can be used when declaring constants. -Constants are valid for the entire time a program runs, within the scope they -were declared in. 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 or -the speed of light. +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, 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 @@ -195,21 +185,6 @@ 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: -<!--- A potential reword of the above for clarity: - -As you saw in the guessing game tutorial in Chapter 2, 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: - -/JT ---> -<!-- Sounds good to me, I've made the change to JT's version. What do you -think, Liz? /Carol --> - Filename: src/main.rs ``` @@ -226,17 +201,6 @@ fn main() { println!("The value of x is: {x}"); } ``` -<!--- We haven't really introduced block scoping yet. I know we're starting -with variables, but I wonder if we should introduce scopes before shadowing, -or explain that each block has its own set of variables. -/JT ---> -<!-- Chapter 4 goes into scopes in more detail. I feel like block scoping is a -pretty common programming concept, and the behavior of scopes in Rust that -we're demonstrating here is the same behavior as scopes have in most other -common programming languages. I don't recall getting comments from readers -being confused about scopes at this point. I added a small phrase in the next -paragraph that the curly brackets are creating a new scope... do you think -that's enough, Liz? /Carol --> This program first binds `x` to a value of `5`. Then it creates a new variable `x` by repeating `let x =`, taking the original value and adding `1` so the @@ -246,10 +210,6 @@ variable, multiplying the previous value by `2` to give `x` a value of `12`. When that scope is over, the inner shadowing ends and `x` returns to being `6`. When we run this program, it will output the following: -<!--- I lean towards reiterating that each `let x` is creating a new variable. -/JT --> -<!-- I've added a few mentions to that effect in the previous paragraph, what do you think, Liz? /Carol --> - ``` $ cargo run Compiling variables v0.1.0 (file:///projects/variables) @@ -259,46 +219,21 @@ The value of x in the inner scope is: 12 The value of x is: 6 ``` -Shadowing is different from marking a variable as `mut`, because we’ll get a +Shadowing is different from marking a variable as `mut` because we’ll get a compile-time error if we accidentally try to reassign to this variable without using the `let` keyword. By using `let`, we can perform a few transformations on a value but have the variable be immutable after those transformations have been completed. -<!--- so, to be clear, we're not overwriting the variable, so when the -shadowing variable goes out of scope the earlier variables become visible to -the compiler? ---> -<!-- Well, we *are* overwriting it *in the inner scope* -- there's no way to -access the original value from the outer scope within the inner scope after -the shadowing. But yes, shadowing only applies to the scope it happens in, -which is what this example illustrates. Is there something that could be -made clearer? /Carol --> -<!-- JT, what do you think, is this clear enough as is or is there some way to clarify in the text? /LC --> -<!--- I made a couple notes above trying to see if we could tease out a good -explanation. Shadowing is effectively creating new variables and then these -variables get a kind of "higher priority" when you look up the same variable -name. Shadowing priority is kind of a "most recent wins", and it stays until -that variable is shadowed by a following one or that variable goes out of scope. -/JT --> - The other difference between `mut` and shadowing is that because we’re 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: -<!--- Question: the further I read, the more I wonder if we should put the shadowing -stuff later. Is it valuable here as a kind of "building the right mental model" or -are we using up too much of our complexity budget for building that mental model -relatively early in the journey? Once we're introducing shadowing into new types -we're getting relatively deep into Rust-specific coding patterns /JT --> -<!-- I think it's important to address this here because shadowing is extremely -common in idiomatic Rust code, but can be unfamiliar. I'm not sure where it -would be appropriate to address if not here. /Carol --> - ``` - let spaces = " "; - let spaces = spaces.len(); +let spaces = " "; +let spaces = spaces.len(); ``` The first `spaces` variable is a string type and the second `spaces` variable @@ -308,8 +243,8 @@ the simpler `spaces` name. However, if we try to use `mut` for this, as shown here, we’ll get a compile-time error: ``` - let mut spaces = " "; - spaces = spaces.len(); +let mut spaces = " "; +spaces = spaces.len(); ``` The error says we’re not allowed to mutate a variable’s type: @@ -339,20 +274,16 @@ Keep in mind that Rust is a *statically typed* language, which means that it must know the types of all variables at compile time. The compiler can usually infer what type we want to use based on the value and how we use it. In cases when many types are possible, such as when we converted a `String` to a numeric -type using `parse` in the “Comparing the Guess to the Secret Number†section in -Chapter 2, we must add a type annotation, like this: +type using `parse` in “Comparing the Guess to the Secret Number†on page XX, we +must add a type annotation, like this: ``` let guess: u32 = "42".parse().expect("Not a number!"); ``` -If we don’t add the `: u32` type annotation above, Rust will display the -following error, which means the compiler needs more information from us to -know which type we want to use: - -<!--- To help visual parsing, you might want to say "If we don't add the `: u32` type -annotation above... /JT ---> -<!-- Done /Carol --> +If we don’t add the `: u32` type annotation shown in the preceding code, Rust +will display the following error, which means the compiler needs more +information from us to know which type we want to use: ``` $ cargo build @@ -377,20 +308,20 @@ these from other programming languages. Let’s jump into how they work in Rust. An *integer* is a number without a fractional component. We used one integer type in Chapter 2, the `u32` type. This type declaration indicates that the value it’s associated with should be an unsigned integer (signed integer types -start with `i`, instead of `u`) that takes up 32 bits of space. Table 3-1 shows +start with `i` instead of `u`) that takes up 32 bits of space. Table 3-1 shows the built-in integer types in Rust. We can use any of these variants to declare the type of an integer value. Table 3-1: Integer Types in Rust -| Length | Signed | Unsigned | -|---------|---------|----------| -| 8-bit | `i8` | `u8` | -| 16-bit | `i16` | `u16` | -| 32-bit | `i32` | `u32` | -| 64-bit | `i64` | `u64` | -| 128-bit | `i128` | `u128` | -| arch | `isize` | `usize` | +| Length | Signed | Unsigned | +|---|---|---| +| 8-bit | `i8` | `u8` | +| 16-bit | `i16` | `u16` | +| 32-bit | `i32` | `u32` | +| 64-bit | `i64` | `u64` | +| 128-bit | `i128` | `u128` | +| arch | `isize` | `usize` | Each variant can be either signed or unsigned and has an explicit size. *Signed* and *unsigned* refer to whether it’s possible for the number to be @@ -420,55 +351,54 @@ have the same value as if you had specified `1000`. Table 3-2: Integer Literals in Rust -| Number literals | Example | -|------------------|---------------| -| Decimal | `98_222` | -| Hex | `0xff` | -| Octal | `0o77` | -| Binary | `0b1111_0000` | -| Byte (`u8` only) | `b'A'` | +| Number literals | Example | +|---|---| +| Decimal | `98_222` | +| Hex | `0xff` | +| Octal | `0o77` | +| Binary | `0b1111_0000` | +| Byte (`u8` only) | `b'A'` | So how do you know which type of integer to use? If you’re unsure, Rust’s defaults are generally good places to start: integer types default to `i32`. The primary situation in which you’d use `isize` or `usize` is when indexing some sort of collection. -> ##### Integer Overflow +> ### Integer Overflow > > Let’s say you have a variable of type `u8` that can hold values between 0 and -> 255. If you try to change the variable to a value outside of that range, such -> as 256, *integer overflow* will occur, which can result in one of two -> behaviors. When you’re compiling in debug mode, Rust includes checks for -> integer overflow that cause your program to *panic* at runtime if this -> behavior occurs. Rust uses the term panicking when a program exits with an -> error; we’ll discuss panics in more depth in the “Unrecoverable Errors with -> `panic!`†section in Chapter 9. +255. If you try to change the variable to a value outside that range, such as +256, *integer overflow* will occur, which can result in one of two behaviors. +When you’re compiling in debug mode, Rust includes checks for integer overflow +that cause your program to *panic* at runtime if this behavior occurs. Rust +uses the term *panicking* when a program exits with an error; we’ll discuss +panics in more depth in “Unrecoverable Errors with panic!†on page XX. > > When you’re compiling in release mode with the `--release` flag, Rust does -> *not* include checks for integer overflow that cause panics. Instead, if -> overflow occurs, Rust performs *two’s complement wrapping*. In short, values -> greater than the maximum value the type can hold “wrap around†to the minimum -> of the values the type can hold. In the case of a `u8`, the value 256 becomes -> 0, the value 257 becomes 1, and so on. The program won’t panic, but the -> variable will have a value that probably isn’t what you were expecting it to -> have. Relying on integer overflow’s wrapping behavior is considered an error. +*not* include checks for integer overflow that cause panics. Instead, if +overflow occurs, Rust performs *two’s complement wrapping*. In short, values +greater than the maximum value the type can hold “wrap around†to the minimum +of the values the type can hold. In the case of a `u8`, the value 256 becomes +0, the value 257 becomes 1, and so on. The program won’t panic, but the +variable will have a value that probably isn’t what you were expecting it to +have. Relying on integer overflow’s wrapping behavior is considered an error. > > To explicitly handle the possibility of overflow, you can use these families -> of methods provided by the standard library for primitive numeric types: +of methods provided by the standard library for primitive numeric types: > -> - Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add` -> - Return the `None` value if there is overflow with the `checked_*` methods -> - Return the value and a boolean indicating whether there was overflow with -> the `overflowing_*` methods -> - Saturate at the value’s minimum or maximum values with `saturating_*` -> methods +> * Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add`. +> * Return the `None` value if there is overflow with the `checked_*` methods. +> * Return the value and a boolean indicating whether there was overflow with +the `overflowing_*` methods. +> * Saturate at the value’s minimum or maximum values with the `saturating_*` +methods. #### Floating-Point Types Rust also has two primitive types for *floating-point numbers*, which are numbers with decimal points. Rust’s floating-point types are `f32` and `f64`, which are 32 bits and 64 bits in size, respectively. The default type is `f64` -because on modern CPUs it’s roughly the same speed as `f32` but is capable of +because on modern CPUs, it’s roughly the same speed as `f32` but is capable of more precision. All floating-point types are signed. Here’s an example that shows floating-point numbers in action: @@ -488,9 +418,9 @@ Floating-point numbers are represented according to the IEEE-754 standard. The #### Numeric Operations -Rust supports the basic mathematical operations you’d expect for all of the -number types: addition, subtraction, multiplication, division, and remainder. -Integer division rounds down to the nearest integer. The following code shows +Rust supports the basic mathematical operations you’d expect for all the number +types: addition, subtraction, multiplication, division, and remainder. Integer +division truncates toward zero to the nearest integer. The following code shows how you’d use each numeric operation in a `let` statement: Filename: src/main.rs @@ -508,7 +438,7 @@ fn main() { // division let quotient = 56.7 / 32.2; - let floored = 2 / 3; // Results in 0 + let truncated = -5 / 3; // Results in -1 // remainder let remainder = 43 % 5; @@ -536,12 +466,12 @@ fn main() { ``` The main way to use Boolean values is through conditionals, such as an `if` -expression. We’ll cover how `if` expressions work in Rust in the “Control -Flow†section. +expression. We’ll cover how `if` expressions work in Rust in “Control Flow†on +page XX. #### The Character Type -Rust’s `char` type is the language’s most primitive alphabetic type. Here’s +Rust’s `char` type is the language’s most primitive alphabetic type. Here are some examples of declaring `char` values: Filename: src/main.rs @@ -563,7 +493,7 @@ Values range from `U+0000` to `U+D7FF` and `U+E000` to `U+10FFFF` inclusive. However, a “character†isn’t really a concept in Unicode, so your human intuition for what a “character†is may not match up with what a `char` is in Rust. We’ll discuss this topic in detail in “Storing UTF-8 Encoded Text with -Strings†in Chapter 8. +Strings†on page XX. ### Compound Types @@ -572,9 +502,9 @@ primitive compound types: tuples and arrays. #### The Tuple Type -A tuple is a general way of grouping together a number of values with a variety -of types into one compound type. Tuples have a fixed length: once declared, -they cannot grow or shrink in size. +A *tuple* is a general way of grouping together a number of values with a +variety of types into one compound type. Tuples have a fixed length: once +declared, they cannot grow or shrink in size. We create a tuple by writing a comma-separated list of values inside parentheses. Each position in the tuple has a type, and the types of the @@ -589,7 +519,7 @@ fn main() { } ``` -The variable `tup` binds to the entire tuple, because a tuple is considered a +The variable `tup` binds to the entire tuple because a tuple is considered a single compound element. To get the individual values out of a tuple, we can use pattern matching to destructure a tuple value, like this: @@ -607,7 +537,7 @@ fn main() { This program first creates a tuple and binds it to the variable `tup`. It then uses a pattern with `let` to take `tup` and turn it into three separate -variables, `x`, `y`, and `z`. This is called *destructuring*, because it breaks +variables, `x`, `y`, and `z`. This is called *destructuring* because it breaks the single tuple into three parts. Finally, the program prints the value of `y`, which is `6.4`. @@ -632,28 +562,11 @@ This program creates the tuple `x` and then accesses each element of the tuple using their respective indices. As with most programming languages, the first index in a tuple is 0. -<!--- Indexing into a tuple using a constant, just like accessing a field of a struct, -I think is maybe a more natural way to think of this than thinking of `x.0`, `x.1`, etc -as separate variables. In the struct case, we don't think of each field as a separate -variable, but instead that there's a path to get to the contained values that can be -used and checked at compile time. /JT ---> -<!-- I think JT was actually confused with what this paragraph was trying to -say, it was explaining that this particular example created new variables and -bound them to the values of the tuple elements, not that the tuple elements -*were* separate variables, so I've reworded this paragraph. Please check that -this makes sense, Liz! /Carol --> - The tuple without any values has a special name, *unit*. This value and its corresponding type are both written `()` and represent an empty value or an empty return type. Expressions implicitly return the unit value if they don’t return any other value. -<!--- It's trick to see the difference between `()` and `()`. Maybe we can say: "The -tuple without any values has a special name, *unit*. This value, and its corresponding -type -- also written `()` -- represent an empty value or an empty return type." /JT ---> -<!-- I've tried to clear this up, but didn't take JT's suggestion exactly, -there were too many subphrases in my opinion /Carol --> - #### The Array Type Another way to have a collection of multiple values is with an *array*. Unlike @@ -674,7 +587,7 @@ fn main() { Arrays are useful when you want your data allocated on the stack rather than the heap (we will discuss the stack and the heap more in Chapter 4) or when you want to ensure you always have a fixed number of elements. An array isn’t as -flexible as the vector type, though. A vector is a similar collection type +flexible as the vector type, though. A *vector* is a similar collection type provided by the standard library that *is* allowed to grow or shrink in size. If you’re unsure whether to use an array or a vector, chances are you should use a vector. Chapter 8 discusses vectors in more detail. @@ -711,7 +624,7 @@ The array named `a` will contain `5` elements that will all be set to the value `3` initially. This is the same as writing `let a = [3, 3, 3, 3, 3];` but in a more concise way. -##### Accessing Array Elements +#### Accessing Array Elements An array is a single chunk of memory of a known, fixed size that can be allocated on the stack. You can access elements of an array using indexing, @@ -728,11 +641,11 @@ fn main() { } ``` -In this example, the variable named `first` will get the value `1`, because -that is the value at index `[0]` in the array. The variable named `second` will -get the value `2` from index `[1]` in the array. +In this example, the variable named `first` will get the value `1` because that +is the value at index `[0]` in the array. The variable named `second` will get +the value `2` from index `[1]` in the array. -##### Invalid Array Element Access +#### Invalid Array Element Access Let’s see what happens if you try to access an element of an array that is past the end of the array. Say you run this code, similar to the guessing game in @@ -768,12 +681,13 @@ fn main() { ``` This code compiles successfully. If you run this code using `cargo run` and -enter 0, 1, 2, 3, or 4, the program will print out the corresponding value at -that index in the array. If you instead enter a number past the end of the -array, such as 10, you’ll see output like this: +enter `0`, `1`, `2`, `3`, or `4`, the program will print out the corresponding +value at that index in the array. If you instead enter a number past the end of +the array, such as `10`, you’ll see output like this: ``` -thread 'main' panicked at 'index out of bounds: the len is 5 but the index is 10', src/main.rs:19:19 +thread 'main' panicked at 'index out of bounds: the len is 5 but the index is +10', src/main.rs:19:19 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` @@ -793,13 +707,6 @@ kind of error by immediately exiting instead of allowing the memory access and continuing. Chapter 9 discusses more of Rust’s error handling and how you can write readable, safe code that neither panics nor allows invalid memory access. -<!--- I get the idea, though I'm feeling a little uneasy with leaving the reader -thinking "panic > invalid access" as the end of the story. Maybe we can tag something -on to the end: "Chapter 9 discusses more of Rust's error handling, and how you can -write readable, safe code that doesn't panic and doesn't allow invalid memory access. -/JT ---> -<!-- I've incorporated JT's suggestion with a bit of rewording above /Carol --> - ## Functions Functions are prevalent in Rust code. You’ve already seen one of the most @@ -836,14 +743,6 @@ called from inside the `main` function. Note that we defined `another_function` as well. Rust doesn’t care where you define your functions, only that they’re defined somewhere in a scope that can be seen by the caller. -<!--- nit: Rust does want the functions in a place the caller can see. If they're -not in scope, Rust won't let the program build. Maybe we can say: -"only that they're defined somewhere the caller can see them". -or alt: "only that they're defined somewhere in a scope that can be seen by the -caller" -/JT ---> -<!-- Done! /Carol --> - Let’s start a new binary project named *functions* to explore functions further. Place the `another_function` example in *src/main.rs* and run it. You should see the following output: @@ -858,8 +757,8 @@ Another function. ``` The lines execute in the order in which they appear in the `main` function. -First, the “Hello, world!†message prints, and then `another_function` is -called and its message is printed. +First the “Hello, world!†message prints, and then `another_function` is called +and its message is printed. ### Parameters @@ -885,9 +784,6 @@ fn another_function(x: i32) { } ``` -<!--- nit: might want to use `{x}` /JT ---> -<!-- Done! /Carol --> - Try running this program; you should get the following output: ``` @@ -909,9 +805,6 @@ definitions means the compiler almost never needs you to use them elsewhere in the code to figure out what type you mean. The compiler is also able to give more helpful error messages if it knows what types the function expects. -<!--- Also helps give much better error messages /JT ---> -<!-- Added a note! /Carol --> - When defining multiple parameters, separate the parameter declarations with commas, like this: @@ -957,19 +850,14 @@ understand. Other languages don’t have the same distinctions, so let’s look what statements and expressions are and how their differences affect the bodies of functions. -*Statements* are instructions that perform some action and do not return a -value. *Expressions* evaluate to a resulting value. Let’s look at some examples. +* **Statements **: are instructions that perform some action and do not return +a value. +* **Expressions **: evaluate to a resultant value. Let’s look at some examples. We’ve actually already used statements and expressions. Creating a variable and assigning a value to it with the `let` keyword is a statement. In Listing 3-1, `let y = 6;` is a statement. -<!--- To help clarify how they're related, we could say that "`let y = 6;`" is a -statement, and the `6` being assigned to `y` is an expression. edit: I see we -say this later, just thought it might be a little nicer to give an examples of -each just following their definition. /JT ---> -<!-- I think I'm going to leave this as-is /Carol --> - Filename: src/main.rs ``` @@ -1007,33 +895,16 @@ error: expected expression, found statement (`let`) | = note: variable declaration using `let` is a statement -error[E0658]: `let` expressions in this position are experimental +error[E0658]: `let` expressions in this position are unstable --> src/main.rs:2:14 | 2 | let x = (let y = 6); | ^^^^^^^^^ | - = note: see issue #53667 <https://github.com/rust-lang/rust/issues/53667> for more information - = help: you can write `matches!(<expr>, <pattern>)` instead of `let <pattern> = <expr>` - -warning: unnecessary parentheses around assigned value - --> src/main.rs:2:13 - | -2 | let x = (let y = 6); - | ^ ^ - | - = note: `#[warn(unused_parens)]` on by default -help: remove these parentheses - | -2 - let x = (let y = 6); -2 + let x = let y = 6; - | + = note: see issue #53667 <https://github.com/rust-lang/rust/issues/53667> for +more information ``` -<!--- The errors in more recent Rust look slightly different here, if we want -to update before publication. /JT ---> -<!-- Updated here and I will also check when we're in Word /Carol --> - The `let y = 6` statement does not return a value, so there isn’t anything for `x` to bind to. This is different from what happens in other languages, such as C and Ruby, where the assignment returns the value of the assignment. In those @@ -1052,30 +923,22 @@ Filename: src/main.rs ``` fn main() { - let y = { + 1 let y = {2 let x = 3; - x + 1 + 3 x + 1 }; println!("The value of y is: {y}"); } ``` -This expression: - -``` -{ - let x = 3; - x + 1 -} -``` - -is a block that, in this case, evaluates to `4`. That value gets bound to `y` -as part of the `let` statement. Note that the `x + 1` line doesn’t have a -semicolon at the end, unlike most of the lines you’ve seen so far. Expressions -do not include ending semicolons. If you add a semicolon to the end of an -expression, you turn it into a statement, and it will then not return a value. -Keep this in mind as you explore function return values and expressions next. +The expression [2] is a block that, in this case, evaluates to `4`. That value +gets bound to `y` as part of the `let` statement [1]. Note the line without a +semicolon at the end [3], which is unlike most of the lines you’ve seen so far. +Expressions do not include ending semicolons. If you add a semicolon to the end +of an expression, you turn it into a statement, and it will then not return a +value. Keep this in mind as you explore function return values and expressions +next. ### Functions with Return Values @@ -1128,10 +991,6 @@ Second, the `five` function has no parameters and defines the type of the return value, but the body of the function is a lonely `5` with no semicolon because it’s an expression whose value we want to return. -<!--- If you want, you could point out that the `println!` line that main ends -on is a statement, hence why main doesn't have a return value. /JT ---> -<!-- I don't think I want to :) /Carol --> - Let’s look at another example: Filename: src/main.rs @@ -1150,7 +1009,7 @@ fn plus_one(x: i32) -> i32 { Running this code will print `The value of x is: 6`. But if we place a semicolon at the end of the line containing `x + 1`, changing it from an -expression to a statement, we’ll get an error. +expression to a statement, we’ll get an error: Filename: src/main.rs @@ -1179,10 +1038,10 @@ error[E0308]: mismatched types | | | implicitly returns `()` as its body has no tail or `return` expression 8 | x + 1; - | - help: consider removing this semicolon + | - help: remove this semicolon ``` -The main error message, “mismatched types,†reveals the core issue with this +The main error message, `mismatched types`, reveals the core issue with this code. The definition of the function `plus_one` says that it will return an `i32`, but statements don’t evaluate to a value, which is expressed by `()`, the unit type. Therefore, nothing is returned, which contradicts the function @@ -1236,16 +1095,16 @@ fn main() { ``` Rust also has another kind of comment, documentation comments, which we’ll -discuss in the “Publishing a Crate to Crates.io†section of Chapter 14. +discuss in “Publishing a Crate to Crates.io†on page XX. ## Control Flow -The ability to run some code depending on if a condition is true, or run some -code repeatedly while a condition is true, are basic building blocks in most -programming languages. The most common constructs that let you control the flow -of execution of Rust code are `if` expressions and loops. +The ability to run some code depending on whether a condition is `true` and to +run some code repeatedly while a condition is `true` are basic building blocks +in most programming languages. The most common constructs that let you control +the flow of execution of Rust code are `if` expressions and loops. -### `if` Expressions +### if Expressions An `if` expression allows you to branch your code depending on conditions. You provide a condition and then state, “If this condition is met, run this block @@ -1270,16 +1129,16 @@ fn main() { All `if` expressions start with the keyword `if`, followed by a condition. In this case, the condition checks whether or not the variable `number` has a -value less than 5. We place the block of code to execute if the condition is true -immediately after the condition inside curly brackets. Blocks of code +value less than 5. We place the block of code to execute if the condition is +`true` immediately after the condition inside curly brackets. Blocks of code associated with the conditions in `if` expressions are sometimes called *arms*, -just like the arms in `match` expressions that we discussed in the “Comparing -the Guess to the Secret Number†section of Chapter 2. +just like the arms in `match` expressions that we discussed in “Comparing the +Guess to the Secret Number†on page XX. -Optionally, we can also include an `else` expression, which we chose -to do here, to give the program an alternative block of code to execute should -the condition evaluate to false. If you don’t provide an `else` expression and -the condition is false, the program will just skip the `if` block and move on +Optionally, we can also include an `else` expression, which we chose to do +here, to give the program an alternative block of code to execute should the +condition evaluate to `false`. If you don’t provide an `else` expression and +the condition is `false`, the program will just skip the `if` block and move on to the next bit of code. Try running this code; you should see the following output: @@ -1359,7 +1218,7 @@ fn main() { Running this code will print `number was something other than zero`. -#### Handling Multiple Conditions with `else if` +#### Handling Multiple Conditions with else if You can use multiple conditions by combining `if` and `else` in an `else if` expression. For example: @@ -1394,17 +1253,17 @@ number is divisible by 3 ``` When this program executes, it checks each `if` expression in turn and executes -the first body for which the condition holds true. Note that even though 6 is -divisible by 2, we don’t see the output `number is divisible by 2`, nor do we -see the `number is not divisible by 4, 3, or 2` text from the `else` block. -That’s because Rust only executes the block for the first true condition, and -once it finds one, it doesn’t even check the rest. +the first body for which the condition evaluates to `true`. Note that even +though 6 is divisible by 2, we don’t see the output `number is divisible by 2`, +nor do we see the `number is not divisible by 4, 3, or 2` text from the `else` +block. That’s because Rust only executes the block for the first `true` +condition, and once it finds one, it doesn’t even check the rest. Using too many `else if` expressions can clutter your code, so if you have more than one, you might want to refactor your code. Chapter 6 describes a powerful Rust branching construct called `match` for these cases. -#### Using `if` in a `let` Statement +#### Using if in a let Statement Because `if` is an expression, we can use it on the right side of a `let` statement to assign the outcome to a variable, as in Listing 3-2. @@ -1420,19 +1279,8 @@ fn main() { } ``` -<!--- Style nit: `{number}`. /JT ---> -<!-- Fixed! /Carol --> - Listing 3-2: Assigning the result of an `if` expression to a variable -<!--- I was wondering when listings got numbered and when they didn't. Many of -the above don't get a number a title, though maybe it'd help readability? /JT ---> -<!-- Liz: Chapter 3 doesn't have many listing numbers because on the first -round of printing, we hadn't really figured out what we were doing with listing -numbers yet. I'm happy to add more listing numbers in Chapter 3, but it'll take -me some time to go through and add appropriate captions, check cross -references, etc. Let me know if you'd like me to spend that time. /Carol --> - The `number` variable will be bound to a value based on the outcome of the `if` expression. Run this code to see what happens: @@ -1475,7 +1323,8 @@ error[E0308]: `if` and `else` have incompatible types --> src/main.rs:4:44 | 4 | let number = if condition { 5 } else { "six" }; - | - ^^^^^ expected integer, found `&str` + | - ^^^^^ expected integer, found +`&str` | | | expected because of this ``` @@ -1493,12 +1342,12 @@ if it had to keep track of multiple hypothetical types for any variable. It’s often useful to execute a block of code more than once. For this task, Rust provides several *loops*, which will run through the code inside the loop -body to the end and then start immediately back at the beginning. To -experiment with loops, let’s make a new project called *loops*. +body to the end and then start immediately back at the beginning. To experiment +with loops, let’s make a new project called *loops*. Rust has three kinds of loops: `loop`, `while`, and `for`. Let’s try each one. -#### Repeating Code with `loop` +#### Repeating Code with loop The `loop` keyword tells Rust to execute a block of code over and over again forever or until you explicitly tell it to stop. @@ -1517,9 +1366,9 @@ fn main() { ``` When we run this program, we’ll see `again!` printed over and over continuously -until we stop the program manually. Most terminals support the keyboard shortcut -<span class="keystroke">ctrl-c</span> to interrupt a program that is stuck in -a continual loop. Give it a try: +until we stop the program manually. Most terminals support the keyboard +shortcut ctrl-C to interrupt a program that is stuck in a continual loop. Give +it a try: ``` $ cargo run @@ -1533,25 +1382,20 @@ again! ^Cagain! ``` -The symbol `^C` represents where you pressed <span class="keystroke">ctrl-c -</span>. You may or may not see the word `again!` printed after the `^C`, -depending on where the code was in the loop when it received the interrupt -signal. +The symbol `^C` represents where you pressed ctrl-C. You may or may not see the +word `again!` printed after the `^C`, depending on where the code was in the +loop when it received the interrupt signal. Fortunately, Rust also provides a way to break out of a loop using code. You can place the `break` keyword within the loop to tell the program when to stop -executing the loop. Recall that we did this in the guessing game in the -“Quitting After a Correct Guess†section of Chapter 2 to exit the program when -the user won the game by guessing the correct number. +executing the loop. Recall that we did this in the guessing game in “Quitting +After a Correct Guess†on page XX to exit the program when the user won the +game by guessing the correct number. We also used `continue` in the guessing game, which in a loop tells the program to skip over any remaining code in this iteration of the loop and go to the next iteration. -<!--- Before you show loop labels below, you might want to give a code example -of using `break` to break a loop. /JT ---> -<!-- I've rearranged the sections to take this suggestion here /Carol --> - #### Returning Values from Loops One of the uses of a `loop` is to retry an operation you know might fail, such @@ -1580,20 +1424,18 @@ fn main() { Before the loop, we declare a variable named `counter` and initialize it to `0`. Then we declare a variable named `result` to hold the value returned from the loop. On every iteration of the loop, we add `1` to the `counter` variable, -and then check whether the counter is equal to `10`. When it is, we use the +and then check whether the `counter` is equal to `10`. When it is, we use the `break` keyword with the value `counter * 2`. After the loop, we use a semicolon to end the statement that assigns the value to `result`. Finally, we -print the value in `result`, which in this case is 20. +print the value in `result`, which in this case is `20`. #### Loop Labels to Disambiguate Between Multiple Loops -<!-- Liz: New heading for this section, what do you think? /Carol --> - If you have loops within loops, `break` and `continue` apply to the innermost -loop at that point. You can optionally specify a *loop label* on a loop that we -can then use with `break` or `continue` to specify that those keywords apply to -the labeled loop instead of the innermost loop. Loop labels must begin with a -single quote. Here’s an example with two nested loops: +loop at that point. You can optionally specify a *loop label* on a loop that +you can then use with `break` or `continue` to specify that those keywords +apply to the labeled loop instead of the innermost loop. Loop labels must begin +with a single quote. Here’s an example with two nested loops: ``` fn main() { @@ -1639,10 +1481,10 @@ remaining = 10 End count = 2 ``` -#### Conditional Loops with `while` +#### Conditional Loops with while A program will often need to evaluate a condition within a loop. While the -condition is true, the loop runs. When the condition ceases to be true, the +condition is `true`, the loop runs. When the condition ceases to be `true`, the program calls `break`, stopping the loop. It’s possible to implement behavior like this using a combination of `loop`, `if`, `else`, and `break`; you could try that now in a program, if you’d like. However, this pattern is so common @@ -1666,13 +1508,14 @@ fn main() { } ``` -Listing 3-3: Using a `while` loop to run code while a condition holds true +Listing 3-3: Using a `while` loop to run code while a condition evaluates to +`true` This construct eliminates a lot of nesting that would be necessary if you used -`loop`, `if`, `else`, and `break`, and it’s clearer. While a condition holds -true, the code runs; otherwise, it exits the loop. +`loop`, `if`, `else`, and `break`, and it’s clearer. While a condition +evaluates to `true`, the code runs; otherwise, it exits the loop. -#### Looping Through a Collection with `for` +#### Looping Through a Collection with for You can choose to use the `while` construct to loop over the elements of a collection, such as an array. For example, the loop in Listing 3-4 prints each @@ -1697,8 +1540,8 @@ Listing 3-4: Looping through each element of a collection using a `while` loop Here, the code counts up through the elements in the array. It starts at index `0`, and then loops until it reaches the final index in the array (that is, -when `index < 5` is no longer true). Running this code will print every element -in the array: +when `index < 5` is no longer `true`). Running this code will print every +element in the array: ``` $ cargo run @@ -1717,8 +1560,8 @@ will reach a value of `5` at some point, the loop stops executing before trying to fetch a sixth value from the array. However, this approach is error prone; we could cause the program to panic if -the index value or test condition are incorrect. For example, if you changed -the definition of the `a` array to have four elements but forgot to update the +the index value or test condition is incorrect. For example, if you changed the +definition of the `a` array to have four elements but forgot to update the condition to `while index < 4`, the code would panic. It’s also slow, because the compiler adds runtime code to perform the conditional check of whether the index is within the bounds of the array on every iteration through the loop. @@ -1775,15 +1618,16 @@ This code is a bit nicer, isn’t it? ## Summary -You made it! That was a sizable chapter: you learned about variables, scalar -and compound data types, functions, comments, `if` expressions, and loops! -To practice with the concepts discussed in this chapter, try building -programs to do the following: +You made it! This was a sizable chapter: you learned about variables, scalar +and compound data types, functions, comments, `if` expressions, and loops! To +practice with the concepts discussed in this chapter, try building programs to +do the following: * Convert temperatures between Fahrenheit and Celsius. -* Generate the nth Fibonacci number. +* Generate the *n*th Fibonacci number. * Print the lyrics to the Christmas carol “The Twelve Days of Christmas,†- taking advantage of the repetition in the song. +taking advantage of the repetition in the song. When you’re ready to move on, we’ll talk about a concept in Rust that *doesn’t* commonly exist in other programming languages: ownership. + diff --git a/src/doc/book/nostarch/chapter04.md b/src/doc/book/nostarch/chapter04.md index cbcad103e..11f7f4944 100644 --- a/src/doc/book/nostarch/chapter04.md +++ b/src/doc/book/nostarch/chapter04.md @@ -16,21 +16,15 @@ features: borrowing, slices, and how Rust lays data out in memory. ## What Is Ownership? -*Ownership* is a set of rules that governs how a Rust program manages memory. +*Ownership* is a set of rules that govern how a Rust program manages memory. All programs have to manage the way they use a computer’s memory while running. -Some languages have garbage collection that regularly looks for no-longer used +Some languages have garbage collection that regularly looks for no-longer-used memory as the program runs; in other languages, the programmer must explicitly allocate and free the memory. Rust uses a third approach: memory is managed through a system of ownership with a set of rules that the compiler checks. If any of the rules are violated, the program won’t compile. None of the features of ownership will slow down your program while it’s running. -<!--- Minor nit: garbage collection isn't constant, it happens at times specified -by the collection algorithm. Maybe "Some languages have garbage collection that -regularly looks for no-longer used memory as the program runs." -/JT ---> -<!-- Took this suggestion! /Carol --> - Because ownership is a new concept for many programmers, it does take some time to get used to. The good news is that the more experienced you become with Rust and the rules of the ownership system, the easier you’ll find it to naturally @@ -44,92 +38,63 @@ strings. > ### The Stack and the Heap > > Many programming languages don’t require you to think about the stack and the -> heap very often. But in a systems programming language like Rust, whether a -> value is on the stack or the heap affects how the language behaves and why -> you have to make certain decisions. Parts of ownership will be described in -> relation to the stack and the heap later in this chapter, so here is a brief -> explanation in preparation. +heap very often. But in a systems programming language like Rust, whether a +value is on the stack or the heap affects how the language behaves and why you +have to make certain decisions. Parts of ownership will be described in +relation to the stack and the heap later in this chapter, so here is a brief +explanation in preparation. > > Both the stack and the heap are parts of memory available to your code to use -> at runtime, but they are structured in different ways. The stack stores -> values in the order it gets them and removes the values in the opposite -> order. This is referred to as *last in, first out*. Think of a stack of -> plates: when you add more plates, you put them on top of the pile, and when -> you need a plate, you take one off the top. Adding or removing plates from -> the middle or bottom wouldn’t work as well! Adding data is called *pushing -> onto the stack*, and removing data is called *popping off the stack*. All -> data stored on the stack must have a known, fixed size. Data with an unknown -> size at compile time or a size that might change must be stored on the heap -> instead. +at runtime, but they are structured in different ways. The stack stores values +in the order it gets them and removes the values in the opposite order. This is +referred to as *last in, first out*. Think of a stack of plates: when you add +more plates, you put them on top of the pile, and when you need a plate, you +take one off the top. Adding or removing plates from the middle or bottom +wouldn’t work as well! Adding data is called *pushing onto the stack*, and +removing data is called *popping off the stack*. All data stored on the stack +must have a known, fixed size. Data with an unknown size at compile time or a +size that might change must be stored on the heap instead. > > The heap is less organized: when you put data on the heap, you request a -> certain amount of space. The memory allocator finds an empty spot in the heap -> that is big enough, marks it as being in use, and returns a *pointer*, which -> is the address of that location. This process is called *allocating on the -> heap* and is sometimes abbreviated as just *allocating* (pushing values onto -> the stack is not considered allocating). Because the pointer to the heap is a -> known, fixed size, you can store the pointer on the stack, but when you want -> the actual data, you must follow the pointer. Think of being seated at a -> restaurant. When you enter, you state the number of people in your group, and -> the staff finds an empty table that fits everyone and leads you there. If -> someone in your group comes late, they can ask where you’ve been seated to -> find you. +certain amount of space. The memory allocator finds an empty spot in the heap +that is big enough, marks it as being in use, and returns a *pointer*, which is +the address of that location. This process is called *allocating on the heap* +and is sometimes abbreviated as just *allocating* (pushing values onto the +stack is not considered allocating). Because the pointer to the heap is a +known, fixed size, you can store the pointer on the stack, but when you want +the actual data, you must follow the pointer. Think of being seated at a +restaurant. When you enter, you state the number of people in your group, and +the host finds an empty table that fits everyone and leads you there. If +someone in your group comes late, they can ask where you’ve been seated to find +you. > > Pushing to the stack is faster than allocating on the heap because the -> allocator never has to search for a place to store new data; that location is -> always at the top of the stack. Comparatively, allocating space on the heap -> requires more work, because the allocator must first find a big enough space -> to hold the data and then perform bookkeeping to prepare for the next -> allocation. - -<!--- Minor nit: not sure if worth clarifying but thought I'd mention - performance -for heap allocation I think isn't as much the time spent in the allocator but that -you have to spend time asking the system for memory. Custom allocators still have to -do the allocation step but try to avoid the system step where possible. -/JT ---> -<!-- I think this is a bit in the weeds, not making any change here /Carol --> - +allocator never has to search for a place to store new data; that location is +always at the top of the stack. Comparatively, allocating space on the heap +requires more work because the allocator must first find a big enough space to +hold the data and then perform bookkeeping to prepare for the next allocation. +> > Accessing data in the heap is slower than accessing data on the stack because -> you have to follow a pointer to get there. Contemporary processors are faster -> if they jump around less in memory. Continuing the analogy, consider a server -> at a restaurant taking orders from many tables. It’s most efficient to get -> all the orders at one table before moving on to the next table. Taking an -> order from table A, then an order from table B, then one from A again, and -> then one from B again would be a much slower process. By the same token, a -> processor can do its job better if it works on data that’s close to other -> data (as it is on the stack) rather than farther away (as it can be on the -> heap). - -<!--- I don't quite understand the last sentence. If you allocate enough to create -virtual memory, sure. But modern systems you're probably safe for most things? Also, -if we're contrasting against something like the heap, just having the ability to allocate -large space is probably a big benefit of the heap rather than a drawback. IMHO I'd probably -just drop the last sentence. -/JT ---> -<!-- Done! /Carol --> - +you have to follow a pointer to get there. Contemporary processors are faster +if they jump around less in memory. Continuing the analogy, consider a server +at a restaurant taking orders from many tables. It’s most efficient to get all +the orders at one table before moving on to the next table. Taking an order +from table A, then an order from table B, then one from A again, and then one +from B again would be a much slower process. By the same token, a processor can +do its job better if it works on data that’s close to other data (as it is on +the stack) rather than farther away (as it can be on the heap). > > When your code calls a function, the values passed into the function -> (including, potentially, pointers to data on the heap) and the function’s -> local variables get pushed onto the stack. When the function is over, those -> values get popped off the stack. - -<!--- Some calling conventions don't always use the stack for parameters. -For example, Windows x64 calling convention puts the first 4 arguments into -registers, and only puts args 5 and later on the stack. Ditto for the return -value. If it can fit in a register, x64 will use that instead of the stack: - -https://docs.microsoft.com/en-us/cpp/build/x64-calling-convention?view=msvc-170#parameter-passing -/JT ---> -<!-- I think this is a bit in the weeds, not making any change here /Carol --> - +(including, potentially, pointers to data on the heap) and the function’s local +variables get pushed onto the stack. When the function is over, those values +get popped off the stack. > > Keeping track of what parts of code are using what data on the heap, -> minimizing the amount of duplicate data on the heap, and cleaning up unused -> data on the heap so you don’t run out of space are all problems that ownership -> addresses. Once you understand ownership, you won’t need to think about the -> stack and the heap very often, but knowing that the main purpose of ownership -> is to manage heap data can help explain why it works the way it does. +minimizing the amount of duplicate data on the heap, and cleaning up unused +data on the heap so you don’t run out of space are all problems that ownership +addresses. Once you understand ownership, you won’t need to think about the +stack and the heap very often, but knowing that the main purpose of ownership +is to manage heap data can help explain why it works the way it does. ### Ownership Rules @@ -140,14 +105,6 @@ work through the examples that illustrate them: * There can only be one owner at a time. * When the owner goes out of scope, the value will be dropped. -<!--- Maybe splitting hairs, but for the first bullet I'd say: -"Each value in Rust has an *owner*". - -If we say variables here, and then find out later that, for example, structs can -also be owners, this gets a bit mirky. -/JT ---> -<!-- Took this suggestion! /Carol --> - ### Variable Scope Now that we’re past basic Rust syntax, we won’t include all the `fn main() {` @@ -170,8 +127,8 @@ which it’s declared until the end of the current *scope*. Listing 4-1 shows a program with comments annotating where the variable `s` would be valid. ``` -{ // s is not valid here, it’s not yet declared - let s = "hello"; // s is valid from this point forward. +{ // s is not valid here, since it's not yet declared + let s = "hello"; // s is valid from this point forward // do stuff with s } // this scope is now over, and s is no longer valid @@ -181,23 +138,23 @@ Listing 4-1: A variable and the scope in which it is valid In other words, there are two important points in time here: -* When `s` comes *into scope*, it is valid. -* It remains valid until it goes *out of scope*. +* When `s` comes *into* scope, it is valid. +* It remains valid until it goes *out of* scope. At this point, the relationship between scopes and when variables are valid is similar to that in other programming languages. Now we’ll build on top of this understanding by introducing the `String` type. -### The `String` Type +### The String Type To illustrate the rules of ownership, we need a data type that is more complex -than those we covered in the “Data Types†section of Chapter 3. The types -covered previously are all a known size, can be stored on the stack and popped -off the stack when their scope is over, and can be quickly and trivially copied -to make a new, independent instance if another part of code needs to use the -same value in a different scope. But we want to look at data that is stored on -the heap and explore how Rust knows when to clean up that data, and the -`String` type is a great example. +than those we covered in “Data Types†on page XX. The types covered previously +are of a known size, can be stored on the stack and popped off the stack when +their scope is over, and can be quickly and trivially copied to make a new, +independent instance if another part of code needs to use the same value in a +different scope. But we want to look at data that is stored on the heap and +explore how Rust knows when to clean up that data, and the `String` type is a +great example. We’ll concentrate on the parts of `String` that relate to ownership. These aspects also apply to other complex data types, whether they are provided by @@ -220,9 +177,9 @@ let s = String::from("hello"); The double colon `::` operator allows us to namespace this particular `from` function under the `String` type rather than using some sort of name like -`string_from`. We’ll discuss this syntax more in the “Method Syntax†section of -Chapter 5 and when we talk about namespacing with modules in “Paths for -Referring to an Item in the Module Tree†in Chapter 7. +`string_from`. We’ll discuss this syntax more in “Method Syntax†on page XX, +and when we talk about namespacing with modules in “Paths for Referring to an +Item in the Module Tree†on page XX. This kind of string *can* be mutated: @@ -231,11 +188,11 @@ let mut s = String::from("hello"); s.push_str(", world!"); // push_str() appends a literal to a String -println!("{}", s); // This will print `hello, world!` +println!("{s}"); // This will print `hello, world!` ``` So, what’s the difference here? Why can `String` be mutated but literals -cannot? The difference is how these two types deal with memory. +cannot? The difference is in how these two types deal with memory. ### Memory and Allocation @@ -251,8 +208,8 @@ we need to allocate an amount of memory on the heap, unknown at compile time, to hold the contents. This means: * The memory must be requested from the memory allocator at runtime. -* We need a way of returning this memory to the allocator when we’re - done with our `String`. +* We need a way of returning this memory to the allocator when we’re done with +our `String`. That first part is done by us: when we call `String::from`, its implementation requests the memory it needs. This is pretty much universal in programming @@ -261,19 +218,13 @@ languages. However, the second part is different. In languages with a *garbage collector (GC)*, the GC keeps track of and cleans up memory that isn’t being used anymore, and we don’t need to think about it. In most languages without a GC, -it’s our responsibility to identify when memory is no longer being used and +it’s our responsibility to identify when memory is no longer being used and to call code to explicitly free it, just as we did to request it. Doing this correctly has historically been a difficult programming problem. If we forget, we’ll waste memory. If we do it too early, we’ll have an invalid variable. If we do it twice, that’s a bug too. We need to pair exactly one `allocate` with exactly one `free`. -<!--- The phrase "explicitly return it" gives a connotation in programming of -returning a value to a caller rather than the more casual returning it to the OS. -Maybe we can say "explicitly delete it" or "explicitly free it". -/JT ---> -<!-- Changed "return" to "free" /Carol --> - Rust takes a different path: the memory is automatically returned once the variable that owns it goes out of scope. Here’s a version of our scope example from Listing 4-1 using a `String` instead of a string literal: @@ -294,23 +245,23 @@ and it’s where the author of `String` can put the code to return the memory. Rust calls `drop` automatically at the closing curly bracket. > Note: In C++, this pattern of deallocating resources at the end of an item’s -> lifetime is sometimes called *Resource Acquisition Is Initialization (RAII)*. -> The `drop` function in Rust will be familiar to you if you’ve used RAII -> patterns. +lifetime is sometimes called *Resource Acquisition Is Initialization* *(RAII)*. +The `drop` function in Rust will be familiar to you if you’ve used RAII +patterns. This pattern has a profound impact on the way Rust code is written. It may seem simple right now, but the behavior of code can be unexpected in more complicated situations when we want to have multiple variables use the data we’ve allocated on the heap. Let’s explore some of those situations now. -#### Ways Variables and Data Interact: Move +#### Variables and Data Interacting with Move Multiple variables can interact with the same data in different ways in Rust. Let’s look at an example using an integer in Listing 4-2. ``` - let x = 5; - let y = x; +let x = 5; +let y = x; ``` Listing 4-2: Assigning the integer value of variable `x` to `y` @@ -324,8 +275,8 @@ onto the stack. Now let’s look at the `String` version: ``` - let s1 = String::from("hello"); - let s2 = s1; +let s1 = String::from("hello"); +let s2 = s1; ``` This looks very similar, so we might assume that the way it works would be the @@ -338,38 +289,20 @@ the memory that holds the contents of the string, a length, and a capacity. This group of data is stored on the stack. On the right is the memory on the heap that holds the contents. -<img alt="String in memory" src="img/trpl04-01.svg" class="center" style="width: 50%;" /> - -<!--- This might be me being a bit nitpicky - when you show what the string looks like -in memory, we're showing indices for data pointed to by ptr. I have a bit of a knee-jerk -reaction here since we don't think of strings has having indices in Rust (because of UTF-8) -Not sure if it's well enough alone, or if it might be better for the ptr to point at -at cells of memory without giving them indices. - -Something like: - -[ptr | --] -> [h][e][l][l][o] -[len | 5] -[capacity | 5] -/JT ---> -<!-- I think this is a bit in the weeds, not making any change here /Carol --> - -Figure 4-1: Representation in memory of a `String` holding the value `"hello"` +Figure 4-1: Representation in memory of a `String` holding the value `"hello"` bound to `s1` -The length is how much memory, in bytes, the contents of the `String` is +The length is how much memory, in bytes, the contents of the `String` are currently using. The capacity is the total amount of memory, in bytes, that the -`String` has received from the allocator. The difference between length -and capacity matters, but not in this context, so for now, it’s fine to ignore -the capacity. +`String` has received from the allocator. The difference between length and +capacity matters, but not in this context, so for now, it’s fine to ignore the +capacity. When we assign `s1` to `s2`, the `String` data is copied, meaning we copy the pointer, the length, and the capacity that are on the stack. We do not copy the data on the heap that the pointer refers to. In other words, the data representation in memory looks like Figure 4-2. -<img alt="s1 and s2 pointing to the same value" src="img/trpl04-02.svg" class="center" style="width: 50%;" /> - Figure 4-2: Representation in memory of the variable `s2` that has a copy of the pointer, length, and capacity of `s1` @@ -378,8 +311,6 @@ look like if Rust instead copied the heap data as well. If Rust did this, the operation `s2 = s1` could be very expensive in terms of runtime performance if the data on the heap were large. -<img alt="s1 and s2 to two places" src="img/trpl04-03.svg" class="center" style="width: 50%;" /> - Figure 4-3: Another possibility for what `s2 = s1` might do if Rust copied the heap data as well @@ -391,7 +322,7 @@ same memory. This is known as a *double free* error and is one of the memory safety bugs we mentioned previously. Freeing memory twice can lead to memory corruption, which can potentially lead to security vulnerabilities. -To ensure memory safety, after the line `let s2 = s1`, Rust considers `s1` as +To ensure memory safety, after the line `let s2 = s1;`, Rust considers `s1` as no longer valid. Therefore, Rust doesn’t need to free anything when `s1` goes out of scope. Check out what happens when you try to use `s1` after `s2` is created; it won’t work: @@ -400,7 +331,7 @@ created; it won’t work: let s1 = String::from("hello"); let s2 = s1; -println!("{}, world!", s1); +println!("{s1}, world!"); ``` You’ll get an error like this because Rust prevents you from using the @@ -411,33 +342,32 @@ error[E0382]: borrow of moved value: `s1` --> src/main.rs:5:28 | 2 | let s1 = String::from("hello"); - | -- move occurs because `s1` has type `String`, which does not implement the `Copy` trait + | -- move occurs because `s1` has type `String`, which + does not implement the `Copy` trait 3 | let s2 = s1; | -- value moved here 4 | -5 | println!("{}, world!", s1); - | ^^ value borrowed here after move +5 | println!("{s1}, world!"); + | ^^ value borrowed here after move ``` If you’ve heard the terms *shallow copy* and *deep copy* while working with other languages, the concept of copying the pointer, length, and capacity without copying the data probably sounds like making a shallow copy. But -because Rust also invalidates the first variable, instead of calling it a -shallow copy, it’s known as a *move*. In this example, we would say that -`s1` was *moved* into `s2`. So what actually happens is shown in Figure 4-4. - -<img alt="s1 moved to s2" src="img/trpl04-04.svg" class="center" style="width: 50%;" /> +because Rust also invalidates the first variable, instead of being called a +shallow copy, it’s known as a *move*. In this example, we would say that `s1` +was *moved* into `s2`. So, what actually happens is shown in Figure 4-4. Figure 4-4: Representation in memory after `s1` has been invalidated -That solves our problem! With only `s2` valid, when it goes out of scope, it +That solves our problem! With only `s2` valid, when it goes out of scope it alone will free the memory, and we’re done. In addition, there’s a design choice that’s implied by this: Rust will never automatically create “deep†copies of your data. Therefore, any *automatic* copying can be assumed to be inexpensive in terms of runtime performance. -#### Ways Variables and Data Interact: Clone +#### Variables and Data Interacting with Clone If we *do* want to deeply copy the heap data of the `String`, not just the stack data, we can use a common method called `clone`. We’ll discuss method @@ -450,7 +380,7 @@ Here’s an example of the `clone` method in action: let s1 = String::from("hello"); let s2 = s1.clone(); -println!("s1 = {}, s2 = {}", s1, s2); +println!("s1 = {s1}, s2 = {s2}"); ``` This works just fine and explicitly produces the behavior shown in Figure 4-3, @@ -462,14 +392,14 @@ different is going on. #### Stack-Only Data: Copy -There’s another wrinkle we haven’t talked about yet. This code using integers – -part of which was shown in Listing 4-2 – works and is valid: +There’s another wrinkle we haven’t talked about yet. This code using +integers—part of which was shown in Listing 4-2—works and is valid: ``` let x = 5; let y = x; -println!("x = {}, y = {}", x, y); +println!("x = {x}, y = {y}"); ``` But this code seems to contradict what we just learned: we don’t have a call to @@ -480,7 +410,7 @@ time are stored entirely on the stack, so copies of the actual values are quick to make. That means there’s no reason we would want to prevent `x` from being valid after we create the variable `y`. In other words, there’s no difference between deep and shallow copying here, so calling `clone` wouldn’t do anything -different from the usual shallow copying and we can leave it out. +different from the usual shallow copying, and we can leave it out. Rust has a special annotation called the `Copy` trait that we can place on types that are stored on the stack, as integers are (we’ll talk more about @@ -488,29 +418,13 @@ traits in Chapter 10). If a type implements the `Copy` trait, variables that use it do not move, but rather are trivially copied, making them still valid after assignment to another variable. -<!--- an older variable that uses that type, we mean? /LC ---> -<!-- I removed "older" here, I don't think that was quite right-- this sentence -is trying to describe the line `let y = x` where the variable `x` is assigned -to `y`. The variables must be the same type because they're getting the same -value, so "that uses that type" isn't relevant. Let me know if there's any -aspects that are still confusing here. /Carol --> -<!-- JT, is this all clear in the text? /LC --> -<!--- I think this is fine. When I teach it, I tend to stress *move* and *copy* -so that they can build up that framework. So my slight tweak to the above might -be: - -"If a type implements the `Copy` trait, variables that use it do not move but rather are -trivially copied, making them still valid after assignment to another variable." -/JT ---> -<!-- Took this suggestion! /Carol --> - Rust won’t let us annotate a type with `Copy` if the type, or any of its parts, has implemented the `Drop` trait. If the type needs something special to happen when the value goes out of scope and we add the `Copy` annotation to that type, we’ll get a compile-time error. To learn about how to add the `Copy` annotation -to your type to implement the trait, see “Derivable Traits†in Appendix C. +to your type to implement the trait, see “Derivable Traits†on page XX. -So what types implement the `Copy` trait? You can check the documentation for +So, what types implement the `Copy` trait? You can check the documentation for the given type to be sure, but as a general rule, any group of simple scalar values can implement `Copy`, and nothing that requires allocation or is some form of resource can implement `Copy`. Here are some of the types that @@ -518,10 +432,10 @@ implement `Copy`: * All the integer types, such as `u32`. * The Boolean type, `bool`, with values `true` and `false`. -* All the floating point types, such as `f64`. +* All the floating-point types, such as `f64`. * The character type, `char`. * Tuples, if they only contain types that also implement `Copy`. For example, - `(i32, i32)` implements `Copy`, but `(i32, String)` does not. +`(i32, i32)` implements `Copy`, but `(i32, String)` does not. ### Ownership and Functions @@ -530,9 +444,8 @@ assigning a value to a variable. Passing a variable to a function will move or copy, just as assignment does. Listing 4-3 has an example with some annotations showing where variables go into and out of scope. -Filename: src/main.rs - ``` +// src/main.rs fn main() { let s = String::from("hello"); // s comes into scope @@ -545,17 +458,17 @@ fn main() { // but i32 is Copy, so it's okay to still // use x afterward -} // Here, x goes out of scope, then s. But because s's value was moved, nothing - // special happens. +} // Here, x goes out of scope, then s. However, because s's value was moved, + // nothing special happens fn takes_ownership(some_string: String) { // some_string comes into scope - println!("{}", some_string); + println!("{some_string}"); } // Here, some_string goes out of scope and `drop` is called. The backing - // memory is freed. + // memory is freed fn makes_copy(some_integer: i32) { // some_integer comes into scope - println!("{}", some_integer); -} // Here, some_integer goes out of scope. Nothing special happens. + println!("{some_integer}"); +} // Here, some_integer goes out of scope. Nothing special happens ``` Listing 4-3: Functions with ownership and scope annotated @@ -567,13 +480,12 @@ the ownership rules prevent you from doing so. ### Return Values and Scope -Returning values can also transfer ownership. Listing 4-4 shows an example -of a function that returns some value, with similar annotations as those in -Listing 4-3. - -Filename: src/main.rs +Returning values can also transfer ownership. Listing 4-4 shows an example of a +function that returns some value, with similar annotations as those in Listing +4-3. ``` +// src/main.rs fn main() { let s1 = gives_ownership(); // gives_ownership moves its return // value into s1 @@ -584,7 +496,7 @@ fn main() { // takes_and_gives_back, which also // moves its return value into s3 } // Here, s3 goes out of scope and is dropped. s2 was moved, so nothing - // happens. s1 goes out of scope and is dropped. + // happens. s1 goes out of scope and is dropped fn gives_ownership() -> String { // gives_ownership will move its // return value into the function @@ -597,7 +509,7 @@ fn gives_ownership() -> String { // gives_ownership will move its // function } -// This function takes a String and returns one +// This function takes a String and returns a String fn takes_and_gives_back(a_string: String) -> String { // a_string comes into // scope @@ -628,7 +540,7 @@ fn main() { let (s2, len) = calculate_length(s1); - println!("The length of '{}' is {}.", s2, len); + println!("The length of '{s2}' is {len}."); } fn calculate_length(s: String) -> (String, usize) { @@ -655,12 +567,6 @@ the data stored at that address; that data is owned by some other variable. Unlike a pointer, a reference is guaranteed to point to a valid value of a particular type for the life of that reference. -<!--- Possible wording tweak: "a reference is guaranteed to point to a valid value of a -particular type for the life of that reference" or "a reference is always guaranteed -to point to a valid value of a particular type" -/JT ---> -<!-- Took this suggestion! /Carol --> - Here is how you would define and use a `calculate_length` function that has a reference to an object as a parameter instead of taking ownership of the value: @@ -672,7 +578,7 @@ fn main() { let len = calculate_length(&s1); - println!("The length of '{}' is {}.", s1, len); + println!("The length of '{s1}' is {len}."); } fn calculate_length(s: &String) -> usize { @@ -686,14 +592,12 @@ function return value is gone. Second, note that we pass `&s1` into `String`. These ampersands represent *references*, and they allow you to refer to some value without taking ownership of it. Figure 4-5 depicts this concept. -<img alt="&String s pointing at String s1" src="img/trpl04-05.svg" class="center" /> - Figure 4-5: A diagram of `&String s` pointing at `String s1` > Note: The opposite of referencing by using `&` is *dereferencing*, which is -> accomplished with the dereference operator, `*`. We’ll see some uses of the -> dereference operator in Chapter 8 and discuss details of dereferencing in -> Chapter 15. +accomplished with the dereference operator, `*`. We’ll see some uses of the +dereference operator in Chapter 8 and discuss details of dereferencing in +Chapter 15. Let’s take a closer look at the function call here: @@ -714,12 +618,12 @@ the parameter `s` is a reference. Let’s add some explanatory annotations: fn calculate_length(s: &String) -> usize { // s is a reference to a String s.len() } // Here, s goes out of scope. But because it does not have ownership of what - // it refers to, it is not dropped. + // it refers to, the String is not dropped ``` The scope in which the variable `s` is valid is the same as any function parameter’s scope, but the value pointed to by the reference is not dropped -when `s` stops being used because `s` doesn’t have ownership. When functions +when `s` stops being used, because `s` doesn’t have ownership. When functions have references as parameters instead of the actual values, we won’t need to return the values in order to give back ownership, because we never had ownership. @@ -728,7 +632,7 @@ We call the action of creating a reference *borrowing*. As in real life, if a person owns something, you can borrow it from them. When you’re done, you have to give it back. You don’t own it. -So what happens if we try to modify something we’re borrowing? Try the code in +So, what happens if we try to modify something we’re borrowing? Try the code in Listing 4-6. Spoiler alert: it doesn’t work! Filename: src/main.rs @@ -750,13 +654,16 @@ Listing 4-6: Attempting to modify a borrowed value Here’s the error: ``` -error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` reference +error[E0596]: cannot borrow `*some_string` as mutable, as it is behind a `&` +reference --> src/main.rs:8:5 | 7 | fn change(some_string: &String) { - | ------- help: consider changing this to be a mutable reference: `&mut String` + | ------- help: consider changing this to be a mutable +reference: `&mut String` 8 | some_string.push_str(", world"); - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `some_string` is a `&` reference, so the data it refers to cannot be borrowed as mutable + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `some_string` is a `&` reference, so +the data it refers to cannot be borrowed as mutable ``` Just as variables are immutable by default, so are references. We’re not @@ -781,7 +688,7 @@ fn change(some_string: &mut String) { } ``` -First, we change `s` to be `mut`. Then we create a mutable reference with `&mut +First we change `s` to be `mut`. Then we create a mutable reference with `&mut s` where we call the `change` function, and update the function signature to accept a mutable reference with `some_string: &mut String`. This makes it very clear that the `change` function will mutate the value it borrows. @@ -790,22 +697,15 @@ Mutable references have one big restriction: if you have a mutable reference to a value, you can have no other references to that value. This code that attempts to create two mutable references to `s` will fail: -<!--- Clarification: "Mutable references have one big restriction: if you have a -mutable reference to a value, you can have no other references to that value." -This covers both not having two mutable references and having a mutable references -and an immutable reference to the same value. -/JT ---> -<!-- Took this suggestion! /Carol --> - Filename: src/main.rs ``` - let mut s = String::from("hello"); +let mut s = String::from("hello"); - let r1 = &mut s; - let r2 = &mut s; +let r1 = &mut s; +let r2 = &mut s; - println!("{}, {}", r1, r2); +println!("{r1}, {r2}"); ``` Here’s the error: @@ -819,8 +719,8 @@ error[E0499]: cannot borrow `s` as mutable more than once at a time 5 | let r2 = &mut s; | ^^^^^^ second mutable borrow occurs here 6 | -7 | println!("{}, {}", r1, r2); - | -- first borrow later used here +7 | println!("{r1}, {r2}"); + | -- first borrow later used here ``` This error says that this code is invalid because we cannot borrow `s` as @@ -831,7 +731,7 @@ in `r2` that borrows the same data as `r1`. The restriction preventing multiple mutable references to the same data at the same time allows for mutation but in a very controlled fashion. It’s something -that new Rustaceans struggle with, because most languages let you mutate +that new Rustaceans struggle with because most languages let you mutate whenever you’d like. The benefit of having this restriction is that Rust can prevent data races at compile time. A *data race* is similar to a race condition and happens when these three behaviors occur: @@ -841,8 +741,8 @@ condition and happens when these three behaviors occur: * There’s no mechanism being used to synchronize access to the data. Data races cause undefined behavior and can be difficult to diagnose and fix -when you’re trying to track them down at runtime; Rust prevents this problem -by refusing to compile code with data races! +when you’re trying to track them down at runtime; Rust prevents this problem by +refusing to compile code with data races! As always, we can use curly brackets to create a new scope, allowing for multiple mutable references, just not *simultaneous* ones: @@ -852,7 +752,7 @@ let mut s = String::from("hello"); { let r1 = &mut s; -} // r1 goes out of scope here, so we can make a new reference with no problems. +} // r1 goes out of scope here, so we can make a new reference with no problems let r2 = &mut s; ``` @@ -867,13 +767,14 @@ let r1 = &s; // no problem let r2 = &s; // no problem let r3 = &mut s; // BIG PROBLEM -println!("{}, {}, and {}", r1, r2, r3); +println!("{r1}, {r2}, and {r3}"); ``` Here’s the error: ``` -error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immutable +error[E0502]: cannot borrow `s` as mutable because it is also borrowed as +immutable --> src/main.rs:6:14 | 4 | let r1 = &s; // no problem @@ -882,8 +783,8 @@ error[E0502]: cannot borrow `s` as mutable because it is also borrowed as immuta 6 | let r3 = &mut s; // BIG PROBLEM | ^^^^^^ mutable borrow occurs here 7 | -8 | println!("{}, {}, and {}", r1, r2, r3); - | -- immutable borrow later used here +8 | println!("{r1}, {r2}, and {r3}"); + | -- immutable borrow later used here ``` Whew! We *also* cannot have a mutable reference while we have an immutable one @@ -904,20 +805,18 @@ let mut s = String::from("hello"); let r1 = &s; // no problem let r2 = &s; // no problem -println!("{} and {}", r1, r2); +println!("{r1} and {r2}"); // variables r1 and r2 will not be used after this point let r3 = &mut s; // no problem -println!("{}", r3); +println!("{r3}"); ``` The scopes of the immutable references `r1` and `r2` end after the `println!` where they are last used, which is before the mutable reference `r3` is -created. These scopes don’t overlap, so this code is allowed. The ability of -the compiler to tell that a reference is no longer being used at a point before -the end of the scope is called *Non-Lexical Lifetimes* (NLL for short), and you -can read more about it in The Edition Guide at -*https://doc.rust-lang.org/edition-guide/rust-2018/ownership-and-lifetimes/non-lexical-lifetimes.html*. +created. These scopes don’t overlap, so this code is allowed: the compiler can +tell that the reference is no longer being used at a point before the end of +the scope. Even though borrowing errors may be frustrating at times, remember that it’s the Rust compiler pointing out a potential bug early (at compile time rather @@ -927,9 +826,9 @@ have to track down why your data isn’t what you thought it was. ### Dangling References In languages with pointers, it’s easy to erroneously create a *dangling -pointer*--a pointer that references a location in memory that may have been -given to someone else--by freeing some memory while preserving a pointer to -that memory. In Rust, by contrast, the compiler guarantees that references will +pointer*—a pointer that references a location in memory that may have been +given to someone else—by freeing some memory while preserving a pointer to that +memory. In Rust, by contrast, the compiler guarantees that references will never be dangling references: if you have a reference to some data, the compiler will ensure that the data will not go out of scope before the reference to the data does. @@ -960,7 +859,8 @@ error[E0106]: missing lifetime specifier 5 | fn dangle() -> &String { | ^ expected named lifetime parameter | - = help: this function's return type contains a borrowed value, but there is no value for it to be borrowed from + = help: this function's return type contains a borrowed value, +but there is no value for it to be borrowed from help: consider using the `'static` lifetime | 5 | fn dangle() -> &'static String { @@ -972,22 +872,21 @@ discuss lifetimes in detail in Chapter 10. But, if you disregard the parts about lifetimes, the message does contain the key to why this code is a problem: ``` -this function's return type contains a borrowed value, but there is no value -for it to be borrowed from +this function's return type contains a borrowed value, but there +is no value for it to be borrowed from ``` Let’s take a closer look at exactly what’s happening at each stage of our `dangle` code: -Filename: src/main.rs - ``` +// src/main.rs fn dangle() -> &String { // dangle returns a reference to a String let s = String::from("hello"); // s is a new String &s // we return a reference to the String, s -} // Here, s goes out of scope, and is dropped. Its memory goes away. +} // Here, s goes out of scope and is dropped, so its memory goes away // Danger! ``` @@ -1014,7 +913,7 @@ deallocated. Let’s recap what we’ve discussed about references: * At any given time, you can have *either* one mutable reference *or* any - number of immutable references. +number of immutable references. * References must always be valid. Next, we’ll look at a different kind of reference: slices. @@ -1030,12 +929,6 @@ words separated by spaces and returns the first word it finds in that string. If the function doesn’t find a space in the string, the whole string must be one word, so the entire string should be returned. -<!--- Do we want to clarify this is for words separated by spaces? -Not all languages use spaces to separate words: -https://www.w3.org/International/articles/typography/linebreak.en#whatisword -/JT ---> -<!-- Took this suggestion! /Carol --> - Let’s work through how we’d write the signature of this function without using slices, to understand the problem that slices will solve: @@ -1052,15 +945,15 @@ Filename: src/main.rs ``` fn first_word(s: &String) -> usize { - [1] let bytes = s.as_bytes(); + 1 let bytes = s.as_bytes(); - for (i, &item)[2] in bytes.iter()[3].enumerate() { - [4] if item == b' ' { + for (2 i, &item) in 3 bytes.iter().enumerate() { + 4 if item == b' ' { return i; } } - [5] s.len() + 5 s.len() } ``` @@ -1071,13 +964,13 @@ Because we need to go through the `String` element by element and check whether a value is a space, we’ll convert our `String` to an array of bytes using the `as_bytes` method [1]. -Next, we create an iterator over the array of bytes using the `iter` method [3]. -We’ll discuss iterators in more detail in Chapter 13. For now, know that `iter` -is a method that returns each element in a collection and that `enumerate` -wraps the result of `iter` and returns each element as part of a tuple instead. -The first element of the tuple returned from `enumerate` is the index, and the -second element is a reference to the element. This is a bit more convenient -than calculating the index ourselves. +Next, we create an iterator over the array of bytes using the `iter` method +[3]. We’ll discuss iterators in more detail in Chapter 13. For now, know that +`iter` is a method that returns each element in a collection and that +`enumerate` wraps the result of `iter` and returns each element as part of a +tuple instead. The first element of the tuple returned from `enumerate` is the +index, and the second element is a reference to the element. This is a bit more +convenient than calculating the index ourselves. Because the `enumerate` method returns a tuple, we can use patterns to destructure that tuple. We’ll be discussing patterns more in Chapter 6. In the @@ -1096,9 +989,8 @@ because it’s a separate value from the `String`, there’s no guarantee that i will still be valid in the future. Consider the program in Listing 4-8 that uses the `first_word` function from Listing 4-7. -Filename: src/main.rs - ``` +// src/main.rs fn main() { let mut s = String::from("hello world"); @@ -1130,8 +1022,8 @@ fn second_word(s: &String) -> (usize, usize) { Now we’re tracking a starting *and* an ending index, and we have even more values that were calculated from data in a particular state but aren’t tied to -that state at all. We have three unrelated variables floating around that -need to be kept in sync. +that state at all. We have three unrelated variables floating around that need +to be kept in sync. Luckily, Rust has a solution to this problem: string slices. @@ -1140,10 +1032,10 @@ Luckily, Rust has a solution to this problem: string slices. A *string slice* is a reference to part of a `String`, and it looks like this: ``` - let s = String::from("hello world"); +let s = String::from("hello world"); - let hello = &s[0..5]; - let world = &s[6..11]; +let hello = &s[0..5]; +let world = &s[6..11]; ``` Rather than a reference to the entire `String`, `hello` is a reference to a @@ -1152,17 +1044,15 @@ using a range within brackets by specifying `[starting_index..ending_index]`, where `starting_index` is the first position in the slice and `ending_index` is one more than the last position in the slice. Internally, the slice data structure stores the starting position and the length of the slice, which -corresponds to `ending_index` minus `starting_index`. So in the case of `let +corresponds to `ending_index` minus `starting_index`. So, in the case of `let world = &s[6..11];`, `world` would be a slice that contains a pointer to the -byte at index 6 of `s` with a length value of 5. +byte at index 6 of `s` with a length value of `5`. Figure 4-6 shows this in a diagram. -<img alt="world containing a pointer to the byte at index 6 of String s and a length 5" src="img/trpl04-06.svg" class="center" style="width: 50%;" /> - Figure 4-6: String slice referring to part of a `String` -With Rust’s `..` range syntax, if you want to start at index zero, you can drop +With Rust’s `..` range syntax, if you want to start at index 0, you can drop the value before the two periods. In other words, these are equal: ``` @@ -1197,11 +1087,11 @@ let slice = &s[..]; ``` > Note: String slice range indices must occur at valid UTF-8 character -> boundaries. If you attempt to create a string slice in the middle of a -> multibyte character, your program will exit with an error. For the purposes -> of introducing string slices, we are assuming ASCII only in this section; a -> more thorough discussion of UTF-8 handling is in the “Storing UTF-8 Encoded -> Text with Strings†section of Chapter 8. +boundaries. If you attempt to create a string slice in the middle of a +multibyte character, your program will exit with an error. For the purposes of +introducing string slices, we are assuming ASCII only in this section; a more +thorough discussion of UTF-8 handling is in “Storing UTF-8 Encoded Text with +Strings†on page XX. With all this information in mind, let’s rewrite `first_word` to return a slice. The type that signifies “string slice†is written as `&str`: @@ -1222,10 +1112,10 @@ fn first_word(s: &String) -> &str { } ``` -We get the index for the end of the word in the same way as we did in Listing -4-7, by looking for the first occurrence of a space. When we find a space, we -return a string slice using the start of the string and the index of the space -as the starting and ending indices. +We get the index for the end of the word the same way we did in Listing 4-7, by +looking for the first occurrence of a space. When we find a space, we return a +string slice using the start of the string and the index of the space as the +starting and ending indices. Now when we call `first_word`, we get back a single value that is tied to the underlying data. The value is made up of a reference to the starting point of @@ -1237,7 +1127,7 @@ Returning a slice would also work for a `second_word` function: fn second_word(s: &String) -> &str { ``` -We now have a straightforward API that’s much harder to mess up, because the +We now have a straightforward API that’s much harder to mess up because the compiler will ensure the references into the `String` remain valid. Remember the bug in the program in Listing 4-8, when we got the index to the end of the first word but then cleared the string so our index was invalid? That code was @@ -1257,7 +1147,7 @@ fn main() { s.clear(); // error! - println!("the first word is: {}", word); + println!("the first word is: {word}"); } ``` @@ -1274,8 +1164,8 @@ immutable 18 | s.clear(); // error! | ^^^^^^^^^ mutable borrow occurs here 19 | -20 | println!("the first word is: {}", word); - | ---- immutable borrow later used here +20 | println!("the first word is: {word}"); + | ---- immutable borrow later used here ``` Recall from the borrowing rules that if we have an immutable reference to @@ -1287,7 +1177,7 @@ reference in `clear` and the immutable reference in `word` from existing at the same time, and compilation fails. Not only has Rust made our API easier to use, but it has also eliminated an entire class of errors at compile time! -#### String Literals Are Slices +#### String Literals as Slices Recall that we talked about string literals being stored inside the binary. Now that we know about slices, we can properly understand string literals: @@ -1323,9 +1213,10 @@ the type of the `s` parameter If we have a string slice, we can pass that directly. If we have a `String`, we can pass a slice of the `String` or a reference to the `String`. This flexibility takes advantage of *deref coercions*, a feature we will cover in -the “Implicit Deref Coercions with Functions and Methods†section of Chapter -15. Defining a function to take a string slice instead of a reference to a -`String` makes our API more general and useful without losing any functionality: +“Implicit Deref Coercions with Functions and Methods†on page XX. + +Defining a function to take a string slice instead of a reference to a `String` +makes our API more general and useful without losing any functionality: Filename: src/main.rs @@ -1333,16 +1224,18 @@ Filename: src/main.rs fn main() { let my_string = String::from("hello world"); - // `first_word` works on slices of `String`s, whether partial or whole + // `first_word` works on slices of `String`s, whether partial + // or whole let word = first_word(&my_string[0..6]); let word = first_word(&my_string[..]); - // `first_word` also works on references to `String`s, which are equivalent - // to whole slices of `String`s + // `first_word` also works on references to `String`s, which + // are equivalent to whole slices of `String`s let word = first_word(&my_string); let my_string_literal = "hello world"; - // `first_word` works on slices of string literals, whether partial or whole + // `first_word` works on slices of string literals, + // whether partial or whole let word = first_word(&my_string_literal[0..6]); let word = first_word(&my_string_literal[..]); @@ -1355,14 +1248,14 @@ fn main() { ### Other Slices String slices, as you might imagine, are specific to strings. But there’s a -more general slice type, too. Consider this array: +more general slice type too. Consider this array: ``` let a = [1, 2, 3, 4, 5]; ``` -Just as we might want to refer to a part of a string, we might want to refer -to part of an array. We’d do so like this: +Just as we might want to refer to part of a string, we might want to refer to +part of an array. We’d do so like this: ``` let a = [1, 2, 3, 4, 5]; @@ -1388,3 +1281,4 @@ means you don’t have to write and debug extra code to get this control. Ownership affects how lots of other parts of Rust work, so we’ll talk about these concepts further throughout the rest of the book. Let’s move on to Chapter 5 and look at grouping pieces of data together in a `struct`. + diff --git a/src/doc/book/nostarch/chapter05.md b/src/doc/book/nostarch/chapter05.md index 356ba82af..9881a3b74 100644 --- a/src/doc/book/nostarch/chapter05.md +++ b/src/doc/book/nostarch/chapter05.md @@ -19,16 +19,16 @@ We’ll demonstrate how to define and instantiate structs. We’ll discuss how t define associated functions, especially the kind of associated functions called *methods*, to specify behavior associated with a struct type. Structs and enums (discussed in Chapter 6) are the building blocks for creating new types in your -program’s domain to take full advantage of Rust’s compile time type checking. +program’s domain to take full advantage of Rust’s compile-time type checking. ## Defining and Instantiating Structs -Structs are similar to tuples, discussed in “The Tuple Type†section, in that -both hold multiple related values. Like tuples, the pieces of a struct can be -different types. Unlike with tuples, in a struct you’ll name each piece of data -so it’s clear what the values mean. Adding these names means that structs are -more flexible than tuples: you don’t have to rely on the order of the data to -specify or access the values of an instance. +Structs are similar to tuples, discussed in “The Tuple Type†on page XX, in +that both hold multiple related values. Like tuples, the pieces of a struct can +be different types. Unlike with tuples, in a struct you’ll name each piece of +data so it’s clear what the values mean. Adding these names means that structs +are more flexible than tuples: you don’t have to rely on the order of the data +to specify or access the values of an instance. To define a struct, we enter the keyword `struct` and name the entire struct. A struct’s name should describe the significance of the pieces of data being @@ -36,6 +36,8 @@ grouped together. Then, inside curly brackets, we define the names and types of the pieces of data, which we call *fields*. For example, Listing 5-1 shows a struct that stores information about a user account. +Filename: src/main.rs + ``` struct User { active: bool, @@ -49,20 +51,22 @@ Listing 5-1: A `User` struct definition To use a struct after we’ve defined it, we create an *instance* of that struct by specifying concrete values for each of the fields. We create an instance by -stating the name of the struct and then add curly brackets containing `key: -value` pairs, where the keys are the names of the fields and the values are the +stating the name of the struct and then add curly brackets containing key: +value pairs, where the keys are the names of the fields and the values are the data we want to store in those fields. We don’t have to specify the fields in the same order in which we declared them in the struct. In other words, the struct definition is like a general template for the type, and instances fill in that template with particular data to create values of the type. For example, we can declare a particular user as shown in Listing 5-2. +Filename: src/main.rs + ``` fn main() { let user1 = User { - email: String::from("someone@example.com"), - username: String::from("someusername123"), active: true, + username: String::from("someusername123"), + email: String::from("someone@example.com"), sign_in_count: 1, }; } @@ -76,19 +80,14 @@ mutable, we can change a value by using the dot notation and assigning into a particular field. Listing 5-3 shows how to change the value in the `email` field of a mutable `User` instance. -<!--- Do we want to mention that `user1.email` will move the field? We can't -just use `user1.email` multiple times re: "wherever we wanted -to use this value" -/JT ---> -<!-- I don't really want to mention that, but I did reword to avoid the -implication that we can use the value wherever we wanted to. /Carol --> +Filename: src/main.rs ``` fn main() { let mut user1 = User { - email: String::from("someone@example.com"), - username: String::from("someusername123"), active: true, + username: String::from("someusername123"), + email: String::from("someone@example.com"), sign_in_count: 1, }; @@ -110,9 +109,9 @@ the `sign_in_count` gets a value of `1`. ``` fn build_user(email: String, username: String) -> User { User { - email: email, - username: username, active: true, + username: username, + email: email, sign_in_count: 1, } } @@ -130,22 +129,22 @@ would get even more annoying. Luckily, there’s a convenient shorthand! Because the parameter names and the struct field names are exactly the same in Listing 5-4, we can use the *field init shorthand* syntax to rewrite -`build_user` so that it behaves exactly the same but doesn’t have the -repetition of `email` and `username`, as shown in Listing 5-5. +`build_user` so it behaves exactly the same but doesn’t have the repetition of +`username` and `email`, as shown in Listing 5-5. ``` fn build_user(email: String, username: String) -> User { User { - email, - username, active: true, + username, + email, sign_in_count: 1, } } ``` Listing 5-5: A `build_user` function that uses field init shorthand because the -`email` and `username` parameters have the same name as struct fields +`username` and `email` parameters have the same name as struct fields Here, we’re creating a new instance of the `User` struct, which has a field named `email`. We want to set the `email` field’s value to the value in the @@ -153,7 +152,7 @@ named `email`. We want to set the `email` field’s value to the value in the the `email` parameter have the same name, we only need to write `email` rather than `email: email`. -### Creating Instances From Other Instances With Struct Update Syntax +### Creating Instances from Other Instances with Struct Update Syntax It’s often useful to create a new instance of a struct that includes most of the values from another instance, but changes some. You can do this using @@ -163,9 +162,11 @@ First, in Listing 5-6 we show how to create a new `User` instance in `user2` regularly, without the update syntax. We set a new value for `email` but otherwise use the same values from `user1` that we created in Listing 5-2. +Filename: src/main.rs + ``` fn main() { - // --snip-- + --snip-- let user2 = User { active: user1.active, @@ -182,9 +183,12 @@ Using struct update syntax, we can achieve the same effect with less code, as shown in Listing 5-7. The syntax `..` specifies that the remaining fields not explicitly set should have the same value as the fields in the given instance. +Filename: src/main.rs + ``` fn main() { - // --snip-- + --snip-- + let user2 = User { email: String::from("another@example.com"), @@ -194,7 +198,7 @@ fn main() { ``` Listing 5-7: Using struct update syntax to set a new `email` value for a `User` -instance but use the rest of the values from `user1` +instance but to use the rest of the values from `user1` The code in Listing 5-7 also creates an instance in `user2` that has a different value for `email` but has the same values for the `username`, @@ -204,33 +208,30 @@ corresponding fields in `user1`, but we can choose to specify values for as many fields as we want in any order, regardless of the order of the fields in the struct’s definition. -Note that the struct update syntax uses `=` like an assignment; this is -because it moves the data, just as we saw in the “Ways Variables and Data -Interact: Move†section. In this example, we can no longer use `user1` after -creating `user2` because the `String` in the `username` field of `user1` was -moved into `user2`. If we had given `user2` new `String` values for both -`email` and `username`, and thus only used the `active` and `sign_in_count` -values from `user1`, then `user1` would still be valid after creating `user2`. -The types of `active` and `sign_in_count` are types that implement the `Copy` -trait, so the behavior we discussed in the “Stack-Only Data: Copy†section -would apply. - -<!--- Misspelled "assignment" above. -/JT ---> -<!-- Fixed! /Carol --> - -### Using Tuple Structs without Named Fields to Create Different Types - -Rust also supports structs that look similar to tuples, called *tuple -structs*. Tuple structs have the added meaning the struct name provides but -don’t have names associated with their fields; rather, they just have the types -of the fields. Tuple structs are useful when you want to give the whole tuple a -name and make the tuple a different type from other tuples, and when naming each +Note that the struct update syntax uses `=` like an assignment; this is because +it moves the data, just as we saw in “Variables and Data Interacting with Move†+on page XX. In this example, we can no longer use `user1` after creating +`user2` because the `String` in the `username` field of `user1` was moved into +`user2`. If we had given `user2` new `String` values for both `email` and +`username`, and thus only used the `active` and `sign_in_count` values from +`user1`, then `user1` would still be valid after creating `user2`. Both +`active` and `sign_in_count` are types that implement the `Copy` trait, so the +behavior we discussed in “Stack-Only Data: Copy†on page XX would apply. + +### Using Tuple Structs Without Named Fields to Create Different Types + +Rust also supports structs that look similar to tuples, called *tuple structs*. +Tuple structs have the added meaning the struct name provides but don’t have +names associated with their fields; rather, they just have the types of the +fields. Tuple structs are useful when you want to give the whole tuple a name +and make the tuple a different type from other tuples, and when naming each field as in a regular struct would be verbose or redundant. To define a tuple struct, start with the `struct` keyword and the struct name -followed by the types in the tuple. For example, here we define and use -two tuple structs named `Color` and `Point`: +followed by the types in the tuple. For example, here we define and use two +tuple structs named `Color` and `Point`: + +Filename: src/main.rs ``` struct Color(i32, i32, i32); @@ -242,7 +243,7 @@ fn main() { } ``` -Note that the `black` and `origin` values are different types, because they’re +Note that the `black` and `origin` values are different types because they’re instances of different tuple structs. Each struct you define is its own type, even though the fields within the struct might have the same types. For example, a function that takes a parameter of type `Color` cannot take a @@ -251,30 +252,17 @@ values. Otherwise, tuple struct instances are similar to tuples in that you can destructure them into their individual pieces, and you can use a `.` followed by the index to access an individual value. -<!--- The last line above feels a bit misleading. There are related -restrictions on tuple structs that don't apply to tuples. - -One example is you can't create a tuple struct with a tuple. -``` -struct Color(i32, i32, i32); - -fn main() { - let x: Color = (1, 2, 3); -} -``` - -You can't pass a tuple struct to something that expects a tuple, either. -/JT ---> -<!-- I've reworded to avoid that implication /Carol --> - ### Unit-Like Structs Without Any Fields You can also define structs that don’t have any fields! These are called *unit-like structs* because they behave similarly to `()`, the unit type that -we mentioned in “The Tuple Type†section. Unit-like structs can be useful when -you need to implement a trait on some type but don’t have any data that you -want to store in the type itself. We’ll discuss traits in Chapter 10. Here’s an -example of declaring and instantiating a unit struct named `AlwaysEqual`: +we mentioned in “The Tuple Type†on page XX. Unit-like structs can be useful +when you need to implement a trait on some type but don’t have any data that +you want to store in the type itself. We’ll discuss traits in Chapter 10. +Here’s an example of declaring and instantiating a unit struct named +`AlwaysEqual`: + +Filename: src/main.rs ``` struct AlwaysEqual; @@ -284,8 +272,8 @@ fn main() { } ``` -To define `AlwaysEqual`, we use the `struct` keyword, the name we want, then a -semicolon. No need for curly brackets or parentheses! Then we can get an +To define `AlwaysEqual`, we use the `struct` keyword, the name we want, and +then a semicolon. No need for curly brackets or parentheses! Then we can get an instance of `AlwaysEqual` in the `subject` variable in a similar way: using the name we defined, without any curly brackets or parentheses. Imagine that later we’ll implement behavior for this type such that every instance of @@ -297,31 +285,30 @@ implement them on any type, including unit-like structs. > ### Ownership of Struct Data > > In the `User` struct definition in Listing 5-1, we used the owned `String` -> type rather than the `&str` string slice type. This is a deliberate choice -> because we want each instance of this struct to own all of its data and for -> that data to be valid for as long as the entire struct is valid. +type rather than the `&str` string slice type. This is a deliberate choice +because we want each instance of this struct to own all of its data and for +that data to be valid for as long as the entire struct is valid. > > It’s also possible for structs to store references to data owned by something -> else, but to do so requires the use of *lifetimes*, a Rust feature that we’ll -> discuss in Chapter 10. Lifetimes ensure that the data referenced by a struct -> is valid for as long as the struct is. Let’s say you try to store a reference -> in a struct without specifying lifetimes, like the following; this won’t work: -> -> Filename: src/main.rs +else, but to do so requires the use of *lifetimes*, a Rust feature that we’ll +discuss in Chapter 10. Lifetimes ensure that the data referenced by a struct is +valid for as long as the struct is. Let’s say you try to store a reference in a +struct without specifying lifetimes, like the following in *src/main.rs*; this +won’t work: > > ``` > struct User { +> active: bool, > username: &str, > email: &str, > sign_in_count: u64, -> active: bool, > } > > fn main() { > let user1 = User { -> email: "someone@example.com", -> username: "someusername123", > active: true, +> username: "someusername123", +> email: "someone@example.com", > sign_in_count: 1, > }; > } @@ -330,7 +317,7 @@ implement them on any type, including unit-like structs. > The compiler will complain that it needs lifetime specifiers: > > ``` -> $ cargo run +> $ `cargo run` > Compiling structs v0.1.0 (file:///projects/structs) > error[E0106]: missing lifetime specifier > --> src/main.rs:3:15 @@ -361,8 +348,8 @@ implement them on any type, including unit-like structs. > ``` > > In Chapter 10, we’ll discuss how to fix these errors so you can store -> references in structs, but for now, we’ll fix errors like these using owned -> types like `String` instead of references like `&str`. +references in structs, but for now, we’ll fix errors like these using owned +types like `String` instead of references like `&str`. ## An Example Program Using Structs @@ -399,10 +386,6 @@ and height variables Now, run this program using `cargo run`: ``` -$ cargo run - Compiling rectangles v0.1.0 (file:///projects/rectangles) - Finished dev [unoptimized + debuginfo] target(s) in 0.42s - Running `target/debug/rectangles` The area of the rectangle is 1500 square pixels. ``` @@ -417,10 +400,10 @@ fn area(width: u32, height: u32) -> u32 { ``` The `area` function is supposed to calculate the area of one rectangle, but the -function we wrote has two parameters, and it's not clear anywhere in our +function we wrote has two parameters, and it’s not clear anywhere in our program that the parameters are related. It would be more readable and more manageable to group width and height together. We’ve already discussed one way -we might do that in “The Tuple Type†section of Chapter 3: by using tuples. +we might do that in “The Tuple Type†on page XX: by using tuples. ### Refactoring with Tuples @@ -434,21 +417,21 @@ fn main() { println!( "The area of the rectangle is {} square pixels.", - area(rect1) + 1 area(rect1) ); } fn area(dimensions: (u32, u32)) -> u32 { - dimensions.0 * dimensions.1 + 2 dimensions.0 * dimensions.1 } ``` Listing 5-9: Specifying the width and height of the rectangle with a tuple In one way, this program is better. Tuples let us add a bit of structure, and -we’re now passing just one argument. But in another way, this version is less -clear: tuples don’t name their elements, so we have to index into the parts of -the tuple, making our calculation less obvious. +we’re now passing just one argument [1]. But in another way, this version is +less clear: tuples don’t name their elements, so we have to index into the +parts of the tuple [2], making our calculation less obvious. Mixing up the width and height wouldn’t matter for the area calculation, but if we want to draw the rectangle on the screen, it would matter! We would have to @@ -466,13 +449,13 @@ parts, as shown in Listing 5-10. Filename: src/main.rs ``` -struct Rectangle { - width: u32, +1 struct Rectangle { + 2 width: u32, height: u32, } fn main() { - let rect1 = Rectangle { + 3 let rect1 = Rectangle { width: 30, height: 50, }; @@ -483,27 +466,27 @@ fn main() { ); } -fn area(rectangle: &Rectangle) -> u32 { - rectangle.width * rectangle.height +4 fn area(rectangle: &Rectangle) -> u32 { + 5 rectangle.width * rectangle.height } ``` Listing 5-10: Defining a `Rectangle` struct -Here we’ve defined a struct and named it `Rectangle`. Inside the curly +Here, we’ve defined a struct and named it `Rectangle` [1]. Inside the curly brackets, we defined the fields as `width` and `height`, both of which have -type `u32`. Then in `main`, we created a particular instance of `Rectangle` -that has a width of 30 and a height of 50. +type `u32` [2]. Then, in `main`, we created a particular instance of +`Rectangle` that has a width of `30` and a height of `50` [3]. Our `area` function is now defined with one parameter, which we’ve named -`rectangle`, whose type is an immutable borrow of a struct `Rectangle` -instance. As mentioned in Chapter 4, we want to borrow the struct rather than -take ownership of it. This way, `main` retains its ownership and can continue -using `rect1`, which is the reason we use the `&` in the function signature and -where we call the function. +`rectangle`, whose type is an immutable borrow of a struct `Rectangle` instance +[4]. As mentioned in Chapter 4, we want to borrow the struct rather than take +ownership of it. This way, `main` retains its ownership and can continue using +`rect1`, which is the reason we use the `&` in the function signature and where +we call the function. The `area` function accesses the `width` and `height` fields of the `Rectangle` -instance (note that accessing fields of a borrowed struct instance does not +instance [5] (note that accessing fields of a borrowed struct instance does not move the field values, which is why you often see borrows of structs). Our function signature for `area` now says exactly what we mean: calculate the area of `Rectangle`, using its `width` and `height` fields. This conveys that the @@ -511,14 +494,6 @@ width and height are related to each other, and it gives descriptive names to the values rather than using the tuple index values of `0` and `1`. This is a win for clarity. -<!--- Tying to my comment above about `user1.email` moving that field: we should -take a minute here and explain that accessing fields on a borrowed struct does -not move them, and why you often see borrows of structs. -/JT ---> -<!-- I've added a note in the paragraph above; I haven't really seen people -struggle with that concept though so I don't want to spend too much time on it -/Carol --> - ### Adding Useful Functionality with Derived Traits It’d be useful to be able to print an instance of `Rectangle` while we’re @@ -555,7 +530,7 @@ error[E0277]: `Rectangle` doesn't implement `std::fmt::Display` The `println!` macro can do many kinds of formatting, and by default, the curly brackets tell `println!` to use formatting known as `Display`: output intended for direct end user consumption. The primitive types we’ve seen so far -implement `Display` by default, because there’s only one way you’d want to show +implement `Display` by default because there’s only one way you’d want to show a `1` or any other primitive type to a user. But with structs, the way `println!` should format the output is less clear because there are more display possibilities: Do you want commas or not? Do you want to print the @@ -567,7 +542,8 @@ If we continue reading the errors, we’ll find this helpful note: ``` = help: the trait `std::fmt::Display` is not implemented for `Rectangle` -= note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead += note: in format strings you may be able to use `{:?}` (or {:#?} for +pretty-print) instead ``` Let’s try it! The `println!` macro call will now look like `println!("rect1 is @@ -620,24 +596,16 @@ Now when we run the program, we won’t get any errors, and we’ll see the following output: ``` -$ cargo run - Compiling rectangles v0.1.0 (file:///projects/rectangles) - Finished dev [unoptimized + debuginfo] target(s) in 0.48s - Running `target/debug/rectangles` rect1 is Rectangle { width: 30, height: 50 } ``` Nice! It’s not the prettiest output, but it shows the values of all the fields for this instance, which would definitely help during debugging. When we have larger structs, it’s useful to have output that’s a bit easier to read; in -those cases, we can use `{:#?}` instead of `{:?}` in the `println!` string. -In this example, using the `{:#?}` style will output: +those cases, we can use `{:#?}` instead of `{:?}` in the `println!` string. In +this example, using the `{:#?}` style will output the following: ``` -$ cargo run - Compiling rectangles v0.1.0 (file:///projects/rectangles) - Finished dev [unoptimized + debuginfo] target(s) in 0.48s - Running `target/debug/rectangles` rect1 is Rectangle { width: 30, height: 50, @@ -645,20 +613,22 @@ rect1 is Rectangle { ``` Another way to print out a value using the `Debug` format is to use the `dbg!` -macro, which takes ownership of an expression (as opposed to `println!` that +macro, which takes ownership of an expression (as opposed to `println!`, which takes a reference), prints the file and line number of where that `dbg!` macro -call occurs in your code along with the resulting value of that expression, and +call occurs in your code along with the resultant value of that expression, and returns ownership of the value. > Note: Calling the `dbg!` macro prints to the standard error console stream -> (`stderr`), as opposed to `println!` which prints to the standard output -> console stream (`stdout`). We’ll talk more about `stderr` and `stdout` in the -> “Writing Error Messages to Standard Error Instead of Standard Output†section -> in Chapter 12. +(`stderr`), as opposed to `println!`, which prints to the standard output +console stream (`stdout`). We’ll talk more about `stderr` and `stdout` in +“Writing Error Messages to Standard Error Instead of Standard Output†on page +XX. Here’s an example where we’re interested in the value that gets assigned to the `width` field, as well as the value of the whole struct in `rect1`: +Filename: src/main.rs + ``` #[derive(Debug)] struct Rectangle { @@ -669,31 +639,21 @@ struct Rectangle { fn main() { let scale = 2; let rect1 = Rectangle { - width: dbg!(30 * scale), + 1 width: dbg!(30 * scale), height: 50, }; - dbg!(&rect1); + 2 dbg!(&rect1); } ``` -We can put `dbg!` around the expression `30 * scale` and, because `dbg!` +We can put `dbg!` around the expression `30 * scale` [1] and, because `dbg!` returns ownership of the expression’s value, the `width` field will get the same value as if we didn’t have the `dbg!` call there. We don’t want `dbg!` to -take ownership of `rect1`, so we use a reference to `rect1` in the next call. -Here’s what the output of this example looks like: - -<!--- is it worth calling out that println! doesn't have the dbg! shortcoming -of taking ownership? -/JT ---> -<!-- I added a note in the paragraph above that starts with "Another way to -print out a value" /Carol --> +take ownership of `rect1`, so we use a reference to `rect1` in the next call +[2]. Here’s what the output of this example looks like: ``` -$ cargo run - Compiling rectangles v0.1.0 (file:///projects/rectangles) - Finished dev [unoptimized + debuginfo] target(s) in 0.61s - Running `target/debug/rectangles` [src/main.rs:10] 30 * scale = 60 [src/main.rs:14] &rect1 = Rectangle { width: 60, @@ -701,13 +661,13 @@ $ cargo run } ``` -We can see the first bit of output came from *src/main.rs* line 10, where we’re -debugging the expression `30 * scale`, and its resulting value is 60 (the -`Debug` formatting implemented for integers is to print only their value). The -`dbg!` call on line 14 of *src/main.rs* outputs the value of `&rect1`, which is -the `Rectangle` struct. This output uses the pretty `Debug` formatting of the -`Rectangle` type. The `dbg!` macro can be really helpful when you’re trying to -figure out what your code is doing! +We can see the first bit of output came from [1] where we’re debugging the +expression `30 * scale`, and its resultant value is `60` (the `Debug` +formatting implemented for integers is to print only their value). The `dbg!` +call at [2] outputs the value of `&rect1`, which is the `Rectangle` struct. +This output uses the pretty `Debug` formatting of the `Rectangle` type. The +`dbg!` macro can be really helpful when you’re trying to figure out what your +code is doing! In addition to the `Debug` trait, Rust has provided a number of traits for us to use with the `derive` attribute that can add useful behavior to our custom @@ -718,10 +678,10 @@ your own traits in Chapter 10. There are also many attributes other than Reference at *https://doc.rust-lang.org/reference/attributes.html*. Our `area` function is very specific: it only computes the area of rectangles. -It would be helpful to tie this behavior more closely to our `Rectangle` -struct, because it won’t work with any other type. Let’s look at how we can -continue to refactor this code by turning the `area` function into an `area` -*method* defined on our `Rectangle` type. +It would be helpful to tie this behavior more closely to our `Rectangle` struct +because it won’t work with any other type. Let’s look at how we can continue to +refactor this code by turning the `area` function into an `area` *method* +defined on our `Rectangle` type. ## Method Syntax @@ -729,18 +689,9 @@ continue to refactor this code by turning the `area` function into an `area` name, they can have parameters and a return value, and they contain some code that’s run when the method is called from somewhere else. Unlike functions, methods are defined within the context of a struct (or an enum or a trait -object, which we cover in Chapters 6 and 17, respectively), and their first -parameter is always `self`, which represents the instance of the struct the -method is being called on. - -<!--- minor nit: some folks call the non-self functions in an `impl` -"static methods" as a nod to OO languages that do the same. For folks -from that background, we may want to call out that instance methods always -have `self` and methods on the type do not. -/JT ---> -<!-- This paragraph already says "their first parameter is always `self`", and -we get into associated functions in just a bit. I don't want to distract with -that info here; not changing anything at this spot. /Carol --> +object, which we cover in Chapter 6 and Chapter 17, respectively), and their +first parameter is always `self`, which represents the instance of the struct +the method is being called on. ### Defining Methods @@ -757,8 +708,8 @@ struct Rectangle { height: u32, } -impl Rectangle { - fn area(&self) -> u32 { +1 impl Rectangle { + 2 fn area(&self) -> u32 { self.width * self.height } } @@ -771,7 +722,7 @@ fn main() { println!( "The area of the rectangle is {} square pixels.", - rect1.area() + 3 rect1.area() ); } ``` @@ -779,14 +730,14 @@ fn main() { Listing 5-13: Defining an `area` method on the `Rectangle` struct To define the function within the context of `Rectangle`, we start an `impl` -(implementation) block for `Rectangle`. Everything within this `impl` block +(implementation) block for `Rectangle` [1]. Everything within this `impl` block will be associated with the `Rectangle` type. Then we move the `area` function -within the `impl` curly brackets and change the first (and in this case, only) -parameter to be `self` in the signature and everywhere within the body. In -`main`, where we called the `area` function and passed `rect1` as an argument, -we can instead use *method syntax* to call the `area` method on our `Rectangle` -instance. The method syntax goes after an instance: we add a dot followed by -the method name, parentheses, and any arguments. +within the `impl` curly brackets [2] and change the first (and in this case, +only) parameter to be `self` in the signature and everywhere within the body. +In `main`, where we called the `area` function and passed `rect1` as an +argument, we can instead use *method syntax* to call the `area` method on our +`Rectangle` instance [3]. The method syntax goes after an instance: we add a +dot followed by the method name, parentheses, and any arguments. In the signature for `area`, we use `&self` instead of `rectangle: &Rectangle`. The `&self` is actually short for `self: &Self`. Within an `impl` block, the @@ -794,28 +745,30 @@ type `Self` is an alias for the type that the `impl` block is for. Methods must have a parameter named `self` of type `Self` for their first parameter, so Rust lets you abbreviate this with only the name `self` in the first parameter spot. Note that we still need to use the `&` in front of the `self` shorthand to -indicate this method borrows the `Self` instance, just as we did in `rectangle: -&Rectangle`. Methods can take ownership of `self`, borrow `self` immutably as -we’ve done here, or borrow `self` mutably, just as they can any other parameter. - -We’ve chosen `&self` here for the same reason we used `&Rectangle` in the -function version: we don’t want to take ownership, and we just want to read the -data in the struct, not write to it. If we wanted to change the instance that -we’ve called the method on as part of what the method does, we’d use `&mut -self` as the first parameter. Having a method that takes ownership of the -instance by using just `self` as the first parameter is rare; this technique is -usually used when the method transforms `self` into something else and you want -to prevent the caller from using the original instance after the transformation. - -The main reason for using methods instead of functions, in addition to providing -method syntax and not having to repeat the type of `self` in every method’s -signature, is for organization. We’ve put all the things we can do with an -instance of a type in one `impl` block rather than making future users of our -code search for capabilities of `Rectangle` in various places in the library we -provide. +indicate that this method borrows the `Self` instance, just as we did in +`rectangle: &Rectangle`. Methods can take ownership of `self`, borrow `self` +immutably, as we’ve done here, or borrow `self` mutably, just as they can any +other parameter. + +We chose `&self` here for the same reason we used `&Rectangle` in the function +version: we don’t want to take ownership, and we just want to read the data in +the struct, not write to it. If we wanted to change the instance that we’ve +called the method on as part of what the method does, we’d use `&mut self` as +the first parameter. Having a method that takes ownership of the instance by +using just `self` as the first parameter is rare; this technique is usually +used when the method transforms `self` into something else and you want to +prevent the caller from using the original instance after the transformation. + +The main reason for using methods instead of functions, in addition to +providing method syntax and not having to repeat the type of `self` in every +method’s signature, is for organization. We’ve put all the things we can do +with an instance of a type in one `impl` block rather than making future users +of our code search for capabilities of `Rectangle` in various places in the +library we provide. Note that we can choose to give a method the same name as one of the struct’s -fields. For example, we can define a method on `Rectangle` also named `width`: +fields. For example, we can define a method on `Rectangle` that is also named +`width`: Filename: src/main.rs @@ -833,42 +786,45 @@ fn main() { }; if rect1.width() { - println!("The rectangle has a nonzero width; it is {}", rect1.width); + println!( + "The rectangle has a nonzero width; it is {}", + rect1.width + ); } } ``` Here, we’re choosing to make the `width` method return `true` if the value in -the instance’s `width` field is greater than 0, and `false` if the value is 0: -we can use a field within a method of the same name for any purpose. In `main`, -when we follow `rect1.width` with parentheses, Rust knows we mean the method -`width`. When we don’t use parentheses, Rust knows we mean the field `width`. +the instance’s `width` field is greater than `0` and `false` if the value is +`0`: we can use a field within a method of the same name for any purpose. In +`main`, when we follow `rect1.width` with parentheses, Rust knows we mean the +method `width`. When we don’t use parentheses, Rust knows we mean the field +`width`. Often, but not always, when we give methods with the same name as a field we want it to only return the value in the field and do nothing else. Methods like this are called *getters*, and Rust does not implement them automatically for struct fields as some other languages do. Getters are useful because you can -make the field private but the method public and thus enable read-only access -to that field as part of the type’s public API. We will be discussing what -public and private are and how to designate a field or method as public or -private in Chapter 7. +make the field private but the method public, and thus enable read-only access +to that field as part of the type’s public API. We will discuss what public and +private are and how to designate a field or method as public or private in +Chapter 7. -> ### Where’s the `->` Operator? +> ### Where’s the -> Operator? > > In C and C++, two different operators are used for calling methods: you use -> `.` if you’re calling a method on the object directly and `->` if you’re -> calling the method on a pointer to the object and need to dereference the -> pointer first. In other words, if `object` is a pointer, -> `object->something()` is similar to `(*object).something()`. +`.` if you’re calling a method on the object directly and `->` if you’re +calling the method on a pointer to the object and need to dereference the +pointer first. In other words, if `object` is a pointer, +`object->`something`()` is similar to `(*object).`something`()`. > > Rust doesn’t have an equivalent to the `->` operator; instead, Rust has a -> feature called *automatic referencing and dereferencing*. Calling methods is -> one of the few places in Rust that has this behavior. -> -> Here’s how it works: when you call a method with `object.something()`, Rust -> automatically adds in `&`, `&mut`, or `*` so `object` matches the signature of -> the method. In other words, the following are the same: +feature called *automatic referencing and dereferencing*. Calling methods is +one of the few places in Rust that has this behavior. > +> Here’s how it works: when you call a method with `object.`something`()`, Rust +automatically adds in `&`, `&mut`, or `*` so `object` matches the signature of +the method. In other words, the following are the same: > > ``` > p1.distance(&p2); @@ -876,20 +832,20 @@ private in Chapter 7. > ``` > > The first one looks much cleaner. This automatic referencing behavior works -> because methods have a clear receiver—the type of `self`. Given the receiver -> and name of a method, Rust can figure out definitively whether the method is -> reading (`&self`), mutating (`&mut self`), or consuming (`self`). The fact -> that Rust makes borrowing implicit for method receivers is a big part of -> making ownership ergonomic in practice. +because methods have a clear receiver—the type of `self`. Given the receiver +and name of a method, Rust can figure out definitively whether the method is +reading (`&self`), mutating (`&mut self`), or consuming (`self`). The fact that +Rust makes borrowing implicit for method receivers is a big part of making +ownership ergonomic in practice. ### Methods with More Parameters Let’s practice using methods by implementing a second method on the `Rectangle` -struct. This time, we want an instance of `Rectangle` to take another instance +struct. This time we want an instance of `Rectangle` to take another instance of `Rectangle` and return `true` if the second `Rectangle` can fit completely -within `self` (the first `Rectangle`); otherwise it should return `false`. That -is, once we’ve defined the `can_hold` method, we want to be able to write the -program shown in Listing 5-14. +within `self` (the first `Rectangle`); otherwise, it should return `false`. +That is, once we’ve defined the `can_hold` method, we want to be able to write +the program shown in Listing 5-14. Filename: src/main.rs @@ -915,8 +871,8 @@ fn main() { Listing 5-14: Using the as-yet-unwritten `can_hold` method -And the expected output would look like the following, because both dimensions -of `rect2` are smaller than the dimensions of `rect1` but `rect3` is wider than +The expected output would look like the following because both dimensions of +`rect2` are smaller than the dimensions of `rect1`, but `rect3` is wider than `rect1`: ``` @@ -934,7 +890,7 @@ read `rect2` (rather than write, which would mean we’d need a mutable borrow), and we want `main` to retain ownership of `rect2` so we can use it again after calling the `can_hold` method. The return value of `can_hold` will be a Boolean, and the implementation will check whether the width and height of -`self` are both greater than the width and height of the other `Rectangle`, +`self` are greater than the width and height of the other `Rectangle`, respectively. Let’s add the new `can_hold` method to the `impl` block from Listing 5-13, shown in Listing 5-15. @@ -981,8 +937,8 @@ Filename: src/main.rs ``` impl Rectangle { - fn square(size: u32) -> Self [1] { - Self [2] { + fn square(size: u32) -> 1 Self { + 2 Self { width: size, height: size, } @@ -999,17 +955,11 @@ To call this associated function, we use the `::` syntax with the struct name; the struct: the `::` syntax is used for both associated functions and namespaces created by modules. We’ll discuss modules in Chapter 7. -<!--- Should we mention the most common associated function is `new`? And that -new isn't built into the language. -/JT ---> -<!-- I've added a note as such above to the paragraph that starts with -"Associated functions that aren’t methods" /Carol --> - -### Multiple `impl` Blocks +### Multiple impl Blocks Each struct is allowed to have multiple `impl` blocks. For example, Listing -5-15 is equivalent to the code shown in Listing 5-16, which has each method -in its own `impl` block. +5-15 is equivalent to the code shown in Listing 5-16, which has each method in +its own `impl` block. ``` impl Rectangle { @@ -1043,31 +993,3 @@ structs have. But structs aren’t the only way you can create custom types: let’s turn to Rust’s enum feature to add another tool to your toolbox. -<!--- We don't mention that you can only use `impl` in the same crate as the -type it's created in, otherwise you could use `impl` and add methods on types -that come from other people (which you can't do, unless you make a trait to -attach them to) - -Another thing we may want to mention is that `Self` inside of an `impl` refers -to the type being impl'd. So you might write the above: - -``` -impl Rectangle { - fn square(size: u32) -> Self { - Self { - width: size, - height: size, - } - } -} -``` -which is often a bit more ergonomic. - -/JT ---> -<!-- I've changed the `square` example to use `Self` and added some wingdings -and notes explaining that. I don't really want to get into the restrictions on -`impl` on types defined in another crate, because we haven't covered traits -yet. Traits let you do `impl Trait for OtherCrateType` in some circumstances, -so I don't want to say "you can't use an `impl` block on types from other -crates" because I'd have to allude to traits or potentially give the reader the -wrong impression. We get into these restrictions in chapter 10. --> diff --git a/src/doc/book/nostarch/chapter06.md b/src/doc/book/nostarch/chapter06.md index 47b51b5a1..ea4328bea 100644 --- a/src/doc/book/nostarch/chapter06.md +++ b/src/doc/book/nostarch/chapter06.md @@ -8,8 +8,8 @@ directory, so all fixes need to be made in `/src/`. # Enums and Pattern Matching -In this chapter we’ll look at *enumerations*, also referred to as *enums*. -Enums allow you to define a type by enumerating its possible *variants*. First, +In this chapter, we’ll look at *enumerations*, also referred to as *enums*. +Enums allow you to define a type by enumerating its possible *variants*. First we’ll define and use an enum to show how an enum can encode meaning along with data. Next, we’ll explore a particularly useful enum, called `Option`, which expresses that a value can be either something or nothing. Then we’ll look at @@ -18,37 +18,8 @@ code for different values of an enum. Finally, we’ll cover how the `if let` construct is another convenient and concise idiom available to handle enums in your code. -<!--- The above about algebraic data types feels pretty niche. Should it get -the "expert aside" treatment that some of the early texts gets? /JT ---> -<!-- I decided to just remove the paragraph this comment was about. /Carol --> - ## Defining an Enum -<!--- I added this first line, it seems like this is what we're saying? Maybe -summarize what enums are better suited for: when you know all possible outcomes -and that the outcomes must be distinct from each other? I was hoping to -generalize their usage early. Edit: reading on, I can see that might be tricky, -so ignore this if so! /LC ---> -<!-- I made a slight edit to the first line here, what do you think? I don't -think "enums are an alternative to structs" was quite right, because that -sounded like in any situation, you could choose either enum or struct according -to your preferences, but what I'd like the reader to come away with is that -some situations are better expressed with enums; others with structs. /Carol --> -<!-- I think this makes sense! I wonder if there's more we could add to give an -idea of why we're contrasting them with structs, to give the reader a point of -reference. What do you think JT? Would more explanation here be redundant? /LC ---> -<!--- Here's my try for a framing, using our earlier Rectangle example: -Where structs give you a way of grouping together related fields and data, like -a `Rectangle` with its `width` and `height`, we don't yet have a way of saying -a values is one of a possible set of values. For example, we may want to say -that Rectangle is one of a set of possible shapes. To do this, Rust allows us -to encode these possibilities as an enum. Let's look at... -/JT ---> -<!-- I've generally taken JT's suggestion with a few edits. I'm a little -concerned that we won't ever actually make a `Shape` enum with variants -`Rectangle`, `Circle`, and `Triangle`? Is that a problem, Liz? /Carol --> - Where structs give you a way of grouping together related fields and data, like a `Rectangle` with its `width` and `height`, enums give you a way of saying a value is one of a possible set of values. For example, we may want to say that @@ -64,7 +35,7 @@ variants, which is where enumeration gets its name. Any IP address can be either a version four or a version six address, but not both at the same time. That property of IP addresses makes the enum data -structure appropriate, because an enum value can only be one of its variants. +structure appropriate because an enum value can only be one of its variants. Both version four and version six addresses are still fundamentally IP addresses, so they should be treated as the same type when the code is handling situations that apply to any kind of IP address. @@ -114,22 +85,22 @@ Chapter 5, you might be tempted to tackle this problem with structs as shown in Listing 6-1. ``` -enum IpAddrKind { +1 enum IpAddrKind { V4, V6, } -struct IpAddr { - kind: IpAddrKind, - address: String, +2 struct IpAddr { + 3 kind: IpAddrKind, + 4 address: String, } -let home = IpAddr { +5 let home = IpAddr { kind: IpAddrKind::V4, address: String::from("127.0.0.1"), }; -let loopback = IpAddr { +6 let loopback = IpAddr { kind: IpAddrKind::V6, address: String::from("::1"), }; @@ -138,14 +109,14 @@ let loopback = IpAddr { Listing 6-1: Storing the data and `IpAddrKind` variant of an IP address using a `struct` -Here, we’ve defined a struct `IpAddr` that has two fields: a `kind` field that -is of type `IpAddrKind` (the enum we defined previously) and an `address` field -of type `String`. We have two instances of this struct. The first is `home`, -and it has the value `IpAddrKind::V4` as its `kind` with associated address -data of `127.0.0.1`. The second instance is `loopback`. It has the other -variant of `IpAddrKind` as its `kind` value, `V6`, and has address `::1` -associated with it. We’ve used a struct to bundle the `kind` and `address` -values together, so now the variant is associated with the value. +Here, we’ve defined a struct `IpAddr` [2] that has two fields: a `kind` field +[3] that is of type `IpAddrKind` (the enum we defined previously [1]) and an +`address` field [4] of type `String`. We have two instances of this struct. The +first is `home` [5], and it has the value `IpAddrKind::V4` as its `kind` with +associated address data of `127.0.0.1`. The second instance is `loopback` [6]. +It has the other variant of `IpAddrKind` as its `kind` value, `V6`, and has +address `::1` associated with it. We’ve used a struct to bundle the `kind` and +`address` values together, so now the variant is associated with the value. However, representing the same concept using just an enum is more concise: rather than an enum inside a struct, we can put data directly into each enum @@ -164,7 +135,7 @@ let loopback = IpAddr::V6(String::from("::1")); ``` We attach data to each variant of the enum directly, so there is no need for an -extra struct. Here it’s also easier to see another detail of how enums work: +extra struct. Here, it’s also easier to see another detail of how enums work: the name of each enum variant that we define also becomes a function that constructs an instance of the enum. That is, `IpAddr::V4()` is a function call that takes a `String` argument and returns an instance of the `IpAddr` type. We @@ -172,7 +143,7 @@ automatically get this constructor function defined as a result of defining the enum. There’s another advantage to using an enum rather than a struct: each variant -can have different types and amounts of associated data. Version four type IP +can have different types and amounts of associated data. Version four IP addresses will always have four numeric components that will have values between 0 and 255. If we wanted to store `V4` addresses as four `u8` values but still express `V6` addresses as one `String` value, we wouldn’t be able to with @@ -199,11 +170,11 @@ different structs, which are defined differently for each variant: ``` struct Ipv4Addr { - // --snip-- + --snip-- } struct Ipv6Addr { - // --snip-- + --snip-- } enum IpAddr { @@ -240,7 +211,7 @@ types of values This enum has four variants with different types: * `Quit` has no data associated with it at all. -* `Move` has named fields like a struct does. +* `Move` has named fields, like a struct does. * `Write` includes a single `String`. * `ChangeColor` includes three `i32` values. @@ -260,16 +231,10 @@ struct WriteMessage(String); // tuple struct struct ChangeColorMessage(i32, i32, i32); // tuple struct ``` -But if we used the different structs, which each have their own type, we +But if we used the different structs, each of which has its own type, we couldn’t as easily define a function to take any of these kinds of messages as we could with the `Message` enum defined in Listing 6-2, which is a single type. -<!--- We're also hinting at pattern matching complexity if we use the struct -method. Should we call it out and mention the pattern matching chapter? -/JT ---> -<!-- If readers don't have experience with pattern matching, I don't think this -will resonate with them, so I'm not going to mention it here. /Carol --> - There is one more similarity between enums and structs: just as we’re able to define methods on structs using `impl`, we’re also able to define methods on enums. Here’s a method named `call` that we could define on our `Message` enum: @@ -277,34 +242,34 @@ enums. Here’s a method named `call` that we could define on our `Message` enum ``` impl Message { fn call(&self) { - // method body would be defined here + 1 // method body would be defined here } } -let m = Message::Write(String::from("hello")); +2 let m = Message::Write(String::from("hello")); m.call(); ``` The body of the method would use `self` to get the value that we called the -method on. In this example, we’ve created a variable `m` that has the value +method on. In this example, we’ve created a variable `m` [2] that has the value `Message::Write(String::from("hello"))`, and that is what `self` will be in the -body of the `call` method when `m.call()` runs. +body of the `call` method [1] when `m.call()` runs. Let’s look at another enum in the standard library that is very common and useful: `Option`. -### The `Option` Enum and Its Advantages Over Null Values +### The Option Enum and Its Advantages Over Null Values This section explores a case study of `Option`, which is another enum defined by the standard library. The `Option` type encodes the very common scenario in which a value could be something or it could be nothing. -For example, if you request the first of a list containing items, you would get -a value. If you request the first item of an empty list, you would get nothing. -Expressing this concept in terms of the type system means the compiler can -check whether you’ve handled all the cases you should be handling; this -functionality can prevent bugs that are extremely common in other programming -languages. +For example, if you request the first item in a list containing multiple items, +you would get a value. If you request the first item in an empty list, you +would get nothing. Expressing this concept in terms of the type system means +the compiler can check whether you’ve handled all the cases you should be +handling; this functionality can prevent bugs that are extremely common in +other programming languages. Programming language design is often thought of in terms of which features you include, but the features you exclude are important too. Rust doesn’t have the @@ -316,17 +281,16 @@ In his 2009 presentation “Null References: The Billion Dollar Mistake,†Tony Hoare, the inventor of null, has this to say: > I call it my billion-dollar mistake. At that time, I was designing the first -> comprehensive type system for references in an object-oriented language. My -> goal was to ensure that all use of references should be absolutely safe, with -> checking performed automatically by the compiler. But I couldn’t resist the -> temptation to put in a null reference, simply because it was so easy to -> implement. This has led to innumerable errors, vulnerabilities, and system -> crashes, which have probably caused a billion dollars of pain and damage in -> the last forty years. - -The problem with null values is that if you try to use a null value as a -not-null value, you’ll get an error of some kind. Because this null or not-null -property is pervasive, it’s extremely easy to make this kind of error. +comprehensive type system for references in an object-oriented language. My +goal was to ensure that all use of references should be absolutely safe, with +checking performed automatically by the compiler. But I couldn’t resist the +temptation to put in a null reference, simply because it was so easy to +implement. This has led to innumerable errors, vulnerabilities, and system +crashes, which have probably caused a billion dollars of pain and damage in the +last forty years.The problem with null values is that if you try to use a null +value as a not-null value, you’ll get an error of some kind. Because this null +or not-null property is pervasive, it’s extremely easy to make this kind of +error. However, the concept that null is trying to express is still a useful one: a null is a value that is currently invalid or absent for some reason. @@ -334,8 +298,7 @@ null is a value that is currently invalid or absent for some reason. The problem isn’t really with the concept but with the particular implementation. As such, Rust does not have nulls, but it does have an enum that can encode the concept of a value being present or absent. This enum is -`Option<T>`, and it is defined by the standard library -as follows: +`Option<T>`, and it is defined by the standard library as follows: ``` enum Option<T> { @@ -352,11 +315,11 @@ prefix. The `Option<T>` enum is still just a regular enum, and `Some(T)` and The `<T>` syntax is a feature of Rust we haven’t talked about yet. It’s a generic type parameter, and we’ll cover generics in more detail in Chapter 10. -For now, all you need to know is that `<T>` means the `Some` variant of the -`Option` enum can hold one piece of data of any type, and that each concrete -type that gets used in place of `T` makes the overall `Option<T>` type a -different type. Here are some examples of using `Option` values to hold number -types and string types: +For now, all you need to know is that `<T>` means that the `Some` variant of +the `Option` enum can hold one piece of data of any type, and that each +concrete type that gets used in place of `T` makes the overall `Option<T>` type +a different type. Here are some examples of using `Option` values to hold +number types and string types: ``` let some_number = Some(5); @@ -365,26 +328,6 @@ let some_char = Some('e'); let absent_number: Option<i32> = None; ``` -<!--- I would maybe do the above more explicitly as: - -" -``` -let some_number = Some(5); - -let some_number2: Option<i32> = Some(5); -``` -The types of `some_number` and `some_number2` in the above are identical. -" - -Using `Some("a string")` we're going to open the door to references in -generic positions (which we still need to build up to). We talk a little about -Option<&str> below, but I don't think it helps explain the enum concept. - -/JT ---> -<!-- I changed the above to use `char` rather than string slice, but we're -trying to show that options holding different types are themselves different -types below, so I didn't want to make them both `i32`. /Carol --> - The type of `some_number` is `Option<i32>`. The type of `some_char` is `Option<char>`, which is a different type. Rust can infer these types because we’ve specified a value inside the `Some` variant. For `absent_number`, Rust @@ -394,13 +337,13 @@ type that the corresponding `Some` variant will hold by looking only at a `Option<i32>`. When we have a `Some` value, we know that a value is present and the value is -held within the `Some`. When we have a `None` value, in some sense, it means -the same thing as null: we don’t have a valid value. So why is having -`Option<T>` any better than having null? +held within the `Some`. When we have a `None` value, in some sense it means the +same thing as null: we don’t have a valid value. So why is having `Option<T>` +any better than having null? In short, because `Option<T>` and `T` (where `T` can be any type) are different types, the compiler won’t let us use an `Option<T>` value as if it were -definitely a valid value. For example, this code won’t compile because it’s +definitely a valid value. For example, this code won’t compile, because it’s trying to add an `i8` to an `Option<i8>`: ``` @@ -410,11 +353,9 @@ let y: Option<i8> = Some(5); let sum = x + y; ``` -If we run this code, we get an error message like this: +If we run this code, we get an error message like this one: ``` -$ cargo run - Compiling enums v0.1.0 (file:///projects/enums) error[E0277]: cannot add `Option<i8>` to `i8` --> src/main.rs:5:17 | @@ -435,8 +376,7 @@ using the value. In other words, you have to convert an `Option<T>` to a `T` before you can perform `T` operations with it. Generally, this helps catch one of the most -common issues with null: assuming that something isn’t null when it actually -is. +common issues with null: assuming that something isn’t null when it actually is. Eliminating the risk of incorrectly assuming a not-null value helps you to be more confident in your code. In order to have a value that can possibly be @@ -447,30 +387,30 @@ when the value is null. Everywhere that a value has a type that isn’t an deliberate design decision for Rust to limit null’s pervasiveness and increase the safety of Rust code. -So, how do you get the `T` value out of a `Some` variant when you have a value -of type `Option<T>` so you can use that value? The `Option<T>` enum has a large -number of methods that are useful in a variety of situations; you can check -them out in its documentation. Becoming familiar with the methods on +So how do you get the `T` value out of a `Some` variant when you have a value +of type `Option<T>` so that you can use that value? The `Option<T>` enum has a +large number of methods that are useful in a variety of situations; you can +check them out in its documentation. Becoming familiar with the methods on `Option<T>` will be extremely useful in your journey with Rust. In general, in order to use an `Option<T>` value, you want to have code that will handle each variant. You want some code that will run only when you have a `Some(T)` value, and this code is allowed to use the inner `T`. You want some -other code to run if you have a `None` value, and that code doesn’t have a `T` -value available. The `match` expression is a control flow construct that does -just this when used with enums: it will run different code depending on which -variant of the enum it has, and that code can use the data inside the matching -value. - -## The `match` Control Flow Construct - -Rust has an extremely powerful control flow construct called `match` that allows -you to compare a value against a series of patterns and then execute code based -on which pattern matches. Patterns can be made up of literal values, variable -names, wildcards, and many other things; Chapter 18 covers all the different -kinds of patterns and what they do. The power of `match` comes from the -expressiveness of the patterns and the fact that the compiler confirms that all -possible cases are handled. +other code to run only if you have a `None` value, and that code doesn’t have a +`T` value available. The `match` expression is a control flow construct that +does just this when used with enums: it will run different code depending on +which variant of the enum it has, and that code can use the data inside the +matching value. + +## The match Control Flow Construct + +Rust has an extremely powerful control flow construct called `match` that +allows you to compare a value against a series of patterns and then execute +code based on which pattern matches. Patterns can be made up of literal values, +variable names, wildcards, and many other things; Chapter 18 covers all the +different kinds of patterns and what they do. The power of `match` comes from +the expressiveness of the patterns and the fact that the compiler confirms that +all possible cases are handled. Think of a `match` expression as being like a coin-sorting machine: coins slide down a track with variously sized holes along it, and each coin falls through @@ -479,12 +419,12 @@ through each pattern in a `match`, and at the first pattern the value “fits,†the value falls into the associated code block to be used during execution. Speaking of coins, let’s use them as an example using `match`! We can write a -function that takes an unknown United States coin and, in a similar way as the -counting machine, determines which coin it is and return its value in cents, as -shown here in Listing 6-3. +function that takes an unknown US coin and, in a similar way as the counting +machine, determines which coin it is and returns its value in cents, as shown +in Listing 6-3. ``` -[1]enum Coin { +1 enum Coin { Penny, Nickel, Dime, @@ -492,8 +432,8 @@ shown here in Listing 6-3. } fn value_in_cents(coin: Coin) -> u8 { - match coin { - Coin::Penny => 1, + 2 match coin { + 3 Coin::Penny => 1, Coin::Nickel => 5, Coin::Dime => 10, Coin::Quarter => 25, @@ -504,36 +444,29 @@ fn value_in_cents(coin: Coin) -> u8 { Listing 6-3: An enum and a `match` expression that has the variants of the enum as its patterns -Let’s break down the `match` in the `value_in_cents` function. First, we list +Let’s break down the `match` in the `value_in_cents` function. First we list the `match` keyword followed by an expression, which in this case is the value -`coin`. This seems very similar to an expression used with `if`, but there’s a -big difference: with `if`, the expression needs to return a Boolean value, but -here, it can return any type. The type of `coin` in this example is the `Coin` -enum that we defined at [1]. +`coin` [2]. This seems very similar to an expression used with `if`, but +there’s a big difference: with `if`, the expression needs to return a Boolean +value, but here it can return any type. The type of `coin` in this example is +the `Coin` enum that we defined at [1]. Next are the `match` arms. An arm has two parts: a pattern and some code. The first arm here has a pattern that is the value `Coin::Penny` and then the `=>` -operator that separates the pattern and the code to run. The code in this case -is just the value `1`. Each arm is separated from the next with a comma. +operator that separates the pattern and the code to run [3]. The code in this +case is just the value `1`. Each arm is separated from the next with a comma. -<!--- Tiny nit, though not sure how to phrase it. Arms are separated by commas -in this example, though if you use blocks instead of simple values you won't use -commas. We see this happen in the next example. -/JT ---> -<!-- I clarified in the paragraph before the next example. You *can* use commas -even if there's curly brackets, but people don't usually. /Carol --> - -When the `match` expression executes, it compares the resulting value against +When the `match` expression executes, it compares the resultant value against the pattern of each arm, in order. If a pattern matches the value, the code associated with that pattern is executed. If that pattern doesn’t match the value, execution continues to the next arm, much as in a coin-sorting machine. We can have as many arms as we need: in Listing 6-3, our `match` has four arms. -The code associated with each arm is an expression, and the resulting value of +The code associated with each arm is an expression, and the resultant value of the expression in the matching arm is the value that gets returned for the entire `match` expression. -We don't typically use curly brackets if the match arm code is short, as it is +We don’t typically use curly brackets if the match arm code is short, as it is in Listing 6-3 where each arm just returns a value. If you want to run multiple lines of code in a match arm, you must use curly brackets, and the comma following the arm is then optional. For example, the following code prints @@ -554,7 +487,7 @@ fn value_in_cents(coin: Coin) -> u8 { } ``` -### Patterns that Bind to Values +### Patterns That Bind to Values Another useful feature of match arms is that they can bind to the parts of the values that match the pattern. This is how we can extract values out of enum @@ -564,15 +497,15 @@ As an example, let’s change one of our enum variants to hold data inside it. From 1999 through 2008, the United States minted quarters with different designs for each of the 50 states on one side. No other coins got state designs, so only quarters have this extra value. We can add this information to -our `enum` by changing the `Quarter` variant to include a `UsState` value stored -inside it, which we’ve done here in Listing 6-4. +our `enum` by changing the `Quarter` variant to include a `UsState` value +stored inside it, which we’ve done in Listing 6-4. ``` #[derive(Debug)] // so we can inspect the state in a minute enum UsState { Alabama, Alaska, - // --snip-- + --snip-- } enum Coin { @@ -588,8 +521,8 @@ Listing 6-4: A `Coin` enum in which the `Quarter` variant also holds a Let’s imagine that a friend is trying to collect all 50 state quarters. While we sort our loose change by coin type, we’ll also call out the name of the -state associated with each quarter so if it’s one our friend doesn’t have, they -can add it to their collection. +state associated with each quarter so that if it’s one our friend doesn’t have, +they can add it to their collection. In the match expression for this code, we add a variable called `state` to the pattern that matches values of the variant `Coin::Quarter`. When a @@ -617,13 +550,13 @@ that point, the binding for `state` will be the value `UsState::Alaska`. We can then use that binding in the `println!` expression, thus getting the inner state value out of the `Coin` enum variant for `Quarter`. -### Matching with `Option<T>` +### Matching with Option<T> In the previous section, we wanted to get the inner `T` value out of the `Some` -case when using `Option<T>`; we can also handle `Option<T>` using `match` as we -did with the `Coin` enum! Instead of comparing coins, we’ll compare the -variants of `Option<T>`, but the way that the `match` expression works remains -the same. +case when using `Option<T>`; we can also handle `Option<T>` using `match`, as +we did with the `Coin` enum! Instead of comparing coins, we’ll compare the +variants of `Option<T>`, but the way the `match` expression works remains the +same. Let’s say we want to write a function that takes an `Option<i32>` and, if there’s a value inside, adds 1 to that value. If there isn’t a value inside, @@ -636,44 +569,40 @@ Listing 6-5. ``` fn plus_one(x: Option<i32>) -> Option<i32> { match x { - None => None, - Some(i) => Some(i + 1), + 1 None => None, + 2 Some(i) => Some(i + 1), } } let five = Some(5); -let six = plus_one(five); -let none = plus_one(None); +let six = plus_one(five); 3 +let none = plus_one(None); 4 ``` Listing 6-5: A function that uses a `match` expression on an `Option<i32>` Let’s examine the first execution of `plus_one` in more detail. When we call -`plus_one(five)`, the variable `x` in the body of `plus_one` will have the -value `Some(5)`. We then compare that against each match arm. +`plus_one(five)` [3], the variable `x` in the body of `plus_one` will have the +value `Some(5)`. We then compare that against each match arm: ``` None => None, ``` -The `Some(5)` value doesn’t match the pattern `None`, so we continue to the -next arm. +The `Some(5)` value doesn’t match the pattern `None` [1], so we continue to the +next arm: ``` Some(i) => Some(i + 1), ``` -Does `Some(5)` match `Some(i)`? Why yes it does! We have the same variant. The -`i` binds to the value contained in `Some`, so `i` takes the value `5`. The +Does `Some(5)` match `Some(i)` [2]? Why yes, it does! We have the same variant. +The `i` binds to the value contained in `Some`, so `i` takes the value `5`. The code in the match arm is then executed, so we add 1 to the value of `i` and create a new `Some` value with our total `6` inside. Now let’s consider the second call of `plus_one` in Listing 6-5, where `x` is -`None`. We enter the `match` and compare to the first arm. - -``` -None => None, -``` +`None` [4]. We enter the `match` and compare to the first arm [1]. It matches! There’s no value to add to, so the program stops and returns the `None` value on the right side of `=>`. Because the first arm matched, no other @@ -704,26 +633,31 @@ a bug Rust knows how to catch. If we try to compile this code, we’ll get this error: ``` -$ cargo run - Compiling enums v0.1.0 (file:///projects/enums) error[E0004]: non-exhaustive patterns: `None` not covered - --> src/main.rs:3:15 + --> src/main.rs:3:15 + | +3 | match x { + | ^ pattern `None` not covered + | + note: `Option<i32>` defined here + = note: the matched value is of type `Option<i32>` +help: ensure that all possible cases are being handled by adding +a match arm with a wildcard pattern or an explicit pattern as +shown | -3 | match x { - | ^ pattern `None` not covered +4 ~ Some(i) => Some(i + 1), +5 ~ None => todo!(), | - = help: ensure that all possible cases are being handled, possibly by adding wildcards or more match arms - = note: the matched value is of type `Option<i32>` ``` -Rust knows that we didn’t cover every possible case and even knows which +Rust knows that we didn’t cover every possible case, and even knows which pattern we forgot! Matches in Rust are *exhaustive*: we must exhaust every last possibility in order for the code to be valid. Especially in the case of `Option<T>`, when Rust prevents us from forgetting to explicitly handle the `None` case, it protects us from assuming that we have a value when we might have null, thus making the billion-dollar mistake discussed earlier impossible. -### Catch-all Patterns and the `_` Placeholder +### Catch-all Patterns and the _ Placeholder Using enums, we can also take special actions for a few particular values, but for all other values take one default action. Imagine we’re implementing a game @@ -740,7 +674,7 @@ let dice_roll = 9; match dice_roll { 3 => add_fancy_hat(), 7 => remove_fancy_hat(), - other => move_player(other), + 1 other => move_player(other), } fn add_fancy_hat() {} @@ -748,10 +682,10 @@ fn remove_fancy_hat() {} fn move_player(num_spaces: u8) {} ``` -For the first two arms, the patterns are the literal values 3 and 7. For the -last arm that covers every other possible value, the pattern is the variable -we’ve chosen to name `other`. The code that runs for the `other` arm uses the -variable by passing it to the `move_player` function. +For the first two arms, the patterns are the literal values `3` and `7`. For +the last arm that covers every other possible value, the pattern is the +variable we’ve chosen to name `other` [1]. The code that runs for the `other` +arm uses the variable by passing it to the `move_player` function. This code compiles, even though we haven’t listed all the possible values a `u8` can have, because the last pattern will match all values not specifically @@ -785,10 +719,10 @@ fn reroll() {} This example also meets the exhaustiveness requirement because we’re explicitly ignoring all other values in the last arm; we haven’t forgotten anything. -Finally, we’ll change the rules of the game one more time, so that nothing else +Finally, we’ll change the rules of the game one more time so that nothing else happens on your turn if you roll anything other than a 3 or a 7. We can express that by using the unit value (the empty tuple type we mentioned in “The Tuple -Type†section) as the code that goes with the `_` arm: +Type†on page XX) as the code that goes with the `_` arm: ``` let dice_roll = 9; @@ -810,17 +744,18 @@ There’s more about patterns and matching that we’ll cover in Chapter 18. For now, we’re going to move on to the `if let` syntax, which can be useful in situations where the `match` expression is a bit wordy. -## Concise Control Flow with `if let` +## Concise Control Flow with if let The `if let` syntax lets you combine `if` and `let` into a less verbose way to handle values that match one pattern while ignoring the rest. Consider the -program in Listing 6-6 that matches on an `Option<u8>` value in the `config_max` -variable but only wants to execute code if the value is the `Some` variant. +program in Listing 6-6 that matches on an `Option<u8>` value in the +`config_max` variable but only wants to execute code if the value is the `Some` +variant. ``` let config_max = Some(3u8); match config_max { - Some(max) => println!("The maximum is configured to be {}", max), + Some(max) => println!("The maximum is configured to be {max}"), _ => (), } ``` @@ -840,7 +775,7 @@ code behaves the same as the `match` in Listing 6-6: ``` let config_max = Some(3u8); if let Some(max) = config_max { - println!("The maximum is configured to be {}", max); + println!("The maximum is configured to be {max}"); } ``` @@ -848,7 +783,7 @@ The syntax `if let` takes a pattern and an expression separated by an equal sign. It works the same way as a `match`, where the expression is given to the `match` and the pattern is its first arm. In this case, the pattern is `Some(max)`, and the `max` binds to the value inside the `Some`. We can then -use `max` in the body of the `if let` block in the same way as we used `max` in +use `max` in the body of the `if let` block in the same way we used `max` in the corresponding `match` arm. The code in the `if let` block isn’t run if the value doesn’t match the pattern. @@ -867,7 +802,7 @@ We can include an `else` with an `if let`. The block of code that goes with the `Coin` enum definition in Listing 6-4, where the `Quarter` variant also held a `UsState` value. If we wanted to count all non-quarter coins we see while also announcing the state of the quarters, we could do that with a `match` -expression like this: +expression, like this: ``` let mut count = 0; @@ -877,7 +812,7 @@ match coin { } ``` -Or we could use an `if let` and `else` expression like this: +Or we could use an `if let` and `else` expression, like this: ``` let mut count = 0; @@ -901,19 +836,10 @@ values, depending on how many cases you need to handle. Your Rust programs can now express concepts in your domain using structs and enums. Creating custom types to use in your API ensures type safety: the -compiler will make certain your functions get only values of the type each +compiler will make certain your functions only get values of the type each function expects. In order to provide a well-organized API to your users that is straightforward to use and only exposes exactly what your users will need, let’s now turn to Rust’s modules. -<!--- I'm of two minds whether `?` should squeeze in here? We talk about `if -let` but then switch topics next chapter and talk about modules. In the wild, -I'd bet `?` would be as common, perhaps more common, than `if let`. - -But I'll defer to your pedagogy plan. Just wanted to share the thought. -/JT ---> -<!-- Yeah introducing `?` here would be a big change; I don't want to talk -about that until we've talked about `Result` even though you can use `?` on -`Option` now, because `?` is still way more common with `Result`. /Carol --> diff --git a/src/doc/book/nostarch/chapter07.md b/src/doc/book/nostarch/chapter07.md index 32a9eb2fb..8b2dce777 100644 --- a/src/doc/book/nostarch/chapter07.md +++ b/src/doc/book/nostarch/chapter07.md @@ -20,7 +20,7 @@ optionally one library crate. As a package grows, you can extract parts into separate crates that become external dependencies. This chapter covers all these techniques. For very large projects comprising a set of interrelated packages that evolve together, Cargo provides *workspaces*, which we’ll cover -in the “Cargo Workspaces†section in Chapter 14. +in “Cargo Workspaces†on page XX. We’ll also discuss encapsulating implementation details, which lets you reuse code at a higher level: once you’ve implemented an operation, other code can @@ -43,11 +43,11 @@ organization, including which details are exposed, which details are private, and what names are in each scope in your programs. These features, sometimes collectively referred to as the *module system*, include: -* **Packages:** A Cargo feature that lets you build, test, and share crates -* **Crates:** A tree of modules that produces a library or executable -* **Modules** and **use:** Let you control the organization, scope, and - privacy of paths -* **Paths:** A way of naming an item, such as a struct, function, or module +* **Packages **: A Cargo feature that lets you build, test, and share crates +* **Crates**: A tree of modules that produces a library or executable +* **Modules and use**: Let you control the organization, scope, and privacy of +paths +* **Paths **: A way of naming an item, such as a struct, function, or module In this chapter, we’ll cover all these features, discuss how they interact, and explain how to use them to manage scope. By the end, you should have a solid @@ -57,37 +57,16 @@ understanding of the module system and be able to work with scopes like a pro! The first parts of the module system we’ll cover are packages and crates. -<!-- Do you have a general definition of a crate we can add, or is it too -dependent on whether it's a binary or library crate? /LC --> -<!-- I've struggled to come up with something that isn't just "smaller than a -package but bigger than a module"... "reusable" or "what you specify as a -dependency" only applies to library crates... this definition I've added here -gets a little bit into how the compiler sees crates, which might be too much -detail? What do you think about this next paragraph? /Carol --> -<!-- JT, what do you think? /LC --> -<!-- I think this works. - -Carol - I'm wondering a bit if "packages" above helps the reader build the -mental model or if it's kind of an implementation detail for cargo (we could -say we "package crates"). You're definitely the expert here, but I wonder if we -can simplify down to Crates/Modules/Paths and mention that we'll introduce some -of the techniques the tooling uses to work with these later. /JT --> -<!-- I feel like we need to explain the `[package]` section in *Cargo.toml*, -and explain what the container is when you have a library and one or more -binaries in one directory, and that's a package. It is a little weird because -people hardly ever talk in terms of packages, only in terms of crates, but I -think it's better to have the discussion of package here. /Carol --> - A *crate* is the smallest amount of code that the Rust compiler considers at a time. Even if you run `rustc` rather than `cargo` and pass a single source code -file (as we did all the way back in the “Writing and Running a Rust Program†-section of Chapter 1), the compiler considers that file to be a crate. Crates -can contain modules, and the modules may be defined in other files that get -compiled with the crate, as we’ll see in the coming sections. +file (as we did all the way back in “Writing and Running a Rust Program†on +page XX), the compiler considers that file to be a crate. Crates can contain +modules, and the modules may be defined in other files that get compiled with +the crate, as we’ll see in the coming sections. A crate can come in one of two forms: a binary crate or a library crate. *Binary crates* are programs you can compile to an executable that you can run, -such as a command-line program or a server. Each must have a function called +such as a command line program or a server. Each must have a function called `main` that defines what happens when the executable runs. All the crates we’ve created so far have been binary crates. @@ -95,27 +74,28 @@ created so far have been binary crates. executable. Instead, they define functionality intended to be shared with multiple projects. For example, the `rand` crate we used in Chapter 2 provides functionality that generates random numbers. Most of the time when Rustaceans -say “crateâ€, they mean library crate, and they use “crate†interchangeably with -the general programming concept of a “library". +say “crate,†they mean library crate, and they use “crate†interchangeably with +the general programming concept of a “library.†The *crate root* is a source file that the Rust compiler starts from and makes -up the root module of your crate (we’ll explain modules in depth in the -“Defining Modules to Control Scope and Privacy†section). +up the root module of your crate (we’ll explain modules in depth in “Defining +Modules to Control Scope and Privacy†on page XX). A *package* is a bundle of one or more crates that provides a set of functionality. A package contains a *Cargo.toml* file that describes how to build those crates. Cargo is actually a package that contains the binary crate -for the command-line tool you’ve been using to build your code. The Cargo +for the command line tool you’ve been using to build your code. The Cargo package also contains a library crate that the binary crate depends on. Other projects can depend on the Cargo library crate to use the same logic the Cargo -command-line tool uses. +command line tool uses. -A package can contain as many binary crates as you like, but at most only one +A crate can come in one of two forms: a binary crate or a library crate. A +package can contain as many binary crates as you like, but at most only one library crate. A package must contain at least one crate, whether that’s a library or binary crate. -Let’s walk through what happens when we create a package. First, we enter the -command `cargo new`: +Let’s walk through what happens when we create a package. First we enter the +command `cargo new my-project`: ``` $ cargo new my-project @@ -127,19 +107,15 @@ $ ls my-project/src main.rs ``` -<!-- I can't remember if we warned folks we were going to use unix commands. May -want to throw in the Windows command here too, so they feel welcome. /JT --> -<!-- I don't think JT has seen chapter 1 yet, we address that there /Carol --> - -After we run `cargo new`, we use `ls` to see what Cargo creates. In the project -directory, there’s a *Cargo.toml* file, giving us a package. There’s also a -*src* directory that contains *main.rs*. Open *Cargo.toml* in your text editor, -and note there’s no mention of *src/main.rs*. Cargo follows a convention that -*src/main.rs* is the crate root of a binary crate with the same name as the -package. Likewise, Cargo knows that if the package directory contains -*src/lib.rs*, the package contains a library crate with the same name as the -package, and *src/lib.rs* is its crate root. Cargo passes the crate root files -to `rustc` to build the library or binary. +After we run `cargo new my-project`, we use `ls` to see what Cargo creates. In +the project directory, there’s a *Cargo.toml* file, giving us a package. +There’s also a *src* directory that contains *main.rs*. Open *Cargo.toml* in +your text editor, and note there’s no mention of *src/main.rs*. Cargo follows a +convention that *src/main.rs* is the crate root of a binary crate with the same +name as the package. Likewise, Cargo knows that if the package directory +contains *src/lib.rs*, the package contains a library crate with the same name +as the package, and *src/lib.rs* is its crate root. Cargo passes the crate root +files to `rustc` to build the library or binary. Here, we have a package that only contains *src/main.rs*, meaning it only contains a binary crate named `my-project`. If a package contains *src/main.rs* @@ -147,154 +123,103 @@ and *src/lib.rs*, it has two crates: a binary and a library, both with the same name as the package. A package can have multiple binary crates by placing files in the *src/bin* directory: each file will be a separate binary crate. -## Defining Modules to Control Scope and Privacy - -In this section, we’ll talk about modules and other parts of the module system, -namely *paths* that allow you to name items; the `use` keyword that brings a -path into scope; and the `pub` keyword to make items public. We’ll also discuss -the `as` keyword, external packages, and the glob operator. - -First, we’re going to start with a list of rules for easy reference when you’re -organizing your code in the future. Then we’ll explain each of the rules in -detail. - -### Modules Cheat Sheet - -<!--WHEN TRANSFERRED TO WORD, DECIDE ON BOX OR NOT --> - -Here we provide a quick reference on how modules, paths, the `use` keyword, and -the `pub` keyword work in the compiler, and how most developers organize their -code. We’ll be going through examples of each of these rules throughout this -chapter, but this is a great place to refer to as a reminder of how modules -work. - -- **Start from the crate root**: When compiling a crate, the compiler first - looks in the crate root file (usually *src/lib.rs* for a library crate or - *src/main.rs* for a binary crate) for code to compile. - <!-- I may be asking a silly question here... but what is the compiler looking - for in the crate root file? just things to start compiling? /LC --> - <!-- That's exactly it-- it's the starting point of compilation, and the - compiler will only find files if they're connected to the crate root somehow. - Do you think that should be mentioned here? Is there something about this - explanation that would make you feel more confident about the concept? /Carol - --> - <!-- I've added "for things to compile" -- I wanted to make sure the reader - knew they weren't missing anything, that there wasn't a particular thing - being looked for that the reader wasn't aware of /LC --> - <!-- I changed "things" to "code" to be more precise /Carol --> -- **Declaring modules**: In the crate root file, you can declare new modules; -say, you declare a “garden†module with `mod garden;`. The compiler will look +> ### Modules Cheat Sheet +> +> Before we get to the details of modules and paths, here we provide a quick +reference on how modules, paths, the `use` keyword, and the `pub` keyword work +in the compiler, and how most developers organize their code. We’ll be going +through examples of each of these rules throughout this chapter, but this is a +great place to refer to as a reminder of how modules work. +> +> * **Start from the crate root**: When compiling a crate, the compiler first +looks in the crate root file (usually *src/lib.rs* for a library crate or +*src/main.rs* for a binary crate) for code to compile. +> * **Declaring modules**: In the crate root file, you can declare new modules; +say you declare a “garden†module with `mod garden;`. The compiler will look for the module’s code in these places: - - - Inline, within curly brackets that replace the semicolon following `mod - garden` - <!-- instead of or after the semicolon? Or is all of this instead of a - semicolon? /LC --> - <!-- Curly brackets and everything within them instead of the semicolon. - I'm not sure a pithy way to make that distinction clearer? /Carol --> - <!-- JT, would "Inline, within curly brackets that replace the semicolon - following `mod garden` be clearer/accurate? /LC --> - <!-- I wonder if we should order it where this cheatsheet happens after - we show more examples. Most of the time, you'll use the `mod` keyword to - pull files in as you refactor out into separate files. Sometimes you'll use - it for those key cases, like grouping tests. Showing those examples and then - going into the resolution may be a bit easier. - - To your question - I think of this as something that could be more of - a warning. If you want to use `mod foo`, then be sure you haven't already - declared a module called that in the current file. If you do, the compiler - will see it first before it looks for a file with that name. /JT --> - <!-- I feel pretty strongly that the cheat sheet needs to go first, so that - after a reader's first time through the book, when they go back to the - modules chapter to try and figure out why their modules aren't working, - they get this first rather than having to read through or skip through the - examples when they're already frustrated. - - I also don't feel like the "warning" way of talking about this belongs - here. I almost added a section called "common mistakes" or "pitfalls" or - "troubleshooting", and I think talking about what you *don't* want to do - would belong there... - - Liz, I'm fine with your suggested wording and I've made that change. /Carol - --> - - - In the file *src/garden.rs* - - In the file *src/garden/mod.rs* -- **Declaring submodules**: In any file other than the crate root, you can - declare submodules. For example, you might declare `mod vegetables;` in - *src/garden.rs*. The compiler will look for the submodule’s code within the - directory named for the parent module in these places: - - Inline, directly following `mod vegetables`, within curly brackets instead - of the semicolon - - In the file *src/garden/vegetables.rs* - - In the file *src/garden/vegetables/mod.rs* -- **Paths to code in modules**: Once a module is part of your crate, you can - refer to code in that module from anywhere else in that same crate, as long - as the privacy rules allow, using the path to the code. For example, an - `Asparagus` type in the garden vegetables module would be found at - `crate::garden::vegetables::Asparagus`. -- **Private vs public**: Code within a module is private from its parent - modules by default. To make a module public, declare it with `pub mod` - instead of `mod`. To make items within a public module public as well, use - `pub` before their declarations. -- **The `use` keyword**: Within a scope, the `use` keyword creates shortcuts to - items to reduce repetition of long paths. In any scope that can refer to - `crate::garden::vegetables::Asparagus`, you can create a shortcut with `use - crate::garden::vegetables::Asparagus;` and from then on you only need to - write `Asparagus` to make use of that type in the scope. - -Here we create a binary crate named `backyard` that illustrates these rules. The -crate’s directory, also named `backyard`, contains these files and directories: - -``` -backyard -├── Cargo.lock -├── Cargo.toml -└── src - ├── garden - │  └── vegetables.rs - ├── garden.rs - └── main.rs -``` - -The crate root file in this case is *src/main.rs*, and it contains: - -Filename: src/main.rs - -``` -use crate::garden::vegetables::Asparagus; - -pub mod garden; - -fn main() { - let plant = Asparagus {}; - println!("I'm growing {:?}!", plant); -} -``` - -The `pub mod garden;` line tells the compiler to include the code it finds in +> +> * Inline, within curly brackets that replace the semicolon following `mod +garden` +> * In the file *src/garden.rs.* +> * In the file *src/garden/mod.rs* +> * **Declaring submodules**: In any file other than the crate root, you can +declare submodules. For example, you might declare `mod vegetables;` in +*src/garden.rs*. The compiler will look for the submodule’s code within the +directory named for the parent module in these places: +> +> * Inline, directly following `mod vegetables`, within curly brackets instead +of the semicolon +> * In the file *src/garden/vegetables.rs* +> * In the file *src/garden/vegetables/mod.rs* +> * **Paths to code in modules**: Once a module is part of your crate, you can +refer to code in that module from anywhere else in that same crate, as long as +the privacy rules allow, using the path to the code. For example, an +`Asparagus` type in the garden vegetables module would be found at +`crate::garden::vegetables::Asparagus`. +> * **Private vs. public**: Code within a module is private from its parent +modules by default. To make a module public, declare it with `pub mod` instead +of `mod`. To make items within a public module public as well, use `pub` before +their declarations. +> * **The use keyword**: Within a scope, the `use` keyword creates shortcuts to +items to reduce repetition of long paths. In any scope that can refer to +`crate::garden::vegetables::Asparagus`, you can create a shortcut with `use +crate::garden::vegetables::Asparagus;` and from then on you only need to write +`Asparagus` to make use of that type in the scope. +> +> Here, we create a binary crate named `backyard` that illustrates these rules. +The crate’s directory, also named `backyard`, contains these files and +directories: +> +> ``` +> backyard +> ├── Cargo.lock +> ├── Cargo.toml +> └── src +> ├── garden +> │ └── vegetables.rs +> ├── garden.rs +> └── main.rs +> ``` +> +> The crate root file in this case is *src/main.rs*, and it contains: +> +> ``` +> use crate::garden::vegetables::Asparagus; +> +> pub mod garden; +> +> fn main() { +> let plant = Asparagus {}; +> println!("I'm growing {:?}!", plant); +> } +> ``` +> +> The `pub mod garden;` line tells the compiler to include the code it finds in *src/garden.rs*, which is: - -Filename: src/garden.rs - -``` -pub mod vegetables; -``` - -Here, `pub mod vegetables;` means the code in *src/garden/vegetables.rs* is +> +> ``` +> pub mod vegetables; +> ``` +> +> Here, `pub mod vegetables;` means the code in *src/garden/vegetables.rs* is included too. That code is: +> +> ``` +> #[derive(Debug)] +> pub struct Asparagus {} +> ``` +> +> Now let’s get into the details of these rules and demonstrate them in action! -``` -#[derive(Debug)] -pub struct Asparagus {} -``` - -Now let’s get into the details of these rules and demonstrate them in action! +## Defining Modules to Control Scope and Privacy -### Grouping Related Code in Modules +In this section, we’ll talk about modules and other parts of the module system, +namely *paths*, which allow you to name items; the `use` keyword that brings a +path into scope; and the `pub` keyword to make items public. We’ll also discuss +the `as` keyword, external packages, and the glob operator. *Modules* let us organize code within a crate for readability and easy reuse. -Modules also allow us to control the *privacy* of items, because code within a +Modules also allow us to control the *privacy* of items because code within a module is private by default. Private items are internal implementation details not available for outside use. We can choose to make modules and the items within them public, which exposes them to allow external code to use and depend @@ -302,7 +227,7 @@ on them. As an example, let’s write a library crate that provides the functionality of a restaurant. We’ll define the signatures of functions but leave their bodies -empty to concentrate on the organization of the code, rather than the +empty to concentrate on the organization of the code rather than the implementation of a restaurant. In the restaurant industry, some parts of a restaurant are referred to as @@ -313,9 +238,10 @@ chefs and cooks work in the kitchen, dishwashers clean up, and managers do administrative work. To structure our crate in this way, we can organize its functions into nested -modules. Create a new library named `restaurant` by running `cargo new --lib -restaurant`; then enter the code in Listing 7-1 into *src/lib.rs* to define -some modules and function signatures. Here’s the front of house section: +modules. Create a new library named `restaurant` by running `cargo new +restaurant --lib`. Then enter the code in Listing 7-1 into *src/lib.rs* to +define some modules and function signatures; this code is the front of house +section. Filename: src/lib.rs @@ -374,13 +300,13 @@ crate Listing 7-2: The module tree for the code in Listing 7-1 -This tree shows how some of the modules nest inside one another; for example, +This tree shows how some of the modules nest inside other modules; for example, `hosting` nests inside `front_of_house`. The tree also shows that some modules -are *siblings* to each other, meaning they’re defined in the same module; -`hosting` and `serving` are siblings defined within `front_of_house`. If module -A is contained inside module B, we say that module A is the *child* of module B -and that module B is the *parent* of module A. Notice that the entire module -tree is rooted under the implicit module named `crate`. +are *siblings*, meaning they’re defined in the same module; `hosting` and +`serving` are siblings defined within `front_of_house`. If module A is +contained inside module B, we say that module A is the *child* of module B and +that module B is the *parent* of module A. Notice that the entire module tree +is rooted under the implicit module named `crate`. The module tree might remind you of the filesystem’s directory tree on your computer; this is a very apt comparison! Just like directories in a filesystem, @@ -395,28 +321,27 @@ know its path. A path can take two forms: -* An *absolute path* is the full path starting from a crate root; for code - from an external crate, the absolute path begins with the crate name, and for - code from the current crate, it starts with the literal `crate`. +* An *absolute path* is the full path starting from a crate root; for code from +an external crate, the absolute path begins with the crate name, and for code +from the current crate, it starts with the literal `crate`. * A *relative path* starts from the current module and uses `self`, `super`, or - an identifier in the current module. +an identifier in the current module. Both absolute and relative paths are followed by one or more identifiers separated by double colons (`::`). Returning to Listing 7-1, say we want to call the `add_to_waitlist` function. This is the same as asking: what’s the path of the `add_to_waitlist` function? -Listing 7-3 contains Listing 7-1 with some of the modules and functions -removed. +Listing 7-3 contains Listing 7-1 with some of the modules and functions removed. -We’ll show two ways to call the `add_to_waitlist` function from a new function -`eat_at_restaurant` defined in the crate root. These paths are correct, but +We’ll show two ways to call the `add_to_waitlist` function from a new function, +`eat_at_restaurant`, defined in the crate root. These paths are correct, but there’s another problem remaining that will prevent this example from compiling -as-is. We’ll explain why in a bit. +as is. We’ll explain why in a bit. The `eat_at_restaurant` function is part of our library crate’s public API, so -we mark it with the `pub` keyword. In the “Exposing Paths with the `pub` -Keyword†section, we’ll go into more detail about `pub`. +we mark it with the `pub` keyword. In “Exposing Paths with the pub Keyword†on +page XX, we’ll go into more detail about `pub`. Filename: src/lib.rs @@ -436,10 +361,6 @@ pub fn eat_at_restaurant() { } ``` -<!-- We should probably let the reader know the above is expected to fail a -little earlier. /JT --> -<!-- I've rearranged a bit /Carol --> - Listing 7-3: Calling the `add_to_waitlist` function using absolute and relative paths @@ -460,20 +381,20 @@ filesystem equivalent would be using the path that the path is relative. Choosing whether to use a relative or absolute path is a decision you’ll make -based on your project, and depends on whether you’re more likely to move item -definition code separately from or together with the code that uses the item. -For example, if we move the `front_of_house` module and the `eat_at_restaurant` -function into a module named `customer_experience`, we’d need to update the -absolute path to `add_to_waitlist`, but the relative path would still be valid. -However, if we moved the `eat_at_restaurant` function separately into a module -named `dining`, the absolute path to the `add_to_waitlist` call would stay the -same, but the relative path would need to be updated. - -Our preference in general is to specify absolute paths because it’s more likely -we’ll want to move code definitions and item calls independently of each other. +based on your project, and it depends on whether you’re more likely to move +item definition code separately from or together with the code that uses the +item. For example, if we moved the `front_of_house` module and the +`eat_at_restaurant` function into a module named `customer_experience`, we’d +need to update the absolute path to `add_to_waitlist`, but the relative path +would still be valid. However, if we moved the `eat_at_restaurant` function +separately into a module named `dining`, the absolute path to the +`add_to_waitlist` call would stay the same, but the relative path would need to +be updated. Our preference in general is to specify absolute paths because it’s +more likely we’ll want to move code definitions and item calls independently of +each other. Let’s try to compile Listing 7-3 and find out why it won’t compile yet! The -error we get is shown in Listing 7-4. +errors we get are shown in Listing 7-4. ``` $ cargo build @@ -526,7 +447,7 @@ inner code you can change without breaking outer code. However, Rust does give you the option to expose inner parts of child modules’ code to outer ancestor modules by using the `pub` keyword to make an item public. -### Exposing Paths with the `pub` Keyword +### Exposing Paths with the pub Keyword Let’s return to the error in Listing 7-4 that told us the `hosting` module is private. We want the `eat_at_restaurant` function in the parent module to have @@ -542,20 +463,14 @@ mod front_of_house { } } -pub fn eat_at_restaurant() { - // Absolute path - crate::front_of_house::hosting::add_to_waitlist(); - - // Relative path - front_of_house::hosting::add_to_waitlist(); -} +--snip-- ``` Listing 7-5: Declaring the `hosting` module as `pub` to use it from `eat_at_restaurant` -Unfortunately, the code in Listing 7-5 still results in an error, as shown in -Listing 7-6. +Unfortunately, the code in Listing 7-5 still results in compiler errors, as +shown in Listing 7-6. ``` $ cargo build @@ -612,17 +527,11 @@ mod front_of_house { } } -pub fn eat_at_restaurant() { - // Absolute path - crate::front_of_house::hosting::add_to_waitlist(); - - // Relative path - front_of_house::hosting::add_to_waitlist(); -} +--snip-- ``` Listing 7-7: Adding the `pub` keyword to `mod hosting` and `fn add_to_waitlist` -lets us call the function from `eat_at_restaurant` +lets us call the function from `eat_at_restaurant`. Now the code will compile! To see why adding the `pub` keyword lets us use these paths in `add_to_waitlist` with respect to the privacy rules, let’s look @@ -650,48 +559,45 @@ If you plan on sharing your library crate so other projects can use your code, your public API is your contract with users of your crate that determines how they can interact with your code. There are many considerations around managing changes to your public API to make it easier for people to depend on your -crate. These considerations are out of the scope of this book; if you’re -interested in this topic, see The Rust API Guidelines at -*https://rust-lang.github.io/api-guidelines/*. - +crate. These considerations are beyond the scope of this book; if you’re +interested in this topic, see the Rust API Guidelines at +*https://rust-lang.github.io/api-guidelines*. -> #### Best Practices for Packages with a Binary and a Library +> ### Best Practices for Packages with a Binary and a Library > -> We mentioned a package can contain both a *src/main.rs* binary crate root as -> well as a *src/lib.rs* library crate root, and both crates will have the -> package name by default. Typically, packages with this pattern of containing -> both a library and a binary crate will have just -> enough code in the binary crate to start an executable that calls code with -> the library crate. This lets other projects benefit from the most -> functionality that the package provides, because the library crate’s code can -> be shared. +> We mentioned that a package can contain both a *src/main.rs* binary crate +root as well as a *src/lib.rs* library crate root, and both crates will have +the package name by default. Typically, packages with this pattern of +containing both a library and a binary crate will have just enough code in the +binary crate to start an executable that calls code with the library crate. +This lets other projects benefit from the most functionality that the package +provides because the library crate’s code can be shared. > > The module tree should be defined in *src/lib.rs*. Then, any public items can -> be used in the binary crate by starting paths with the name of the package. -> The binary crate becomes a user of the library crate just like a completely -> external crate would use the library crate: it can only use the public API. -> This helps you design a good API; not only are you the author, you’re also a -> client! +be used in the binary crate by starting paths with the name of the package. The +binary crate becomes a user of the library crate just like a completely +external crate would use the library crate: it can only use the public API. +This helps you design a good API; not only are you the author, you’re also a +client! > -> In Chapter 12, we’ll demonstrate this organizational practice with a -> command-line program that will contain both a binary crate and a library -> crate. +> In Chapter 12, we’ll demonstrate this organizational practice with a command +line program that will contain both a binary crate and a library crate. -### Starting Relative Paths with `super` +### Starting Relative Paths with super We can construct relative paths that begin in the parent module, rather than the current module or the crate root, by using `super` at the start of the path. This is like starting a filesystem path with the `..` syntax. Using `super` allows us to reference an item that we know is in the parent module, which can make rearranging the module tree easier when the module is closely -related to the parent, but the parent might be moved elsewhere in the module +related to the parent but the parent might be moved elsewhere in the module tree someday. Consider the code in Listing 7-8 that models the situation in which a chef fixes an incorrect order and personally brings it out to the customer. The function `fix_incorrect_order` defined in the `back_of_house` module calls the function `deliver_order` defined in the parent module by specifying the path to -`deliver_order` starting with `super`: +`deliver_order`, starting with `super`. Filename: src/lib.rs @@ -722,7 +628,7 @@ code gets moved to a different module. ### Making Structs and Enums Public We can also use `pub` to designate structs and enums as public, but there are a -few details extra to the usage of `pub` with structs and enums. If we use `pub` +few extra details to the usage of `pub` with structs and enums. If we use `pub` before a struct definition, we make the struct public, but the struct’s fields will still be private. We can make each field public or not on a case-by-case basis. In Listing 7-9, we’ve defined a public `back_of_house::Breakfast` struct @@ -758,8 +664,9 @@ pub fn eat_at_restaurant() { meal.toast = String::from("Wheat"); println!("I'd like {} toast please", meal.toast); - // The next line won't compile if we uncomment it; we're not allowed - // to see or modify the seasonal fruit that comes with the meal + // The next line won't compile if we uncomment it; we're not + // allowed to see or modify the seasonal fruit that comes + // with the meal // meal.seasonal_fruit = String::from("blueberries"); } ``` @@ -769,7 +676,7 @@ Listing 7-9: A struct with some public fields and some private fields Because the `toast` field in the `back_of_house::Breakfast` struct is public, in `eat_at_restaurant` we can write and read to the `toast` field using dot notation. Notice that we can’t use the `seasonal_fruit` field in -`eat_at_restaurant` because `seasonal_fruit` is private. Try uncommenting the +`eat_at_restaurant`, because `seasonal_fruit` is private. Try uncommenting the line modifying the `seasonal_fruit` field value to see what error you get! Also, note that because `back_of_house::Breakfast` has a private field, the @@ -798,7 +705,7 @@ pub fn eat_at_restaurant() { } ``` -Listing 7-10: Designating an enum as public makes all its variants public +Listing 7-10: Designating an enum as public makes all its variants public. Because we made the `Appetizer` enum public, we can use the `Soup` and `Salad` variants in `eat_at_restaurant`. @@ -813,7 +720,7 @@ There’s one more situation involving `pub` that we haven’t covered, and that our last module system feature: the `use` keyword. We’ll cover `use` by itself first, and then we’ll show how to combine `pub` and `use`. -## Bringing Paths into Scope with the `use` Keyword +## Bringing Paths into Scope with the use Keyword Having to write out the paths to call functions can feel inconvenient and repetitive. In Listing 7-7, whether we chose the absolute or relative path to @@ -854,7 +761,7 @@ also check privacy, like any other paths. Note that `use` only creates the shortcut for the particular scope in which the `use` occurs. Listing 7-12 moves the `eat_at_restaurant` function into a new child module named `customer`, which is then a different scope than the `use` -statement, so the function body won’t compile: +statement, so the function body won’t compile. Filename: src/lib.rs @@ -874,7 +781,7 @@ mod customer { } ``` -Listing 7-12: A `use` statement only applies in the scope it’s in +Listing 7-12: A `use` statement only applies in the scope it’s in. The compiler error shows that the shortcut no longer applies within the `customer` module: @@ -900,11 +807,11 @@ fix this problem, move the `use` within the `customer` module too, or reference the shortcut in the parent module with `super::hosting` within the child `customer` module. -### Creating Idiomatic `use` Paths +### Creating Idiomatic use Paths In Listing 7-11, you might have wondered why we specified `use crate::front_of_house::hosting` and then called `hosting::add_to_waitlist` in -`eat_at_restaurant` rather than specifying the `use` path all the way out to +`eat_at_restaurant`, rather than specifying the `use` path all the way out to the `add_to_waitlist` function to achieve the same result, as in Listing 7-13. Filename: src/lib.rs @@ -926,9 +833,9 @@ pub fn eat_at_restaurant() { Listing 7-13: Bringing the `add_to_waitlist` function into scope with `use`, which is unidiomatic -Although both Listing 7-11 and 7-13 accomplish the same task, Listing 7-11 is -the idiomatic way to bring a function into scope with `use`. Bringing the -function’s parent module into scope with `use` means we have to specify the +Although both Listing 7-11 and Listing 7-13 accomplish the same task, Listing +7-11 is the idiomatic way to bring a function into scope with `use`. Bringing +the function’s parent module into scope with `use` means we have to specify the parent module when calling the function. Specifying the parent module when calling the function makes it clear that the function isn’t locally defined while still minimizing repetition of the full path. The code in Listing 7-13 is @@ -958,7 +865,7 @@ emerged, and folks have gotten used to reading and writing Rust code this way. The exception to this idiom is if we’re bringing two items with the same name into scope with `use` statements, because Rust doesn’t allow that. Listing 7-15 shows how to bring two `Result` types into scope that have the same name but -different parent modules and how to refer to them. +different parent modules, and how to refer to them. Filename: src/lib.rs @@ -967,11 +874,11 @@ use std::fmt; use std::io; fn function1() -> fmt::Result { - // --snip-- + --snip-- } fn function2() -> io::Result<()> { - // --snip-- + --snip-- } ``` @@ -980,10 +887,10 @@ requires using their parent modules. As you can see, using the parent modules distinguishes the two `Result` types. If instead we specified `use std::fmt::Result` and `use std::io::Result`, we’d -have two `Result` types in the same scope and Rust wouldn’t know which one we +have two `Result` types in the same scope, and Rust wouldn’t know which one we meant when we used `Result`. -### Providing New Names with the `as` Keyword +### Providing New Names with the as Keyword There’s another solution to the problem of bringing two types of the same name into the same scope with `use`: after the path, we can specify `as` and a new @@ -997,11 +904,11 @@ use std::fmt::Result; use std::io::Result as IoResult; fn function1() -> Result { - // --snip-- + --snip-- } fn function2() -> IoResult<()> { - // --snip-- + --snip-- } ``` @@ -1012,13 +919,13 @@ In the second `use` statement, we chose the new name `IoResult` for the that we’ve also brought into scope. Listing 7-15 and Listing 7-16 are considered idiomatic, so the choice is up to you! -### Re-exporting Names with `pub use` +### Re-exporting Names with pub use When we bring a name into scope with the `use` keyword, the name available in the new scope is private. To enable the code that calls our code to refer to that name as if it had been defined in that code’s scope, we can combine `pub` -and `use`. This technique is called *re-exporting* because we’re bringing -an item into scope but also making that item available for others to bring into +and `use`. This technique is called *re-exporting* because we’re bringing an +item into scope but also making that item available for others to bring into their scope. Listing 7-17 shows the code in Listing 7-11 with `use` in the root module @@ -1047,7 +954,7 @@ Before this change, external code would have to call the `add_to_waitlist` function by using the path `restaurant::front_of_house::hosting::add_to_waitlist()`. Now that this `pub use` has re-exported the `hosting` module from the root module, external code -can now use the path `restaurant::hosting::add_to_waitlist()` instead. +can use the path `restaurant::hosting::add_to_waitlist()` instead. Re-exporting is useful when the internal structure of your code is different from how programmers calling your code would think about the domain. For @@ -1057,8 +964,8 @@ probably won’t think about the parts of the restaurant in those terms. With `pub use`, we can write our code with one structure but expose a different structure. Doing so makes our library well organized for programmers working on the library and programmers calling the library. We’ll look at another example -of `pub use` and how it affects your crate’s documentation in the “Exporting a -Convenient Public API with `pub use`†section of Chapter 14. +of `pub use` and how it affects your crate’s documentation in “Exporting a +Convenient Public API with pub use†on page XX. ### Using External Packages @@ -1069,29 +976,29 @@ added this line to *Cargo.toml*: Filename: Cargo.toml ``` -rand = "0.8.3" +rand = "0.8.5" ``` Adding `rand` as a dependency in *Cargo.toml* tells Cargo to download the -`rand` package and any dependencies from *https://crates.io/* and make `rand` +`rand` package and any dependencies from *https://crates.io*, and make `rand` available to our project. Then, to bring `rand` definitions into the scope of our package, we added a `use` line starting with the name of the crate, `rand`, and listed the items we -wanted to bring into scope. Recall that in the “Generating a Random Number†-section in Chapter 2, we brought the `Rng` trait into scope and called the -`rand::thread_rng` function: +wanted to bring into scope. Recall that in “Generating a Random Number†on page +XX, we brought the `Rng` trait into scope and called the `rand::thread_rng` +function: ``` use rand::Rng; fn main() { - let secret_number = rand::thread_rng().gen_range(1..101); + let secret_number = rand::thread_rng().gen_range(1..=100); } ``` Members of the Rust community have made many packages available at -*https://crates.io/*, and pulling any of them into your package involves these +*https://crates.io*, and pulling any of them into your package involves these same steps: listing them in your package’s *Cargo.toml* file and using `use` to bring items from their crates into scope. @@ -1108,20 +1015,20 @@ use std::collections::HashMap; This is an absolute path starting with `std`, the name of the standard library crate. -### Using Nested Paths to Clean Up Large `use` Lists +### Using Nested Paths to Clean Up Large use Lists -If we’re using multiple items defined in the same crate or same module, -listing each item on its own line can take up a lot of vertical space in our -files. For example, these two `use` statements we had in the Guessing Game in -Listing 2-4 bring items from `std` into scope: +If we’re using multiple items defined in the same crate or same module, listing +each item on its own line can take up a lot of vertical space in our files. For +example, these two `use` statements we had in the guessing game in Listing 2-4 +bring items from `std` into scope: Filename: src/main.rs ``` -// --snip-- +--snip-- use std::cmp::Ordering; use std::io; -// --snip-- +--snip-- ``` Instead, we can use nested paths to bring the same items into scope in one @@ -1132,9 +1039,9 @@ differ, as shown in Listing 7-18. Filename: src/main.rs ``` -// --snip-- +--snip-- use std::{cmp::Ordering, io}; -// --snip-- +--snip-- ``` Listing 7-18: Specifying a nested path to bring multiple items with the same @@ -1187,10 +1094,9 @@ harder to tell what names are in scope and where a name used in your program was defined. The glob operator is often used when testing to bring everything under test -into the `tests` module; we’ll talk about that in the “How to Write Tests†-section in Chapter 11. The glob operator is also sometimes used as part of the -prelude pattern: see the standard library documentation for more information on -that pattern. +into the `tests` module; we’ll talk about that in “How to Write Tests†on page +XX. The glob operator is also sometimes used as part of the prelude pattern: +see the standard library documentation for more information on that pattern. ## Separating Modules into Different Files @@ -1204,7 +1110,7 @@ modules defined in the crate root file. In this case, the crate root file is *src/lib.rs*, but this procedure also works with binary crates whose crate root file is *src/main.rs*. -First, we’ll extract the `front_of_house` module to its own file. Remove the +First we’ll extract the `front_of_house` module to its own file. Remove the code inside the curly brackets for the `front_of_house` module, leaving only the `mod front_of_house;` declaration, so that *src/lib.rs* contains the code shown in Listing 7-21. Note that this won’t compile until we create the @@ -1245,18 +1151,17 @@ Note that you only need to load a file using a `mod` declaration *once* in your module tree. Once the compiler knows the file is part of the project (and knows where in the module tree the code resides because of where you’ve put the `mod` statement), other files in your project should refer to the loaded file’s code -using a path to where it was declared, as covered in the “Paths for Referring -to an Item in the Module Tree†section. In other words, `mod` is *not* an +using a path to where it was declared, as covered in “Paths for Referring to an +Item in the Module Tree†on page XX. In other words, `mod` is *not* an “include†operation that you may have seen in other programming languages. -Next, we’ll extract the `hosting` module to its own file. The process -is a bit different because `hosting` is a child module of `front_of_house`, not -of the root module. We’ll place the file for `hosting` in a new directory that -will be named for its ancestors in the module tree, in this case -*src/front_of_house/*. +Next, we’ll extract the `hosting` module to its own file. The process is a bit +different because `hosting` is a child module of `front_of_house`, not of the +root module. We’ll place the file for `hosting` in a new directory that will be +named for its ancestors in the module tree, in this case *src/front_of_house*. -To start moving `hosting`, we change *src/front_of_house.rs* to contain only the -declaration of the `hosting` module: +To start moving `hosting`, we change *src/front_of_house.rs* to contain only +the declaration of the `hosting` module: Filename: src/front_of_house.rs @@ -1264,7 +1169,7 @@ Filename: src/front_of_house.rs pub mod hosting; ``` -Then we create a *src/front_of_house* directory and a file *hosting.rs* to +Then we create a *src/front_of_house* directory and a *hosting.rs* file to contain the definitions made in the `hosting` module: Filename: src/front_of_house/hosting.rs @@ -1275,34 +1180,33 @@ pub fn add_to_waitlist() {} If we instead put *hosting.rs* in the *src* directory, the compiler would expect the *hosting.rs* code to be in a `hosting` module declared in the crate -root, and not delcared as a child of the `front_of_house` module. The -compiler’s rules for which files to check for which modules’ code means the +root, and not declared as a child of the `front_of_house` module. The +compiler’s rules for which files to check for which modules’ code mean the directories and files more closely match the module tree. - > ### Alternate File Paths > > So far we’ve covered the most idiomatic file paths the Rust compiler uses, -> but Rust also supports an older style of file path. For a module named -> `front_of_house` declared in the crate root, the compiler will look for the -> module’s code in: +but Rust also supports an older style of file path. For a module named +`front_of_house` declared in the crate root, the compiler will look for the +module’s code in: > > * *src/front_of_house.rs* (what we covered) > * *src/front_of_house/mod.rs* (older style, still supported path) > > For a module named `hosting` that is a submodule of `front_of_house`, the -> compiler will look for the module’s code in: +compiler will look for the module’s code in: > > * *src/front_of_house/hosting.rs* (what we covered) > * *src/front_of_house/hosting/mod.rs* (older style, still supported path) > -> If you use both styles for the same module, you’ll get a compiler error. Using -> a mix of both styles for different modules in the same project is allowed, but -> might be confusing for people navigating your project. +> If you use both styles for the same module, you’ll get a compiler error. +Using a mix of both styles for different modules in the same project is +allowed, but might be confusing for people navigating your project. > > The main downside to the style that uses files named *mod.rs* is that your -> project can end up with many files named *mod.rs*, which can get confusing -> when you have them open in your editor at the same time. +project can end up with many files named *mod.rs*, which can get confusing when +you have them open in your editor at the same time. We’ve moved each module’s code to a separate file, and the module tree remains the same. The function calls in `eat_at_restaurant` will work without any @@ -1317,8 +1221,8 @@ that module. ## Summary -Rust lets you split a package into multiple crates and a crate into modules -so you can refer to items defined in one module from another module. You can do +Rust lets you split a package into multiple crates and a crate into modules so +you can refer to items defined in one module from another module. You can do this by specifying absolute or relative paths. These paths can be brought into scope with a `use` statement so you can use a shorter path for multiple uses of the item in that scope. Module code is private by default, but you can make @@ -1326,3 +1230,4 @@ definitions public by adding the `pub` keyword. In the next chapter, we’ll look at some collection data structures in the standard library that you can use in your neatly organized code. + diff --git a/src/doc/book/nostarch/chapter08.md b/src/doc/book/nostarch/chapter08.md index 1c7968c99..c44ebd8f7 100644 --- a/src/doc/book/nostarch/chapter08.md +++ b/src/doc/book/nostarch/chapter08.md @@ -20,9 +20,9 @@ collections that are used very often in Rust programs: * A *vector* allows you to store a variable number of values next to each other. * A *string* is a collection of characters. We’ve mentioned the `String` type - previously, but in this chapter we’ll talk about it in depth. -* A *hash map* allows you to associate a value with a particular key. It’s a - particular implementation of the more general data structure called a *map*. +previously, but in this chapter we’ll talk about it in depth. +* A *hash map* allows you to associate a value with a specific key. It’s a +particular implementation of the more general data structure called a *map*. To learn about the other kinds of collections provided by the standard library, see the documentation at *https://doc.rust-lang.org/std/collections/index.html*. @@ -63,8 +63,8 @@ the type of value you want to store, so you rarely need to do this type annotation. Rust conveniently provides the `vec!` macro, which will create a new vector that holds the values you give it. Listing 8-2 creates a new `Vec<i32>` that holds the values `1`, `2`, and `3`. The integer type is `i32` -because that’s the default integer type, as we discussed in the “Data Types†-section of Chapter 3. +because that’s the default integer type, as we discussed in “Data Types†on +page XX. ``` let v = vec![1, 2, 3]; @@ -97,26 +97,9 @@ make it mutable using the `mut` keyword, as discussed in Chapter 3. The numbers we place inside are all of type `i32`, and Rust infers this from the data, so we don’t need the `Vec<i32>` annotation. -<!-- -I think people from other languages may get stuck a bit here because this is -the first time (I think?) that we're showing a hindley-milner style type -inference in action (rather than using the initializer to infer the type). - -Should we show the definition for `push`? That'd let us tie together the method -call, mutable reference to self drawing on the `impl` we saw in earlier -chapters and help to explain a little why the above works without having to -annotate the type of the Vec. -/JT ---> -<!-- I think readers would be more confused showing the definition of `push` -here because we haven't covered generics yet. I haven't gotten comments about -people being confused at this point (which doesn't mean they aren't), but -personally when I learned this, it made sense to me that the type of the vector -would be known from what I put in it. I'm leaning towards not elaborating here. -/Carol --> - ### Reading Elements of Vectors -There are two ways to reference a value stored in a vector: via indexing or +There are two ways to reference a value stored in a vector: via indexing or by using the `get` method. In the following examples, we’ve annotated the types of the values that are returned from these functions for extra clarity. @@ -126,18 +109,18 @@ syntax and the `get` method. ``` let v = vec![1, 2, 3, 4, 5]; -[1] let third: &i32 = &v[2]; -println!("The third element is {}", third); +1 let third: &i32 = &v[2]; +println!("The third element is {third}"); -[2] let third: Option<&i32> = v.get(2); +2 let third: Option<&i32> = v.get(2); match third { - Some(third) => println!("The third element is {}", third), + Some(third) => println!("The third element is {third}"), None => println!("There is no third element."), } ``` -Listing 8-4: Using indexing syntax or the `get` method to access an item in a -vector +Listing 8-4: Using indexing syntax and using the `get` method to access an item +in a vector Note a few details here. We use the index value of `2` to get the third element [1] because vectors are indexed by number, starting at zero. Using `&` and `[]` @@ -145,18 +128,11 @@ gives us a reference to the element at the index value. When we use the `get` method with the index passed as an argument [2], we get an `Option<&T>` that we can use with `match`. -<!--- -I think it should be "Second, we get the third element by using both `&` and -`[]`" -/JT ---> -<!-- No, it shouldn't, but I reworded this whole paragraph and added wingdings -because it was unclear /Carol --> - -The reason Rust provides these two ways to reference an element is so you can -choose how the program behaves when you try to use an index value outside the -range of existing elements. As an example, let’s see what happens when we have -a vector of five elements and then we try to access an element at index 100 -with each technique, as shown in Listing 8-5. +Rust provides these two ways to reference an element so you can choose how the +program behaves when you try to use an index value outside the range of +existing elements. As an example, let’s see what happens when we have a vector +of five elements and then we try to access an element at index 100 with each +technique, as shown in Listing 8-5. ``` let v = vec![1, 2, 3, 4, 5]; @@ -191,7 +167,7 @@ rule that states you can’t have mutable and immutable references in the same scope. That rule applies in Listing 8-6, where we hold an immutable reference to the first element in a vector and try to add an element to the end. This program won’t work if we also try to refer to that element later in the -function: +function. ``` let mut v = vec![1, 2, 3, 4, 5]; @@ -200,7 +176,7 @@ let first = &v[0]; v.push(6); -println!("The first element is: {}", first); +println!("The first element is: {first}"); ``` Listing 8-6: Attempting to add an element to a vector while holding a reference @@ -209,6 +185,8 @@ to an item Compiling this code will result in this error: ``` +error[E0502]: cannot borrow `v` as mutable because it is also borrowed as +immutable --> src/main.rs:6:5 | 4 | let first = &v[0]; @@ -217,8 +195,8 @@ Compiling this code will result in this error: 6 | v.push(6); | ^^^^^^^^^ mutable borrow occurs here 7 | -8 | println!("The first element is: {}", first); - | ----- immutable borrow later used here +8 | println!("The first element is: {first}"); + | ----- immutable borrow later used here ``` The code in Listing 8-6 might look like it should work: why should a reference @@ -232,9 +210,9 @@ pointing to deallocated memory. The borrowing rules prevent programs from ending up in that situation. > Note: For more on the implementation details of the `Vec<T>` type, see “The -> Rustonomicon†at *https://doc.rust-lang.org/nomicon/vec/vec.html*. +Rustonomicon†at *https://doc.rust-lang.org/nomicon/vec/vec.html*. -### Iterating over the Values in a Vector +### Iterating Over the Values in a Vector To access each element in a vector in turn, we would iterate through all of the elements rather than use indices to access one at a time. Listing 8-7 shows how @@ -244,7 +222,7 @@ to use a `for` loop to get immutable references to each element in a vector of ``` let v = vec![100, 32, 57]; for i in &v { - println!("{}", i); + println!("{i}"); } ``` @@ -265,10 +243,9 @@ for i in &mut v { Listing 8-8: Iterating over mutable references to elements in a vector To change the value that the mutable reference refers to, we have to use the -`*` dereference operator to get to the value in `i` before we can use the -`+=` operator. We’ll talk more about the dereference operator in the -“Following the Pointer to the Value with the Dereference Operator†-section of Chapter 15. +`*` dereference operator to get to the value in `i` before we can use the `+=` +operator. We’ll talk more about the dereference operator in “Following the +Pointer to the Value†on page XX. Iterating over a vector, whether immutably or mutably, is safe because of the borrow checker’s rules. If we attempted to insert or remove items in the `for` @@ -277,37 +254,13 @@ similar to the one we got with the code in Listing 8-6. The reference to the vector that the `for` loop holds prevents simultaneous modification of the whole vector. -<!-- -Maybe worth a mention: the above use of the mutable reference while you iterate -is perfectly safe because there's no changing that's happening to the vector -that would invalidate the iterator. But, if you wanted to iterate the vector -while also trying to remove or insert elements, you'd get an error. For example: - -``` -let mut v = vec![100, 32, 57]; -for i in &mut v { - *i += 50; - if *i > 100 { - v.push(10); // <-- a second mutable reference is needed and will fail to compile - } -} -``` - -Things like this help Rust prevent some classic C++ issues where people didn't -think about the implications of growing/shrinking a container while iterating -over it. -/JT ---> -<!-- I thought Listing 8-6 covered this, but I can see how driving home the -connection with iteration as well is worthwhile so I added a paragraph just -before this comment. Please check for clarity Liz! /Carol --> - ### Using an Enum to Store Multiple Types -Vectors can only store values that are the same type. This can be inconvenient; -there are definitely use cases for needing to store a list of items of -different types. Fortunately, the variants of an enum are defined under the -same enum type, so when we need one type to represent elements of different -types, we can define and use an enum! +Vectors can only store values that are of the same type. This can be +inconvenient; there are definitely use cases for needing to store a list of +items of different types. Fortunately, the variants of an enum are defined +under the same enum type, so when we need one type to represent elements of +different types, we can define and use an enum! For example, say we want to get values from a row in a spreadsheet in which some of the columns in the row contain integers, some floating-point numbers, @@ -330,8 +283,7 @@ let row = vec![ ]; ``` -Listing 8-9: Defining an `enum` to store values of different types in one -vector +Listing 8-9: Defining an `enum` to store values of different types in one vector Rust needs to know what types will be in the vector at compile time so it knows exactly how much memory on the heap will be needed to store each element. We @@ -346,7 +298,7 @@ store in a vector, the enum technique won’t work. Instead, you can use a trait object, which we’ll cover in Chapter 17. Now that we’ve discussed some of the most common ways to use vectors, be sure -to review the API documentation for all the many useful methods defined on +to review the API documentation for all of the many useful methods defined on `Vec<T>` by the standard library. For example, in addition to `push`, a `pop` method removes and returns the last element. @@ -372,19 +324,6 @@ valid. Let’s move on to the next collection type: `String`! -<!-- -nit: I think "meaning the integers it holds will be cleaned up" reads a little -better - -nit #2: imho dropping isn't as imports when you start using vectors as reading -elements from the vector. Is it better for training to mention it here, or -would it be possible to move it later? -/JT --> -<!-- Took both nit suggestions-- reworded for nit #1 and moved this section to -the end of the Vec section (and renumbered the listings) for nit #2. Liz, -please check to make sure I didn't miss anything in the way the Vec section -flows now! /Carol --> - ## Storing UTF-8 Encoded Text with Strings We talked about strings in Chapter 4, but we’ll look at them in more depth now. @@ -420,22 +359,10 @@ of those types. Although this section is largely about `String`, both types are used heavily in Rust’s standard library, and both `String` and string slices are UTF-8 encoded. -<!--- -I'm wondering if listing the above makes it a bit more cumbersome. In effect, -out of gate we're saying there are a lot of different string types. - -But perhaps we could focus on String and &str here and let them learn about -CString/CStr when doing FFI and OsString/OsStr when they work on paths? -Basically, I'm wondering if we should cut down on the concept count and let -them come across those alternate strings more naturally. -/JT ---> -<!-- I'm ok with that! I removed the paragraph talking about the other, rarer -string types. /Carol --> - ### Creating a New String Many of the same operations available with `Vec<T>` are available with `String` -as well, because `String` is actually implemented as a wrapper around a vector +as well because `String` is actually implemented as a wrapper around a vector of bytes with some extra guarantees, restrictions, and capabilities. An example of a function that works the same way with `Vec<T>` and `String` is the `new` function to create an instance, shown in Listing 8-11. @@ -446,9 +373,9 @@ let mut s = String::new(); Listing 8-11: Creating a new, empty `String` -This line creates a new empty string called `s`, which we can then load data -into. Often, we’ll have some initial data that we want to start the string -with. For that, we use the `to_string` method, which is available on any type +This line creates a new, empty string called `s`, into which we can then load +data. Often, we’ll have some initial data with which we want to start the +string. For that, we use the `to_string` method, which is available on any type that implements the `Display` trait, as string literals do. Listing 8-12 shows two examples. @@ -467,7 +394,7 @@ literal This code creates a string containing `initial contents`. We can also use the function `String::from` to create a `String` from a string -literal. The code in Listing 8-13 is equivalent to the code from Listing 8-12 +literal. The code in Listing 8-13 is equivalent to the code in Listing 8-12 that uses `to_string`. ``` @@ -480,7 +407,7 @@ string literal Because strings are used for so many things, we can use many different generic APIs for strings, providing us with a lot of options. Some of them can seem redundant, but they all have their place! In this case, `String::from` and -`to_string` do the same thing, so which you choose is a matter of style and +`to_string` do the same thing, so which one you choose is a matter of style and readability. Remember that strings are UTF-8 encoded, so we can include any properly encoded @@ -510,7 +437,7 @@ A `String` can grow in size and its contents can change, just like the contents of a `Vec<T>`, if you push more data into it. In addition, you can conveniently use the `+` operator or the `format!` macro to concatenate `String` values. -#### Appending to a String with `push_str` and `push` +#### Appending to a String with push_str and push We can grow a `String` by using the `push_str` method to append a string slice, as shown in Listing 8-15. @@ -531,7 +458,7 @@ parameter. For example, in the code in Listing 8-16, we want to be able to use let mut s1 = String::from("foo"); let s2 = "bar"; s1.push_str(s2); -println!("s2 is {}", s2); +println!("s2 is {s2}"); ``` Listing 8-16: Using a string slice after appending its contents to a `String` @@ -540,7 +467,7 @@ If the `push_str` method took ownership of `s2`, we wouldn’t be able to print its value on the last line. However, this code works as we’d expect! The `push` method takes a single character as a parameter and adds it to the -`String`. Listing 8-17 adds the letter "l" to a `String` using the `push` +`String`. Listing 8-17 adds the letter *l* to a `String` using the `push` method. ``` @@ -552,7 +479,7 @@ Listing 8-17: Adding one character to a `String` value using `push` As a result, `s` will contain `lol`. -#### Concatenation with the `+` Operator or the `format!` Macro +#### Concatenation with the + Operator or the format! Macro Often, you’ll want to combine two existing strings. One way to do so is to use the `+` operator, as shown in Listing 8-18. @@ -579,8 +506,8 @@ fn add(self, s: &str) -> String { In the standard library, you’ll see `add` defined using generics and associated types. Here, we’ve substituted in concrete types, which is what happens when we call this method with `String` values. We’ll discuss generics in Chapter 10. -This signature gives us the clues we need to understand the tricky bits of the -`+` operator. +This signature gives us the clues we need in order to understand the tricky +bits of the `+` operator. First, `s2` has an `&`, meaning that we’re adding a *reference* of the second string to the first string. This is because of the `s` parameter in the `add` @@ -588,29 +515,6 @@ function: we can only add a `&str` to a `String`; we can’t add two `String` values together. But wait—the type of `&s2` is `&String`, not `&str`, as specified in the second parameter to `add`. So why does Listing 8-18 compile? -<!-- -The above isn't quite right - the trait for ops::Add uses an Rhs associated type -instead of using T for both lhs and rhs. - -``` -pub trait Add<Rhs = Self> { - type Output; - fn add(self, rhs: Rhs) -> Self::Output; -} -``` - -The implementation of Add for String fills in Rhs with the slice: - -``` -impl<'_> Add<&'_ str> for String -``` - -Not sure if it's better to fix the description and not have deref coercion -discussion following, or fix the example so you can have the coercion -discussion. -/JT ---> -<!-- I've made an edit above to address this /Carol --> - The reason we’re able to use `&s2` in the call to `add` is that the compiler can *coerce* the `&String` argument into a `&str`. When we call the `add` method, Rust uses a *deref coercion*, which here turns `&s2` into `&s2[..]`. @@ -618,13 +522,13 @@ We’ll discuss deref coercion in more depth in Chapter 15. Because `add` does not take ownership of the `s` parameter, `s2` will still be a valid `String` after this operation. -Second, we can see in the signature that `add` takes ownership of `self`, +Second, we can see in the signature that `add` takes ownership of `self` because `self` does *not* have an `&`. This means `s1` in Listing 8-18 will be -moved into the `add` call and will no longer be valid after that. So although +moved into the `add` call and will no longer be valid after that. So, although `let s3 = s1 + &s2;` looks like it will copy both strings and create a new one, this statement actually takes ownership of `s1`, appends a copy of the contents of `s2`, and then returns ownership of the result. In other words, it looks -like it’s making a lot of copies but isn’t; the implementation is more +like it’s making a lot of copies, but it isn’t; the implementation is more efficient than copying. If we need to concatenate multiple strings, the behavior of the `+` operator @@ -639,15 +543,15 @@ let s = s1 + "-" + &s2 + "-" + &s3; ``` At this point, `s` will be `tic-tac-toe`. With all of the `+` and `"` -characters, it’s difficult to see what’s going on. For more complicated string -combining, we can instead use the `format!` macro: +characters, it’s difficult to see what’s going on. For combining strings in +more complicated ways, we can instead use the `format!` macro: ``` let s1 = String::from("tic"); let s2 = String::from("tac"); let s3 = String::from("toe"); -let s = format!("{}-{}-{}", s1, s2, s3); +let s = format!("{s1}-{s2}-{s3}"); ``` This code also sets `s` to `tic-tac-toe`. The `format!` macro works like @@ -668,7 +572,7 @@ let s1 = String::from("hello"); let h = s1[0]; ``` -Listing 8-19: Attempting to use indexing syntax with a String +Listing 8-19: Attempting to use indexing syntax with a `String` This code will result in the following error: @@ -679,7 +583,8 @@ error[E0277]: the type `String` cannot be indexed by `{integer}` 3 | let h = s1[0]; | ^^^^^ `String` cannot be indexed by `{integer}` | - = help: the trait `Index<{integer}>` is not implemented for `String` + = help: the trait `Index<{integer}>` is not implemented for +`String` ``` The error and the note tell the story: Rust strings don’t support indexing. But @@ -695,20 +600,21 @@ encoded UTF-8 example strings from Listing 8-14. First, this one: let hello = String::from("Hola"); ``` -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.) +In this case, `len` will be `4`, which means the vector storing the string +`"Hola"` is 4 bytes long. Each of these letters takes one 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): ``` let hello = String::from("ЗдравÑтвуйте"); ``` -Asked how long the string is, you might say 12. In fact, Rust’s answer is 24: -that’s the number of bytes it takes to encode “ЗдравÑтвуйте†in UTF-8, because -each Unicode scalar value in that string takes 2 bytes of storage. Therefore, -an index into the string’s bytes will not always correlate to a valid Unicode -scalar value. To demonstrate, consider this invalid Rust code: +If you were asked how long the string is, you might say 12. In fact, Rust’s +answer is 24: that’s the number of bytes it takes to encode “ЗдравÑтвуйте†in +UTF-8, because each Unicode scalar value in that string takes 2 bytes of +storage. Therefore, an index into the string’s bytes will not always correlate +to a valid Unicode scalar value. To demonstrate, consider this invalid Rust +code: ``` let hello = "ЗдравÑтвуйте"; @@ -738,8 +644,8 @@ If we look at the Hindi word “नमसà¥à¤¤à¥‡â€ written in the Devanagari stored as a vector of `u8` values that looks like this: ``` -[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, 164, 164, -224, 165, 135] +[224, 164, 168, 224, 164, 174, 224, 164, 184, 224, 165, 141, 224, +164, 164, 224, 165, 135] ``` That’s 18 bytes and is how computers ultimately store this data. If we look at @@ -785,8 +691,8 @@ let hello = "ЗдравÑтвуйте"; let s = &hello[0..4]; ``` -Here, `s` will be a `&str` that contains the first 4 bytes of the string. -Earlier, we mentioned that each of these characters was 2 bytes, which means +Here, `s` will be a `&str` that contains the first four bytes of the string. +Earlier, we mentioned that each of these characters was two bytes, which means `s` will be `Зд`. If we were to try to slice only part of a character’s bytes with something like @@ -794,55 +700,29 @@ If we were to try to slice only part of a character’s bytes with something lik index were accessed in a vector: ``` -thread 'main' panicked at 'byte index 1 is not a char boundary; it is inside 'З' (bytes 0..2) of `ЗдравÑтвуйте`', src/main.rs:4:14 +thread 'main' panicked at 'byte index 1 is not a char boundary; +it is inside 'З' (bytes 0..2) of `ЗдравÑтвуйте`', src/main.rs:4:14 ``` -You should use ranges to create string slices with caution, because doing so -can crash your program. +You should use caution when creating string slices with ranges, because doing +so can crash your program. ### Methods for Iterating Over Strings -<!--- is there a reason this comes after how to slice, rather than after the -discussion on why we can't directly index into a string? /LC ---> -<!-- I think the idea was that we show this progression of from worst technique -to best: - -1. direct indexing, which doesn't compile -2. slicing with a range, which looks similar to indexing, which does compile -but might panic at runtime -3. iterating over chars or bytes, which compiles and won't panic - -Do you have suggestions on making this clearer? I've tried to add a bit at the -beginning of this section /Carol ---> -<!-- JT, what do you think -- is this ordering clear to you? /LC --> -<!--- -I'm okay with the current order - I think showing why it's bad, what's close to -what you try first, and then finally the idiomatic Rust solution reads okay. - -One tiny nit, for flow, would be to use the Cyrillic example first here to show -how `.chars()` works well for it and then mention that for more complex -scripts, like Hindi, you'll need to use the more full-featured string handling -you find on crates.io. -/JT ---> -<!-- I've taken JT's suggestion here to use part of the Cyrillic string, then -mention you'll need a crate to correctly get the grapheme clusters for Hindi -/Carol --> - The best way to operate on pieces of strings is to be explicit about whether you want characters or bytes. For individual Unicode scalar values, use the -`chars` method. Calling `chars` on “Зд†separates out and returns two values -of type `char`, and you can iterate over the result to access each element: +`chars` method. Calling `chars` on “Зд†separates out and returns two values of +type `char`, and you can iterate over the result to access each element: -```rust +``` for c in "Зд".chars() { - println!("{}", c); + println!("{c}"); } ``` This code will print the following: -```text +``` З д ``` @@ -850,15 +730,15 @@ This code will print the following: Alternatively, the `bytes` method returns each raw byte, which might be appropriate for your domain: -```rust +``` for b in "Зд".bytes() { - println!("{}", b); + println!("{b}"); } ``` This code will print the four bytes that make up this string: -```text +``` 208 151 208 @@ -866,41 +746,19 @@ This code will print the four bytes that make up this string: ``` But be sure to remember that valid Unicode scalar values may be made up of more -than 1 byte. +than one byte. -Getting grapheme clusters from strings as with the Devanagari script is +Getting grapheme clusters from strings, as with the Devanagari script, is complex, so this functionality is not provided by the standard library. Crates -are available on *https://crates.io/* if this is the functionality you need. +are available at *https://crates.io* if this is the functionality you need. ### Strings Are Not So Simple -<!--- -Because Strings are quite complicated, and have complications that are all -their own and unlike any other containers, I wonder if maybe this chapter -should be two different chapters with one specifically being about strings, -string slices, chars, and related? -/JT ---> -<!-- I don't think I want to make that big of a change at this point... the -original idea was to compare and contrast the different containers, perhaps -that's not serving its purpose as well as a chapter split could... I'll think -about this for the next major revision. /Carol --> - -<!--- -We don't talk about searching in a string. Feels like it could use an example -or two? -/JT ---> -<!-- To address this suggestion and a bit of the previous suggestion as well, I -changed the first paragraph in the "Creating a New String" section to mention -that a `String` is implemented using a `Vec`. Then, to echo the last paragraph -before the "Dropping a Vector Drops Its Elements" section, I've added some text -here to again urge the reader to check out the standard library documentation -for more functionality. /Carol --> - To summarize, strings are complicated. Different programming languages make different choices about how to present this complexity to the programmer. Rust has chosen to make the correct handling of `String` data the default behavior for all Rust programs, which means programmers have to put more thought into -handling UTF-8 data upfront. This trade-off exposes more of the complexity of +handling UTF-8 data up front. This trade-off exposes more of the complexity of strings than is apparent in other programming languages, but it prevents you from having to handle errors involving non-ASCII characters later in your development life cycle. @@ -916,11 +774,11 @@ Let’s switch to something a bit less complex: hash maps! ## Storing Keys with Associated Values in Hash Maps The last of our common collections is the *hash map*. The type `HashMap<K, V>` -stores a mapping of keys of type `K` to values of type `V` using a -*hashing function*, which determines how it places these keys and values into -memory. Many programming languages support this kind of data structure, but -they often use a different name, such as hash, map, object, hash table, -dictionary, or associative array, just to name a few. +stores a mapping of keys of type `K` to values of type `V` using a *hashing +function*, which determines how it places these keys and values into memory. +Many programming languages support this kind of data structure, but they often +use a different name, such as *hash*, *map*, *object*, *hash table*, +*dictionary*, or *associative array*, just to name a few. Hash maps are useful when you want to look up data not by using an index, as you can with vectors, but by using a key that can be of any type. For example, @@ -934,7 +792,7 @@ As always, check the standard library documentation for more information. ### Creating a New Hash Map -One way to create an empty hash map is using `new` and adding elements with +One way to create an empty hash map is to use `new` and to add elements with `insert`. In Listing 8-20, we’re keeping track of the scores of two teams whose names are *Blue* and *Yellow*. The Blue team starts with 10 points, and the Yellow team starts with 50. @@ -958,25 +816,11 @@ standard library; there’s no built-in macro to construct them, for example. Just like vectors, hash maps store their data on the heap. This `HashMap` has keys of type `String` and values of type `i32`. Like vectors, hash maps are -homogeneous: all of the keys must have the same type as each other, and all of -the values must have the same type. - -<!--- -I'm not sure I've seen this in the wild? I'm tempted to say to skip the zip -example for flow and go from creating the hash map to working with its -contents. -/JT ---> -<!-- Cut Listing 8-21 and renumbered! /Carol --> +homogeneous: all of the keys must have the same type, and all of the values +must have the same type. ### Accessing Values in a Hash Map -<!--- -For flow, would it make sense for this section to follow creating the hash map? -That way we introduce a useful concept and also continue the teams example. -/JT ---> -<!-- Ok, I've switched the order of "Accessing Values in a Hash Map" and "Hash -Maps and Ownership" and renumbered! Does this still make sense Liz? /Carol --> - We can get a value out of the hash map by providing its key to the `get` method, as shown in Listing 8-21. @@ -989,7 +833,7 @@ scores.insert(String::from("Blue"), 10); scores.insert(String::from("Yellow"), 50); let team_name = String::from("Blue"); -let score = scores.get(&team_name).unwrap_or(0); +let score = scores.get(&team_name).copied().unwrap_or(0); ``` Listing 8-21: Accessing the score for the Blue team stored in the hash map @@ -997,17 +841,11 @@ Listing 8-21: Accessing the score for the Blue team stored in the hash map Here, `score` will have the value that’s associated with the Blue team, and the result will be `10`. The `get` method returns an `Option<&V>`; if there’s no value for that key in the hash map, `get` will return `None`. This program -handles the `Option` by calling `unwrap_or` to set `score` to zero if `scores` -doesn’t have an entry for the key. - -<!--- -Should there be a quick example here to show handling Some/None again before -we move on to iteration? -/JT ---> -<!-- I've changed the code in Listing 8-21 a bit to actually handle the -`Option` instead of referencing chapter 6, what do you think Liz? /Carol --> +handles the `Option` by calling `copied` to get an `Option<i32>` rather than an +`Option<&i32>`, then `unwrap_or` to set `score` to zero if `scores` doesn’t +have an entry for the key. -We can iterate over each key/value pair in a hash map in a similar manner as we +We can iterate over each key–value pair in a hash map in a similar manner as we do with vectors, using a `for` loop: ``` @@ -1019,7 +857,7 @@ scores.insert(String::from("Blue"), 10); scores.insert(String::from("Yellow"), 50); for (key, value) in &scores { - println!("{}: {}", key, value); + println!("{key}: {value}"); } ``` @@ -1044,8 +882,8 @@ let field_value = String::from("Blue"); let mut map = HashMap::new(); map.insert(field_name, field_value); -// field_name and field_value are invalid at this point, try using them and -// see what compiler error you get! +// field_name and field_value are invalid at this point, try +// using them and see what compiler error you get! ``` Listing 8-22: Showing that keys and values are owned by the hash map once @@ -1057,40 +895,14 @@ they’ve been moved into the hash map with the call to `insert`. If we insert references to values into the hash map, the values won’t be moved into the hash map. The values that the references point to must be valid for at least as long as the hash map is valid. We’ll talk more about these issues in -the “Validating References with Lifetimes†section in Chapter 10. +“Validating References with Lifetimes†on page XX. ### Updating a Hash Map Although the number of key and value pairs is growable, each unique key can only have one value associated with it at a time (but not vice versa: for -example, both the Blue team and the Yellow team could have value 10 stored in -the `scores` hash map). -<!--- And vice versa? /LC ---> -<!-- No, you could have a hashmap that has ("Blue", 10) and ("Yellow", 10) for -example. Stating this here feels a bit off topic for updating the value of an -existing key, though, I'm not sure how to work it in. Do you think that's -important enough to state here? If so, do you have suggestions on how to do it -without distracting from the main point of this section? /Carol --> -<!-- It may not be important enough, what do you think JT? /LC --> -<!--- -I think it's maybe worth calling out. Something you could use to drive -this home is the `.entry()` call. This makes it clear that for any key there's -one cell (or entry) that you're updating in the hash map. I see we use it -later, though worth a thought if bringing it earlier helps? -/JT ---> -<!-- I've added a short sentence here, but every time I try to add something -more, I end up getting tangled in saying things like "key value" as opposed to -"value value", which is terrible... or I worry about misleading readers into -thinking that you can't use a `Vec<T>` as a HashMap value type, which you -totally can to store multiple "values" in one vector "value", which you totally -can, it's just a little more complicated. Or I try to say "multiple keys can -have the same value" which sounds like it could imply that there would be a -*shared* value stored in the HashMap, which wouldn't be the case, there would -be two separate allocations that would happen to have the same value... I just -haven't heard a reader wondering if each value can only have one key with it -before (which doesn't mean they haven't wondered it, I just haven't heard of -it) so I don't want to lead readers astray if they weren't already going that -direction? What do you think about what's here now, Liz? /Carol --> +example, both the Blue team and the Yellow team could have the value `10` +stored in the `scores` hash map). When you want to change the data in a hash map, you have to decide how to handle the case when a key already has a value assigned. You could replace the @@ -1104,7 +916,7 @@ new value. Let’s look at how to do each of these! If we insert a key and a value into a hash map and then insert that same key with a different value, the value associated with that key will be replaced. Even though the code in Listing 8-23 calls `insert` twice, the hash map will -only contain one key/value pair because we’re inserting the value for the Blue +only contain one key–value pair because we’re inserting the value for the Blue team’s key both times. ``` @@ -1125,47 +937,16 @@ overwritten. #### Adding a Key and Value Only If a Key Isn’t Present -<!--- to be clear, are we talking about default values here, or just checking -for an existing value before allowing insertion of a value? /LC---> -<!-- I'm not sure what you mean exactly. Checking for an existing value before -allowing insertion of a value can be used to insert whatever value would mean -"default" in your program, or it can be used to insert some other value that -you wouldn't call a default. That is, in Listing 8-25, would you call 50 a -default value or no? (I don't think we've given enough information about what -the program is ultimately trying to do to tell if 50 is a default or not, and I -don't think it matters, but I am interested to know if there's something I'm -missing that you're trying to get at). Can you elaborate on what was confusing -and perhaps propose wording that would have cleared this up for you, and I can -fix if needed? /Carol--> -<!-- I suppose what I'm asking is whether a value is inserted from the started -as a default value and then updated, meaning the key never has no value, or -whether we're only allowing insertion of a value if there isn't already a -value. I think it's the latter and maybe that's clear enough as is! JT, what do -you think? /LC --> -<!--- -I think the idea is generally right, we're going to insert the value if the -key is not already in the hash map. Maybe the title could be: - -"Adding a key and value only if a key isn't present" - -Worth a note: I think "default" values are a bit of a loaded term in Rust. If -we use it, we may confuse people later if we they come across `Default`, which -is the default value of a type (like 0 is for i64, via `i64::default()`) -/JT ---> -<!-- Ok, I've taken JT's suggestion for the section title and tried to reword -the text here a bit; is this clearer, Liz? I share JT's concern about using the -word "default"... /Carol --> - It’s common to check whether a particular key already exists in the hash map -with a value then take the following actions: if the key does exist in the hash -map, the existing value should remain the way it is. If the key doesn’t exist, -insert it and a value for it. +with a value and then to take the following actions: if the key does exist in +the hash map, the existing value should remain the way it is; if the key +doesn’t exist, insert it and a value for it. Hash maps have a special API for this called `entry` that takes the key you want to check as a parameter. The return value of the `entry` method is an enum called `Entry` that represents a value that might or might not exist. Let’s say we want to check whether the key for the Yellow team has a value associated -with it. If it doesn’t, we want to insert the value 50, and the same for the +with it. If it doesn’t, we want to insert the value `50`, and the same for the Blue team. Using the `entry` API, the code looks like Listing 8-24. ``` @@ -1184,16 +965,16 @@ Listing 8-24: Using the `entry` method to only insert if the key does not already have a value The `or_insert` method on `Entry` is defined to return a mutable reference to -the value for the corresponding `Entry` key if that key exists, and if not, +the value for the corresponding `Entry` key if that key exists, and if not, it inserts the parameter as the new value for this key and returns a mutable reference to the new value. This technique is much cleaner than writing the logic ourselves and, in addition, plays more nicely with the borrow checker. Running the code in Listing 8-24 will print `{"Yellow": 50, "Blue": 10}`. The first call to `entry` will insert the key for the Yellow team with the value -50 because the Yellow team doesn’t have a value already. The second call to +`50` because the Yellow team doesn’t have a value already. The second call to `entry` will not change the hash map because the Blue team already has the -value 10. +value `10`. #### Updating a Value Based on the Old Value @@ -1202,7 +983,7 @@ update it based on the old value. For instance, Listing 8-25 shows code that counts how many times each word appears in some text. We use a hash map with the words as keys and increment the value to keep track of how many times we’ve seen that word. If it’s the first time we’ve seen a word, we’ll first insert -the value 0. +the value `0`. ``` use std::collections::HashMap; @@ -1223,37 +1004,29 @@ Listing 8-25: Counting occurrences of words using a hash map that stores words and counts This code will print `{"world": 2, "hello": 1, "wonderful": 1}`. You might see -the same key/value pairs printed in a different order: recall from the -“Accessing Values in a Hash Map†section that iterating over a hash map happens -in an arbitrary order. +the same key–value pairs printed in a different order: recall from “Accessing +Values in a Hash Map†on page XX that iterating over a hash map happens in an +arbitrary order. -The `split_whitespace` method returns an iterator over sub-slices, separated by +The `split_whitespace` method returns an iterator over subslices, separated by whitespace, of the value in `text`. The `or_insert` method returns a mutable -reference (`&mut V`) to the value for the specified key. Here we store that +reference (`&mut V`) to the value for the specified key. Here, we store that mutable reference in the `count` variable, so in order to assign to that value, we must first dereference `count` using the asterisk (`*`). The mutable reference goes out of scope at the end of the `for` loop, so all of these changes are safe and allowed by the borrowing rules. -<!--- -Running the above gave me `{"world": 2, "wonderful": 1, "hello": 1}` so the key -order may not be deterministic or may change based on changes to the hashing -function in the std lib. -/JT ---> -<!-- I've added a note that getting a different order is perfectly normal -/Carol --> - ### Hashing Functions By default, `HashMap` uses a hashing function called *SipHash* that can provide -resistance to Denial of Service (DoS) attacks involving hash tables. This is +resistance to denial-of-service (DoS) attacks involving hash tables. This is not the fastest hashing algorithm available, but the trade-off for better security that comes with the drop in performance is worth it. If you profile your code and find that the default hash function is too slow for your purposes, you can switch to another function by specifying a different hasher. A *hasher* is a type that implements the `BuildHasher` trait. We’ll talk about traits and how to implement them in Chapter 10. You don’t necessarily have to -implement your own hasher from scratch; *https://crates.io/* has libraries +implement your own hasher from scratch; *https://crates.io* has libraries shared by other Rust users that provide hashers implementing many common hashing algorithms. @@ -1263,22 +1036,22 @@ Vectors, strings, and hash maps will provide a large amount of functionality necessary in programs when you need to store, access, and modify data. Here are some exercises you should now be equipped to solve: -* Given a list of integers, use a vector and return the median (when sorted, - the value in the middle position) and mode (the value that occurs most often; - a hash map will be helpful here) of the list. -* Convert strings to pig latin. The first consonant of each word is moved to - the end of the word and “ay†is added, so “first†becomes “irst-fay.†Words - that start with a vowel have “hay†added to the end instead (“apple†becomes - “apple-hayâ€). Keep in mind the details about UTF-8 encoding! -* Using a hash map and vectors, create a text interface to allow a user to add - employee names to a department in a company. For example, “Add Sally to - Engineering†or “Add Amir to Sales.†Then let the user retrieve a list of all - people in a department or all people in the company by department, sorted - alphabetically. +1. Given a list of integers, use a vector and return the median (when sorted, +the value in the middle position) and mode (the value that occurs most often; a +hash map will be helpful here) of the list. +1. Convert strings to pig latin. The first consonant of each word is moved to +the end of the word and *ay* is added, so *first* becomes *irst-fay*. Words +that start with a vowel have *hay* added to the end instead (*apple* becomes +*apple-hay*). Keep in mind the details about UTF-8 encoding! +1. Using a hash map and vectors, create a text interface to allow a user to add +employee names to a department in a company; for example, “Add Sally to +Engineering†or “Add Amir to Sales.†Then let the user retrieve a list of all +people in a department or all people in the company by department, sorted +alphabetically. The standard library API documentation describes methods that vectors, strings, and hash maps have that will be helpful for these exercises! -We’re getting into more complex programs in which operations can fail, so, it’s +We’re getting into more complex programs in which operations can fail, so it’s a perfect time to discuss error handling. We’ll do that next! diff --git a/src/doc/book/nostarch/chapter09.md b/src/doc/book/nostarch/chapter09.md index 693dc1be0..4aa81123f 100644 --- a/src/doc/book/nostarch/chapter09.md +++ b/src/doc/book/nostarch/chapter09.md @@ -18,7 +18,7 @@ deployed your code to production! Rust groups errors into two major categories: *recoverable* and *unrecoverable* errors. For a recoverable error, such as a *file not found* error, we most likely just want to report the problem to the user and retry the operation. -Unrecoverable errors are always symptoms of bugs, like trying to access a +Unrecoverable errors are always symptoms of bugs, such as trying to access a location beyond the end of an array, and so we want to immediately stop the program. @@ -31,9 +31,9 @@ about returning `Result<T, E>` values. Additionally, we’ll explore considerations when deciding whether to try to recover from an error or to stop execution. -## Unrecoverable Errors with `panic!` +## Unrecoverable Errors with panic! -Sometimes, bad things happen in your code, and there’s nothing you can do about +Sometimes bad things happen in your code, and there’s nothing you can do about it. In these cases, Rust has the `panic!` macro. There are two ways to cause a panic in practice: by taking an action that causes our code to panic (such as accessing an array past the end) or by explicitly calling the `panic!` macro. @@ -42,39 +42,22 @@ print a failure message, unwind, clean up the stack, and quit. Via an environment variable, you can also have Rust display the call stack when a panic occurs to make it easier to track down the source of the panic. -<!-- does Rust invoke the panic, or do we? Or sometimes it can be either? /LC ---> -<!-- We will have done *something* through a combination of the code we've -written and the data the program gets at runtime. It *might* involve us -literally typing `panic!` into our code, or it might be part of Rust that we're -using that calls `panic!` for us because of something else we've done. Does -that make sense? I've tried to clarify the last sentence a bit here /Carol --> -<!--- -One way we could explain it is to say there are two ways to cause a panic in -practice: by doing an action that causes our code to panic, like accessing an -array past the end or dividing by zero, or by explicitly calling the `panic!` -macro. In both cases, we cause a panic in our application. By default, these -panics will unwind and clean up the stack. Via an environment setting, you can -also have Rust display the call stack when a panic occurs to make it easier to -track down the source of the panic. -/JT ---> -<!-- I've taken JT's suggestion with some edits in the paragraph above /Carol ---> > ### Unwinding the Stack or Aborting in Response to a Panic > -> By default, when a panic occurs, the program starts *unwinding*, which -> means Rust walks back up the stack and cleans up the data from each function -> it encounters. However, this walking back and cleanup is a lot of work. Rust, -> therefore, allows you to choose the alternative of immediately *aborting*, -> which ends the program without cleaning up. +> By default, when a panic occurs the program starts *unwinding*, which means +Rust walks back up the stack and cleans up the data from each function it +encounters. However, walking back and cleaning up is a lot of work. Rust, +therefore, allows you to choose the alternative of immediately *aborting*, +which ends the program without cleaning up. > -> Memory that the program was using will then need to be cleaned -> up by the operating system. If in your project you need to make the resulting -> binary as small as possible, you can switch from unwinding to aborting upon a -> panic by adding `panic = 'abort'` to the appropriate `[profile]` sections in -> your *Cargo.toml* file. For example, if you want to abort on panic in release -> mode, add this: +> Memory that the program was using will then need to be cleaned up by the +operating system. If in your project you need to make the resultant binary as +small as possible, you can switch from unwinding to aborting upon a panic by +adding `panic = 'abort'` to the appropriate `[profile]` sections in your +*Cargo.toml* file. For example, if you want to abort on panic in release mode, +add this: > -> ```toml +> ``` > [profile.release] > panic = 'abort' > ``` @@ -93,7 +76,8 @@ When you run the program, you’ll see something like this: ``` thread 'main' panicked at 'crash and burn', src/main.rs:2:5 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace ``` The call to `panic!` causes the error message contained in the last two lines. @@ -105,17 +89,14 @@ In this case, the line indicated is part of our code, and if we go to that line, we see the `panic!` macro call. In other cases, the `panic!` call might be in code that our code calls, and the filename and line number reported by the error message will be someone else’s code where the `panic!` macro is -called, not the line of our code that eventually led to the `panic!` call. We -can use the backtrace of the functions the `panic!` call came from to figure -out the part of our code that is causing the problem. We’ll discuss backtraces -in more detail next. - -### Using a `panic!` Backtrace +called, not the line of our code that eventually led to the `panic!` call. -Let’s look at another example to see what it’s like when a `panic!` call comes -from a library because of a bug in our code instead of from our code calling -the macro directly. Listing 9-1 has some code that attempts to access an -index in a vector beyond the range of valid indexes. +We can use the backtrace of the functions the `panic!` call came from to figure +out the part of our code that is causing the problem. To understand how to use +a `panic!` backtrace, let’s look at another example and see what it’s like when +a `panic!` call comes from a library because of a bug in our code instead of +from our code calling the macro directly. Listing 9-1 has some code that +attempts to access an index in a vector beyond the range of valid indexes. Filename: src/main.rs @@ -131,10 +112,10 @@ Listing 9-1: Attempting to access an element beyond the end of a vector, which will cause a call to `panic!` Here, we’re attempting to access the 100th element of our vector (which is at -index 99 because indexing starts at zero), but the vector has only 3 elements. -In this situation, Rust will panic. Using `[]` is supposed to return an -element, but if you pass an invalid index, there’s no element that Rust could -return here that would be correct. +index 99 because indexing starts at zero), but the vector has only three +elements. In this situation, Rust will panic. Using `[]` is supposed to return +an element, but if you pass an invalid index, there’s no element that Rust +could return here that would be correct. In C, attempting to read beyond the end of a data structure is undefined behavior. You might get whatever is at the location in memory that would @@ -149,44 +130,55 @@ element at an index that doesn’t exist, Rust will stop execution and refuse to continue. Let’s try it and see: ``` -thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5 +thread 'main' panicked at 'index out of bounds: the len is 3 but the index is +99', src/main.rs:4:5 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` -This error points at line 4 of our `main.rs` where we attempt to access index -99. The next note line tells us that we can set the `RUST_BACKTRACE` -environment variable to get a backtrace of exactly what happened to cause the -error. A *backtrace* is a list of all the functions that have been called to -get to this point. Backtraces in Rust work as they do in other languages: the -key to reading the backtrace is to start from the top and read until you see -files you wrote. That’s the spot where the problem originated. The lines above -that spot are code that your code has called; the lines below are code that -called your code. These before-and-after lines might include core Rust code, -standard library code, or crates that you’re using. Let’s try getting a -backtrace by setting the `RUST_BACKTRACE` environment variable to any value -except 0. Listing 9-2 shows output similar to what you’ll see. +This error points at line 4 of our *main.rs* where we attempt to access `index`. + +The `note:` line tells us that we can set the `RUST_BACKTRACE` environment +variable to get a backtrace of exactly what happened to cause the error. A +*backtrace* is a list of all the functions that have been called to get to this +point. Backtraces in Rust work as they do in other languages: the key to +reading the backtrace is to start from the top and read until you see files you +wrote. That’s the spot where the problem originated. The lines above that spot +are code that your code has called; the lines below are code that called your +code. These before-and-after lines might include core Rust code, standard +library code, or crates that you’re using. Let’s try getting a backtrace by +setting the `RUST_BACKTRACE` environment variable to any value except `0`. +Listing 9-2 shows output similar to what you’ll see. ``` $ RUST_BACKTRACE=1 cargo run -thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5 +thread 'main' panicked at 'index out of bounds: the len is 3 but the index is +99', src/main.rs:4:5 stack backtrace: 0: rust_begin_unwind - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/std/src/panicking.rs:483 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/std +/src/panicking.rs:584:5 1: core::panicking::panic_fmt - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/panicking.rs:85 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/panicking.rs:142:14 2: core::panicking::panic_bounds_check - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/panicking.rs:62 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/panicking.rs:84:5 3: <usize as core::slice::index::SliceIndex<[T]>>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/slice/index.rs:255 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/slice/index.rs:242:10 4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/slice/index.rs:15 - 5: <alloc::vec::Vec<T> as core::ops::index::Index<I>>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/alloc/src/vec.rs:1982 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/slice/index.rs:18:9 + 5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/alloc +/src/vec/mod.rs:2591:9 6: panic::main - at ./src/main.rs:4 + at ./src/main.rs:4:5 7: core::ops::function::FnOnce::call_once - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/ops/function.rs:227 -note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace. + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core +/src/ops/function.rs:248:5 +note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose +backtrace. ``` Listing 9-2: The backtrace generated by a call to `panic!` displayed when the @@ -208,21 +200,19 @@ panics in the future, you’ll need to figure out what action the code is taking with what values to cause the panic and what the code should do instead. We’ll come back to `panic!` and when we should and should not use `panic!` to -handle error conditions in the “To `panic!` or Not to `panic!`†section later -in this chapter. Next, we’ll look at how to recover from an error using -`Result`. +handle error conditions in “To panic! or Not to panic!†on page XX. Next, we’ll +look at how to recover from an error using `Result`. -## Recoverable Errors with `Result` +## Recoverable Errors with Result Most errors aren’t serious enough to require the program to stop entirely. -Sometimes, when a function fails, it’s for a reason that you can easily -interpret and respond to. For example, if you try to open a file and that -operation fails because the file doesn’t exist, you might want to create the -file instead of terminating the process. +Sometimes when a function fails it’s for a reason that you can easily interpret +and respond to. For example, if you try to open a file and that operation fails +because the file doesn’t exist, you might want to create the file instead of +terminating the process. -Recall from “Handling Potential Failure with the `Result` Type†in Chapter 2 -that the `Result` enum is defined as having two variants, `Ok` and `Err`, as -follows: +Recall from “Handling Potential Failure with Result†on page XX that the +`Result` enum is defined as having two variants, `Ok` and `Err`, as follows: ``` enum Result<T, E> { @@ -237,7 +227,7 @@ the type of the value that will be returned in a success case within the `Ok` variant, and `E` represents the type of the error that will be returned in a failure case within the `Err` variant. Because `Result` has these generic type parameters, we can use the `Result` type and the functions defined on it in -many different situations where the successful value and error value we want to +many different situations where the success value and error value we want to return may differ. Let’s call a function that returns a `Result` value because the function could @@ -255,18 +245,6 @@ fn main() { Listing 9-3: Opening a file -<!--- -This brings up an interesting point - should we teach them to install -rust-analyzer in the setup instructions? If so, then we can tell them to mouse -over the name of what they want the typename of. The "assign something to i32 to -have rustc tell you what it is" feels a bit like old style Rust. -/JT ---> -<!-- I somewhat disagree here; not everyone uses IDE plugins. I'll see what JT -says about mentioning rust-analyzer in chapter 1 rather than in the appendix... -I am in favor of making the book shorter, though, so I've removed the parts -about asking the compiler what the type of something is by deliberately -annotating with the wrong type. /Carol --> - The return type of `File::open` is a `Result<T, E>`. The generic parameter `T` has been filled in by the implementation of `File::open` with the type of the success value, `std::fs::File`, which is a file handle. The type of `E` used in @@ -282,7 +260,7 @@ In the case where `File::open` succeeds, the value in the variable `greeting_file_result` will be an instance of `Ok` that contains a file handle. In the case where it fails, the value in `greeting_file_result` will be an instance of `Err` that contains more information about the kind of error that -happened. +occurred. We need to add to the code in Listing 9-3 to take different actions depending on the value `File::open` returns. Listing 9-4 shows one way to handle the @@ -299,7 +277,9 @@ fn main() { let greeting_file = match greeting_file_result { Ok(file) => file, - Err(error) => panic!("Problem opening the file: {:?}", error), + Err(error) => { + panic!("Problem opening the file: {:?}", error); + } }; } ``` @@ -322,7 +302,9 @@ there’s no file named *hello.txt* in our current directory and we run this code, we’ll see the following output from the `panic!` macro: ``` -thread 'main' panicked at 'Problem opening the file: Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:8:23 +thread 'main' panicked at 'Problem opening the file: Os { code: + 2, kind: NotFound, message: "No such file or directory" }', +src/main.rs:8:23 ``` As usual, this output tells us exactly what has gone wrong. @@ -330,11 +312,11 @@ As usual, this output tells us exactly what has gone wrong. ### Matching on Different Errors The code in Listing 9-4 will `panic!` no matter why `File::open` failed. -However, we want to take different actions for different failure reasons: if +However, we want to take different actions for different failure reasons. If `File::open` failed because the file doesn’t exist, we want to create the file and return the handle to the new file. If `File::open` failed for any other reason—for example, because we didn’t have permission to open the file—we still -want the code to `panic!` in the same way as it did in Listing 9-4. For this we +want the code to `panic!` in the same way it did in Listing 9-4. For this, we add an inner `match` expression, shown in Listing 9-5. Filename: src/main.rs @@ -349,14 +331,22 @@ fn main() { let greeting_file = match greeting_file_result { Ok(file) => file, Err(error) => match error.kind() { - ErrorKind::NotFound => match File::create("hello.txt") { - Ok(fc) => fc, - Err(e) => panic!("Problem creating the file: {:?}", e), + ErrorKind::NotFound => { + match File::create("hello.txt") { + Ok(fc) => fc, + Err(e) => panic!( + "Problem creating the file: {:?}", + e + ), + } } other_error => { - panic!("Problem opening the file: {:?}", other_error); + panic!( + "Problem opening the file: {:?}", + other_error + ); } - } + }, }; } ``` @@ -380,40 +370,41 @@ file can’t be created, a different error message is printed. The second arm of the outer `match` stays the same, so the program panics on any error besides the missing file error. -> ### Alternatives to Using `match` with `Result<T, E>` -> -> That’s a lot of `match`! The `match` expression is very useful but also very -> much a primitive. In Chapter 13, you’ll learn about closures, which are used -> with many of the methods defined on `Result<T, E>`. These methods can be more -> concise than using `match` when handling `Result<T, E>` values in your code. +#### Alternatives to Using match with Result<T, E> -> For example, here’s another way to write the same logic as shown in Listing -> 9-5, this time using closures and the `unwrap_or_else` method: -> -> ``` -> use std::fs::File; -> use std::io::ErrorKind; -> -> fn main() { -> let greeting_file = File::open("hello.txt").unwrap_or_else(|error| { -> if error.kind() == ErrorKind::NotFound { -> File::create("hello.txt").unwrap_or_else(|error| { -> panic!("Problem creating the file: {:?}", error); -> }) -> } else { -> panic!("Problem opening the file: {:?}", error); -> } -> }); -> } -> ``` -> -> Although this code has the same behavior as Listing 9-5, it doesn’t contain -> any `match` expressions and is cleaner to read. Come back to this example -> after you’ve read Chapter 13, and look up the `unwrap_or_else` method in the -> standard library documentation. Many more of these methods can clean up huge -> nested `match` expressions when you’re dealing with errors. +That’s a lot of `match`! The `match` expression is very useful but also very +much a primitive. In Chapter 13, you’ll learn about closures, which are used +with many of the methods defined on `Result<T, E>`. These methods can be more +concise than using `match` when handling `Result<T, E>` values in your code. -### Shortcuts for Panic on Error: `unwrap` and `expect` +For example, here’s another way to write the same logic as shown in Listing +9-5, this time using closures and the `unwrap_or_else` method: + +``` +// src/main.rs +use std::fs::File; +use std::io::ErrorKind; + +fn main() { + let greeting_file = File::open("hello.txt").unwrap_or_else(|error| { + if error.kind() == ErrorKind::NotFound { + File::create("hello.txt").unwrap_or_else(|error| { + panic!("Problem creating the file: {:?}", error); + }) + } else { + panic!("Problem opening the file: {:?}", error); + } + }); +} +``` + +Although this code has the same behavior as Listing 9-5, it doesn’t contain any +`match` expressions and is cleaner to read. Come back to this example after +you’ve read Chapter 13, and look up the `unwrap_or_else` method in the standard +library documentation. Many more of these methods can clean up huge nested +`match` expressions when you’re dealing with errors. + +#### Shortcuts for Panic on Error: unwrap and expect Using `match` works well enough, but it can be a bit verbose and doesn’t always communicate intent well. The `Result<T, E>` type has many helper methods @@ -437,20 +428,11 @@ If we run this code without a *hello.txt* file, we’ll see an error message fro the `panic!` call that the `unwrap` method makes: ``` -thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error { -repr: Os { code: 2, message: "No such file or directory" } }', -src/libcore/result.rs:906:4 +thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Os { +code: 2, kind: NotFound, message: "No such file or directory" }', +src/main.rs:4:49 ``` -<!--- -More recent rustc versions give a bit better error here (specifically the location): - -thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: -Os { code: 2, kind: NotFound, message: "No such file or directory" }', src/main.rs:4:37 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -/JT ---> -<!-- I'll update the error output when we're in Word /Carol --> - Similarly, the `expect` method lets us also choose the `panic!` error message. Using `expect` instead of `unwrap` and providing good error messages can convey your intent and make tracking down the source of a panic easier. The syntax of @@ -473,36 +455,20 @@ will be the parameter that we pass to `expect`, rather than the default `panic!` message that `unwrap` uses. Here’s what it looks like: ``` -thread 'main' panicked at 'hello.txt should be included in this project: Error { repr: Os { code: -2, message: "No such file or directory" } }', src/libcore/result.rs:906:4 +thread 'main' panicked at 'hello.txt should be included in this project: Os { +code: 2, kind: NotFound, message: "No such file or directory" }', +src/main.rs:5:10 ``` -<!--- -Ditto with the above: - -thread 'main' panicked at 'Failed to open hello.txt: Os { code: 2, kind: NotFound, -message: "No such file or directory" }', src/main.rs:4:37 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace -/JT ---> -<!-- I'll update the error output when we're in Word /Carol --> - In production-quality code, most Rustaceans choose `expect` rather than `unwrap` and give more context about why the operation is expected to always succeed. That way, if your assumptions are ever proven wrong, you have more information to use in debugging. -<!--- -Now that `unwrap` and `expect` give an improved file location, we may not -need the paragraph above. -/JT ---> -<!-- I've changed the paragraph above, as well as the text in the examaple -usage of `expect`, to better reflect current best practices and the reasons for -them. /Carol --> - ### Propagating Errors When a function’s implementation calls something that might fail, instead of -handling the error within the function itself, you can return the error to the +handling the error within the function itself you can return the error to the calling code so that it can decide what to do. This is known as *propagating* the error and gives more control to the calling code, where there might be more information or logic that dictates how the error should be handled than what @@ -518,19 +484,19 @@ Filename: src/main.rs use std::fs::File; use std::io::{self, Read}; -fn read_username_from_file() -> Result<String, io::Error> [1] { - let username_file_result = File::open("hello.txt"); [2] +1 fn read_username_from_file() -> Result<String, io::Error> { + 2 let username_file_result = File::open("hello.txt"); - let mut username_file [3] = match username_file_result { - Ok(file) => file, [4] - Err(e) => return Err(e), [5] + 3 let mut username_file = match username_file_result { + 4 Ok(file) => file, + 5 Err(e) => return Err(e), }; - let mut username = String::new(); [6] + 6 let mut username = String::new(); - match username_file.read_to_string(&mut username) [7] { - Ok(_) => Ok(username), [8] - Err(e) => Err(e), [9] + 7 match username_file.read_to_string(&mut username) { + 8 Ok(_) => Ok(username), + 9 Err(e) => Err(e), } } ``` @@ -541,12 +507,12 @@ This function can be written in a much shorter way, but we’re going to start b doing a lot of it manually in order to explore error handling; at the end, we’ll show the shorter way. Let’s look at the return type of the function first: `Result<String, io::Error>` [1]. This means the function is returning a -value of the type `Result<T, E>` where the generic parameter `T` has been -filled in with the concrete type `String`, and the generic type `E` has been +value of the type `Result<T, E>`, where the generic parameter `T` has been +filled in with the concrete type `String` and the generic type `E` has been filled in with the concrete type `io::Error`. If this function succeeds without any problems, the code that calls this -function will receive an `Ok` value that holds a `String`—the username that +function will receive an `Ok` value that holds a `String`—the `username` that this function read from the file [8]. If this function encounters any problems, the calling code will receive an `Err` value that holds an instance of `io::Error` that contains more information about what the problems were. We @@ -564,9 +530,9 @@ function continues. In the `Err` case, instead of calling `panic!`, we use the error value from `File::open`, now in the pattern variable `e`, back to the calling code as this function’s error value [5]. -So if we have a file handle in `username_file`, the function then creates a new -`String` in variable `username` [6] and calls the `read_to_string` method on -the file handle in `username_file` to read the contents of the file into +So, if we have a file handle in `username_file`, the function then creates a +new `String` in variable `username` [6] and calls the `read_to_string` method +on the file handle in `username_file` to read the contents of the file into `username` [7]. The `read_to_string` method also returns a `Result` because it might fail, even though `File::open` succeeded. So we need another `match` to handle that `Result`: if `read_to_string` succeeds, then our function has @@ -576,20 +542,6 @@ same way that we returned the error value in the `match` that handled the return value of `File::open`. However, we don’t need to explicitly say `return`, because this is the last expression in the function [9]. -<!--- -Style nit: I'm finding the above two paragraphs a bit difficult to read -comfortably. I think one issue is that we're using a handful of single letter -variable names while also trying to walk someone through an explanation of -multiple concepts. - -Maybe just me? But feels like the above example might be explained a bit better -if we used more complete variable names so the explanation could have a better -flow (without trying to remember what each of the single-letter variables meant) -/JT ---> -<!-- Totally valid! I've changed the variable names in this, previous, and -following examples, broke up these paragraphs a bit, and added wingdings. -/Carol --> - The code that calls this code will then handle getting either an `Ok` value that contains a username or an `Err` value that contains an `io::Error`. It’s up to the calling code to decide what to do with those values. If the calling @@ -602,18 +554,17 @@ it to handle appropriately. This pattern of propagating errors is so common in Rust that Rust provides the question mark operator `?` to make this easier. -#### A Shortcut for Propagating Errors: the `?` Operator +#### A Shortcut for Propagating Errors: The ? Operator Listing 9-7 shows an implementation of `read_username_from_file` that has the -same functionality as in Listing 9-6, but this implementation uses the -`?` operator. +same functionality as in Listing 9-6, but this implementation uses the `?` +operator. Filename: src/main.rs ``` use std::fs::File; -use std::io; -use std::io::Read; +use std::io::{self, Read}; fn read_username_from_file() -> Result<String, io::Error> { let mut username_file = File::open("hello.txt")?; @@ -651,13 +602,6 @@ define `impl From<io::Error> for OurError` to construct an instance of `read_username_from_file` will call `from` and convert the error types without needing to add any more code to the function. -<!--- -It's a bit fuzzy what `impl From<OtherError> for ReturnedError` means. We may -want to use a more concrete example, like: `impl From<OurError> for io::Error`. -/JT ---> -<!-- I've added a more concrete example here, but converting the other way, -which I think is more likely in production code /Carol --> - In the context of Listing 9-7, the `?` at the end of the `File::open` call will return the value inside an `Ok` to the variable `username_file`. If an error occurs, the `?` operator will return early out of the whole function and give @@ -672,8 +616,7 @@ Filename: src/main.rs ``` use std::fs::File; -use std::io; -use std::io::Read; +use std::io::{self, Read}; fn read_username_from_file() -> Result<String, io::Error> { let mut username = String::new(); @@ -718,7 +661,7 @@ into that `String`, and returns it. Of course, using `fs::read_to_string` doesn’t give us the opportunity to explain all the error handling, so we did it the longer way first. -#### Where The `?` Operator Can Be Used +#### Where the ? Operator Can Be Used The `?` operator can only be used in functions whose return type is compatible with the value the `?` is used on. This is because the `?` operator is defined @@ -729,8 +672,8 @@ as the `match` expression we defined in Listing 9-6. In Listing 9-6, the it’s compatible with this `return`. In Listing 9-10, let’s look at the error we’ll get if we use the `?` operator -in a `main` function with a return type incompatible with the type of the value -we use `?` on: +in a `main` function with a return type that is incompatible with the type of +the value we use `?` on. Filename: src/main.rs @@ -743,7 +686,7 @@ fn main() { ``` Listing 9-10: Attempting to use the `?` in the `main` function that returns -`()` won’t compile +`()` won’t compile. This code opens a file, which might fail. The `?` operator follows the `Result` value returned by `File::open`, but this `main` function has the return type of @@ -751,15 +694,19 @@ value returned by `File::open`, but this `main` function has the return type of message: ``` -error[E0277]: the `?` operator can only be used in a function that returns `Result` or `Option` (or another type that implements `FromResidual`) - --> src/main.rs:4:36 - | -3 | / fn main() { -4 | | let f = File::open("hello.txt")?; - | | ^ cannot use the `?` operator in a function that returns `()` -5 | | } - | |_- this function should return `Result` or `Option` to accept `?` - | +error[E0277]: the `?` operator can only be used in a function that returns +`Result` or `Option` (or another type that implements `FromResidual`) + --> src/main.rs:4:48 + | +3 | / fn main() { +4 | | let greeting_file = File::open("hello.txt")?; + | | ^ cannot use the `?` +operator in a function that returns `()` +5 | | } + | |_- this function should return `Result` or `Option` to accept `?` + | + = help: the trait `FromResidual<Result<Infallible, std::io::Error>>` is not +implemented for `()` ``` This error points out that we’re only allowed to use the `?` operator in a @@ -768,9 +715,9 @@ function that returns `Result`, `Option`, or another type that implements To fix the error, you have two choices. One choice is to change the return type of your function to be compatible with the value you’re using the `?` operator -on as long as you have no restrictions preventing that. The other technique is -to use a `match` or one of the `Result<T, E>` methods to handle the `Result<T, -E>` in whatever way is appropriate. +on as long as you have no restrictions preventing that. The other choice is to +use a `match` or one of the `Result<T, E>` methods to handle the `Result<T, E>` +in whatever way is appropriate. The error message also mentioned that `?` can be used with `Option<T>` values as well. As with using `?` on `Result`, you can only use `?` on `Option` in a @@ -778,9 +725,9 @@ function that returns an `Option`. The behavior of the `?` operator when called on an `Option<T>` is similar to its behavior when called on a `Result<T, E>`: if the value is `None`, the `None` will be returned early from the function at that point. If the value is `Some`, the value inside the `Some` is the -resulting value of the expression and the function continues. Listing 9-11 has +resultant value of the expression, and the function continues. Listing 9-11 has an example of a function that finds the last character of the first line in the -given text: +given text. ``` fn last_char_of_first_line(text: &str) -> Option<char> { @@ -804,7 +751,7 @@ The `?` extracts the string slice, and we can call `chars` on that string slice to get an iterator of its characters. We’re interested in the last character in this first line, so we call `last` to return the last item in the iterator. This is an `Option` because it’s possible that the first line is the empty -string, for example if `text` starts with a blank line but has characters on +string; for example, if `text` starts with a blank line but has characters on other lines, as in `"\nhi"`. However, if there is a last character on the first line, it will be returned in the `Some` variant. The `?` operator in the middle gives us a concise way to express this logic, allowing us to implement the @@ -819,14 +766,16 @@ you can use methods like the `ok` method on `Result` or the `ok_or` method on `Option` to do the conversion explicitly. So far, all the `main` functions we’ve used return `()`. The `main` function is -special because it’s the entry and exit point of executable programs, and there -are restrictions on what its return type can be for the programs to behave as -expected. +special because it’s the entry point and exit point of an executable program, +and there are restrictions on what its return type can be for the program to +behave as expected. -Luckily, `main` can also return a `Result<(), E>`. Listing 9-12 has the -code from Listing 9-10 but we’ve changed the return type of `main` to be +Luckily, `main` can also return a `Result<(), E>`. Listing 9-12 has the code +from Listing 9-10, but we’ve changed the return type of `main` to be `Result<(), Box<dyn Error>>` and added a return value `Ok(())` to the end. This -code will now compile: +code will now compile. + +Filename: src/main.rs ``` use std::error::Error; @@ -839,51 +788,36 @@ fn main() -> Result<(), Box<dyn Error>> { } ``` -<!--- -The move to `Box<dyn Error>` isn't unexpected for an experienced Rust -developer, but I wonder if we should keep `std::io::Error` here to keep with -the flow of the previous examples? - -I think my instinct was to mention this since we don't use the flexibility -the trait object gives us. Instead, we switch to explaining how exit codes -work with Result values. -/JT ---> -<!-- The idea here was to give the reader code that will work in the future no -matter what errors they're trying to return from main. If we put in -std::io::Error, it'll work for this example, but probably not in the reader's -own projects. I've added a sentence to the end of the paragraph after Listing -9-12's caption to explain this thinking. /Carol --> - Listing 9-12: Changing `main` to return `Result<(), E>` allows the use of the -`?` operator on `Result` values - -The `Box<dyn Error>` type is a *trait object*, which we’ll talk about in the -“Using Trait Objects that Allow for Values of Different Types†section in -Chapter 17. For now, you can read `Box<dyn Error>` to mean “any kind of error.†-Using `?` on a `Result` value in a `main` function with the error type `Box<dyn -Error>` is allowed, because it allows any `Err` value to be returned early. -Even though the body of this `main` function will only ever return errors of -type `std::io::Error`, by specifying `Box<dyn Error>`, this signature will -continue to be correct even if more code that returns other errors is added to -the body of `main`. - -When a `main` function returns a `Result<(), E>`, the executable will -exit with a value of `0` if `main` returns `Ok(())` and will exit with a -nonzero value if `main` returns an `Err` value. Executables written in C return -integers when they exit: programs that exit successfully return the integer -`0`, and programs that error return some integer other than `0`. Rust also -returns integers from executables to be compatible with this convention. +`?` operator on `Result` values. + +The `Box<dyn Error>` type is a *trait object*, which we’ll talk about in “Using +Trait Objects That Allow for Values of Different Types†on page XX. For now, +you can read `Box<dyn Error>` to mean “any kind of error.†Using `?` on a +`Result` value in a `main` function with the error type `Box<dyn Error>` is +allowed because it allows any `Err` value to be returned early. Even though the +body of this `main` function will only ever return errors of type +`std::io::Error`, by specifying `Box<dyn Error>`, this signature will continue +to be correct even if more code that returns other errors is added to the body +of `main`. + +When a `main` function returns a `Result<(), E>`, the executable will exit with +a value of `0` if `main` returns `Ok(())` and will exit with a nonzero value if +`main` returns an `Err` value. Executables written in C return integers when +they exit: programs that exit successfully return the integer `0`, and programs +that error return some integer other than `0`. Rust also returns integers from +executables to be compatible with this convention. The `main` function may return any types that implement the `std::process::Termination` trait, which contains a function `report` that -returns an `ExitCode` Consult the standard library documentation for more +returns an `ExitCode`. Consult the standard library documentation for more information on implementing the `Termination` trait for your own types. Now that we’ve discussed the details of calling `panic!` or returning `Result`, let’s return to the topic of how to decide which is appropriate to use in which cases. -## To `panic!` or Not to `panic!` +## To panic! or Not to panic! So how do you decide when you should call `panic!` and when you should return `Result`? When code panics, there’s no way to recover. You could call `panic!` @@ -904,11 +838,11 @@ some general guidelines on how to decide whether to panic in library code. ### Examples, Prototype Code, and Tests -When you’re writing an example to illustrate some concept, also including robust -error-handling code can make the example less clear. In -examples, it’s understood that a call to a method like `unwrap` that could -panic is meant as a placeholder for the way you’d want your application to -handle errors, which can differ based on what the rest of your code is doing. +When you’re writing an example to illustrate some concept, also including +robust error-handling code can make the example less clear. In examples, it’s +understood that a call to a method like `unwrap` that could panic is meant as a +placeholder for the way you’d want your application to handle errors, which can +differ based on what the rest of your code is doing. Similarly, the `unwrap` and `expect` methods are very handy when prototyping, before you’re ready to decide how to handle errors. They leave clear markers in @@ -931,17 +865,6 @@ that you’ll never have an `Err` variant, it’s perfectly acceptable to call `unwrap`, and even better to document the reason you think you’ll never have an `Err` variant in the `expect` text. Here’s an example: -<!--- -Some Rust devs may have a nuanced take on the above, myself included. I'd say -you'd be safer to use `.expect(...)` and put as the argument the reason why it -should never fail. If, in the future it ever *does* fail for some reason -(probably as a result of many code fixes over time), then you've got a message -to start with telling you what the original expectation was. -/JT ---> -<!-- I agree with this and reinforcing this best practice; I've changed the -`unwrap` to `expect` and demonstrated a good message. I still don't want to -shame people too much for using `unwrap`, though. /Carol --> - ``` use std::net::IpAddr; @@ -960,25 +883,24 @@ valid IP address. If the IP address string came from a user rather than being hardcoded into the program and therefore *did* have a possibility of failure, we’d definitely want to handle the `Result` in a more robust way instead. Mentioning the assumption that this IP address is hardcoded will prompt us to -change `expect` to better error handling code if in the future, we need to get +change `expect` to better error-handling code if, in the future, we need to get the IP address from some other source instead. ### Guidelines for Error Handling -It’s advisable to have your code panic when it’s possible that your code -could end up in a bad state. In this context, a *bad state* is when some -assumption, guarantee, contract, or invariant has been broken, such as when -invalid values, contradictory values, or missing values are passed to your -code—plus one or more of the following: +It’s advisable to have your code panic when it’s possible that your code could +end up in a bad state. In this context, a *bad state* is when some assumption, +guarantee, contract, or invariant has been broken, such as when invalid values, +contradictory values, or missing values are passed to your code—plus one or +more of the following: * The bad state is something that is unexpected, as opposed to something that - will likely happen occasionally, like a user entering data in the wrong - format. +will likely happen occasionally, like a user entering data in the wrong format. * Your code after this point needs to rely on not being in this bad state, - rather than checking for the problem at every step. +rather than checking for the problem at every step. * There’s not a good way to encode this information in the types you use. We’ll - work through an example of what we mean in the “Encoding States and Behavior - as Types†section of Chapter 17. +work through an example of what we mean in “Encoding States and Behavior as +Types†on page XX. If someone calls your code and passes in values that don’t make sense, it’s best to return an error if you can so the user of the library can decide what @@ -989,24 +911,6 @@ development. Similarly, `panic!` is often appropriate if you’re calling external code that is out of your control and it returns an invalid state that you have no way of fixing. -<!--- -Disagree a bit with the above. I don't think libraries should ever panic. They -should always be written defensively so they can be used in a broader range of -applications, which include applications where crashing could result in data -loss. - -Rather than crashing, libraries can encode the reasons they failed based on the -user's input into an error that can be returned to the user. - -In practice, the only time the application should absolutely crash is if -continuing could bring harm to the user's machine, their data, filesystem, and -so on. Otherwise, the user should just be given a warning that the operation -couldn't be completed successfully, so they can take their next action. If we -crash, unfortunately the user never gets that choice. -/JT ---> -<!-- I think we actually agree here but the original text wasn't clear enough; -I've edited. /Carol --> - However, when failure is expected, it’s more appropriate to return a `Result` than to make a `panic!` call. Examples include a parser being given malformed data or an HTTP request returning a status that indicates you have hit a rate @@ -1022,25 +926,12 @@ an out-of-bounds memory access: trying to access memory that doesn’t belong to the current data structure is a common security problem. Functions often have *contracts*: their behavior is only guaranteed if the inputs meet particular requirements. Panicking when the contract is violated makes sense because a -contract violation always indicates a caller-side bug and it’s not a kind of +contract violation always indicates a caller-side bug, and it’s not a kind of error you want the calling code to have to explicitly handle. In fact, there’s no reasonable way for calling code to recover; the calling *programmers* need to fix the code. Contracts for a function, especially when a violation will cause a panic, should be explained in the API documentation for the function. -<!--- -The wording of the first sentence in the above paragraph reads like we should -panic on invalid data, but in the previous paragraph we say malformed data -should be a `Result`. The rest makes sense, where the spirit of when the stdlib -panics is less about invalid data and more about when the user will be put at -risk. -/JT ---> -<!-- I think we were trying to draw a distinction between "malformed" and -"invalid" values that perhaps wasn't very clear. I've tried to clarify by -adding "could put a user at risk", but I don't really want to get into the -specifics of this because only a subset of readers will be writing code like -this... /Carol --> - However, having lots of error checks in all of your functions would be verbose and annoying. Fortunately, you can use Rust’s type system (and thus the type checking done by the compiler) to do many of the checks for you. If your @@ -1064,16 +955,18 @@ numbers before checking it against our secret number; we only validated that the guess was positive. In this case, the consequences were not very dire: our output of “Too high†or “Too low†would still be correct. But it would be a useful enhancement to guide the user toward valid guesses and have different -behavior when a user guesses a number that’s out of range versus when a user -types, for example, letters instead. +behavior when the user guesses a number that’s out of range versus when the +user types, for example, letters instead. One way to do this would be to parse the guess as an `i32` instead of only a `u32` to allow potentially negative numbers, and then add a check for the number being in range, like so: +Filename: src/main.rs + ``` loop { - // --snip-- + --snip-- let guess: i32 = match guess.trim().parse() { Ok(num) => num, @@ -1086,7 +979,7 @@ loop { } match guess.cmp(&secret_number) { - // --snip-- + --snip-- } ``` @@ -1096,7 +989,7 @@ and ask for another guess. After the `if` expression, we can proceed with the comparisons between `guess` and the secret number knowing that `guess` is between 1 and 100. -However, this is not an ideal solution: if it was absolutely critical that the +However, this is not an ideal solution: if it were absolutely critical that the program only operated on values between 1 and 100, and it had many functions with this requirement, having a check like this in every function would be tedious (and might impact performance). @@ -1108,71 +1001,60 @@ confidently use the values they receive. Listing 9-13 shows one way to define a `Guess` type that will only create an instance of `Guess` if the `new` function receives a value between 1 and 100. +Filename: src/lib.rs + ``` -pub struct Guess { +1 pub struct Guess { value: i32, } impl Guess { - pub fn new(value: i32) -> Guess { - if value < 1 || value > 100 { - panic!("Guess value must be between 1 and 100, got {}.", value); + 2 pub fn new(value: i32) -> Guess { + 3 if value < 1 || value > 100 { + 4 panic!( + "Guess value must be between 1 and 100, got {}.", + value + ); } - Guess { value } + 5 Guess { value } } - pub fn value(&self) -> i32 { + 6 pub fn value(&self) -> i32 { self.value } } ``` -<!--- -The above example feels a bit off to me. We talk earlier about user input being -a prime candidate for recoverable errors, and then we talk about encoding only -proper states in the type system. But this examples seems to work with user -input and panic if it's not correct, rather than using recoverable errors or -encoding the state into the type. - -Maybe you could have them guess rock/paper/scissors and encode the -rock/paper/scissor as three enum values, and if they type something outside of -that, we don't allow it. Otherwise we create an enum of that value. -/JT ---> -<!-- The point about this listing panicking is valid, but I disagree a little. -I think this is encoding only valid states into the type system. Also, Chapter -11 builds on this example to show how to use `should_panic`, so I'm going to -leave this the way it is. /Carol --> - Listing 9-13: A `Guess` type that will only continue with values between 1 and 100 -First, we define a struct named `Guess` that has a field named `value` that -holds an `i32`. This is where the number will be stored. +First we define a struct named `Guess` that has a field named `value` that +holds an `i32` [1]. This is where the number will be stored. Then we implement an associated function named `new` on `Guess` that creates -instances of `Guess` values. The `new` function is defined to have one +instances of `Guess` values [2]. The `new` function is defined to have one parameter named `value` of type `i32` and to return a `Guess`. The code in the -body of the `new` function tests `value` to make sure it’s between 1 and 100. -If `value` doesn’t pass this test, we make a `panic!` call, which will alert -the programmer who is writing the calling code that they have a bug they need -to fix, because creating a `Guess` with a `value` outside this range would +body of the `new` function tests `value` to make sure it’s between 1 and 100 +[3]. If `value` doesn’t pass this test, we make a `panic!` call [4], which will +alert the programmer who is writing the calling code that they have a bug they +need to fix, because creating a `Guess` with a `value` outside this range would violate the contract that `Guess::new` is relying on. The conditions in which `Guess::new` might panic should be discussed in its public-facing API documentation; we’ll cover documentation conventions indicating the possibility of a `panic!` in the API documentation that you create in Chapter 14. If `value` does pass the test, we create a new `Guess` with its `value` field set -to the `value` parameter and return the `Guess`. +to the `value` parameter and return the `Guess` [5]. Next, we implement a method named `value` that borrows `self`, doesn’t have any -other parameters, and returns an `i32`. This kind of method is sometimes called -a *getter*, because its purpose is to get some data from its fields and return -it. This public method is necessary because the `value` field of the `Guess` -struct is private. It’s important that the `value` field be private so code -using the `Guess` struct is not allowed to set `value` directly: code outside -the module *must* use the `Guess::new` function to create an instance of -`Guess`, thereby ensuring there’s no way for a `Guess` to have a `value` that -hasn’t been checked by the conditions in the `Guess::new` function. +other parameters, and returns an `i32` [6]. This kind of method is sometimes +called a *getter* because its purpose is to get some data from its fields and +return it. This public method is necessary because the `value` field of the +`Guess` struct is private. It’s important that the `value` field be private so +code using the `Guess` struct is not allowed to set `value` directly: code +outside the module *must* use the `Guess::new` function to create an instance +of `Guess`, thereby ensuring there’s no way for a `Guess` to have a `value` +that hasn’t been checked by the conditions in the `Guess::new` function. A function that has a parameter or returns only numbers between 1 and 100 could then declare in its signature that it takes or returns a `Guess` rather than an @@ -1180,7 +1062,7 @@ then declare in its signature that it takes or returns a `Guess` rather than an ## Summary -Rust’s error handling features are designed to help you write more robust code. +Rust’s error-handling features are designed to help you write more robust code. The `panic!` macro signals that your program is in a state it can’t handle and lets you tell the process to stop instead of trying to proceed with invalid or incorrect values. The `Result` enum uses Rust’s type system to indicate that @@ -1193,17 +1075,3 @@ Now that you’ve seen useful ways that the standard library uses generics with the `Option` and `Result` enums, we’ll talk about how generics work and how you can use them in your code. -<!--- -A meta comment: the coverage of `panic!` here feels helpful in terms of giving -a more complete understanding of Rust, but in practice (and this may depend -on domain), using `panic!` should be a fairly limited thing. - -Something I noticed we don't touch on but may want to is panic hooks, as -unrecoverable errors isn't exactly true. You can recover from an unwinding -panic if you need to code defensively against, say, a dependency panicking and -you don't want your app to go down as a result. -/JT ---> -<!-- Yeahhh I don't want to mention panic hooks, one because I don't think most -people will need to think about them or implement one, and two because a subset -of people will look at that and think "oh look, exception handling!" which... -is not what it's for. /Carol --> diff --git a/src/doc/book/nostarch/chapter10.md b/src/doc/book/nostarch/chapter10.md index 2030c335e..bb8919d79 100644 --- a/src/doc/book/nostarch/chapter10.md +++ b/src/doc/book/nostarch/chapter10.md @@ -15,13 +15,13 @@ how they relate to other generics without knowing what will be in their place when compiling and running the code. Functions can take parameters of some generic type, instead of a concrete type -like `i32` or `String`, in the same way a function takes parameters with -unknown values to run the same code on multiple concrete values. In fact, we’ve -already used generics in Chapter 6 with `Option<T>`, Chapter 8 with `Vec<T>` -and `HashMap<K, V>`, and Chapter 9 with `Result<T, E>`. In this chapter, you’ll +like `i32` or `String`, in the same way they take parameters with unknown +values to run the same code on multiple concrete values. In fact, we’ve already +used generics in Chapter 6 with `Option<T>`, in Chapter 8 with `Vec<T>` and +`HashMap<K, V>`, and in Chapter 9 with `Result<T, E>`. In this chapter, you’ll explore how to define your own types, functions, and methods with generics! -First, we’ll review how to extract a function to reduce code duplication. We’ll +First we’ll review how to extract a function to reduce code duplication. We’ll then use the same technique to make a generic function from two functions that differ only in the types of their parameters. We’ll also explain how to use generic types in struct and enum definitions. @@ -39,47 +39,47 @@ help. ## Removing Duplication by Extracting a Function Generics allow us to replace specific types with a placeholder that represents -multiple types to remove code duplication. -Before diving into generics syntax, then, let’s first look at how to remove -duplication in a way that doesn’t involve generic types by extracting a -function that replaces specific values with a placeholder that represents -multiple values. Then we’ll apply the same technique to extract a generic -function! By looking at how to recognize duplicated code you can extract into a -function, you’ll start to recognize duplicated code that can use generics. +multiple types to remove code duplication. Before diving into generics syntax, +let’s first look at how to remove duplication in a way that doesn’t involve +generic types by extracting a function that replaces specific values with a +placeholder that represents multiple values. Then we’ll apply the same +technique to extract a generic function! By looking at how to recognize +duplicated code you can extract into a function, you’ll start to recognize +duplicated code that can use generics. -We begin with the short program in Listing 10-1 that finds the largest number -in a list. +We’ll begin with the short program in Listing 10-1 that finds the largest +number in a list. Filename: src/main.rs ``` fn main() { - let number_list = vec![34, 50, 25, 100, 65]; + 1 let number_list = vec![34, 50, 25, 100, 65]; - let mut largest = &number_list[0]; + 2 let mut largest = &number_list[0]; - for number in &number_list { - if number > largest { - largest = number; + 3 for number in &number_list { + 4 if number > largest { + 5 largest = number; } } - println!("The largest number is {}", largest); + println!("The largest number is {largest}"); } ``` Listing 10-1: Finding the largest number in a list of numbers -We store a list of integers in the variable `number_list` and place a reference -to the first number in the list in a variable named `largest`. We then iterate -through all the numbers in the list, and if the current number is greater than -the number stored in `largest`, replace the reference in that variable. -However, if the current number is less than or equal to the largest number seen -so far, the variable doesn’t change, and the code moves on to the next number -in the list. After considering all the numbers in the list, `largest` should -refer to the largest number, which in this case is 100. +We store a list of integers in the variable `number_list` [1] and place a +reference to the first number in the list in a variable named `largest` [2]. We +then iterate through all the numbers in the list [3], and if the current number +is greater than the number stored in `largest` [4], we replace the reference in +that variable [5]. However, if the current number is less than or equal to the +largest number seen so far, the variable doesn’t change, and the code moves on +to the next number in the list. After considering all the numbers in the list, +`largest` should refer to the largest number, which in this case is 100. -We've now been tasked with finding the largest number in two different lists of +We’ve now been tasked with finding the largest number in two different lists of numbers. To do so, we can choose to duplicate the code in Listing 10-1 and use the same logic at two different places in the program, as shown in Listing 10-2. @@ -97,7 +97,7 @@ fn main() { } } - println!("The largest number is {}", largest); + println!("The largest number is {largest}"); let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8]; @@ -109,7 +109,7 @@ fn main() { } } - println!("The largest number is {}", largest); + println!("The largest number is {largest}"); } ``` @@ -148,12 +148,12 @@ fn main() { let number_list = vec![34, 50, 25, 100, 65]; let result = largest(&number_list); - println!("The largest number is {}", result); + println!("The largest number is {result}"); let number_list = vec![102, 34, 6000, 89, 54, 2, 43, 8]; let result = largest(&number_list); - println!("The largest number is {}", result); + println!("The largest number is {result}"); } ``` @@ -161,22 +161,15 @@ Listing 10-3: Abstracted code to find the largest number in two lists The `largest` function has a parameter called `list`, which represents any concrete slice of `i32` values we might pass into the function. As a result, -when we call the function, the code runs on the specific values that we pass -in. +when we call the function, the code runs on the specific values that we pass in. In summary, here are the steps we took to change the code from Listing 10-2 to Listing 10-3: -<!--- -"In summary"? -/JT ---> -<!-- I believe "In sum" to be fine, but other people have been confused by it -as well, so I'm ok changing it. /Carol --> - 1. Identify duplicate code. -2. Extract the duplicate code into the body of the function and specify the - inputs and return values of that code in the function signature. -3. Update the two instances of duplicated code to call the function instead. +1. Extract the duplicate code into the body of the function, and specify the +inputs and return values of that code in the function signature. +1. Update the two instances of duplicated code to call the function instead. Next, we’ll use these same steps with generics to reduce code duplication. In the same way that the function body can operate on an abstract `list` instead @@ -201,7 +194,7 @@ parameters and return value. Doing so makes our code more flexible and provides more functionality to callers of our function while preventing code duplication. Continuing with our `largest` function, Listing 10-4 shows two functions that -both find the largest value in a slice. We'll then combine these into a single +both find the largest value in a slice. We’ll then combine these into a single function that uses generics. Filename: src/main.rs @@ -235,16 +228,16 @@ fn main() { let number_list = vec![34, 50, 25, 100, 65]; let result = largest_i32(&number_list); - println!("The largest number is {}", result); + println!("The largest number is {result}"); let char_list = vec!['y', 'm', 'a', 'q']; let result = largest_char(&char_list); - println!("The largest char is {}", result); + println!("The largest char is {result}"); } ``` -Listing 10-4: Two functions that differ only in their names and the types in +Listing 10-4: Two functions that differ only in their names and in the types in their signatures The `largest_i32` function is the one we extracted in Listing 10-3 that finds @@ -255,16 +248,16 @@ 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, 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 one letter, and +Rust’s type-naming convention is CamelCase. 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. Similarly, when we use a type parameter name in a function signature, we have to declare the type parameter name before we use it. To define the generic -`largest` function, place type name declarations inside angle brackets, `<>`, -between the name of the function and the parameter list, like this: +`largest` function, we place type name declarations inside angle brackets, +`<>`, between the name of the function and the parameter list, like this: ``` fn largest<T>(list: &[T]) -> &T { @@ -299,33 +292,33 @@ fn main() { let number_list = vec![34, 50, 25, 100, 65]; let result = largest(&number_list); - println!("The largest number is {}", result); + println!("The largest number is {result}"); let char_list = vec!['y', 'm', 'a', 'q']; let result = largest(&char_list); - println!("The largest char is {}", result); + println!("The largest char is {result}"); } ``` Listing 10-5: The `largest` function using generic type parameters; this -doesn’t yet compile yet +doesn’t compile yet If we compile this code right now, we’ll get this error: ``` -error[E0369]: binary operation `>` cannot be applied to type `T` +error[E0369]: binary operation `>` cannot be applied to type `&T` --> src/main.rs:5:17 | 5 | if item > largest { - | ---- ^ ------- T + | ---- ^ ------- &T | | - | T + | &T | help: consider restricting type parameter `T` | -1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> T { - | ^^^^^^^^^^^^^^^^^^^^^^ +1 | fn largest<T: std::cmp::PartialOrd>(list: &[T]) -> &T { + | ++++++++++++++++++++++ ``` The help text mentions `std::cmp::PartialOrd`, which is a *trait*, and we’re @@ -334,31 +327,11 @@ states that the body of `largest` won’t work for all possible types that `T` could be. Because we want to compare values of type `T` in the body, we can only use types whose values can be ordered. To enable comparisons, the standard library has the `std::cmp::PartialOrd` trait that you can implement on types -(see Appendix C for more on this trait). By following the help text's +(see Appendix C for more on this trait). By following the help text’s suggestion, we restrict the types valid for `T` to only those that implement `PartialOrd` and this example will compile, because the standard library implements `PartialOrd` on both `i32` and `char`. -<!--- -The wording at the end of the above paragraph feels a little odd. For the -"You’ll learn how to specify that a generic type has a particular trait in the -“Traits as Parameters†section." -- the error message above tells you how to -maybe fix it. - -Well, it *could* fix it but the way the example is written adds multiple -constraints. - -Do we want to leave this example unfinished and move onto other topics for a -bit or revise the example so it's more self-contained, allowing the compiler to -help us and later revisit after we've learned more? -/JT ---> -<!-- I've modified the example and explanation just slightly so that only -adding the `PartialOrd` trait as suggested here will fix it completely, perhaps -leaving the reader hanging a little bit less. It's really hard to teach -generics and trait bounds, though, because you can't do much with generics -unless you have trait bounds too (and can't learn why you'd want trait bounds -without knowing about generics). /Carol --> - ### In Struct Definitions We can also define structs to use a generic type parameter in one or more @@ -368,9 +341,9 @@ fields using the `<>` syntax. Listing 10-6 defines a `Point<T>` struct to hold Filename: src/main.rs ``` -struct Point<T> { - x: T, - y: T, +1 struct Point<T> { + 2 x: T, + 3 y: T, } fn main() { @@ -382,9 +355,10 @@ fn main() { Listing 10-6: A `Point<T>` struct that holds `x` and `y` values of type `T` The syntax for using generics in struct definitions is similar to that used in -function definitions. First, we declare the name of the type parameter inside -angle brackets just after the name of the struct. Then we use the generic type -in the struct definition where we would otherwise specify concrete data types. +function definitions. First we declare the name of the type parameter inside +angle brackets just after the name of the struct [1]. Then we use the generic +type in the struct definition where we would otherwise specify concrete data +types [23]. Note that because we’ve used only one generic type to define `Point<T>`, this definition says that the `Point<T>` struct is generic over some type `T`, and @@ -408,42 +382,18 @@ fn main() { Listing 10-7: The fields `x` and `y` must be the same type because both have the same generic data type `T`. -In this example, when we assign the integer value 5 to `x`, we let the compiler -know that the generic type `T` will be an integer for this instance of -`Point<T>`. Then when we specify 4.0 for `y`, which we’ve defined to have the +In this example, when we assign the integer value `5` to `x`, we let the +compiler know that the generic type `T` will be an integer for this instance of +`Point<T>`. Then when we specify `4.0` for `y`, which we’ve defined to have the same type as `x`, we’ll get a type mismatch error like this: -<!--- -Not sure how or where we might want to call this out, but this is also how -type inference in Rust works. If we don't know the type, we look for how it's -used. That fresh type becomes a concrete type, and any use after that which -is different than we expect becomes an error. - -fn main() { - let mut x; - - x = 5; - x = 4.0; -} - -Also gives: - | -2 | let mut x; - | ----- expected due to the type of this binding -... -5 | x = 4.0; - | ^^^ expected integer, found floating-point number - -/JT ---> -<!-- Yeah, it's kind of neat trivia, but doesn't really fit here I don't think. -/Carol --> - ``` error[E0308]: mismatched types --> src/main.rs:7:38 | 7 | let wont_work = Point { x: 5, y: 4.0 }; - | ^^^ expected integer, found floating-point number + | ^^^ expected integer, found floating- +point number ``` To define a `Point` struct where `x` and `y` are both generics but could have @@ -471,7 +421,7 @@ values of different types Now all the instances of `Point` shown are allowed! You can use as many generic type parameters in a definition as you want, but using more than a few makes -your code hard to read. If you're finding you need lots of generic types in +your code hard to read. If you’re finding you need lots of generic types in your code, it could indicate that your code needs restructuring into smaller pieces. @@ -521,7 +471,7 @@ avoid duplication by using generic types instead. ### In Method Definitions We can implement methods on structs and enums (as we did in Chapter 5) and use -generic types in their definitions, too. Listing 10-9 shows the `Point<T>` +generic types in their definitions too. Listing 10-9 shows the `Point<T>` struct we defined in Listing 10-6 with a method named `x` implemented on it. Filename: src/main.rs @@ -545,16 +495,6 @@ fn main() { } ``` -<!--- - -The above code gives a warning for the unused `y`. Maybe we can print both -`x` and `y`? - -/JT ---> -<!-- In general, I'm not worried about unused code warnings, there's a lot of -examples that have unused code because they're small examples. I don't think -there's much value in adding a method and printing `y` as well. /Carol --> - Listing 10-9: Implementing a method named `x` on the `Point<T>` struct that will return a reference to the `x` field of type `T` @@ -593,7 +533,7 @@ This code means the type `Point<f32>` will have a `distance_from_origin` method; other instances of `Point<T>` where `T` is not of type `f32` will not have this method defined. The method measures how far our point is from the point at coordinates (0.0, 0.0) and uses mathematical operations that are -available only for floating point types. +available only for floating-point types. Generic type parameters in a struct definition aren’t always the same as those you use in that same struct’s method signatures. Listing 10-11 uses the generic @@ -610,8 +550,11 @@ struct Point<X1, Y1> { y: Y1, } -impl<X1, Y1> Point<X1, Y1> { - fn mixup<X2, Y2>(self, other: Point<X2, Y2>) -> Point<X1, Y2> { +1 impl<X1, Y1> Point<X1, Y1> { + 2 fn mixup<X2, Y2>( + self, + other: Point<X2, Y2>, + ) -> Point<X1, Y2> { Point { x: self.x, y: other.y, @@ -620,12 +563,12 @@ impl<X1, Y1> Point<X1, Y1> { } fn main() { - let p1 = Point { x: 5, y: 10.4 }; - let p2 = Point { x: "Hello", y: 'c' }; + 3 let p1 = Point { x: 5, y: 10.4 }; + 4 let p2 = Point { x: "Hello", y: 'c' }; - let p3 = p1.mixup(p2); + 5 let p3 = p1.mixup(p2); - println!("p3.x = {}, p3.y = {}", p3.x, p3.y); + 6 println!("p3.x = {}, p3.y = {}", p3.x, p3.y); } ``` @@ -633,25 +576,25 @@ Listing 10-11: A method that uses generic types different from its struct’s definition In `main`, we’ve defined a `Point` that has an `i32` for `x` (with value `5`) -and an `f64` for `y` (with value `10.4`). The `p2` variable is a `Point` struct -that has a string slice for `x` (with value `"Hello"`) and a `char` for `y` -(with value `c`). Calling `mixup` on `p1` with the argument `p2` gives us `p3`, -which will have an `i32` for `x`, because `x` came from `p1`. The `p3` variable -will have a `char` for `y`, because `y` came from `p2`. The `println!` macro -call will print `p3.x = 5, p3.y = c`. +and an `f64` for `y` (with value `10.4` [3]). The `p2` variable is a `Point` +struct that has a string slice for `x` (with value `"Hello"`) and a `char` for +`y` (with value `c` [4]). Calling `mixup` on `p1` with the argument `p2` gives +us `p3` [5], which will have an `i32` for `x` because `x` came from `p1`. The +`p3` variable will have a `char` for `y` because `y` came from `p2`. The +`println!` macro call [6] will print `p3.x = 5, p3.y = c`. The purpose of this example is to demonstrate a situation in which some generic parameters are declared with `impl` and some are declared with the method definition. Here, the generic parameters `X1` and `Y1` are declared after -`impl` because they go with the struct definition. The generic parameters `X2` -and `Y2` are declared after `fn mixup`, because they’re only relevant to the -method. +`impl` [1] because they go with the struct definition. The generic parameters +`X2` and `Y2` are declared after `fn mixup` [2] because they’re only relevant +to the 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 run any -slower than it would with concrete types. +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 generics at compile time. *Monomorphization* is the process of turning generic @@ -676,15 +619,6 @@ is `f64`. As such, it expands the generic definition of `Option<T>` into two definitions specialized to `i32` and `f64`, thereby replacing the generic definition with the specific ones. -<!--- - -We may want to be clear in the above it doesn't actually do this, as you -wouldn't be able to write `enum Option_i32` in your code as it would clash. - -/JT ---> -<!-- I've reworded the last sentence in the above paragraph and the next -sentence to hopefully sidestep the issue JT pointed out. /Carol --> - The monomorphized version of the code looks similar to the following (the compiler uses different names than what we’re using here for illustration): @@ -716,13 +650,13 @@ at runtime. ## Traits: Defining Shared Behavior -A *trait* defines functionality a particular type has and can share with other -types. We can use traits to define shared behavior in an abstract way. We can -use *trait bounds* to specify that a generic type can be any type that has +A *trait* defines the functionality a particular type has and can share with +other types. We can use traits to define shared behavior in an abstract way. We +can use *trait bounds* to specify that a generic type can be any type that has certain behavior. > Note: Traits are similar to a feature often called *interfaces* in other -> languages, although with some differences. +languages, although with some differences. ### Defining a Trait @@ -733,15 +667,15 @@ define a set of behaviors necessary to accomplish some purpose. For example, let’s say we have multiple structs that hold various kinds and amounts of text: a `NewsArticle` struct that holds a news story filed in a -particular location and a `Tweet` that can have at most 280 characters along +particular location and a `Tweet` that can have, at most, 280 characters along with metadata that indicates whether it was a new tweet, a retweet, or a reply to another tweet. We want to make a media aggregator library crate named `aggregator` that can display summaries of data that might be stored in a `NewsArticle` or `Tweet` -instance. To do this, we need a summary from each type, and we’ll request -that summary by calling a `summarize` method on an instance. Listing 10-12 -shows the definition of a public `Summary` trait that expresses this behavior. +instance. To do this, we need a summary from each type, and we’ll request that +summary by calling a `summarize` method on an instance. Listing 10-12 shows the +definition of a public `Summary` trait that expresses this behavior. Filename: src/lib.rs @@ -755,7 +689,7 @@ Listing 10-12: A `Summary` trait that consists of the behavior provided by a `summarize` method Here, we declare a trait using the `trait` keyword and then the trait’s name, -which is `Summary` in this case. We’ve also declared the trait as `pub` so that +which is `Summary` in this case. We also declare the trait as `pub` so that crates depending on this crate can make use of this trait too, as we’ll see in a few examples. Inside the curly brackets, we declare the method signatures that describe the behaviors of the types that implement this trait, which in @@ -768,7 +702,7 @@ that any type that has the `Summary` trait will have the method `summarize` defined with this signature exactly. A trait can have multiple methods in its body: the method signatures are listed -one per line and each line ends in a semicolon. +one per line, and each line ends in a semicolon. ### Implementing a Trait on a Type @@ -777,7 +711,7 @@ we can implement it on the types in our media aggregator. Listing 10-13 shows an implementation of the `Summary` trait on the `NewsArticle` struct that uses the headline, the author, and the location to create the return value of `summarize`. For the `Tweet` struct, we define `summarize` as the username -followed by the entire text of the tweet, assuming that tweet content is +followed by the entire text of the tweet, assuming that the tweet content is already limited to 280 characters. Filename: src/lib.rs @@ -792,7 +726,12 @@ pub struct NewsArticle { impl Summary for NewsArticle { fn summarize(&self) -> String { - format!("{}, by {} ({})", self.headline, self.author, self.location) + format!( + "{}, by {} ({})", + self.headline, + self.author, + self.location + ) } } @@ -821,8 +760,6 @@ that the trait definition has defined. Instead of adding a semicolon after each signature, we use curly brackets and fill in the method body with the specific behavior that we want the methods of the trait to have for the particular type. -<!-- NOTE TO ADD SOME NUMBER INDICATORS HERE IN THE WORD FILES --> - Now that the library has implemented the `Summary` trait on `NewsArticle` and `Tweet`, users of the crate can call the trait methods on instances of `NewsArticle` and `Tweet` in the same way we call regular methods. The only @@ -852,23 +789,23 @@ know, people`. Other crates that depend on the `aggregator` crate can also bring the `Summary` trait into scope to implement `Summary` on their own types. One restriction to -note is that we can implement a trait on a type only if at least one of the -trait or the type is local to our crate. For example, we can implement standard +note is that we can implement a trait on a type only if either the trait or the +type, or both, are local to our crate. For example, we can implement standard library traits like `Display` on a custom type like `Tweet` as part of our -`aggregator` crate functionality, because the type `Tweet` is local to our +`aggregator` crate functionality because the type `Tweet` is local to our `aggregator` crate. We can also implement `Summary` on `Vec<T>` in our -`aggregator` crate, because the trait `Summary` is local to our `aggregator` +`aggregator` crate because the trait `Summary` is local to our `aggregator` crate. But we can’t implement external traits on external types. For example, we can’t -implement the `Display` trait on `Vec<T>` within our `aggregator` crate, -because `Display` and `Vec<T>` are both defined in the standard library and -aren’t local to our `aggregator` crate. This restriction is part of a property -called *coherence*, and more specifically the *orphan rule*, so named because -the parent type is not present. This rule ensures that other people’s code -can’t break your code and vice versa. Without the rule, two crates could -implement the same trait for the same type, and Rust wouldn’t know which -implementation to use. +implement the `Display` trait on `Vec<T>` within our `aggregator` crate because +`Display` and `Vec<T>` are both defined in the standard library and aren’t +local to our `aggregator` crate. This restriction is part of a property called +*coherence*, and more specifically the *orphan rule*, so named because the +parent type is not present. This rule ensures that other people’s code can’t +break your code and vice versa. Without the rule, two crates could implement +the same trait for the same type, and Rust wouldn’t know which implementation +to use. ### Default Implementations @@ -877,7 +814,7 @@ in a trait instead of requiring implementations for all methods on every type. Then, as we implement the trait on a particular type, we can keep or override each method’s default behavior. -In Listing 10-14 we specify a default string for the `summarize` method of the +In Listing 10-14, we specify a default string for the `summarize` method of the `Summary` trait instead of only defining the method signature, as we did in Listing 10-12. @@ -891,8 +828,8 @@ pub trait Summary { } ``` -Listing 10-14: Defining a `Summary` trait with a default implementation of -the `summarize` method +Listing 10-14: Defining a `Summary` trait with a default implementation of the +`summarize` method To use a default implementation to summarize instances of `NewsArticle`, we specify an empty `impl` block with `impl Summary for NewsArticle {}`. @@ -904,7 +841,9 @@ the `summarize` method on an instance of `NewsArticle`, like this: ``` let article = NewsArticle { - headline: String::from("Penguins win the Stanley Cup Championship!"), + headline: String::from( + "Penguins win the Stanley Cup Championship!" + ), location: String::from("Pittsburgh, PA, USA"), author: String::from("Iceburgh"), content: String::from( @@ -936,7 +875,10 @@ pub trait Summary { fn summarize_author(&self) -> String; fn summarize(&self) -> String { - format!("(Read more from {}...)", self.summarize_author()) + format!( + "(Read more from {}...)", + self.summarize_author() + ) } } ``` @@ -956,7 +898,8 @@ After we define `summarize_author`, we can call `summarize` on instances of the `Tweet` struct, and the default implementation of `summarize` will call the definition of `summarize_author` that we’ve provided. Because we’ve implemented `summarize_author`, the `Summary` trait has given us the behavior of the -`summarize` method without requiring us to write any more code. +`summarize` method without requiring us to write any more code. Here’s what +that looks like: ``` let tweet = Tweet { @@ -979,7 +922,7 @@ overriding implementation of that same method. ### Traits as Parameters Now that you know how to define and implement traits, we can explore how to use -traits to define functions that accept many different types. We'll use the +traits to define functions that accept many different types. We’ll use the `Summary` trait we implemented on the `NewsArticle` and `Tweet` types in Listing 10-13 to define a `notify` function that calls the `summarize` method on its `item` parameter, which is of some type that implements the `Summary` @@ -1036,7 +979,7 @@ The generic type `T` specified as the type of the `item1` and `item2` parameters constrains the function such that the concrete type of the value passed as an argument for `item1` and `item2` must be the same. -#### Specifying Multiple Trait Bounds with the `+` Syntax +#### Specifying Multiple Trait Bounds with the + Syntax We can also specify more than one trait bound. Say we wanted `notify` to use display formatting as well as `summarize` on `item`: we specify in the `notify` @@ -1056,14 +999,14 @@ pub fn notify<T: Summary + Display>(item: &T) { With the two trait bounds specified, the body of `notify` can call `summarize` and use `{}` to format `item`. -#### Clearer Trait Bounds with `where` Clauses +#### Clearer Trait Bounds with where Clauses Using too many trait bounds has its downsides. Each generic has its own trait bounds, so functions with multiple generic type parameters can contain lots of trait bound information between the function’s name and its parameter list, making the function signature hard to read. For this reason, Rust has alternate syntax for specifying trait bounds inside a `where` clause after the function -signature. So instead of writing this: +signature. So, instead of writing this: ``` fn some_function<T: Display + Clone, U: Clone + Debug>(t: &T, u: &U) -> i32 { @@ -1073,8 +1016,9 @@ we can use a `where` clause, like this: ``` fn some_function<T, U>(t: &T, u: &U) -> i32 - where T: Display + Clone, - U: Clone + Debug +where + T: Display + Clone, + U: Clone + Debug, { ``` @@ -1082,7 +1026,7 @@ This function’s signature is less cluttered: the function name, parameter list and return type are close together, similar to a function without lots of trait bounds. -### Returning Types that Implement Traits +### Returning Types That Implement Traits We can also use the `impl Trait` syntax in the return position to return a value of some type that implements a trait, as shown here: @@ -1145,22 +1089,17 @@ fn returns_summarizable(switch: bool) -> impl Summary { Returning either a `NewsArticle` or a `Tweet` isn’t allowed due to restrictions around how the `impl Trait` syntax is implemented in the compiler. We’ll cover -how to write a function with this behavior in the “Using Trait Objects That -Allow for Values of Different Types†section of Chapter 17. - -<!-- I've removed the whole "Fixing the `largest` Function with Trait Bounds" -section now that the example is slightly different and adding the one trait -bound as the compiler suggests fixed Listing 10-5 earlier. I've also renumbered -the following listings. /Carol--> +how to write a function with this behavior in “Using Trait Objects That Allow +for Values of Different Types†on page XX. ### Using Trait Bounds to Conditionally Implement Methods By using a trait bound with an `impl` block that uses generic type parameters, we can implement methods conditionally for types that implement the specified traits. For example, the type `Pair<T>` in Listing 10-15 always implements the -`new` function to return a new instance of `Pair<T>` (recall from the “Defining -Methods†section of Chapter 5 that `Self` is a type alias for the type of the -`impl` block, which in this case is `Pair<T>`). But in the next `impl` block, +`new` function to return a new instance of `Pair<T>` (recall from “Defining +Methods†on page XX that `Self` is a type alias for the type of the `impl` +block, which in this case is `Pair<T>`). But in the next `impl` block, `Pair<T>` only implements the `cmp_display` method if its inner type `T` implements the `PartialOrd` trait that enables comparison *and* the `Display` trait that enables printing. @@ -1197,14 +1136,14 @@ on trait bounds We can also conditionally implement a trait for any type that implements another trait. Implementations of a trait on any type that satisfies the trait -bounds are called *blanket implementations* and are extensively used in the +bounds are called *blanket implementations* and are used extensively in the Rust standard library. For example, the standard library implements the `ToString` trait on any type that implements the `Display` trait. The `impl` block in the standard library looks similar to this code: ``` impl<T: Display> ToString for T { - // --snip-- + --snip-- } ``` @@ -1225,48 +1164,27 @@ reduce duplication but also specify to the compiler that we want the generic type to have particular behavior. The compiler can then use the trait bound information to check that all the concrete types used with our code provide the correct behavior. In dynamically typed languages, we would get an error at -runtime if we called a method on a type which didn’t define the method. But Rust -moves these errors to compile time so we’re forced to fix the problems before -our code is even able to run. Additionally, we don’t have to write code that -checks for behavior at runtime because we’ve already checked at compile time. -Doing so improves performance without having to give up the flexibility of -generics. +runtime if we called a method on a type which didn’t define the method. But +Rust moves these errors to compile time so we’re forced to fix the problems +before our code is even able to run. Additionally, we don’t have to write code +that checks for behavior at runtime because we’ve already checked at compile +time. Doing so improves performance without having to give up the flexibility +of generics. ## Validating References with Lifetimes -<!--- - -meta comment: this chapter is already pretty hefty. We just went through both -generics and a whirlwind tour of traits. Lifetimes, while related to generics, -feel like you might want to give a five minute break between them, let those -sink in, and then pick up this topic. - -I noticed a couple topics we may want to touch on above for a bit of -completeness: - -* A closer look at how From/Into work and how they relate to each other. -* Using traits to specialize what you do when returning values. - i.e., Why does `let four: u32 = "4".parse().unwrap();` work? -* Turbofish - -/JT ---> -<!-- These comments are totally valid, but seeing as this revision is already -dragging on later than we were hoping, I don't really want to do large scale -reorganization at this point. /Carol --> - Lifetimes are another kind of generic that we’ve already been using. Rather than ensuring that a type has the behavior we want, lifetimes ensure that references are valid as long as we need them to be. -One detail we didn’t discuss in the “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 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. +One detail we didn’t discuss in “References and Borrowing†on page XX 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 must annotate types only 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 have, so this is going to feel unfamiliar. Although we won’t cover lifetimes in @@ -1282,32 +1200,32 @@ scope. ``` fn main() { - let r; + 1 let r; { - let x = 5; - r = &x; - } + 2 let x = 5; + 3 r = &x; + 4 } - println!("r: {}", r); + 5 println!("r: {r}"); } ``` Listing 10-16: An attempt to use a reference whose value has gone out of scope -> Note: The examples in Listings 10-16, 10-17, and 10-23 declare variables -> without giving them an initial value, so the variable name exists in the -> outer scope. At first glance, this might appear to be in conflict with Rust’s -> having no null values. However, if we try to use a variable before giving it -> a value, we’ll get a compile-time error, which shows that Rust indeed does -> not allow null values. +> Note: The examples in Listing 10-16, 10-17, and 10-23 declare variables +without giving them an initial value, so the variable name exists in the outer +scope. At first glance, this might appear to be in conflict with Rust’s having +no null values. However, if we try to use a variable before giving it a value, +we’ll get a compile-time error, which shows that Rust indeed does not allow +null values. -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 -try to use it. Here is the error message: +The outer scope declares a variable named `r` with no initial value [1], and +the inner scope declares a variable named `x` with the initial value of `5` +[2]. Inside the inner scope, we attempt to set the value of `r` as a reference +to `x` [3]. Then the inner scope ends [4], and we attempt to print the value in +`r` [5]. This code won’t compile because the value that `r` is referring to has +gone out of scope before we try to use it. Here is the error message: ``` error[E0597]: `x` does not live long enough @@ -1318,17 +1236,17 @@ error[E0597]: `x` does not live long enough 7 | } | - `x` dropped here while still borrowed 8 | -9 | println!("r: {}", r); - | - borrow later used here +9 | println!("r: {r}"); + | - borrow later used here ``` -The variable `x` doesn’t “live long enough.†The reason is that `x` will be out -of scope when the inner scope ends on line 7. But `r` is still valid for the -outer scope; because its scope is larger, we say that it “lives longer.†If -Rust allowed this code to work, `r` would be referencing memory that was -deallocated when `x` went out of scope, and anything we tried to do with `r` -wouldn’t work correctly. So how does Rust determine that this code is invalid? -It uses a borrow checker. +The error message says that the variable `x` “does not live long enough.†The +reason is that `x` will be out of scope when the inner scope ends on line 7. +But `r` is still valid for the outer scope; because its scope is larger, we say +that it “lives longer.†If Rust allowed this code to work, `r` would be +referencing memory that was deallocated when `x` went out of scope, and +anything we tried to do with `r` wouldn’t work correctly. So how does Rust +determine that this code is invalid? It uses a borrow checker. ### The Borrow Checker @@ -1345,7 +1263,7 @@ fn main() { r = &x; // | | } // -+ | // | - println!("r: {}", r); // | + println!("r: {r}"); // | } // ---------+ ``` @@ -1359,7 +1277,7 @@ lifetimes and sees that `r` has a lifetime of `'a` but that it refers to memory with a lifetime of `'b`. The program is rejected because `'b` is shorter than `'a`: the subject of the reference doesn’t live as long as the reference. -Listing 10-18 fixes the code so it doesn’t have a dangling reference and +Listing 10-18 fixes the code so it doesn’t have a dangling reference and it compiles without any errors. ``` @@ -1368,7 +1286,7 @@ fn main() { // | let r = &x; // --+-- 'a | // | | - println!("r: {}", r); // | | + println!("r: {r}"); // | | // --+ | } // ----------+ ``` @@ -1399,7 +1317,7 @@ fn main() { let string2 = "xyz"; let result = longest(string1.as_str(), string2); - println!("The longest string is {}", result); + println!("The longest string is {result}"); } ``` @@ -1408,9 +1326,9 @@ longer of two string slices Note that we want the function to take string slices, which are references, rather than strings, because we don’t want the `longest` function to take -ownership of its parameters. Refer to the “String Slices as Parameters†section -in Chapter 4 for more discussion about why the parameters we use in Listing -10-19 are the ones we want. +ownership of its parameters. Refer to “String Slices as Parameters†on page XX +for more discussion about why the parameters we use in Listing 10-19 are the +ones we want. If we try to implement the `longest` function as shown in Listing 10-20, it won’t compile. @@ -1439,11 +1357,12 @@ error[E0106]: missing lifetime specifier 9 | fn longest(x: &str, y: &str) -> &str { | ---- ---- ^ expected named lifetime parameter | - = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `x` or `y` + = help: this function's return type contains a borrowed value, +but the signature does not say whether it is borrowed from `x` or `y` help: consider introducing a named lifetime parameter | 9 | fn longest<'a>(x: &'a str, y: &'a str) -> &'a str { - | ^^^^ ^^^^^^^ ^^^^^^^ ^^^ + | ++++ ++ ++ ++ ``` The help text reveals that the return type needs a generic lifetime parameter @@ -1487,25 +1406,16 @@ reference to an `i32` that also has the lifetime `'a`. &'a mut i32 // a mutable reference with an explicit lifetime ``` -One lifetime annotation by itself doesn’t have much meaning, because the +One lifetime annotation by itself doesn’t have much meaning because the annotations are meant to tell Rust how generic lifetime parameters of multiple references relate to each other. Let’s examine how the lifetime annotations relate to each other in the context of the `longest` function. -<!--- - -The above description is a little hard to follow with a code example. - -/JT ---> -<!-- Rather than fleshing out the code that goes with this description, I've -moved some of the description to the next section to go with the code example -there. /Carol --> - ### Lifetime Annotations in Function Signatures To use lifetime annotations in function signatures, we need to declare the generic *lifetime* parameters inside angle brackets between the function name -and the parameter list, just as we did with generic *type* parameters +and the parameter list, just as we did with generic *type* parameters. We want the signature to express the following constraint: the returned reference will be valid as long as both the parameters are valid. This is the @@ -1579,7 +1489,7 @@ fn main() { { let string2 = String::from("xyz"); let result = longest(string1.as_str(), string2.as_str()); - println!("The longest string is {}", result); + println!("The longest string is {result}"); } } ``` @@ -1589,7 +1499,7 @@ that have different concrete lifetimes In this example, `string1` is valid until the end of the outer scope, `string2` is valid until the end of the inner scope, and `result` references something -that is valid until the end of the inner scope. Run this code, and you’ll see +that is valid until the end of the inner scope. Run this code and you’ll see that the borrow checker approves; it will compile and print `The longest string is long string is long`. @@ -1611,7 +1521,7 @@ fn main() { let string2 = String::from("xyz"); result = longest(string1.as_str(), string2.as_str()); } - println!("The longest string is {}", result); + println!("The longest string is {result}"); } ``` @@ -1624,11 +1534,12 @@ error[E0597]: `string2` does not live long enough --> src/main.rs:6:44 | 6 | result = longest(string1.as_str(), string2.as_str()); - | ^^^^^^^ borrowed value does not live long enough + | ^^^^^^^^^^^^^^^^ borrowed value +does not live long enough 7 | } | - `string2` dropped here while still borrowed -8 | println!("The longest string is {}", result); - | ------ borrow later used here +8 | println!("The longest string is {result}"); + | ------ borrow later used here ``` The error shows that for `result` to be valid for the `println!` statement, @@ -1637,7 +1548,7 @@ this because we annotated the lifetimes of the function parameters and return values using the same lifetime parameter `'a`. As humans, we can look at this code and see that `string1` is longer than -`string2` and therefore `result` will contain a reference to `string1`. +`string2`, and therefore, `result` will contain a reference to `string1`. Because `string1` has not gone out of scope yet, a reference to `string1` will still be valid for the `println!` statement. However, the compiler can’t see that the reference is valid in this case. We’ve told Rust that the lifetime of @@ -1693,14 +1604,12 @@ lifetime is not related to the lifetime of the parameters at all. Here is the error message we get: ``` -error[E0515]: cannot return value referencing local variable `result` +error[E0515]: cannot return reference to local variable `result` --> src/main.rs:11:5 | 11 | result.as_str() - | ------^^^^^^^^^ - | | - | returns a value referencing data owned by the current function - | `result` is borrowed here + | ^^^^^^^^^^^^^^^ returns a reference to data owned by the +current function ``` The problem is that `result` goes out of scope and gets cleaned up at the end @@ -1718,29 +1627,27 @@ would create dangling pointers or otherwise violate memory safety. ### Lifetime Annotations in Struct Definitions -So far, the structs we’ve defined all hold owned types. We can define structs to -hold references, but in that case we would need to add a lifetime annotation on -every reference in the struct’s definition. Listing 10-24 has a struct named +So far, the structs we’ve defined all hold owned types. We can define structs +to hold references, but in that case we would need to add a lifetime annotation +on every reference in the struct’s definition. Listing 10-24 has a struct named `ImportantExcerpt` that holds a string slice. -<!--- - -nit: "So far, the structs we've *defined* all hold owned types" - -/JT ---> -<!-- Fixed! /Carol --> - Filename: src/main.rs ``` -struct ImportantExcerpt<'a> { - part: &'a str, +1 struct ImportantExcerpt<'a> { + 2 part: &'a str, } fn main() { - let novel = String::from("Call me Ishmael. Some years ago..."); - let first_sentence = novel.split('.').next().expect("Could not find a '.'"); - let i = ImportantExcerpt { + 3 let novel = String::from( + "Call me Ishmael. Some years ago..." + ); + 4 let first_sentence = novel + .split('.') + .next() + .expect("Could not find a '.'"); + 5 let i = ImportantExcerpt { part: first_sentence, }; } @@ -1749,25 +1656,25 @@ fn main() { Listing 10-24: A struct that holds a reference, requiring a lifetime annotation This struct has the single field `part` that holds a string slice, which is a -reference. As with generic data types, we declare the name of the generic +reference [2]. As with generic data types, we declare the name of the generic lifetime parameter inside angle brackets after the name of the struct so we can -use the lifetime parameter in the body of the struct definition. This +use the lifetime parameter in the body of the struct definition [1]. This annotation means an instance of `ImportantExcerpt` can’t outlive the reference it holds in its `part` field. The `main` function here creates an instance of the `ImportantExcerpt` struct -that holds a reference to the first sentence of the `String` owned by the -variable `novel`. The data in `novel` exists before the `ImportantExcerpt` -instance is created. In addition, `novel` doesn’t go out of scope until after -the `ImportantExcerpt` goes out of scope, so the reference in the -`ImportantExcerpt` instance is valid. +[5] that holds a reference to the first sentence of the `String` [4] owned by +the variable `novel` [3]. The data in `novel` exists before the +`ImportantExcerpt` instance is created. In addition, `novel` doesn’t go out of +scope until after the `ImportantExcerpt` goes out of scope, so the reference in +the `ImportantExcerpt` instance is valid. ### Lifetime Elision You’ve learned that every reference has a lifetime and that you need to specify -lifetime parameters for functions or structs that use references. However, in -Chapter 4 we had a function in Listing 4-9, shown again in Listing 10-25, that -compiled without lifetime annotations. +lifetime parameters for functions or structs that use references. However, we +had a function in Listing 4-9, shown again in Listing 10-25, that compiled +without lifetime annotations. Filename: src/lib.rs @@ -1830,8 +1737,8 @@ which it can’t figure out lifetimes, the compiler will stop with an error. These rules apply to `fn` definitions as well as `impl` blocks. The first rule is that the compiler assigns a lifetime parameter to each -parameter that’s a reference. In other words, a function with one parameter gets -one lifetime parameter: `fn foo<'a>(x: &'a i32)`; a function with two +parameter that’s a reference. In other words, a function with one parameter +gets one lifetime parameter: `fn foo<'a>(x: &'a i32)`; a function with two parameters gets two separate lifetime parameters: `fn foo<'a, 'b>(x: &'a i32, y: &'b i32)`; and so on. @@ -1907,7 +1814,7 @@ use the lifetime parameters depends on whether they’re related to the struct fields or the method parameters and return values. Lifetime names for struct fields always need to be declared after the `impl` -keyword and then used after the struct’s name, because those lifetimes are part +keyword and then used after the struct’s name because those lifetimes are part of the struct’s type. In method signatures inside the `impl` block, references might be tied to the @@ -1916,7 +1823,7 @@ addition, the lifetime elision rules often make it so that lifetime annotations aren’t necessary in method signatures. Let’s look at some examples using the struct named `ImportantExcerpt` that we defined in Listing 10-24. -First, we’ll use a method named `level` whose only parameter is a reference to +First we’ll use a method named `level` whose only parameter is a reference to `self` and whose return value is an `i32`, which is not a reference to anything: ``` @@ -1936,7 +1843,7 @@ Here is an example where the third lifetime elision rule applies: ``` impl<'a> ImportantExcerpt<'a> { fn announce_and_return_part(&self, announcement: &str) -> &str { - println!("Attention please: {}", announcement); + println!("Attention please: {announcement}"); self.part } } @@ -1957,9 +1864,8 @@ string literals have the `'static` lifetime, which we can annotate as follows: let s: &'static str = "I have a static lifetime."; ``` -The text of this string is stored directly in the program’s binary, which -is always available. Therefore, the lifetime of all string literals is -`'static`. +The text of this string is stored directly in the program’s binary, which is +always available. Therefore, the lifetime of all string literals is `'static`. You might see suggestions to use the `'static` lifetime in error messages. But before specifying `'static` as the lifetime for a reference, think about @@ -1967,7 +1873,7 @@ whether the reference you have actually lives the entire lifetime of your program or not, and whether you want it to. Most of the time, an error message suggesting the `'static` lifetime results from attempting to create a dangling reference or a mismatch of the available lifetimes. In such cases, the solution -is fixing those problems, not specifying the `'static` lifetime. +is to fix those problems, not to specify the `'static` lifetime. ## Generic Type Parameters, Trait Bounds, and Lifetimes Together @@ -1985,7 +1891,7 @@ fn longest_with_an_announcement<'a, T>( where T: Display, { - println!("Announcement! {}", ann); + println!("Announcement! {ann}"); if x.len() > y.len() { x } else { @@ -2021,3 +1927,4 @@ that you will only need in very advanced scenarios; for those, you should read the Rust Reference at *https://doc.rust-lang.org/reference/trait-bounds.html*. But next, you’ll learn how to write tests in Rust so you can make sure your code is working the way it should. + diff --git a/src/doc/book/nostarch/chapter11.md b/src/doc/book/nostarch/chapter11.md index ea4ffe5bf..cf909d70c 100644 --- a/src/doc/book/nostarch/chapter11.md +++ b/src/doc/book/nostarch/chapter11.md @@ -33,11 +33,12 @@ We can write tests that assert, for example, that when we pass `3` to the we make changes to our code to make sure any existing correct behavior has not changed. -Testing is a complex skill: although we can’t cover every detail about how to -write good tests in one chapter, we’ll discuss the mechanics of Rust’s testing -facilities. We’ll talk about the annotations and macros available to you when -writing your tests, the default behavior and options provided for running your -tests, and how to organize tests into unit tests and integration tests. +Testing is a complex skill: although we can’t cover in one chapter every detail +about how to write good tests, in this chapter we will discuss the mechanics of +Rust’s testing facilities. We’ll talk about the annotations and macros +available to you when writing your tests, the default behavior and options +provided for running your tests, and how to organize tests into unit tests and +integration tests. ## How to Write Tests @@ -45,9 +46,9 @@ Tests are Rust functions that verify that the non-test code is functioning in the expected manner. The bodies of test functions typically perform these three actions: -1. Set up any needed data or state. -2. Run the code you want to test. -3. Assert the results are what you expect. +* Set up any needed data or state. +* Run the code you want to test. +* Assert that the results are what you expect. Let’s look at the features Rust provides specifically for writing tests that take these actions, which include the `test` attribute, a few macros, and the @@ -60,8 +61,8 @@ attribute. Attributes are metadata about pieces of Rust code; one example is the `derive` attribute we used with structs in Chapter 5. To change a function into a test function, add `#[test]` on the line before `fn`. When you run your tests with the `cargo test` command, Rust builds a test runner binary that runs -the annotated functions and reports on whether each -test function passes or fails. +the annotated functions and reports on whether each test function passes or +fails. Whenever we make a new library project with Cargo, a test module with a test function in it is automatically generated for us. This module gives you a @@ -89,10 +90,10 @@ Filename: src/lib.rs ``` #[cfg(test)] mod tests { -[1] #[test] + 1 #[test] fn it_works() { let result = 2 + 2; - [2] assert_eq!(result, 4); + 2 assert_eq!(result, 4); } } ``` @@ -119,19 +120,21 @@ The `cargo test` command runs all tests in our project, as shown in Listing $ cargo test Compiling adder v0.1.0 (file:///projects/adder) Finished test [unoptimized + debuginfo] target(s) in 0.57s - Running unittests (target/debug/deps/adder-92948b65e88960b4) + Running unittests src/lib.rs (target/debug/deps/adder- +92948b65e88960b4) -[1] running 1 test -[2] test tests::it_works ... ok +1 running 1 test +2 test tests::it_works ... ok -[3] test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +3 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s -[4] Doc-tests adder + 4 Doc-tests adder running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s - +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Listing 11-2: The output from running the automatically generated test @@ -143,13 +146,12 @@ ok.` [3] means that all the tests passed, and the portion that reads `1 passed; 0 failed` totals the number of tests that passed or failed. It’s possible to mark a test as ignored so it doesn’t run in a particular -instance; we’ll cover that in the “Ignoring Some Tests Unless Specifically -Requested†section later in this chapter. Because we haven’t done that here, -the summary shows `0 ignored`. We can also pass an argument to the `cargo test` -command to run only tests whose name matches a string; this is called *filtering* -and we’ll cover that in the “Running a Subset of Tests by Name†section. -Here we haven’t filtered the tests being run, so the end of the summary shows `0 -filtered out`. +instance; we’ll cover that in “Ignoring Some Tests Unless Specifically +Requested†on page XX. Because we haven’t done that here, the summary shows `0 +ignored`. We can also pass an argument to the `cargo test` command to run only +tests whose name matches a string; this is called *filtering* and we’ll cover +it in “Running a Subset of Tests by Name†on page XX. Here we haven’t filtered +the tests being run, so the end of the summary shows `0 filtered out`. The `0 measured` statistic is for benchmark tests that measure performance. Benchmark tests are, as of this writing, only available in nightly Rust. See @@ -161,10 +163,10 @@ The next part of the test output starting at `Doc-tests adder` [4] is for the results of any documentation tests. We don’t have any documentation tests yet, but Rust can compile any code examples that appear in our API documentation. This feature helps keep your docs and your code in sync! We’ll discuss how to -write documentation tests in the “Documentation Comments as Tests†section of -Chapter 14. For now, we’ll ignore the `Doc-tests` output. +write documentation tests in “Documentation Comments as Tests†on page XX. For +now, we’ll ignore the `Doc-tests` output. -Let’s start to customize the test to our own needs. First change the name of +Let’s start to customize the test to our own needs. First, change the name of the `it_works` function to a different name, such as `exploration`, like so: Filename: src/lib.rs @@ -174,7 +176,8 @@ Filename: src/lib.rs mod tests { #[test] fn exploration() { - assert_eq!(2 + 2, 4); + let result = 2 + 2; + assert_eq!(result, 4); } } ``` @@ -186,7 +189,8 @@ Then run `cargo test` again. The output now shows `exploration` instead of running 1 test test tests::exploration ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Now we’ll add another test, but this time we’ll make a test that fails! Tests @@ -222,18 +226,20 @@ Run the tests again using `cargo test`. The output should look like Listing ``` running 2 tests test tests::exploration ... ok -[1] test tests::another ... FAILED +1 test tests::another ... FAILED -[2] failures: +2 failures: ---- tests::another stdout ---- thread 'main' panicked at 'Make this test fail', src/lib.rs:10:9 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace -[3] failures: +3 failures: tests::another -[4] test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +4 test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s error: test failed, to rerun pass '--lib' ``` @@ -248,7 +254,7 @@ line 10 in the *src/lib.rs* file. The next section [3] lists just the names of all the failing tests, which is useful when there are lots of tests and lots of detailed failing test output. We can use the name of a failing test to run just that test to more easily debug it; we’ll talk more about ways to run tests in -the “Controlling How Tests Are Run†section. +“Controlling How Tests Are Run†on page XX. The summary line displays at the end [4]: overall, our test result is `FAILED`. We had one test pass and one test fail. @@ -256,7 +262,7 @@ We had one test pass and one test fail. Now that you’ve seen what the test results look like in different scenarios, let’s look at some macros other than `panic!` that are useful in tests. -### Checking Results with the `assert!` Macro +### Checking Results with the assert! Macro The `assert!` macro, provided by the standard library, is useful when you want to ensure that some condition in a test evaluates to `true`. We give the @@ -265,9 +271,9 @@ to ensure that some condition in a test evaluates to `true`. We give the `assert!` macro calls `panic!` to cause the test to fail. Using the `assert!` macro helps us check that our code is functioning in the way we intend. -In Chapter 5, Listing 5-15, we used a `Rectangle` struct and a `can_hold` -method, which are repeated here in Listing 11-5. Let’s put this code in the -*src/lib.rs* file, then write some tests for it using the `assert!` macro. +In Listing 5-15, we used a `Rectangle` struct and a `can_hold` method, which +are repeated here in Listing 11-5. Let’s put this code in the *src/lib.rs* +file, then write some tests for it using the `assert!` macro. Filename: src/lib.rs @@ -299,11 +305,11 @@ Filename: src/lib.rs ``` #[cfg(test)] mod tests { -[1] use super::*; + 1 use super::*; #[test] -[2] fn larger_can_hold_smaller() { - [3] let larger = Rectangle { + 2 fn larger_can_hold_smaller() { + 3 let larger = Rectangle { width: 8, height: 7, }; @@ -312,7 +318,7 @@ mod tests { height: 1, }; - [4] assert!(larger.can_hold(&smaller)); + 4 assert!(larger.can_hold(&smaller)); } } ``` @@ -322,11 +328,11 @@ indeed hold a smaller rectangle Note that we’ve added a new line inside the `tests` module: `use super::*;` [1]. The `tests` module is a regular module that follows the usual visibility -rules we covered in Chapter 7 in the “Paths for Referring to an Item in the -Module Tree†section. Because the `tests` module is an inner module, we need to -bring the code under test in the outer module into the scope of the inner -module. We use a glob here so anything we define in the outer module is -available to this `tests` module. +rules we covered in “Paths for Referring to an Item in the Module Tree†on page +XX. Because the `tests` module is an inner module, we need to bring the code +under test in the outer module into the scope of the inner module. We use a +glob here, so anything we define in the outer module is available to this +`tests` module. We’ve named our test `larger_can_hold_smaller` [2], and we’ve created the two `Rectangle` instances that we need [3]. Then we called the `assert!` macro and @@ -338,7 +344,8 @@ out! running 1 test test tests::larger_can_hold_smaller ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` It does pass! Let’s add another test, this time asserting that a smaller @@ -353,7 +360,7 @@ mod tests { #[test] fn larger_can_hold_smaller() { - // --snip-- + --snip-- } #[test] @@ -381,7 +388,8 @@ running 2 tests test tests::larger_can_hold_smaller ... ok test tests::smaller_cannot_hold_larger ... ok -test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Two tests that pass! Now let’s see what happens to our test results when we @@ -390,7 +398,8 @@ method by replacing the greater-than sign with a less-than sign when it compares the widths: ``` -// --snip-- +--snip-- + impl Rectangle { fn can_hold(&self, other: &Rectangle) -> bool { self.width < other.width && self.height > other.height @@ -408,26 +417,29 @@ test tests::larger_can_hold_smaller ... FAILED failures: ---- tests::larger_can_hold_smaller stdout ---- -thread 'main' 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 +thread 'main' 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 failures: tests::larger_can_hold_smaller -test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` -Our tests caught the bug! Because `larger.width` is 8 and `smaller.width` is -5, the comparison of the widths in `can_hold` now returns `false`: 8 is not +Our tests caught the bug! Because `larger.width` is `8` and `smaller.width` is +`5`, the comparison of the widths in `can_hold` now returns `false`: 8 is not less than 5. -### Testing Equality with the `assert_eq!` and `assert_ne!` Macros +### Testing Equality with the assert_eq! and assert_ne! Macros A common way to verify functionality is to test for equality between the result of the code under test and the value you expect the code to return. You could -do this using the `assert!` macro and passing it an expression using the `==` -operator. However, this is such a common test that the standard library +do this by using the `assert!` macro and passing it an expression using the +`==` operator. However, this is such a common test that the standard library provides a pair of macros—`assert_eq!` and `assert_ne!`—to perform this test more conveniently. These macros compare two arguments for equality or inequality, respectively. They’ll also print the two values if the assertion @@ -464,7 +476,8 @@ Let’s check that it passes! running 1 test test tests::it_adds_two ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` We pass `4` as the argument to `assert_eq!`, which is equal to the result of @@ -489,23 +502,25 @@ test tests::it_adds_two ... FAILED failures: ---- tests::it_adds_two stdout ---- -[1] thread 'main' panicked at 'assertion failed: `(left == right)` -[2] left: `4`, -[3] right: `5`', src/lib.rs:11:9 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +1 thread 'main' panicked at 'assertion failed: `(left == right)` +2 left: `4`, +3 right: `5`', src/lib.rs:11:9 +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace failures: tests::it_adds_two -test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Our test caught the bug! The `it_adds_two` test failed, and the message tells -us that the assertion that fails was `` assertion failed: `(left == right)` `` -[1] and what the `left` [2] and `right` [3] values are. This message helps us -start debugging: the `left` argument was `4` but the `right` argument, where we -had `add_two(2)`, was `5`. You can imagine that this would be especially -helpful when we have a lot of tests going on. +us that the assertion that failed was `assertion failed: `(left == right)`` [1] +and what the `left` [2] and `right` [3] values are. This message helps us start +debugging: the `left` argument was `4` but the `right` argument, where we had +`add_two(2)`, was `5`. You can imagine that this would be especially helpful +when we have a lot of tests going on. Note that in some languages and test frameworks, the parameters to equality assertion functions are called `expected` and `actual`, and the order in which @@ -513,7 +528,7 @@ we specify the arguments matters. However, in Rust, they’re called `left` and `right`, and the order in which we specify the value we expect and the value the code produces doesn’t matter. We could write the assertion in this test as `assert_eq!(add_two(2), 4)`, which would result in the same failure message -that displays `` assertion failed: `(left == right)` ``. +that displays `assertion failed: `(left == right)``. The `assert_ne!` macro will pass if the two values we give it are not equal and fail if they’re equal. This macro is most useful for cases when we’re not sure @@ -531,21 +546,20 @@ the standard library types implement these traits. For structs and enums that you define yourself, you’ll need to implement `PartialEq` to assert equality of those types. You’ll also need to implement `Debug` to print the values when the assertion fails. Because both traits are derivable traits, as mentioned in -Listing 5-12 in Chapter 5, this is usually as straightforward as adding the +Listing 5-12, this is usually as straightforward as adding the `#[derive(PartialEq, Debug)]` annotation to your struct or enum definition. See -Appendix C, “Derivable Traits,†for more details about these and other -derivable traits. +Appendix C for more details about these and other derivable traits. ### Adding Custom Failure Messages You can also add a custom message to be printed with the failure message as optional arguments to the `assert!`, `assert_eq!`, and `assert_ne!` macros. Any arguments specified after the required arguments are passed along to the -`format!` macro (discussed in Chapter 8 in the “Concatenation with the `+` -Operator or the `format!` Macro†section), so you can pass a format string that -contains `{}` placeholders and values to go in those placeholders. Custom -messages are useful for documenting what an assertion means; when a test fails, -you’ll have a better idea of what the problem is with the code. +`format!` macro (discussed in “Concatenation with the + Operator or the format! +Macro†on page XX), so you can pass a format string that contains `{}` +placeholders and values to go in those placeholders. Custom messages are useful +for documenting what an assertion means; when a test fails, you’ll have a +better idea of what the problem is with the code. For example, let’s say we have a function that greets people by name and we want to test that the name we pass into the function appears in the output: @@ -554,7 +568,7 @@ Filename: src/lib.rs ``` pub fn greeting(name: &str) -> String { - format!("Hello {}!", name) + format!("Hello {name}!") } #[cfg(test)] @@ -594,8 +608,10 @@ 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 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +thread 'main' panicked at 'assertion failed: +result.contains(\"Carol\")', src/lib.rs:12:9 +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace failures: @@ -614,8 +630,7 @@ fn greeting_contains_name() { let result = greeting("Carol"); assert!( result.contains("Carol"), - "Greeting did not contain name, value was `{}`", - result + "Greeting did not contain name, value was `{result}`" ); } ``` @@ -624,21 +639,23 @@ Now when we run the test, we’ll get a more informative error message: ``` ---- tests::greeting_contains_name stdout ---- -thread 'main' 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 +thread 'main' 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 ``` We can see the value we actually got in the test output, which would help us debug what happened instead of what we were expecting to happen. -### Checking for Panics with `should_panic` +### Checking for Panics with should_panic In addition to checking return values, it’s important to check that our code handles error conditions as we expect. For example, consider the `Guess` type -that we created in Chapter 9, Listing 9-13. Other code that uses `Guess` -depends on the guarantee that `Guess` instances will contain only values -between 1 and 100. We can write a test that ensures that attempting to create a -`Guess` instance with a value outside that range panics. +that we created in Listing 9-13. Other code that uses `Guess` depends on the +guarantee that `Guess` instances will contain only values between 1 and 100. We +can write a test that ensures that attempting to create a `Guess` instance with +a value outside that range panics. We do this by adding the attribute `should_panic` to our test function. The test passes if the code inside the function panics; the test fails if the code @@ -647,9 +664,8 @@ inside the function doesn’t panic. Listing 11-8 shows a test that checks that the error conditions of `Guess::new` happen when we expect them to. -Filename: src/lib.rs - ``` +// src/lib.rs pub struct Guess { value: i32, } @@ -657,7 +673,10 @@ pub struct Guess { impl Guess { pub fn new(value: i32) -> Guess { if value < 1 || value > 100 { - panic!("Guess value must be between 1 and 100, got {}.", value); + panic!( + "Guess value must be between 1 and 100, got {}.", + value + ); } Guess { value } @@ -676,7 +695,7 @@ mod tests { } ``` -Listing 11-8: Testing that a condition will cause a `panic!` +Listing 11-8: Testing that a condition will cause a panic! We place the `#[should_panic]` attribute after the `#[test]` attribute and before the test function it applies to. Let’s look at the result when this test @@ -686,18 +705,24 @@ passes: running 1 test test tests::greater_than_100 - should panic ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Looks good! Now let’s introduce a bug in our code by removing the condition that the `new` function will panic if the value is greater than 100: ``` -// --snip-- +// src/lib.rs +--snip-- + impl Guess { pub fn new(value: i32) -> Guess { if value < 1 { - panic!("Guess value must be between 1 and 100, got {}.", value); + panic!( + "Guess value must be between 1 and 100, got {}.", + value + ); } Guess { value } @@ -719,7 +744,8 @@ note: test did not panic as expected failures: tests::greater_than_100 -test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` We don’t get a very helpful message in this case, but when we look at the test @@ -735,10 +761,9 @@ consider the modified code for `Guess` in Listing 11-9 where the `new` function panics with different messages depending on whether the value is too small or too large. -Filename: src/lib.rs - ``` -// --snip-- +// src/lib.rs +--snip-- impl Guess { pub fn new(value: i32) -> Guess { @@ -777,32 +802,30 @@ This test will pass because the value we put in the `should_panic` attribute’s `expected` parameter is a substring of the message that the `Guess::new` function panics with. We could have specified the entire panic message that we expect, which in this case would be `Guess value must be less than or equal to -100, got 200.` What you choose to specify depends on how much of the panic +100, got 200`. What you choose to specify depends on how much of the panic message is unique or dynamic and how precise you want your test to be. In this case, a substring of the panic message is enough to ensure that the code in the test function executes the `else if value > 100` case. -<!--- -We may want to make extra clear above that `expected` here means substring. I -think many people would assume equality rather than substring like the -expected/actual of unit tests. - -(let alone how .expect(..) works. It seems we use the word expect in different -ways around the language/library ) -/JT ---> -<!-- I've changed the example to be more clearly a substring specified, and -changed the caption as well. Hope that makes it extra clear! /Carol --> - To see what happens when a `should_panic` test with an `expected` message fails, let’s again introduce a bug into our code by swapping the bodies of the `if value < 1` and the `else if value > 100` blocks: ``` +// src/lib.rs +--snip-- if value < 1 { - panic!("Guess value must be less than or equal to 100, got {}.", value); + panic!( + "Guess value must be less than or equal to 100, got {}.", + value + ); } else if value > 100 { - panic!("Guess value must be greater than or equal to 1, got {}.", value); + panic!( + "Guess value must be greater than or equal to 1, got {}.", + value + ); } +--snip-- ``` This time when we run the `should_panic` test, it will fail: @@ -814,30 +837,35 @@ 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 'main' 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."`, + panic message: `"Guess value must be greater than or equal to 1, got +200."`, expected substring: `"less than or equal to 100"` failures: tests::greater_than_100 -test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s ``` The failure message indicates that this test did indeed panic as we expected, but the panic message did not include the expected string `'Guess value must be less than or equal to 100'`. The panic message that we did get in this case was -`Guess value must be greater than or equal to 1, got 200.` Now we can start +`Guess value must be greater than or equal to 1, got 200`. Now we can start figuring out where our bug is! -### Using `Result<T, E>` in Tests +### Using Result<T, E> in Tests Our tests so far all panic when they fail. We can also write tests that use `Result<T, E>`! Here’s the test from Listing 11-1, rewritten to use `Result<T, E>` and return an `Err` instead of panicking: +Filename: src/lib.rs + ``` #[cfg(test)] mod tests { @@ -872,15 +900,15 @@ test`. ## Controlling How Tests Are Run -Just as `cargo run` compiles your code and then runs the resulting binary, -`cargo test` compiles your code in test mode and runs the resulting test +Just as `cargo run` compiles your code and then runs the resultant binary, +`cargo test` compiles your code in test mode and runs the resultant test binary. The default behavior of the binary produced by `cargo test` is to run all the tests in parallel and capture output generated during test runs, preventing the output from being displayed and making it easier to read the output related to the test results. You can, however, specify command line options to change this default behavior. -Some command line options go to `cargo test`, and some go to the resulting test +Some command line options go to `cargo test`, and some go to the resultant test binary. To separate these two types of arguments, you list the arguments that go to `cargo test` followed by the separator `--` and then the ones that go to the test binary. Running `cargo test --help` displays the options you can use @@ -934,7 +962,7 @@ Filename: src/lib.rs ``` fn prints_and_returns_10(a: i32) -> i32 { - println!("I got the value {}", a); + println!("I got the value {a}"); 10 } @@ -968,16 +996,18 @@ test tests::this_test_will_fail ... FAILED failures: ---- tests::this_test_will_fail stdout ---- -[1] I got the value 8 +1 I got the value 8 thread 'main' 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 +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace failures: tests::this_test_will_fail -test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Note that nowhere in this output do we see `I got the value 4`, which is @@ -986,8 +1016,8 @@ output from the test that failed, `I got the value 8` [1], appears in the section of the test summary output, which also shows the cause of the test failure. -If we want to see printed values for passing tests as well, we can tell Rust -to also show the output of successful tests with `--show-output`. +If we want to see printed values for passing tests as well, we can tell Rust to +also show the output of successful tests with `--show-output`: ``` $ cargo test -- --show-output @@ -1017,12 +1047,14 @@ I got the value 8 thread 'main' 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 +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace failures: tests::this_test_will_fail -test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 1 passed; 1 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` ### Running a Subset of Tests by Name @@ -1074,7 +1106,8 @@ test tests::add_three_and_two ... ok test tests::add_two_and_two ... ok test tests::one_hundred ... ok -test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` #### Running Single Tests @@ -1085,12 +1118,14 @@ We can pass the name of any test function to `cargo test` to run only that test: $ cargo test one_hundred Compiling adder v0.1.0 (file:///projects/adder) Finished test [unoptimized + debuginfo] target(s) in 0.69s - Running unittests (target/debug/deps/adder-92948b65e88960b4) + Running unittests src/lib.rs (target/debug/deps/adder- +92948b65e88960b4) running 1 test test tests::one_hundred ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 2 +filtered out; finished in 0.00s ``` Only the test with the name `one_hundred` ran; the other two tests didn’t match @@ -1110,13 +1145,15 @@ run those two by running `cargo test add`: $ cargo test add Compiling adder v0.1.0 (file:///projects/adder) Finished test [unoptimized + debuginfo] target(s) in 0.61s - Running unittests (target/debug/deps/adder-92948b65e88960b4) + Running unittests src/lib.rs (target/debug/deps/adder- +92948b65e88960b4) running 2 tests test tests::add_three_and_two ... ok test tests::add_two_and_two ... ok -test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 1 +filtered out; finished in 0.00s ``` This command ran all tests with `add` in the name and filtered out the test @@ -1137,7 +1174,8 @@ Filename: src/lib.rs ``` #[test] fn it_works() { - assert_eq!(2 + 2, 4); + let result = 2 + 2; + assert_eq!(result, 4); } #[test] @@ -1147,20 +1185,22 @@ fn expensive_test() { } ``` -After `#[test]` we add the `#[ignore]` line to the test we want to exclude. Now -when we run our tests, `it_works` runs, but `expensive_test` doesn’t: +After `#[test]`, we add the `#[ignore]` line to the test we want to exclude. +Now when we run our tests, `it_works` runs, but `expensive_test` doesn’t: ``` $ cargo test Compiling adder v0.1.0 (file:///projects/adder) Finished test [unoptimized + debuginfo] target(s) in 0.60s - Running unittests (target/debug/deps/adder-92948b65e88960b4) + Running unittests src/lib.rs (target/debug/deps/adder- +92948b65e88960b4) running 2 tests test expensive_test ... ignored test it_works ... ok -test result: ok. 1 passed; 0 failed; 1 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 1 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` The `expensive_test` function is listed as `ignored`. If we want to run only @@ -1169,19 +1209,21 @@ the ignored tests, we can use `cargo test -- --ignored`: ``` $ cargo test -- --ignored Finished test [unoptimized + debuginfo] target(s) in 0.61s - Running unittests (target/debug/deps/adder-92948b65e88960b4) + Running unittests src/lib.rs (target/debug/deps/adder- +92948b65e88960b4) running 1 test test expensive_test ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 1 +filtered out; finished in 0.00s ``` By controlling which tests run, you can make sure your `cargo test` results -will be fast. When you’re at a point where it makes sense to check the results -of the `ignored` tests and you have time to wait for the results, you can run -`cargo test -- --ignored` instead. If you want to run all tests whether they’re -ignored or not, you can run `cargo test -- --include-ignored`. +will be returned quickly. When you’re at a point where it makes sense to check +the results of the `ignored` tests and you have time to wait for the results, +you can run `cargo test -- --ignored` instead. If you want to run all tests +whether they’re ignored or not, you can run `cargo test -- --include-ignored`. ## Test Organization @@ -1206,16 +1248,16 @@ code that they’re testing. The convention is to create a module named `tests` in each file to contain the test functions and to annotate the module with `cfg(test)`. -#### The Tests Module and `#[cfg(test)]` +#### The Tests Module and #[cfg(test)] -The `#[cfg(test)]` annotation on the tests module tells Rust to compile and run -the test code only when you run `cargo test`, not when you run `cargo build`. -This saves compile time when you only want to build the library and saves space -in the resulting compiled artifact because the tests are not included. You’ll -see that because integration tests go in a different directory, they don’t need -the `#[cfg(test)]` annotation. However, because unit tests go in the same files -as the code, you’ll use `#[cfg(test)]` to specify that they shouldn’t be -included in the compiled result. +The `#[cfg(test)]` annotation on the `tests` module tells Rust to compile and +run the test code only when you run `cargo test`, not when you run `cargo +build`. This saves compile time when you only want to build the library and +saves space in the resultant compiled artifact because the tests are not +included. You’ll see that because integration tests go in a different +directory, they don’t need the `#[cfg(test)]` annotation. However, because unit +tests go in the same files as the code, you’ll use `#[cfg(test)]` to specify +that they shouldn’t be included in the compiled result. Recall that when we generated the new `adder` project in the first section of this chapter, Cargo generated this code for us: @@ -1227,12 +1269,13 @@ Filename: src/lib.rs mod tests { #[test] fn it_works() { - assert_eq!(2 + 2, 4); + let result = 2 + 2; + assert_eq!(result, 4); } } ``` -This code is the automatically generated test module. The attribute `cfg` +This code is the automatically generated `tests` module. The attribute `cfg` stands for *configuration* and tells Rust that the following item should only be included given a certain configuration option. In this case, the configuration option is `test`, which is provided by Rust for compiling and @@ -1275,7 +1318,7 @@ Listing 11-12: Testing a private function Note that the `internal_adder` function is not marked as `pub`. Tests are just Rust code, and the `tests` module is just another module. As we discussed in -the “Paths for Referring to an Item in the Module Tree†section, items in child +“Paths for Referring to an Item in the Module Tree†on page XX, items in child modules can use the items in their ancestor modules. In this test, we bring all of the `test` module’s parent’s items into scope with `use super::*`, and then the test can call `internal_adder`. If you don’t think private functions should @@ -1291,7 +1334,7 @@ work correctly on their own could have problems when integrated, so test coverage of the integrated code is important as well. To create integration tests, you first need a *tests* directory. -#### The *tests* Directory +#### The tests Directory We create a *tests* directory at the top level of our project directory, next to *src*. Cargo knows to look for integration test files in this directory. We @@ -1307,12 +1350,12 @@ adder ├── Cargo.lock ├── Cargo.toml ├── src -│  └── lib.rs +│ └── lib.rs └── tests └── integration_test.rs ``` -Enter the code in Listing 11-13 into the *tests/integration_test.rs* file: +Enter the code in Listing 11-13 into the *tests/integration_test.rs* file. Filename: tests/integration_test.rs @@ -1327,37 +1370,42 @@ fn it_adds_two() { Listing 11-13: An integration test of a function in the `adder` crate -Each file in the `tests` directory is a separate crate, so we need to bring our -library into each test crate’s scope. For that reason we add `use adder` at the -top of the code, which we didn’t need in the unit tests. +Each file in the *tests* directory is a separate crate, so we need to bring our +library into each test crate’s scope. For that reason we add `use adder;` at +the top of the code, which we didn’t need in the unit tests. We don’t need to annotate any code in *tests/integration_test.rs* with -`#[cfg(test)]`. Cargo treats the `tests` directory specially and compiles files +`#[cfg(test)]`. Cargo treats the *tests* directory specially and compiles files in this directory only when we run `cargo test`. Run `cargo test` now: ``` $ cargo test Compiling adder v0.1.0 (file:///projects/adder) Finished test [unoptimized + debuginfo] target(s) in 1.31s - Running unittests (target/debug/deps/adder-1082c4b063a8fbe6) + Running unittests src/lib.rs (target/debug/deps/adder- +1082c4b063a8fbe6) -[1] running 1 test +1 running 1 test test tests::internal ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s - [2] Running tests/integration_test.rs (target/debug/deps/integration_test-1082c4b063a8fbe6) + 2 Running tests/integration_test.rs +(target/debug/deps/integration_test-1082c4b063a8fbe6) running 1 test -[3] test it_adds_two ... ok +3 test it_adds_two ... ok -[4] test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +4 test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s Doc-tests adder running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` The three sections of output include the unit tests, the integration test, and @@ -1386,12 +1434,14 @@ followed by the name of the file: ``` $ cargo test --test integration_test Finished test [unoptimized + debuginfo] target(s) in 0.64s - Running tests/integration_test.rs (target/debug/deps/integration_test-82e7799c1bc62298) + Running tests/integration_test.rs +(target/debug/deps/integration_test-82e7799c1bc62298) running 1 test test it_adds_two ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` This command runs only the tests in the *tests/integration_test.rs* file. @@ -1409,11 +1459,11 @@ regarding how to separate code into modules and files. The different behavior of *tests* directory files is most noticeable when you have a set of helper functions to use in multiple integration test files and -you try to follow the steps in the “Separating Modules into Different Files†-section of Chapter 7 to extract them into a common module. For example, if we -create *tests/common.rs* and place a function named `setup` in it, we can add -some code to `setup` that we want to call from multiple test functions in -multiple test files: +you try to follow the steps in “Separating Modules into Different Files†on +page XX to extract them into a common module. For example, if we create +*tests/common.rs* and place a function named `setup` in it, we can add some +code to `setup` that we want to call from multiple test functions in multiple +test files: Filename: tests/common.rs @@ -1431,53 +1481,58 @@ did we call the `setup` function from anywhere: running 1 test test tests::internal ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s - Running tests/common.rs (target/debug/deps/common-92948b65e88960b4) + Running tests/common.rs (target/debug/deps/common- +92948b65e88960b4) running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s - Running tests/integration_test.rs (target/debug/deps/integration_test-92948b65e88960b4) + Running tests/integration_test.rs +(target/debug/deps/integration_test-92948b65e88960b4) running 1 test test it_adds_two ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s Doc-tests adder running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Having `common` appear in the test results with `running 0 tests` displayed for it is not what we wanted. We just wanted to share some code with the other -integration test files. -To avoid having `common` appear in the test output, instead of creating -*tests/common.rs*, we’ll create *tests/common/mod.rs*. The project directory -now looks like this: +integration test files. To avoid having `common` appear in the test output, +instead of creating *tests/common.rs*, we’ll create *tests/common/mod.rs*. The +project directory now looks like this: ``` ├── Cargo.lock ├── Cargo.toml ├── src -│  └── lib.rs +│ └── lib.rs └── tests ├── common - │  └── mod.rs + │ └── mod.rs └── integration_test.rs ``` This is the older naming convention that Rust also understands that we -mentioned in the “Alternate File Paths†section of Chapter 7. Naming the file -this way tells Rust not to treat the `common` module as an integration test -file. When we move the `setup` function code into *tests/common/mod.rs* and -delete the *tests/common.rs* file, the section in the test output will no -longer appear. Files in subdirectories of the *tests* directory don’t get -compiled as separate crates or have sections in the test output. +mentioned in “Alternate File Paths†on page XX. Naming the file this way tells +Rust not to treat the `common` module as an integration test file. When we move +the `setup` function code into *tests/common/mod.rs* and delete the +*tests/common.rs* file, the section in the test output will no longer appear. +Files in subdirectories of the *tests* directory don’t get compiled as separate +crates or have sections in the test output. After we’ve created *tests/common/mod.rs*, we can use it from any of the integration test files as a module. Here’s an example of calling the `setup` @@ -1498,7 +1553,7 @@ fn it_adds_two() { ``` Note that the `mod common;` declaration is the same as the module declaration -we demonstrated in Listing 7-21. Then in the test function, we can call the +we demonstrated in Listing 7-21. Then, in the test function, we can call the `common::setup()` function. #### Integration Tests for Binary Crates @@ -1512,10 +1567,9 @@ crates can use; binary crates are meant to be run on their own. This is one of the reasons Rust projects that provide a binary have a straightforward *src/main.rs* file that calls logic that lives in the *src/lib.rs* file. Using that structure, integration tests *can* test the -library crate with `use` to make the important functionality available. -If the important functionality works, the small amount of code in the -*src/main.rs* file will work as well, and that small amount of code doesn’t -need to be tested. +library crate with `use` to make the important functionality available. If the +important functionality works, the small amount of code in the *src/main.rs* +file will work as well, and that small amount of code doesn’t need to be tested. ## Summary @@ -1531,11 +1585,3 @@ reduce logic bugs having to do with how your code is expected to behave. Let’s combine the knowledge you learned in this chapter and in previous chapters to work on a project! -<!--- -We hint at doc tests but don't cover them. Should we have a section in this -chapter about that? They're pretty handy. -/JT ---> -<!-- We cover that in chapter 14, and there's a forward reference to that in -"The Anatomy of a Test Function" section. I don't actually think most Rust -developers will write doc tests; they're the most useful when writing open -source libraries, which I think only a minority of developers do. /Carol --> diff --git a/src/doc/book/nostarch/chapter12.md b/src/doc/book/nostarch/chapter12.md index 950b2e999..86e986173 100644 --- a/src/doc/book/nostarch/chapter12.md +++ b/src/doc/book/nostarch/chapter12.md @@ -26,8 +26,8 @@ Along the way, we’ll show how to make our command line tool use the terminal features that many other command line tools use. We’ll read the value of an environment variable to allow the user to configure the behavior of our tool. We’ll also print error messages to the standard error console stream (`stderr`) -instead of standard output (`stdout`), so, for example, the user can redirect -successful output to a file while still seeing error messages onscreen. +instead of standard output (`stdout`) so that, for example, the user can +redirect successful output to a file while still seeing error messages onscreen. One Rust community member, Andrew Gallant, has already created a fully featured, very fast version of `grep`, called `ripgrep`. By comparison, our @@ -37,14 +37,14 @@ background knowledge you need to understand a real-world project such as Our `grep` project will combine a number of concepts you’ve learned so far: -* Organizing code (using what you learned about modules in Chapter 7) -* Using vectors and strings (collections, Chapter 8) +* Organizing code (Chapter 7) +* Using vectors and strings (Chapter 8) * Handling errors (Chapter 9) * Using traits and lifetimes where appropriate (Chapter 10) * Writing tests (Chapter 11) We’ll also briefly introduce closures, iterators, and trait objects, which -Chapters 13 and 17 will cover in detail. +Chapter 13 and Chapter 17 will cover in detail. ## Accepting Command Line Arguments @@ -69,8 +69,8 @@ $ cargo run -- searchstring example-filename.txt ``` Right now, the program generated by `cargo new` cannot process arguments we -give it. Some existing libraries on *https://crates.io/* can help with writing -a program that accepts command line arguments, but because you’re just learning +give it. Some existing libraries on *https://crates.io* can help with writing a +program that accepts command line arguments, but because you’re just learning this concept, let’s implement this capability ourselves. ### Reading the Argument Values @@ -85,7 +85,7 @@ collection, such as a vector, that contains all the elements the iterator produces. The code in Listing 12-1 allows your `minigrep` program to read any command -line arguments passed to it and then collect the values into a vector. +line arguments passed to it, and then collect the values into a vector. Filename: src/main.rs @@ -101,7 +101,7 @@ fn main() { Listing 12-1: Collecting the command line arguments into a vector and printing them -First, we bring the `std::env` module into scope with a `use` statement so we +First we bring the `std::env` module into scope with a `use` statement so we can use its `args` function. Notice that the `std::env::args` function is nested in two levels of modules. As we discussed in Chapter 7, in cases where the desired function is nested in more than one module, we’ve chosen to bring @@ -111,20 +111,20 @@ adding `use std::env::args` and then calling the function with just `args`, because `args` might easily be mistaken for a function that’s defined in the current module. -> ### The `args` Function and Invalid Unicode +> ### The args Function and Invalid Unicode > > Note that `std::env::args` will panic if any argument contains invalid -> Unicode. If your program needs to accept arguments containing invalid -> Unicode, use `std::env::args_os` instead. That function returns an iterator -> that produces `OsString` values instead of `String` values. We’ve chosen to -> use `std::env::args` here for simplicity, because `OsString` values differ -> per platform and are more complex to work with than `String` values. +Unicode. If your program needs to accept arguments containing invalid Unicode, +use `std::env::args_os` instead. That function returns an iterator that +produces `OsString` values instead of `String` values. We’ve chosen to use +`std::env::args` here for simplicity because `OsString` values differ per +platform and are more complex to work with than `String` values. On the first line of `main`, we call `env::args`, and we immediately use `collect` to turn the iterator into a vector containing all the values produced by the iterator. We can use the `collect` function to create many kinds of collections, so we explicitly annotate the type of `args` to specify that we -want a vector of strings. Although we very rarely need to annotate types in +want a vector of strings. Although you very rarely need to annotate types in Rust, `collect` is one function you do often need to annotate because Rust isn’t able to infer the kind of collection you want. @@ -137,9 +137,6 @@ $ cargo run [src/main.rs:5] args = [ "target/debug/minigrep", ] -``` - -``` $ cargo run -- needle haystack --snip-- [src/main.rs:5] args = [ @@ -153,8 +150,8 @@ Notice that the first value in the vector is `"target/debug/minigrep"`, which is the name of our binary. This matches the behavior of the arguments list in C, letting programs use the name by which they were invoked in their execution. It’s often convenient to have access to the program name in case you want to -print it in messages or change behavior of the program based on what command -line alias was used to invoke the program. But for the purposes of this +print it in messages or change the behavior of the program based on what +command line alias was used to invoke the program. But for the purposes of this chapter, we’ll ignore it and save only the two arguments we need. ### Saving the Argument Values in Variables @@ -184,7 +181,7 @@ Listing 12-2: Creating variables to hold the query argument and file path argument As we saw when we printed the vector, the program’s name takes up the first -value in the vector at `args[0]`, so we’re starting arguments at index `1`. The +value in the vector at `args[0]`, so we’re starting arguments at index 1. The first argument `minigrep` takes is the string we’re searching for, so we put a reference to the first argument in the variable `query`. The second argument will be the file path, so we put a reference to the second argument in the @@ -212,7 +209,7 @@ capabilities instead. ## Reading a File Now we’ll add functionality to read the file specified in the `file_path` -argument. First, we need a sample file to test it with: we’ll use a file with a +argument. First we need a sample file to test it with: we’ll use a file with a small amount of text over multiple lines with some repeated words. Listing 12-3 has an Emily Dickinson poem that will work well! Create a file called *poem.txt* at the root level of your project, and enter the poem “I’m Nobody! @@ -232,7 +229,7 @@ To tell your name the livelong day To an admiring bog! ``` -Listing 12-3: A poem by Emily Dickinson makes a good test case +Listing 12-3: A poem by Emily Dickinson makes a good test case. With the text in place, edit *src/main.rs* and add code to read the file, as shown in Listing 12-4. @@ -241,26 +238,26 @@ Filename: src/main.rs ``` use std::env; -[1] use std::fs; +1 use std::fs; fn main() { - // --snip-- + --snip-- println!("In file {}", file_path); - [2] let contents = fs::read_to_string(file_path) + 2 let contents = fs::read_to_string(file_path) .expect("Should have been able to read the file"); - [3] println!("With text:\n{contents}"); + 3 println!("With text:\n{contents}"); } ``` Listing 12-4: Reading the contents of the file specified by the second argument -First, we bring in a relevant part of the standard library with a `use` +First we bring in a relevant part of the standard library with a `use` statement: we need `std::fs` to handle files [1]. In `main`, the new statement `fs::read_to_string` takes the `file_path`, opens -that file, and returns a `std::io::Result<String>` of the file’s contents [2]. +that file, and returns an `std::io::Result<String>` of the file’s contents [2]. After that, we again add a temporary `println!` statement that prints the value of `contents` after the file is read, so we can check that the program is @@ -295,9 +292,9 @@ responsibilities: generally, functions are clearer and easier to maintain if each function is responsible for only one idea. The other problem is that we’re not handling errors as well as we could. The program is still small, so these flaws aren’t a big problem, but as the program grows, it will be harder to fix -them cleanly. It’s good practice to begin refactoring early on when developing -a program, because it’s much easier to refactor smaller amounts of code. We’ll -do that next. +them cleanly. It’s a good practice to begin refactoring early on when +developing a program because it’s much easier to refactor smaller amounts of +code. We’ll do that next. ## Refactoring to Improve Modularity and Error Handling @@ -342,12 +339,12 @@ community has developed guidelines for splitting the separate concerns of a binary program when `main` starts getting large. This process has the following steps: -* Split your program into a *main.rs* and a *lib.rs* and move your program’s - logic to *lib.rs*. +* Split your program into a *main.rs* file and a *lib.rs* file and move your +program’s logic to *lib.rs*. * As long as your command line parsing logic is small, it can remain in - *main.rs*. +*main.rs*. * When the command line parsing logic starts getting complicated, extract it - from *main.rs* and move it to *lib.rs*. +from *main.rs* and move it to *lib.rs*. The responsibilities that remain in the `main` function after this process should be limited to the following: @@ -358,7 +355,7 @@ should be limited to the following: * Handling the error if `run` returns an error This pattern is about separating concerns: *main.rs* handles running the -program, and *lib.rs* handles all the logic of the task at hand. Because you +program and *lib.rs* handles all the logic of the task at hand. Because you can’t test the `main` function directly, this structure lets you test all of your program’s logic by moving it into functions in *lib.rs*. The code that remains in *main.rs* will be small enough to verify its correctness by reading @@ -368,7 +365,7 @@ it. Let’s rework our program by following this process. We’ll extract the functionality for parsing arguments into a function that `main` will call to prepare for moving the command line parsing logic to -*src/lib.rs*. Listing 12-5 shows the new start of `main` that calls a new +src/lib.rs*. Listing 12-5 shows the new start of `main` that calls a new function `parse_config`, which we’ll define in *src/main.rs* for the moment. Filename: src/main.rs @@ -379,7 +376,7 @@ fn main() { let (query, file_path) = parse_config(&args); - // --snip-- + --snip-- } fn parse_config(args: &[String]) -> (&str, &str) { @@ -431,25 +428,25 @@ Filename: src/main.rs fn main() { let args: Vec<String> = env::args().collect(); - [1] let config = parse_config(&args); + 1 let config = parse_config(&args); - println!("Searching for {}", config.query[2]); - println!("In file {}", config.file_path[3]); + println!("Searching for {}", 2 config.query); + println!("In file {}", 3 config.file_path); - let contents = fs::read_to_string(config.file_path[4]) + let contents = fs::read_to_string(4 config.file_path) .expect("Should have been able to read the file"); - // --snip-- + --snip-- } -[5] struct Config { +5 struct Config { query: String, file_path: String, } -[6] fn parse_config(args: &[String]) -> Config { - [7] let query = args[1].clone(); - [8] let file_path = args[2].clone(); +6 fn parse_config(args: &[String]) -> Config { + 7 let query = args[1].clone(); + 8 let file_path = args[2].clone(); Config { query, file_path } } @@ -459,8 +456,8 @@ Listing 12-6: Refactoring `parse_config` to return an instance of a `Config` struct We’ve added a struct named `Config` defined to have fields named `query` and -`file_path` [5]. The signature of `parse_config` now indicates that it returns a -`Config` value [6]. In the body of `parse_config`, where we used to return +`file_path` [5]. The signature of `parse_config` now indicates that it returns +a `Config` value [6]. In the body of `parse_config`, where we used to return string slices that reference `String` values in `args`, we now define `Config` to contain owned `String` values. The `args` variable in `main` is the owner of the argument values and is only letting the `parse_config` function borrow @@ -469,44 +466,43 @@ ownership of the values in `args`. There are a number of ways we could manage the `String` data; the easiest, though somewhat inefficient, route is to call the `clone` method on the values -[7][8]. This will make a full copy of the data for the `Config` instance to +[7] [8]. This will make a full copy of the data for the `Config` instance to own, which takes more time and memory than storing a reference to the string data. However, cloning the data also makes our code very straightforward because we don’t have to manage the lifetimes of the references; in this circumstance, giving up a little performance to gain simplicity is a worthwhile trade-off. -> ### The Trade-Offs of Using `clone` +> ### The Trade-Offs of Using clone > > There’s a tendency among many Rustaceans to avoid using `clone` to fix -> ownership problems because of its runtime cost. In -> Chapter 13, you’ll learn how to use more efficient -> methods in this type of situation. But for now, it’s okay to copy a few -> strings to continue making progress because you’ll make these copies only -> once and your file path and query string are very small. It’s better to have -> a working program that’s a bit inefficient than to try to hyperoptimize code -> on your first pass. As you become more experienced with Rust, it’ll be -> easier to start with the most efficient solution, but for now, it’s -> perfectly acceptable to call `clone`. +ownership problems because of its runtime cost. In Chapter 13, you’ll learn how +to use more efficient methods in this type of situation. But for now, it’s okay +to copy a few strings to continue making progress because you’ll make these +copies only once and your file path and query string are very small. It’s +better to have a working program that’s a bit inefficient than to try to +hyperoptimize code on your first pass. As you become more experienced with +Rust, it’ll be easier to start with the most efficient solution, but for now, +it’s perfectly acceptable to call `clone`. We’ve updated `main` so it places the instance of `Config` returned by `parse_config` into a variable named `config` [1], and we updated the code that previously used the separate `query` and `file_path` variables so it now uses -the fields on the `Config` struct instead [2][3][4]. +the fields on the `Config` struct instead [2] [3] [4]. Now our code more clearly conveys that `query` and `file_path` are related and that their purpose is to configure how the program will work. Any code that uses these values knows to find them in the `config` instance in the fields named for their purpose. -#### Creating a Constructor for `Config` +#### Creating a Constructor for Config So far, we’ve extracted the logic responsible for parsing the command line arguments from `main` and placed it in the `parse_config` function. Doing so -helped us to see that the `query` and `file_path` values were related and that +helped us see that the `query` and `file_path` values were related, and that relationship should be conveyed in our code. We then added a `Config` struct to -name the related purpose of `query` and `file_path` and to be able to return the -values’ names as struct field names from the `parse_config` function. +name the related purpose of `query` and `file_path` and to be able to return +the values’ names as struct field names from the `parse_config` function. So now that the purpose of the `parse_config` function is to create a `Config` instance, we can change `parse_config` from a plain function to a function @@ -523,15 +519,15 @@ Filename: src/main.rs fn main() { let args: Vec<String> = env::args().collect(); - [1] let config = Config::new(&args); + 1 let config = Config::new(&args); - // --snip-- + --snip-- } -// --snip-- +--snip-- -[2] impl Config { - [3] fn new(args: &[String]) -> Config { +2 impl Config { + 3 fn new(args: &[String]) -> Config { let query = args[1].clone(); let file_path = args[2].clone(); @@ -559,8 +555,10 @@ $ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep) Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep` -thread 'main' panicked at 'index out of bounds: the len is 1 but the index is 1', src/main.rs:27:21 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +thread 'main' panicked at 'index out of bounds: the len is 1 but +the index is 1', src/main.rs:27:21 +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace ``` The line `index out of bounds: the len is 1 but the index is 1` is an error @@ -570,18 +568,18 @@ they should do instead. Let’s fix that now. #### Improving the Error Message In Listing 12-8, we add a check in the `new` function that will verify that the -slice is long enough before accessing index 1 and 2. If the slice isn’t long -enough, the program panics and displays a better error message. +slice is long enough before accessing index 1 and index 2. If the slice isn’t +long enough, the program panics and displays a better error message. Filename: src/main.rs ``` -// --snip-- +--snip-- fn new(args: &[String]) -> Config { if args.len() < 3 { panic!("not enough arguments"); } - // --snip-- + --snip-- ``` Listing 12-8: Adding a check for the number of arguments @@ -589,9 +587,9 @@ Listing 12-8: Adding a check for the number of arguments This code is similar to the `Guess::new` function we wrote in Listing 9-13, where we called `panic!` when the `value` argument was out of the range of valid values. Instead of checking for a range of values here, we’re checking -that the length of `args` is at least 3 and the rest of the function can +that the length of `args` is at least `3` and the rest of the function can operate under the assumption that this condition has been met. If `args` has -fewer than three items, this condition will be true, and we call the `panic!` +fewer than three items, this condition will be `true`, and we call the `panic!` macro to end the program immediately. With these extra few lines of code in `new`, let’s run the program without any @@ -602,19 +600,21 @@ $ cargo run Compiling minigrep v0.1.0 (file:///projects/minigrep) Finished dev [unoptimized + debuginfo] target(s) in 0.0s Running `target/debug/minigrep` -thread 'main' panicked at 'not enough arguments', src/main.rs:26:13 -note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace +thread 'main' panicked at 'not enough arguments', +src/main.rs:26:13 +note: run with `RUST_BACKTRACE=1` environment variable to display +a backtrace ``` This output is better: we now have a reasonable error message. However, we also -have extraneous information we don’t want to give to our users. Perhaps using -the technique we used in Listing 9-13 isn’t the best to use here: a call to +have extraneous information we don’t want to give to our users. Perhaps the +technique we used in Listing 9-13 isn’t the best one to use here: a call to `panic!` is more appropriate for a programming problem than a usage problem, as discussed in Chapter 9. Instead, we’ll use the other technique you learned about in Chapter 9—returning a `Result` that indicates either success or an error. -#### Returning a `Result` Instead of Calling `panic!` +#### Returning a Result Instead of Calling panic! We can instead return a `Result` value that will contain a `Config` instance in the successful case and will describe the problem in the error case. We’re also @@ -650,7 +650,7 @@ impl Config { Listing 12-9: Returning a `Result` from `Config::build` Our `build` function returns a `Result` with a `Config` instance in the success -case and a `&'static str` in the error case. Our error values will always be +case and an `&'static str` in the error case. Our error values will always be string literals that have the `'static` lifetime. We’ve made two changes in the body of the function: instead of calling `panic!` @@ -662,7 +662,7 @@ Returning an `Err` value from `Config::build` allows the `main` function to handle the `Result` value returned from the `build` function and exit the process more cleanly in the error case. -#### Calling `Config::build` and Handling Errors +#### Calling Config::build and Handling Errors To handle the error case and print a user-friendly message, we need to update `main` to handle the `Result` being returned by `Config::build`, as shown in @@ -674,17 +674,17 @@ called our program that the program exited with an error state. Filename: src/main.rs ``` -[1] use std::process; +1 use std::process; fn main() { let args: Vec<String> = env::args().collect(); - [2] let config = Config::build(&args).unwrap_or_else([3]|err[4]| { - [5] println!("Problem parsing arguments: {err}"); - [6] process::exit(1); + 2 let config = Config::build(&args).3 unwrap_or_else(|4 err| { + 5 println!("Problem parsing arguments: {err}"); + 6 process::exit(1); }); - // --snip-- + --snip-- ``` Listing 12-10: Exiting with an error code if building a `Config` fails @@ -693,11 +693,11 @@ In this listing, we’ve used a method we haven’t covered in detail yet: `unwrap_or_else`, which is defined on `Result<T, E>` by the standard library [2]. Using `unwrap_or_else` allows us to define some custom, non-`panic!` error handling. If the `Result` is an `Ok` value, this method’s behavior is similar -to `unwrap`: it returns the inner value `Ok` is wrapping. However, if the value -is an `Err` value, this method calls the code in the *closure*, which is an -anonymous function we define and pass as an argument to `unwrap_or_else` [3]. -We’ll cover closures in more detail in Chapter 13. For now, you just need to -know that `unwrap_or_else` will pass the inner value of the `Err`, which in +to `unwrap`: it returns the inner value that `Ok` is wrapping. However, if the +value is an `Err` value, this method calls the code in the *closure*, which is +an anonymous function we define and pass as an argument to `unwrap_or_else` +[3]. We’ll cover closures in more detail in Chapter 13. For now, you just need +to know that `unwrap_or_else` will pass the inner value of the `Err`, which in this case is the static string `"not enough arguments"` that we added in Listing 12-9, to our closure in the argument `err` that appears between the vertical pipes [4]. The code in the closure can then use the `err` value when @@ -721,12 +721,12 @@ Problem parsing arguments: not enough arguments Great! This output is much friendlier for our users. -### Extracting Logic from `main` +### Extracting Logic from main Now that we’ve finished refactoring the configuration parsing, let’s turn to the program’s logic. As we stated in “Separation of Concerns for Binary -Projectsâ€, we’ll extract a function named `run` that will hold all the logic -currently in the `main` function that isn’t involved with setting up +Projects†on page XX, we’ll extract a function named `run` that will hold all +the logic currently in the `main` function that isn’t involved with setting up configuration or handling errors. When we’re done, `main` will be concise and easy to verify by inspection, and we’ll be able to write tests for all the other logic. @@ -739,7 +739,7 @@ Filename: src/main.rs ``` fn main() { - // --snip-- + --snip-- println!("Searching for {}", config.query); println!("In file {}", config.file_path); @@ -754,7 +754,7 @@ fn run(config: Config) { println!("With text:\n{contents}"); } -// --snip-- +--snip-- ``` Listing 12-11: Extracting a `run` function containing the rest of the program @@ -764,7 +764,7 @@ The `run` function now contains all the remaining logic from `main`, starting from reading the file. The `run` function takes the `Config` instance as an argument. -#### Returning Errors from the `run` Function +#### Returning Errors from the run Function With the remaining program logic separated into the `run` function, we can improve the error handling, as we did with `Config::build` in Listing 12-9. @@ -777,25 +777,25 @@ signature and body of `run`. Filename: src/main.rs ``` -[1] use std::error::Error; +1 use std::error::Error; -// --snip-- +--snip-- -[2] fn run(config: Config) -> Result<(), Box<dyn Error>> { - let contents = fs::read_to_string(config.file_path)?[3]; +2 fn run(config: Config) -> Result<(), Box<dyn Error>> { + let contents = fs::read_to_string(config.file_path)3 ?; println!("With text:\n{contents}"); - [4] Ok(()) + 4 Ok(()) } ``` Listing 12-12: Changing the `run` function to return `Result` We’ve made three significant changes here. First, we changed the return type of -the `run` function to `Result<(), Box<dyn Error>>` [2]. This function previously -returned the unit type, `()`, and we keep that as the value returned in the -`Ok` case. +the `run` function to `Result<(), Box<dyn Error>>` [2]. This function +previously returned the unit type, `()`, and we keep that as the value returned +in the `Ok` case. For the error type, we used the *trait object* `Box<dyn Error>` (and we’ve brought `std::error::Error` into scope with a `use` statement at the top [1]). @@ -803,7 +803,7 @@ We’ll cover trait objects in Chapter 17. For now, just know that `Box<dyn Error>` means the function will return a type that implements the `Error` trait, but we don’t have to specify what particular type the return value will be. This gives us flexibility to return error values that may be of different -types in different error cases. The `dyn` keyword is short for “dynamic.†+types in different error cases. The `dyn` keyword is short for *dynamic*. Second, we’ve removed the call to `expect` in favor of the `?` operator [3], as we talked about in Chapter 9. Rather than `panic!` on an error, `?` will return @@ -826,7 +826,8 @@ warning: unused `Result` that must be used | ^^^^^^^^^^^^ | = note: `#[warn(unused_must_use)]` on by default - = note: this `Result` may be an `Err` variant, which should be handled + = note: this `Result` may be an `Err` variant, which should be +handled ``` Rust tells us that our code ignored the `Result` value and the `Result` value @@ -834,7 +835,7 @@ might indicate that an error occurred. But we’re not checking to see whether o not there was an error, and the compiler reminds us that we probably meant to have some error-handling code here! Let’s rectify that problem now. -#### Handling Errors Returned from `run` in `main` +#### Handling Errors Returned from run in main We’ll check for errors and handle them using a technique similar to one we used with `Config::build` in Listing 12-10, but with a slight difference: @@ -843,7 +844,7 @@ Filename: src/main.rs ``` fn main() { - // --snip-- + --snip-- println!("Searching for {}", config.query); println!("In file {}", config.file_path); @@ -856,11 +857,11 @@ fn main() { ``` We use `if let` rather than `unwrap_or_else` to check whether `run` returns an -`Err` value and call `process::exit(1)` if it does. The `run` function doesn’t -return a value that we want to `unwrap` in the same way that `Config::build` -returns the `Config` instance. Because `run` returns `()` in the success case, -we only care about detecting an error, so we don’t need `unwrap_or_else` to -return the unwrapped value, which would only be `()`. +`Err` value and to call `process::exit(1)` if it does. The `run` function +doesn’t return a value that we want to `unwrap` in the same way that +`Config::build` returns the `Config` instance. Because `run` returns `()` in +the success case, we only care about detecting an error, so we don’t need +`unwrap_or_else` to return the unwrapped value, which would only be `()`. The bodies of the `if let` and the `unwrap_or_else` functions are the same in both cases: we print the error and exit. @@ -868,10 +869,10 @@ both cases: we print the error and exit. ### Splitting Code into a Library Crate Our `minigrep` project is looking good so far! Now we’ll split the -*src/main.rs* file and put some code into the *src/lib.rs* file. That way we +*src/main.rs* file and put some code into the *src/lib.rs* file. That way, we can test the code and have a *src/main.rs* file with fewer responsibilities. -Let’s move all the code that isn’t the `main` function from *src/main.rs* to +Let’s move all the code that isn’t in the `main` function from *src/main.rs* to *src/lib.rs*: * The `run` function definition @@ -895,13 +896,15 @@ pub struct Config { } impl Config { - pub fn build(args: &[String]) -> Result<Config, &'static str> { - // --snip-- + pub fn build( + args: &[String], + ) -> Result<Config, &'static str> { + --snip-- } } pub fn run(config: Config) -> Result<(), Box<dyn Error>> { - // --snip-- + --snip-- } ``` @@ -923,9 +926,9 @@ use std::process; use minigrep::Config; fn main() { - // --snip-- + --snip-- if let Err(e) = minigrep::run(config) { - // --snip-- + --snip-- } } ``` @@ -935,8 +938,7 @@ Listing 12-14: Using the `minigrep` library crate in *src/main.rs* We add a `use minigrep::Config` line to bring the `Config` type from the library crate into the binary crate’s scope, and we prefix the `run` function with our crate name. Now all the functionality should be connected and should -work. Run the program with `cargo run` and make sure everything works -correctly. +work. Run the program with `cargo run` and make sure everything works correctly. Whew! That was a lot of work, but we’ve set ourselves up for success in the future. Now it’s much easier to handle errors, and we’ve made the code more @@ -954,21 +956,21 @@ for the core functionality of our code. We can call functions directly with various arguments and check return values without having to call our binary from the command line. -In this section, we’ll add the searching logic to the `minigrep` program -using the test-driven development (TDD) process with the following steps: +In this section, we’ll add the searching logic to the `minigrep` program using +the test-driven development (TDD) process with the following steps: 1. Write a test that fails and run it to make sure it fails for the reason you - expect. -2. Write or modify just enough code to make the new test pass. -3. Refactor the code you just added or changed and make sure the tests - continue to pass. -4. Repeat from step 1! +expect. +1. Write or modify just enough code to make the new test pass. +1. Refactor the code you just added or changed and make sure the tests continue +to pass. +1. Repeat from step 1! Though it’s just one of many ways to write software, TDD can help drive code design. Writing the test before you write the code that makes the test pass helps to maintain high test coverage throughout the process. -We’ll test drive the implementation of the functionality that will actually do +We’ll test-drive the implementation of the functionality that will actually do the searching for the query string in the file contents and produce a list of lines that match the query. We’ll add this functionality in a function called `search`. @@ -977,11 +979,11 @@ lines that match the query. We’ll add this functionality in a function called Because we don’t need them anymore, let’s remove the `println!` statements from *src/lib.rs* and *src/main.rs* that we used to check the program’s behavior. -Then, in *src/lib.rs*, add a `tests` module with a test function, as we did in -Chapter 11. The test function specifies the behavior we want the `search` -function to have: it will take a query and the text to search, and it will -return only the lines from the text that contain the query. Listing 12-15 shows -this test, which won’t compile yet. +Then, in *src/lib.rs*, we’ll add a `tests` module with a test function, as we +did in Chapter 11. The test function specifies the behavior we want the +`search` function to have: it will take a query and the text to search, and it +will return only the lines from the text that contain the query. Listing 12-15 +shows this test, which won’t compile yet. Filename: src/lib.rs @@ -998,7 +1000,10 @@ Rust: safe, fast, productive. Pick three."; - assert_eq!(vec!["safe, fast, productive."], search(query, contents)); + assert_eq!( + vec!["safe, fast, productive."], + search(query, contents) + ); } } ``` @@ -1006,7 +1011,7 @@ Pick three."; Listing 12-15: Creating a failing test for the `search` function we wish we had This test searches for the string `"duct"`. The text we’re searching is three -lines, only one of which contains `"duct"` (Note that the backslash after the +lines, only one of which contains `"duct"` (note that the backslash after the opening double quote tells Rust not to put a newline character at the beginning of the contents of this string literal). We assert that the value returned from the `search` function contains only the line we expect. @@ -1017,12 +1022,15 @@ principles, we’ll add just enough code to get the test to compile and run by adding a definition of the `search` function that always returns an empty vector, as shown in Listing 12-16. Then the test should compile and fail because an empty vector doesn’t match a vector containing the line `"safe, -fast, productive."` +fast, productive."`. Filename: src/lib.rs ``` -pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { +pub fn search<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { vec![] } ``` @@ -1049,16 +1057,24 @@ get this error: ``` error[E0106]: missing lifetime specifier - --> src/lib.rs:28:51 + --> src/lib.rs:31:10 | -28 | pub fn search(query: &str, contents: &str) -> Vec<&str> { - | ---- ---- ^ expected named lifetime parameter +29 | query: &str, + | ---- +30 | contents: &str, + | ---- +31 | ) -> Vec<&str> { + | ^ expected named lifetime parameter | - = help: this function's return type contains a borrowed value, but the signature does not say whether it is borrowed from `query` or `contents` + = help: this function's return type contains a borrowed value, but the +signature does not say whether it is borrowed from `query` or `contents` help: consider introducing a named lifetime parameter | -28 | pub fn search<'a>(query: &'a str, contents: &'a str) -> Vec<&'a str> { - | ++++ ++ ++ ++ +28 ~ pub fn search<'a>( +29 ~ query: &'a str, +30 ~ contents: &'a str, +31 ~ ) -> Vec<&'a str> { + | ``` Rust can’t possibly know which of the two arguments we need, so we need to tell @@ -1069,8 +1085,8 @@ syntax. Other programming languages don’t require you to connect arguments to return values in the signature, but this practice will get easier over time. You might -want to compare this example with the “Validating References with Lifetimes†-section in Chapter 10. +want to compare this example with the examples in “Validating References with +Lifetimes†on page XX. Now let’s run the test: @@ -1086,16 +1102,17 @@ 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 + right: `[]`', src/lib.rs:47:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace failures: tests::one_result -test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s error: test failed, to rerun pass '--lib' ``` @@ -1107,24 +1124,27 @@ Great, the test fails, exactly as we expected. Let’s get the test to pass! Currently, our test is failing because we always return an empty vector. To fix that and implement `search`, our program needs to follow these steps: -* Iterate through each line of the contents. -* Check whether the line contains our query string. -* If it does, add it to the list of values we’re returning. -* If it doesn’t, do nothing. -* Return the list of results that match. +1. Iterate through each line of the contents. +1. Check whether the line contains our query string. +1. If it does, add it to the list of values we’re returning. +1. If it doesn’t, do nothing. +1. Return the list of results that match. Let’s work through each step, starting with iterating through lines. -#### Iterating Through Lines with the `lines` Method +#### Iterating Through Lines with the lines Method Rust has a helpful method to handle line-by-line iteration of strings, -conveniently named `lines`, that works as shown in Listing 12-17. Note this -won’t compile yet. +conveniently named `lines`, that works as shown in Listing 12-17. Note that +this won’t compile yet. Filename: src/lib.rs ``` -pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { +pub fn search<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { for line in contents.lines() { // do something with line } @@ -1143,12 +1163,15 @@ in a collection. Next, we’ll check whether the current line contains our query string. Fortunately, strings have a helpful method named `contains` that does this for us! Add a call to the `contains` method in the `search` function, as shown in -Listing 12-18. Note this still won’t compile yet. +Listing 12-18. Note that this still won’t compile yet. Filename: src/lib.rs ``` -pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { +pub fn search<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { for line in contents.lines() { if line.contains(query) { // do something with line @@ -1160,8 +1183,8 @@ pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { Listing 12-18: Adding functionality to see whether the line contains the string in `query` -At the moment, we’re building up functionality. To get it to compile, we need -to return a value from the body as we indicated we would in the function +At the moment, we’re building up functionality. To get the code to compile, we +need to return a value from the body as we indicated we would in the function signature. #### Storing Matching Lines @@ -1174,7 +1197,10 @@ we return the vector, as shown in Listing 12-19. Filename: src/lib.rs ``` -pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { +pub fn search<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { let mut results = Vec::new(); for line in contents.lines() { @@ -1198,7 +1224,8 @@ $ cargo test running 1 test test tests::one_result ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Our test passed, so we know it works! @@ -1210,7 +1237,7 @@ but it doesn’t take advantage of some useful features of iterators. We’ll return to this example in Chapter 13, where we’ll explore iterators in detail, and look at how to improve it. -#### Using the `search` Function in the `run` Function +#### Using the search Function in the run Function Now that the `search` function is working and tested, we need to call `search` from our `run` function. We need to pass the `config.query` value and the @@ -1234,7 +1261,7 @@ pub fn run(config: Config) -> Result<(), Box<dyn Error>> { We’re still using a `for` loop to return each line from `search` and print it. Now the entire program should work! Let’s try it out, first with a word that -should return exactly one line from the Emily Dickinson poem, “frogâ€: +should return exactly one line from the Emily Dickinson poem: *frog*. ``` $ cargo run -- frog poem.txt @@ -1244,7 +1271,7 @@ $ cargo run -- frog poem.txt How public, like a frog ``` -Cool! Now let’s try a word that will match multiple lines, like “bodyâ€: +Cool! Now let’s try a word that will match multiple lines, like *body*: ``` $ cargo run -- body poem.txt @@ -1256,7 +1283,7 @@ How dreary to be somebody! ``` And finally, let’s make sure that we don’t get any lines when we search for a -word that isn’t anywhere in the poem, such as “monomorphizationâ€: +word that isn’t anywhere in the poem, such as *monomorphization*: ``` $ cargo run -- monomorphization poem.txt @@ -1281,7 +1308,7 @@ users enter it each time they want it to apply, but by instead making it an environment variable, we allow our users to set the environment variable once and have all their searches be case insensitive in that terminal session. -### Writing a Failing Test for the Case-Insensitive `search` Function +### Writing a Failing Test for the Case-Insensitive search Function We first add a new `search_case_insensitive` function that will be called when the environment variable has a value. We’ll continue to follow the TDD process, @@ -1306,7 +1333,10 @@ safe, fast, productive. Pick three. Duct tape."; - assert_eq!(vec!["safe, fast, productive."], search(query, contents)); + assert_eq!( + vec!["safe, fast, productive."], + search(query, contents) + ); } #[test] @@ -1330,7 +1360,7 @@ Listing 12-20: Adding a new failing test for the case-insensitive function we’re about to add Note that we’ve edited the old test’s `contents` too. We’ve added a new line -with the text `"Duct tape."` using a capital D that shouldn’t match the query +with the text `"Duct tape."` using a capital *D* that shouldn’t match the query `"duct"` when we’re searching in a case-sensitive manner. Changing the old test in this way helps ensure that we don’t accidentally break the case-sensitive search functionality that we’ve already implemented. This test should pass now @@ -1338,18 +1368,18 @@ and should continue to pass as we work on the case-insensitive search. The new test for the case-*insensitive* search uses `"rUsT"` as its query. In the `search_case_insensitive` function we’re about to add, the query `"rUsT"` -should match the line containing `"Rust:"` with a capital R and match the line -`"Trust me."` even though both have different casing from the query. This is -our failing test, and it will fail to compile because we haven’t yet defined +should match the line containing `"Rust:"` with a capital *R* and match the +line `"Trust me."` even though both have different casing from the query. This +is our failing test, and it will fail to compile because we haven’t yet defined the `search_case_insensitive` function. Feel free to add a skeleton implementation that always returns an empty vector, similar to the way we did for the `search` function in Listing 12-16 to see the test compile and fail. -### Implementing the `search_case_insensitive` Function +### Implementing the search_case_insensitive Function The `search_case_insensitive` function, shown in Listing 12-21, will be almost the same as the `search` function. The only difference is that we’ll lowercase -the `query` and each `line` so whatever the case of the input arguments, +the `query` and each `line` so that whatever the case of the input arguments, they’ll be the same case when we check whether the line contains the query. Filename: src/lib.rs @@ -1359,11 +1389,11 @@ pub fn search_case_insensitive<'a>( query: &str, contents: &'a str, ) -> Vec<&'a str> { - [1] let query = query.to_lowercase(); + 1 let query = query.to_lowercase(); let mut results = Vec::new(); for line in contents.lines() { - if line.to_lowercase()[2].contains(&query[3]) { + if 2 line.to_lowercase().contains(3 &query) { results.push(line); } } @@ -1375,8 +1405,8 @@ pub fn search_case_insensitive<'a>( Listing 12-21: Defining the `search_case_insensitive` function to lowercase the query and the line before comparing them -First, we lowercase the `query` string and store it in a shadowed variable with -the same name [1]. Calling `to_lowercase` on the query is necessary so no +First we lowercase the `query` string and store it in a shadowed variable with +the same name [1]. Calling `to_lowercase` on the query is necessary so that no matter whether the user’s query is `"rust"`, `"RUST"`, `"Rust"`, or `"rUsT"`, we’ll treat the query as if it were `"rust"` and be insensitive to the case. While `to_lowercase` will handle basic Unicode, it won’t be 100% accurate. If @@ -1384,7 +1414,7 @@ we were writing a real application, we’d want to do a bit more work here, but this section is about environment variables, not Unicode, so we’ll leave it at that here. -Note that `query` is now a `String` rather than a string slice, because calling +Note that `query` is now a `String` rather than a string slice because calling `to_lowercase` creates new data rather than referencing existing data. Say the query is `"rUsT"`, as an example: that string slice doesn’t contain a lowercase `u` or `t` for us to use, so we have to allocate a new `String` containing @@ -1403,14 +1433,15 @@ running 2 tests test tests::case_insensitive ... ok test tests::case_sensitive ... ok -test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 2 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.00s ``` Great! They passed. Now, let’s call the new `search_case_insensitive` function -from the `run` function. First, we’ll add a configuration option to the -`Config` struct to switch between case-sensitive and case-insensitive search. -Adding this field will cause compiler errors because we aren’t initializing -this field anywhere yet: +from the `run` function. First we’ll add a configuration option to the `Config` +struct to switch between case-sensitive and case-insensitive search. Adding +this field will cause compiler errors because we aren’t initializing this field +anywhere yet: Filename: src/lib.rs @@ -1461,10 +1492,12 @@ Filename: src/lib.rs ``` use std::env; -// --snip-- +--snip-- impl Config { - pub fn build(args: &[String]) -> Result<Config, &'static str> { + pub fn build( + args: &[String] + ) -> Result<Config, &'static str> { if args.len() < 3 { return Err("not enough arguments"); } @@ -1486,7 +1519,7 @@ impl Config { Listing 12-23: Checking for any value in an environment variable named `IGNORE_CASE` -Here, we create a new variable `ignore_case`. To set its value, we call the +Here, we create a new variable, `ignore_case`. To set its value, we call the `env::var` function and pass it the name of the `IGNORE_CASE` environment variable. The `env::var` function returns a `Result` that will be the successful `Ok` variant that contains the value of the environment variable if @@ -1496,7 +1529,7 @@ if the environment variable is not set. We’re using the `is_ok` method on the `Result` to check whether the environment variable is set, which means the program should do a case-insensitive search. If the `IGNORE_CASE` environment variable isn’t set to anything, `is_ok` will -return false and the program will perform a case-sensitive search. We don’t +return `false` and the program will perform a case-sensitive search. We don’t care about the *value* of the environment variable, just whether it’s set or unset, so we’re checking `is_ok` rather than using `unwrap`, `expect`, or any of the other methods we’ve seen on `Result`. @@ -1505,9 +1538,9 @@ We pass the value in the `ignore_case` variable to the `Config` instance so the `run` function can read that value and decide whether to call `search_case_insensitive` or `search`, as we implemented in Listing 12-22. -Let’s give it a try! First, we’ll run our program without the environment +Let’s give it a try! First we’ll run our program without the environment variable set and with the query `to`, which should match any line that contains -the word “to†in all lowercase: +the word *to* in all lowercase: ``` $ cargo run -- to poem.txt @@ -1518,8 +1551,8 @@ Are you nobody, too? How dreary to be somebody! ``` -Looks like that still works! Now, let’s run the program with `IGNORE_CASE` -set to `1` but with the same query `to`. +Looks like that still works! Now let’s run the program with `IGNORE_CASE` set +to `1` but with the same query `to`: ``` $ IGNORE_CASE=1 cargo run -- to poem.txt @@ -1532,14 +1565,14 @@ run the program as separate commands: PS> $Env:IGNORE_CASE=1; cargo run -- to poem.txt ``` -This will make `IGNORE_CASE` persist for the remainder of your shell -session. It can be unset with the `Remove-Item` cmdlet: +This will make `IGNORE_CASE` persist for the remainder of your shell session. +It can be unset with the `Remove-Item` cmdlet: ``` PS> Remove-Item Env:IGNORE_CASE ``` -We should get lines that contain “to†that might have uppercase letters: +We should get lines that contain *to* that might have uppercase letters: ``` Are you nobody, too? @@ -1548,7 +1581,7 @@ To tell your name the livelong day To an admiring bog! ``` -Excellent, we also got lines containing “Toâ€! Our `minigrep` program can now do +Excellent, we also got lines containing *To*! Our `minigrep` program can now do case-insensitive searching controlled by an environment variable. Now you know how to manage options set using either command line arguments or environment variables. @@ -1573,12 +1606,12 @@ error messages. This distinction enables users to choose to direct the successful output of a program to a file but still print error messages to the screen. -The `println!` macro is only capable of printing to standard output, so we -have to use something else to print to standard error. +The `println!` macro is only capable of printing to standard output, so we have +to use something else to print to standard error. ### Checking Where Errors Are Written -First, let’s observe how the content printed by `minigrep` is currently being +First let’s observe how the content printed by `minigrep` is currently being written to standard output, including any error messages we want to write to standard error instead. We’ll do that by redirecting the standard output stream to a file while intentionally causing an error. We won’t redirect the standard @@ -1587,7 +1620,7 @@ the screen. Command line programs are expected to send error messages to the standard error stream so we can still see error messages on the screen even if we redirect the -standard output stream to a file. Our program is not currently well-behaved: +standard output stream to a file. Our program is not currently well behaved: we’re about to see that it saves the error message output to a file instead! To demonstrate this behavior, we’ll run the program with `>` and the file path, @@ -1684,3 +1717,4 @@ well tested. Next, we’ll explore some Rust features that were influenced by functional languages: closures and iterators. + diff --git a/src/doc/book/nostarch/chapter13.md b/src/doc/book/nostarch/chapter13.md index 8f7717ccb..52c1f5f97 100644 --- a/src/doc/book/nostarch/chapter13.md +++ b/src/doc/book/nostarch/chapter13.md @@ -23,15 +23,15 @@ More specifically, we’ll cover: * *Closures*, a function-like construct you can store in a variable * *Iterators*, a way of processing a series of elements * How to use closures and iterators to improve the I/O project in Chapter 12 -* The performance of closures and iterators (Spoiler alert: they’re faster than - you might think!) +* The performance of closures and iterators (spoiler alert: they’re faster than +you might think!) We’ve already covered some other Rust features, such as pattern matching and enums, that are also influenced by the functional style. Because mastering closures and iterators is an important part of writing idiomatic, fast Rust code, we’ll devote this entire chapter to them. -## Closures: Anonymous Functions that Capture Their Environment +## Closures: Anonymous Functions That Capture Their Environment Rust’s closures are anonymous functions you can save in a variable or pass as arguments to other functions. You can create the closure in one place and then @@ -43,8 +43,8 @@ customization. ### Capturing the Environment with Closures We’ll first examine how we can use closures to capture values from the -environment they’re defined in for later use. Here’s the scenario: Every so -often, our t-shirt company gives away an exclusive, limited-edition shirt to +environment they’re defined in for later use. Here’s the scenario: every so +often, our T-shirt company gives away an exclusive, limited-edition shirt to someone on our mailing list as a promotion. People on the mailing list can optionally add their favorite color to their profile. If the person chosen for a free shirt has their favorite color set, they get that color shirt. If the @@ -56,9 +56,9 @@ enum called `ShirtColor` that has the variants `Red` and `Blue` (limiting the number of colors available for simplicity). We represent the company’s inventory with an `Inventory` struct that has a field named `shirts` that contains a `Vec<ShirtColor>` representing the shirt colors currently in stock. -The method `giveaway` defined on `Inventory` gets the optional shirt -color preference of the free shirt winner, and returns the shirt color the -person will get. This setup is shown in Listing 13-1: +The method `giveaway` defined on `Inventory` gets the optional shirt color +preference of the free-shirt winner, and returns the shirt color the person +will get. This setup is shown in Listing 13-1. Filename: src/main.rs @@ -74,8 +74,11 @@ struct Inventory { } impl Inventory { - fn giveaway(&self, user_preference: Option<ShirtColor>) -> ShirtColor { - user_preference.unwrap_or_else(|| self.most_stocked()) [1] + fn giveaway( + &self, + user_preference: Option<ShirtColor>, + ) -> ShirtColor { + 1 user_preference.unwrap_or_else(|| self.most_stocked()) } fn most_stocked(&self) -> ShirtColor { @@ -98,18 +101,22 @@ impl Inventory { fn main() { let store = Inventory { - shirts: vec![ShirtColor::Blue, ShirtColor::Red, ShirtColor::Blue], [2] + 2 shirts: vec![ + ShirtColor::Blue, + ShirtColor::Red, + ShirtColor::Blue, + ], }; let user_pref1 = Some(ShirtColor::Red); - let giveaway1 = store.giveaway(user_pref1); [3] + 3 let giveaway1 = store.giveaway(user_pref1); println!( "The user with preference {:?} gets {:?}", user_pref1, giveaway1 ); let user_pref2 = None; - let giveaway2 = store.giveaway(user_pref2); [4] + 4 let giveaway2 = store.giveaway(user_pref2); println!( "The user with preference {:?} gets {:?}", user_pref2, giveaway2 @@ -125,11 +132,11 @@ method for a user with a preference for a red shirt [3] and a user without any preference [4]. Again, this code could be implemented in many ways, and here, to focus on -closures, we’ve stuck to concepts you’ve already learned except for the body of -the `giveaway` method that uses a closure. In the `giveaway` method, we get the -user preference as a parameter of type `Option<ShirtColor>` and call the -`unwrap_or_else` method on `user_preference` [1]. The `unwrap_or_else` method on -`Option<T>` is defined by the standard library. It takes one argument: a +closures, we’ve stuck to concepts you’ve already learned, except for the body +of the `giveaway` method that uses a closure. In the `giveaway` method, we get +the user preference as a parameter of type `Option<ShirtColor>` and call the +`unwrap_or_else` method on `user_preference` [1]. The `unwrap_or_else` method +on `Option<T>` is defined by the standard library. It takes one argument: a closure without any arguments that returns a value `T` (the same type stored in the `Some` variant of the `Option<T>`, in this case `ShirtColor`). If the `Option<T>` is the `Some` variant, `unwrap_or_else` returns the value from @@ -138,18 +145,14 @@ calls the closure and returns the value returned by the closure. We specify the closure expression `|| self.most_stocked()` as the argument to `unwrap_or_else`. This is a closure that takes no parameters itself (if the -closure had parameters, they would appear between the two vertical bars). The +closure had parameters, they would appear between the two vertical pipes). The body of the closure calls `self.most_stocked()`. We’re defining the closure here, and the implementation of `unwrap_or_else` will evaluate the closure later if the result is needed. -Running this code prints: +Running this code prints the following: ``` -$ cargo run - Compiling shirt-company v0.1.0 (file:///projects/shirt-company) - Finished dev [unoptimized + debuginfo] target(s) in 0.27s - Running `target/debug/shirt-company` The user with preference Some(Red) gets Red The user with preference None gets Blue ``` @@ -184,7 +187,7 @@ explicitness and clarity at the cost of being more verbose than is strictly necessary. Annotating the types for a closure would look like the definition shown in Listing 13-2. In this example, we’re defining a closure and storing it in a variable rather than defining the closure in the spot we pass it as an -argument as we did in Listing 13-1. +argument, as we did in Listing 13-1. Filename: src/main.rs @@ -200,11 +203,11 @@ Listing 13-2: Adding optional type annotations of the parameter and return value types in the closure With type annotations added, the syntax of closures looks more similar to the -syntax of functions. Here we define a function that adds 1 to its parameter and -a closure that has the same behavior, for comparison. We’ve added some spaces -to line up the relevant parts. This illustrates how closure syntax is similar -to function syntax except for the use of pipes and the amount of syntax that is -optional: +syntax of functions. Here, we define a function that adds 1 to its parameter +and a closure that has the same behavior, for comparison. We’ve added some +spaces to line up the relevant parts. This illustrates how closure syntax is +similar to function syntax except for the use of pipes and the amount of syntax +that is optional: ``` fn add_one_v1 (x: u32) -> u32 { x + 1 } @@ -213,13 +216,13 @@ let add_one_v3 = |x| { x + 1 }; let add_one_v4 = |x| x + 1 ; ``` -The first line shows a function definition, and the second line shows a fully +The first line shows a function definition and the second line shows a fully annotated closure definition. In the third line, we remove the type annotations -from the closure definition. In the fourth line, we remove the brackets, which -are optional because the closure body has only one expression. These are all -valid definitions that will produce the same behavior when they’re called. The -`add_one_v3` and `add_one_v4` lines require the closures to be evaluated to be -able to compile because the types will be inferred from their usage. This is +from the closure definition. In the fourth line, we remove the curly brackets, +which are optional because the closure body has only one expression. These are +all valid definitions that will produce the same behavior when they’re called. +The `add_one_v3` and `add_one_v4` lines require the closures to be evaluated to +be able to compile because the types will be inferred from their usage. This is similar to `let v = Vec::new();` needing either type annotations or values of some type to be inserted into the `Vec` for Rust to be able to infer the type. @@ -251,7 +254,8 @@ error[E0308]: mismatched types --> src/main.rs:5:29 | 5 | let n = example_closure(5); - | ^- help: try using a conversion method: `.to_string()` + | ^- help: try using a conversion method: +`.to_string()` | | | expected struct `String`, found integer ``` @@ -271,7 +275,7 @@ captured values. In Listing 13-4, we define a closure that captures an immutable reference to the vector named `list` because it only needs an immutable reference to print -the value: +the value. Filename: src/main.rs @@ -280,10 +284,10 @@ fn main() { let list = vec![1, 2, 3]; println!("Before defining closure: {:?}", list); - [1] let only_borrows = || println!("From closure: {:?}", list); + 1 let only_borrows = || println!("From closure: {:?}", list); println!("Before calling closure: {:?}", list); - only_borrows(); [2] + 2 only_borrows(); println!("After calling closure: {:?}", list); } ``` @@ -308,7 +312,7 @@ After calling closure: [1, 2, 3] ``` Next, in Listing 13-5, we change the closure body so that it adds an element to -the `list` vector. The closure now captures a mutable reference: +the `list` vector. The closure now captures a mutable reference. Filename: src/main.rs @@ -350,7 +354,7 @@ the data so that it’s owned by the new thread. We’ll discuss threads and why you would want to use them in detail in Chapter 16 when we talk about concurrency, but for now, let’s briefly explore spawning a new thread using a closure that needs the `move` keyword. Listing 13-6 shows Listing 13-4 modified -to print the vector in a new thread rather than in the main thread: +to print the vector in a new thread rather than in the main thread. Filename: src/main.rs @@ -361,8 +365,8 @@ fn main() { let list = vec![1, 2, 3]; println!("Before defining closure: {:?}", list); - [1] thread::spawn(move || { - [2] println!("From thread: {:?}", list) + 1 thread::spawn(move || { + 2 println!("From thread: {:?}", list) }).join().unwrap(); } ``` @@ -372,29 +376,30 @@ ownership of `list` We spawn a new thread, giving the thread a closure to run as an argument. The closure body prints out the list. In Listing 13-4, the closure only captured -`list` using an immutable reference because that's the least amount of access +`list` using an immutable reference because that’s the least amount of access to `list` needed to print it. In this example, even though the closure body -still only needs an immutable reference, we need to specify that `list` should -be moved into the closure by putting the `move` keyword at the beginning of the -closure definition. The new thread might finish before the rest of the main -thread finishes, or the main thread might finish first. If the main thread -maintained ownership of `list` but ended before the new thread did and dropped -`list`, the immutable reference in the thread would be invalid. Therefore, the -compiler requires that `list` be moved into the closure given to the new thread -so the reference will be valid. Try removing the `move` keyword or using `list` -in the main thread after the closure is defined to see what compiler errors you -get! - -### Moving Captured Values Out of Closures and the `Fn` Traits +still only needs an immutable reference [2], we need to specify that `list` +should be moved into the closure by putting the `move` keyword [1] at the +beginning of the closure definition. The new thread might finish before the +rest of the main thread finishes, or the main thread might finish first. If the +main thread maintains ownership of `list` but ends before the new thread and +drops `list`, the immutable reference in the thread would be invalid. +Therefore, the compiler requires that `list` be moved into the closure given to +the new thread so the reference will be valid. Try removing the `move` keyword +or using `list` in the main thread after the closure is defined to see what +compiler errors you get! + +### Moving Captured Values Out of Closures and the Fn Traits Once a closure has captured a reference or captured ownership of a value from the environment where the closure is defined (thus affecting what, if anything, is moved *into* the closure), the code in the body of the closure defines what happens to the references or values when the closure is evaluated later (thus -affecting what, if anything, is moved *out of* the closure). A closure body can -do any of the following: move a captured value out of the closure, mutate the -captured value, neither move nor mutate the value, or capture nothing from the -environment to begin with. +affecting what, if anything, is moved *out of* the closure). + +A closure body can do any of the following: move a captured value out of the +closure, mutate the captured value, neither move nor mutate the value, or +capture nothing from the environment to begin with. The way a closure captures and handles values from the environment affects which traits the closure implements, and traits are how functions and structs @@ -402,18 +407,18 @@ can specify what kinds of closures they can use. Closures will automatically implement one, two, or all three of these `Fn` traits, in an additive fashion, depending on how the closure’s body handles the values: -1. `FnOnce` applies to closures that can be called once. All closures implement - at least this trait, because all closures can be called. A closure that - moves captured values out of its body will only implement `FnOnce` and none - of the other `Fn` traits, because it can only be called once. -2. `FnMut` applies to closures that don’t move captured values out of their - body, but that might mutate the captured values. These closures can be - called more than once. -3. `Fn` applies to closures that don’t move captured values out of their body - and that don’t mutate captured values, as well as closures that capture - nothing from their environment. These closures can be called more than once - without mutating their environment, which is important in cases such as - calling a closure multiple times concurrently. +* `FnOnce` applies to closures that can be called once. All closures implement +at least this trait because all closures can be called. A closure that moves +captured values out of its body will only implement `FnOnce` and none of the +other `Fn` traits because it can only be called once. +* `FnMut` applies to closures that don’t move captured values out of their +body, but that might mutate the captured values. These closures can be called +more than once. +* `Fn` applies to closures that don’t move captured values out of their body +and that don’t mutate captured values, as well as closures that capture nothing +from their environment. These closures can be called more than once without +mutating their environment, which is important in cases such as calling a +closure multiple times concurrently. Let’s look at the definition of the `unwrap_or_else` method on `Option<T>` that we used in Listing 13-1: @@ -444,27 +449,27 @@ the closure we provide when calling `unwrap_or_else`. The trait bound specified on the generic type `F` is `FnOnce() -> T`, which means `F` must be able to be called once, take no arguments, and return a `T`. Using `FnOnce` in the trait bound expresses the constraint that -`unwrap_or_else` is only going to call `f` at most one time. In the body of +`unwrap_or_else` is only going to call `f` one time, at most. In the body of `unwrap_or_else`, we can see that if the `Option` is `Some`, `f` won’t be called. If the `Option` is `None`, `f` will be called once. Because all -closures implement `FnOnce`, `unwrap_or_else` accepts the most different kinds -of closures and is as flexible as it can be. +closures implement `FnOnce`, `unwrap_or_else` accepts the largest variety of +closures and is as flexible as it can be. > Note: Functions can implement all three of the `Fn` traits too. If what we -> want to do doesn’t require capturing a value from the environment, we can use -> the name of a function rather than a closure where we need something that -> implements one of the `Fn` traits. For example, on an `Option<Vec<T>>` value, -> we could call `unwrap_or_else(Vec::new)` to get a new, empty vector if the -> value is `None`. +want to do doesn’t require capturing a value from the environment, we can use +the name of a function rather than a closure where we need something that +implements one of the `Fn` traits. For example, on an `Option<Vec<T>>` value, +we could call `unwrap_or_else(Vec::new)` to get a new, empty vector if the +value is `None`. -Now let’s look at the standard library method `sort_by_key` defined on slices, +Now let’s look at the standard library method `sort_by_key`, defined on slices, to see how that differs from `unwrap_or_else` and why `sort_by_key` uses `FnMut` instead of `FnOnce` for the trait bound. The closure gets one argument in the form of a reference to the current item in the slice being considered, and returns a value of type `K` that can be ordered. This function is useful when you want to sort a slice by a particular attribute of each item. In Listing 13-7, we have a list of `Rectangle` instances and we use `sort_by_key` -to order them by their `width` attribute from low to high: +to order them by their `width` attribute from low to high. Filename: src/main.rs @@ -510,21 +515,17 @@ This code prints: The reason `sort_by_key` is defined to take an `FnMut` closure is that it calls the closure multiple times: once for each item in the slice. The closure `|r| -r.width` doesn’t capture, mutate, or move out anything from its environment, so +r.width` doesn’t capture, mutate, or move anything out from its environment, so it meets the trait bound requirements. In contrast, Listing 13-8 shows an example of a closure that implements just the `FnOnce` trait, because it moves a value out of the environment. The -compiler won’t let us use this closure with `sort_by_key`: +compiler won’t let us use this closure with `sort_by_key`. Filename: src/main.rs ``` -#[derive(Debug)] -struct Rectangle { - width: u32, - height: u32, -} +--snip-- fn main() { let mut list = [ @@ -549,7 +550,7 @@ Listing 13-8: Attempting to use an `FnOnce` closure with `sort_by_key` This is a contrived, convoluted way (that doesn’t work) to try and count the number of times `sort_by_key` gets called when sorting `list`. This code attempts to do this counting by pushing `value`—a `String` from the closure’s -environment—into the `sort_operations` vector. The closure captures `value` +environment—into the `sort_operations` vector. The closure captures `value` and then moves `value` out of the closure by transferring ownership of `value` to the `sort_operations` vector. This closure can be called once; trying to call it a second time wouldn’t work because `value` would no longer be in the @@ -559,7 +560,8 @@ that `value` can’t be moved out of the closure because the closure must implement `FnMut`: ``` -error[E0507]: cannot move out of `value`, a captured variable in an `FnMut` closure +error[E0507]: cannot move out of `value`, a captured variable in an `FnMut` +closure --> src/main.rs:18:30 | 15 | let value = String::from("by key called"); @@ -568,7 +570,8 @@ error[E0507]: cannot move out of `value`, a captured variable in an `FnMut` clos 17 | list.sort_by_key(|r| { | ______________________- 18 | | sort_operations.push(value); - | | ^^^^^ move occurs because `value` has type `String`, which does not implement the `Copy` trait + | | ^^^^^ move occurs because `value` has +type `String`, which does not implement the `Copy` trait 19 | | r.width 20 | | }); | |_____- captured by this `FnMut` closure @@ -576,39 +579,33 @@ error[E0507]: cannot move out of `value`, a captured variable in an `FnMut` clos The error points to the line in the closure body that moves `value` out of the environment. To fix this, we need to change the closure body so that it doesn’t -move values out of the environment. To count the number of times `sort_by_key` -is called, keeping a counter in the environment and incrementing its value in -the closure body is a more straightforward way to calculate that. The closure -in Listing 13-9 works with `sort_by_key` because it is only capturing a mutable -reference to the `num_sort_operations` counter and can therefore be called more -than once: +move values out of the environment. Keeping a counter in the environment and +incrementing its value in the closure body is a more straightforward way to +count the number of times `sort_by_key` is called. The closure in Listing 13-9 +works with `sort_by_key` because it is only capturing a mutable reference to +the `num_sort_operations` counter and can therefore be called more than once. Filename: src/main.rs ``` -#[derive(Debug)] -struct Rectangle { - width: u32, - height: u32, -} +--snip-- fn main() { - let mut list = [ - Rectangle { width: 10, height: 1 }, - Rectangle { width: 3, height: 5 }, - Rectangle { width: 7, height: 12 }, - ]; + --snip-- let mut num_sort_operations = 0; list.sort_by_key(|r| { num_sort_operations += 1; r.width }); - println!("{:#?}, sorted in {num_sort_operations} operations", list); + println!( + "{:#?}, sorted in {num_sort_operations} operations", + list + ); } ``` -Listing 13-9: Using an `FnMut` closure with `sort_by_key` is allowed +Listing 13-9: Using an `FnMut` closure with `sort_by_key` is allowed. The `Fn` traits are important when defining or using functions or types that make use of closures. In the next section, we’ll discuss iterators. Many @@ -637,10 +634,10 @@ let v1_iter = v1.iter(); Listing 13-10: Creating an iterator The iterator is stored in the `v1_iter` variable. Once we’ve created an -iterator, we can use it in a variety of ways. In Listing 3-5 in Chapter 3, we -iterated over an array using a `for` loop to execute some code on each of its -items. Under the hood this implicitly created and then consumed an iterator, -but we glossed over how exactly that works until now. +iterator, we can use it in a variety of ways. In Listing 3-5, we iterated over +an array using a `for` loop to execute some code on each of its items. Under +the hood, this implicitly created and then consumed an iterator, but we glossed +over how exactly that works until now. In the example in Listing 13-11, we separate the creation of the iterator from the use of the iterator in the `for` loop. When the `for` loop is called using @@ -653,7 +650,7 @@ let v1 = vec![1, 2, 3]; let v1_iter = v1.iter(); for val in v1_iter { - println!("Got: {}", val); + println!("Got: {val}"); } ``` @@ -665,12 +662,12 @@ you would likely write this same functionality by starting a variable at index incrementing the variable value in a loop until it reached the total number of items in the vector. -Iterators handle all that logic for you, cutting down on repetitive code you +Iterators handle all of that logic for you, cutting down on repetitive code you could potentially mess up. Iterators give you more flexibility to use the same logic with many different kinds of sequences, not just data structures you can index into, like vectors. Let’s examine how iterators do that. -### The `Iterator` Trait and the `next` Method +### The Iterator Trait and the next Method All iterators implement a trait named `Iterator` that is defined in the standard library. The definition of the trait looks like this: @@ -685,7 +682,7 @@ pub trait Iterator { } ``` -Notice this definition uses some new syntax: `type Item` and `Self::Item`, +Notice that this definition uses some new syntax: `type Item` and `Self::Item`, which are defining an *associated type* with this trait. We’ll talk about associated types in depth in Chapter 19. For now, all you need to know is that this code says implementing the `Iterator` trait requires that you also define @@ -694,8 +691,8 @@ method. In other words, the `Item` type will be the type returned from the iterator. The `Iterator` trait only requires implementors to define one method: the -`next` method, which returns one item of the iterator at a time wrapped in -`Some` and, when iteration is over, returns `None`. +`next` method, which returns one item of the iterator at a time, wrapped in +`Some`, and, when iteration is over, returns `None`. We can call the `next` method on iterators directly; Listing 13-12 demonstrates what values are returned from repeated calls to `next` on the iterator created @@ -733,7 +730,7 @@ ownership of `v1` and returns owned values, we can call `into_iter` instead of `iter`. Similarly, if we want to iterate over mutable references, we can call `iter_mut` instead of `iter`. -### Methods that Consume the Iterator +### Methods That Consume the Iterator The `Iterator` trait has a number of different methods with default implementations provided by the standard library; you can find out about these @@ -742,12 +739,12 @@ trait. Some of these methods call the `next` method in their definition, which is why you’re required to implement the `next` method when implementing the `Iterator` trait. -Methods that call `next` are called *consuming adaptors*, because calling them +Methods that call `next` are called *consuming adapters* because calling them uses up the iterator. One example is the `sum` method, which takes ownership of the iterator and iterates through the items by repeatedly calling `next`, thus consuming the iterator. As it iterates through, it adds each item to a running total and returns the total when iteration is complete. Listing 13-13 has a -test illustrating a use of the `sum` method: +test illustrating a use of the `sum` method. Filename: src/lib.rs @@ -770,17 +767,17 @@ iterator We aren’t allowed to use `v1_iter` after the call to `sum` because `sum` takes ownership of the iterator we call it on. -### Methods that Produce Other Iterators +### Methods That Produce Other Iterators -*Iterator adaptors* are methods defined on the `Iterator` trait that don’t +*Iterator adapters* are methods defined on the `Iterator` trait that don’t consume the iterator. Instead, they produce different iterators by changing some aspect of the original iterator. -Listing 13-17 shows an example of calling the iterator adaptor method `map`, +Listing 13-14 shows an example of calling the iterator adapter method `map`, which takes a closure to call on each item as the items are iterated through. The `map` method returns a new iterator that produces the modified items. The closure here creates a new iterator in which each item from the vector will be -incremented by 1: +incremented by 1. Filename: src/main.rs @@ -790,7 +787,7 @@ let v1: Vec<i32> = vec![1, 2, 3]; v1.iter().map(|x| x + 1); ``` -Listing 13-14: Calling the iterator adaptor `map` to create a new iterator +Listing 13-14: Calling the iterator adapter `map` to create a new iterator However, this code produces a warning: @@ -806,17 +803,16 @@ warning: unused `Map` that must be used ``` The code in Listing 13-14 doesn’t do anything; the closure we’ve specified -never gets called. The warning reminds us why: iterator adaptors are lazy, and +never gets called. The warning reminds us why: iterator adapters are lazy, and we need to consume the iterator here. To fix this warning and consume the iterator, we’ll use the `collect` method, -which we used in Chapter 12 with `env::args` in Listing 12-1. This method -consumes the iterator and collects the resulting values into a collection data -type. +which we used with `env::args` in Listing 12-1. This method consumes the +iterator and collects the resultant values into a collection data type. -In Listing 13-15, we collect the results of iterating over the iterator that’s -returned from the call to `map` into a vector. This vector will end up -containing each item from the original vector incremented by 1. +In Listing 13-15, we collect into a vector the results of iterating over the +iterator that’s returned from the call to `map`. This vector will end up +containing each item from the original vector, incremented by 1. Filename: src/main.rs @@ -828,7 +824,7 @@ let v2: Vec<_> = v1.iter().map(|x| x + 1).collect(); assert_eq!(v2, vec![2, 3, 4]); ``` -Listing 13-15: Calling the `map` method to create a new iterator and then +Listing 13-15: Calling the `map` method to create a new iterator, and then calling the `collect` method to consume the new iterator and create a vector Because `map` takes a closure, we can specify any operation we want to perform @@ -836,11 +832,11 @@ on each item. This is a great example of how closures let you customize some behavior while reusing the iteration behavior that the `Iterator` trait provides. -You can chain multiple calls to iterator adaptors to perform complex actions in +You can chain multiple calls to iterator adapters to perform complex actions in a readable way. But because all iterators are lazy, you have to call one of the -consuming adaptor methods to get results from calls to iterator adaptors. +consuming adapter methods to get results from calls to iterator adapters. -### Using Closures that Capture Their Environment +### Using Closures That Capture Their Environment Many iterator adapters take closures as arguments, and commonly the closures we’ll specify as arguments to iterator adapters will be closures that capture @@ -915,18 +911,18 @@ The `shoes_in_size` function takes ownership of a vector of shoes and a shoe size as parameters. It returns a vector containing only shoes of the specified size. -In the body of `shoes_in_size`, we call `into_iter` to create an iterator -that takes ownership of the vector. Then we call `filter` to adapt that -iterator into a new iterator that only contains elements for which the closure -returns `true`. +In the body of `shoes_in_size`, we call `into_iter` to create an iterator that +takes ownership of the vector. Then we call `filter` to adapt that iterator +into a new iterator that only contains elements for which the closure returns +`true`. The closure captures the `shoe_size` parameter from the environment and compares the value with each shoe’s size, keeping only shoes of the size specified. Finally, calling `collect` gathers the values returned by the adapted iterator into a vector that’s returned by the function. -The test shows that when we call `shoes_in_size`, we get back only shoes -that have the same size as the value we specified. +The test shows that when we call `shoes_in_size`, we get back only shoes that +have the same size as the value we specified. ## Improving Our I/O Project @@ -935,19 +931,21 @@ Chapter 12 by using iterators to make places in the code clearer and more concise. Let’s look at how iterators can improve our implementation of the `Config::build` function and the `search` function. -### Removing a `clone` Using an Iterator +### Removing a clone Using an Iterator In Listing 12-6, we added code that took a slice of `String` values and created an instance of the `Config` struct by indexing into the slice and cloning the values, allowing the `Config` struct to own those values. In Listing 13-17, we’ve reproduced the implementation of the `Config::build` function as it was -in Listing 12-23: +in Listing 12-23. Filename: src/lib.rs ``` impl Config { - pub fn build(args: &[String]) -> Result<Config, &'static str> { + pub fn build( + args: &[String] + ) -> Result<Config, &'static str> { if args.len() < 3 { return Err("not enough arguments"); } @@ -1001,7 +999,7 @@ fn main() { process::exit(1); }); - // --snip-- + --snip-- } ``` @@ -1013,12 +1011,13 @@ Filename: src/main.rs ``` fn main() { - let config = Config::build(env::args()).unwrap_or_else(|err| { - eprintln!("Problem parsing arguments: {err}"); - process::exit(1); - }); + let config = + Config::build(env::args()).unwrap_or_else(|err| { + eprintln!("Problem parsing arguments: {err}"); + process::exit(1); + }); - // --snip-- + --snip-- } ``` @@ -1031,8 +1030,8 @@ we’re passing ownership of the iterator returned from `env::args` to Next, we need to update the definition of `Config::build`. In your I/O project’s *src/lib.rs* file, let’s change the signature of `Config::build` to -look like Listing 13-19. This still won’t compile because we need to update the -function body. +look like Listing 13-19. This still won’t compile, because we need to update +the function body. Filename: src/lib.rs @@ -1041,7 +1040,7 @@ impl Config { pub fn build( mut args: impl Iterator<Item = String>, ) -> Result<Config, &'static str> { - // --snip-- + --snip-- ``` Listing 13-19: Updating the signature of `Config::build` to expect an iterator @@ -1053,18 +1052,18 @@ the `Iterator` trait and returns `String` values. We’ve updated the signature of the `Config::build` function so the parameter `args` has a generic type with the trait bounds `impl Iterator<Item = String>` instead of `&[String]`. This usage of the `impl Trait` syntax we discussed in -the “Traits as Parameters†section of Chapter 10 means that `args` can be any -type that implements the `Iterator` type and returns `String` items. +“Traits as Parameters†on page XX means that `args` can be any type that +implements the `Iterator` type and returns `String` items. Because we’re taking ownership of `args` and we’ll be mutating `args` by iterating over it, we can add the `mut` keyword into the specification of the `args` parameter to make it mutable. -#### Using `Iterator` Trait Methods Instead of Indexing +#### Using Iterator Trait Methods Instead of Indexing Next, we’ll fix the body of `Config::build`. Because `args` implements the `Iterator` trait, we know we can call the `next` method on it! Listing 13-20 -updates the code from Listing 12-23 to use the `next` method: +updates the code from Listing 12-23 to use the `next` method. Filename: src/lib.rs @@ -1100,21 +1099,24 @@ Listing 13-20: Changing the body of `Config::build` to use iterator methods Remember that the first value in the return value of `env::args` is the name of the program. We want to ignore that and get to the next value, so first we call -`next` and do nothing with the return value. Second, we call `next` to get the -value we want to put in the `query` field of `Config`. If `next` returns a +`next` and do nothing with the return value. Then we call `next` to get the +value we want to put in the `query` field of `Config`. If `next` returns `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. -### Making Code Clearer with Iterator Adaptors +### Making Code Clearer with Iterator Adapters We can also take advantage of iterators in the `search` function in our I/O -project, which is reproduced here in Listing 13-21 as it was in Listing 12-19: +project, which is reproduced here in Listing 13-21 as it was in Listing 12-19. Filename: src/lib.rs ``` -pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { +pub fn search<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { let mut results = Vec::new(); for line in contents.lines() { @@ -1129,17 +1131,20 @@ pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { Listing 13-21: The implementation of the `search` function from Listing 12-19 -We can write this code in a more concise way using iterator adaptor methods. +We can write this code in a more concise way using iterator adapter methods. Doing so also lets us avoid having a mutable intermediate `results` vector. The functional programming style prefers to minimize the amount of mutable state to make code clearer. Removing the mutable state might enable a future enhancement -to make searching happen in parallel, because we wouldn’t have to manage -concurrent access to the `results` vector. Listing 13-22 shows this change: +to make searching happen in parallel because we wouldn’t have to manage +concurrent access to the `results` vector. Listing 13-22 shows this change. Filename: src/lib.rs ``` -pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { +pub fn search<'a>( + query: &str, + contents: &'a str, +) -> Vec<&'a str> { contents .lines() .filter(|line| line.contains(query)) @@ -1147,24 +1152,23 @@ pub fn search<'a>(query: &str, contents: &'a str) -> Vec<&'a str> { } ``` -Listing 13-22: Using iterator adaptor methods in the implementation of the +Listing 13-22: Using iterator adapter methods in the implementation of the `search` function Recall that the purpose of the `search` function is to return all lines in `contents` that contain the `query`. Similar to the `filter` example in Listing -13-16, this code uses the `filter` adaptor to keep only the lines that -`line.contains(query)` returns `true` for. We then collect the matching lines -into another vector with `collect`. Much simpler! Feel free to make the same -change to use iterator methods in the `search_case_insensitive` function as -well. +13-16, this code uses the `filter` adapter to keep only the lines for which +`line.contains(query)` returns `true`. We then collect the matching lines into +another vector with `collect`. Much simpler! Feel free to make the same change +to use iterator methods in the `search_case_insensitive` function as well. -### Choosing Between Loops or Iterators +### Choosing Between Loops and Iterators The next logical question is which style you should choose in your own code and why: the original implementation in Listing 13-21 or the version using iterators in Listing 13-22. Most Rust programmers prefer to use the iterator style. It’s a bit tougher to get the hang of at first, but once you get a feel -for the various iterator adaptors and what they do, iterators can be easier to +for the various iterator adapters and what they do, iterators can be easier to understand. Instead of fiddling with the various bits of looping and building new vectors, the code focuses on the high-level objective of the loop. This abstracts away some of the commonplace code so it’s easier to see the concepts @@ -1172,8 +1176,7 @@ that are unique to this code, such as the filtering condition each element in the iterator must pass. But are the two implementations truly equivalent? The intuitive assumption -might be that the more low-level loop will be faster. Let’s talk about -performance. +might be that the lower-level loop will be faster. Let’s talk about performance. ## Comparing Performance: Loops vs. Iterators @@ -1192,8 +1195,8 @@ test bench_search_iter ... bench: 19,234,900 ns/iter (+/- 657,200) ``` The iterator version was slightly faster! We won’t explain the benchmark code -here, because the point is not to prove that the two versions are equivalent -but to get a general sense of how these two implementations compare +here because the point is not to prove that the two versions are equivalent but +to get a general sense of how these two implementations compare performance-wise. For a more comprehensive benchmark, you should check using various texts of @@ -1201,24 +1204,22 @@ various sizes as the `contents`, different words and words of different lengths as the `query`, and all kinds of other variations. The point is this: iterators, although a high-level abstraction, get compiled down to roughly the same code as if you’d written the lower-level code yourself. Iterators are one -of Rust’s *zero-cost abstractions*, by which we mean using the abstraction +of Rust’s *zero-cost abstractions*, by which we mean that using the abstraction imposes no additional runtime overhead. This is analogous to how Bjarne Stroustrup, the original designer and implementor of C++, defines *zero-overhead* in “Foundations of C++†(2012): > In general, C++ implementations obey the zero-overhead principle: What you -> don’t use, you don’t pay for. And further: What you do use, you couldn’t hand -> code any better. - -As another example, the following code is taken from an audio decoder. The -decoding algorithm uses the linear prediction mathematical operation to -estimate future values based on a linear function of the previous samples. This -code uses an iterator chain to do some math on three variables in scope: a -`buffer` slice of data, an array of 12 `coefficients`, and an amount by which -to shift data in `qlp_shift`. We’ve declared the variables within this example -but not given them any values; although this code doesn’t have much meaning -outside of its context, it’s still a concise, real-world example of how Rust -translates high-level ideas to low-level code. +don’t use, you don’t pay for. And further: What you do use, you couldn’t hand +code any better.As another example, the following code is taken from an audio +decoder. The decoding algorithm uses the linear prediction mathematical +operation to estimate future values based on a linear function of the previous +samples. This code uses an iterator chain to do some math on three variables in +scope: a `buffer` slice of data, an array of 12 `coefficients`, and an amount +by which to shift data in `qlp_shift`. We’ve declared the variables within this +example but not given them any values; although this code doesn’t have much +meaning outside of its context, it’s still a concise, real-world example of how +Rust translates high-level ideas to low-level code. ``` let buffer: &mut [i32]; @@ -1237,12 +1238,12 @@ for i in 12..buffer.len() { To calculate the value of `prediction`, this code iterates through each of the 12 values in `coefficients` and uses the `zip` method to pair the coefficient -values with the previous 12 values in `buffer`. Then, for each pair, we -multiply the values together, sum all the results, and shift the bits in the -sum `qlp_shift` bits to the right. +values with the previous 12 values in `buffer`. Then, for each pair, it +multiplies the values together, sums all the results, and shifts the bits in +the sum `qlp_shift` bits to the right. Calculations in applications like audio decoders often prioritize performance -most highly. Here, we’re creating an iterator, using two adaptors, and then +most highly. Here, we’re creating an iterator, using two adapters, and then consuming the value. What assembly code would this Rust code compile to? Well, as of this writing, it compiles down to the same assembly you’d write by hand. There’s no loop at all corresponding to the iteration over the values in @@ -1253,7 +1254,7 @@ the loop. All of the coefficients get stored in registers, which means accessing the values is very fast. There are no bounds checks on the array access at runtime. -All these optimizations that Rust is able to apply make the resulting code +All of these optimizations that Rust is able to apply make the resultant code extremely efficient. Now that you know this, you can use iterators and closures without fear! They make code seem like it’s higher level but don’t impose a runtime performance penalty for doing so. @@ -1269,3 +1270,4 @@ Rust’s goal to strive to provide zero-cost abstractions. Now that we’ve improved the expressiveness of our I/O project, let’s look at some more features of `cargo` that will help us share the project with the world. + diff --git a/src/doc/book/nostarch/chapter14.md b/src/doc/book/nostarch/chapter14.md index 076410232..f5f2be719 100644 --- a/src/doc/book/nostarch/chapter14.md +++ b/src/doc/book/nostarch/chapter14.md @@ -8,19 +8,19 @@ directory, so all fixes need to be made in `/src/`. # More About Cargo and Crates.io -So far we’ve used only the most basic features of Cargo to build, run, and test -our code, but it can do a lot more. In this chapter, we’ll discuss some of its -other, more advanced features to show you how to do the following: +So far, we’ve used only the most basic features of Cargo to build, run, and +test our code, but it can do a lot more. In this chapter, we’ll discuss some of +its other, more advanced features to show you how to do the following: -* Customize your build through release profiles -* Publish libraries on *https://crates.io/* -* Organize large projects with workspaces -* Install binaries from *https://crates.io/* -* Extend Cargo using custom commands +* Customize your build through release profiles. +* Publish libraries on *https://crates.i**o*. +* Organize large projects with workspaces. +* Install binaries from *https://crates.io*. +* Extend Cargo using custom commands. Cargo can do even more than the functionality we cover in this chapter, so for a full explanation of all its features, see its documentation at -*https://doc.rust-lang.org/cargo/*. +*https://doc.rust-lang.org/cargo*. ## Customizing Builds with Release Profiles @@ -30,7 +30,7 @@ various options for compiling code. Each profile is configured independently of the others. Cargo has two main profiles: the `dev` profile Cargo uses when you run `cargo -build` and the `release` profile Cargo uses when you run `cargo build +build`, and the `release` profile Cargo uses when you run `cargo build --release`. The `dev` profile is defined with good defaults for development, and the `release` profile has good defaults for release builds. @@ -45,7 +45,7 @@ $ cargo build --release The `dev` and `release` are these different profiles used by the compiler. -Cargo has default settings for each of the profiles that apply when you haven't +Cargo has default settings for each of the profiles that apply when you haven’t explicitly added any `[profile.*]` sections in the project’s *Cargo.toml* file. By adding `[profile.*]` sections for any profile you want to customize, you override any subset of the default settings. For example, here are the default @@ -64,7 +64,7 @@ opt-level = 3 The `opt-level` setting controls the number of optimizations Rust will apply to your code, with a range of 0 to 3. Applying more optimizations extends compiling time, so if you’re in development and compiling your code often, -you’ll want fewer optimizations to compile faster even if the resulting code +you’ll want fewer optimizations to compile faster even if the resultant code runs slower. The default `opt-level` for `dev` is therefore `0`. When you’re ready to release your code, it’s best to spend more time compiling. You’ll only compile in release mode once, but you’ll run the compiled program many times, @@ -89,11 +89,12 @@ Cargo will use the defaults for the `dev` profile plus our customization to optimizations than the default, but not as many as in a release build. For the full list of configuration options and defaults for each profile, see -Cargo’s documentation at *https://doc.rust-lang.org/cargo/reference/profiles.html*. +Cargo’s documentation at +*https://doc.rust-lang.org/cargo/reference/profiles.html*. ## Publishing a Crate to Crates.io -We’ve used packages from *https://crates.io/* as dependencies of our project, +We’ve used packages from *https://crates.io* as dependencies of our project, but you can also share your code with other people by publishing your own packages. The crate registry at *https://crates.io* distributes the source code of your packages, so it primarily hosts code that is open source. @@ -120,7 +121,7 @@ for an `add_one` function in a crate named `my_crate`. Filename: src/lib.rs -```` +``` /// Adds one to the number given. /// /// # Examples @@ -134,17 +135,10 @@ Filename: src/lib.rs pub fn add_one(x: i32) -> i32 { x + 1 } -```` +``` Listing 14-1: A documentation comment for a function -<!-- I removed two sets of ``` here because it was inverting the text and code -formatting, but you may want to check that I have't changed meaning in the -code! /LC --> -<!-- Yeah, those need to be in there. It's definitely weird that it's a code -block inside of a code block-- I think I've fixed it by adding more ` around -the outer block, but I'll check it again when we're in Word. /Carol --> - Here, we give a description of what the `add_one` function does, start a section with the heading `Examples`, and then provide code that demonstrates how to use the `add_one` function. We can generate the HTML documentation from @@ -156,9 +150,7 @@ For convenience, running `cargo doc --open` will build the HTML for your current crate’s documentation (as well as the documentation for all of your crate’s dependencies) and open the result in a web browser. Navigate to the `add_one` function and you’ll see how the text in the documentation comments is -rendered, as shown in Figure 14-1: - -<img alt="Rendered HTML documentation for the `add_one` function of `my_crate`" src="img/trpl14-01.png" class="center" /> +rendered, as shown in Figure 14-1. Figure 14-1: HTML documentation for the `add_one` function @@ -168,16 +160,16 @@ We used the `# Examples` Markdown heading in Listing 14-1 to create a section in the HTML with the title “Examples.†Here are some other sections that crate authors commonly use in their documentation: -* **Panics**: The scenarios in which the function being documented could - panic. Callers of the function who don’t want their programs to panic should - make sure they don’t call the function in these situations. +* **Panics**: The scenarios in which the function being documented could panic. +Callers of the function who don’t want their programs to panic should make sure +they don’t call the function in these situations. * **Errors**: If the function returns a `Result`, describing the kinds of - errors that might occur and what conditions might cause those errors to be - returned can be helpful to callers so they can write code to handle the - different kinds of errors in different ways. +errors that might occur and what conditions might cause those errors to be +returned can be helpful to callers so they can write code to handle the +different kinds of errors in different ways. * **Safety**: If the function is `unsafe` to call (we discuss unsafety in - Chapter 19), there should be a section explaining why the function is unsafe - and covering the invariants that the function expects callers to uphold. +Chapter 19), there should be a section explaining why the function is unsafe +and covering the invariants that the function expects callers to uphold. Most documentation comments don’t need all of these sections, but this is a good checklist to remind you of the aspects of your code users will be @@ -191,7 +183,8 @@ test` will run the code examples in your documentation as tests! Nothing is better than documentation with examples. But nothing is worse than examples that don’t work because the code has changed since the documentation was written. If we run `cargo test` with the documentation for the `add_one` -function from Listing 14-1, we will see a section in the test results like this: +function from Listing 14-1, we will see a section in the test results that +looks like this: ``` Doc-tests my_crate @@ -199,35 +192,36 @@ function from Listing 14-1, we will see a section in the test results like this: running 1 test test src/lib.rs - add_one (line 5) ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.27s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 +filtered out; finished in 0.27s ``` -Now if we change either the function or the example so the `assert_eq!` in the +Now, if we change either the function or the example so the `assert_eq!` in the example panics and run `cargo test` again, we’ll see that the doc tests catch that the example and the code are out of sync with each other! #### Commenting Contained Items -The style of doc comment `//!` adds documentation to the item that contains the -comments rather than to the items following the comments. We typically use +The doc comment `//!` adds documentation to the item that *contains* the +comments rather than to the items *following* the comments. We typically use these doc comments inside the crate root file (*src/lib.rs* by convention) or inside a module to document the crate or the module as a whole. For example, to add documentation that describes the purpose of the `my_crate` crate that contains the `add_one` function, we add documentation comments that start with `//!` to the beginning of the *src/lib.rs* file, as shown in Listing -14-2: +14-2. Filename: src/lib.rs ``` //! # My Crate //! -//! `my_crate` is a collection of utilities to make performing certain -//! calculations more convenient. +//! `my_crate` is a collection of utilities to make performing +//! certain calculations more convenient. /// Adds one to the number given. -// --snip-- +--snip-- ``` Listing 14-2: Documentation for the `my_crate` crate as a whole @@ -238,11 +232,9 @@ that contains this comment rather than an item that follows this comment. In this case, that item is the *src/lib.rs* file, which is the crate root. These comments describe the entire crate. -When we run `cargo doc --open`, these comments will display on the front -page of the documentation for `my_crate` above the list of public items in the -crate, as shown in Figure 14-2: - -<img alt="Rendered HTML documentation with a comment for the crate as a whole" src="img/trpl14-02.png" class="center" /> +When we run `cargo doc --open`, these comments will display on the front page +of the documentation for `my_crate` above the list of public items in the +crate, as shown in Figure 14-2. Figure 14-2: Rendered documentation for `my_crate`, including the comment describing the crate as a whole @@ -251,7 +243,7 @@ Documentation comments within items are useful for describing crates and modules especially. Use them to explain the overall purpose of the container to help your users understand the crate’s organization. -### Exporting a Convenient Public API with `pub use` +### Exporting a Convenient Public API with pub use The structure of your public API is a major consideration when publishing a crate. People who use your crate are less familiar with the structure than you @@ -259,26 +251,26 @@ are and might have difficulty finding the pieces they want to use if your crate has a large module hierarchy. In Chapter 7, we covered how to make items public using the `pub` keyword, and -bring items into a scope with the `use` keyword. However, the structure that -makes sense to you while you’re developing a crate might not be very convenient -for your users. You might want to organize your structs in a hierarchy -containing multiple levels, but then people who want to use a type you’ve -defined deep in the hierarchy might have trouble finding out that type exists. -They might also be annoyed at having to enter `use` -`my_crate::some_module::another_module::UsefulType;` rather than `use` -`my_crate::UsefulType;`. +how to bring items into a scope with the `use` keyword. However, the structure +that makes sense to you while you’re developing a crate might not be very +convenient for your users. You might want to organize your structs in a +hierarchy containing multiple levels, but then people who want to use a type +you’ve defined deep in the hierarchy might have trouble finding out that type +exists. They might also be annoyed at having to enter `use` +`my_crate::`some_module`::`another_module`::`UsefulType`;` rather than `use` +`my_crate::`UsefulType`;`. The good news is that if the structure *isn’t* convenient for others to use from another library, you don’t have to rearrange your internal organization: instead, you can re-export items to make a public structure that’s different -from your private structure by using `pub use`. Re-exporting takes a public +from your private structure by using `pub use`. *Re-exporting* takes a public item in one location and makes it public in another location, as if it were defined in the other location instead. For example, say we made a library named `art` for modeling artistic concepts. Within this library are two modules: a `kinds` module containing two enums named `PrimaryColor` and `SecondaryColor` and a `utils` module containing a -function named `mix`, as shown in Listing 14-3: +function named `mix`, as shown in Listing 14-3. Filename: src/lib.rs @@ -308,8 +300,11 @@ pub mod utils { /// Combines two primary colors in equal amounts to create /// a secondary color. - pub fn mix(c1: PrimaryColor, c2: PrimaryColor) -> SecondaryColor { - // --snip-- + pub fn mix( + c1: PrimaryColor, + c2: PrimaryColor, + ) -> SecondaryColor { + --snip-- } } ``` @@ -318,9 +313,7 @@ Listing 14-3: An `art` library with items organized into `kinds` and `utils` modules Figure 14-3 shows what the front page of the documentation for this crate -generated by `cargo doc` would look like: - -<img alt="Rendered documentation for the `art` crate that lists the `kinds` and `utils` modules" src="img/trpl14-03.png" class="center" /> +generated by `cargo doc` would look like. Figure 14-3: Front page of the documentation for `art` that lists the `kinds` and `utils` modules @@ -332,7 +325,7 @@ see them. Another crate that depends on this library would need `use` statements that bring the items from `art` into scope, specifying the module structure that’s currently defined. Listing 14-4 shows an example of a crate that uses the -`PrimaryColor` and `mix` items from the `art` crate: +`PrimaryColor` and `mix` items from the `art` crate. Filename: src/main.rs @@ -361,7 +354,7 @@ module names in the `use` statements. To remove the internal organization from the public API, we can modify the `art` crate code in Listing 14-3 to add `pub use` statements to re-export the -items at the top level, as shown in Listing 14-5: +items at the top level, as shown in Listing 14-5. Filename: src/lib.rs @@ -375,37 +368,26 @@ pub use self::kinds::SecondaryColor; pub use self::utils::mix; pub mod kinds { - // --snip-- + --snip-- } pub mod utils { - // --snip-- + --snip-- } ``` -<!-- The example feels a tiny bit awkward. If you're -going to use `pub use`, in my experience it's probably going -to happen when you're pulling in definitions from sub-crates. -In this one, we create modules that we export and also -re-export symbols from those same modules. In practice, -you'd probably use sub-crates or move the definitions around. /JT --> -<!-- I don't want to get into sub-crates here, but I've added a sentence about -this common usage in the second-to-last paragraph of this section. /Carol --> - Listing 14-5: Adding `pub use` statements to re-export items The API documentation that `cargo doc` generates for this crate will now list and link re-exports on the front page, as shown in Figure 14-4, making the `PrimaryColor` and `SecondaryColor` types and the `mix` function easier to find. -<img alt="Rendered documentation for the `art` crate with the re-exports on the front page" src="img/trpl14-04.png" class="center" /> - -Figure 14-4: The front page of the documentation for `art` -that lists the re-exports +Figure 14-4: The front page of the documentation for `art` that lists the +re-exports The `art` crate users can still see and use the internal structure from Listing 14-3 as demonstrated in Listing 14-4, or they can use the more convenient -structure in Listing 14-5, as shown in Listing 14-6: +structure in Listing 14-5, as shown in Listing 14-6. Filename: src/main.rs @@ -414,7 +396,7 @@ use art::mix; use art::PrimaryColor; fn main() { - // --snip-- + --snip-- } ``` @@ -423,7 +405,7 @@ Listing 14-6: A program using the re-exported items from the `art` crate In cases where there are many nested modules, re-exporting the types at the top level with `pub use` can make a significant difference in the experience of people who use the crate. Another common use of `pub use` is to re-export -definitions of a dependency in the current crate to make that crate's +definitions of a dependency in the current crate to make that crate’s definitions part of your crate’s public API. Creating a useful public API structure is more of an art than a science, and @@ -436,11 +418,11 @@ differs from their public API. ### Setting Up a Crates.io Account Before you can publish any crates, you need to create an account on -*https://crates.io/* and get an API token. To do so, visit the home page at -*https://crates.io/* and log in via a GitHub account. (The GitHub account is +*https://crates.io* and get an API token. To do so, visit the home page at +*https://crates.io* and log in via a GitHub account. (The GitHub account is currently a requirement, but the site might support other ways of creating an account in the future.) Once you’re logged in, visit your account settings at -*https://crates.io/me/* and retrieve your API key. Then run the `cargo login` +*https://crates.io/me* and retrieve your API key. Then run the `cargo login` command with your API key, like this: ``` @@ -450,7 +432,7 @@ $ cargo login abcdefghijklmnopqrstuvwxyz012345 This command will inform Cargo of your API token and store it locally in *~/.cargo/credentials*. Note that this token is a *secret*: do not share it with anyone else. If you do share it with anyone for any reason, you should -revoke it and generate a new token on *https://crates.io/*. +revoke it and generate a new token on *https://crates.io*. ### Adding Metadata to a New Crate @@ -460,7 +442,7 @@ file. Your crate will need a unique name. While you’re working on a crate locally, you can name a crate whatever you’d like. However, crate names on -*https://crates.io/* are allocated on a first-come, first-served basis. Once a +*https://crates.io* are allocated on a first-come, first-served basis. Once a crate name is taken, no one else can publish a crate with that name. Before attempting to publish a crate, search for the name you want to use. If the name has been used, you will need to find another name and edit the `name` field in @@ -480,22 +462,26 @@ the crate at this point, you’ll get a warning and then an error: ``` $ cargo publish Updating crates.io index -warning: manifest has no description, license, license-file, documentation, homepage or repository. -See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info. +warning: manifest has no description, license, license-file, documentation, +homepage or repository. +See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata +for more info. --snip-- error: failed to publish to registry at https://crates.io Caused by: - the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata -``` - -This errors because you’re missing some crucial information: a description and -license are required so people will know what your crate does and under what -terms they can use it. In *Cargo.toml*, add a description that's just a -sentence or two, because it will appear with your crate in search results. For -the `license` field, you need to give a *license identifier value*. The Linux -Foundation’s Software Package Data Exchange (SPDX) at -*http://spdx.org/licenses/* lists the identifiers you can use for this value. + the remote server responded with an error: missing or empty metadata fields: +description, license. Please see https://doc.rust- +lang.org/cargo/reference/manifest.html for how to upload metadata +``` + +This results in an error because you’re missing some crucial information: a +description and license are required so people will know what your crate does +and under what terms they can use it. In *Cargo.toml*, add a description that’s +just a sentence or two, because it will appear with your crate in search +results. For the `license` field, you need to give a *license identifier +value*. The Linux Foundation’s Software Package Data Exchange (SPDX) at +*http://spdx.org/licenses* lists the identifiers you can use for this value. For example, to specify that you’ve licensed your crate using the MIT License, add the `MIT` identifier: @@ -528,27 +514,28 @@ Filename: Cargo.toml name = "guessing_game" version = "0.1.0" edition = "2021" -description = "A fun game where you guess what number the computer has chosen." +description = "A fun game where you guess what number the +computer has chosen." license = "MIT OR Apache-2.0" [dependencies] ``` -Cargo’s documentation at *https://doc.rust-lang.org/cargo/* describes other -metadata you can specify to ensure others can discover and use your crate more -easily. +Cargo’s documentation at *https://doc.rust-lang.org/cargo* describes other +metadata you can specify to ensure that others can discover and use your crate +more easily. ### Publishing to Crates.io Now that you’ve created an account, saved your API token, chosen a name for your crate, and specified the required metadata, you’re ready to publish! -Publishing a crate uploads a specific version to *https://crates.io/* for -others to use. +Publishing a crate uploads a specific version to *https://crates.io* for others +to use. Be careful, because a publish is *permanent*. The version can never be -overwritten, and the code cannot be deleted. One major goal of crates.io is to +overwritten, and the code cannot be deleted. One major goal of Crates.io is to act as a permanent archive of code so that builds of all projects that depend -on crates from *https://crates.io/* will continue to work. Allowing version +on crates from *https://crates.io* will continue to work. Allowing version deletions would make fulfilling that goal impossible. However, there is no limit to the number of crate versions you can publish. @@ -572,53 +559,33 @@ anyone can easily add your crate as a dependency of their project. When you’ve made changes to your crate and are ready to release a new version, you change the `version` value specified in your *Cargo.toml* file and -republish. Use the Semantic Versioning rules at *http://semver.org/* to decide -what an appropriate next version number is based on the kinds of changes you’ve -made. Then run `cargo publish` to upload the new version. +republish. Use the Semantic Versioning rules at *http://semver.org* to decide +what an appropriate next version number is, based on the kinds of changes +you’ve made. Then run `cargo publish` to upload the new version. -### Deprecating Versions from Crates.io with `cargo yank` +### Deprecating Versions from Crates.io with cargo yank Although you can’t remove previous versions of a crate, you can prevent any future projects from adding them as a new dependency. This is useful when a crate version is broken for one reason or another. In such situations, Cargo -supports *yanking* a crate version. +supports yanking a crate version. -Yanking a version prevents new projects from depending on that version while +*Yanking* a version prevents new projects from depending on that version while allowing all existing projects that depend on it to continue. Essentially, a yank means that all projects with a *Cargo.lock* will not break, and any future *Cargo.lock* files generated will not use the yanked version. To yank a version of a crate, in the directory of the crate that you’ve previously published, run `cargo yank` and specify which version you want to -yank. For example, if we've published a crate named `guessing_game` version -1.0.1 and we want to yank it, in the project directory for `guessing_game` we'd +yank. For example, if we’ve published a crate named `guessing_game` version +1.0.1 and we want to yank it, in the project directory for `guessing_game` we’d run: ``` $ cargo yank --vers 1.0.1 Updating crates.io index - Yank guessing_game:1.0.1 -``` - -<!-- so we run this on a crate, then load that crate onto crates.io? Or does -this go in a file that's part of the new crate version? /LC --> -<!-- No, this is a command to run in the directory of a crate that has already -been published to crates.io. Do you have suggestions on how to make this -clearer? I've tried a bit above /Carol --> -<!-- Ah, I see! I think this is clear. JT, does this read okay to you? /LC --> -<!-- I think this makes sense. Maybe you could make it clear in the example -that you're in the project directory? - -``` -my_project> cargo yank --vers 1.0.1 + Yank guessing_game@1.0.1 ``` -and then show the message that cargo returns when the version is yanked to -help key them in. -/JT --> -<!-- We haven't used that notation anywhere else in the book, of showing the -current directory in the prompt. I think showing the output is a good idea -though, so I've added that above and made the introduction to the scenario more -concrete. /Carol--> By adding `--undo` to the command, you can also undo a yank and allow projects to start depending on a version again: @@ -626,7 +593,7 @@ to start depending on a version again: ``` $ cargo yank --vers 1.0.1 --undo Updating crates.io index - Unyank guessing_game_:1.0.1 + Unyank guessing_game@1.0.1 ``` A yank *does not* delete any code. It cannot, for example, delete accidentally @@ -645,10 +612,10 @@ help manage multiple related packages that are developed in tandem. A *workspace* is a set of packages that share the same *Cargo.lock* and output directory. Let’s make a project using a workspace—we’ll use trivial code so we can concentrate on the structure of the workspace. There are multiple ways to -structure a workspace, so we'll just show one common way. We’ll have a +structure a workspace, so we’ll just show one common way. We’ll have a workspace containing a binary and two libraries. The binary, which will provide the main functionality, will depend on the two libraries. One library will -provide an `add_one` function, and a second library an `add_two` function. +provide an `add_one` function and the other library an `add_two` function. These three crates will be part of the same workspace. We’ll start by creating a new directory for the workspace: @@ -663,14 +630,6 @@ Instead, it will start with a `[workspace]` section that will allow us to add members to the workspace by specifying the path to the package with our binary crate; in this case, that path is *adder*: -<!-- You can have metadata in the top-level Cargo.toml along with the -`[workspace]` section. We use this in Nushell, for example: - -https://github.com/nushell/nushell/blob/main/Cargo.toml - - /JT --> -<!-- Fixed! /Carol --> - Filename: Cargo.toml ``` @@ -764,8 +723,8 @@ pub fn add_one(x: i32) -> i32 { ``` Now we can have the `adder` package with our binary depend on the `add_one` -package that has our library. First, we’ll need to add a path dependency on -`add_one` to *adder/Cargo.toml*. +package that has our library. First we’ll need to add a path dependency on +`add_one` to *adder/Cargo.toml*: Filename: adder/Cargo.toml @@ -808,9 +767,9 @@ $ cargo build Finished dev [unoptimized + debuginfo] target(s) in 0.68s ``` -To run the binary crate from the *add* directory, we can specify which -package in the workspace we want to run by using the `-p` argument and the -package name with `cargo run`: +To run the binary crate from the *add* directory, we can specify which package +in the workspace we want to run by using the `-p` argument and the package name +with `cargo run`: ``` $ cargo run -p adder @@ -837,7 +796,7 @@ Filename: add_one/Cargo.toml ``` [dependencies] -rand = "0.8.3" +rand = "0.8.5" ``` We can now add `use rand;` to the *add_one/src/lib.rs* file, and building the @@ -848,20 +807,10 @@ referring to the `rand` we brought into scope: ``` $ cargo build Updating crates.io index - Downloaded rand v0.8.3 + Downloaded rand v0.8.5 --snip-- - Compiling rand v0.8.3 + Compiling rand v0.8.5 Compiling add_one v0.1.0 (file:///projects/add/add_one) -warning: unused import: `rand` - --> add_one/src/lib.rs:1:5 - | -1 | use rand; - | ^^^^ - | - = note: `#[warn(unused_imports)]` on by default - -warning: 1 warning emitted - Compiling adder v0.1.0 (file:///projects/add/adder) Finished dev [unoptimized + debuginfo] target(s) in 10.18s ``` @@ -874,7 +823,7 @@ to the *adder/src/main.rs* file for the `adder` package, we’ll get an error: ``` $ cargo build - --snip-- + --snip-- Compiling adder v0.1.0 (file:///projects/add/adder) error[E0432]: unresolved import `rand` --> adder/src/main.rs:2:5 @@ -923,24 +872,27 @@ $ cargo test Compiling add_one v0.1.0 (file:///projects/add/add_one) Compiling adder v0.1.0 (file:///projects/add/adder) Finished test [unoptimized + debuginfo] target(s) in 0.27s - Running target/debug/deps/add_one-f0253159197f7841 + Running unittests src/lib.rs (target/debug/deps/add_one-f0253159197f7841) running 1 test test tests::it_works ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s - Running target/debug/deps/adder-49979ff40686fa8e + Running unittests src/main.rs (target/debug/deps/adder-49979ff40686fa8e) running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s Doc-tests add_one running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s ``` The first section of the output shows that the `it_works` test in the `add_one` @@ -955,24 +907,26 @@ we want to test: ``` $ cargo test -p add_one Finished test [unoptimized + debuginfo] target(s) in 0.00s - Running target/debug/deps/add_one-b3235fea9a156f74 + Running unittests src/lib.rs (target/debug/deps/add_one-b3235fea9a156f74) running 1 test test tests::it_works ... ok -test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s Doc-tests add_one running 0 tests -test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s +test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; +finished in 0.00s ``` This output shows `cargo test` only ran the tests for the `add_one` crate and didn’t run the `adder` crate tests. -If you publish the crates in the workspace to *https://crates.io/*, each crate +If you publish the crates in the workspace to *https://crates.io*, each crate in the workspace will need to be published separately. Like `cargo test`, we can publish a particular crate in our workspace by using the `-p` flag and specifying the name of the crate we want to publish. @@ -980,17 +934,17 @@ specifying the name of the crate we want to publish. For additional practice, add an `add_two` crate to this workspace in a similar way as the `add_one` crate! -As your project grows, consider using a workspace: it’s easier to understand -smaller, individual components than one big blob of code. Furthermore, keeping -the crates in a workspace can make coordination between crates easier if they -are often changed at the same time. +As your project grows, consider using a workspace: it provides +easier-to-understand, smaller, individual components than one big blob of code. +Furthermore, keeping the crates in a workspace can make coordination between +crates easier if they are often changed at the same time. -## Installing Binaries with `cargo install` +## Installing Binaries with cargo install The `cargo install` command allows you to install and use binary crates locally. This isn’t intended to replace system packages; it’s meant to be a convenient way for Rust developers to install tools that others have shared on -*https://crates.io/*. Note that you can only install packages that have binary +*https://crates.io*. Note that you can only install packages that have binary targets. A *binary target* is the runnable program that is created if the crate has a *src/main.rs* file or another file specified as a binary, as opposed to a library target that isn’t runnable on its own but is suitable for including @@ -1010,35 +964,36 @@ can run the following: ``` $ cargo install ripgrep Updating crates.io index - Downloaded ripgrep v11.0.2 + Downloaded ripgrep v13.0.0 Downloaded 1 crate (243.3 KB) in 0.88s - Installing ripgrep v11.0.2 ---snip-- - Compiling ripgrep v11.0.2 + Installing ripgrep v13.0.0 + --snip-- + Compiling ripgrep v13.0.0 Finished release [optimized + debuginfo] target(s) in 3m 10s Installing ~/.cargo/bin/rg - Installed package `ripgrep v11.0.2` (executable `rg`) + Installed package `ripgrep v13.0.0` (executable `rg`) ``` The second-to-last line of the output shows the location and the name of the installed binary, which in the case of `ripgrep` is `rg`. As long as the installation directory is in your `$PATH`, as mentioned previously, you can -then run `rg --help` and start using a faster, rustier tool for searching files! +then run `rg --help` and start using a faster, Rustier tool for searching files! ## Extending Cargo with Custom Commands Cargo is designed so you can extend it with new subcommands without having to -modify Cargo. If a binary in your `$PATH` is named `cargo-something`, you can -run it as if it was a Cargo subcommand by running `cargo something`. Custom +modify it. If a binary in your `$PATH` is named `cargo-something`, you can run +it as if it were a Cargo subcommand by running `cargo something`. Custom commands like this are also listed when you run `cargo --list`. Being able to use `cargo install` to install extensions and then run them just like the -built-in Cargo tools is a super convenient benefit of Cargo’s design! +built-in Cargo tools is a super-convenient benefit of Cargo’s design! ## Summary -Sharing code with Cargo and *https://crates.io/* is part of what makes the Rust +Sharing code with Cargo and *https://crates.io* is part of what makes the Rust ecosystem useful for many different tasks. Rust’s standard library is small and stable, but crates are easy to share, use, and improve on a timeline different from that of the language. Don’t be shy about sharing code that’s useful to you -on *https://crates.io/*; it’s likely that it will be useful to someone else as +on *https://crates.io*; it’s likely that it will be useful to someone else as well! + diff --git a/src/doc/book/nostarch/chapter15.md b/src/doc/book/nostarch/chapter15.md index 166277fab..c0e847da1 100644 --- a/src/doc/book/nostarch/chapter15.md +++ b/src/doc/book/nostarch/chapter15.md @@ -13,34 +13,34 @@ memory. This address refers to, or “points at,†some other data. The most common kind of pointer in Rust is a reference, which you learned about in Chapter 4. References are indicated by the `&` symbol and borrow the value they point to. They don’t have any special capabilities other than referring to -data, and have no overhead. +data, and they have no overhead. *Smart pointers*, on the other hand, are data structures that act like a pointer but also have additional metadata and capabilities. The concept of smart pointers isn’t unique to Rust: smart pointers originated in C++ and exist in other languages as well. Rust has a variety of smart pointers defined in the standard library that provide functionality beyond that provided by references. -To explore the general concept, we'll look at a couple of different examples of +To explore the general concept, we’ll look at a couple of different examples of smart pointers, including a *reference counting* smart pointer type. This pointer enables you to allow data to have multiple owners by keeping track of the number of owners and, when no owners remain, cleaning up the data. Rust, with its concept of ownership and borrowing, has an additional difference between references and smart pointers: while references only borrow data, in -many cases, smart pointers *own* the data they point to. +many cases smart pointers *own* the data they point to. -Though we didn't call them as such at the time, we’ve already encountered a few +Though we didn’t call them as such at the time, we’ve already encountered a few smart pointers in this book, including `String` and `Vec<T>` in Chapter 8. Both -these types count as smart pointers because they own some memory and allow you -to manipulate it. They also have metadata and extra capabilities or guarantees. -`String`, for example, stores its capacity as metadata and has the extra -ability to ensure its data will always be valid UTF-8. +of these types count as smart pointers because they own some memory and allow +you to manipulate it. They also have metadata and extra capabilities or +guarantees. `String`, for example, stores its capacity as metadata and has the +extra ability to ensure its data will always be valid UTF-8. Smart pointers are usually implemented using structs. Unlike an ordinary struct, smart pointers implement the `Deref` and `Drop` traits. The `Deref` trait allows an instance of the smart pointer struct to behave like a reference so you can write your code to work with either references or smart pointers. -The `Drop` trait allows you to customize the code that's run when an instance +The `Drop` trait allows you to customize the code that’s run when an instance of the smart pointer goes out of scope. In this chapter, we’ll discuss both traits and demonstrate why they’re important to smart pointers. @@ -49,10 +49,10 @@ frequently in Rust, this chapter won’t cover every existing smart pointer. Man libraries have their own smart pointers, and you can even write your own. We’ll cover the most common smart pointers in the standard library: -* `Box<T>` for allocating values on the heap +* `Box<T>`, for allocating values on the heap * `Rc<T>`, a reference counting type that enables multiple ownership * `Ref<T>` and `RefMut<T>`, accessed through `RefCell<T>`, a type that enforces - the borrowing rules at runtime instead of compile time +the borrowing rules at runtime instead of compile time In addition, we’ll cover the *interior mutability* pattern where an immutable type exposes an API for mutating an interior value. We’ll also discuss @@ -60,7 +60,7 @@ type exposes an API for mutating an interior value. We’ll also discuss Let’s dive in! -## Using `Box<T>` to Point to Data on the Heap +## Using Box<T> to Point to Data on the Heap The most straightforward smart pointer is a *box*, whose type is written `Box<T>`. Boxes allow you to store data on the heap rather than the stack. What @@ -72,35 +72,35 @@ heap instead of on the stack. But they don’t have many extra capabilities either. You’ll use them most often in these situations: * When you have a type whose size can’t be known at compile time and you want - to use a value of that type in a context that requires an exact size +to use a value of that type in a context that requires an exact size * When you have a large amount of data and you want to transfer ownership but - ensure the data won’t be copied when you do so +ensure the data won’t be copied when you do so * When you want to own a value and you care only that it’s a type that - implements a particular trait rather than being of a specific type +implements a particular trait rather than being of a specific type -We’ll demonstrate the first situation in the “Enabling Recursive Types with -Boxes†section. In the second case, transferring ownership of a large amount of +We’ll demonstrate the first situation in “Enabling Recursive Types with Boxes†+on page XX. In the second case, transferring ownership of a large amount of data can take a long time because the data is copied around on the stack. To improve performance in this situation, we can store the large amount of data on the heap in a box. Then, only the small amount of pointer data is copied around on the stack, while the data it references stays in one place on the heap. The -third case is known as a *trait object*, and Chapter 17 devotes an entire -section, “Using Trait Objects That Allow for Values of Different Types,†just -to that topic. So what you learn here you’ll apply again in Chapter 17! +third case is known as a *trait object*, and “Using Trait Objects That Allow +for Values of Different Types†on page XX is devoted to that topic. So what you +learn here you’ll apply again in that section! -### Using a `Box<T>` to Store Data on the Heap +### Using Box<T> to Store Data on the Heap Before we discuss the heap storage use case for `Box<T>`, we’ll cover the syntax and how to interact with values stored within a `Box<T>`. -Listing 15-1 shows how to use a box to store an `i32` value on the heap: +Listing 15-1 shows how to use a box to store an `i32` value on the heap. Filename: src/main.rs ``` fn main() { let b = Box::new(5); - println!("b = {}", b); + println!("b = {b}"); } ``` @@ -118,34 +118,34 @@ Putting a single value on the heap isn’t very useful, so you won’t use boxes themselves in this way very often. Having values like a single `i32` on the stack, where they’re stored by default, is more appropriate in the majority of situations. Let’s look at a case where boxes allow us to define types that we -wouldn’t be allowed to if we didn’t have boxes. +wouldn’t be allowed to define if we didn’t have boxes. ### Enabling Recursive Types with Boxes -A value of *recursive type* can have another value of the same type as part of -itself. Recursive types pose an issue because at compile time Rust needs to +A value of a *recursive type* can have another value of the same type as part +of itself. Recursive types pose an issue because at compile time Rust needs to know how much space a type takes up. However, the nesting of values of recursive types could theoretically continue infinitely, so Rust can’t know how much space the value needs. Because boxes have a known size, we can enable recursive types by inserting a box in the recursive type definition. -As an example of a recursive type, let’s explore the *cons list*. This is a data -type commonly found in functional programming languages. The cons list type -we’ll define is straightforward except for the recursion; therefore, the +As an example of a recursive type, let’s explore the *cons list*. This is a +data type commonly found in functional programming languages. The cons list +type we’ll define is straightforward except for the recursion; therefore, the concepts in the example we’ll work with will be useful any time you get into more complex situations involving recursive types. #### More Information About the Cons List A *cons list* is a data structure that comes from the Lisp programming language -and its dialects and is made up of nested pairs, and is the Lisp version of a -linked list. Its name comes from the `cons` function (short for “construct -functionâ€) in Lisp that constructs a new pair from its two arguments. By +and its dialects, is made up of nested pairs, and is the Lisp version of a +linked list. Its name comes from the `cons` function (short for *construct +function*) in Lisp that constructs a new pair from its two arguments. By calling `cons` on a pair consisting of a value and another pair, we can construct cons lists made up of recursive pairs. -For example, here's a pseudocode representation of a cons list containing the -list 1, 2, 3 with each pair in parentheses: +For example, here’s a pseudocode representation of a cons list containing the +list `1, 2, 3` with each pair in parentheses: ``` (1, (2, (3, Nil))) @@ -181,16 +181,18 @@ Listing 15-2: The first attempt at defining an enum to represent a cons list data structure of `i32` values > Note: We’re implementing a cons list that holds only `i32` values for the -> purposes of this example. We could have implemented it using generics, as we -> discussed in Chapter 10, to define a cons list type that could store values of -> any type. +purposes of this example. We could have implemented it using generics, as we +discussed in Chapter 10, to define a cons list type that could store values of +any type. Using the `List` type to store the list `1, 2, 3` would look like the code in -Listing 15-3: +Listing 15-3. Filename: src/main.rs ``` +--snip-- + use crate::List::{Cons, Nil}; fn main() { @@ -206,7 +208,7 @@ is one more `Cons` value that holds `3` and a `List` value, which is finally `Nil`, the non-recursive variant that signals the end of the list. If we try to compile the code in Listing 15-3, we get the error shown in -Listing 15-4: +Listing 15-4. ``` error[E0072]: recursive type `List` has infinite size @@ -217,7 +219,11 @@ error[E0072]: recursive type `List` 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 make `List` +representable + | +2 | Cons(i32, Box<List>), + | ++++ + ``` Listing 15-4: The error we get when attempting to define a recursive enum @@ -225,7 +231,7 @@ Listing 15-4: The error we get when attempting to define a recursive enum The error shows this type “has infinite size.†The reason is that we’ve defined `List` with a variant that is recursive: it holds another value of itself directly. As a result, Rust can’t figure out how much space it needs to store a -`List` value. Let’s break down why we get this error. First, we'll look at how +`List` value. Let’s break down why we get this error. First we’ll look at how Rust decides how much space it needs to store a value of a non-recursive type. #### Computing the Size of a Non-Recursive Type @@ -258,23 +264,22 @@ type needs, the compiler looks at the variants, starting with the `Cons` variant. The `Cons` variant holds a value of type `i32` and a value of type `List`, and this process continues infinitely, as shown in Figure 15-1. -<img alt="An infinite Cons list" src="img/trpl15-01.svg" class="center" style="width: 50%;" /> - Figure 15-1: An infinite `List` consisting of infinite `Cons` variants -#### Using `Box<T>` to Get a Recursive Type with a Known Size +#### Using Box<T> to Get a Recursive Type with a Known Size Because Rust can’t figure out how much space to allocate for recursively defined types, the compiler gives an error with this helpful suggestion: ``` -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 make `List` +representable | 2 | Cons(i32, Box<List>), - | ^^^^ ^ + | ++++ + ``` -In this suggestion, “indirection†means that instead of storing a value +In this suggestion, *indirection* means that instead of storing a value directly, we should change the data structure to store the value indirectly by storing a pointer to the value instead. @@ -288,7 +293,7 @@ this implementation is now more like placing the items next to one another rather than inside one another. We can change the definition of the `List` enum in Listing 15-2 and the usage -of the `List` in Listing 15-3 to the code in Listing 15-5, which will compile: +of the `List` in Listing 15-3 to the code in Listing 15-5, which will compile. Filename: src/main.rs @@ -301,31 +306,38 @@ enum List { use crate::List::{Cons, Nil}; fn main() { - let list = Cons(1, Box::new(Cons(2, Box::new(Cons(3, Box::new(Nil)))))); + let list = Cons( + 1, + Box::new(Cons( + 2, + Box::new(Cons( + 3, + Box::new(Nil) + )) + )) + ); } ``` Listing 15-5: Definition of `List` that uses `Box<T>` in order to have a known size -The `Cons` variant needs the size of an `i32` plus the space to store the -box’s pointer data. The `Nil` variant stores no values, so it needs less space -than the `Cons` variant. We now know that any `List` value will take up the -size of an `i32` plus the size of a box’s pointer data. By using a box, we’ve -broken the infinite, recursive chain, so the compiler can figure out the size -it needs to store a `List` value. Figure 15-2 shows what the `Cons` variant -looks like now. +The `Cons` variant needs the size of an `i32` plus the space to store the box’s +pointer data. The `Nil` variant stores no values, so it needs less space than +the `Cons` variant. We now know that any `List` value will take up the size of +an `i32` plus the size of a box’s pointer data. By using a box, we’ve broken +the infinite, recursive chain, so the compiler can figure out the size it needs +to store a `List` value. Figure 15-2 shows what the `Cons` variant looks like +now. -<img alt="A finite Cons list" src="img/trpl15-02.svg" class="center" /> - -Figure 15-2: A `List` that is not infinitely sized because `Cons` holds a `Box` +Figure 15-2: A `List` that is not infinitely sized, because `Cons` holds a `Box` Boxes provide only the indirection and heap allocation; they don’t have any other special capabilities, like those we’ll see with the other smart pointer types. They also don’t have the performance overhead that these special capabilities incur, so they can be useful in cases like the cons list where the indirection is the only feature we need. We’ll look at more use cases for boxes -in Chapter 17, too. +in Chapter 17. The `Box<T>` type is a smart pointer because it implements the `Deref` trait, which allows `Box<T>` values to be treated like references. When a `Box<T>` @@ -335,7 +347,7 @@ even more important to the functionality provided by the other smart pointer types we’ll discuss in the rest of this chapter. Let’s explore these two traits in more detail. -## Treating Smart Pointers Like Regular References with the `Deref` Trait +## Treating Smart Pointers Like Regular References with Deref Implementing the `Deref` trait allows you to customize the behavior of the *dereference operator* `*` (not to be confused with the multiplication or glob @@ -347,31 +359,31 @@ Let’s first look at how the dereference operator works with regular references Then we’ll try to define a custom type that behaves like `Box<T>`, and see why the dereference operator doesn’t work like a reference on our newly defined type. We’ll explore how implementing the `Deref` trait makes it possible for -smart pointers to work in ways similar to references. Then we’ll look at -Rust’s *deref coercion* feature and how it lets us work with either references -or smart pointers. +smart pointers to work in ways similar to references. Then we’ll look at Rust’s +*deref coercion* feature and how it lets us work with either references or +smart pointers. -> Note: there’s one big difference between the `MyBox<T>` type we’re about to -> build and the real `Box<T>`: our version will not store its data on the heap. -> We are focusing this example on `Deref`, so where the data is actually stored -> is less important than the pointer-like behavior. +> Note: There’s one big difference between the `MyBox<T>` type we’re about to +build and the real `Box<T>`: our version will not store its data on the heap. +We are focusing this example on `Deref`, so where the data is actually stored +is less important than the pointer-like behavior. ### Following the Pointer to the Value A regular reference is a type of pointer, and one way to think of a pointer is as an arrow to a value stored somewhere else. In Listing 15-6, we create a reference to an `i32` value and then use the dereference operator to follow the -reference to the value: +reference to the value. Filename: src/main.rs ``` fn main() { - [1] let x = 5; - [2] let y = &x; + 1 let x = 5; + 2 let y = &x; - [3] assert_eq!(5, x); - [4] assert_eq!(5, *y); + 3 assert_eq!(5, x); + 4 assert_eq!(5, *y); } ``` @@ -393,31 +405,33 @@ error[E0277]: can't compare `{integer}` with `&{integer}` --> src/main.rs:6:5 | 6 | assert_eq!(5, y); - | ^^^^^^^^^^^^^^^^ no implementation for `{integer} == &{integer}` + | ^^^^^^^^^^^^^^^^ no implementation for `{integer} == +&{integer}` | - = help: the trait `PartialEq<&{integer}>` is not implemented for `{integer}` + = help: the trait `PartialEq<&{integer}>` is not implemented +for `{integer}` ``` Comparing a number and a reference to a number isn’t allowed because they’re different types. We must use the dereference operator to follow the reference to the value it’s pointing to. -### Using `Box<T>` Like a Reference +### Using Box<T> Like a Reference We can rewrite the code in Listing 15-6 to use a `Box<T>` instead of a reference; the dereference operator used on the `Box<T>` in Listing 15-7 functions in the same way as the dereference operator used on the reference in -Listing 15-6: +Listing 15-6. Filename: src/main.rs ``` fn main() { let x = 5; - [1] let y = Box::new(x); + 1 let y = Box::new(x); assert_eq!(5, x); - [2] assert_eq!(5, *y); + 2 assert_eq!(5, *y); } ``` @@ -445,18 +459,18 @@ Listing 15-8 defines a `MyBox<T>` type in the same way. We’ll also define a Filename: src/main.rs ``` -[1] struct MyBox<T>(T); + 1 struct MyBox<T>(T); impl<T> MyBox<T> { - [2] fn new(x: T) -> MyBox<T> { - [3] MyBox(x) + 2 fn new(x: T) -> MyBox<T> { + 3 MyBox(x) } } ``` Listing 15-8: Defining a `MyBox<T>` type -We define a struct named `MyBox` and declare a generic parameter `T` [1], +We define a struct named `MyBox` and declare a generic parameter `T` [1] because we want our type to hold values of any type. The `MyBox` type is a tuple struct with one element of type `T`. The `MyBox::new` function takes one parameter of type `T` [2] and returns a `MyBox` instance that holds the value @@ -482,7 +496,7 @@ fn main() { Listing 15-9: Attempting to use `MyBox<T>` in the same way we used references and `Box<T>` -Here’s the resulting compilation error: +Here’s the resultant compilation error: ``` error[E0614]: type `MyBox<{integer}>` cannot be dereferenced @@ -496,14 +510,14 @@ Our `MyBox<T>` type can’t be dereferenced because we haven’t implemented tha ability on our type. To enable dereferencing with the `*` operator, we implement the `Deref` trait. -### Treating a Type Like a Reference by Implementing the `Deref` Trait +### Implementing the Deref Trait -As discussed in the “Implementing a Trait on a Type†section of Chapter 10, to -implement a trait, we need to provide implementations for the trait’s required -methods. The `Deref` trait, provided by the standard library, requires us to -implement one method named `deref` that borrows `self` and returns a reference -to the inner data. Listing 15-10 contains an implementation of `Deref` to add -to the definition of `MyBox`: +As discussed in “Implementing a Trait on a Type†on page XX, to implement a +trait we need to provide implementations for the trait’s required methods. The +`Deref` trait, provided by the standard library, requires us to implement one +method named `deref` that borrows `self` and returns a reference to the inner +data. Listing 15-10 contains an implementation of `Deref` to add to the +definition of `MyBox``<T>`. Filename: src/main.rs @@ -511,10 +525,10 @@ Filename: src/main.rs use std::ops::Deref; impl<T> Deref for MyBox<T> { - [1] type Target = T; + 1 type Target = T; fn deref(&self) -> &Self::Target { - [2] &self.0 + 2 &self.0 } } ``` @@ -528,10 +542,10 @@ them in more detail in Chapter 19. We fill in the body of the `deref` method with `&self.0` so `deref` returns a reference to the value we want to access with the `*` operator [2]; recall from -the “Using Tuple Structs without Named Fields to Create Different Types†-section of Chapter 5 that `.0` accesses the first value in a tuple struct. The -`main` function in Listing 15-9 that calls `*` on the `MyBox<T>` value now -compiles, and the assertions pass! +“Using Tuple Structs Without Named Fields to Create Different Types†on page XX +that `.0` accesses the first value in a tuple struct. The `main` function in +Listing 15-9 that calls `*` on the `MyBox<T>` value now compiles, and the +assertions pass! Without the `Deref` trait, the compiler can only dereference `&` references. The `deref` method gives the compiler the ability to take a value of any type @@ -553,7 +567,7 @@ identically whether we have a regular reference or a type that implements The reason the `deref` method returns a reference to a value, and that the plain dereference outside the parentheses in `*(y.deref())` is still necessary, -is to do with the ownership system. If the `deref` method returned the value +has to do with the ownership system. If the `deref` method returned the value directly instead of a reference to the value, the value would be moved out of `self`. We don’t want to take ownership of the inner value inside `MyBox<T>` in this case or in most cases where we use the dereference operator. @@ -584,7 +598,7 @@ can work for either references or smart pointers. To see deref coercion in action, let’s use the `MyBox<T>` type we defined in Listing 15-8 as well as the implementation of `Deref` that we added in Listing 15-10. Listing 15-11 shows the definition of a function that has a string slice -parameter: +parameter. Filename: src/main.rs @@ -597,8 +611,8 @@ fn hello(name: &str) { Listing 15-11: A `hello` function that has the parameter `name` of type `&str` We can call the `hello` function with a string slice as an argument, such as -`hello("Rust");` for example. Deref coercion makes it possible to call `hello` -with a reference to a value of type `MyBox<String>`, as shown in Listing 15-12: +`hello("Rust");`, for example. Deref coercion makes it possible to call `hello` +with a reference to a value of type `MyBox<String>`, as shown in Listing 15-12. Filename: src/main.rs @@ -661,10 +675,10 @@ cases: * From `&mut T` to `&mut U` when `T: DerefMut<Target=U>` * From `&mut T` to `&U` when `T: Deref<Target=U>` -The first two cases are the same as each other except that the second -implements mutability. The first case states that if you have a `&T`, and `T` -implements `Deref` to some type `U`, you can get a `&U` transparently. The -second case states that the same deref coercion happens for mutable references. +The first two cases are the same except that the second implements mutability. +The first case states that if you have a `&T`, and `T` implements `Deref` to +some type `U`, you can get a `&U` transparently. The second case states that +the same deref coercion happens for mutable references. The third case is trickier: Rust will also coerce a mutable reference to an immutable one. But the reverse is *not* possible: immutable references will @@ -678,12 +692,12 @@ the borrowing rules don’t guarantee that. Therefore, Rust can’t make the assumption that converting an immutable reference to a mutable reference is possible. -## Running Code on Cleanup with the `Drop` Trait +## Running Code on Cleanup with the Drop Trait The second trait important to the smart pointer pattern is `Drop`, which lets you customize what happens when a value is about to go out of scope. You can -provide an implementation for the `Drop` trait on any type, and that code -can be used to release resources like files or network connections. +provide an implementation for the `Drop` trait on any type, and that code can +be used to release resources like files or network connections. We’re introducing `Drop` in the context of smart pointers because the functionality of the `Drop` trait is almost always used when implementing a @@ -692,7 +706,7 @@ space on the heap that the box points to. In some languages, for some types, the programmer must call code to free memory or resources every time they finish using an instance of those types. Examples -include file handles, sockets, or locks. If they forget, the system might +include file handles, sockets, and locks. If they forget, the system might become overloaded and crash. In Rust, you can specify that a particular bit of code be run whenever a value goes out of scope, and the compiler will insert this code automatically. As a result, you don’t need to be careful about @@ -706,7 +720,7 @@ let’s implement `drop` with `println!` statements for now. Listing 15-14 shows a `CustomSmartPointer` struct whose only custom functionality is that it will print `Dropping CustomSmartPointer!` when the -instance goes out of scope, to show when Rust runs the `drop` function. +instance goes out of scope, to show when Rust runs the `drop` method. Filename: src/main.rs @@ -715,21 +729,24 @@ struct CustomSmartPointer { data: String, } -[1] impl Drop for CustomSmartPointer { +1 impl Drop for CustomSmartPointer { fn drop(&mut self) { - [2] println!("Dropping CustomSmartPointer with data `{}`!", self.data); + 2 println!( + "Dropping CustomSmartPointer with data `{}`!", + self.data + ); } } fn main() { - [3] let c = CustomSmartPointer { + 3 let c = CustomSmartPointer { data: String::from("my stuff"), }; - [4] let d = CustomSmartPointer { + 4 let d = CustomSmartPointer { data: String::from("other stuff"), }; - [5] println!("CustomSmartPointers created."); -[6] } + 5 println!("CustomSmartPointers created."); +6 } ``` Listing 15-14: A `CustomSmartPointer` struct that implements the `Drop` trait @@ -738,12 +755,12 @@ where we would put our cleanup code The `Drop` trait is included in the prelude, so we don’t need to bring it into scope. We implement the `Drop` trait on `CustomSmartPointer` [1] and provide an implementation for the `drop` method that calls `println!` [2]. The body of the -`drop` function is where you would place any logic that you wanted to run when -an instance of your type goes out of scope. We’re printing some text here to +`drop` method is where you would place any logic that you wanted to run when an +instance of your type goes out of scope. We’re printing some text here to demonstrate visually when Rust will call `drop`. -In `main`, we create two instances of `CustomSmartPointer` [3][4] and then -print `CustomSmartPointers created` [5]. At the end of `main` [6], our +In `main`, we create two instances of `CustomSmartPointer` at [3] and [4] and +then print `CustomSmartPointers created` [5]. At the end of `main` [6], our instances of `CustomSmartPointer` will go out of scope, and Rust will call the code we put in the `drop` method [2], printing our final message. Note that we didn’t need to call the `drop` method explicitly. @@ -758,26 +775,24 @@ Dropping CustomSmartPointer with data `my stuff`! Rust automatically called `drop` for us when our instances went out of scope, calling the code we specified. Variables are dropped in the reverse order of -their creation, so `d` was dropped before `c`. This example's purpose is to +their creation, so `d` was dropped before `c`. This example’s purpose is to give you a visual guide to how the `drop` method works; usually you would specify the cleanup code that your type needs to run rather than a print message. -### Dropping a Value Early with `std::mem::drop` - Unfortunately, it’s not straightforward to disable the automatic `drop` functionality. Disabling `drop` isn’t usually necessary; the whole point of the `Drop` trait is that it’s taken care of automatically. Occasionally, however, you might want to clean up a value early. One example is when using smart pointers that manage locks: you might want to force the `drop` method that releases the lock so that other code in the same scope can acquire the lock. -Rust doesn’t let you call the `Drop` trait’s `drop` method manually; instead +Rust doesn’t let you call the `Drop` trait’s `drop` method manually; instead, you have to call the `std::mem::drop` function provided by the standard library if you want to force a value to be dropped before the end of its scope. If we try to call the `Drop` trait’s `drop` method manually by modifying the `main` function from Listing 15-14, as shown in Listing 15-15, we’ll get a -compiler error: +compiler error. Filename: src/main.rs @@ -788,7 +803,9 @@ fn main() { }; println!("CustomSmartPointer created."); c.drop(); - println!("CustomSmartPointer dropped before the end of main."); + println!( + "CustomSmartPointer dropped before the end of main." + ); } ``` @@ -805,6 +822,7 @@ error[E0040]: explicit use of destructor method | --^^^^-- | | | | | explicit destructor calls not allowed + | help: consider using `drop` function: `drop(c)` ``` This error message states that we’re not allowed to explicitly call `drop`. The @@ -823,9 +841,9 @@ scope, and we can’t call the `drop` method explicitly. So, if we need to force a value to be cleaned up early, we use the `std::mem::drop` function. The `std::mem::drop` function is different from the `drop` method in the `Drop` -trait. We call it by passing as an argument the value we want to force drop. +trait. We call it by passing as an argument the value we want to force-drop. The function is in the prelude, so we can modify `main` in Listing 15-15 to -call the `drop` function, as shown in Listing 15-16: +call the `drop` function, as shown in Listing 15-16. Filename: src/main.rs @@ -836,7 +854,9 @@ fn main() { }; println!("CustomSmartPointer created."); drop(c); - println!("CustomSmartPointer dropped before the end of main."); + println!( + "CustomSmartPointer dropped before the end of main." + ); } ``` @@ -851,7 +871,7 @@ Dropping CustomSmartPointer with data `some data`! CustomSmartPointer dropped before the end of main. ``` -The text ```Dropping CustomSmartPointer with data `some data`!``` is printed +The text `Dropping CustomSmartPointer with data `some data`!` is printed between the `CustomSmartPointer created.` and `CustomSmartPointer dropped before the end of main.` text, showing that the `drop` method code is called to drop `c` at that point. @@ -870,7 +890,7 @@ Now that we’ve examined `Box<T>` and some of the characteristics of smart pointers, let’s look at a few other smart pointers defined in the standard library. -## `Rc<T>`, the Reference Counted Smart Pointer +## Rc<T>, the Reference Counted Smart Pointer In the majority of cases, ownership is clear: you know exactly which variable owns a given value. However, there are cases when a single value might have @@ -889,7 +909,7 @@ Imagine `Rc<T>` as a TV in a family room. When one person enters to watch TV, they turn it on. Others can come into the room and watch the TV. When the last person leaves the room, they turn off the TV because it’s no longer being used. If someone turns off the TV while others are still watching it, there would be -uproar from the remaining TV watchers! +an uproar from the remaining TV watchers! We use the `Rc<T>` type when we want to allocate some data on the heap for multiple parts of our program to read and we can’t determine at compile time @@ -901,23 +921,21 @@ Note that `Rc<T>` is only for use in single-threaded scenarios. When we discuss concurrency in Chapter 16, we’ll cover how to do reference counting in multithreaded programs. -### Using `Rc<T>` to Share Data +### Using Rc<T> to Share Data Let’s return to our cons list example in Listing 15-5. Recall that we defined it using `Box<T>`. This time, we’ll create two lists that both share ownership -of a third list. Conceptually, this looks similar to Figure 15-3: - -<img alt="Two lists that share ownership of a third list" src="img/trpl15-03.svg" class="center" /> +of a third list. Conceptually, this looks similar to Figure 15-3. Figure 15-3: Two lists, `b` and `c`, sharing ownership of a third list, `a` -We’ll create list `a` that contains 5 and then 10. Then we’ll make two more -lists: `b` that starts with 3 and `c` that starts with 4. Both `b` and `c` -lists will then continue on to the first `a` list containing 5 and 10. In other -words, both lists will share the first list containing 5 and 10. +We’ll create list `a` that contains `5` and then `10`. Then we’ll make two more +lists: `b` that starts with `3` and `c` that starts with `4`. Both `b` and `c` +lists will then continue on to the first `a` list containing `5` and `10`. In +other words, both lists will share the first list containing `5` and `10`. Trying to implement this scenario using our definition of `List` with `Box<T>` -won’t work, as shown in Listing 15-17: +won’t work, as shown in Listing 15-17. Filename: src/main.rs @@ -931,13 +949,13 @@ use crate::List::{Cons, Nil}; fn main() { let a = Cons(5, Box::new(Cons(10, Box::new(Nil)))); -[1] let b = Cons(3, Box::new(a)); -[2] let c = Cons(4, Box::new(a)); + 1 let b = Cons(3, Box::new(a)); + 2 let c = Cons(4, Box::new(a)); } ``` -Listing 15-17: Demonstrating we’re not allowed to have two lists using `Box<T>` -that try to share ownership of a third list +Listing 15-17: Demonstrating that we’re not allowed to have two lists using +`Box<T>` that try to share ownership of a third list When we compile this code, we get this error: @@ -946,7 +964,8 @@ error[E0382]: use of moved value: `a` --> src/main.rs:11:30 | 9 | let a = Cons(5, Box::new(Cons(10, Box::new(Nil)))); - | - move occurs because `a` has type `List`, which does not implement the `Copy` trait + | - move occurs because `a` has type `List`, which +does not implement the `Copy` trait 10 | let b = Cons(3, Box::new(a)); | - value moved here 11 | let c = Cons(4, Box::new(a)); @@ -983,22 +1002,22 @@ enum List { } use crate::List::{Cons, Nil}; -[1] use std::rc::Rc; +1 use std::rc::Rc; fn main() { -[2] let a = Rc::new(Cons(5, Rc::new(Cons(10, Rc::new(Nil))))); -[3] let b = Cons(3, Rc::clone(&a)); -[4] let c = Cons(4, Rc::clone(&a)); + 2 let a = Rc::new(Cons(5, Rc::new(Cons(10, Rc::new(Nil))))); + 3 let b = Cons(3, Rc::clone(&a)); + 4 let c = Cons(4, Rc::clone(&a)); } ``` Listing 15-18: A definition of `List` that uses `Rc<T>` We need to add a `use` statement to bring `Rc<T>` into scope [1] because it’s -not in the prelude. In `main`, we create the list holding 5 and 10 and store it -in a new `Rc<List>` in `a` [2]. Then when we create `b` [3] and `c` [4], we -call the `Rc::clone` function and pass a reference to the `Rc<List>` in `a` as -an argument. +not in the prelude. In `main`, we create the list holding `5` and `10` and +store it in a new `Rc<List>` in `a` [2]. Then, when we create `b` [3] and `c` +[4], we call the `Rc::clone` function and pass a reference to the `Rc<List>` in +`a` as an argument. We could have called `a.clone()` rather than `Rc::clone(&a)`, but Rust’s convention is to use `Rc::clone` in this case. The implementation of @@ -1011,7 +1030,7 @@ increase the reference count. When looking for performance problems in the code, we only need to consider the deep-copy clones and can disregard calls to `Rc::clone`. -### Cloning an `Rc<T>` Increases the Reference Count +### Cloning an Rc<T> Increases the Reference Count Let’s change our working example in Listing 15-18 so we can see the reference counts changing as we create and drop references to the `Rc<List>` in `a`. @@ -1022,16 +1041,30 @@ then we can see how the reference count changes when `c` goes out of scope. Filename: src/main.rs ``` +--snip-- + fn main() { let a = Rc::new(Cons(5, Rc::new(Cons(10, Rc::new(Nil))))); - println!("count after creating a = {}", Rc::strong_count(&a)); + println!( + "count after creating a = {}", + Rc::strong_count(&a) + ); let b = Cons(3, Rc::clone(&a)); - println!("count after creating b = {}", Rc::strong_count(&a)); + println!( + "count after creating b = {}", + Rc::strong_count(&a) + ); { let c = Cons(4, Rc::clone(&a)); - println!("count after creating c = {}", Rc::strong_count(&a)); + println!( + "count after creating c = {}", + Rc::strong_count(&a) + ); } - println!("count after c goes out of scope = {}", Rc::strong_count(&a)); + println!( + "count after c goes out of scope = {}", + Rc::strong_count(&a) + ); } ``` @@ -1040,8 +1073,8 @@ Listing 15-19: Printing the reference count At each point in the program where the reference count changes, we print the reference count, which we get by calling the `Rc::strong_count` function. This function is named `strong_count` rather than `count` because the `Rc<T>` type -also has a `weak_count`; we’ll see what `weak_count` is used for in the -“Preventing Reference Cycles: Turning an `Rc<T>` into a `Weak<T>`†section. +also has a `weak_count`; we’ll see what `weak_count` is used for in “Preventing +Reference Cycles Using Weak<T>†on page XX. This code prints the following: @@ -1074,7 +1107,7 @@ section, we’ll discuss the interior mutability pattern and the `RefCell<T>` type that you can use in conjunction with an `Rc<T>` to work with this immutability restriction. -## `RefCell<T>` and the Interior Mutability Pattern +## RefCell<T> and the Interior Mutability Pattern *Interior mutability* is a design pattern in Rust that allows you to mutate data even when there are immutable references to that data; normally, this @@ -1092,14 +1125,14 @@ safe API, and the outer type is still immutable. Let’s explore this concept by looking at the `RefCell<T>` type that follows the interior mutability pattern. -### Enforcing Borrowing Rules at Runtime with `RefCell<T>` +### Enforcing Borrowing Rules at Runtime with RefCell<T> Unlike `Rc<T>`, the `RefCell<T>` type represents single ownership over the data -it holds. So, what makes `RefCell<T>` different from a type like `Box<T>`? +it holds. So what makes `RefCell<T>` different from a type like `Box<T>`? Recall the borrowing rules you learned in Chapter 4: -* At any given time, you can have *either* (but not both) one mutable reference - or any number of immutable references. +* At any given time, you can have *either* one mutable reference or any number +of immutable references (but not both). * References must always be valid. With references and `Box<T>`, the borrowing rules’ invariants are enforced at @@ -1137,13 +1170,13 @@ multithreaded program in Chapter 16. Here is a recap of the reasons to choose `Box<T>`, `Rc<T>`, or `RefCell<T>`: * `Rc<T>` enables multiple owners of the same data; `Box<T>` and `RefCell<T>` - have single owners. +have single owners. * `Box<T>` allows immutable or mutable borrows checked at compile time; `Rc<T>` - allows only immutable borrows checked at compile time; `RefCell<T>` allows - immutable or mutable borrows checked at runtime. +allows only immutable borrows checked at compile time; `RefCell<T>` allows +immutable or mutable borrows checked at runtime. * Because `RefCell<T>` allows mutable borrows checked at runtime, you can - mutate the value inside the `RefCell<T>` even when the `RefCell<T>` is - immutable. +mutate the value inside the `RefCell<T>` even when the `RefCell<T>` is +immutable. Mutating the value inside an immutable value is the *interior mutability* pattern. Let’s look at a situation in which interior mutability is useful and @@ -1154,6 +1187,8 @@ examine how it’s possible. A consequence of the borrowing rules is that when you have an immutable value, you can’t borrow it mutably. For example, this code won’t compile: +Filename: src/main.rs + ``` fn main() { let x = 5; @@ -1164,7 +1199,8 @@ fn main() { If you tried to compile this code, you’d get the following error: ``` -error[E0596]: cannot borrow `x` as mutable, as it is not declared as mutable +error[E0596]: cannot borrow `x` as mutable, as it is not declared +as mutable --> src/main.rs:3:13 | 2 | let x = 5; @@ -1188,13 +1224,13 @@ an immutable value and see why that is useful. #### A Use Case for Interior Mutability: Mock Objects Sometimes during testing a programmer will use a type in place of another type, -in order to observe particular behavior and assert it's implemented correctly. -This placeholder type is called a *test double*. Think of it in the sense of a -"stunt double" in filmmaking, where a person steps in and substitutes for an -actor to do a particular tricky scene. Test doubles stand in for other types -when we're running tests. *Mock objects* are specific types of test doubles -that record what happens during a test so you can assert that the correct -actions took place. +in order to observe particular behavior and assert that it’s implemented +correctly. This placeholder type is called a *test double*. Think of it in the +sense of a stunt double in filmmaking, where a person steps in and substitutes +for an actor to do a particularly tricky scene. Test doubles stand in for other +types when we’re running tests. *Mock objects* are specific types of test +doubles that record what happens during a test so you can assert that the +correct actions took place. Rust doesn’t have objects in the same sense as other languages have objects, and Rust doesn’t have mock object functionality built into the standard library @@ -1210,15 +1246,15 @@ Our library will only provide the functionality of tracking how close to the maximum a value is and what the messages should be at what times. Applications that use our library will be expected to provide the mechanism for sending the messages: the application could put a message in the application, send an -email, send a text message, or something else. The library doesn’t need to know -that detail. All it needs is something that implements a trait we’ll provide -called `Messenger`. Listing 15-20 shows the library code: +email, send a text message, or do something else. The library doesn’t need to +know that detail. All it needs is something that implements a trait we’ll +provide called `Messenger`. Listing 15-20 shows the library code. Filename: src/lib.rs ``` pub trait Messenger { -[1] fn send(&self, msg: &str); + 1 fn send(&self, msg: &str); } pub struct LimitTracker<'a, T: Messenger> { @@ -1231,7 +1267,10 @@ impl<'a, T> LimitTracker<'a, T> where T: Messenger, { - pub fn new(messenger: &'a T, max: usize) -> LimitTracker<'a, T> { + pub fn new( + messenger: &'a T, + max: usize + ) -> LimitTracker<'a, T> { LimitTracker { messenger, value: 0, @@ -1239,19 +1278,21 @@ where } } -[2] pub fn set_value(&mut self, value: usize) { + 2 pub fn set_value(&mut self, value: usize) { self.value = value; - let percentage_of_max = self.value as f64 / self.max as f64; + let percentage_of_max = + self.value as f64 / self.max as f64; if percentage_of_max >= 1.0 { - self.messenger.send("Error: You are over your quota!"); + self.messenger + .send("Error: You are over your quota!"); } else if percentage_of_max >= 0.9 { self.messenger - .send("Urgent warning: You've used up over 90% of your quota!"); + .send("Urgent: You're at 90% of your quota!"); } else if percentage_of_max >= 0.75 { self.messenger - .send("Warning: You've used up over 75% of your quota!"); + .send("Warning: You're at 75% of your quota!"); } } } @@ -1269,7 +1310,7 @@ part is that we want to test the behavior of the `set_value` method on the but `set_value` doesn’t return anything for us to make assertions on. We want to be able to say that if we create a `LimitTracker` with something that implements the `Messenger` trait and a particular value for `max`, when we pass -different numbers for `value`, the messenger is told to send the appropriate +different numbers for `value` the messenger is told to send the appropriate messages. We need a mock object that, instead of sending an email or text message when we @@ -1277,7 +1318,7 @@ call `send`, will only keep track of the messages it’s told to send. We can create a new instance of the mock object, create a `LimitTracker` that uses the mock object, call the `set_value` method on `LimitTracker`, and then check that the mock object has the messages we expect. Listing 15-21 shows an attempt to -implement a mock object to do just that, but the borrow checker won’t allow it: +implement a mock object to do just that, but the borrow checker won’t allow it. Filename: src/lib.rs @@ -1286,28 +1327,31 @@ Filename: src/lib.rs mod tests { use super::*; - [1] struct MockMessenger { - [2] sent_messages: Vec<String>, + 1 struct MockMessenger { + 2 sent_messages: Vec<String>, } impl MockMessenger { - [3] fn new() -> MockMessenger { + 3 fn new() -> MockMessenger { MockMessenger { sent_messages: vec![], } } } - [4] impl Messenger for MockMessenger { + 4 impl Messenger for MockMessenger { fn send(&self, message: &str) { - [5] self.sent_messages.push(String::from(message)); + 5 self.sent_messages.push(String::from(message)); } } #[test] - [6] fn it_sends_an_over_75_percent_warning_message() { + 6 fn it_sends_an_over_75_percent_warning_message() { let mock_messenger = MockMessenger::new(); - let mut limit_tracker = LimitTracker::new(&mock_messenger, 100); + let mut limit_tracker = LimitTracker::new( + &mock_messenger, + 100 + ); limit_tracker.set_value(80); @@ -1329,37 +1373,40 @@ we can give a `MockMessenger` to a `LimitTracker`. In the definition of the the `MockMessenger` list of `sent_messages`. In the test, we’re testing what happens when the `LimitTracker` is told to set -`value` to something that is more than 75 percent of the `max` value [6]. -First, we create a new `MockMessenger`, which will start with an empty list of +`value` to something that is more than 75 percent of the `max` value [6]. First +we create a new `MockMessenger`, which will start with an empty list of messages. Then we create a new `LimitTracker` and give it a reference to the -new `MockMessenger` and a `max` value of 100. We call the `set_value` method on -the `LimitTracker` with a value of 80, which is more than 75 percent of 100. -Then we assert that the list of messages that the `MockMessenger` is keeping -track of should now have one message in it. +new `MockMessenger` and a `max` value of `100`. We call the `set_value` method +on the `LimitTracker` with a value of `80`, which is more than 75 percent of +100. Then we assert that the list of messages that the `MockMessenger` is +keeping track of should now have one message in it. However, there’s one problem with this test, as shown here: ``` -error[E0596]: cannot borrow `self.sent_messages` as mutable, as it is behind a `&` reference +error[E0596]: cannot borrow `self.sent_messages` as mutable, as it is behind a +`&` reference --> src/lib.rs:58:13 | 2 | fn send(&self, msg: &str); - | ----- help: consider changing that to be a mutable reference: `&mut self` + | ----- help: consider changing that to be a mutable reference: +`&mut self` ... 58 | self.sent_messages.push(String::from(message)); - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `self` is a `&` reference, so the data it refers to cannot be borrowed as mutable + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ `self` is a +`&` reference, so the data it refers to cannot be borrowed as mutable ``` -We can’t modify the `MockMessenger` to keep track of the messages, because the +We can’t modify the `MockMessenger` to keep track of the messages because the `send` method takes an immutable reference to `self`. We also can’t take the -suggestion from the error text to use `&mut self` instead, because then the +suggestion from the error text to use `&mut self` instead because then the signature of `send` wouldn’t match the signature in the `Messenger` trait -definition (feel free to try and see what error message you get). +definition (feel free to try it and see what error message you get). This is a situation in which interior mutability can help! We’ll store the -`sent_messages` within a `RefCell<T>`, and then the `send` method will be -able to modify `sent_messages` to store the messages we’ve seen. Listing 15-22 -shows what that looks like: +`sent_messages` within a `RefCell<T>`, and then the `send` method will be able +to modify `sent_messages` to store the messages we’ve seen. Listing 15-22 shows +what that looks like. Filename: src/lib.rs @@ -1370,28 +1417,33 @@ mod tests { use std::cell::RefCell; struct MockMessenger { - [1] sent_messages: RefCell<Vec<String>>, + 1 sent_messages: RefCell<Vec<String>>, } impl MockMessenger { fn new() -> MockMessenger { MockMessenger { - sent_messages: RefCell::new(vec![]) [2], + 2 sent_messages: RefCell::new(vec![]), } } } impl Messenger for MockMessenger { fn send(&self, message: &str) { - [3] self.sent_messages.borrow_mut().push(String::from(message)); + self.sent_messages + 3 .borrow_mut() + .push(String::from(message)); } } #[test] fn it_sends_an_over_75_percent_warning_message() { - // --snip-- + --snip-- - [4] assert_eq!(mock_messenger.sent_messages.borrow().len(), 1); + assert_eq!( + 4 mock_messenger.sent_messages.borrow().len(), + 1 + ); } } ``` @@ -1406,9 +1458,9 @@ instance around the empty vector [2]. For the implementation of the `send` method, the first parameter is still an immutable borrow of `self`, which matches the trait definition. We call `borrow_mut` on the `RefCell<Vec<String>>` in `self.sent_messages` [3] to get a -mutable reference to the value inside the `RefCell<Vec<String>>`, which is -the vector. Then we can call `push` on the mutable reference to the vector to -keep track of the messages sent during the test. +mutable reference to the value inside the `RefCell<Vec<String>>`, which is the +vector. Then we can call `push` on the mutable reference to the vector to keep +track of the messages sent during the test. The last change we have to make is in the assertion: to see how many items are in the inner vector, we call `borrow` on the `RefCell<Vec<String>>` to get an @@ -1416,7 +1468,7 @@ immutable reference to the vector [4]. Now that you’ve seen how to use `RefCell<T>`, let’s dig into how it works! -#### Keeping Track of Borrows at Runtime with `RefCell<T>` +#### Keeping Track of Borrows at Runtime with RefCell<T> When creating immutable and mutable references, we use the `&` and `&mut` syntax, respectively. With `RefCell<T>`, we use the `borrow` and `borrow_mut` @@ -1428,7 +1480,7 @@ can treat them like regular references. The `RefCell<T>` keeps track of how many `Ref<T>` and `RefMut<T>` smart pointers are currently active. Every time we call `borrow`, the `RefCell<T>` increases its count of how many immutable borrows are active. When a `Ref<T>` -value goes out of scope, the count of immutable borrows goes down by one. Just +value goes out of scope, the count of immutable borrows goes down by 1. Just like the compile-time borrowing rules, `RefCell<T>` lets us have many immutable borrows or one mutable borrow at any point in time. @@ -1442,15 +1494,15 @@ at runtime. Filename: src/lib.rs ``` - impl Messenger for MockMessenger { - fn send(&self, message: &str) { - let mut one_borrow = self.sent_messages.borrow_mut(); - let mut two_borrow = self.sent_messages.borrow_mut(); +impl Messenger for MockMessenger { + fn send(&self, message: &str) { + let mut one_borrow = self.sent_messages.borrow_mut(); + let mut two_borrow = self.sent_messages.borrow_mut(); - one_borrow.push(String::from(message)); - two_borrow.push(String::from(message)); - } + one_borrow.push(String::from(message)); + two_borrow.push(String::from(message)); } +} ``` Listing 15-23: Creating two mutable references in the same scope to see that @@ -1473,7 +1525,7 @@ BorrowMutError`. This is how `RefCell<T>` handles violations of the borrowing rules at runtime. Choosing to catch borrowing errors at runtime rather than compile time, as -we've done here, means you'd potentially be finding mistakes in your code later +we’ve done here, means you’d potentially be finding mistakes in your code later in the development process: possibly not until your code was deployed to production. Also, your code would incur a small runtime performance penalty as a result of keeping track of the borrows at runtime rather than compile time. @@ -1483,7 +1535,7 @@ in a context where only immutable values are allowed. You can use `RefCell<T>` despite its trade-offs to get more functionality than regular references provide. -### Having Multiple Owners of Mutable Data by Combining `Rc<T>` and `RefCell<T>` +### Allowing Multiple Owners of Mutable Data with Rc<T> and RefCell<T> A common way to use `RefCell<T>` is in combination with `Rc<T>`. Recall that `Rc<T>` lets you have multiple owners of some data, but it only gives immutable @@ -1493,10 +1545,10 @@ get a value that can have multiple owners *and* that you can mutate! For example, recall the cons list example in Listing 15-18 where we used `Rc<T>` to allow multiple lists to share ownership of another list. Because `Rc<T>` holds only immutable values, we can’t change any of the values in the -list once we’ve created them. Let’s add in `RefCell<T>` to gain the ability to +list once we’ve created them. Let’s add in `RefCell<T>` for its ability to change the values in the lists. Listing 15-24 shows that by using a `RefCell<T>` in the `Cons` definition, we can modify the value stored in all -the lists: +the lists. Filename: src/main.rs @@ -1512,14 +1564,14 @@ use std::cell::RefCell; use std::rc::Rc; fn main() { - [1] let value = Rc::new(RefCell::new(5)); + 1 let value = Rc::new(RefCell::new(5)); - [2] let a = Rc::new(Cons(Rc::clone(&value), Rc::new(Nil))); + 2 let a = Rc::new(Cons(Rc::clone(&value), Rc::new(Nil))); let b = Cons(Rc::new(RefCell::new(3)), Rc::clone(&a)); let c = Cons(Rc::new(RefCell::new(4)), Rc::clone(&a)); - [3] *value.borrow_mut() += 10; + 3 *value.borrow_mut() += 10; println!("a after = {:?}", a); println!("b after = {:?}", b); @@ -1541,13 +1593,13 @@ can both refer to `a`, which is what we did in Listing 15-18. After we’ve created the lists in `a`, `b`, and `c`, we want to add 10 to the value in `value` [3]. We do this by calling `borrow_mut` on `value`, which uses -the automatic dereferencing feature we discussed in Chapter 5 (see the section -“Where’s the `->` Operator?â€) to dereference the `Rc<T>` to the inner -`RefCell<T>` value. The `borrow_mut` method returns a `RefMut<T>` smart -pointer, and we use the dereference operator on it and change the inner value. +the automatic dereferencing feature we discussed in “Where’s the -> Operator?†+on page XX to dereference the `Rc<T>` to the inner `RefCell<T>` value. The +`borrow_mut` method returns a `RefMut<T>` smart pointer, and we use the +dereference operator on it and change the inner value. When we print `a`, `b`, and `c`, we can see that they all have the modified -value of 15 rather than 5: +value of `15` rather than `5`: ``` a after = Cons(RefCell { value: 15 }, Nil) @@ -1561,7 +1613,7 @@ access to its interior mutability so we can modify our data when we need to. The runtime checks of the borrowing rules protect us from data races, and it’s sometimes worth trading a bit of speed for this flexibility in our data structures. Note that `RefCell<T>` does not work for multithreaded code! -`Mutex<T>` is the thread-safe version of `RefCell<T>` and we’ll discuss +`Mutex<T>` is the thread-safe version of `RefCell<T>`, and we’ll discuss `Mutex<T>` in Chapter 16. ## Reference Cycles Can Leak Memory @@ -1579,7 +1631,7 @@ will never be dropped. Let’s look at how a reference cycle might happen and how to prevent it, starting with the definition of the `List` enum and a `tail` method in Listing -15-25: +15-25. Filename: src/main.rs @@ -1590,12 +1642,12 @@ use std::rc::Rc; #[derive(Debug)] enum List { - [1] Cons(i32, RefCell<Rc<List>>), + 1 Cons(i32, RefCell<Rc<List>>), Nil, } impl List { - [2] fn tail(&self) -> Option<&RefCell<Rc<List>>> { + 2 fn tail(&self) -> Option<&RefCell<Rc<List>>> { match self { Cons(_, item) => Some(item), Nil => None, @@ -1610,9 +1662,9 @@ modify what a `Cons` variant is referring to We’re using another variation of the `List` definition from Listing 15-5. The second element in the `Cons` variant is now `RefCell<Rc<List>>` [1], meaning that instead of having the ability to modify the `i32` value as we did in -Listing 15-24, we want to modify the `List` value a `Cons` variant is -pointing to. We’re also adding a `tail` method [2] to make it convenient for us -to access the second item if we have a `Cons` variant. +Listing 15-24, we want to modify the `List` value a `Cons` variant is pointing +to. We’re also adding a `tail` method [2] to make it convenient for us to +access the second item if we have a `Cons` variant. In Listing 15-26, we’re adding a `main` function that uses the definitions in Listing 15-25. This code creates a list in `a` and a list in `b` that points to @@ -1624,23 +1676,32 @@ Filename: src/main.rs ``` fn main() { - [1] let a = Rc::new(Cons(5, RefCell::new(Rc::new(Nil)))); + 1 let a = Rc::new(Cons(5, RefCell::new(Rc::new(Nil)))); println!("a initial rc count = {}", Rc::strong_count(&a)); println!("a next item = {:?}", a.tail()); - [2] let b = Rc::new(Cons(10, RefCell::new(Rc::clone(&a)))); + 2 let b = Rc::new(Cons(10, RefCell::new(Rc::clone(&a)))); - println!("a rc count after b creation = {}", Rc::strong_count(&a)); + println!( + "a rc count after b creation = {}", + Rc::strong_count(&a) + ); println!("b initial rc count = {}", Rc::strong_count(&b)); println!("b next item = {:?}", b.tail()); - [3] if let Some(link) = a.tail() { - [4] *link.borrow_mut() = Rc::clone(&b); + 3 if let Some(link) = a.tail() { + 4 *link.borrow_mut() = Rc::clone(&b); } - println!("b rc count after changing a = {}", Rc::strong_count(&b)); - println!("a rc count after changing a = {}", Rc::strong_count(&a)); + println!( + "b rc count after changing a = {}", + Rc::strong_count(&b) + ); + println!( + "a rc count after changing a = {}", + Rc::strong_count(&a) + ); // Uncomment the next line to see that we have a cycle; // it will overflow the stack @@ -1653,8 +1714,8 @@ other We create an `Rc<List>` instance holding a `List` value in the variable `a` with an initial list of `5, Nil` [1]. We then create an `Rc<List>` instance -holding another `List` value in the variable `b` that contains the value 10 and -points to the list in `a` [2]. +holding another `List` value in the variable `b` that contains the value `10` +and points to the list in `a` [2]. We modify `a` so it points to `b` instead of `Nil`, creating a cycle. We do that by using the `tail` method to get a reference to the `RefCell<Rc<List>>` @@ -1675,30 +1736,28 @@ b rc count after changing a = 2 a rc count after changing a = 2 ``` -The reference count of the `Rc<List>` instances in both `a` and `b` are 2 after +The reference count of the `Rc<List>` instances in both `a` and `b` is 2 after we change the list in `a` to point to `b`. At the end of `main`, Rust drops the -variable `b`, which decreases the reference count of the `b` `Rc<List>` instance -from 2 to 1. The memory that `Rc<List>` has on the heap won’t be dropped at -this point, because its reference count is 1, not 0. Then Rust drops `a`, which -decreases the reference count of the `a` `Rc<List>` instance from 2 to 1 as -well. This instance’s memory can’t be dropped either, because the other +variable `b`, which decreases the reference count of the `b` `Rc<List>` +instance from 2 to 1. The memory that `Rc<List>` has on the heap won’t be +dropped at this point because its reference count is 1, not 0. Then Rust drops +`a`, which decreases the reference count of the `a` `Rc<List>` instance from 2 +to 1 as well. This instance’s memory can’t be dropped either, because the other `Rc<List>` instance still refers to it. The memory allocated to the list will remain uncollected forever. To visualize this reference cycle, we’ve created a diagram in Figure 15-4. -<img alt="Reference cycle of lists" src="img/trpl15-04.svg" class="center" /> - Figure 15-4: A reference cycle of lists `a` and `b` pointing to each other 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 -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 -than it needed and might overwhelm the system, causing it to run out of +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 than it needed and might overwhelm the system, causing it to run out of available memory. Creating reference cycles is not easily done, but it’s not impossible either. @@ -1719,7 +1778,7 @@ Let’s look at an example using graphs made up of parent nodes and child nodes to see when non-ownership relationships are an appropriate way to prevent reference cycles. -### Preventing Reference Cycles: Turning an `Rc<T>` into a `Weak<T>` +### Preventing Reference Cycles Using Weak<T> So far, we’ve demonstrated that calling `Rc::clone` increases the `strong_count` of an `Rc<T>` instance, and an `Rc<T>` instance is only cleaned @@ -1727,7 +1786,7 @@ up if its `strong_count` is 0. You can also create a *weak reference* to the value within an `Rc<T>` instance by calling `Rc::downgrade` and passing a reference to the `Rc<T>`. Strong references are how you can share ownership of an `Rc<T>` instance. Weak references don’t express an ownership relationship, -and their count doesn't affect when an `Rc<T>` instance is cleaned up. They +and their count doesn’t affect when an `Rc<T>` instance is cleaned up. They won’t cause a reference cycle because any cycle involving some weak references will be broken once the strong reference count of values involved is 0. @@ -1739,7 +1798,7 @@ Instead of increasing the `strong_count` in the `Rc<T>` instance by 1, calling `Rc<T>` instance to be cleaned up. Because the value that `Weak<T>` references might have been dropped, to do -anything with the value that a `Weak<T>` is pointing to, you must make sure the +anything with the value that a `Weak<T>` is pointing to you must make sure the value still exists. Do this by calling the `upgrade` method on a `Weak<T>` instance, which will return an `Option<Rc<T>>`. You’ll get a result of `Some` if the `Rc<T>` value has not been dropped yet and a result of `None` if the @@ -1751,7 +1810,7 @@ As an example, rather than using a list whose items know only about the next item, we’ll create a tree whose items know about their children items *and* their parent items. -#### Creating a Tree Data Structure: a `Node` with Child Nodes +#### Creating a Tree Data Structure: A Node with Child Nodes To start, we’ll build a tree with nodes that know about their child nodes. We’ll create a struct named `Node` that holds its own `i32` value as well as @@ -1777,8 +1836,8 @@ modify which nodes are children of another node, so we have a `RefCell<T>` in `children` around the `Vec<Rc<Node>>`. Next, we’ll use our struct definition and create one `Node` instance named -`leaf` with the value 3 and no children, and another instance named `branch` -with the value 5 and `leaf` as one of its children, as shown in Listing 15-27: +`leaf` with the value `3` and no children, and another instance named `branch` +with the value `5` and `leaf` as one of its children, as shown in Listing 15-27. Filename: src/main.rs @@ -1810,7 +1869,7 @@ parent. We’ll do that next. To make the child node aware of its parent, we need to add a `parent` field to our `Node` struct definition. The trouble is in deciding what the type of -`parent` should be. We know it can’t contain an `Rc<T>`, because that would +`parent` should be. We know it can’t contain an `Rc<T>` because that would create a reference cycle with `leaf.parent` pointing to `branch` and `branch.children` pointing to `leaf`, which would cause their `strong_count` values to never be 0. @@ -1820,7 +1879,7 @@ children: if a parent node is dropped, its child nodes should be dropped as well. However, a child should not own its parent: if we drop a child node, the parent should still exist. This is a case for weak references! -So instead of `Rc<T>`, we’ll make the type of `parent` use `Weak<T>`, +So, instead of `Rc<T>`, we’ll make the type of `parent` use `Weak<T>`, specifically a `RefCell<Weak<Node>>`. Now our `Node` struct definition looks like this: @@ -1838,35 +1897,41 @@ struct Node { } ``` -A node will be able to refer to its parent node but doesn’t own its parent. -In Listing 15-28, we update `main` to use this new definition so the `leaf` -node will have a way to refer to its parent, `branch`: +A node will be able to refer to its parent node but doesn’t own its parent. In +Listing 15-28, we update `main` to use this new definition so the `leaf` node +will have a way to refer to its parent, `branch`. -Filename: src/main.rs +Filename: src/main.rs ``` fn main() { let leaf = Rc::new(Node { value: 3, - [1] parent: RefCell::new(Weak::new()), + 1 parent: RefCell::new(Weak::new()), children: RefCell::new(vec![]), }); - [2] println!("leaf parent = {:?}", leaf.parent.borrow().upgrade()); + 2 println!( + "leaf parent = {:?}", + leaf.parent.borrow().upgrade() + ); let branch = Rc::new(Node { value: 5, - [3] parent: RefCell::new(Weak::new()), + 3 parent: RefCell::new(Weak::new()), children: RefCell::new(vec![Rc::clone(&leaf)]), }); - [4] *leaf.parent.borrow_mut() = Rc::downgrade(&branch); + 4 *leaf.parent.borrow_mut() = Rc::downgrade(&branch); - [5] println!("leaf parent = {:?}", leaf.parent.borrow().upgrade()); + 5 println!( + "leaf parent = {:?}", + leaf.parent.borrow().upgrade() + ); } ``` -Listing 15-28: A `leaf` node with a weak reference to its parent node `branch` +Listing 15-28: A `leaf` node with a weak reference to its parent node, `branch` Creating the `leaf` node looks similar to Listing 15-27 with the exception of the `parent` field: `leaf` starts out without a parent, so we create a new, @@ -1881,13 +1946,13 @@ leaf parent = None ``` When we create the `branch` node, it will also have a new `Weak<Node>` -reference in the `parent` field [3], because `branch` doesn’t have a parent +reference in the `parent` field [3] because `branch` doesn’t have a parent node. We still have `leaf` as one of the children of `branch`. Once we have the `Node` instance in `branch`, we can modify `leaf` to give it a `Weak<Node>` reference to its parent [4]. We use the `borrow_mut` method on the `RefCell<Weak<Node>>` in the `parent` field of `leaf`, and then we use the `Rc::downgrade` function to create a `Weak<Node>` reference to `branch` from -the `Rc<Node>` in `branch.` +the `Rc<Node>` in `branch`. When we print the parent of `leaf` again [5], this time we’ll get a `Some` variant holding `branch`: now `leaf` can access its parent! When we print @@ -1904,13 +1969,13 @@ The lack of infinite output indicates that this code didn’t create a reference cycle. We can also tell this by looking at the values we get from calling `Rc::strong_count` and `Rc::weak_count`. -#### Visualizing Changes to `strong_count` and `weak_count` +#### Visualizing Changes to strong_count and weak_count Let’s look at how the `strong_count` and `weak_count` values of the `Rc<Node>` instances change by creating a new inner scope and moving the creation of `branch` into that scope. By doing so, we can see what happens when `branch` is created and then dropped when it goes out of scope. The modifications are shown -in Listing 15-29: +in Listing 15-29. Filename: src/main.rs @@ -1922,13 +1987,13 @@ fn main() { children: RefCell::new(vec![]), }); - [1] println!( + 1 println!( "leaf strong = {}, weak = {}", Rc::strong_count(&leaf), Rc::weak_count(&leaf), ); - [2] { + 2 { let branch = Rc::new(Node { value: 5, parent: RefCell::new(Weak::new()), @@ -1937,21 +2002,24 @@ fn main() { *leaf.parent.borrow_mut() = Rc::downgrade(&branch); - [3] println!( + 3 println!( "branch strong = {}, weak = {}", Rc::strong_count(&branch), Rc::weak_count(&branch), ); - [4] println!( + 4 println!( "leaf strong = {}, weak = {}", Rc::strong_count(&leaf), Rc::weak_count(&leaf), ); - [5] } + 5 } - [6] println!("leaf parent = {:?}", leaf.parent.borrow().upgrade()); - [7] println!( + 6 println!( + "leaf parent = {:?}", + leaf.parent.borrow().upgrade() + ); + 7 println!( "leaf strong = {}, weak = {}", Rc::strong_count(&leaf), Rc::weak_count(&leaf), @@ -1967,7 +2035,7 @@ count of 0 [1]. In the inner scope [2], we create `branch` and associate it with `leaf`, at which point when we print the counts [3], the `Rc<Node>` in `branch` will have a strong count of 1 and a weak count of 1 (for `leaf.parent` pointing to `branch` with a `Weak<Node>`). When we print the counts in `leaf` -[4], we’ll see it will have a strong count of 2, because `branch` now has a +[4], we’ll see it will have a strong count of 2 because `branch` now has a clone of the `Rc<Node>` of `leaf` stored in `branch.children`, but will still have a weak count of 0. @@ -1978,7 +2046,7 @@ don’t get any memory leaks! If we try to access the parent of `leaf` after the end of the scope, we’ll get `None` again [6]. At the end of the program [7], the `Rc<Node>` in `leaf` has a -strong count of 1 and a weak count of 0, because the variable `leaf` is now the +strong count of 1 and a weak count of 0 because the variable `leaf` is now the only reference to the `Rc<Node>` again. All of the logic that manages the counts and value dropping is built into @@ -2005,7 +2073,8 @@ memory leaks and how to prevent them using `Weak<T>`. If this chapter has piqued your interest and you want to implement your own smart pointers, check out “The Rustonomicon†at -*https://doc.rust-lang.org/stable/nomicon/* for more useful information. +*https://doc.rust-lang.org/stable/nomicon* for more useful information. Next, we’ll talk about concurrency in Rust. You’ll even learn about a few new smart pointers. + diff --git a/src/doc/book/nostarch/chapter16.md b/src/doc/book/nostarch/chapter16.md index 1f404f84d..7c5389e4f 100644 --- a/src/doc/book/nostarch/chapter16.md +++ b/src/doc/book/nostarch/chapter16.md @@ -16,30 +16,6 @@ computers take advantage of their multiple processors. Historically, programming in these contexts has been difficult and error prone: Rust hopes to change that. -<!-- Concurrent programming isn't necessarily helped by having multiple -processors. How I've been teaching it is to distinguish the two by their -workload: concurrent programming serves the needs of I/O-bound workloads and -parallel programming serves the needs of CPU-bound workloads. If you give -CPU bound workloads more CPUs, you have the opportunity to possibly go faster -(assuming sufficient parallelism in the code). For I/O-bound workloads, -rather than the need to have multiple processors, you need to be able to -get as many I/O requests in flight and being processed as you can. This -allows more I/O requests, and as a result better throughput/response time -on those I/O requests. - -We could introduce these concepts and then simplify like we do in a bit to -say that the design considerations of Rust allow both concurrency and -parallelism to be done safely (...and for the remainder of the chapter talk -about those design considerations rather than the specifics for either -concurrency or parallelism) /JT --> -<!-- I really don't want to get in the weeds on this because there are many -other books and resources about concurrency and parallelism because these -concepts aren't Rust specific. I want this to feel accessible to programmers -who have never even considered whether their programs are I/O or CPU bound, -because those are the types of programmers we want to empower (and make them -feel empowered to create concurrent and/or parallel code) through Rust. So I'm -deliberately choosing not to change anything here. /Carol --> - Initially, the Rust team thought that ensuring memory safety and preventing concurrency problems were two separate challenges to be solved with different methods. Over time, the team discovered that the ownership and type systems are @@ -55,16 +31,16 @@ shipped to production. We’ve nicknamed this aspect of Rust *fearless* subtle bugs and is easy to refactor without introducing new bugs. > Note: For simplicity’s sake, we’ll refer to many of the problems as -> *concurrent* rather than being more precise by saying *concurrent and/or -> parallel*. If this book were about concurrency and/or parallelism, we’d be -> more specific. For this chapter, please mentally substitute *concurrent -> and/or parallel* whenever we use *concurrent*. +*concurrent* rather than being more precise by saying *concurrent and/or +parallel*. If this book were about concurrency and/or parallelism, we’d be more +specific. For this chapter, please mentally substitute *concurrent and/or +parallel* whenever we use *concurrent*. Many languages are dogmatic about the solutions they offer for handling concurrent problems. For example, Erlang has elegant functionality for message-passing concurrency but has only obscure ways to share state between threads. Supporting only a subset of possible solutions is a reasonable -strategy for higher-level languages, because a higher-level language promises +strategy for higher-level languages because a higher-level language promises benefits from giving up some control to gain abstractions. However, lower-level languages are expected to provide the solution with the best performance in any given situation and have fewer abstractions over the hardware. Therefore, Rust @@ -76,9 +52,9 @@ Here are the topics we’ll cover in this chapter: * How to create threads to run multiple pieces of code at the same time * *Message-passing* concurrency, where channels send messages between threads * *Shared-state* concurrency, where multiple threads have access to some piece - of data +of data * The `Sync` and `Send` traits, which extend Rust’s concurrency guarantees to - user-defined types as well as types provided by the standard library +user-defined types as well as types provided by the standard library ## Using Threads to Run Code Simultaneously @@ -96,11 +72,11 @@ order in which parts of your code on different threads will run. This can lead to problems, such as: * Race conditions, where threads are accessing data or resources in an - inconsistent order +inconsistent order * Deadlocks, where two threads are waiting for each other, preventing both - threads from continuing +threads from continuing * Bugs that happen only in certain situations and are hard to reproduce and fix - reliably +reliably Rust attempts to mitigate the negative effects of using threads, but programming in a multithreaded context still takes careful thought and requires @@ -112,14 +88,14 @@ operating systems provide an API the language can call for creating new threads. The Rust standard library uses a *1:1* model of thread implementation, whereby a program uses one operating system thread per one language thread. There are crates that implement other models of threading that make different -tradeoffs to the 1:1 model. +trade-offs to the 1:1 model. -### Creating a New Thread with `spawn` +### Creating a New Thread with spawn To create a new thread, we call the `thread::spawn` function and pass it a closure (we talked about closures in Chapter 13) containing the code we want to run in the new thread. The example in Listing 16-1 prints some text from a main -thread and other text from a new thread: +thread and other text from a new thread. Filename: src/main.rs @@ -130,13 +106,13 @@ use std::time::Duration; fn main() { thread::spawn(|| { for i in 1..10 { - println!("hi number {} from the spawned thread!", i); + println!("hi number {i} from the spawned thread!"); thread::sleep(Duration::from_millis(1)); } }); for i in 1..5 { - println!("hi number {} from the main thread!", i); + println!("hi number {i} from the main thread!"); thread::sleep(Duration::from_millis(1)); } } @@ -174,19 +150,20 @@ If you run this code and only see output from the main thread, or don’t see an overlap, try increasing the numbers in the ranges to create more opportunities for the operating system to switch between the threads. -### Waiting for All Threads to Finish Using `join` Handles +### Waiting for All Threads to Finish Using join Handles The code in Listing 16-1 not only stops the spawned thread prematurely most of the time due to the main thread ending, but because there is no guarantee on the order in which threads run, we also can’t guarantee that the spawned thread will get to run at all! -We can fix the problem of the spawned thread not running or ending prematurely -by saving the return value of `thread::spawn` in a variable. The return type of -`thread::spawn` is `JoinHandle`. A `JoinHandle` is an owned value that, when we -call the `join` method on it, will wait for its thread to finish. Listing 16-2 -shows how to use the `JoinHandle` of the thread we created in Listing 16-1 and -call `join` to make sure the spawned thread finishes before `main` exits: +We can fix the problem of the spawned thread not running or of it ending +prematurely by saving the return value of `thread::spawn` in a variable. The +return type of `thread::spawn` is `JoinHandle<T>`. A `JoinHandle<T>` is an +owned value that, when we call the `join` method on it, will wait for its +thread to finish. Listing 16-2 shows how to use the `JoinHandle<T>` of the +thread we created in Listing 16-1 and call `join` to make sure the spawned +thread finishes before `main` exits. Filename: src/main.rs @@ -197,13 +174,13 @@ use std::time::Duration; fn main() { let handle = thread::spawn(|| { for i in 1..10 { - println!("hi number {} from the spawned thread!", i); + println!("hi number {i} from the spawned thread!"); thread::sleep(Duration::from_millis(1)); } }); for i in 1..5 { - println!("hi number {} from the main thread!", i); + println!("hi number {i} from the main thread!"); thread::sleep(Duration::from_millis(1)); } @@ -211,7 +188,7 @@ fn main() { } ``` -Listing 16-2: Saving a `JoinHandle` from `thread::spawn` to guarantee the +Listing 16-2: Saving a `JoinHandle<T>` from `thread::spawn` to guarantee the thread is run to completion Calling `join` on the handle blocks the thread currently running until the @@ -251,7 +228,7 @@ use std::time::Duration; fn main() { let handle = thread::spawn(|| { for i in 1..10 { - println!("hi number {} from the spawned thread!", i); + println!("hi number {i} from the spawned thread!"); thread::sleep(Duration::from_millis(1)); } }); @@ -259,7 +236,7 @@ fn main() { handle.join().unwrap(); for i in 1..5 { - println!("hi number {} from the main thread!", i); + println!("hi number {i} from the main thread!"); thread::sleep(Duration::from_millis(1)); } } @@ -287,21 +264,21 @@ hi number 4 from the main thread! Small details, such as where `join` is called, can affect whether or not your threads run at the same time. -### Using `move` Closures with Threads +### Using move Closures with Threads -We'll often use the `move` keyword with closures passed to `thread::spawn` +We’ll often use the `move` keyword with closures passed to `thread::spawn` because the closure will then take ownership of the values it uses from the environment, thus transferring ownership of those values from one thread to -another. In the “Capturing the Environment with Closures†section of Chapter -13, we discussed `move` in the context of closures. Now, we’ll concentrate more -on the interaction between `move` and `thread::spawn`. +another. In “Capturing the Environment with Closures†on page XX, we discussed +`move` in the context of closures. Now we’ll concentrate more on the +interaction between `move` and `thread::spawn`. Notice in Listing 16-1 that the closure we pass to `thread::spawn` takes no arguments: we’re not using any data from the main thread in the spawned thread’s code. To use data from the main thread in the spawned thread, the spawned thread’s closure must capture the values it needs. Listing 16-3 shows an attempt to create a vector in the main thread and use it in the spawned -thread. However, this won’t yet work, as you’ll see in a moment. +thread. However, this won’t work yet, as you’ll see in a moment. Filename: src/main.rs @@ -328,7 +305,8 @@ should be able to access `v` inside that new thread. But when we compile this example, we get the following error: ``` -error[E0373]: closure may outlive the current function, but it borrows `v`, which is owned by the current function +error[E0373]: closure may outlive the current function, but it borrows `v`, +which is owned by the current function --> src/main.rs:6:32 | 6 | let handle = thread::spawn(|| { @@ -344,7 +322,8 @@ note: function requires argument type to outlive `'static` 7 | | println!("Here's a vector: {:?}", v); 8 | | }); | |______^ -help: to force the closure to take ownership of `v` (and any other referenced variables), use the `move` keyword +help: to force the closure to take ownership of `v` (and any other referenced +variables), use the `move` keyword | 6 | let handle = thread::spawn(move || { | ++++ @@ -352,11 +331,11 @@ help: to force the closure to take ownership of `v` (and any other referenced va Rust *infers* how to capture `v`, and because `println!` only needs a reference to `v`, the closure tries to borrow `v`. However, there’s a problem: Rust can’t -tell how long the spawned thread will run, so it doesn’t know if the reference -to `v` will always be valid. +tell how long the spawned thread will run, so it doesn’t know whether the +reference to `v` will always be valid. Listing 16-4 provides a scenario that’s more likely to have a reference to `v` -that won’t be valid: +that won’t be valid. Filename: src/main.rs @@ -379,10 +358,10 @@ fn main() { Listing 16-4: A thread with a closure that attempts to capture a reference to `v` from a main thread that drops `v` -If Rust allowed us to run this code, there’s a possibility the spawned thread -would be immediately put in the background without running at all. The spawned -thread has a reference to `v` inside, but the main thread immediately drops -`v`, using the `drop` function we discussed in Chapter 15. Then, when the +If Rust allowed us to run this code, there’s a possibility that the spawned +thread would be immediately put in the background without running at all. The +spawned thread has a reference to `v` inside, but the main thread immediately +drops `v`, using the `drop` function we discussed in Chapter 15. Then, when the spawned thread starts to execute, `v` is no longer valid, so a reference to it is also invalid. Oh no! @@ -390,7 +369,8 @@ To fix the compiler error in Listing 16-3, we can use the error message’s advice: ``` -help: to force the closure to take ownership of `v` (and any other referenced variables), use the `move` keyword +help: to force the closure to take ownership of `v` (and any other referenced +variables), use the `move` keyword | 6 | let handle = thread::spawn(move || { | ++++ @@ -399,7 +379,7 @@ help: to force the closure to take ownership of `v` (and any other referenced va By adding the `move` keyword before the closure, we force the closure to take ownership of the values it’s using rather than allowing Rust to infer that it should borrow the values. The modification to Listing 16-3 shown in Listing -16-5 will compile and run as we intend: +16-5 will compile and run as we intend. Filename: src/main.rs @@ -432,12 +412,14 @@ error[E0382]: use of moved value: `v` --> src/main.rs:10:10 | 4 | let v = vec![1, 2, 3]; - | - move occurs because `v` has type `Vec<i32>`, which does not implement the `Copy` trait + | - move occurs because `v` has type `Vec<i32>`, which does not +implement the `Copy` trait 5 | 6 | let handle = thread::spawn(move || { | ------- value moved into closure here 7 | println!("Here's a vector: {:?}", v); - | - variable moved due to use in closure + | - variable moved due to use in +closure ... 10 | drop(v); // oh no! | ^ value used here after move @@ -453,38 +435,18 @@ rules when we try to use `v` in the main thread. The `move` keyword overrides Rust’s conservative default of borrowing; it doesn’t let us violate the ownership rules. -With a basic understanding of threads and the thread API, let’s look at what we -can *do* with threads. +Now that we’ve covered what threads are and the methods supplied by the thread +API, let’s look at some situations in which we can use threads. ## Using Message Passing to Transfer Data Between Threads One increasingly popular approach to ensuring safe concurrency is *message passing*, where threads or actors communicate by sending each other messages -containing data. Here’s the idea in a slogan from the Go language -documentation at *https://golang.org/doc/effective_go.html#concurrency*: -“Do not communicate by sharing memory; instead, share memory by communicating.†- -<!-- are they communicating to decide which thread should be running, or by -"communicate" do we just mean sharing data? /LC --> -<!-- Just sharing data. Is there something that should be clarified here? I'm -not sure what to do because this paragraph doesn't mention deciding which -thread should be running, it only mentions sharing data, so I'm not sure where -the possible confusion is coming from. /Carol --> -<!-- JT, if this will be already obvious to a reader, no changes needed. I just -wanted to ensure there was no potential confusion around what is being -communicated /LC --> -<!-- I like that we want to give a shout-out to Go's thinking process when -we align, though I made a bit of a face reading the quote. "Share memory" is a -such a loaded concept that I think people might stumble a bit over the play on -the technical words. - -Funnily the next line following that quote in the Go book is: - -"This approach can be taken too far." :D -/JT --> -<!-- I think this means JT is fine leaving this the way it is! /Carol --> - -To accomplish message-sending concurrency, Rust's standard library provides an +containing data. Here’s the idea in a slogan from the Go language documentation +at *https://golang.org/doc/effective_go.html#concurrency*: “Do not communicate +by sharing memory; instead, share memory by communicating.†+ +To accomplish message-sending concurrency, Rust’s standard library provides an implementation of *channels*. A channel is a general programming concept by which data is sent from one thread to another. @@ -493,7 +455,7 @@ water, such as a stream or a river. If you put something like a rubber duck into a river, it will travel downstream to the end of the waterway. A channel has two halves: a transmitter and a receiver. The transmitter half is -the upstream location where you put rubber ducks into the river, and the +the upstream location where you put the rubber duck into the river, and the receiver half is where the rubber duck ends up downstream. One part of your code calls methods on the transmitter with the data you want to send, and another part checks the receiving end for arriving messages. A channel is said @@ -503,9 +465,9 @@ Here, we’ll work up to a program that has one thread to generate values and send them down a channel, and another thread that will receive the values and print them out. We’ll be sending simple values between threads using a channel to illustrate the feature. Once you’re familiar with the technique, you could -use channels for any threads that needs to communicate between each other, such -as a chat system or a system where many threads perform parts of a calculation -and send the parts to one thread that aggregates the results. +use channels for any threads that need to communicate with each other, such as +a chat system or a system where many threads perform parts of a calculation and +send the parts to one thread that aggregates the results. First, in Listing 16-6, we’ll create a channel but not do anything with it. Note that this won’t compile yet because Rust can’t tell what type of values we @@ -533,14 +495,14 @@ producer for now, but we’ll add multiple producers when we get this example working. The `mpsc::channel` function returns a tuple, the first element of which is the -sending end--the transmitter--and the second element is the receiving end--the -receiver. The abbreviations `tx` and `rx` are traditionally used in many fields -for *transmitter* and *receiver* respectively, so we name our variables as such -to indicate each end. We’re using a `let` statement with a pattern that -destructures the tuples; we’ll discuss the use of patterns in `let` statements -and destructuring in Chapter 18. For now, know that using a `let` statement -this way is a convenient approach to extract the pieces of the tuple returned -by `mpsc::channel`. +sending end—the transmitter—and the second element of which is the receiving +end—the receiver. The abbreviations `tx` and `rx` are traditionally used in +many fields for *transmitter* and *receiver*, respectively, so we name our +variables as such to indicate each end. We’re using a `let` statement with a +pattern that destructures the tuples; we’ll discuss the use of patterns in +`let` statements and destructuring in Chapter 18. For now, know that using a +`let` statement in this way is a convenient approach to extract the pieces of +the tuple returned by `mpsc::channel`. Let’s move the transmitting end into a spawned thread and have it send one string so the spawned thread is communicating with the main thread, as shown in @@ -563,18 +525,18 @@ fn main() { } ``` -Listing 16-7: Moving `tx` to a spawned thread and sending “hi†+Listing 16-7: Moving `tx` to a spawned thread and sending `"hi"` Again, we’re using `thread::spawn` to create a new thread and then using `move` to move `tx` into the closure so the spawned thread owns `tx`. The spawned thread needs to own the transmitter to be able to send messages through the channel. -The transmitter has a `send` method that takes the value we want to send. -The `send` method returns a `Result<T, E>` type, so if the receiver has -already been dropped and there’s nowhere to send a value, the send operation -will return an error. In this example, we’re calling `unwrap` to panic in case -of an error. But in a real application, we would handle it properly: return to +The transmitter has a `send` method that takes the value we want to send. The +`send` method returns a `Result<T, E>` type, so if the receiver has already +been dropped and there’s nowhere to send a value, the send operation will +return an error. In this example, we’re calling `unwrap` to panic in case of an +error. But in a real application, we would handle it properly: return to Chapter 9 to review strategies for proper error handling. In Listing 16-8, we’ll get the value from the receiver in the main thread. This @@ -596,11 +558,11 @@ fn main() { }); let received = rx.recv().unwrap(); - println!("Got: {}", received); + println!("Got: {received}"); } ``` -Listing 16-8: Receiving the value “hi†in the main thread and printing it +Listing 16-8: Receiving the value `"hi"` in the main thread and printing it The receiver has two useful methods: `recv` and `try_recv`. We’re using `recv`, short for *receive*, which will block the main thread’s execution and wait @@ -637,7 +599,7 @@ advantage of thinking about ownership throughout your Rust programs. Let’s do an experiment to show how channels and ownership work together to prevent problems: we’ll try to use a `val` value in the spawned thread *after* we’ve sent it down the channel. Try compiling the code in Listing 16-9 to see why -this code isn’t allowed: +this code isn’t allowed. Filename: src/main.rs @@ -651,11 +613,11 @@ fn main() { thread::spawn(move || { let val = String::from("hi"); tx.send(val).unwrap(); - println!("val is {}", val); + println!("val is {val}"); }); let received = rx.recv().unwrap(); - println!("Got: {}", received); + println!("Got: {received}"); } ``` @@ -673,15 +635,16 @@ error[E0382]: borrow of moved value: `val` --> src/main.rs:10:31 | 8 | let val = String::from("hi"); - | --- move occurs because `val` has type `String`, which does not implement the `Copy` trait + | --- move occurs because `val` has type `String`, which does +not implement the `Copy` trait 9 | tx.send(val).unwrap(); | --- value moved here -10 | println!("val is {}", val); - | ^^^ value borrowed here after move +10 | println!("val is {val}"); + | ^^^ value borrowed here after move ``` -Our concurrency mistake has caused a compile time error. The `send` function -takes ownership of its parameter, and when the value is moved, the receiver +Our concurrency mistake has caused a compile-time error. The `send` function +takes ownership of its parameter, and when the value is moved the receiver takes ownership of it. This stops us from accidentally using the value again after sending it; the ownership system checks that everything is okay. @@ -718,24 +681,24 @@ fn main() { }); for received in rx { - println!("Got: {}", received); + println!("Got: {received}"); } } ``` -Listing 16-10: Sending multiple messages and pausing between each +Listing 16-10: Sending multiple messages and pausing between each one This time, the spawned thread has a vector of strings that we want to send to the main thread. We iterate over them, sending each individually, and pause between each by calling the `thread::sleep` function with a `Duration` value of -1 second. +one second. In the main thread, we’re not calling the `recv` function explicitly anymore: instead, we’re treating `rx` as an iterator. For each value received, we’re printing it. When the channel is closed, iteration will end. When running the code in Listing 16-10, you should see the following output -with a 1-second pause in between each line: +with a one-second pause in between each line: ``` Got: hi @@ -750,52 +713,52 @@ the spawned thread. ### Creating Multiple Producers by Cloning the Transmitter -Earlier we mentioned that `mpsc` was an acronym for *multiple producer, -single consumer*. Let’s put `mpsc` to use and expand the code in Listing 16-10 -to create multiple threads that all send values to the same receiver. We can do -so by cloning the transmitter, as shown in Listing 16-11: +Earlier we mentioned that `mpsc` was an acronym for *multiple producer, single +consumer*. Let’s put `mpsc` to use and expand the code in Listing 16-10 to +create multiple threads that all send values to the same receiver. We can do so +by cloning the transmitter, as shown in Listing 16-11. Filename: src/main.rs ``` - // --snip-- - - let (tx, rx) = mpsc::channel(); - - let tx1 = tx.clone(); - thread::spawn(move || { - let vals = vec![ - String::from("hi"), - String::from("from"), - String::from("the"), - String::from("thread"), - ]; - - for val in vals { - tx1.send(val).unwrap(); - thread::sleep(Duration::from_secs(1)); - } - }); +--snip-- + +let (tx, rx) = mpsc::channel(); + +let tx1 = tx.clone(); +thread::spawn(move || { + let vals = vec![ + String::from("hi"), + String::from("from"), + String::from("the"), + String::from("thread"), + ]; + + for val in vals { + tx1.send(val).unwrap(); + thread::sleep(Duration::from_secs(1)); + } +}); - thread::spawn(move || { - let vals = vec![ - String::from("more"), - String::from("messages"), - String::from("for"), - String::from("you"), - ]; +thread::spawn(move || { + let vals = vec![ + String::from("more"), + String::from("messages"), + String::from("for"), + String::from("you"), + ]; - for val in vals { - tx.send(val).unwrap(); - thread::sleep(Duration::from_secs(1)); - } - }); - - for received in rx { - println!("Got: {}", received); + for val in vals { + tx.send(val).unwrap(); + thread::sleep(Duration::from_secs(1)); } +}); + +for received in rx { + println!("Got: {received}"); +} - // --snip-- +--snip-- ``` Listing 16-11: Sending multiple messages from multiple producers @@ -828,22 +791,17 @@ concurrency. ## Shared-State Concurrency -Message passing is a fine way of handling concurrency, but it’s not the only -one. Another method would be for multiple threads to access the same shared -data. Consider this part of the slogan from the Go language documentation -again: “do not communicate by sharing memory.†- -<!-- NB: if we decide to do anything with the Go quote above, we also -reference it here. -/JT --> -<!-- Also not changing anything here. /Carol --> +Message passing is a fine way to handle concurrency, but it’s not the only way. +Another method would be for multiple threads to access the same shared data. +Consider this part of the slogan from the Go language documentation again: “Do +not communicate by sharing memory.†What would communicating by sharing memory look like? In addition, why would message-passing enthusiasts caution not to use memory sharing? -In a way, channels in any programming language are similar to single ownership, +In a way, channels in any programming language are similar to single ownership because once you transfer a value down a channel, you should no longer use that -value. Shared memory concurrency is like multiple ownership: multiple threads +value. Shared-memory concurrency is like multiple ownership: multiple threads can access the same memory location at the same time. As you saw in Chapter 15, where smart pointers made multiple ownership possible, multiple ownership can add complexity because these different owners need managing. Rust’s type system @@ -853,7 +811,7 @@ for shared memory. ### Using Mutexes to Allow Access to Data from One Thread at a Time -*Mutex* is an abbreviation for *mutual exclusion*, as in, a mutex allows only +*Mutex* is an abbreviation for *mutual exclusion*, as in a mutex allows only one thread to access some data at any given time. To access the data in a mutex, a thread must first signal that it wants access by asking to acquire the mutex’s *lock*. The lock is a data structure that is part of the mutex that @@ -863,9 +821,9 @@ mutex is described as *guarding* the data it holds via the locking system. Mutexes have a reputation for being difficult to use because you have to remember two rules: -* You must attempt to acquire the lock before using the data. -* When you’re done with the data that the mutex guards, you must unlock the - data so other threads can acquire the lock. +1. You must attempt to acquire the lock before using the data. +1. When you’re done with the data that the mutex guards, you must unlock the +data so other threads can acquire the lock. For a real-world metaphor for a mutex, imagine a panel discussion at a conference with only one microphone. Before a panelist can speak, they have to @@ -880,10 +838,10 @@ Management of mutexes can be incredibly tricky to get right, which is why so many people are enthusiastic about channels. However, thanks to Rust’s type system and ownership rules, you can’t get locking and unlocking wrong. -#### The API of `Mutex<T>` +#### The API of Mutex<T> As an example of how to use a mutex, let’s start by using a mutex in a -single-threaded context, as shown in Listing 16-12: +single-threaded context, as shown in Listing 16-12. Filename: src/main.rs @@ -891,14 +849,14 @@ Filename: src/main.rs use std::sync::Mutex; fn main() { - [1] let m = Mutex::new(5); + 1 let m = Mutex::new(5); { - [2] let mut num = m.lock().unwrap(); - [3] *num = 6; - [4] } + 2 let mut num = m.lock().unwrap(); + 3 *num = 6; + 4 } - [5] println!("m = {:?}", m); + 5 println!("m = {:?}", m); } ``` @@ -928,19 +886,19 @@ pointer implements `Deref` to point at our inner data; the smart pointer also has a `Drop` implementation that releases the lock automatically when a `MutexGuard` goes out of scope, which happens at the end of the inner scope [4]. As a result, we don’t risk forgetting to release the lock and blocking the -mutex from being used by other threads, because the lock release happens +mutex from being used by other threads because the lock release happens automatically. After dropping the lock, we can print the mutex value and see that we were able -to change the inner `i32` to 6 [5]. +to change the inner `i32` to `6` [5]. -#### Sharing a `Mutex<T>` Between Multiple Threads +#### Sharing a Mutex<T> Between Multiple Threads -Now, let’s try to share a value between multiple threads using `Mutex<T>`. -We’ll spin up 10 threads and have them each increment a counter value by 1, so -the counter goes from 0 to 10. The next example in Listing 16-13 will have -a compiler error, and we’ll use that error to learn more about using -`Mutex<T>` and how Rust helps us use it correctly. +Now let’s try to share a value between multiple threads using `Mutex<T>`. We’ll +spin up 10 threads and have them each increment a counter value by 1, so the +counter goes from 0 to 10. The example in Listing 16-13 will have a compiler +error, and we’ll use that error to learn more about using `Mutex<T>` and how +Rust helps us use it correctly. Filename: src/main.rs @@ -949,27 +907,27 @@ use std::sync::Mutex; use std::thread; fn main() { - [1] let counter = Mutex::new(0); + 1 let counter = Mutex::new(0); let mut handles = vec![]; - [2] for _ in 0..10 { - [3] let handle = thread::spawn(move || { - [4] let mut num = counter.lock().unwrap(); + 2 for _ in 0..10 { + 3 let handle = thread::spawn(move || { + 4 let mut num = counter.lock().unwrap(); - [5] *num += 1; + 5 *num += 1; }); - [6] handles.push(handle); + 6 handles.push(handle); } for handle in handles { - [7] handle.join().unwrap(); + 7 handle.join().unwrap(); } - [8] println!("Result: {}", *counter.lock().unwrap()); + 8 println!("Result: {}", *counter.lock().unwrap()); } ``` -Listing 16-13: Ten threads each increment a counter guarded by a `Mutex<T>` +Listing 16-13: Ten threads, each incrementing a counter guarded by a `Mutex<T>` We create a `counter` variable to hold an `i32` inside a `Mutex<T>` [1], as we did in Listing 16-12. Next, we create 10 threads by iterating over a range of @@ -991,22 +949,24 @@ error[E0382]: use of moved value: `counter` --> src/main.rs:9:36 | 5 | let counter = Mutex::new(0); - | ------- move occurs because `counter` has type `Mutex<i32>`, which does not implement the `Copy` trait + | ------- move occurs because `counter` has type `Mutex<i32>`, which +does not implement the `Copy` trait ... 9 | let handle = thread::spawn(move || { - | ^^^^^^^ value moved into closure here, in previous iteration of loop + | ^^^^^^^ value moved into closure here, +in previous iteration of loop 10 | let mut num = counter.lock().unwrap(); | ------- use occurs due to use in closure ``` The error message states that the `counter` value was moved in the previous -iteration of the loop. Rust is telling us that we can’t move the ownership -of lock `counter` into multiple threads. Let’s fix the compiler error with a +iteration of the loop. Rust is telling us that we can’t move the ownership of +lock `counter` into multiple threads. Let’s fix the compiler error with the multiple-ownership method we discussed in Chapter 15. #### Multiple Ownership with Multiple Threads -In Chapter 15, we gave a value multiple owners by using the smart pointer +In Chapter 15, we gave a value to multiple owners by using the smart pointer `Rc<T>` to create a reference counted value. Let’s do the same here and see what happens. We’ll wrap the `Mutex<T>` in `Rc<T>` in Listing 16-14 and clone the `Rc<T>` before moving ownership to the thread. @@ -1043,33 +1003,36 @@ fn main() { Listing 16-14: Attempting to use `Rc<T>` to allow multiple threads to own the `Mutex<T>` -Once again, we compile and get... different errors! The compiler is teaching us -a lot. +Once again, we compile and get… different errors! The compiler is teaching us a +lot. ``` -[1] error[E0277]: `Rc<Mutex<i32>>` cannot be sent between threads safely +error[E0277]: `Rc<Mutex<i32>>` cannot be sent between threads safely 1 --> src/main.rs:11:22 | 11 | let handle = thread::spawn(move || { | ______________________^^^^^^^^^^^^^_- | | | - | | `Rc<Mutex<i32>>` cannot be sent between threads safely + | | `Rc<Mutex<i32>>` cannot be sent between threads +safely 12 | | let mut num = counter.lock().unwrap(); 13 | | 14 | | *num += 1; 15 | | }); | |_________- within this `[closure@src/main.rs:11:36: 15:10]` | -[2] = help: within `[closure@src/main.rs:11:36: 15:10]`, the trait `Send` is not implemented for `Rc<Mutex<i32>>` - = note: required because it appears within the type `[closure@src/main.rs:11:36: 15:10]` += help: within `[closure@src/main.rs:11:36: 15:10]`, the trait `Send` is not +implemented for `Rc<Mutex<i32>>` 2 + = note: required because it appears within the type +`[closure@src/main.rs:11:36: 15:10]` note: required by a bound in `spawn` ``` Wow, that error message is very wordy! Here’s the important part to focus on: -`` `Rc<Mutex<i32>>` cannot be sent between threads safely `` [1]. The compiler -is also telling us the reason why: ``the trait `Send` is not implemented for -`Rc<Mutex<i32>>` `` [2]. We’ll talk about `Send` in the next section: it’s one -of the traits that ensures the types we use with threads are meant for use in +``Rc<Mutex<i32>>` cannot be sent between threads safely` [1]. The compiler is +also telling us the reason why: `the trait `Send` is not implemented for +`Rc<Mutex<i32>>`` [2]. We’ll talk about `Send` in the next section: it’s one of +the traits that ensures the types we use with threads are meant for use in concurrent situations. Unfortunately, `Rc<T>` is not safe to share across threads. When `Rc<T>` @@ -1081,7 +1044,7 @@ could in turn lead to memory leaks or a value being dropped before we’re done with it. What we need is a type exactly like `Rc<T>` but one that makes changes to the reference count in a thread-safe way. -#### Atomic Reference Counting with `Arc<T>` +#### Atomic Reference Counting with Arc<T> Fortunately, `Arc<T>` *is* a type like `Rc<T>` that is safe to use in concurrent situations. The *a* stands for *atomic*, meaning it’s an *atomically @@ -1100,7 +1063,7 @@ guarantees atomics provide. Let’s return to our example: `Arc<T>` and `Rc<T>` have the same API, so we fix our program by changing the `use` line, the call to `new`, and the call to -`clone`. The code in Listing 16-15 will finally compile and run: +`clone`. The code in Listing 16-15 will finally compile and run. Filename: src/main.rs @@ -1152,12 +1115,7 @@ standard library. These types provide safe, concurrent, atomic access to primitive types. We chose to use `Mutex<T>` with a primitive type for this example so we could concentrate on how `Mutex<T>` works. -<!-- Do we want to mention that for simple counters we have simpler types in -the standard library? (eg, AtomicI64 for the above) -/JT --> -<!-- Done! /Carol--> - -### Similarities Between `RefCell<T>`/`Rc<T>` and `Mutex<T>`/`Arc<T>` +### Similarities Between RefCell<T>/Rc<T> and Mutex<T>/Arc<T> You might have noticed that `counter` is immutable but we could get a mutable reference to the value inside it; this means `Mutex<T>` provides interior @@ -1180,7 +1138,7 @@ useful information. We’ll round out this chapter by talking about the `Send` and `Sync` traits and how we can use them with custom types. -## Extensible Concurrency with the `Sync` and `Send` Traits +## Extensible Concurrency with the Send and Sync Traits Interestingly, the Rust language has *very* few concurrency features. Almost every concurrency feature we’ve talked about so far in this chapter has been @@ -1189,9 +1147,9 @@ concurrency are not limited to the language or the standard library; you can write your own concurrency features or use those written by others. However, two concurrency concepts are embedded in the language: the -`std::marker` traits `Sync` and `Send`. +`std::marker` traits `Send` and `Sync` . -### Allowing Transference of Ownership Between Threads with `Send` +### Allowing Transference of Ownership Between Threads with Send The `Send` marker trait indicates that ownership of values of the type implementing `Send` can be transferred between threads. Almost every Rust type @@ -1204,15 +1162,15 @@ performance penalty. Therefore, Rust’s type system and trait bounds ensure that you can never accidentally send an `Rc<T>` value across threads unsafely. When we tried to do -this in Listing 16-14, we got the error `the trait Send is not implemented for -Rc<Mutex<i32>>`. When we switched to `Arc<T>`, which is `Send`, the code +this in Listing 16-14, we got the error `the trait `Send` is not implemented +for `Rc<Mutex<i32>>``. When we switched to `Arc<T>`, which is `Send`, the code compiled. Any type composed entirely of `Send` types is automatically marked as `Send` as well. Almost all primitive types are `Send`, aside from raw pointers, which we’ll discuss in Chapter 19. -### Allowing Access from Multiple Threads with `Sync` +### Allowing Access from Multiple Threads with Sync The `Sync` marker trait indicates that it is safe for the type implementing `Sync` to be referenced from multiple threads. In other words, any type `T` is @@ -1225,10 +1183,9 @@ The smart pointer `Rc<T>` is also not `Sync` for the same reasons that it’s no family of related `Cell<T>` types are not `Sync`. The implementation of borrow checking that `RefCell<T>` does at runtime is not thread-safe. The smart pointer `Mutex<T>` is `Sync` and can be used to share access with multiple -threads as you saw in the “Sharing a `Mutex<T>` Between Multiple -Threads†section. +threads, as you saw in “Sharing a Mutex<T> Between Multiple Threads†on page XX. -### Implementing `Send` and `Sync` Manually Is Unsafe +### Implementing Send and Sync Manually Is Unsafe Because types that are made up of `Send` and `Sync` traits are automatically also `Send` and `Sync`, we don’t have to implement those traits manually. As @@ -1239,7 +1196,7 @@ Manually implementing these traits involves implementing unsafe Rust code. We’ll talk about using unsafe Rust code in Chapter 19; for now, the important information is that building new concurrent types not made up of `Send` and `Sync` parts requires careful thought to uphold the safety guarantees. “The -Rustonomicon†at *https://doc.rust-lang.org/stable/nomicon/* has more +Rustonomicon†at *https://doc.rust-lang.org/stable/nomicon* has more information about these guarantees and how to uphold them. ## Summary @@ -1266,3 +1223,4 @@ go forth and make your programs concurrent, fearlessly! Next, we’ll talk about idiomatic ways to model problems and structure solutions as your Rust programs get bigger. In addition, we’ll discuss how Rust’s idioms relate to those you might be familiar with from object-oriented programming. + diff --git a/src/doc/book/nostarch/chapter17.md b/src/doc/book/nostarch/chapter17.md index f13b1484a..946d20a11 100644 --- a/src/doc/book/nostarch/chapter17.md +++ b/src/doc/book/nostarch/chapter17.md @@ -6,29 +6,24 @@ directory, so all fixes need to be made in `/src/`. [TOC] -# Object-Oriented Programming Features of Rust +# Object-Oriented Programming Features Object-oriented programming (OOP) is a way of modeling programs. Objects as a programmatic concept were introduced in the programming language Simula in the 1960s. Those objects influenced Alan Kay’s programming architecture in which objects pass messages to each other. To describe this architecture, he coined the term *object-oriented programming* in 1967. Many competing definitions -describe what OOP is, and by some of these definitions Rust is object-oriented, +describe what OOP is, and by some of these definitions Rust is object oriented but by others it is not. In this chapter, we’ll explore certain characteristics -that are commonly considered object-oriented and how those characteristics +that are commonly considered object oriented and how those characteristics translate to idiomatic Rust. We’ll then show you how to implement an object-oriented design pattern in Rust and discuss the trade-offs of doing so versus implementing a solution using some of Rust’s strengths instead. -<!-- Nit: we should probably use "object-oriented" throughout, rather using both -"object-oriented" and "object oriented" -/JT --> -<!-- Done! /Carol --> - ## Characteristics of Object-Oriented Languages There is no consensus in the programming community about what features a -language must have to be considered object-oriented. Rust is influenced by many +language must have to be considered object oriented. Rust is influenced by many programming paradigms, including OOP; for example, we explored the features that came from functional programming in Chapter 13. Arguably, OOP languages share certain common characteristics, namely objects, encapsulation, and @@ -38,20 +33,20 @@ Rust supports it. ### Objects Contain Data and Behavior The book *Design Patterns: Elements of Reusable Object-Oriented Software* by -Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (Addison-Wesley -Professional, 1994), colloquially referred to as *The Gang of Four* book, is a -catalog of object-oriented design patterns. It defines OOP this way: +Erich Gamma, Richard Helm, Ralph Johnson, and John Vlissides (Addison-Wesley, +1994), colloquially referred to as *The Gang of Four* book, is a catalog of +object-oriented design patterns. It defines OOP in this way: -> Object-oriented programs are made up of objects. An *object* packages both -> data and the procedures that operate on that data. The procedures are -> typically called *methods* or *operations*. +Object-oriented programs are made up of objects. An *object* packages both data +and the procedures that operate on that data. The procedures are typically +called *methods* or *operations*. -Using this definition, Rust is object-oriented: structs and enums have data, +Using this definition, Rust is object oriented: structs and enums have data, and `impl` blocks provide methods on structs and enums. Even though structs and enums with methods aren’t *called* objects, they provide the same functionality, according to the Gang of Four’s definition of objects. -### Encapsulation that Hides Implementation Details +### Encapsulation That Hides Implementation Details Another aspect commonly associated with OOP is the idea of *encapsulation*, which means that the implementation details of an object aren’t accessible to @@ -66,10 +61,10 @@ keyword to decide which modules, types, functions, and methods in our code should be public, and by default everything else is private. For example, we can define a struct `AveragedCollection` that has a field containing a vector of `i32` values. The struct can also have a field that contains the average of -the values in the vector, meaning the average doesn’t have to be computed -on demand whenever anyone needs it. In other words, `AveragedCollection` will +the values in the vector, meaning the average doesn’t have to be computed on +demand whenever anyone needs it. In other words, `AveragedCollection` will cache the calculated average for us. Listing 17-1 has the definition of the -`AveragedCollection` struct: +`AveragedCollection` struct. Filename: src/lib.rs @@ -87,7 +82,7 @@ The struct is marked `pub` so that other code can use it, but the fields within the struct remain private. This is important in this case because we want to ensure that whenever a value is added or removed from the list, the average is also updated. We do this by implementing `add`, `remove`, and `average` methods -on the struct, as shown in Listing 17-2: +on the struct, as shown in Listing 17-2. Filename: src/lib.rs @@ -120,18 +115,12 @@ impl AveragedCollection { } ``` -<!-- The above example will crash with a division by zero if you call it at -any time when it's empty. Not sure if we want to fix, but thought I'd point -it out. -/JT --> -<!-- It actually won't because f64 / 0 is NaN, not a panic /Carol --> - Listing 17-2: Implementations of the public methods `add`, `remove`, and `average` on `AveragedCollection` The public methods `add`, `remove`, and `average` are the only ways to access -or modify data in an instance of `AveragedCollection`. When an item is added -to `list` using the `add` method or removed using the `remove` method, the +or modify data in an instance of `AveragedCollection`. When an item is added to +`list` using the `add` method or removed using the `remove` method, the implementations of each call the private `update_average` method that handles updating the `average` field as well. @@ -145,15 +134,15 @@ Because we’ve encapsulated the implementation details of the struct `AveragedCollection`, we can easily change aspects, such as the data structure, in the future. For instance, we could use a `HashSet<i32>` instead of a `Vec<i32>` for the `list` field. As long as the signatures of the `add`, -`remove`, and `average` public methods stay the same, code using +`remove`, and `average` public methods stayed the same, code using `AveragedCollection` wouldn’t need to change. If we made `list` public instead, this wouldn’t necessarily be the case: `HashSet<i32>` and `Vec<i32>` have different methods for adding and removing items, so the external code would likely have to change if it were modifying `list` directly. -If encapsulation is a required aspect for a language to be considered -object-oriented, then Rust meets that requirement. The option to use `pub` or -not for different parts of code enables encapsulation of implementation details. +If encapsulation is a required aspect for a language to be considered object +oriented, then Rust meets that requirement. The option to use `pub` or not for +different parts of code enables encapsulation of implementation details. ### Inheritance as a Type System and as Code Sharing @@ -161,8 +150,8 @@ not for different parts of code enables encapsulation of implementation details. another object’s definition, thus gaining the parent object’s data and behavior without you having to define them again. -If a language must have inheritance to be an object-oriented language, then -Rust is not one. There is no way to define a struct that inherits the parent +If a language must have inheritance to be object oriented, then Rust is not +such a language. There is no way to define a struct that inherits the parent struct’s fields and method implementations without using a macro. However, if you’re used to having inheritance in your programming toolbox, you @@ -182,22 +171,6 @@ also override the default implementation of the `summarize` method when we implement the `Summary` trait, which is similar to a child class overriding the implementation of a method inherited from a parent class. -<!-- I'm a bit uncomfortable with the above. I think it's more honest to say -that Rust doesn't support inheritance unless you use a macro. Saying to use -the trait system to an OO programmer is going to leave them pretty confused, as -traits lack of the basics of inheritance: you can't use and modify state, you -have to use a surrogate type to hold the trait implementation, you can't -instantiate, and so on. - -The example that came to mind: trying to teach OO programmers who want to -build a UI library with traditional OO techniques using the trait system. -It's unfortunately not going to work very well, if at all. - -A trait's main focus is polymorphism and not inheritance. It's probably -better for folks coming from OO backgrounds if we just come out and say it, tbh. -/JT --> -<!-- I agree, and I've made some edits to the paragraphs above /Carol --> - The other reason to use inheritance relates to the type system: to enable a child type to be used in the same places as the parent type. This is also called *polymorphism*, which means that you can substitute multiple objects for @@ -206,12 +179,12 @@ each other at runtime if they share certain characteristics. > ### Polymorphism > > To many people, polymorphism is synonymous with inheritance. But it’s -> actually a more general concept that refers to code that can work with data -> of multiple types. For inheritance, those types are generally subclasses. +actually a more general concept that refers to code that can work with data of +multiple types. For inheritance, those types are generally subclasses. > > Rust instead uses generics to abstract over different possible types and -> trait bounds to impose constraints on what those types must provide. This is -> sometimes called *bounded parametric polymorphism*. +trait bounds to impose constraints on what those types must provide. This is +sometimes called *bounded parametric polymorphism*. Inheritance has recently fallen out of favor as a programming design solution in many programming languages because it’s often at risk of sharing more code @@ -223,15 +196,6 @@ apply to the subclass. In addition, some languages will only allow single inheritance (meaning a subclass can only inherit from one class), further restricting the flexibility of a program’s design. -<!-- Nit - "inherit from one class" and "single-inheritance" read a bit -differently to me. Saying you inherit from only one class almost makes it sound -like that the class you inherit from can't have a parent. Probably minor, just -made me read that sentence a couple times. -/JT --> -<!-- I've included the term "single inheritance" above (it appears that usually -it's not hyphenated) but kept what was there as an explanation in case the -reader isn't familiar. /Carol --> - For these reasons, Rust takes the different approach of using trait objects instead of inheritance. Let’s look at how trait objects enable polymorphism in Rust. @@ -239,7 +203,7 @@ Rust. ## Using Trait Objects That Allow for Values of Different Types In Chapter 8, we mentioned that one limitation of vectors is that they can -store elements of only one type. We created a workaround in Listing 8-10 where +store elements of only one type. We created a workaround in Listing 8-9 where we defined a `SpreadsheetCell` enum that had variants to hold integers, floats, and text. This meant we could store different types of data in each cell and still have a vector that represented a row of cells. This is a perfectly good @@ -257,7 +221,7 @@ some types for people to use, such as `Button` or `TextField`. In addition, instance, one programmer might add an `Image` and another might add a `SelectBox`. -We won’t implement a fully fledged GUI library for this example but will show +We won’t implement a full-fledged GUI library for this example but will show how the pieces would fit together. At the time of writing the library, we can’t know and define all the types other programmers might want to create. But we do know that `gui` needs to keep track of many values of different types, and it @@ -283,12 +247,12 @@ implementing our specified trait and a table used to look up trait methods on that type at runtime. We create a trait object by specifying some sort of pointer, such as a `&` reference or a `Box<T>` smart pointer, then the `dyn` keyword, and then specifying the relevant trait. (We’ll talk about the reason -trait objects must use a pointer in Chapter 19 in the section “Dynamically -Sized Types and the `Sized` Trait.â€) We can use trait objects in place of a -generic or concrete type. Wherever we use a trait object, Rust’s type system -will ensure at compile time that any value used in that context will implement -the trait object’s trait. Consequently, we don’t need to know all the possible -types at compile time. +trait objects must use a pointer in “Dynamically Sized Types and the Sized +Trait†on page XX.) We can use trait objects in place of a generic or concrete +type. Wherever we use a trait object, Rust’s type system will ensure at compile +time that any value used in that context will implement the trait object’s +trait. Consequently, we don’t need to know all the possible types at compile +time. We’ve mentioned that, in Rust, we refrain from calling structs and enums “objects†to distinguish them from other languages’ objects. In a struct or @@ -302,7 +266,7 @@ languages: their specific purpose is to allow abstraction across common behavior. Listing 17-3 shows how to define a trait named `Draw` with one method named -`draw`: +`draw`. Filename: src/lib.rs @@ -317,8 +281,8 @@ Listing 17-3: Definition of the `Draw` trait This syntax should look familiar from our discussions on how to define traits in Chapter 10. Next comes some new syntax: Listing 17-4 defines a struct named `Screen` that holds a vector named `components`. This vector is of type -`Box<dyn Draw>`, which is a trait object; it’s a stand-in for any type inside -a `Box` that implements the `Draw` trait. +`Box<dyn Draw>`, which is a trait object; it’s a stand-in for any type inside a +`Box` that implements the `Draw` trait. Filename: src/lib.rs @@ -332,7 +296,7 @@ Listing 17-4: Definition of the `Screen` struct with a `components` field holding a vector of trait objects that implement the `Draw` trait On the `Screen` struct, we’ll define a method named `run` that will call the -`draw` method on each of its `components`, as shown in Listing 17-5: +`draw` method on each of its `components`, as shown in Listing 17-5. Filename: src/lib.rs @@ -353,8 +317,8 @@ This works differently from defining a struct that uses a generic type parameter with trait bounds. A generic type parameter can only be substituted with one concrete type at a time, whereas trait objects allow for multiple concrete types to fill in for the trait object at runtime. For example, we -could have defined the `Screen` struct using a generic type and a trait bound -as in Listing 17-6: +could have defined the `Screen` struct using a generic type and a trait bound, +as in Listing 17-6. Filename: src/lib.rs @@ -394,7 +358,7 @@ Now we’ll add some types that implement the `Draw` trait. We’ll provide the `Button` type. Again, actually implementing a GUI library is beyond the scope of this book, so the `draw` method won’t have any useful implementation in its body. To imagine what the implementation might look like, a `Button` struct -might have fields for `width`, `height`, and `label`, as shown in Listing 17-7: +might have fields for `width`, `height`, and `label`, as shown in Listing 17-7. Filename: src/lib.rs @@ -425,8 +389,8 @@ happens when a user clicks the button. These kinds of methods won’t apply to types like `TextField`. If someone using our library decides to implement a `SelectBox` struct that has -`width`, `height`, and `options` fields, they implement the `Draw` trait on the -`SelectBox` type as well, as shown in Listing 17-8: +`width`, `height`, and `options` fields, they would implement the `Draw` trait +on the `SelectBox` type as well, as shown in Listing 17-8. Filename: src/main.rs @@ -453,7 +417,7 @@ Our library’s user can now write their `main` function to create a `Screen` instance. To the `Screen` instance, they can add a `SelectBox` and a `Button` by putting each in a `Box<T>` to become a trait object. They can then call the `run` method on the `Screen` instance, which will call `draw` on each of the -components. Listing 17-9 shows this implementation: +components. Listing 17-9 shows this implementation. Filename: src/main.rs @@ -484,12 +448,6 @@ fn main() { } ``` -<!-- I'd forgotten the UI components were in this chapter. To close on the -thought from earlier: we don't use any inheritance in our example, only -polymorphism. This probably is a vote for my earlier suggestion. -/JT --> -<!-- I indeed took the earlier suggestion. /Carol --> - Listing 17-9: Using trait objects to store values of different types that implement the same trait @@ -500,9 +458,9 @@ means it implements the `draw` method. This concept—of being concerned only with the messages a value responds to rather than the value’s concrete type—is similar to the concept of *duck -typing* in dynamically typed languages: if it walks like a duck and quacks -like a duck, then it must be a duck! In the implementation of `run` on `Screen` -in Listing 17-5, `run` doesn’t need to know what the concrete type of each +typing* in dynamically typed languages: if it walks like a duck and quacks like +a duck, then it must be a duck! In the implementation of `run` on `Screen` in +Listing 17-5, `run` doesn’t need to know what the concrete type of each component is. It doesn’t check whether a component is an instance of a `Button` or a `SelectBox`, it just calls the `draw` method on the component. By specifying `Box<dyn Draw>` as the type of the values in the `components` @@ -516,7 +474,7 @@ if a value doesn’t implement a method but we call it anyway. Rust won’t comp our code if the values don’t implement the traits that the trait objects need. For example, Listing 17-10 shows what happens if we try to create a `Screen` -with a `String` as a component: +with a `String` as a component. Filename: src/main.rs @@ -532,8 +490,8 @@ fn main() { } ``` -Listing 17-10: Attempting to use a type that doesn’t -implement the trait object’s trait +Listing 17-10: Attempting to use a type that doesn’t implement the trait +object’s trait We’ll get this error because `String` doesn’t implement the `Draw` trait: @@ -542,27 +500,28 @@ error[E0277]: the trait bound `String: Draw` is not satisfied --> src/main.rs:5:26 | 5 | components: vec![Box::new(String::from("Hi"))], - | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `Draw` is not implemented for `String` + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ the trait `Draw` is +not implemented for `String` | = note: required for the cast to the object type `dyn Draw` ``` -This error lets us know that either we’re passing something to `Screen` we -didn’t mean to pass and so should pass a different type or we should implement +This error lets us know that either we’re passing something to `Screen` that we +didn’t mean to pass and so should pass a different type, or we should implement `Draw` on `String` so that `Screen` is able to call `draw` on it. ### Trait Objects Perform Dynamic Dispatch -Recall in the “Performance of Code Using Generics†section in Chapter 10 our -discussion on the monomorphization process performed by the compiler when we -use trait bounds on generics: the compiler generates nongeneric implementations -of functions and methods for each concrete type that we use in place of a -generic type parameter. The code that results from monomorphization is doing -*static dispatch*, which is when the compiler knows what method you’re calling -at compile time. This is opposed to *dynamic dispatch*, which is when the -compiler can’t tell at compile time which method you’re calling. In dynamic -dispatch cases, the compiler emits code that at runtime will figure out which -method to call. +Recall in “Performance of Code Using Generics†on page XX our discussion on the +monomorphization process performed by the compiler when we use trait bounds on +generics: the compiler generates nongeneric implementations of functions and +methods for each concrete type that we use in place of a generic type +parameter. The code that results from monomorphization is doing *static +dispatch*, which is when the compiler knows what method you’re calling at +compile time. This is opposed to *dynamic dispatch*, which is when the compiler +can’t tell at compile time which method you’re calling. In dynamic dispatch +cases, the compiler emits code that at runtime will figure out which method to +call. When we use trait objects, Rust must use dynamic dispatch. The compiler doesn’t know all the types that might be used with the code that’s using trait objects, @@ -581,26 +540,13 @@ pattern is that we define a set of states a value can have internally. The states are represented by a set of *state objects*, and the value’s behavior changes based on its state. We’re going to work through an example of a blog post struct that has a field to hold its state, which will be a state object -from the set "draft", "review", or "published". -<!-- can you give a quick example here, something we could visualize? are we -saying "we define a set of states a value can have as state objects...."? /LC ---> -<!-- What do you think about this, hinting at the coming example quickly? It -felt weird to introduce something different only to switch gears in a few -paragraphs, so is moving the example's introduction here ok? /Carol --> -<!-- JT, what do you think? /LC --> -<!-- Seems okay. My one thought coming to the end of the paragraph was "is -this better than using an enum?" Not sure if we want to sidebar a bit on -why we chose traits over enums, but some readers might be curious. -/JT --> -<!-- I've added a box later titled "Why Not An Enum?" to address this -- I -think that makes a nice exercise for the reader :) /Carol --> - -The state objects share functionality: in Rust, of course, we use -structs and traits rather than objects and inheritance. Each state object is -responsible for its own behavior and for governing when it should change into -another state. The value that holds a state object knows nothing about the -different behavior of the states or when to transition between states. +from the set “draft,†“review,†or “published.†+ +The state objects share functionality: in Rust, of course, we use structs and +traits rather than objects and inheritance. Each state object is responsible +for its own behavior and for governing when it should change into another +state. The value that holds a state object knows nothing about the different +behavior of the states or when to transition between states. The advantage of using the state pattern is that, when the business requirements of the program change, we won’t need to change the code of the @@ -608,18 +554,18 @@ value holding the state or the code that uses the value. We’ll only need to update the code inside one of the state objects to change its rules or perhaps add more state objects. -First, we’re going to implement the state pattern in a more traditional +First we’re going to implement the state pattern in a more traditional object-oriented way, then we’ll use an approach that’s a bit more natural in -Rust. Let’s dig in to incrementally implementing a blog post workflow using the +Rust. Let’s dig in to incrementally implement a blog post workflow using the state pattern. The final functionality will look like this: 1. A blog post starts as an empty draft. -2. When the draft is done, a review of the post is requested. -3. When the post is approved, it gets published. -4. Only published blog posts return content to print, so unapproved posts can’t - accidentally be published. +1. When the draft is done, a review of the post is requested. +1. When the post is approved, it gets published. +1. Only published blog posts return content to print, so unapproved posts can’t +accidentally be published. Any other changes attempted on a post should have no effect. For example, if we try to approve a draft blog post before we’ve requested a review, the post @@ -635,16 +581,16 @@ Filename: src/main.rs use blog::Post; fn main() { - [1] let mut post = Post::new(); + 1 let mut post = Post::new(); - [2] post.add_text("I ate a salad for lunch today"); - [3] assert_eq!("", post.content()); + 2 post.add_text("I ate a salad for lunch today"); + 3 assert_eq!("", post.content()); - [4] post.request_review(); - [5] assert_eq!("", post.content()); + 4 post.request_review(); + 5 assert_eq!("", post.content()); - [6] post.approve(); - [7] assert_eq!("I ate a salad for lunch today", post.content()); + 6 post.approve(); + 7 assert_eq!("I ate a salad for lunch today", post.content()); } ``` @@ -667,13 +613,13 @@ post will be returned when `content` is called [7]. Notice that the only type we’re interacting with from the crate is the `Post` type. This type will use the state pattern and will hold a value that will be one of three state objects representing the various states a post can be -in—draft, waiting for review, or published. Changing from one state to another -will be managed internally within the `Post` type. The states change in -response to the methods called by our library’s users on the `Post` instance, -but they don’t have to manage the state changes directly. Also, users can’t -make a mistake with the states, like publishing a post before it’s reviewed. +in—draft, review, or published. Changing from one state to another will be +managed internally within the `Post` type. The states change in response to the +methods called by our library’s users on the `Post` instance, but they don’t +have to manage the state changes directly. Also, users can’t make a mistake +with the states, such as publishing a post before it’s reviewed. -### Defining `Post` and Creating a New Instance in the Draft State +### Defining Post and Creating a New Instance in the Draft State Let’s get started on the implementation of the library! We know we need a public `Post` struct that holds some content, so we’ll start with the @@ -681,22 +627,6 @@ definition of the struct and an associated public `new` function to create an instance of `Post`, as shown in Listing 17-12. We’ll also make a private `State` trait that will define the behavior that all state objects for a `Post` must have. -<!-- JT, I had a few questions here about what the state objects and state -traits are doing. I'd appreciate your view on whether this all reads well with -nothing missing! /LC --> -<!-- Seems okay. If you're going to try to use a traditional OO approach in -Rust, it'll have a bit of this style. I'm glad we include something that's a -bit more Rust-y at the end of the chapter. - -What I might suggest is that we give the reader a bit of a roadmap here to say -that we're going to explore two solutions to this problem. The first, a more -traditional approach encoded into Rust, and the second, an approach that's more -natural to Rust. -/JT --> -<!-- Great idea! I've added a bit in the introduction of this section above -- -"First, we’re going to implement the state pattern in a more traditional -object-oriented way, then we’ll use an approach that’s a bit more natural in -Rust." /Carol --> Then `Post` will hold a trait object of `Box<dyn State>` inside an `Option<T>` in a private field named `state` to hold the state object. You’ll see why the @@ -713,8 +643,8 @@ pub struct Post { impl Post { pub fn new() -> Post { Post { - [1] state: Some(Box::new(Draft {})), - [2] content: String::new(), + 1 state: Some(Box::new(Draft {})), + 2 content: String::new(), } } } @@ -737,9 +667,9 @@ want a post to start in. When we create a new `Post`, we set its `state` field to a `Some` value that holds a `Box` [1]. This `Box` points to a new instance of the `Draft` struct. -This ensures whenever we create a new instance of `Post`, it will start out as -a draft. Because the `state` field of `Post` is private, there is no way to -create a `Post` in any other state! In the `Post::new` function, we set the +This ensures that whenever we create a new instance of `Post`, it will start +out as a draft. Because the `state` field of `Post` is private, there is no way +to create a `Post` in any other state! In the `Post::new` function, we set the `content` field to a new, empty `String` [2]. ### Storing the Text of the Post Content @@ -750,13 +680,13 @@ blog post. We implement this as a method, rather than exposing the `content` field as `pub`, so that later we can implement a method that will control how the `content` field’s data is read. The `add_text` method is pretty straightforward, so let’s add the implementation in Listing 17-13 to the `impl -Post` block: +Post` block. Filename: src/lib.rs ``` impl Post { - // --snip-- + --snip-- pub fn add_text(&mut self, text: &str) { self.content.push_str(text); } @@ -766,7 +696,7 @@ impl Post { Listing 17-13: Implementing the `add_text` method to add text to a post’s `content` -The `add_text` method takes a mutable reference to `self`, because we’re +The `add_text` method takes a mutable reference to `self` because we’re changing the `Post` instance that we’re calling `add_text` on. We then call `push_str` on the `String` in `content` and pass the `text` argument to add to the saved `content`. This behavior doesn’t depend on the state the post is in, @@ -783,13 +713,13 @@ implement the `content` method with the simplest thing that will fulfill this requirement: always returning an empty string slice. We’ll change this later once we implement the ability to change a post’s state so it can be published. So far, posts can only be in the draft state, so the post content should always -be empty. Listing 17-14 shows this placeholder implementation: +be empty. Listing 17-14 shows this placeholder implementation. Filename: src/lib.rs ``` impl Post { - // --snip-- + --snip-- pub fn content(&self) -> &str { "" } @@ -802,32 +732,32 @@ Listing 17-14: Adding a placeholder implementation for the `content` method on With this added `content` method, everything in Listing 17-11 up to the line at [3] works as intended. -### Requesting a Review of the Post Changes Its State +### Requesting a Review Changes the Post’s State Next, we need to add functionality to request a review of a post, which should -change its state from `Draft` to `PendingReview`. Listing 17-15 shows this code: +change its state from `Draft` to `PendingReview`. Listing 17-15 shows this code. Filename: src/lib.rs ``` impl Post { - // --snip-- - [1] pub fn request_review(&mut self) { - [2] if let Some(s) = self.state.take() { - [3] self.state = Some(s.request_review()) + --snip-- + 1 pub fn request_review(&mut self) { + 2 if let Some(s) = self.state.take() { + 3 self.state = Some(s.request_review()) } } } trait State { - [4] fn request_review(self: Box<Self>) -> Box<dyn State>; + 4 fn request_review(self: Box<Self>) -> Box<dyn State>; } struct Draft {} impl State for Draft { fn request_review(self: Box<Self>) -> Box<dyn State> { - [5] Box::new(PendingReview {}) + 5 Box::new(PendingReview {}) } } @@ -835,7 +765,7 @@ struct PendingReview {} impl State for PendingReview { fn request_review(self: Box<Self>) -> Box<dyn State> { - [6] self + 6 self } } ``` @@ -859,7 +789,7 @@ ownership of `Box<Self>`, invalidating the old state so the state value of the To consume the old state, the `request_review` method needs to take ownership of the state value. This is where the `Option` in the `state` field of `Post` comes in: we call the `take` method to take the `Some` value out of the `state` -field and leave a `None` in its place, because Rust doesn’t let us have +field and leave a `None` in its place because Rust doesn’t let us have unpopulated fields in structs [2]. This lets us move the `state` value out of `Post` rather than borrowing it. Then we’ll set the post’s `state` value to the result of this operation. @@ -872,7 +802,7 @@ we’ve transformed it into a new state. The `request_review` method on `Draft` returns a new, boxed instance of a new `PendingReview` struct [5], which represents the state when a post is waiting for a review. The `PendingReview` struct also implements the `request_review` -method but doesn’t do any transformations. Rather, it returns itself [6], +method but doesn’t do any transformations. Rather, it returns itself [6] because when we request a review on a post already in the `PendingReview` state, it should stay in the `PendingReview` state. @@ -885,17 +815,17 @@ slice. We can now have a `Post` in the `PendingReview` state as well as in the `Draft` state, but we want the same behavior in the `PendingReview` state. Listing 17-11 now works up to the line at [5]! -### Adding `approve` to Change the Behavior of `content` +### Adding approve to Change the Behavior of content The `approve` method will be similar to the `request_review` method: it will set `state` to the value that the current state says it should have when that -state is approved, as shown in Listing 17-16: +state is approved, as shown in Listing 17-16. Filename: src/lib.rs ``` impl Post { - // --snip-- + --snip-- pub fn approve(&mut self) { if let Some(s) = self.state.take() { self.state = Some(s.approve()) @@ -911,18 +841,18 @@ trait State { struct Draft {} impl State for Draft { - // --snip-- + --snip-- fn approve(self: Box<Self>) -> Box<dyn State> { - [1] self + 1 self } } struct PendingReview {} impl State for PendingReview { - // --snip-- + --snip-- fn approve(self: Box<Self>) -> Box<dyn State> { - [2] Box::new(Published {}) + 2 Box::new(Published {}) } } @@ -949,33 +879,33 @@ Similar to the way `request_review` on `PendingReview` works, if we call the return `self` [1]. When we call `approve` on `PendingReview`, it returns a new, boxed instance of the `Published` struct [2]. The `Published` struct implements the `State` trait, and for both the `request_review` method and the `approve` -method, it returns itself, because the post should stay in the `Published` -state in those cases. +method, it returns itself because the post should stay in the `Published` state +in those cases. Now we need to update the `content` method on `Post`. We want the value returned from `content` to depend on the current state of the `Post`, so we’re going to have the `Post` delegate to a `content` method defined on its `state`, -as shown in Listing 17-17: +as shown in Listing 17-17. Filename: src/lib.rs ``` impl Post { - // --snip-- + --snip-- pub fn content(&self) -> &str { self.state.as_ref().unwrap().content(self) } - // --snip-- + --snip-- } ``` Listing 17-17: Updating the `content` method on `Post` to delegate to a `content` method on `State` -Because the goal is to keep all these rules inside the structs that implement -`State`, we call a `content` method on the value in `state` and pass the post -instance (that is, `self`) as an argument. Then we return the value that’s -returned from using the `content` method on the `state` value. +Because the goal is to keep all of these rules inside the structs that +implement `State`, we call a `content` method on the value in `state` and pass +the post instance (that is, `self`) as an argument. Then we return the value +that’s returned from using the `content` method on the `state` value. We call the `as_ref` method on the `Option` because we want a reference to the value inside the `Option` rather than ownership of the value. Because `state` @@ -983,37 +913,37 @@ is an `Option<Box<dyn State>>`, when we call `as_ref`, an `Option<&Box<dyn State>>` is returned. If we didn’t call `as_ref`, we would get an error because we can’t move `state` out of the borrowed `&self` of the function parameter. -We then call the `unwrap` method, which we know will never panic, because we +We then call the `unwrap` method, which we know will never panic because we know the methods on `Post` ensure that `state` will always contain a `Some` value when those methods are done. This is one of the cases we talked about in -the “Cases In Which You Have More Information Than the Compiler†section of -Chapter 9 when we know that a `None` value is never possible, even though the -compiler isn’t able to understand that. +“Cases in Which You Have More Information Than the Compiler†on page XX when we +know that a `None` value is never possible, even though the compiler isn’t able +to understand that. At this point, when we call `content` on the `&Box<dyn State>`, deref coercion will take effect on the `&` and the `Box` so the `content` method will ultimately be called on the type that implements the `State` trait. That means we need to add `content` to the `State` trait definition, and that is where we’ll put the logic for what content to return depending on which state we -have, as shown in Listing 17-18: +have, as shown in Listing 17-18. Filename: src/lib.rs ``` trait State { - // --snip-- + --snip-- fn content<'a>(&self, post: &'a Post) -> &'a str { - [1] "" + 1 "" } } -// --snip-- +--snip-- struct Published {} impl State for Published { - // --snip-- + --snip-- fn content<'a>(&self, post: &'a Post) -> &'a str { - [2] &post.content + 2 &post.content } } ``` @@ -1021,9 +951,9 @@ impl State for Published { Listing 17-18: Adding the `content` method to the `State` trait We add a default implementation for the `content` method that returns an empty -string slice [1]. That means we don’t need to implement `content` on the `Draft` -and `PendingReview` structs. The `Published` struct will override the `content` -method and return the value in `post.content` [2]. +string slice [1]. That means we don’t need to implement `content` on the +`Draft` and `PendingReview` structs. The `Published` struct will override the +`content` method and return the value in `post.content` [2]. Note that we need lifetime annotations on this method, as we discussed in Chapter 10. We’re taking a reference to a `post` as an argument and returning a @@ -1034,14 +964,14 @@ And we’re done—all of Listing 17-11 now works! We’ve implemented the state pattern with the rules of the blog post workflow. The logic related to the rules lives in the state objects rather than being scattered throughout `Post`. -> #### Why Not An Enum? +> ### Why Not An Enum? > > You may have been wondering why we didn’t use an `enum` with the different -> possible post states as variants. That’s certainly a possible solution, try -> it and compare the end results to see which you prefer! One disadvantage of -> using an enum is every place that checks the value of the enum will need a -> `match` expression or similar to handle every possible variant. This could -> get more repetitive than this trait object solution. +possible post states as variants. That’s certainly a possible solution; try it +and compare the end results to see which you prefer! One disadvantage of using +an enum is that every place that checks the value of the enum will need a +`match` expression or similar to handle every possible variant. This could get +more repetitive than this trait object solution. ### Trade-offs of the State Pattern @@ -1069,11 +999,11 @@ functionality. To see the simplicity of maintaining code that uses the state pattern, try a few of these suggestions: * Add a `reject` method that changes the post’s state from `PendingReview` back - to `Draft`. +to `Draft`. * Require two calls to `approve` before the state can be changed to `Published`. * Allow users to add text content only when a post is in the `Draft` state. - Hint: have the state object responsible for what might change about the - content but not responsible for modifying the `Post`. +Hint: have the state object responsible for what might change about the content +but not responsible for modifying the `Post`. One downside of the state pattern is that, because the states implement the transitions between states, some of the states are coupled to each other. If we @@ -1085,22 +1015,22 @@ another design pattern. Another downside is that we’ve duplicated some logic. To eliminate some of the duplication, we might try to make default implementations for the -`request_review` and `approve` methods on the `State` trait that return `self`; -however, this would violate object safety, because the trait doesn’t know what -the concrete `self` will be exactly. We want to be able to use `State` as a -trait object, so we need its methods to be object safe. +`request_review` and `approve` methods on the `State` trait that return `self`. +However, this wouldn’t work: when using `State` as a trait object, the trait +doesn’t know what the concrete `self` will be exactly, so the return type isn’t +known at compile time. Other duplication includes the similar implementations of the `request_review` and `approve` methods on `Post`. Both methods delegate to the implementation of the same method on the value in the `state` field of `Option` and set the new value of the `state` field to the result. If we had a lot of methods on `Post` that followed this pattern, we might consider defining a macro to eliminate the -repetition (see the “Macros†section in Chapter 19). +repetition (see “Macros†on page XX). By implementing the state pattern exactly as it’s defined for object-oriented languages, we’re not taking as full advantage of Rust’s strengths as we could. Let’s look at some changes we can make to the `blog` crate that can make -invalid states and transitions into compile time errors. +invalid states and transitions into compile-time errors. #### Encoding States and Behavior as Types @@ -1129,9 +1059,9 @@ and the ability to add text to the post’s content. But instead of having a draft posts don’t have the `content` method at all. That way, if we try to get a draft post’s content, we’ll get a compiler error telling us the method doesn’t exist. As a result, it will be impossible for us to accidentally -display draft post content in production, because that code won’t even compile. +display draft post content in production because that code won’t even compile. Listing 17-19 shows the definition of a `Post` struct and a `DraftPost` struct, -as well as methods on each: +as well as methods on each. Filename: src/lib.rs @@ -1145,19 +1075,19 @@ pub struct DraftPost { } impl Post { - [1] pub fn new() -> DraftPost { + 1 pub fn new() -> DraftPost { DraftPost { content: String::new(), } } - [2] pub fn content(&self) -> &str { + 2 pub fn content(&self) -> &str { &self.content } } impl DraftPost { - [3] pub fn add_text(&mut self, text: &str) { + 3 pub fn add_text(&mut self, text: &str) { self.content.push_str(text); } } @@ -1189,15 +1119,15 @@ So how do we get a published post? We want to enforce the rule that a draft post has to be reviewed and approved before it can be published. A post in the pending review state should still not display any content. Let’s implement these constraints by adding another struct, `PendingReviewPost`, defining the -`request_review` method on `DraftPost` to return a `PendingReviewPost`, and +`request_review` method on `DraftPost` to return a `PendingReviewPost` and defining an `approve` method on `PendingReviewPost` to return a `Post`, as -shown in Listing 17-20: +shown in Listing 17-20. Filename: src/lib.rs ``` impl DraftPost { - // --snip-- + --snip-- pub fn request_review(self) -> PendingReviewPost { PendingReviewPost { content: self.content, @@ -1240,7 +1170,7 @@ called on, so we need to add more `let post =` shadowing assignments to save the returned instances. We also can’t have the assertions about the draft and pending review posts’ contents be empty strings, nor do we need them: we can’t compile code that tries to use the content of posts in those states any longer. -The updated code in `main` is shown in Listing 17-21: +The updated code in `main` is shown in Listing 17-21. Filename: src/main.rs @@ -1287,16 +1217,17 @@ object-oriented languages don’t have. ## Summary -No matter whether or not you think Rust is an object-oriented language after +Regardless of whether you think Rust is an object-oriented language after reading this chapter, you now know that you can use trait objects to get some object-oriented features in Rust. Dynamic dispatch can give your code some flexibility in exchange for a bit of runtime performance. You can use this flexibility to implement object-oriented patterns that can help your code’s maintainability. Rust also has other features, like ownership, that object-oriented languages don’t have. An object-oriented pattern won’t always -be the best way to take advantage of Rust’s strengths, but is an available +be the best way to take advantage of Rust’s strengths, but it is an available option. Next, we’ll look at patterns, which are another of Rust’s features that enable lots of flexibility. We’ve looked at them briefly throughout the book but haven’t seen their full capability yet. Let’s go! + diff --git a/src/doc/book/nostarch/chapter18.md b/src/doc/book/nostarch/chapter18.md index 0b104dcf6..40c7f10a1 100644 --- a/src/doc/book/nostarch/chapter18.md +++ b/src/doc/book/nostarch/chapter18.md @@ -23,20 +23,6 @@ Some example patterns include `x`, `(a, 3)`, and `Some(Color::Red)`. In the contexts in which patterns are valid, these components describe the shape of data. Our program then matches values against the patterns to determine whether it has the correct shape of data to continue running a particular piece of code. -<!-- is there some generic pattern we can show as an example, early on, or -is it too dependent on where the pattern is used? /LC --> -<!-- Yeah, if a pattern is out of context, it doesn't look special. Like `3` -can be a pattern. /Carol --> -<!-- We could mention something like, "If you've written a little Rust, you've -already used patterns without knowing it. For example `let x = 3`, the `x` is -a pattern." Though looks like we use this later. - -Or, we could say, "Some example patterns include: `x`, `(a, b)`, and `Color::Red` -/JT --> -<!-- Ok, I've tried rewording this paragraph to include some examples, I do -think it's important to emphasize that these are only patterns in the contexts -patterns may exist, because without the context, there's no way to distinguish -patterns from regular values /Carol --> To use a pattern, we compare it to some value. If the pattern matches the value, we use the value parts in our code. Recall the `match` expressions in @@ -56,7 +42,7 @@ Patterns pop up in a number of places in Rust, and you’ve been using them a lo without realizing it! This section discusses all the places where patterns are valid. -### `match` Arms +### match Arms As discussed in Chapter 6, we use patterns in the arms of `match` expressions. Formally, `match` expressions are defined as the keyword `match`, a value to @@ -71,7 +57,7 @@ match VALUE { } ``` -For example, here's the `match` expression from Listing 6-5 that matches on an +For example, here’s the `match` expression from Listing 6-5 that matches on an `Option<i32>` value in the variable `x`: ``` @@ -81,7 +67,7 @@ match x { } ``` -The patterns in this `match` expression are the `None` and `Some(i)` on the +The patterns in this `match` expression are the `None` and `Some(i)` to the left of each arrow. One requirement for `match` expressions is that they need to be *exhaustive* in @@ -93,12 +79,12 @@ value can never fail and thus covers every remaining case. The particular pattern `_` will match anything, but it never binds to a variable, so it’s often used in the last match arm. The `_` pattern can be useful when you want to ignore any value not specified, for example. We’ll -cover the `_` pattern in more detail in the “Ignoring Values in a Pattern†-section later in this chapter. +cover the `_` pattern in more detail in “Ignoring Values in a Pattern†on page +XX. -### Conditional `if let` Expressions +### Conditional if let Expressions -In Chapter 6 we discussed how to use `if let` expressions mainly as a shorter +In Chapter 6, we discussed how to use `if let` expressions mainly as a shorter way to write the equivalent of a `match` that only matches one case. Optionally, `if let` can have a corresponding `else` containing code to run if the pattern in the `if let` doesn’t match. @@ -106,8 +92,8 @@ the pattern in the `if let` doesn’t match. Listing 18-1 shows that it’s also possible to mix and match `if let`, `else if`, and `else if let` expressions. Doing so gives us more flexibility than a `match` expression in which we can express only one value to compare with the -patterns. Also, Rust doesn't require that the conditions in a series of `if -let`, `else if`, `else if let` arms relate to each other. +patterns. Also, Rust doesn’t require that the conditions in a series of `if +let`, `else if`, and `else if let` arms relate to each other. The code in Listing 18-1 determines what color to make your background based on a series of checks for several conditions. For this example, we’ve created @@ -122,18 +108,20 @@ fn main() { let is_tuesday = false; let age: Result<u8, _> = "34".parse(); - [1] if let Some(color) = favorite_color { - [2] println!("Using your favorite color, {color}, as the background"); - [3] } else if is_tuesday { - [4] println!("Tuesday is green day!"); - [5]} else if let Ok(age) = age { - [6] if age > 30 { - [7] println!("Using purple as the background color"); + 1 if let Some(color) = favorite_color { + 2 println!( + "Using your favorite, {color}, as the background" + ); + 3 } else if is_tuesday { + 4 println!("Tuesday is green day!"); + 5 } else if let Ok(age) = age { + 6 if age > 30 { + 7 println!("Using purple as the background color"); } else { - [8] println!("Using orange as the background color"); + 8 println!("Using orange as the background color"); } - [9] } else { - [10] println!("Using blue as the background color"); + 9 } else { + 10 println!("Using blue as the background color"); } } ``` @@ -145,7 +133,7 @@ background [2]. If no favorite color is specified and today is Tuesday [3], the background color is green [4]. Otherwise, if the user specifies their age as a string and we can parse it as a number successfully [5], the color is either purple [7] or orange [8] depending on the value of the number [6]. If none of -these conditions apply [9], the background color is blue. +these conditions apply [9], the background color is blue [10]. This conditional structure lets us support complex requirements. With the hardcoded values we have here, this example will print `Using purple as the @@ -159,29 +147,20 @@ can’t combine these two conditions into `if let Ok(age) = age && age > 30`. Th shadowed `age` we want to compare to 30 isn’t valid until the new scope starts with the curly bracket. -<!-- Have we given them an intuition yet for why this is? I may be forgetting -something from the earlier chapters, but I wonder if we should reiterate that -when a pattern matches, the variable that gets bound is only valid for the -expression or block that follows the match. /JT --> -<!-- I don't really see a difference between saying "The shadowed `age` we want -to compare to 30 isn't valid until the new scope starts with the curly bracket" -and "when a pattern matches, the variable that gets bound is only valid for the -expression or block that follows the match"? To me, it sounds like this would -be saying the same thing twice, so I'm not going to change anything here. -/Carol --> - The downside of using `if let` expressions is that the compiler doesn’t check for exhaustiveness, whereas with `match` expressions it does. If we omitted the last `else` block [9] and therefore missed handling some cases, the compiler would not alert us to the possible logic bug. -### `while let` Conditional Loops +### while let Conditional Loops Similar in construction to `if let`, the `while let` conditional loop allows a `while` loop to run for as long as a pattern continues to match. In Listing -18-2 we code a `while let` loop that uses a vector as a stack and prints the +18-2, we code a `while let` loop that uses a vector as a stack and prints the values in the vector in the opposite order in which they were pushed. +Filename: src/main.rs + ``` let mut stack = Vec::new(); @@ -190,31 +169,33 @@ stack.push(2); stack.push(3); while let Some(top) = stack.pop() { - println!("{}", top); + println!("{top}"); } ``` Listing 18-2: Using a `while let` loop to print values for as long as `stack.pop()` returns `Some` -This example prints 3, 2, and then 1. The `pop` method takes the last element -out of the vector and returns `Some(value)`. If the vector is empty, `pop` -returns `None`. The `while` loop continues running the code in its block as -long as `pop` returns `Some`. When `pop` returns `None`, the loop stops. We can -use `while let` to pop every element off our stack. +This example prints `3`, `2`, and then `1`. The `pop` method takes the last +element out of the vector and returns `Some(value)`. If the vector is empty, +`pop` returns `None`. The `while` loop continues running the code in its block +as long as `pop` returns `Some`. When `pop` returns `None`, the loop stops. We +can use `while let` to pop every element off our stack. -### `for` Loops +### for Loops In a `for` loop, the value that directly follows the keyword `for` is a -pattern. For example, in `for x in y` the `x` is the pattern. Listing 18-3 -demonstrates how to use a pattern in a `for` loop to destructure, or break +pattern. For example, in `for x in y`, the `x` is the pattern. Listing 18-3 +demonstrates how to use a pattern in a `for` loop to *destructure*, or break apart, a tuple as part of the `for` loop. +Filename: src/main.rs + ``` let v = vec!['a', 'b', 'c']; for (index, value) in v.iter().enumerate() { - println!("{} is at index {}", value, index); + println!("{value} is at index {index}"); } ``` @@ -234,7 +215,7 @@ tuple `(0, 'a')`. When this value is matched to the pattern `(index, value)`, `index` will be `0` and `value` will be `'a'`, printing the first line of the output. -### `let` Statements +### let Statements Prior to this chapter, we had only explicitly discussed using patterns with `match` and `if let`, but in fact, we’ve used patterns in other places as well, @@ -245,7 +226,7 @@ variable assignment with `let`: let x = 5; ``` -Every time you've used a `let` statement like this you've been using patterns, +Every time you’ve used a `let` statement like this you’ve been using patterns, although you might not have realized it! More formally, a `let` statement looks like this: @@ -253,14 +234,14 @@ like this: let PATTERN = EXPRESSION; ``` -In statements like `let x = 5;` with a variable name in the `PATTERN` slot, the +In statements like `let x = 5;` with a variable name in the PATTERN slot, the variable name is just a particularly simple form of a pattern. Rust compares -the expression against the pattern and assigns any names it finds. So in the +the expression against the pattern and assigns any names it finds. So, in the `let x = 5;` example, `x` is a pattern that means “bind what matches here to the variable `x`.†Because the name `x` is the whole pattern, this pattern effectively means “bind everything to the variable `x`, whatever the value is.†-To see the pattern matching aspect of `let` more clearly, consider Listing +To see the pattern-matching aspect of `let` more clearly, consider Listing 18-4, which uses a pattern with `let` to destructure a tuple. ``` @@ -272,9 +253,9 @@ at once Here, we match a tuple against a pattern. Rust compares the value `(1, 2, 3)` to the pattern `(x, y, z)` and sees that the value matches the pattern, in that -it sees that the number of elements is the same in both, so Rust -binds `1` to `x`, `2` to `y`, and `3` to `z`. You can think of this tuple -pattern as nesting three individual variable patterns inside it. +it sees that the number of elements is the same in both, so Rust binds `1` to +`x`, `2` to `y`, and `3` to `z`. You can think of this tuple pattern as nesting +three individual variable patterns inside it. If the number of elements in the pattern doesn’t match the number of elements in the tuple, the overall type won’t match and we’ll get a compiler error. For @@ -295,7 +276,8 @@ error[E0308]: mismatched types --> src/main.rs:2:9 | 2 | let (x, y) = (1, 2, 3); - | ^^^^^^ --------- this expression has type `({integer}, {integer}, {integer})` + | ^^^^^^ --------- this expression has type `({integer}, {integer}, +{integer})` | | | expected a tuple with 3 elements, found one with 2 elements | @@ -304,9 +286,9 @@ error[E0308]: mismatched types ``` To fix the error, we could ignore one or more of the values in the tuple using -`_` or `..`, as you’ll see in the “Ignoring Values in a Pattern†section. If -the problem is that we have too many variables in the pattern, the solution is -to make the types match by removing variables so the number of variables equals +`_` or `..`, as you’ll see in “Ignoring Values in a Pattern†on page XX. If the +problem is that we have too many variables in the pattern, the solution is to +make the types match by removing variables so the number of variables equals the number of elements in the tuple. ### Function Parameters @@ -321,7 +303,7 @@ fn foo(x: i32) { } ``` -Listing 18-6: A function signature uses patterns in the parameters +Listing 18-6: A function signature using patterns in the parameters The `x` part is a pattern! As we did with `let`, we could match a tuple in a function’s arguments to the pattern. Listing 18-7 splits the values in a tuple @@ -331,7 +313,7 @@ Filename: src/main.rs ``` fn print_coordinates(&(x, y): &(i32, i32)) { - println!("Current location: ({}, {})", x, y); + println!("Current location: ({x}, {y})"); } fn main() { @@ -346,10 +328,10 @@ This code prints `Current location: (3, 5)`. The values `&(3, 5)` match the pattern `&(x, y)`, so `x` is the value `3` and `y` is the value `5`. We can also use patterns in closure parameter lists in the same way as in -function parameter lists, because closures are similar to functions, as +function parameter lists because closures are similar to functions, as discussed in Chapter 13. -At this point, you’ve seen several ways of using patterns, but patterns don’t +At this point, you’ve seen several ways to use patterns, but patterns don’t work the same in every place we can use them. In some places, the patterns must be irrefutable; in other circumstances, they can be refutable. We’ll discuss these two concepts next. @@ -365,12 +347,12 @@ a_value` because if the value in the `a_value` variable is `None` rather than `Some`, the `Some(x)` pattern will not match. Function parameters, `let` statements, and `for` loops can only accept -irrefutable patterns, because the program cannot do anything meaningful when -values don’t match. The `if let` and `while let` expressions accept -refutable and irrefutable patterns, but the compiler warns against -irrefutable patterns because by definition they’re intended to handle possible -failure: the functionality of a conditional is in its ability to perform -differently depending on success or failure. +irrefutable patterns because the program cannot do anything meaningful when +values don’t match. The `if let` and `while let` expressions accept refutable +and irrefutable patterns, but the compiler warns against irrefutable patterns +because, by definition, they’re intended to handle possible failure: the +functionality of a conditional is in its ability to perform differently +depending on success or failure. In general, you shouldn’t have to worry about the distinction between refutable and irrefutable patterns; however, you do need to be familiar with the concept @@ -380,7 +362,7 @@ using the pattern with, depending on the intended behavior of the code. Let’s look at an example of what happens when we try to use a refutable pattern where Rust requires an irrefutable pattern and vice versa. Listing 18-8 shows a -`let` statement, but for the pattern we’ve specified `Some(x)`, a refutable +`let` statement, but for the pattern, we’ve specified `Some(x)`, a refutable pattern. As you might expect, this code will not compile. ``` @@ -389,7 +371,7 @@ let Some(x) = some_option_value; Listing 18-8: Attempting to use a refutable pattern with `let` -If `some_option_value` was a `None` value, it would fail to match the pattern +If `some_option_value` were a `None` value, it would fail to match the pattern `Some(x)`, meaning the pattern is refutable. However, the `let` statement can only accept an irrefutable pattern because there is nothing valid the code can do with a `None` value. At compile time, Rust will complain that we’ve tried to @@ -402,13 +384,15 @@ error[E0005]: refutable pattern in local binding: `None` not covered 3 | let Some(x) = some_option_value; | ^^^^^^^ pattern `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: `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: the matched value is of type `Option<i32>` help: you might want to use `if let` to ignore the variant that isn't matched | -3 | if let Some(x) = some_option_value { /* */ } - | +3 | let x = if let Some(x) = some_option_value { x } else { todo!() }; + | ++++++++++ ++++++++++++++++++++++ ``` Because we didn’t cover (and couldn’t cover!) every valid value with the @@ -416,13 +400,13 @@ pattern `Some(x)`, Rust rightfully produces a compiler error. If we have a refutable pattern where an irrefutable pattern is needed, we can fix it by changing the code that uses the pattern: instead of using `let`, we -can use `if let`. Then if the pattern doesn’t match, the code will just skip +can use `if let`. Then, if the pattern doesn’t match, the code will just skip the code in the curly brackets, giving it a way to continue validly. Listing 18-9 shows how to fix the code in Listing 18-8. ``` if let Some(x) = some_option_value { - println!("{}", x); + println!("{x}"); } ``` @@ -436,7 +420,7 @@ the compiler will give a warning. ``` if let x = 5 { - println!("{}", x); + println!("{x}"); }; ``` @@ -453,7 +437,8 @@ warning: irrefutable `if let` pattern | ^^^^^^^^^ | = note: `#[warn(irrefutable_let_patterns)]` on by default - = note: this pattern will always match, so the `if let` is useless + = note: this pattern will always match, so the `if let` is +useless = help: consider replacing the `if let` with a `let` ``` @@ -469,14 +454,16 @@ patterns. ## Pattern Syntax -In this section, we gather all the syntax valid in patterns and discuss why and -when you might want to use each one. +In this section, we gather all the syntax that is valid in patterns and discuss +why and when you might want to use each one. ### Matching Literals As you saw in Chapter 6, you can match patterns against literals directly. The following code gives some examples: +Filename: src/main.rs + ``` let x = 1; @@ -488,14 +475,14 @@ match x { } ``` -This code prints `one` because the value in `x` is 1. This syntax is useful +This code prints `one` because the value in `x` is `1`. This syntax is useful when you want your code to take an action if it gets a particular concrete value. ### Matching Named Variables Named variables are irrefutable patterns that match any value, and we’ve used -them many times in the book. However, there is a complication when you use +them many times in this book. However, there is a complication when you use named variables in `match` expressions. Because `match` starts a new scope, variables declared as part of a pattern inside the `match` expression will shadow those with the same name outside the `match` construct, as is the case @@ -509,16 +496,16 @@ Filename: src/main.rs ``` fn main() { - [1] let x = Some(5); - [2] let y = 10; + 1 let x = Some(5); + 2 let y = 10; match x { - [3] Some(50) => println!("Got 50"), - [4] Some(y) => println!("Matched, y = {y}"), - [5] _ => println!("Default case, x = {:?}", x), + 3 Some(50) => println!("Got 50"), + 4 Some(y) => println!("Matched, y = {y}"), + 5 _ => println!("Default case, x = {:?}", x), } - [6] println!("at the end: x = {:?}, y = {y}", x); + 6 println!("at the end: x = {:?}, y = {y}", x); } ``` @@ -532,7 +519,7 @@ code continues. The pattern in the second match arm [4] introduces a new variable named `y` that will match any value inside a `Some` value. Because we’re in a new scope inside the `match` expression, this is a new `y` variable, not the `y` we -declared at the beginning with the value 10 [2]. This new `y` binding will +declared at the beginning with the value `10` [2]. This new `y` binding will match any value inside a `Some`, which is what we have in `x`. Therefore, this new `y` binds to the inner value of the `Some` in `x`. That value is `5`, so the expression for that arm executes and prints `Matched, y = 5`. @@ -550,8 +537,8 @@ the inner `y`. The last `println!` [6] produces `at the end: x = Some(5), y = To create a `match` expression that compares the values of the outer `x` and `y`, rather than introducing a shadowed variable, we would need to use a match -guard conditional instead. We’ll talk about match guards later in the “Extra -Conditionals with Match Guards†section. +guard conditional instead. We’ll talk about match guards in “Extra Conditionals +with Match Guards†on page XX. ### Multiple Patterns @@ -561,6 +548,8 @@ the value of `x` against the match arms, the first of which has an *or* option, meaning if the value of `x` matches either of the values in that arm, that arm’s code will run: +Filename: src/main.rs + ``` let x = 1; @@ -573,12 +562,14 @@ match x { This code prints `one or two`. -### Matching Ranges of Values with `..=` +### Matching Ranges of Values with ..= The `..=` syntax allows us to match to an inclusive range of values. In the following code, when a pattern matches any of the values within the given range, that arm will execute: +Filename: src/main.rs + ``` let x = 5; @@ -588,11 +579,11 @@ match x { } ``` -If `x` is 1, 2, 3, 4, or 5, the first arm will match. This syntax is more -convenient for multiple match values than using the `|` operator to express the -same idea; if we were to use `|` we would have to specify `1 | 2 | 3 | 4 | 5`. -Specifying a range is much shorter, especially if we want to match, say, any -number between 1 and 1,000! +If `x` is `1`, `2`, `3`, `4`, or `5`, the first arm will match. This syntax is +more convenient for multiple match values than using the `|` operator to +express the same idea; if we were to use `|`, we would have to specify `1 | 2 | +3 | 4 | 5`. Specifying a range is much shorter, especially if we want to match, +say, any number between 1 and 1,000! The compiler checks that the range isn’t empty at compile time, and because the only types for which Rust can tell if a range is empty or not are `char` and @@ -600,6 +591,8 @@ numeric values, ranges are only allowed with numeric or `char` values. Here is an example using ranges of `char` values: +Filename: src/main.rs + ``` let x = 'c'; @@ -684,7 +677,7 @@ destructure the other fields. In Listing 18-14, we have a `match` expression that separates `Point` values into three cases: points that lie directly on the `x` axis (which is true when -`y = 0`), on the `y` axis (`x = 0`), or neither. +`y = 0`), on the `y` axis (`x = 0`), or on neither axis. Filename: src/main.rs @@ -693,9 +686,11 @@ fn main() { let p = Point { x: 0, y: 7 }; match p { - Point { x, y: 0 } => println!("On the x axis at {}", x), - Point { x: 0, y } => println!("On the y axis at {}", y), - Point { x, y } => println!("On neither axis: ({}, {})", x, y), + Point { x, y: 0 } => println!("On the x axis at {x}"), + Point { x: 0, y } => println!("On the y axis at {y}"), + Point { x, y } => { + println!("On neither axis: ({x}, {y})"); + } } } ``` @@ -712,21 +707,16 @@ value of the `y` field. The third arm doesn’t specify any literals, so it matches any other `Point` and creates variables for both the `x` and `y` fields. In this example, the value `p` matches the second arm by virtue of `x` -containing a 0, so this code will print `On the y axis at 7`. +containing a `0`, so this code will print `On the y axis at 7`. Remember that a `match` expression stops checking arms once it has found the first matching pattern, so even though `Point { x: 0, y: 0}` is on the `x` axis and the `y` axis, this code would only print `On the x axis at 0`. -<!-- We should remind them that we stop at the first pattern, so even though -0,0 is on both x- and y-axis in a sense, you'll only ever see the "on x-axis -message" /JT --> -<!-- Done! /Carol --> - #### Destructuring Enums -We've destructured enums in this book (for example, Listing 6-5 in Chapter 6), -but haven’t yet explicitly discussed that the pattern to destructure an enum +We’ve destructured enums in this book (for example, Listing 6-5), but we +haven’t yet explicitly discussed that the pattern to destructure an enum corresponds to the way the data stored within the enum is defined. As an example, in Listing 18-15 we use the `Message` enum from Listing 6-2 and write a `match` with patterns that will destructure each inner value. @@ -742,22 +732,24 @@ enum Message { } fn main() { - [1] let msg = Message::ChangeColor(0, 160, 255); + 1 let msg = Message::ChangeColor(0, 160, 255); match msg { - [2] Message::Quit => { - println!("The Quit variant has no data to destructure.") + 2 Message::Quit => { + println!( + "The Quit variant has no data to destructure." + ); } - [3] Message::Move { x, y } => { + 3 Message::Move { x, y } => { println!( - "Move in the x direction {} and in the y direction {}", - x, y + "Move in the x dir {x}, in the y dir {y}" ); } - [4] Message::Write(text) => println!("Text message: {}", text), - [5] Message::ChangeColor(r, g, b) => println!( - "Change the color to red {}, green {}, and blue {}", - r, g, b + 4 Message::Write(text) => { + println!("Text message: {text}"); + } + 5 Message::ChangeColor(r, g, b) => println!( + "Change color to red {r}, green {g}, and blue {b}" ), } } @@ -765,7 +757,7 @@ fn main() { Listing 18-15: Destructuring enum variants that hold different kinds of values -This code will print `Change the color to red 0, green 160, and blue 255`. Try +This code will print `Change color to red 0, green 160, and blue 255`. Try changing the value of `msg` [1] to see the code from the other arms run. For enum variants without any data, like `Message::Quit` [2], we can’t @@ -791,6 +783,8 @@ but matching can work on nested items too! For example, we can refactor the code in Listing 18-15 to support RGB and HSV colors in the `ChangeColor` message, as shown in Listing 18-16. +Filename: src/main.rs + ``` enum Color { Rgb(i32, i32, i32), @@ -809,12 +803,10 @@ fn main() { match msg { Message::ChangeColor(Color::Rgb(r, g, b)) => println!( - "Change the color to red {}, green {}, and blue {}", - r, g, b + "Change color to red {r}, green {g}, and blue {b}" ), Message::ChangeColor(Color::Hsv(h, s, v)) => println!( - "Change the color to hue {}, saturation {}, and value {}", - h, s, v + "Change color to hue {h}, saturation {s}, value {v}" ), _ => (), } @@ -837,7 +829,8 @@ The following example shows a complicated destructure where we nest structs and tuples inside a tuple and destructure all the primitive values out: ``` -let ((feet, inches), Point { x, y }) = ((3, 10), Point { x: 3, y: -10 }); +let ((feet, inches), Point { x, y }) = + ((3, 10), Point { x: 3, y: -10 }); ``` This code lets us break complex types into their component parts so we can use @@ -856,7 +849,7 @@ pattern (which you’ve seen), using the `_` pattern within another pattern, using a name that starts with an underscore, or using `..` to ignore remaining parts of a value. Let’s explore how and why to use each of these patterns. -#### Ignoring an Entire Value with `_` +#### An Entire Value with _ We’ve used the underscore as a wildcard pattern that will match any value but not bind to the value. This is especially useful as the last arm in a `match` @@ -867,7 +860,7 @@ Filename: src/main.rs ``` fn foo(_: i32, y: i32) { - println!("This code only uses the y parameter: {}", y); + println!("This code only uses the y parameter: {y}"); } fn main() { @@ -883,12 +876,12 @@ and will print `This code only uses the y parameter: 4`. In most cases when you no longer need a particular function parameter, you would change the signature so it doesn’t include the unused parameter. Ignoring a function parameter can be especially useful in cases when, for example, -you're implementing a trait when you need a certain type signature but the +you’re implementing a trait when you need a certain type signature but the function body in your implementation doesn’t need one of the parameters. You then avoid getting a compiler warning about unused function parameters, as you would if you used a name instead. -#### Ignoring Parts of a Value with a Nested `_` +#### Parts of a Value with a Nested _ We can also use `_` inside another pattern to ignore just part of a value, for example, when we want to test for only part of a value but have no use for the @@ -897,6 +890,8 @@ responsible for managing a setting’s value. The business requirements are that the user should not be allowed to overwrite an existing customization of a setting but can unset the setting and give it a value if it is currently unset. +Filename: src/main.rs + ``` let mut setting_value = Some(5); let new_setting_value = Some(10); @@ -923,30 +918,32 @@ when `setting_value` and `new_setting_value` are the `Some` variant. In that case, we print the reason for not changing `setting_value`, and it doesn’t get changed. -In all other cases (if either `setting_value` or `new_setting_value` are -`None`) expressed by the `_` pattern in the second arm, we want to allow +In all other cases (if either `setting_value` or `new_setting_value` is `None`) +expressed by the `_` pattern in the second arm, we want to allow `new_setting_value` to become `setting_value`. We can also use underscores in multiple places within one pattern to ignore particular values. Listing 18-19 shows an example of ignoring the second and fourth values in a tuple of five items. +Filename: src/main.rs + ``` let numbers = (2, 4, 8, 16, 32); match numbers { (first, _, third, _, fifth) => { - println!("Some numbers: {first}, {third}, {fifth}") + println!("Some numbers: {first}, {third}, {fifth}"); } } ``` Listing 18-19: Ignoring multiple parts of a tuple -This code will print `Some numbers: 2, 8, 32`, and the values 4 and 16 will be -ignored. +This code will print `Some numbers: 2, 8, 32`, and the values `4` and `16` will +be ignored. -#### Ignoring an Unused Variable by Starting Its Name with `_` +#### An Unused Variable by Starting Its Name with _ If you create a variable but don’t use it anywhere, Rust will usually issue a warning because an unused variable could be a bug. However, sometimes it’s @@ -965,10 +962,10 @@ fn main() { } ``` -Listing 18-20: Starting a variable name with an -underscore to avoid getting unused variable warnings +Listing 18-20: Starting a variable name with an underscore to avoid getting +unused variable warnings -Here we get a warning about not using the variable `y`, but we don’t get a +Here, we get a warning about not using the variable `y`, but we don’t get a warning about not using `_x`. Note that there is a subtle difference between using only `_` and using a name @@ -976,6 +973,8 @@ that starts with an underscore. The syntax `_x` still binds the value to the variable, whereas `_` doesn’t bind at all. To show a case where this distinction matters, Listing 18-21 will provide us with an error. +Filename: src/main.rs + ``` let s = Some(String::from("Hello!")); @@ -987,13 +986,15 @@ println!("{:?}", s); ``` Listing 18-21: An unused variable starting with an underscore still binds the -value, which might take ownership of the value +value, which might take ownership of the value. We’ll receive an error because the `s` value will still be moved into `_s`, which prevents us from using `s` again. However, using the underscore by itself doesn’t ever bind to the value. Listing 18-22 will compile without any errors because `s` doesn’t get moved into `_`. +Filename: src/main.rs + ``` let s = Some(String::from("Hello!")); @@ -1004,11 +1005,11 @@ if let Some(_) = s { println!("{:?}", s); ``` -Listing 18-22: Using an underscore does not bind the value +Listing 18-22: Using an underscore does not bind the value. This code works just fine because we never bind `s` to anything; it isn’t moved. -#### Ignoring Remaining Parts of a Value with `..` +#### Remaining Parts of a Value with .. With values that have many parts, we can use the `..` syntax to use specific parts and ignore the rest, avoiding the need to list underscores for each @@ -1018,6 +1019,8 @@ explicitly matched in the rest of the pattern. In Listing 18-23, we have a `match` expression, we want to operate only on the `x` coordinate and ignore the values in the `y` and `z` fields. +Filename: src/main.rs + ``` struct Point { x: i32, @@ -1028,7 +1031,7 @@ struct Point { let origin = Point { x: 0, y: 0, z: 0 }; match origin { - Point { x, .. } => println!("x is {}", x), + Point { x, .. } => println!("x is {x}"), } ``` @@ -1059,8 +1062,8 @@ fn main() { Listing 18-24: Matching only the first and last values in a tuple and ignoring all other values -In this code, the first and last value are matched with `first` and `last`. The -`..` will match and ignore everything in the middle. +In this code, the first and last values are matched with `first` and `last`. +The `..` will match and ignore everything in the middle. However, using `..` must be unambiguous. If it is unclear which values are intended for matching and which should be ignored, Rust will give us an error. @@ -1075,7 +1078,7 @@ fn main() { match numbers { (.., second, ..) => { - println!("Some numbers: {}", second) + println!("Some numbers: {second}"); }, } } @@ -1111,14 +1114,16 @@ useful for expressing more complex ideas than a pattern alone allows. The condition can use variables created in the pattern. Listing 18-26 shows a `match` where the first arm has the pattern `Some(x)` and also has a match -guard of `if x % 2 == 0` (which will be true if the number is even). +guard of `if x % 2 == 0` (which will be `true` if the number is even). + +Filename: src/main.rs ``` let num = Some(4); match num { - Some(x) if x % 2 == 0 => println!("The number {} is even", x), - Some(x) => println!("The number {} is odd", x), + Some(x) if x % 2 == 0 => println!("The number {x} is even"), + Some(x) => println!("The number {x} is odd"), None => (), } ``` @@ -1126,18 +1131,18 @@ match num { Listing 18-26: Adding a match guard to a pattern This example will print `The number 4 is even`. When `num` is compared to the -pattern in the first arm, it matches, because `Some(4)` matches `Some(x)`. Then +pattern in the first arm, it matches because `Some(4)` matches `Some(x)`. Then the match guard checks whether the remainder of dividing `x` by 2 is equal to 0, and because it is, the first arm is selected. If `num` had been `Some(5)` instead, the match guard in the first arm would -have been false because the remainder of 5 divided by 2 is 1, which is not +have been `false` because the remainder of 5 divided by 2 is 1, which is not equal to 0. Rust would then go to the second arm, which would match because the second arm doesn’t have a match guard and therefore matches any `Some` variant. There is no way to express the `if x % 2 == 0` condition within a pattern, so the match guard gives us the ability to express this logic. The downside of -this additional expressiveness is that the compiler doesn't try to check for +this additional expressiveness is that the compiler doesn’t try to check for exhaustiveness when match guard expressions are involved. In Listing 18-11, we mentioned that we could use match guards to solve our @@ -1185,6 +1190,8 @@ guard. The important part of this example is that the `if y` match guard applies to `4`, `5`, *and* `6`, even though it might look like `if y` only applies to `6`. +Filename: src/main.rs + ``` let x = 4; let y = false; @@ -1200,11 +1207,11 @@ Listing 18-28: Combining multiple patterns with a match guard The match condition states that the arm only matches if the value of `x` is equal to `4`, `5`, or `6` *and* if `y` is `true`. When this code runs, the pattern of the first arm matches because `x` is `4`, but the match guard `if y` -is false, so the first arm is not chosen. The code moves on to the second arm, -which does match, and this program prints `no`. The reason is that the `if` -condition applies to the whole pattern `4 | 5 | 6`, not only to the last value -`6`. In other words, the precedence of a match guard in relation to a pattern -behaves like this: +is `false`, so the first arm is not chosen. The code moves on to the second +arm, which does match, and this program prints `no`. The reason is that the +`if` condition applies to the whole pattern `4 | 5 | 6`, not just to the last +value `6`. In other words, the precedence of a match guard in relation to a +pattern behaves like this: ``` (4 | 5 | 6) if y => ... @@ -1221,15 +1228,17 @@ were applied only to the final value in the list of values specified using the `|` operator, the arm would have matched and the program would have printed `yes`. -### `@` Bindings +### @ Bindings The *at* operator `@` lets us create a variable that holds a value at the same -time as we’re testing that value for a pattern match. In Listing 18-29, we want -to test that a `Message::Hello` `id` field is within the range `3..=7`. We also +time we’re testing that value for a pattern match. In Listing 18-29, we want to +test that a `Message::Hello` `id` field is within the range `3..=7`. We also want to bind the value to the variable `id_variable` so we can use it in the code associated with the arm. We could name this variable `id`, the same as the field, but for this example we’ll use a different name. +Filename: src/main.rs + ``` enum Message { Hello { id: i32 }, @@ -1240,11 +1249,11 @@ let msg = Message::Hello { id: 5 }; match msg { Message::Hello { id: id_variable @ 3..=7, - } => println!("Found an id in range: {}", id_variable), + } => println!("Found an id in range: {id_variable}"), Message::Hello { id: 10..=12 } => { println!("Found an id in another range") } - Message::Hello { id } => println!("Found some other id: {}", id), + Message::Hello { id } => println!("Some other id: {id}"), } ``` @@ -1254,12 +1263,12 @@ This example will print `Found an id in range: 5`. By specifying `id_variable @` before the range `3..=7`, we’re capturing whatever value matched the range while also testing that the value matched the range pattern. -In the second arm, where we only have a range specified in the pattern, the code -associated with the arm doesn’t have a variable that contains the actual value -of the `id` field. The `id` field’s value could have been 10, 11, or 12, but -the code that goes with that pattern doesn’t know which it is. The pattern code -isn’t able to use the value from the `id` field, because we haven’t saved the -`id` value in a variable. +In the second arm, where we only have a range specified in the pattern, the +code associated with the arm doesn’t have a variable that contains the actual +value of the `id` field. The `id` field’s value could have been 10, 11, or 12, +but the code that goes with that pattern doesn’t know which it is. The pattern +code isn’t able to use the value from the `id` field because we haven’t saved +the `id` value in a variable. In the last arm, where we’ve specified a variable without a range, we do have the value available to use in the arm’s code in a variable named `id`. The @@ -1280,3 +1289,4 @@ variables. We can create simple or complex patterns to suit our needs. Next, for the penultimate chapter of the book, we’ll look at some advanced aspects of a variety of Rust’s features. + diff --git a/src/doc/book/nostarch/chapter19.md b/src/doc/book/nostarch/chapter19.md index 5ef3fd7a2..410e7eb62 100644 --- a/src/doc/book/nostarch/chapter19.md +++ b/src/doc/book/nostarch/chapter19.md @@ -9,7 +9,7 @@ directory, so all fixes need to be made in `/src/`. # Advanced Features By now, you’ve learned the most commonly used parts of the Rust programming -language. Before we do one more project in Chapter 20, we’ll look at a few +language. Before we do one more project, in Chapter 20, we’ll look at a few aspects of the language you might run into every once in a while, but may not use every day. You can use this chapter as a reference for when you encounter any unknowns. The features covered here are useful in very specific situations. @@ -19,11 +19,11 @@ grasp of all the features Rust has to offer. In this chapter, we’ll cover: * Unsafe Rust: how to opt out of some of Rust’s guarantees and take - responsibility for manually upholding those guarantees +responsibility for manually upholding those guarantees * Advanced traits: associated types, default type parameters, fully qualified - syntax, supertraits, and the newtype pattern in relation to traits +syntax, supertraits, and the newtype pattern in relation to traits * Advanced types: more about the newtype pattern, type aliases, the never type, - and dynamically sized types +and dynamically sized types * Advanced functions and closures: function pointers and returning closures * Macros: ways to define code that defines more code at compile time @@ -61,30 +61,30 @@ that holds the unsafe code. You can take five actions in unsafe Rust that you can’t in safe Rust, which we call *unsafe superpowers*. Those superpowers include the ability to: -* Dereference a raw pointer -* Call an unsafe function or method -* Access or modify a mutable static variable -* Implement an unsafe trait -* Access fields of `union`s +1. Dereference a raw pointer +1. Call an unsafe function or method +1. Access or modify a mutable static variable +1. Implement an unsafe trait +1. Access fields of `union`s It’s important to understand that `unsafe` doesn’t turn off the borrow checker -or disable any other of Rust’s safety checks: if you use a reference in unsafe +or disable any of Rust’s other safety checks: if you use a reference in unsafe code, it will still be checked. The `unsafe` keyword only gives you access to these five features that are then not checked by the compiler for memory -safety. You’ll still get some degree of safety inside of an unsafe block. +safety. You’ll still get some degree of safety inside an unsafe block. In addition, `unsafe` does not mean the code inside the block is necessarily dangerous or that it will definitely have memory safety problems: the intent is that as the programmer, you’ll ensure the code inside an `unsafe` block will access memory in a valid way. -People are fallible, and mistakes will happen, but by requiring these five -unsafe operations to be inside blocks annotated with `unsafe` you’ll know that +People are fallible and mistakes will happen, but by requiring these five +unsafe operations to be inside blocks annotated with `unsafe`, you’ll know that any errors related to memory safety must be within an `unsafe` block. Keep `unsafe` blocks small; you’ll be thankful later when you investigate memory bugs. -To isolate unsafe code as much as possible, it’s best to enclose unsafe code +To isolate unsafe code as much as possible, it’s best to enclose such code within a safe abstraction and provide a safe API, which we’ll discuss later in the chapter when we examine unsafe functions and methods. Parts of the standard library are implemented as safe abstractions over unsafe code that has been @@ -98,18 +98,18 @@ some abstractions that provide a safe interface to unsafe code. ### Dereferencing a Raw Pointer -In Chapter 4, in the “Dangling References†section, we mentioned that the -compiler ensures references are always valid. Unsafe Rust has two new types -called *raw pointers* that are similar to references. As with references, raw -pointers can be immutable or mutable and are written as `*const T` and `*mut -T`, respectively. The asterisk isn’t the dereference operator; it’s part of the +In “Dangling References†on page XX, we mentioned that the compiler ensures +references are always valid. Unsafe Rust has two new types called *raw +pointers* that are similar to references. As with references, raw pointers can +be immutable or mutable and are written as `*const T` and `*mut T`, +respectively. The asterisk isn’t the dereference operator; it’s part of the type name. In the context of raw pointers, *immutable* means that the pointer can’t be directly assigned to after being dereferenced. Different from references and smart pointers, raw pointers: * Are allowed to ignore the borrowing rules by having both immutable and - mutable pointers or multiple mutable pointers to the same location +mutable pointers or multiple mutable pointers to the same location * Aren’t guaranteed to point to valid memory * Are allowed to be null * Don’t implement any automatic cleanup @@ -144,9 +144,9 @@ To demonstrate this, next we’ll create a raw pointer whose validity we can’t so certain of. Listing 19-2 shows how to create a raw pointer to an arbitrary location in memory. Trying to use arbitrary memory is undefined: there might be data at that address or there might not, the compiler might optimize the code -so there is no memory access, or the program might error with a segmentation -fault. Usually, there is no good reason to write code like this, but it is -possible. +so there is no memory access, or the program might terminate with a +segmentation fault. Usually, there is no good reason to write code like this, +but it is possible. ``` let address = 0x012345usize; @@ -176,8 +176,8 @@ Listing 19-3: Dereferencing raw pointers within an `unsafe` block Creating a pointer does no harm; it’s only when we try to access the value that it points at that we might end up dealing with an invalid value. -Note also that in Listing 19-1 and 19-3, we created `*const i32` and `*mut i32` -raw pointers that both pointed to the same memory location, where `num` is +Note also that in Listings 19-1 and 19-3, we created `*const i32` and `*mut +i32` raw pointers that both pointed to the same memory location, where `num` is stored. If we instead tried to create an immutable and a mutable reference to `num`, the code would not have compiled because Rust’s ownership rules don’t allow a mutable reference at the same time as any immutable references. With @@ -186,8 +186,8 @@ same location and change data through the mutable pointer, potentially creating a data race. Be careful! With all of these dangers, why would you ever use raw pointers? One major use -case is when interfacing with C code, as you’ll see in the next section, -“Calling an Unsafe Function or Method.†Another case is when building up safe +case is when interfacing with C code, as you’ll see in “Calling an Unsafe +Function or Method†on page XX. Another case is when building up safe abstractions that the borrow checker doesn’t understand. We’ll introduce unsafe functions and then look at an example of a safe abstraction that uses unsafe code. @@ -201,7 +201,7 @@ definition. The `unsafe` keyword in this context indicates the function has requirements we need to uphold when we call this function, because Rust can’t guarantee we’ve met these requirements. By calling an unsafe function within an `unsafe` block, we’re saying that we’ve read this function’s documentation and -take responsibility for upholding the function’s contracts. +we take responsibility for upholding the function’s contracts. Here is an unsafe function named `dangerous` that doesn’t do anything in its body: @@ -218,13 +218,15 @@ We must call the `dangerous` function within a separate `unsafe` block. If we try to call `dangerous` without the `unsafe` block, we’ll get an error: ``` -error[E0133]: call to unsafe function is unsafe and requires unsafe function or block +error[E0133]: call to unsafe function is unsafe and requires +unsafe function or block --> src/main.rs:4:5 | 4 | dangerous(); | ^^^^^^^^^^^ call to unsafe function | - = note: consult the function's documentation for information on how to avoid undefined behavior + = note: consult the function's documentation for information on +how to avoid undefined behavior ``` With the `unsafe` block, we’re asserting to Rust that we’ve read the function’s @@ -264,7 +266,10 @@ implement `split_at_mut` as a function rather than a method and only for slices of `i32` values rather than for a generic type `T`. ``` -fn split_at_mut(values: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) { +fn split_at_mut( + values: &mut [i32], + mid: usize, +) -> (&mut [i32], &mut [i32]) { let len = values.len(); assert!(mid <= len); @@ -289,12 +294,12 @@ When we try to compile the code in Listing 19-5, we’ll get an error: ``` error[E0499]: cannot borrow `*values` as mutable more than once at a time - --> src/main.rs:6:31 + --> src/main.rs:9:31 | -1 | fn split_at_mut(values: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) { - | - let's call the lifetime of this reference `'1` +2 | values: &mut [i32], + | - let's call the lifetime of this reference `'1` ... -6 | (&mut values[..mid], &mut values[mid..]) +9 | (&mut values[..mid], &mut values[mid..]) | --------------------------^^^^^^-------- | | | | | | | second mutable borrow occurs here @@ -314,16 +319,19 @@ to unsafe functions to make the implementation of `split_at_mut` work. ``` use std::slice; -fn split_at_mut(values: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) { - [1] let len = values.len(); - [2] let ptr = values.as_mut_ptr(); +fn split_at_mut( + values: &mut [i32], + mid: usize, +) -> (&mut [i32], &mut [i32]) { + 1 let len = values.len(); + 2 let ptr = values.as_mut_ptr(); - [3] assert!(mid <= len); + 3 assert!(mid <= len); - [4] unsafe { + 4 unsafe { ( - [5] slice::from_raw_parts_mut(ptr, mid), - [6] slice::from_raw_parts_mut(ptr.add(mid), len - mid), + 5 slice::from_raw_parts_mut(ptr, mid), + 6 slice::from_raw_parts_mut(ptr.add(mid), len - mid), ) } } @@ -332,13 +340,12 @@ fn split_at_mut(values: &mut [i32], mid: usize) -> (&mut [i32], &mut [i32]) { Listing 19-6: Using unsafe code in the implementation of the `split_at_mut` function - -Recall from “The Slice Type†section in Chapter 4 that a slice is a pointer to -some data and the length of the slice. We use the `len` method to get the -length of a slice [1] and the `as_mut_ptr` method to access the raw pointer of -a slice [2]. In this case, because we have a mutable slice to `i32` values, -`as_mut_ptr` returns a raw pointer with the type `*mut i32`, which we’ve stored -in the variable `ptr`. +Recall from “The Slice Type†on page XX that a slice is a pointer to some data +and the length of the slice. We use the `len` method to get the length of a +slice [1] and the `as_mut_ptr` method to access the raw pointer of a slice [2]. +In this case, because we have a mutable slice to `i32` values, `as_mut_ptr` +returns a raw pointer with the type `*mut i32`, which we’ve stored in the +variable `ptr`. We keep the assertion that the `mid` index is within the slice [3]. Then we get to the unsafe code [4]: the `slice::from_raw_parts_mut` function takes a raw @@ -350,15 +357,15 @@ we create a slice using that pointer and the remaining number of items after The function `slice::from_raw_parts_mut` is unsafe because it takes a raw pointer and must trust that this pointer is valid. The `add` method on raw -pointers is also unsafe, because it must trust that the offset location is also +pointers is also unsafe because it must trust that the offset location is also a valid pointer. Therefore, we had to put an `unsafe` block around our calls to -`slice::from_raw_parts_mut` and `add` so we could call them. By looking at -the code and by adding the assertion that `mid` must be less than or equal to +`slice::from_raw_parts_mut` and `add` so we could call them. By looking at the +code and by adding the assertion that `mid` must be less than or equal to `len`, we can tell that all the raw pointers used within the `unsafe` block will be valid pointers to data within the slice. This is an acceptable and appropriate use of `unsafe`. -Note that we don’t need to mark the resulting `split_at_mut` function as +Note that we don’t need to mark the resultant `split_at_mut` function as `unsafe`, and we can call this function from safe Rust. We’ve created a safe abstraction to the unsafe code with an implementation of the function that uses `unsafe` code in a safe way, because it creates only valid pointers from the @@ -374,7 +381,9 @@ use std::slice; let address = 0x01234usize; let r = address as *mut i32; -let values: &[i32] = unsafe { slice::from_raw_parts_mut(r, 10000) }; +let values: &[i32] = unsafe { + slice::from_raw_parts_mut(r, 10000) +}; ``` Listing 19-7: Creating a slice from an arbitrary memory location @@ -383,11 +392,11 @@ We don’t own the memory at this arbitrary location, and there is no guarantee that the slice this code creates contains valid `i32` values. Attempting to use `values` as though it’s a valid slice results in undefined behavior. -#### Using `extern` Functions to Call External Code +#### Using extern Functions to Call External Code -Sometimes, your Rust code might need to interact with code written in another +Sometimes your Rust code might need to interact with code written in another language. For this, Rust has the keyword `extern` that facilitates the creation -and use of a *Foreign Function Interface (FFI)*. An FFI is a way for a +and use of a *Foreign Function Interface* *(FFI)*, which is a way for a programming language to define functions and enable a different (foreign) programming language to call those functions. @@ -406,7 +415,10 @@ extern "C" { fn main() { unsafe { - println!("Absolute value of -3 according to C: {}", abs(-3)); + println!( + "Absolute value of -3 according to C: {}", + abs(-3) + ); } } ``` @@ -416,33 +428,25 @@ language Within the `extern "C"` block, we list the names and signatures of external functions from another language we want to call. The `"C"` part defines which -*application binary interface (ABI)* the external function uses: the ABI +*application binary interface* *(ABI)* the external function uses: the ABI defines how to call the function at the assembly level. The `"C"` ABI is the most common and follows the C programming language’s ABI. -<!-- Totally optional - but do we want to mention the other external types -that Rust supports here? Also, do we want to mention there are helper -crates for connecting to other languages, include C++? -/JT --> -<!-- I don't really want to get into the other external types or other -languages; there are other resources that cover these topics better than I -could here. /Carol --> - -> #### Calling Rust Functions from Other Languages +> ### Calling Rust Functions from Other Languages > > We can also use `extern` to create an interface that allows other languages -> to call Rust functions. Instead of an creating a whole `extern` block, we add -> the `extern` keyword and specify the ABI to use just before the `fn` keyword -> for the relevant function. We also need to add a `#[no_mangle]` annotation to -> tell the Rust compiler not to mangle the name of this function. *Mangling* is -> when a compiler changes the name we’ve given a function to a different name -> that contains more information for other parts of the compilation process to -> consume but is less human readable. Every programming language compiler -> mangles names slightly differently, so for a Rust function to be nameable by -> other languages, we must disable the Rust compiler’s name mangling. +to call Rust functions. Instead of creating a whole `extern` block, we add the +`extern` keyword and specify the ABI to use just before the `fn` keyword for +the relevant function. We also need to add a `#[no_mangle]` annotation to tell +the Rust compiler not to mangle the name of this function. *Mangling* is when a +compiler changes the name we’ve given a function to a different name that +contains more information for other parts of the compilation process to consume +but is less human readable. Every programming language compiler mangles names +slightly differently, so for a Rust function to be nameable by other languages, +we must disable the Rust compiler’s name mangling. > > In the following example, we make the `call_from_c` function accessible from -> C code, after it’s compiled to a shared library and linked from C: +C code, after it’s compiled to a shared library and linked from C: > > ``` > #[no_mangle] @@ -455,13 +459,12 @@ could here. /Carol --> ### Accessing or Modifying a Mutable Static Variable -In this book, we’ve not yet talked about *global variables*, which Rust does +In this book, we’ve not yet talked about global variables, which Rust does support but can be problematic with Rust’s ownership rules. If two threads are accessing the same mutable global variable, it can cause a data race. In Rust, global variables are called *static* variables. Listing 19-9 shows an -example declaration and use of a static variable with a string slice as a -value. +example declaration and use of a static variable with a string slice as a value. Filename: src/main.rs @@ -469,18 +472,18 @@ Filename: src/main.rs static HELLO_WORLD: &str = "Hello, world!"; fn main() { - println!("name is: {}", HELLO_WORLD); + println!("value is: {HELLO_WORLD}"); } ``` Listing 19-9: Defining and using an immutable static variable -Static variables are similar to constants, which we discussed in the -“Differences Between Variables and Constants†section in Chapter 3. The names -of static variables are in `SCREAMING_SNAKE_CASE` by convention. Static -variables can only store references with the `'static` lifetime, which means -the Rust compiler can figure out the lifetime and we aren’t required to -annotate it explicitly. Accessing an immutable static variable is safe. +Static variables are similar to constants, which we discussed in “Constants†on +page XX. The names of static variables are in `SCREAMING_SNAKE_CASE` by +convention. Static variables can only store references with the `'static` +lifetime, which means the Rust compiler can figure out the lifetime and we +aren’t required to annotate it explicitly. Accessing an immutable static +variable is safe. A subtle difference between constants and immutable static variables is that values in a static variable have a fixed address in memory. Using the value @@ -505,12 +508,12 @@ fn main() { add_to_count(3); unsafe { - println!("COUNTER: {}", COUNTER); + println!("COUNTER: {COUNTER}"); } } ``` -Listing 19-10: Reading from or writing to a mutable static variable is unsafe +Listing 19-10: Reading from or writing to a mutable static variable is unsafe. As with regular variables, we specify mutability using the `mut` keyword. Any code that reads or writes from `COUNTER` must be within an `unsafe` block. This @@ -522,7 +525,7 @@ With mutable data that is globally accessible, it’s difficult to ensure there are no data races, which is why Rust considers mutable static variables to be unsafe. Where possible, it’s preferable to use the concurrency techniques and thread-safe smart pointers we discussed in Chapter 16 so the compiler checks -that data accessed from different threads is done safely. +that data access from different threads is done safely. ### Implementing an Unsafe Trait @@ -540,8 +543,6 @@ unsafe trait Foo { unsafe impl Foo for i32 { // method implementations go here } - -fn main() {} ``` Listing 19-11: Defining and implementing an unsafe trait @@ -549,25 +550,25 @@ Listing 19-11: Defining and implementing an unsafe trait By using `unsafe impl`, we’re promising that we’ll uphold the invariants that the compiler can’t verify. -As an example, recall the `Sync` and `Send` marker traits we discussed in the -“Extensible Concurrency with the `Sync` and `Send` Traits†section in Chapter -16: the compiler implements these traits automatically if our types are -composed entirely of `Send` and `Sync` types. If we implement a type that -contains a type that is not `Send` or `Sync`, such as raw pointers, and we want -to mark that type as `Send` or `Sync`, we must use `unsafe`. Rust can’t verify -that our type upholds the guarantees that it can be safely sent across threads -or accessed from multiple threads; therefore, we need to do those checks -manually and indicate as such with `unsafe`. +As an example, recall the `Send` and `Sync` marker traits we discussed in +“Extensible Concurrency with the Send and Sync Traits†on page XX: the compiler +implements these traits automatically if our types are composed entirely of +`Send` and `Sync` types. If we implement a type that contains a type that is +not `Send` or `Sync`, such as raw pointers, and we want to mark that type as +`Send` or `Sync`, we must use `unsafe`. Rust can’t verify that our type upholds +the guarantees that it can be safely sent across threads or accessed from +multiple threads; therefore, we need to do those checks manually and indicate +as such with `unsafe`. ### Accessing Fields of a Union -The final action that works only with `unsafe` is accessing fields of a -*union*. A `union` is similar to a `struct`, but only one declared field is -used in a particular instance at one time. Unions are primarily used to -interface with unions in C code. Accessing union fields is unsafe because Rust -can’t guarantee the type of the data currently being stored in the union -instance. You can learn more about unions in the Rust Reference at -*https://doc.rust-lang.org/reference/items/unions.html*. +The final action that works only with `unsafe` is accessing fields of a union. +A `union` is similar to a `struct`, but only one declared field is used in a +particular instance at one time. Unions are primarily used to interface with +unions in C code. Accessing union fields is unsafe because Rust can’t guarantee +the type of the data currently being stored in the union instance. You can +learn more about unions in the Rust Reference at +*https://doc.rust-lang.org/reference/items/unions.html**.* ### When to Use Unsafe Code @@ -579,11 +580,11 @@ it easier to track down the source of problems when they occur. ## Advanced Traits -We first covered traits in the “Traits: Defining Shared Behavior†section of -Chapter 10, but we didn’t discuss the more advanced details. Now that you know -more about Rust, we can get into the nitty-gritty. +We first covered traits in “Traits: Defining Shared Behavior†on page XX, but +we didn’t discuss the more advanced details. Now that you know more about Rust, +we can get into the nitty-gritty. -### Specifying Placeholder Types in Trait Definitions with Associated Types +### Associated Types *Associated types* connect a type placeholder with a trait such that the trait method definitions can use these placeholder types in their signatures. The @@ -632,7 +633,7 @@ impl Iterator for Counter { type Item = u32; fn next(&mut self) -> Option<Self::Item> { - // --snip-- + --snip-- ``` This syntax seems comparable to that of generics. So why not just define the @@ -648,7 +649,7 @@ Listing 19-13: A hypothetical definition of the `Iterator` trait using generics The difference is that when using generics, as in Listing 19-13, we must annotate the types in each implementation; because we can also implement -`Iterator<String> for Counter` or any other type, we could have multiple +`Iterator<``String``> for Counter` or any other type, we could have multiple implementations of `Iterator` for `Counter`. In other words, when a trait has a generic parameter, it can be implemented for a type multiple times, changing the concrete types of the generic type parameters each time. When we use the @@ -657,29 +658,23 @@ indicate which implementation of `Iterator` we want to use. With associated types, we don’t need to annotate types because we can’t implement a trait on a type multiple times. In Listing 19-12 with the -definition that uses associated types, we can only choose what the type of -`Item` will be once, because there can only be one `impl Iterator for Counter`. -We don’t have to specify that we want an iterator of `u32` values everywhere -that we call `next` on `Counter`. +definition that uses associated types, we can choose what the type of `Item` +will be only once because there can be only one `impl Iterator for Counter`. We +don’t have to specify that we want an iterator of `u32` values everywhere we +call `next` on `Counter`. Associated types also become part of the trait’s contract: implementors of the trait must provide a type to stand in for the associated type placeholder. Associated types often have a name that describes how the type will be used, -and documenting the associated type in the API documentation is good practice. - -<!-- It also makes the type a part of the trait's contract. Not sure if -too subtle of a point, but the associated type of a trait is part of the -require things that the implementor must provide. They often also have a name -that may clue you in as to how that required type will be used. -/JT --> -<!-- Great points, I've added a small paragraph here! /Carol --> +and documenting the associated type in the API documentation is a good practice. ### Default Generic Type Parameters and Operator Overloading When we use generic type parameters, we can specify a default concrete type for the generic type. This eliminates the need for implementors of the trait to specify a concrete type if the default type works. You specify a default type -when declaring a generic type with the `<PlaceholderType=ConcreteType>` syntax. +when declaring a generic type with the `<`PlaceholderType`=`ConcreteType`>` +syntax. A great example of a situation where this technique is useful is with *operator overloading*, in which you customize the behavior of an operator (such as `+`) @@ -690,7 +685,7 @@ operators. But you can overload the operations and corresponding traits listed in `std::ops` by implementing the traits associated with the operator. For example, in Listing 19-14 we overload the `+` operator to add two `Point` instances together. We do this by implementing the `Add` trait on a `Point` -struct: +struct. Filename: src/main.rs @@ -743,7 +738,7 @@ trait Add<Rhs=Self> { This code should look generally familiar: a trait with one method and an associated type. The new part is `Rhs=Self`: this syntax is called *default -type parameters*. The `Rhs` generic type parameter (short for “right hand +type parameters*. The `Rhs` generic type parameter (short for “right-hand sideâ€) defines the type of the `rhs` parameter in the `add` method. If we don’t specify a concrete type for `Rhs` when we implement the `Add` trait, the type of `Rhs` will default to `Self`, which will be the type we’re implementing @@ -756,11 +751,11 @@ default. We have two structs, `Millimeters` and `Meters`, holding values in different units. This thin wrapping of an existing type in another struct is known as the -*newtype pattern*, which we describe in more detail in the “Using the Newtype -Pattern to Implement External Traits on External Types†section. We want to add -values in millimeters to values in meters and have the implementation of `Add` -do the conversion correctly. We can implement `Add` for `Millimeters` with -`Meters` as the `Rhs`, as shown in Listing 19-15. +*newtype pattern*, which we describe in more detail in “Using the Newtype +Pattern to Implement External Traits on External Types†on page XX. We want to +add values in millimeters to values in meters and have the implementation of +`Add` do the conversion correctly. We can implement `Add` for `Millimeters` +with `Meters` as the `Rhs`, as shown in Listing 19-15. Filename: src/lib.rs @@ -780,15 +775,15 @@ impl Add<Meters> for Millimeters { ``` Listing 19-15: Implementing the `Add` trait on `Millimeters` to add -`Millimeters` to `Meters` +`Millimeters` and `Meters` To add `Millimeters` and `Meters`, we specify `impl Add<Meters>` to set the value of the `Rhs` type parameter instead of using the default of `Self`. You’ll use default type parameters in two main ways: -* To extend a type without breaking existing code -* To allow customization in specific cases most users won’t need +1. To extend a type without breaking existing code +1. To allow customization in specific cases most users won’t need The standard library’s `Add` trait is an example of the second purpose: usually, you’ll add two like types, but the `Add` trait provides the ability to @@ -802,7 +797,7 @@ type parameter to an existing trait, you can give it a default to allow extension of the functionality of the trait without breaking the existing implementation code. -### Fully Qualified Syntax for Disambiguation: Calling Methods with the Same Name +### Disambiguating Between Methods with the Same Name Nothing in Rust prevents a trait from having a method with the same name as another trait’s method, nor does Rust prevent you from implementing both traits @@ -849,7 +844,7 @@ impl Human { Listing 19-16: Two traits are defined to have a `fly` method and are implemented on the `Human` type, and a `fly` method is implemented on `Human` -directly +directly. When we call `fly` on an instance of `Human`, the compiler defaults to calling the method that is directly implemented on the type, as shown in Listing 19-17. @@ -894,10 +889,6 @@ disambiguate. Running this code prints the following: ``` -$ cargo run - Compiling traits-example v0.1.0 (file:///projects/traits-example) - Finished dev [unoptimized + debuginfo] target(s) in 0.46s - Running `target/debug/traits-example` This is your captain speaking. Up! *waving arms furiously* @@ -909,12 +900,12 @@ trait to use based on the type of `self`. However, associated functions that are not methods don’t have a `self` parameter. When there are multiple types or traits that define non-method -functions with the same function name, Rust doesn't always know which type you -mean unless you use *fully qualified syntax*. For example, in Listing 19-19 we -create a trait for an animal shelter that wants to name all baby dogs *Spot*. -We make an `Animal` trait with an associated non-method function `baby_name`. -The `Animal` trait is implemented for the struct `Dog`, on which we also -provide an associated non-method function `baby_name` directly. +functions with the same function name, Rust doesn’t always know which type you +mean unless you use fully qualified syntax. For example, in Listing 19-19 we +create a trait for an animal shelter that wants to name all baby dogs Spot. We +make an `Animal` trait with an associated non-method function `baby_name`. The +`Animal` trait is implemented for the struct `Dog`, on which we also provide an +associated non-method function `baby_name` directly. Filename: src/main.rs @@ -984,7 +975,8 @@ error[E0283]: type annotations needed --> src/main.rs:20:43 | 20 | println!("A baby dog is called a {}", Animal::baby_name()); - | ^^^^^^^^^^^^^^^^^ cannot infer type + | ^^^^^^^^^^^^^^^^^ cannot infer +type | = note: cannot satisfy `_: Animal` ``` @@ -998,7 +990,10 @@ Filename: src/main.rs ``` fn main() { - println!("A baby dog is called a {}", <Dog as Animal>::baby_name()); + println!( + "A baby dog is called a {}", + <Dog as Animal>::baby_name() + ); } ``` @@ -1028,20 +1023,20 @@ in the program. You only need to use this more verbose syntax in cases where there are multiple implementations that use the same name and Rust needs help to identify which implementation you want to call. -### Using Supertraits to Require One Trait’s Functionality Within Another Trait +### Using Supertraits -Sometimes, you might write a trait definition that depends on another trait: -for a type to implement the first trait, you want to require that type to also +Sometimes you might write a trait definition that depends on another trait: for +a type to implement the first trait, you want to require that type to also implement the second trait. You would do this so that your trait definition can make use of the associated items of the second trait. The trait your trait definition is relying on is called a *supertrait* of your trait. For example, let’s say we want to make an `OutlinePrint` trait with an -`outline_print` method that will print a given value formatted so that it's +`outline_print` method that will print a given value formatted so that it’s framed in asterisks. That is, given a `Point` struct that implements the -standard library trait `Display` to result in `(x, y)`, when we -call `outline_print` on a `Point` instance that has `1` for `x` and `3` for -`y`, it should print the following: +standard library trait `Display` to result in `(x, y)`, when we call +`outline_print` on a `Point` instance that has `1` for `x` and `3` for `y`, it +should print the following: ``` ********** @@ -1111,7 +1106,8 @@ error[E0277]: `Point` doesn't implement `std::fmt::Display` | ^^^^^^^^^^^^ `Point` cannot be formatted with the default formatter | = help: the trait `std::fmt::Display` is not implemented for `Point` - = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead + = note: in format strings you may be able to use `{:?}` (or {:#?} for +pretty-print) instead note: required by a bound in `OutlinePrint` --> src/main.rs:3:21 | @@ -1134,24 +1130,23 @@ impl fmt::Display for Point { } ``` -Then implementing the `OutlinePrint` trait on `Point` will compile +Then, implementing the `OutlinePrint` trait on `Point` will compile successfully, and we can call `outline_print` on a `Point` instance to display it within an outline of asterisks. -### Using the Newtype Pattern to Implement External Traits on External Types - -In Chapter 10 in the “Implementing a Trait on a Type†section, we mentioned the -orphan rule that states we’re only allowed to implement a trait on a type if -either the trait or the type are local to our crate. -It’s possible to get -around this restriction using the *newtype pattern*, which involves creating a -new type in a tuple struct. (We covered tuple structs in the “Using Tuple -Structs without Named Fields to Create Different Types†section of Chapter 5.) -The tuple struct will have one field and be a thin wrapper around the type we -want to implement a trait for. Then the wrapper type is local to our crate, and -we can implement the trait on the wrapper. *Newtype* is a term that originates -from the Haskell programming language. There is no runtime performance penalty -for using this pattern, and the wrapper type is elided at compile time. +### Using the Newtype Pattern to Implement External Traits + +In “Implementing a Trait on a Type†on page XX, we mentioned the orphan rule +that states we’re only allowed to implement a trait on a type if either the +trait or the type, or both, are local to our crate. It’s possible to get around +this restriction using the *newtype pattern*, which involves creating a new +type in a tuple struct. (We covered tuple structs in “Using Tuple Structs +Without Named Fields to Create Different Types†on page XX.) The tuple struct +will have one field and be a thin wrapper around the type for which we want to +implement a trait. Then the wrapper type is local to our crate, and we can +implement the trait on the wrapper. *Newtype* is a term that originates from +the Haskell programming language. There is no runtime performance penalty for +using this pattern, and the wrapper type is elided at compile time. As an example, let’s say we want to implement `Display` on `Vec<T>`, which the orphan rule prevents us from doing directly because the `Display` trait and the @@ -1173,15 +1168,18 @@ impl fmt::Display for Wrapper { } fn main() { - let w = Wrapper(vec![String::from("hello"), String::from("world")]); - println!("w = {}", w); + let w = Wrapper(vec![ + String::from("hello"), + String::from("world"), + ]); + println!("w = {w}"); } ``` Listing 19-23: Creating a `Wrapper` type around `Vec<String>` to implement `Display` -The implementation of `Display` uses `self.0` to access the inner `Vec<T>`, +The implementation of `Display` uses `self.0` to access the inner `Vec<T>` because `Wrapper` is a tuple struct and `Vec<T>` is the item at index 0 in the tuple. Then we can use the functionality of the `Display` type on `Wrapper`. @@ -1190,9 +1188,9 @@ doesn’t have the methods of the value it’s holding. We would have to impleme all the methods of `Vec<T>` directly on `Wrapper` such that the methods delegate to `self.0`, which would allow us to treat `Wrapper` exactly like a `Vec<T>`. If we wanted the new type to have every method the inner type has, -implementing the `Deref` trait (discussed in Chapter 15 in the “Treating Smart -Pointers Like Regular References with the `Deref` Trait†section) on the -`Wrapper` to return the inner type would be a solution. If we don’t want the +implementing the `Deref` trait on the `Wrapper` to return the inner type would +be a solution (we discussed implementing the `Deref` trait in “Treating Smart +Pointers Like Regular References with Deref†on page XX). If we didn’t want the `Wrapper` type to have all the methods of the inner type—for example, to restrict the `Wrapper` type’s behavior—we would have to implement just the methods we do want manually. @@ -1210,16 +1208,15 @@ the `!` type and dynamically sized types. ### Using the Newtype Pattern for Type Safety and Abstraction -> Note: This section assumes you’ve read the earlier section “Using the -> Newtype Pattern to Implement External Traits on External -> Types.†+> Note: This section assumes you’ve read the earlier section “Using the Newtype +Pattern to Implement External Traits†on page XX. The newtype pattern is also useful for tasks beyond those we’ve discussed so far, including statically enforcing that values are never confused and indicating the units of a value. You saw an example of using newtypes to indicate units in Listing 19-15: recall that the `Millimeters` and `Meters` structs wrapped `u32` values in a newtype. If we wrote a function with a -parameter of type `Millimeters`, we couldn’t compile a program that +parameter of type `Millimeters`, we wouldn’t be able to compile a program that accidentally tried to call that function with a value of type `Meters` or a plain `u32`. @@ -1233,8 +1230,8 @@ associated with their name. Code using `People` would only interact with the public API we provide, such as a method to add a name string to the `People` collection; that code wouldn’t need to know that we assign an `i32` ID to names internally. The newtype pattern is a lightweight way to achieve encapsulation -to hide implementation details, which we discussed in the “Encapsulation that -Hides Implementation Details†section of Chapter 17. +to hide implementation details, which we discussed in “Encapsulation That Hides +Implementation Details†on page XX. ### Creating Type Synonyms with Type Aliases @@ -1246,7 +1243,7 @@ the alias `Kilometers` to `i32` like so: type Kilometers = i32; ``` -Now, the alias `Kilometers` is a *synonym* for `i32`; unlike the `Millimeters` +Now the alias `Kilometers` is a *synonym* for `i32`; unlike the `Millimeters` and `Meters` types we created in Listing 19-15, `Kilometers` is not a separate, new type. Values that have the type `Kilometers` will be treated the same as values of type `i32`: @@ -1262,20 +1259,11 @@ println!("x + y = {}", x + y); Because `Kilometers` and `i32` are the same type, we can add values of both types and we can pass `Kilometers` values to functions that take `i32` -parameters. However, using this method, we don’t get the type checking benefits +parameters. However, using this method, we don’t get the type-checking benefits that we get from the newtype pattern discussed earlier. In other words, if we mix up `Kilometers` and `i32` values somewhere, the compiler will not give us an error. -<!-- Having a few battle wounds trying to debug using this pattern, it's -definitely good to warn people that if they use type aliases to the same base -type in their program (like multiple aliases to `usize`), they're asking for -trouble as the typechecker will not help them if they mix up their types. -/JT --> -<!-- I'm not sure if JT was saying this paragraph was good or it could use more -emphasis? I've added a sentence to the end of the paragraph above in case it -was the latter /Carol --> - The main use case for type synonyms is to reduce repetition. For example, we might have a lengthy type like this: @@ -1288,14 +1276,16 @@ over the code can be tiresome and error prone. Imagine having a project full of code like that in Listing 19-24. ``` -let f: Box<dyn Fn() + Send + 'static> = Box::new(|| println!("hi")); +let f: Box<dyn Fn() + Send + 'static> = Box::new(|| { + println!("hi"); +}); fn takes_long_type(f: Box<dyn Fn() + Send + 'static>) { - // --snip-- + --snip-- } fn returns_long_type() -> Box<dyn Fn() + Send + 'static> { - // --snip-- + --snip-- } ``` @@ -1311,11 +1301,11 @@ type Thunk = Box<dyn Fn() + Send + 'static>; let f: Thunk = Box::new(|| println!("hi")); fn takes_long_type(f: Thunk) { - // --snip-- + --snip-- } fn returns_long_type() -> Thunk { - // --snip-- + --snip-- } ``` @@ -1343,7 +1333,10 @@ pub trait Write { fn flush(&mut self) -> Result<(), Error>; fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>; - fn write_fmt(&mut self, fmt: fmt::Arguments) -> Result<(), Error>; + fn write_fmt( + &mut self, + fmt: fmt::Arguments, + ) -> Result<(), Error>; } ``` @@ -1374,7 +1367,7 @@ us a consistent interface across all of `std::io`. Because it’s an alias, it†just another `Result<T, E>`, which means we can use any methods that work on `Result<T, E>` with it, as well as special syntax like the `?` operator. -### The Never Type that Never Returns +### The Never Type That Never Returns Rust has a special type named `!` that’s known in type theory lingo as the *empty type* because it has no values. We prefer to call it the *never type* @@ -1383,16 +1376,16 @@ return. Here is an example: ``` fn bar() -> ! { - // --snip-- + --snip-- } ``` This code is read as “the function `bar` returns never.†Functions that return -never are called *diverging functions*. We can’t create values of the type `!` +never are called *diverging functions*. We can’t create values of the type `!`, so `bar` can never possibly return. But what use is a type you can never create values for? Recall the code from -Listing 2-5, part of the number guessing game; we’ve reproduced a bit of it +Listing 2-5, part of the number-guessing game; we’ve reproduced a bit of it here in Listing 19-26. ``` @@ -1404,9 +1397,9 @@ let guess: u32 = match guess.trim().parse() { Listing 19-26: A `match` with an arm that ends in `continue` -At the time, we skipped over some details in this code. In Chapter 6 in “The -`match` Control Flow Operator†section, we discussed that `match` arms must all -return the same type. So, for example, the following code doesn’t work: +At the time, we skipped over some details in this code. In “The match Control +Flow Construct†on page XX, we discussed that `match` arms must all return the +same type. So, for example, the following code doesn’t work: ``` let guess = match guess.trim().parse() { @@ -1440,7 +1433,9 @@ impl<T> Option<T> { pub fn unwrap(self) -> T { match self { Some(val) => val, - None => panic!("called `Option::unwrap()` on a `None` value"), + None => panic!( + "called `Option::unwrap()` on a `None` value" + ), } } } @@ -1466,7 +1461,7 @@ Here, the loop never ends, so `!` is the value of the expression. However, this wouldn’t be true if we included a `break`, because the loop would terminate when it got to the `break`. -### Dynamically Sized Types and the `Sized` Trait +### Dynamically Sized Types and the Sized Trait Rust needs to know certain details about its types, such as how much space to allocate for a value of a particular type. This leaves one corner of its type @@ -1493,25 +1488,25 @@ storage and `s2` needs 15. This is why it’s not possible to create a variable holding a dynamically sized type. So what do we do? In this case, you already know the answer: we make the types -of `s1` and `s2` a `&str` rather than a `str`. Recall from the “String Slices†-section of Chapter 4 that the slice data structure just stores the starting -position and the length of the slice. So although a `&T` is a single value that -stores the memory address of where the `T` is located, a `&str` is *two* -values: the address of the `str` and its length. As such, we can know the size -of a `&str` value at compile time: it’s twice the length of a `usize`. That is, -we always know the size of a `&str`, no matter how long the string it refers to -is. In general, this is the way in which dynamically sized types are used in -Rust: they have an extra bit of metadata that stores the size of the dynamic +of `s1` and `s2` a `&str` rather than a `str`. Recall from “String Slices†on +page XX that the slice data structure just stores the starting position and the +length of the slice. So, although a `&T` is a single value that stores the +memory address of where the `T` is located, a `&str` is *two* values: the +address of the `str` and its length. As such, we can know the size of a `&str` +value at compile time: it’s twice the length of a `usize`. That is, we always +know the size of a `&str`, no matter how long the string it refers to is. In +general, this is the way in which dynamically sized types are used in Rust: +they have an extra bit of metadata that stores the size of the dynamic information. The golden rule of dynamically sized types is that we must always put values of dynamically sized types behind a pointer of some kind. We can combine `str` with all kinds of pointers: for example, `Box<str>` or `Rc<str>`. In fact, you’ve seen this before but with a different dynamically sized type: traits. Every trait is a dynamically sized type we can refer to by -using the name of the trait. In Chapter 17 in the “Using Trait Objects That -Allow for Values of Different Types†section, we mentioned that to use traits -as trait objects, we must put them behind a pointer, such as `&dyn Trait` or -`Box<dyn Trait>` (`Rc<dyn Trait>` would work too). +using the name of the trait. In “Using Trait Objects That Allow for Values of +Different Types†on page XX, we mentioned that to use traits as trait objects, +we must put them behind a pointer, such as `&dyn Trait` or `Box<dyn Trait>` +(`Rc<dyn Trait>` would work too). To work with DSTs, Rust provides the `Sized` trait to determine whether or not a type’s size is known at compile time. This trait is automatically implemented @@ -1521,7 +1516,7 @@ generic function definition like this: ``` fn generic<T>(t: T) { - // --snip-- + --snip-- } ``` @@ -1529,7 +1524,7 @@ is actually treated as though we had written this: ``` fn generic<T: Sized>(t: T) { - // --snip-- + --snip-- } ``` @@ -1539,7 +1534,7 @@ restriction: ``` fn generic<T: ?Sized>(t: &T) { - // --snip-- + --snip-- } ``` @@ -1564,14 +1559,14 @@ including function pointers and returning closures. We’ve talked about how to pass closures to functions; you can also pass regular functions to functions! This technique is useful when you want to pass a function you’ve already defined rather than defining a new closure. Functions -coerce to the type `fn` (with a lowercase f), not to be confused with the `Fn` -closure trait. The `fn` type is called a *function pointer*. Passing functions -with function pointers will allow you to use functions as arguments to other -functions. +coerce to the type `fn` (with a lowercase *f*), not to be confused with the +`Fn` closure trait. The `fn` type is called a *function pointer*. Passing +functions with function pointers will allow you to use functions as arguments +to other functions. 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 +`add_one` that adds 1 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 function `f` twice, passing it the `arg` value, then adds the two function call @@ -1592,7 +1587,7 @@ fn do_twice(f: fn(i32) -> i32, arg: i32) -> i32 { fn main() { let answer = do_twice(add_one, 5); - println!("The answer is: {}", answer); + println!("The answer is: {answer}"); } ``` @@ -1619,13 +1614,15 @@ functions can accept functions as arguments, but C doesn’t have closures. As an example of where you could use either a closure defined inline or a named function, let’s look at a use of the `map` method provided by the `Iterator` -trait in the standard library. To use the `map` function to turn a -vector of numbers into a vector of strings, we could use a closure, like this: +trait in the standard library. To use the `map` function to turn a vector of +numbers into a vector of strings, we could use a closure, like this: ``` let list_of_numbers = vec![1, 2, 3]; -let list_of_strings: Vec<String> = - list_of_numbers.iter().map(|i| i.to_string()).collect(); +let list_of_strings: Vec<String> = list_of_numbers + .iter() + .map(|i| i.to_string()) + .collect(); ``` Or we could name a function as the argument to `map` instead of the closure, @@ -1633,23 +1630,25 @@ like this: ``` let list_of_numbers = vec![1, 2, 3]; -let list_of_strings: Vec<String> = - list_of_numbers.iter().map(ToString::to_string).collect(); +let list_of_strings: Vec<String> = list_of_numbers + .iter() + .map(ToString::to_string) + .collect(); ``` -Note that we must use the fully qualified syntax that we talked about earlier -in the “Advanced Traits†section because there are multiple functions available +Note that we must use the fully qualified syntax that we talked about in +“Advanced Traits†on page XX because there are multiple functions available named `to_string`. -Here, we’re using the `to_string` function defined in the -`ToString` trait, which the standard library has implemented for any type that -implements `Display`. +Here, we’re using the `to_string` function defined in the `ToString` trait, +which the standard library has implemented for any type that implements +`Display`. -Recall from the “Enum values†section of Chapter 6 that the name of each enum -variant that we define also becomes an initializer function. We can use these -initializer functions as function pointers that implement the closure traits, -which means we can specify the initializer functions as arguments for methods -that take closures, like so: +Recall from “Enum Values†on page XX that the name of each enum variant that we +define also becomes an initializer function. We can use these initializer +functions as function pointers that implement the closure traits, which means +we can specify the initializer functions as arguments for methods that take +closures, like so: ``` enum Status { @@ -1657,12 +1656,14 @@ enum Status { Stop, } -let list_of_statuses: Vec<Status> = (0u32..20).map(Status::Value).collect(); +let list_of_statuses: Vec<Status> = (0u32..20) + .map(Status::Value) + .collect(); ``` -Here we create `Status::Value` instances using each `u32` value in the range +Here, we create `Status::Value` instances using each `u32` value in the range that `map` is called on by using the initializer function of `Status::Value`. -Some people prefer this style, and some people prefer to use closures. They +Some people prefer this style and some people prefer to use closures. They compile to the same code, so use whichever style is clearer to you. ### Returning Closures @@ -1689,10 +1690,14 @@ error[E0746]: return type cannot have an unboxed trait object --> src/lib.rs:1:25 | 1 | fn returns_closure() -> dyn Fn(i32) -> i32 { - | ^^^^^^^^^^^^^^^^^^ doesn't have a size known at compile-time + | ^^^^^^^^^^^^^^^^^^ doesn't have a size known at +compile-time | - = note: for information on `impl Trait`, see <https://doc.rust-lang.org/book/ch10-02-traits.html#returning-types-that-implement-traits> -help: use `impl Fn(i32) -> i32` as the return type, as all return paths are of type `[closure@src/lib.rs:2:5: 2:14]`, which implements `Fn(i32) -> i32` + = note: for information on `impl Trait`, see +<https://doc.rust-lang.org/book/ch10-02-traits.html#returning-types-that- +implement-traits> +help: use `impl Fn(i32) -> i32` as the return type, as all return paths are of +type `[closure@src/lib.rs:2:5: 2:14]`, which implements `Fn(i32) -> i32` | 1 | fn returns_closure() -> impl Fn(i32) -> i32 { | ~~~~~~~~~~~~~~~~~~~ @@ -1708,9 +1713,8 @@ fn returns_closure() -> Box<dyn Fn(i32) -> i32> { } ``` -This code will compile just fine. For more about trait objects, refer to the -section “Using Trait Objects That Allow for Values of Different Types†in -Chapter 17. +This code will compile just fine. For more about trait objects, refer to “Using +Trait Objects That Allow for Values of Different Types†on page XX. Next, let’s look at macros! @@ -1722,10 +1726,10 @@ of features in Rust: *declarative* macros with `macro_rules!` and three kinds of *procedural* macros: * Custom `#[derive]` macros that specify code added with the `derive` attribute - used on structs and enums +used on structs and enums * Attribute-like macros that define custom attributes usable on any item * Function-like macros that look like function calls but operate on the tokens - specified as their argument +specified as their argument We’ll talk about each of these in turn, but first, let’s look at why we even need macros when we already have functions. @@ -1740,7 +1744,7 @@ macros *expand* to produce more code than the code you’ve written manually. Metaprogramming is useful for reducing the amount of code you have to write and maintain, which is also one of the roles of functions. However, macros have -some additional powers that functions don’t. +some additional powers that functions don’t have. A function signature must declare the number and type of parameters the function has. Macros, on the other hand, can take a variable number of @@ -1760,14 +1764,14 @@ Another important difference between macros and functions is that you must define macros or bring them into scope *before* you call them in a file, as opposed to functions you can define anywhere and call anywhere. -### Declarative Macros with `macro_rules!` for General Metaprogramming +### Declarative Macros with macro_rules! for General Metaprogramming The most widely used form of macros in Rust is the *declarative macro*. These are also sometimes referred to as “macros by example,†“`macro_rules!` macros,†or just plain “macros.†At their core, declarative macros allow you to write something similar to a Rust `match` expression. As discussed in Chapter 6, `match` expressions are control structures that take an expression, compare the -resulting value of the expression to patterns, and then run the code associated +resultant value of the expression to patterns, and then run the code associated with the matching pattern. Macros also compare a value to patterns that are associated with particular code: in this situation, the value is the literal Rust source code passed to the macro; the patterns are compared with the @@ -1794,15 +1798,15 @@ Listing 19-28 shows a slightly simplified definition of the `vec!` macro. Filename: src/lib.rs ``` -[1] #[macro_export] -[2] macro_rules! vec { - [3] ( $( $x:expr ),* ) => { +1 #[macro_export] +2 macro_rules! vec { + 3 ( $( $x:expr ),* ) => { { let mut temp_vec = Vec::new(); - [4] $( - [5] temp_vec.push($x [6]); + 4 $( + 5 temp_vec.push(6 $x); )* - [7] temp_vec + 7 temp_vec } }; } @@ -1811,8 +1815,8 @@ Filename: src/lib.rs Listing 19-28: A simplified version of the `vec!` macro definition > Note: The actual definition of the `vec!` macro in the standard library -> includes code to preallocate the correct amount of memory up front. That code -> is an optimization that we don’t include here to make the example simpler. +includes code to pre-allocate the correct amount of memory up front. That code +is an optimization that we don’t include here, to make the example simpler. The `#[macro_export]` annotation [1] indicates that this macro should be made available whenever the crate in which the macro is defined is brought into @@ -1830,20 +1834,19 @@ is the only pattern in this macro, there is only one valid way to match; any other pattern will result in an error. More complex macros will have more than one arm. -Valid pattern syntax in macro definitions is different than the pattern syntax +Valid pattern syntax in macro definitions is different from the pattern syntax covered in Chapter 18 because macro patterns are matched against Rust code structure rather than values. Let’s walk through what the pattern pieces in Listing 19-28 mean; for the full macro pattern syntax, see the Rust Reference at *https://doc.rust-lang.org/reference/macros-by-example.html*. -First, we use a set of parentheses to encompass the whole pattern. We use a +First we use a set of parentheses to encompass the whole pattern. We use a dollar sign (`$`) to declare a variable in the macro system that will contain the Rust code matching the pattern. The dollar sign makes it clear this is a -macro variable as opposed to a regular Rust variable. -Next comes a set of parentheses that captures values that match the -pattern within the parentheses for use in the replacement code. Within `$()` is -`$x:expr`, which matches any Rust expression and gives the expression the name -`$x`. +macro variable as opposed to a regular Rust variable. Next comes a set of +parentheses that captures values that match the pattern within the parentheses +for use in the replacement code. Within `$()` is `$x:expr`, which matches any +Rust expression and gives the expression the name `$x`. The comma following `$()` indicates that a literal comma separator character could optionally appear after the code that matches the code in `$()`. The `*` @@ -1853,11 +1856,11 @@ When we call this macro with `vec![1, 2, 3];`, the `$x` pattern matches three times with the three expressions `1`, `2`, and `3`. Now let’s look at the pattern in the body of the code associated with this arm: -`temp_vec.push()` [5] within `$()*` [4][7] is generated for each part that -matches `$()` in the pattern zero or more times depending on how many times the -pattern matches. The `$x` [6] is replaced with each expression matched. When we -call this macro with `vec![1, 2, 3];`, the code generated that replaces this -macro call will be the following: +`temp_vec.push()` [5] within `$()* at [4] and [7] is generated for each part +that matches `$()` in the pattern zero or more times depending on how many +times the pattern matches. The `$x` [6] is replaced with each expression +matched. When we call this macro with `vec![1, 2, 3];`, the code generated that +replaces this macro call will be the following: ``` { @@ -1874,24 +1877,16 @@ generate code to create a vector containing the specified elements. To learn more about how to write macros, consult the online documentation or other resources, such as “The Little Book of Rust Macros†at -*https://veykril.github.io/tlborm/* started by Daniel Keep and continued by +*https://veykril.github.io/tlborm* started by Daniel Keep and continued by Lukas Wirth. -<!-- Not sure what "In the future, Rust will have a second kind of declarative -macro" means here. I suspect we're "stuck" with the two kinds of macros we -already have today, at least I don't see much energy in pushing to add a third -just yet. -/JT --> -<!-- Yeah, great catch, I think that part was back when we had more dreams that -have now been postponed/abandoned. I've removed. /Carol --> - ### Procedural Macros for Generating Code from Attributes -The second form of macros is the *procedural macro*, which acts more like a -function (and is a type of procedure). Procedural macros accept some code as an -input, operate on that code, and produce some code as an output rather than +The second form of macros is the procedural macro, which acts more like a +function (and is a type of procedure). *Procedural macros* accept some code as +an input, operate on that code, and produce some code as an output rather than matching against patterns and replacing the code with other code as declarative -macros do. The three kinds of procedural macros are custom derive, +macros do. The three kinds of procedural macros are custom `derive`, attribute-like, and function-like, and all work in a similar fashion. When creating procedural macros, the definitions must reside in their own crate @@ -1903,7 +1898,7 @@ macro variety. Filename: src/lib.rs ``` -use proc_macro; +use proc_macro::TokenStream; #[some_attribute] pub fn some_name(input: TokenStream) -> TokenStream { @@ -1922,20 +1917,20 @@ that specifies which kind of procedural macro we’re creating. We can have multiple kinds of procedural macros in the same crate. Let’s look at the different kinds of procedural macros. We’ll start with a -custom derive macro and then explain the small dissimilarities that make the +custom `derive` macro and then explain the small dissimilarities that make the other forms different. -### How to Write a Custom `derive` Macro +### How to Write a Custom derive Macro Let’s create a crate named `hello_macro` that defines a trait named `HelloMacro` with one associated function named `hello_macro`. Rather than making our users implement the `HelloMacro` trait for each of their types, we’ll provide a procedural macro so users can annotate their type with `#[derive(HelloMacro)]` to get a default implementation of the `hello_macro` -function. The default implementation will print `Hello, Macro! My name is -TypeName!` where `TypeName` is the name of the type on which this trait has -been defined. In other words, we’ll write a crate that enables another -programmer to write code like Listing 19-30 using our crate. +function. The default implementation will print `Hello, Macro! My name is` +TypeName`!` where TypeName is the name of the type on which this trait has been +defined. In other words, we’ll write a crate that enables another programmer to +write code like Listing 19-30 using our crate. Filename: src/main.rs @@ -2002,8 +1997,8 @@ name at runtime. We need a macro to generate code at compile time. The next step is to define the procedural macro. At the time of this writing, procedural macros need to be in their own crate. Eventually, this restriction might be lifted. The convention for structuring crates and macro crates is as -follows: for a crate named `foo`, a custom derive procedural macro crate is -called `foo_derive`. Let’s start a new crate called `hello_macro_derive` inside +follows: for a crate named foo, a custom `derive` procedural macro crate is +called foo`_derive`. Let’s start a new crate called `hello_macro_derive` inside our `hello_macro` project: ``` @@ -2095,11 +2090,11 @@ The `hello_macro_derive` function first converts the `input` from a operations on. This is where `syn` comes into play. The `parse` function in `syn` takes a `TokenStream` and returns a `DeriveInput` struct representing the parsed Rust code. Listing 19-32 shows the relevant parts of the `DeriveInput` -struct we get from parsing the `struct Pancakes;` string: +struct we get from parsing the `struct Pancakes;` string. ``` DeriveInput { - // --snip-- + --snip-- ident: Ident { ident: "Pancakes", @@ -2121,14 +2116,14 @@ Listing 19-32: The `DeriveInput` instance we get when parsing the code that has the macro’s attribute in Listing 19-30 The fields of this struct show that the Rust code we’ve parsed is a unit struct -with the `ident` (identifier, meaning the name) of `Pancakes`. There are more +with the `ident` (*identifier*, meaning the name) of `Pancakes`. There are more fields on this struct for describing all sorts of Rust code; check the `syn` documentation for `DeriveInput` at *https://docs.rs/syn/1.0/syn/struct.DeriveInput.html* for more information. Soon we’ll define the `impl_hello_macro` function, which is where we’ll build the new Rust code we want to include. But before we do, note that the output -for our derive macro is also a `TokenStream`. The returned `TokenStream` is +for our `derive` macro is also a `TokenStream`. The returned `TokenStream` is added to the code that our crate users write, so when they compile their crate, they’ll get the extra functionality that we provide in the modified `TokenStream`. @@ -2153,7 +2148,10 @@ fn impl_hello_macro(ast: &syn::DeriveInput) -> TokenStream { let gen = quote! { impl HelloMacro for #name { fn hello_macro() { - println!("Hello, Macro! My name is {}!", stringify!(#name)); + println!( + "Hello, Macro! My name is {}!", + stringify!(#name) + ); } } }; @@ -2166,7 +2164,7 @@ Listing 19-33: Implementing the `HelloMacro` trait using the parsed Rust code We get an `Ident` struct instance containing the name (identifier) of the annotated type using `ast.ident`. The struct in Listing 19-32 shows that when we run the `impl_hello_macro` function on the code in Listing 19-30, the -`ident` we get will have the `ident` field with a value of `"Pancakes"`. Thus, +`ident` we get will have the `ident` field with a value of `"Pancakes"`. Thus the `name` variable in Listing 19-33 will contain an `Ident` struct instance that, when printed, will be the string `"Pancakes"`, the name of the struct in Listing 19-30. @@ -2185,13 +2183,13 @@ introduction. We want our procedural macro to generate an implementation of our `HelloMacro` trait for the type the user annotated, which we can get by using `#name`. The -trait implementation has the one function `hello_macro`, whose body contains the -functionality we want to provide: printing `Hello, Macro! My name is` and then -the name of the annotated type. +trait implementation has the one function `hello_macro`, whose body contains +the functionality we want to provide: printing `Hello, Macro! My name is` and +then the name of the annotated type. The `stringify!` macro used here is built into Rust. It takes a Rust expression, such as `1 + 2`, and at compile time turns the expression into a -string literal, such as `"1 + 2"`. This is different than `format!` or +string literal, such as `"1 + 2"`. This is different from `format!` or `println!`, macros which evaluate the expression and then turn the result into a `String`. There is a possibility that the `#name` input might be an expression to print literally, so we use `stringify!`. Using `stringify!` also @@ -2203,7 +2201,7 @@ and `hello_macro_derive`. Let’s hook up these crates to the code in Listing your *projects* directory using `cargo new pancakes`. We need to add `hello_macro` and `hello_macro_derive` as dependencies in the `pancakes` crate’s *Cargo.toml*. If you’re publishing your versions of `hello_macro` and -`hello_macro_derive` to *https://crates.io/*, they would be regular +`hello_macro_derive` to *https://crates.io*, they would be regular dependencies; if not, you can specify them as `path` dependencies as follows: ``` @@ -2219,15 +2217,15 @@ should print `Hello, Macro! My name is Pancakes!` The implementation of the trait implementation. Next, let’s explore how the other kinds of procedural macros differ from custom -derive macros. +`derive` macros. -### Attribute-like macros +### Attribute-like Macros -Attribute-like macros are similar to custom derive macros, but instead of +Attribute-like macros are similar to custom `derive` macros, but instead of generating code for the `derive` attribute, they allow you to create new attributes. They’re also more flexible: `derive` only works for structs and enums; attributes can be applied to other items as well, such as functions. -Here’s an example of using an attribute-like macro: say you have an attribute +Here’s an example of using an attribute-like macro. Say you have an attribute named `route` that annotates functions when using a web application framework: ``` @@ -2240,7 +2238,10 @@ macro. The signature of the macro definition function would look like this: ``` #[proc_macro_attribute] -pub fn route(attr: TokenStream, item: TokenStream) -> TokenStream { +pub fn route( + attr: TokenStream, + item: TokenStream +) -> TokenStream { ``` Here, we have two parameters of type `TokenStream`. The first is for the @@ -2248,21 +2249,21 @@ contents of the attribute: the `GET, "/"` part. The second is the body of the item the attribute is attached to: in this case, `fn index() {}` and the rest of the function’s body. -Other than that, attribute-like macros work the same way as custom derive +Other than that, attribute-like macros work the same way as custom `derive` macros: you create a crate with the `proc-macro` crate type and implement a function that generates the code you want! -### Function-like macros +### Function-like Macros Function-like macros define macros that look like function calls. Similarly to `macro_rules!` macros, they’re more flexible than functions; for example, they -can take an unknown number of arguments. However, `macro_rules!` macros can be -defined only using the match-like syntax we discussed in the section -“Declarative Macros with `macro_rules!` for General Metaprogramming†earlier. -Function-like macros take a `TokenStream` parameter and their definition -manipulates that `TokenStream` using Rust code as the other two types of -procedural macros do. An example of a function-like macro is an `sql!` macro -that might be called like so: +can take an unknown number of arguments. However, `macro_rules!` macros can +only be defined using the match-like syntax we discussed in “Declarative Macros +with macro_rules! for General Metaprogramming†on page XX. Function-like macros +take a `TokenStream` parameter, and their definition manipulates that +`TokenStream` using Rust code as the other two types of procedural macros do. +An example of a function-like macro is an `sql!` macro that might be called +like so: ``` let sql = sql!(SELECT * FROM posts WHERE id=1); @@ -2277,32 +2278,19 @@ syntactically correct, which is much more complex processing than a pub fn sql(input: TokenStream) -> TokenStream { ``` -This definition is similar to the custom derive macro’s signature: we receive +This definition is similar to the custom `derive` macro’s signature: we receive the tokens that are inside the parentheses and return the code we wanted to generate. -<!-- I may get a few looks for this, but I wonder if we should trim the -procedural macros section above a bit. There's a lot of information in there, -but it feels like something we could intro and then point people off to other -materials for. Reason being (and I know I may be in the minority here), -procedural macros are something we should use only rarely in our Rust projects. -They are a burden on the compiler, have the potential to hurt readability and -maintainability, and... you know the saying with great power comes great -responsibilty and all that. /JT --> -<!-- I think we felt obligated to have this section when procedural macros were -introduced because there wasn't any documentation for them. I feel like the -custom derive is the most common kind people want to make... While I'd love to -not have to maintain this section, I asked around and people seemed generally -in favor of keeping it, so I think I will, for now. /Carol --> - ## Summary Whew! Now you have some Rust features in your toolbox that you likely won’t use often, but you’ll know they’re available in very particular circumstances. We’ve introduced several complex topics so that when you encounter them in -error message suggestions or in other peoples’ code, you’ll be able to +error message suggestions or in other people’s code, you’ll be able to recognize these concepts and syntax. Use this chapter as a reference to guide you to solutions. Next, we’ll put everything we’ve discussed throughout the book into practice and do one more project! + diff --git a/src/doc/book/nostarch/chapter20.md b/src/doc/book/nostarch/chapter20.md index e692e2f1d..9d4e22cd7 100644 --- a/src/doc/book/nostarch/chapter20.md +++ b/src/doc/book/nostarch/chapter20.md @@ -16,21 +16,19 @@ lessons. For our final project, we’ll make a web server that says “hello†and looks like Figure 20-1 in a web browser. -!hello from rust at *img/trpl20-01.png* - Figure 20-1: Our final shared project Here is our plan for building the web server: 1. Learn a bit about TCP and HTTP. -2. Listen for TCP connections on a socket. -3. Parse a small number of HTTP requests. -4. Create a proper HTTP response. -5. Improve the throughput of our server with a thread pool. +1. Listen for TCP connections on a socket. +1. Parse a small number of HTTP requests. +1. Create a proper HTTP response. +1. Improve the throughput of our server with a thread pool. Before we get started, we should mention one detail: the method we’ll use won’t be the best way to build a web server with Rust. Community members have -published a number of production-ready crates available at *https://crates.io/* +published a number of production-ready crates available at *https://crates.io* that provide more complete web server and thread pool implementations than we’ll build. However, our intention in this chapter is to help you learn, not to take the easy route. Because Rust is a systems programming language, we can @@ -81,12 +79,12 @@ Filename: src/main.rs use std::net::TcpListener; fn main() { - [1] let listener = TcpListener::bind("127.0.0.1:7878").unwrap(); + 1 let listener = TcpListener::bind("127.0.0.1:7878").unwrap(); - [2] for stream in listener.incoming() { - [3] let stream = stream.unwrap(); + 2 for stream in listener.incoming() { + 3 let stream = stream.unwrap(); - [4] println!("Connection established!"); + 4 println!("Connection established!"); } } ``` @@ -99,7 +97,7 @@ Using `TcpListener`, we can listen for TCP connections at the address address representing your computer (this is the same on every computer and doesn’t represent the authors’ computer specifically), and `7878` is the port. We’ve chosen this port for two reasons: HTTP isn’t normally accepted on this -port so our server is unlikely to conflict with any other web server you might +port, so our server is unlikely to conflict with any other web server you might have running on your machine, and 7878 is *rust* typed on a telephone. The `bind` function in this scenario works like the `new` function in that it @@ -109,7 +107,7 @@ to a port.†The `bind` function returns a `Result<T, E>`, which indicates that it’s possible for binding to fail. For example, connecting to port 80 requires -administrator privileges (nonadministrators can listen only on ports higher +administrator privileges (non-administrators can listen only on ports higher than 1023), so if we tried to connect to port 80 without being an administrator, binding wouldn’t work. Binding also wouldn’t work, for example, if we ran two instances of our program and so had two programs listening to the @@ -141,7 +139,7 @@ open connections are closed. Let’s try running this code! Invoke `cargo run` in the terminal and then load *127.0.0.1:7878* in a web browser. The browser should show an error message -like “Connection reset,†because the server isn’t currently sending back any +like “Connection reset†because the server isn’t currently sending back any data. But when you look at your terminal, you should see several messages that were printed when the browser connected to the server! @@ -152,7 +150,7 @@ Connection established! Connection established! ``` -Sometimes, you’ll see multiple messages printed for one browser request; the +Sometimes you’ll see multiple messages printed for one browser request; the reason might be that the browser is making a request for the page as well as a request for other resources, like the *favicon.ico* icon that appears in the browser tab. @@ -164,10 +162,10 @@ part of the `drop` implementation. Browsers sometimes deal with closed connections by retrying, because the problem might be temporary. The important factor is that we’ve successfully gotten a handle to a TCP connection! -Remember to stop the program by pressing <span class="keystroke">ctrl-c -when you’re done running a particular version of the code. Then restart the -program by invoking the `cargo run` command after you’ve made each set of code -changes to make sure you’re running the newest code. +Remember to stop the program by pressing ctrl-C when you’re done running a +particular version of the code. Then restart the program by invoking the `cargo +run` command after you’ve made each set of code changes to make sure you’re +running the newest code. ### Reading the Request @@ -181,7 +179,7 @@ look like Listing 20-2. Filename: src/main.rs ``` -[1] use std::{ +1 use std::{ io::{prelude::*, BufReader}, net::{TcpListener, TcpStream}, }; @@ -192,19 +190,19 @@ fn main() { for stream in listener.incoming() { let stream = stream.unwrap(); - [2] handle_connection(stream); + 2 handle_connection(stream); } } fn handle_connection(mut stream: TcpStream) { - [3] let buf_reader = BufReader::new(&mut stream); - [4] let http_request: Vec<_> = buf_reader - [5] .lines() - [6] .map(|result| result.unwrap()) - [7] .take_while(|line| !line.is_empty()) + 3 let buf_reader = BufReader::new(&mut stream); + 4 let http_request: Vec<_> = buf_reader + 5 .lines() + 6 .map(|result| result.unwrap()) + 7 .take_while(|line| !line.is_empty()) .collect(); - [8] println!("Request: {:#?}", http_request); + 8 println!("Request: {:#?}", http_request); } ``` @@ -251,8 +249,11 @@ $ cargo run Request: [ "GET / HTTP/1.1", "Host: 127.0.0.1:7878", - "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:99.0) Gecko/20100101 Firefox/99.0", - "Accept: text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8", + "User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:99.0) +Gecko/20100101 Firefox/99.0", + "Accept: +text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/* +;q=0.8", "Accept-Language: en-US,en;q=0.5", "Accept-Encoding: gzip, deflate, br", "DNT: 1", @@ -292,17 +293,17 @@ being used, such as `GET` or `POST`, which describes how the client is making this request. Our client used a `GET` request, which means it is asking for information. -The next part of the request line is */*, which indicates the *Uniform Resource -Identifier* *(URI)* the client is requesting: a URI is almost, but not quite, -the same as a *Uniform Resource Locator* *(URL)*. The difference between URIs +The next part of the request line is */*, which indicates the *uniform resource +identifier* *(URI)* the client is requesting: a URI is almost, but not quite, +the same as a *uniform resource locator* *(URL)*. The difference between URIs and URLs isn’t important for our purposes in this chapter, but the HTTP spec -uses the term URI, so we can just mentally substitute URL for URI here. +uses the term *URI*, so we can just mentally substitute *URL* for *URI* here. The last part is the HTTP version the client uses, and then the request line -ends in a *CRLF sequence*. (CRLF stands for *carriage return* and *line feed*, +ends in a CRLF sequence. (CRLF stands for *carriage return* and *line feed*, which are terms from the typewriter days!) The CRLF sequence can also be written as `\r\n`, where `\r` is a carriage return and `\n` is a line feed. The -CRLF sequence separates the request line from the rest of the request data. +*CRLF sequence* separates the request line from the rest of the request data. Note that when the CRLF is printed, we see a new line start rather than `\r\n`. Looking at the request line data we received from running our program so far, @@ -334,8 +335,8 @@ a reason phrase that provides a text description of the status code. After the CRLF sequence are any headers, another CRLF sequence, and the body of the response. -Here is an example response that uses HTTP version 1.1, has a status code of -200, an OK reason phrase, no headers, and no body: +Here is an example response that uses HTTP version 1.1, and has a status code +of 200, an OK reason phrase, no headers, and no body: ``` HTTP/1.1 200 OK\r\n\r\n @@ -358,9 +359,9 @@ fn handle_connection(mut stream: TcpStream) { .take_while(|line| !line.is_empty()) .collect(); - [1] let response = "HTTP/1.1 200 OK\r\n\r\n"; + 1 let response = "HTTP/1.1 200 OK\r\n\r\n"; - [2] stream.write_all(response.as_bytes()[3]).unwrap(); + 2 stream.write_all(response.3 as_bytes()).unwrap(); } ``` @@ -376,7 +377,7 @@ a real application you would add error handling here. With these changes, let’s run our code and make a request. We’re no longer printing any data to the terminal, so we won’t see any output other than the output from Cargo. When you load *127.0.0.1:7878* in a web browser, you should -get a blank page instead of an error. You’ve just hand-coded receiving an HTTP +get a blank page instead of an error. You’ve just handcoded receiving an HTTP request and sending a response! ### Returning Real HTML @@ -413,11 +414,11 @@ Filename: src/main.rs ``` use std::{ - [1] fs, + 1 fs, io::{prelude::*, BufReader}, net::{TcpListener, TcpStream}, }; -// --snip-- +--snip-- fn handle_connection(mut stream: TcpStream) { let buf_reader = BufReader::new(&mut stream); @@ -431,8 +432,11 @@ fn handle_connection(mut stream: TcpStream) { let contents = fs::read_to_string("hello.html").unwrap(); let length = contents.len(); - [2] let response = - format!("{status_line}\r\nContent-Length: {length}\r\n\r\n{contents}"); + 2 let response = format!( + "{status_line}\r\n\ + Content-Length: {length}\r\n\r\n\ + {contents}" + ); stream.write_all(response.as_bytes()).unwrap(); } @@ -442,8 +446,8 @@ Listing 20-5: Sending the contents of *hello.html* as the body of the response We’ve added `fs` to the `use` statement to bring the standard library’s filesystem module into scope [1]. The code for reading the contents of a file -to a string should look familiar; we used it in Chapter 12 when we read the -contents of a file for our I/O project in Listing 12-4. +to a string should look familiar; we used it when we read the contents of a +file for our I/O project in Listing 12-4. Next, we use `format!` to add the file’s contents as the body of the success response [2]. To ensure a valid HTTP response, we add the `Content-Length` @@ -465,7 +469,7 @@ request to */*. Right now, our web server will return the HTML in the file no matter what the client requested. Let’s add functionality to check that the browser is -requesting */* before returning the HTML file and return an error if the +requesting */* before returning the HTML file, and return an error if the browser requests anything else. For this we need to modify `handle_connection`, as shown in Listing 20-6. This new code checks the content of the request received against what we know a request for */* looks like and adds `if` and @@ -474,23 +478,29 @@ received against what we know a request for */* looks like and adds `if` and Filename: src/main.rs ``` -// --snip-- +--snip-- fn handle_connection(mut stream: TcpStream) { let buf_reader = BufReader::new(&mut stream); - [1] let request_line = buf_reader.lines().next().unwrap().unwrap(); + 1 let request_line = buf_reader + .lines() + .next() + .unwrap() + .unwrap(); - [2] if request_line == "GET / HTTP/1.1" { + 2 if request_line == "GET / HTTP/1.1" { let status_line = "HTTP/1.1 200 OK"; let contents = fs::read_to_string("hello.html").unwrap(); let length = contents.len(); let response = format!( - "{status_line}\r\nContent-Length: {length}\r\n\r\n{contents}" + "{status_line}\r\n\ + Content-Length: {length}\r\n\r\n\ + {contents}" ); stream.write_all(response.as_bytes()).unwrap(); - [3] } else { + 3 } else { // some other request } } @@ -526,18 +536,20 @@ indicating the response to the end user. Filename: src/main.rs ``` - // --snip-- - } else { - [1] let status_line = "HTTP/1.1 404 NOT FOUND"; - [2] let contents = fs::read_to_string("404.html").unwrap(); - let length = contents.len(); +--snip-- +} else { + 1 let status_line = "HTTP/1.1 404 NOT FOUND"; + 2 let contents = fs::read_to_string("404.html").unwrap(); + let length = contents.len(); - let response = format!( - "{status_line}\r\nContent-Length: {length}\r\n\r\n{contents}" - ); + let response = format!( + "{status_line}\r\n\ + Content-Length: {length}\r\n\r\n + {contents}" + ); - stream.write_all(response.as_bytes()).unwrap(); - } + stream.write_all(response.as_bytes()).unwrap(); +} ``` Listing 20-7: Responding with status code 404 and an error page if anything @@ -546,8 +558,8 @@ other than */* was requested Here, our response has a status line with status code 404 and the reason phrase `NOT FOUND` [1]. The body of the response will be the HTML in the file *404.html* [1]. You’ll need to create a *404.html* file next to *hello.html* -for the error page; again feel free to use any HTML you want or use the example -HTML in Listing 20-8. +for the error page; again feel free to use any HTML you want, or use the +example HTML in Listing 20-8. Filename: 404.html @@ -573,34 +585,38 @@ return the contents of *hello.html*, and any other request, like ### A Touch of Refactoring -At the moment the `if` and `else` blocks have a lot of repetition: they’re both -reading files and writing the contents of the files to the stream. The only -differences are the status line and the filename. Let’s make the code more +At the moment, the `if` and `else` blocks have a lot of repetition: they’re +both reading files and writing the contents of the files to the stream. The +only differences are the status line and the filename. Let’s make the code more concise by pulling out those differences into separate `if` and `else` lines that will assign the values of the status line and the filename to variables; we can then use those variables unconditionally in the code to read the file -and write the response. Listing 20-9 shows the resulting code after replacing +and write the response. Listing 20-9 shows the resultant code after replacing the large `if` and `else` blocks. Filename: src/main.rs ``` -// --snip-- +--snip-- fn handle_connection(mut stream: TcpStream) { - // --snip-- + --snip-- - let (status_line, filename) = if request_line == "GET / HTTP/1.1" { - ("HTTP/1.1 200 OK", "hello.html") - } else { - ("HTTP/1.1 404 NOT FOUND", "404.html") - }; + let (status_line, filename) = + if request_line == "GET / HTTP/1.1" { + ("HTTP/1.1 200 OK", "hello.html") + } else { + ("HTTP/1.1 404 NOT FOUND", "404.html") + }; let contents = fs::read_to_string(filename).unwrap(); let length = contents.len(); - let response = - format!("{status_line}\r\nContent-Length: {length}\r\n\r\n{contents}"); + let response = format!( + "{status_line}\r\n\ + Content-Length: {length}\r\n\r\n\ + {contents}" + ); stream.write_all(response.as_bytes()).unwrap(); } @@ -638,14 +654,14 @@ server received more and more requests, this serial execution would be less and less optimal. If the server receives a request that takes a long time to process, subsequent requests will have to wait until the long request is finished, even if the new requests can be processed quickly. We’ll need to fix -this, but first, we’ll look at the problem in action. +this, but first we’ll look at the problem in action. -### Simulating a Slow Request in the Current Server Implementation +### Simulating a Slow Request We’ll look at how a slow-processing request can affect other requests made to our current server implementation. Listing 20-10 implements handling a request to */sleep* with a simulated slow response that will cause the server to sleep -for 5 seconds before responding. +for five seconds before responding. Filename: src/main.rs @@ -657,44 +673,44 @@ use std::{ thread, time::Duration, }; -// --snip-- +--snip-- fn handle_connection(mut stream: TcpStream) { - // --snip-- + --snip-- - let (status_line, filename) = [1] match &request_line[..] { - [2] "GET / HTTP/1.1" => ("HTTP/1.1 200 OK", "hello.html"), - [3] "GET /sleep HTTP/1.1" => { + let (status_line, filename) = 1 match &request_line[..] { + 2 "GET / HTTP/1.1" => ("HTTP/1.1 200 OK", "hello.html"), + 3 "GET /sleep HTTP/1.1" => { thread::sleep(Duration::from_secs(5)); ("HTTP/1.1 200 OK", "hello.html") } - [4] _ => ("HTTP/1.1 404 NOT FOUND", "404.html"), + 4 _ => ("HTTP/1.1 404 NOT FOUND", "404.html"), }; - // --snip-- + --snip-- } ``` -Listing 20-10: Simulating a slow request by sleeping for 5 seconds +Listing 20-10: Simulating a slow request by sleeping for five seconds We switched from `if` to `match` now that we have three cases [1]. We need to -explicitly match on a slice of `request_line` to pattern match against the +explicitly match on a slice of `request_line` to pattern-match against the string literal values; `match` doesn’t do automatic referencing and -dereferencing like the equality method does. +dereferencing, like the equality method does. The first arm [2] is the same as the `if` block from Listing 20-9. The second arm [3] matches a request to */sleep*. When that request is received, the -server will sleep for 5 seconds before rendering the successful HTML page. The -third arm [4] is the same as the `else` block from Listing 20-9. +server will sleep for five seconds before rendering the successful HTML page. +The third arm [4] is the same as the `else` block from Listing 20-9. You can see how primitive our server is: real libraries would handle the recognition of multiple requests in a much less verbose way! Start the server using `cargo run`. Then open two browser windows: one for -*http://127.0.0.1:7878/* and the other for *http://127.0.0.1:7878/sleep*. If -you enter the */* URI a few times, as before, you’ll see it respond quickly. -But if you enter */sleep* and then load */*, you’ll see that */* waits until -`sleep` has slept for its full 5 seconds before loading. +*http://127.0.0.1:7878* and the other for *http://127.0.0.1:7878/sleep*. If you +enter the */* URI a few times, as before, you’ll see it respond quickly. But if +you enter */sleep* and then load */*, you’ll see that */* waits until `sleep` +has slept for its full five seconds before loading. There are multiple techniques we could use to avoid requests backing up behind a slow request; the one we’ll implement is a thread pool. @@ -711,33 +727,28 @@ a new task. A thread pool allows you to process connections concurrently, increasing the throughput of your server. We’ll limit the number of threads in the pool to a small number to protect us -from Denial of Service (DoS) attacks; if we had our program create a new thread -for each request as it came in, someone making 10 million requests to our -server could create havoc by using up all our server’s resources and grinding -the processing of requests to a halt. +from DoS attacks; if we had our program create a new thread for each request as +it came in, someone making 10 million requests to our server could create havoc +by using up all our server’s resources and grinding the processing of requests +to a halt. Rather than spawning unlimited threads, then, we’ll have a fixed number of threads waiting in the pool. Requests that come in are sent to the pool for processing. The pool will maintain a queue of incoming requests. Each of the threads in the pool will pop off a request from this queue, handle the request, and then ask the queue for another request. With this design, we can process up -to `N` requests concurrently, where `N` is the number of threads. If each -thread is responding to a long-running request, subsequent requests can still -back up in the queue, but we’ve increased the number of long-running requests -we can handle before reaching that point. +to N requests concurrently, where N is the number of threads. If each thread is +responding to a long-running request, subsequent requests can still back up in +the queue, but we’ve increased the number of long-running requests we can +handle before reaching that point. This technique is just one of many ways to improve the throughput of a web -server. Other options you might explore are the *fork/join model*, the -*single-threaded async I/O model*, or the *multi-threaded async I/O model*. If +server. Other options you might explore are the fork/join model, the +single-threaded async I/O model, and the multithreaded async I/O model. If you’re interested in this topic, you can read more about other solutions and try to implement them; with a low-level language like Rust, all of these options are possible. -<!-- A more modern approach would probably use tokio, which could be a -multi-threaded async I/O model. /JT --> -<!-- I've added "multi-theraded async I/O model", I don't want to get into -particular async crates though /Carol --> - Before we begin implementing a thread pool, let’s talk about what using the pool should look like. When you’re trying to design code, writing the client interface first can help guide your design. Write the API of the code so it’s @@ -757,8 +768,7 @@ First, let’s explore how our code might look if it did create a new thread for every connection. As mentioned earlier, this isn’t our final plan due to the problems with potentially spawning an unlimited number of threads, but it is a starting point to get a working multithreaded server first. Then we’ll add the -thread pool as an improvement, and contrasting the two solutions will be -easier. +thread pool as an improvement, and contrasting the two solutions will be easier. Listing 20-11 shows the changes to make to `main` to spawn a new thread to handle each stream within the `for` loop. @@ -790,9 +800,9 @@ new threads without any limit. #### Creating a Finite Number of Threads -We want our thread pool to work in a similar, familiar way so switching from -threads to a thread pool doesn’t require large changes to the code that uses -our API. Listing 20-12 shows the hypothetical interface for a `ThreadPool` +We want our thread pool to work in a similar, familiar way so that switching +from threads to a thread pool doesn’t require large changes to the code that +uses our API. Listing 20-12 shows the hypothetical interface for a `ThreadPool` struct we want to use instead of `thread::spawn`. Filename: src/main.rs @@ -800,12 +810,12 @@ Filename: src/main.rs ``` fn main() { let listener = TcpListener::bind("127.0.0.1:7878").unwrap(); - [1] let pool = ThreadPool::new(4); + 1 let pool = ThreadPool::new(4); for stream in listener.incoming() { let stream = stream.unwrap(); - [2] pool.execute(|| { + 2 pool.execute(|| { handle_connection(stream); }); } @@ -819,9 +829,9 @@ of threads, in this case four [1]. Then, in the `for` loop, `pool.execute` has a similar interface as `thread::spawn` in that it takes a closure the pool should run for each stream [2]. We need to implement `pool.execute` so it takes the closure and gives it to a thread in the pool to run. This code won’t yet -compile, but we’ll try so the compiler can guide us in how to fix it. +compile, but we’ll try so that the compiler can guide us in how to fix it. -#### Building `ThreadPool` Using Compiler Driven Development +#### Building ThreadPool Using Compiler-Driven Development Make the changes in Listing 20-12 to *src/main.rs*, and then let’s use the compiler errors from `cargo check` to drive our development. Here is the first @@ -831,21 +841,21 @@ error we get: $ cargo check Checking hello v0.1.0 (file:///projects/hello) error[E0433]: failed to resolve: use of undeclared type `ThreadPool` - --> src/main.rs:10:16 + --> src/main.rs:11:16 | -10 | let pool = ThreadPool::new(4); +11 | let pool = ThreadPool::new(4); | ^^^^^^^^^^ use of undeclared type `ThreadPool` ``` Great! This error tells us we need a `ThreadPool` type or module, so we’ll build one now. Our `ThreadPool` implementation will be independent of the kind -of work our web server is doing. So, let’s switch the `hello` crate from a +of work our web server is doing. So let’s switch the `hello` crate from a binary crate to a library crate to hold our `ThreadPool` implementation. After we change to a library crate, we could also use the separate thread pool library for any work we want to do using a thread pool, not just for serving web requests. -Create a *src/lib.rs* that contains the following, which is the simplest +Create a *src/lib.rs* file that contains the following, which is the simplest definition of a `ThreadPool` struct that we can have for now: Filename: src/lib.rs @@ -854,7 +864,7 @@ Filename: src/lib.rs pub struct ThreadPool; ``` -Then edit *main.rs* file to bring `ThreadPool` into scope from the library +Then edit the *main.rs* file to bring `ThreadPool` into scope from the library crate by adding the following code to the top of *src/main.rs*: Filename: src/main.rs @@ -869,11 +879,13 @@ we need to address: ``` $ cargo check Checking hello v0.1.0 (file:///projects/hello) -error[E0599]: no function or associated item named `new` found for struct `ThreadPool` in the current scope - --> src/bin/main.rs:11:28 +error[E0599]: no function or associated item named `new` found for struct +`ThreadPool` in the current scope + --> src/main.rs:12:28 | -11 | let pool = ThreadPool::new(4); - | ^^^ function or associated item not found in `ThreadPool` +12 | let pool = ThreadPool::new(4); + | ^^^ function or associated item not found in +`ThreadPool` ``` This error indicates that next we need to create an associated function named @@ -894,37 +906,37 @@ impl ThreadPool { } ``` -We chose `usize` as the type of the `size` parameter, because we know that a +We chose `usize` as the type of the `size` parameter because we know that a negative number of threads doesn’t make any sense. We also know we’ll use this -4 as the number of elements in a collection of threads, which is what the -`usize` type is for, as discussed in the “Integer Types†section of Chapter 3. +`4` as the number of elements in a collection of threads, which is what the +`usize` type is for, as discussed in “Integer Types†on page XX. Let’s check the code again: ``` $ cargo check Checking hello v0.1.0 (file:///projects/hello) -error[E0599]: no method named `execute` found for struct `ThreadPool` in the current scope - --> src/bin/main.rs:16:14 +error[E0599]: no method named `execute` found for struct `ThreadPool` in the +current scope + --> src/main.rs:17:14 | -16 | pool.execute(|| { +17 | pool.execute(|| { | ^^^^^^^ method not found in `ThreadPool` ``` Now the error occurs because we don’t have an `execute` method on `ThreadPool`. -Recall from the “Creating a Finite Number of Threads†section that we decided +Recall from “Creating a Finite Number of Threads†on page XX that we decided our thread pool should have an interface similar to `thread::spawn`. In addition, we’ll implement the `execute` function so it takes the closure it’s given and gives it to an idle thread in the pool to run. We’ll define the `execute` method on `ThreadPool` to take a closure as a -parameter. Recall from the “Moving Captured Values Out of the Closure and the -`Fn` Traits†section in Chapter 13 that we can take closures as parameters with -three different traits: `Fn`, `FnMut`, and `FnOnce`. We need to decide which -kind of closure to use here. We know we’ll end up doing something similar to -the standard library `thread::spawn` implementation, so we can look at what -bounds the signature of `thread::spawn` has on its parameter. The documentation -shows us the following: +parameter. Recall from “Moving Captured Values Out of Closures and the Fn +Traits†on page XX that we can take closures as parameters with three different +traits: `Fn`, `FnMut`, and `FnOnce`. We need to decide which kind of closure to +use here. We know we’ll end up doing something similar to the standard library +`thread::spawn` implementation, so we can look at what bounds the signature of +`thread::spawn` has on its parameter. The documentation shows us the following: ``` pub fn spawn<F, T>(f: F) -> JoinHandle<T> @@ -952,10 +964,10 @@ Filename: src/lib.rs ``` impl ThreadPool { - // --snip-- + --snip-- pub fn execute<F>(&self, f: F) where - F: FnOnce() [1] + Send + 'static, + F: FnOnce() 1 + Send + 'static, { } } @@ -967,7 +979,7 @@ function definitions, the return type can be omitted from the signature, but even if we have no parameters, we still need the parentheses. Again, this is the simplest implementation of the `execute` method: it does -nothing, but we’re trying only to make our code compile. Let’s check it again: +nothing, but we’re only trying to make our code compile. Let’s check it again: ``` $ cargo check @@ -981,18 +993,18 @@ the chapter. Our library isn’t actually calling the closure passed to `execute yet! > Note: A saying you might hear about languages with strict compilers, such as -> Haskell and Rust, is “if the code compiles, it works.†But this saying is not -> universally true. Our project compiles, but it does absolutely nothing! If we -> were building a real, complete project, this would be a good time to start -> writing unit tests to check that the code compiles *and* has the behavior we -> want. +Haskell and Rust, is “if the code compiles, it works.†But this saying is not +universally true. Our project compiles, but it does absolutely nothing! If we +were building a real, complete project, this would be a good time to start +writing unit tests to check that the code compiles *and* has the behavior we +want. -#### Validating the Number of Threads in `new` +#### Validating the Number of Threads in new We aren’t doing anything with the parameters to `new` and `execute`. Let’s implement the bodies of these functions with the behavior we want. To start, let’s think about `new`. Earlier we chose an unsigned type for the `size` -parameter, because a pool with a negative number of threads makes no sense. +parameter because a pool with a negative number of threads makes no sense. However, a pool with zero threads also makes no sense, yet zero is a perfectly valid `usize`. We’ll add code to check that `size` is greater than zero before we return a `ThreadPool` instance and have the program panic if it receives a @@ -1006,16 +1018,16 @@ impl ThreadPool { /// /// The size is the number of threads in the pool. /// - [1] /// # Panics + 1 /// # Panics /// /// The `new` function will panic if the size is zero. pub fn new(size: usize) -> ThreadPool { - [2] assert!(size > 0); + 2 assert!(size > 0); ThreadPool } - // --snip-- + --snip-- } ``` @@ -1035,14 +1047,10 @@ you’re feeling ambitious, try to write a function named `build` with the following signature to compare with the `new` function: ``` -pub fn build(size: usize) -> Result<ThreadPool, PoolCreationError> { +pub fn build( + size: usize +) -> Result<ThreadPool, PoolCreationError> { ``` -<!-- Similar nit here to a comment I made a few chapters ago: fallible -constructors are awkward to use. We may want to discourage their use. A modern -approach might use a builder pattern to set the number of threads, and use a -default number of threads that's non-zero. /JT --> -<!-- I've changed the function name to be `build` which nicely matches the -changes JT suggested for chapter 12. /Carol --> #### Creating Space to Store the Threads @@ -1073,18 +1081,18 @@ returned a `ThreadPool` instance containing them. Filename: src/lib.rs ``` -[1] use std::thread; +1 use std::thread; pub struct ThreadPool { - [2] threads: Vec<thread::JoinHandle<()>>, + 2 threads: Vec<thread::JoinHandle<()>>, } impl ThreadPool { - // --snip-- + --snip-- pub fn new(size: usize) -> ThreadPool { assert!(size > 0); - [3] let mut threads = Vec::with_capacity(size); + 3 let mut threads = Vec::with_capacity(size); for _ in 0..size { // create some threads and store them in the vector @@ -1092,26 +1100,26 @@ impl ThreadPool { ThreadPool { threads } } - // --snip-- + --snip-- } ``` Listing 20-14: Creating a vector for `ThreadPool` to hold the threads -We’ve brought `std::thread` into scope in the library crate [1], because we’re +We’ve brought `std::thread` into scope in the library crate [1] because we’re using `thread::JoinHandle` as the type of the items in the vector in `ThreadPool` [2]. Once a valid size is received, our `ThreadPool` creates a new vector that can hold `size` items [3]. The `with_capacity` function performs the same task as -`Vec::new` but with an important difference: it preallocates space in the +`Vec::new` but with an important difference: it pre-allocates space in the vector. Because we know we need to store `size` elements in the vector, doing this allocation up front is slightly more efficient than using `Vec::new`, which resizes itself as elements are inserted. When you run `cargo check` again, it should succeed. -#### A `Worker` Struct Responsible for Sending Code from the `ThreadPool` to a Thread +#### Sending Code from the ThreadPool to a Thread We left a comment in the `for` loop in Listing 20-14 regarding the creation of threads. Here, we’ll look at how we actually create threads. The standard @@ -1125,31 +1133,31 @@ implement it manually. We’ll implement this behavior by introducing a new data structure between the `ThreadPool` and the threads that will manage this new behavior. We’ll call this data structure *Worker*, which is a common term in pooling -implementations. The Worker picks up code that needs to be run and runs the -code in the Worker’s thread. +implementations. The `Worker` picks up code that needs to be run and runs the +code in its thread. -Think of people working in the kitchen at a restaurant: the -workers wait until orders come in from customers, and then they’re responsible -for taking those orders and filling them. +Think of people working in the kitchen at a restaurant: the workers wait until +orders come in from customers, and then they’re responsible for taking those +orders and filling them. Instead of storing a vector of `JoinHandle<()>` instances in the thread pool, we’ll store instances of the `Worker` struct. Each `Worker` will store a single `JoinHandle<()>` instance. Then we’ll implement a method on `Worker` that will take a closure of code to run and send it to the already running thread for -execution. We’ll also give each worker an `id` so we can distinguish between -the different workers in the pool when logging or debugging. +execution. We’ll also give each `Worker` an `id` so we can distinguish between +the different instances of `Worker` in the pool when logging or debugging. Here is the new process that will happen when we create a `ThreadPool`. We’ll implement the code that sends the closure to the thread after we have `Worker` set up in this way: 1. Define a `Worker` struct that holds an `id` and a `JoinHandle<()>`. -2. Change `ThreadPool` to hold a vector of `Worker` instances. -3. Define a `Worker::new` function that takes an `id` number and returns a - `Worker` instance that holds the `id` and a thread spawned with an empty - closure. -4. In `ThreadPool::new`, use the `for` loop counter to generate an `id`, create - a new `Worker` with that `id`, and store the worker in the vector. +1. Change `ThreadPool` to hold a vector of `Worker` instances. +1. Define a `Worker::new` function that takes an `id` number and returns a +`Worker` instance that holds the `id` and a thread spawned with an empty +closure. +1. In `ThreadPool::new`, use the `for` loop counter to generate an `id`, create +a new `Worker` with that `id`, and store the `Worker` in the vector. If you’re up for a challenge, try implementing these changes on your own before looking at the code in Listing 20-15. @@ -1162,49 +1170,39 @@ Filename: src/lib.rs use std::thread; pub struct ThreadPool { - [1] workers: Vec<Worker>, + 1 workers: Vec<Worker>, } impl ThreadPool { - // --snip-- + --snip-- pub fn new(size: usize) -> ThreadPool { assert!(size > 0); let mut workers = Vec::with_capacity(size); - [2] for id in 0..size { - [3] workers.push(Worker::new(id)); + 2 for id in 0..size { + 3 workers.push(Worker::new(id)); } ThreadPool { workers } } - // --snip-- + --snip-- } -[4] struct Worker { +4 struct Worker { id: usize, thread: thread::JoinHandle<()>, } impl Worker { - [5] fn new(id: usize) -> Worker { - [6] let thread = thread::spawn(|| {}); + 5 fn new(id: usize) -> Worker { + 6 let thread = thread::spawn(|| {}); - Worker { [7] id, [8] thread } + Worker { 7 id, 8 thread } } } ``` -<!-- Spawning a thread in the constructor isn't safe to do as the spawn -of the thread may fail. You can use -https://doc.rust-lang.org/std/thread/struct.Builder.html#method.spawn -to be better protected against running out of resources. This should -probably not live in the constructor, but instead in some helper function -that can return a Result. /JT --> -<!-- I've added a note in a few paragraphs. I think this behavior is perfectly -fine for this example so I'm not going to change the code, but it is something -readers should know. /Carol --> - Listing 20-15: Modifying `ThreadPool` to hold `Worker` instances instead of holding threads directly @@ -1221,11 +1219,11 @@ so we make the `Worker` struct [4] and its `new` function [5] private. The empty closure [6]. > Note: If the operating system can’t create a thread because there aren’t -> enough system resources, `thread::spawn` will panic. That will cause our -> whole server to panic, even though the creation of some threads might -> succeed. For simplicity’s sake, this behavior is fine, but in a production -> thread pool implementation, you’d likely want to use `std::thread::Builder` -> and its `spawn` method that returns `Result` instead. +enough system resources, `thread::spawn` will panic. That will cause our whole +server to panic, even though the creation of some threads might succeed. For +simplicity’s sake, this behavior is fine, but in a production thread pool +implementation, you’d likely want to use `std::thread::Builder` and its `spawn` +method that returns `Result` instead. This code will compile and will store the number of `Worker` instances we specified as an argument to `ThreadPool::new`. But we’re *still* not processing @@ -1247,13 +1245,13 @@ as the queue of jobs, and `execute` will send a job from the `ThreadPool` to the `Worker` instances, which will send the job to its thread. Here is the plan: 1. The `ThreadPool` will create a channel and hold on to the sender. -2. Each `Worker` will hold on to the receiver. -3. We’ll create a new `Job` struct that will hold the closures we want to send - down the channel. -4. The `execute` method will send the job it wants to execute through the - sender. -5. In its thread, the `Worker` will loop over its receiver and execute the - closures of any jobs it receives. +1. Each `Worker` will hold on to the receiver. +1. We’ll create a new `Job` struct that will hold the closures we want to send +down the channel. +1. The `execute` method will send the job it wants to execute through the +sender. +1. In its thread, the `Worker` will loop over its receiver and execute the +closures of any jobs it receives. Let’s start by creating a channel in `ThreadPool::new` and holding the sender in the `ThreadPool` instance, as shown in Listing 20-16. The `Job` struct @@ -1273,11 +1271,11 @@ pub struct ThreadPool { struct Job; impl ThreadPool { - // --snip-- + --snip-- pub fn new(size: usize) -> ThreadPool { assert!(size > 0); - [1] let (sender, receiver) = mpsc::channel(); + 1 let (sender, receiver) = mpsc::channel(); let mut workers = Vec::with_capacity(size); @@ -1285,9 +1283,9 @@ impl ThreadPool { workers.push(Worker::new(id)); } - ThreadPool { workers, [2] sender } + ThreadPool { workers, 2 sender } } - // --snip-- + --snip-- } ``` @@ -1297,16 +1295,16 @@ transmits `Job` instances In `ThreadPool::new`, we create our new channel [1] and have the pool hold the sender [2]. This will successfully compile. -Let’s try passing a receiver of the channel into each worker as the thread pool -creates the channel. We know we want to use the receiver in the thread that the -workers spawn, so we’ll reference the `receiver` parameter in the closure. The -code in Listing 20-17 won’t quite compile yet. +Let’s try passing a receiver of the channel into each `Worker` as the thread +pool creates the channel. We know we want to use the receiver in the thread +that the `Worker` instances spawn, so we’ll reference the `receiver` parameter +in the closure. The code in Listing 20-17 won’t quite compile yet. Filename: src/lib.rs ``` impl ThreadPool { - // --snip-- + --snip-- pub fn new(size: usize) -> ThreadPool { assert!(size > 0); @@ -1315,20 +1313,20 @@ impl ThreadPool { let mut workers = Vec::with_capacity(size); for id in 0..size { - [1] workers.push(Worker::new(id, receiver)); + 1 workers.push(Worker::new(id, receiver)); } ThreadPool { workers, sender } } - // --snip-- + --snip-- } -// --snip-- +--snip-- impl Worker { fn new(id: usize, receiver: mpsc::Receiver<Job>) -> Worker { let thread = thread::spawn(|| { - [2] receiver; + 2 receiver; }); Worker { id, thread } @@ -1336,7 +1334,7 @@ impl Worker { } ``` -Listing 20-17: Passing the receiver to the workers +Listing 20-17: Passing the receiver to each `Worker` We’ve made some small and straightforward changes: we pass the receiver into `Worker::new` [1], and then we use it inside the closure [2]. @@ -1347,13 +1345,15 @@ When we try to check this code, we get this error: $ cargo check Checking hello v0.1.0 (file:///projects/hello) error[E0382]: use of moved value: `receiver` - --> src/lib.rs:27:42 + --> src/lib.rs:26:42 | -22 | let (sender, receiver) = mpsc::channel(); - | -------- move occurs because `receiver` has type `std::sync::mpsc::Receiver<Job>`, which does not implement the `Copy` trait +21 | let (sender, receiver) = mpsc::channel(); + | -------- move occurs because `receiver` has type +`std::sync::mpsc::Receiver<Job>`, which does not implement the `Copy` trait ... -27 | workers.push(Worker::new(id, receiver)); - | ^^^^^^^^ value moved here, in previous iteration of loop +26 | workers.push(Worker::new(id, receiver)); + | ^^^^^^^^ value moved here, in +previous iteration of loop ``` The code is trying to pass `receiver` to multiple `Worker` instances. This @@ -1361,7 +1361,8 @@ won’t work, as you’ll recall from Chapter 16: the channel implementation tha Rust provides is multiple *producer*, single *consumer*. This means we can’t just clone the consuming end of the channel to fix this code. We also don’t want to send a message multiple times to multiple consumers; we want one list -of messages with multiple workers such that each message gets processed once. +of messages with multiple `Worker` instances such that each message gets +processed once. Additionally, taking a job off the channel queue involves mutating the `receiver`, so the threads need a safe way to share and modify `receiver`; @@ -1369,9 +1370,10 @@ otherwise, we might get race conditions (as covered in Chapter 16). Recall the thread-safe smart pointers discussed in Chapter 16: to share ownership across multiple threads and allow the threads to mutate the value, we -need to use `Arc<Mutex<T>>`. The `Arc` type will let multiple workers own the -receiver, and `Mutex` will ensure that only one worker gets a job from the -receiver at a time. Listing 20-18 shows the changes we need to make. +need to use `Arc<Mutex<T>>`. The `Arc` type will let multiple `Worker` +instances own the receiver, and `Mutex` will ensure that only one `Worker` gets +a job from the receiver at a time. Listing 20-18 shows the changes we need to +make. Filename: src/lib.rs @@ -1380,75 +1382,81 @@ use std::{ sync::{mpsc, Arc, Mutex}, thread, }; -// --snip-- +--snip-- impl ThreadPool { - // --snip-- + --snip-- pub fn new(size: usize) -> ThreadPool { assert!(size > 0); let (sender, receiver) = mpsc::channel(); - [1] let receiver = Arc::new(Mutex::new(receiver)); + 1 let receiver = Arc::new(Mutex::new(receiver)); let mut workers = Vec::with_capacity(size); for id in 0..size { - workers.push(Worker::new(id, Arc::clone(&receiver)[2])); + workers.push( + Worker::new(id, Arc::clone(& 2 receiver)) + ); } ThreadPool { workers, sender } } - // --snip-- + --snip-- } -// --snip-- +--snip-- impl Worker { - fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker { - // --snip-- + fn new( + id: usize, + receiver: Arc<Mutex<mpsc::Receiver<Job>>>, + ) -> Worker { + --snip-- } } ``` -Listing 20-18: Sharing the receiver among the workers using `Arc` and `Mutex` +Listing 20-18: Sharing the receiver among the `Worker` instances using `Arc` +and `Mutex` In `ThreadPool::new`, we put the receiver in an `Arc` and a `Mutex` [1]. For -each new worker, we clone the `Arc` to bump the reference count so the workers -can share ownership of the receiver [2]. +each new `Worker`, we clone the `Arc` to bump the reference count so the +`Worker` instances can share ownership of the receiver [2]. With these changes, the code compiles! We’re getting there! -#### Implementing the `execute` Method +#### Implementing the execute Method Let’s finally implement the `execute` method on `ThreadPool`. We’ll also change `Job` from a struct to a type alias for a trait object that holds the type of -closure that `execute` receives. As discussed in the “Creating Type Synonyms -with Type Aliases†section of Chapter 19, type aliases allow us to make long -types shorter for ease of use. Look at Listing 20-19. +closure that `execute` receives. As discussed in “Creating Type Synonyms with +Type Aliases†on page XX, type aliases allow us to make long types shorter for +ease of use. Look at Listing 20-19. Filename: src/lib.rs ``` -// --snip-- +--snip-- type Job = Box<dyn FnOnce() + Send + 'static>; impl ThreadPool { - // --snip-- + --snip-- pub fn execute<F>(&self, f: F) where F: FnOnce() + Send + 'static, { - [1] let job = Box::new(f); + 1 let job = Box::new(f); - [2] self.sender.send(job).unwrap(); + 2 self.sender.send(job).unwrap(); } } -// --snip-- +--snip-- ``` Listing 20-19: Creating a `Job` type alias for a `Box` that holds each closure @@ -1463,7 +1471,7 @@ executing: our threads continue executing as long as the pool exists. The reason we use `unwrap` is that we know the failure case won’t happen, but the compiler doesn’t know that. -But we’re not quite done yet! In the worker, our closure being passed to +But we’re not quite done yet! In the `Worker`, our closure being passed to `thread::spawn` still only *references* the receiving end of the channel. Instead, we need the closure to loop forever, asking the receiving end of the channel for a job and running the job when it gets one. Let’s make the change @@ -1472,12 +1480,19 @@ shown in Listing 20-20 to `Worker::new`. Filename: src/lib.rs ``` -// --snip-- +--snip-- impl Worker { - fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker { + fn new( + id: usize, + receiver: Arc<Mutex<mpsc::Receiver<Job>>>, + ) -> Worker { let thread = thread::spawn(move || loop { - let job = receiver.lock()[1].unwrap()[2].recv()[3].unwrap()[4]; + let job = receiver + 1 .lock() + 2 .unwrap() + 3 .recv() + 4 .unwrap(); println!("Worker {id} got a job; executing."); @@ -1489,7 +1504,8 @@ impl Worker { } ``` -Listing 20-20: Receiving and executing the jobs in the worker’s thread +Listing 20-20: Receiving and executing the jobs in the `Worker` instance’s +thread Here, we first call `lock` on the `receiver` to acquire the mutex [1], and then we call `unwrap` to panic on any errors [2]. Acquiring a lock might fail if the @@ -1555,21 +1571,24 @@ overloaded if the server receives a lot of requests. If we make a request to */sleep*, the server will be able to serve other requests by having another thread run them. -> Note: if you open */sleep* in multiple browser windows simultaneously, they -> might load one at a time in 5 second intervals. Some web browsers execute -> multiple instances of the same request sequentially for caching reasons. This -> limitation is not caused by our web server. +> Note: If you open */sleep* in multiple browser windows simultaneously, they +might load one at a time in five-second intervals. Some web browsers execute +multiple instances of the same request sequentially for caching reasons. This +limitation is not caused by our web server. After learning about the `while let` loop in Chapter 18, you might be wondering -why we didn’t write the worker thread code as shown in Listing 20-21. +why we didn’t write the `Worker` thread code as shown in Listing 20-21. Filename: src/lib.rs ``` -// --snip-- +--snip-- impl Worker { - fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker { + fn new( + id: usize, + receiver: Arc<Mutex<mpsc::Receiver<Job>>>, + ) -> Worker { let thread = thread::spawn(move || { while let Ok(job) = receiver.lock().unwrap().recv() { println!("Worker {id} got a job; executing."); @@ -1598,21 +1617,20 @@ longer than intended if we aren’t mindful of the lifetime of the The code in Listing 20-20 that uses `let job = receiver.lock().unwrap().recv().unwrap();` works because with `let`, any -temporary values used in the expression on the right hand side of the equals +temporary values used in the expression on the right-hand side of the equal sign are immediately dropped when the `let` statement ends. However, `while let` (and `if let` and `match`) does not drop temporary values until the end of the associated block. In Listing 20-21, the lock remains held for the duration -of the call to `job()`, meaning other workers cannot receive jobs. +of the call to `job()`, meaning other `Worker` instances cannot receive jobs. ## Graceful Shutdown and Cleanup The code in Listing 20-20 is responding to requests asynchronously through the use of a thread pool, as we intended. We get some warnings about the `workers`, `id`, and `thread` fields that we’re not using in a direct way that reminds us -we’re not cleaning up anything. When we use the less elegant <span -class="keystroke">ctrl-c</span> method to halt the main thread, all other -threads are stopped immediately as well, even if they’re in the middle of -serving a request. +we’re not cleaning up anything. When we use the less elegant ctrl-C method to +halt the main thread, all other threads are stopped immediately as well, even +if they’re in the middle of serving a request. Next, then, we’ll implement the `Drop` trait to call `join` on each of the threads in the pool so they can finish the requests they’re working on before @@ -1621,7 +1639,7 @@ accepting new requests and shut down. To see this code in action, we’ll modify our server to accept only two requests before gracefully shutting down its thread pool. -### Implementing the `Drop` Trait on `ThreadPool` +### Implementing the Drop Trait on ThreadPool Let’s start with implementing `Drop` on our thread pool. When the pool is dropped, our threads should all join to make sure they finish their work. @@ -1633,10 +1651,10 @@ Filename: src/lib.rs ``` impl Drop for ThreadPool { fn drop(&mut self) { - [1] for worker in &mut self.workers { - [2] println!("Shutting down worker {}", worker.id); + 1 for worker in &mut self.workers { + 2 println!("Shutting down worker {}", worker.id); - [3] worker.thread.join().unwrap(); + 3 worker.thread.join().unwrap(); } } } @@ -1644,21 +1662,29 @@ impl Drop for ThreadPool { Listing 20-22: Joining each thread when the thread pool goes out of scope -First, we loop through each of the thread pool `workers` [1]. We use `&mut` for +First we loop through each of the thread pool `workers` [1]. We use `&mut` for this because `self` is a mutable reference, and we also need to be able to -mutate `worker`. For each worker, we print a message saying that this -particular worker is shutting down [2], and then we call `join` on that -worker’s thread [3]. If the call to `join` fails, we use `unwrap` to make Rust -panic and go into an ungraceful shutdown. +mutate `worker`. For each `worker`, we print a message saying that this +particular `Worker` instance is shutting down [2], and then we call `join` on +that `Worker` instance’s thread [3]. If the call to `join` fails, we use +`unwrap` to make Rust panic and go into an ungraceful shutdown. Here is the error we get when we compile this code: ``` -error[E0507]: cannot move out of `worker.thread` which is behind a mutable reference - --> src/lib.rs:52:13 - | -52 | worker.thread.join().unwrap(); - | ^^^^^^^^^^^^^ move occurs because `worker.thread` has type `JoinHandle<()>`, which does not implement the `Copy` trait +error[E0507]: cannot move out of `worker.thread` which is behind a mutable +reference + --> src/lib.rs:52:13 + | +52 | worker.thread.join().unwrap(); + | ^^^^^^^^^^^^^ ------ `worker.thread` moved due to this +method call + | | + | 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` ``` The error tells us we can’t call `join` because we only have a mutable borrow @@ -1687,24 +1713,27 @@ Now let’s lean on the compiler to find the other places that need to change. Checking this code, we get two errors: ``` -error[E0599]: no method named `join` found for enum `Option` in the current scope +error[E0599]: no method named `join` found for enum `Option` in the current +scope --> src/lib.rs:52:27 | 52 | worker.thread.join().unwrap(); - | ^^^^ method not found in `Option<JoinHandle<()>>` + | ^^^^ method not found in +`Option<JoinHandle<()>>` error[E0308]: mismatched types --> src/lib.rs:72:22 | 72 | Worker { id, thread } - | ^^^^^^ expected enum `Option`, found struct `JoinHandle` + | ^^^^^^ expected enum `Option`, found struct +`JoinHandle` | = note: expected enum `Option<JoinHandle<()>>` found struct `JoinHandle<_>` help: try wrapping the expression in `Some` | -72 | Worker { id, Some(thread) } - | +++++ + +72 | Worker { id, thread: Some(thread) } + | +++++++++++++ + ``` Let’s address the second error, which points to the code at the end of @@ -1715,8 +1744,11 @@ Filename: src/lib.rs ``` impl Worker { - fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker { - // --snip-- + fn new( + id: usize, + receiver: Arc<Mutex<mpsc::Receiver<Job>>>, + ) -> Worker { + --snip-- Worker { id, @@ -1738,8 +1770,8 @@ impl Drop for ThreadPool { for worker in &mut self.workers { println!("Shutting down worker {}", worker.id); - [1] if let Some(thread) = worker.thread.take() { - [2] thread.join().unwrap(); + 1 if let Some(thread) = worker.thread.take() { + 2 thread.join().unwrap(); } } } @@ -1749,27 +1781,27 @@ impl Drop for ThreadPool { As discussed in Chapter 17, the `take` method on `Option` takes the `Some` variant out and leaves `None` in its place. We’re using `if let` to destructure the `Some` and get the thread [1]; then we call `join` on the thread [2]. If a -worker’s thread is already `None`, we know that worker has already had its -thread cleaned up, so nothing happens in that case. +`Worker` instance’s thread is already `None`, we know that `Worker` has already +had its thread cleaned up, so nothing happens in that case. ### Signaling to the Threads to Stop Listening for Jobs With all the changes we’ve made, our code compiles without any warnings. -However, the bad news is this code doesn’t function the way we want it to yet. -The key is the logic in the closures run by the threads of the `Worker` -instances: at the moment, we call `join`, but that won’t shut down the threads +However, the bad news is that this code doesn’t function the way we want it to +yet. The key is the logic in the closures run by the threads of the `Worker` +instances: at the moment, we call `join`, but that won’t shut down the threads, because they `loop` forever looking for jobs. If we try to drop our `ThreadPool` with our current implementation of `drop`, the main thread will -block forever waiting for the first thread to finish. +block forever, waiting for the first thread to finish. -To fix this problem, we’ll need a change in the the `ThreadPool` `drop` +To fix this problem, we’ll need a change in the `ThreadPool` `drop` implementation and then a change in the `Worker` loop. -First, we’ll change the `ThreadPool` `drop` implementation to explicitly drop +First we’ll change the `ThreadPool` `drop` implementation to explicitly drop the `sender` before waiting for the threads to finish. Listing 20-23 shows the changes to `ThreadPool` to explicitly drop `sender`. We use the same `Option` and `take` technique as we did with the thread to be able to move `sender` out -of `ThreadPool`: +of `ThreadPool`. Filename: src/lib.rs @@ -1778,10 +1810,10 @@ pub struct ThreadPool { workers: Vec<Worker>, sender: Option<mpsc::Sender<Job>>, } -// --snip-- +--snip-- impl ThreadPool { pub fn new(size: usize) -> ThreadPool { - // --snip-- + --snip-- ThreadPool { workers, @@ -1795,13 +1827,17 @@ impl ThreadPool { { let job = Box::new(f); - self.sender.as_ref().unwrap().send(job).unwrap(); + self.sender + .as_ref() + .unwrap() + .send(job) + .unwrap(); } } impl Drop for ThreadPool { fn drop(&mut self) { - [1] drop(self.sender.take()); + 1 drop(self.sender.take()); for worker in &mut self.workers { println!("Shutting down worker {}", worker.id); @@ -1814,28 +1850,37 @@ impl Drop for ThreadPool { } ``` -Listing 20-23: Explicitly drop `sender` before joining the worker threads +Listing 20-23: Explicitly dropping `sender` before joining the `Worker` threads Dropping `sender` [1] closes the channel, which indicates no more messages will -be sent. When that happens, all the calls to `recv` that the workers do in the -infinite loop will return an error. In Listing 20-24, we change the `Worker` -loop to gracefully exit the loop in that case, which means the threads will -finish when the `ThreadPool` `drop` implementation calls `join` on them. +be sent. When that happens, all the calls to `recv` that the `Worker` instances +do in the infinite loop will return an error. In Listing 20-24, we change the +`Worker` loop to gracefully exit the loop in that case, which means the threads +will finish when the `ThreadPool` `drop` implementation calls `join` on them. Filename: src/lib.rs ``` impl Worker { - fn new(id: usize, receiver: Arc<Mutex<mpsc::Receiver<Job>>>) -> Worker { + fn new( + id: usize, + receiver: Arc<Mutex<mpsc::Receiver<Job>>>, + ) -> Worker { let thread = thread::spawn(move || loop { - match receiver.lock().unwrap().recv() { + let message = receiver.lock().unwrap().recv(); + + match message { Ok(job) => { - println!("Worker {id} got a job; executing."); + println!( + "Worker {id} got a job; executing." + ); job(); } Err(_) => { - println!("Worker {id} disconnected; shutting down."); + println!( + "Worker {id} shutting down." + ); break; } } @@ -1849,7 +1894,7 @@ impl Worker { } ``` -Listing 20-24: Explicitly break out of the loop when `recv` returns an error +Listing 20-24: Explicitly breaking out of the loop when `recv` returns an error To see this code in action, let’s modify `main` to accept only two requests before gracefully shutting down the server, as shown in Listing 20-25. @@ -1873,8 +1918,8 @@ fn main() { } ``` -Listing 20-25: Shut down the server after serving two requests by exiting the -loop +Listing 20-25: Shutting down the server after serving two requests by exiting +the loop You wouldn’t want a real-world web server to shut down after serving only two requests. This code just demonstrates that the graceful shutdown and cleanup is @@ -1905,26 +1950,27 @@ Shutting down worker 2 Shutting down worker 3 ``` -You might see a different ordering of workers and messages printed. We can see -how this code works from the messages: workers 0 and 3 got the first two -requests. The server stopped accepting connections after the second connection, -and the `Drop` implementation on `ThreadPool` starts executing before worker 3 -even starts its job. Dropping the `sender` disconnects all the workers and -tells them to shut down. The workers each print a message when they disconnect, -and then the thread pool calls `join` to wait for each worker thread to finish. +You might see a different ordering of `Worker` IDs and messages printed. We can +see how this code works from the messages: `Worker` instances 0 and 3 got the +first two requests. The server stopped accepting connections after the second +connection, and the `Drop` implementation on `ThreadPool` starts executing +before `Worker` 3 even starts its job. Dropping the `sender` disconnects all +the `Worker` instances and tells them to shut down. The `Worker` instances each +print a message when they disconnect, and then the thread pool calls `join` to +wait for each `Worker` thread to finish. Notice one interesting aspect of this particular execution: the `ThreadPool` -dropped the `sender`, and before any worker received an error, we tried to join -worker 0. Worker 0 had not yet gotten an error from `recv`, so the main thread -blocked waiting for worker 0 to finish. In the meantime, worker 3 received a -job and then all threads received an error. When worker 0 finished, the main -thread waited for the rest of the workers to finish. At that point, they had -all exited their loops and stopped. +dropped the `sender`, and before any `Worker` received an error, we tried to +join `Worker` 0. `Worker` 0 had not yet gotten an error from `recv`, so the +main thread blocked, waiting for `Worker` 0 to finish. In the meantime, +`Worker` 3 received a job and then all threads received an error. When `Worker` +0 finished, the main thread waited for the rest of the `Worker` instances to +finish. At that point, they had all exited their loops and stopped. Congrats! We’ve now completed our project; we have a basic web server that uses a thread pool to respond asynchronously. We’re able to perform a graceful shutdown of the server, which cleans up all the threads in the pool. See -*https://www.nostarch.com/Rust2021/* to download the full code for this chapter +*https://www.nostarch.com/Rust2021* to download the full code for this chapter for reference. We could do more here! If you want to continue enhancing this project, here are @@ -1934,14 +1980,15 @@ some ideas: * Add tests of the library’s functionality. * Change calls to `unwrap` to more robust error handling. * Use `ThreadPool` to perform some task other than serving web requests. -* Find a thread pool crate on *https://crates.io/* and implement a similar web - server using the crate instead. Then compare its API and robustness to the - thread pool we implemented. +* Find a thread pool crate on *https://crates.io* and implement a similar web +server using the crate instead. Then compare its API and robustness to the +thread pool we implemented. ## Summary Well done! You’ve made it to the end of the book! We want to thank you for joining us on this tour of Rust. You’re now ready to implement your own Rust -projects and help with other peoples’ projects. Keep in mind that there is a +projects and help with other people’s projects. Keep in mind that there is a welcoming community of other Rustaceans who would love to help you with any challenges you encounter on your Rust journey. + diff --git a/src/doc/book/nostarch/frontmatter.md b/src/doc/book/nostarch/frontmatter.md new file mode 100644 index 000000000..001f96483 --- /dev/null +++ b/src/doc/book/nostarch/frontmatter.md @@ -0,0 +1,292 @@ +<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +--> +## About the Authors + +Carol Nichols is a member of the Rust Crates.io Team and a former member of the +Rust Core Team. She’s a co-founder of Integer 32, LLC, the world’s first +Rust-focused software consultancy. Nichols has also organized the Rust Belt +Rust Conference. + +Steve Klabnik was the lead for the Rust documentation team and was one of +Rust’s core developers. A frequent speaker and a prolific open source +contributor, he previously worked on projects such as Ruby and Ruby on Rails. + +## About the Technical Reviewer + +JT is a Rust core team member and the co-creator of the Rust error message +format, Rust Language Server (RLS), and Nushell. They first started using Rust +in 2011, and in 2016 joined Mozilla to work on Rust full time, helping to shape +its direction for widespread use. These days, they are a freelance Rust trainer +and advocate for safe systems programming. + +## Brief Contents + +## Contents in Detail + +## Foreword + +It wasn’t always so clear, but the Rust programming language is fundamentally +about *empowerment*: no matter what kind of code you are writing now, Rust +empowers you to reach further, to program with confidence in a wider variety of +domains than you did before. + +Take, for example, “systems-level†work that deals with low-level details of +memory management, data representation, and concurrency. Traditionally, this +realm of programming is seen as arcane, accessible to only a select few who +have devoted the necessary years learning it to avoid its infamous pitfalls. +And even those who practice it do so with caution, lest their code be open to +exploits, crashes, or corruption. + +Rust breaks down these barriers by eliminating the old pitfalls and providing a +friendly, polished set of tools to help you along the way. Programmers who need +to “dip down†into lower-level control can do so with Rust, without taking on +the customary risk of crashes or security holes and without having to learn the +fine points of a fickle toolchain. Better yet, the language is designed to +guide you naturally toward reliable code that is efficient in terms of speed +and memory usage. + +Programmers who are already working with low-level code can use Rust to raise +their ambitions. For example, introducing parallelism in Rust is a relatively +low-risk operation: the compiler will catch the classical mistakes for you. And +you can tackle more aggressive optimizations in your code with the confidence +that you won’t accidentally introduce crashes or vulnerabilities. + +But Rust isn’t limited to low-level systems programming. It’s expressive and +ergonomic enough to make CLI apps, web servers, and many other kinds of code +quite pleasant to write—you’ll find simple examples later in the book. Working +with Rust allows you to build skills that transfer from one domain to another; +you can learn Rust by writing a web app, then apply those same skills to target +your Raspberry Pi. + +This book fully embraces the potential of Rust to empower its users. It’s a +friendly and approachable text intended to help you level up not just your +knowledge of Rust, but also your reach and confidence as a programmer in +general. So dive in, get ready to learn—and welcome to the Rust community! + +Nicholas Matsakis and Aaron Turon + +## ACKNOWLEDGMENTS + +We would like to thank everyone who has worked on the Rust language for +creating an amazing language worth writing a book about. We’re grateful to +everyone in the Rust community for being welcoming and creating an environment +worth welcoming more folks into. + +We’re especially thankful for everyone who read early versions of this book +online and provided feedback, bug reports, and pull requests. Special thanks to +Eduard-Mihai Burtescu, Alex Crichton, and JT for providing technical review, +and to Karen Rustad Tölva for the cover art. Thank you to our team at No +Starch, including Bill Pollock, Liz Chadwick, and Janelle Ludowise, for +improving this book and bringing it to print. + +Carol is grateful for the opportunity to work on this book. She thanks her +family for their constant love and support, especially her husband, Jake +Goulding, and her daughter, Vivian. + +## Preface + +This version of the text assumes you’re using Rust 1.62.0 (released 2022-06-30) +or later with `edition="2021"` in the *Cargo.toml* file of all projects to +configure them to use Rust 2021 edition idioms. See “Installation†on page XX +for instructions on installing or updating Rust, and see Appendix E for +information on editions. + +The 2021 edition of the Rust language includes a number of improvements that +make Rust more ergonomic and that correct some inconsistencies. On top of a +general update to reflect these improvements, this rendition of the book has a +number of improvements to address specific feedback: + +* Chapter 7 contains a new quick reference section on organizing your code into +multiple files with modules. +* Chapter 13 has new and improved closure examples that more clearly illustrate +captures, the `move` keyword, and the `Fn` traits. +* We fixed a number of small errors and imprecise wording throughout the book. +Thank you to the readers who reported them! + +Note that any code from earlier renditions of this book that compiled will +continue to compile with the relevant edition in the project’s *Cargo.toml*, +even as you update the Rust compiler version you’re using. That’s Rust’s +backward-compatibility guarantees at work! + +## Introduction + +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 only be +caught 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) +integration for code completion and inline error messages. + +By using these and other tools in the Rust ecosystem, developers can be +productive while writing systems-level code. + +### 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 +students’ 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. + +## 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. Chapter 2, Chapter 12, and Chapter 20 are project chapters; the rest are +concept chapters. + +**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. 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 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 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 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 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. + +In **Chapter 20**, we’ll complete a project in which we’ll implement a +low-level multithreaded web server! + +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. + +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. In most situations, we’ll lead you to the correct version of any code +that doesn’t compile. + +## Resources and How to Contribute to This Book + +This book is open source. If you find an error, please don’t hesitate to file +an issue or send a pull request on GitHub at +*https://github.com/rust-lang/book*. Please see *CONTRIBUTING.md* at +*https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md* for more details. + +The source code for the examples in this book, errata, and other information +are available at *https://www.nostarch.com/Rust2021*. + diff --git a/src/doc/book/nostarch/introduction.md b/src/doc/book/nostarch/introduction.md index b3ff9b111..bcaed24c5 100644 --- a/src/doc/book/nostarch/introduction.md +++ b/src/doc/book/nostarch/introduction.md @@ -8,7 +8,7 @@ directory, so all fixes need to be made in `/src/`. # Introduction -Welcome to *The Rust Programming Language*, an introductory book about Rust. +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 @@ -62,12 +62,6 @@ 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. -<!-- with Rust adopted in a lot of really recognizable names, is it worth -namedropping some companies that use Rust significantly? /LC --> -<!-- No, I don't want to show favoritism, and there are lots of politics around -the big companies using Rust that I don't want to get into. I would also worry -about the list getting dated. /Carol --> - ### Open Source Developers Rust is for people who want to build the Rust programming language, community, @@ -119,7 +113,7 @@ 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 +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. @@ -182,10 +176,11 @@ that doesn’t compile. ## Resources and How to Contribute to This Book -This book is open source. If you find an error, please don't hesitate to file +This book is open source. If you find an error, please don’t hesitate to file an issue or send a pull request on GitHub at *https://github.com/rust-lang/book/*. Please see *CONTRIBUTING.md* at *https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md* for more details. The source code for the examples in this book, errata, and other information are available at *https://www.nostarch.com/Rust2021/*. + diff --git a/src/doc/book/nostarch/preface.md b/src/doc/book/nostarch/preface.md index 5ec239151..33b1a0fd8 100644 --- a/src/doc/book/nostarch/preface.md +++ b/src/doc/book/nostarch/preface.md @@ -1,22 +1,22 @@ -# Preface +## Preface This version of the text assumes you’re using Rust 1.62.0 (released 2022-06-30) -or later with edition="2021" in *Cargo.toml* of all projects to use Rust 2021 -Edition idioms. See “Installation†on page 1 to install or update Rust, and see -Appendix E for information on editions. +or later with `edition="2021"` in *Cargo.toml* of all projects to use Rust 2021 +Edition idioms. See “Installation†on page 1 for instructions on installing or +updating Rust, and see Appendix E for information on editions. -The 2021 Edition of the Rust language includes a small number of improvements -that make Rust more ergonomic and correct some inconsistencies. This rendition -of the book has a number of improvements to address feedback: +The 2021 Edition of the Rust language includes a number of improvements that +make Rust more ergonomic and correct some inconsistencies. On top of a general +update to reflect these improvements, this rendition of the book has a number +of improvements to address specific feedback: -• Chapter 7 contains a new quick reference section on organizing your code into +* Chapter 7 contains a new quick reference section on organizing your code into multiple files with modules. -• Chapter 13 has new and improved closure examples that more clearly illustrate +* Chapter 13 has new and improved closure examples that more clearly illustrate captures, the `move` keyword, and the `Fn` traits. -• We fixed a number of small errors and imprecise wording throughout the book. +* We fixed a number of small errors and imprecise wording throughout the book. Thank you to the readers who reported them! - -Note that any code in earlier renditions of this book that compiled will +Note that any code from earlier renditions of this book that compiled will continue to compile with the relevant edition in the project’s *Cargo.toml*, even as you update the Rust compiler version you’re using. That’s Rust’s backward compatibility guarantees at work! diff --git a/src/doc/book/src/appendix-04-useful-development-tools.md b/src/doc/book/src/appendix-04-useful-development-tools.md index b357f64e2..40b076153 100644 --- a/src/doc/book/src/appendix-04-useful-development-tools.md +++ b/src/doc/book/src/appendix-04-useful-development-tools.md @@ -130,14 +130,15 @@ fn main() { Running `cargo clippy` on this project results in this error: ```text -error: approximate value of `f{32, 64}::consts::PI` found. Consider using it directly +error: approximate value of `f{32, 64}::consts::PI` found --> src/main.rs:2:13 | 2 | let x = 3.1415; | ^^^^^^ | - = note: #[deny(clippy::approx_constant)] on by default - = help: for further information visit https://rust-lang-nursery.github.io/rust-clippy/master/index.html#approx_constant + = note: `#[deny(clippy::approx_constant)]` on by default + = help: consider using the constant directly + = help: for further information visit https://rust-lang.github.io/rust-clippy/master/index.html#approx_constant ``` This error lets you know that Rust already has a more precise `PI` constant @@ -171,9 +172,9 @@ communicate with each other. Different clients can use `rust-analyzer`, such as [lsp]: http://langserver.org/ [vscode]: https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer -Visit the `rust-analyzer` project’s [home page][rust-analyzer] for installation -instructions, then install the language server support in your particular IDE. -Your IDE will gain abilities such as autocompletion, jump to definition, and -inline errors. +Visit the `rust-analyzer` project’s [home page][rust-analyzer]<!-- ignore --> +for installation instructions, then install the language server support in your +particular IDE. Your IDE will gain abilities such as autocompletion, jump to +definition, and inline errors. [rust-analyzer]: https://rust-analyzer.github.io diff --git a/src/doc/book/src/appendix-06-translation.md b/src/doc/book/src/appendix-06-translation.md index 0bc6aabd9..2c5734354 100644 --- a/src/doc/book/src/appendix-06-translation.md +++ b/src/doc/book/src/appendix-06-translation.md @@ -24,7 +24,6 @@ For resources in languages other than English. Most are still in progress; see - [Svenska](https://github.com/sebras/book) - [Farsi](https://github.com/pomokhtari/rust-book-fa) - [Deutsch](https://github.com/rust-lang-de/rustbook-de) -- [Turkish](https://github.com/RustDili/dokuman/tree/master/ceviriler), [online](https://rustdili.github.io/) - [हिंदी](https://github.com/venkatarun95/rust-book-hindi) - [ไทย](https://github.com/rust-lang-th/book-th) - [Danske](https://github.com/DanKHansen/book-dk) diff --git a/src/doc/book/src/ch00-00-introduction.md b/src/doc/book/src/ch00-00-introduction.md index ba7b9ea0e..9df8e6c88 100644 --- a/src/doc/book/src/ch00-00-introduction.md +++ b/src/doc/book/src/ch00-00-introduction.md @@ -24,8 +24,8 @@ the most important groups. 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 a variety of subtle bugs, which in most other languages can be -caught only through extensive testing and careful code review by experienced +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 @@ -36,7 +36,8 @@ 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. -* Rustfmt ensures a consistent coding style across developers. +* The Rustfmt formatting tool ensures a consistent coding style across + developers. * The Rust Language Server powers Integrated Development Environment (IDE) integration for code completion and inline error messages. @@ -55,8 +56,8 @@ programming. ### Companies Hundreds of companies, large and small, use Rust in production for a variety of -tasks. Those tasks include command line tools, web services, DevOps tooling, -embedded devices, audio and video analysis and transcoding, cryptocurrencies, +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. @@ -69,13 +70,13 @@ language. ### People Who Value Speed and Stability Rust is for people who crave speed and stability in a language. By speed, we -mean the speed of the programs that you can create with Rust and the speed at -which Rust lets you write them. 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. +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 @@ -96,8 +97,8 @@ reading a book that specifically provides an introduction to programming. 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 topic; we typically revisit the -topic in a later chapter. +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 @@ -106,15 +107,15 @@ far. Chapters 2, 12, and 20 are project chapters; the rest are concept chapters. 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 the Rust language. 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. At first, you -might even want to skip Chapter 3, which covers Rust features similar to those -of other programming languages, and head straight to Chapter 4 to learn about -Rust’s ownership system. However, 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. +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. You’ll use structs and diff --git a/src/doc/book/src/ch01-01-installation.md b/src/doc/book/src/ch01-01-installation.md index 47664eb4f..fa9617ad9 100644 --- a/src/doc/book/src/ch01-01-installation.md +++ b/src/doc/book/src/ch01-01-installation.md @@ -10,18 +10,18 @@ an internet connection for the download. The following steps install the latest stable version of the Rust compiler. Rust’s stability guarantees ensure that all the examples in the book that compile will continue to compile with newer Rust versions. The output might -differ slightly between versions, because Rust often improves error messages -and warnings. In other words, any newer, stable version of Rust you install -using these steps should work as expected with the content of this book. +differ slightly between versions because Rust often improves error messages and +warnings. In other words, any newer, stable version of Rust you install using +these steps should work as expected with the content of this book. > ### Command Line Notation > > In this chapter and throughout the book, we’ll show some commands used in the > terminal. Lines that you should enter in a terminal all start with `$`. You -> don’t need to type in the `$` character; it’s the command line prompt shown -> to indicate the start of each command. Lines that don’t start with `$` -> typically show the output of the previous command. Additionally, -> PowerShell-specific examples will use `>` rather than `$`. +> don’t need to type the `$` character; it’s the command line prompt shown to +> indicate the start of each command. Lines that don’t start with `$` typically +> show the output of the previous command. Additionally, PowerShell-specific +> examples will use `>` rather than `$`. ### Installing `rustup` on Linux or macOS @@ -60,13 +60,14 @@ the `build-essential` package. On Windows, go to [https://www.rust-lang.org/tools/install][install] and follow the instructions for installing Rust. At some point in the installation, you’ll receive a message explaining that you’ll also need the MSVC build tools for -Visual Studio 2013 or later. To acquire the build tools, you’ll need to install -[Visual Studio 2022][visualstudio]. When asked which workloads to install, -include: +Visual Studio 2013 or later. -- “Desktop Development with C++†-- The Windows 10 or 11 SDK -- The English language pack component, along with any other language pack of +To acquire the build tools, you’ll need to install [Visual Studio +2022][visualstudio]. When asked which workloads to install, include: + +* “Desktop Development with C++†+* The Windows 10 or 11 SDK +* The English language pack component, along with any other language pack of your choosing The rest of this book uses commands that work in both *cmd.exe* and PowerShell. @@ -82,15 +83,15 @@ $ rustc --version ``` You should see the version number, commit hash, and commit date for the latest -stable version that has been released in the following format: +stable version that has been released, in the following format: ```text rustc x.y.z (abcabcabc yyyy-mm-dd) ``` If you see this information, you have installed Rust successfully! If you don’t -see this information, check that Rust is in your `%PATH%` -system variable as follows. +see this information, check that Rust is in your `%PATH%` system variable as +follows. In Windows CMD, use: @@ -100,27 +101,24 @@ In Windows CMD, use: In PowerShell, use: -```console +```powershell > echo $env:Path ``` In Linux and macOS, use: ```console -echo $PATH +$ echo $PATH ``` If that’s all correct and Rust still isn’t working, there are a number of -places you can get help. The easiest is the #beginners channel on [the official -Rust Discord][discord]. There, you can chat with other Rustaceans (a silly -nickname we call ourselves) who can help you out. Other great resources include -[the Users forum][users] and [Stack Overflow][stackoverflow]. +places you can get help. Find out how to get in touch with other Rustaceans (a +silly nickname we call ourselves) on [the community page][community]. ### Updating and Uninstalling -Once Rust is installed via `rustup`, when a new version of Rust is released, -updating to the latest version is easy. From your shell, run the following -update script: +Once Rust is installed via `rustup`, updating to a newly released version is +easy. From your shell, run the following update script: ```console $ rustup update @@ -135,9 +133,9 @@ $ rustup self uninstall ### Local Documentation -The installation of Rust also includes a local copy of the documentation, so -you can read it offline. Run `rustup doc` to open the local documentation in -your browser. +The installation of Rust also includes a local copy of the documentation so +that you can read it offline. Run `rustup doc` to open the local documentation +in your browser. Any time a type or function is provided by the standard library and you’re not sure what it does or how to use it, use the application programming interface @@ -146,6 +144,4 @@ sure what it does or how to use it, use the application programming interface [otherinstall]: https://forge.rust-lang.org/infra/other-installation-methods.html [install]: https://www.rust-lang.org/tools/install [visualstudio]: https://visualstudio.microsoft.com/downloads/ -[discord]: https://discord.gg/rust-lang -[users]: https://users.rust-lang.org/ -[stackoverflow]: https://stackoverflow.com/questions/tagged/rust +[community]: https://www.rust-lang.org/community diff --git a/src/doc/book/src/ch01-02-hello-world.md b/src/doc/book/src/ch01-02-hello-world.md index ce9b8f55b..8d8d754d7 100644 --- a/src/doc/book/src/ch01-02-hello-world.md +++ b/src/doc/book/src/ch01-02-hello-world.md @@ -1,8 +1,8 @@ ## Hello, World! -Now that you’ve installed Rust, let’s write your first Rust program. It’s -traditional when learning a new language to write a little program that prints -the text `Hello, world!` to the screen, so we’ll do the same here! +Now that you’ve installed Rust, it’s time to write your first Rust program. +It’s traditional when learning a new language to write a little program that +prints the text `Hello, world!` to the screen, so we’ll do the same here! > Note: This book assumes basic familiarity with the command line. Rust makes > no specific demands about your editing or tooling or where your code lives, so @@ -10,7 +10,7 @@ the text `Hello, world!` to the screen, so we’ll do the same here! > the command line, feel free to use your favorite IDE. Many IDEs now have some > degree of Rust support; check the IDE’s documentation for details. The Rust > team has been focusing on enabling great IDE support via `rust-analyzer`. See -> [Appendix D][devtools]<!-- ignore --> for more details! +> [Appendix D][devtools]<!-- ignore --> for more details. ### Creating a Project Directory @@ -109,7 +109,7 @@ line as the function declaration, adding one space in between. > use an automatic formatter tool called `rustfmt` to format your code in a > particular style (more on `rustfmt` in > [Appendix D][devtools]<!-- ignore -->). The Rust team has included this tool -> with the standard Rust distribution, like `rustc`, so it should already be +> with the standard Rust distribution, as `rustc` is, so it should already be > installed on your computer! The body of the `main` function holds the following code: @@ -126,7 +126,7 @@ First, Rust style is to indent with four spaces, not a tab. Second, `println!` calls a Rust macro. If it had called a function instead, it would be entered as `println` (without the `!`). We’ll discuss Rust macros in more detail in Chapter 19. For now, you just need to know that using a `!` -means that you’re calling a macro instead of a normal function, and that macros +means that you’re calling a macro instead of a normal function and that macros don’t always follow the same rules as functions. Third, you see the `"Hello, world!"` string. We pass this string as an argument @@ -153,16 +153,16 @@ If you have a C or C++ background, you’ll notice that this is similar to `gcc` or `clang`. After compiling successfully, Rust outputs a binary executable. On Linux, macOS, and PowerShell on Windows, you can see the executable by -entering the `ls` command in your shell. On Linux and macOS, you’ll see two -files. With PowerShell on Windows, you’ll see the same three files that you -would see using CMD. +entering the `ls` command in your shell: ```console $ ls main main.rs ``` -With CMD on Windows, you would enter the following: +On Linux and macOS, you’ll see two files. With PowerShell on Windows, you’ll +see the same three files that you would see using CMD. With CMD on Windows, you +would enter the following: ```cmd > dir /B %= the /B option says to only show the file names =% diff --git a/src/doc/book/src/ch01-03-hello-cargo.md b/src/doc/book/src/ch01-03-hello-cargo.md index 9979e76dd..42cd0889c 100644 --- a/src/doc/book/src/ch01-03-hello-cargo.md +++ b/src/doc/book/src/ch01-03-hello-cargo.md @@ -17,7 +17,7 @@ assumes that you’re using Cargo too. Cargo comes installed with Rust if you used the official installers discussed in the [“Installationâ€][installation]<!-- ignore --> section. If you installed Rust through some other means, check whether Cargo is installed by entering the -following into your terminal: +following in your terminal: ```console $ cargo --version @@ -30,9 +30,9 @@ determine how to install Cargo separately. ### Creating a Project with Cargo Let’s create a new project using Cargo and look at how it differs from our -original “Hello, world!†project. Navigate back to your *projects* directory (or -wherever you decided to store your code). Then, on any operating system, run -the following: +original “Hello, world!†project. Navigate back to your *projects* directory +(or wherever you decided to store your code). Then, on any operating system, +run the following: ```console $ cargo new hello_cargo @@ -74,8 +74,8 @@ edition = "2021" <span class="caption">Listing 1-2: Contents of *Cargo.toml* generated by `cargo new`</span> -This file is in the [*TOML*](https://toml.io)<!-- ignore --> (*Tom’s Obvious, -Minimal Language*) format, which is Cargo’s configuration format. +This file is in the [*TOML*][toml]<!-- ignore --> (*Tom’s Obvious, Minimal +Language*) format, which is Cargo’s configuration format. The first line, `[package]`, is a section heading that indicates that the following statements are configuring a package. As we add more information to @@ -102,7 +102,7 @@ fn main() { Cargo has generated a “Hello, world!†program for you, just like the one we wrote in Listing 1-1! So far, the differences between our project and the -project Cargo generated are that Cargo placed the code in the *src* directory, +project Cargo generated are that Cargo placed the code in the *src* directory and we have a *Cargo.toml* configuration file in the top directory. Cargo expects your source files to live inside the *src* directory. The @@ -147,7 +147,7 @@ manages its contents for you. We just built a project with `cargo build` and ran it with `./target/debug/hello_cargo`, but we can also use `cargo run` to compile the -code and then run the resulting executable all in one command: +code and then run the resultant executable all in one command: ```console $ cargo run @@ -184,7 +184,7 @@ $ cargo check ``` Why would you not want an executable? Often, `cargo check` is much faster than -`cargo build`, because it skips the step of producing an executable. If you’re +`cargo build` because it skips the step of producing an executable. If you’re continually checking your work while writing the code, using `cargo check` will speed up the process of letting you know if your project is still compiling! As such, many Rustaceans run `cargo check` periodically as they write their @@ -236,9 +236,7 @@ $ cd someproject $ cargo build ``` -For more information about Cargo, check out [its documentation]. - -[its documentation]: https://doc.rust-lang.org/cargo/ +For more information about Cargo, check out [its documentation][cargo]. ## Summary @@ -257,4 +255,6 @@ If you would rather start by learning how common programming concepts work in Rust, see Chapter 3 and then return to Chapter 2. [installation]: ch01-01-installation.html#installation +[toml]: https://toml.io [appendix-e]: appendix-05-editions.html +[cargo]: https://doc.rust-lang.org/cargo/ diff --git a/src/doc/book/src/ch02-00-guessing-game-tutorial.md b/src/doc/book/src/ch02-00-guessing-game-tutorial.md index bffbc0501..4dac23764 100644 --- a/src/doc/book/src/ch02-00-guessing-game-tutorial.md +++ b/src/doc/book/src/ch02-00-guessing-game-tutorial.md @@ -3,8 +3,8 @@ Let’s jump into Rust by working through a hands-on project together! This chapter introduces you to a few common Rust concepts by showing you how to use them in a real program. You’ll learn about `let`, `match`, methods, associated -functions, using external crates, and more! In the following chapters, we’ll -explore these ideas in more detail. In this chapter, you’ll practice the +functions, external crates, and more! In the following chapters, we’ll explore +these ideas in more detail. In this chapter, you’ll just practice the fundamentals. We’ll implement a classic beginner programming problem: a guessing game. Here’s @@ -34,7 +34,8 @@ cd listings/ch02-guessing-game-tutorial rm -rf no-listing-01-cargo-new cargo new no-listing-01-cargo-new --name guessing_game cd no-listing-01-cargo-new -cargo run +cargo run > output.txt 2>&1 +cd ../../.. --> <span class="filename">Filename: Cargo.toml</span> @@ -83,16 +84,16 @@ prints it</span> This code contains a lot of information, so let’s go over it line by line. To obtain user input and then print the result as output, we need to bring the -`io` input/output library into scope. The `io` library comes from the -standard library, known as `std`: +`io` input/output library into scope. The `io` library comes from the standard +library, known as `std`: ```rust,ignore {{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:io}} ``` -By default, Rust has a set of items defined in the standard library that it brings -into the scope of every program. This set is called the *prelude*, and you can -see everything in it [in the standard library documentation][prelude]. +By default, Rust has a set of items defined in the standard library that it +brings into the scope of every program. This set is called the *prelude*, and +you can see everything in it [in the standard library documentation][prelude]. If a type you want to use isn’t in the prelude, you have to bring that type into scope explicitly with a `use` statement. Using the `std::io` library @@ -106,8 +107,8 @@ program: {{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:main}} ``` -The `fn` syntax declares a new function, the parentheses, `()`, indicate there -are no parameters, and the curly bracket, `{`, starts the body of the function. +The `fn` syntax declares a new function; the parentheses, `()`, indicate there +are no parameters; and the curly bracket, `{`, starts the body of the function. As you also learned in Chapter 1, `println!` is a macro that prints a string to the screen: @@ -136,7 +137,7 @@ let apples = 5; This line creates a new variable named `apples` and binds it to the value 5. In Rust, variables are immutable by default, meaning once we give the variable a -value, the value won't change. We’ll be discussing this concept in detail in +value, the value won’t change. We’ll be discussing this concept in detail in the [“Variables and Mutabilityâ€][variables-and-mutability]<!-- ignore --> section in Chapter 3. To make a variable mutable, we add `mut` before the variable name: @@ -152,7 +153,7 @@ let mut bananas = 5; // mutable Returning to the guessing game program, you now know that `let mut guess` will introduce a mutable variable named `guess`. The equal sign (`=`) tells Rust we -want to bind something to the variable now. On the right of the equals sign is +want to bind something to the variable now. On the right of the equal sign is the value that `guess` is bound to, which is the result of calling `String::new`, a function that returns a new instance of a `String`. [`String`][string]<!-- ignore --> is a string type provided by the standard @@ -161,7 +162,7 @@ library that is a growable, UTF-8 encoded bit of text. The `::` syntax in the `::new` line indicates that `new` is an associated function of the `String` type. An *associated function* is a function that’s implemented on a type, in this case `String`. This `new` function creates a -new, empty string. You’ll find a `new` function on many types, because it’s a +new, empty string. You’ll find a `new` function on many types because it’s a common name for a function that makes a new value of some kind. In full, the `let mut guess = String::new();` line has created a mutable @@ -178,7 +179,7 @@ input: {{#rustdoc_include ../listings/ch02-guessing-game-tutorial/listing-02-01/src/main.rs:read}} ``` -If we hadn’t imported the `io` library with `use std::io` at the beginning of +If we hadn’t imported the `io` library with `use std::io;` at the beginning of the program, we could still use the function by writing this function call as `std::io::stdin`. The `stdin` function returns an instance of [`std::io::Stdin`][iostdin]<!-- ignore -->, which is a type that represents a @@ -198,12 +199,15 @@ let multiple parts of your code access one piece of data without needing to copy that data into memory multiple times. References are a complex feature, and one of Rust’s major advantages is how safe and easy it is to use references. You don’t need to know a lot of those details to finish this -program. For now, all you need to know is that like variables, references are +program. For now, all you need to know is that, like variables, references are immutable by default. Hence, you need to write `&mut guess` rather than `&guess` to make it mutable. (Chapter 4 will explain references more thoroughly.) -### Handling Potential Failure with the `Result` Type +<!-- Old heading. Do not remove or links may break. --> +<a id="handling-potential-failure-with-the-result-type"></a> + +### Handling Potential Failure with `Result` We’re still working on this line of code. We’re now discussing a third line of text, but note that it’s still part of a single logical line of code. The next @@ -230,10 +234,10 @@ ignore --> is an [*enumeration*][enums]<!-- ignore -->, often called an *enum*, which is a type that can be in one of multiple possible states. We call each possible state a *variant*. -Chapter 6 will cover enums in more detail. The purpose of these `Result` types -is to encode error-handling information. +[Chapter 6][enums]<!-- ignore --> will cover enums in more detail. The purpose +of these `Result` types is to encode error-handling information. -`Result`'s variants are `Ok` and `Err`. The `Ok` variant indicates the +`Result`’s variants are `Ok` and `Err`. The `Ok` variant indicates the operation was successful, and inside `Ok` is the successfully generated value. The `Err` variant means the operation failed, and `Err` contains information about how or why the operation failed. @@ -257,9 +261,9 @@ If you don’t call `expect`, the program will compile, but you’ll get a warni Rust warns that you haven’t used the `Result` value returned from `read_line`, indicating that the program hasn’t handled a possible error. -The right way to suppress the warning is to actually write error handling, but -in our case we just want to crash this program when a problem occurs, so we can -use `expect`. You’ll learn about recovering from errors in [Chapter +The right way to suppress the warning is to actually write error-handling code, +but in our case we just want to crash this program when a problem occurs, so we +can use `expect`. You’ll learn about recovering from errors in [Chapter 9][recover]<!-- ignore -->. ### Printing Values with `println!` Placeholders @@ -273,19 +277,21 @@ the code so far: This line prints the string that now contains the user’s input. The `{}` set of curly brackets is a placeholder: think of `{}` as little crab pincers that hold -a value in place. You can print more than one value using curly brackets: the -first set of curly brackets holds the first value listed after the format -string, the second set holds the second value, and so on. Printing multiple -values in one call to `println!` would look like this: +a value in place. When printing the value of a variable, the variable name can +go inside the curly brackets. When printing the result of evaluating an +expression, place empty curly brackets in the format string, then follow the +format string with a comma-separated list of expressions to print in each empty +curly bracket placeholder in the same order. Printing a variable and the result +of an expression in one call to `println!` would look like this: ```rust let x = 5; let y = 10; -println!("x = {} and y = {}", x, y); +println!("x = {x} and y + 2 = {}", y + 2); ``` -This code would print `x = 5 and y = 10`. +This code would print `x = 5 and y = 12`. ### Testing the First Part @@ -324,15 +330,15 @@ said functionality. Remember that a crate is a collection of Rust source code files. The project we’ve been building is a *binary crate*, which is an executable. The `rand` -crate is a *library crate*, which contains code intended to be used in other -programs and can't be executed on its own. +crate is a *library crate*, which contains code that is intended to be used in +other programs and can’t be executed on its own. Cargo’s coordination of external crates is where Cargo really shines. Before we can write code that uses `rand`, we need to modify the *Cargo.toml* file to include the `rand` crate as a dependency. Open that file now and add the -following line to the bottom beneath the `[dependencies]` section header that +following line to the bottom, beneath the `[dependencies]` section header that Cargo created for you. Be sure to specify `rand` exactly as we have here, with -this version number, or the code examples in this tutorial may not work. +this version number, or the code examples in this tutorial may not work: <!-- When updating the version of `rand` used, also update the version of `rand` used in these files so they all match: @@ -343,50 +349,50 @@ this version number, or the code examples in this tutorial may not work. <span class="filename">Filename: Cargo.toml</span> ```toml -{{#include ../listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml:9:}} +{{#include ../listings/ch02-guessing-game-tutorial/listing-02-02/Cargo.toml:8:}} ``` In the *Cargo.toml* file, everything that follows a header is part of that section that continues until another section starts. In `[dependencies]` you tell Cargo which external crates your project depends on and which versions of those crates you require. In this case, we specify the `rand` crate with the -semantic version specifier `0.8.3`. Cargo understands [Semantic +semantic version specifier `0.8.5`. Cargo understands [Semantic Versioning][semver]<!-- ignore --> (sometimes called *SemVer*), which is a -standard for writing version numbers. The number `0.8.3` is actually shorthand -for `^0.8.3`, which means any version that is at least `0.8.3` but below -`0.9.0`. +standard for writing version numbers. The specifier `0.8.5` is actually +shorthand for `^0.8.5`, which means any version that is at least 0.8.5 but +below 0.9.0. Cargo considers these versions to have public APIs compatible with version -`0.8.3`, and this specification ensures you’ll get the latest patch release -that will still compile with the code in this chapter. Any version `0.9.0` or -greater is not guaranteed to have the same API as what the following examples -use. +0.8.5, and this specification ensures you’ll get the latest patch release that +will still compile with the code in this chapter. Any version 0.9.0 or greater +is not guaranteed to have the same API as what the following examples use. Now, without changing any of the code, let’s build the project, as shown in Listing 2-2. <!-- manual-regeneration cd listings/ch02-guessing-game-tutorial/listing-02-02/ +rm Cargo.lock cargo clean cargo build --> ```console $ cargo build Updating crates.io index - Downloaded rand v0.8.3 - Downloaded libc v0.2.86 - Downloaded getrandom v0.2.2 + Downloaded rand v0.8.5 + Downloaded libc v0.2.127 + Downloaded getrandom v0.2.7 Downloaded cfg-if v1.0.0 - Downloaded ppv-lite86 v0.2.10 - Downloaded rand_chacha v0.3.0 - Downloaded rand_core v0.6.2 - Compiling rand_core v0.6.2 - Compiling libc v0.2.86 - Compiling getrandom v0.2.2 + Downloaded ppv-lite86 v0.2.16 + Downloaded rand_chacha v0.3.1 + Downloaded rand_core v0.6.3 + Compiling libc v0.2.127 + Compiling getrandom v0.2.7 Compiling cfg-if v1.0.0 - Compiling ppv-lite86 v0.2.10 - Compiling rand_chacha v0.3.0 - Compiling rand v0.8.3 + Compiling ppv-lite86 v0.2.16 + Compiling rand_core v0.6.3 + Compiling rand_chacha v0.3.1 + Compiling rand v0.8.5 Compiling guessing_game v0.1.0 (file:///projects/guessing_game) Finished dev [unoptimized + debuginfo] target(s) in 2.53s ``` @@ -395,8 +401,8 @@ $ cargo build adding the rand crate as a dependency</span> You may see different version numbers (but they will all be compatible with the -code, thanks to SemVer!), different lines (depending on the operating system), -and the lines may be in a different order. +code, thanks to SemVer!) and different lines (depending on the operating +system), and the lines may be in a different order. When we include an external dependency, Cargo fetches the latest versions of everything that dependency needs from the *registry*, which is a copy of data @@ -416,8 +422,8 @@ about them in your *Cargo.toml* file. Cargo also knows that you haven’t change anything about your code, so it doesn’t recompile that either. With nothing to do, it simply exits. -If you open up the *src/main.rs* file, make a trivial change, and then save it -and build again, you’ll only see two lines of output: +If you open the *src/main.rs* file, make a trivial change, and then save it and +build again, you’ll only see two lines of output: <!-- manual-regeneration cd listings/ch02-guessing-game-tutorial/listing-02-02/ @@ -430,7 +436,7 @@ $ cargo build Finished dev [unoptimized + debuginfo] target(s) in 2.53 secs ``` -These lines show Cargo only updates the build with your tiny change to the +These lines show that Cargo only updates the build with your tiny change to the *src/main.rs* file. Your dependencies haven’t changed, so Cargo knows it can reuse what it has already downloaded and compiled for those. @@ -439,21 +445,21 @@ reuse what it has already downloaded and compiled for those. Cargo has a mechanism that ensures you can rebuild the same artifact every time you or anyone else builds your code: Cargo will use only the versions of the dependencies you specified until you indicate otherwise. For example, say that -next week version 0.8.4 of the `rand` crate comes out, and that version +next week version 0.8.6 of the `rand` crate comes out, and that version contains an important bug fix, but it also contains a regression that will break your code. To handle this, Rust creates the *Cargo.lock* file the first time you run `cargo build`, so we now have this in the *guessing_game* directory. -When you build a project for the first time, Cargo figures out all the -versions of the dependencies that fit the criteria and then writes them to -the *Cargo.lock* file. When you build your project in the future, Cargo will -see that the *Cargo.lock* file exists and use the versions specified there +When you build a project for the first time, Cargo figures out all the versions +of the dependencies that fit the criteria and then writes them to the +*Cargo.lock* file. When you build your project in the future, Cargo will see +that the *Cargo.lock* file exists and will use the versions specified there rather than doing all the work of figuring out versions again. This lets you have a reproducible build automatically. In other words, your project will -remain at `0.8.3` until you explicitly upgrade, thanks to the *Cargo.lock* -file. Because the *Cargo.lock* file is important for reproducible builds, it's -often checked into source control with the rest of the code in your project. +remain at 0.8.5 until you explicitly upgrade, thanks to the *Cargo.lock* file. +Because the *Cargo.lock* file is important for reproducible builds, it’s often +checked into source control with the rest of the code in your project. #### Updating a Crate to Get a New Version @@ -461,9 +467,9 @@ When you *do* want to update a crate, Cargo provides the command `update`, which will ignore the *Cargo.lock* file and figure out all the latest versions that fit your specifications in *Cargo.toml*. Cargo will then write those versions to the *Cargo.lock* file. Otherwise, by default, Cargo will only look -for versions greater than `0.8.3` and less than `0.9.0`. If the `rand` crate -has released the two new versions `0.8.4` and `0.9.0` you would see the -following if you ran `cargo update`: +for versions greater than 0.8.5 and less than 0.9.0. If the `rand` crate has +released the two new versions 0.8.6 and 0.9.0, you would see the following if +you ran `cargo update`: <!-- manual-regeneration cd listings/ch02-guessing-game-tutorial/listing-02-02/ @@ -474,14 +480,13 @@ as a guide to creating the hypothetical output shown here --> ```console $ cargo update Updating crates.io index - Updating rand v0.8.3 -> v0.8.4 + Updating rand v0.8.5 -> v0.8.6 ``` -Cargo ignores the `0.9.0` release. At this point, you would also notice a -change in your *Cargo.lock* file noting that the version of the `rand` crate -you are now using is `0.8.4`. To use `rand` version `0.9.0` or any version in -the `0.9.x` series, you’d have to update the *Cargo.toml* file to look like -this instead: +Cargo ignores the 0.9.0 release. At this point, you would also notice a change +in your *Cargo.lock* file noting that the version of the `rand` crate you are +now using is 0.8.6. To use `rand` version 0.9.0 or any version in the 0.9.*x* +series, you’d have to update the *Cargo.toml* file to look like this instead: ```toml [dependencies] @@ -493,7 +498,7 @@ available and reevaluate your `rand` requirements according to the new version you have specified. There’s a lot more to say about [Cargo][doccargo]<!-- ignore --> and [its -ecosystem][doccratesio]<!-- ignore --> which we’ll discuss in Chapter 14, but +ecosystem][doccratesio]<!-- ignore -->, which we’ll discuss in Chapter 14, but for now, that’s all you need to know. Cargo makes it very easy to reuse libraries, so Rustaceans are able to write smaller projects that are assembled from a number of packages. @@ -512,16 +517,16 @@ update *src/main.rs*, as shown in Listing 2-3. <span class="caption">Listing 2-3: Adding code to generate a random number</span> -First, we add the line `use rand::Rng`. The `Rng` trait defines methods that +First we add the line `use rand::Rng;`. The `Rng` trait defines methods that random number generators implement, and this trait must be in scope for us to use those methods. Chapter 10 will cover traits in detail. Next, we’re adding two lines in the middle. In the first line, we call the `rand::thread_rng` function that gives us the particular random number -generator that we’re going to use: one that is local to the current thread of -execution and seeded by the operating system. Then we call the `gen_range` +generator we’re going to use: one that is local to the current thread of +execution and is seeded by the operating system. Then we call the `gen_range` method on the random number generator. This method is defined by the `Rng` -trait that we brought into scope with the `use rand::Rng` statement. The +trait that we brought into scope with the `use rand::Rng;` statement. The `gen_range` method takes a range expression as an argument and generates a random number in the range. The kind of range expression we’re using here takes the form `start..=end` and is inclusive on the lower and upper bounds, so we @@ -530,7 +535,7 @@ need to specify `1..=100` to request a number between 1 and 100. > Note: You won’t just know which traits to use and which methods and functions > to call from a crate, so each crate has documentation with instructions for > using it. Another neat feature of Cargo is that running the `cargo doc -> --open` command will build documentation provided by all of your dependencies +> --open` command will build documentation provided by all your dependencies > locally and open it in your browser. If you’re interested in other > functionality in the `rand` crate, for example, run `cargo doc --open` and > click `rand` in the sidebar on the left. @@ -577,8 +582,8 @@ You should get different random numbers, and they should all be numbers between ## Comparing the Guess to the Secret Number Now that we have user input and a random number, we can compare them. That step -is shown in Listing 2-4. Note that this code won’t compile quite yet, as we -will explain. +is shown in Listing 2-4. Note that this code won’t compile just yet, as we will +explain. <span class="filename">Filename: src/main.rs</span> @@ -597,7 +602,7 @@ the three outcomes that are possible when you compare two values. Then we add five new lines at the bottom that use the `Ordering` type. The `cmp` method compares two values and can be called on anything that can be compared. It takes a reference to whatever you want to compare with: here it’s -comparing the `guess` to the `secret_number`. Then it returns a variant of the +comparing `guess` to `secret_number`. Then it returns a variant of the `Ordering` enum we brought into scope with the `use` statement. We use a [`match`][match]<!-- ignore --> expression to decide what to do next based on which variant of `Ordering` was returned from the call to `cmp` with the values @@ -607,14 +612,16 @@ A `match` expression is made up of *arms*. An arm consists of a *pattern* to match against, and the code that should be run if the value given to `match` fits that arm’s pattern. Rust takes the value given to `match` and looks through each arm’s pattern in turn. Patterns and the `match` construct are -powerful Rust features that let you express a variety of situations your code -might encounter and make sure that you handle them all. These features will be +powerful Rust features: they let you express a variety of situations your code +might encounter and they make sure you handle them all. These features will be covered in detail in Chapter 6 and Chapter 18, respectively. Let’s walk through an example with the `match` expression we use here. Say that the user has guessed 50 and the randomly generated secret number this time is -38. When the code compares 50 to 38, the `cmp` method will return -`Ordering::Greater`, because 50 is greater than 38. The `match` expression gets +38. + +When the code compares 50 to 38, the `cmp` method will return +`Ordering::Greater` because 50 is greater than 38. The `match` expression gets the `Ordering::Greater` value and starts checking each arm’s pattern. It looks at the first arm’s pattern, `Ordering::Less`, and sees that the value `Ordering::Greater` does not match `Ordering::Less`, so it ignores the code in @@ -626,6 +633,11 @@ arm in this scenario. However, the code in Listing 2-4 won’t compile yet. Let’s try it: +<!-- +The error numbers in this output should be that of the code **WITHOUT** the +anchor or snip comments +--> + ```console {{#include ../listings/ch02-guessing-game-tutorial/listing-02-04/output.txt}} ``` @@ -642,8 +654,8 @@ elsewhere that would cause Rust to infer a different numerical type. The reason for the error is that Rust cannot compare a string and a number type. Ultimately, we want to convert the `String` the program reads as input into a -real number type so we can compare it numerically to the secret number. We do so -by adding this line to the `main` function body: +real number type so we can compare it numerically to the secret number. We do +so by adding this line to the `main` function body: <span class="filename">Filename: src/main.rs</span> @@ -658,12 +670,12 @@ let guess: u32 = guess.trim().parse().expect("Please type a number!"); ``` We create a variable named `guess`. But wait, doesn’t the program already have -a variable named `guess`? It does, but helpfully Rust allows us to *shadow* the -previous value of `guess` with a new one. Shadowing lets us reuse the `guess` +a variable named `guess`? It does, but helpfully Rust allows us to shadow the +previous value of `guess` with a new one. *Shadowing* lets us reuse the `guess` variable name rather than forcing us to create two unique variables, such as -`guess_str` and `guess` for example. We’ll cover this in more detail in Chapter -3, but for now know that this feature is often used when you want to convert a -value from one type to another type. +`guess_str` and `guess`, for example. We’ll cover this in more detail in +[Chapter 3][shadowing]<!-- ignore -->, but for now, know that this feature is +often used when you want to convert a value from one type to another type. We bind this new variable to the expression `guess.trim().parse()`. The `guess` in the expression refers to the original `guess` variable that contained the @@ -674,9 +686,9 @@ string to the `u32`, which can only contain numerical data. The user must press guess, which adds a newline character to the string. For example, if the user types <span class="keystroke">5</span> and presses <span class="keystroke">enter</span>, `guess` looks like this: `5\n`. The `\n` -represents “newlineâ€. (On Windows, pressing <span +represents “newline.†(On Windows, pressing <span class="keystroke">enter</span> results in a carriage return and a newline, -`\r\n`). The `trim` method eliminates `\n` or `\r\n`, resulting in just `5`. +`\r\n`.) The `trim` method eliminates `\n` or `\r\n`, resulting in just `5`. The [`parse` method on strings][parse]<!-- ignore --> converts a string to another type. Here, we use it to convert from a string to a number. We need to @@ -684,25 +696,27 @@ tell Rust the exact number type we want by using `let guess: u32`. The colon (`:`) after `guess` tells Rust we’ll annotate the variable’s type. Rust has a few built-in number types; the `u32` seen here is an unsigned, 32-bit integer. It’s a good default choice for a small positive number. You’ll learn about -other number types in Chapter 3. Additionally, the `u32` annotation in this -example program and the comparison with `secret_number` means that Rust will -infer that `secret_number` should be a `u32` as well. So now the comparison -will be between two values of the same type! +other number types in [Chapter 3][integers]<!-- ignore -->. + +Additionally, the `u32` annotation in this example program and the comparison +with `secret_number` means Rust will infer that `secret_number` should be a +`u32` as well. So now the comparison will be between two values of the same +type! The `parse` method will only work on characters that can logically be converted into numbers and so can easily cause errors. If, for example, the string contained `AðŸ‘%`, there would be no way to convert that to a number. Because it might fail, the `parse` method returns a `Result` type, much as the `read_line` -method does (discussed earlier in [“Handling Potential Failure with the -`Result` Typeâ€](#handling-potential-failure-with-the-result-type)<!-- ignore --->). We’ll treat this `Result` the same way by using the `expect` method -again. If `parse` returns an `Err` `Result` variant because it couldn’t create -a number from the string, the `expect` call will crash the game and print the -message we give it. If `parse` can successfully convert the string to a number, -it will return the `Ok` variant of `Result`, and `expect` will return the -number that we want from the `Ok` value. +method does (discussed earlier in [“Handling Potential Failure with +`Result`â€](#handling-potential-failure-with-result)<!-- ignore-->). We’ll treat +this `Result` the same way by using the `expect` method again. If `parse` +returns an `Err` `Result` variant because it couldn’t create a number from the +string, the `expect` call will crash the game and print the message we give it. +If `parse` can successfully convert the string to a number, it will return the +`Ok` variant of `Result`, and `expect` will return the number that we want from +the `Ok` value. -Let’s run the program now! +Let’s run the program now: <!-- manual-regeneration cd listings/ch02-guessing-game-tutorial/no-listing-03-convert-string-to-number/ @@ -788,8 +802,8 @@ thread 'main' panicked at 'Please type a number!: ParseIntError { kind: InvalidD note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` -Typing `quit` will quit the game, but as you’ll notice so will entering any -other non-number input. This is suboptimal to say the least; we want the game +Typing `quit` will quit the game, but as you’ll notice, so will entering any +other non-number input. This is suboptimal, to say the least; we want the game to also stop when the correct number is guessed. ### Quitting After a Correct Guess @@ -829,7 +843,7 @@ a `match` expression here, as we did with the `Ordering` result of the `cmp` method. If `parse` is able to successfully turn the string into a number, it will -return an `Ok` value that contains the resulting number. That `Ok` value will +return an `Ok` value that contains the resultant number. That `Ok` value will match the first arm’s pattern, and the `match` expression will just return the `num` value that `parse` produced and put inside the `Ok` value. That number will end up right where we want it in the new `guess` variable we’re creating. @@ -891,10 +905,10 @@ secret number. Listing 2-6 shows the final code. <span class="caption">Listing 2-6: Complete guessing game code</span> -## Summary - At this point, you’ve successfully built the guessing game. Congratulations! +## Summary + This project was a hands-on way to introduce you to many new Rust concepts: `let`, `match`, functions, the use of external crates, and more. In the next few chapters, you’ll learn about these concepts in more detail. Chapter 3 @@ -919,4 +933,6 @@ discusses structs and method syntax, and Chapter 6 explains how enums work. [doccargo]: http://doc.crates.io [doccratesio]: http://doc.crates.io/crates-io.html [match]: ch06-02-match.html +[shadowing]: ch03-01-variables-and-mutability.html#shadowing [parse]: ../std/primitive.str.html#method.parse +[integers]: ch03-02-data-types.html#integer-types diff --git a/src/doc/book/src/ch03-00-common-programming-concepts.md b/src/doc/book/src/ch03-00-common-programming-concepts.md index 8495543f3..2e37fad02 100644 --- a/src/doc/book/src/ch03-00-common-programming-concepts.md +++ b/src/doc/book/src/ch03-00-common-programming-concepts.md @@ -12,9 +12,9 @@ them early will give you a strong core to start from. > #### Keywords > -> The Rust language has a set of *keywords* that are reserved for use by -> the language only, much as in other languages. Keep in mind that you cannot -> use these words as names of variables or functions. Most of the keywords have +> The Rust language has a set of *keywords* that are reserved for use by the +> language only, much as in other languages. Keep in mind that you cannot use +> these words as names of variables or functions. Most of the keywords have > special meanings, and you’ll be using them to do various tasks in your Rust > programs; a few have no current functionality associated with them but have > been reserved for functionality that might be added to Rust in the future. You diff --git a/src/doc/book/src/ch03-01-variables-and-mutability.md b/src/doc/book/src/ch03-01-variables-and-mutability.md index ac583f1b2..883a53050 100644 --- a/src/doc/book/src/ch03-01-variables-and-mutability.md +++ b/src/doc/book/src/ch03-01-variables-and-mutability.md @@ -1,7 +1,7 @@ ## Variables and Mutability As mentioned in the [“Storing Values with -Variablesâ€][storing-values-with-variables]<!-- ignore --> section, by default +Variablesâ€][storing-values-with-variables]<!-- ignore --> section, by default, 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. @@ -9,12 +9,11 @@ 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, let’s generate a new project called *variables* -in your *projects* directory by using `cargo new variables`. +that value. To illustrate this, generate a new project called *variables* in +your *projects* directory by using `cargo new variables`. Then, in your new *variables* directory, open *src/main.rs* and replace its -code with the following code. This code won’t compile just yet, we’ll first -examine the immutability error. +code with the following code, which won’t compile just yet: <span class="filename">Filename: src/main.rs</span> @@ -22,8 +21,8 @@ examine the immutability error. {{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-01-variables-are-immutable/src/main.rs}} ``` -Save and run the program using `cargo run`. You should receive an error -message, as shown in this output: +Save and run the program using `cargo run`. You should receive an error message +regarding an immutability error, as shown in this output: ```console {{#include ../listings/ch03-common-programming-concepts/no-listing-01-variables-are-immutable/output.txt}} @@ -34,9 +33,8 @@ 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. -The error message indicates that the cause of the error is that you `` cannot -assign twice to immutable variable `x` ``, because you tried to assign a second -value to the immutable `x` variable. +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. 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 @@ -45,15 +43,16 @@ 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 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 +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. -But mutability can be very useful, and can make code more convenient to write. -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. 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. +But mutability can be very useful, and can make code more convenient to write. +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]<!-- ignore -->. 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. For example, let’s change *src/main.rs* to the following: @@ -69,8 +68,8 @@ When we run the program now, we get this: {{#include ../listings/ch03-common-programming-concepts/no-listing-02-adding-mut/output.txt}} ``` -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 is up to you and +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 is up to you and depends on what you think is clearest in that particular situation. ### Constants @@ -82,9 +81,9 @@ 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. We’re about to cover types and type annotations in the next -section, [“Data Types,â€][data-types]<!-- ignore --> so don’t worry about the -details right now. Just know that you must always annotate the type. +be annotated. We’ll cover types and type annotations in the next section, +[“Data Types,â€][data-types]<!-- ignore -->, 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. @@ -109,11 +108,11 @@ to the value 10,800. See the [Rust Reference’s section on constant evaluation][const-eval] for more information on what operations can be used when declaring constants. -Constants are valid for the entire time a program runs, within the scope they -were declared in. 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 or -the speed of light. +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, 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 @@ -150,7 +149,7 @@ When we run this program, it will output the following: {{#include ../listings/ch03-common-programming-concepts/no-listing-03-shadowing/output.txt}} ``` -Shadowing is different from marking a variable as `mut`, because we’ll get a +Shadowing is different from marking a variable as `mut` because we’ll get a compile-time error if we accidentally try to reassign to this variable without using the `let` keyword. By using `let`, we can perform a few transformations on a value but have the variable be immutable after those transformations have diff --git a/src/doc/book/src/ch03-02-data-types.md b/src/doc/book/src/ch03-02-data-types.md index 47c00adc8..bedf1450c 100644 --- a/src/doc/book/src/ch03-02-data-types.md +++ b/src/doc/book/src/ch03-02-data-types.md @@ -16,9 +16,9 @@ Chapter 2, we must add a type annotation, like this: let guess: u32 = "42".parse().expect("Not a number!"); ``` -If we don’t add the `: u32` type annotation above, Rust will display the -following error, which means the compiler needs more information from us to -know which type we want to use: +If we don’t add the `: u32` type annotation shown in the preceding code, Rust +will display the following error, which means the compiler needs more +information from us to know which type we want to use: ```console {{#include ../listings/ch03-common-programming-concepts/output-only-01-no-type-annotations/output.txt}} @@ -37,7 +37,7 @@ these from other programming languages. Let’s jump into how they work in Rust. An *integer* is a number without a fractional component. We used one integer type in Chapter 2, the `u32` type. This type declaration indicates that the value it’s associated with should be an unsigned integer (signed integer types -start with `i`, instead of `u`) that takes up 32 bits of space. Table 3-1 shows +start with `i` instead of `u`) that takes up 32 bits of space. Table 3-1 shows the built-in integer types in Rust. We can use any of these variants to declare the type of an integer value. @@ -59,9 +59,8 @@ negative—in other words, whether the number needs to have a sign with it represented without a sign (unsigned). It’s like writing numbers on paper: when the sign matters, a number is shown with a plus sign or a minus sign; however, when it’s safe to assume the number is positive, it’s shown with no sign. -Signed numbers are stored using [two’s -complement](https://en.wikipedia.org/wiki/Two%27s_complement)<!-- ignore --> -representation. +Signed numbers are stored using [two’s complement][twos-complement]<!-- ignore +--> representation. Each signed variant can store numbers from -(2<sup>n - 1</sup>) to 2<sup>n - 1</sup> - 1 inclusive, where *n* is the number of bits that variant uses. So an @@ -98,12 +97,12 @@ some sort of collection. > ##### Integer Overflow > > Let’s say you have a variable of type `u8` that can hold values between 0 and -> 255. If you try to change the variable to a value outside of that range, such -> as 256, *integer overflow* will occur, which can result in one of two -> behaviors. When you’re compiling in debug mode, Rust includes checks for -> integer overflow that cause your program to *panic* at runtime if this -> behavior occurs. Rust uses the term panicking when a program exits with an -> error; we’ll discuss panics in more depth in the [“Unrecoverable Errors with +> 255. If you try to change the variable to a value outside that range, such as +> 256, *integer overflow* will occur, which can result in one of two behaviors. +> When you’re compiling in debug mode, Rust includes checks for integer overflow +> that cause your program to *panic* at runtime if this behavior occurs. Rust +> uses the term *panicking* when a program exits with an error; we’ll discuss +> panics in more depth in the [“Unrecoverable Errors with > `panic!`â€][unrecoverable-errors-with-panic]<!-- ignore --> section in Chapter > 9. > @@ -119,19 +118,19 @@ some sort of collection. > To explicitly handle the possibility of overflow, you can use these families > of methods provided by the standard library for primitive numeric types: > -> - Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add` -> - Return the `None` value if there is overflow with the `checked_*` methods -> - Return the value and a boolean indicating whether there was overflow with -> the `overflowing_*` methods -> - Saturate at the value’s minimum or maximum values with `saturating_*` -> methods +> * Wrap in all modes with the `wrapping_*` methods, such as `wrapping_add`. +> * Return the `None` value if there is overflow with the `checked_*` methods. +> * Return the value and a boolean indicating whether there was overflow with +> the `overflowing_*` methods. +> * Saturate at the value’s minimum or maximum values with the `saturating_*` +> methods. #### Floating-Point Types Rust also has two primitive types for *floating-point numbers*, which are numbers with decimal points. Rust’s floating-point types are `f32` and `f64`, which are 32 bits and 64 bits in size, respectively. The default type is `f64` -because on modern CPUs it’s roughly the same speed as `f32` but is capable of +because on modern CPUs, it’s roughly the same speed as `f32` but is capable of more precision. All floating-point types are signed. Here’s an example that shows floating-point numbers in action: @@ -147,9 +146,9 @@ Floating-point numbers are represented according to the IEEE-754 standard. The #### Numeric Operations -Rust supports the basic mathematical operations you’d expect for all of the -number types: addition, subtraction, multiplication, division, and remainder. -Integer division rounds down to the nearest integer. The following code shows +Rust supports the basic mathematical operations you’d expect for all the number +types: addition, subtraction, multiplication, division, and remainder. Integer +division truncates toward zero to the nearest integer. The following code shows how you’d use each numeric operation in a `let` statement: <span class="filename">Filename: src/main.rs</span> @@ -159,8 +158,9 @@ how you’d use each numeric operation in a `let` statement: ``` Each expression in these statements uses a mathematical operator and evaluates -to a single value, which is then bound to a variable. [Appendix B][appendix_b]<!-- ignore --> contains a -list of all operators that Rust provides. +to a single value, which is then bound to a variable. [Appendix +B][appendix_b]<!-- ignore --> contains a list of all operators that Rust +provides. #### The Boolean Type @@ -180,7 +180,7 @@ Flowâ€][control-flow]<!-- ignore --> section. #### The Character Type -Rust’s `char` type is the language’s most primitive alphabetic type. Here’s +Rust’s `char` type is the language’s most primitive alphabetic type. Here are some examples of declaring `char` values: <span class="filename">Filename: src/main.rs</span> @@ -207,9 +207,9 @@ primitive compound types: tuples and arrays. #### The Tuple Type -A tuple is a general way of grouping together a number of values with a variety -of types into one compound type. Tuples have a fixed length: once declared, -they cannot grow or shrink in size. +A *tuple* is a general way of grouping together a number of values with a +variety of types into one compound type. Tuples have a fixed length: once +declared, they cannot grow or shrink in size. We create a tuple by writing a comma-separated list of values inside parentheses. Each position in the tuple has a type, and the types of the @@ -222,7 +222,7 @@ type annotations in this example: {{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-10-tuples/src/main.rs}} ``` -The variable `tup` binds to the entire tuple, because a tuple is considered a +The variable `tup` binds to the entire tuple because a tuple is considered a single compound element. To get the individual values out of a tuple, we can use pattern matching to destructure a tuple value, like this: @@ -234,7 +234,7 @@ use pattern matching to destructure a tuple value, like this: This program first creates a tuple and binds it to the variable `tup`. It then uses a pattern with `let` to take `tup` and turn it into three separate -variables, `x`, `y`, and `z`. This is called *destructuring*, because it breaks +variables, `x`, `y`, and `z`. This is called *destructuring* because it breaks the single tuple into three parts. Finally, the program prints the value of `y`, which is `6.4`. @@ -275,9 +275,9 @@ Arrays are useful when you want your data allocated on the stack rather than the heap (we will discuss the stack and the heap more in [Chapter 4][stack-and-heap]<!-- ignore -->) or when you want to ensure you always have a fixed number of elements. An array isn’t as flexible as the vector type, -though. A vector is a similar collection type provided by the standard library -that *is* allowed to grow or shrink in size. If you’re unsure whether to use an -array or a vector, chances are you should use a vector. [Chapter +though. A *vector* is a similar collection type provided by the standard +library that *is* allowed to grow or shrink in size. If you’re unsure whether +to use an array or a vector, chances are you should use a vector. [Chapter 8][vectors]<!-- ignore --> discusses vectors in more detail. However, arrays are more useful when you know the number of elements will not @@ -324,9 +324,9 @@ like this: {{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-14-array-indexing/src/main.rs}} ``` -In this example, the variable named `first` will get the value `1`, because -that is the value at index `[0]` in the array. The variable named `second` will -get the value `2` from index `[1]` in the array. +In this example, the variable named `first` will get the value `1` because that +is the value at index `[0]` in the array. The variable named `second` will get +the value `2` from index `[1]` in the array. ##### Invalid Array Element Access @@ -341,9 +341,9 @@ Chapter 2, to get an array index from the user: ``` This code compiles successfully. If you run this code using `cargo run` and -enter 0, 1, 2, 3, or 4, the program will print out the corresponding value at -that index in the array. If you instead enter a number past the end of the -array, such as 10, you’ll see output like this: +enter `0`, `1`, `2`, `3`, or `4`, the program will print out the corresponding +value at that index in the array. If you instead enter a number past the end of +the array, such as `10`, you’ll see output like this: <!-- manual-regeneration cd listings/ch03-common-programming-concepts/no-listing-15-invalid-array-access @@ -374,10 +374,10 @@ write readable, safe code that neither panics nor allows invalid memory access. [comparing-the-guess-to-the-secret-number]: ch02-00-guessing-game-tutorial.html#comparing-the-guess-to-the-secret-number +[twos-complement]: https://en.wikipedia.org/wiki/Two%27s_complement [control-flow]: ch03-05-control-flow.html#control-flow [strings]: ch08-02-strings.html#storing-utf-8-encoded-text-with-strings [stack-and-heap]: ch04-01-what-is-ownership.html#the-stack-and-the-heap [vectors]: ch08-01-vectors.html [unrecoverable-errors-with-panic]: ch09-01-unrecoverable-errors-with-panic.html -[wrapping]: ../std/num/struct.Wrapping.html [appendix_b]: appendix-02-operators.md diff --git a/src/doc/book/src/ch03-03-how-functions-work.md b/src/doc/book/src/ch03-03-how-functions-work.md index c698853ce..2b59f0cd4 100644 --- a/src/doc/book/src/ch03-03-how-functions-work.md +++ b/src/doc/book/src/ch03-03-how-functions-work.md @@ -35,8 +35,8 @@ should see the following output: ``` The lines execute in the order in which they appear in the `main` function. -First, the “Hello, world!†message prints, and then `another_function` is -called and its message is printed. +First the “Hello, world!†message prints, and then `another_function` is called +and its message is printed. ### Parameters @@ -108,8 +108,9 @@ understand. Other languages don’t have the same distinctions, so let’s look what statements and expressions are and how their differences affect the bodies of functions. -*Statements* are instructions that perform some action and do not return a -value. *Expressions* evaluate to a resulting value. Let’s look at some examples. +* **Statements** are instructions that perform some action and do not return + a value. +* **Expressions** evaluate to a resultant value. Let’s look at some examples. We’ve actually already used statements and expressions. Creating a variable and assigning a value to it with the `let` keyword is a statement. In Listing 3-1, @@ -172,10 +173,11 @@ This expression: is a block that, in this case, evaluates to `4`. That value gets bound to `y` as part of the `let` statement. Note that the `x + 1` line doesn’t have a -semicolon at the end, unlike most of the lines you’ve seen so far. Expressions -do not include ending semicolons. If you add a semicolon to the end of an -expression, you turn it into a statement, and it will then not return a value. -Keep this in mind as you explore function return values and expressions next. +semicolon at the end, which is unlike most of the lines you’ve seen so far. +Expressions do not include ending semicolons. If you add a semicolon to the end +of an expression, you turn it into a statement, and it will then not return a +value. Keep this in mind as you explore function return values and expressions +next. ### Functions with Return Values @@ -226,7 +228,7 @@ Let’s look at another example: Running this code will print `The value of x is: 6`. But if we place a semicolon at the end of the line containing `x + 1`, changing it from an -expression to a statement, we’ll get an error. +expression to a statement, we’ll get an error: <span class="filename">Filename: src/main.rs</span> @@ -240,7 +242,7 @@ Compiling this code produces an error, as follows: {{#include ../listings/ch03-common-programming-concepts/no-listing-23-statements-dont-return-values/output.txt}} ``` -The main error message, “mismatched types,†reveals the core issue with this +The main error message, `mismatched types`, reveals the core issue with this code. The definition of the function `plus_one` says that it will return an `i32`, but statements don’t evaluate to a value, which is expressed by `()`, the unit type. Therefore, nothing is returned, which contradicts the function diff --git a/src/doc/book/src/ch03-04-comments.md b/src/doc/book/src/ch03-04-comments.md index 6af0ce175..bfb0cfe17 100644 --- a/src/doc/book/src/ch03-04-comments.md +++ b/src/doc/book/src/ch03-04-comments.md @@ -39,4 +39,7 @@ separate line above the code it’s annotating: ``` Rust also has another kind of comment, documentation comments, which we’ll -discuss in the “Publishing a Crate to Crates.io†section of Chapter 14. +discuss in the [“Publishing a Crate to Crates.ioâ€][publishing]<!-- ignore --> +section of Chapter 14. + +[publishing]: ch14-02-publishing-to-crates-io.html diff --git a/src/doc/book/src/ch03-05-control-flow.md b/src/doc/book/src/ch03-05-control-flow.md index 100bfb3e3..60d6b95a9 100644 --- a/src/doc/book/src/ch03-05-control-flow.md +++ b/src/doc/book/src/ch03-05-control-flow.md @@ -1,9 +1,9 @@ ## Control Flow -The ability to run some code depending on if a condition is true, or run some -code repeatedly while a condition is true, are basic building blocks in most -programming languages. The most common constructs that let you control the flow -of execution of Rust code are `if` expressions and loops. +The ability to run some code depending on whether a condition is `true` and to +run some code repeatedly while a condition is `true` are basic building blocks +in most programming languages. The most common constructs that let you control +the flow of execution of Rust code are `if` expressions and loops. ### `if` Expressions @@ -22,17 +22,17 @@ the `if` expression. In the *src/main.rs* file, input the following: All `if` expressions start with the keyword `if`, followed by a condition. In this case, the condition checks whether or not the variable `number` has a -value less than 5. We place the block of code to execute if the condition is true -immediately after the condition inside curly brackets. Blocks of code +value less than 5. We place the block of code to execute if the condition is +`true` immediately after the condition inside curly brackets. Blocks of code associated with the conditions in `if` expressions are sometimes called *arms*, just like the arms in `match` expressions that we discussed in the [“Comparing the Guess to the Secret Numberâ€][comparing-the-guess-to-the-secret-number]<!-- ignore --> section of Chapter 2. -Optionally, we can also include an `else` expression, which we chose -to do here, to give the program an alternative block of code to execute should -the condition evaluate to false. If you don’t provide an `else` expression and -the condition is false, the program will just skip the `if` block and move on +Optionally, we can also include an `else` expression, which we chose to do +here, to give the program an alternative block of code to execute should the +condition evaluate to `false`. If you don’t provide an `else` expression and +the condition is `false`, the program will just skip the `if` block and move on to the next bit of code. Try running this code; you should see the following output: @@ -105,11 +105,11 @@ see the following output: ``` When this program executes, it checks each `if` expression in turn and executes -the first body for which the condition holds true. Note that even though 6 is -divisible by 2, we don’t see the output `number is divisible by 2`, nor do we -see the `number is not divisible by 4, 3, or 2` text from the `else` block. -That’s because Rust only executes the block for the first true condition, and -once it finds one, it doesn’t even check the rest. +the first body for which the condition evaluates to `true`. Note that even +though 6 is divisible by 2, we don’t see the output `number is divisible by 2`, +nor do we see the `number is not divisible by 4, 3, or 2` text from the `else` +block. That’s because Rust only executes the block for the first `true` +condition, and once it finds one, it doesn’t even check the rest. Using too many `else if` expressions can clutter your code, so if you have more than one, you might want to refactor your code. Chapter 6 describes a powerful @@ -171,8 +171,8 @@ if it had to keep track of multiple hypothetical types for any variable. It’s often useful to execute a block of code more than once. For this task, Rust provides several *loops*, which will run through the code inside the loop -body to the end and then start immediately back at the beginning. To -experiment with loops, let’s make a new project called *loops*. +body to the end and then start immediately back at the beginning. To experiment +with loops, let’s make a new project called *loops*. Rust has three kinds of loops: `loop`, `while`, and `for`. Let’s try each one. @@ -191,9 +191,9 @@ like this: ``` When we run this program, we’ll see `again!` printed over and over continuously -until we stop the program manually. Most terminals support the keyboard shortcut -<span class="keystroke">ctrl-c</span> to interrupt a program that is stuck in -a continual loop. Give it a try: +until we stop the program manually. Most terminals support the keyboard +shortcut <span class="keystroke">ctrl-c</span> to interrupt a program that is +stuck in a continual loop. Give it a try: <!-- manual-regeneration cd listings/ch03-common-programming-concepts/no-listing-32-loop @@ -213,10 +213,10 @@ again! ^Cagain! ``` -The symbol `^C` represents where you pressed <span class="keystroke">ctrl-c -</span>. You may or may not see the word `again!` printed after the `^C`, -depending on where the code was in the loop when it received the interrupt -signal. +The symbol `^C` represents where you pressed <span +class="keystroke">ctrl-c</span>. You may or may not see the word `again!` +printed after the `^C`, depending on where the code was in the loop when it +received the interrupt signal. Fortunately, Rust also provides a way to break out of a loop using code. You can place the `break` keyword within the loop to tell the program when to stop @@ -245,18 +245,18 @@ use it, as shown here: Before the loop, we declare a variable named `counter` and initialize it to `0`. Then we declare a variable named `result` to hold the value returned from the loop. On every iteration of the loop, we add `1` to the `counter` variable, -and then check whether the counter is equal to `10`. When it is, we use the +and then check whether the `counter` is equal to `10`. When it is, we use the `break` keyword with the value `counter * 2`. After the loop, we use a semicolon to end the statement that assigns the value to `result`. Finally, we -print the value in `result`, which in this case is 20. +print the value in `result`, which in this case is `20`. #### Loop Labels to Disambiguate Between Multiple Loops If you have loops within loops, `break` and `continue` apply to the innermost -loop at that point. You can optionally specify a *loop label* on a loop that we -can then use with `break` or `continue` to specify that those keywords apply to -the labeled loop instead of the innermost loop. Loop labels must begin with a -single quote. Here’s an example with two nested loops: +loop at that point. You can optionally specify a *loop label* on a loop that +you can then use with `break` or `continue` to specify that those keywords +apply to the labeled loop instead of the innermost loop. Loop labels must begin +with a single quote. Here’s an example with two nested loops: ```rust {{#rustdoc_include ../listings/ch03-common-programming-concepts/no-listing-32-5-loop-labels/src/main.rs}} @@ -274,7 +274,7 @@ doesn’t specify a label will exit the inner loop only. The `break #### Conditional Loops with `while` A program will often need to evaluate a condition within a loop. While the -condition is true, the loop runs. When the condition ceases to be true, the +condition is `true`, the loop runs. When the condition ceases to be `true`, the program calls `break`, stopping the loop. It’s possible to implement behavior like this using a combination of `loop`, `if`, `else`, and `break`; you could try that now in a program, if you’d like. However, this pattern is so common @@ -292,8 +292,8 @@ time, and then, after the loop, print a message and exit. condition holds true</span> This construct eliminates a lot of nesting that would be necessary if you used -`loop`, `if`, `else`, and `break`, and it’s clearer. While a condition holds -true, the code runs; otherwise, it exits the loop. +`loop`, `if`, `else`, and `break`, and it’s clearer. While a condition +evaluates to `true`, the code runs; otherwise, it exits the loop. #### Looping Through a Collection with `for` @@ -312,8 +312,8 @@ using a `while` loop</span> Here, the code counts up through the elements in the array. It starts at index `0`, and then loops until it reaches the final index in the array (that is, -when `index < 5` is no longer true). Running this code will print every element -in the array: +when `index < 5` is no longer `true`). Running this code will print every +element in the array: ```console {{#include ../listings/ch03-common-programming-concepts/listing-03-04/output.txt}} @@ -324,8 +324,8 @@ will reach a value of `5` at some point, the loop stops executing before trying to fetch a sixth value from the array. However, this approach is error prone; we could cause the program to panic if -the index value or test condition are incorrect. For example, if you changed -the definition of the `a` array to have four elements but forgot to update the +the index value or test condition is incorrect. For example, if you changed the +definition of the `a` array to have four elements but forgot to update the condition to `while index < 4`, the code would panic. It’s also slow, because the compiler adds runtime code to perform the conditional check of whether the index is within the bounds of the array on every iteration through the loop. @@ -372,13 +372,13 @@ This code is a bit nicer, isn’t it? ## Summary -You made it! That was a sizable chapter: you learned about variables, scalar -and compound data types, functions, comments, `if` expressions, and loops! -To practice with the concepts discussed in this chapter, try building -programs to do the following: +You made it! This was a sizable chapter: you learned about variables, scalar +and compound data types, functions, comments, `if` expressions, and loops! To +practice with the concepts discussed in this chapter, try building programs to +do the following: * Convert temperatures between Fahrenheit and Celsius. -* Generate the nth Fibonacci number. +* Generate the *n*th Fibonacci number. * Print the lyrics to the Christmas carol “The Twelve Days of Christmas,†taking advantage of the repetition in the song. diff --git a/src/doc/book/src/ch04-01-what-is-ownership.md b/src/doc/book/src/ch04-01-what-is-ownership.md index 94842e1b0..5249c2dd7 100644 --- a/src/doc/book/src/ch04-01-what-is-ownership.md +++ b/src/doc/book/src/ch04-01-what-is-ownership.md @@ -1,8 +1,8 @@ ## What Is Ownership? -*Ownership* is a set of rules that governs how a Rust program manages memory. +*Ownership* is a set of rules that govern how a Rust program manages memory. All programs have to manage the way they use a computer’s memory while running. -Some languages have garbage collection that regularly looks for no-longer used +Some languages have garbage collection that regularly looks for no-longer-used memory as the program runs; in other languages, the programmer must explicitly allocate and free the memory. Rust uses a third approach: memory is managed through a system of ownership with a set of rules that the compiler checks. If @@ -49,14 +49,14 @@ strings. > known, fixed size, you can store the pointer on the stack, but when you want > the actual data, you must follow the pointer. Think of being seated at a > restaurant. When you enter, you state the number of people in your group, and -> the staff finds an empty table that fits everyone and leads you there. If +> the host finds an empty table that fits everyone and leads you there. If > someone in your group comes late, they can ask where you’ve been seated to > find you. > > Pushing to the stack is faster than allocating on the heap because the > allocator never has to search for a place to store new data; that location is > always at the top of the stack. Comparatively, allocating space on the heap -> requires more work, because the allocator must first find a big enough space +> requires more work because the allocator must first find a big enough space > to hold the data and then perform bookkeeping to prepare for the next > allocation. > @@ -122,8 +122,8 @@ valid</span> In other words, there are two important points in time here: -* When `s` comes *into scope*, it is valid. -* It remains valid until it goes *out of scope*. +* When `s` comes *into* scope, it is valid. +* It remains valid until it goes *out of* scope. At this point, the relationship between scopes and when variables are valid is similar to that in other programming languages. Now we’ll build on top of this @@ -133,7 +133,7 @@ understanding by introducing the `String` type. To illustrate the rules of ownership, we need a data type that is more complex than those we covered in the [“Data Typesâ€][data-types]<!-- ignore --> section -of Chapter 3. The types covered previously are all a known size, can be stored +of Chapter 3. The types covered previously are of a known size, can be stored on the stack and popped off the stack when their scope is over, and can be quickly and trivially copied to make a new, independent instance if another part of code needs to use the same value in a different scope. But we want to @@ -162,7 +162,7 @@ let s = String::from("hello"); The double colon `::` operator allows us to namespace this particular `from` function under the `String` type rather than using some sort of name like `string_from`. We’ll discuss this syntax more in the [“Method -Syntaxâ€][method-syntax]<!-- ignore --> section of Chapter 5 and when we talk +Syntaxâ€][method-syntax]<!-- ignore --> section of Chapter 5, and when we talk about namespacing with modules in [“Paths for Referring to an Item in the Module Treeâ€][paths-module-tree]<!-- ignore --> in Chapter 7. @@ -173,7 +173,7 @@ This kind of string *can* be mutated: ``` So, what’s the difference here? Why can `String` be mutated but literals -cannot? The difference is how these two types deal with memory. +cannot? The difference is in how these two types deal with memory. ### Memory and Allocation @@ -189,8 +189,8 @@ we need to allocate an amount of memory on the heap, unknown at compile time, to hold the contents. This means: * The memory must be requested from the memory allocator at runtime. -* We need a way of returning this memory to the allocator when we’re - done with our `String`. +* We need a way of returning this memory to the allocator when we’re done with + our `String`. That first part is done by us: when we call `String::from`, its implementation requests the memory it needs. This is pretty much universal in programming @@ -199,7 +199,7 @@ languages. However, the second part is different. In languages with a *garbage collector (GC)*, the GC keeps track of and cleans up memory that isn’t being used anymore, and we don’t need to think about it. In most languages without a GC, -it’s our responsibility to identify when memory is no longer being used and +it’s our responsibility to identify when memory is no longer being used and to call code to explicitly free it, just as we did to request it. Doing this correctly has historically been a difficult programming problem. If we forget, we’ll waste memory. If we do it too early, we’ll have an invalid variable. If @@ -231,7 +231,10 @@ simple right now, but the behavior of code can be unexpected in more complicated situations when we want to have multiple variables use the data we’ve allocated on the heap. Let’s explore some of those situations now. -#### Ways Variables and Data Interact: Move +<!-- Old heading. Do not remove or links may break. --> +<a id="ways-variables-and-data-interact-move"></a> + +#### Variables and Data Interacting with Move Multiple variables can interact with the same data in different ways in Rust. Let’s look at an example using an integer in Listing 4-2. @@ -265,23 +268,29 @@ the memory that holds the contents of the string, a length, and a capacity. This group of data is stored on the stack. On the right is the memory on the heap that holds the contents. -<img alt="String in memory" src="img/trpl04-01.svg" class="center" style="width: 50%;" /> +<img alt="Two tables: the first table contains the representation of s1 on the +stack, consisting of its length (5), capacity (5), and a pointer to the first +value in the second table. The second table contains the representation of the +string data on the heap, byte by byte." src="img/trpl04-01.svg" class="center" +style="width: 50%;" /> <span class="caption">Figure 4-1: Representation in memory of a `String` holding the value `"hello"` bound to `s1`</span> -The length is how much memory, in bytes, the contents of the `String` is +The length is how much memory, in bytes, the contents of the `String` are currently using. The capacity is the total amount of memory, in bytes, that the -`String` has received from the allocator. The difference between length -and capacity matters, but not in this context, so for now, it’s fine to ignore -the capacity. +`String` has received from the allocator. The difference between length and +capacity matters, but not in this context, so for now, it’s fine to ignore the +capacity. When we assign `s1` to `s2`, the `String` data is copied, meaning we copy the pointer, the length, and the capacity that are on the stack. We do not copy the data on the heap that the pointer refers to. In other words, the data representation in memory looks like Figure 4-2. -<img alt="s1 and s2 pointing to the same value" src="img/trpl04-02.svg" class="center" style="width: 50%;" /> +<img alt="Three tables: tables s1 and s2 representing those strings on the +stack, respectively, and both pointing to the same string data on the heap." +src="img/trpl04-02.svg" class="center" style="width: 50%;" /> <span class="caption">Figure 4-2: Representation in memory of the variable `s2` that has a copy of the pointer, length, and capacity of `s1`</span> @@ -291,7 +300,9 @@ look like if Rust instead copied the heap data as well. If Rust did this, the operation `s2 = s1` could be very expensive in terms of runtime performance if the data on the heap were large. -<img alt="s1 and s2 to two places" src="img/trpl04-03.svg" class="center" style="width: 50%;" /> +<img alt="Four tables: two tables representing the stack data for s1 and s2, +and each points to its own copy of string data on the heap." +src="img/trpl04-03.svg" class="center" style="width: 50%;" /> <span class="caption">Figure 4-3: Another possibility for what `s2 = s1` might do if Rust copied the heap data as well</span> @@ -304,7 +315,7 @@ same memory. This is known as a *double free* error and is one of the memory safety bugs we mentioned previously. Freeing memory twice can lead to memory corruption, which can potentially lead to security vulnerabilities. -To ensure memory safety, after the line `let s2 = s1`, Rust considers `s1` as +To ensure memory safety, after the line `let s2 = s1;`, Rust considers `s1` as no longer valid. Therefore, Rust doesn’t need to free anything when `s1` goes out of scope. Check out what happens when you try to use `s1` after `s2` is created; it won’t work: @@ -323,23 +334,30 @@ invalidated reference: If you’ve heard the terms *shallow copy* and *deep copy* while working with other languages, the concept of copying the pointer, length, and capacity without copying the data probably sounds like making a shallow copy. But -because Rust also invalidates the first variable, instead of calling it a -shallow copy, it’s known as a *move*. In this example, we would say that -`s1` was *moved* into `s2`. So what actually happens is shown in Figure 4-4. +because Rust also invalidates the first variable, instead of being called a +shallow copy, it’s known as a *move*. In this example, we would say that `s1` +was *moved* into `s2`. So, what actually happens is shown in Figure 4-4. -<img alt="s1 moved to s2" src="img/trpl04-04.svg" class="center" style="width: 50%;" /> +<img alt="Three tables: tables s1 and s2 representing those strings on the +stack, respectively, and both pointing to the same string data on the heap. +Table s1 is grayed out be-cause s1 is no longer valid; only s2 can be used to +access the heap data." src="img/trpl04-04.svg" class="center" style="width: +50%;" /> <span class="caption">Figure 4-4: Representation in memory after `s1` has been invalidated</span> -That solves our problem! With only `s2` valid, when it goes out of scope, it +That solves our problem! With only `s2` valid, when it goes out of scope it alone will free the memory, and we’re done. In addition, there’s a design choice that’s implied by this: Rust will never automatically create “deep†copies of your data. Therefore, any *automatic* copying can be assumed to be inexpensive in terms of runtime performance. -#### Ways Variables and Data Interact: Clone +<!-- Old heading. Do not remove or links may break. --> +<a id="ways-variables-and-data-interact-clone"></a> + +#### Variables and Data Interacting with Clone If we *do* want to deeply copy the heap data of the `String`, not just the stack data, we can use a common method called `clone`. We’ll discuss method @@ -361,8 +379,8 @@ different is going on. #### Stack-Only Data: Copy -There’s another wrinkle we haven’t talked about yet. This code using integers – -part of which was shown in Listing 4-2 – works and is valid: +There’s another wrinkle we haven’t talked about yet. This code using +integers—part of which was shown in Listing 4-2—works and is valid: ```rust {{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-06-copy/src/main.rs:here}} @@ -376,7 +394,7 @@ time are stored entirely on the stack, so copies of the actual values are quick to make. That means there’s no reason we would want to prevent `x` from being valid after we create the variable `y`. In other words, there’s no difference between deep and shallow copying here, so calling `clone` wouldn’t do anything -different from the usual shallow copying and we can leave it out. +different from the usual shallow copying, and we can leave it out. Rust has a special annotation called the `Copy` trait that we can place on types that are stored on the stack, as integers are (we’ll talk more about @@ -391,7 +409,7 @@ we’ll get a compile-time error. To learn about how to add the `Copy` annotatio to your type to implement the trait, see [“Derivable Traitsâ€][derivable-traits]<!-- ignore --> in Appendix C. -So what types implement the `Copy` trait? You can check the documentation for +So, what types implement the `Copy` trait? You can check the documentation for the given type to be sure, but as a general rule, any group of simple scalar values can implement `Copy`, and nothing that requires allocation or is some form of resource can implement `Copy`. Here are some of the types that @@ -399,7 +417,7 @@ implement `Copy`: * All the integer types, such as `u32`. * The Boolean type, `bool`, with values `true` and `false`. -* All the floating point types, such as `f64`. +* All the floating-point types, such as `f64`. * The character type, `char`. * Tuples, if they only contain types that also implement `Copy`. For example, `(i32, i32)` implements `Copy`, but `(i32, String)` does not. @@ -427,9 +445,9 @@ the ownership rules prevent you from doing so. ### Return Values and Scope -Returning values can also transfer ownership. Listing 4-4 shows an example -of a function that returns some value, with similar annotations as those in -Listing 4-3. +Returning values can also transfer ownership. Listing 4-4 shows an example of a +function that returns some value, with similar annotations as those in Listing +4-3. <span class="filename">Filename: src/main.rs</span> diff --git a/src/doc/book/src/ch04-02-references-and-borrowing.md b/src/doc/book/src/ch04-02-references-and-borrowing.md index 060c344bb..ea2d8d202 100644 --- a/src/doc/book/src/ch04-02-references-and-borrowing.md +++ b/src/doc/book/src/ch04-02-references-and-borrowing.md @@ -9,9 +9,8 @@ the data stored at that address; that data is owned by some other variable. Unlike a pointer, a reference is guaranteed to point to a valid value of a particular type for the life of that reference. -Here is how you would define and use a `calculate_length` function that -has a reference to an object as a parameter instead of taking ownership of the -value: +Here is how you would define and use a `calculate_length` function that has a +reference to an object as a parameter instead of taking ownership of the value: <span class="filename">Filename: src/main.rs</span> @@ -25,7 +24,9 @@ function return value is gone. Second, note that we pass `&s1` into `String`. These ampersands represent *references*, and they allow you to refer to some value without taking ownership of it. Figure 4-5 depicts this concept. -<img alt="&String s pointing at String s1" src="img/trpl04-05.svg" class="center" /> +<img alt="Three tables: the table for s contains only a pointer to the table +for s1. The table for s1 contains the stack data for s1 and points to the +string data on the heap." src="img/trpl04-05.svg" class="center" /> <span class="caption">Figure 4-5: A diagram of `&String s` pointing at `String s1`</span> @@ -54,7 +55,7 @@ the parameter `s` is a reference. Let’s add some explanatory annotations: The scope in which the variable `s` is valid is the same as any function parameter’s scope, but the value pointed to by the reference is not dropped -when `s` stops being used because `s` doesn’t have ownership. When functions +when `s` stops being used, because `s` doesn’t have ownership. When functions have references as parameters instead of the actual values, we won’t need to return the values in order to give back ownership, because we never had ownership. @@ -63,7 +64,7 @@ We call the action of creating a reference *borrowing*. As in real life, if a person owns something, you can borrow it from them. When you’re done, you have to give it back. You don’t own it. -So what happens if we try to modify something we’re borrowing? Try the code in +So, what happens if we try to modify something we’re borrowing? Try the code in Listing 4-6. Spoiler alert: it doesn’t work! <span class="filename">Filename: src/main.rs</span> @@ -94,7 +95,7 @@ with just a few small tweaks that use, instead, a *mutable reference*: {{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-09-fixes-listing-04-06/src/main.rs}} ``` -First, we change `s` to be `mut`. Then we create a mutable reference with `&mut +First we change `s` to be `mut`. Then we create a mutable reference with `&mut s` where we call the `change` function, and update the function signature to accept a mutable reference with `some_string: &mut String`. This makes it very clear that the `change` function will mutate the value it borrows. @@ -123,7 +124,7 @@ in `r2` that borrows the same data as `r1`. The restriction preventing multiple mutable references to the same data at the same time allows for mutation but in a very controlled fashion. It’s something -that new Rustaceans struggle with, because most languages let you mutate +that new Rustaceans struggle with because most languages let you mutate whenever you’d like. The benefit of having this restriction is that Rust can prevent data races at compile time. A *data race* is similar to a race condition and happens when these three behaviors occur: @@ -133,8 +134,8 @@ condition and happens when these three behaviors occur: * There’s no mechanism being used to synchronize access to the data. Data races cause undefined behavior and can be difficult to diagnose and fix -when you’re trying to track them down at runtime; Rust prevents this problem -by refusing to compile code with data races! +when you’re trying to track them down at runtime; Rust prevents this problem by +refusing to compile code with data races! As always, we can use curly brackets to create a new scope, allowing for multiple mutable references, just not *simultaneous* ones: @@ -175,10 +176,9 @@ occurs before the mutable reference is introduced: The scopes of the immutable references `r1` and `r2` end after the `println!` where they are last used, which is before the mutable reference `r3` is -created. These scopes don’t overlap, so this code is allowed. The ability of -the compiler to tell that a reference is no longer being used at a point before -the end of the scope is called *Non-Lexical Lifetimes* (NLL for short), and you -can read more about it in [The Edition Guide][nll]. +created. These scopes don’t overlap, so this code is allowed: the compiler can +tell that the reference is no longer being used at a point before the end of +the scope. Even though borrowing errors may be frustrating at times, remember that it’s the Rust compiler pointing out a potential bug early (at compile time rather @@ -188,9 +188,9 @@ have to track down why your data isn’t what you thought it was. ### Dangling References In languages with pointers, it’s easy to erroneously create a *dangling -pointer*--a pointer that references a location in memory that may have been -given to someone else--by freeing some memory while preserving a pointer to -that memory. In Rust, by contrast, the compiler guarantees that references will +pointer*—a pointer that references a location in memory that may have been +given to someone else—by freeing some memory while preserving a pointer to that +memory. In Rust, by contrast, the compiler guarantees that references will never be dangling references: if you have a reference to some data, the compiler will ensure that the data will not go out of scope before the reference to the data does. @@ -251,5 +251,3 @@ Let’s recap what we’ve discussed about references: * References must always be valid. Next, we’ll look at a different kind of reference: slices. - -[nll]: https://doc.rust-lang.org/edition-guide/rust-2018/ownership-and-lifetimes/non-lexical-lifetimes.html diff --git a/src/doc/book/src/ch04-03-slices.md b/src/doc/book/src/ch04-03-slices.md index afb6f76b1..6ffb1dc11 100644 --- a/src/doc/book/src/ch04-03-slices.md +++ b/src/doc/book/src/ch04-03-slices.md @@ -32,7 +32,7 @@ byte index value into the `String` parameter</span> Because we need to go through the `String` element by element and check whether a value is a space, we’ll convert our `String` to an array of bytes using the -`as_bytes` method: +`as_bytes` method. ```rust,ignore {{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-07/src/main.rs:as_bytes}} @@ -60,7 +60,7 @@ Because we get a reference to the element from `.iter().enumerate()`, we use Inside the `for` loop, we search for the byte that represents the space by using the byte literal syntax. If we find a space, we return the position. -Otherwise, we return the length of the string by using `s.len()`: +Otherwise, we return the length of the string by using `s.len()`. ```rust,ignore {{#rustdoc_include ../listings/ch04-understanding-ownership/listing-04-07/src/main.rs:inside_for}} @@ -98,8 +98,8 @@ fn second_word(s: &String) -> (usize, usize) { Now we’re tracking a starting *and* an ending index, and we have even more values that were calculated from data in a particular state but aren’t tied to -that state at all. We have three unrelated variables floating around that -need to be kept in sync. +that state at all. We have three unrelated variables floating around that need +to be kept in sync. Luckily, Rust has a solution to this problem: string slices. @@ -117,18 +117,22 @@ using a range within brackets by specifying `[starting_index..ending_index]`, where `starting_index` is the first position in the slice and `ending_index` is one more than the last position in the slice. Internally, the slice data structure stores the starting position and the length of the slice, which -corresponds to `ending_index` minus `starting_index`. So in the case of `let +corresponds to `ending_index` minus `starting_index`. So, in the case of `let world = &s[6..11];`, `world` would be a slice that contains a pointer to the -byte at index 6 of `s` with a length value of 5. +byte at index 6 of `s` with a length value of `5`. Figure 4-6 shows this in a diagram. -<img alt="world containing a pointer to the byte at index 6 of String s and a length 5" src="img/trpl04-06.svg" class="center" style="width: 50%;" /> +<img alt="Three tables: a table representing the stack data of s, which points +to the byte at index 0 in a table of the string data "hello world" on +the heap. The third table rep-resents the stack data of the slice world, which +has a length value of 5 and points to byte 6 of the heap data table." +src="img/trpl04-06.svg" class="center" style="width: 50%;" /> <span class="caption">Figure 4-6: String slice referring to part of a `String`</span> -With Rust’s `..` range syntax, if you want to start at index zero, you can drop +With Rust’s `..` range syntax, if you want to start at index 0, you can drop the value before the two periods. In other words, these are equal: ```rust @@ -178,10 +182,10 @@ slice. The type that signifies “string slice†is written as `&str`: {{#rustdoc_include ../listings/ch04-understanding-ownership/no-listing-18-first-word-slice/src/main.rs:here}} ``` -We get the index for the end of the word in the same way as we did in Listing -4-7, by looking for the first occurrence of a space. When we find a space, we -return a string slice using the start of the string and the index of the space -as the starting and ending indices. +We get the index for the end of the word the same way we did in Listing 4-7, by +looking for the first occurrence of a space. When we find a space, we return a +string slice using the start of the string and the index of the space as the +starting and ending indices. Now when we call `first_word`, we get back a single value that is tied to the underlying data. The value is made up of a reference to the starting point of @@ -193,7 +197,7 @@ Returning a slice would also work for a `second_word` function: fn second_word(s: &String) -> &str { ``` -We now have a straightforward API that’s much harder to mess up, because the +We now have a straightforward API that’s much harder to mess up because the compiler will ensure the references into the `String` remain valid. Remember the bug in the program in Listing 4-8, when we got the index to the end of the first word but then cleared the string so our index was invalid? That code was @@ -224,7 +228,10 @@ reference in `clear` and the immutable reference in `word` from existing at the same time, and compilation fails. Not only has Rust made our API easier to use, but it has also eliminated an entire class of errors at compile time! -#### String Literals Are Slices +<!-- Old heading. Do not remove or links may break. --> +<a id="string-literals-are-slices"></a> + +#### String Literals as Slices Recall that we talked about string literals being stored inside the binary. Now that we know about slices, we can properly understand string literals: @@ -260,10 +267,11 @@ a string slice for the type of the `s` parameter</span> If we have a string slice, we can pass that directly. If we have a `String`, we can pass a slice of the `String` or a reference to the `String`. This flexibility takes advantage of *deref coercions*, a feature we will cover in -the [“Implicit Deref Coercions with Functions and -Methodsâ€][deref-coercions]<!--ignore--> section of Chapter 15. Defining a -function to take a string slice instead of a reference to a `String` makes our -API more general and useful without losing any functionality: +[“Implicit Deref Coercions with Functions and +Methodsâ€][deref-coercions]<!--ignore--> section of Chapter 15. + +Defining a function to take a string slice instead of a reference to a `String` +makes our API more general and useful without losing any functionality: <span class="filename">Filename: src/main.rs</span> @@ -274,14 +282,14 @@ API more general and useful without losing any functionality: ### Other Slices String slices, as you might imagine, are specific to strings. But there’s a -more general slice type, too. Consider this array: +more general slice type too. Consider this array: ```rust let a = [1, 2, 3, 4, 5]; ``` -Just as we might want to refer to a part of a string, we might want to refer -to part of an array. We’d do so like this: +Just as we might want to refer to part of a string, we might want to refer to +part of an array. We’d do so like this: ```rust let a = [1, 2, 3, 4, 5]; diff --git a/src/doc/book/src/ch05-02-example-structs.md b/src/doc/book/src/ch05-02-example-structs.md index a83fa0564..5d33d9cb1 100644 --- a/src/doc/book/src/ch05-02-example-structs.md +++ b/src/doc/book/src/ch05-02-example-structs.md @@ -198,7 +198,7 @@ that expression, and returns ownership of the value. > Note: Calling the `dbg!` macro prints to the standard error console stream > (`stderr`), as opposed to `println!` which prints to the standard output > console stream (`stdout`). We’ll talk more about `stderr` and `stdout` in the -> “[“Writing Error Messages to Standard Error Instead of Standard +> [“Writing Error Messages to Standard Error Instead of Standard > Output†section in Chapter 12][err]<!-- ignore -->. Here’s an example where we’re interested in the value that gets assigned to the diff --git a/src/doc/book/src/ch08-02-strings.md b/src/doc/book/src/ch08-02-strings.md index bf79c3925..9663d36ab 100644 --- a/src/doc/book/src/ch08-02-strings.md +++ b/src/doc/book/src/ch08-02-strings.md @@ -355,7 +355,7 @@ of type `char`, and you can iterate over the result to access each element: ```rust for c in "Зд".chars() { - println!("{}", c); + println!("{c}"); } ``` @@ -371,7 +371,7 @@ appropriate for your domain: ```rust for b in "Зд".bytes() { - println!("{}", b); + println!("{b}"); } ``` diff --git a/src/doc/book/src/ch09-01-unrecoverable-errors-with-panic.md b/src/doc/book/src/ch09-01-unrecoverable-errors-with-panic.md index f5b9fefb8..5675fe3e7 100644 --- a/src/doc/book/src/ch09-01-unrecoverable-errors-with-panic.md +++ b/src/doc/book/src/ch09-01-unrecoverable-errors-with-panic.md @@ -120,21 +120,21 @@ $ RUST_BACKTRACE=1 cargo run thread 'main' panicked at 'index out of bounds: the len is 3 but the index is 99', src/main.rs:4:5 stack backtrace: 0: rust_begin_unwind - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/std/src/panicking.rs:483 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/std/src/panicking.rs:584:5 1: core::panicking::panic_fmt - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/panicking.rs:85 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/panicking.rs:142:14 2: core::panicking::panic_bounds_check - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/panicking.rs:62 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/panicking.rs:84:5 3: <usize as core::slice::index::SliceIndex<[T]>>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/slice/index.rs:255 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/slice/index.rs:242:10 4: core::slice::index::<impl core::ops::index::Index<I> for [T]>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/slice/index.rs:15 - 5: <alloc::vec::Vec<T> as core::ops::index::Index<I>>::index - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/alloc/src/vec.rs:1982 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/slice/index.rs:18:9 + 5: <alloc::vec::Vec<T,A> as core::ops::index::Index<I>>::index + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/alloc/src/vec/mod.rs:2591:9 6: panic::main - at ./src/main.rs:4 + at ./src/main.rs:4:5 7: core::ops::function::FnOnce::call_once - at /rustc/7eac88abb2e57e752f3302f02be5f3ce3d7adfb4/library/core/src/ops/function.rs:227 + at /rustc/e092d0b6b43f2de967af0887873151bb1c0b18d3/library/core/src/ops/function.rs:248:5 note: Some details are omitted, run with `RUST_BACKTRACE=full` for a verbose backtrace. ``` diff --git a/src/doc/book/src/ch09-02-recoverable-errors-with-result.md b/src/doc/book/src/ch09-02-recoverable-errors-with-result.md index 347ef9aa7..2ee006f09 100644 --- a/src/doc/book/src/ch09-02-recoverable-errors-with-result.md +++ b/src/doc/book/src/ch09-02-recoverable-errors-with-result.md @@ -6,9 +6,9 @@ interpret and respond to. For example, if you try to open a file and that operation fails because the file doesn’t exist, you might want to create the file instead of terminating the process. -Recall from [“Handling Potential Failure with the `Result` -Typeâ€][handle_failure]<!-- ignore --> in Chapter 2 that the `Result` enum is -defined as having two variants, `Ok` and `Err`, as follows: +Recall from [“Handling Potential Failure with `Result`â€][handle_failure]<!-- +ignore --> in Chapter 2 that the `Result` enum is defined as having two +variants, `Ok` and `Err`, as follows: ```rust enum Result<T, E> { @@ -532,6 +532,6 @@ Now that we’ve discussed the details of calling `panic!` or returning `Result` let’s return to the topic of how to decide which is appropriate to use in which cases. -[handle_failure]: ch02-00-guessing-game-tutorial.html#handling-potential-failure-with-the-result-type +[handle_failure]: ch02-00-guessing-game-tutorial.html#handling-potential-failure-with-result [trait-objects]: ch17-02-trait-objects.html#using-trait-objects-that-allow-for-values-of-different-types [termination]: ../std/process/trait.Termination.html diff --git a/src/doc/book/src/ch13-02-iterators.md b/src/doc/book/src/ch13-02-iterators.md index 2efa552a8..030ebf48e 100644 --- a/src/doc/book/src/ch13-02-iterators.md +++ b/src/doc/book/src/ch13-02-iterators.md @@ -133,7 +133,7 @@ ownership of the iterator we call it on. consume the iterator. Instead, they produce different iterators by changing some aspect of the original iterator. -Listing 13-17 shows an example of calling the iterator adaptor method `map`, +Listing 13-14 shows an example of calling the iterator adaptor method `map`, which takes a closure to call on each item as the items are iterated through. The `map` method returns a new iterator that produces the modified items. The closure here creates a new iterator in which each item from the vector will be diff --git a/src/doc/book/src/ch14-02-publishing-to-crates-io.md b/src/doc/book/src/ch14-02-publishing-to-crates-io.md index 64885d052..c5b1ac7fc 100644 --- a/src/doc/book/src/ch14-02-publishing-to-crates-io.md +++ b/src/doc/book/src/ch14-02-publishing-to-crates-io.md @@ -442,10 +442,15 @@ yank. For example, if we've published a crate named `guessing_game` version 1.0.1 and we want to yank it, in the project directory for `guessing_game` we'd run: +<!-- manual-regeneration: +cargo yank carol-test --version 2.1.0 +cargo yank carol-test --version 2.1.0 --undo +--> + ```console $ cargo yank --vers 1.0.1 Updating crates.io index - Yank guessing_game:1.0.1 + Yank guessing_game@1.0.1 ``` By adding `--undo` to the command, you can also undo a yank and allow projects @@ -454,7 +459,7 @@ to start depending on a version again: ```console $ cargo yank --vers 1.0.1 --undo Updating crates.io index - Unyank guessing_game_:1.0.1 + Unyank guessing_game@1.0.1 ``` A yank *does not* delete any code. It cannot, for example, delete accidentally diff --git a/src/doc/book/src/ch14-03-cargo-workspaces.md b/src/doc/book/src/ch14-03-cargo-workspaces.md index 942d61b46..7c67331b7 100644 --- a/src/doc/book/src/ch14-03-cargo-workspaces.md +++ b/src/doc/book/src/ch14-03-cargo-workspaces.md @@ -224,9 +224,9 @@ copy output below; the output updating script doesn't handle subdirectories in p ```console $ cargo build Updating crates.io index - Downloaded rand v0.8.3 + Downloaded rand v0.8.5 --snip-- - Compiling rand v0.8.3 + Compiling rand v0.8.5 Compiling add_one v0.1.0 (file:///projects/add/add_one) warning: unused import: `rand` --> add_one/src/lib.rs:1:5 @@ -236,8 +236,7 @@ warning: unused import: `rand` | = note: `#[warn(unused_imports)]` on by default -warning: 1 warning emitted - +warning: `add_one` (lib) generated 1 warning Compiling adder v0.1.0 (file:///projects/add/adder) Finished dev [unoptimized + debuginfo] target(s) in 10.18s ``` @@ -300,14 +299,14 @@ $ cargo test Compiling add_one v0.1.0 (file:///projects/add/add_one) Compiling adder v0.1.0 (file:///projects/add/adder) Finished test [unoptimized + debuginfo] target(s) in 0.27s - Running target/debug/deps/add_one-f0253159197f7841 + Running unittests src/lib.rs (target/debug/deps/add_one-f0253159197f7841) running 1 test test tests::it_works ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s - Running target/debug/deps/adder-49979ff40686fa8e + Running unittests src/main.rs (target/debug/deps/adder-49979ff40686fa8e) running 0 tests @@ -338,7 +337,7 @@ copy output below; the output updating script doesn't handle subdirectories in p ```console $ cargo test -p add_one Finished test [unoptimized + debuginfo] target(s) in 0.00s - Running target/debug/deps/add_one-b3235fea9a156f74 + Running unittests src/lib.rs (target/debug/deps/add_one-b3235fea9a156f74) running 1 test test tests::it_works ... ok diff --git a/src/doc/book/src/ch14-04-installing-binaries.md b/src/doc/book/src/ch14-04-installing-binaries.md index 425cf9c37..fd821f3a0 100644 --- a/src/doc/book/src/ch14-04-installing-binaries.md +++ b/src/doc/book/src/ch14-04-installing-binaries.md @@ -31,14 +31,14 @@ cargo install something you don't have, copy relevant output below ```console $ cargo install ripgrep Updating crates.io index - Downloaded ripgrep v11.0.2 + Downloaded ripgrep v13.0.0 Downloaded 1 crate (243.3 KB) in 0.88s - Installing ripgrep v11.0.2 + Installing ripgrep v13.0.0 --snip-- - Compiling ripgrep v11.0.2 + Compiling ripgrep v13.0.0 Finished release [optimized + debuginfo] target(s) in 3m 10s Installing ~/.cargo/bin/rg - Installed package `ripgrep v11.0.2` (executable `rg`) + Installed package `ripgrep v13.0.0` (executable `rg`) ``` The second-to-last line of the output shows the location and the name of the diff --git a/src/doc/book/src/ch15-00-smart-pointers.md b/src/doc/book/src/ch15-00-smart-pointers.md index 7552dd5d1..9ecdcc835 100644 --- a/src/doc/book/src/ch15-00-smart-pointers.md +++ b/src/doc/book/src/ch15-00-smart-pointers.md @@ -12,7 +12,7 @@ pointer but also have additional metadata and capabilities. The concept of smart pointers isn’t unique to Rust: smart pointers originated in C++ and exist in other languages as well. Rust has a variety of smart pointers defined in the standard library that provide functionality beyond that provided by references. -To explore the general concept, we'll look at a couple of different examples of +To explore the general concept, we’ll look at a couple of different examples of smart pointers, including a *reference counting* smart pointer type. This pointer enables you to allow data to have multiple owners by keeping track of the number of owners and, when no owners remain, cleaning up the data. @@ -21,7 +21,7 @@ Rust, with its concept of ownership and borrowing, has an additional difference between references and smart pointers: while references only borrow data, in many cases, smart pointers *own* the data they point to. -Though we didn't call them as such at the time, we’ve already encountered a few +Though we didn’t call them as such at the time, we’ve already encountered a few smart pointers in this book, including `String` and `Vec<T>` in Chapter 8. Both these types count as smart pointers because they own some memory and allow you to manipulate it. They also have metadata and extra capabilities or guarantees. @@ -32,7 +32,7 @@ Smart pointers are usually implemented using structs. Unlike an ordinary struct, smart pointers implement the `Deref` and `Drop` traits. The `Deref` trait allows an instance of the smart pointer struct to behave like a reference so you can write your code to work with either references or smart pointers. -The `Drop` trait allows you to customize the code that's run when an instance +The `Drop` trait allows you to customize the code that’s run when an instance of the smart pointer goes out of scope. In this chapter, we’ll discuss both traits and demonstrate why they’re important to smart pointers. diff --git a/src/doc/book/src/ch15-01-box.md b/src/doc/book/src/ch15-01-box.md index 030a7842d..838062552 100644 --- a/src/doc/book/src/ch15-01-box.md +++ b/src/doc/book/src/ch15-01-box.md @@ -82,7 +82,7 @@ functionâ€) in Lisp that constructs a new pair from its two arguments. By calling `cons` on a pair consisting of a value and another pair, we can construct cons lists made up of recursive pairs. -For example, here's a pseudocode representation of a cons list containing the +For example, here’s a pseudocode representation of a cons list containing the list 1, 2, 3 with each pair in parentheses: ```text @@ -150,7 +150,7 @@ a recursive enum</span> The error shows this type “has infinite size.†The reason is that we’ve defined `List` with a variant that is recursive: it holds another value of itself directly. As a result, Rust can’t figure out how much space it needs to store a -`List` value. Let’s break down why we get this error. First, we'll look at how +`List` value. Let’s break down why we get this error. First, we’ll look at how Rust decides how much space it needs to store a value of a non-recursive type. #### Computing the Size of a Non-Recursive Type @@ -196,7 +196,7 @@ after doing automatic regeneration, look at listings/ch15-smart-pointers/listing help: insert some indirection (e.g., a `Box`, `Rc`, or `&`) to make `List` representable | 2 | Cons(i32, Box<List>), - | ^^^^ ^ + | ++++ + ``` In this suggestion, “indirection†means that instead of storing a value diff --git a/src/doc/book/src/ch15-02-deref.md b/src/doc/book/src/ch15-02-deref.md index ba0b8990f..23c9fe8bf 100644 --- a/src/doc/book/src/ch15-02-deref.md +++ b/src/doc/book/src/ch15-02-deref.md @@ -73,11 +73,12 @@ Listing 15-6: `Box<i32>`</span> The main difference between Listing 15-7 and Listing 15-6 is that here we set -`y` to be an instance of a box pointing to a copied value of `x` rather than a -reference pointing to the value of `x`. In the last assertion, we can use the -dereference operator to follow the box’s pointer in the same way that we did -when `y` was a reference. Next, we’ll explore what is special about `Box<T>` -that enables us to use the dereference operator by defining our own box type. +`y` to be an instance of a `Box<T>` pointing to a copied value of `x` rather +than a reference pointing to the value of `x`. In the last assertion, we can +use the dereference operator to follow the pointer of the `Box<T>` in the same +way that we did when `y` was a reference. Next, we’ll explore what is special +about `Box<T>` that enables us to use the dereference operator by defining our +own type. ### Defining Our Own Smart Pointer diff --git a/src/doc/book/src/ch15-03-drop.md b/src/doc/book/src/ch15-03-drop.md index 1ab2b86f0..05ab86873 100644 --- a/src/doc/book/src/ch15-03-drop.md +++ b/src/doc/book/src/ch15-03-drop.md @@ -58,7 +58,7 @@ When we run this program, we’ll see the following output: Rust automatically called `drop` for us when our instances went out of scope, calling the code we specified. Variables are dropped in the reverse order of -their creation, so `d` was dropped before `c`. This example's purpose is to +their creation, so `d` was dropped before `c`. This example’s purpose is to give you a visual guide to how the `drop` method works; usually you would specify the cleanup code that your type needs to run rather than a print message. diff --git a/src/doc/book/src/ch15-05-interior-mutability.md b/src/doc/book/src/ch15-05-interior-mutability.md index 74bb02f05..7b5e825d7 100644 --- a/src/doc/book/src/ch15-05-interior-mutability.md +++ b/src/doc/book/src/ch15-05-interior-mutability.md @@ -103,11 +103,11 @@ an immutable value and see why that is useful. #### A Use Case for Interior Mutability: Mock Objects Sometimes during testing a programmer will use a type in place of another type, -in order to observe particular behavior and assert it's implemented correctly. +in order to observe particular behavior and assert it’s implemented correctly. This placeholder type is called a *test double*. Think of it in the sense of a -"stunt double" in filmmaking, where a person steps in and substitutes for an +“stunt double†in filmmaking, where a person steps in and substitutes for an actor to do a particular tricky scene. Test doubles stand in for other types -when we're running tests. *Mock objects* are specific types of test doubles +when we’re running tests. *Mock objects* are specific types of test doubles that record what happens during a test so you can assert that the correct actions took place. @@ -273,7 +273,7 @@ BorrowMutError`. This is how `RefCell<T>` handles violations of the borrowing rules at runtime. Choosing to catch borrowing errors at runtime rather than compile time, as -we've done here, means you'd potentially be finding mistakes in your code later +we’ve done here, means you’d potentially be finding mistakes in your code later in the development process: possibly not until your code was deployed to production. Also, your code would incur a small runtime performance penalty as a result of keeping track of the borrows at runtime rather than compile time. diff --git a/src/doc/book/src/ch15-06-reference-cycles.md b/src/doc/book/src/ch15-06-reference-cycles.md index 4b55d88a6..bef289202 100644 --- a/src/doc/book/src/ch15-06-reference-cycles.md +++ b/src/doc/book/src/ch15-06-reference-cycles.md @@ -117,7 +117,7 @@ up if its `strong_count` is 0. You can also create a *weak reference* to the value within an `Rc<T>` instance by calling `Rc::downgrade` and passing a reference to the `Rc<T>`. Strong references are how you can share ownership of an `Rc<T>` instance. Weak references don’t express an ownership relationship, -and their count doesn't affect when an `Rc<T>` instance is cleaned up. They +and their count doesn’t affect when an `Rc<T>` instance is cleaned up. They won’t cause a reference cycle because any cycle involving some weak references will be broken once the strong reference count of values involved is 0. diff --git a/src/doc/book/src/ch16-01-threads.md b/src/doc/book/src/ch16-01-threads.md index 52947a99b..cfdd0c706 100644 --- a/src/doc/book/src/ch16-01-threads.md +++ b/src/doc/book/src/ch16-01-threads.md @@ -173,7 +173,7 @@ threads run at the same time. We'll often use the `move` keyword with closures passed to `thread::spawn` because the closure will then take ownership of the values it uses from the environment, thus transferring ownership of those values from one thread to -another. In the [“Capturing the Environment with Closuresâ€][capture]<!-- ignore +another. In the [“Capturing References or Moving Ownershipâ€][capture]<!-- ignore --> section of Chapter 13, we discussed `move` in the context of closures. Now, we’ll concentrate more on the interaction between `move` and `thread::spawn`. @@ -278,4 +278,4 @@ ownership rules. With a basic understanding of threads and the thread API, let’s look at what we can *do* with threads. -[capture]: ch13-01-closures.html#capturing-the-environment-with-closures +[capture]: ch13-01-closures.html#capturing-references-or-moving-ownership diff --git a/src/doc/book/src/ch16-03-shared-state.md b/src/doc/book/src/ch16-03-shared-state.md index 41dccfa13..918d162cf 100644 --- a/src/doc/book/src/ch16-03-shared-state.md +++ b/src/doc/book/src/ch16-03-shared-state.md @@ -219,9 +219,9 @@ thread update the final result with its part. Note that if you are doing simple numerical operations, there are types simpler than `Mutex<T>` types provided by the [`std::sync::atomic` module of the -standard library][atomic]. These types provide safe, concurrent, atomic access -to primitive types. We chose to use `Mutex<T>` with a primitive type for this -example so we could concentrate on how `Mutex<T>` works. +standard library][atomic]<!-- ignore -->. These types provide safe, concurrent, +atomic access to primitive types. We chose to use `Mutex<T>` with a primitive +type for this example so we could concentrate on how `Mutex<T>` works. ### Similarities Between `RefCell<T>`/`Rc<T>` and `Mutex<T>`/`Arc<T>` diff --git a/src/doc/book/tools/doc-to-md.sh b/src/doc/book/tools/doc-to-md.sh index cffe4c04b..8c802a71f 100755 --- a/src/doc/book/tools/doc-to-md.sh +++ b/src/doc/book/tools/doc-to-md.sh @@ -7,6 +7,15 @@ find tmp -name '*.docx' -print0 | \ # Extract just the filename so we can reuse it easily. xargs -0 basename -s .docx | \ while IFS= read -r filename; do + # Truncate the `nostarch` dir file and put the "no editing" warning back. + # Tell shellcheck to ignore this because I want the `/src/` printed + # literally, not expanded. + # shellcheck disable=SC2016 + echo '<!-- DO NOT EDIT THIS FILE. + +This file is periodically generated from the content in the `/src/` +directory, so all fixes need to be made in `/src/`. +-->' > "nostarch/$filename.md" # Make a directory to put the XML in. mkdir -p "tmp/$filename" # Unzip the docx to get at the XML. @@ -15,6 +24,6 @@ while IFS= read -r filename; do xsltproc tools/docx-to-md.xsl "tmp/$filename/word/document.xml" | \ # Hard wrap at 80 chars at word bourdaries. fold -w 80 -s | \ - # Remove trailing whitespace and save in the `nostarch` dir for comparison. - sed -e "s/ *$//" > "nostarch/$filename.md" + # Remove trailing whitespace and append to the file in the `nostarch` dir for comparison. + sed -e "s/ *$//" >> "nostarch/$filename.md" done diff --git a/src/doc/book/tools/docx-to-md.xsl b/src/doc/book/tools/docx-to-md.xsl index 637c7a59c..8deec85c9 100644 --- a/src/doc/book/tools/docx-to-md.xsl +++ b/src/doc/book/tools/docx-to-md.xsl @@ -12,14 +12,41 @@ <xsl:template match="w:p[starts-with(w:pPr/w:pStyle/@w:val, 'Contents3')]" /> <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'ChapterStart']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'ChapterNumber']" /> <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'Normal']" /> <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'Standard']" /> <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'AuthorQuery']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BookHalfTitle']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BookTitle0']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BookEdition']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BookAuthor']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'Copyright']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'CopyrightHead']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'CopyrightLOC']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'ProductionDirective0']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'ProductionDirective']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BoxType']" /> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'GraphicSlug']" /> <xsl:template match="w:p[w:pPr[not(w:pStyle)]]" /> + <xsl:variable name="chapternumber" select="//w:p[w:pPr/w:pStyle/@w:val = 'ChapterNumber']/w:r/w:t" /> + <xsl:variable name="appendixnumber" select="//w:p[w:pPr/w:pStyle/@w:val = 'AppendixNumber']/w:r/w:t" /> + <!-- Paragraph styles --> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'AppendixNumber']" > + <xsl:text> [TOC] </xsl:text> + <xsl:text>## Appendix </xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text>: </xsl:text> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'AppendixTitle']"> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + </xsl:template> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'ChapterTitle']"> <xsl:text> [TOC] </xsl:text> <xsl:text># </xsl:text> @@ -27,11 +54,13 @@ <xsl:text> </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'HeadA']"> + + <xsl:template match="w:p[(w:pPr/w:pStyle/@w:val = 'HeadA' or w:pPr/w:pStyle/@w:val = 'FrontmatterTitle') and w:r/w:t]"> <xsl:text>## </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> </xsl:template> + <xsl:template match="w:p[(w:pPr/w:pStyle/@w:val = 'HeadA' or w:pPr/w:pStyle/@w:val = 'FrontmatterTitle') and not(w:r/w:t)]" /> <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'HeadB']"> <xsl:text>### </xsl:text> @@ -51,10 +80,13 @@ <xsl:text> </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'NumListA' or @w:val = 'NumListB']]"> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'NumListA' or @w:val = 'NumListB' or @w:val = 'ListNumber' or @w:val = 'ListNumber0']]"> <xsl:text>1. </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> + <xsl:if test="not(following-sibling::*[1][self::w:p]) or following-sibling::w:p[1][w:pPr/w:pStyle[@w:val != 'NumListA' and @w:val != 'NumListB' and @w:val != 'ListNumber' and @w:val != 'ListNumber0']]"> + <xsl:text> </xsl:text> + </xsl:if> </xsl:template> <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'NumListC']]"> @@ -63,10 +95,27 @@ <xsl:text> </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BulletA' or @w:val = 'BulletB' or @w:val = 'ListPlainA' or @w:val = 'ListPlainB']]"> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BulletA' or @w:val = 'BulletB' or @w:val = 'ListPlainA' or @w:val = 'ListPlainB' or @w:val = 'ListBullet' or @w:val = 'ListPlain' or @w:val = 'ListBullet0']]"> <xsl:text>* </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> + <xsl:if test="not(following-sibling::*[1][self::w:p]) or following-sibling::w:p[1][w:pPr/w:pStyle[@w:val != 'BulletA' and @w:val != 'BulletB' and @w:val != 'ListPlainA' and @w:val != 'ListPlainB' and @w:val != 'ListBullet' and @w:val != 'ListPlain' and @w:val != 'ListBullet0']]"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BoxListBullet']]"> + <xsl:text>> * </xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + <xsl:choose> + <xsl:when test="following-sibling::w:p[1][w:pPr/w:pStyle[@w:val = 'BoxBody']]"> + <xsl:text>> </xsl:text> + </xsl:when> + <xsl:when test="not(following-sibling::*[1][self::w:p])"> + <xsl:text> </xsl:text> + </xsl:when> + </xsl:choose> </xsl:template> <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BulletC' or @w:val = 'ListPlainC']]"> @@ -81,7 +130,13 @@ <xsl:text> </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BodyFirst' or @w:val = 'Body' or @w:val = 'BodyFirstBox' or @w:val = 'BodyBox' or @w:val = '1stPara']]"> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'CodeLabel']]"> + <xsl:text>Filename: </xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BodyFirst' or @w:val = 'Body' or @w:val = 'BodyFirstBox' or @w:val = 'BodyBox' or @w:val = '1stPara' or @w:val = 'ChapterIntro' or @w:val = 'BodyContinued' or @w:val = 'SourceForeword']]"> <xsl:if test=".//w:t"> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> @@ -113,39 +168,172 @@ <xsl:text> ``` </xsl:text> </xsl:template> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'Code' or @w:val = 'CodeWide' or @w:val = 'CodeAnnotated']]"> + <xsl:if test="not(preceding-sibling::*[1][self::w:p]) or preceding-sibling::w:p[1][w:pPr[not(w:pStyle) or (w:pStyle/@w:val != 'Code' and w:pStyle/@w:val != 'CodeWide' and w:pStyle/@w:val != 'CodeAnnotated')]]"> + <xsl:text>``` </xsl:text> + </xsl:if> + + <!-- Don't apply Emphasis/etc templates in code blocks --> + <xsl:for-each select="w:r"> + <xsl:value-of select="w:t" /> + </xsl:for-each> + + <xsl:text> </xsl:text> + + <xsl:if test="not(following-sibling::*[1][self::w:p]) or following-sibling::w:p[1][w:pPr[not(w:pStyle) or (w:pStyle/@w:val != 'Code' and w:pStyle/@w:val != 'CodeWide' and w:pStyle/@w:val != 'CodeAnnotated')]]"> + <xsl:text>``` </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BoxCode']]"> + <xsl:choose> + <xsl:when test="not(preceding-sibling::*[1][self::w:p]) or preceding-sibling::w:p[1][w:pPr[not(w:pStyle) or w:pStyle/@w:val != 'BoxCode']]"> + <xsl:text>> ``` > </xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text>> </xsl:text> + </xsl:otherwise> + </xsl:choose> + + <xsl:apply-templates select="*" /> + + <xsl:choose> + <xsl:when test="following-sibling::w:p[1][w:pPr/w:pStyle/@w:val = 'BoxCode']"> + <xsl:text> </xsl:text> + </xsl:when> + <xsl:when test="following-sibling::w:p[1][w:pPr/w:pStyle/@w:val = 'BoxBody']"> + <xsl:text> > ``` > </xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text> > ``` </xsl:text> + </xsl:otherwise> + </xsl:choose> + </xsl:template> + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'CodeSingle']"> <xsl:text>``` </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> ``` </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'ProductionDirective']"> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'TableTitle']]"> + <xsl:text>Table </xsl:text> + <xsl:value-of select="$chapternumber" /> + <xsl:value-of select="$appendixnumber" /> + <xsl:text>-</xsl:text> + <xsl:number level="any" count="w:p[w:pPr/w:pStyle[@w:val = 'TableTitle']]" /> + <xsl:text>: </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'Caption' or @w:val = 'TableTitle' or @w:val = 'Caption1' or @w:val = 'Listing']]"> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'Caption' or @w:val = 'Caption1' or @w:val = 'Listing' or @w:val = 'CodeListingCaption']]"> + <xsl:text>Listing </xsl:text> + <xsl:value-of select="$chapternumber" /> + <xsl:value-of select="$appendixnumber" /> + <xsl:text>-</xsl:text> + <xsl:number level="any" count="w:p[w:pPr/w:pStyle[@w:val = 'Caption' or @w:val = 'Caption1' or @w:val = 'Listing' or @w:val = 'CodeListingCaption']]" /> + <xsl:text>: </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BlockQuote']]"> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BlockQuote' or @w:val = 'QuotePara']]"> <xsl:text>> </xsl:text> <xsl:apply-templates select="*" /> </xsl:template> - <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BlockText']]"> - <xsl:text> </xsl:text> + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BoxTitle']]"> + <xsl:text>> ### </xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text> > </xsl:text> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle[@w:val = 'BlockText' or @w:val = 'BoxBody']]"> <xsl:text>> </xsl:text> <xsl:apply-templates select="*" /> - <xsl:text> </xsl:text> + <xsl:choose> + <xsl:when test="following-sibling::w:p[1][w:pPr/w:pStyle/@w:val = 'BlockText' or w:pPr/w:pStyle/@w:val = 'BoxBody' or w:pPr/w:pStyle/@w:val = 'BoxListBullet' or w:pPr/w:pStyle/@w:val = 'BoxCode' or w:pPr/w:pStyle/@w:val = 'BoxRunInHead']"> + <xsl:text> > </xsl:text> + </xsl:when> + <xsl:otherwise> + <xsl:text> </xsl:text> + </xsl:otherwise> + </xsl:choose> </xsl:template> <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'Note']"> - <xsl:text>> </xsl:text> + <xsl:text>> Note: </xsl:text> <xsl:apply-templates select="*" /> <xsl:text> </xsl:text> </xsl:template> + <xsl:template match="w:r[w:rPr/w:rStyle/@w:val = 'NoteHead']" /> + + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'RunInHead']"> + <xsl:text>* **</xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text>**: </xsl:text> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'RunInPara']"> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + <xsl:if test="following-sibling::w:p[1][w:pPr/w:pStyle/@w:val != 'RunInHead']"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BoxRunInHead']"> + <xsl:text>> * **</xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text>**: </xsl:text> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'BoxRunInPara']"> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + <xsl:if test="following-sibling::w:p[1][w:pPr/w:pStyle/@w:val != 'BoxRunInHead']"> + <xsl:text>> </xsl:text> + </xsl:if> + </xsl:template> + + <xsl:template match="w:p[w:pPr/w:pStyle/@w:val = 'CaptionLine']"> + <xsl:text>Figure </xsl:text> + <xsl:value-of select="$chapternumber" /> + <xsl:value-of select="$appendixnumber" /> + <xsl:text>-</xsl:text> + <xsl:number level="any" count="w:p[w:pPr/w:pStyle/@w:val = 'CaptionLine']" /> + <xsl:text>: </xsl:text> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="w:tbl"> + <xsl:apply-templates select="*" /> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="w:tr[.//w:pStyle/@w:val = 'TableHeader']"> + <xsl:apply-templates select="*" /> + <xsl:text>| </xsl:text> + <xsl:for-each select="w:tc"> + <xsl:text>|---</xsl:text> + </xsl:for-each> + <xsl:text>| </xsl:text> + </xsl:template> + + <xsl:template match="w:tr"> + <xsl:apply-templates select="*" /> + <xsl:text>| </xsl:text> + </xsl:template> + + <xsl:template match="w:tc"> + <xsl:text>| </xsl:text> + <xsl:apply-templates select=".//w:r" /> + <xsl:text> </xsl:text> + </xsl:template> + + <xsl:template match="w:p[not(w:pPr)]" /> <xsl:template match="w:p"> Unmatched: <xsl:value-of select="w:pPr/w:pStyle/@w:val" /> @@ -163,9 +351,13 @@ Unmatched: <xsl:value-of select="w:pPr/w:pStyle/@w:val" /> <xsl:if test="starts-with(w:t, ' ')"> <xsl:text> </xsl:text> </xsl:if> - <xsl:text>`</xsl:text> + <xsl:if test="not(preceding-sibling::*[1][self::w:r]) or preceding-sibling::w:r[1][not(w:rPr/w:rStyle/@w:val = 'Literal') and not(w:rPr/w:rStyle/@w:val = 'LiteralBold') and not(w:rPr/w:rStyle/@w:val = 'LiteralCaption') and not(w:rPr/w:rStyle/@w:val = 'LiteralBox')]"> + <xsl:text>`</xsl:text> + </xsl:if> <xsl:value-of select="normalize-space(w:t)" /> - <xsl:text>`</xsl:text> + <xsl:if test="not(following-sibling::*[1][self::w:r]) or following-sibling::w:r[1][not(w:rPr/w:rStyle/@w:val = 'Literal') and not(w:rPr/w:rStyle/@w:val = 'LiteralBold') and not(w:rPr/w:rStyle/@w:val = 'LiteralCaption') and not(w:rPr/w:rStyle/@w:val = 'LiteralBox')] or following-sibling::w:r[1][w:rPr/w:rStyle/@w:val = 'Literal' and not(w:t)]"> + <xsl:text>`</xsl:text> + </xsl:if> <xsl:if test="substring(w:t, string-length(w:t)) = ' '"> <xsl:text> </xsl:text> </xsl:if> @@ -176,7 +368,7 @@ Unmatched: <xsl:value-of select="w:pPr/w:pStyle/@w:val" /> </xsl:choose> </xsl:template> - <xsl:template match="w:r[w:rPr/w:rStyle[@w:val = 'EmphasisBold']]"> + <xsl:template match="w:r[w:rPr/w:rStyle[@w:val = 'EmphasisBold' or @w:val = 'Bold']]"> <xsl:choose> <xsl:when test="normalize-space(w:t) != ''"> <xsl:if test="starts-with(w:t, ' ')"> @@ -195,15 +387,41 @@ Unmatched: <xsl:value-of select="w:pPr/w:pStyle/@w:val" /> </xsl:choose> </xsl:template> - <xsl:template match="w:r[w:rPr/w:rStyle[@w:val = 'EmphasisItalic' or @w:val = 'EmphasisItalicBox' or @w:val = 'EmphasisNote' or @w:val = 'EmphasisRevCaption' or @w:val = 'EmphasisRevItal']]"> + <xsl:template match="w:r[w:rPr/w:rStyle[@w:val = 'EmphasisItalic' or @w:val = 'EmphasisItalicBox' or @w:val = 'EmphasisNote' or @w:val = 'EmphasisRevCaption' or @w:val = 'EmphasisRevItal' or @w:val = 'Italic' or @w:val = 'LinkURL']]"> + <xsl:choose> + <xsl:when test="w:t and normalize-space(w:t) != ''"> + <xsl:if test="starts-with(w:t, ' ')"> + <xsl:text> </xsl:text> + </xsl:if> + <xsl:if test="not(preceding-sibling::*[1][self::w:r]) or preceding-sibling::w:r[1][not(w:t) or not(w:rPr/w:rStyle/@w:val = 'EmphasisItalic') and not(w:rPr/w:rStyle/@w:val = 'EmphasisItalicBox') and not(w:rPr/w:rStyle/@w:val = 'EmphasisNote') and not(w:rPr/w:rStyle/@w:val = 'EmphasisRevCaption') and not(w:rPr/w:rStyle/@w:val = 'EmphasisRevItal') and not(w:rPr/w:rStyle/@w:val = 'Italic') and not(w:rPr/w:rStyle/@w:val = 'LinkURL')]"> + <xsl:text>*</xsl:text> + </xsl:if> + + <xsl:value-of select="normalize-space(w:t)" /> + + <xsl:if test="not(following-sibling::*[1][self::w:r]) or following-sibling::w:r[1][not(w:t) or not(w:rPr/w:rStyle/@w:val = 'EmphasisItalic') and not(w:rPr/w:rStyle/@w:val = 'EmphasisItalicBox') and not(w:rPr/w:rStyle/@w:val = 'EmphasisNote') and not(w:rPr/w:rStyle/@w:val = 'EmphasisRevCaption') and not(w:rPr/w:rStyle/@w:val = 'EmphasisRevItal') and not(w:rPr/w:rStyle/@w:val = 'Italic') and not(w:rPr/w:rStyle/@w:val = 'LinkURL')]"> + <xsl:text>*</xsl:text> + </xsl:if> + + <xsl:if test="substring(w:t, string-length(w:t)) = ' '"> + <xsl:text> </xsl:text> + </xsl:if> + </xsl:when> + <xsl:when test="w:t"> + <xsl:text> </xsl:text> + </xsl:when> + </xsl:choose> + </xsl:template> + + <xsl:template match="w:r[w:rPr/w:rStyle[@w:val = 'CodeAnnotation']]"> <xsl:choose> <xsl:when test="normalize-space(w:t) != ''"> <xsl:if test="starts-with(w:t, ' ')"> <xsl:text> </xsl:text> </xsl:if> - <xsl:text>*</xsl:text> + <xsl:text>[</xsl:text> <xsl:value-of select="normalize-space(w:t)" /> - <xsl:text>*</xsl:text> + <xsl:text>]</xsl:text> <xsl:if test="substring(w:t, string-length(w:t)) = ' '"> <xsl:text> </xsl:text> </xsl:if> @@ -214,6 +432,16 @@ Unmatched: <xsl:value-of select="w:pPr/w:pStyle/@w:val" /> </xsl:choose> </xsl:template> + <xsl:template match="w:r[w:rPr/w:rStyle[@w:val = 'Superscript']]"> + <xsl:if test="not(preceding-sibling::*[1][self::w:r]) or preceding-sibling::w:r[1][not(w:t) or not(w:rPr/w:rStyle/@w:val = 'Superscript')]"> + <xsl:text><sup></xsl:text> + </xsl:if> + <xsl:value-of select="w:t" /> + <xsl:if test="not(following-sibling::*[1][self::w:r]) or following-sibling::w:r[1][not(w:t) or not(w:rPr/w:rStyle/@w:val = 'Superscript')]"> + <xsl:text></sup></xsl:text> + </xsl:if> + </xsl:template> + <xsl:template match="w:r"> <xsl:value-of select="w:t" /> </xsl:template> diff --git a/src/doc/embedded-book/CITATION.bib b/src/doc/embedded-book/CITATION.bib new file mode 100644 index 000000000..5bcade5af --- /dev/null +++ b/src/doc/embedded-book/CITATION.bib @@ -0,0 +1,7 @@ +@booklet{embedded-rust-book, + title = {The Embedded Rust Book}, + author = {{Rust on Embedded Devices Working Group} and others}, + date = {}, % intentionally left empty because the book has no 'publication date' + url = {https://docs.rust-embedded.org/book/}, + urldate = {}, % fill this in manually +} diff --git a/src/doc/embedded-book/src/start/registers.md b/src/doc/embedded-book/src/start/registers.md index 09f695a0a..d5bb3e0cc 100644 --- a/src/doc/embedded-book/src/start/registers.md +++ b/src/doc/embedded-book/src/start/registers.md @@ -22,7 +22,7 @@ You may well find that the code you need to access the peripherals in your micro ## Board Crate -A board crate is the perfect starting point, if you're new to embedded Rust. They nicely abstract the HW details that might be overwelming when starting studying this subject, and makes standard tasks easy, like turning a LED on or off. The functionality it exposes varies a lot between boards. Since this book aims at staying hardware agnostic, the board crates won't be covered by this book. +A board crate is the perfect starting point, if you're new to embedded Rust. They nicely abstract the HW details that might be overwhelming when starting studying this subject, and makes standard tasks easy, like turning a LED on or off. The functionality it exposes varies a lot between boards. Since this book aims at staying hardware agnostic, the board crates won't be covered by this book. If you want to experiment with the STM32F3DISCOVERY board, it is highly recommmand to take a look at the [stm32f3-discovery] board crate, which provides functionality to blink the board LEDs, access its compass, bluetooth and more. The [Discovery] book offers a great introduction to the use of a board crate. diff --git a/src/doc/index.md b/src/doc/index.md index 744c7f709..bf08960f3 100644 --- a/src/doc/index.md +++ b/src/doc/index.md @@ -113,6 +113,12 @@ resources useful. [The Reference](reference/index.html) is not a formal spec, but is more detailed and comprehensive than the book. +## The Style Guide + +[The Rust Style Guide](style-guide/index.html) describes the standard formatting of Rust +code. Most developers use rustfmt to format their code, and rustfmt's default +formatting matches this style guide. + ## The Rustonomicon [The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of unsafe diff --git a/src/doc/nomicon/src/subtyping.md b/src/doc/nomicon/src/subtyping.md index 91e870e5e..6f0c12db4 100644 --- a/src/doc/nomicon/src/subtyping.md +++ b/src/doc/nomicon/src/subtyping.md @@ -252,7 +252,7 @@ type of the referent is shared knowledge, which is why adjusting that type in on one place (the reference) can lead to issues. But if you shrink down a reference's lifetime when you hand it to someone, that lifetime information isn't shared in any way. There are now two independent references with independent lifetimes. -There's no way to mess with original reference's lifetime using the other one. +There's no way to mess with the original reference's lifetime using the other one. Or rather, the only way to mess with someone's lifetime is to build a meowing dog. But as soon as you try to build a meowing dog, the lifetime should be wrapped up diff --git a/src/doc/nomicon/src/transmutes.md b/src/doc/nomicon/src/transmutes.md index 1f6d7d568..eea866859 100644 --- a/src/doc/nomicon/src/transmutes.md +++ b/src/doc/nomicon/src/transmutes.md @@ -2,7 +2,7 @@ Get out of our way type system! We're going to reinterpret these bits or die trying! Even though this book is all about doing things that are unsafe, I -really can't emphasize that you should deeply think about finding Another Way +really can't emphasize enough that you should deeply think about finding Another Way than the operations covered in this section. This is really, truly, the most horribly unsafe thing you can do in Rust. The guardrails here are dental floss. diff --git a/src/doc/reference/book.toml b/src/doc/reference/book.toml index 19b9afc79..9fb3730c8 100644 --- a/src/doc/reference/book.toml +++ b/src/doc/reference/book.toml @@ -10,6 +10,8 @@ edit-url-template = "https://github.com/rust-lang/reference/edit/master/{path}" [output.html.redirect] "/expressions/enum-variant-expr.html" = "struct-expr.html" +"/unsafe-blocks.html" = "unsafe-keyword.html" +"/unsafe-functions.html" = "unsafe-keyword.html" [rust] edition = "2021" diff --git a/src/doc/reference/src/SUMMARY.md b/src/doc/reference/src/SUMMARY.md index 82d70d043..4d9cc1d76 100644 --- a/src/doc/reference/src/SUMMARY.md +++ b/src/doc/reference/src/SUMMARY.md @@ -118,8 +118,7 @@ - [Inline assembly](inline-assembly.md) - [Unsafety](unsafety.md) - - [Unsafe functions](unsafe-functions.md) - - [Unsafe blocks](unsafe-blocks.md) + - [The `unsafe` keyword](unsafe-keyword.md) - [Behavior considered undefined](behavior-considered-undefined.md) - [Behavior not considered unsafe](behavior-not-considered-unsafe.md) diff --git a/src/doc/reference/src/attributes.md b/src/doc/reference/src/attributes.md index 857cd7d72..b7c1ef609 100644 --- a/src/doc/reference/src/attributes.md +++ b/src/doc/reference/src/attributes.md @@ -228,6 +228,8 @@ The following is an index of all built-in attributes. - [`link`] — Specifies a native library to link with an `extern` block. - [`link_name`] — Specifies the name of the symbol for functions or statics in an `extern` block. + - [`link_ordinal`] — Specifies the ordinal of the symbol for functions or + statics in an `extern` block. - [`no_link`] — Prevents linking an extern crate. - [`repr`] — Controls type layout. - [`crate_type`] — Specifies the type of crate (library, executable, etc.). @@ -297,6 +299,7 @@ The following is an index of all built-in attributes. [`ignore`]: attributes/testing.md#the-ignore-attribute [`inline`]: attributes/codegen.md#the-inline-attribute [`link_name`]: items/external-blocks.md#the-link_name-attribute +[`link_ordinal`]: items/external-blocks.md#the-link_ordinal-attribute [`link_section`]: abi.md#the-link_section-attribute [`link`]: items/external-blocks.md#the-link-attribute [`macro_export`]: macros-by-example.md#path-based-scope diff --git a/src/doc/reference/src/attributes/codegen.md b/src/doc/reference/src/attributes/codegen.md index 4ebabaccf..3a36a10ca 100644 --- a/src/doc/reference/src/attributes/codegen.md +++ b/src/doc/reference/src/attributes/codegen.md @@ -347,7 +347,7 @@ trait object whose methods are attributed. [target architecture]: ../conditional-compilation.md#target_arch [trait]: ../items/traits.md [undefined behavior]: ../behavior-considered-undefined.md -[unsafe function]: ../unsafe-functions.md +[unsafe function]: ../unsafe-keyword.md [rust-abi]: ../items/external-blocks.md#abi [`core::intrinsics::caller_location`]: ../../core/intrinsics/fn.caller_location.html [`core::panic::Location::caller`]: ../../core/panic/struct.Location.html#method.caller diff --git a/src/doc/reference/src/attributes/derive.md b/src/doc/reference/src/attributes/derive.md index b8909ac71..bb5631f7a 100644 --- a/src/doc/reference/src/attributes/derive.md +++ b/src/doc/reference/src/attributes/derive.md @@ -24,10 +24,6 @@ impl<T: PartialEq> PartialEq for Foo<T> { fn eq(&self, other: &Foo<T>) -> bool { self.a == other.a && self.b == other.b } - - fn ne(&self, other: &Foo<T>) -> bool { - self.a != other.a || self.b != other.b - } } ``` diff --git a/src/doc/reference/src/attributes/diagnostics.md b/src/doc/reference/src/attributes/diagnostics.md index 1dd9363d8..45f9cc440 100644 --- a/src/doc/reference/src/attributes/diagnostics.md +++ b/src/doc/reference/src/attributes/diagnostics.md @@ -184,7 +184,7 @@ Tuple struct fields are ignored. Here is an example: ```rust -#[deprecated(since = "5.2", note = "foo was rarely used. Users should instead use bar")] +#[deprecated(since = "5.2.0", note = "foo was rarely used. Users should instead use bar")] pub fn foo() {} pub fn bar() {} diff --git a/src/doc/reference/src/conditional-compilation.md b/src/doc/reference/src/conditional-compilation.md index 6966cec4f..97840e4f6 100644 --- a/src/doc/reference/src/conditional-compilation.md +++ b/src/doc/reference/src/conditional-compilation.md @@ -191,6 +191,25 @@ Example values: * `"pc"` * `"unknown"` +### `target_has_atomic` + +Key-value option set for each bit width that the target supports +atomic loads, stores, and compare-and-swap operations. + +When this cfg is present, all of the stable [`core::sync::atomic`] APIs are available for +the relevant atomic width. + +[`core::sync::atomic`]: ../core/sync/atomic/index.html + +Possible values: + +* `"8"` +* `"16"` +* `"32"` +* `"64"` +* `"128"` +* `"ptr"` + ### `test` Enabled when compiling the test harness. Done with `rustc` by using the diff --git a/src/doc/reference/src/destructors.md b/src/doc/reference/src/destructors.md index 6d616b3e7..242d9b2db 100644 --- a/src/doc/reference/src/destructors.md +++ b/src/doc/reference/src/destructors.md @@ -158,7 +158,7 @@ smallest scope that contains the expression and is one of the following: * The entire function body. * A statement. -* The body of a [`if`], [`while`] or [`loop`] expression. +* The body of an [`if`], [`while`] or [`loop`] expression. * The `else` block of an `if` expression. * The condition expression of an `if` or `while` expression, or a `match` guard. diff --git a/src/doc/reference/src/expressions.md b/src/doc/reference/src/expressions.md index 32ee658ff..b2411cd8e 100644 --- a/src/doc/reference/src/expressions.md +++ b/src/doc/reference/src/expressions.md @@ -22,6 +22,7 @@ > | [_MethodCallExpression_]\ > | [_FieldExpression_]\ > | [_ClosureExpression_]\ +> | [_AsyncBlockExpression_]\ > | [_ContinueExpression_]\ > | [_BreakExpression_]\ > | [_RangeExpression_]\ @@ -34,7 +35,6 @@ > [_OuterAttribute_]<sup>\*</sup>[†](#expression-attributes)\ > (\ > [_BlockExpression_]\ -> | [_AsyncBlockExpression_]\ > | [_UnsafeBlockExpression_]\ > | [_LoopExpression_]\ > | [_IfExpression_]\ @@ -42,28 +42,24 @@ > | [_MatchExpression_]\ > ) -An expression may have two roles: it always produces a *value*, and it may have -*effects* (otherwise known as "side effects"). An expression *evaluates to* a -value, and has effects during *evaluation*. Many expressions contain -sub-expressions, called the *operands* of the expression. The meaning of each -kind of expression dictates several things: +An expression may have two roles: it always produces a *value*, and it may have *effects* (otherwise known as "side effects"). +An expression *evaluates to* a value, and has effects during *evaluation*. +Many expressions contain sub-expressions, called the *operands* of the expression. +The meaning of each kind of expression dictates several things: * Whether or not to evaluate the operands when evaluating the expression * The order in which to evaluate the operands * How to combine the operands' values to obtain the value of the expression In this way, the structure of expressions dictates the structure of execution. -Blocks are just another kind of expression, so blocks, statements, expressions, -and blocks again can recursively nest inside each other to an arbitrary depth. +Blocks are just another kind of expression, so blocks, statements, expressions, and blocks again can recursively nest inside each other to an arbitrary depth. -> **Note**: We give names to the operands of expressions so that we may discuss -> them, but these names are not stable and may be changed. +> **Note**: We give names to the operands of expressions so that we may discuss them, but these names are not stable and may be changed. ## Expression precedence -The precedence of Rust operators and expressions is ordered as follows, going -from strong to weak. Binary Operators at the same precedence level are grouped -in the order given by their associativity. +The precedence of Rust operators and expressions is ordered as follows, going from strong to weak. +Binary Operators at the same precedence level are grouped in the order given by their associativity. | Operator/Expression | Associativity | |-----------------------------|---------------------| @@ -89,9 +85,8 @@ in the order given by their associativity. ## Evaluation order of operands -The following list of expressions all evaluate their operands the same way, as -described after the list. Other expressions either don't take operands or -evaluate them conditionally as described on their respective pages. +The following list of expressions all evaluate their operands the same way, as described after the list. +Other expressions either don't take operands or evaluate them conditionally as described on their respective pages. * Dereference expression * Error propagation expression @@ -113,15 +108,13 @@ evaluate them conditionally as described on their respective pages. * Range expression * Return expression -The operands of these expressions are evaluated prior to applying the effects of -the expression. Expressions taking multiple operands are evaluated left to right -as written in the source code. +The operands of these expressions are evaluated prior to applying the effects of the expression. +Expressions taking multiple operands are evaluated left to right as written in the source code. > **Note**: Which subexpressions are the operands of an expression is > determined by expression precedence as per the previous section. -For example, the two `next` method calls will always be called in the same -order: +For example, the two `next` method calls will always be called in the same order: ```rust # // Using vec instead of array to avoid references @@ -134,23 +127,18 @@ assert_eq!( ); ``` -> **Note**: Since this is applied recursively, these expressions are also -> evaluated from innermost to outermost, ignoring siblings until there are no -> inner subexpressions. +> **Note**: Since this is applied recursively, these expressions are also evaluated from innermost to outermost, ignoring siblings until there are no inner subexpressions. ## Place Expressions and Value Expressions -Expressions are divided into two main categories: place expressions and value -expressions; there is also a third, minor category of expressions called -assignee expressions. Within each expression, operands may likewise occur in -either place context or value context. The evaluation of an expression depends -both on its own category and the context it occurs within. +Expressions are divided into two main categories: place expressions and value expressions; +there is also a third, minor category of expressions called assignee expressions. +Within each expression, operands may likewise occur in either place context or value context. +The evaluation of an expression depends both on its own category and the context it occurs within. -A *place expression* is an expression that represents a memory location. These -expressions are [paths] which refer to local variables, [static variables], -[dereferences][deref] (`*expr`), [array indexing] expressions (`expr[expr]`), -[field] references (`expr.f`) and parenthesized place expressions. All other -expressions are value expressions. +A *place expression* is an expression that represents a memory location. +These expressions are [paths] which refer to local variables, [static variables], [dereferences][deref] (`*expr`), [array indexing] expressions (`expr[expr]`), [field] references (`expr.f`) and parenthesized place expressions. +All other expressions are value expressions. A *value expression* is an expression that represents an actual value. @@ -166,11 +154,10 @@ The following contexts are *place expression* contexts: expression. * The base of a [functional update] struct expression. -> Note: Historically, place expressions were called *lvalues* and value -> expressions were called *rvalues*. +> Note: Historically, place expressions were called *lvalues* and value expressions were called *rvalues*. -An *assignee expression* is an expression that appears in the left operand of an -[assignment][assign] expression. Explicitly, the assignee expressions are: +An *assignee expression* is an expression that appears in the left operand of an [assignment][assign] expression. +Explicitly, the assignee expressions are: - Place expressions. - [Underscores][_UnderscoreExpression_]. @@ -185,59 +172,49 @@ Arbitrary parenthesisation is permitted inside assignee expressions. ### Moved and copied types -When a place expression is evaluated in a value expression context, or is bound -by value in a pattern, it denotes the value held _in_ that memory location. If -the type of that value implements [`Copy`], then the value will be copied. In -the remaining situations, if that type is [`Sized`], then it may be possible to -move the value. Only the following place expressions may be moved out of: +When a place expression is evaluated in a value expression context, or is bound by value in a pattern, it denotes the value held _in_ that memory location. +If the type of that value implements [`Copy`], then the value will be copied. +In the remaining situations, if that type is [`Sized`], then it may be possible to move the value. +Only the following place expressions may be moved out of: * [Variables] which are not currently borrowed. * [Temporary values](#temporaries). -* [Fields][field] of a place expression which can be moved out of and - don't implement [`Drop`]. -* The result of [dereferencing][deref] an expression with type [`Box<T>`] and - that can also be moved out of. +* [Fields][field] of a place expression which can be moved out of and don't implement [`Drop`]. +* The result of [dereferencing][deref] an expression with type [`Box<T>`] and that can also be moved out of. -After moving out of a place expression that evaluates to a local variable, the -location is deinitialized and cannot be read from again until it is -reinitialized. In all other cases, trying to use a place expression in a value -expression context is an error. +After moving out of a place expression that evaluates to a local variable, the location is deinitialized and cannot be read from again until it is reinitialized. +In all other cases, trying to use a place expression in a value expression context is an error. ### Mutability -For a place expression to be [assigned][assign] to, mutably [borrowed][borrow], -[implicitly mutably borrowed], or bound to a pattern containing `ref mut`, it -must be _mutable_. We call these *mutable place expressions*. In contrast, -other place expressions are called *immutable place expressions*. +For a place expression to be [assigned][assign] to, mutably [borrowed][borrow], [implicitly mutably borrowed], or bound to a pattern containing `ref mut`, it must be _mutable_. +We call these *mutable place expressions*. +In contrast, other place expressions are called *immutable place expressions*. The following expressions can be mutable place expression contexts: * Mutable [variables] which are not currently borrowed. * [Mutable `static` items]. * [Temporary values]. -* [Fields][field]: this evaluates the subexpression in a mutable place - expression context. +* [Fields][field]: this evaluates the subexpression in a mutable place expression context. * [Dereferences][deref] of a `*mut T` pointer. -* Dereference of a variable, or field of a variable, with type `&mut T`. Note: - This is an exception to the requirement of the next rule. -* Dereferences of a type that implements `DerefMut`: this then requires that - the value being dereferenced is evaluated in a mutable place expression context. -* [Array indexing] of a type that implements `IndexMut`: this - then evaluates the value being indexed, but not the index, in mutable place - expression context. +* Dereference of a variable, or field of a variable, with type `&mut T`. + Note: This is an exception to the requirement of the next rule. +* Dereferences of a type that implements `DerefMut`: + this then requires that the value being dereferenced is evaluated in a mutable place expression context. +* [Array indexing] of a type that implements `IndexMut`: + this then evaluates the value being indexed, but not the index, in mutable place expression context. ### Temporaries -When using a value expression in most place expression contexts, a temporary -unnamed memory location is created and initialized to that value. The expression -evaluates to that location instead, except if [promoted] to a `static`. The -[drop scope] of the temporary is usually the end of the enclosing statement. +When using a value expression in most place expression contexts, a temporary unnamed memory location is created and initialized to that value. +The expression evaluates to that location instead, except if [promoted] to a `static`. +The [drop scope] of the temporary is usually the end of the enclosing statement. ### Implicit Borrows -Certain expressions will treat an expression as a place expression by implicitly -borrowing it. For example, it is possible to compare two unsized [slices][slice] for -equality directly, because the `==` operator implicitly borrows its operands: +Certain expressions will treat an expression as a place expression by implicitly borrowing it. +For example, it is possible to compare two unsized [slices][slice] for equality directly, because the `==` operator implicitly borrows its operands: ```rust # let c = [1, 2, 3]; @@ -264,31 +241,21 @@ Implicit borrows may be taken in the following expressions: ## Overloading Traits -Many of the following operators and expressions can also be overloaded for -other types using traits in `std::ops` or `std::cmp`. These traits also -exist in `core::ops` and `core::cmp` with the same names. +Many of the following operators and expressions can also be overloaded for other types using traits in `std::ops` or `std::cmp`. +These traits also exist in `core::ops` and `core::cmp` with the same names. ## Expression Attributes -[Outer attributes][_OuterAttribute_] before an expression are allowed only in -a few specific cases: +[Outer attributes][_OuterAttribute_] before an expression are allowed only in a few specific cases: * Before an expression used as a [statement]. -* Elements of [array expressions], [tuple expressions], [call expressions], - and tuple-style [struct] expressions. - <!-- - These were likely stabilized inadvertently. - See https://github.com/rust-lang/rust/issues/32796 and - https://github.com/rust-lang/rust/issues/15701 - --> +* Elements of [array expressions], [tuple expressions], [call expressions], and tuple-style [struct] expressions. * The tail expression of [block expressions]. <!-- Keep list in sync with block-expr.md --> They are never allowed before: * [Range][_RangeExpression_] expressions. -* Binary operator expressions ([_ArithmeticOrLogicalExpression_], - [_ComparisonExpression_], [_LazyBooleanExpression_], [_TypeCastExpression_], - [_AssignmentExpression_], [_CompoundAssignmentExpression_]). +* Binary operator expressions ([_ArithmeticOrLogicalExpression_], [_ComparisonExpression_], [_LazyBooleanExpression_], [_TypeCastExpression_], [_AssignmentExpression_], [_CompoundAssignmentExpression_]). [block expressions]: expressions/block-expr.md diff --git a/src/doc/reference/src/expressions/block-expr.md b/src/doc/reference/src/expressions/block-expr.md index a68b27e56..bd9c0a623 100644 --- a/src/doc/reference/src/expressions/block-expr.md +++ b/src/doc/reference/src/expressions/block-expr.md @@ -103,7 +103,7 @@ Async contexts are established by async blocks as well as the bodies of async fu Async blocks act like a function boundary, much like closures. Therefore, the `?` operator and `return` expressions both affect the output of the future, not the enclosing function or other context. -That is, `return <expr>` from within a closure will return the result of `<expr>` as the output of the future. +That is, `return <expr>` from within an async block will return the result of `<expr>` as the output of the future. Similarly, if `<expr>?` propagates an error, that error is propagated as the result of the future. Finally, the `break` and `continue` keywords cannot be used to branch out from an async block. @@ -112,7 +112,7 @@ Therefore the following is illegal: ```rust,compile_fail loop { async move { - break; // This would break out of the loop. + break; // error[E0267]: `break` inside of an `async` block } } ``` @@ -140,6 +140,10 @@ unsafe { let a = unsafe { an_unsafe_fn() }; ``` +## Labelled block expressions + +Labelled block expressions are documented in the [Loops and other breakable expressions] section. + ## Attributes on block expressions [Inner attributes] are allowed directly after the opening brace of a block expression in the following situations: @@ -189,3 +193,4 @@ fn is_unix_platform() -> bool { [tuple expressions]: tuple-expr.md [unsafe operations]: ../unsafety.md [value expressions]: ../expressions.md#place-expressions-and-value-expressions +[Loops and other breakable expressions]: loop-expr.md#labelled-block-expressions diff --git a/src/doc/reference/src/expressions/closure-expr.md b/src/doc/reference/src/expressions/closure-expr.md index bdc177bb5..103f74795 100644 --- a/src/doc/reference/src/expressions/closure-expr.md +++ b/src/doc/reference/src/expressions/closure-expr.md @@ -12,7 +12,7 @@ > _ClosureParam_ :\ > [_OuterAttribute_]<sup>\*</sup> [_PatternNoTopAlt_] ( `:` [_Type_] )<sup>?</sup> -A *closure expression*, also know as a lambda expression or a lambda, defines a [closure type] and evaluates to a value of that type. +A *closure expression*, also known as a lambda expression or a lambda, defines a [closure type] and evaluates to a value of that type. The syntax for a closure expression is an optional `move` keyword, then a pipe-symbol-delimited (`|`) comma-separated list of [patterns], called the *closure parameters* each optionally followed by a `:` and a type, then an optional `->` and type, called the *return type*, and then an expression, called the *closure body operand*. The optional type after each pattern is a type annotation for the pattern. If there is a return type, the closure body must be a [block]. diff --git a/src/doc/reference/src/expressions/grouped-expr.md b/src/doc/reference/src/expressions/grouped-expr.md index 0ff7e2c90..1ae2209c5 100644 --- a/src/doc/reference/src/expressions/grouped-expr.md +++ b/src/doc/reference/src/expressions/grouped-expr.md @@ -16,8 +16,8 @@ Parentheses can be used to explicitly modify the precedence order of subexpressi An example of a parenthesized expression: ```rust -let x: i32 = 2 + 3 * 4; -let y: i32 = (2 + 3) * 4; +let x: i32 = 2 + 3 * 4; // not parenthesized +let y: i32 = (2 + 3) * 4; // parenthesized assert_eq!(x, 14); assert_eq!(y, 20); ``` diff --git a/src/doc/reference/src/expressions/loop-expr.md b/src/doc/reference/src/expressions/loop-expr.md index 308f3e346..204207ee0 100644 --- a/src/doc/reference/src/expressions/loop-expr.md +++ b/src/doc/reference/src/expressions/loop-expr.md @@ -1,4 +1,4 @@ -# Loops +# Loops and other breakable expressions > **<sup>Syntax</sup>**\ > _LoopExpression_ :\ @@ -7,6 +7,7 @@ > | [_PredicateLoopExpression_]\ > | [_PredicatePatternLoopExpression_]\ > | [_IteratorLoopExpression_]\ +> | [_LabelBlockExpression_]\ > ) [_LoopLabel_]: #loop-labels @@ -14,16 +15,19 @@ [_PredicateLoopExpression_]: #predicate-loops [_PredicatePatternLoopExpression_]: #predicate-pattern-loops [_IteratorLoopExpression_]: #iterator-loops +[_LabelBlockExpression_]: #labelled-block-expressions -Rust supports four loop expressions: +Rust supports five loop expressions: * A [`loop` expression](#infinite-loops) denotes an infinite loop. * A [`while` expression](#predicate-loops) loops until a predicate is false. * A [`while let` expression](#predicate-pattern-loops) tests a pattern. * A [`for` expression](#iterator-loops) extracts values from an iterator, looping until the iterator is empty. +* A [labelled block expression](#labelled-block-expressions) runs a loop exactly once, but allows exiting the loop early with `break`. -All four types of loop support [`break` expressions](#break-expressions), [`continue` expressions](#continue-expressions), and [labels](#loop-labels). -Only `loop` supports [evaluation to non-trivial values](#break-and-loop-values). +All five types of loop support [`break` expressions](#break-expressions), and [labels](#loop-labels). +All except labelled block expressions support [`continue` expressions](#continue-expressions). +Only `loop` and labelled block expressions support [evaluation to non-trivial values](#break-and-loop-values). ## Infinite loops @@ -193,6 +197,18 @@ A loop expression may optionally have a _label_. The label is written as a lifet If a label is present, then labeled `break` and `continue` expressions nested within this loop may exit out of this loop or return control to its head. See [break expressions](#break-expressions) and [continue expressions](#continue-expressions). +Labels follow the hygiene and shadowing rules of local variables. For example, this code will print "outer loop": + +```rust +'a: loop { + 'a: loop { + break 'a; + } + print!("outer loop"); + break 'a; +} +``` + ## `break` expressions > **<sup>Syntax</sup>**\ @@ -226,6 +242,16 @@ Example: A `break` expression is only permitted in the body of a loop, and has one of the forms `break`, `break 'label` or ([see below](#break-and-loop-values)) `break EXPR` or `break 'label EXPR`. +## Labelled block expressions + +> **<sup>Syntax</sup>**\ +> _LabelBlockExpression_ :\ +> [_BlockExpression_] + +Labelled block expressions are exactly like block expressions, except that they allow using `break` expressions within the block. +Unlike other loops, `break` expressions within a label expression *must* have a label (i.e. the label is not optional). +Unlike other loops, labelled block expressions *must* begin with a label. + ## `continue` expressions > **<sup>Syntax</sup>**\ diff --git a/src/doc/reference/src/identifiers.md b/src/doc/reference/src/identifiers.md index a4e972cd3..c760f6826 100644 --- a/src/doc/reference/src/identifiers.md +++ b/src/doc/reference/src/identifiers.md @@ -13,7 +13,7 @@ > NON_KEYWORD_IDENTIFIER | RAW_IDENTIFIER <!-- When updating the version, update the UAX links, too. --> -Identifiers follow the specification in [Unicode Standard Annex #31][UAX31] for Unicode version 13.0, with the additions described below. Some examples of identifiers: +Identifiers follow the specification in [Unicode Standard Annex #31][UAX31] for Unicode version 15.0, with the additions described below. Some examples of identifiers: * `foo` * `_identifier` @@ -68,5 +68,5 @@ keyword except the ones listed above for `RAW_IDENTIFIER`. [proc-macro]: procedural-macros.md [reserved]: keywords.md#reserved-keywords [strict]: keywords.md#strict-keywords -[UAX15]: https://www.unicode.org/reports/tr15/tr15-50.html -[UAX31]: https://www.unicode.org/reports/tr31/tr31-33.html +[UAX15]: https://www.unicode.org/reports/tr15/tr15-53.html +[UAX31]: https://www.unicode.org/reports/tr31/tr31-37.html diff --git a/src/doc/reference/src/inline-assembly.md b/src/doc/reference/src/inline-assembly.md index 6233475a3..996b157da 100644 --- a/src/doc/reference/src/inline-assembly.md +++ b/src/doc/reference/src/inline-assembly.md @@ -123,12 +123,17 @@ Several types of operands are supported: * `inlateout(<reg>) <expr>` / `inlateout(<reg>) <in expr> => <out expr>` - Identical to `inout` except that the register allocator can reuse a register allocated to an `in` (this can happen if the compiler knows the `in` has the same initial value as the `inlateout`). - You should only write to the register after all inputs are read, otherwise you may clobber an input. +* `sym <path>` + - `<path>` must refer to a `fn` or `static`. + - A mangled symbol name referring to the item is substituted into the asm template string. + - The substituted string does not include any modifiers (e.g. GOT, PLT, relocations, etc). + - `<path>` is allowed to point to a `#[thread_local]` static, in which case the asm code can combine the symbol with relocations (e.g. `@plt`, `@TPOFF`) to read from thread-local data. Operand expressions are evaluated from left to right, just like function call arguments. After the `asm!` has executed, outputs are written to in left to right order. This is significant if two outputs point to the same place: that place will contain the value of the rightmost output. -Since `global_asm!` exists outside a function, it cannot use input/output operands. +Since `global_asm!` exists outside a function, it can only use `sym` operands. ## Register operands diff --git a/src/doc/reference/src/items/associated-items.md b/src/doc/reference/src/items/associated-items.md index f5dc31aae..2401127b5 100644 --- a/src/doc/reference/src/items/associated-items.md +++ b/src/doc/reference/src/items/associated-items.md @@ -205,22 +205,49 @@ types cannot be defined in [inherent implementations] nor can they be given a default implementation in traits. An *associated type declaration* declares a signature for associated type -definitions. It is written as `type`, then an [identifier], and -finally an optional list of trait bounds. +definitions. It is written in one of the following forms, where `Assoc` is the +name of the associated type, `Params` is a comma-separated list of type, +lifetime or const parameters, `Bounds` is a plus-separated list of trait bounds +that the associated type must meet, and `WhereBounds` is a comma-separated list +of bounds that the parameters must meet: + +<!-- ignore: illustrative example forms --> +```rust,ignore +type Assoc; +type Assoc: Bounds; +type Assoc<Params>; +type Assoc<Params>: Bounds; +type Assoc<Params> where WhereBounds; +type Assoc<Params>: Bounds where WhereBounds; +``` The identifier is the name of the declared type alias. The optional trait bounds must be fulfilled by the implementations of the type alias. There is an implicit [`Sized`] bound on associated types that can be relaxed using the special `?Sized` bound. -An *associated type definition* defines a type alias on another type. It is -written as `type`, then an [identifier], then an `=`, and finally a [type]. +An *associated type definition* defines a type alias for the implementation +of a trait on a type. They are written similarly to an *associated type declaration*, +but cannot contain `Bounds`, but instead must contain a `Type`: + +<!-- ignore: illustrative example forms --> +```rust,ignore +type Assoc = Type; +type Assoc<Params> = Type; // the type `Type` here may reference `Params` +type Assoc<Params> = Type where WhereBounds; +type Assoc<Params> where WhereBounds = Type; // deprecated, prefer the form above +``` If a type `Item` has an associated type `Assoc` from a trait `Trait`, then `<Item as Trait>::Assoc` is a type that is an alias of the type specified in the associated type definition. Furthermore, if `Item` is a type parameter, then `Item::Assoc` can be used in type parameters. -Associated types must not include [generic parameters] or [where clauses]. +Associated types may include [generic parameters] and [where clauses]; these are +often referred to as *generic associated types*, or *GATs*. If the type `Thing` +has an associated type `Item` from a trait `Trait` with the generics `<'a>` , the +type can be named like `<Thing as Trait>::Item<'x>`, where `'x` is some lifetime +in scope. In this case, `'x` will be used wherever `'a` appears in the associated +type definitions on impls. ```rust trait AssociatedType { @@ -249,6 +276,37 @@ fn main() { } ``` +An example of associated types with generics and where clauses: + +```rust +struct ArrayLender<'a, T>(&'a mut [T; 16]); + +trait Lend { + // Generic associated type declaration + type Lender<'a> where Self: 'a; + fn lend<'a>(&'a mut self) -> Self::Lender<'a>; +} + +impl<T> Lend for [T; 16] { + // Generic associated type definition + type Lender<'a> = ArrayLender<'a, T> where Self: 'a; + + fn lend<'a>(&'a mut self) -> Self::Lender<'a> { + ArrayLender(self) + } +} + +fn borrow<'a, T: Lend>(array: &'a mut T) -> <T as Lend>::Lender<'a> { + array.lend() +} + + +fn main() { + let mut array = [0usize; 16]; + let lender = borrow(&mut array); +} +``` + ### Associated Types Container Example Consider the following example of a `Container` trait. Notice that the type is @@ -279,6 +337,83 @@ impl<T> Container for Vec<T> { } ``` +### Relationship between `Bounds` and `WhereBounds` + +In this example: + +```rust +# use std::fmt::Debug; +trait Example { + type Output<T>: Ord where T: Debug; +} +``` + +Given a reference to the associated type like `<X as Example>::Output<Y>`, the associated type itself must be `Ord`, and the type `Y` must be `Debug`. + +### Required where clauses on generic associated types + +Generic associated type declarations on traits currently may require a list of +where clauses, dependent on functions in the trait and how the GAT is used. These +rules may be loosened in the future; updates can be found [on the generic +associated types initiative repository](https://rust-lang.github.io/generic-associated-types-initiative/explainer/required_bounds.html). + +In a few words, these where clauses are required in order to maximize the allowed +definitions of the associated type in impls. To do this, any clauses that *can be +proven to hold* on functions (using the parameters of the function or trait) +where a GAT appears as an input or output must also be written on the GAT itself. + +```rust +trait LendingIterator { + type Item<'x> where Self: 'x; + fn next<'a>(&'a mut self) -> Self::Item<'a>; +} +``` + +In the above, on the `next` function, we can prove that `Self: 'a`, because of +the implied bounds from `&'a mut self`; therefore, we must write the equivalent +bound on the GAT itself: `where Self: 'x`. + +When there are multiple functions in a trait that use the GAT, then the +*intersection* of the bounds from the different functions are used, rather than +the union. + +```rust +trait Check<T> { + type Checker<'x>; + fn create_checker<'a>(item: &'a T) -> Self::Checker<'a>; + fn do_check(checker: Self::Checker<'_>); +} +``` + +In this example, no bounds are required on the `type Checker<'a>;`. While we +know that `T: 'a` on `create_checker`, we do not know that on `do_check`. However, +if `do_check` was commented out, then the `where T: 'x` bound would be required +on `Checker`. + +The bounds on associated types also propagate required where clauses. + +```rust +trait Iterable { + type Item<'a> where Self: 'a; + type Iterator<'a>: Iterator<Item = Self::Item<'a>> where Self: 'a; + fn iter<'a>(&'a self) -> Self::Iterator<'a>; +} +``` + +Here, `where Self: 'a` is required on `Item` because of `iter`. However, `Item` +is used in the bounds of `Iterator`, the `where Self: 'a` clause is also required +there. + +Finally, any explicit uses of `'static` on GATs in the trait do not count towards +the required bounds. + +```rust +trait StaticReturn { + type Y<'a>; + fn foo(&self) -> Self::Y<'static>; +} +``` + ## Associated Constants *Associated constants* are [constants] associated with a type. diff --git a/src/doc/reference/src/items/external-blocks.md b/src/doc/reference/src/items/external-blocks.md index e768a1502..c91e1d10c 100644 --- a/src/doc/reference/src/items/external-blocks.md +++ b/src/doc/reference/src/items/external-blocks.md @@ -122,6 +122,9 @@ specifies the kind of library with the following possible values: - `static` — Indicates a static library. - `framework` — Indicates a macOS framework. This is only valid for macOS targets. +- `raw-dylib` — Indicates a dynamic library where the compiler will generate + an import library to link against (see [`dylib` versus `raw-dylib`] below + for details). This is only valid for Windows targets. The `name` key must be included if `kind` is specified. @@ -198,9 +201,26 @@ The default for this modifier is `-whole-archive`. More implementation details about this modifier can be found in [`whole-archive` documentation for rustc]. +#### `dylib` versus `raw-dylib` + +On Windows, linking against a dynamic library requires that an import library +is provided to the linker: this is a special static library that declares all +of the symbols exported by the dynamic library in such a way that the linker +knows that they have to be dynamically loaded at runtime. + +Specifying `kind = "dylib"` instructs the Rust compiler to link an import +library based on the `name` key. The linker will then use its normal library +resolution logic to find that import library. Alternatively, specifying +`kind = "raw-dylib"` instructs the compiler to generate an import library +during compilation and provide that to the linker instead. + +`raw-dylib` is only supported on Windows and not supported on 32-bit x86 +(`target_arch="x86"`). Using it when targeting other platforms or +x86 on Windows will result in a compiler error. + ### The `link_name` attribute -The `link_name` attribute may be specified on declarations inside an `extern` +The *`link_name` attribute* may be specified on declarations inside an `extern` block to indicate the symbol to import for the given function or static. It uses the [_MetaNameValueStr_] syntax to specify the name of the symbol. @@ -211,6 +231,41 @@ extern { } ``` +Using this attribute with the `link_ordinal` attribute will result in a +compiler error. + +### The `link_ordinal` attribute + +The *`link_ordinal` attribute* can be applied on declarations inside an `extern` +block to indicate the numeric ordinal to use when generating the import library +to link against. An ordinal is a unique number per symbol exported by a dynamic +library on Windows and can be used when the library is being loaded to find +that symbol rather than having to look it up by name. + +<div class="warning"> + +Warning: `link_ordinal` should only be used in cases where the ordinal of the +symbol is known to be stable: if the ordinal of a symbol is not explicitly set +when its containing binary is built then one will be automatically assigned to +it, and that assigned ordinal may change between builds of the binary. + +</div> + +<!-- ignore: Only works on x86 Windows --> +```rust,ignore +#[link(name = "exporter", kind = "raw-dylib")] +extern "stdcall" { + #[link_ordinal(15)] + fn imported_function_stdcall(i: i32); +} +``` + +This attribute is only used with the `raw-dylib` linking kind. +Using any other kind will result in a compiler error. + +Using this attribute with the `link_name` attribute will result in a +compiler error. + ### Attributes on function parameters Attributes on extern function parameters follow the same rules and @@ -233,3 +288,4 @@ restrictions as [regular function parameters]. [regular function parameters]: functions.md#attributes-on-function-parameters [`bundle` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-bundle [`whole-archive` documentation for rustc]: ../../rustc/command-line-arguments.html#linking-modifiers-whole-archive +[`dylib` versus `raw-dylib`]: #dylib-versus-raw-dylib diff --git a/src/doc/reference/src/items/functions.md b/src/doc/reference/src/items/functions.md index 325588a53..5b4ac7af6 100644 --- a/src/doc/reference/src/items/functions.md +++ b/src/doc/reference/src/items/functions.md @@ -59,8 +59,8 @@ fn answer_to_life_the_universe_and_everything() -> i32 { ## Function parameters -As with `let` bindings, function parameters are irrefutable [patterns], so any -pattern that is valid in a let binding is also valid as a parameter: +Function parameters are irrefutable [patterns], so any pattern that is valid in +an else-less `let` binding is also valid as a parameter: ```rust fn first((value, _): (i32, i32)) -> i32 { value } diff --git a/src/doc/reference/src/items/traits.md b/src/doc/reference/src/items/traits.md index 26870a0fc..3c5d31d5c 100644 --- a/src/doc/reference/src/items/traits.md +++ b/src/doc/reference/src/items/traits.md @@ -70,6 +70,7 @@ Object safe traits can be the base trait of a [trait object]. A trait is * All [supertraits] must also be object safe. * `Sized` must not be a [supertrait][supertraits]. In other words, it must not require `Self: Sized`. * It must not have any associated constants. +* It must not have any associated types with generics. * All associated functions must either be dispatchable from a trait object or be explicitly non-dispatchable: * Dispatchable functions require: * Not have any type parameters (although lifetime parameters are allowed), diff --git a/src/doc/reference/src/items/type-aliases.md b/src/doc/reference/src/items/type-aliases.md index ff0cc75f7..d2e14b903 100644 --- a/src/doc/reference/src/items/type-aliases.md +++ b/src/doc/reference/src/items/type-aliases.md @@ -4,7 +4,7 @@ > _TypeAlias_ :\ > `type` [IDENTIFIER] [_GenericParams_]<sup>?</sup> > ( `:` [_TypeParamBounds_] )<sup>?</sup> -> [_WhereClause_]<sup>?</sup> ( `=` [_Type_] )<sup>?</sup> `;` +> [_WhereClause_]<sup>?</sup> ( `=` [_Type_] [_WhereClause_]<sup>?</sup>)<sup>?</sup> `;` A _type alias_ defines a new name for an existing [type]. Type aliases are declared with the keyword `type`. Every value has a single, specific type, but @@ -31,11 +31,18 @@ let _ = UseAlias(5); // OK let _ = TypeAlias(5); // Doesn't work ``` -A type alias without the [_Type_] specification may only appear as an -[associated type] in a [trait]. +A type alias, when not used as an associated type, must include a [_Type_] and +may not include [_TypeParamBounds_]. -A type alias with [_TypeParamBounds_] may only specified when used as -an [associated type] in a [trait]. +A type alias, when used as an [associated type] in a [trait], must not include a +[_Type_] specification but may include [_TypeParamBounds_]. + +A type alias, when used as an [associated type] in a [trait impl], must include +a [_Type_] specification and may not include [_TypeParamBounds_]. + +Where clauses before the equals sign on a type alias in a [trait impl] (like +`type TypeAlias<T> where T: Foo = Bar<T>`) are deprecated. Where clauses after +the equals sign (like `type TypeAlias<T> = Bar<T> where T: Foo`) are preferred. [IDENTIFIER]: ../identifiers.md [_GenericParams_]: generics.md @@ -45,3 +52,4 @@ an [associated type] in a [trait]. [associated type]: associated-items.md#associated-types [trait]: traits.md [type]: ../types.md +[trait impl]: implementations.md#trait-implementations diff --git a/src/doc/reference/src/patterns.md b/src/doc/reference/src/patterns.md index 5c81ecd87..14bbac155 100644 --- a/src/doc/reference/src/patterns.md +++ b/src/doc/reference/src/patterns.md @@ -22,18 +22,16 @@ > | [_PathPattern_]\ > | [_MacroInvocation_] -Patterns are used to match values against structures and to, -optionally, bind variables to values inside these structures. They are also -used in variable declarations and parameters for functions and closures. +Patterns are used to match values against structures and to, optionally, bind variables to values inside these structures. +They are also used in variable declarations and parameters for functions and closures. The pattern in the following example does four things: * Tests if `person` has the `car` field filled with something. -* Tests if the person's `age` field is between 13 and 19, and binds its value to - the `person_age` variable. +* Tests if the person's `age` field is between 13 and 19, and binds its value to the `person_age` variable. * Binds a reference to the `name` field to the variable `person_name`. -* Ignores the rest of the fields of `person`. The remaining fields can have any value and - are not bound to any variables. +* Ignores the rest of the fields of `person`. + The remaining fields can have any value and are not bound to any variables. ```rust # struct Car; @@ -65,8 +63,7 @@ if let Patterns are used in: * [`let` declarations](statements.md#let-statements) -* [Function](items/functions.md) and [closure](expressions/closure-expr.md) - parameters +* [Function](items/functions.md) and [closure](expressions/closure-expr.md) parameters * [`match` expressions](expressions/match-expr.md) * [`if let` expressions](expressions/if-expr.md) * [`while let` expressions](expressions/loop-expr.md#predicate-pattern-loops) @@ -75,13 +72,10 @@ Patterns are used in: ## Destructuring Patterns can be used to *destructure* [structs], [enums], and [tuples]. -Destructuring breaks up a value into its component pieces. The syntax used is -almost the same as when creating such values. In a pattern whose [scrutinee] -expression has a `struct`, `enum` or `tuple` type, a placeholder (`_`) stands -in for a *single* data field, whereas a wildcard `..` stands in for *all* the -remaining fields of a particular variant. When destructuring a data structure -with named (but not numbered) fields, it is allowed to write `fieldname` as a -shorthand for `fieldname: fieldname`. +Destructuring breaks up a value into its component pieces. +The syntax used is almost the same as when creating such values. +In a pattern whose [scrutinee] expression has a `struct`, `enum` or `tuple` type, a placeholder (`_`) stands in for a *single* data field, whereas a wildcard `..` stands in for *all* the remaining fields of a particular variant. +When destructuring a data structure with named (but not numbered) fields, it is allowed to write `fieldname` as a shorthand for `fieldname: fieldname`. ```rust # enum Message { @@ -104,9 +98,9 @@ match message { ## Refutability -A pattern is said to be *refutable* when it has the possibility of not being matched -by the value it is being matched against. *Irrefutable* patterns, on the other hand, -always match the value they are being matched against. Examples: +A pattern is said to be *refutable* when it has the possibility of not being matched by the value it is being matched against. +*Irrefutable* patterns, on the other hand, always match the value they are being matched against. +Examples: ```rust let (x, y) = (1, 2); // "(x, y)" is an irrefutable pattern @@ -141,16 +135,12 @@ if let (a, 3) = (1, 2) { // "(a, 3)" is refutable, and will not match [INTEGER_LITERAL]: tokens.md#integer-literals [FLOAT_LITERAL]: tokens.md#floating-point-literals -_Literal patterns_ match exactly the same value as what is created by the -literal. Since negative numbers are not [literals], literal patterns also -accept an optional minus sign before the literal, which acts like the negation -operator. +_Literal patterns_ match exactly the same value as what is created by the literal. +Since negative numbers are not [literals], literal patterns also accept an optional minus sign before the literal, which acts like the negation operator. <div class="warning"> -Floating-point literals are currently accepted, but due to the complexity of comparing -them, they are going to be forbidden on literal patterns in a future version of Rust (see -[issue #41620](https://github.com/rust-lang/rust/issues/41620)). +Floating-point literals are currently accepted, but due to the complexity of comparing them, they are going to be forbidden on literal patterns in a future version of Rust (see [issue #41620](https://github.com/rust-lang/rust/issues/41620)). </div> @@ -175,14 +165,13 @@ for i in -2..5 { > _IdentifierPattern_ :\ > `ref`<sup>?</sup> `mut`<sup>?</sup> [IDENTIFIER] (`@` [_PatternNoTopAlt_] ) <sup>?</sup> -Identifier patterns bind the value they match to a variable. The identifier -must be unique within the pattern. The variable will shadow any variables of -the same name in scope. The scope of the new binding depends on the context of -where the pattern is used (such as a `let` binding or a `match` arm). +Identifier patterns bind the value they match to a variable. +The identifier must be unique within the pattern. +The variable will shadow any variables of the same name in scope. +The scope of the new binding depends on the context of where the pattern is used (such as a `let` binding or a `match` arm). -Patterns that consist of only an identifier, possibly with a `mut`, match any value and -bind it to that identifier. This is the most commonly used pattern in variable -declarations and parameters for functions and closures. +Patterns that consist of only an identifier, possibly with a `mut`, match any value and bind it to that identifier. +This is the most commonly used pattern in variable declarations and parameters for functions and closures. ```rust let mut variable = 10; @@ -191,9 +180,8 @@ fn sum(x: i32, y: i32) -> i32 { # } ``` -To bind the matched value of a pattern to a variable, use the syntax `variable @ -subpattern`. For example, the following binds the value 2 to `e` (not the -entire range: the range here is a range subpattern). +To bind the matched value of a pattern to a variable, use the syntax `variable @ subpattern`. +For example, the following binds the value 2 to `e` (not the entire range: the range here is a range subpattern). ```rust let x = 2; @@ -204,10 +192,8 @@ match x { } ``` -By default, identifier patterns bind a variable to a copy of or move from the -matched value depending on whether the matched value implements [`Copy`]. -This can be changed to bind to a reference by using the `ref` keyword, -or to a mutable reference using `ref mut`. For example: +By default, identifier patterns bind a variable to a copy of or move from the matched value depending on whether the matched value implements [`Copy`]. +This can be changed to bind to a reference by using the `ref` keyword, or to a mutable reference using `ref mut`. For example: ```rust # let a = Some(10); @@ -222,10 +208,10 @@ match a { } ``` -In the first match expression, the value is copied (or moved). In the second match, -a reference to the same memory location is bound to the variable value. This syntax is -needed because in destructuring subpatterns the `&` operator can't be applied to -the value's fields. For example, the following is not valid: +In the first match expression, the value is copied (or moved). +In the second match, a reference to the same memory location is bound to the variable value. +This syntax is needed because in destructuring subpatterns the `&` operator can't be applied to the value's fields. +For example, the following is not valid: ```rust,compile_fail # struct Person { @@ -247,21 +233,18 @@ To make it valid, write the following: if let Person {name: ref person_name, age: 18..=150 } = value { } ``` -Thus, `ref` is not something that is being matched against. Its objective is -exclusively to make the matched binding a reference, instead of potentially -copying or moving what was matched. +Thus, `ref` is not something that is being matched against. +Its objective is exclusively to make the matched binding a reference, instead of potentially copying or moving what was matched. -[Path patterns](#path-patterns) take precedence over identifier patterns. It is an error -if `ref` or `ref mut` is specified and the identifier shadows a constant. +[Path patterns](#path-patterns) take precedence over identifier patterns. +It is an error if `ref` or `ref mut` is specified and the identifier shadows a constant. -Identifier patterns are irrefutable if the `@` subpattern is irrefutable or -the subpattern is not specified. +Identifier patterns are irrefutable if the `@` subpattern is irrefutable or the subpattern is not specified. ### Binding modes -To service better ergonomics, patterns operate in different *binding modes* in -order to make it easier to bind references to values. When a reference value is matched by -a non-reference pattern, it will be automatically treated as a `ref` or `ref mut` binding. +To service better ergonomics, patterns operate in different *binding modes* in order to make it easier to bind references to values. +When a reference value is matched by a non-reference pattern, it will be automatically treated as a `ref` or `ref mut` binding. Example: ```rust @@ -271,26 +254,22 @@ if let Some(y) = x { } ``` -*Non-reference patterns* include all patterns except bindings, [wildcard -patterns](#wildcard-pattern) (`_`), [`const` patterns](#path-patterns) of reference types, -and [reference patterns](#reference-patterns). - -If a binding pattern does not explicitly have `ref`, `ref mut`, or `mut`, then it uses the -*default binding mode* to determine how the variable is bound. The default binding -mode starts in "move" mode which uses move semantics. When matching a pattern, the -compiler starts from the outside of the pattern and works inwards. Each time a reference -is matched using a non-reference pattern, it will automatically dereference the value and -update the default binding mode. References will set the default binding mode to `ref`. -Mutable references will set the mode to `ref mut` unless the mode is already `ref` in -which case it remains `ref`. If the automatically dereferenced value is still a reference, -it is dereferenced and this process repeats. - -Move bindings and reference bindings can be mixed together in the same pattern, doing so will -result in partial move of the object bound to and the object cannot be used afterwards. +*Non-reference patterns* include all patterns except bindings, [wildcard patterns](#wildcard-pattern) (`_`), [`const` patterns](#path-patterns) of reference types, and [reference patterns](#reference-patterns). + +If a binding pattern does not explicitly have `ref`, `ref mut`, or `mut`, then it uses the *default binding mode* to determine how the variable is bound. +The default binding mode starts in "move" mode which uses move semantics. +When matching a pattern, the compiler starts from the outside of the pattern and works inwards. +Each time a reference is matched using a non-reference pattern, it will automatically dereference the value and update the default binding mode. +References will set the default binding mode to `ref`. +Mutable references will set the mode to `ref mut` unless the mode is already `ref` in which case it remains `ref`. +If the automatically dereferenced value is still a reference, it is dereferenced and this process repeats. + +Move bindings and reference bindings can be mixed together in the same pattern. +Doing so will result in partial move of the object bound to and the object cannot be used afterwards. This applies only if the type cannot be copied. -In the example below, `name` is moved out of `person`, trying to use `person` as a whole or -`person.name` would result in an error because of *partial move*. +In the example below, `name` is moved out of `person`. +Trying to use `person` as a whole or `person.name` would result in an error because of *partial move*. Example: @@ -310,10 +289,10 @@ let Person { name, ref age } = person; > _WildcardPattern_ :\ > `_` -The _wildcard pattern_ (an underscore symbol) matches any value. It is used to ignore values when they don't -matter. Inside other patterns it matches a single data field (as opposed to the `..` -which matches the remaining fields). Unlike identifier patterns, it does not copy, move -or borrow the value it matches. +The _wildcard pattern_ (an underscore symbol) matches any value. +It is used to ignore values when they don't matter. +Inside other patterns it matches a single data field (as opposed to the `..` which matches the remaining fields). +Unlike identifier patterns, it does not copy, move or borrow the value it matches. Examples: @@ -351,13 +330,9 @@ The wildcard pattern is always irrefutable. > _RestPattern_ :\ > `..` -The _rest pattern_ (the `..` token) acts as a variable-length pattern which -matches zero or more elements that haven't been matched already before and -after. It may only be used in [tuple](#tuple-patterns), [tuple -struct](#tuple-struct-patterns), and [slice](#slice-patterns) patterns, and -may only appear once as one of the elements in those patterns. It is also -allowed in an [identifier pattern](#identifier-patterns) for [slice -patterns](#slice-patterns) only. +The _rest pattern_ (the `..` token) acts as a variable-length pattern which matches zero or more elements that haven't been matched already before and after. +It may only be used in [tuple](#tuple-patterns), [tuple struct](#tuple-struct-patterns), and [slice](#slice-patterns) patterns, and may only appear once as one of the elements in those patterns. +It is also allowed in an [identifier pattern](#identifier-patterns) for [slice patterns](#slice-patterns) only. The rest pattern is always irrefutable. @@ -413,7 +388,8 @@ match tuple { > _RangePatternBound_ `..=` _RangePatternBound_ > > _HalfOpenRangePattern_ :\ -> | _RangePatternBound_ `..` +> _RangePatternBound_ `..` +> | `..=` _RangePatternBound_ > > _ObsoleteRangePattern_ :\ > _RangePatternBound_ `...` _RangePatternBound_ @@ -425,29 +401,50 @@ match tuple { > | `-`<sup>?</sup> [FLOAT_LITERAL]\ > | [_PathExpression_] -Range patterns match values within the range defined by their bounds. A range pattern may be -closed or half-open. A range pattern is closed if it has both a lower and an upper bound, and -it matches all the values between and including both of its bounds. A range pattern that is -half-open is written with a lower bound but not an upper bound, and matches any value equal to -or greater than the specified lower bound. +*Range patterns* match scalar values within the range defined by their bounds. +A bound on the left of its sigils is a *lower bound*. +A bound on the right is an *upper bound*. +A range pattern may be closed or half-open. + +A range pattern is *closed* if it has both a lower and an upper bound. +The only closed ranged pattern is the inclusive range pattern. + +*Inclusive range patterns* match all the values between and including both of its bounds. +It is written as its lower bounds, followed by `..=`, followed by its upper bounds. +The type of it is the type unification of its upper and lower bounds. + +For example, a pattern `'m'..='p'` will match only the values `'m'`, `'n'`, `'o'`, and `'p'`. + +The lower bound cannot be greater than the upper bound. +That is, in `a..=b`, a ≤ b must be the case. +For example, it is an error to have a range pattern `10..=0`. -For example, a pattern `'m'..='p'` will match only the values `'m'`, `'n'`, `'o'`, and `'p'`. For an integer the -pattern `1..` will match 9, or 9001, or 9007199254740991 (if it is of an appropriate size), but -not 0, and not negative numbers for signed integers. The bounds can be literals or paths that point -to constant values. +Range patterns are *half-open* if they have only an upper or lower bound. +They have the same type as their upper or lower bound. -A half-open range pattern in the style `a..` cannot be used to match within the context of a slice. +A half open range with only a lower bound is written as its lower bound followed by `..`. +These range patterns will match on any value greater than or equal to the lower bound. +For example, `1..` will match 1, 9, or 9001, or 9007199254740991 (if it is of an appropriate size), but not 0, and not negative numbers for signed integers. +The bounds can be literals or paths that point to constant values. -A pattern `a..=b` must always have a ≤ b. It is an error to have a range pattern -`10..=0`, for example. +A half open range with only an upper bound is written as `..=` followed by its upper bound. +These range patterns will match on any value less than or equal to the upper bound. +For example, `..=10` will match 10, 1, 0, and for signed interger types, all negative values. -Range patterns only work on scalar types. The accepted types are: +Half-open range patterns cannot be used as the top-level pattern for subpatterns in [slice patterns](#slice-patterns). -* Integer types (u8, i8, u16, i16, usize, isize, etc.). -* Character types (char). -* Floating point types (f32 and f64). This is being deprecated and will not be available - in a future version of Rust (see - [issue #41620](https://github.com/rust-lang/rust/issues/41620)). +The bounds is written as one of: + +* A character, byte, integer, or float literal. +* A `-` followed by an integer or float literal. +* A [path] + +If the bounds is written as a path, after macro resolution, the path must resolve to a constant item of the type `char`, an integer type, or a float type. + +The type and value of the bounds is dependent upon how it is written out. +If the bounds is a [path], the pattern has the type and value of the [constant] the path resolves to. +If it is a literal, it has the type and value of the corresponding [literal expression]. +If is a literal preceded by a `-`, it has the same type as the corresponding [literal expression] and the value of [negating] the value of the corresponding literal expression. Examples: @@ -524,23 +521,26 @@ println!("{}", match 0xfacade { }); ``` -Range patterns for (non-`usize` and -`isize`) integer and `char` types are irrefutable -when they span the entire set of possible values of a type. For example, `0u8..=255u8` -is irrefutable. The range of values for an integer type is the closed range from its -minimum to maximum value. The range of values for a `char` type are precisely those -ranges containing all Unicode Scalar Values: `'\u{0000}'..='\u{D7FF}'` and -`'\u{E000}'..='\u{10FFFF}'`. +Range patterns for fix-width integer and `char` types are irrefutable when they span the entire set of possible values of a type. +For example, `0u8..=255u8` is irrefutable. +The range of values for an integer type is the closed range from its minimum to maximum value. +The range of values for a `char` type are precisely those ranges containing all Unicode Scalar Values: `'\u{0000}'..='\u{D7FF}'` and `'\u{E000}'..='\u{10FFFF}'`. + +Floating point range patterns are deprecated and may be removed in a future Rust release. +See [issue #41620](https://github.com/rust-lang/rust/issues/41620) for more information. > **Edition Differences**: Before the 2021 edition, closed range patterns may also be written using `...` as an alternative to `..=`, with the same meaning. +> **Note**: Although range patterns use the same syntax as [range expressions], there are no exclusive range patterns. +> That is, neither `x .. y` nor `.. x` are valid range patterns. + ## Reference patterns > **<sup>Syntax</sup>**\ > _ReferencePattern_ :\ > (`&`|`&&`) `mut`<sup>?</sup> [_PatternWithoutRange_] -Reference patterns dereference the pointers that are being matched -and, thus, borrow them. +Reference patterns dereference the pointers that are being matched and, thus, borrow them. For example, these two matches on `x: &i32` are equivalent: @@ -553,11 +553,9 @@ let b = match int_reference { &0 => "zero", _ => "some" }; assert_eq!(a, b); ``` -The grammar production for reference patterns has to match the token `&&` to match a -reference to a reference because it is a token by itself, not two `&` tokens. +The grammar production for reference patterns has to match the token `&&` to match a reference to a reference because it is a token by itself, not two `&` tokens. -Adding the `mut` keyword dereferences a mutable reference. The mutability must match the -mutability of the reference. +Adding the `mut` keyword dereferences a mutable reference. The mutability must match the mutability of the reference. Reference patterns are always irrefutable. @@ -594,8 +592,7 @@ Reference patterns are always irrefutable. Struct patterns match struct values that match all criteria defined by its subpatterns. They are also used to [destructure](#destructuring) a struct. -On a struct pattern, the fields are referenced by name, index (in the case of tuple -structs) or ignored by use of `..`: +On a struct pattern, the fields are referenced by name, index (in the case of tuple structs) or ignored by use of `..`: ```rust # struct Point { @@ -644,8 +641,7 @@ match struct_value { } ``` -The `ref` and/or `mut` _IDENTIFIER_ syntax matches any value and binds it to -a variable with the same name as the given field. +The `ref` and/or `mut` _IDENTIFIER_ syntax matches any value and binds it to a variable with the same name as the given field. ```rust # struct Struct { @@ -669,9 +665,8 @@ A struct pattern is refutable when one of its subpatterns is refutable. > _TupleStructItems_ :\ > [_Pattern_] ( `,` [_Pattern_] )<sup>\*</sup> `,`<sup>?</sup> -Tuple struct patterns match tuple struct and enum values that match all criteria defined -by its subpatterns. They are also used to [destructure](#destructuring) a tuple struct or -enum value. +Tuple struct patterns match tuple struct and enum values that match all criteria defined by its subpatterns. +They are also used to [destructure](#destructuring) a tuple struct or enum value. A tuple struct pattern is refutable when one of its subpatterns is refutable. @@ -689,8 +684,7 @@ A tuple struct pattern is refutable when one of its subpatterns is refutable. Tuple patterns match tuple values that match all criteria defined by its subpatterns. They are also used to [destructure](#destructuring) a tuple. -The form `(..)` with a single [_RestPattern_] is a special form that does not -require a comma, and matches a tuple of any size. +The form `(..)` with a single [_RestPattern_] is a special form that does not require a comma, and matches a tuple of any size. The tuple pattern is refutable when one of its subpatterns is refutable. @@ -710,10 +704,8 @@ assert_eq!(b, "ten"); > _GroupedPattern_ :\ > `(` [_Pattern_] `)` -Enclosing a pattern in parentheses can be used to explicitly control the -precedence of compound patterns. For example, a reference pattern next to a -range pattern such as `&0..=5` is ambiguous and is not allowed, but can be -expressed with parentheses. +Enclosing a pattern in parentheses can be used to explicitly control the precedence of compound patterns. +For example, a reference pattern next to a range pattern such as `&0..=5` is ambiguous and is not allowed, but can be expressed with parentheses. ```rust let int_reference = &3; @@ -733,6 +725,7 @@ match int_reference { > [_Pattern_] \(`,` [_Pattern_])<sup>\*</sup> `,`<sup>?</sup> Slice patterns can match both arrays of fixed size and slices of dynamic size. + ```rust // Fixed size let arr = [1, 2, 3]; @@ -751,14 +744,10 @@ match v[..] { }; ``` -Slice patterns are irrefutable when matching an array as long as each element -is irrefutable. When matching a slice, it is irrefutable only in the form with -a single `..` [rest pattern](#rest-patterns) or [identifier -pattern](#identifier-patterns) with the `..` rest pattern as a subpattern. +Slice patterns are irrefutable when matching an array as long as each element is irrefutable. +When matching a slice, it is irrefutable only in the form with a single `..` [rest pattern](#rest-patterns) or [identifier pattern](#identifier-patterns) with the `..` rest pattern as a subpattern. -Within a slice, a half-open range pattern like `a..` must be enclosed in parentheses, -as in `(a..)`, to clarify it is intended to match a single value. -A future version of Rust may give the non-parenthesized version an alternate meaning. +Within a slice, a half-open range pattern like `a..` must be enclosed in parentheses, as in `(a..)`, to clarify it is intended to match a single value. ## Path patterns @@ -778,33 +767,27 @@ Unqualified path patterns can refer to: Qualified path patterns can only refer to associated constants. -Constants cannot be a union type. Struct and enum constants must have -`#[derive(PartialEq, Eq)]` (not merely implemented). +Constants cannot be a union type. +Struct and enum constants must have `#[derive(PartialEq, Eq)]` (not merely implemented). -Path patterns are irrefutable when they refer to structs or an enum variant when the enum -has only one variant or a constant whose type is irrefutable. They are refutable when they -refer to refutable constants or enum variants for enums with multiple variants. +Path patterns are irrefutable when they refer to structs or an enum variant when the enum has only one variant or a constant whose type is irrefutable. +They are refutable when they refer to refutable constants or enum variants for enums with multiple variants. ## Or-patterns -_Or-patterns_ are patterns that match on one of two or more sub-patterns (e.g. -`A | B | C`). They can nest arbitrarily. Syntactically, or-patterns are allowed -in any of the places where other patterns are allowed (represented by the -_Pattern_ production), with the exceptions of `let`-bindings and function and -closure arguments (represented by the _PatternNoTopAlt_ production). +_Or-patterns_ are patterns that match on one of two or more sub-patterns (for example `A | B | C`). +They can nest arbitrarily. +Syntactically, or-patterns are allowed in any of the places where other patterns are allowed (represented by the _Pattern_ production), with the exceptions of `let`-bindings and function and closure arguments (represented by the _PatternNoTopAlt_ production). ### Static semantics -1. Given a pattern `p | q` at some depth for some arbitrary patterns `p` and `q`, - the pattern is considered ill-formed if: +1. Given a pattern `p | q` at some depth for some arbitrary patterns `p` and `q`, the pattern is considered ill-formed if: + the type inferred for `p` does not unify with the type inferred for `q`, or + the same set of bindings are not introduced in `p` and `q`, or - + the type of any two bindings with the same name in `p` and `q` do not unify - with respect to types or binding modes. + + the type of any two bindings with the same name in `p` and `q` do not unify with respect to types or binding modes. - Unification of types is in all instances aforementioned exact and - implicit [type coercions] do not apply. + Unification of types is in all instances aforementioned exact and implicit [type coercions] do not apply. 2. When type checking an expression `match e_s { a_1 => e_1, ... a_n => e_n }`, for each match arm `a_i` which contains a pattern of form `p_i | q_i`, @@ -812,35 +795,27 @@ closure arguments (represented by the _PatternNoTopAlt_ production). at the depth `d` where it exists the fragment of `e_s` at depth `d`, the type of the expression fragment does not unify with `p_i | q_i`. -3. With respect to exhaustiveness checking, a pattern `p | q` is - considered to cover `p` as well as `q`. For some constructor `c(x, ..)` - the distributive law applies such that `c(p | q, ..rest)` covers the same - set of value as `c(p, ..rest) | c(q, ..rest)` does. This can be applied - recursively until there are no more nested patterns of form `p | q` other - than those that exist at the top level. +3. With respect to exhaustiveness checking, a pattern `p | q` is considered to cover `p` as well as `q`. + For some constructor `c(x, ..)` the distributive law applies such that `c(p | q, ..rest)` covers the same set of value as `c(p, ..rest) | c(q, ..rest)` does. + This can be applied recursively until there are no more nested patterns of form `p | q` other than those that exist at the top level. - Note that by *"constructor"* we do not refer to tuple struct patterns, - but rather we refer to a pattern for any product type. - This includes enum variants, tuple structs, structs with named fields, - arrays, tuples, and slices. + Note that by *"constructor"* we do not refer to tuple struct patterns, but rather we refer to a pattern for any product type. + This includes enum variants, tuple structs, structs with named fields, arrays, tuples, and slices. ### Dynamic semantics -1. The dynamic semantics of pattern matching a scrutinee expression `e_s` - against a pattern `c(p | q, ..rest)` at depth `d` where `c` is some constructor, - `p` and `q` are arbitrary patterns, and `rest` is optionally any remaining - potential factors in `c`, is defined as being the same as that of - `c(p, ..rest) | c(q, ..rest)`. +1. The dynamic semantics of pattern matching a scrutinee expression `e_s` against a pattern `c(p | q, ..rest)` at depth `d` where `c` is some constructor, + `p` and `q` are arbitrary patterns, + and `rest` is optionally any remaining potential factors in `c`, + is defined as being the same as that of `c(p, ..rest) | c(q, ..rest)`. ### Precedence with other undelimited patterns -As shown elsewhere in this chapter, there are several types of patterns that -are syntactically undelimited, including identifier patterns, reference -patterns, and or-patterns. Or-patterns always have the lowest-precedence. This -allows us to reserve syntactic space for a possible future type ascription -feature and also to reduce ambiguity. For example, `x @ A(..) | B(..)` will -result in an error that `x` is not bound in all patterns, `&A(x) | B(x)` will -result in a type mismatch between `x` in the different subpatterns. +As shown elsewhere in this chapter, there are several types of patterns that are syntactically undelimited, including identifier patterns, reference patterns, and or-patterns. +Or-patterns always have the lowest-precedence. +This allows us to reserve syntactic space for a possible future type ascription feature and also to reduce ambiguity. +For example, `x @ A(..) | B(..)` will result in an error that `x` is not bound in all patterns. +`&A(x) | B(x)` will result in a type mismatch between `x` in the different subpatterns. [_GroupedPattern_]: #grouped-patterns [_IdentifierPattern_]: #identifier-patterns @@ -865,8 +840,13 @@ result in a type mismatch between `x` in the different subpatterns. [`Copy`]: special-types-and-traits.md#copy [IDENTIFIER]: identifiers.md +[constant]: items/constant-items.md [enums]: items/enumerations.md [literals]: expressions/literal-expr.md +[literal expression]: expressions/literal-expr.md +[negating]: expressions/operator-expr.md#negation-operators +[path]: expressions/path-expr.md +[range expressions]: expressions/range-expr.md [structs]: items/structs.md [tuples]: types/tuple.md [scrutinee]: glossary.md#scrutinee diff --git a/src/doc/reference/src/statements-and-expressions.md b/src/doc/reference/src/statements-and-expressions.md index b093972a9..fede41196 100644 --- a/src/doc/reference/src/statements-and-expressions.md +++ b/src/doc/reference/src/statements-and-expressions.md @@ -1,11 +1,7 @@ # Statements and expressions -Rust is _primarily_ an expression language. This means that most forms of -value-producing or effect-causing evaluation are directed by the uniform syntax -category of _expressions_. Each kind of expression can typically _nest_ within -each other kind of expression, and rules for evaluation of expressions involve -specifying both the value produced by the expression and the order in which its -sub-expressions are themselves evaluated. +Rust is _primarily_ an expression language. +This means that most forms of value-producing or effect-causing evaluation are directed by the uniform syntax category of _expressions_. +Each kind of expression can typically _nest_ within each other kind of expression, and rules for evaluation of expressions involve specifying both the value produced by the expression and the order in which its sub-expressions are themselves evaluated. -In contrast, statements serve _mostly_ to contain and explicitly -sequence expression evaluation. +In contrast, statements serve _mostly_ to contain and explicitly sequence expression evaluation. diff --git a/src/doc/reference/src/statements.md b/src/doc/reference/src/statements.md index 8d9c21d7d..c2ae585a0 100644 --- a/src/doc/reference/src/statements.md +++ b/src/doc/reference/src/statements.md @@ -9,35 +9,27 @@ > | [_MacroInvocationSemi_] -A *statement* is a component of a [block], which is in turn a component of an -outer [expression] or [function]. +A *statement* is a component of a [block], which is in turn a component of an outer [expression] or [function]. -Rust has two kinds of statement: [declaration -statements](#declaration-statements) and [expression -statements](#expression-statements). +Rust has two kinds of statement: [declaration statements](#declaration-statements) and [expression statements](#expression-statements). ## Declaration statements -A *declaration statement* is one that introduces one or more *names* into the -enclosing statement block. The declared names may denote new variables or new -[items][item]. +A *declaration statement* is one that introduces one or more *names* into the enclosing statement block. +The declared names may denote new variables or new [items][item]. -The two kinds of declaration statements are item declarations and `let` -statements. +The two kinds of declaration statements are item declarations and `let` statements. ### Item declarations -An *item declaration statement* has a syntactic form identical to an -[item declaration][item] within a [module]. Declaring an item within a statement -block restricts its scope to the block containing the statement. The item is not -given a [canonical path] nor are any sub-items it may declare. The exception to -this is that associated items defined by [implementations] are still accessible -in outer scopes as long as the item and, if applicable, trait are accessible. +An *item declaration statement* has a syntactic form identical to an [item declaration][item] within a [module]. +Declaring an item within a statement block restricts its scope to the block containing the statement. +The item is not given a [canonical path] nor are any sub-items it may declare. +The exception to this is that associated items defined by [implementations] are still accessible in outer scopes as long as the item and, if applicable, trait are accessible. It is otherwise identical in meaning to declaring the item inside a module. -There is no implicit capture of the containing function's generic parameters, -parameters, and local variables. For example, `inner` may not access -`outer_var`. +There is no implicit capture of the containing function's generic parameters, parameters, and local variables. +For example, `inner` may not access `outer_var`. ```rust fn outer() { @@ -54,16 +46,32 @@ fn outer() { > **<sup>Syntax</sup>**\ > _LetStatement_ :\ > [_OuterAttribute_]<sup>\*</sup> `let` [_PatternNoTopAlt_] -> ( `:` [_Type_] )<sup>?</sup> (`=` [_Expression_] )<sup>?</sup> `;` +> ( `:` [_Type_] )<sup>?</sup> (`=` [_Expression_] [†](#let-else-restriction) +> ( `else` [_BlockExpression_]) <sup>?</sup> ) <sup>?</sup> `;` +> +> <span id="let-else-restriction">†When an `else` block is specified, the +> _Expression_ must not be a [_LazyBooleanExpression_], or end with a `}`.</span> + +A *`let` statement* introduces a new set of [variables], given by a [pattern]. +The pattern is followed optionally by a type annotation and then either ends, or is followed by an initializer expression plus an optional `else` block. +When no type annotation is given, the compiler will infer the type, or signal an error if insufficient type information is available for definite inference. +Any variables introduced by a variable declaration are visible from the point of declaration until the end of the enclosing block scope, except when they are shadowed by another variable declaration. + +If an `else` block is not present, the pattern must be irrefutable. +If an `else` block is present, the pattern may be refutable. +If the pattern does not match (this requires it to be refutable), the `else` block is executed. +The `else` block must always diverge (evaluate to the [never type]). -A *`let` statement* introduces a new set of [variables], given by an -irrefutable [pattern]. The pattern is followed optionally by a type -annotation and then optionally by an initializer expression. When no -type annotation is given, the compiler will infer the type, or signal -an error if insufficient type information is available for definite -inference. Any variables introduced by a variable declaration are visible -from the point of declaration until the end of the enclosing block scope, -except when they are shadowed by another variable declaration. +```rust +let (mut v, w) = (vec![1, 2, 3], 42); // The bindings may be mut or const +let Some(t) = v.pop() else { // Refutable patterns require an else block + panic!(); // The else block must diverge +}; +let [u, v] = [v[0], v[1]] else { // This pattern is irrefutable, so the compiler + // will lint as the else block is redundant. + panic!(); +}; +``` ## Expression statements @@ -72,16 +80,13 @@ except when they are shadowed by another variable declaration. > [_ExpressionWithoutBlock_][expression] `;`\ > | [_ExpressionWithBlock_][expression] `;`<sup>?</sup> -An *expression statement* is one that evaluates an [expression] and ignores its -result. As a rule, an expression statement's purpose is to trigger the effects -of evaluating its expression. +An *expression statement* is one that evaluates an [expression] and ignores its result. +As a rule, an expression statement's purpose is to trigger the effects of evaluating its expression. -An expression that consists of only a [block expression][block] or control flow -expression, if used in a context where a statement is permitted, can omit the -trailing semicolon. This can cause an ambiguity between it being parsed as a -standalone statement and as a part of another expression; in this case, it is -parsed as a statement. The type of [_ExpressionWithBlock_][expression] -expressions when used as statements must be the unit type. +An expression that consists of only a [block expression][block] or control flow expression, if used in a context where a statement is permitted, can omit the trailing semicolon. +This can cause an ambiguity between it being parsed as a standalone statement and as a part of another expression; +in this case, it is parsed as a statement. +The type of [_ExpressionWithBlock_][expression] expressions when used as statements must be the unit type. ```rust # let mut v = vec![1, 2, 3]; @@ -113,14 +118,15 @@ if true { ## Attributes on Statements -Statements accept [outer attributes]. The attributes that have meaning on a -statement are [`cfg`], and [the lint check attributes]. +Statements accept [outer attributes]. +The attributes that have meaning on a statement are [`cfg`], and [the lint check attributes]. [block]: expressions/block-expr.md [expression]: expressions.md [function]: items/functions.md [item]: items.md [module]: items/modules.md +[never type]: types/never.md [canonical path]: paths.md#canonical-paths [implementations]: items/implementations.md [variables]: variables.md @@ -128,9 +134,11 @@ statement are [`cfg`], and [the lint check attributes]. [`cfg`]: conditional-compilation.md [the lint check attributes]: attributes/diagnostics.md#lint-check-attributes [pattern]: patterns.md +[_BlockExpression_]: expressions/block-expr.md [_ExpressionStatement_]: #expression-statements [_Expression_]: expressions.md [_Item_]: items.md +[_LazyBooleanExpression_]: expressions/operator-expr.md#lazy-boolean-operators [_LetStatement_]: #let-statements [_MacroInvocationSemi_]: macros.md#macro-invocation [_OuterAttribute_]: attributes.md diff --git a/src/doc/reference/src/tokens.md b/src/doc/reference/src/tokens.md index 197c20147..8f9bcb1f7 100644 --- a/src/doc/reference/src/tokens.md +++ b/src/doc/reference/src/tokens.md @@ -667,7 +667,7 @@ Similarly the `r`, `b`, and `br` prefixes used in raw string literals, byte lite > **Edition Differences**: Starting with the 2021 edition, reserved prefixes are reported as an error by the lexer (in particular, they cannot be passed to macros). > -> Before the 2021 edition, a reserved prefixes are accepted by the lexer and interpreted as multiple tokens (for example, one token for the identifier or keyword, followed by a `#` token). +> Before the 2021 edition, reserved prefixes are accepted by the lexer and interpreted as multiple tokens (for example, one token for the identifier or keyword, followed by a `#` token). > > Examples accepted in all editions: > ```rust diff --git a/src/doc/reference/src/type-layout.md b/src/doc/reference/src/type-layout.md index ce9296662..80a36abb8 100644 --- a/src/doc/reference/src/type-layout.md +++ b/src/doc/reference/src/type-layout.md @@ -20,8 +20,10 @@ The alignment of a value can be checked with the [`align_of_val`] function. The *size* of a value is the offset in bytes between successive elements in an array with that item type including alignment padding. The size of a value is -always a multiple of its alignment. The size of a value can be checked with the -[`size_of_val`] function. +always a multiple of its alignment. Note that some types are zero-sized; 0 is +considered a multiple of any alignment (for example, on some platforms, the type +`[u16; 0]` has size 0 and alignment 2). The size of a value can be checked with +the [`size_of_val`] function. Types where all values have the same size and alignment, and both are known at compile time, implement the [`Sized`] trait and can be checked with the @@ -86,9 +88,9 @@ String slices are a UTF-8 representation of characters that have the same layout ## Tuple Layout -Tuples do not have any guarantees about their layout. +Tuples are laid out according to the [default representation][Default]. -The exception to this is the unit tuple (`()`) which is guaranteed as a +The exception to this is the unit tuple (`()`), which is guaranteed as a zero-sized type to have a size of 0 and an alignment of 1. ## Trait Object Layout @@ -162,7 +164,25 @@ representation will not change the layout of `Inner`. Nominal types without a `repr` attribute have the default representation. Informally, this representation is also called the `rust` representation. -There are no guarantees of data layout made by this representation. +The only data layout guarantees made by this representation are those required +for soundness. They are: + + 1. The fields are properly aligned. + 2. The fields do not overlap. + 3. The alignment of the type is at least the maximum alignment of its fields. + +Formally, the first guarantee means that the offset of any field is divisible by +that field's alignment. The second guarantee means that the fields can be +ordered such that the offset plus the size of any field is less than or equal to +the offset of the next field in the ordering. The ordering does not have to be +the same as the order in which the fields are specified in the declaration of +the type. + +Be aware that the second guarantee does not imply that the fields have distinct +addresses: zero-sized types may have the same address as other fields in the +same struct. + +There are no other guarantees of data layout made by this representation. ### The `C` Representation diff --git a/src/doc/reference/src/types/function-pointer.md b/src/doc/reference/src/types/function-pointer.md index a51f76135..82103beaa 100644 --- a/src/doc/reference/src/types/function-pointer.md +++ b/src/doc/reference/src/types/function-pointer.md @@ -62,5 +62,5 @@ restrictions as [regular function parameters]. [closures]: closure.md [extern function]: ../items/functions.md#extern-function-qualifier [function items]: function-item.md -[unsafe function]: ../unsafe-functions.md +[unsafe function]: ../unsafe-keyword.md [regular function parameters]: ../items/functions.md#attributes-on-function-parameters diff --git a/src/doc/reference/src/types/pointer.md b/src/doc/reference/src/types/pointer.md index 9c8d80f39..4a74370a5 100644 --- a/src/doc/reference/src/types/pointer.md +++ b/src/doc/reference/src/types/pointer.md @@ -11,8 +11,8 @@ They can be moved or copied, stored into data structs, and returned from functio ### Shared references (`&`) -These point to memory _owned by some other value_. -When a shared reference to a value is created it prevents direct mutation of the value. +Shared references point to memory which is owned by some other value. +When a shared reference to a value is created, it prevents direct mutation of the value. [Interior mutability] provides an exception for this in certain circumstances. As the name suggests, any number of shared references to a value may exist. A shared reference type is written `&type`, or `&'a type` when you need to specify an explicit lifetime. @@ -22,7 +22,7 @@ Releasing a reference has no effect on the value it points to, but referencing o ### Mutable references (`&mut`) -These also point to memory owned by some other value. +Mutable references point to memory which is owned by some other value. A mutable reference type is written `&mut type` or `&'a mut type`. A mutable reference (that hasn't been borrowed) is the only way to access the value it points to, so is not `Copy`. diff --git a/src/doc/reference/src/unsafe-blocks.md b/src/doc/reference/src/unsafe-blocks.md deleted file mode 100644 index 754278445..000000000 --- a/src/doc/reference/src/unsafe-blocks.md +++ /dev/null @@ -1,22 +0,0 @@ -# Unsafe blocks - -A block of code can be prefixed with the `unsafe` keyword, to permit calling -`unsafe` functions or dereferencing raw pointers within a safe function. - -When a programmer has sufficient conviction that a sequence of potentially -unsafe operations is actually safe, they can encapsulate that sequence (taken -as a whole) within an `unsafe` block. The compiler will consider uses of such -code safe, in the surrounding context. - -Unsafe blocks are used to wrap foreign libraries, make direct use of hardware -or implement features not directly present in the language. For example, Rust -provides the language features necessary to implement memory-safe concurrency -in the language but the implementation of threads and message passing is in the -standard library. - -Rust's type system is a conservative approximation of the dynamic safety -requirements, so in some cases there is a performance cost to using safe code. -For example, a doubly-linked list is not a tree structure and can only be -represented with reference-counted pointers in safe code. By using `unsafe` -blocks to represent the reverse links as raw pointers, it can be implemented -with only boxes. diff --git a/src/doc/reference/src/unsafe-functions.md b/src/doc/reference/src/unsafe-functions.md deleted file mode 100644 index 7a5064c08..000000000 --- a/src/doc/reference/src/unsafe-functions.md +++ /dev/null @@ -1,5 +0,0 @@ -# Unsafe functions - -Unsafe functions are functions that are not safe in all contexts and/or for all -possible inputs. Such a function must be prefixed with the keyword `unsafe` and -can only be called from an `unsafe` block or another `unsafe` function. diff --git a/src/doc/reference/src/unsafe-keyword.md b/src/doc/reference/src/unsafe-keyword.md new file mode 100644 index 000000000..5fa5deea6 --- /dev/null +++ b/src/doc/reference/src/unsafe-keyword.md @@ -0,0 +1,58 @@ +# The `unsafe` keyword + +The `unsafe` keyword can occur in several different contexts: +unsafe functions (`unsafe fn`), unsafe blocks (`unsafe {}`), unsafe traits (`unsafe trait`), and unsafe trait implementations (`unsafe impl`). +It plays several different roles, depending on where it is used and whether the `unsafe_op_in_unsafe_fn` lint is enabled: +- it is used to mark code that *defines* extra safety conditions (`unsafe fn`, `unsafe trait`) +- it is used to mark code that needs to *satisfy* extra safety conditions (`unsafe {}`, `unsafe impl`, `unsafe fn` without [`unsafe_op_in_unsafe_fn`]) + +The following discusses each of these cases. +See the [keyword documentation][keyword] for some illustrative examples. + +## Unsafe functions (`unsafe fn`) + +Unsafe functions are functions that are not safe in all contexts and/or for all possible inputs. +We say they have *extra safety conditions*, which are requirements that must be upheld by all callers and that the compiler does not check. +For example, [`get_unchecked`] has the extra safety condition that the index must be in-bounds. +The unsafe function should come with documentation explaining what those extra safety conditions are. + +Such a function must be prefixed with the keyword `unsafe` and can only be called from inside an `unsafe` block, or inside `unsafe fn` without the [`unsafe_op_in_unsafe_fn`] lint. + +## Unsafe blocks (`unsafe {}`) + +A block of code can be prefixed with the `unsafe` keyword, to permit calling `unsafe` functions or dereferencing raw pointers. +By default, the body of an unsafe function is also considered to be an unsafe block; +this can be changed by enabling the [`unsafe_op_in_unsafe_fn`] lint. + +By putting operations into an unsafe block, the programmer states that they have taken care of satisfying the extra safety conditions of all operations inside that block. + +Unsafe blocks are the logical dual to unsafe functions: +where unsafe functions define a proof obligation that callers must uphold, unsafe blocks state that all relevant proof obligations have been discharged. +There are many ways to discharge proof obligations; +for example, there could be run-time checks or data structure invariants that guarantee that certain properties are definitely true, or the unsafe block could be inside an `unsafe fn` and use its own proof obligations to discharge the proof obligations of its callees. + +Unsafe blocks are used to wrap foreign libraries, make direct use of hardware or implement features not directly present in the language. +For example, Rust provides the language features necessary to implement memory-safe concurrency in the language but the implementation of threads and message passing in the standard library uses unsafe blocks. + +Rust's type system is a conservative approximation of the dynamic safety requirements, so in some cases there is a performance cost to using safe code. +For example, a doubly-linked list is not a tree structure and can only be represented with reference-counted pointers in safe code. +By using `unsafe` blocks to represent the reverse links as raw pointers, it can be implemented without reference counting. +(See ["Learn Rust With Entirely Too Many Linked Lists"](https://rust-unofficial.github.io/too-many-lists/) for a more in-depth exploration of this particular example.) + +## Unsafe traits (`unsafe trait`) + +An unsafe trait is a trait that comes with extra safety conditions that must be upheld by *implementations* of the trait. +The unsafe trait should come with documentation explaining what those extra safety conditions are. + +Such a trait must be prefixed with the keyword `unsafe` and can only be implemented by `unsafe impl` blocks. + +## Unsafe trait implementations (`unsafe impl`) + +When implementing an unsafe trait, the implementation needs to be prefixed with the `unsafe` keyword. +By writing `unsafe impl`, the programmer states that they have taken care of satisfying the extra safety conditions required by the trait. + +Unsafe trait implementations are the logical dual to unsafe traits: where unsafe traits define a proof obligation that implementations must uphold, unsafe implementations state that all relevant proof obligations have been discharged. + +[keyword]: ../std/keyword.unsafe.html +[`get_unchecked`]: ../std/primitive.slice.html#method.get_unchecked +[`unsafe_op_in_unsafe_fn`]: ../rustc/lints/listing/allowed-by-default.html#unsafe-op-in-unsafe-fn diff --git a/src/doc/rust-by-example/src/cargo/conventions.md b/src/doc/rust-by-example/src/cargo/conventions.md index 6e8196608..2335104f5 100644 --- a/src/doc/rust-by-example/src/cargo/conventions.md +++ b/src/doc/rust-by-example/src/cargo/conventions.md @@ -25,9 +25,9 @@ foo └── my_other_bin.rs ``` -To tell `cargo` to compile or run this binary as opposed to the default or other -binaries, we just pass `cargo` the `--bin my_other_bin` flag, where `my_other_bin` -is the name of the binary we want to work with. +To tell `cargo` to only compile or run this binary, we just pass `cargo` the +`--bin my_other_bin` flag, where `my_other_bin` is the name of the binary we +want to work with. In addition to extra binaries, `cargo` supports [more features] such as benchmarks, tests, and examples. diff --git a/src/doc/rust-by-example/src/cargo/deps.md b/src/doc/rust-by-example/src/cargo/deps.md index 8913e9e38..85f223f98 100644 --- a/src/doc/rust-by-example/src/cargo/deps.md +++ b/src/doc/rust-by-example/src/cargo/deps.md @@ -11,8 +11,8 @@ To create a new Rust project, # A binary cargo new foo -# OR A library -cargo new --lib foo +# A library +cargo new --lib bar ``` For the rest of this chapter, let's assume we are making a binary, rather than @@ -21,14 +21,19 @@ a library, but all of the concepts are the same. After the above commands, you should see a file hierarchy like this: ```txt -foo -├── Cargo.toml -└── src - └── main.rs +. +├── bar +│ ├── Cargo.toml +│ └── src +│ └── lib.rs +└── foo + ├── Cargo.toml + └── src + └── main.rs ``` -The `main.rs` is the root source file for your new project -- nothing new there. -The `Cargo.toml` is the config file for `cargo` for this project (`foo`). If you +The `main.rs` is the root source file for your new `foo` project -- nothing new there. +The `Cargo.toml` is the config file for `cargo` for this project. If you look inside it, you should see something like this: ```toml diff --git a/src/doc/rust-by-example/src/conversion/from_into.md b/src/doc/rust-by-example/src/conversion/from_into.md index 266d10f28..47b327142 100644 --- a/src/doc/rust-by-example/src/conversion/from_into.md +++ b/src/doc/rust-by-example/src/conversion/from_into.md @@ -66,7 +66,7 @@ impl From<i32> for Number { fn main() { let int = 5; - // Try removing the type declaration + // Try removing the type annotation let num: Number = int.into(); println!("My number is {:?}", num); } diff --git a/src/doc/rust-by-example/src/error/iter_result.md b/src/doc/rust-by-example/src/error/iter_result.md index e77e21ff6..288f4fc02 100644 --- a/src/doc/rust-by-example/src/error/iter_result.md +++ b/src/doc/rust-by-example/src/error/iter_result.md @@ -51,7 +51,7 @@ fn main() { ## Fail the entire operation with `collect()` -`Result` implements `FromIter` so that a vector of results (`Vec<Result<T, E>>`) +`Result` implements `FromIterator` so that a vector of results (`Vec<Result<T, E>>`) can be turned into a result with a vector (`Result<Vec<T>, E>`). Once an `Result::Err` is found, the iteration will terminate. 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 eb515aee6..117333f12 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 @@ -1,6 +1,6 @@ # Unpacking options and defaults -The is more than one way to unpack an `Option` and fall back on a default if it is `None`. To choose the one that meets our needs, we need to consider the following: +There is more than one way to unpack an `Option` and fall back on a default if it is `None`. To choose the one that meets our needs, we need to consider the following: * do we need eager or lazy evaluation? * do we need to keep the original empty value intact, or modify it in place? @@ -60,7 +60,7 @@ fn main() { ## `get_or_insert()` evaluates eagerly, modifies empty value in place -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 evaluaes its parameter, so variable `apple` is moved: +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)] @@ -75,7 +75,7 @@ fn main() { // my_fruit is: Apple // first_available_fruit is: Apple //println!("Variable named `apple` is moved: {:?}", apple); - // TODO: uncomment the line above to see the compliler error + // TODO: uncomment the line above to see the compiler error } ``` diff --git a/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md b/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md index 54552972a..93b7e4205 100644 --- a/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md +++ b/src/doc/rust-by-example/src/flow_control/match/destructuring/destructure_slice.md @@ -45,4 +45,4 @@ fn main() { ### See also: -[Arrays and Slices](../../../primitives/array.md) +[Arrays and Slices](../../../primitives/array.md) and [Binding](../binding.md) for `@` sigil diff --git a/src/doc/rust-by-example/src/flow_control/match/guard.md b/src/doc/rust-by-example/src/flow_control/match/guard.md index 6dba58f13..63008a743 100644 --- a/src/doc/rust-by-example/src/flow_control/match/guard.md +++ b/src/doc/rust-by-example/src/flow_control/match/guard.md @@ -5,7 +5,7 @@ A `match` *guard* can be added to filter the arm. ```rust,editable enum Temperature { Celsius(i32), - Farenheit(i32), + Fahrenheit(i32), } fn main() { @@ -17,8 +17,8 @@ fn main() { // The `if condition` part ^ is a guard Temperature::Celsius(t) => println!("{}C is below 30 Celsius", t), - Temperature::Farenheit(t) if t > 86 => println!("{}F is above 86 Farenheit", t), - Temperature::Farenheit(t) => println!("{}F is below 86 Farenheit", t), + Temperature::Fahrenheit(t) if t > 86 => println!("{}F is above 86 Fahrenheit", t), + Temperature::Fahrenheit(t) => println!("{}F is below 86 Fahrenheit", t), } } ``` diff --git a/src/doc/rust-by-example/src/macros.md b/src/doc/rust-by-example/src/macros.md index ffeb923e5..3f12fcc41 100644 --- a/src/doc/rust-by-example/src/macros.md +++ b/src/doc/rust-by-example/src/macros.md @@ -37,4 +37,4 @@ So why are macros useful? 3. Variadic interfaces. Sometimes you want to define an interface that takes a variable number of arguments. An example is `println!` which could take any - number of arguments, depending on the format string!. (More on this later) + number of arguments, depending on the format string. (More on this later) diff --git a/src/doc/rust-by-example/src/mod/struct_visibility.md b/src/doc/rust-by-example/src/mod/struct_visibility.md index e7359413c..8641a7264 100644 --- a/src/doc/rust-by-example/src/mod/struct_visibility.md +++ b/src/doc/rust-by-example/src/mod/struct_visibility.md @@ -13,7 +13,6 @@ mod my { } // A public struct with a private field of generic type `T` - #[allow(dead_code)] pub struct ClosedBox<T> { contents: T, } @@ -56,4 +55,4 @@ fn main() { [generics][generics] and [methods][methods] [generics]: ../generics.md -[methods]: ../fn/methods.md
\ No newline at end of file +[methods]: ../fn/methods.md diff --git a/src/doc/rust-by-example/src/primitives/array.md b/src/doc/rust-by-example/src/primitives/array.md index 841c71c14..0f56182cd 100644 --- a/src/doc/rust-by-example/src/primitives/array.md +++ b/src/doc/rust-by-example/src/primitives/array.md @@ -64,7 +64,7 @@ fn main() { } } - // Out of bound indexing causes compile error + // Out of bound indexing causes runtime error //println!("{}", xs[5]); } ``` diff --git a/src/doc/rust-by-example/src/std/box.md b/src/doc/rust-by-example/src/std/box.md index 0740c07d6..ebc8ff430 100644 --- a/src/doc/rust-by-example/src/std/box.md +++ b/src/doc/rust-by-example/src/std/box.md @@ -62,11 +62,11 @@ fn main() { mem::size_of_val(&rectangle)); // box size == pointer size - println!("Boxed point occupies {} bytes on the heap", + println!("Boxed point occupies {} bytes on the stack", mem::size_of_val(&boxed_point)); - println!("Boxed rectangle occupies {} bytes on the heap", + println!("Boxed rectangle occupies {} bytes on the stack", mem::size_of_val(&boxed_rectangle)); - println!("Boxed box occupies {} bytes on the heap", + println!("Boxed box occupies {} bytes on the stack", mem::size_of_val(&box_in_a_box)); // Copy the data contained in `boxed_point` into `unboxed_point` diff --git a/src/doc/rust-by-example/src/std/str.md b/src/doc/rust-by-example/src/std/str.md index 26d8fd109..a15038b90 100644 --- a/src/doc/rust-by-example/src/std/str.md +++ b/src/doc/rust-by-example/src/std/str.md @@ -69,7 +69,7 @@ This way you can add any character to your string, even unprintable ones and ones that you don't know how to type. If you want a literal backslash, escape it with another one: `\\` -String or character literal delimiters occuring within a literal must be escaped: `"\""`, `'\''`. +String or character literal delimiters occurring within a literal must be escaped: `"\""`, `'\''`. ```rust,editable fn main() { diff --git a/src/doc/rust-by-example/src/std_misc/path.md b/src/doc/rust-by-example/src/std_misc/path.md index 48d85c144..af0f3d388 100644 --- a/src/doc/rust-by-example/src/std_misc/path.md +++ b/src/doc/rust-by-example/src/std_misc/path.md @@ -13,8 +13,10 @@ between `Path` and `PathBuf` is similar to that of `str` and `String`: a `PathBuf` can be mutated in-place, and can be dereferenced to a `Path`. Note that a `Path` is *not* internally represented as an UTF-8 string, but -instead is stored as a vector of bytes (`Vec<u8>`). Therefore, converting a -`Path` to a `&str` is *not* free and may fail (an `Option` is returned). +instead is stored as an `OsString`. Therefore, converting a `Path` to a `&str` +is *not* free and may fail (an `Option` is returned). However, a `Path` can be +freely converted to an `OsString` or `&OsStr` using `into_os_string` and +`as_os_str`, respectively. ```rust,editable use std::path::Path; diff --git a/src/doc/rust-by-example/src/testing/doc_testing.md b/src/doc/rust-by-example/src/testing/doc_testing.md index 2fac440f9..1d6cd46ad 100644 --- a/src/doc/rust-by-example/src/testing/doc_testing.md +++ b/src/doc/rust-by-example/src/testing/doc_testing.md @@ -1,9 +1,10 @@ # Documentation testing The primary way of documenting a Rust project is through annotating the source -code. Documentation comments are written in [markdown] and support code -blocks in them. Rust takes care about correctness, so these code blocks are -compiled and used as documentation tests. +code. Documentation comments are written in +[CommonMark Markdown specification][commonmark] and support code blocks in them. +Rust takes care about correctness, so these code blocks are compiled and used +as documentation tests. ```rust,ignore /// First line is a short summary describing function. @@ -83,7 +84,7 @@ and `unwrap` it in hidden `main`. Sounds complicated? Here's an example: /// ``` /// # // hidden lines start with `#` symbol, but they're still compilable! /// # fn try_main() -> Result<(), String> { // line that wraps the body shown in doc -/// let res = try::try_div(10, 2)?; +/// let res = doccomments::try_div(10, 2)?; /// # Ok(()) // returning from try_main /// # } /// # fn main() { // starting main that'll unwrap() @@ -106,6 +107,6 @@ pub fn try_div(a: i32, b: i32) -> Result<i32, String> { * [API Guidelines][doc-nursery] on documentation guidelines [doc-nursery]: https://rust-lang-nursery.github.io/api-guidelines/documentation.html -[markdown]: https://daringfireball.net/projects/markdown/ +[commonmark]: https://commonmark.org/ [RFC505]: https://github.com/rust-lang/rfcs/blob/master/text/0505-api-comment-conventions.md [question-instead-of-unwrap]: https://rust-lang-nursery.github.io/api-guidelines/documentation.html#examples-use--not-try-not-unwrap-c-question-mark diff --git a/src/doc/rust-by-example/src/types/cast.md b/src/doc/rust-by-example/src/types/cast.md index 6182874cd..deed34cf7 100644 --- a/src/doc/rust-by-example/src/types/cast.md +++ b/src/doc/rust-by-example/src/types/cast.md @@ -53,13 +53,13 @@ fn main() { // Unless it already fits, of course. println!(" 128 as a i16 is: {}", 128 as i16); - // 128 as i8 -> -128, whose two's complement in eight bits is: + // 128 as u8 -> 128, whose value in 8-bit two's complement representation is: println!(" 128 as a i8 is : {}", 128 as i8); // repeating the example above // 1000 as u8 -> 232 println!("1000 as a u8 is : {}", 1000 as u8); - // and the two's complement of 232 is -24 + // and the value of 232 in 8-bit two's complement representation is -24 println!(" 232 as a i8 is : {}", 232 as i8); // Since Rust 1.45, the `as` keyword performs a *saturating cast* @@ -67,23 +67,23 @@ fn main() { // the upper bound or is less than the lower bound, the returned value // will be equal to the bound crossed. - // 300.0 is 255 - println!("300.0 is {}", 300.0_f32 as u8); + // 300.0 as u8 is 255 + println!(" 300.0 as u8 is : {}", 300.0_f32 as u8); // -100.0 as u8 is 0 - println!("-100.0 as u8 is {}", -100.0_f32 as u8); + println!("-100.0 as u8 is : {}", -100.0_f32 as u8); // nan as u8 is 0 - println!("nan as u8 is {}", f32::NAN as u8); + println!(" nan as u8 is : {}", f32::NAN as u8); // This behavior incurs a small runtime cost and can be avoided // with unsafe methods, however the results might overflow and // return **unsound values**. Use these methods wisely: unsafe { - // 300.0 is 44 - println!("300.0 is {}", 300.0_f32.to_int_unchecked::<u8>()); + // 300.0 as u8 is 44 + println!(" 300.0 as u8 is : {}", 300.0_f32.to_int_unchecked::<u8>()); // -100.0 as u8 is 156 - println!("-100.0 as u8 is {}", (-100.0_f32).to_int_unchecked::<u8>()); + println!("-100.0 as u8 is : {}", (-100.0_f32).to_int_unchecked::<u8>()); // nan as u8 is 0 - println!("nan as u8 is {}", f32::NAN.to_int_unchecked::<u8>()); + println!(" nan as u8 is : {}", f32::NAN.to_int_unchecked::<u8>()); } } ``` diff --git a/src/doc/rust-by-example/src/unsafe/asm.md b/src/doc/rust-by-example/src/unsafe/asm.md index ee6b8088a..7ad6e0c5e 100644 --- a/src/doc/rust-by-example/src/unsafe/asm.md +++ b/src/doc/rust-by-example/src/unsafe/asm.md @@ -227,7 +227,7 @@ This state is generally referred to as being "clobbered". We need to tell the compiler about this since it may need to save and restore this state around the inline assembly block. ```rust -use core::arch::asm; +use std::arch::asm; fn main() { // three entries of four bytes each @@ -333,7 +333,7 @@ In some cases, fine control is needed over the way a register name is formatted By default the compiler will always choose the name that refers to the full register size (e.g. `rax` on x86-64, `eax` on x86, etc). -This default can be overriden by using modifiers on the template string operands, just like you would with format strings: +This default can be overridden by using modifiers on the template string operands, just like you would with format strings: ```rust use std::arch::asm; diff --git a/src/doc/rustc-dev-guide/.github/workflows/ci.yml b/src/doc/rustc-dev-guide/.github/workflows/ci.yml index c571d408d..a21e342cb 100644 --- a/src/doc/rustc-dev-guide/.github/workflows/ci.yml +++ b/src/doc/rustc-dev-guide/.github/workflows/ci.yml @@ -14,28 +14,28 @@ jobs: if: github.repository == 'rust-lang/rustc-dev-guide' runs-on: ubuntu-latest env: - MDBOOK_VERSION: 0.4.12 - MDBOOK_LINKCHECK_VERSION: 0.7.2 - MDBOOK_MERMAID_VERSION: 0.10.0 - MDBOOK_TOC_VERSION: 0.6.1 + MDBOOK_VERSION: 0.4.21 + MDBOOK_LINKCHECK_VERSION: 0.7.6 + MDBOOK_MERMAID_VERSION: 0.11.2 + MDBOOK_TOC_VERSION: 0.9.0 DEPLOY_DIR: book/html BASE_SHA: ${{ github.event.pull_request.base.sha }} steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v3 with: # linkcheck needs the base commit. fetch-depth: 0 - name: Cache binaries id: mdbook-cache - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/.cargo/bin key: ${{ runner.os }}-${{ env.MDBOOK_VERSION }}--${{ env.MDBOOK_LINKCHECK_VERSION }}--${{ env.MDBOOK_TOC_VERSION }}--${{ env.MDBOOK_MERMAID_VERSION }} - name: Cache linkcheck - uses: actions/cache@v2 + uses: actions/cache@v3 with: path: | ~/book/linkcheck @@ -49,10 +49,9 @@ jobs: - name: Install latest nightly Rust toolchain if: steps.mdbook-cache.outputs.cache-hit != 'true' - uses: actions-rs/toolchain@v1 - with: - toolchain: nightly - override: true + run: | + rustup update nightly + rustup override set nightly - name: Install Dependencies if: steps.mdbook-cache.outputs.cache-hit != 'true' diff --git a/src/doc/rustc-dev-guide/.github/workflows/date-check.yml b/src/doc/rustc-dev-guide/.github/workflows/date-check.yml index b808876a4..c34c11c1e 100644 --- a/src/doc/rustc-dev-guide/.github/workflows/date-check.yml +++ b/src/doc/rustc-dev-guide/.github/workflows/date-check.yml @@ -15,7 +15,7 @@ jobs: steps: - name: Checkout repo - uses: actions/checkout@v2 + uses: actions/checkout@v3 - name: Ensure Rust is up-to-date run: | diff --git a/src/doc/rustc-dev-guide/book.toml b/src/doc/rustc-dev-guide/book.toml index c86ec5638..dc216760e 100644 --- a/src/doc/rustc-dev-guide/book.toml +++ b/src/doc/rustc-dev-guide/book.toml @@ -43,3 +43,4 @@ warning-policy = "error" [output.html.redirect] "/compiletest.html" = "tests/compiletest.html" "/diagnostics/sessiondiagnostic.html" = "diagnostics/diagnostic-structs.html" +"/miri.html" = "const-eval/interpret.html" diff --git a/src/doc/rustc-dev-guide/src/SUMMARY.md b/src/doc/rustc-dev-guide/src/SUMMARY.md index 99b24fe59..360265c0e 100644 --- a/src/doc/rustc-dev-guide/src/SUMMARY.md +++ b/src/doc/rustc-dev-guide/src/SUMMARY.md @@ -152,7 +152,7 @@ - [MIR optimizations](./mir/optimizations.md) - [Debugging](./mir/debugging.md) - [Constant evaluation](./const-eval.md) - - [miri const evaluator](./miri.md) + - [Interpreter](./const-eval/interpret.md) - [Monomorphization](./backend/monomorph.md) - [Lowering MIR](./backend/lowering-mir.md) - [Code Generation](./backend/codegen.md) diff --git a/src/doc/rustc-dev-guide/src/about-this-guide.md b/src/doc/rustc-dev-guide/src/about-this-guide.md index b2c71866c..71407854e 100644 --- a/src/doc/rustc-dev-guide/src/about-this-guide.md +++ b/src/doc/rustc-dev-guide/src/about-this-guide.md @@ -5,7 +5,7 @@ as well as to help new contributors get involved in rustc development. There are seven parts to this guide: -1. [Building and debugging `rustc`][p1]: +1. [Building `rustc`][p1]: Contains information that should be useful no matter how you are contributing, about building, debugging, profiling, etc. 2. [Contributing to `rustc`][p2]: @@ -23,7 +23,7 @@ There are seven parts to this guide: 7. [Appendices][p7] at the end with useful reference information. There are a few of these with different information, including a glossary. -[p1]: ./getting-started.md +[p1]: ./building/how-to-build-and-run.html [p2]: ./contributing.md [p3]: ./part-2-intro.md [p4]: ./part-3-intro.md diff --git a/src/doc/rustc-dev-guide/src/appendix/glossary.md b/src/doc/rustc-dev-guide/src/appendix/glossary.md index 375db493c..42306dc1c 100644 --- a/src/doc/rustc-dev-guide/src/appendix/glossary.md +++ b/src/doc/rustc-dev-guide/src/appendix/glossary.md @@ -36,6 +36,7 @@ Term | Meaning <span id="infcx">infcx</span> | The type inference context (`InferCtxt`). (see `rustc_middle::infer`) <span id="inf-var">inference variable</span> | When doing type or region inference, an "inference variable" is a kind of special type/region that represents what you are trying to infer. Think of X in algebra. For example, if we are trying to infer the type of a variable in a program, we create an inference variable to represent that unknown type. <span id="intern">intern</span> | Interning refers to storing certain frequently-used constant data, such as strings, and then referring to the data by an identifier (e.g. a `Symbol`) rather than the data itself, to reduce memory usage and number of allocations. See [this chapter](../memory.md) for more info. +<span id="interpreter">interpreter</span> | The heart of const evaluation, running MIR code at compile time. ([see more](../const-eval/interpret.md)) <span id="intrinsic">intrinsic</span> | Intrinsics are special functions that are implemented in the compiler itself but exposed (often unstably) to users. They do magical and dangerous things. (See [`std::intrinsics`](https://doc.rust-lang.org/std/intrinsics/index.html)) <span id="ir">IR</span> | Short for Intermediate Representation, a general term in compilers. During compilation, the code is transformed from raw source (ASCII text) to various IRs. In Rust, these are primarily HIR, MIR, and LLVM IR. Each IR is well-suited for some set of computations. For example, MIR is well-suited for the borrow checker, and LLVM IR is well-suited for codegen because LLVM accepts it. <span id="irlo">IRLO</span> | `IRLO` or `irlo` is sometimes used as an abbreviation for [internals.rust-lang.org](https://internals.rust-lang.org). @@ -47,7 +48,7 @@ Term | Meaning <span id="llvm">[LLVM]</span> | (actually not an acronym :P) an open-source compiler backend. It accepts LLVM IR and outputs native binaries. Various languages (e.g. Rust) can then implement a compiler front-end that outputs LLVM IR and use LLVM to compile to all the platforms LLVM supports. <span id="memoization">memoization</span> | The process of storing the results of (pure) computations (such as pure function calls) to avoid having to repeat them in the future. This is typically a trade-off between execution speed and memory usage. <span id="mir">MIR</span> | The Mid-level IR that is created after type-checking for use by borrowck and codegen. ([see more](../mir/index.md)) -<span id="miri">miri</span> | An interpreter for MIR used for constant evaluation. ([see more](../miri.md)) +<span id="miri">Miri</span> | A tool to detect Undefined Behavior in (unsafe) Rust code. ([see more](https://github.com/rust-lang/miri)) <span id="mono">monomorphization</span> | The process of taking generic implementations of types and functions and instantiating them with concrete types. For example, in the code we might have `Vec<T>`, but in the final executable, we will have a copy of the `Vec` code for every concrete type used in the program (e.g. a copy for `Vec<usize>`, a copy for `Vec<MyStruct>`, etc). <span id="normalize">normalize</span> | A general term for converting to a more canonical form, but in the case of rustc typically refers to [associated type normalization](../traits/goals-and-clauses.md#normalizeprojection---type). <span id="newtype">newtype</span> | A wrapper around some other type (e.g., `struct Foo(T)` is a "newtype" for `T`). This is commonly used in Rust to give a stronger type for indices. diff --git a/src/doc/rustc-dev-guide/src/backend/codegen.md b/src/doc/rustc-dev-guide/src/backend/codegen.md index 5feea5202..e2c92430e 100644 --- a/src/doc/rustc-dev-guide/src/backend/codegen.md +++ b/src/doc/rustc-dev-guide/src/backend/codegen.md @@ -3,7 +3,7 @@ Code generation (or "codegen") is the part of the compiler that actually generates an executable binary. Usually, rustc uses LLVM for code generation, -bu there is also support for [Cranelift] and [GCC]. +but there is also support for [Cranelift] and [GCC]. The key is that rustc doesn't implement codegen itself. It's worth noting, though, that in the Rust source code, many parts of the backend have `codegen` in their names diff --git a/src/doc/rustc-dev-guide/src/backend/debugging.md b/src/doc/rustc-dev-guide/src/backend/debugging.md index 791a61fbe..26375204e 100644 --- a/src/doc/rustc-dev-guide/src/backend/debugging.md +++ b/src/doc/rustc-dev-guide/src/backend/debugging.md @@ -222,7 +222,7 @@ really helpful for this. 1. Once you have some LLVM IR for the problematic code (see above), you can create a minimal working example with Godbolt. Go to -[gcc.godbolt.org](https://gcc.godbolt.org). +[llvm.godbolt.org](https://llvm.godbolt.org). 2. Choose `LLVM-IR` as programming language. diff --git a/src/doc/rustc-dev-guide/src/building/bootstrapping.md b/src/doc/rustc-dev-guide/src/building/bootstrapping.md index 939c47f1b..3bacc21d3 100644 --- a/src/doc/rustc-dev-guide/src/building/bootstrapping.md +++ b/src/doc/rustc-dev-guide/src/building/bootstrapping.md @@ -54,7 +54,7 @@ and its associated dynamic libraries, which `x.py` will download for you. (You can also configure `x.py` to use something else.) -The stage0 compiler is then used only to compile `rustbuild`, `std`, and `rustc`. +The stage0 compiler is then used only to compile `src/bootstrap`, `std`, and `rustc`. When compiling `rustc`, the stage0 compiler uses the freshly compiled `std`. There are two concepts at play here: a compiler (with its set of dependencies) @@ -73,9 +73,12 @@ In theory, the stage1 compiler is functionally identical to the stage2 compiler, but in practice there are subtle differences. In particular, the stage1 compiler itself was built by stage0 and hence not by the source in your working directory. -This means that the symbol names used in the compiler source -may not match the symbol names that would have been made by the stage1 compiler, -which can cause problems for dynamic libraries and tests. +This means that the ABI generated by the stage0 compiler may not match the ABI that would have been +made by the stage1 compiler, which can cause problems for dynamic libraries, tests, and tools using +`rustc_private`. + +Note that the `proc_macro` crate avoids this issue with a C FFI layer called `proc_macro::bridge`, +allowing it to be used with stage 1. The `stage2` compiler is the one distributed with `rustup` and all other install methods. However, it takes a very long time to build @@ -226,14 +229,6 @@ another program we are building with the stage N compiler: `build --stage N compiler/rustc` is linking the stage N artifacts to the `std` built by the stage N compiler. -Here is a chart of a full build using `x.py`: - -<img alt="A diagram of the rustc compilation phases" src="../img/rustc_stages.svg" class="center" /> - -Keep in mind this diagram is a simplification, i.e. `rustdoc` can be built at -different stages, the process is a bit different when passing flags such as -`--keep-stage`, or if there are non-host targets. - ### Stages and `std` Note that there are two `std` libraries in play here: @@ -365,7 +360,7 @@ This flag has the following effects: Code which does not use `-Z force-unstable-if-unmarked` should include the `#![feature(rustc_private)]` crate attribute to access these force-unstable -crates. This is needed for things that link `rustc`, such as `miri`, `rls`, or +crates. This is needed for things that link `rustc`, such as `miri` or `clippy`. You can find more discussion about sysroots in: @@ -375,9 +370,46 @@ You can find more discussion about sysroots in: [rustdoc PR]: https://github.com/rust-lang/rust/pull/76728 -### Directories and artifacts generated by `x.py` +## Passing flags to commands invoked by `bootstrap` + +`x.py` allows you to pass stage-specific flags to `rustc` and `cargo` when bootstrapping. +The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as `RUSTFLAGS` to the bootstrap stage +(stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages. +`RUSTFLAGS` will work, but also affects the build of `bootstrap` itself, so it will be rare to want +to use it. +Finally, `MAGIC_EXTRA_RUSTFLAGS` bypasses the `cargo` cache to pass flags to rustc without +recompiling all dependencies. + +`RUSTDOCFLAGS`, `RUSTDOCFLAGS_BOOTSTRAP`, and `RUSTDOCFLAGS_NOT_BOOTSTRAP` are anologous to +`RUSTFLAGS`, but for rustdoc. + +`CARGOFLAGS` will pass arguments to cargo itself (e.g. `--timings`). `CARGOFLAGS_BOOTSTRAP` and +`CARGOFLAGS_NOT_BOOTSTRAP` work analogously to `RUSTFLAGS_BOOTSTRAP`. + +`--test-args` will pass arguments through to the test runner. For `src/test/ui`, this is +compiletest; for unit tests and doctests this is the `libtest` runner. Most test runner accept +`--help`, which you can use to find out the options accepted by the runner. -The following tables indicate the outputs of various stage actions: +## Environment Variables + +During bootstrapping, there are a bunch of compiler-internal environment +variables that are used. If you are trying to run an intermediate version of +`rustc`, sometimes you may need to set some of these environment variables +manually. Otherwise, you get an error like the following: + +```text +thread 'main' panicked at 'RUSTC_STAGE was not set: NotPresent', library/core/src/result.rs:1165:5 +``` + +If `./stageN/bin/rustc` gives an error about environment variables, that +usually means something is quite wrong -- or you're trying to compile e.g. +`rustc` or `std` or something that depends on environment variables. In +the unlikely case that you actually need to invoke rustc in such a situation, +you can tell the bootstrap shim to print all env variables by adding `-vvv` to your `x.py` command. + +### Directories and artifacts generated by `bootstrap` + +This is an incomplete reference for the outputs generated by bootstrap: | Stage 0 Action | Output | |-----------------------------------------------------------|----------------------------------------------| @@ -416,27 +448,3 @@ The following tables indicate the outputs of various stage actions: | copy `rustdoc` | `build/HOST/stage2/bin` | `--stage=2` stops here. - -## Passing stage-specific flags to `rustc` - -`x.py` allows you to pass stage-specific flags to `rustc` when bootstrapping. -The `RUSTFLAGS_BOOTSTRAP` environment variable is passed as RUSTFLAGS to the bootstrap stage -(stage0), and `RUSTFLAGS_NOT_BOOTSTRAP` is passed when building artifacts for later stages. - -## Environment Variables - -During bootstrapping, there are a bunch of compiler-internal environment -variables that are used. If you are trying to run an intermediate version of -`rustc`, sometimes you may need to set some of these environment variables -manually. Otherwise, you get an error like the following: - -```text -thread 'main' panicked at 'RUSTC_STAGE was not set: NotPresent', library/core/src/result.rs:1165:5 -``` - -If `./stageN/bin/rustc` gives an error about environment variables, that -usually means something is quite wrong -- or you're trying to compile e.g. -`rustc` or `std` or something that depends on environment variables. In -the unlikely case that you actually need to invoke rustc in such a situation, -you can find the environment variable values by adding the following flag to -your `x.py` command: `--on-fail=print-env`. diff --git a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md index cce9d766a..c5cf3166d 100644 --- a/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md +++ b/src/doc/rustc-dev-guide/src/building/how-to-build-and-run.md @@ -150,8 +150,9 @@ This final product (stage1 compiler + libs built using that compiler) is what you need to build other Rust programs (unless you use `#![no_std]` or `#![no_core]`). -You will probably find that building the stage1 `std` is a bottleneck for you** -- but fear not, -there is a (hacky) workaround. See [the section on "recommended workflows"](./suggested.md) below. +You will probably find that building the stage1 `std` is a bottleneck for you, +but fear not, there is a (hacky) workaround... +see [the section on "recommended workflows"](./suggested.md) below. Note that this whole command just gives you a subset of the full `rustc` build. The **full** `rustc` build (what you get with `./x.py build @@ -220,6 +221,15 @@ fall back to using `cargo` from the installed `nightly`, `beta`, or `stable` too `rustup install nightly` if you haven't already. See the [rustup documentation on custom toolchains](https://rust-lang.github.io/rustup/concepts/toolchains.html#custom-toolchains). +**Note:** rust-analyzer and IntelliJ Rust plugin use a component called +`rust-analyzer-proc-macro-srv` to work with proc macros. If you intend to use a +custom toolchain for a project (e.g. via `rustup override set stage1`) you may +want to build this component: + +```bash +./x.py build proc-macro-srv-cli +``` + ## Building targets for cross-compilation To produce a compiler that can cross-compile for other targets, diff --git a/src/doc/rustc-dev-guide/src/building/new-target.md b/src/doc/rustc-dev-guide/src/building/new-target.md index 77833fad1..f999a9472 100644 --- a/src/doc/rustc-dev-guide/src/building/new-target.md +++ b/src/doc/rustc-dev-guide/src/building/new-target.md @@ -102,15 +102,11 @@ unreleased version of `libc`, you can add it to the top-level ```diff diff --git a/Cargo.toml b/Cargo.toml -index be15e50e2bc..4fb1248ba99 100644 +index 1e83f05e0ca..4d0172071c1 100644 --- a/Cargo.toml +++ b/Cargo.toml -@@ -66,10 +66,11 @@ cargo = { path = "src/tools/cargo" } +@@ -113,6 +113,8 @@ cargo-util = { path = "src/tools/cargo/crates/cargo-util" } [patch.crates-io] - # Similar to Cargo above we want the RLS to use a vendored version of `rustfmt` - # that we're shipping as well (to ensure that the rustfmt in RLS and the - # `rustfmt` executable are the same exact version). - rustfmt-nightly = { path = "src/tools/rustfmt" } +libc = { git = "https://github.com/rust-lang/libc", rev = "0bf7ce340699dcbacabdf5f16a242d2219a49ee0" } # See comments in `src/tools/rustc-workspace-hack/README.md` for what's going on diff --git a/src/doc/rustc-dev-guide/src/building/prerequisites.md b/src/doc/rustc-dev-guide/src/building/prerequisites.md index 0783e82ee..100b14aca 100644 --- a/src/doc/rustc-dev-guide/src/building/prerequisites.md +++ b/src/doc/rustc-dev-guide/src/building/prerequisites.md @@ -9,6 +9,7 @@ Before building the compiler, you need the following things installed: * `git` * `ssl` which comes in `libssl-dev` or `openssl-devel` * `pkg-config` if you are compiling on Linux and targeting Linux +* `libstdc++-static` may be required on some Linux distributions such as Fedora and Ubuntu If building LLVM from source (the default), you'll need additional tools: @@ -36,8 +37,10 @@ winget install -e Python.Python.3 winget install -e Kitware.CMake ``` -If any of those is installed already, winget will detect it. -Then edit your systems `PATH` variable and add: `C:\Program Files\CMake\bin`. +If any of those is installed already, winget will detect it. Then edit your system's `PATH` variable +and add: `C:\Program Files\CMake\bin`. See +[this guide on editing the system `PATH`](https://www.java.com/en/download/help/path.html) from the +Java documentation. For more information about building on Windows, see [the `rust-lang/rust` README](https://github.com/rust-lang/rust#building-on-windows). diff --git a/src/doc/rustc-dev-guide/src/building/suggested.md b/src/doc/rustc-dev-guide/src/building/suggested.md index 3e077977d..5c5e571e4 100644 --- a/src/doc/rustc-dev-guide/src/building/suggested.md +++ b/src/doc/rustc-dev-guide/src/building/suggested.md @@ -36,14 +36,18 @@ you can write: <!-- date-check: apr 2022 --><!-- the date comment is for the edi "./build/$TARGET_TRIPLE/stage0/bin/rustfmt", "--edition=2021" ], + "rust-analyzer.procMacro.server": "./build/$TARGET_TRIPLE/stage0/libexec/rust-analyzer-proc-macro-srv", "rust-analyzer.procMacro.enable": true, "rust-analyzer.cargo.buildScripts.enable": true, + "rust-analyzer.cargo.buildScripts.invocationLocation": "root", + "rust-analyzer.cargo.buildScripts.invocationStrategy": "once", "rust-analyzer.cargo.buildScripts.overrideCommand": [ "python3", "x.py", "check", "--json-output" ], + "rust-analyzer.cargo.sysroot": "./build/$TARGET_TRIPLE/stage0-sysroot", "rust-analyzer.rustc.source": "./Cargo.toml", } ``` diff --git a/src/doc/rustc-dev-guide/src/closure.md b/src/doc/rustc-dev-guide/src/closure.md index b43be3213..c3906a80b 100644 --- a/src/doc/rustc-dev-guide/src/closure.md +++ b/src/doc/rustc-dev-guide/src/closure.md @@ -135,10 +135,10 @@ appropriate trait: `Fn` trait for immutable borrow, `FnMut` for mutable borrow, and `FnOnce` for move semantics. Most of the code related to the closure is in the -[`compiler/rustc_typeck/src/check/upvar.rs`][upvar] file and the data structures are +[`compiler/rustc_hir_typeck/src/upvar.rs`][upvar] file and the data structures are declared in the file [`compiler/rustc_middle/src/ty/mod.rs`][ty]. -[upvar]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/check/upvar/index.html +[upvar]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/upvar/index.html [ty]:https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/index.html Before we go any further, let's discuss how we can examine the flow of control through the rustc @@ -146,12 +146,12 @@ codebase. For closures specifically, set the `RUST_LOG` env variable as below an output in a file: ```console -> RUST_LOG=rustc_typeck::check::upvar rustc +stage1 -Z dump-mir=all \ +> RUST_LOG=rustc_hir_typeck::upvar rustc +stage1 -Z dump-mir=all \ <.rs file to compile> 2> <file where the output will be dumped> ``` This uses the stage1 compiler and enables `debug!` logging for the -`rustc_typeck::check::upvar` module. +`rustc_hir_typeck::upvar` module. The other option is to step through the code using lldb or gdb. @@ -164,7 +164,7 @@ Let's start with [`upvar.rs`][upvar]. This file has something called the [`euv::ExprUseVisitor`] which walks the source of the closure and invokes a callback for each upvar that is borrowed, mutated, or moved. -[`euv::ExprUseVisitor`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/expr_use_visitor/struct.ExprUseVisitor.html +[`euv::ExprUseVisitor`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/expr_use_visitor/struct.ExprUseVisitor.html ```rust fn main() { @@ -210,6 +210,6 @@ self.tables .extend(delegate.adjust_upvar_captures); ``` -[`Delegate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/expr_use_visitor/trait.Delegate.html -[ibk]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/check/upvar/struct.InferBorrowKind.html -[cmt]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/mem_categorization/index.html +[`Delegate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/expr_use_visitor/trait.Delegate.html +[ibk]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/upvar/struct.InferBorrowKind.html +[cmt]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/mem_categorization/index.html diff --git a/src/doc/rustc-dev-guide/src/const-eval.md b/src/doc/rustc-dev-guide/src/const-eval.md index 5a11f8cdd..a7b1c8963 100644 --- a/src/doc/rustc-dev-guide/src/const-eval.md +++ b/src/doc/rustc-dev-guide/src/const-eval.md @@ -20,26 +20,72 @@ Additionally constant evaluation can be used to reduce the workload or binary size at runtime by precomputing complex operations at compiletime and only storing the result. +All uses of constant evaluation can either be categorized as "influencing the type system" +(array lengths, enum variant discriminants, const generic parameters), or as solely being +done to precompute expressions to be used at runtime. + Constant evaluation can be done by calling the `const_eval_*` functions of `TyCtxt`. They're the wrappers of the `const_eval` query. +* `const_eval_global_id_for_typeck` evaluates a constant to a valtree, + so the result value can be further inspected by the compiler. +* `const_eval_global_id` evaluate a constant to an "opaque blob" containing its final value; + this is only useful for codegen backends and the CTFE evaluator engine itself. +* `eval_static_initializer` specifically computes the initial values of a static. + Statics are special; all other functions do not represent statics correctly + and have thus assertions preventing their use on statics. + The `const_eval_*` functions use a [`ParamEnv`](./param_env.html) of environment in which the constant is evaluated (e.g. the function within which the constant is used) and a [`GlobalId`]. The `GlobalId` is made up of an `Instance` referring to a constant or static or of an `Instance` of a function and an index into the function's `Promoted` table. -Constant evaluation returns a [`EvalToConstValueResult`] with either the error, or a -representation of the constant. `static` initializers are always represented as -[`miri`](./miri.html) virtual memory allocations (via [`ConstValue::ByRef`]). -Other constants get represented as [`ConstValue::Scalar`] -or [`ConstValue::Slice`] if possible. This means that the `const_eval_*` -functions cannot be used to create miri-pointers to the evaluated constant. -If you need the value of a constant inside Miri, you need to directly work with -[`const_to_op`]. +Constant evaluation returns an [`EvalToValTreeResult`] for type system constants or +[`EvalToConstValueResult`] with either the error, or a representation of the constant. + +Constants for the type system are encoded in "valtree representation". The `ValTree` datastructure +allows us to represent + +* arrays, +* many structs, +* tuples, +* enums and, +* most primitives. + +The basic rule for +being permitted in the type system is that every value must be uniquely represented. In other +words: a specific value must only be representable in one specific way. For example: there is only +one way to represent an array of two integers as a `ValTree`: +`ValTree::Branch(&[ValTree::Leaf(first_int), ValTree;:Leaf(second_int)])`. +Even though theoretically a `[u32; 2]` could be encoded in a `u64` and thus just be a +`ValTree::Leaf(bits_of_two_u32)`, that is not a legal construction of `ValTree` +(and is very complex to do, so it is unlikely anyone is tempted to do so). + +These rules also mean that some values are not representable. There can be no `union`s in type +level constants, as it is not clear how they should be represented, because their active variant +is unknown. Similarly there is no way to represent raw pointers, as addresses are unknown at +compile-time and thus we cannot make any assumptions about them. References on the other hand +*can* be represented, as equality for references is defined as equality on their value, so we +ignore their address and just look at the backing value. We must make sure that the pointer values +of the references are not observable at compile time. We thus encode `&42` exactly like `42`. +Any conversion from +valtree back to codegen constants must reintroduce an actual indirection. At codegen time the +addresses may be deduplicated between multiple uses or not, entirely depending on arbitrary +optimization choices. + +As a consequence, all decoding of `ValTree` must happen by matching on the type first and making +decisions depending on that. The value itself gives no useful information without the type that +belongs to it. + +Other constants get represented as [`ConstValue::Scalar`] or +[`ConstValue::Slice`] if possible. These values are only useful outside the +compile-time interpreter. If you need the value of a constant during +interpretation, you need to directly work with [`const_to_op`]. [`GlobalId`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/struct.GlobalId.html [`ConstValue::Scalar`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/value/enum.ConstValue.html#variant.Scalar [`ConstValue::Slice`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/value/enum.ConstValue.html#variant.Slice [`ConstValue::ByRef`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/value/enum.ConstValue.html#variant.ByRef [`EvalToConstValueResult`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/error/type.EvalToConstValueResult.html +[`EvalToValTreeResult`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/interpret/error/type.EvalToValTreeResult.html [`const_to_op`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_const_eval/interpret/struct.InterpCx.html#method.const_to_op diff --git a/src/doc/rustc-dev-guide/src/miri.md b/src/doc/rustc-dev-guide/src/const-eval/interpret.md index c5de358d2..ee044505e 100644 --- a/src/doc/rustc-dev-guide/src/miri.md +++ b/src/doc/rustc-dev-guide/src/const-eval/interpret.md @@ -1,14 +1,13 @@ -# Miri +# Interpreter <!-- toc --> -The Miri (**MIR** **I**nterpreter) engine is a virtual machine for executing MIR without -compiling to machine code. It is usually invoked via `tcx.const_eval_*` functions. -In the following, we will refer to the Miri engine as just "Miri", but note that -there also is a stand-alone -[tool called "Miri"](https://github.com/rust-lang/miri/) that is based on the -engine (sometimes referred to as Miri-the-tool to disambiguate it from the -engine). +The interpreter is a virtual machine for executing MIR without compiling to +machine code. It is usually invoked via `tcx.const_eval_*` functions. The +interpreter is shared between the compiler (for compile-time function +evaluation, CTFE) and the tool [Miri](https://github.com/rust-lang/miri/), which +uses the same virtual machine to detect Undefined Behavior in (unsafe) Rust +code. If you start out with a constant: @@ -98,7 +97,7 @@ further queries need to be executed in order to get at something as simple as a `usize`. Future evaluations of the same constants will not actually invoke -Miri, but just use the cached result. +the interpreter, but just use the cached result. [`Operand`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_const_eval/interpret/enum.Operand.html [`Immediate`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_const_eval/interpret/enum.Immediate.html @@ -108,7 +107,7 @@ Miri, but just use the cached result. ## Datastructures -Miri's outside-facing datastructures can be found in +The interpreter's outside-facing datastructures can be found in [rustc_middle/src/mir/interpret](https://github.com/rust-lang/rust/blob/master/compiler/rustc_middle/src/mir/interpret). This is mainly the error enum and the [`ConstValue`] and [`Scalar`] types. A `ConstValue` can be either `Scalar` (a single `Scalar`, i.e., integer or thin @@ -124,7 +123,7 @@ in an `Option<u64>` yielding the `Scalar` if possible. ## Memory -To support any kind of pointers, Miri needs to have a "virtual memory" that the +To support any kind of pointers, the interpreter needs to have a "virtual memory" that the pointers can point to. This is implemented in the [`Memory`] type. In the simplest model, every global variable, stack variable and every dynamic allocation corresponds to an [`Allocation`] in that memory. (Actually using an @@ -164,7 +163,7 @@ track of which of its bytes are initialized. ### Global memory and exotic allocations -`Memory` exists only during the Miri evaluation; it gets destroyed when the +`Memory` exists only during evaluation; it gets destroyed when the final value of the constant is computed. In case that constant contains any pointers, those get "interned" and moved to a global "const eval memory" that is part of `TyCtxt`. These allocations stay around for the remaining computation @@ -190,10 +189,10 @@ bytes of its value. ### Pointer values vs Pointer types -One common cause of confusion in Miri is that being a pointer *value* and having +One common cause of confusion in the interpreter is that being a pointer *value* and having a pointer *type* are entirely independent properties. By "pointer value", we refer to a `Scalar::Ptr` containing a `Pointer` and thus pointing somewhere into -Miri's virtual memory. This is in contrast to `Scalar::Raw`, which is just some +the interpreter's virtual memory. This is in contrast to `Scalar::Raw`, which is just some concrete integer. However, a variable of pointer or reference *type*, such as `*const T` or `&T`, @@ -214,7 +213,7 @@ that allow accessing the fields of a `ConstValue` (`ByRef` or otherwise). You sh never have to access an `Allocation` directly except for translating it to the compilation target (at the moment just LLVM). -Miri starts by creating a virtual stack frame for the current constant that is +The interpreter starts by creating a virtual stack frame for the current constant that is being evaluated. There's essentially no difference between a constant and a function with no arguments, except that constants do not allow local (named) variables at the time of writing this guide. @@ -231,7 +230,7 @@ The frames are just a `Vec<Frame>`, there's no way to actually refer to a `Frame`'s memory even if horrible shenanigans are done via unsafe code. The only memory that can be referred to are `Allocation`s. -Miri now calls the `step` method (in +The interpreter now calls the `step` method (in [rustc_const_eval/src/interpret/step.rs](https://github.com/rust-lang/rust/blob/master/compiler/rustc_const_eval/src/interpret/step.rs) ) until it either returns an error or has no further statements to execute. Each statement will now initialize or modify the locals or the virtual memory diff --git a/src/doc/rustc-dev-guide/src/contributing.md b/src/doc/rustc-dev-guide/src/contributing.md index e59bb0a77..279bc2f28 100644 --- a/src/doc/rustc-dev-guide/src/contributing.md +++ b/src/doc/rustc-dev-guide/src/contributing.md @@ -183,6 +183,7 @@ As a developer to this repository, you don't have to treat the following externa differently from other crates that are directly in this repo: * [Clippy](https://github.com/rust-lang/rust-clippy) +* [Miri](https://github.com/rust-lang/miri) * [rustfmt](https://github.com/rust-lang/rustfmt) * [rust-analyzer](https://github.com/rust-lang/rust-analyzer) @@ -249,37 +250,36 @@ subtrees) actually needs to use `git subtree`. ### External Dependencies (submodules) -Currently building Rust will also build the following external projects: +Building Rust will also use external git repositories tracked using [git +submodules]. The complete list may be found in the [`.gitmodules`] file. Some +of these projects are required (like `stdarch` for the standard library) and +some of them are optional (like [Miri]). -* [miri](https://github.com/rust-lang/miri) -* [rls](https://github.com/rust-lang/rls/) +Usage of submodules is discussed more in the [Using Git +chapter](git.md#git-submodules). -We allow breakage of these tools in the nightly channel. Maintainers of these -projects will be notified of the breakages and should fix them as soon as -possible. - -After the external is fixed, one could add the changes with - -```sh -git add path/to/submodule -``` - -outside the submodule. - -In order to prepare your tool-fixing PR, you can run the build locally by doing -`./x.py build src/tools/TOOL`. If you will be editing the sources -there, you may wish to set `submodules = false` in the `config.toml` -to prevent `x.py` from resetting to the original branch. +Some of the submodules are allowed to be in a "broken" state where they +either don't build or their tests don't pass, e.g. the documentation books +like [The Rust Reference]. Maintainers of these projects will be notified +when the project is in a broken state, and they should fix them as soon +as possible. The current status is tracked on the [toolstate website]. +More information may be found on the Forge [Toolstate chapter]. Breakage is not allowed in the beta and stable channels, and must be addressed -before the PR is merged. +before the PR is merged. They are also not allowed to be broken on master in +the week leading up to the beta cut. + +[git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules +[`.gitmodules`]: https://github.com/rust-lang/rust/blob/master/.gitmodules +[The Rust Reference]: https://github.com/rust-lang/reference/ +[toolstate website]: https://rust-lang-nursery.github.io/rust-toolstate/ +[Toolstate chapter]: https://forge.rust-lang.org/infra/toolstate.html #### Breaking Tools Built With The Compiler Rust's build system builds a number of tools that make use of the internals of the compiler and that are hosted in a separate repository, and included in Rust -via git submodules. This includes [RLS](https://github.com/rust-lang/rls) and -[Miri](https://github.com/rust-lang/Miri). If these tools break because of your +via git submodules (such as [Miri]). If these tools break because of your changes, you may run into a sort of "chicken and egg" problem. These tools rely on the latest compiler to be built so you can't update them (in their own repositories) to reflect your changes to the compiler until those changes are @@ -299,7 +299,7 @@ done and the tools are working again, you go back in the compiler and update the tools so they can be distributed again. This should avoid a bunch of synchronization dances and is also much easier on contributors as -there's no need to block on rls/miri/other tools changes going upstream. +there's no need to block on tools changes going upstream. Here are those same steps in detail: @@ -309,8 +309,8 @@ Here are those same steps in detail: from resetting to the original branch after you make your changes. If you need to [update any submodules to their latest versions](#updating-submodules), see the section of this file about that for more information. -2. (optional) Run `./x.py test src/tools/rls` (substituting the submodule - that broke for `rls`). Fix any errors in the submodule (and possibly others). +2. (optional) Run `./x.py test src/tools/cargo` (substituting the submodule + that broke for `cargo`). Fix any errors in the submodule (and possibly others). 3. (optional) Make commits for your changes and send them to upstream repositories as a PR. 4. (optional) Maintainers of these submodules will **not** merge the PR. The PR can't be merged because CI will be broken. You'll want to write a message on the PR referencing @@ -320,71 +320,6 @@ Here are those same steps in detail: 7. (optional) Help land your PR on the upstream repository now that your changes are in nightly. 8. (optional) Send a PR to rust-lang/rust updating the submodule. -#### Updating submodules - -These instructions are specific to updating `rls`, however they may apply -to the other submodules as well. Please help by improving these instructions -if you find any discrepancies or special cases that need to be addressed. - -To update the `rls` submodule, start by running the appropriate -[`git submodule` command](https://git-scm.com/book/en/v2/Git-Tools-Submodules). -For example, to update to the latest commit on the remote master branch, -you may want to run: -``` -git submodule update --remote src/tools/rls -``` -If you run `./x.py build` now, and you are lucky, it may just work. If you see -an error message about patches that did not resolve to any crates, you will need -to complete a few more steps which are outlined with their rationale below. - -*(This error may change in the future to include more information.)* -``` -error: failed to resolve patches for `https://github.com/rust-lang/rls` - -Caused by: - patch for `rls` in `https://github.com/rust-lang/rls` did not resolve to any crates -failed to run: ~/rust/build/x86_64-unknown-linux-gnu/stage0/bin/cargo build --manifest-path ~/rust/src/bootstrap/Cargo.toml -``` - -The [`[patch]`][patchsec] section of `Cargo.toml` can be very useful for -testing. In addition to that, you should read the [Overriding -dependencies][overriding] section of the documentation. - -[patchsec]: http://doc.crates.io/manifest.html#the-patch-section -[overriding]: http://doc.crates.io/specifying-dependencies.html#overriding-dependencies - -Specifically, the following [section in Overriding dependencies][testingbugfix] -reveals what the problem is: - -[testingbugfix]: http://doc.crates.io/specifying-dependencies.html#testing-a-bugfix - -> Next up we need to ensure that our lock file is updated to use this new -> version of uuid so our project uses the locally checked out copy instead of -> one from crates.io. The way `[patch]` works is that it'll load the dependency -> at ../path/to/uuid and then whenever crates.io is queried for versions of -> uuid it'll also return the local version. -> -> This means that the version number of the local checkout is significant and -> will affect whether the patch is used. Our manifest declared uuid = "1.0" -> which means we'll only resolve to >= 1.0.0, < 2.0.0, and Cargo's greedy -> resolution algorithm also means that we'll resolve to the maximum version -> within that range. Typically this doesn't matter as the version of the git -> repository will already be greater or match the maximum version published on -> crates.io, but it's important to keep this in mind! - -This says that when we updated the submodule, the version number in our -`src/tools/rls/Cargo.toml` changed. The new version is different from -the version in `Cargo.lock`, so the build can no longer continue. - -To resolve this, we need to update `Cargo.lock`. Luckily, cargo provides a -command to do this easily. - -``` -$ cargo update -p rls -``` - -This should change the version listed in `Cargo.lock` to the new version you updated -the submodule to. Running `./x.py build` should work now. ## Writing Documentation diff --git a/src/doc/rustc-dev-guide/src/diagnostics.md b/src/doc/rustc-dev-guide/src/diagnostics.md index 0f0bfd895..e1d5fbe1a 100644 --- a/src/doc/rustc-dev-guide/src/diagnostics.md +++ b/src/doc/rustc-dev-guide/src/diagnostics.md @@ -314,10 +314,10 @@ reporting errors. [errors]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/index.html -Diagnostics can be implemented as types which implement the `SessionDiagnostic` +Diagnostics can be implemented as types which implement the `IntoDiagnostic` trait. This is preferred for new diagnostics as it enforces a separation between diagnostic emitting logic and the main code paths. For less-complex -diagnostics, the `SessionDiagnostic` trait can be derived -- see [Diagnostic +diagnostics, the `IntoDiagnostic` trait can be derived -- see [Diagnostic structs][diagnostic-structs]. Within the trait implementation, the APIs described below can be used as normal. @@ -388,10 +388,8 @@ In addition to telling the user exactly _why_ their code is wrong, it's oftentimes furthermore possible to tell them how to fix it. To this end, `DiagnosticBuilder` offers a structured suggestions API, which formats code suggestions pleasingly in the terminal, or (when the `--error-format json` flag -is passed) as JSON for consumption by tools, most notably the [Rust Language -Server][rls] and [`rustfix`][rustfix]. +is passed) as JSON for consumption by tools like [`rustfix`][rustfix]. -[rls]: https://github.com/rust-lang/rls [rustfix]: https://github.com/rust-lang/rustfix Not all suggestions should be applied mechanically, they have a degree of @@ -757,7 +755,7 @@ then dumped into the `Session::buffered_lints` used by the rest of the compiler. The compiler accepts an `--error-format json` flag to output diagnostics as JSON objects (for the benefit of tools such as `cargo -fix` or the RLS). It looks like this: +fix`). It looks like this: ```console $ rustc json_error_demo.rs --error-format json @@ -771,7 +769,7 @@ object, but the series of lines taken together is, unfortunately, not valid JSON, thwarting tools and tricks (such as [piping to `python3 -m json.tool`](https://docs.python.org/3/library/json.html#module-json.tool)) that require such. (One speculates that this was intentional for LSP -performance purposes, so that each line/object can be sent to RLS as +performance purposes, so that each line/object can be sent as it is flushed?) Also note the "rendered" field, which contains the "human" output as a diff --git a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md index f456474c7..d51e79348 100644 --- a/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md +++ b/src/doc/rustc-dev-guide/src/diagnostics/diagnostic-structs.md @@ -1,14 +1,14 @@ # Diagnostic and subdiagnostic structs rustc has two diagnostic derives that can be used to create simple diagnostics, which are recommended to be used when they are applicable: -`#[derive(SessionDiagnostic)]` and `#[derive(SessionSubdiagnostic)]`. +`#[derive(Diagnostic)]` and `#[derive(Subdiagnostic)]`. Diagnostics created with the derive macros can be translated into different languages and each has a slug that uniquely identifies the diagnostic. -## `#[derive(SessionDiagnostic)]` +## `#[derive(Diagnostic)]` Instead of using the `DiagnosticBuilder` API to create and emit diagnostics, -the `SessionDiagnostic` derive can be used. `#[derive(SessionDiagnostic)]` is +the `Diagnostic` derive can be used. `#[derive(Diagnostic)]` is only applicable for simple diagnostics that don't require much logic in deciding whether or not to add additional subdiagnostics. @@ -16,24 +16,24 @@ Consider the [definition][defn] of the "field already declared" diagnostic shown below: ```rust,ignore -#[derive(SessionDiagnostic)] -#[diag(typeck::field_already_declared, code = "E0124")] +#[derive(Diagnostic)] +#[diag(hir_analysis_field_already_declared, code = "E0124")] pub struct FieldAlreadyDeclared { pub field_name: Ident, #[primary_span] #[label] pub span: Span, - #[label(typeck::previous_decl_label)] + #[label(hir_analysis_previous_decl_label)] pub prev_span: Span, } ``` -`SessionDiagnostic` can only be applied to structs. Every `SessionDiagnostic` +`Diagnostic` can only be applied to structs. Every `Diagnostic` has to have one attribute, `#[diag(...)]`, applied to the struct itself. If an error has an error code (e.g. "E0624"), then that can be specified using the `code` sub-attribute. Specifying a `code` isn't mandatory, but if you are -porting a diagnostic that uses `DiagnosticBuilder` to use `SessionDiagnostic` +porting a diagnostic that uses `DiagnosticBuilder` to use `Diagnostic` then you should keep the code if there was one. `#[diag(..)]` must provide a slug as the first positional argument (a path to an @@ -47,16 +47,16 @@ In our example, the Fluent message for the "field already declared" diagnostic looks like this: ```fluent -typeck_field_already_declared = +hir_analysis_field_already_declared = field `{$field_name}` is already declared .label = field already declared .previous_decl_label = `{$field_name}` first declared here ``` -`typeck_field_already_declared` is the slug from our example and is followed +`hir_analysis_field_already_declared` is the slug from our example and is followed by the diagnostic message. -Every field of the `SessionDiagnostic` which does not have an annotation is +Every field of the `Diagnostic` which does not have an annotation is available in Fluent messages as a variable, like `field_name` in the example above. Fields can be annotated `#[skip_arg]` if this is undesired. @@ -66,19 +66,19 @@ of the diagnostic. Diagnostics are more than just their primary message, they often include labels, notes, help messages and suggestions, all of which can also be -specified on a `SessionDiagnostic`. +specified on a `Diagnostic`. `#[label]`, `#[help]` and `#[note]` can all be applied to fields which have the type `Span`. Applying any of these attributes will create the corresponding subdiagnostic with that `Span`. These attributes will look for their diagnostic message in a Fluent attribute attached to the primary Fluent message. In our example, `#[label]` will look for -`typeck_field_already_declared.label` (which has the message "field already +`hir_analysis_field_already_declared.label` (which has the message "field already declared"). If there is more than one subdiagnostic of the same type, then these attributes can also take a value that is the attribute name to look for (e.g. `previous_decl_label` in our example). -Other types have special behavior when used in a `SessionDiagnostic` derive: +Other types have special behavior when used in a `Diagnostic` derive: - Any attribute applied to an `Option<T>` and will only emit a subdiagnostic if the option is `Some(..)`. @@ -107,21 +107,21 @@ the value of the `field_name` field of the struct), not a Fluent identifier. `applicability` can be used to specify the applicability in the attribute, it cannot be used when the field's type contains an `Applicability`. -In the end, the `SessionDiagnostic` derive will generate an implementation of -`SessionDiagnostic` that looks like the following: +In the end, the `Diagnostic` derive will generate an implementation of +`IntoDiagnostic` that looks like the following: ```rust,ignore -impl SessionDiagnostic<'_> for FieldAlreadyDeclared { - fn into_diagnostic(self, sess: &'_ rustc_session::Session) -> DiagnosticBuilder<'_> { - let mut diag = sess.struct_err(rustc_errors::fluent::typeck::field_already_declared); +impl IntoDiagnostic<'_> for FieldAlreadyDeclared { + fn into_diagnostic(self, handler: &'_ rustc_errors::Handler) -> DiagnosticBuilder<'_> { + let mut diag = handler.struct_err(rustc_errors::fluent::hir_analysis_field_already_declared); diag.set_span(self.span); diag.span_label( self.span, - rustc_errors::fluent::typeck::label + rustc_errors::fluent::hir_analysis_label ); diag.span_label( self.prev_span, - rustc_errors::fluent::typeck::previous_decl_label + rustc_errors::fluent::hir_analysis_previous_decl_label ); diag } @@ -141,22 +141,20 @@ tcx.sess.emit_err(FieldAlreadyDeclared { ``` ### Reference -`#[derive(SessionDiagnostic)]` and `#[derive(LintDiagnostic)]` support the +`#[derive(Diagnostic)]` and `#[derive(LintDiagnostic)]` support the following attributes: - `#[diag(slug, code = "...")]` - - _Applied to struct._ + - _Applied to struct or enum variant._ - _Mandatory_ - Defines the text and error code to be associated with the diagnostic. - Slug (_Mandatory_) - Uniquely identifies the diagnostic and corresponds to its Fluent message, mandatory. - - A path to an item in `rustc_errors::fluent`. Always in a module starting - with a Fluent resource name (which is typically the name of the crate - that the diagnostic is from), e.g. - `rustc_errors::fluent::typeck::field_already_declared` + - A path to an item in `rustc_errors::fluent`, e.g. + `rustc_errors::fluent::hir_analysis_field_already_declared` (`rustc_errors::fluent` is implicit in the attribute, so just - `typeck::field_already_declared`). + `hir_analysis_field_already_declared`). - See [translation documentation](./translation.md). - `code = "..."` (_Optional_) - Specifies the error code. @@ -191,14 +189,12 @@ following attributes: - _Applied to `(Span, MachineApplicability)` or `Span` fields._ - Adds a suggestion subdiagnostic. - Slug (_Mandatory_) - - A path to an item in `rustc_errors::fluent`. Always in a module starting - with a Fluent resource name (which is typically the name of the crate - that the diagnostic is from), e.g. - `rustc_errors::fluent::typeck::field_already_declared` + - A path to an item in `rustc_errors::fluent`, e.g. + `rustc_errors::fluent::hir_analysis_field_already_declared` (`rustc_errors::fluent` is implicit in the attribute, so just - `typeck::field_already_declared`). Fluent attributes for all messages - exist as top-level items in that module (so `typeck_message.attr` is just - `typeck::attr`). + `hir_analysis_field_already_declared`). Fluent attributes for all messages + exist as top-level items in that module (so `hir_analysis_message.attr` is just + `attr`). - See [translation documentation](./translation.md). - Defaults to `rustc_errors::fluent::_subdiag::suggestion` (or - `.suggestion` in Fluent). @@ -210,20 +206,20 @@ following attributes: `has-placeholders` or `unspecified`. - `#[subdiagnostic]` - _Applied to a type that implements `AddToDiagnostic` (from - `#[derive(SessionSubdiagnostic)]`)._ + `#[derive(Subdiagnostic)]`)._ - Adds the subdiagnostic represented by the subdiagnostic struct. - `#[primary_span]` (_Optional_) - - _Applied to `Span` fields on `SessionSubdiagnostic`s. Not used for `LintDiagnostic`s._ + - _Applied to `Span` fields on `Subdiagnostic`s. Not used for `LintDiagnostic`s._ - Indicates the primary span of the diagnostic. - `#[skip_arg]` (_Optional_) - _Applied to any field._ - Prevents the field from being provided as a diagnostic argument. -## `#[derive(SessionSubdiagnostic)]` +## `#[derive(Subdiagnostic)]` It is common in the compiler to write a function that conditionally adds a specific subdiagnostic to an error if it is applicable. Oftentimes these subdiagnostics could be represented using a diagnostic struct even if the -overall diagnostic could not. In this circumstance, the `SessionSubdiagnostic` +overall diagnostic could not. In this circumstance, the `Subdiagnostic` derive can be used to represent a partial diagnostic (e.g a note, label, help or suggestion) as a struct. @@ -231,14 +227,14 @@ Consider the [definition][subdiag_defn] of the "expected return type" label shown below: ```rust -#[derive(SessionSubdiagnostic)] +#[derive(Subdiagnostic)] pub enum ExpectedReturnTypeLabel<'tcx> { - #[label(typeck::expected_default_return_type)] + #[label(hir_analysis_expected_default_return_type)] Unit { #[primary_span] span: Span, }, - #[label(typeck::expected_return_type)] + #[label(hir_analysis_expected_return_type)] Other { #[primary_span] span: Span, @@ -247,9 +243,9 @@ pub enum ExpectedReturnTypeLabel<'tcx> { } ``` -Unlike `SessionDiagnostic`, `SessionSubdiagnostic` can be applied to structs or +Unlike `Diagnostic`, `Subdiagnostic` can be applied to structs or enums. Attributes that are placed on the type for structs are placed on each -variants for enums (or vice versa). Each `SessionSubdiagnostic` should have one +variants for enums (or vice versa). Each `Subdiagnostic` should have one attribute applied to the struct or each variant, one of: - `#[label(..)]` for defining a label @@ -268,9 +264,9 @@ In our example, the Fluent message for the "expected return type" label looks like this: ```fluent -typeck_expected_default_return_type = expected `()` because of default return type +hir_analysis_expected_default_return_type = expected `()` because of default return type -typeck_expected_return_type = expected `{$expected}` because of return type +hir_analysis_expected_return_type = expected `{$expected}` because of return type ``` Using the `#[primary_span]` attribute on a field (with type `Span`) will denote @@ -281,7 +277,7 @@ Every field of the type/variant which does not have an annotation is available in Fluent messages as a variable. Fields can be annotated `#[skip_arg]` if this is undesired. -Like `SessionDiagnostic`, `SessionSubdiagnostic` supports `Option<T>` and +Like `Diagnostic`, `Subdiagnostic` supports `Option<T>` and `Vec<T>` fields. Suggestions can be emitted using one of four attributes on the type/variant: @@ -306,8 +302,8 @@ following sub-attributes: Applicabilities can also be specified as a field (of type `Applicability`) using the `#[applicability]` attribute. -In the end, the `SessionSubdiagnostic` derive will generate an implementation -of `SessionSubdiagnostic` that looks like the following: +In the end, the `Subdiagnostic` derive will generate an implementation +of `AddToDiagnostic` that looks like the following: ```rust impl<'tcx> AddToDiagnostic for ExpectedReturnTypeLabel<'tcx> { @@ -315,11 +311,11 @@ impl<'tcx> AddToDiagnostic for ExpectedReturnTypeLabel<'tcx> { use rustc_errors::{Applicability, IntoDiagnosticArg}; match self { ExpectedReturnTypeLabel::Unit { span } => { - diag.span_label(span, rustc_errors::fluent::typeck::expected_default_return_type) + diag.span_label(span, rustc_errors::fluent::hir_analysis_expected_default_return_type) } ExpectedReturnTypeLabel::Other { span, expected } => { diag.set_arg("expected", expected); - diag.span_label(span, rustc_errors::fluent::typeck::expected_return_type) + diag.span_label(span, rustc_errors::fluent::hir_analysis_expected_return_type) } } @@ -333,7 +329,7 @@ diagnostic or by assigning it to a `#[subdiagnostic]`-annotated field of a diagnostic struct. ### Reference -`#[derive(SessionSubdiagnostic)]` supports the following attributes: +`#[derive(Subdiagnostic)]` supports the following attributes: - `#[label(slug)]`, `#[help(slug)]` or `#[note(slug)]` - _Applied to struct or enum variant. Mutually exclusive with struct/enum variant attributes._ @@ -342,26 +338,22 @@ diagnostic struct. - Slug (_Mandatory_) - Uniquely identifies the diagnostic and corresponds to its Fluent message, mandatory. - - A path to an item in `rustc_errors::fluent`. Always in a module starting - with a Fluent resource name (which is typically the name of the crate - that the diagnostic is from), e.g. - `rustc_errors::fluent::typeck::field_already_declared` + - A path to an item in `rustc_errors::fluent`, e.g. + `rustc_errors::fluent::hir_analysis_field_already_declared` (`rustc_errors::fluent` is implicit in the attribute, so just - `typeck::field_already_declared`). + `hir_analysis_field_already_declared`). - See [translation documentation](./translation.md). - `#[suggestion{,_hidden,_short,_verbose}(slug, code = "...", applicability = "...")]` - _Applied to struct or enum variant. Mutually exclusive with struct/enum variant attributes._ - _Mandatory_ - Defines the type to be representing a suggestion. - Slug (_Mandatory_) - - A path to an item in `rustc_errors::fluent`. Always in a module starting - with a Fluent resource name (which is typically the name of the crate - that the diagnostic is from), e.g. - `rustc_errors::fluent::typeck::field_already_declared` + - A path to an item in `rustc_errors::fluent`, e.g. + `rustc_errors::fluent::hir_analysis_field_already_declared` (`rustc_errors::fluent` is implicit in the attribute, so just - `typeck::field_already_declared`). Fluent attributes for all messages - exist as top-level items in that module (so `typeck_message.attr` is just - `typeck::attr`). + `hir_analysis::field_already_declared`). Fluent attributes for all messages + exist as top-level items in that module (so `hir_analysis_message.attr` is just + `hir_analysis::attr`). - See [translation documentation](./translation.md). - Defaults to `rustc_errors::fluent::_subdiag::suggestion` (or - `.suggestion` in Fluent). @@ -376,19 +368,32 @@ diagnostic struct. - `maybe-incorrect` - `has-placeholders` - `unspecified` -- `#[primary_span]` (_Mandatory_ for labels and suggestions; _optional_ otherwise) +- `#[multipart_suggestion{,_hidden,_short,_verbose}(slug, applicability = "...")]` + - _Applied to struct or enum variant. Mutually exclusive with struct/enum variant attributes._ + - _Mandatory_ + - Defines the type to be representing a multipart suggestion. + - Slug (_Mandatory_): see `#[suggestion]` + - `applicability = "..."` (_Optional_): see `#[suggestion]` +- `#[primary_span]` (_Mandatory_ for labels and suggestions; _optional_ otherwise; not applicable +to multipart suggestions) - _Applied to `Span` fields._ - Indicates the primary span of the subdiagnostic. -- `#[applicability]` (_Optional_; only applicable to suggestions) +- `#[suggestion_part(code = "...")]` (_Mandatory_; only applicable to multipart suggestions) + - _Applied to `Span` fields._ + - Indicates the span to be one part of the multipart suggestion. + - `code = "..."` (_Mandatory_) + - Value is a format string indicating the code to be suggested as a + replacement. +- `#[applicability]` (_Optional_; only applicable to (simple and multipart) suggestions) - _Applied to `Applicability` fields._ - Indicates the applicability of the suggestion. - `#[skip_arg]` (_Optional_) - _Applied to any field._ - Prevents the field from being provided as a diagnostic argument. -[defn]: https://github.com/rust-lang/rust/blob/bbe9d27b8ff36da56638aa43d6d0cdfdf89a4e57/compiler/rustc_typeck/src/errors.rs#L65-L74 -[use]: https://github.com/rust-lang/rust/blob/eb82facb1626166188d49599a3313fc95201f556/compiler/rustc_typeck/src/collect.rs#L981-L985 +[defn]: https://github.com/rust-lang/rust/blob/6201eabde85db854c1ebb57624be5ec699246b50/compiler/rustc_hir_analysis/src/errors.rs#L68-L77 +[use]: https://github.com/rust-lang/rust/blob/f1112099eba41abadb6f921df7edba70affe92c5/compiler/rustc_hir_analysis/src/collect.rs#L823-L827 -[subdiag_defn]: https://github.com/rust-lang/rust/blob/e70c60d34b9783a2fd3171d88d248c2e0ec8ecdd/compiler/rustc_typeck/src/errors.rs#L220-L233 -[subdiag_use_1]: https://github.com/rust-lang/rust/blob/e70c60d34b9783a2fd3171d88d248c2e0ec8ecdd/compiler/rustc_typeck/src/check/fn_ctxt/suggestions.rs#L556-L560 -[subdiag_use_2]: https://github.com/rust-lang/rust/blob/e70c60d34b9783a2fd3171d88d248c2e0ec8ecdd/compiler/rustc_typeck/src/check/fn_ctxt/suggestions.rs#L575-L579 +[subdiag_defn]: https://github.com/rust-lang/rust/blob/f1112099eba41abadb6f921df7edba70affe92c5/compiler/rustc_hir_analysis/src/errors.rs#L221-L234 +[subdiag_use_1]: https://github.com/rust-lang/rust/blob/f1112099eba41abadb6f921df7edba70affe92c5/compiler/rustc_hir_analysis/src/check/fn_ctxt/suggestions.rs#L670-L674 +[subdiag_use_2]: https://github.com/rust-lang/rust/blob/f1112099eba41abadb6f921df7edba70affe92c5/compiler/rustc_hir_analysis/src/check/fn_ctxt/suggestions.rs#L704-L707 diff --git a/src/doc/rustc-dev-guide/src/diagnostics/translation.md b/src/doc/rustc-dev-guide/src/diagnostics/translation.md index 5bb37fbc2..e36333039 100644 --- a/src/doc/rustc-dev-guide/src/diagnostics/translation.md +++ b/src/doc/rustc-dev-guide/src/diagnostics/translation.md @@ -11,7 +11,7 @@ There are two ways of writing translatable diagnostics: diagnostic structs). See [the diagnostic and subdiagnostic structs documentation](./diagnostic-structs.md). 2. Using typed identifiers with `DiagnosticBuilder` APIs (in - `SessionDiagnostic` implementations). + `Diagnostic` implementations). When adding or changing a translatable diagnostic, you don't need to worry about the translations, only updating the original English message. Currently, @@ -127,14 +127,12 @@ pub static DEFAULT_LOCALE_RESOURCES: &'static [&'static str] = &[ ]; mod fluent_generated { - mod typeck { - pub const field_multiply_specified_in_initializer: DiagnosticMessage = - DiagnosticMessage::new("typeck_field_multiply_specified_in_initializer"); - pub const label: SubdiagnosticMessage = - SubdiagnosticMessage::attr("label"); - pub const label_previous_use: SubdiagnosticMessage = - SubdiagnosticMessage::attr("previous_use_label"); - } + pub const typeck_field_multiply_specified_in_initializer: DiagnosticMessage = + DiagnosticMessage::new("typeck_field_multiply_specified_in_initializer"); + pub const label: SubdiagnosticMessage = + SubdiagnosticMessage::attr("label"); + pub const label_previous_use: SubdiagnosticMessage = + SubdiagnosticMessage::attr("previous_use_label"); } ``` @@ -143,9 +141,9 @@ mod fluent_generated { ```rust use rustc_errors::fluent; -let mut err = sess.struct_span_err(span, fluent::typeck::field_multiply_specified_in_initializer); -err.span_label(span, fluent::typeck::label); -err.span_label(previous_use_span, fluent::typeck::previous_use_label); +let mut err = sess.struct_span_err(span, fluent::typeck_field_multiply_specified_in_initializer); +err.span_label(span, fluent::label); +err.span_label(previous_use_span, fluent::previous_use_label); err.emit(); ``` diff --git a/src/doc/rustc-dev-guide/src/feature-gates.md b/src/doc/rustc-dev-guide/src/feature-gates.md index 229281f2f..9e9a83ea6 100644 --- a/src/doc/rustc-dev-guide/src/feature-gates.md +++ b/src/doc/rustc-dev-guide/src/feature-gates.md @@ -9,7 +9,9 @@ modifying feature gates. See ["Stability in code"] for help with adding a new feature; this section just covers how to add the feature gate *declaration*. -Add a feature gate declaration to `rustc_feature/src/active.rs` in the active +First, add the feature name to `rustc_span/src/symbol.rs` in the `Symbols {...}` block. + +Then, add a feature gate declaration to `rustc_feature/src/active.rs` in the active `declare_features` block: ```rust,ignore diff --git a/src/doc/rustc-dev-guide/src/generics.md b/src/doc/rustc-dev-guide/src/generics.md index 13549b2fb..0173bee8f 100644 --- a/src/doc/rustc-dev-guide/src/generics.md +++ b/src/doc/rustc-dev-guide/src/generics.md @@ -125,7 +125,7 @@ You may have a couple of followup questions… `MyStruct`: `Adt(Foo, &[Param(0), Param(1)])`. **`subst`** How do we actually do the substitutions? There is a function for that too! You use -[`subst`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/subst/trait.Subst.html) to +[`subst`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/subst/struct.EarlyBinder.html#method.subst) to replace a `SubstRef` with another list of types. [Here is an example of actually using `subst` in the compiler][substex]. The exact details are not @@ -134,7 +134,7 @@ a real `ty::Ty`. You can see that we first get some substitutions (`substs`). T `type_of` to get a type and call `ty.subst(substs)` to get a new version of `ty` with the substitutions made. -[substex]: https://github.com/rust-lang/rust/blob/597f432489f12a3f33419daa039ccef11a12c4fd/src/librustc_typeck/astconv.rs#L942-L953 +[substex]: https://github.com/rust-lang/rust/blob/0940040c0486a536be4f8685c7dd9a078f9e87c2/compiler/rustc_hir_analysis/src/astconv/mod.rs#L1231-L1242 **Note on indices:** It is possible for the indices in `Param` to not match with what we expect. For example, the index could be out of bounds or it could be the index of a lifetime when we were diff --git a/src/doc/rustc-dev-guide/src/git.md b/src/doc/rustc-dev-guide/src/git.md index 5899753ba..65397e349 100644 --- a/src/doc/rustc-dev-guide/src/git.md +++ b/src/doc/rustc-dev-guide/src/git.md @@ -148,8 +148,8 @@ Your branch is up to date with 'origin/master'. Changes not staged for commit: (use "git add <file>..." to update what will be committed) (use "git restore <file>..." to discard changes in working directory) + modified: src/llvm-project (new commits) modified: src/tools/cargo (new commits) - modified: src/tools/rls (new commits) no changes added to commit (use "git add" and/or "git commit -a") ``` @@ -176,6 +176,8 @@ There is a workaround in [the issue][#77620-workaround]. [#77620]: https://github.com/rust-lang/rust/issues/77620 [#77620-workaround]: https://github.com/rust-lang/rust/issues/77620#issuecomment-705228229 +(Note that as of Sept 2022 `miri` is a subtree and not a submodule.) + ## Rebasing and Conflicts When you edit your code locally, you are making changes to the version of @@ -391,41 +393,41 @@ you might want to get used to the main concepts of Git before reading this secti The `rust-lang/rust` repository uses [Git submodules] as a way to use other Rust projects from within the `rust` repo. Examples include Rust's fork of -`llvm-project` and many devtools such as `cargo` and `rls`. +`llvm-project`, `cargo` and libraries like `stdarch` and `backtrace`. Those projects are developed and maintained in an separate Git (and GitHub) repository, and they have their own Git history/commits, issue tracker and PRs. Submodules allow us to create some sort of embedded sub-repository inside the `rust` repository and use them like they were directories in the `rust` repository. -Take `miri` for example. `miri` is maintained in the [`rust-lang/miri`] repository, -but it is used in `rust-lang/rust` by the compiler for const evaluation. We bring it -in `rust` as a submodule, in the `src/tools/miri` folder. +Take `llvm-project` for example. `llvm-project` is maintained in the [`rust-lang/llvm-project`] +repository, but it is used in `rust-lang/rust` by the compiler for code generation and +optimization. We bring it in `rust` as a submodule, in the `src/llvm-project` folder. The contents of submodules are ignored by Git: submodules are in some sense isolated -from the rest of the repository. However, if you try to `cd src/tools/miri` and then +from the rest of the repository. However, if you try to `cd src/llvm-project` and then run `git status`: ``` -HEAD detached at 3fafb835 +HEAD detached at 9567f08afc943 nothing to commit, working tree clean ``` -As far as git is concerned, you are no longer in the `rust` repo, but in the `miri` repo. +As far as git is concerned, you are no longer in the `rust` repo, but in the `llvm-project` repo. You will notice that we are in "detached HEAD" state, i.e. not on a branch but on a particular commit. This is because, like any dependency, we want to be able to control which version to use. Submodules allow us to do just that: every submodule is "pinned" to a certain commit, which doesn't change unless modified manually. If you use `git checkout <commit>` -in the `miri` directory and go back to the `rust` directory, you can stage this -change like any other, e.g. by running `git add src/tools/miri`. (Note that if +in the `llvm-project` directory and go back to the `rust` directory, you can stage this +change like any other, e.g. by running `git add src/llvm-project`. (Note that if you *don't* stage the change to commit, then you run the risk that running `x.py` will just undo your change by switching back to the previous commit when it automatically "updates" the submodules.) This version selection is usually done by the maintainers of the project, and -looks like [this][miri-update]. +looks like [this][llvm-update]. Git submodules take some time to get used to, so don't worry if it isn't perfectly clear yet. You will rarely have to use them directly and, again, you don't need @@ -434,6 +436,5 @@ exist and that they correspond to some sort of embedded subrepository dependency that Git can nicely and fairly conveniently handle for us. [Git submodules]: https://git-scm.com/book/en/v2/Git-Tools-Submodules -[`rust-toolstate`]: https://rust-lang-nursery.github.io/rust-toolstate/ -[`rust-lang/miri`]: https://github.com/rust-lang/miri -[miri-update]: https://github.com/rust-lang/rust/pull/77500/files +[`rust-lang/llvm-project`]: https://github.com/rust-lang/llvm-project +[llvm-update]: https://github.com/rust-lang/rust/pull/99464/files diff --git a/src/doc/rustc-dev-guide/src/img/rustc_stages.svg b/src/doc/rustc-dev-guide/src/img/rustc_stages.svg deleted file mode 100644 index 25f7ab11b..000000000 --- a/src/doc/rustc-dev-guide/src/img/rustc_stages.svg +++ /dev/null @@ -1,3 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd"> -<svg xmlns="http://www.w3.org/2000/svg" style="background-color: rgb(255, 255, 255);" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="581px" height="816px" viewBox="-0.5 -0.5 581 816"><defs/><g><rect x="0" y="0" width="580" height="315" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="0" y="665" width="580" height="150" fill="#ffffff" stroke="#000000" pointer-events="all"/><rect x="0" y="345" width="580" height="287.5" fill="#ffffff" stroke="#000000" pointer-events="all"/><path d="M 120 25 L 193.63 25" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 198.88 25 L 191.88 28.5 L 193.63 25 L 191.88 21.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 25px; margin-left: 160px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Download</div></div></div></foreignObject><text x="160" y="28" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Download</text></switch></g><rect x="40" y="10" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 25px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">beta</div></div></div></foreignObject><text x="80" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">beta</text></switch></g><rect x="200" y="10" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 25px; margin-left: 201px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0</div></div></div></foreignObject><text x="240" y="29" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0</text></switch></g><path d="M 120 120 L 173.63 120" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 120 L 171.88 123.5 L 173.63 120 L 171.88 116.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 120px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="123" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="105" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 120px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0</div></div></div></foreignObject><text x="80" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0</text></switch></g><path d="M 260 120 L 313.63 120" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 120 L 311.88 123.5 L 313.63 120 L 311.88 116.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 120px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="123" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="105" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 120px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">libtest/libstd</div></div></div></foreignObject><text x="220" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">libtest/libstd</text></switch></g><path d="M 400 120 L 453.63 120" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 458.88 120 L 451.88 123.5 L 453.63 120 L 451.88 116.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 120px; margin-left: 430px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Copy</div></div></div></foreignObject><text x="430" y="123" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="320" y="105" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 120px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0-std</div></div></div></foreignObject><text x="360" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0-std</text></switch></g><path d="M 515 135 L 515 145 Q 515 155 505 155 L 230 155 Q 220 155 220 161.82 L 220 168.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 220 173.88 L 216.5 166.88 L 220 168.63 L 223.5 166.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="460" y="105" width="110" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 120px; margin-left: 461px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0-sysroot</div></div></div></foreignObject><text x="515" y="124" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0-sysroot</text></switch></g><path d="M 120 190 L 173.63 190" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 190 L 171.88 193.5 L 173.63 190 L 171.88 186.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 190px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="193" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="175" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 190px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0</div></div></div></foreignObject><text x="80" y="194" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0</text></switch></g><path d="M 260 190 L 313.63 190" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 190 L 311.88 193.5 L 313.63 190 L 311.88 186.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 190px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="193" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="175" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 190px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">rustc</div></div></div></foreignObject><text x="220" y="194" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">rustc</text></switch></g><path d="M 400 190 L 453.63 190" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 458.88 190 L 451.88 193.5 L 453.63 190 L 451.88 186.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 190px; margin-left: 430px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Copy</div></div></div></foreignObject><text x="430" y="193" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="320" y="175" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 190px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0-rustc</div></div></div></foreignObject><text x="360" y="194" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0-rustc</text></switch></g><path d="M 515 205 L 515 227.5 Q 515 237.5 505 237.5 L 230 237.5 Q 220 237.5 220 247.5 L 220 263.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 220 268.88 L 216.5 261.88 L 220 263.63 L 223.5 261.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="460" y="175" width="110" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 190px; margin-left: 461px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0-sysroot</div></div></div></foreignObject><text x="515" y="194" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0-sysroot</text></switch></g><path d="M 120 237.5 L 210 237.5 Q 220 237.5 220 247.5 L 220 263.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 220 268.88 L 216.5 261.88 L 220 263.63 L 223.5 261.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="40" y="222.5" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 238px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">llvm</div></div></div></foreignObject><text x="80" y="241" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">llvm</text></switch></g><path d="M 120 285 L 173.63 285" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 285 L 171.88 288.5 L 173.63 285 L 171.88 281.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 285px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="288" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="270" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 285px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0</div></div></div></foreignObject><text x="80" y="289" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0</text></switch></g><path d="M 260 285 L 313.63 285" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 285 L 311.88 288.5 L 313.63 285 L 311.88 281.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 285px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="288" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="270" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 285px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">codegen</div></div></div></foreignObject><text x="220" y="289" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">codegen</text></switch></g><rect x="320" y="270" width="100" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 285px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0-codegen</div></div></div></foreignObject><text x="370" y="289" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0-codegen</text></switch></g><rect x="-30" y="145" width="90" height="20" fill="none" stroke="none" transform="rotate(-90,15,155)" pointer-events="all"/><g transform="translate(-0.5 -0.5)rotate(-90 15 155)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 155px; margin-left: -29px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">Stage 0</div></div></div></foreignObject><text x="15" y="162" fill="#000000" font-family="Helvetica" font-size="24px" text-anchor="middle">Stage 0</text></switch></g><path d="M 150 380 L 203.63 380" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 208.88 380 L 201.88 383.5 L 203.63 380 L 201.88 376.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 380px; margin-left: 174px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Copy</div></div></div></foreignObject><text x="174" y="383" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="40" y="355" width="110" height="50" rx="7.5" ry="7.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 380px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0-rustc<br />stage0-codegen<br />stage0-sysroot</div></div></div></foreignObject><text x="95" y="384" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0-rustc...</text></switch></g><path d="M 250 395 L 250 405 Q 250 415 240 415 L 90 415 Q 80 415 80 421.82 L 80 428.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 80 433.88 L 76.5 426.88 L 80 428.63 L 83.5 426.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="210" y="365" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 380px; margin-left: 211px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1</div></div></div></foreignObject><text x="250" y="384" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1</text></switch></g><path d="M 120 450 L 173.63 450" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 450 L 171.88 453.5 L 173.63 450 L 171.88 446.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 450px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="453" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="435" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 450px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1</div></div></div></foreignObject><text x="80" y="454" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1</text></switch></g><path d="M 260 450 L 313.63 450" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 450 L 311.88 453.5 L 313.63 450 L 311.88 446.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 450px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="453" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="435" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 450px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">libtest/libstd</div></div></div></foreignObject><text x="220" y="454" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">libtest/libstd</text></switch></g><path d="M 400 450 L 453.63 450" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 458.88 450 L 451.88 453.5 L 453.63 450 L 451.88 446.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 450px; margin-left: 430px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Copy</div></div></div></foreignObject><text x="430" y="453" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="320" y="435" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 450px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1-std</div></div></div></foreignObject><text x="360" y="454" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1-std</text></switch></g><path d="M 515 465 L 515 477.5 Q 515 487.5 505 487.5 L 230 487.5 Q 220 487.5 220 495.57 L 220 503.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 220 508.88 L 216.5 501.88 L 220 503.63 L 223.5 501.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="460" y="435" width="110" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 450px; margin-left: 461px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1/lib/rustlib</div></div></div></foreignObject><text x="515" y="454" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1/lib/rustlib</text></switch></g><path d="M 120 525 L 173.63 525" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 525 L 171.88 528.5 L 173.63 525 L 171.88 521.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 525px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="528" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="510" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 525px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1</div></div></div></foreignObject><text x="80" y="529" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1</text></switch></g><path d="M 260 525 L 313.63 525" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 525 L 311.88 528.5 L 313.63 525 L 311.88 521.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 525px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="528" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="510" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 525px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">rustc</div></div></div></foreignObject><text x="220" y="529" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">rustc</text></switch></g><path d="M 400 525 L 453.63 525" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 458.88 525 L 451.88 528.5 L 453.63 525 L 451.88 521.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 525px; margin-left: 430px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Copy</div></div></div></foreignObject><text x="430" y="528" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="320" y="510" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 525px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1-rustc</div></div></div></foreignObject><text x="360" y="529" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1-rustc</text></switch></g><path d="M 515 540 L 515 550 Q 515 560 505 560 L 230 560 Q 220 560 220 566.82 L 220 573.63" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 220 578.88 L 216.5 571.88 L 220 573.63 L 223.5 571.88 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="460" y="510" width="110" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 525px; margin-left: 461px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1/lib/rustlib</div></div></div></foreignObject><text x="515" y="529" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1/lib/rustlib</text></switch></g><path d="M 120 595 L 173.63 595" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 595 L 171.88 598.5 L 173.63 595 L 171.88 591.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 595px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="598" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="580" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 595px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1</div></div></div></foreignObject><text x="80" y="599" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1</text></switch></g><path d="M 260 595 L 313.63 595" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 595 L 311.88 598.5 L 313.63 595 L 311.88 591.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 595px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="598" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="580" width="80" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 595px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">codegen</div></div></div></foreignObject><text x="220" y="599" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">codegen</text></switch></g><rect x="320" y="580" width="100" height="30" rx="4.5" ry="4.5" fill="#fff2cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 98px; height: 1px; padding-top: 595px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1-codegen</div></div></div></foreignObject><text x="370" y="599" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1-codegen</text></switch></g><rect x="-30" y="510" width="90" height="20" fill="none" stroke="none" transform="rotate(-90,15,520)" pointer-events="all"/><g transform="translate(-0.5 -0.5)rotate(-90 15 520)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 520px; margin-left: -29px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div>Stage 1</div></div></div></div></foreignObject><text x="15" y="527" fill="#000000" font-family="Helvetica" font-size="24px" text-anchor="middle">Stage 1</text></switch></g><path d="M 150 702.5 L 203.63 702.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 208.88 702.5 L 201.88 706 L 203.63 702.5 L 201.88 699 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 703px; margin-left: 174px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Copy</div></div></div></foreignObject><text x="174" y="706" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="40" y="677.5" width="110" height="50" rx="7.5" ry="7.5" fill="#ccff99" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 108px; height: 1px; padding-top: 703px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage1-rustc<br />stage1-codegen<br />stage1/lib/rustlib</div></div></div></foreignObject><text x="95" y="706" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage1-rustc...</text></switch></g><path d="M 250 717.5 L 250 730 Q 250 740 240 740 L 90 740 Q 80 740 80 748.07 L 80 756.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 80 761.38 L 76.5 754.38 L 80 756.13 L 83.5 754.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="210" y="687.5" width="80" height="30" rx="4.5" ry="4.5" fill="#ccff99" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 703px; margin-left: 211px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage2</div></div></div></foreignObject><text x="250" y="706" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage2</text></switch></g><path d="M 120 777.5 L 173.63 777.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 777.5 L 171.88 781 L 173.63 777.5 L 171.88 774 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 778px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="781" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="762.5" width="80" height="30" rx="4.5" ry="4.5" fill="#ccff99" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 778px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage2</div></div></div></foreignObject><text x="80" y="781" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage2</text></switch></g><path d="M 260 777.5 L 313.63 777.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 318.88 777.5 L 311.88 781 L 313.63 777.5 L 311.88 774 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 778px; margin-left: 290px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Outputs</div></div></div></foreignObject><text x="290" y="781" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Outputs</text></switch></g><rect x="180" y="762.5" width="80" height="30" rx="4.5" ry="4.5" fill="#ccff99" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 778px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">rustdoc</div></div></div></foreignObject><text x="220" y="781" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">rustdoc</text></switch></g><path d="M 400 777.5 L 443.63 777.5" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 448.88 777.5 L 441.88 781 L 443.63 777.5 L 441.88 774 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 778px; margin-left: 425px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; "><div style="font-size: 11px">Copy</div></div></div></div></foreignObject><text x="425" y="781" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Copy</text></switch></g><rect x="320" y="762.5" width="80" height="30" rx="4.5" ry="4.5" fill="#ccff99" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 778px; margin-left: 321px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage2-tools</div></div></div></foreignObject><text x="360" y="781" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage2-tools</text></switch></g><path d="M 120 70 L 173.63 70" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 178.88 70 L 171.88 73.5 L 173.63 70 L 171.88 66.5 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 1px; height: 1px; padding-top: 70px; margin-left: 144px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 11px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; background-color: #ffffff; white-space: nowrap; ">Builds</div></div></div></foreignObject><text x="144" y="73" fill="#000000" font-family="Helvetica" font-size="11px" text-anchor="middle">Builds</text></switch></g><rect x="40" y="55" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 70px; margin-left: 41px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage0</div></div></div></foreignObject><text x="80" y="74" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage0</text></switch></g><rect x="180" y="55" width="80" height="30" rx="4.5" ry="4.5" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 70px; margin-left: 181px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">bootstrap</div></div></div></foreignObject><text x="220" y="74" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">bootstrap</text></switch></g><path d="M 190 560 L 130 560 Q 120 560 120 558.75 L 120 558.13 Q 120 557.5 130 557.5 L 210 557.5 Q 220 557.5 220 564.32 L 220 571.13" fill="none" stroke="#000000" stroke-miterlimit="10" pointer-events="stroke"/><path d="M 220 576.38 L 216.5 569.38 L 220 571.13 L 223.5 569.38 Z" fill="#000000" stroke="#000000" stroke-miterlimit="10" pointer-events="all"/><rect x="110" y="551" width="80" height="18" rx="2.7" ry="2.7" fill="#ffe6cc" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 560px; margin-left: 111px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">llvm</div></div></div></foreignObject><text x="150" y="564" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">llvm</text></switch></g><rect x="450" y="762.5" width="80" height="30" rx="4.5" ry="4.5" fill="#ccff99" stroke="#000000" pointer-events="all"/><g transform="translate(-0.5 -0.5)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 78px; height: 1px; padding-top: 778px; margin-left: 451px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 12px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; ">stage2</div></div></div></foreignObject><text x="490" y="781" fill="#000000" font-family="Helvetica" font-size="12px" text-anchor="middle">stage2</text></switch></g><rect x="-30" y="735" width="90" height="20" fill="none" stroke="none" transform="rotate(-90,15,745)" pointer-events="all"/><g transform="translate(-0.5 -0.5)rotate(-90 15 745)"><switch><foreignObject style="overflow: visible; text-align: left;" pointer-events="none" width="100%" height="100%" requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"><div xmlns="http://www.w3.org/1999/xhtml" style="display: flex; align-items: unsafe center; justify-content: unsafe center; width: 88px; height: 1px; padding-top: 745px; margin-left: -29px;"><div style="box-sizing: border-box; font-size: 0; text-align: center; "><div style="display: inline-block; font-size: 24px; font-family: Helvetica; color: #000000; line-height: 1.2; pointer-events: all; white-space: normal; word-wrap: normal; "><div>Stage 2</div></div></div></div></foreignObject><text x="15" y="752" fill="#000000" font-family="Helvetica" font-size="24px" text-anchor="middle">Stage 2</text></switch></g></g><switch><g requiredFeatures="http://www.w3.org/TR/SVG11/feature#Extensibility"/><a transform="translate(0,-5)" xlink:href="https://desk.draw.io/support/solutions/articles/16000042487" target="_blank"><text text-anchor="middle" font-size="10px" x="50%" y="100%">Viewer does not support full SVG 1.1</text></a></switch></svg>
\ No newline at end of file diff --git a/src/doc/rustc-dev-guide/src/implementing_new_features.md b/src/doc/rustc-dev-guide/src/implementing_new_features.md index ef6ae6179..9147c1b41 100644 --- a/src/doc/rustc-dev-guide/src/implementing_new_features.md +++ b/src/doc/rustc-dev-guide/src/implementing_new_features.md @@ -28,6 +28,12 @@ get by with only an r+. For example, it is OK to add or modify unstable command-line flags or attributes without an FCP for compiler development or standard library use, as long as you don't expect them to be in wide use in the nightly ecosystem. +Some teams have lighter weight processes that they use in scenarios +like this; for example, the compiler team recommends +filing a Major Change Proposal ([MCP][mcp]) as a lightweight way to +garner support and feedback without requiring full consensus. + +[mcp]: compiler/mcp.md#public-facing-changes-require-rfcbot-fcp You don't need to have the implementation fully ready for r+ to propose an FCP, but it is generally a good idea to have at least a proof @@ -123,9 +129,9 @@ a new unstable feature: 2. Pick a name for the feature gate (for RFCs, use the name in the RFC). -3. Add a feature gate declaration to `rustc_feature/src/active.rs` - in the active `declare_features` block. See [here][add-feature-gate] for - detailed instructions. +3. Add a feature gate declaration to `rustc_feature/src/active.rs` in the active + `declare_features` block, and add the feature gate keyword to + `rustc_span/src/symbol.rs`. See [here][add-feature-gate] for detailed instructions. 4. Prevent usage of the new feature unless the feature gate is set. You can check it in most places in the compiler using the diff --git a/src/doc/rustc-dev-guide/src/method-lookup.md b/src/doc/rustc-dev-guide/src/method-lookup.md index 8eb8ec5ce..8b49e8d00 100644 --- a/src/doc/rustc-dev-guide/src/method-lookup.md +++ b/src/doc/rustc-dev-guide/src/method-lookup.md @@ -32,8 +32,8 @@ inference variables or other information. [fully-qualified syntax]: https://doc.rust-lang.org/nightly/book/ch19-03-advanced-traits.html#fully-qualified-syntax-for-disambiguation-calling-methods-with-the-same-name [UFCS]: https://github.com/rust-lang/rfcs/blob/master/text/0132-ufcs.md -[probe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/check/method/probe/ -[confirm]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/check/method/confirm/ +[probe]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/method/probe/ +[confirm]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_typeck/method/confirm/ ## The Probe phase diff --git a/src/doc/rustc-dev-guide/src/name-resolution.md b/src/doc/rustc-dev-guide/src/name-resolution.md index c4f44909b..1dbc95ead 100644 --- a/src/doc/rustc-dev-guide/src/name-resolution.md +++ b/src/doc/rustc-dev-guide/src/name-resolution.md @@ -174,7 +174,7 @@ Still, it probably provides useful first guidepost to what happens in there. following stages of compilation? * Who calls it and how it is actually used. * Is it a pass and then the result is only used, or can it be computed - incrementally (e.g. for RLS)? + incrementally? * The overall strategy description is a bit vague. * Where does the name `Rib` come from? * Does this thing have its own tests, or is it tested only as part of some e2e diff --git a/src/doc/rustc-dev-guide/src/opaque-types-impl-trait-inference.md b/src/doc/rustc-dev-guide/src/opaque-types-impl-trait-inference.md index 52d2127bf..f9c2ea74d 100644 --- a/src/doc/rustc-dev-guide/src/opaque-types-impl-trait-inference.md +++ b/src/doc/rustc-dev-guide/src/opaque-types-impl-trait-inference.md @@ -147,7 +147,7 @@ flowchart TD ### Relating an opaque type to another type -There is one central place where an opaqe type gets its hidden type constrained, +There is one central place where an opaque type gets its hidden type constrained, and that is the `handle_opaque_type` function. Amusingly it takes two types, so you can pass any two types, but one of them should be an opaque type. @@ -216,7 +216,7 @@ and then handle it correctly. The MIR borrow checker relates things via `nll_relate` and only cares about regions. Any type relation will trigger the binding of hidden types, so the borrow checker is doing the same thing as the type checker, -but ignores obivously dead code (e.g. after a panic). +but ignores obviously dead code (e.g. after a panic). The borrow checker is also the source of truth when it comes to hidden types, as it is the only one who can properly figure out what lifetimes on the hidden type correspond to which lifetimes on the opaque type declaration. @@ -224,7 +224,7 @@ to which lifetimes on the opaque type declaration. ## Backwards compatibility hacks `impl Trait` in return position has various quirks that were not part -of any RFCs and are likely accidental stabilizations. +of any RFCs and are likely accidental stabilization. To support these, the `replace_opaque_types_with_inference_vars` is being used to reintroduce the previous behaviour. diff --git a/src/doc/rustc-dev-guide/src/overview.md b/src/doc/rustc-dev-guide/src/overview.md index c7da92542..7fbdfd359 100644 --- a/src/doc/rustc-dev-guide/src/overview.md +++ b/src/doc/rustc-dev-guide/src/overview.md @@ -177,7 +177,7 @@ satisfy/optimize for. For example, of space on the user's system... - Compiler memory usage: while compiling a program, we don't want to use more memory than we need. -- Program speed: how fast is your compiled program. More/better compile-time +- Program speed: how fast is your compiled program? More/better compile-time analyses often means the compiler can do better optimizations. - Program size: how large is the compiled binary? Similar to the previous point. @@ -190,7 +190,7 @@ satisfy/optimize for. For example, the input programs says they do, and should continue to do so despite the tremendous amount of change constantly going on. - Integration: a number of other tools need to use the compiler in - various ways (e.g. cargo, clippy, miri, RLS) that must be supported. + various ways (e.g. cargo, clippy, miri) that must be supported. - Compiler stability: the compiler should not crash or fail ungracefully on the stable channel. - Rust stability: the compiler must respect Rust's stability guarantees by not diff --git a/src/doc/rustc-dev-guide/src/panic-implementation.md b/src/doc/rustc-dev-guide/src/panic-implementation.md index 66e61548e..d1ca202dc 100644 --- a/src/doc/rustc-dev-guide/src/panic-implementation.md +++ b/src/doc/rustc-dev-guide/src/panic-implementation.md @@ -28,7 +28,7 @@ Actually resolving this goes through several layers of indirection: 1. In `compiler/rustc_middle/src/middle/weak_lang_items.rs`, `panic_impl` is declared as 'weak lang item', with the symbol `rust_begin_unwind`. This is - used in `rustc_typeck/src/collect.rs` to set the actual symbol name to + used in `rustc_hir_analysis/src/collect.rs` to set the actual symbol name to `rust_begin_unwind`. Note that `panic_impl` is declared in an `extern "Rust"` block, diff --git a/src/doc/rustc-dev-guide/src/rustc-driver.md b/src/doc/rustc-dev-guide/src/rustc-driver.md index 7250c852c..cef50111d 100644 --- a/src/doc/rustc-dev-guide/src/rustc-driver.md +++ b/src/doc/rustc-dev-guide/src/rustc-driver.md @@ -7,7 +7,7 @@ using the interface defined in the [`rustc_interface`] crate. The `rustc_interface` crate provides external users with an (unstable) API for running code at particular times during the compilation process, allowing third parties to effectively use `rustc`'s internals as a library for -analyzing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc). +analyzing a crate or emulating the compiler in-process (e.g. rustdoc). For those using `rustc` as a library, the [`rustc_interface::run_compiler()`][i_rc] function is the main entrypoint to the compiler. It takes a configuration for the compiler diff --git a/src/doc/rustc-dev-guide/src/rustdoc.md b/src/doc/rustc-dev-guide/src/rustdoc.md index 4cdda5a3e..23428efd6 100644 --- a/src/doc/rustc-dev-guide/src/rustdoc.md +++ b/src/doc/rustc-dev-guide/src/rustdoc.md @@ -148,7 +148,7 @@ authors can request rebuilds, which will be run with the latest rustdoc. Docs.rs performs some transformations on rustdoc's output in order to save storage and display a navigation bar at the top. In particular, certain static -files (like main.js and rustdoc.css may be shared across multiple invocations +files, like main.js and rustdoc.css, may be shared across multiple invocations of the same version of rustdoc. Others, like crates.js and sidebar-items.js, are different for different invocations. Still others, like fonts, will never change. These categories are distinguished using the `SharedResource` enum in diff --git a/src/doc/rustc-dev-guide/src/stability.md b/src/doc/rustc-dev-guide/src/stability.md index 3469ce2ba..b7308ee73 100644 --- a/src/doc/rustc-dev-guide/src/stability.md +++ b/src/doc/rustc-dev-guide/src/stability.md @@ -74,13 +74,11 @@ To stabilize a feature, follow these steps: 0. Ask a **@T-libs-api** member to start an FCP on the tracking issue and wait for the FCP to complete (with `disposition-merge`). -1. Change `#[unstable(...)]` to `#[stable(since = "version")]`. - `version` should be the *current nightly*, i.e. stable+2. You can see which version is - the current nightly [on Forge](https://forge.rust-lang.org/#current-release-versions). +1. Change `#[unstable(...)]` to `#[stable(since = "CURRENT_RUSTC_VERSION")]`. 2. Remove `#![feature(...)]` from any test or doc-test for this API. If the feature is used in the compiler or tools, remove it from there as well. 3. If applicable, change `#[rustc_const_unstable(...)]` to - `#[rustc_const_stable(since = "version")]`. + `#[rustc_const_stable(since = "CURRENT_RUSTC_VERSION")]`. 4. Open a PR against `rust-lang/rust`. - Add the appropriate labels: `@rustbot modify labels: +T-libs-api`. - Link to the tracking issue and say "Closes #XXXXX". diff --git a/src/doc/rustc-dev-guide/src/tests/ci.md b/src/doc/rustc-dev-guide/src/tests/ci.md index 21f834130..cca4973cb 100644 --- a/src/doc/rustc-dev-guide/src/tests/ci.md +++ b/src/doc/rustc-dev-guide/src/tests/ci.md @@ -2,9 +2,10 @@ ## Testing infrastructure +<!-- date-check: oct 2022 --> When a Pull Request is opened on GitHub, [GitHub Actions] will automatically launch a build that will run all tests on some configurations -(x86_64-gnu-llvm-12 linux. x86_64-gnu-tools linux, mingw-check linux). +(x86_64-gnu-llvm-13 linux, x86_64-gnu-tools linux, and mingw-check linux). In essence, each runs `./x.py test` with various different options. The integration bot [bors] is used for coordinating merges to the master branch. diff --git a/src/doc/rustc-dev-guide/src/tests/intro.md b/src/doc/rustc-dev-guide/src/tests/intro.md index 8b65e4df5..66e0a9eef 100644 --- a/src/doc/rustc-dev-guide/src/tests/intro.md +++ b/src/doc/rustc-dev-guide/src/tests/intro.md @@ -115,7 +115,7 @@ will unpack, build, and run all tests. ### Tool tests Packages that are included with Rust have all of their tests run as well. -This includes things such as cargo, clippy, rustfmt, rls, miri, bootstrap +This includes things such as cargo, clippy, rustfmt, miri, bootstrap (testing the Rust build system itself), etc. Most of the tools are located in the [`src/tools`] directory. diff --git a/src/doc/rustc-dev-guide/src/tests/running.md b/src/doc/rustc-dev-guide/src/tests/running.md index be9d965e4..5d1441936 100644 --- a/src/doc/rustc-dev-guide/src/tests/running.md +++ b/src/doc/rustc-dev-guide/src/tests/running.md @@ -245,14 +245,20 @@ The binary will be created at `./build/$HOST_ARCH/stage2-tools/$TARGET_ARCH/release/remote-test-server`. Copy this over to the remote machine. -On the remote machine, run the `remote-test-server` with the `remote` argument -(and optionally `-v` for verbose output). Output should look like this: +On the remote machine, run the `remote-test-server` with the `--bind +0.0.0.0:12345` flag (and optionally `-v` for verbose output). Output should +look like this: ```sh -$ ./remote-test-server -v remote +$ ./remote-test-server -v --bind 0.0.0.0:12345 starting test server listening on 0.0.0.0:12345! ``` +Note that binding the server to 0.0.0.0 will allow all hosts able to reach your +machine to execute arbitrary code on your machine. We strongly recommend either +setting up a firewall to block external access to port 12345, or to use a more +restrictive IP address when binding. + You can test if the `remote-test-server` is working by connecting to it and sending `ping\n`. It should reply `pong`: ```sh diff --git a/src/doc/rustc-dev-guide/src/traits/resolution.md b/src/doc/rustc-dev-guide/src/traits/resolution.md index 195fe6050..88767ad94 100644 --- a/src/doc/rustc-dev-guide/src/traits/resolution.md +++ b/src/doc/rustc-dev-guide/src/traits/resolution.md @@ -72,10 +72,10 @@ Trait resolution consists of three major parts: are completely fulfilled. Basically it is a worklist of obligations to be selected: once selection is successful, the obligation is removed from the worklist and any nested obligations are enqueued. + Fulfillment constrains inference variables. -- **Coherence**: The coherence checks are intended to ensure that there - are never overlapping impls, where two impls could be used with - equal precedence. +- **Evaluation**: Checks whether obligations holds without constraining + any inference variables. Used by selection. ## Selection @@ -111,6 +111,8 @@ may lead to other errors downstream). ### Candidate assembly +**TODO**: Talk about _why_ we have different candidates, and why it needs to happen in a probe. + Searches for impls/where-clauses/etc that might possibly be used to satisfy the obligation. Each of those is called a candidate. To avoid ambiguity, we want to find exactly one @@ -120,68 +122,23 @@ the obligation contains unbound inference variables. The subroutines that decide whether a particular impl/where-clause/etc applies to a particular obligation are collectively referred to as the process of -_matching_. As of <!-- date-check --> May 2022, this amounts to unifying -the `Self` types, but in the future we may also recursively consider some of the -nested obligations, in the case of an impl. - -**TODO**: what does "unifying the `Self` types" mean? The `Self` of the -obligation with that of an impl? - -The basic idea for candidate assembly is to do a first pass in which -we identify all possible candidates. During this pass, all that we do -is try and unify the type parameters. (In particular, we ignore any -nested where clauses.) Presuming that this unification succeeds, the -impl is added as a candidate. +_matching_. For `impl` candidates <!-- date-check: Oct 2022 -->, +this amounts to unifying the impl header (the `Self` type and the trait arguments) +while ignoring nested obligations. If matching succeeds then we add it +to a set of candidates. There are other rules when assembling candidates for +built-in traits such as `Copy`, `Sized`, and `CoerceUnsized`. Once this first pass is done, we can examine the set of candidates. If it is a singleton set, then we are done: this is the only impl in -scope that could possibly apply. Otherwise, we can winnow down the set -of candidates by using where clauses and other conditions. If this -reduced set yields a single, unambiguous entry, we're good to go, -otherwise the result is considered ambiguous. - -#### The basic process: Inferring based on the impls we see - -This process is easier if we work through some examples. Consider -the following trait: - -```rust,ignore -trait Convert<Target> { - fn convert(&self) -> Target; -} -``` +scope that could possibly apply. Otherwise, we can **winnow** down the set +of candidates by using where clauses and other conditions. Winnowing uses +`evaluate_candidate` to check whether the nested obligations may apply. +If this still leaves more than 1 candidate, we use ` fn candidate_should_be_dropped_in_favor_of` +to prefer some candidates over others. -This trait just has one method. It's about as simple as it gets. It -converts from the (implicit) `Self` type to the `Target` type. If we -wanted to permit conversion between `isize` and `usize`, we might -implement `Convert` like so: -```rust,ignore -impl Convert<usize> for isize { ... } // isize -> usize -impl Convert<isize> for usize { ... } // usize -> isize -``` - -Now imagine there is some code like the following: - -```rust,ignore -let x: isize = ...; -let y = x.convert(); -``` - -The call to convert will generate a trait reference `Convert<$Y> for -isize`, where `$Y` is the type variable representing the type of -`y`. Of the two impls we can see, the only one that matches is -`Convert<usize> for isize`. Therefore, we can -select this impl, which will cause the type of `$Y` to be unified to -`usize`. (Note that while assembling candidates, we do the initial -unifications in a transaction, so that they don't affect one another.) - -**TODO**: The example says we can "select" the impl, but this section is -talking specifically about candidate assembly. Does this mean we can sometimes -skip confirmation? Or is this poor wording? -**TODO**: Is the unification of `$Y` part of trait resolution or type -inference? Or is this not the same type of "inference variable" as in type -inference? +If this reduced set yields a single, unambiguous entry, we're good to go, +otherwise the result is considered ambiguous. #### Winnowing: Resolving ambiguities @@ -281,38 +238,18 @@ result of selection would be an error. Note that the candidate impl is chosen based on the `Self` type, but confirmation is done based on (in this case) the `Target` type parameter. -### Selection during translation +### Selection during codegen As mentioned above, during type checking, we do not store the results of trait -selection. At trans time, we repeat the trait selection to choose a particular -impl for each method call. In this second selection, we do not consider any -where-clauses to be in scope because we know that each resolution will resolve -to a particular impl. - -One interesting twist has to do with nested obligations. In general, in trans, -we only need to do a "shallow" selection for an obligation. That is, we wish to -identify which impl applies, but we do not (yet) need to decide how to select -any nested obligations. Nonetheless, we *do* currently do a complete resolution, -and that is because it can sometimes inform the results of type inference. +selection. At codegen time, we repeat the trait selection to choose a particular +impl for each method call. This is done using `fn codegen_select_candidate`. +In this second selection, we do not consider any where-clauses to be in scope +because we know that each resolution will resolve to a particular impl. + +One interesting twist has to do with nested obligations. In general, in codegen, +we only to figure out which candidate applies, we do not care about nested obligations, +as these are already assumed to be true. Nonetheless, we *do* currently do fulfill all of them. +That is because it can sometimes inform the results of type inference. That is, we do not have the full substitutions in terms of the type variables of the impl available to us, so we must run trait selection to figure everything out. - -**TODO**: is this still talking about trans? - -Here is an example: - -```rust,ignore -trait Foo { ... } -impl<U, T:Bar<U>> Foo for Vec<T> { ... } - -impl Bar<usize> for isize { ... } -``` - -After one shallow round of selection for an obligation like `Vec<isize> -: Foo`, we would know which impl we want, and we would know that -`T=isize`, but we do not know the type of `U`. We must select the -nested obligation `isize : Bar<U>` to find out that `U=usize`. - -It would be good to only do *just as much* nested resolution as -necessary. Currently, though, we just do a full resolution. diff --git a/src/doc/rustc-dev-guide/src/ty.md b/src/doc/rustc-dev-guide/src/ty.md index 1cc03fce0..9b35f0d4c 100644 --- a/src/doc/rustc-dev-guide/src/ty.md +++ b/src/doc/rustc-dev-guide/src/ty.md @@ -78,7 +78,7 @@ expected type. The [`astconv` module][astconv] is where the code responsible for but also in other parts of the compiler that want to ask questions like "what argument types does this function expect?" -[astconv]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_typeck/astconv/index.html +[astconv]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_hir_analysis/astconv/index.html **How semantics drive the two instances of `Ty`** diff --git a/src/doc/rustc/src/SUMMARY.md b/src/doc/rustc/src/SUMMARY.md index d9d430c20..06883ddd5 100644 --- a/src/doc/rustc/src/SUMMARY.md +++ b/src/doc/rustc/src/SUMMARY.md @@ -20,9 +20,11 @@ - [aarch64-nintendo-switch-freestanding](platform-support/aarch64-nintendo-switch-freestanding.md) - [armeb-unknown-linux-gnueabi](platform-support/armeb-unknown-linux-gnueabi.md) - [armv4t-none-eabi](platform-support/armv4t-none-eabi.md) + - [armv5te-none-eabi](platform-support/armv5te-none-eabi.md) - [armv6k-nintendo-3ds](platform-support/armv6k-nintendo-3ds.md) - [armv7-unknown-linux-uclibceabi](platform-support/armv7-unknown-linux-uclibceabi.md) - [armv7-unknown-linux-uclibceabihf](platform-support/armv7-unknown-linux-uclibceabihf.md) + - [\*-android and \*-androideabi](platform-support/android.md) - [\*-fuchsia](platform-support/fuchsia.md) - [\*-kmc-solid_\*](platform-support/kmc-solid.md) - [m68k-unknown-linux-gnu](platform-support/m68k-unknown-linux-gnu.md) @@ -33,6 +35,7 @@ - [*-unknown-openbsd](platform-support/openbsd.md) - [\*-unknown-uefi](platform-support/unknown-uefi.md) - [wasm64-unknown-unknown](platform-support/wasm64-unknown-unknown.md) + - [x86_64-fortanix-unknown-sgx](platform-support/x86_64-fortanix-unknown-sgx.md) - [x86_64-unknown-none](platform-support/x86_64-unknown-none.md) - [Targets](targets/index.md) - [Built-in Targets](targets/built-in.md) diff --git a/src/doc/rustc/src/command-line-arguments.md b/src/doc/rustc/src/command-line-arguments.md index f05ff3f1b..2dc182b3d 100644 --- a/src/doc/rustc/src/command-line-arguments.md +++ b/src/doc/rustc/src/command-line-arguments.md @@ -270,6 +270,11 @@ This flag will set which lints should be set to the [warn level](lints/levels.md _Note:_ The order of these lint level arguments is taken into account, see [lint level via compiler flag](lints/levels.md#via-compiler-flag) for more information. +<a id="option-force-warn"></a> +## `--force-warn`: force a lint to warn + +This flag sets the given lint to the [forced warn level](lints/levels.md#force-warn) and the level cannot be overridden, even ignoring the [lint caps](lints/levels.md#capping-lints). + <a id="option-a-allow"></a> ## `-A`: set lint allowed @@ -295,9 +300,9 @@ _Note:_ The order of these lint level arguments is taken into account, see [lint ## `-Z`: set unstable options This flag will allow you to set unstable options of rustc. In order to set multiple options, -the -Z flag can be used multiple times. For example: `rustc -Z verbose -Z time`. +the -Z flag can be used multiple times. For example: `rustc -Z verbose -Z time-passes`. Specifying options with -Z is only available on nightly. To view all available options -run: `rustc -Z help`. +run: `rustc -Z help`, or see [The Unstable Book](../unstable-book/index.html). <a id="option-cap-lints"></a> ## `--cap-lints`: set the most restrictive lint level @@ -381,6 +386,12 @@ are: - `always` — Always use colors. - `never` — Never colorize output. +<a id="option-diagnostic-width"></a> +## `--diagnostic-width`: specify the terminal width for diagnostics + +This flag takes a number that specifies the width of the terminal in characters. +Formatting of diagnostics will take the width into consideration to make them better fit on the screen. + <a id="option-remap-path-prefix"></a> ## `--remap-path-prefix`: remap source names in output diff --git a/src/doc/rustc/src/platform-support.md b/src/doc/rustc/src/platform-support.md index 3a6963ebc..a36518cc8 100644 --- a/src/doc/rustc/src/platform-support.md +++ b/src/doc/rustc/src/platform-support.md @@ -125,17 +125,17 @@ target | std | notes `aarch64-apple-ios` | ✓ | ARM64 iOS [`aarch64-apple-ios-sim`](platform-support/aarch64-apple-ios-sim.md) | ✓ | Apple iOS Simulator on ARM64 `aarch64-fuchsia` | ✓ | ARM64 Fuchsia -`aarch64-linux-android` | ✓ | ARM64 Android +[`aarch64-linux-android`](platform-support/android.md) | ✓ | ARM64 Android `aarch64-unknown-none-softfloat` | * | Bare ARM64, softfloat `aarch64-unknown-none` | * | Bare ARM64, hardfloat -`arm-linux-androideabi` | ✓ | ARMv7 Android +[`arm-linux-androideabi`](platform-support/android.md) | ✓ | ARMv7 Android `arm-unknown-linux-musleabi` | ✓ | ARMv6 Linux with MUSL `arm-unknown-linux-musleabihf` | ✓ | ARMv6 Linux with MUSL, hardfloat `armebv7r-none-eabi` | * | Bare ARMv7-R, Big Endian `armebv7r-none-eabihf` | * | Bare ARMv7-R, Big Endian, hardfloat `armv5te-unknown-linux-gnueabi` | ✓ | ARMv5TE Linux (kernel 4.4, glibc 2.23) `armv5te-unknown-linux-musleabi` | ✓ | ARMv5TE Linux with MUSL -`armv7-linux-androideabi` | ✓ | ARMv7a Android +[`armv7-linux-androideabi`](platform-support/android.md) | ✓ | ARMv7a Android `armv7-unknown-linux-gnueabi` | ✓ |ARMv7 Linux (kernel 4.15, glibc 2.27) `armv7-unknown-linux-musleabi` | ✓ |ARMv7 Linux with MUSL `armv7-unknown-linux-musleabihf` | ✓ | ARMv7 Linux with MUSL, hardfloat @@ -144,9 +144,9 @@ target | std | notes `armv7r-none-eabihf` | * | Bare ARMv7-R, hardfloat `asmjs-unknown-emscripten` | ✓ | asm.js via Emscripten `i586-pc-windows-msvc` | * | 32-bit Windows w/o SSE -`i586-unknown-linux-gnu` | ✓ | 32-bit Linux w/o SSE (kernel 4.4, glibc 2.23) +`i586-unknown-linux-gnu` | ✓ | 32-bit Linux w/o SSE (kernel 3.2, glibc 2.17) `i586-unknown-linux-musl` | ✓ | 32-bit Linux w/o SSE, MUSL -`i686-linux-android` | ✓ | 32-bit x86 Android +[`i686-linux-android`](platform-support/android.md) | ✓ | 32-bit x86 Android `i686-unknown-freebsd` | ✓ | 32-bit FreeBSD `i686-unknown-linux-musl` | ✓ | 32-bit Linux with MUSL `mips-unknown-linux-musl` | ✓ | MIPS Linux with MUSL @@ -165,7 +165,7 @@ target | std | notes `thumbv7em-none-eabi` | * | Bare Cortex-M4, M7 `thumbv7em-none-eabihf` | * | Bare Cortex-M4F, M7F, FPU, hardfloat `thumbv7m-none-eabi` | * | Bare Cortex-M3 -`thumbv7neon-linux-androideabi` | ✓ | Thumb2-mode ARMv7a Android with NEON +[`thumbv7neon-linux-androideabi`](platform-support/android.md) | ✓ | Thumb2-mode ARMv7a Android with NEON `thumbv7neon-unknown-linux-gnueabihf` | ✓ | Thumb2-mode ARMv7a Linux with NEON (kernel 4.4, glibc 2.23) `thumbv8m.base-none-eabi` | * | ARMv8-M Baseline `thumbv8m.main-none-eabi` | * | ARMv8-M Mainline @@ -174,9 +174,9 @@ target | std | notes `wasm32-unknown-unknown` | ✓ | WebAssembly `wasm32-wasi` | ✓ | WebAssembly with WASI `x86_64-apple-ios` | ✓ | 64-bit x86 iOS -`x86_64-fortanix-unknown-sgx` | ✓ | [Fortanix ABI] for 64-bit Intel SGX +[`x86_64-fortanix-unknown-sgx`](platform-support/x86_64-fortanix-unknown-sgx.md) | ✓ | [Fortanix ABI] for 64-bit Intel SGX `x86_64-fuchsia` | ✓ | 64-bit Fuchsia -`x86_64-linux-android` | ✓ | 64-bit x86 Android +[`x86_64-linux-android`](platform-support/android.md) | ✓ | 64-bit x86 Android `x86_64-pc-solaris` | ✓ | 64-bit Solaris 10/11, illumos `x86_64-unknown-linux-gnux32` | ✓ | 64-bit Linux (x32 ABI) (kernel 4.15, glibc 2.27) [`x86_64-unknown-none`](platform-support/x86_64-unknown-none.md) | * | Freestanding/bare-metal x86_64, softfloat @@ -226,6 +226,7 @@ target | std | host | notes [`armeb-unknown-linux-gnueabi`](platform-support/armeb-unknown-linux-gnueabi.md) | ✓ | ? | ARM BE8 the default ARM big-endian architecture since [ARMv6](https://developer.arm.com/documentation/101754/0616/armlink-Reference/armlink-Command-line-Options/--be8?lang=en). `armv4t-none-eabi` | * | | ARMv4T A32 `armv4t-unknown-linux-gnueabi` | ? | | +[`armv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | ARMv5TE A32 `armv5te-unknown-linux-uclibceabi` | ? | | ARMv5TE Linux with uClibc `armv6-unknown-freebsd` | ✓ | ✓ | ARMv6 FreeBSD `armv6-unknown-netbsd-eabihf` | ? | | @@ -292,6 +293,7 @@ target | std | host | notes `sparc64-unknown-netbsd` | ✓ | ✓ | NetBSD/sparc64 [`sparc64-unknown-openbsd`](platform-support/openbsd.md) | ✓ | ✓ | OpenBSD/sparc64 `thumbv4t-none-eabi` | * | | ARMv4T T32 +[`thumbv5te-none-eabi`](platform-support/armv5te-none-eabi.md) | * | | ARMv5TE T32 `thumbv7a-pc-windows-msvc` | ? | | `thumbv7a-uwp-windows-msvc` | ✓ | | `thumbv7neon-unknown-linux-musleabihf` | ? | | Thumb2-mode ARMv7a Linux with NEON, MUSL diff --git a/src/doc/rustc/src/platform-support/android.md b/src/doc/rustc/src/platform-support/android.md new file mode 100644 index 000000000..b2c8e5d4d --- /dev/null +++ b/src/doc/rustc/src/platform-support/android.md @@ -0,0 +1,45 @@ +# *-linux-android and *-linux-androideabi + +**Tier: 2** + +[Android] is a mobile operating system built on top of the Linux kernel. + +[Android]: https://source.android.com/ + +## Target maintainers + +- Chris Wailes ([@chriswailes](https://github.com/chriswailes)) +- Matthew Maurer ([@maurer](https://github.com/maurer)) +- Martin Geisler ([@mgeisler](https://github.com/mgeisler)) + +## Requirements + +This target is cross-compiled from a host environment. Development may be done +from the [source tree] or using the Android NDK. + +[source tree]: https://source.android.com/docs/setup/build/downloading + +Android targets support std. Generated binaries use the ELF file format. + +## NDK/API Update Policy + +Rust will support the most recent Long Term Support (LTS) Android Native +Development Kit (NDK). By default Rust will support all API levels supported +by the NDK, but a higher minimum API level may be required if deemed necessary. + +## Building the target + +To build Rust binaries for Android you'll need a copy of the most recent LTS +edition of the [Android NDK]. Supported Android targets are: + +* aarch64-linux-android +* arm-linux-androideabi +* armv7-linux-androideabi +* i686-linux-android +* thumbv7neon-linux-androideabi +* x86_64-linux-android + +[Android NDK]: https://developer.android.com/ndk/downloads + +A list of all supported targets can be found +[here](https://doc.rust-lang.org/rustc/platform-support.html) diff --git a/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md b/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md index 507631cdc..432e0cfc9 100644 --- a/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md +++ b/src/doc/rustc/src/platform-support/armeb-unknown-linux-gnueabi.md @@ -1,7 +1,7 @@ # armeb-unknown-linux-gnueabi **Tier: 3** -Target for cross-compiling Linux user-mode applications targetting the ARM BE8 architecture. +Target for cross-compiling Linux user-mode applications targeting the ARM BE8 architecture. ## Overview BE8 architecture retains the same little-endian ordered code-stream used by conventional little endian ARM systems, however the data accesses are in big-endian. BE8 is used primarily in high-performance networking applications where the ability to read packets in their native "Network Byte Order" is important (many network protocols transmit data in big-endian byte order for their wire formats). diff --git a/src/doc/rustc/src/platform-support/armv5te-none-eabi.md b/src/doc/rustc/src/platform-support/armv5te-none-eabi.md new file mode 100644 index 000000000..f469dab1c --- /dev/null +++ b/src/doc/rustc/src/platform-support/armv5te-none-eabi.md @@ -0,0 +1,66 @@ +# `armv5te-none-eabi` + +**Tier: 3** + +Bare-metal target for any cpu in the ARMv5TE architecture family, supporting +ARM/Thumb code interworking (aka `a32`/`t32`), with `a32` code as the default code +generation. + +The `thumbv5te-none-eabi` target is the same as this one, but the instruction set defaults to `t32`. + +## Target Maintainers + +* [@QuinnPainter](https://github.com/QuinnPainter) + +## Requirements + +The target is cross-compiled, and uses static linking. + +By default, the `lld` linker included with Rust will be used. + +However, you may want to use the `arm-none-eabi-ld` linker instead. This can be obtained for Windows/Mac/Linux from the [ARM +Developer Website][arm-dev], or possibly from your OS's package manager. To use it, add the following to your `.cargo/config.toml`: + +```toml +[target.armv5te-none-eabi] +linker = "arm-none-eabi-ld" +``` + +[arm-dev]: https://developer.arm.com/Tools%20and%20Software/GNU%20Toolchain + +This target doesn't provide a linker script, you'll need to bring your own +according to the specific device you want to target. Pass +`-Clink-arg=-Tyour_script.ld` as a rustc argument to make the linker use +`your_script.ld` during linking. + +## Building Rust Programs + +Because it is Tier 3, rust does not yet ship pre-compiled artifacts for this target. + +Just use the `build-std` nightly cargo feature to build the `core` library. You +can pass this as a command line argument to cargo, or your `.cargo/config.toml` +file might include the following lines: + +```toml +[unstable] +build-std = ["core"] +``` + +Most of `core` should work as expected, with the following notes: +* the target is "soft float", so `f32` and `f64` operations are emulated in + software. +* integer division is also emulated in software. +* the target is old enough that it doesn't have atomic instructions. + +`alloc` is also supported, as long as you provide your own global allocator. + +Rust programs are output as ELF files. + +## Testing + +This is a cross-compiled target that you will need to emulate during testing. + +Because this is a device-agnostic target, and the exact emulator that you'll +need depends on the specific device you want to run your code on. + +For example, when programming for the DS, you can use one of the several available DS emulators, such as [melonDS](https://melonds.kuribo64.net/). diff --git a/src/doc/rustc/src/platform-support/x86_64-fortanix-unknown-sgx.md b/src/doc/rustc/src/platform-support/x86_64-fortanix-unknown-sgx.md new file mode 100644 index 000000000..97b5827c1 --- /dev/null +++ b/src/doc/rustc/src/platform-support/x86_64-fortanix-unknown-sgx.md @@ -0,0 +1,72 @@ +# `x86_64-fortanix-unknown-sgx` + +**Tier: 2** + +Secure enclaves using [Intel Software Guard Extensions +(SGX)](https://www.intel.com/content/www/us/en/developer/tools/software-guard-extensions/overview.html) +based on the ABI defined by Fortanix for the [Enclave Development Platform +(EDP)](https://edp.fortanix.com/). + +## Target maintainers + +The [EDP team](mailto:edp.maintainers@fortanix.com) at Fortanix. + +- Jethro Beekman [@jethrogb](https://github.com/jethrogb) +- Raoul Strackx [@raoulstrackx](https://github.com/raoulstrackx) +- Mohsen Zohrevandi [@mzohreva](https://github.com/mzohreva) + +## Requirements + +The target supports `std` with a default allocator. Only cross compilation is +supported. + +Binaries support all CPUs that include Intel SGX. Only 64-bit mode is supported. + +Not all `std` features are supported, see [Using Rust's +std](https://edp.fortanix.com/docs/concepts/rust-std/) for details. + +The `extern "C"` calling convention is the System V AMD64 ABI. + +The supported ABI is the +[fortanix-sgx-abi](https://edp.fortanix.com/docs/api/fortanix_sgx_abi/index.html). + +The compiler output is ELF, but the native format for the platform is the SGX +stream (SGXS) format. A converter like +[ftxsgx-elf2sgxs](https://crates.io/crates/fortanix-sgx-tools) is needed. + +Programs in SGXS format adhering to the Fortanix SGX ABI can be run with any +compatible runner, such as +[ftxsgx-runner](https://crates.io/crates/fortanix-sgx-tools). + +See the [EDP installation +guide](https://edp.fortanix.com/docs/installation/guide/) for recommendations +on how to setup a development and runtime environment. + +## Building the target + +As a tier 2 target, the target is built by the Rust project. + +You can configure rustbuild like so: + +```toml +[build] +build-stage = 1 +target = ["x86_64-fortanix-unknown-sgx"] +``` + +## Building Rust programs + +Standard build flows using `cargo` or `rustc` should work. + +## Testing + +The Rust test suite as well as custom unit and integration tests will run on +hardware that has Intel SGX enabled if a cargo runner is configured correctly, +see the requirements section. + +## Cross-compilation toolchains and C code + +C code is not generally supported, as there is no libc. C code compiled for +x86-64 in freestanding mode using the System V AMD64 ABI may work. The +[rs-libc](https://crates.io/crates/rs-libc) crate contains a subset of libc +that's known to work with this target. diff --git a/src/doc/rustdoc/book.toml b/src/doc/rustdoc/book.toml index dfa685785..45405a117 100644 --- a/src/doc/rustdoc/book.toml +++ b/src/doc/rustdoc/book.toml @@ -6,9 +6,5 @@ title = "The rustdoc book" git-repository-url = "https://github.com/rust-lang/rust/tree/master/src/doc/rustdoc" [output.html.redirect] -"/what-to-include.html" = "write-documentation/what-to-include.html" "/the-doc-attribute.html" = "write-documentation/the-doc-attribute.html" -"/linking-to-items-by-name.html" = "write-documentation/linking-to-items-by-name.html" "/documentation-tests.html" = "write-documentation/documentation-tests.html" -"/website-features.html" = "advanced-features.html#custom-search-engines" -"/passes.html" = "deprecated-features.html#passes" diff --git a/src/doc/rustdoc/src/unstable-features.md b/src/doc/rustdoc/src/unstable-features.md index 32b350074..b8b5014ab 100644 --- a/src/doc/rustdoc/src/unstable-features.md +++ b/src/doc/rustdoc/src/unstable-features.md @@ -197,6 +197,35 @@ To do so, the `#[doc(keyword = "...")]` attribute is used. Example: mod empty_mod {} ``` +## Effects of other nightly features + +These nightly-only features are not primarily related to Rustdoc, +but have convenient effects on the documentation produced. + +### `fundamental` types + +Annotating a type with `#[fundamental]` primarily influences coherence rules about generic types, +i.e., they alter whether other crates can provide implementations for that type. +The unstable book [links to further information][unstable-fundamental]. + +[unstable-fundamental]: https://doc.rust-lang.org/unstable-book/language-features/fundamental.html + +For documentation, this has an additional side effect: +If a method is implemented on `F<T>` (or `F<&T>`), +where `F` is a fundamental type, +then the method is not only documented at the page about `F`, +but also on the page about `T`. +In a sense, it makes the type transparent to Rustdoc. +This is especially convenient for types that work as annotated pointers, +such as `Pin<&mut T>`, +as it ensures that methods only implemented through those annotated pointers +can still be found with the type they act on. + +If the `fundamental` feature's effect on coherence is not intended, +such a type can be marked as fundamental only for purposes of documentation +by introducing a custom feature and +limiting the use of `fundamental` to when documentation is built. + ## Unstable command-line arguments These features are enabled by passing a command-line flag to Rustdoc, but the flags in question are @@ -465,6 +494,16 @@ Note that the third item is the crate root, which in this case is undocumented. [JSON format](https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types/). `--output-format html` has no effect, and is also accepted on stable toolchains. +JSON Output for toolchain crates (`std`, `alloc`, `core`, `test`, and `proc_macro`) +is available via the `rust-docs-json` rustup component. + +```shell +rustup component add --toolchain nightly rust-docs-json +``` + +Then the json files will be present in the `share/doc/rust/json/` directory +of the rustup toolchain directory. + It can also be used with `--show-coverage`. Take a look at its [documentation](#--show-coverage-calculate-the-percentage-of-items-with-documentation) for more information. diff --git a/src/doc/style-guide/book.toml b/src/doc/style-guide/book.toml new file mode 100644 index 000000000..056aec8cd --- /dev/null +++ b/src/doc/style-guide/book.toml @@ -0,0 +1,8 @@ +[book] +title = "The Rust Style Guide" +author = "The Rust Style Team" +multilingual = false +src = "src" + +[output.html] +git-repository-url = "https://github.com/rust-lang/rust/tree/HEAD/src/doc/style-guide/" diff --git a/src/doc/style-guide/src/README.md b/src/doc/style-guide/src/README.md new file mode 100644 index 000000000..adb73a7ee --- /dev/null +++ b/src/doc/style-guide/src/README.md @@ -0,0 +1,190 @@ +# Rust Style Guide + +## Motivation - why use a formatting tool? + +Formatting code is a mostly mechanical task which takes both time and mental +effort. By using an automatic formatting tool, a programmer is relieved of +this task and can concentrate on more important things. + +Furthermore, by sticking to an established style guide (such as this one), +programmers don't need to formulate ad hoc style rules, nor do they need to +debate with other programmers what style rules should be used, saving time, +communication overhead, and mental energy. + +Humans comprehend information through pattern matching. By ensuring that all +Rust code has similar formatting, less mental effort is required to comprehend a +new project, lowering the barrier to entry for new developers. + +Thus, there are productivity benefits to using a formatting tool (such as +rustfmt), and even larger benefits by using a community-consistent formatting, +typically by using a formatting tool's default settings. + + +## Formatting conventions + +### Indentation and line width + +* Use spaces, not tabs. +* Each level of indentation must be four spaces (that is, all indentation + outside of string literals and comments must be a multiple of four). +* The maximum width for a line is 100 characters. +* A tool should be configurable for all three of these variables. + + +### Blank lines + +Separate items and statements by either zero or one blank lines (i.e., one or +two newlines). E.g, + +```rust +fn foo() { + let x = ...; + + let y = ...; + let z = ...; +} + +fn bar() {} +fn baz() {} +``` + +Formatting tools should make the bounds on blank lines configurable: there +should be separate minimum and maximum numbers of newlines between both +statements and (top-level) items (i.e., four options). As described above, the +defaults for both statements and items should be minimum: 1, maximum: 2. + + +### [Module-level items](items.md) +### [Statements](statements.md) +### [Expressions](expressions.md) +### [Types](types.md) + + +### Comments + +The following guidelines for comments are recommendations only, a mechanical +formatter might skip formatting of comments. + +Prefer line comments (`//`) to block comments (`/* ... */`). + +When using line comments there should be a single space after the opening sigil. + +When using single-line block comments there should be a single space after the +opening sigil and before the closing sigil. Multi-line block comments should +have a newline after the opening sigil and before the closing sigil. + +Prefer to put a comment on its own line. Where a comment follows code, there +should be a single space before it. Where a block comment is inline, there +should be surrounding whitespace as if it were an identifier or keyword. There +should be no trailing whitespace after a comment or at the end of any line in a +multi-line comment. Examples: + +```rust +// A comment on an item. +struct Foo { ... } + +fn foo() {} // A comment after an item. + +pub fn foo(/* a comment before an argument */ x: T) {...} +``` + +Comments should usually be complete sentences. Start with a capital letter, end +with a period (`.`). An inline block comment may be treated as a note without +punctuation. + +Source lines which are entirely a comment should be limited to 80 characters +in length (including comment sigils, but excluding indentation) or the maximum +width of the line (including comment sigils and indentation), whichever is +smaller: + +```rust +// This comment goes up to the ................................. 80 char margin. + +{ + // This comment is .............................................. 80 chars wide. +} + +{ + { + { + { + { + { + // This comment is limited by the ......................... 100 char margin. + } + } + } + } + } +} +``` + +#### Doc comments + +Prefer line comments (`///`) to block comments (`/** ... */`). + +Prefer outer doc comments (`///` or `/** ... */`), only use inner doc comments +(`//!` and `/*! ... */`) to write module-level or crate-level documentation. + +Doc comments should come before attributes. + +### Attributes + +Put each attribute on its own line, indented to the level of the item. +In the case of inner attributes (`#!`), indent it to the level of the inside of +the item. Prefer outer attributes, where possible. + +For attributes with argument lists, format like functions. + +```rust +#[repr(C)] +#[foo(foo, bar)] +struct CRepr { + #![repr(C)] + x: f32, + y: f32, +} +``` + +For attributes with an equal sign, there should be a single space before and +after the `=`, e.g., `#[foo = 42]`. + +There must only be a single `derive` attribute. Note for tool authors: if +combining multiple `derive` attributes into a single attribute, the ordering of +the derived names should be preserved. E.g., `#[derive(bar)] #[derive(foo)] +struct Baz;` should be formatted to `#[derive(bar, foo)] struct Baz;`. + +### *small* items + +In many places in this guide we specify that a formatter may format an item +differently if it is *small*, for example struct literals: + +```rust +// Normal formatting +Foo { + f1: an_expression, + f2: another_expression(), +} + +// *small* formatting +Foo { f1, f2 } +``` + +We leave it to individual tools to decide on exactly what *small* means. In +particular, tools are free to use different definitions in different +circumstances. + +Some suitable heuristics are the size of the item (in characters) or the +complexity of an item (for example, that all components must be simple names, +not more complex sub-expressions). For more discussion on suitable heuristics, +see [this issue](https://github.com/rust-lang-nursery/fmt-rfcs/issues/47). + +Tools should give the user an option to ignore such heuristics and always use +the normal formatting. + + +## [Non-formatting conventions](advice.md) + +## [Cargo.toml conventions](cargo.md) + +## [Principles used for deciding these guidelines](principles.md) diff --git a/src/doc/style-guide/src/SUMMARY.md b/src/doc/style-guide/src/SUMMARY.md new file mode 100644 index 000000000..004692fa6 --- /dev/null +++ b/src/doc/style-guide/src/SUMMARY.md @@ -0,0 +1,11 @@ +# Summary + +[Introduction](README.md) + +- [Module-level items](items.md) +- [Statements](statements.md) +- [Expressions](expressions.md) +- [Types](types.md) +- [Non-formatting conventions](advice.md) +- [`Cargo.toml` conventions](cargo.md) +- [Principles used for deciding these guidelines](principles.md) diff --git a/src/doc/style-guide/src/advice.md b/src/doc/style-guide/src/advice.md new file mode 100644 index 000000000..ab4b92b0a --- /dev/null +++ b/src/doc/style-guide/src/advice.md @@ -0,0 +1,34 @@ +# Other style advice + +## Expressions + +Prefer to use Rust's expression oriented nature where possible; + +```rust +// use +let x = if y { 1 } else { 0 }; +// not +let x; +if y { + x = 1; +} else { + x = 0; +} +``` + +## Names + + * Types shall be `UpperCamelCase`, + * Enum variants shall be `UpperCamelCase`, + * Struct fields shall be `snake_case`, + * Function and method names shall be `snake_case`, + * Local variables shall be `snake_case`, + * Macro names shall be `snake_case`, + * Constants (`const`s and immutable `static`s) shall be `SCREAMING_SNAKE_CASE`. + * When a name is forbidden because it is a reserved word (e.g., `crate`), use a + trailing underscore to make the name legal (e.g., `crate_`), or use raw + identifiers if possible. + +### Modules + +Avoid `#[path]` annotations where possible. diff --git a/src/doc/style-guide/src/cargo.md b/src/doc/style-guide/src/cargo.md new file mode 100644 index 000000000..f4993ba06 --- /dev/null +++ b/src/doc/style-guide/src/cargo.md @@ -0,0 +1,78 @@ +# Cargo.toml conventions + +## Formatting conventions + +Use the same line width and indentation as Rust code. + +Put a blank line between the last key-value pair in a section and the header of +the next section. Do not place a blank line between section headers and the +key-value pairs in that section, or between key-value pairs in a section. + +Sort key names alphabetically within each section, with the exception of the +`[package]` section. Put the `[package]` section at the top of the file; put +the `name` and `version` keys in that order at the top of that section, +followed by the remaining keys other than `description` in alphabetical order, +followed by the `description` at the end of that section. + +Don't use quotes around any standard key names; use bare keys. Only use quoted +keys for non-standard keys whose names require them, and avoid introducing such +key names when possible. See the [TOML +specification](https://github.com/toml-lang/toml/blob/master/versions/en/toml-v0.4.0.md#table) +for details. + +Put a single space both before and after the `=` between a key and value. Do +not indent any key names; start all key names at the start of a line. + +Use multi-line strings (rather than newline escape sequences) for any string +values that include multiple lines, such as the crate description. + +For array values, such as a list of authors, put the entire list on the same +line as the key, if it fits. Otherwise, use block indentation: put a newline +after the opening square bracket, indent each item by one indentation level, +put a comma after each item (including the last), and put the closing square +bracket at the start of a line by itself after the last item. + +```rust +authors = [ + "A Uthor <a.uthor@example.org>", + "Another Author <author@example.net>", +] +``` + +For table values, such as a crate dependency with a path, write the entire +table using curly braces and commas on the same line as the key if it fits. If +the entire table does not fit on the same line as the key, separate it out into +a separate section with key-value pairs: + +```toml +[dependencies] +crate1 = { path = "crate1", version = "1.2.3" } + +[dependencies.extremely_long_crate_name_goes_here] +path = "extremely_long_path_name_goes_right_here" +version = "4.5.6" +``` + +## Metadata conventions + +The authors list should consist of strings that each contain an author name +followed by an email address in angle brackets: `Full Name <email@address>`. +It should not contain bare email addresses, or names without email addresses. +(The authors list may also include a mailing list address without an associated +name.) + +The license field must contain a valid [SPDX +expression](https://spdx.org/spdx-specification-21-web-version#h.jxpfx0ykyb60), +using valid [SPDX license names](https://spdx.org/licenses/). (As an exception, +by widespread convention, the license field may use `/` in place of ` OR `; for +example, `MIT/Apache-2.0`.) + +The homepage field, if present, must consist of a single URL, including the +scheme (e.g. `https://example.org/`, not just `example.org`.) + +Within the description field, wrap text at 80 columns. Don't start the +description field with the name of the crate (e.g. "cratename is a ..."); just +describe the crate itself. If providing a multi-sentence description, the first +sentence should go on a line by itself and summarize the crate, like the +subject of an email or commit message; subsequent sentences can then describe +the crate in more detail. diff --git a/src/doc/style-guide/src/expressions.md b/src/doc/style-guide/src/expressions.md new file mode 100644 index 000000000..c7d0446dd --- /dev/null +++ b/src/doc/style-guide/src/expressions.md @@ -0,0 +1,850 @@ +## Expressions + +### Blocks + +A block expression should have a newline after the initial `{` and before the +terminal `}`. Any qualifier before the block (e.g., `unsafe`) should always be +on the same line as the opening brace, and separated with a single space. The +contents of the block should be block indented: + +```rust +fn block_as_stmt() { + a_call(); + + { + a_call_inside_a_block(); + + // a comment in a block + the_value + } +} + +fn block_as_expr() { + let foo = { + a_call_inside_a_block(); + + // a comment in a block + the_value + }; +} + +fn unsafe_block_as_stmt() { + a_call(); + + unsafe { + a_call_inside_a_block(); + + // a comment in a block + the_value + } +} +``` + +If a block has an attribute, it should be on its own line: + +```rust +fn block_as_stmt() { + #[an_attribute] + { + #![an_inner_attribute] + + // a comment in a block + the_value + } +} +``` + +Avoid writing comments on the same line as the braces. + +An empty block should be written as `{}`. + +A block may be written on a single line if: + +* it is either used in expression position (not statement position) or is an + unsafe block in statement position +* contains a single-line expression and no statements +* contains no comments + +A single line block should have spaces after the opening brace and before the +closing brace. + +Examples: + +```rust +fn main() { + // Single line + let _ = { a_call() }; + let _ = unsafe { a_call() }; + + // Not allowed on one line + // Statement position. + { + a_call() + } + + // Contains a statement + let _ = { + a_call(); + }; + unsafe { + a_call(); + } + + // Contains a comment + let _ = { + // A comment + }; + let _ = { + // A comment + a_call() + }; + + // Multiple lines + let _ = { + a_call(); + another_call() + }; + let _ = { + a_call( + an_argument, + another_arg, + ) + }; +} +``` + + +### Closures + +Don't put any extra spaces before the first `|` (unless the closure is prefixed +by `move`); put a space between the second `|` and the expression of the +closure. Between the `|`s, you should use function definition syntax, however, +elide types where possible. + +Use closures without the enclosing `{}`, if possible. Add the `{}` when you have +a return type, when there are statements, there are comments in the body, or the +body expression spans multiple lines and is a control-flow expression. If using +braces, follow the rules above for blocks. Examples: + +```rust +|arg1, arg2| expr + +move |arg1: i32, arg2: i32| -> i32 { + expr1; + expr2 +} + +|| Foo { + field1, + field2: 0, +} + +|| { + if true { + blah + } else { + boo + } +} + +|x| unsafe { + expr +} +``` + + +### Struct literals + +If a struct literal is *small* it may be formatted on a single line. If not, +each field should be on it's own, block-indented line. There should be a +trailing comma in the multi-line form only. There should be a space after the +colon only. + +There should be a space before the opening brace. In the single-line form there +should be spaces after the opening brace and before the closing brace. + +```rust +Foo { field1, field2: 0 } +let f = Foo { + field1, + field2: an_expr, +}; +``` + +Functional record update syntax is treated like a field, but it must never have +a trailing comma. There should be no space after `..`. + +let f = Foo { + field1, + ..an_expr +}; + + +### Tuple literals + +Use a single-line form where possible. There should not be spaces around the +parentheses. Where a single-line form is not possible, each element of the tuple +should be on its own block-indented line and there should be a trailing comma. + +```rust +(a, b, c) + +let x = ( + a_long_expr, + another_very_long_expr, +); +``` + + +### Tuple struct literals + +There should be no space between the identifier and the opening parenthesis. +Otherwise, follow the rules for tuple literals, e.g., `Foo(a, b)`. + + +### Enum literals + +Follow the formatting rules for the various struct literals. Prefer using the +name of the enum as a qualifying name, unless the enum is in the prelude. E.g., + +```rust +Foo::Bar(a, b) +Foo::Baz { + field1, + field2: 1001, +} +Ok(an_expr) +``` + + +### Array literals + +For simple array literals, avoid line breaking, no spaces around square +brackets, contents of the array should be separated by commas and spaces. If +using the repeating initialiser, there should be a space after the semicolon +only. Apply the same rules if using the `vec!` or similar macros (always use +square brackets here). Examples: + +```rust +fn main() { + [1, 2, 3]; + vec![a, b, c, d]; + let a = [42; 10]; +} +``` + +If a line must be broken, prefer breaking only after the `;`, if possible. +Otherwise, follow the rules below for function calls. In any case, the contents +of the initialiser should be block indented and there should be line breaks +after the opening bracket and before the closing bracket: + +```rust +fn main() { + [ + a_long_expression(); + 1234567890 + ] + let x = [ + an_expression, + another_expression, + a_third_expression, + ]; +} +``` + + +### Array accesses, indexing, and slicing. + +No spaces around the square brackets, avoid breaking lines if possible, never +break a line between the target expression and the opening bracket. If the +indexing expression covers multiple lines, then it should be block indented and +there should be newlines after the opening brackets and before the closing +bracket. However, this should be avoided where possible. + +Examples: + +```rust +fn main() { + foo[42]; + &foo[..10]; + bar[0..100]; + foo[4 + 5 / bar]; + a_long_target[ + a_long_indexing_expression + ]; +} +``` + +### Unary operations + +Do not include a space between a unary op and its operand (i.e., `!x`, not +`! x`). However, there must be a space after `&mut`. Avoid line-breaking +between a unary operator and its operand. + +### Binary operations + +Do include spaces around binary ops (i.e., `x + 1`, not `x+1`) (including `=` +and other assignment operators such as `+=` or `*=`). + +For comparison operators, because for `T op U`, `&T op &U` is also implemented: +if you have `t: &T`, and `u: U`, prefer `*t op u` to `t op &u`. In general, +within expressions, prefer dereferencing to taking references. + +Use parentheses liberally, do not necessarily elide them due to precedence. +Tools should not automatically insert or remove parentheses. Do not use spaces +to indicate precedence. + +If line-breaking, put the operator on a new line and block indent. Put each +sub-expression on its own line. E.g., + +```rust +foo_bar + + bar + + baz + + qux + + whatever +``` + +Prefer line-breaking at an assignment operator (either `=` or `+=`, etc.) rather +than at other binary operators. + +### Control flow + +Do not include extraneous parentheses for `if` and `while` expressions. + +```rust +if true { +} +``` + +is better than + +```rust +if (true) { +} +``` + +Do include extraneous parentheses if it makes an arithmetic or logic expression +easier to understand (`(x * 15) + (y * 20)` is fine) + +### Function calls + +Do not put a space between the function name, and the opening parenthesis. + +Do not put a space between an argument, and the comma which follows. + +Do put a space between an argument, and the comma which precedes it. + +Prefer not to break a line in the callee expression. + +#### Single-line calls + +Do not put a space between the function name and open paren, between the open +paren and the first argument, or between the last argument and the close paren. + +Do not put a comma after the last argument. + +```rust +foo(x, y, z) +``` + +#### Multi-line calls + +If the function call is not *small*, it would otherwise over-run the max width, +or any argument or the callee is multi-line, then the call should be formatted +across multiple lines. In this case, each argument should be on it's own block- +indented line, there should be a newline after the opening parenthesis and +before the closing parenthesis, and there should be a trailing comma. E.g., + +```rust +a_function_call( + arg1, + a_nested_call(a, b), +) +``` + + +### Method calls + +Follow the function rules for calling. + +Do not put any spaces around the `.`. + +```rust +x.foo().bar().baz(x, y, z); +``` + + +### Macro uses + +Macros which can be parsed like other constructs should be formatted like those +constructs. For example, a macro use `foo!(a, b, c)` can be parsed like a +function call (ignoring the `!`), therefore it should be formatted following the +rules for function calls. + +#### Special case macros + +Macros which take a format string and where all other arguments are *small* may +be formatted with arguments before and after the format string on a single line +and the format string on its own line, rather than putting each argument on its +own line. For example, + +```rust +println!( + "Hello {} and {}", + name1, name2, +); + +assert_eq!( + x, y, + "x and y were not equal, see {}", + reason, +); +``` + + +### Casts (`as`) + +Put spaces before and after `as`: + +```rust +let cstr = "Hi\0" as *const str as *const [u8] as *const std::os::raw::c_char; +``` + + +### Chains of fields and method calls + +A chain is a sequence of field accesses and/or method calls. A chain may also +include the try operator ('?'). E.g., `a.b.c().d` or `foo?.bar().baz?`. + +Prefer formatting on one line if possible, and the chain is *small*. If +formatting on multiple lines, each field access or method call in the chain +should be on its own line with the line-break before the `.` and after any `?`. +Each line should be block-indented. E.g., + +```rust +let foo = bar + .baz? + .qux(); +``` + +If the length of the last line of the first element plus its indentation is +less than or equal to the indentation of the second line (and there is space), +then combine the first and second lines, e.g., + +```rust +x.baz? + .qux() + +let foo = x + .baz? + .qux(); + +foo( + expr1, + expr2, +).baz? + .qux(); +``` + +#### Multi-line elements + +If any element in a chain is formatted across multiple lines, then that element +and any later elements must be on their own line. Earlier elements may be kept +on a single line. E.g., + +```rust +a.b.c()?.d + .foo( + an_expr, + another_expr, + ) + .bar + .baz +``` + +Note there is block indent due to the chain and the function call in the above +example. + +Prefer formatting the whole chain in multi-line style and each element on one +line, rather than putting some elements on multiple lines and some on a single +line, e.g., + +```rust +// Better +self.pre_comment + .as_ref() + .map_or(false, |comment| comment.starts_with("//")) + +// Worse +self.pre_comment.as_ref().map_or( + false, + |comment| comment.starts_with("//"), +) +``` + +### Control flow expressions + +This section covers `if`, `if let`, `loop`, `while`, `while let`, and `for` +expressions. + +The keyword, any initial clauses, and the opening brace of the block should be +on a single line. The usual rules for [block formatting](#blocks) should be +applied to the block. + +If there is an `else` component, then the closing brace, `else`, any following +clause, and the opening brace should all be on the same line. There should be a +single space before and after the `else` keyword. For example: + +```rust +if ... { + ... +} else { + ... +} + +if let ... { + ... +} else if ... { + ... +} else { + ... +} +``` + +If the control line needs to be broken, then prefer to break before the `=` in +`* let` expressions and before `in` in a `for` expression; the following line +should be block indented. If the control line is broken for any reason, then the +opening brace should be on its own line and not indented. Examples: + +```rust +while let Some(foo) + = a_long_expression +{ + ... +} + +for foo + in a_long_expression +{ + ... +} + +if a_long_expression + && another_long_expression + || a_third_long_expression +{ + ... +} +``` + +Where the initial clause is multi-lined and ends with one or more closing +parentheses, square brackets, or braces, and there is nothing else on that line, +and that line is not indented beyond the indent on the first line of the control +flow expression, then the opening brace of the block should be put on the same +line with a preceding space. For example: + +```rust +if !self.config.file_lines().intersects( + &self.codemap.lookup_line_range( + stmt.span, + ), +) { // Opening brace on same line as initial clause. + ... +} +``` + + +#### Single line `if else` + +Formatters may place an `if else` or `if let else` on a single line if it occurs +in expression context (i.e., is not a standalone statement), it contains a +single `else` clause, and is *small*. For example: + +```rust +let y = if x { 0 } else { 1 }; + +// Examples that must be multi-line. +let y = if something_very_long { + not_small +} else { + also_not_small +}; + +if x { + 0 +} else { + 1 +} +``` + + +### Match + +Prefer not to line-break inside the discriminant expression. There must always +be a line break after the opening brace and before the closing brace. The match +arms must be block indented once: + +```rust +match foo { + // arms +} + +let x = match foo.bar.baz() { + // arms +}; +``` + +Use a trailing comma for a match arm if and only if not using a block. + +Never start a match arm pattern with `|`, e.g., + +```rust +match foo { + // Don't do this. + | foo => bar, + // Or this. + | a_very_long_pattern + | another_pattern + | yet_another_pattern + | a_forth_pattern => { + ... + } +} +``` + +Prefer + + +```rust +match foo { + foo => bar, + a_very_long_pattern + | another_pattern + | yet_another_pattern + | a_forth_pattern => { + ... + } +} +``` + +Avoid splitting the left-hand side (before the `=>`) of a match arm where +possible. If the right-hand side of the match arm is kept on the same line, +never use a block (unless the block is empty). + +If the right-hand side consists of multiple statements or has line comments or +the start of the line cannot be fit on the same line as the left-hand side, use +a block. + +The body of a block arm should be block indented once. + +Examples: + +```rust +match foo { + foo => bar, + a_very_long_patten | another_pattern if an_expression() => { + no_room_for_this_expression() + } + foo => { + // A comment. + an_expression() + } + foo => { + let a = statement(); + an_expression() + } + bar => {} + // Trailing comma on last item. + foo => bar, +} +``` + +If the body is a single expression with no line comments and not a control flow +expression, then it may be started on the same line as the right-hand side. If +not, then it must be in a block. Example, + +```rust +match foo { + // A combinable expression. + foo => a_function_call(another_call( + argument1, + argument2, + )), + // A non-combinable expression + bar => { + a_function_call( + another_call( + argument1, + argument2, + ), + another_argument, + ) + } +} +``` + +#### Line-breaking + +Where it is possible to use a block form on the right-hand side and avoid +breaking the left-hand side, do that. E.g. + +```rust + // Assuming the following line does done fit in the max width + a_very_long_pattern | another_pattern => ALongStructName { + ... + }, + // Prefer this + a_very_long_pattern | another_pattern => { + ALongStructName { + ... + } + } + // To splitting the pattern. +``` + +Never break after `=>` without using the block form of the body. + +If the left-hand side must be split and there is an `if` clause, break before +the `if` and block indent. In this case, always use a block body and start the +body on a new line: + +```rust + a_very_long_pattern | another_pattern + if expr => + { + ... + } +``` + +If required to break the pattern, put each clause of the pattern on its own +line with no additional indent, breaking before the `|`. If there is an `if` +clause, then you must use the above form: + +```rust + a_very_long_pattern + | another_pattern + | yet_another_pattern + | a_forth_pattern => { + ... + } + a_very_long_pattern + | another_pattern + | yet_another_pattern + | a_forth_pattern + if expr => + { + ... + } +``` + +If the pattern is multi-line, and the last line is less wide than the indent, do +not put the `if` clause on a newline. E.g., + +```rust + Token::Dimension { + value, + ref unit, + .. + } if num_context.is_ok(context.parsing_mode, value) => { + ... + } +``` + +If every clause in a pattern is *small*, but does not fit on one line, then the +pattern may be formatted across multiple lines with as many clauses per line as +possible. Again break before a `|`: + +```rust + foo | bar | baz + | qux => { + ... + } +``` + +We define a pattern clause to be *small* if it matches the following grammar: + +``` +[small, ntp]: + - single token + - `&[single-line, ntp]` + +[small]: + - `[small, ntp]` + - unary tuple constructor `([small, ntp])` + - `&[small]` +``` + +E.g., `&&Some(foo)` matches, `Foo(4, Bar)` does not. + + +### Combinable expressions + +Where a function call has a single argument, and that argument is formatted +across multiple-lines, the outer call may be formatted as if it were a single- +line call. The same combining behaviour may be applied to any similar +expressions which have multi-line, block-indented lists of sub-expressions +delimited by parentheses (e.g., macros or tuple struct literals). E.g., + +```rust +foo(bar( + an_expr, + another_expr, +)) + +let x = foo(Bar { + field: whatever, +}); + +foo(|param| { + action(); + foo(param) +}) +``` + +Such behaviour should extend recursively, however, tools may choose to limit the +depth of nesting. + +Only where the multi-line sub-expression is a closure with an explicit block, +this combining behaviour may be used where there are other arguments, as long as +all the arguments and the first line of the closure fit on the first line, the +closure is the last argument, and there is only one closure argument: + +```rust +foo(first_arg, x, |param| { + action(); + foo(param) +}) +``` + + +### Ranges + +Do not put spaces in ranges, e.g., `0..10`, `x..=y`, `..x.len()`, `foo..`. + +When writing a range with both upper and lower bounds, if the line must be +broken, break before the range operator and block indent the second line: + +```rust +a_long_expression + ..another_long_expression +``` + +For the sake of indicating precedence, we recommend that if either bound is a +compound expression, then use parentheses around it, e.g., `..(x + 1)`, +`(x.f)..(x.f.len())`, or `0..(x - 10)`. + + +### Hexadecimal literals + +Hexadecimal literals may use upper- or lower-case letters, but they must not be +mixed within the same literal. Projects should use the same case for all +literals, but we do not make a recommendation for either lower- or upper-case. +Tools should have an option to convert mixed case literals to upper-case, and +may have an option to convert all literals to either lower- or upper-case. + + +## Patterns + +Patterns should be formatted like their corresponding expressions. See the +section on `match` for additional formatting for patterns in match arms. diff --git a/src/doc/style-guide/src/items.md b/src/doc/style-guide/src/items.md new file mode 100644 index 000000000..283597535 --- /dev/null +++ b/src/doc/style-guide/src/items.md @@ -0,0 +1,565 @@ +## Items + +`extern crate` statements must be first in a file. They must be ordered +alphabetically. + +`use` statements, and module *declarations* (`mod foo;`, not `mod { ... }`) +must come before other items. We recommend that imports come before module +declarations; if imports and modules are separated, then they should be ordered +alphabetically. When sorting, `self` and `super` must come before any other +names. Module declarations should not be moved if they are annotated with +`#[macro_use]`, since that may be semantics changing. + +Tools should make the above ordering optional. + + +### Function definitions + +In Rust, one finds functions by searching for `fn [function-name]`; It's +important that you style your code so that it's very searchable in this way. + +The proper ordering and spacing is: + +```rust +[pub] [unsafe] [extern ["ABI"]] fn foo(arg1: i32, arg2: i32) -> i32 { + ... +} +``` + +Avoid comments within the signature itself. + +If the function signature does not fit on one line, then break after the opening +parenthesis and before the closing parenthesis and put each argument on its own +block-indented line. For example, + +```rust +fn foo( + arg1: i32, + arg2: i32, +) -> i32 { + ... +} +``` + +Note the trailing comma on the last argument. + + +### Tuples and tuple structs + +Write the type list as you would a parameter list to a function. + +Build a tuple or tuple struct as you would call a function. + +#### Single-line + +```rust +struct Bar(Type1, Type2); + +let x = Bar(11, 22); +let y = (11, 22, 33); +``` + +### Enums + +In the declaration, put each variant on its own line, block indented. + +Format each variant accordingly as either a struct, tuple struct, or identifier, +which doesn't require special formatting (but without the `struct` keyword. + +```rust +enum FooBar { + First(u32), + Second, + Error { + err: Box<Error>, + line: u32, + }, +} +``` + +If a struct variant is [*small*](index.html#small-items), it may be formatted on +one line. In this case, do not use a trailing comma for the field list, but do +put spaces around each brace: + +```rust +enum FooBar { + Error { err: Box<Error>, line: u32 }, +} +``` + +In an enum with multiple struct variants, if any struct variant is written on +multiple lines, then the multi-line formatting should be used for all struct +variants. However, such a situation might be an indication that you should +factor out the fields of the variant into their own struct. + + +### Structs and Unions + +Struct names follow on the same line as the `struct` keyword, with the opening +brace on the same line when it fits within the right margin. All struct fields +are indented once and end with a trailing comma. The closing brace is not +indented and appears on its own line. + +```rust +struct Foo { + a: A, + b: B, +} +``` + +If and only if the type of a field does not fit within the right margin, it is +pulled down to its own line and indented again. + +```rust +struct Foo { + a: A, + long_name: + LongType, +} +``` + +Prefer using a unit struct (e.g., `struct Foo;`) to an empty struct (e.g., +`struct Foo();` or `struct Foo {}`, these only exist to simplify code +generation), but if you must use an empty struct, keep it on one line with no +space between the braces: `struct Foo;` or `struct Foo {}`. + +The same guidelines are used for untagged union declarations. + +```rust +union Foo { + a: A, + b: B, + long_name: + LongType, +} +``` + + +### Tuple structs + +Put the whole struct on one line if possible. Types in the parentheses should be +separated by a comma and space with no trailing comma. No spaces around the +parentheses or semi-colon: + +```rust +pub struct Foo(String, u8); +``` + +Prefer unit structs to empty tuple structs (these only exist to simplify code +generation), e.g., `struct Foo;` rather than `struct Foo();`. + +For more than a few fields, prefer a proper struct with named fields. Given +this, a tuple struct should always fit on one line. If it does not, block format +the fields with a field on each line and a trailing comma: + +```rust +pub struct Foo( + String, + u8, +); +``` + + +### Traits + +Trait items should be block-indented. If there are no items, the trait may be +formatted on a single line. Otherwise there should be line-breaks after the +opening brace and before the closing brace: + +```rust +trait Foo {} + +pub trait Bar { + ... +} +``` + +If the trait has bounds, there should be a space after the colon but not before +and before and after each `+`, e.g., + +```rust +trait Foo: Debug + Bar {} +``` + +Prefer not to line-break in the bounds if possible (consider using a `where` +clause). Prefer to break between bounds than to break any individual bound. If +you must break the bounds, put each bound (including the first) on its own +block-indented line, break before the `+` and put the opening brace on its own +line: + +```rust +pub trait IndexRanges: + Index<Range<usize>, Output=Self> + + Index<RangeTo<usize>, Output=Self> + + Index<RangeFrom<usize>, Output=Self> + + Index<RangeFull, Output=Self> +{ + ... +} +``` + + +### Impls + +Impl items should be block indented. If there are no items, the impl may be +formatted on a single line. Otherwise there should be line-breaks after the +opening brace and before the closing brace: + +```rust +impl Foo {} + +impl Bar for Foo { + ... +} +``` + +Avoid line-breaking in the signature if possible. If a line break is required in +a non-inherent impl, break immediately before `for`, block indent the concrete type +and put the opening brace on its own line: + +```rust +impl Bar + for Foo +{ + ... +} +``` + + +### Extern crate + +`extern crate foo;` + +Use spaces around keywords, no spaces around the semi-colon. + + +### Modules + +```rust +mod foo { +} +``` + +```rust +mod foo; +``` + +Use spaces around keywords and before the opening brace, no spaces around the +semi-colon. + +### macro\_rules! + +Use `{}` for the full definition of the macro. + +```rust +macro_rules! foo { +} +``` + + +### Generics + +Prefer to put a generics clause on one line. Break other parts of an item +declaration rather than line-breaking a generics clause. If a generics clause is +large enough to require line-breaking, you should prefer to use a `where` clause +instead. + +Do not put spaces before or after `<` nor before `>`. Only put a space after `>` +if it is followed by a word or opening brace, not an opening parenthesis. There +should be a space after each comma and no trailing comma. + +```rust +fn foo<T: Display, U: Debug>(x: Vec<T>, y: Vec<U>) ... + +impl<T: Display, U: Debug> SomeType<T, U> { ... +``` + +If the generics clause must be formatted across multiple lines, each parameter +should have its own block-indented line, there should be newlines after the +opening bracket and before the closing bracket, and the should be a trailing +comma. + +```rust +fn foo< + T: Display, + U: Debug, +>(x: Vec<T>, y: Vec<U>) ... +``` + +If an associated type is bound in a generic type, then there should be spaces on +either side of the `=`: + +```rust +<T: Example<Item = u32>> +``` + +Prefer to use single-letter names for generic parameters. + + +### `where` clauses + +These rules apply for `where` clauses on any item. + +A `where` clause may immediately follow a closing bracket of any kind. +Otherwise, it must start a new line, with no indent. Each component of a `where` +clause must be on its own line and be block indented. There should be a trailing +comma, unless the clause is terminated with a semicolon. If the `where` clause +is followed by a block (or assignment), the block should be started on a new +line. Examples: + +```rust +fn function<T, U>(args) +where + T: Bound, + U: AnotherBound, +{ + body +} + +fn foo<T>( + args +) -> ReturnType +where + T: Bound, +{ + body +} + +fn foo<T, U>( + args, +) where + T: Bound, + U: AnotherBound, +{ + body +} + +fn foo<T, U>( + args +) -> ReturnType +where + T: Bound, + U: AnotherBound; // Note, no trailing comma. + +// Note that where clauses on `type` aliases are not enforced and should not +// be used. +type Foo<T> +where + T: Bound += Bar<T>; +``` + +If a `where` clause is very short, we recommend using an inline bound on the +type parameter. + + +If a component of a `where` clause is long, it may be broken before `+` and +further block indented. Each bound should go on its own line. E.g., + +```rust +impl<T: ?Sized, Idx> IndexRanges<Idx> for T +where + T: Index<Range<Idx>, Output = Self::Output> + + Index<RangeTo<Idx>, Output = Self::Output> + + Index<RangeFrom<Idx>, Output = Self::Output> + + Index<RangeInclusive<Idx>, Output = Self::Output> + + Index<RangeToInclusive<Idx>, Output = Self::Output> + Index<RangeFull> +``` + +#### Option - `where_single_line` + +`where_single_line` is `false` by default. If `true`, then a where clause with +exactly one component may be formatted on a single line if the rest of the +item's signature is also kept on one line. In this case, there is no need for a +trailing comma and if followed by a block, no need for a newline before the +block. E.g., + +```rust +// May be single-lined. +fn foo<T>(args) -> ReturnType +where T: Bound { + body +} + +// Must be multi-lined. +fn foo<T>( + args +) -> ReturnType +where + T: Bound, +{ + body +} +``` + + +### Type aliases + +Type aliases should generally be kept on one line. If necessary to break the +line, do so after the `=`; the right-hand-side should be block indented: + +```rust +pub type Foo = Bar<T>; + +// If multi-line is required +type VeryLongType<T, U: SomeBound> = + AnEvenLongerType<T, U, Foo<T>>; +``` + +Where possible avoid `where` clauses and keep type constraints inline. Where +that is not possible split the line before and after the `where` clause (and +split the `where` clause as normal), e.g., + +```rust +type VeryLongType<T, U> +where + T: U::AnAssociatedType, + U: SomeBound, += AnEvenLongerType<T, U, Foo<T>>; +``` + + +### Associated types + +Associated types should follow the guidelines above for type aliases. Where an +associated type has a bound, there should be a space after the colon but not +before: + +```rust +pub type Foo: Bar; +``` + + +### extern items + +When writing extern items (such as `extern "C" fn`), always be explicit about +the ABI. For example, write `extern "C" fn foo ...`, not `extern fn foo ...`, or +`extern "C" { ... }`. + + +### Imports (`use` statements) + +If an import can be formatted on one line, do so. There should be no spaces +around braces. + +```rust +use a::b::c; +use a::b::d::*; +use a::b::{foo, bar, baz}; +``` + + +#### Large list imports + +Prefer to use multiple imports rather than a multi-line import. However, tools +should not split imports by default (they may offer this as an option). + +If an import does require multiple lines (either because a list of single names +does not fit within the max width, or because of the rules for nested imports +below), then break after the opening brace and before the closing brace, use a +trailing comma, and block indent the names. + + +```rust +// Prefer +foo::{long, list, of, imports}; +foo::{more, imports}; + +// If necessary +foo::{ + long, list, of, imports, more, + imports, // Note trailing comma +}; +``` + + +#### Ordering of imports + +A *group* of imports is a set of imports on the same or sequential lines. One or +more blank lines or other items (e.g., a function) separate groups of imports. + +Within a group of imports, imports must be sorted ascii-betically. Groups of +imports must not be merged or re-ordered. + + +E.g., input: + +```rust +use d; +use c; + +use b; +use a; +``` + +output: + +```rust +use c; +use d; + +use a; +use b; +``` + +Because of `macro_use`, attributes must also start a new group and prevent +re-ordering. + +Note that tools which only have access to syntax (such as Rustfmt) cannot tell +which imports are from an external crate or the std lib, etc. + + +#### Ordering list import + +Names in a list import must be sorted ascii-betically, but with `self` and +`super` first, and groups and glob imports last. This applies recursively. For +example, `a::*` comes before `b::a` but `a::b` comes before `a::*`. E.g., +`use foo::bar::{a, b::c, b::d, b::d::{x, y, z}, b::{self, r, s}};`. + + +#### Normalisation + +Tools must make the following normalisations: + +* `use a::self;` -> `use a;` +* `use a::{};` -> (nothing) +* `use a::{b};` -> `use a::b;` + +And must apply these recursively. + +Tools must not otherwise merge or un-merge import lists or adjust glob imports +(without an explicit option). + + +#### Nested imports + +If there are any nested imports in a list import, then use the multi-line form, +even if the import fits on one line. Each nested import must be on its own line, +but non-nested imports must be grouped on as few lines as possible. + +For example, + +```rust +use a::b::{ + x, y, z, + u::{...}, + w::{...}, +}; +``` + + +#### Merging/un-merging imports + +An example: + +```rust +// Un-merged +use a::b; +use a::c::d; + +// Merged +use a::{b, c::d}; +``` + +Tools must not merge or un-merge imports by default. They may offer merging or +un-merging as an option. diff --git a/src/doc/style-guide/src/principles.md b/src/doc/style-guide/src/principles.md new file mode 100644 index 000000000..b02b3c047 --- /dev/null +++ b/src/doc/style-guide/src/principles.md @@ -0,0 +1,51 @@ +# Guiding principles and rationale + +When deciding on style guidelines, the style team tried to be guided by the +following principles (in rough priority order): + +* readability + - scan-ability + - avoiding misleading formatting + - accessibility - readable and editable by users using the the widest + variety of hardware, including non-visual accessibility interfaces + - readability of code when quoted in rustc error messages + +* aesthetics + - sense of 'beauty' + - consistent with other languages/tools + +* specifics + - compatibility with version control practices - preserving diffs, + merge-friendliness, etc. + - preventing right-ward drift + - minimising vertical space + +* application + - ease of manual application + - ease of implementation (in Rustfmt, and in other tools/editors/code generators) + - internal consistency + - simplicity of formatting rules + + +## Overarching guidelines + +Prefer block indent over visual indent. E.g., + +```rust +// Block indent +a_function_call( + foo, + bar, +); + +// Visual indent +a_function_call(foo, + bar); +``` + +This makes for smaller diffs (e.g., if `a_function_call` is renamed in the above +example) and less rightward drift. + +Lists should have a trailing comma when followed by a newline, see the block +indent example above. This choice makes moving code (e.g., by copy and paste) +easier and makes smaller diffs. diff --git a/src/doc/style-guide/src/statements.md b/src/doc/style-guide/src/statements.md new file mode 100644 index 000000000..29b48bb1e --- /dev/null +++ b/src/doc/style-guide/src/statements.md @@ -0,0 +1,150 @@ +### Let statements + +There should be spaces after the `:` and on both sides of the `=` (if they are +present). No space before the semi-colon. + +```rust +// A comment. +let pattern: Type = expr; + +let pattern; +let pattern: Type; +let pattern = expr; +``` + +If possible the declaration should be formatted on a single line. If this is not +possible, then try splitting after the `=`, if the declaration can fit on two +lines. The expression should be block indented. + +```rust +let pattern: Type = + expr; +``` + +If the first line does not fit on a single line, then split after the colon, +using block indentation. If the type covers multiple lines, even after line- +breaking after the `:`, then the first line may be placed on the same line as +the `:`, subject to the [combining rules](https://github.com/rust-lang-nursery/fmt-rfcs/issues/61) (WIP). + + +```rust +let pattern: + Type = + expr; +``` + +e.g, + +```rust +let Foo { + f: abcd, + g: qwer, +}: Foo<Bar> = + Foo { f, g }; + +let (abcd, + defg): + Baz = +{ ... } +``` + +If the expression covers multiple lines, if the first line of the expression +fits in the remaining space, it stays on the same line as the `=`, the rest of the +expression is not indented. If the first line does not fit, then it should start +on the next lines, and should be block indented. If the expression is a block +and the type or pattern cover multiple lines, then the opening brace should be +on a new line and not indented (this provides separation for the interior of the +block from the type), otherwise the opening brace follows the `=`. + +Examples: + +```rust +let foo = Foo { + f: abcd, + g: qwer, +}; + +let foo = + ALongName { + f: abcd, + g: qwer, + }; + +let foo: Type = { + an_expression(); + ... +}; + +let foo: + ALongType = +{ + an_expression(); + ... +}; + +let Foo { + f: abcd, + g: qwer, +}: Foo<Bar> = Foo { + f: blimblimblim, + g: blamblamblam, +}; + +let Foo { + f: abcd, + g: qwer, +}: Foo<Bar> = foo( + blimblimblim, + blamblamblam, +); +``` + + +### Macros in statement position + +A macro use in statement position should use parentheses or square brackets as +delimiters and should be terminated with a semi-colon. There should be no spaces +between the name, `!`, the delimiters, or the `;`. + +```rust +// A comment. +a_macro!(...); +``` + + +### Expressions in statement position + +There should be no space between the expression and the semi-colon. + +``` +<expr>; +``` + +All expressions in statement position should be terminated with a semi-colon, +unless they end with a block or are used as the value for a block. + +E.g., + +```rust +{ + an_expression(); + expr_as_value() +} + +return foo(); + +loop { + break; +} +``` + +Use a semi-colon where an expression has void type, even if it could be +propagated. E.g., + +```rust +fn foo() { ... } + +fn bar() { + foo(); +} +``` diff --git a/src/doc/style-guide/src/types.md b/src/doc/style-guide/src/types.md new file mode 100644 index 000000000..25861ddab --- /dev/null +++ b/src/doc/style-guide/src/types.md @@ -0,0 +1,58 @@ +## Types and Bounds + +### Single line formatting + +* `[T]` no spaces +* `[T; expr]`, e.g., `[u32; 42]`, `[Vec<Foo>; 10 * 2 + foo()]` (space after colon, no spaces around square brackets) +* `*const T`, `*mut T` (no space after `*`, space before type) +* `&'a T`, `&T`, `&'a mut T`, `&mut T` (no space after `&`, single spaces separating other words) +* `unsafe extern "C" fn<'a, 'b, 'c>(T, U, V) -> W` or `fn()` (single spaces around keyowrds and sigils, and after commas, no trailing commas, no spaces around brackets) +* `!` should be treated like any other type name, `Name` +* `(A, B, C, D)` (spaces after commas, no spaces around parens, no trailing comma unless it is a one-tuple) +* `<Baz<T> as SomeTrait>::Foo::Bar` or `Foo::Bar` or `::Foo::Bar` (no spaces around `::` or angle brackets, single spaces around `as`) +* `Foo::Bar<T, U, V>` (spaces after commas, no trailing comma, no spaces around angle brackets) +* `T + T + T` (single spaces between types, and `+`). +* `impl T + T + T` (single spaces between keyword, types, and `+`). + +Parentheses used in types should not be surrounded by whitespace, e.g., `(Foo)` + + +### Line breaks + +Avoid breaking lines in types where possible. Prefer breaking at outermost scope, e.g., prefer + +```rust +Foo< + Bar, + Baz<Type1, Type2>, +> +``` + +to + +```rust +Foo<Bar, Baz< + Type1, + Type2, +>> +``` + +`[T; expr]` may be broken after the `;` if necessary. + +Function types may be broken following the rules for function declarations. + +Generic types may be broken following the rules for generics. + +Types with `+` may be broken after any `+` using block indent and breaking before the `+`. When breaking such a type, all `+`s should be line broken, e.g., + +```rust +impl Clone + + Copy + + Debug + +Box< + Clone + + Copy + + Debug +> +``` diff --git a/src/doc/unstable-book/src/compiler-flags/dylib-lto.md b/src/doc/unstable-book/src/compiler-flags/dylib-lto.md new file mode 100644 index 000000000..f69ea334f --- /dev/null +++ b/src/doc/unstable-book/src/compiler-flags/dylib-lto.md @@ -0,0 +1,4 @@ +## `dylib-lto` + +This option enables using LTO for the `dylib` crate type. This is currently only used for compiling +`rustc` itself (more specifically, the `librustc_driver` dylib). diff --git a/src/doc/unstable-book/src/compiler-flags/self-profile-events.md b/src/doc/unstable-book/src/compiler-flags/self-profile-events.md index 3ce18743b..3e644f786 100644 --- a/src/doc/unstable-book/src/compiler-flags/self-profile-events.md +++ b/src/doc/unstable-book/src/compiler-flags/self-profile-events.md @@ -41,7 +41,7 @@ $ rustc -Zself-profile -Zself-profile-events=default,args - `llvm` - Adds tracing information about LLVM passes and codegeneration. - - Disabled by default because this only works when `-Znew-llvm-pass-manager` is enabled. + - Disabled by default because this significantly increases the trace file size. ## Event synonyms diff --git a/src/doc/unstable-book/src/language-features/arbitrary-enum-discriminant.md b/src/doc/unstable-book/src/language-features/arbitrary-enum-discriminant.md deleted file mode 100644 index e0bb78227..000000000 --- a/src/doc/unstable-book/src/language-features/arbitrary-enum-discriminant.md +++ /dev/null @@ -1,37 +0,0 @@ -# `arbitrary_enum_discriminant` - -The tracking issue for this feature is: [#60553] - -[#60553]: https://github.com/rust-lang/rust/issues/60553 - ------------------------- - -The `arbitrary_enum_discriminant` feature permits tuple-like and -struct-like enum variants with `#[repr(<int-type>)]` to have explicit discriminants. - -## Examples - -```rust -#![feature(arbitrary_enum_discriminant)] - -#[allow(dead_code)] -#[repr(u8)] -enum Enum { - Unit = 3, - Tuple(u16) = 2, - Struct { - a: u8, - b: u16, - } = 1, -} - -impl Enum { - fn tag(&self) -> u8 { - unsafe { *(self as *const Self as *const u8) } - } -} - -assert_eq!(3, Enum::Unit.tag()); -assert_eq!(2, Enum::Tuple(5).tag()); -assert_eq!(1, Enum::Struct{a: 7, b: 11}.tag()); -``` diff --git a/src/doc/unstable-book/src/language-features/asm-sym.md b/src/doc/unstable-book/src/language-features/asm-sym.md deleted file mode 100644 index 103d91caf..000000000 --- a/src/doc/unstable-book/src/language-features/asm-sym.md +++ /dev/null @@ -1,13 +0,0 @@ -# `asm_sym` - -The tracking issue for this feature is: [#93333] - -[#93333]: https://github.com/rust-lang/rust/issues/93333 - ------------------------- - -This feature adds a `sym <path>` operand type to `asm!` and `global_asm!`. -- `<path>` must refer to a `fn` or `static`. -- A mangled symbol name referring to the item is substituted into the asm template string. -- The substituted string does not include any modifiers (e.g. GOT, PLT, relocations, etc). -- `<path>` is allowed to point to a `#[thread_local]` static, in which case the asm code can combine the symbol with relocations (e.g. `@plt`, `@TPOFF`) to read from thread-local data. diff --git a/src/doc/unstable-book/src/language-features/half-open-range-patterns-in-slices.md b/src/doc/unstable-book/src/language-features/half-open-range-patterns-in-slices.md new file mode 100644 index 000000000..56a1a97df --- /dev/null +++ b/src/doc/unstable-book/src/language-features/half-open-range-patterns-in-slices.md @@ -0,0 +1,30 @@ +# `half_open_range_patterns_in_slices` + +The tracking issue for this feature is: [#67264] +It is part of the `exclusive_range_pattern` feature, +tracked at [#37854]. + +[#67264]: https://github.com/rust-lang/rust/issues/67264 +[#37854]: https://github.com/rust-lang/rust/issues/37854 +----- + +This feature allow using top-level half-open range patterns in slices. + +```rust +#![feature(half_open_range_patterns_in_slices)] +#![feature(exclusive_range_pattern)] + +fn main() { + let xs = [13, 1, 5, 2, 3, 1, 21, 8]; + let [a @ 3.., b @ ..3, c @ 4..6, ..] = xs else { return; }; +} +``` + +Note that this feature is not required if the patterns are wrapped between parenthesis. + +```rust +fn main() { + let xs = [13, 1]; + let [(a @ 3..), c] = xs else { return; }; +} +``` diff --git a/src/doc/unstable-book/src/language-features/half-open-range-patterns.md b/src/doc/unstable-book/src/language-features/half-open-range-patterns.md deleted file mode 100644 index 3b16dd049..000000000 --- a/src/doc/unstable-book/src/language-features/half-open-range-patterns.md +++ /dev/null @@ -1,27 +0,0 @@ -# `half_open_range_patterns` - -The tracking issue for this feature is: [#67264] -It is part of the `#![exclusive_range_pattern]` feature, -tracked at [#37854]. - -[#67264]: https://github.com/rust-lang/rust/issues/67264 -[#37854]: https://github.com/rust-lang/rust/issues/37854 ------ - -The `half_open_range_patterns` feature allows RangeTo patterns -(`..10`) to be used in appropriate pattern matching contexts. -This requires also enabling the `exclusive_range_pattern` feature. - -It also enabled RangeFrom patterns but that has since been -stabilized. - -```rust -#![feature(half_open_range_patterns)] -#![feature(exclusive_range_pattern)] - let x = 5; - match x { - ..0 => println!("negative!"), // "RangeTo" pattern. Unstable. - 0 => println!("zero!"), - 1.. => println!("positive!"), // "RangeFrom" pattern. Stable. - } -``` diff --git a/src/doc/unstable-book/src/language-features/unix-sigpipe.md b/src/doc/unstable-book/src/language-features/unix-sigpipe.md index aa39b6eb2..7ed6a7de8 100644 --- a/src/doc/unstable-book/src/language-features/unix-sigpipe.md +++ b/src/doc/unstable-book/src/language-features/unix-sigpipe.md @@ -36,7 +36,7 @@ hello world Set the `SIGPIPE` handler to `SIG_IGN` before invoking `fn main()`. This will result in `ErrorKind::BrokenPipe` errors if you program tries to write to a closed pipe. This is normally what you want if you for example write socket servers, socket clients, or pipe peers. -This is what libstd has done by default since 2014. Omitting `#[unix_sigpipe = "..."]` is the same as having `#[unix_sigpipe = "sig_ign"]`. +This is what libstd has done by default since 2014. (However, see the note on child processes below.) ### Example @@ -52,3 +52,11 @@ hello world thread 'main' panicked at 'failed printing to stdout: Broken pipe (os error 32)', library/std/src/io/stdio.rs:1016:9 note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace ``` + +### Note on child processes + +When spawning child processes, the legacy Rust behavior if `#[unix_sigpipe]` is not specified is to +reset `SIGPIPE` to `SIG_DFL`. + +If `#[unix_sigpipe = "..."]` is specified, no matter what its value is, the signal disposition of +`SIGPIPE` is no longer reset. This means that the child inherits the parent's `SIGPIPE` behavior. |
