Steve Klabnik [Mon, 23 Mar 2015 21:05:44 +0000 (17:05 -0400)]
Rollup merge of #23509 - aturon:stab-entry, r=Gankro
This commit marks as `#[stable]` the `Entry` types for the maps provided
by `std`. The main reason these had been left unstable previously was
uncertainty about an eventual trait design, but several plausible
designs have been proposed that all work fine with the current type definitions.
Steve Klabnik [Mon, 23 Mar 2015 21:05:43 +0000 (17:05 -0400)]
Rollup merge of #22954 - ches:docs, r=steveklabnik
Greetings Rustaceans!
I've just been getting acquainted with Rust through the guide. First let me say that it's already in great shape, chapters are kept a good length to be digestible and paced to move the reader along fluidly, so my compliments to contributors!
Along the way I noticed a few minor copy errors, and also a few areas that I thought more subjectively could stand to be improved. My commits here are divided so that minor edits unlikely to be very contentious could be cherry-picked, and then topically on parts that might generate more discussion.
I also have some comments and questions that aren't directly associated with any changes on this branch yet. I'm not sure how you like to triage this sort of thing but I'll present them below and if it's appropriate they could be moved to separate issues or I might be able to help work some of them out within the scope of this PR. Sorry that these are a lot to take in, pretty much everything below here can be digested independently of the current changes in this PR so you could read the rest later :smile:
### Questions and Comments
I'll give stable links to doc revisions as of this writing.
1. The [example using `PartialEq` in the Traits chapter][1] is poor—we have no idea how `PartialEq` works at this point in the text (or at any point, AFAICT), so it isn't clear why it won't work as a trait bound in this situation and `Float` almost magically does, with the aid of existing tailor-made identity functions that seem unlikely to be so conveniently available when we encounter a scenario like this in our real-world code.
This section just seems glossed over, or perhaps content has moved around over time or there's an assumption that implementing equality with `PartialEq` should be covered in the guide eventually so this example will be less foreign. As it stands the text is hard to follow and not very meaningful.
2. I found treatment of the relationship of trait objects to pointers in the *Static and Dynamic Dispatch* chapter unclear. [The "Why Pointers?" section][2] opens with this line:
> The use of language like "fat pointer" implies that a trait object is always a pointer of some form, but why?
But the phrase "fat pointer" hasn't been used anywhere before. This is some of the more complex material in the guide, but this section nevertheless feels displaced, not clearly connecting preceding subject matter. Earlier we've covered the internal representation of trait objects and significance of pointers they contain, but it hasn't been spelled out (other than what `&Foo` syntax suggests) that trait objects are references (and why). That's what the "Why Pointers?" section is aiming to do I gather, but it seems out of place, I think it'd make more sense to cover this before the gory details of their internals.
3. Suggestion: move the *Error Handling* chapter much earlier in the Intermediate section of the guide, or even into the Basics section. I know the Intermediate section isn't intended to be read in order per se, but plenty of people like me are just going to read it straight through anyway :grin: These are pretty fundamental concepts to understand and `Option`, `Result`, and idioms like `unwrap()` and `.ok().expect()` are referenced numerous times throughout the rest of the guide. They feature pretty prominently as early as *Standard Input* and *Guessing Game* chapters in Basics, in fact. I happen to have a good understanding of these already through encountering their analogs in typed functional languages, but if I didn't I believe I really would have appreciated reading *Error Handling* much earlier.
4. In the `rustdoc` chapter, a [comment at the beginning of the first source example][3] refers to a "link" crate attribute being needed. There seems to be no such attribute present in the source. I believe this refers to `crate_type` [according to the reference][4], but it'd be nice if this example were updated/clarified (I think `crate_id` is deprecated/obsolete too).
This brings me to a related comment also: after encountering crate attributes in the reference and also docs on Cargo configuration like `crate-type = ["dylib"]`, I'm uncertain about the relationship/redundancy between these. I'm sure this is the kind of thing where docs are simply struggling to keep pace with rapid changes in Rust and Cargo, just wanted to flag that this distinction ought to be clearly covered in the docs for one or the other at some point, it's presently hard to track down.
5. Minor: link to sample editor configurations in [the introductory chapter][5] is broken, probably the generator automatically translates `.md` links to `.html`. Perhaps it shouldn't do that for absolute URLs.
6. Following from my changes to the enums coverage in [*Compound Data Types*][6] in this PR: sum types are an important topic and I tried to make some improvements, but I think the motivating example of `Character` with `Digit(i32)` and `Other` variants is a pretty weak one, and a better example could greatly improve cohesion with the `Ordering` coverage later in the section and how that ties into pattern matching in the subsequent chapter. I just haven't thought of a better example to suggest yet.
In particular, the text states:
> This may seem rather limiting, but it's a limitation which we can overcome.
This is referring to `Character`, and actually to more than one limitation: the preceding admonition that its variants aren't comparable/don't have ordering, and don't support binary operators like `*` and `+`. Overcoming these limitations actually never gets explained—we next cover how `Ordering` works as an enum itself for plain `i32`s, but never get around to showing how this might be applied to our `Digit` variant type.
Since the coverage of enums already segues into pattern matching and this could be even tighter with a stronger example, it might be nice if our example enum were somehow connected to the final example program for the Basics section too, where `Ordering` reappears. I don't see how it would fit with the current guessing game example, but food for thought.
7. `#[derive]` seems conspicuously missing from the guide. It would probably make sense to introduce after showing simple examples of implementing equality and/or ordering traits by hand, which have been mentioned as possibilities above. Perhaps it's too much to breach this as early as the Basic section though without traits being introduced. `#[derive]` itself and the derivable traits can certainly be saved for Intermediate and referenced as covered later, in any case.
Niko Matsakis [Fri, 6 Mar 2015 15:14:12 +0000 (10:14 -0500)]
When matching against a pattern (either via `match` or `let`) that
contains ref-bindings, do not permit any upcasting from the type of
the value being matched. Similarly, do not permit coercion in a `let`.
This is a [breaking-change] in that it closes a type hole that
previously existed, and in that coercion is not performed. You should
be able to work around the latter by converting:
```rust
let ref mut x: T = expr;
```
into
```rust
let x: T = expr;
let ref mut x = x;
```
Restricting coercion not to apply in the case of `let ref` or `let ref mut` is sort
of unexciting to me, but seems the best solution:
1. Mixing coercion and `let ref` or `let ref mut` is a bit odd, because you are taking
the address of a (coerced) temporary, but only sometimes. It's not syntactically evident,
in other words, what's going on. When you're doing a coercion, you're kind of
2. Put another way, I would like to preserve the relationship that
`equality <= subtyping <= coercion <= as-coercion`, where this is
an indication of the number of `(T1,T2)` pairs that are accepted by
the various relations. Trying to mix `let ref mut` and coercion
would create another kind of relation that is like coercion, but
acts differently in the case where a precise match is needed.
3. In any case, this is strictly more conservative than what we had
before and we can undo it in the future if we find a way to make
coercion mix with type equality.
The change to match I feel ok about but similarly unthrilled. There is
some subtle text already concerning whether to use eqtype or subtype
for identifier bindings. The best fix I think would be to always have
match use strict equality but use subtyping on identifier bindings,
but the comment `(*)` explains why that's not working at the moment.
As above, I think we can change this as we clean up the code there.
Rollup merge of #23570 - dotdash:issue23550, r=eddyb
Boolean values and small aggregates have a different type in args/allocas than
in SSA values but the intrinsics for volatile and atomic ops were
missing the necessary casts to handle that.
Rollup merge of #23559 - aturon:future-proof-map-index, r=Gankro
This commit removes the `IndexMut` impls on `HashMap` and `BTreeMap`, in
order to future-proof the API against the eventual inclusion of an
`IndexSet` trait.
but to keep the design space as unconstrained as possible, we do not
currently want to support `IndexMut`, in case some other strategy will
eventually be needed.
Code currently using mutating index notation can use `get_mut` instead.
Björn Steinbrink [Fri, 20 Mar 2015 23:21:38 +0000 (00:21 +0100)]
Fix volatile / atomic ops on bools and small aggregates
Boolean values and small aggregates have a different type in
args/allocas than in SSA values but the intrinsics for volatile and
atomic ops were missing the necessary casts to handle that.
bors [Sat, 21 Mar 2015 05:25:21 +0000 (05:25 +0000)]
Auto merge of #23470 - alexcrichton:less-prelude, r=aturon
This commit removes the reexports of `old_io` traits as well as `old_path` types
and traits from the prelude. This functionality is now all deprecated and needs
to be removed to make way for other functionality like `Seek` in the `std::io`
module (currently reexported as `NewSeek` in the io prelude).
Alex Crichton [Tue, 17 Mar 2015 20:33:26 +0000 (13:33 -0700)]
std: Remove old_io/old_path from the prelude
This commit removes the reexports of `old_io` traits as well as `old_path` types
and traits from the prelude. This functionality is now all deprecated and needs
to be removed to make way for other functionality like `Seek` in the `std::io`
module (currently reexported as `NewSeek` in the io prelude).
Aaron Turon [Fri, 20 Mar 2015 17:22:57 +0000 (10:22 -0700)]
Future-proof indexing on maps: remove IndexMut
This commit removes the `IndexMut` impls on `HashMap` and `BTreeMap`, in
order to future-proof the API against the eventual inclusion of an
`IndexSet` trait.
but to keep the design space as unconstrained as possible, we do not
currently want to support `IndexMut`, in case some other strategy will
eventually be needed.
Code currently using mutating index notation can use `get_mut` instead.
bors [Fri, 20 Mar 2015 11:29:12 +0000 (11:29 +0000)]
Auto merge of #23522 - steveklabnik:gh22518, r=Manishearth
When investigating #22518, this chapter is really the only part that has `rand`, and the rest still works without it. We should have some examples like this, but for now, it's more important to be right than perfect.
Rollup merge of #23526 - mbrubeck:uppercase, r=steveklabnik
`uppercase` and `lowercase` are currently named `to_uppercase` and `to_lowercase`. Also adds a link to the `char` type documentation which has much more detail on these iterators.
Rollup merge of #23447 - kjpgit:kjp/pointerexample, r=steveklabnik
These two borrowing examples were confusing/misleading. This changes it
to more clearly show how you _can_ borrow a box, and also uses & instead
of &*.
Rollup merge of #23504 - alexcrichton:parse-error-not-unit, r=aturon
The IP and socket address types all had `FromStr` implemented but the
implementations were not marked stable, nor was the error type returned ready to
be properly stabilized.
This commit marks the implementations of `FromStr` as stable and also renamed
the `ParseError` structure to `AddrParseError`. The error is now also an opaque
structure that cannot be constructed outside the standard library.
bors [Fri, 20 Mar 2015 04:30:04 +0000 (04:30 +0000)]
Auto merge of #23504 - alexcrichton:parse-error-not-unit, r=aturon
The IP and socket address types all had `FromStr` implemented but the
implementations were not marked stable, nor was the error type returned ready to
be properly stabilized.
This commit marks the implementations of `FromStr` as stable and also renamed
the `ParseError` structure to `AddrParseError`. The error is now also an opaque
structure that cannot be constructed outside the standard library.
Rollup merge of #23489 - michaelwoerister:span-artihmetic-overflow-bug, r=alexcrichton
This should solve issues #23115, #23469, and #23407.
As the title says, this is just a workaround. The underlying problem is that macro expansion can produce invalid spans. I've opened issue #23480 so we don't forget about that.
bors [Thu, 19 Mar 2015 22:37:02 +0000 (22:37 +0000)]
Auto merge of #23489 - michaelwoerister:span-artihmetic-overflow-bug, r=alexcrichton
This should solve issues #23115, #23469, and #23407.
As the title says, this is just a workaround. The underlying problem is that macro expansion can produce invalid spans. I've opened issue #23480 so we don't forget about that.
Matt Brubeck [Thu, 19 Mar 2015 20:34:18 +0000 (13:34 -0700)]
Update docs for ToUppercase/ToLowercase structs
`uppercase` and `lowercase` are currently named `to_uppercase` and `to_lowercase`.
Also adds a link to the `char` type documentation which has much more detail
on these iterators.
bors [Thu, 19 Mar 2015 19:15:22 +0000 (19:15 +0000)]
Auto merge of #23430 - alexcrichton:io-error, r=aturon
This commit stabilizes the `ErrorKind` enumeration which is consumed by and
generated by the `io::Error` type. The purpose of this type is to serve as a
cross-platform namespace to categorize errors into. Two specific issues are
addressed as part of this stablization:
* The naming of each variant was scrutinized and some were tweaked. An example
is how `FileNotFound` was renamed to simply `NotFound`. These names should not
show either a Unix or Windows bias and the set of names is intended to grow
over time. For now the names will likely largely consist of those errors
generated by the I/O APIs in the standard library.
* The mapping of OS error codes onto kinds has been altered. Coalescing no
longer occurs (multiple error codes become one kind). It is intended that each
OS error code, if bound, corresponds to only one `ErrorKind`. The current set
of error kinds was expanded slightly to include some networking errors.
This commit also adds a `raw_os_error` function which returns an `Option<i32>`
to extract the underlying raw error code from the `Error`.
Alex Crichton [Tue, 17 Mar 2015 01:08:57 +0000 (18:08 -0700)]
std: Stablize io::ErrorKind
This commit stabilizes the `ErrorKind` enumeration which is consumed by and
generated by the `io::Error` type. The purpose of this type is to serve as a
cross-platform namespace to categorize errors into. Two specific issues are
addressed as part of this stablization:
* The naming of each variant was scrutinized and some were tweaked. An example
is how `FileNotFound` was renamed to simply `NotFound`. These names should not
show either a Unix or Windows bias and the set of names is intended to grow
over time. For now the names will likely largely consist of those errors
generated by the I/O APIs in the standard library.
* The mapping of OS error codes onto kinds has been altered. Coalescing no
longer occurs (multiple error codes become one kind). It is intended that each
OS error code, if bound, corresponds to only one `ErrorKind`. The current set
of error kinds was expanded slightly to include some networking errors.
This commit also adds a `raw_os_error` function which returns an `Option<i32>`
to extract the underlying raw error code from the `Error`.
bors [Thu, 19 Mar 2015 16:42:16 +0000 (16:42 +0000)]
Auto merge of #23213 - ipetkov:rustdoc-src-fix, r=huonw
* rustdoc was doubly appending the file name to the path of where to
generate the source files, meanwhile, the [src] hyperlinks were not
* Added a flag to rustdoc::html::render::clean_srcpath to ignore the
last path component, i.e. the file name itself to prevent the issue
* This also avoids creating directories with the same name as source
files, and it makes sure the link to `main.css` is correct as well.
Aaron Turon [Thu, 19 Mar 2015 06:36:19 +0000 (23:36 -0700)]
Stabilize Entry types
This commit marks as `#[stable]` the `Entry` types for the maps provided
by `std`. The main reason these had been left unstable previously was
uncertainty about an eventual trait design, but several plausible
designs have been proposed that all work fine with the current type definitions.
Rollup merge of #23428 - Manishearth:ast-doc, r=steveklabnik
I often have to run `ast-json` or look into the pretty-printer source to figure out what the fields of an AST enum mean. I've tried to document most of what I know (and some semi-obvious stuff).
Rollup merge of #23475 - nikomatsakis:closure-ret-syntax, r=acrichto
Require braces when a closure has an explicit return type. This is a [breaking-change]: instead of a closure like `|| -> i32 22`, prefer `|| -> i32 { 22 }`.
Alex Crichton [Thu, 19 Mar 2015 03:08:15 +0000 (20:08 -0700)]
std: Stabilize FromStr implementations in std::net
The IP and socket address types all had `FromStr` implemented but the
implementations were not marked stable, nor was the error type returned ready to
be properly stabilized.
This commit marks the implementations of `FromStr` as stable and also renamed
the `ParseError` structure to `AddrParseError`. The error is now also an opaque
structure that cannot be constructed outside the standard library.
projects / rust.git / log