mirror of
https://github.com/haraldh/chainerror.git
synced 2025-06-02 22:48:07 +02:00
docs: use new names
Signed-off-by: Harald Hoyer <harald@hoyer.xyz>
This commit is contained in:
parent
55c16d7867
commit
82257c881a
27 changed files with 74 additions and 76 deletions
1
booksrc/LICENSE-APACHE
Symbolic link
1
booksrc/LICENSE-APACHE
Symbolic link
|
@ -0,0 +1 @@
|
|||
../LICENSE-APACHE
|
1
booksrc/LICENSE-MIT
Symbolic link
1
booksrc/LICENSE-MIT
Symbolic link
|
@ -0,0 +1 @@
|
|||
../LICENSE-MIT
|
|
@ -1,6 +1,6 @@
|
|||
# ErrorKind to the rescue
|
||||
|
||||
To cope with different kind of errors, we introduce the kind of an error `Func1ErrorKind` with an enum.
|
||||
To cope with different kind of errors, we introduce the `kind` of an error `Func1ErrorKind` with an enum.
|
||||
|
||||
Because we derive `Debug` and implement `Display` our `Func1ErrorKind` enum, this enum can be used as
|
||||
a `std::error::Error`.
|
||||
|
@ -8,10 +8,9 @@ a `std::error::Error`.
|
|||
Only returning `Func1ErrorKind` in `func1()` now let us get rid of `Result<(), Box<Error + Send + Sync>>` and we can
|
||||
use `ChainResult<(), Func1ErrorKind>`.
|
||||
|
||||
In `main` we can now directly use the methods of `ChainError<T>` without downcasting the error first.
|
||||
In `main` we can now directly use the methods of `chainerror::Error<T>` without downcasting the error first.
|
||||
|
||||
Also a nice `match` on `ChainError<T>.kind()` is now possible, which returns `&T`, meaning
|
||||
`&Func1ErrorKind` here.
|
||||
Also, a nice `match` on `chainerror::Error<T>.kind()` is now possible, which returns `&T`, meaning `&Func1ErrorKind` here.
|
||||
|
||||
~~~rust
|
||||
{{#include ../examples/tutorial10.rs}}
|
||||
|
|
|
@ -21,7 +21,7 @@ which gives us a lot more detail.
|
|||
|
||||
To create your own Errors, you might find [crates](https://crates.io) which create enum `Display+Debug` via derive macros.
|
||||
|
||||
Also noteworthy is [custom_error](https://crates.io/crates/custom_error) to define your custom errors,
|
||||
Also, noteworthy is [custom_error](https://crates.io/crates/custom_error) to define your custom errors,
|
||||
which can then be used with `chainerror`.
|
||||
|
||||
~~~rust
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
# Deref for the ErrorKind
|
||||
|
||||
Because ChainError<T> implements Deref to &T, we can also match on `*e` instead of `e.kind()`
|
||||
Because chainerror::Error<T> implements Deref to &T, we can also match on `*e` instead of `e.kind()`
|
||||
or call a function with `&e`
|
||||
~~~rust
|
||||
{{#include ../examples/tutorial12.rs}}
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
# Writing a library
|
||||
|
||||
I would advise to only expose an `mycrate::ErrorKind` and type alias `mycrate::Error` to `ChainError<mycrate::ErrorKind>`
|
||||
I would advise to only expose an `mycrate::ErrorKind` and type alias `mycrate::Error` to `chainerror::Error<mycrate::ErrorKind>`
|
||||
so you can tell your library users to use the `.kind()` method as `std::io::Error` does.
|
||||
|
||||
If you later decide to make your own `Error` implementation, your library users don't
|
||||
|
|
|
@ -25,7 +25,7 @@ along with the `Location` of the `context()` call and returns `Err(newerror)`.
|
|||
`?` then returns the inner error applying `.into()`, so that we
|
||||
again have a `Err(Box<Error + Send + Sync>)` as a result.
|
||||
|
||||
The `Debug` implementation of `ChainError<T>` (which is returned by `context()`)
|
||||
The `Debug` implementation of `chainerror::Error<T>` (which is returned by `context()`)
|
||||
prints the `Debug` of `T` prefixed with the stored filename and line number.
|
||||
|
||||
`ChainError<T>` in our case is `ChainError<&str>`.
|
||||
`chainerror::Error<T>` in our case is `chainerror::Error<&str>`.
|
||||
|
|
|
@ -14,13 +14,13 @@ If you compare the output to the previous example, you will see,
|
|||
that:
|
||||
|
||||
~~~
|
||||
Error: src/main.rs:19: "func1 error"
|
||||
Error: examples/tutorial2.rs:20:16: func1 error
|
||||
~~~
|
||||
|
||||
changed to just:
|
||||
|
||||
~~~
|
||||
src/main.rs:16: "func1 error"
|
||||
examples/tutorial3.rs:17:13: func1 error
|
||||
~~~
|
||||
|
||||
This is, because we caught the error of `func1()` in `main()` and print it out ourselves.
|
||||
|
|
|
@ -14,5 +14,4 @@ Sometimes you want to inspect the `source()` of an `Error`.
|
|||
Note, that because we changed the output of the error in `main()` from
|
||||
`Debug` to `Display`, we don't see the error backtrace with filename and line number.
|
||||
|
||||
To enable the `Display` backtrace, you have to enable the feature `display-cause` for `chainerror`.
|
||||
|
||||
To use the `Display` backtrace, you have to use the alternative display format output `{:#}`.
|
||||
|
|
|
@ -4,15 +4,15 @@
|
|||
|
||||
~~~rust,ignore
|
||||
fn is_chain<T: 'static + Display + Debug>(&self) -> bool
|
||||
fn downcast_chain_ref<T: 'static + Display + Debug>(&self) -> Option<&ChainError<T>>
|
||||
fn downcast_chain_mut<T: 'static + Display + Debug>(&mut self) -> Option<&mut ChainError<T>>
|
||||
fn downcast_chain_ref<T: 'static + Display + Debug>(&self) -> Option<&chainerror::Error<T>>
|
||||
fn downcast_chain_mut<T: 'static + Display + Debug>(&mut self) -> Option<&mut chainerror::Error<T>>
|
||||
fn root_cause(&self) -> Option<&(dyn Error + 'static)>
|
||||
fn find_cause<U: Error + 'static>(&self) -> Option<&U>
|
||||
fn find_chain_cause<U: Error + 'static>(&self) -> Option<&ChainError<U>>
|
||||
fn find_chain_cause<U: Error + 'static>(&self) -> Option<&chainerror::Error<U>>
|
||||
fn kind<'a>(&'a self) -> &'a T
|
||||
~~~
|
||||
|
||||
Using `downcast_chain_ref::<String>()` gives a `ChainError<String>`, which can be used
|
||||
Using `downcast_chain_ref::<String>()` gives a `chainerror::Error<String>`, which can be used
|
||||
to call `.find_cause::<io::Error>()`.
|
||||
|
||||
~~~rust,ignore
|
||||
|
|
|
@ -1,14 +1,14 @@
|
|||
# Finding an Error cause
|
||||
|
||||
To distinguish the errors occuring in various places, we can define named string errors with the
|
||||
To distinguish the errors occurring in various places, we can define named string errors with the
|
||||
"new type" pattern.
|
||||
|
||||
~~~rust,ignore
|
||||
derive_str_context!(Func2Error);
|
||||
derive_str_context!(Func1Error);
|
||||
chainerror::str_context!(Func2Error);
|
||||
chainerror::str_context!(Func1Error);
|
||||
~~~
|
||||
|
||||
Instead of `ChainError<String>` we now have `struct Func1Error(String)` and `ChainError<Func1Error>`.
|
||||
Instead of `chainerror::Error<String>` we now have `struct Func1Error(String)` and `chainerror::Error<Func1Error>`.
|
||||
|
||||
In the `main` function you can see, how we can match the different errors.
|
||||
|
||||
|
@ -18,9 +18,9 @@ Also see:
|
|||
~~~
|
||||
as a shortcut to
|
||||
~~~rust,ignore
|
||||
if let Some(f2err) = f1err.find_cause::<ChainError<Func2Error>>() {
|
||||
if let Some(f2err) = f1err.find_cause::<chainerror::Error<Func2Error>>() {
|
||||
~~~
|
||||
hiding the `ChainError<T>` implementation detail.
|
||||
hiding the `chainerror::Error<T>` implementation detail.
|
||||
|
||||
~~~rust
|
||||
{{#include ../examples/tutorial8.rs}}
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue