This changes how rustic generate `id` and `href` attributes for section header anchor. Now they are more github-like.
Also fixes breakage in docs caused by this and broken links in "Error Handling" section of book.
r? @steveklabnik
cc @alexcrichton
In code like `let x = 5`, I am initially confused as to the meaning of "let doesn't take a name on the left hand side, it actually accepts a pattern." - I interpret that as the pattern being located as: `<pattern> let [...]`.
I think what is meant is that the name/pattern is on the left hand side *of the assignment*, rather than to the left of the *let* statement. This change clarifies that.
Using "later" in this context makes more sense than "greater" so it's been changed to match the Linux requirement above it rather than the other way around.
- Headlines begin at 1st level now like the rest of the book
- All Headlines a blank line above and below
- Fix links in this chapter's TOC
r? @steveklabnik
This commit does some refactoring to make almost all of the `std::rt` private.
Specifically, the following items are no longer part of its API:
* DEFAULT_ERROR_CODE
* backtrace
* unwind
* args
* at_exit
* cleanup
* heap (this is just alloc::heap)
* min_stack
* util
The module is now tagged as `#[doc(hidden)]` as the only purpose it's serve is
an entry point for the `panic!` macro via the `begin_unwind` and
`begin_unwind_fmt` reexports.
This commit does some refactoring to make almost all of the `std::rt` private.
Specifically, the following items are no longer part of its API:
* DEFAULT_ERROR_CODE
* backtrace
* unwind
* args
* at_exit
* cleanup
* heap (this is just alloc::heap)
* min_stack
* util
The module is now tagged as `#[doc(hidden)]` as the only purpose it's serve is
an entry point for the `panic!` macro via the `begin_unwind` and
`begin_unwind_fmt` reexports.
r? @steveklabnik
The phrase 'academic research' rubs me the wrong way. I have some concern about the role of this page and think it could be expanded to more than just academic papers and cleaned up a lot.
I took a stab at fixing #28064. Not sure if this all-features-in-one-example approach is the right one. Also I completely made up the terms "star globbing" and "brace expansion globbing" -- they are just called "glob-like syntax" in the reference.
I took a stab at fixing #28064. Not sure if this all-features-in-one-example approach is the right one. Also I completely made up the terms "star globbing" and "brace expansion globbing" -- they are just called "glob-like syntax" in the reference.
As I understand, there are no proc closures in Rust any more. So this pr removes `procedure_type` production. It isn't used anywhere. The `proc` is still a keyword.
r? @steveklabnik
@bors: r+ rollup
I have two issues with the section "Deref and method calls" of the book's chapter "Deref coercions".
- (Minor) It says "In other words, these are the same two things in Rust:", followed by a code block in which no two things seem similar, much less the same. Presumably this sentence made more sense in a previous revision.
- The next paragraph conflates two concepts which, imho, should kept separate. They are
- deref coercion, i.e. inserting as many `*` as necessary and
- implicitly referencing the receiver, i.e. inserting a single `&` to satisfy the method's `self` parameter type.
I appreciate that with the proposed changes the example becomes very contrived, even for a foo-bar-baz one. However, the current exmplanation is just wrong.
This adds missing `?` marks to productions for loops and break/continue.
It also adds missing option label to while let loop.
Note that '[' foo ']' means grouping in BNF, and '?' is used for possible missing items.
r? @steveklabnik
Originally in an example it reads as follows:
```rust
fn inverse<T>() -> T
// this is using ConvertTo as if it were "ConvertFrom<i32>"
where i32: ConvertTo<T> {
42.convert()
}
```
There was no mention of `ConvertFrom` elsewhere in the page other than in this comment. Is this supposed to be `ConvertTo<i64>` ?
I'm confused by this example.
It came up twice in quick succession on IRC that rustdoc doesn't run tests in bin crates, and doesn't give any explanation/warning either as to why. I thought it couldn't hurt to emphasize that in the Book.
The chapter on concurrency has two examples that both start with:
let something = thread::spawn(…
but the returned values have different types, because the second example has `.join()` at the end of the expression.
I haven't noticed that join at first, and was wondering how is that possible that the result can have `.is_err()` and `.join()` methods.
I've changed the second example to have the same structure as the first, so they're easy to compare.
Per @steveklabnik's comment [here](https://github.com/rust-lang/cargo/issues/739#issuecomment-130085860), the Pandoc components of the Makefile are no longer used, and as such the corresponding components of the documentation are out of date.
- I've removed the Pandoc (and therefore also LaTeX) elements of the makefile and confirmed that the build proceeds correctly.
- I updated the documentation to reference `rustdoc` and of Pandoc.
r? @steveklabnik
The previous wording was confusing. While would we need to go through
the whole list just to find the first code point? `chars()` being an
iterator, we only need to walk from the beginning of the list.
Note that I am not a native English speaker and I have still difficulties to spot if a "the" is needed somewhere. Feel free to take this PR as a mere suggestion.
r? @steveklabnik
To correctly reexport statically included libraries from a DLL on Windows, the
compiler will soon need to have knowledge about what symbols are statically
included and which are not. To solve this problem a new unstable
`#[linked_from]` attribute is being added and recognized on `extern` blocks to
indicate which native library the symbols are coming from.
The compiler then keeps track of what the set of FFI symbols are that are
included statically. This information will be used in a future commit to
configure how we invoke the linker on Windows.
This commit removes all morestack support from the compiler which entails:
* Segmented stacks are no longer emitted in codegen.
* We no longer build or distribute libmorestack.a
* The `stack_exhausted` lang item is no longer required
The only current use of the segmented stack support in LLVM is to detect stack
overflow. This is no longer really required, however, because we already have
guard pages for all threads and registered signal handlers watching for a
segfault on those pages (to print out a stack overflow message). Additionally,
major platforms (aka Windows) already don't use morestack.
This means that Rust is by default less likely to catch stack overflows because
if a function takes up more than one page of stack space it won't hit the guard
page. This is what the purpose of morestack was (to catch this case), but it's
better served with stack probes which have more cross platform support and no
runtime support necessary. Until LLVM supports this for all platform it looks
like morestack isn't really buying us much.
cc #16012 (still need stack probes)
Closes#26458 (a drive-by fix to help diagnostics on stack overflow)
r? @brson
This commit removes all morestack support from the compiler which entails:
* Segmented stacks are no longer emitted in codegen.
* We no longer build or distribute libmorestack.a
* The `stack_exhausted` lang item is no longer required
The only current use of the segmented stack support in LLVM is to detect stack
overflow. This is no longer really required, however, because we already have
guard pages for all threads and registered signal handlers watching for a
segfault on those pages (to print out a stack overflow message). Additionally,
major platforms (aka Windows) already don't use morestack.
This means that Rust is by default less likely to catch stack overflows because
if a function takes up more than one page of stack space it won't hit the guard
page. This is what the purpose of morestack was (to catch this case), but it's
better served with stack probes which have more cross platform support and no
runtime support necessary. Until LLVM supports this for all platform it looks
like morestack isn't really buying us much.
cc #16012 (still need stack probes)
Closes#26458 (a drive-by fix to help diagnostics on stack overflow)
The previous wording was confusing. While would we need to go through
the whole list just to find the first code point? `chars()` being an
iterator, we only need to walk from the beginning of the list.
Keeping integer values and integer references in the "value" columns made the examples quite difficult for me to follow. I've added unicode arrows to make references more obvious, without using a character with actual meaning in the rust language (like `&` or previously `~`).
I got a bit confused reading the guide over why all of a sudden there was an asterisk in the code. I was explained what it was there for in the IRC, and I think it should added it to the docs to prevent any further confusion!
In Section 3.2, TARPL says that "standard allocators (including jemalloc, the one used by default in Rust) generally consider passing in 0 for the size of an allocation as Undefined Behaviour."
However, the C standard and jemalloc manual says allocating zero bytes
should succeed:
- C11 7.22.3 paragraph 1: "If the size of the space requested is zero, the behavior is implementation-defined: either a null pointer is returned, or the behavior is as if the size were some nonzero value, except that the returned pointer shall not be used to access an object."
- [jemalloc manual](http://www.freebsd.org/cgi/man.cgi?query=jemalloc&sektion=3): "The malloc and calloc functions return a pointer to the allocated memory if successful; otherwise a NULL pointer is returned and errno is set to ENOMEM."
+ Note that the description for `allocm` says "Behavior is undefined if size is 0," but it is an experimental API.
r? @Gankro
In Section 3.2, TARPL says that "standard allocators (including jemalloc, the one used by default in Rust) generally consider passing in 0 for the size of an allocation as Undefined Behaviour."
However, the C standard and jemalloc manual says allocating zero bytes
should succeed:
- C11 7.22.3 paragraph 1: "If the size of the space requested is zero, the behavior is implementation-defined: either a null pointer is returned, or the behavior is as if the size were some nonzero value, except that the returned pointer shall not be used to access an object."
- [jemalloc manual](http://www.freebsd.org/cgi/man.cgi?query=jemalloc&sektion=3): "The malloc and calloc functions return a pointer to the allocated memory if successful; otherwise a NULL pointer is returned and errno is set to ENOMEM."
+ Note that the description for `allocm` says "Behavior is undefined if size is 0," but it is an experimental API.
'work' can refer to the game itself, ie, 'this compiles but the game isn't finished,'
so 'compile' is a more clear way to describe the problem.
Thanks jhun on irc
'work' can refer to the game itself, ie, 'this compiles but the game isn't finished,'
so 'compile' is a more clear way to describe the problem.
Thanks jhun on irc
- Move "Destructuring" after "Multiple patterns", because some of
later sections include examples which make use of destructuring.
- Move "Ignoring bindings" after "Destructoring", because the former
features Result<T,E> destructuring. Some of examples in later
sections use "_" and "..", so "Ignoring bindings" must be
positioned before them.
- Fix#27347 by moving "Ref and mut ref" before "Ranges" and
"Bindings", because "Bindings" section includes a somewhat
difficult example, which also makes use of "ref" and "mut ref"
operators.
- Move "Destructuring" after "Multiple patterns", because some of
later sections include examples which make use of destructuring.
- Move "Ignoring bindings" after "Destructoring", because the former
features Result<T,E> destructuring. Some of examples in later
sections use "_" and "..", so "Ignoring bindings" must be
positioned before them.
- Fix#27347 by moving "Ref and mut ref" before "Ranges" and
"Bindings", because "Bindings" section includes a somewhat
difficult example, which also makes use of "ref" and "mut ref"
operators.
- Fix#26968 by noting the difference between ".." and "_" more explicitly
- Change one of the examples to show the match-all behaviour of ".."
- Merge "Ignoring variants" and "Ignoring bindings" sections into the latter
r? @steveklabnik
Clarifications for those new to Rust and Cargo:
* It's a good idea to get rid of the original `main.exe` in project root
* Slight clarification on the use of `main.rs` vs `lib.rs`
* Clarify that the TOML file needs to be in project root
- Fix#26968 by noting the difference between ".." and "_" more explicitly
- Change one of the examples to show the match-all behaviour of ".."
- Merge "Ignoring variants" and "Ignoring bindings" sections into the latter
this makes the second code block consistent with the first code block -- other than being in reversed order, the first code block claims b is u16 and c is u32, whereas the second code block claims the opposite. seems to be an obvious typo.
This is *mostly* reducing *my* use of *italics* but there's some other misc changes interspersed as I went along.
This updates the italicizing alphabetically from `a` to `ra`.
r? @steveklabnik
Squashed at reviewer's request:
Add heading at the end of the introductory material
Spice up introductory paragraphs a bit
Use quotes instead of <code> for phrase
Remove "other" in "other restrictions" (it's not obvious that any other
restrictions have been mentioned)
"Default methods" is a second-level heading, but is not a subsection of
"Where clause"
Reword "Default methods" introduction: it's not the "last feature" on
this page
This includes a new example with Rectangle, instead of reusing HasArea,
because fn area would require the Mul trait, and the added complexity of
that would be better left for the Operators and Overloading chapter.
Squashed at reviewer's request: Move teaser for trait bounds to bottom
Guessing Game states that "Rust only imports a few things into every
program, the ‘prelude’". That isn't strictly true. That is all it
imports by default and the change clarifies that point.
I've been baking this out of tree for long enough. This is currently about ~2/5ths the size of TRPL. Time to get it in tree so it can be more widely maintained and scrutinized. I've preserved the whole gruesome history including various rewrites. I can definitely squash these a fair amount if desired. Some random people submitted minor fixes though, so they're mixed in.
Edit: forgot to link to rendered http://cglab.ca/~abeinges/blah/turpl/_book/
Edit2:
To streamline the review process, I'm going to break this into sections that need official "domain expert" approval:
# Summary
* [ ] references.md -- very important, needs work
* [x] Meet Safe and Unsafe: reviewed by @aturon
* [x] Data Layout: reviewed by @arielb1
* [x] Ownership: reviewed by @aturon ( and sorta @nikomatsakis ) -- significantly updated, may need re-r
* [x] Coversions: reviewed by @nrc
* [x] Uninitialized Memory: reviewed by @pnkfelix
* [x] Ownership-Oriented Resource Management: reviewed by @aturon
* [x] Unwinding: reviewed by @alexcrichton
* [x] Concurrency: reviewed by @aturon
* [x] Implementing Vec: r? @huonw
Added definitions for 'Expression', 'Expression-Oriented Language' and 'Statement' to glossary.
Sorted the definitions alphabetically.
r? @steveklabnik
The reader could probably infer this from the current text, but for C++ programmers it's not obvious that struct fields don't automatically become public.
Apparently I wasn't the only one to be confused:
http://stackoverflow.com/questions/29157300/field-of-struct-is-private-when-importing-module
I don't think an example is necessary, but can add one if desired.
r? @steveklabnik
Instead of bar/baz, use valid/invalid as default methods. This
illustrates why you might want default methods, and shows that you can
call other trait methods from a default method.
r? @steveklabnik
Instead of bar/baz, use valid/invalid as default methods. This
illustrates why you might want default methods, and shows that you can
call other trait methods from a default method.
Was browsing somebody else's code and came across a snippet using labels. Looking around, it seems like there was an example for this in [rustbyexample](http://rustbyexample.com/flow_control/loop/nested.html) but none in trpl.
Updated "Installing Rust" and "After installation" to provide additional guidance to Windows users on including Rust in the Path system variable.
r? @steveklabnik
This PR fixes a snippet of code on the error handling chapter of \"The Rust Programming Language\".
//cc @steveklabnik
The docs state that trying to compile the snippet will yield the following error:
```bash
anon>:13:5: 20:6 error: non-exhaustive patterns: `_` not covered [E0004]
```
But instead the error received is:
```bash
<anon>:22:46: 22:56 error: unresolved name `NewRelease`
<anon>:22 std::io::println(descriptive_probability(NewRelease));
^~~~~~~~~~
<anon>:22:5: 22:21 error: unresolved name `std::io::println`
<anon>:22 std::io::println(descriptive_probability(NewRelease));
^~~~~~~~~~~~~~~~
error: aborting due to 2 previous errors
playpen: application terminated with error code 101
```
After applying this PR the expected error is returned:
```bash
anon>:13:5: 20:6 error: non-exhaustive patterns: `_` not covered [E0004]
<anon>:13 match probability(&event) {
<anon>:14 1.00 => \"certain\",
<anon>:15 0.00 => \"impossible\",
<anon>:16 0.00 ... 0.25 => \"very unlikely\",
<anon>:17 0.25 ... 0.50 => \"unlikely\",
<anon>:18 0.50 ... 0.75 => \"likely\",
...
<anon>:13:5: 20:6 help: see the detailed explanation for E0004
error: aborting due to previous error
```
Grammatical update (and passive -> active, but I'm not sure if "Rust" is often used as a subject in the book; feel free to revert that part for style, but keep the subject-verb agreement)
I am not mentioning #[unsafe_drop_flag] because it should go away
eventually, and also because it's just an attribute, it's not
really a use of the `unsafe` keyword.
Fixes#26345
