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.

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.get(DateTimeUnit::Year));

pub fn from_ymdhms(
    year: i32,
    month: u32,
    day: u32,
    hour: u32,
    min: u32,
    sec: 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 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 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 from_timestamp(timestamp: i64) -> Result<Self, AstrolabeError>

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

Returns an OutOfRange error if the provided timestamp would result in an out of range date.

let date_time = DateTime::from_timestamp(0).unwrap();
assert_eq!("1970/01/01 00:00:00", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn from_days(days: i32) -> Self

Creates a new DateTime instance from days.

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

pub fn from_seconds(seconds: i64) -> Result<Self, AstrolabeError>

Creates a new DateTime instance from seconds.

Returns an OutOfRange error if the provided seconds would result in an out of range date.

let date_time = DateTime::from_seconds(86400).unwrap();
assert_eq!("0001/01/02", date_time.format("yyyy/MM/dd"));

pub fn from_nanoseconds(nanoseconds: i128) -> Result<Self, AstrolabeError>

Creates a new DateTime instance from nanoseconds.

Returns an OutOfRange error if the provided nanoseconds would result in an out of range date.

let date_time = DateTime::from_nanoseconds(86_400_000_000_000).unwrap();
assert_eq!("0001/01/02", date_time.format("yyyy/MM/dd"));

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

Creates a new DateTime instance from an RFC3339 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 set_time(&self, nanoseconds: u64) -> Result<Self, AstrolabeError>

Creates a new DateTime with the specified amount of nanoseconds set as clock time.

Returns an OutOfRange error if the provided nanoseconds are invalid (over 86_399_999_999_999)

let date_time = DateTime::from_days(738276).set_time(3_600_000_000_000).unwrap();
assert_eq!("2022/05/02 01:00:00", date_time.format("yyyy/MM/dd HH:mm:ss"));

pub fn date(&self) -> Date

Returns the date.

let date_time = DateTime::from_days(123);
let date = date_time.date();
assert_eq!(123, date.as_days());

pub fn time(&self) -> Time

Returns the clock time.

let date_time = DateTime::from_days(0).set_time(3_600_000_000_000).unwrap();
let time = date_time.time();
assert_eq!(3_600_000_000_000, time.as_nanoseconds());

pub fn as_days(&self) -> i32

Returns the number of days since January 1, 0001 00:00:00 UTC. (Negative if date is before)

let date_time = DateTime::from_ymd(1, 1, 2).unwrap();
assert_eq!(1, date_time.as_days());

pub fn as_seconds(&self) -> i64

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

let date_time = DateTime::from_ymd(1, 1, 2).unwrap();
assert_eq!(86400, date_time.as_seconds());

pub fn as_nanoseconds(&self) -> i128

Returns the number of nanoseconds since January 1, 0001 00:00:00 UTC. (Negative if date is before)

let date_time = DateTime::from_ymd(1, 1, 2).unwrap();
assert_eq!(86_400_000_000_000, date_time.as_nanoseconds());

pub fn timestamp(&self) -> i64

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

let date_time = DateTime::from_ymd(2000, 1, 1).unwrap();
assert_eq!(946_684_800, date_time.timestamp());

pub fn between(&self, compare: &Self) -> u64

Returns the number of seconds between two DateTime instances.

let date_time1 = DateTime::from_ymd(1970, 1, 1).unwrap();
let date_time2 = DateTime::from_ymd(1970, 1, 2).unwrap();
assert_eq!(86400, date_time1.between(&date_time2));
assert_eq!(86400, date_time2.between(&date_time1));

pub fn get(&self, unit: DateTimeUnit) -> i64

Get a specific DateTimeUnit.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
assert_eq!(2022, date_time.get(DateTimeUnit::Year));
assert_eq!(5, date_time.get(DateTimeUnit::Month));
assert_eq!(32, date_time.get(DateTimeUnit::Min));

pub fn apply(
    &self,
    amount: i64,
    unit: DateTimeUnit
) -> Result<Self, AstrolabeError>

Creates a new DateTime instance with a specified amount of time applied (added or subtracted).

Note: When using DateTimeUnit::Month, it adds calendar months and not 30 days. See it’s documentation for examples.

Returns an OutOfRange error if the provided value would result in an out of range date.

let date_time = DateTime::from_ymdhms(1970, 1, 1, 12, 32, 1).unwrap();
let applied = date_time.apply(1, DateTimeUnit::Day).unwrap();
assert_eq!("1970-01-01 12:32:01", date_time.format("yyyy-MM-dd HH:mm:ss"));
assert_eq!("1970-01-02 12:32:01", applied.format("yyyy-MM-dd HH:mm:ss"));
let applied_2 = applied.apply(-1, DateTimeUnit::Hour).unwrap();
assert_eq!("1970-01-02 11:32:01", applied_2.format("yyyy-MM-dd HH:mm:ss"));

pub fn set(&self, value: i32, unit: DateTimeUnit) -> Result<Self, AstrolabeError>

Creates a new DateTime instance with a specific DateTimeUnit set to the provided value.

Returns an OutOfRange error if the provided value is invalid or out of range.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
assert_eq!(2000, date_time.set(2000, DateTimeUnit::Year).unwrap().get(DateTimeUnit::Year));
assert_eq!(10, date_time.set(10, DateTimeUnit::Min).unwrap().get(DateTimeUnit::Min));

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

Format as an RFC3339 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 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 set_offset_time(
    &self,
    hour: u32,
    minute: u32,
    second: u32,
    offset: Offset
) -> Result<Self, AstrolabeError>

Creates a new DateTime instance with a given timezone offset defined as time units (hour, minute and second). Offset can range anywhere from UTC-23:59:59 to UTC+23:59:59.

The offset affects all format functions and the get and set functions but does not change the datetime itself which always represents UTC.

Returns an OutOfRange error if the provided offset is either not between UTC-23:59:59 and UTC+23:59:59 or if it would lead to an out of range date.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = date_time.set_offset(7200).unwrap();
assert_eq!("2022/05/02 14:32:01", with_offset.format("yyyy/MM/dd HH:mm:ss"));

pub fn set_offset(&self, seconds: i32) -> Result<Self, AstrolabeError>

Creates a new DateTime instance with a given timezone offset defined as seconds. Offset can range anywhere from UTC-23:59:59 to UTC+23:59:59.

The offset affects all format functions and the get and set functions but does not change the datetime itself which always represents UTC.

Returns an OutOfRange error if the provided offset is either not between UTC-23:59:59 and UTC+23:59:59 or if it would lead to an out of range date.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = date_time.set_offset(7200).unwrap();
assert_eq!("2022/05/02 14:32:01", with_offset.format("yyyy/MM/dd HH:mm:ss"));

pub fn as_offset_time(
    &self,
    hour: u32,
    minute: u32,
    second: u32,
    offset: Offset
) -> Result<Self, AstrolabeError>

Creates a new DateTime instance, 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.

The offset affects all format functions and the get and set functions but does not change the datetime itself which always represents UTC.

Returns an OutOfRange error if the provided offset is either not between UTC-23:59:59 and UTC+23:59:59 or if it would lead to an out of range date.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = date_time.as_offset_time(2, 0, 0, Offset::East).unwrap();
assert_eq!("2022/05/02 12:32:01", with_offset.format("yyyy/MM/dd HH:mm:ss"));

pub fn as_offset(&self, seconds: i32) -> Result<Self, AstrolabeError>

Creates a new DateTime instance, 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.

The offset affects all format functions and the get and set functions but does not change the datetime itself which always represents UTC.

Returns an OutOfRange error if the provided offset is either not between UTC-23:59:59 and UTC+23:59:59 or if it would lead to an out of range date.

let date_time = DateTime::from_ymdhms(2022, 5, 2, 12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = date_time.as_offset(7200).unwrap();
assert_eq!("2022/05/02 12:32:01", with_offset.format("yyyy/MM/dd HH:mm:ss"));

pub fn get_offset(&self) -> i32

Returns the set offset in seconds.

let date_time = DateTime::now().set_offset(3600).unwrap();
assert_eq!(3600, date_time.get_offset());

Trait Implementations

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 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 Display for DateTime

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

Formats the value using the given formatter.

impl From<&DateTime> for DateTime

fn from(date_time: &DateTime) -> Self

Converts to this type from the input type.

impl PartialEq<DateTime> 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 Copy for DateTime

impl Eq for DateTime

impl StructuralEq for DateTime