error: switch everything over to structured errors

This was an incredibly tedious and tortuous refactor. But this removes
almost all of the "create ad hoc stringly-typed errors everywhere."

This partially makes progress toward #418, but my initial impetus for
doing this was to see if I could reduce binary size and improve
compilation times. My general target was to see if I could reduce total
LLVM lines. I tested this with [Biff] using this command in the root of
the Biff repo:

```
cargo llvm-lines --profile release-lto
```

Before this change, Biff had 768,596 LLVM lines. With this change, it
has 757,331 lines. So... an improvement, but a very modest one.

What about compilation times? This does seem to translate to---also a
modest---improvement. For compiling release builds of Biff. Before:

```
$ hyperfine -w1 --prepare 'cargo clean' 'cargo b -r'
Benchmark 1: cargo b -r
  Time (mean ± σ):      7.776 s ±  0.052 s    [User: 65.876 s, System: 2.621 s]
  Range (min … max):    7.690 s …  7.862 s    10 runs
```

After:

```
$ hyperfine -w1 --prepare 'cargo clean' 'cargo b -r'
Benchmark 1: cargo b -r
  Time (mean ± σ):      7.591 s ±  0.067 s    [User: 65.686 s, System: 2.564 s]
  Range (min … max):    7.504 s …  7.689 s    10 runs
```

What about dev builds? Before:

```
$ hyperfine -w1 --prepare 'cargo clean' 'cargo b'
Benchmark 1: cargo b
  Time (mean ± σ):      4.074 s ±  0.022 s    [User: 14.493 s, System: 1.818 s]
  Range (min … max):    4.037 s …  4.099 s    10 runs
```

After:

```
$ hyperfine -w1 --prepare 'cargo clean' 'cargo b'
Benchmark 1: cargo b
  Time (mean ± σ):      4.541 s ±  0.027 s    [User: 15.385 s, System: 2.081 s]
  Range (min … max):    4.503 s …  4.591 s    10 runs
```

Well... that's disappointing. A modest improvement to release builds,
but a fairly large regression in dev builds. Maybe it's because of the
additional hand-written impls for new structured error types? Bah.

And binary size? Normal release builds (not LTO) of Biff that were
stripped were 4,431,456 bytes before this change and 4,392,064 after.

Hopefully this will unlock other improvements to justify doing this.
Note also that this slims down a number of error messages.

[Biff]: https://github.com/BurntSushi/biff

Author: BurntSushi

src/civil/date.rs

@@ -3,7 +3,7 @@ use core::time::Duration as UnsignedDuration;
 use crate::{
     civil::{DateTime, Era, ISOWeekDate, Time, Weekday},
     duration::{Duration, SDuration},
-    error::{err, Error, ErrorContext},
+    error::{civil::Error as E, Error, ErrorContext},
     fmt::{
         self,
         temporal::{DEFAULT_DATETIME_PARSER, DEFAULT_DATETIME_PRINTER},
@@ -1057,7 +1057,7 @@ impl Date {
 
         let nth = t::SpanWeeks::try_new("nth weekday", nth)?;
         if nth == C(0) {
-            Err(err!("nth weekday cannot be `0`"))
+            Err(Error::from(E::NthWeekdayNonZero))
         } else if nth > C(0) {
             let nth = nth.max(C(1));
             let weekday_diff = weekday.since_ranged(self.weekday().next());
@@ -1515,14 +1515,8 @@ impl Date {
             -1 => self.yesterday(),
             1 => self.tomorrow(),
             days => {
-                let days = UnixEpochDay::try_new("days", days).with_context(
-                    || {
-                        err!(
-                            "{days} computed from duration {duration:?} \
-                             overflows Jiff's datetime limits",
-                        )
-                    },
-                )?;
+                let days = UnixEpochDay::try_new("days", days)
+                    .context(E::OverflowDaysDuration)?;
                 let days =
                     self.to_unix_epoch_day().try_checked_add("days", days)?;
                 Ok(Date::from_unix_epoch_day(days))
@@ -2941,11 +2935,9 @@ impl DateDifference {
             //
             // NOTE: I take the above back. It's actually possible for the
             // months component to overflow when largest=month.
-            return Err(err!(
-                "rounding the span between two dates must use days \
-                 or bigger for its units, but found {units}",
-                units = largest.plural(),
-            ));
+            return Err(Error::from(E::RoundMustUseDaysOrBigger {
+                unit: largest,
+            }));
         }
         if largest <= Unit::Week {
             let mut weeks = t::SpanWeeks::rfrom(C(0));

src/civil/datetime.rs

@@ -5,7 +5,7 @@ use crate::{
         datetime, Date, DateWith, Era, ISOWeekDate, Time, TimeWith, Weekday,
     },
     duration::{Duration, SDuration},
-    error::{err, Error, ErrorContext},
+    error::{civil::Error as E, Error, ErrorContext},
     fmt::{
         self,
         temporal::{self, DEFAULT_DATETIME_PARSER},
@@ -1695,25 +1695,18 @@ impl DateTime {
         {
             (true, true) => Ok(self),
             (false, true) => {
-                let new_date =
-                    old_date.checked_add(span).with_context(|| {
-                        err!("failed to add {span} to {old_date}")
-                    })?;
+                let new_date = old_date
+                    .checked_add(span)
+                    .context(E::FailedAddSpanDate)?;
                 Ok(DateTime::from_parts(new_date, old_time))
             }
             (true, false) => {
-                let (new_time, leftovers) =
-                    old_time.overflowing_add(span).with_context(|| {
-                        err!("failed to add {span} to {old_time}")
-                    })?;
-                let new_date =
-                    old_date.checked_add(leftovers).with_context(|| {
-                        err!(
-                            "failed to add overflowing span, {leftovers}, \
-                             from adding {span} to {old_time}, \
-                             to {old_date}",
-                        )
-                    })?;
+                let (new_time, leftovers) = old_time
+                    .overflowing_add(span)
+                    .context(E::FailedAddSpanTime)?;
+                let new_date = old_date
+                    .checked_add(leftovers)
+                    .context(E::FailedAddSpanOverflowing)?;
                 Ok(DateTime::from_parts(new_date, new_time))
             }
             (false, false) => self.checked_add_span_general(&span),
@@ -1727,20 +1720,14 @@ impl DateTime {
         let span_date = span.without_lower(Unit::Day);
         let span_time = span.only_lower(Unit::Day);
 
-        let (new_time, leftovers) =
-            old_time.overflowing_add(span_time).with_context(|| {
-                err!("failed to add {span_time} to {old_time}")
-            })?;
-        let new_date = old_date.checked_add(span_date).with_context(|| {
-            err!("failed to add {span_date} to {old_date}")
-        })?;
-        let new_date = new_date.checked_add(leftovers).with_context(|| {
-            err!(
-                "failed to add overflowing span, {leftovers}, \
-                             from adding {span_time} to {old_time}, \
-                             to {new_date}",
-            )
-        })?;
+        let (new_time, leftovers) = old_time
+            .overflowing_add(span_time)
+            .context(E::FailedAddSpanTime)?;
+        let new_date =
+            old_date.checked_add(span_date).context(E::FailedAddSpanDate)?;
+        let new_date = new_date
+            .checked_add(leftovers)
+            .context(E::FailedAddSpanOverflowing)?;
         Ok(DateTime::from_parts(new_date, new_time))
     }
 
@@ -1751,13 +1738,9 @@ impl DateTime {
     ) -> Result<DateTime, Error> {
         let (date, time) = (self.date(), self.time());
         let (new_time, leftovers) = time.overflowing_add_duration(duration)?;
-        let new_date = date.checked_add(leftovers).with_context(|| {
-            err!(
-                "failed to add overflowing signed duration, {leftovers:?}, \
-                 from adding {duration:?} to {time},
-                 to {date}",
-            )
-        })?;
+        let new_date = date
+            .checked_add(leftovers)
+            .context(E::FailedAddDurationOverflowing)?;
         Ok(DateTime::from_parts(new_date, new_time))
     }
 
@@ -3552,9 +3535,10 @@ impl DateTimeRound {
         // it for good reasons.
         match self.smallest {
             Unit::Year | Unit::Month | Unit::Week => {
-                return Err(err!(
-                    "rounding datetimes does not support {unit}",
-                    unit = self.smallest.plural()
+                return Err(Error::from(
+                    crate::error::util::RoundingIncrementError::Unsupported {
+                        unit: self.smallest,
+                    },
                 ));
             }
             // We don't do any rounding in this case, so just bail now.
@@ -3592,9 +3576,7 @@ impl DateTimeRound {
         // supported datetimes.
         let end = start
             .checked_add(Span::new().days_ranged(days_len))
-            .with_context(|| {
-                err!("adding {days_len} days to {start} failed")
-            })?;
+            .context(E::FailedAddDays)?;
         Ok(DateTime::from_parts(end, time))
     }
 

src/civil/iso_week_date.rs

@@ -1,6 +1,6 @@
 use crate::{
     civil::{Date, DateTime, Weekday},
-    error::{err, Error},
+    error::{civil::Error as E, Error},
     fmt::temporal::{DEFAULT_DATETIME_PARSER, DEFAULT_DATETIME_PRINTER},
     util::{
         rangeint::RInto,
@@ -711,9 +711,7 @@ impl ISOWeekDate {
         debug_assert_eq!(t::Year::MIN, ISOYear::MIN);
         debug_assert_eq!(t::Year::MAX, ISOYear::MAX);
         if week == C(53) && !is_long_year(year) {
-            return Err(err!(
-                "ISO week number `{week}` is invalid for year `{year}`"
-            ));
+            return Err(Error::from(E::InvalidISOWeekNumber));
         }
         // And also, the maximum Date constrains what we can utter with
         // ISOWeekDate so that we can preserve infallible conversions between

src/civil/time.rs

@@ -3,7 +3,7 @@ use core::time::Duration as UnsignedDuration;
 use crate::{
     civil::{Date, DateTime},
     duration::{Duration, SDuration},
-    error::{err, Error, ErrorContext},
+    error::{civil::Error as E, Error, ErrorContext},
     fmt::{
         self,
         temporal::{self, DEFAULT_DATETIME_PARSER},
@@ -950,23 +950,14 @@ impl Time {
         self,
         duration: SignedDuration,
     ) -> Result<Time, Error> {
-        let original = duration;
         let start = t::NoUnits128::rfrom(self.to_nanosecond());
         let duration = t::NoUnits128::new_unchecked(duration.as_nanos());
         // This can never fail because the maximum duration fits into a
         // 96-bit integer, and adding any 96-bit integer to any 64-bit
         // integer can never overflow a 128-bit integer.
         let end = start.try_checked_add("nanoseconds", duration).unwrap();
         let end = CivilDayNanosecond::try_rfrom("nanoseconds", end)
-            .with_context(|| {
-                err!(
-                    "adding signed duration {duration:?}, equal to
-                     {nanos} nanoseconds, to {time} overflowed",
-                    duration = original,
-                    nanos = original.as_nanos(),
-                    time = self,
-                )
-            })?;
+            .context(E::OverflowTimeNanoseconds)?;
         Ok(Time::from_nanosecond(end))
     }
 
@@ -2603,11 +2594,9 @@ impl TimeDifference {
         }
         let largest = self.round.get_largest().unwrap_or(Unit::Hour);
         if largest > Unit::Hour {
-            return Err(err!(
-                "rounding the span between two times must use hours \
-                 or smaller for its units, but found {units}",
-                units = largest.plural(),
-            ));
+            return Err(Error::from(E::RoundMustUseHoursOrSmaller {
+                unit: largest,
+            }));
         }
         let start = t1.to_nanosecond();
         let end = t2.to_nanosecond();
@@ -3012,22 +3001,13 @@ impl TimeWith {
             None => self.original.subsec_nanosecond_ranged(),
             Some(subsec_nanosecond) => {
                 if self.millisecond.is_some() {
-                    return Err(err!(
-                        "cannot set both TimeWith::millisecond \
-                         and TimeWith::subsec_nanosecond",
-                    ));
+                    return Err(Error::from(E::IllegalTimeWithMillisecond));
                 }
                 if self.microsecond.is_some() {
-                    return Err(err!(
-                        "cannot set both TimeWith::microsecond \
-                         and TimeWith::subsec_nanosecond",
-                    ));
+                    return Err(Error::from(E::IllegalTimeWithMicrosecond));
                 }
                 if self.nanosecond.is_some() {
-                    return Err(err!(
-                        "cannot set both TimeWith::nanosecond \
-                         and TimeWith::subsec_nanosecond",
-                    ));
+                    return Err(Error::from(E::IllegalTimeWithNanosecond));
                 }
                 SubsecNanosecond::try_new(
                     "subsec_nanosecond",

src/duration.rs

@@ -1,7 +1,7 @@
 use core::time::Duration as UnsignedDuration;
 
 use crate::{
-    error::{err, ErrorContext},
+    error::{duration::Error as E, ErrorContext},
     Error, SignedDuration, Span,
 };
 
@@ -24,12 +24,8 @@ impl Duration {
             Duration::Span(span) => Ok(SDuration::Span(span)),
             Duration::Signed(sdur) => Ok(SDuration::Absolute(sdur)),
             Duration::Unsigned(udur) => {
-                let sdur =
-                    SignedDuration::try_from(udur).with_context(|| {
-                        err!(
-                            "unsigned duration {udur:?} exceeds Jiff's limits"
-                        )
-                    })?;
+                let sdur = SignedDuration::try_from(udur)
+                    .context(E::RangeUnsignedDuration)?;
                 Ok(SDuration::Absolute(sdur))
             }
         }
@@ -91,9 +87,8 @@ impl Duration {
                     // Otherwise, this is the only failure point in this entire
                     // routine. And specifically, we fail here in precisely
                     // the cases where `udur.as_secs() > |i64::MIN|`.
-                    -SignedDuration::try_from(udur).with_context(|| {
-                        err!("failed to negate unsigned duration {udur:?}")
-                    })?
+                    -SignedDuration::try_from(udur)
+                        .context(E::FailedNegateUnsignedDuration)?
                 };
                 Ok(Duration::Signed(sdur))
             }

src/error/civil.rs

@@ -0,0 +1,86 @@
+use crate::{error, Unit};
+
+#[derive(Clone, Debug)]
+pub(crate) enum Error {
+    FailedAddDays,
+    FailedAddDurationOverflowing,
+    FailedAddSpanDate,
+    FailedAddSpanOverflowing,
+    FailedAddSpanTime,
+    IllegalTimeWithMicrosecond,
+    IllegalTimeWithMillisecond,
+    IllegalTimeWithNanosecond,
+    InvalidISOWeekNumber,
+    OverflowDaysDuration,
+    OverflowTimeNanoseconds,
+    NthWeekdayNonZero,
+    RoundMustUseDaysOrBigger { unit: Unit },
+    RoundMustUseHoursOrSmaller { unit: Unit },
+}
+
+impl From<Error> for error::Error {
+    #[cold]
+    #[inline(never)]
+    fn from(err: Error) -> error::Error {
+        error::ErrorKind::Civil(err).into()
+    }
+}
+
+impl error::IntoError for Error {
+    fn into_error(self) -> error::Error {
+        self.into()
+    }
+}
+
+impl core::fmt::Display for Error {
+    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
+        use self::Error::*;
+
+        match *self {
+            FailedAddDays => f.write_str("failed to add days to date"),
+            FailedAddDurationOverflowing => {
+                f.write_str("failed to add overflowing duration")
+            }
+            FailedAddSpanDate => f.write_str("failed to add span to date"),
+            FailedAddSpanOverflowing => {
+                f.write_str("failed to add overflowing span")
+            }
+            FailedAddSpanTime => f.write_str("failed to add span to time"),
+            IllegalTimeWithMicrosecond => f.write_str(
+                "cannot set both `TimeWith::microsecond` \
+                 and `TimeWith::subsec_nanosecond`",
+            ),
+            IllegalTimeWithMillisecond => f.write_str(
+                "cannot set both `TimeWith::millisecond` \
+                 and `TimeWith::subsec_nanosecond`",
+            ),
+            IllegalTimeWithNanosecond => f.write_str(
+                "cannot set both `TimeWith::nanosecond` \
+                 and `TimeWith::subsec_nanosecond`",
+            ),
+            InvalidISOWeekNumber => {
+                f.write_str("ISO week number is invalid for given year")
+            }
+            OverflowDaysDuration => f.write_str(
+                "number of days derived from duration exceed's \
+                 Jiff's datetime limits",
+            ),
+            OverflowTimeNanoseconds => {
+                f.write_str("adding duration to time overflowed")
+            }
+            NthWeekdayNonZero => f.write_str("nth weekday cannot be `0`"),
+            RoundMustUseDaysOrBigger { unit } => write!(
+                f,
+                "rounding the span between two dates must use days \
+                 or bigger for its units, but found {unit}",
+                unit = unit.plural(),
+            ),
+            RoundMustUseHoursOrSmaller { unit } => write!(
+                f,
+                "rounding the span between two times must use hours \
+                 or smaller for its units, but found {unit}",
+                unit = unit.plural(),
+            ),
+        }
+    }
+}