src/libstd/error.rs

   1 // Copyright 2014 The Rust Project Developers. See the COPYRIGHT
   2 // file at the top-level directory of this distribution and at
   3 // http://rust-lang.org/COPYRIGHT.
   4 //
   5 // Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
   6 // http://www.apache.org/licenses/LICENSE-2.0> or the MIT license
   7 // <LICENSE-MIT or http://opensource.org/licenses/MIT>, at your
   8 // option. This file may not be copied, modified, or distributed
   9 // except according to those terms.
  10
  11 //! Traits for working with Errors.
  12 //!
  13 //! # The `Error` trait
  14 //!
  15 //! `Error` is a trait representing the basic expectations for error values,
  16 //! i.e. values of type `E` in `Result<T, E>`. At a minimum, errors must provide
  17 //! a description, but they may optionally provide additional detail and cause
  18 //! chain information:
  19 //!
  20 //! ```
  21 //! trait Error {
  22 //!     fn description(&self) -> &str;
  23 //!
  24 //!     fn detail(&self) -> Option<String> { None }
  25 //!     fn cause(&self) -> Option<&Error> { None }
  26 //! }
  27 //! ```
  28 //!
  29 //! The `cause` method is generally used when errors cross "abstraction
  30 //! boundaries", i.e.  when a one module must report an error that is "caused"
  31 //! by an error from a lower-level module. This setup makes it possible for the
  32 //! high-level module to provide its own errors that do not commit to any
  33 //! particular implementation, but also reveal some of its implementation for
  34 //! debugging via `cause` chains.
  35 //!
  36 //! # The `FromError` trait
  37 //!
  38 //! `FromError` is a simple trait that expresses conversions between different
  39 //! error types. To provide maximum flexibility, it does not require either of
  40 //! the types to actually implement the `Error` trait, although this will be the
  41 //! common case.
  42 //!
  43 //! The main use of this trait is in the `try!` macro, which uses it to
  44 //! automatically convert a given error to the error specified in a function's
  45 //! return type.
  46 //!
  47 //! For example,
  48 //!
  49 //! ```
  50 //! use std::error::FromError;
  51 //! use std::io::{File, IoError};
  52 //! use std::os::{MemoryMap, MapError};
  53 //! use std::path::Path;
  54 //!
  55 //! enum MyError {
  56 //!     Io(IoError),
  57 //!     Map(MapError)
  58 //! }
  59 //!
  60 //! impl FromError<IoError> for MyError {
  61 //!     fn from_error(err: IoError) -> MyError {
  62 //!         MyError::Io(err)
  63 //!     }
  64 //! }
  65 //!
  66 //! impl FromError<MapError> for MyError {
  67 //!     fn from_error(err: MapError) -> MyError {
  68 //!         MyError::Map(err)
  69 //!     }
  70 //! }
  71 //!
  72 //! #[allow(unused_variables)]
  73 //! fn open_and_map() -> Result<(), MyError> {
  74 //!     let f = try!(File::open(&Path::new("foo.txt")));
  75 //!     let m = try!(MemoryMap::new(0, &[]));
  76 //!     // do something interesting here...
  77 //!     Ok(())
  78 //! }
  79 //! ```
  80
  81 #![stable]
  82
  83 use prelude::v1::*;
  84
  85 use str::Utf8Error;
  86 use string::{FromUtf8Error, FromUtf16Error};
  87
  88 /// Base functionality for all errors in Rust.
  89 #[unstable = "the exact API of this trait may change"]
  90 pub trait Error {
  91     /// A short description of the error; usually a static string.
  92     fn description(&self) -> &str;
  93
  94     /// A detailed description of the error, usually including dynamic information.
  95     fn detail(&self) -> Option<String> { None }
  96
  97     /// The lower-level cause of this error, if any.
  98     fn cause(&self) -> Option<&Error> { None }
  99 }
 100
 101 /// A trait for types that can be converted from a given error type `E`.
 102 #[stable]
 103 pub trait FromError<E> {
 104     /// Perform the conversion.
 105     fn from_error(err: E) -> Self;
 106 }
 107
 108 // Any type is convertable from itself
 109 #[stable]
 110 impl<E> FromError<E> for E {
 111     fn from_error(err: E) -> E {
 112         err
 113     }
 114 }
 115
 116 #[stable]
 117 impl Error for Utf8Error {
 118     fn description(&self) -> &str {
 119         match *self {
 120             Utf8Error::TooShort => "invalid utf-8: not enough bytes",
 121             Utf8Error::InvalidByte(..) => "invalid utf-8: corrupt contents",
 122         }
 123     }
 124
 125     fn detail(&self) -> Option<String> { Some(self.to_string()) }
 126 }
 127
 128 #[stable]
 129 impl Error for FromUtf8Error {
 130     fn description(&self) -> &str { "invalid utf-8" }
 131     fn detail(&self) -> Option<String> { Some(self.to_string()) }
 132 }
 133
 134 #[stable]
 135 impl Error for FromUtf16Error {
 136     fn description(&self) -> &str { "invalid utf-16" }
 137 }