Clarify the semantics of enum discriminants
cf. https://doc.rust-lang.org/error-index.html#E0082
> The default type for enum discriminants is isize, but it can be adjusted by adding the repr attribute to the enum declaration.
It would be great if anyone could check my English.
This PR implements [RFC 1192](https://github.com/rust-lang/rfcs/blob/master/text/1192-inclusive-ranges.md), which is triple-dot syntax for inclusive range expressions. The new stuff is behind two feature gates (one for the syntax and one for the std::ops types). This replaces the deprecated functionality in std::iter. Along the way I simplified the desugaring for all ranges.
This is my first contribution to rust which changes more than one character outside of a test or comment, so please review carefully! Some of the individual commit messages have more of my notes. Also thanks for putting up with my dumb questions in #rust-internals.
- For implementing `std::ops::RangeInclusive`, I took @Stebalien's suggestion from https://github.com/rust-lang/rfcs/pull/1192#issuecomment-137864421. It seemed to me to make the implementation easier and increase type safety. If that stands, the RFC should be amended to avoid confusion.
- I also kind of like @glaebhoerl's [idea](https://github.com/rust-lang/rfcs/pull/1254#issuecomment-147815299), which is unified inclusive/exclusive range syntax something like `x>..=y`. We can experiment with this while everything is behind a feature gate.
- There are a couple of FIXMEs left (see the last commit). I didn't know what to do about `RangeArgument` and I haven't added `Index` impls yet. Those should be discussed/finished before merging.
cc @Gankro since you [complained](https://www.reddit.com/r/rust/comments/3xkfro/what_happened_to_inclusive_ranges/cy5j0yq)
cc #27777#30877rust-lang/rust#1192rust-lang/rfcs#1254
relevant to #28237 (tracking issue)
Vectors come up in sections dedicated to ownership with the assumption that we know something about it but we haven't seen it yet. On the other hand, you need not know anything about ownership or lifetimes to understand the basics of vectors covered in the vector section of the book. Additionally, by moving it where it is there is a natural progression from loops to an iterative type which discusses for loops. This kind of interaction is generally better for learning.
I would like to have moved the struct section as well but I'm less confident about how to handle it since the ownership sections discuss structs and the structs section talks about mutable borrow.
This commit implements documentation generation of the nomicon, the book, the
style guide, and the standalone docs. New steps were added for each one as well
as appropriate makefile targets for each one as well.
This commit is the result of the FCPs ending for the 1.8 release cycle for both
the libs and the lang suteams. The full list of changes are:
Stabilized
* `braced_empty_structs`
* `augmented_assignments`
* `str::encode_utf16` - renamed from `utf16_units`
* `str::EncodeUtf16` - renamed from `Utf16Units`
* `Ref::map`
* `RefMut::map`
* `ptr::drop_in_place`
* `time::Instant`
* `time::SystemTime`
* `{Instant,SystemTime}::now`
* `{Instant,SystemTime}::duration_since` - renamed from `duration_from_earlier`
* `{Instant,SystemTime}::elapsed`
* Various `Add`/`Sub` impls for `Time` and `SystemTime`
* `SystemTimeError`
* `SystemTimeError::duration`
* Various impls for `SystemTimeError`
* `UNIX_EPOCH`
* `ops::{Add,Sub,Mul,Div,Rem,BitAnd,BitOr,BitXor,Shl,Shr}Assign`
Deprecated
* Scoped TLS (the `scoped_thread_local!` macro)
* `Ref::filter_map`
* `RefMut::filter_map`
* `RwLockReadGuard::map`
* `RwLockWriteGuard::map`
* `Condvar::wait_timeout_with`
Closes#27714Closes#27715Closes#27746Closes#27748Closes#27908Closes#29866
Refinement of paragraph referenced by [this issue](https://github.com/rust-lang/rust/issues/31927).
The paragraph in question had been adjusted already, but I've made some further clarifications which should help with readability and not leave the reader any `dangling pointers`.
As a Rust newbie, I found the book's explanation for why the `filter` closure gets a reference very confusing, and tried to figure out why `filter` is somehow less consumptive than `map` -- but it isn't; that's controlled by `iter`/`into_iter`. I flailed around for a while until @habnabit explained it to me, and in retrospect it is quite obvious :-)
Reference implied that use declarations may appear *only* at the top of blocks and modules, but it is not the case, and the following is valid:
```Rust
fn foo() {
let x = 92;
use baz::bar;
}
```
r? @steveklabnik
This commit implements documentation generation of the nomicon, the book, the
style guide, and the standalone docs. New steps were added for each one as well
as appropriate makefile targets for each one as well.
I feel sorry for bothering you with such a literally one character changes. If it is counter productive feel free to point it out in the comments, that would be totally understandable. I could try to pack such a changes together in one PR to make them less distractive.
r? @steveklabnik
Not everyone knows this convention. We could just rename the variables in the
example, but since this notation is commonly used it's a good opportunity to
introduce it.
r? @steveklabnik
This is a minor change. Please see title. IMO this is important since this is the first instance when we talk about allocating a vector. Not saying that it is allocated on the stack here leaves room for speculation and this might put off some people (they might not even read the later sections which go into more detail about this).
The scope of these refactorings is a little bit bigger than the title implies. See each commit for details.
I’m submitting this for nitpicking now (the first 4 commits), because I feel the basic idea/implementation is sound and should work. I will eventually expand this PR to cover the translator changes necessary for all this to work (+ tests), ~~and perhaps implement a dynamic dropping scheme while I’m at it as well.~~
r? @nikomatsakis
Currently the `mipsel-unknown-linux-gnu` target doesn't actually set the
`target_arch` value to `mipsel` but it rather uses `mips`. Alternatively the
`powerpc64le` target does indeed set the `target_arch` as `powerpc64le`,
causing a bit of inconsistency between theset two.
As these are just the same instance of one instruction set, let's use
`target_endian` to switch between them and only set the `target_arch` as one
value. This should cut down on the number of `#[cfg]` annotations necessary and
all around be a little more ergonomic.
Some other shufflings as well:
* Three powerpc triples for Linux have been added recently
* An armv7 linux triple was added recently
* The 64-bit Solaris triple is now mentioned in tier 3
We are currently now also building nightlies for iOS, powerpc triples, and
armv7, but there hasn't been much vetting of the triples themselves so I've left
them in tier 3 for now.
Fixes#31334
This is just a quicker fix for this issue; since I'm working on the next draft of the book, I don't want to put a huuuge amount of work into improving it here.
Updated documentation to clarify the difference between `and_then` and `map`. This also explains why we need `and_then` in addition to `map`. Please look at the diff for more information.
r? @alexcrichton
Currently the `mipsel-unknown-linux-gnu` target doesn't actually set the
`target_arch` value to `mipsel` but it rather uses `mips`. Alternatively the
`powerpc64le` target does indeed set the `target_arch` as `powerpc64le`,
causing a bit of inconsistency between theset two.
As these are just the same instance of one instruction set, let's use
`target_endian` to switch between them and only set the `target_arch` as one
value. This should cut down on the number of `#[cfg]` annotations necessary and
all around be a little more ergonomic.
Some other shufflings as well:
* Three powerpc triples for Linux have been added recently
* An armv7 linux triple was added recently
* The 64-bit Solaris triple is now mentioned in tier 3
We are currently now also building nightlies for iOS, powerpc triples, and
armv7, but there hasn't been much vetting of the triples themselves so I've left
them in tier 3 for now.
Block comments don't have to be in the format `/*! ... !*/`
in order to be read as doc comments about the parent block.
The format `/*! ... */` is enough.
Block comments don't have to be in the format `/*! ... !*/`
in order to be read as doc comments about the parent block.
The format `/*! ... */` is enough.
When I read the book, the following sentence of the reference documentation helped me greatly to understand slices:
"Slices are a view into a block of memory represented as a pointer and a length."
In this commit, I tried to integrate the gist of that into the slice section inside of "primitive-types.md". I am not a native speaker, so feel very free to improve the wording.
r? @steveklabnik
Fix spacing style of `T: Bound` in docs
The space between `T` and `Bound` is the typical style used in code and
produced by rustdoc's rendering. Fixed first in Reflect's docs and then
I fixed all occurrences in docs I could find.
The space between `T` and `Bound` is the typical style used in code and
produced by rustdoc's rendering. Fixed first in Reflect's docs and then
I fixed all occurrences in docs I could find.
* Moved semicolon to the right place in the `let` statement in the ZST section.
* Fixed the missing ZST additions for `RawValIter<T>` from this section in the final code section.
Ref issue [30825](https://github.com/rust-lang/rust/issues/30825)
This commit should suffice to add a concise introduction to the concept of crates.
My only worry, is that it is maybe too concise; but, the book seems to be written with the understanding that the new Rust user is coming from another language, and so will understand what a Library or Code Package is.
This feature is partially stabilized, so describe each part in the appropriate place.
r? @alexcrichton @brson
It would be nice to backport this to beta, since this is the first release where this is true. I try really hard to not do doc backports, but this isn't very large, and might be worth making an exception, I dunno.
When I read the book, the following sentence of the reference documentation helped me greatly to understand slices:
"Slices are a view into a block of memory represented as a pointer and a length."
In this commit, I tried to integrate the gist of that into the slice section inside of "primitive-types.md".
len needs to be prefixed by self for this to work. That is something which trips me up all the time. It's reassuring to see that happening to seasoned Rust programmers.
I'm working my way through TRPL beginning at "Syntax and Semantics" as was recommended in a previous version.
I'm expecting the chapter to incrementally build up my knowledge of the language section by section, assuming no prior Rust experience. So it was a bit of a speed-bump to encounter references and the vector type in a code example long before they had been defined and explained.
Another commit in this PR tries to make consistent what is a "chapter" of TRPL versus a "section." Just a nit-pick, but not thinking about that stuff keeps my focus on the important material.
My background: Python programmer since ~2000, with moderate exposure to C, C++, assembly, operating systems, and system architecture in university several years ago.
For your kind consideration, feel welcome to use or drop or rework any part of this.
In a straight-through read of "Syntax and Semantics," the concept of a
"reference" is used here before it is explained. Mention that and link to
the section explaining references.
In a straight-through read of "Syntax and Semantics," the first time we
meet a generic, and the first time we meet a vector, is when a Vec<T> shows
up in this example. I'm not sure that I could argue that the whole section
should appear later in the book than the ones on vectors and generics, so
instead just give the reader a brief introduction to both and a promise to
follow up later.
heap::deallocate expects a *mut u8, but here a *mut T is given as the type of the argument. This would not compile. The final code is correct, however.
Rust differs in that behavior from C: In C, the newline escapes are resolved
before anything else, and in Rust this depends on whether the backslash is
escaped itself.
A difference can be observed in the following two programs:
```c
int main()
{
printf("\\
n\n");
return 0;
}
```
```rust
fn main() {
println!("\\
n");
}
```
The first program prints two newlines, the second one prints a backslash, a
newline, the latin character n and a final newline.
I noticed the alignment was off in the error handling part of the book. This was caused because two tabs had crept into the file. I have changed these for spaces.
Rust differs in that behavior from C: In C, the newline escapes are resolved
before anything else, and in Rust this depends on whether the backslash is
escaped itself.
A difference can be observed in the following two programs:
```c
#include <stdio.h>
int main()
{
printf("\\
n\n");
return 0;
}
```
```rust
fn main() {
println!("\\
n");
}
```
The first program prints two newlines, the second one prints a backslash, a
newline, the latin character n and a final newline.
Some history:
While getting Rust to 1.0, it was a struggle to keep the book in a
working state. I had always wanted a certain kind of TOC, but couldn't
quite get it there.
At the 11th hour, I wrote up "Rust inside other langauges" and "Dining
Philosophers" in an attempt to get the book in the direction I wanted to
go. They were fine, but not my best work. I wanted to further expand
this section, but it's just never going to end up happening. We're doing
the second draft of the book now, and these sections are basically gone
already.
Here's the issues with these two sections, and removing them just fixes
it all:
// Philosophers
There was always controversy over which ones were chosen, and why. This
is kind of a perpetual bikeshed, but it comes up every once in a while.
The implementation was originally supposed to show off channels, but
never did, due to time constraints. Months later, I still haven't
re-written it to use them.
People get different results and assume that means they're wrong, rather
than the non-determinism inherent in concurrency. Platform differences
aggrivate this, as does the exact amount of sleeping and printing.
// Rust Inside Other Languages
This section is wonderful, and shows off a strength of Rust. However,
it's not clear what qualifies a language to be in this section. And I'm
not sure how tracking a ton of other languages is gonna work, into the
future; we can't test _anything_ in this section, so it's prone to
bitrot.
By removing this section, and making the Guessing Game an initial
tutorial, we will move this version of the book closer to the future
version, and just eliminate all of these questions.
In addition, this also solves the 'split-brained'-ness of having two
paths, which has endlessly confused people in the past.
I'm sad to see these sections go, but I think it's for the best.
Fixes#30471Fixes#30163Fixes#30162Fixes#25488Fixes#30345Fixes#29590Fixes#28713Fixes#28915
And probably others. This lengthy list alone is enough to show that
these should have been removed.
RIP.
fs::File was being referenced without either calling via std::fs::File or by using File after having used fs::File. Also Path was being referenced without first having used std::path::Path.
Rewrite of a paragraph in in the `match` section.
The colon `:` should be used only when the sentence preceeding it is a
complete sentence. If this is not the case, then a `;` should be used;
this denotes that the following fragment is a part of the previous
fragment.
I got a new bike; it has two wheels. (Similar to I got a new bike, it has two wheels)
The ice cream truck has great flavours; blueberry, blackberry, berryberry.
Writing a complete sentence:
- with a list under it
- You can join two sentences with it: Much like this.
r? @steveklabnik
Some history:
While getting Rust to 1.0, it was a struggle to keep the book in a
working state. I had always wanted a certain kind of TOC, but couldn't
quite get it there.
At the 11th hour, I wrote up "Rust inside other langauges" and "Dining
Philosophers" in an attempt to get the book in the direction I wanted to
go. They were fine, but not my best work. I wanted to further expand
this section, but it's just never going to end up happening. We're doing
the second draft of the book now, and these sections are basically gone
already.
Here's the issues with these two sections, and removing them just fixes
it all:
// Philosophers
There was always controversy over which ones were chosen, and why. This
is kind of a perpetual bikeshed, but it comes up every once in a while.
The implementation was originally supposed to show off channels, but
never did, due to time constraints. Months later, I still haven't
re-written it to use them.
People get different results and assume that means they're wrong, rather
than the non-determinism inherent in concurrency. Platform differences
aggrivate this, as does the exact amount of sleeping and printing.
// Rust Inside Other Languages
This section is wonderful, and shows off a strength of Rust. However,
it's not clear what qualifies a language to be in this section. And I'm
not sure how tracking a ton of other languages is gonna work, into the
future; we can't test _anything_ in this section, so it's prone to
bitrot.
By removing this section, and making the Guessing Game an initial
tutorial, we will move this version of the book closer to the future
version, and just eliminate all of these questions.
In addition, this also solves the 'split-brained'-ness of having two
paths, which has endlessly confused people in the past.
I'm sad to see these sections go, but I think it's for the best.
Fixes#30471Fixes#30163Fixes#30162Fixes#25488Fixes#30345Fixes#28713Fixes#28915
And probably others. This lengthy list alone is enough to show that
these should have been removed.
RIP.
Didn't build/test the change, but if that one-character fix isn't correct, I'll eat my hat. :-) Found this reading the book over the last week or two since Mozlando -- much enjoying the book so far.
book: Some operator fixes for the syntax index
- Correct the names of the comparison traits (PartialOrd)
- Mention only the traits that overload the operator (PartialOrd,
PartialEq), not operator-unrelated traits (Ord, Eq).
- Add `!=` operator.
- Correct the names of the comparison traits (PartialOrd)
- Mention only the traits that overload the operator (PartialOrd,
PartialEq), not operator-unrelated traits (Ord, Eq).
- Add `!=` operator.
The website will [shortly](https://github.com/rust-lang/rust-www/pull/241) provide the main documentation landing page as well as the [FAQ](https://github.com/rust-lang/rust-www/issues/202). All of the content here will be there.
This strips out everything and makes the index *just* an index into the in-tree content. My only real qualm with this is that this will become the content on doc.rust-lang.org (a sweet URL), while the main documentation page will be www.rust-lang.org/documentation.html.
r? @steveklabnik
correcting use of ':' in sentences.
The colon `:` should be used only when the sentence preceeding it is a
complete sentence. If this is not the case, then a `;` should be used;
this denotes that the following fragment is a part of the previous
fragment.
This PR is a rebase of the original PR by @eddyb https://github.com/rust-lang/rust/pull/21836 with some unrebasable parts manually reapplied, feature gate added + type equality restriction added as described below.
This implementation is partial because the type equality restriction is applied to all type ascription expressions and not only those in lvalue contexts. Thus, all difficulties with detection of these contexts and translation of coercions having effect in runtime are avoided.
So, you can't write things with coercions like `let slice = &[1, 2, 3]: &[u8];`. It obviously makes type ascription less useful than it should be, but it's still much more useful than not having type ascription at all.
In particular, things like `let v = something.iter().collect(): Vec<_>;` and `let u = t.into(): U;` work as expected and I'm pretty happy with these improvements alone.
Part of https://github.com/rust-lang/rust/issues/23416
The previous example had no chance of compiling in either form, due to the restrictive follow set for `ty`. This one has the desired behavior: http://is.gd/kYdw4g (well, I don't exactly desire this behavior at all, but it's true at least :p )
The Rustonomicon's Lifetimes chapter uses the idiom "big ask", which is obscure compared to "tall order" (check [Google ngrams](https://books.google.com/ngrams/graph?content=big+ask%2C+tall+order&year_start=1800)). Also, it's easily mistaken for a typo; either "a big task" or "a big thing to ask" could plausibly work there.
r? @steveklabnik
…entation clearer
I could not use colors as suggested for #29854 because Github doesn't support these in markdown, however this solution may be better for color-blind readers.
The Rustonomicon's Lifetimes chapter uses the idiom "big ask", which is obscure compared to "tall order" (check Google ngrams). Also, it's easily mistaken for a typo; either "a big task" or "a big thing to ask" could plausibly work there.
Closes https://github.com/rust-lang/rust/issues/29935
The attributes `deprecated` and `rustc_deprecated` are completely independent in this implementation and it leads to some noticeable code duplication. Representing `deprecated` as
```
Stability {
level: Stable { since: "" },
feature: "",
depr: Some(Deprecation),
}
```
or, contrariwise, splitting rustc_deprecation from stability makes most of the duplication go away.
I can do this refactoring, but before doing it I must be sure, that further divergence of `deprecated` and `rustc_deprecated` is certainly not a goal.
cc @llogiq
The previous example had no chance of compiling in either form, due to the restrictive follow set for `ty`. This one has the desired behavior: http://is.gd/kYdw4g (well, I don't exactly desire this behavior at all, but it's true at least :p )
r? @steveklabnik
Currently neither the API docs nor the book clearly explain that out-of-bounds array indexing causes a panic. Since this is fairly important and seems to surprise a number of new Rust programmers, I think it's worth adding to both places. (But if you think it would be better to put this info in the API docs only, that's fine too.)
Some specific things I'd like feedback on:
* The new text here talks about panicking, which hasn't been formally introduced at this point in chapter 5 (though it has been mentioned in previous sections too).
* Similarly the `Vec::get` example uses `Option<T>` which hasn't been fully introduced yet. Should we leave out this example?
