56 lines
2 KiB
Rust
56 lines
2 KiB
Rust
// Copyright 2014 The Rust Project Developers. See the COPYRIGHT
|
|
// file at the top-level directory of this distribution and at
|
|
// http://rust-lang.org/COPYRIGHT.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
|
|
// http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
|
|
// <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
|
|
// option. This file may not be copied, modified, or distributed
|
|
// except according to those terms.
|
|
|
|
//! Traits for working with Errors.
|
|
//!
|
|
//! # The `Error` trait
|
|
//!
|
|
//! `Error` is a trait representing the basic expectations for error values,
|
|
//! i.e. values of type `E` in `Result<T, E>`. At a minimum, errors must provide
|
|
//! a description, but they may optionally provide additional detail (via
|
|
//! `Display`) and cause chain information:
|
|
//!
|
|
//! ```
|
|
//! use std::fmt::Display;
|
|
//!
|
|
//! trait Error: Display {
|
|
//! fn description(&self) -> &str;
|
|
//!
|
|
//! fn cause(&self) -> Option<&Error> { None }
|
|
//! }
|
|
//! ```
|
|
//!
|
|
//! The `cause` method is generally used when errors cross "abstraction
|
|
//! boundaries", i.e. when a one module must report an error that is "caused"
|
|
//! by an error from a lower-level module. This setup makes it possible for the
|
|
//! high-level module to provide its own errors that do not commit to any
|
|
//! particular implementation, but also reveal some of its implementation for
|
|
//! debugging via `cause` chains.
|
|
|
|
#![stable(feature = "rust1", since = "1.0.0")]
|
|
|
|
use prelude::*;
|
|
use fmt::{Debug, Display};
|
|
|
|
/// Base functionality for all errors in Rust.
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
pub trait Error: Debug + Display {
|
|
/// A short description of the error.
|
|
///
|
|
/// The description should not contain newlines or sentence-ending
|
|
/// punctuation, to facilitate embedding in larger user-facing
|
|
/// strings.
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
fn description(&self) -> &str;
|
|
|
|
/// The lower-level cause of this error, if any.
|
|
#[stable(feature = "rust1", since = "1.0.0")]
|
|
fn cause(&self) -> Option<&Error> { None }
|
|
}
|