diff --git a/src/libcore/any.rs b/src/libcore/any.rs index 021f575b0acea..0c2e2d1dec0ea 100644 --- a/src/libcore/any.rs +++ b/src/libcore/any.rs @@ -114,6 +114,9 @@ pub trait AnyRefExt<'a> { fn downcast_ref(self) -> Option<&'a T>; } +// Note: this code is copied to std::error, and should be unified as +// soon as possible. + #[stable] impl<'a> AnyRefExt<'a> for &'a Any { #[inline] diff --git a/src/libcore/prelude.rs b/src/libcore/prelude.rs index 680f91945d103..425b9f14b38fb 100644 --- a/src/libcore/prelude.rs +++ b/src/libcore/prelude.rs @@ -37,8 +37,6 @@ pub use ops::{Shl, Shr}; pub use ops::{Index, IndexMut}; pub use ops::{Slice, SliceMut}; pub use ops::{Fn, FnMut, FnOnce}; -pub use option::{Option, Some, None}; -pub use result::{Result, Ok, Err}; // Reexported functions pub use iter::range; @@ -57,7 +55,9 @@ pub use iter::{OrdIterator, MutableDoubleEndedIterator, ExactSize}; pub use num::{Num, NumCast, CheckedAdd, CheckedSub, CheckedMul}; pub use num::{Signed, Unsigned, Float}; pub use num::{Primitive, Int, ToPrimitive, FromPrimitive}; +pub use option::{Option, Some, None}; pub use ptr::RawPtr; +pub use result::{Result, Ok, Err}; pub use str::{Str, StrSlice}; pub use tuple::{Tuple1, Tuple2, Tuple3, Tuple4}; pub use tuple::{Tuple5, Tuple6, Tuple7, Tuple8}; diff --git a/src/libstd/error.rs b/src/libstd/error.rs new file mode 100644 index 0000000000000..0bbe0a46fc68d --- /dev/null +++ b/src/libstd/error.rs @@ -0,0 +1,137 @@ +// 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 or the MIT license +// , 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`. At a minimum, errors must provide +//! a description, but they may optionally provide additional detail and cause +//! chain information: +//! +//! ``` +//! pub trait Error: Send + Any { +//! fn description(&self) -> &str; +//! +//! fn detail(&self) -> Option { None } +//! 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. +//! +//! The trait inherits from `Any` to allow *downcasting*: converting from a +//! trait object to a specific concrete type when applicable. +//! +//! # The `FromError` trait +//! +//! `FromError` is a simple trait that expresses conversions between different +//! error types. To provide maximum flexibility, it does not require either of +//! the types to actually implement the `Error` trait, although this will be the +//! common case. +//! +//! The main use of this trait is in the `try!` macro, which uses it to +//! automatically convert a given error to the error specified in a function's +//! return type. + +use any::{Any, AnyRefExt, AnyMutRefExt}; +use mem::{transmute, transmute_copy}; +use option::{Option, Some, None}; +use raw::TraitObject; +use intrinsics::TypeId; +use kinds::Send; +use string::String; + +/// Base functionality for all errors in Rust. +pub trait Error: Send + Any { + /// A short description of the error; usually a static string. + fn description(&self) -> &str; + + /// A detailed description of the error, usually including dynamic information. + fn detail(&self) -> Option { None } + + /// The lower-level cause of this error, if any. + fn cause(&self) -> Option<&Error> { None } +} + +/// A trait for types that can be converted from a given error type `E`. +pub trait FromError { + /// Perform the conversion. + fn from_error(err: E) -> Self; +} + +// Any type is convertable from itself +impl FromError for E { + fn from_error(err: E) -> E { + err + } +} + +// FIXME (#https://github.com/rust-lang/rust/pull/17669/): Add this once multidispatch lands +// impl FromError for Box { +// fn from_err(err: E) -> Box { +// box err as Box +// } +// } + +// Note: the definitions below are copied from core::any, and should be unified +// as soon as possible. + +impl<'a> AnyRefExt<'a> for &'a Error { + #[inline] + fn is(self) -> bool { + // Get TypeId of the type this function is instantiated with + let t = TypeId::of::(); + + // Get TypeId of the type in the trait object + let boxed = self.get_type_id(); + + // Compare both TypeIds on equality + t == boxed + } + + #[inline] + fn downcast_ref(self) -> Option<&'a T> { + if self.is::() { + unsafe { + // Get the raw representation of the trait object + let to: TraitObject = transmute_copy(&self); + + // Extract the data pointer + Some(transmute(to.data)) + } + } else { + None + } + } +} + +impl<'a> AnyMutRefExt<'a> for &'a mut Error { + #[inline] + fn downcast_mut(self) -> Option<&'a mut T> { + if self.is::() { + unsafe { + // Get the raw representation of the trait object + let to: TraitObject = transmute_copy(&self); + + // Extract the data pointer + Some(transmute(to.data)) + } + } else { + None + } + } +} diff --git a/src/libstd/lib.rs b/src/libstd/lib.rs index 67080f4551f06..cac1904e37f07 100644 --- a/src/libstd/lib.rs +++ b/src/libstd/lib.rs @@ -218,6 +218,7 @@ pub mod time; /* Common traits */ +pub mod error; pub mod from_str; pub mod num; pub mod to_string; diff --git a/src/libstd/prelude.rs b/src/libstd/prelude.rs index 48be404b0d02a..785d059911479 100644 --- a/src/libstd/prelude.rs +++ b/src/libstd/prelude.rs @@ -48,8 +48,6 @@ #[doc(no_inline)] pub use ops::{Index, IndexMut}; #[doc(no_inline)] pub use ops::{Slice, SliceMut}; #[doc(no_inline)] pub use ops::{Fn, FnMut, FnOnce}; -#[doc(no_inline)] pub use option::{Option, Some, None}; -#[doc(no_inline)] pub use result::{Result, Ok, Err}; // Reexported functions #[doc(no_inline)] pub use from_str::from_str; @@ -75,8 +73,10 @@ #[doc(no_inline)] pub use num::{Signed, Unsigned, Primitive, Int, Float}; #[doc(no_inline)] pub use num::{FloatMath, ToPrimitive, FromPrimitive}; #[doc(no_inline)] pub use boxed::Box; +#[doc(no_inline)] pub use option::{Option, Some, None}; #[doc(no_inline)] pub use path::{GenericPath, Path, PosixPath, WindowsPath}; #[doc(no_inline)] pub use ptr::{RawPtr, RawMutPtr}; +#[doc(no_inline)] pub use result::{Result, Ok, Err}; #[doc(no_inline)] pub use io::{Buffer, Writer, Reader, Seek}; #[doc(no_inline)] pub use str::{Str, StrVector, StrSlice}; #[doc(no_inline)] pub use str::{IntoMaybeOwned, StrAllocating, UnicodeStrSlice};