Span: add saturating arithmetic

[BurntSushi]

All of the datetime types have both checked and saturating arithmetic defined for them. Saturating arithmetic is nice because it avoids needing to deal with error conditions while returning a "reasonable" result that is probably obviously wrong in the rare cases it occurs.

Saturating arithmetic for the datetime types is defined in terms of checked arithmetic. For exmaple, for Zoned:

    pub fn saturating_add(&self, span: Span) -> Zoned {
        self.checked_add(span).unwrap_or_else(|_| {
            let ts = if span.is_negative() {
                Timestamp::MIN
            } else {
                Timestamp::MAX
            };
            ts.to_zoned(self.time_zone().clone())
        })
    }

This is in general a good strategy for datetime types because there are singular minimum and maximum values for datetimes. That is, there are only two ways for them to overflow: go under the minimum or over the maximum.

But for a Span, while there is technically a minimal and maximal Span that can be defined, overflow can occur as a result of arithmetic on individual fields. So for example, adding 19_998.years() + 1.year() would overflow because it exceeds the year limit, but it doesn't exceed the maximal logical duration representable by a span.

So if we do define saturating arithmetic on a span, I do wonder how exactly this would work. Right now, this is the implementation of checked arithmetic:

    #[inline]
    fn checked_add(self, span: Span) -> Result<Span, Error> {
        let (span1, span2) = (span, self.span);
        let unit = span1.largest_unit().max(span2.largest_unit());
        let start = match self.relative {
            Some(r) => {
                if !r.is_variable(unit) {
                    return span1.checked_add_invariant(unit, &span2);
                }
                r.to_relative()?
            }
            None => {
                if unit.is_definitively_variable() {
                    return Err(err!(
                        "using largest unit (which is '{unit}') in given span \
                         requires that a relative reference time be given, \
                         but none was provided",
                        unit = unit.singular(),
                    ));
                }
                return span1.checked_add_invariant(unit, &span2);
            }
        };
        let mid = start.checked_add(span1)?;
        let end = mid.checked_add(span2)?;
        start.until(unit, &end)
    }

Notice how the arithmetic is actually arithmetic on datetime and span types. I do wonder if we can make this saturating by copying it and using saturating arithmetic for the datetime + span operations. But I haven't fully thought through its semantics.