Enum Relative

enum Relative<'a> {
    Civil(RelativeCivil),
    Zoned(RelativeZoned<'a>),
}

An internal abstraction for managing a relative datetime for use in some Span APIs.

This is effectively the same as a SpanRelativeTo, but uses a Cow<Zoned> instead of a &Zoned. This makes it non-Copy, but allows us to craft a more uniform API. (i.e., relative + span = relative instead of `relative

• span = owned_relativeor whatever.) Note that theCopyimpl onSpanRelativeTomeans it has to accept a&Zoned. It can't ever take a Zoned` since it is non-Copy.

NOTE: Separately from above, I think it’s plausible that this type could be designed a bit differently. Namely, something like this:

struct Relative<'a> {
    tz: Option<&'a TimeZone>,
    dt: DateTime,
    ts: Timestamp,
}

That is, we do zone aware stuff but without an actual Zoned type. But I think in order to make that work, we would need to expose most of the Zoned API as functions on its component types (DateTime, Timestamp and TimeZone). I think we are likely to want to do that for public API reasons, but I’d like to resist it since I think it will add a lot of complexity. Or maybe we need a Unzoned type that is DateTime and Timestamp, but requires passing the time zone in to each of its methods. That might work quite well, even if it was just an internal type.

Anyway, I’m not 100% sure the above would work, but I think it would. It would be nicer because everything would be Copy all the time. We’d never need a Cow<TimeZone> for example, because we never need to change or create a new time zone.

Variants

Civil(RelativeCivil)

Zoned(RelativeZoned<'a>)

Implementations

impl<'a> Relative<'a>

fn checked_add(&self, span: Span) -> Result<Relative<'_>, Error>

Adds the given span to this relative datetime.

This defers to either DateTime::checked_add or Zoned::checked_add, depending on the type of relative datetime.

The Relative datetime returned is guaranteed to have the same internal datetie type as self.

Errors

This returns an error in the same cases as the underlying checked arithmetic APIs. In general, this occurs when adding the given span would result in overflow.

fn checked_add_duration( &self, duration: SignedDuration, ) -> Result<Relative<'_>, Error>

fn until(&self, largest: Unit, other: &Relative<'_>) -> Result<Span, Error>

Returns the span of time from this relative datetime to the one given, with units as large as largest.

Errors

This returns an error in the same cases as when the underlying DateTime::until or Zoned::until fail. Because this doesn’t set or expose any rounding configuration, this can generally only occur when largest is Unit::Nanosecond and the span of time between self and other is too big to represent as a 64-bit integer nanosecond count.

Panics

This panics if self and other are different internal datetime types. For example, if self was a civil datetime and other were a zoned datetime.

fn to_nanosecond(&self) -> ri128<{ i128::MIN }, { i128::MAX }>

Converts this relative datetime to a nanosecond in UTC time.

Errors

If there was a problem doing this conversion, then an error is returned. In practice, this only occurs for a civil datetime near the civil datetime minimum and maximum values.

fn into_relative_span( self, largest: Unit, span: Span, ) -> Result<RelativeSpan<'a>, Error>

Create a balanced span of time relative to this datetime.

The relative span returned has the same internal datetime type (civil or zoned) as this relative datetime.

Errors

This returns an error when the span in this range cannot be represented. In general, this only occurs when asking for largest units of Unit::Nanosecond and when the span is too big to fit into a 64-bit nanosecond count.

This can also return an error in other extreme cases, such as when adding the given span to this relative datetime results in overflow, or if this relative datetime is a civil datetime and it couldn’t be converted to a timestamp in UTC.

fn round( self, span: Span, smallest: Unit, largest: Unit, increment: ri128<{ i128::MIN }, { i128::MAX }>, mode: RoundMode, ) -> Result<Span, Error>

Rounds the given span using the given rounding configuration.

Trait Implementations

impl<'a> Clone for Relative<'a>

fn clone(&self) -> Relative<'a>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Relative<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.