1
Fork 0

remove example usage of from_str in error docs

Fixes #24185
This commit is contained in:
Steve Klabnik 2015-04-16 15:50:24 -04:00
parent 3ca83a79bf
commit a2ccc81f4b

View file

@ -20,18 +20,18 @@ panic. A *failure* is an error that can be recovered from in some way. A
*panic* is an error that cannot be recovered from. *panic* is an error that cannot be recovered from.
What do we mean by "recover"? Well, in most cases, the possibility of an error What do we mean by "recover"? Well, in most cases, the possibility of an error
is expected. For example, consider the `from_str` function: is expected. For example, consider the `parse` function:
```{rust,ignore} ```ignore
from_str("5"); "5".parse();
``` ```
This function takes a string argument and converts it into another type. But This method converts a string into another type. But because it's a string, you
because it's a string, you can't be sure that the conversion actually works. can't be sure that the conversion actually works. For example, what should this
For example, what should this convert to? convert to?
```{rust,ignore} ```ignore
from_str("hello5world"); "hello5world".parse();
``` ```
This won't work. So we know that this function will only work properly for some This won't work. So we know that this function will only work properly for some
@ -40,7 +40,8 @@ inputs. It's expected behavior. We call this kind of error a *failure*.
On the other hand, sometimes, there are errors that are unexpected, or which On the other hand, sometimes, there are errors that are unexpected, or which
we cannot recover from. A classic example is an `assert!`: we cannot recover from. A classic example is an `assert!`:
```{rust,ignore} ```rust
# let x = 5;
assert!(x == 5); assert!(x == 5);
``` ```
@ -119,17 +120,19 @@ Rust calls these sorts of errors *panics*.
# Handling errors with `Option` and `Result` # Handling errors with `Option` and `Result`
The simplest way to indicate that a function may fail is to use the `Option<T>` The simplest way to indicate that a function may fail is to use the `Option<T>`
type. Remember our `from_str()` example? Here's its type signature: type. For example, the `find` method on strings attempts to find a pattern
in a string, and returns an `Option`:
```{rust,ignore} ```rust
pub fn from_str<A: FromStr>(s: &str) -> Option<A> let s = "foo";
assert_eq!(s.find('f'), Some(0));
assert_eq!(s.find('z'), None);
``` ```
`from_str()` returns an `Option<A>`. If the conversion succeeds, it will return
`Some(value)`, and if it fails, it will return `None`.
This is appropriate for the simplest of cases, but doesn't give us a lot of This is appropriate for the simplest of cases, but doesn't give us a lot of
information in the failure case. What if we wanted to know _why_ the conversion information in the failure case. What if we wanted to know _why_ the function
failed? For this, we can use the `Result<T, E>` type. It looks like this: failed? For this, we can use the `Result<T, E>` type. It looks like this:
```rust ```rust