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 (via
  18 //! [`Display`]) and cause chain information:
  19 //!
  20 //! ```
  21 //! use std::fmt::Display;
  22 //!
  23 //! trait Error: Display {
  24 //!     fn description(&self) -> &str;
  25 //!
  26 //!     fn cause(&self) -> Option<&Error> { None }
  27 //! }
  28 //! ```
  29 //!
  30 //! The [`cause`] method is generally used when errors cross "abstraction
  31 //! boundaries", i.e.  when a one module must report an error that is "caused"
  32 //! by an error from a lower-level module. This setup makes it possible for the
  33 //! high-level module to provide its own errors that do not commit to any
  34 //! particular implementation, but also reveal some of its implementation for
  35 //! debugging via [`cause`] chains.
  36 //!
  37 //! [`Result<T, E>`]: ../result/enum.Result.html
  38 //! [`Display`]: ../fmt/trait.Display.html
  39 //! [`cause`]: trait.Error.html#method.cause
  40
  41 #![stable(feature = "rust1", since = "1.0.0")]
  42
  43 // A note about crates and the facade:
  44 //
  45 // Originally, the `Error` trait was defined in libcore, and the impls
  46 // were scattered about. However, coherence objected to this
  47 // arrangement, because to create the blanket impls for `Box` required
  48 // knowing that `&str: !Error`, and we have no means to deal with that
  49 // sort of conflict just now. Therefore, for the time being, we have
  50 // moved the `Error` trait into libstd. As we evolve a sol'n to the
  51 // coherence challenge (e.g., specialization, neg impls, etc) we can
  52 // reconsider what crate these items belong in.
  53
  54 use any::TypeId;
  55 use cell;
  56 use char;
  57 use fmt::{self, Debug, Display};
  58 use mem::transmute;
  59 use num;
  60 use str;
  61 use string;
  62
  63 /// Base functionality for all errors in Rust.
  64 #[stable(feature = "rust1", since = "1.0.0")]
  65 pub trait Error: Debug + Display {
  66     /// A short description of the error.
  67     ///
  68     /// The description should only be used for a simple message.
  69     /// It should not contain newlines or sentence-ending punctuation,
  70     /// to facilitate embedding in larger user-facing strings.
  71     /// For showing formatted error messages with more information see
  72     /// [`Display`].
  73     ///
  74     /// [`Display`]: ../fmt/trait.Display.html
  75     ///
  76     /// # Examples
  77     ///
  78     /// ```
  79     /// use std::error::Error;
  80     ///
  81     /// match "xc".parse::<u32>() {
  82     ///     Err(e) => {
  83     ///         println!("Error: {}", e.description());
  84     ///     }
  85     ///     _ => println!("No error"),
  86     /// }
  87     /// ```
  88     #[stable(feature = "rust1", since = "1.0.0")]
  89     fn description(&self) -> &str;
  90
  91     /// The lower-level cause of this error, if any.
  92     ///
  93     /// # Examples
  94     ///
  95     /// ```
  96     /// use std::error::Error;
  97     /// use std::fmt;
  98     ///
  99     /// #[derive(Debug)]
 100     /// struct SuperError {
 101     ///     side: SuperErrorSideKick,
 102     /// }
 103     ///
 104     /// impl fmt::Display for SuperError {
 105     ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 106     ///         write!(f, "SuperError is here!")
 107     ///     }
 108     /// }
 109     ///
 110     /// impl Error for SuperError {
 111     ///     fn description(&self) -> &str {
 112     ///         "I'm the superhero of errors"
 113     ///     }
 114     ///
 115     ///     fn cause(&self) -> Option<&Error> {
 116     ///         Some(&self.side)
 117     ///     }
 118     /// }
 119     ///
 120     /// #[derive(Debug)]
 121     /// struct SuperErrorSideKick;
 122     ///
 123     /// impl fmt::Display for SuperErrorSideKick {
 124     ///     fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 125     ///         write!(f, "SuperErrorSideKick is here!")
 126     ///     }
 127     /// }
 128     ///
 129     /// impl Error for SuperErrorSideKick {
 130     ///     fn description(&self) -> &str {
 131     ///         "I'm SuperError side kick"
 132     ///     }
 133     /// }
 134     ///
 135     /// fn get_super_error() -> Result<(), SuperError> {
 136     ///     Err(SuperError { side: SuperErrorSideKick })
 137     /// }
 138     ///
 139     /// fn main() {
 140     ///     match get_super_error() {
 141     ///         Err(e) => {
 142     ///             println!("Error: {}", e.description());
 143     ///             println!("Caused by: {}", e.cause().unwrap());
 144     ///         }
 145     ///         _ => println!("No error"),
 146     ///     }
 147     /// }
 148     /// ```
 149     #[stable(feature = "rust1", since = "1.0.0")]
 150     fn cause(&self) -> Option<&Error> { None }
 151
 152     /// Get the `TypeId` of `self`
 153     #[doc(hidden)]
 154     #[unstable(feature = "error_type_id",
 155                reason = "unclear whether to commit to this public implementation detail",
 156                issue = "27745")]
 157     fn type_id(&self) -> TypeId where Self: 'static {
 158         TypeId::of::<Self>()
 159     }
 160 }
 161
 162 #[stable(feature = "rust1", since = "1.0.0")]
 163 impl<'a, E: Error + 'a> From<E> for Box<Error + 'a> {
 164     fn from(err: E) -> Box<Error + 'a> {
 165         Box::new(err)
 166     }
 167 }
 168
 169 #[stable(feature = "rust1", since = "1.0.0")]
 170 impl<'a, E: Error + Send + Sync + 'a> From<E> for Box<Error + Send + Sync + 'a> {
 171     fn from(err: E) -> Box<Error + Send + Sync + 'a> {
 172         Box::new(err)
 173     }
 174 }
 175
 176 #[stable(feature = "rust1", since = "1.0.0")]
 177 impl From<String> for Box<Error + Send + Sync> {
 178     fn from(err: String) -> Box<Error + Send + Sync> {
 179         #[derive(Debug)]
 180         struct StringError(String);
 181
 182         impl Error for StringError {
 183             fn description(&self) -> &str { &self.0 }
 184         }
 185
 186         impl Display for StringError {
 187             fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 188                 Display::fmt(&self.0, f)
 189             }
 190         }
 191
 192         Box::new(StringError(err))
 193     }
 194 }
 195
 196 #[stable(feature = "string_box_error", since = "1.6.0")]
 197 impl From<String> for Box<Error> {
 198     fn from(str_err: String) -> Box<Error> {
 199         let err1: Box<Error + Send + Sync> = From::from(str_err);
 200         let err2: Box<Error> = err1;
 201         err2
 202     }
 203 }
 204
 205 #[stable(feature = "rust1", since = "1.0.0")]
 206 impl<'a, 'b> From<&'b str> for Box<Error + Send + Sync + 'a> {
 207     fn from(err: &'b str) -> Box<Error + Send + Sync + 'a> {
 208         From::from(String::from(err))
 209     }
 210 }
 211
 212 #[stable(feature = "string_box_error", since = "1.6.0")]
 213 impl<'a> From<&'a str> for Box<Error> {
 214     fn from(err: &'a str) -> Box<Error> {
 215         From::from(String::from(err))
 216     }
 217 }
 218
 219 #[unstable(feature = "never_type_impls", issue = "35121")]
 220 impl Error for ! {
 221     fn description(&self) -> &str { *self }
 222 }
 223
 224 #[stable(feature = "rust1", since = "1.0.0")]
 225 impl Error for str::ParseBoolError {
 226     fn description(&self) -> &str { "failed to parse bool" }
 227 }
 228
 229 #[stable(feature = "rust1", since = "1.0.0")]
 230 impl Error for str::Utf8Error {
 231     fn description(&self) -> &str {
 232         "invalid utf-8: corrupt contents"
 233     }
 234 }
 235
 236 #[stable(feature = "rust1", since = "1.0.0")]
 237 impl Error for num::ParseIntError {
 238     fn description(&self) -> &str {
 239         self.__description()
 240     }
 241 }
 242
 243 #[unstable(feature = "try_from", issue = "33417")]
 244 impl Error for num::TryFromIntError {
 245     fn description(&self) -> &str {
 246         self.__description()
 247     }
 248 }
 249
 250 #[stable(feature = "rust1", since = "1.0.0")]
 251 impl Error for num::ParseFloatError {
 252     fn description(&self) -> &str {
 253         self.__description()
 254     }
 255 }
 256
 257 #[stable(feature = "rust1", since = "1.0.0")]
 258 impl Error for string::FromUtf8Error {
 259     fn description(&self) -> &str {
 260         "invalid utf-8"
 261     }
 262 }
 263
 264 #[stable(feature = "rust1", since = "1.0.0")]
 265 impl Error for string::FromUtf16Error {
 266     fn description(&self) -> &str {
 267         "invalid utf-16"
 268     }
 269 }
 270
 271 #[stable(feature = "str_parse_error2", since = "1.8.0")]
 272 impl Error for string::ParseError {
 273     fn description(&self) -> &str {
 274         match *self {}
 275     }
 276 }
 277
 278 #[stable(feature = "decode_utf16", since = "1.9.0")]
 279 impl Error for char::DecodeUtf16Error {
 280     fn description(&self) -> &str {
 281         "unpaired surrogate found"
 282     }
 283 }
 284
 285 #[stable(feature = "box_error", since = "1.8.0")]
 286 impl<T: Error> Error for Box<T> {
 287     fn description(&self) -> &str {
 288         Error::description(&**self)
 289     }
 290
 291     fn cause(&self) -> Option<&Error> {
 292         Error::cause(&**self)
 293     }
 294 }
 295
 296 #[stable(feature = "fmt_error", since = "1.11.0")]
 297 impl Error for fmt::Error {
 298     fn description(&self) -> &str {
 299         "an error occurred when formatting an argument"
 300     }
 301 }
 302
 303 #[stable(feature = "try_borrow", since = "1.13.0")]
 304 impl Error for cell::BorrowError {
 305     fn description(&self) -> &str {
 306         "already mutably borrowed"
 307     }
 308 }
 309
 310 #[stable(feature = "try_borrow", since = "1.13.0")]
 311 impl Error for cell::BorrowMutError {
 312     fn description(&self) -> &str {
 313         "already borrowed"
 314     }
 315 }
 316
 317 #[unstable(feature = "try_from", issue = "33417")]
 318 impl Error for char::CharTryFromError {
 319     fn description(&self) -> &str {
 320         "converted integer out of range for `char`"
 321     }
 322 }
 323
 324 #[stable(feature = "char_from_str", since = "1.19.0")]
 325 impl Error for char::ParseCharError {
 326     fn description(&self) -> &str {
 327         self.__description()
 328     }
 329 }
 330
 331
 332 // copied from any.rs
 333 impl Error + 'static {
 334     /// Returns true if the boxed type is the same as `T`
 335     #[stable(feature = "error_downcast", since = "1.3.0")]
 336     #[inline]
 337     pub fn is<T: Error + 'static>(&self) -> bool {
 338         // Get TypeId of the type this function is instantiated with
 339         let t = TypeId::of::<T>();
 340
 341         // Get TypeId of the type in the trait object
 342         let boxed = self.type_id();
 343
 344         // Compare both TypeIds on equality
 345         t == boxed
 346     }
 347
 348     /// Returns some reference to the boxed value if it is of type `T`, or
 349     /// `None` if it isn't.
 350     #[stable(feature = "error_downcast", since = "1.3.0")]
 351     #[inline]
 352     pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
 353         if self.is::<T>() {
 354             unsafe {
 355                 Some(&*(self as *const Error as *const T))
 356             }
 357         } else {
 358             None
 359         }
 360     }
 361
 362     /// Returns some mutable reference to the boxed value if it is of type `T`, or
 363     /// `None` if it isn't.
 364     #[stable(feature = "error_downcast", since = "1.3.0")]
 365     #[inline]
 366     pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
 367         if self.is::<T>() {
 368             unsafe {
 369                 Some(&mut *(self as *mut Error as *mut T))
 370             }
 371         } else {
 372             None
 373         }
 374     }
 375 }
 376
 377 impl Error + 'static + Send {
 378     /// Forwards to the method defined on the type `Any`.
 379     #[stable(feature = "error_downcast", since = "1.3.0")]
 380     #[inline]
 381     pub fn is<T: Error + 'static>(&self) -> bool {
 382         <Error + 'static>::is::<T>(self)
 383     }
 384
 385     /// Forwards to the method defined on the type `Any`.
 386     #[stable(feature = "error_downcast", since = "1.3.0")]
 387     #[inline]
 388     pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
 389         <Error + 'static>::downcast_ref::<T>(self)
 390     }
 391
 392     /// Forwards to the method defined on the type `Any`.
 393     #[stable(feature = "error_downcast", since = "1.3.0")]
 394     #[inline]
 395     pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
 396         <Error + 'static>::downcast_mut::<T>(self)
 397     }
 398 }
 399
 400 impl Error + 'static + Send + Sync {
 401     /// Forwards to the method defined on the type `Any`.
 402     #[stable(feature = "error_downcast", since = "1.3.0")]
 403     #[inline]
 404     pub fn is<T: Error + 'static>(&self) -> bool {
 405         <Error + 'static>::is::<T>(self)
 406     }
 407
 408     /// Forwards to the method defined on the type `Any`.
 409     #[stable(feature = "error_downcast", since = "1.3.0")]
 410     #[inline]
 411     pub fn downcast_ref<T: Error + 'static>(&self) -> Option<&T> {
 412         <Error + 'static>::downcast_ref::<T>(self)
 413     }
 414
 415     /// Forwards to the method defined on the type `Any`.
 416     #[stable(feature = "error_downcast", since = "1.3.0")]
 417     #[inline]
 418     pub fn downcast_mut<T: Error + 'static>(&mut self) -> Option<&mut T> {
 419         <Error + 'static>::downcast_mut::<T>(self)
 420     }
 421 }
 422
 423 impl Error {
 424     #[inline]
 425     #[stable(feature = "error_downcast", since = "1.3.0")]
 426     /// Attempt to downcast the box to a concrete type.
 427     pub fn downcast<T: Error + 'static>(self: Box<Self>) -> Result<Box<T>, Box<Error>> {
 428         if self.is::<T>() {
 429             unsafe {
 430                 let raw: *mut Error = Box::into_raw(self);
 431                 Ok(Box::from_raw(raw as *mut T))
 432             }
 433         } else {
 434             Err(self)
 435         }
 436     }
 437 }
 438
 439 impl Error + Send {
 440     #[inline]
 441     #[stable(feature = "error_downcast", since = "1.3.0")]
 442     /// Attempt to downcast the box to a concrete type.
 443     pub fn downcast<T: Error + 'static>(self: Box<Self>)
 444                                         -> Result<Box<T>, Box<Error + Send>> {
 445         let err: Box<Error> = self;
 446         <Error>::downcast(err).map_err(|s| unsafe {
 447             // reapply the Send marker
 448             transmute::<Box<Error>, Box<Error + Send>>(s)
 449         })
 450     }
 451 }
 452
 453 impl Error + Send + Sync {
 454     #[inline]
 455     #[stable(feature = "error_downcast", since = "1.3.0")]
 456     /// Attempt to downcast the box to a concrete type.
 457     pub fn downcast<T: Error + 'static>(self: Box<Self>)
 458                                         -> Result<Box<T>, Box<Self>> {
 459         let err: Box<Error> = self;
 460         <Error>::downcast(err).map_err(|s| unsafe {
 461             // reapply the Send+Sync marker
 462             transmute::<Box<Error>, Box<Error + Send + Sync>>(s)
 463         })
 464     }
 465 }
 466
 467 #[cfg(test)]
 468 mod tests {
 469     use super::Error;
 470     use fmt;
 471
 472     #[derive(Debug, PartialEq)]
 473     struct A;
 474     #[derive(Debug, PartialEq)]
 475     struct B;
 476
 477     impl fmt::Display for A {
 478         fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 479             write!(f, "A")
 480         }
 481     }
 482     impl fmt::Display for B {
 483         fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
 484             write!(f, "B")
 485         }
 486     }
 487
 488     impl Error for A {
 489         fn description(&self) -> &str { "A-desc" }
 490     }
 491     impl Error for B {
 492         fn description(&self) -> &str { "A-desc" }
 493     }
 494
 495     #[test]
 496     fn downcasting() {
 497         let mut a = A;
 498         let mut a = &mut a as &mut (Error + 'static);
 499         assert_eq!(a.downcast_ref::<A>(), Some(&A));
 500         assert_eq!(a.downcast_ref::<B>(), None);
 501         assert_eq!(a.downcast_mut::<A>(), Some(&mut A));
 502         assert_eq!(a.downcast_mut::<B>(), None);
 503
 504         let a: Box<Error> = Box::new(A);
 505         match a.downcast::<B>() {
 506             Ok(..) => panic!("expected error"),
 507             Err(e) => assert_eq!(*e.downcast::<A>().unwrap(), A),
 508         }
 509     }
 510 }