Type Alias UnixSeconds

pub(crate) type UnixSeconds = ri64<{ _ }, { _ }>;

The range of Unix seconds supported by Jiff.

This range should correspond to the first second of Year::MIN up through (and including) the last second of Year::MAX. Actually computing that is non-trivial, however, it can be computed easily enough using Unix programs like date:

$ TZ=0 date -d 'Mon Jan  1 12:00:00 AM  -9999' +'%s'
date: invalid date ‘Mon Jan  1 12:00:00 AM  -9999’
$ TZ=0 date -d 'Fri Dec 31 23:59:59  9999' +'%s'
253402300799

Well, almost easily enough. date apparently doesn’t support negative years. But it does support negative timestamps:

$ TZ=0 date -d '@-377705116800'
Mon Jan  1 12:00:00 AM  -9999
$ TZ=0 date -d '@253402300799'
Fri Dec 31 11:59:59 PM  9999

With that said, we actually end up restricting the range a bit more than what’s above. Namely, what’s above is what we support for civil datetimes. Because of time zones, we need to choose whether all Timestamp values can be infallibly converted to civil::DateTime values, or whether all civil::DateTime values can be infallibly converted to Timestamp values. I chose the former because getting a civil datetime is important for formatting. If I didn’t choose the former, there would be some instants that could not be formatted. Thus, we make room by shrinking the range of allowed instants by precisely the maximum supported time zone offset.

Aliased Type

pub(crate) struct UnixSeconds {
    pub(crate) val: i64,
    pub(crate) min: i64,
    pub(crate) max: i64,
}

Fields

val: i64

The actual value of the integer.

Callers should not access this directly. There are some very rare cases where algorithms are too difficult to express on ranged integers, and it’s useful to be able to reach inside and access the raw value directly. (For example, the conversions between Unix epoch day and Gregorian date.)

min: i64

The minimum possible value computed so far.

This value is only present when debug_assertions are enabled. In that case, it is used to ensure the minimum possible value when the integer is actually observed (or converted) is still within the legal range.

Callers should not access this directly. There are some very rare cases where algorithms are too difficult to express on ranged integers, and it’s useful to be able to reach inside and access the raw value directly. (For example, the conversions between Unix epoch day and Gregorian date.)

max: i64

The maximum possible value computed so far.

This value is only present when debug_assertions are enabled. In that case, it is used to ensure the maximum possible value when the integer is actually observed (or converted) is still within the legal range.

Callers should not access this directly. There are some very rare cases where algorithms are too difficult to express on ranged integers, and it’s useful to be able to reach inside and access the raw value directly. (For example, the conversions between Unix epoch day and Gregorian date.)