rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-12-22 06:47:49 +02:00
Code Issues Releases Activity

Format all Markdown files with dprint (#1157)

Browse Source 
This is the result of running `dprint fmt` after removing `src/` from
the list of excluded directories.

This also reformats the Rust code: we might want to tweak this a bit in
the future since some of the changes removes the hand-formatting. Of
course, this formatting can be seen as a mis-feature, so maybe this is
good overall.

Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged
after this, meaning that all existing translations remain valid! A few
messages were changed because of stray whitespace characters:

     msgid ""
     "Slices always borrow from another object. In this example, `a` has to remain "
    -"'alive' (in scope) for at least as long as our slice. "
    +"'alive' (in scope) for at least as long as our slice."
     msgstr ""

The formatting is enforced in CI and we will have to see how annoying
this is in practice for the many contributors. If it becomes annoying,
we should look into fixing dprint/check#11 so that `dprint` can annotate
the lines that need fixing directly, then I think we can consider more
strict formatting checks.

I added more customization to `rustfmt.toml`. This is to better emulate
the dense style used in the course:

- `max_width = 85` allows lines to take up the full width available in
our code blocks (when taking margins and the line numbers into account).
- `wrap_comments = true` ensures that we don't show very long comments
in the code examples. I edited some comments to shorten them and avoid
unnecessary line breaks — please trim other unnecessarily long comments
when you see them! Remember we're writing code for slides 😄
- `use_small_heuristics = "Max"` allows for things like struct literals
and if-statements to take up the full line width configured above.

The formatting settings apply to all our Rust code right now — I think
we could improve this with https://github.com/dprint/dprint/issues/711
which lets us add per-directory `dprint` configuration files. However,
the `inherit: true` setting is not yet implemented (as far as I can
tell), so a nested configuration file will have to copy most or all of
the top-level file.
This commit is contained in:
Martin Geisler
2023-12-31 00:15:07 +01:00
committed by GitHub
parent f43e72e0ad
commit c9f66fd425
302 changed files with 3067 additions and 2622 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
src/hello-world/benefits.md
View File

@@ -6,7 +6,8 @@ minutes: 3
Some unique selling points of Rust:
- _Compile time memory safety_ - whole classes of memory bugs are prevented at compile time
- _Compile time memory safety_ - whole classes of memory bugs are prevented at
compile time
- No uninitialized variables.
- No double-frees.
- No use-after-free.
@@ -39,14 +40,14 @@ later.
Make sure to ask the class which languages they have experience with. Depending
on the answer you can highlight different features of Rust:
* Experience with C or C++: Rust eliminates a whole class of _runtime errors_
- Experience with C or C++: Rust eliminates a whole class of _runtime errors_
via the borrow checker. You get performance like in C and C++, but you don't
have the memory unsafety issues. In addition, you get a modern language with
constructs like pattern matching and built-in dependency management.
* Experience with Java, Go, Python, JavaScript...: You get the same memory safety
as in those languages, plus a similar high-level language feeling. In addition
you get fast and predictable performance like C and C++ (no garbage collector)
as well as access to low-level hardware (should you need it)
- Experience with Java, Go, Python, JavaScript...: You get the same memory
safety as in those languages, plus a similar high-level language feeling. In
addition you get fast and predictable performance like C and C++ (no garbage
collector) as well as access to low-level hardware (should you need it)
</details>

27
src/hello-world/hello-world.md
View File

@@ -15,11 +15,11 @@ fn main() {
What you see:
* Functions are introduced with `fn`.
* Blocks are delimited by curly braces like in C and C++.
* The `main` function is the entry point of the program.
* Rust has hygienic macros, `println!` is an example of this.
* Rust strings are UTF-8 encoded and can contain any Unicode character.
- Functions are introduced with `fn`.
- Blocks are delimited by curly braces like in C and C++.
- The `main` function is the entry point of the program.
- Rust has hygienic macros, `println!` is an example of this.
- Rust strings are UTF-8 encoded and can contain any Unicode character.
<details>
@@ -28,20 +28,21 @@ a ton of it over the next four days so we start small with something familiar.
Key points:
* Rust is very much like other languages in the C/C++/Java tradition. It is
imperative and it doesn't try to reinvent things unless
absolutely necessary.
- Rust is very much like other languages in the C/C++/Java tradition. It is
imperative and it doesn't try to reinvent things unless absolutely necessary.
* Rust is modern with full support for things like Unicode.
- Rust is modern with full support for things like Unicode.
* Rust uses macros for situations where you want to have a variable number of
- Rust uses macros for situations where you want to have a variable number of
arguments (no function [overloading](basic-syntax/functions-interlude.md)).
* Macros being 'hygienic' means they don't accidentally capture identifiers from
- Macros being 'hygienic' means they don't accidentally capture identifiers from
the scope they are used in. Rust macros are actually only
[partially hygienic](https://veykril.github.io/tlborm/decl-macros/minutiae/hygiene.html).
* Rust is multi-paradigm. For example, it has powerful [object-oriented programming features](https://doc.rust-lang.org/book/ch17-00-oop.html),
and, while it is not a functional language, it includes a range of [functional concepts](https://doc.rust-lang.org/book/ch13-00-functional-features.html).
- Rust is multi-paradigm. For example, it has powerful
[object-oriented programming features](https://doc.rust-lang.org/book/ch17-00-oop.html),
and, while it is not a functional language, it includes a range of
[functional concepts](https://doc.rust-lang.org/book/ch13-00-functional-features.html).
</details>

8
src/hello-world/playground.md
View File

@@ -6,15 +6,15 @@ minutes: 2
The [Rust Playground](https://play.rust-lang.org/) provides an easy way to run
short Rust programs, and is the basis for the examples and exercises in this
course. Try running the "hello-world" program it starts with. It comes with a
course. Try running the "hello-world" program it starts with. It comes with a
few handy features:
- Under "Tools", use the `rustfmt` option to format your code in the "standard"
way.
- Rust has two main "profiles" for generating code: Debug (extra runtime
checks, less optimization) and Release (fewer runtime checks, lots of
optimization). These are accessible under "Debug" at the top.
- Rust has two main "profiles" for generating code: Debug (extra runtime checks,
less optimization) and Release (fewer runtime checks, lots of optimization).
These are accessible under "Debug" at the top.
- If you're interested, use "ASM" under "..." to see the generated assembly
code.

35
src/hello-world/what-is-rust.md
View File

@@ -6,29 +6,28 @@ minutes: 10
Rust is a new programming language which had its [1.0 release in 2015][1]:
* Rust is a statically compiled language in a similar role as C++
* `rustc` uses LLVM as its backend.
* Rust supports many [platforms and
architectures](https://doc.rust-lang.org/nightly/rustc/platform-support.html):
* x86, ARM, WebAssembly, ...
* Linux, Mac, Windows, ...
* Rust is used for a wide range of devices:
* firmware and boot loaders,
* smart displays,
* mobile phones,
* desktops,
* servers.
- Rust is a statically compiled language in a similar role as C++
- `rustc` uses LLVM as its backend.
- Rust supports many
[platforms and architectures](https://doc.rust-lang.org/nightly/rustc/platform-support.html):
- x86, ARM, WebAssembly, ...
- Linux, Mac, Windows, ...
- Rust is used for a wide range of devices:
- firmware and boot loaders,
- smart displays,
- mobile phones,
- desktops,
- servers.
<details>
Rust fits in the same area as C++:
* High flexibility.
* High level of control.
* Can be scaled down to very constrained devices such as microcontrollers.
* Has no runtime or garbage collection.
* Focuses on reliability and safety without sacrificing performance.
- High flexibility.
- High level of control.
- Can be scaled down to very constrained devices such as microcontrollers.
- Has no runtime or garbage collection.
- Focuses on reliability and safety without sacrificing performance.
</details>