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