Struct DateTime 

pub struct DateTime<C: Calendar, S: Standard> { /* private fields */ }

A calendar date and time, with attosecond precision, representing the time elapsed since the start of the Common Era in a traditional way according to a particular time Standard.

DateTimes are type parameterized by a Calendar type which is either Gregorian or Julian.

Normal ranges for values are as follows:

• year: any i32 value (-2_147_483_648 .. 2_147_483_647)
• month: 1 .. 12
• day: 1 .. 31 (or less in some months)
• hour: 0 .. 23
• minute: 0 .. 59
• second: 0 .. 60 (60 is only used under leap-second time standards)
• attosecond: 0 .. 999_999_999_999_999_999

Even when years are negative, the other values must remain in the positive ranges as specified (i.e. negative values are not a reflection against zero, but just an extension further backwards)

Zero and Negative years are handled in accordance with ISO 8601, such that year 0 is 1 B.C., and year -1 is 2 B.C., etc. In general:

• n B.C. is represented by year 1-n
• Year -y represents year y+1 B.C. (for positive y).

This type is proleptic; that is, it allows values for dates outside the normal usage period of the Calendar.

The oldest date representable is -2147483648-01-01 00:00:00.000000000000000000

The newest date representable is 2147483647-12-31 23:59:59.999999999999999999

Internally this is stored in a packed format and is 128 bits in size.

This represents the same thing that an Instant does, but it makes Calendar data easier to work with, and has such date precomputed and packed within.

Implementations

impl<C: Calendar, S: Standard> DateTime<C, S>

pub unsafe fn new_unchecked( year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, attosecond: u64, ) -> Self

Create a new DateTime with the given parts.

Safety

Parameter values must be within normal ranges, or else the results are not defined.

pub fn new( year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, attosecond: u64, ) -> Result<Self, Error>

Create a new DateTime from the given parts.

Values must be within normal ranges. See DateTime for details.

Errors

Will return Error::RangeError if any input is outside of the normal range (months from 1-12, days from 1-31, hours from 0-23, minutes from 0-59, seconds from 0-60, attoseconds from 0-999_999_999_999_999_999)

pub fn new_bc( bc_year: i32, month: u8, day: u8, hour: u8, minute: u8, second: u8, attosecond: u64, ) -> Result<Self, Error>

Create a new DateTime from the given parts, with BC years.

Values must be within normal ranges. See DateTime for details.

Errors

Will return Error::RangeError if any input is outside of the normal range (months from 1-12, days from 1-31, hours from 0-23, minutes from 0-59, seconds from 0-60, attoseconds from 0-999_999_999_999_999_999)

pub fn new_abnormal( year: i32, month: i64, day: i64, hour: i64, minute: i64, second: i64, attosecond: i64, ) -> Self

Create a new DateTime from the given parts.

Values that are out of normal ranges are allowed, including values that are negative. This function will adjust the input your provide into a normal form.

The types we are working with are large i64 types, but they can still overflow. Overflow is not detected or reported (FIXME).

Panics

Shouldn’t panic but several math assertions may trigger if we have a bug when compiled in development mode.

pub fn from_day_number(day_number: i64) -> Result<Self, Error>

Create a DateTime from a day number (integer).

January 1st of 1 A.D. (Common Era) is the epoch and has a day number of 0.

Hour, minute, second and attosecond will be zero.

Errors

Will return a Error::RangeError if day_number is out of range.

pub fn from_day_number_and_fraction( day_number: i64, day_fraction: f64, ) -> Result<Self, Error>

Create a DateTime from a day number (integer) and day fraction (float).

January 1st of 1 A.D. (Common Era) is the epoch and has a day number of 0.

Errors

Will return a Error::RangeError if day_number is out of range.

Will return Error::RangeError if day_fraction is <0.0 or >=1.0

Panics

Panics on assertions that should only fail if there is a bug.

pub fn from_duration_from_epoch(duration: Duration) -> Self

Create a DateTime from a Duration from the calendar epoch (with the calendar epoch represented in time Standard S, such that no time Standard conversions are done here).

pub fn year(&self) -> i32

The year part

pub fn year_bc(&self) -> i32

The year part in BC years

pub fn month(&self) -> u8

The month part. Ranges from 1 .. 12

pub fn month0(&self) -> u8

The month part where January is mapped to 0. Ranges from 0 .. 11

pub fn day(&self) -> u8

The day part. Ranges from 1 .. 31

pub fn day0(&self) -> u8

The day part where the 1st day is mapped to 0. Ranges from 0 .. 30

pub fn hour(&self) -> u8

The hour part. Ranges from 0 .. 23

pub fn minute(&self) -> u8

The minute part. Ranges from 0 .. 59

pub fn second(&self) -> u8

The second part. Ranges from 0 .. 59

pub fn attosecond(&self) -> u64

The attosecond part. Ranges from 0 .. 999_999_999_999_999_999

pub fn date(&self) -> (i32, u8, u8)

The date part

Returns (year, month, day)

pub fn time(&self) -> (u8, u8, u8, u64)

The time part

Returns (hour, minute, second, attosecond)

pub fn set_year(&mut self, year: i32)

Set the year, leaving other fields unchanged

pub fn set_year_bc(&mut self, year_bc: i32)

Set the year with a BC year, leaving other fields unchanged

pub fn set_month(&mut self, month: u8) -> Result<(), Error>

Set the month, leaving other fields unchanged

Errors

Will return Error::RangeError if month is <1 or >12.

pub fn set_day(&mut self, day: u8) -> Result<(), Error>

Set the day, leaving other fields unchanged

Errors

Will return Error::RangeError if day is outside of the range of days for the month.

pub fn set_hour(&mut self, hour: u8) -> Result<(), Error>

Set the hour, leaving other fields unchanged

Errors

Will return Error::RangeError if hour is greater than 23.

pub fn set_minute(&mut self, minute: u8) -> Result<(), Error>

Set the minute, leaving other fields unchanged

Errors

Will return Error::RangeError if minute is greater than 59.

pub fn set_second(&mut self, second: u8) -> Result<(), Error>

Set the second, leaving other fields unchanged

Errors

Will return Error::RangeError if second is greater than 60. The second of ‘60’ should only be used for leapsecond situations, but no error is thrown if used otherwise.

pub fn set_attosecond(&mut self, attosecond: u64) -> Result<(), Error>

Set the attosecond, leaving other fields unchanged

Errors

Will return Error::RangeError if attosecond are out of the proscribed range (more than 1 seconds worth of attoseconds)

pub fn set_date(&mut self, date: (i32, u8, u8)) -> Result<(), Error>

Set the date part (year, month, day)

Errors

Will return Error::RangeError if any input values are out of the proscribed range

pub fn set_time(&mut self, date: (u8, u8, u8, u64)) -> Result<(), Error>

Set the time part (hour, minute, second, attosecond)

Errors

Will return Error::RangeError if any input values are out of the proscribed range

pub fn day_number(&self) -> i64

Day number (integer).

January 1st of 1 A.D. (Common Era) is the epoch and has a day number of 0.

Panics

Will only panic on a bug that caused internal values to get out of range.

pub fn day_fraction(&self) -> f64

Day fraction, fractional part of the day since midnight

This isn’t attosecond accurate because a day contains more attoseconds than can fit in a f64 (which has 52 bits of precision). However, it should be accurate to 10,000 attoseconds.

pub fn duration_from_epoch(&self) -> Duration

Duration from the calendar epoch (with the calendar epoch represented in the time Standard S, such that no time Standard conversions are done here).

Panics

Only panics if we have an internal data consistency issue

Trait Implementations

impl<C: Calendar, S: Standard> Add<Duration> for DateTime<C, S>

type Output = DateTime<C, S>

The resulting type after applying the + operator.

fn add(self, rhs: Duration) -> Self

Performs the + operation.

impl<C: Clone + Calendar, S: Clone + Standard> Clone for DateTime<C, S>

fn clone(&self) -> DateTime<C, S>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<C: Calendar, S: Standard> Debug for DateTime<C, S>

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

Formats the value using the given formatter.

impl<C: Calendar, S: Standard> Display for DateTime<C, S>

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

Formats the value using the given formatter.

impl<C: Calendar, S: Standard> From<DateTime<C, S>> for Instant

fn from(dt: DateTime<C, S>) -> Self

Converts to this type from the input type.

impl<C: Calendar, S: Standard> From<Instant> for DateTime<C, S>

fn from(i: Instant) -> Self

Converts to this type from the input type.

impl<C: Calendar, S: Standard> Hash for DateTime<C, S>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<C: Calendar, S: Standard> Ord for DateTime<C, S>

fn cmp(&self, other: &Self) -> Ordering

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<C: Calendar, S: Standard> PartialEq for DateTime<C, S>

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C: Calendar, S: Standard> PartialOrd for DateTime<C, S>

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator.

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<C: Calendar, S: Standard> Sub<Duration> for DateTime<C, S>

type Output = DateTime<C, S>

The resulting type after applying the - operator.

fn sub(self, rhs: Duration) -> Self

Performs the - operation.

impl<C: Calendar, S: Standard> Sub for DateTime<C, S>

type Output = Duration

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Duration

Performs the - operation.

impl<S: Standard> TryFrom<DateTime<Gregorian, S>> for DateTime<Julian, S>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(input: DateTime<Gregorian, S>) -> Result<Self, Self::Error>

Performs the conversion.

impl<S: Standard> TryFrom<DateTime<Julian, S>> for DateTime<Gregorian, S>

type Error = Error

The type returned in the event of a conversion error.

fn try_from(input: DateTime<Julian, S>) -> Result<Self, Self::Error>

Performs the conversion.

impl<C: Copy + Calendar, S: Copy + Standard> Copy for DateTime<C, S>

impl<C: Calendar, S: Standard> Eq for DateTime<C, S>

impl<C: Calendar, S: Standard> Send for DateTime<C, S>