pub struct Error {
inner: Option<Arc<ErrorInner>>,
}Expand description
An error that can occur in this crate.
The most common type of error is a result of overflow. But other errors exist as well:
- Time zone database lookup failure.
- Configuration problem. (For example, trying to round a span with calendar units without providing a relative datetime.)
- An I/O error as a result of trying to open a time zone database from a
directory via
TimeZoneDatabase::from_dir. - Parse errors.
§Introspection is limited
Other than implementing the std::error::Error trait when the
std feature is enabled, the core::fmt::Debug trait and the
core::fmt::Display trait, this error type currently provides no
introspection capabilities.
§Design
This crate follows the “One True God Error Type Pattern,” where only one error type exists for a variety of different operations. This design was chosen after attempting to provide finer grained error types. But finer grained error types proved difficult in the face of composition.
More about this design choice can be found in a GitHub issue about error types.
Fields§
§inner: Option<Arc<ErrorInner>>The internal representation of an error.
This is in an Arc to make an Error cloneable. It could otherwise
be automatically cloneable, but it embeds a std::io::Error when the
std feature is enabled, which isn’t cloneable.
This also makes clones cheap. And it also make the size of error equal
to one word (although a Box would achieve that last goal). This is
why we put the Arc here instead of on std::io::Error directly.
Implementations§
Source§impl Error
impl Error
Sourcepub(crate) fn adhoc<'a>(message: impl Display + 'a) -> Error
pub(crate) fn adhoc<'a>(message: impl Display + 'a) -> Error
Creates a new “ad hoc” error value.
An ad hoc error value is just an opaque string. In theory we should avoid creating such error values, but in practice, they are extremely convenient. And the alternative is quite brutal given the varied ways in which things in a datetime library can fail. (Especially parsing errors.)
Sourcepub(crate) fn adhoc_from_args<'a>(message: Arguments<'a>) -> Error
pub(crate) fn adhoc_from_args<'a>(message: Arguments<'a>) -> Error
Like Error::adhoc, but accepts a core::fmt::Arguments.
This is used with the err! macro so that we can thread a
core::fmt::Arguments down. This lets us extract a &'static str
from some messages in core-only mode and provide somewhat decent error
messages in some cases.
Sourcepub(crate) fn adhoc_from_static_str(message: &'static str) -> Error
pub(crate) fn adhoc_from_static_str(message: &'static str) -> Error
Like Error::adhoc, but creates an error from a &'static str
directly.
This is useful in contexts where you know you have a &'static str,
and avoids relying on alloc-only routines like Error::adhoc.
Sourcepub(crate) fn range(
what: &'static str,
given: impl Into<i128>,
min: impl Into<i128>,
max: impl Into<i128>,
) -> Error
pub(crate) fn range( what: &'static str, given: impl Into<i128>, min: impl Into<i128>, max: impl Into<i128>, ) -> Error
Creates a new error indicating that a given value is out of the
specified min..=max range. The given what label is used in the
error message as a human readable description of what exactly is out
of range. (e.g., “seconds”)
Creates a new error from the special “shared” error type.
Sourcepub(crate) fn io(err: Error) -> Error
pub(crate) fn io(err: Error) -> Error
A convenience constructor for building an I/O error.
This returns an error that is just a simple wrapper around the
std::io::Error type. In general, callers should alwasys attach some
kind of context to this error (like a file path).
This is only available when the std feature is enabled.