rewrite part of the tutorial #10690
rewrite part of the tutorial #10690
Conversation
|
This can be expanded by going into detail about how to mutate the list in-place by using a mutable reference, including an introduction to swaps. It can then introduce named lifetimes by demonstrating searching through the list and returning a reference to the value. It could introduce traits by implementing I think this is a much better way to teach the language than how we're doing it right now. |
| ~~~ {.xfail-test} | ||
| // error: illegal recursive enum type; wrap the inner value in a box to make it representable | ||
| enum List { | ||
| Cons(int, List), |
There was a problem hiding this comment.
Is it worth not using int? (because of e.g. #9940)
There was a problem hiding this comment.
(Also, it might be "smoother" to mention that we're going to be storing ints in the text.)
|
This looks really good to me. |
|
I like the idea of the tutorial waking through implementing a structure or a small project, but it seems a little out of place as written. There's lots of general "these are rust concepts" sections, and then all of a sudden there's a section on implementing a linked list. As @huonw pointed out, the linked-list idea also just kinda falls out of scope suddenly without much closure in what just happened. I have a feeling that @brson may want to weigh in on this, but I would be wary on adding such a sudden interjection of implementing a linked list without much of an intro or conclusion. |
|
I think the current design of a section dedicated to every major language feature with isolated examples is material for the manual rather than a tutorial. It falls out of scope suddenly because I haven't dedicated very much time to it yet as I'm not sure it will be accepted. I do plan on extending it to be many times larger than it is at the moment and covering generics, iterators, references and other features this way. My view of what a tutorial should be is a concise overview of the language and then jumping right in to implementing something simple like a linked list. It can then continue on with more complex examples like an AI for a simple board game. It should cover all the high-level semantics of each language feature this way but it doesn't need to get bogged down in the details as we have a manual. |
|
@brson Opinions? |
|
|
||
| An *owned box* (`~`) uses a dynamic memory allocation to provide the invariant | ||
| of always being the size of a pointer, regardless of the contained type. This | ||
| can be leverage to create a valid `List` definition: |
There was a problem hiding this comment.
Though the motivation is good, this seems like a fairly round-about way to describe boxes. It sort of claims that boxes exist to create types that are pointer sized, which is a fairly novel way to think about boxes. It also is a bit of a tautology, paraphrasing "boxes use allocation to be the size of a pointer", since "box" and "pointer" are essentially synonyms, this is saying "boxes use allocation and are the size of boxes".
There was a problem hiding this comment.
Is this the first mention of "pointers"?
|
I agree with this direction, but also agree with others that this style needs to be carried over throughout the tutorial. What are your plans to expand this? |
|
Well, I see that you outlined some of your plans earlier. Let me think a sec. |
| > ***Note:*** The `Option` type is an enum representing an *optional* value. | ||
| > It's comparable to a nullable pointer in many other languages, but stores the | ||
| > contained value unboxed. | ||
| assert_eq!(std::mem::size_of::<Foo>(), std::mem::size_of::<u32>() * 4); |
There was a problem hiding this comment.
I think the std::mem:: is obscuring these examples, they'd be clearer as
use std::mem::size_of; // import the size_of function
assert_eq!(size_of::<Foo>(), size_of::<u32>() * 4)
...I think.
There was a problem hiding this comment.
use statements don't seem to be covered at all :(
This begins a rewrite of some sections the tutorial as an introduction to concepts through the implementation of a simple data structure. I think this would be a good way to introduce references, traits and many other concepts too. For example, the section introducing alternatives to ownership can demonstrate a persistent list.
This begins a rewrite of some sections the tutorial as an introduction to concepts through the implementation of a simple data structure. I think this would be a good way to introduce references, generics, traits and many other concepts too. For example, the section introducing alternatives to ownership can demonstrate a persistent list.
| ~~~ | ||
|
|
||
| This error message is related to Rust's precise control over memory layout, and | ||
| solving it will require introducing the concept of *boxing*. |
There was a problem hiding this comment.
Thanks for adding this example. This is the exact issue I ran into when I first played around with Rust. Having this as part of the tutorial is certainly going to help a lot of people.
…ts, r=llogiq Document that `cargo clippy --fix` implies `--all-targets` In [`cargo fix`'s documentation](https://doc.rust-lang.org/cargo/commands/cargo-fix.html) they indicate that `fix` implies `--all-targets` if no target is supplied. As Clippy uses Cargo under the hood, this also applies to Clippy, but we didn't document that behaviour. This PR changes that Fixes rust-lang#10690 changelog: Add to documentation that `--fix` implies `--all-targets`
This begins a rewrite of some sections the tutorial as an introduction
to concepts through the implementation of a simple data structure. I
think this would be a good way to introduce references, generics, traits
and many other concepts too. For example, the section introducing
alternatives to ownership can demonstrate a persistent list.