From 9d3deb4766e1c3c9d0a0f98fc124de7063b47030 Mon Sep 17 00:00:00 2001 From: David Szotten Date: Fri, 18 Sep 2015 17:21:30 +0100 Subject: [PATCH 1/8] fix anchor link --- src/doc/trpl/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index edb794a54aea4..5cd847da823ce 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -210,7 +210,7 @@ that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that ### Composing `Option` values -In [`option-ex-string-find`](#code-option-ex-string-find-2) +In [`option-ex-string-find`](#code-option-ex-string-find) we saw how to use `find` to discover the extension in a file name. Of course, not all file names have a `.` in them, so it's possible that the file name has no extension. This *possibility of absence* is encoded into the types using From 634ffe562450278e9d77066d3607a1971353979b Mon Sep 17 00:00:00 2001 From: David Szotten Date: Fri, 18 Sep 2015 22:16:31 +0100 Subject: [PATCH 2/8] remove preceeding blank line --- src/doc/trpl/error-handling.md | 1 - 1 file changed, 1 deletion(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index 5cd847da823ce..f7d5db2ddf1d7 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -89,7 +89,6 @@ an integer as an argument, doubles it and prints it.
```rust,should_panic - use std::env; fn main() { From 4e42fcd92ad0d918cb0474551601c387fa4999a3 Mon Sep 17 00:00:00 2001 From: David Szotten Date: Sat, 19 Sep 2015 11:43:32 +0100 Subject: [PATCH 3/8] link needs puncuation --- src/doc/trpl/error-handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index f7d5db2ddf1d7..6d1d2f4099842 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -28,7 +28,7 @@ systems may want to jump around. * [The `Result` type](#the-result-type) * [Parsing integers](#parsing-integers) * [The `Result` type alias idiom](#the-result-type-alias-idiom) - * [A brief interlude: unwrapping isn't evil](#a-brief-interlude-unwrapping-isnt-evil) + * [A brief interlude: unwrapping isn't evil](#a-brief-interlude:-unwrapping-isn't-evil) * [Working with multiple error types](#working-with-multiple-error-types) * [Composing `Option` and `Result`](#composing-option-and-result) * [The limits of combinators](#the-limits-of-combinators) @@ -41,7 +41,7 @@ systems may want to jump around. * [The real `try!` macro](#the-real-try!-macro) * [Composing custom error types](#composing-custom-error-types) * [Advice for library writers](#advice-for-library-writers) -* [Case study: A program to read population data](#case-study-a-program-to-read-population-data) +* [Case study: A program to read population data](#case-study:-a-program-to-read-population-data) * [Initial setup](#initial-setup) * [Argument parsing](#argument-parsing) * [Writing the logic](#writing-the-logic) From 30c91cd7f7527cee89e4997827fbe61ea39f2729 Mon Sep 17 00:00:00 2001 From: David Szotten Date: Sat, 19 Sep 2015 11:43:57 +0100 Subject: [PATCH 4/8] angle brackets get mis-parsed. bug? --- src/doc/trpl/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index 6d1d2f4099842..9dbc27dfcb8ae 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -45,7 +45,7 @@ systems may want to jump around. * [Initial setup](#initial-setup) * [Argument parsing](#argument-parsing) * [Writing the logic](#writing-the-logic) - * [Error handling with `Box`](#error-handling-with-box) + * [Error handling with `Box`](#error-handling-with-box%3Cerror%3E) * [Reading from stdin](#reading-from-stdin) * [Error handling with a custom type](#error-handling-with-a-custom-type) * [Adding functionality](#adding-functionality) From 3a5e9a3f9934a850753110769c49521a659cd03a Mon Sep 17 00:00:00 2001 From: David Szotten Date: Sat, 19 Sep 2015 11:44:55 +0100 Subject: [PATCH 5/8] wrap more referenced code blocks in divs --- src/doc/trpl/error-handling.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index 9dbc27dfcb8ae..521538b955678 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -186,6 +186,7 @@ But wait, what about `unwrap` used in [`unwrap-double`](#code-unwrap-double)? There was no case analysis there! Instead, the case analysis was put inside the `unwrap` method for you. You could define it yourself if you want: +
```rust enum Option { None, @@ -202,6 +203,7 @@ impl Option { } } ``` +
The `unwrap` method *abstracts away the case analysis*. This is precisely the thing that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that @@ -251,6 +253,7 @@ option is `None`, in which case, just return `None`. Rust has parametric polymorphism, so it is very easy to define a combinator that abstracts this pattern: + Indeed, `map` is [defined as a method][2] on `Option` in the standard library. @@ -390,12 +394,14 @@ remove choices because they will panic if `Option` is `None`. The `Result` type is also [defined in the standard library][6]: +
```rust enum Result { Ok(T), Err(E), } ``` +
The `Result` type is a richer version of `Option`. Instead of expressing the possibility of *absence* like `Option` does, `Result` expresses the possibility @@ -666,6 +672,7 @@ with both an `Option` and a `Result`, the solution is *usually* to convert the (from `env::args()`) means the user didn't invoke the program correctly. We could just use a `String` to describe the error. Let's try: +
```rust use std::env; @@ -682,6 +689,7 @@ fn main() { } } ``` +
There are a couple new things in this example. The first is the use of the [`Option::ok_or`](../std/option/enum.Option.html#method.ok_or) @@ -898,6 +906,7 @@ seen above. Here is a simplified definition of a `try!` macro: +
```rust macro_rules! try { ($e:expr) => (match $e { @@ -906,6 +915,7 @@ macro_rules! try { }); } ``` +
(The [real definition](../std/macro.try!.html) is a bit more sophisticated. We will address that later.) @@ -1158,11 +1168,13 @@ The `std::convert::From` trait is [defined in the standard library](../std/convert/trait.From.html): +
```rust trait From { fn from(T) -> Self; } ``` +
Deliciously simple, yes? `From` is very useful because it gives us a generic way to talk about conversion *from* a particular type `T` to some other type @@ -1238,6 +1250,7 @@ macro_rules! try { This is not it's real definition. It's real definition is [in the standard library](../std/macro.try!.html): +
```rust macro_rules! try { ($e:expr) => (match $e { @@ -1246,6 +1259,7 @@ macro_rules! try { }); } ``` +
There's one tiny but powerful change: the error value is passed through `From::from`. This makes the `try!` macro a lot more powerful because it gives From 436e8d69bf7326181225cb3c0226d11efef5d8f8 Mon Sep 17 00:00:00 2001 From: David Szotten Date: Sat, 19 Sep 2015 11:45:09 +0100 Subject: [PATCH 6/8] its vs it's --- src/doc/trpl/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index 521538b955678..4cba68e172462 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -1247,7 +1247,7 @@ macro_rules! try { } ``` -This is not it's real definition. It's real definition is +This is not its real definition. Its real definition is [in the standard library](../std/macro.try!.html):
From f7d8b418147fe46f3d0eaba295a0111394446bb0 Mon Sep 17 00:00:00 2001 From: David Szotten Date: Sat, 19 Sep 2015 11:45:30 +0100 Subject: [PATCH 7/8] missing punctuation --- src/doc/trpl/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index 4cba68e172462..18d2fae0d7545 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -1470,7 +1470,7 @@ representation. But certainly, this will vary depending on use cases. At a minimum, you should probably implement the [`Error`](../std/error/trait.Error.html) trait. This will give users of your library some minimum flexibility for -[composing errors](#the-real-try-macro). Implementing the `Error` trait also +[composing errors](#the-real-try!-macro). Implementing the `Error` trait also means that users are guaranteed the ability to obtain a string representation of an error (because it requires impls for both `fmt::Debug` and `fmt::Display`). From 5ab3058569245171a44283fddee6c119a31765b7 Mon Sep 17 00:00:00 2001 From: David Szotten Date: Sat, 19 Sep 2015 12:06:36 +0100 Subject: [PATCH 8/8] change back to anchors; divs break md --- src/doc/trpl/error-handling.md | 36 +++++++++++++++++----------------- 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/doc/trpl/error-handling.md b/src/doc/trpl/error-handling.md index 18d2fae0d7545..18ce93ea06a64 100644 --- a/src/doc/trpl/error-handling.md +++ b/src/doc/trpl/error-handling.md @@ -87,7 +87,8 @@ thread '
' panicked at 'Invalid number: 11', src/bin/panic-simple.rs:5 Here's another example that is slightly less contrived. A program that accepts an integer as an argument, doubles it and prints it. -
+ + ```rust,should_panic use std::env; @@ -98,7 +99,6 @@ fn main() { println!("{}", 2 * n); } ``` -
If you give this program zero arguments (error 1) or if the first argument isn't an integer (error 2), the program will panic just like in the first @@ -139,7 +139,8 @@ system is an important concept because it will cause the compiler to force the programmer to handle that absence. Let's take a look at an example that tries to find a character in a string: -
+ + ```rust // Searches `haystack` for the Unicode character `needle`. If one is found, the // byte offset of the character is returned. Otherwise, `None` is returned. @@ -152,7 +153,6 @@ fn find(haystack: &str, needle: char) -> Option { None } ``` -
Notice that when this function finds a matching character, it doen't just return the `offset`. Instead, it returns `Some(offset)`. `Some` is a variant or @@ -186,7 +186,8 @@ But wait, what about `unwrap` used in [`unwrap-double`](#code-unwrap-double)? There was no case analysis there! Instead, the case analysis was put inside the `unwrap` method for you. You could define it yourself if you want: -
+ + ```rust enum Option { None, @@ -203,7 +204,6 @@ impl Option { } } ``` -
The `unwrap` method *abstracts away the case analysis*. This is precisely the thing that makes `unwrap` ergonomic to use. Unfortunately, that `panic!` means that @@ -253,7 +253,8 @@ option is `None`, in which case, just return `None`. Rust has parametric polymorphism, so it is very easy to define a combinator that abstracts this pattern: - Indeed, `map` is [defined as a method][2] on `Option` in the standard library. @@ -394,14 +394,14 @@ remove choices because they will panic if `Option` is `None`. The `Result` type is also [defined in the standard library][6]: -
+ + ```rust enum Result { Ok(T), Err(E), } ``` -
The `Result` type is a richer version of `Option`. Instead of expressing the possibility of *absence* like `Option` does, `Result` expresses the possibility @@ -672,7 +672,8 @@ with both an `Option` and a `Result`, the solution is *usually* to convert the (from `env::args()`) means the user didn't invoke the program correctly. We could just use a `String` to describe the error. Let's try: -
+ + ```rust use std::env; @@ -689,7 +690,6 @@ fn main() { } } ``` -
There are a couple new things in this example. The first is the use of the [`Option::ok_or`](../std/option/enum.Option.html#method.ok_or) @@ -906,7 +906,8 @@ seen above. Here is a simplified definition of a `try!` macro: -
+ + ```rust macro_rules! try { ($e:expr) => (match $e { @@ -915,7 +916,6 @@ macro_rules! try { }); } ``` -
(The [real definition](../std/macro.try!.html) is a bit more sophisticated. We will address that later.) @@ -1168,13 +1168,13 @@ The `std::convert::From` trait is [defined in the standard library](../std/convert/trait.From.html): -
+ + ```rust trait From { fn from(T) -> Self; } ``` -
Deliciously simple, yes? `From` is very useful because it gives us a generic way to talk about conversion *from* a particular type `T` to some other type @@ -1250,7 +1250,8 @@ macro_rules! try { This is not its real definition. Its real definition is [in the standard library](../std/macro.try!.html): -
+ + ```rust macro_rules! try { ($e:expr) => (match $e { @@ -1259,7 +1260,6 @@ macro_rules! try { }); } ``` -
There's one tiny but powerful change: the error value is passed through `From::from`. This makes the `try!` macro a lot more powerful because it gives