Command Line Applications in Rust
Output
Printing “Hello World”
#![allow(unused)] fn main() { println!("Hello World"); }
Well, that was easy.
Great, onto the next topic.Using
println!
You can pretty much print all the things you like
with theprintln!
macro.
This macro has some pretty amazing capabilities,
but also a special syntax.
It expects you to write a string literal as the first parameter,
that contains placeholders that will be filled in
by the values of the parameters that follow as further arguments.For example:
#![allow(unused)] fn main() { let x = 42; println!("My lucky number is {}.", x); }
will print
My lucky number is 42.
The curly braces (
{}
) in the string above is one of these placeholders.
This is the default placeholder type
that tries to print the given value in a human readable way.
For numbers and strings this works very well,
but not all types can do that.
This is why there is also a “debug representation”,
that you can get by filling the braces of the placeholder like this:{:?}
.For example,
#![allow(unused)] fn main() { let xs = vec![1, 2, 3]; println!("The list is: {:?}", xs); }
will print
The list is: [1, 2, 3]
If you want your own data types to be printable for debugging and logging,
you can in most cases add a#[derive(Debug)]
above their definition.Printing errors
Printing errors should be done via
stderr
to make it easier for users
and other tools
to pipe their outputs to files
or more tools.In Rust this is achieved
withprintln!
andeprintln!
,
the former printing tostdout
and the latter tostderr
.#![allow(unused)] fn main() { println!("This is information"); eprintln!("This is an error! :("); }
A note on printing performance
Printing to the terminal is surprisingly slow!
If you call things likeprintln!
in a loop,
it can easily become a bottleneck in an otherwise fast program.
To speed this up,
there are two things you can do.First,
you might want to reduce the number of writes
that actually “flush” to the terminal.
println!
tells the system to flush to the terminal every time,
because it is common to print each new line.
If you don’t need that,
you can wrap yourstdout
handle in aBufWriter
which by default buffers up to 8 kB.
(You can still call.flush()
on thisBufWriter
when you want to print immediately.)#![allow(unused)] fn main() { use std::io::{self, Write}; let stdout = io::stdout(); // get the global stdout entity let mut handle = io::BufWriter::new(stdout); // optional: wrap that handle in a buffer writeln!(handle, "foo: {}", 42); // add `?` if you care about errors here }
Second,
it helps to acquire a lock onstdout
(orstderr
)
and usewriteln!
to print to it directly.
This prevents the system from locking and unlockingstdout
over and over again.#![allow(unused)] fn main() { use std::io::{self, Write}; let stdout = io::stdout(); // get the global stdout entity let mut handle = stdout.lock(); // acquire a lock on it writeln!(handle, "foo: {}", 42); // add `?` if you care about errors here }
You can also combine the two approaches.
Showing a progress bar
Some CLI applications run less than a second,
others take minutes or hours.
If you are writing one of the latter types of programs,
you might want to show the user that something is happening.
For this, you should try to print useful status updates,
ideally in a form that can be easily consumed.Using the indicatif crate,
you can add progress bars
and little spinners to your program.
Here’s a quick example:fn main() { let pb = indicatif::ProgressBar::new(100); for i in 0..100 { do_hard_work(); pb.println(format!("[+] finished #{}", i)); pb.inc(1); } pb.finish_with_message("done"); }
See the documentation
and examples
for more information.Logging
To make it easier to understand what is happening in our program,
we might want to add some log statements.
This is usually easy while writing your application.
But it will become super helpful when running this program again in half a year.
In some regard,
logging is the same as usingprintln!
,
except that you can specify the importance of a message.
The levels you can usually use are error, warn, info, debug, and trace
(error has the highest priority, trace the lowest).To add simple logging to your application,
you’ll need two things:
The log crate (this contains macros named after the log level)
and an adapter that actually writes the log output somewhere useful.
Having the ability to use log adapters is very flexible:
You can, for example, use them to write logs not only to the terminal
but also to syslog, or to a central log server.Since we are right now only concerned with writing a CLI application,
an easy adapter to use is env_logger.
It’s called “env” logger because you can
use an environment variable to specify which parts of your application
you want to log
(and at which level you want to log them).
It will prefix your log messages with a timestamp
and the module where the log messages come from.
Since libraries can also uselog
,
you easily configure their log output, too.Here’s a quick example:
use log::{info, warn}; fn main() { env_logger::init(); info!("starting up"); warn!("oops, nothing implemented!"); }
Assuming you have this file as
src/bin/output-log.rs
,
on Linux and macOS, you can run it like this:$ env RUST_LOG=info cargo run --bin output-log Finished dev [unoptimized + debuginfo] target(s) in 0.17s Running `target/debug/output-log` [2018-11-30T20:25:52Z INFO output_log] starting up [2018-11-30T20:25:52Z WARN output_log] oops, nothing implemented!
In Windows PowerShell, you can run it like this:
$ $env:RUST_LOG="info" $ cargo run --bin output-log Finished dev [unoptimized + debuginfo] target(s) in 0.17s Running `target/debug/output-log.exe` [2018-11-30T20:25:52Z INFO output_log] starting up [2018-11-30T20:25:52Z WARN output_log] oops, nothing implemented!
In Windows CMD, you can run it like this:
$ set RUST_LOG=info $ cargo run --bin output-log Finished dev [unoptimized + debuginfo] target(s) in 0.17s Running `target/debug/output-log.exe` [2018-11-30T20:25:52Z INFO output_log] starting up [2018-11-30T20:25:52Z WARN output_log] oops, nothing implemented!
RUST_LOG
is the name of the environment variable
you can use to set your log settings.
env_logger
also contains a builder
so you can programmatically adjust these settings,
and, for example, also show info level messages by default.There are a lot of alternative logging adapters out there,
and also alternatives or extensions tolog
.
If you know your application will have a lot to log,
make sure to review them,
and make your users’ life easier.
#[repr(transparent)]
pub struct Error { /* private fields */ }
Expand description
The Error
type, a wrapper around a dynamic error type.
Error
works a lot like Box<dyn std::error::Error>
, but with these
differences:
Error
requires that the error isSend
,Sync
, and'static
.Error
guarantees that a backtrace is available, even if the underlying
error type does not provide one.Error
is represented as a narrow pointer — exactly one word in
size instead of two.
Display representations
When you print an error object using “{}” or to_string(), only the outermost
underlying error or context is printed, not any of the lower level causes.
This is exactly as if you had called the Display impl of the error from
which you constructed your anyhow::Error.
Failed to read instrs from ./path/to/instrs.json
To print causes as well using anyhow’s default formatting of causes, use the
alternate selector “{:#}”.
Failed to read instrs from ./path/to/instrs.json: No such file or directory (os error 2)
The Debug format “{:?}” includes your backtrace if one was captured. Note
that this is the representation you get by default if you return an error
from fn main
instead of printing it explicitly yourself.
Error: Failed to read instrs from ./path/to/instrs.json
Caused by:
No such file or directory (os error 2)
and if there is a backtrace available:
Error: Failed to read instrs from ./path/to/instrs.json
Caused by:
No such file or directory (os error 2)
Stack backtrace:
0: <E as anyhow::context::ext::StdError>::ext_context
at /git/anyhow/src/backtrace.rs:26
1: core::result::Result<T,E>::map_err
at /git/rustc/src/libcore/result.rs:596
2: anyhow::context::<impl anyhow::Context<T,E> for core::result::Result<T,E>>::with_context
at /git/anyhow/src/context.rs:58
3: testing::main
at src/main.rs:5
4: std::rt::lang_start
at /git/rustc/src/libstd/rt.rs:61
5: main
6: __libc_start_main
7: _start
To see a conventional struct-style Debug representation, use “{:#?}”.
Error {
context: "Failed to read instrs from ./path/to/instrs.json",
source: Os {
code: 2,
kind: NotFound,
message: "No such file or directory",
},
}
If none of the built-in representations are appropriate and you would prefer
to render the error and its cause chain yourself, it can be done something
like this:
use anyhow::{Context, Result};
fn main() {
if let Err(err) = try_main() {
eprintln!("ERROR: {}", err);
err.chain().skip(1).for_each(|cause| eprintln!("because: {}", cause));
std::process::exit(1);
}
}
fn try_main() -> Result<()> {
...
}
impl Error
Create a new error object from any error type.
The error type must be threadsafe and 'static
, so that the Error
will be as well.
If the error type does not provide a backtrace, a backtrace will be
created here to ensure that a backtrace exists.
Create a new error object from a printable error message.
If the argument implements std::error::Error, prefer Error::new
instead which preserves the underlying error’s cause chain and
backtrace. If the argument may or may not implement std::error::Error
now or in the future, use anyhow!(err)
which handles either way
correctly.
Error::msg("...")
is equivalent to anyhow!("...")
but occasionally
convenient in places where a function is preferable over a macro, such
as iterator or stream combinators:
use anyhow::{Error, Result};
use futures::stream::{Stream, StreamExt, TryStreamExt};
async fn demo<S>(stream: S) -> Result<Vec<Output>>
where
S: Stream<Item = Input>,
{
stream
.then(ffi::do_some_work) // returns Result<Output, &str>
.map_err(Error::msg)
.try_collect()
.await
}
Wrap the error value with additional context.
For attaching context to a Result
as it is propagated, the
Context
extension trait may be more convenient than
this function.
The primary reason to use error.context(...)
instead of
result.context(...)
via the Context
trait would be if the context
needs to depend on some data held by the underlying error:
use anyhow::Result;
use std::fs::File;
use std::path::Path;
struct ParseError {
line: usize,
column: usize,
}
fn parse_impl(file: File) -> Result<T, ParseError> {
...
}
pub fn parse(path: impl AsRef<Path>) -> Result<T> {
let file = File::open(&path)?;
parse_impl(file).map_err(|error| {
let context = format!(
"only the first {} lines of {} are valid",
error.line, path.as_ref().display(),
);
anyhow::Error::new(error).context(context)
})
}
Get the backtrace for this Error.
In order for the backtrace to be meaningful, one of the two environment
variables RUST_LIB_BACKTRACE=1
or RUST_BACKTRACE=1
must be defined
and RUST_LIB_BACKTRACE
must not be 0
. Backtraces are somewhat
expensive to capture in Rust, so we don’t necessarily want to be
capturing them all over the place all the time.
- If you want panics and errors to both have backtraces, set
RUST_BACKTRACE=1
; - If you want only errors to have backtraces, set
RUST_LIB_BACKTRACE=1
; - If you want only panics to have backtraces, set
RUST_BACKTRACE=1
and
RUST_LIB_BACKTRACE=0
.
Stability
Standard library backtraces are only available on the nightly channel.
Tracking issue: rust-lang/rust#53487.
On stable compilers, this function is only available if the crate’s
“backtrace” feature is enabled, and will use the backtrace
crate as
the underlying backtrace implementation.
[dependencies]
anyhow = { version = "1.0", features = ["backtrace"] }
An iterator of the chain of source errors contained by this Error.
This iterator will visit every error in the cause chain of this error
object, beginning with the error that this error object was created
from.
Example
use anyhow::Error;
use std::io;
pub fn underlying_io_error_kind(error: &Error) -> Option<io::ErrorKind> {
for cause in error.chain() {
if let Some(io_error) = cause.downcast_ref::<io::Error>() {
return Some(io_error.kind());
}
}
None
}
The lowest level cause of this error — this error’s cause’s
cause’s cause etc.
The root cause is the last error in the iterator produced by
chain()
.
Returns true if E
is the type held by this error object.
For errors with context, this method returns true if E
matches the
type of the context C
or the type of the error on which the
context has been attached. For details about the interaction between
context and downcasting, see here.
Attempt to downcast the error object to a concrete type.
Downcast this error object by reference.
Example
// If the error was caused by redaction, then return a tombstone instead
// of the content.
match root_cause.downcast_ref::<DataStoreError>() {
Some(DataStoreError::Censored(_)) => Ok(Poll::Ready(REDACTED_CONTENT)),
None => Err(error),
}
Downcast this error object by mutable reference.
impl !RefUnwindSafe for Error
impl Send for Error
impl Sync for Error
impl Unpin for Error
impl !UnwindSafe for Error
impl<T> Any for Twhere
T: ‘static + ?Sized,
impl<T> Borrow<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> From<!> for T
impl<T> From<T> for T
impl<T, U> Into<U> for Twhere
U: From<T>,
Calls U::from(self)
.
That is, this conversion is whatever the implementation of
From<T> for U
chooses to do.
impl<T> ToString for Twhere
T: Display + ?Sized,
impl<T, U> TryFrom<U> for Twhere
U: Into<T>,
The type returned in the event of a conversion error.
Performs the conversion.
impl<T, U> TryInto<U> for Twhere
U: TryFrom<T>,
The type returned in the event of a conversion error.
Performs the conversion.
Error handling in Rust is very different if you’re coming from other languages. In languages like Java, JS, Python etc, you usually throw
exceptions and return
successful values. In Rust, you return something called a Result
.
The Result<T, E>
type is an enum that has two variants — Ok(T)
for successful value or Err(E)
for error value:
enum Result<T, E> {
Ok(T),
Err(E),
}
Returning errors instead of throwing them is a paradigm shift in error handling. If you’re new to Rust, there will be some friction initially as it requires you to reason about errors in a different way.
In this post, I’ll go through some common error handling patterns so you gradually become familiar with how things are done in Rust:
- Ignore the error
- Terminate the program
- Use a fallback value
- Bubble up the error
- Bubble up multiple errors
- Match boxed errors
- Libraries vs Applications
- Create custom errors
- Bubble up custom errors
- Match custom errors
Ignore the error
Let’s start with the simplest scenario where we just ignore the error. This sounds careless but has a couple of legitimate use cases:
- We’re prototyping our code and don’t want to spend time on error handling.
- We’re confident that the error won’t occur.
Let’s say that we’re reading a file which we’re pretty sure would be present:
use std::fs;
fn main() {
let content = fs::read_to_string("./Cargo.toml").unwrap();
println!("{}", content)
}
Even though we know that the file would be present, the compiler has no way of knowing that. So we use unwrap
to tell the compiler to trust us and return the value inside. If the read_to_string
function returns an Ok()
value, unwrap
will get the contents of Ok
and assign it to the content
variable. If it returns an error, it will “panic”. Panic either terminates the program or exits the current thread.
Note that unwrap
is used in quite a lot of Rust examples to skip error handling. This is mostly done for convenience and shouldn’t be used in real code as it is.
Terminate the program
Some errors cannot be handled or recovered from. In these cases, it’s better to fail fast by terminating the program.
Let’s use the same example as above — we’re reading a file which we’re sure to be present. Let’s imagine that, for this program, that file is absolutely important without which it won’t work properly. If for some reason, this file is absent, it’s better to terminate the program.
We can use unwrap
as before or use expect
— it’s same as unwrap
but lets us add extra error message.
use std::fs;
fn main() {
let content = fs::read_to_string("./Cargo.toml").expect("Can't read Cargo.toml");
println!("{}", content)
}
See also: panic!
Use a fallback value
In some cases, you can handle the error by falling back to a default value.
For example, let’s say we’re writing a server and the port it listens to can be configured using an environment variable. If the environment variable is not set, accessing that value would result in an error. But we can easily handle that by falling back to a default value.
use std::env;
fn main() {
let port = env::var("PORT").unwrap_or("3000".to_string());
println!("{}", port);
}
Here, we’ve used a variation of unwrap
called unwrap_or
which lets us supply default values.
See also: unwrap_or_else
, unwrap_or_default
Bubble up the error
When you don’t have enough context to handle the error, you can bubble up (propagate) the error to the caller function.
Here’s a contrived example which uses a webservice to get the current year:
use std::collections::HashMap;
fn main() {
match get_current_date() {
Ok(date) => println!("We've time travelled to {}!!", date),
Err(e) => eprintln!("Oh noes, we don't know which era we're in! :( n {}", e),
}
}
fn get_current_date() -> Result<String, reqwest::Error> {
let url = "https://postman-echo.com/time/object";
let result = reqwest::blocking::get(url);
let response = match result {
Ok(res) => res,
Err(err) => return Err(err),
};
let body = response.json::<HashMap<String, i32>>();
let json = match body {
Ok(json) => json,
Err(err) => return Err(err),
};
let date = json["years"].to_string();
Ok(date)
}
There are two function calls inside the get_current_date
function (get
and json
) that return Result
values. Since get_current_date
doesn’t have context of what to do when they return errors, it uses pattern matching to propagate the errors to main
.
Using pattern matching to handle multiple or nested errors can make your code “noisy”. Instead, we can rewrite the above code using the ?
operator:
use std::collections::HashMap;
fn main() {
match get_current_date() {
Ok(date) => println!("We've time travelled to {}!!", date),
Err(e) => eprintln!("Oh noes, we don't know which era we're in! :( n {}", e),
}
}
fn get_current_date() -> Result<String, reqwest::Error> {
let url = "https://postman-echo.com/time/object";
let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
let date = res["years"].to_string();
Ok(date)
}
This looks much cleaner!
The ?
operator is similar to unwrap
but instead of panicking, it propagates the error to the calling function. One thing to keep in mind is that we can use the ?
operator only for functions that return a Result
or Option
type.
Bubble up multiple errors
In the previous example, the get
and json
functions return a reqwest::Error
error which we’ve propagated using the ?
operator. But what if we’ve another function call that returned a different error value?
Let’s extend the previous example by returning a formatted date instead of the year:
+ use chrono::NaiveDate;
use std::collections::HashMap;
fn main() {
match get_current_date() {
Ok(date) => println!("We've time travelled to {}!!", date),
Err(e) => eprintln!("Oh noes, we don't know which era we're in! :( n {}", e),
}
}
fn get_current_date() -> Result<String, reqwest::Error> {
let url = "https://postman-echo.com/time/object";
let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
- let date = res["years"].to_string();
+ let formatted_date = format!("{}-{}-{}", res["years"], res["months"] + 1, res["date"]);
+ let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")?;
+ let date = parsed_date.format("%Y %B %d").to_string();
Ok(date)
}
The above code won’t compile as parse_from_str
returns a chrono::format::ParseError
error and not reqwest::Error
.
We can fix this by Box
ing the errors:
use chrono::NaiveDate;
use std::collections::HashMap;
fn main() {
match get_current_date() {
Ok(date) => println!("We've time travelled to {}!!", date),
Err(e) => eprintln!("Oh noes, we don't know which era we're in! :( n {}", e),
}
}
- fn get_current_date() -> Result<String, reqwest::Error> {
+ fn get_current_date() -> Result<String, Box<dyn std::error::Error>> {
let url = "https://postman-echo.com/time/object";
let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
let formatted_date = format!("{}-{}-{}", res["years"], res["months"] + 1, res["date"]);
let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")?;
let date = parsed_date.format("%Y %B %d").to_string();
Ok(date)
}
Returning a trait object Box<dyn std::error::Error>
is very convenient when we want to return multiple errors!
See also: anyhow
, eyre
Match boxed errors
So far, we’ve only printed the errors in the main
function but not handled them. If we want to handle and recover from boxed errors, we need to “downcast” them:
use chrono::NaiveDate;
use std::collections::HashMap;
fn main() {
match get_current_date() {
Ok(date) => println!("We've time travelled to {}!!", date),
- Err(e) => eprintln!("Oh noes, we don't know which era we're in! :( n {}", e),
+ Err(e) => {
+ eprintln!("Oh noes, we don't know which era we're in! :(");
+ if let Some(err) = e.downcast_ref::<reqwest::Error>() {
+ eprintln!("Request Error: {}", err)
+ } else if let Some(err) = e.downcast_ref::<chrono::format::ParseError>() {
+ eprintln!("Parse Error: {}", err)
+ }
+ }
}
}
fn get_current_date() -> Result<String, Box<dyn std::error::Error>> {
let url = "https://postman-echo.com/time/object";
let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
let formatted_date = format!("{}-{}-{}", res["years"], res["months"] + 1, res["date"]);
let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")?;
let date = parsed_date.format("%Y %B %d").to_string();
Ok(date)
}
Notice how we need to be aware of the implementation details (different errors inside) of get_current_date
to be able to downcast them inside main
.
See also: downcast
, downcast_mut
Applications vs Libraries
As mentioned previously, the downside to boxed errors is that if we want to handle the underlying errors, we need to be aware of the implementation details. When we return something as Box<dyn std::error::Error>
, the concrete type information is erased. To handle the different errors in different ways, we need to downcast them to concrete types and this casting can fail at runtime.
However, saying something is a “downside” is not very useful without context. A good rule of thumb is to question whether the code you’re writing is an “application” or a “library”:
Application
- The code you’re writing would be used by end users.
- Most errors generated by application code won’t be handled but instead logged or reported to the user.
- It’s okay to use boxed errors.
Library
- The code you’re writing would be consumed by other code. A “library” can be open source crates, internal libraries etc
- Errors are part of your library’s API, so your consumers know what errors to expect and recover from.
- Errors from your library are often handled by your consumers so they need to be structured and easy to perform exhaustive match on.
- If you return boxed errors, then your consumers need to be aware of the errors created by your code, your dependencies, and so on!
- Instead of boxed errors, we can return custom errors.
Create custom errors
For library code, we can convert all the errors to our own custom error and propagate them instead of boxed errors. In our example, we currently have two errors — reqwest::Error
and chrono::format::ParseError
. We can convert them to MyCustomError::HttpError
and MyCustomError::ParseError
respectively.
Let’s start by creating an enum to hold our two error variants:
// error.rs
pub enum MyCustomError {
HttpError,
ParseError,
}
The Error
trait requires us to implement the Debug
and Display
traits:
// error.rs
use std::fmt;
#[derive(Debug)]
pub enum MyCustomError {
HttpError,
ParseError,
}
impl std::error::Error for MyCustomError {}
impl fmt::Display for MyCustomError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
MyCustomError::HttpError => write!(f, "HTTP Error"),
MyCustomError::ParseError => write!(f, "Parse Error"),
}
}
}
We’ve created our own custom error!
This is obviously a simple example as the error variants don’t contain much information about the error. But this should be sufficient as a starting point for creating more complex and realistic custom errors. Here are some real life examples: ripgrep, reqwest, csv and serde_json
See also: thiserror
, snafu
Bubble up custom errors
Let’s update our code to return the custom errors we just created:
// main.rs
+ mod error;
use chrono::NaiveDate;
+ use error::MyCustomError;
use std::collections::HashMap;
fn main() {
// skipped, will get back later
}
- fn get_current_date() -> Result<String, Box<dyn std::error::Error>> {
+ fn get_current_date() -> Result<String, MyCustomError> {
let url = "https://postman-echo.com/time/object";
- let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
+ let res = reqwest::blocking::get(url)
+ .map_err(|_| MyCustomError::HttpError)?
+ .json::<HashMap<String, i32>>()
+ .map_err(|_| MyCustomError::HttpError)?;
let formatted_date = format!("{}-{}-{}", res["years"], res["months"] + 1, res["date"]);
- let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")?;
+ let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")
+ .map_err(|_| MyCustomError::ParseError)?;
let date = parsed_date.format("%Y %B %d").to_string();
Ok(date)
}
Notice how we’re using map_err
to convert the error from one type to another type.
But things got verbose as a result — our function is littered with these map_err
calls. We can implement the From
trait to automatically coerce the error types when we use the ?
operator:
// error.rs
use std::fmt;
#[derive(Debug)]
pub enum MyCustomError {
HttpError,
ParseError,
}
impl std::error::Error for MyCustomError {}
impl fmt::Display for MyCustomError {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
match self {
MyCustomError::HttpError => write!(f, "HTTP Error"),
MyCustomError::ParseError => write!(f, "Parse Error"),
}
}
}
+ impl From<reqwest::Error> for MyCustomError {
+ fn from(_: reqwest::Error) -> Self {
+ MyCustomError::HttpError
+ }
+ }
+ impl From<chrono::format::ParseError> for MyCustomError {
+ fn from(_: chrono::format::ParseError) -> Self {
+ MyCustomError::ParseError
+ }
+ }
// main.rs
mod error;
use chrono::NaiveDate;
use error::MyCustomError;
use std::collections::HashMap;
fn main() {
// skipped, will get back later
}
fn get_current_date() -> Result<String, MyCustomError> {
let url = "https://postman-echo.com/time/object";
- let res = reqwest::blocking::get(url)
- .map_err(|_| MyCustomError::HttpError)?
- .json::<HashMap<String, i32>>()
- .map_err(|_| MyCustomError::HttpError)?;
+ let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
let formatted_date = format!("{}-{}-{}", res["years"], res["months"] + 1, res["date"]);
- let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")
- .map_err(|_| MyCustomError::ParseError)?;
+ let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")?;
let date = parsed_date.format("%Y %B %d").to_string();
Ok(date)
}
We’ve removed map_err
and the code looks much cleaner!
However, From
trait is not magic and there are times when we need to use map_err
. In the above example, we’ve moved the type conversion from inside the get_current_date
function to the From<X> for MyCustomError
implementation. This works well when the information needed to convert from one error to MyCustomError
can be obtained from the original error object. If not, we need to use map_err
inside get_current_date
.
Match custom errors
We’ve ignored the changes in main
until now, here’s how we can handle the custom errors:
// main.rs
mod error;
use chrono::NaiveDate;
use error::MyCustomError;
use std::collections::HashMap;
fn main() {
match get_current_date() {
Ok(date) => println!("We've time travelled to {}!!", date),
Err(e) => {
eprintln!("Oh noes, we don't know which era we're in! :(");
- if let Some(err) = e.downcast_ref::<reqwest::Error>() {
- eprintln!("Request Error: {}", err)
- } else if let Some(err) = e.downcast_ref::<chrono::format::ParseError>() {
- eprintln!("Parse Error: {}", err)
- }
+ match e {
+ MyCustomError::HttpError => eprintln!("Request Error: {}", e),
+ MyCustomError::ParseError => eprintln!("Parse Error: {}", e),
+ }
}
}
}
fn get_current_date() -> Result<String, MyCustomError> {
let url = "https://postman-echo.com/time/object";
let res = reqwest::blocking::get(url)?.json::<HashMap<String, i32>>()?;
let formatted_date = format!("{}-{}-{}", res["years"], res["months"] + 1, res["date"]);
let parsed_date = NaiveDate::parse_from_str(formatted_date.as_str(), "%Y-%m-%d")?;
let date = parsed_date.format("%Y %B %d").to_string();
Ok(date)
}
Notice how unlike boxed errors, we can actually match on the variants inside MyCustomError
enum.
Conclusion
Thanks for reading! I hope this post was helpful in introducing the basics of error handling in Rust. I’ve added the examples to a repo in GitHub which you can use for practice. If you’ve more questions, please contact me at sheshbabu [at] gmail.com. Feel free to follow me in Twitter for more posts like this
Struct std::io::Error
pub struct Error { /* fields omitted */ }
The error type for I/O operations of the Read
, Write
, Seek
, and associated traits.
Errors mostly originate from the underlying OS, but custom instances of Error
can be created with crafted error messages and a particular value of ErrorKind
.
impl Error
[src]
pub fn new<E>(kind: ErrorKind, error: E) -> Error where
E: Into<Box<dyn Error + Send + Sync>>,
[src]
E: Into<Box<dyn Error + Send + Sync>>,
Creates a new I/O error from a known kind of error as well as an arbitrary error payload.
This function is used to generically create I/O errors which do not originate from the OS itself. The error
argument is an arbitrary payload which will be contained in this Error
.
use std::io::{Error, ErrorKind}; // errors can be created from strings let custom_error = Error::new(ErrorKind::Other, "oh no!"); // errors can also be created from other errors let custom_error2 = Error::new(ErrorKind::Interrupted, custom_error);
pub fn last_os_error() -> Error
[src]
Returns an error representing the last OS error which occurred.
This function reads the value of errno
for the target platform (e.g. GetLastError
on Windows) and will return a corresponding instance of Error
for the error code.
use std::io::Error; println!("last OS error: {:?}", Error::last_os_error());
pub fn from_raw_os_error(code: i32) -> Error
[src]
Creates a new instance of an Error
from a particular OS error code.
On Linux:
use std::io; let error = io::Error::from_raw_os_error(22); assert_eq!(error.kind(), io::ErrorKind::InvalidInput);
On Windows:
use std::io; let error = io::Error::from_raw_os_error(10022); assert_eq!(error.kind(), io::ErrorKind::InvalidInput);
pub fn raw_os_error(&self) -> Option<i32>
[src]
Returns the OS error that this error represents (if any).
If this Error
was constructed via last_os_error
or from_raw_os_error
, then this function will return Some
, otherwise it will return None
.
use std::io::{Error, ErrorKind}; fn print_os_error(err: &Error) { if let Some(raw_os_err) = err.raw_os_error() { println!("raw OS error: {:?}", raw_os_err); } else { println!("Not an OS error"); } } fn main() { // Will print "raw OS error: ...". print_os_error(&Error::last_os_error()); // Will print "Not an OS error". print_os_error(&Error::new(ErrorKind::Other, "oh no!")); }
pub fn get_ref(&self) -> Option<&(dyn Error + Send + Sync + 'static)>
[src]1.3.0
Returns a reference to the inner error wrapped by this error (if any).
If this Error
was constructed via new
then this function will return Some
, otherwise it will return None
.
use std::io::{Error, ErrorKind}; fn print_error(err: &Error) { if let Some(inner_err) = err.get_ref() { println!("Inner error: {:?}", inner_err); } else { println!("No inner error"); } } fn main() { // Will print "No inner error". print_error(&Error::last_os_error()); // Will print "Inner error: ...". print_error(&Error::new(ErrorKind::Other, "oh no!")); }
pub fn get_mut(&mut self) -> Option<&mut (dyn Error + Send + Sync + 'static)>
[src]1.3.0
Returns a mutable reference to the inner error wrapped by this error (if any).
If this Error
was constructed via new
then this function will return Some
, otherwise it will return None
.
use std::io::{Error, ErrorKind}; use std::{error, fmt}; use std::fmt::Display; #[derive(Debug)] struct MyError { v: String, } impl MyError { fn new() -> MyError { MyError { v: "oh no!".to_string() } } fn change_message(&mut self, new_message: &str) { self.v = new_message.to_string(); } } impl error::Error for MyError {} impl Display for MyError { fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { write!(f, "MyError: {}", &self.v) } } fn change_error(mut err: Error) -> Error { if let Some(inner_err) = err.get_mut() { inner_err.downcast_mut::<MyError>().unwrap().change_message("I've been changed!"); } err } fn print_error(err: &Error) { if let Some(inner_err) = err.get_ref() { println!("Inner error: {}", inner_err); } else { println!("No inner error"); } } fn main() { // Will print "No inner error". print_error(&change_error(Error::last_os_error())); // Will print "Inner error: ...". print_error(&change_error(Error::new(ErrorKind::Other, MyError::new()))); }
pub fn into_inner(self) -> Option<Box<dyn Error + Send + Sync>>
[src]1.3.0
Consumes the Error
, returning its inner error (if any).
If this Error
was constructed via new
then this function will return Some
, otherwise it will return None
.
use std::io::{Error, ErrorKind}; fn print_error(err: Error) { if let Some(inner_err) = err.into_inner() { println!("Inner error: {}", inner_err); } else { println!("No inner error"); } } fn main() { // Will print "No inner error". print_error(Error::last_os_error()); // Will print "Inner error: ...". print_error(Error::new(ErrorKind::Other, "oh no!")); }
pub fn kind(&self) -> ErrorKind
[src]
Returns the corresponding ErrorKind
for this error.
use std::io::{Error, ErrorKind}; fn print_error(err: Error) { println!("{:?}", err.kind()); } fn main() { // Will print "Other". print_error(Error::last_os_error()); // Will print "AddrInUse". print_error(Error::new(ErrorKind::AddrInUse, "oh no!")); }
impl Debug for Error
[src]
impl Display for Error
[src]
impl Error for Error
[src]
fn description(&self) -> &str
[src]
👎 Deprecated since 1.42.0: use the Display impl or to_string()
if let Err(e) = "xc".parse::<u32>() { // Print
e itself, no need for description(). eprintln!("Error: {}", e); }
Read more
fn cause(&self) -> Option<&dyn Error>
[src]
👎 Deprecated since 1.33.0: replaced by Error::source, which can support downcasting
fn source(&self) -> Option<&(dyn Error + 'static)>
[src]
The lower-level source of this error, if any. Read more
fn backtrace(&self) -> Option<&Backtrace>
[src]
🔬 This is a nightly-only experimental API. (backtrace #53487)
Returns a stack backtrace, if available, of where this error occurred. Read more
impl From<ErrorKind> for Error
[src]1.14.0
Intended for use for errors not exposed to the user, where allocating onto the heap (for normal construction via Error::new) is too costly.
fn from(kind: ErrorKind) -> Error
[src]
Converts an ErrorKind
into an Error
.
This conversion allocates a new error with a simple representation of error kind.
use std::io::{Error, ErrorKind}; let not_found = ErrorKind::NotFound; let error = Error::from(not_found); assert_eq!("entity not found", format!("{}", error));
impl<W> From<IntoInnerError<W>> for Error
[src]
impl From<NulError> for Error
[src]
impl !RefUnwindSafe for Error
impl Send for Error
impl Sync for Error
impl Unpin for Error
impl !UnwindSafe for Error
impl<T> Any for T where
T: 'static + ?Sized,
[src]
T: 'static + ?Sized,
impl<T> Borrow<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow(&self) -> &Tⓘ
Notable traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized,
type Output = <F as Future>::Output;
impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized,
type Item = <I as Iterator>::Item;
impl<R: Read + ?Sized, '_> Read for &'_ mut R
impl<W: Write + ?Sized, '_> Write for &'_ mut W
[src]
Notable traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where F: Unpin + Future + ?Sized, type Output = <F as Future>::Output; impl<'_, I> Iterator for &'_ mut I where I: Iterator + ?Sized, type Item = <I as Iterator>::Item; impl<R: Read + ?Sized, '_> Read for &'_ mut R impl<W: Write + ?Sized, '_> Write for &'_ mut W
Immutably borrows from an owned value. Read more
impl<T> BorrowMut<T> for T where
T: ?Sized,
[src]
T: ?Sized,
fn borrow_mut(&mut self) -> &mut Tⓘ
Notable traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where
F: Unpin + Future + ?Sized,
type Output = <F as Future>::Output;
impl<'_, I> Iterator for &'_ mut I where
I: Iterator + ?Sized,
type Item = <I as Iterator>::Item;
impl<R: Read + ?Sized, '_> Read for &'_ mut R
impl<W: Write + ?Sized, '_> Write for &'_ mut W
[src]
Notable traits for &'_ mut F
impl<'_, F> Future for &'_ mut F where F: Unpin + Future + ?Sized, type Output = <F as Future>::Output; impl<'_, I> Iterator for &'_ mut I where I: Iterator + ?Sized, type Item = <I as Iterator>::Item; impl<R: Read + ?Sized, '_> Read for &'_ mut R impl<W: Write + ?Sized, '_> Write for &'_ mut W
Mutably borrows from an owned value. Read more
impl<T> From<T> for T
[src]
fn from(t: T) -> T
[src]
Performs the conversion.
impl<T, U> Into<U> for T where
U: From<T>,
[src]
U: From<T>,
fn into(self) -> U
[src]
Performs the conversion.
impl<T> ToString for T where
T: Display + ?Sized,
[src]
T: Display + ?Sized,
impl<T, U> TryFrom<U> for T where
U: Into<T>,
[src]
U: Into<T>,
impl<T, U> TryInto<U> for T where
U: TryFrom<T>,
[src]
U: TryFrom<T>,