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.
The old version switched in between examples from the value `5i` to `"Hello"` and back.
Additionally, the code generated by `rustc print.rs --pretty=expanded` is not as verbose anymore.
Currently, the Guide says tuples "are only equivalent if the arity, types, and values are all identical", before presenting an example that uses `==` to compare two tuples whose arity and contained types match. This is misleading, because it implies that `==` can dynamically check whether two tuples have the same arity and contained types, whereas trying to do this would lead to a compiler error.
I tried to avoid destroying the flow of this section, but I'm not sure if I've been successful.
The old version switched in between examples from the value `5i` to `"Hello"`
and back. Additionally, the code generated by `rustc print.rs
--pretty=expanded` is not as verbose anymore.
Hi,
These are a few small edits to the Guide that I made while reading online. Really well done and approachable.
I have a few questions below, but I don't know if this is the proper place to ask them, so feel free to ignore the below.
1. Trailing commas seem to be a convention in Rust and are used quite a bit throughout the Guide, but are never explicitly mentioned. Maybe adding a short mention about them when they first appear in the Structs section might be helpful to those who are unfamiliar with or don't use them in other languages.
2. In the Iterators section, there is a block of code like this:
```rust
let mut range = range(0i, 10i);
loop {
match range.next() {
Some(x) => {
println!("{}", x);
} // no comma needed?
None => { break }
}
}
```
My inclination would be to put a comma where the comment is to separate the two arms to get this to compile, but it runs fine either way. Is there a convention on commas for scenarios like this where each arm is enclosed in `{}`?
All the best,
O-I
Oddly (to me), this code runs fine without the comma separating the `Some` and `None` arms of the `match` construct. It seems like Rust doesn't require you to separate arms with commas if all the expressions are enclosed in braces.
Mention that using `pub` is called exporting.
Remove that `use` is called re-exporting, because `pub use` should be
called re-exporting. The guide currently doesn't cover `pub use`.
It's a rather useful syntax, and non-obvious.
A friend of mine is learning Rust and was trying to find a way to easily do such an initialization — he couldn't find it in the guide and was pretty surprised when I showed him. Looks like something that should be mentioned.
r? @steveklabnik
See: http://doc.rust-lang.org/std/from_str/trait.FromStr.html
```
let input_num = from_str::<Option<uint>>("5");
```
```
<anon>:2:21: 2:45 error: failed to find an implementation of trait std::from_str::FromStr for core::option::Option<uint>
<anon>:2 let input_num = from_str::<Option<uint>>("5");
^~~~~~~~~~~~~~~~~~~~~~~~
```
This closes#17260. The guide references the old install location for
the windows rust install before it was split into 64bit and 32bit
installers. This adds a link to each binary.
The Guide isn't 100% perfect, but it's basically complete. It's
certainly better than the tutorial is. Time to start pointing more
people its way.
I also just made it consistent to call all things 'guides' rather than
tutorials.
Fixes#9874. This is the big one.
And two bugs that just go away.
Fixes#14503.
Fixes#15009.
This part can get _really_ confusing, and we want to make sure that
people succeed in the guide. I plan on making a module guide in the
future to replace the information here.
We have to specify the module and the function name in the example where
the module shares a crate with the executable as well, so remove the
redundant (and potentially confusing) mention.
We have to specify the module and the function name in the example where
the module shares a crate with the executable as well, so remove the
redundant (and potentially confusing) mention.
Also:
* Remove unseeming repetition.
* By now, the reader has already heard that Rust is safe by default, so
reduce the overlong sentence, making it easier to read.
