As a new user, I spent a while confused when flycheck told me the code sample I'd typed in was invalid. I ended up figuring out some of what comes after the code sample more painfully by myself because there was no indication that it was broken in the text beforehand. This one line change makes it clear that the code following it is an experiment that may not work rather than something to assume just works.
This removes some leftover line-numbering cruft from elided error examples and brings some minor clarifications.
I’m not super happy about the ‘we cannot have two mutable pointers that point to the same memory’ wording (to the best of my understanding we can’t even have one mutable and one immutable), but other attempts to word this were derailing the flow a bit too much.
I think it helps to show that the variables introduced in match blocks are indeed independent from the matched variable `x` (especially when `x` is still reachable inside those blocks and might be useful), so this renames them accordingly. Maybe some linter (or language-level warning?) will eventually warn about shadowing `x` in such cases. ;)
I’m not super happy about the matching-on-range example, as it’s too contrived (`e` and `x` are exactly the same here), but I couldn’t come up with something both simple and non-redundant.
https://github.com/rust-lang/rfcs/pull/221
The current terminology of "task failure" often causes problems when
writing or speaking about code. You often want to talk about the
possibility of an operation that returns a Result "failing", but cannot
because of the ambiguity with task failure. Instead, you have to speak
of "the failing case" or "when the operation does not succeed" or other
circumlocutions.
Likewise, we use a "Failure" header in rustdoc to describe when
operations may fail the task, but it would often be helpful to separate
out a section describing the "Err-producing" case.
We have been steadily moving away from task failure and toward Result as
an error-handling mechanism, so we should optimize our terminology
accordingly: Result-producing functions should be easy to describe.
To update your code, rename any call to `fail!` to `panic!` instead.
Assuming you have not created your own macro named `panic!`, this
will work on UNIX based systems:
grep -lZR 'fail!' . | xargs -0 -l sed -i -e 's/fail!/panic!/g'
You can of course also do this by hand.
[breaking-change]
Some minor wording fixes to the Closures chapter; my brain tripped a few times when reading it, so I tried to come up with something a bit smoother. I’m not a native speaker, so please do review this critically.
Explain that Rust has different pointer types because there is a
tradeoff between flexibility and efficiency. Motivate boxes as
fixed-size containers of variable-sized objects. Clarify that Box and Rc
are pointer types that you deref with * just like references. Stick to
explaining the semantics and avoid implementation details. Scope isn't
the most accurate framework to think about deallocation (since you
return boxes and otherwise move values out of scopes); it's more "when
the value is done being used," i.e., lifetime. Provide a connection
between Rust's pointer types by locating them on a flexibiltiy /
performance scale. Explain the compiler can't statically analyze
lifetimes with multiple owners; hence the need for (runtime) reference
counting.
Explain the primary disadvantage of garbage collection is runtime
overhead and unpredictable pauses. Elucidate where the name "race
condition" comes from. Emphasize that Rust can guarantee your code is
free of race conditions and other memory errors, with no runtime
overhead.
cc @steveklabnik
Explain the primary disadvantage of garbage collection is runtime
overhead and unpredictable pauses. Elucidate where the name "race
condition" comes from. Emphasize that Rust can guarantee your code is
free of race conditions and other memory errors, with no runtime
overhead.
The array is the fundamental concept; vectors are growable arrays, and
slices are views into either. Show common array ops up front: length
and iteration. Mention arrays are immutable by default. Highlight
definite initialization and bounds-checking as safety features. Show
that you only need a type suffix on one element of initializers.
Explain that vectors are a value-add library type over arrays, not a
fundamental type; show they have the same "interface." Motivate slices
as efficient views into arrays; explain you can slice vectors, Strings,
&str because they're backed by arrays.
