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