Struct astrolabe::DateTime

pub struct DateTime { /* private fields */ }

Combined date and time. Date is in the proleptic Gregorian calendar and clock time is with nanosecond precision.

See the DateUtilites and TimeUtilities implementations for get, set and manipulation methods.

OffsetUtilities implements methods for setting and getting the offset.

Range: 30. June -5879611 00:00:00..=12. July 5879611 23:59:59. Please note that year 0 does not exist. After year -1 follows year 1.

Implementations

impl DateTime

pub fn now() -> Self

Creates a new DateTime instance with SystemTime::now().

let date_time = DateTime::now();
assert!(2021 < date_time.year());

pub fn now_local() -> Self

Creates a new DateTime instance with SystemTime::now() with the local timezone as the offset.

let date_time = DateTime::now_local();
assert!(2021 < date_time.year());
assert_eq!(date_time.get_offset(), Offset::Local);

pub fn from_ymdhms( year: i32, month: u32, day: u32, hour: u32, minute: u32, second: u32 ) -> Result<Self, AstrolabeError>

Creates a new DateTime instance from year, month, day (day of month), hour, minute and seconds.

Returns an OutOfRange error if the provided values are invalid.

let date_time = DateTime::from_ymdhms(2022, 05, 02, 12, 32, 1).unwrap();
assert_eq!("2022/05/02 12:32:01", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn as_ymdhms(&self) -> (i32, u32, u32, u32, u32, u32)

Returns the DateTime as year, month, day (day of month), hour, minute and seconds.

let date_time = DateTime::from_ymdhms(2022, 05, 02, 12, 32, 1).unwrap();
let (year, month, day, hour, minute, second) = date_time.as_ymdhms();
assert_eq!(2022, year);
assert_eq!(5, month);
assert_eq!(2, day);
assert_eq!(12, hour);
assert_eq!(32, minute);
assert_eq!(1, second);

pub fn from_ymd(year: i32, month: u32, day: u32) -> Result<Self, AstrolabeError>

Creates a new DateTime instance from year, month and day (day of month).

Returns an OutOfRange error if the provided values are invalid.

let date_time = DateTime::from_ymd(2022, 05, 02).unwrap();
assert_eq!("2022/05/02", date_time.format("yyyy/MM/dd"));

pub fn as_ymd(&self) -> (i32, u32, u32)

Returns the DateTime as year, month and day (day of month).

let date_time = DateTime::from_ymd(2022, 05, 02).unwrap();
let (year, month, day) = date_time.as_ymd();
assert_eq!(2022, year);
assert_eq!(5, month);
assert_eq!(2, day);

pub fn from_hms( hour: u32, minute: u32, second: u32 ) -> Result<Self, AstrolabeError>

Creates a new DateTime instance from hour, minute and seconds.

Returns an OutOfRange error if the provided values are invalid.

let date_time = DateTime::from_hms(12, 32, 12).unwrap();
assert_eq!("0001/01/01 12:32:12", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn as_hms(&self) -> (u32, u32, u32)

Returns the DateTime as hour, minute and seconds.

let date_time = DateTime::from_hms(12, 12, 12).unwrap();
let (hour, minute, second) = date_time.as_hms();
assert_eq!(12, hour);
assert_eq!(12, minute);
assert_eq!(12, second);

pub fn set_time(&self, time: Time) -> Self

Creates a new DateTime with the specified time.

let time = Time::from_hms(12, 32, 1).unwrap();
let date_time = DateTime::from_ymd(2022, 5, 2).unwrap().set_time(time);
assert_eq!("2022/05/02 12:32:01", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn parse_rfc3339(string: &str) -> Result<Self, AstrolabeError>

Creates a new DateTime instance from an RFC 3339 timestamp string.

let date_time = DateTime::parse_rfc3339("2022-05-02T15:30:20Z").unwrap();
assert_eq!("2022/05/02 15:30:20", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn format_rfc3339(&self, precision: Precision) -> String

Format as an RFC 3339 timestamp (2022-05-02T15:30:20Z).

Use the Precision enum to specify decimal places after seconds:

• Precision::Seconds -> 2022-05-02T15:30:20Z
• Precision::Centis -> 2022-05-02T15:30:20.00Z
• Precision::Millis -> 2022-05-02T15:30:20.000Z
• Precision::Micros -> 2022-05-02T15:30:20.000000Z
• Precision::Nanos -> 2022-05-02T15:30:20.000000000Z

let date_time = DateTime::from_ymdhms(2022, 5, 2, 15, 30, 20).unwrap();
assert_eq!("2022-05-02T15:30:20Z", date_time.format_rfc3339(Precision::Seconds));
// Equivalent to:
assert_eq!("2022-05-02T15:30:20Z", date_time.format("yyyy-MM-ddTHH:mm:ssXXX"));

pub fn parse(string: &str, format: &str) -> Result<Self, AstrolabeError>

Parses a string with a given format and creates a new DateTime instance from it. See DateTime::format for a list of available symbols.

Returns an InvalidFormat error if the given string could not be parsed with the given format.

let date_time = DateTime::parse("2022-05-02 12:32:01", "yyyy-MM-dd HH:mm:ss").unwrap();
assert_eq!("2022/05/02 12:32:01", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn format(&self, format: &str) -> String

Formatting with format strings based on Unicode Date Field Symbols.

Please note that not all symbols are implemented. If you need something that is not implemented, please open an issue on GitHub describing your need.

Available Symbols:

Field Type	Pattern	Examples	Hint
era	G..GGG	AD
	GGGG	Anno Domini	*
	GGGGG	A
year	y	2, 20, 201, 2017, 20173
	yy	02, 20, 01, 17, 73
	yyy	002, 020, 201, 2017, 20173
	yyyy	0002, 0020, 0201, 2017, 20173
	yyyyy+	…	Unlimited length, padded with zeros.
quarter	q	2	*
	qq	02
	qqq	Q2
	qqqq	2nd quarter
	qqqqq	2
month	M	9, 12
	MM	09, 12
	MMM	Sep
	MMMM	September	*
	MMMMM	S
week	w	8, 27	Week of year
	ww	08, 27	*
days	d	1	Day of month
	dd	01	*
	D	1, 24, 135	Day of year, *
	DD	01, 24, 135
	DDD	001, 024, 135
week day	e	3	1-7, 1 is Sunday, *
	ee	03	1-7, 1 is Sunday
	eee	Tue
	eeee	Tuesday
	eeeee	T
	eeeeee	Tu
	eeeeeee	2	1-7, 1 is Monday
	eeeeeeee	02	1-7, 1 is Monday
AM, PM	a..aa	AM, PM
	aaa	am, pm	*
	aaaa	a.m., p.m.
	aaaaa	a, p
AM, PM, noon, midnight	b..bb	AM, PM, noon, midnight
	bbb	am, pm, noon, midnight	*
	bbbb	a.m., p.m., noon, midnight
	bbbbb	a, p, n, mi
hour	h	1, 12	[1-12]
	hh	01, 12	*
	H	0, 23	[0-23]
	HH	00, 23	*
	K	0, 11	[0-11]
	KK	00, 11	*
	k	1, 24	[1-24]
	kk	01, 24	*
minute	m	0, 59
	mm	00, 59	*
second	s	0, 59
	ss	00, 59	*
subsecond values	n	1, 9	Deciseconds
	nn	01, 99	Centiseconds
	nnn	001, 999	Milliseconds, *
	nnnn	000001, 999999	Microseconds
	nnnnn	000000001, 999999999	Nanoseconds
zone	X	-08, +0530, Z
	XX	-0800, Z
	XXX	-08:00, Z	*
	XXXX	-0800, -075258, Z
	XXXXX	-08:00, -07:52:58, Z
	x	-08, +0530, +00	Like X but without Z
	xx	-0800, +0000
	xxx	-08:00, +00:00	*
	xxxx	-0800, -075258, +0000
	xxxxx	-08:00, -07:52:58, +00:00

* = Default

If the sequence is longer than listed in the table, the output will be the same as the default pattern for this unit (marked with *).

Surround any character with apostrophes (') to escape them. If you want escape ', write ''.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
assert_eq!("2022/05/02 12:32:01", date_time.format("yyyy/MM/dd HH:mm:ss"));
// Escape characters
assert_eq!("2022/MM/dd 12:32:01", date_time.format("yyyy/'MM/dd' HH:mm:ss"));
assert_eq!("2022/'05/02' 12:32:01", date_time.format("yyyy/''MM/dd'' HH:mm:ss"));

pub fn duration_between(&self, compare: &Self) -> Duration

Returns the duration between the provided DateTime.

Trait Implementations

impl Add<Duration> for DateTime

type Output = DateTime

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Time> for DateTime

type Output = DateTime

The resulting type after applying the + operator.

fn add(self, rhs: Time) -> Self::Output

Performs the + operation.

impl AddAssign<Duration> for DateTime

fn add_assign(&mut self, rhs: Duration)

Performs the += operation.

impl AddAssign<Time> for DateTime

fn add_assign(&mut self, rhs: Time)

Performs the += operation.

impl Clone for DateTime

fn clone(&self) -> DateTime

Returns a copy of the value.

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

Performs copy-assignment from source.

impl DateUtilities for DateTime

fn year(&self) -> i32

Returns the year.

fn month(&self) -> u32

Returns the month of the year (1-12).

fn day(&self) -> u32

Returns the day of the month (1-31).

fn day_of_year(&self) -> u32

Returns the day of the year (1-365 or 1-366).

fn weekday(&self) -> u8

Returns the day of the week (0-6, 0 is Sunday).

fn from_timestamp(timestamp: i64) -> Self

Creates a date from a unix timestamp (non-leap seconds since January 1, 1970 00:00:00 UTC).

fn timestamp(&self) -> i64

Returns the number of non-leap seconds since January 1, 1970 00:00:00 UTC. (Negative if date is before)

fn set_year(&self, year: i32) -> Result<Self, AstrolabeError>

Sets the year to the provided value. Has to be in range -5879611..=5879611.

fn set_month(&self, month: u32) -> Result<Self, AstrolabeError>

Sets the month of the year to the provided value. Has to be in range 1..=12.

fn set_day(&self, day: u32) -> Result<Self, AstrolabeError>

Sets the day of the month to the provided value. Has to be in range 1..=31 and cannot be greater than the number of days in the current month.

fn set_day_of_year(&self, day_of_year: u32) -> Result<Self, AstrolabeError>

Sets the day of the year to the provided value. Has to be in range 1..=365 or 1..=366 in case of a leap year.

fn add_years(&self, years: u32) -> Self

Adds the provided years to the current date.

fn add_months(&self, months: u32) -> Self

Adds the provided months to the current date.

fn add_days(&self, days: u32) -> Self

Adds the provided days to the current date.

fn sub_years(&self, years: u32) -> Self

Subtracts the provided years from the current date.

fn sub_months(&self, months: u32) -> Self

Subtracts the provided months from the current date.

fn sub_days(&self, days: u32) -> Self

Subtracts the provided days from the current date.

fn clear_until_year(&self) -> Self

Clears date/time units until the year (inclusive).

fn clear_until_month(&self) -> Self

Clears date/time units until the month (inclusive).

fn clear_until_day(&self) -> Self

Clears date/time units until the day (inclusive).

fn years_since(&self, compare: &Self) -> i32

Returns full years since the provided date.

fn months_since(&self, compare: &Self) -> i32

Returns full months since the provided date.

fn days_since(&self, compare: &Self) -> i64

Returns full days since the provided date.

impl Debug for DateTime

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

Formats the value using the given formatter.

impl Default for DateTime

fn default() -> DateTime

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for DateTime

Available on crate feature serde only.

Deserialize an RFC 3339 string into a DateTime instance.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for DateTime

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

Formats the value using the given formatter.

impl From<&Date> for DateTime

fn from(value: &Date) -> Self

Converts to this type from the input type.

impl From<&DateTime> for Date

fn from(value: &DateTime) -> Self

Converts to this type from the input type.

impl From<&DateTime> for DateTime

fn from(date_time: &DateTime) -> Self

Converts to this type from the input type.

impl From<&DateTime> for Time

fn from(value: &DateTime) -> Self

Converts to this type from the input type.

impl From<&Time> for DateTime

fn from(time: &Time) -> Self

Converts to this type from the input type.

impl From<Date> for DateTime

fn from(value: Date) -> Self

Converts to this type from the input type.

impl From<DateTime> for Date

fn from(value: DateTime) -> Self

Converts to this type from the input type.

impl From<DateTime> for Time

fn from(value: DateTime) -> Self

Converts to this type from the input type.

impl From<Time> for DateTime

fn from(value: Time) -> Self

Converts to this type from the input type.

impl FromStr for DateTime

type Err = AstrolabeError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl OffsetUtilities for DateTime

fn set_offset(&self, offset: Offset) -> Self

Sets the offset

fn as_offset(&self, offset: Offset) -> Self

Sets the offset, assuming the current instance has the provided offset applied. The new instance will have the specified offset and the datetime itself will be converted to UTC.

fn get_offset(&self) -> Offset

Returns the offset

impl Ord for DateTime

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 + PartialOrd,

Restrict a value to a certain interval.

impl PartialEq for DateTime

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

This method tests for self and other values to be equal, and is used by ==.

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

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

impl PartialOrd for DateTime

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

This method tests less than (for self and other) and is used by the < operator.

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

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

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Serialize for DateTime

Available on crate feature serde only.

Serialize a DateTime instance as an RFC 3339 string.

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<Duration> for DateTime

type Output = DateTime

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Time> for DateTime

type Output = DateTime

The resulting type after applying the - operator.

fn sub(self, rhs: Time) -> Self::Output

Performs the - operation.

impl SubAssign<Duration> for DateTime

fn sub_assign(&mut self, rhs: Duration)

Performs the -= operation.

impl SubAssign<Time> for DateTime

fn sub_assign(&mut self, rhs: Time)

Performs the -= operation.

impl TimeUtilities for DateTime

fn add_hours(&self, hours: u32) -> Self

Panics if the provided value would result in an out of range datetime.

fn add_minutes(&self, minutes: u32) -> Self

Panics if the provided value would result in an out of range datetime.

fn add_seconds(&self, seconds: u32) -> Self

Panics if the provided value would result in an out of range datetime.

fn hour(&self) -> u32

Returns the hour (0-23).

fn minute(&self) -> u32

Returns the minute of the hour (0-59).

fn second(&self) -> u32

Returns the second of the minute (0-59).

fn milli(&self) -> u32

Returns the millisecond of the second (0-999).

fn micro(&self) -> u32

Returns the microsecond of the second (0-999_999).

fn nano(&self) -> u32

Returns the nanosecond of the second (0-999_999_999).

fn set_hour(&self, hour: u32) -> Result<Self, AstrolabeError>

Sets the hour to the provided value. Has to be in range 0..=23.

fn set_minute(&self, minute: u32) -> Result<Self, AstrolabeError>

Sets the minute to the provided value. Has to be in range 0..=59.

fn set_second(&self, second: u32) -> Result<Self, AstrolabeError>

Sets the second to the provided value. Has to be in range 0..=59.

fn set_milli(&self, milli: u32) -> Result<Self, AstrolabeError>

Sets the millisecond to the provided value. Has to be in range 0..=100.

fn set_micro(&self, micro: u32) -> Result<Self, AstrolabeError>

Sets the microsecond to the provided value. Has to be in range 0..=100_000.

fn set_nano(&self, nano: u32) -> Result<Self, AstrolabeError>

Sets the nanosecond to the provided value. Has to be in range 0..=100_000_000.

fn add_millis(&self, millis: u32) -> Self

Adds the provided milliseconds.

fn add_micros(&self, micros: u32) -> Self

Adds the provided microseconds.

fn add_nanos(&self, nanos: u32) -> Self

Adds the provided nanoseconds.

fn sub_hours(&self, hours: u32) -> Self

Subtracts the provided hours.

fn sub_minutes(&self, minutes: u32) -> Self

Subtracts the provided minutes.

fn sub_seconds(&self, seconds: u32) -> Self

Subtracts the provided seconds.

fn sub_millis(&self, millis: u32) -> Self

Subtracts the provided milliseconds.

fn sub_micros(&self, micros: u32) -> Self

Subtracts the provided microseconds.

fn sub_nanos(&self, nanos: u32) -> Self

Subtracts the provided nanoseconds.

fn clear_until_hour(&self) -> Self

Clears date/time units until the hour (inclusive).

fn clear_until_minute(&self) -> Self

Clears date/time units until the minute (inclusive).

fn clear_until_second(&self) -> Self

Clears date/time units until the second (inclusive).

fn clear_until_milli(&self) -> Self

Clears date/time units until the millisecond (inclusive).

fn clear_until_micro(&self) -> Self

Clears date/time units until the microsecond (inclusive).

fn clear_until_nano(&self) -> Self

Clears date/time units until the nanosecond (inclusive).

type SubDayReturn = i64

Return type for the hour_, minutes_ and seconds_since functions. Is i32 for Time and i64 for DateTime.

fn hours_since(&self, compare: &Self) -> Self::SubDayReturn

Returns full hours since the provided time.

fn minutes_since(&self, compare: &Self) -> Self::SubDayReturn

Returns full minutes since the provided time.

fn seconds_since(&self, compare: &Self) -> Self::SubDayReturn

Returns full seconds since the provided time.

type SubSecReturn = i128

Return type for the millis_, micros_ and manos_since functions. Is i64 for Time and i128 for DateTime.

fn millis_since(&self, compare: &Self) -> Self::SubSecReturn

Returns full milliseconds since the provided time.

fn micros_since(&self, compare: &Self) -> Self::SubSecReturn

Returns full microseconds since the provided time.

fn nanos_since(&self, compare: &Self) -> Self::SubSecReturn

Returns full nanoseconds since the provided time.

impl Copy for DateTime

impl Eq for DateTime