Struct astrolabe::Time

pub struct Time { /* private fields */ }

Clock time with nanosecond precision.

Implementations

impl Time

pub fn now() -> Self

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

let time = Time::now();
println!("{}", time);

pub fn from_hms(hour: u32, min: u32, sec: u32) -> Result<Self, AstrolabeError>

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

Returns an OutOfRange error if the provided time is invalid.

let time = Time::from_hms(12, 32, 01).unwrap();
assert_eq!("12:32:01", time.format("HH:mm:ss"));

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

Creates a new Time instance from seconds.

Returns an OutOfRange error if the provided seconds are invalid (over 86399)

let time = Time::from_seconds(1_234).unwrap();
assert_eq!("00:20:34", time.format("HH:mm:ss"));

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

Creates a new Time instance from seconds.

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

let time = Time::from_nanoseconds(1_234).unwrap();
assert_eq!(1_234, time.as_nanoseconds());

pub fn as_seconds(&self) -> u64

Returns the time as seconds.

let time = Time::from_hms(12, 12, 12).unwrap();
assert_eq!(43932, time.as_seconds());

pub fn as_nanoseconds(&self) -> u64

Returns the time as nanoseconds.

let time = Time::from_hms(12, 12, 12).unwrap();
assert_eq!(43_932_000_000_000, time.as_nanoseconds());

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

Returns the number of nanoseconds between two Time instances.

let time = Time::from_hms(12, 0, 0).unwrap();
let time_2 = Time::from_hms(12, 0, 1).unwrap();
assert_eq!(1_000_000_000, time.between(&time_2));
assert_eq!(1_000_000_000, time_2.between(&time));

pub fn get(&self, unit: TimeUnit) -> u64

Get a specific TimeUnit.

let time = Time::from_hms(12, 32, 15).unwrap();
assert_eq!(12, time.get(TimeUnit::Hour));
assert_eq!(32, time.get(TimeUnit::Min));
assert_eq!(15, time.get(TimeUnit::Sec));

let time = Time::from_nanoseconds(1_123_456_789).unwrap();
assert_eq!(12, time.get(TimeUnit::Centis));
assert_eq!(123, time.get(TimeUnit::Millis));
assert_eq!(123_456, time.get(TimeUnit::Micros));
assert_eq!(123_456_789, time.get(TimeUnit::Nanos));

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

Creates a new Time instance with a specific TimeUnit set to the provided value.

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

let mut time = Time::from_hms(12, 32, 15).unwrap();
time = time.set(15, TimeUnit::Hour).unwrap();
time = time.set(10, TimeUnit::Min).unwrap();
assert_eq!("15:10:15", time.format("HH:mm:ss"));

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

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

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

let time = Time::from_hms(12, 32, 15).unwrap();

let applied = time.apply(1, TimeUnit::Hour).unwrap();
assert_eq!("12:32:15", time.format("HH:mm:ss"));
assert_eq!("13:32:15", applied.format("HH:mm:ss"));

let applied_2 = applied.apply(-1, TimeUnit::Hour).unwrap();
assert_eq!("12:32:15", applied_2.format("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
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 time = Time::from_hms(12, 32, 1).unwrap();
assert_eq!("12:32:01", time.format("HH:mm:ss"));
// Escape characters
assert_eq!("12:mm:ss", time.format("HH:'mm:ss'"));
assert_eq!("12:'32:01'", time.format("HH:''mm:ss''"));

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

Creates a new Time 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 time itself which always represents UTC.

Returns an OutOfRange error if the provided offset is not between UTC-23:59:59 and UTC+23:59:59.

let time = Time::from_hms(12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = time.set_offset_time(2, 0, 0, Offset::East).unwrap();
assert_eq!("14:32:01", with_offset.format("HH:mm:ss"));

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

Creates a new Time 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 time itself which always represents UTC.

Returns an OutOfRange error if the provided offset is not between UTC-23:59:59 and UTC+23:59:59.

let time = Time::from_hms(12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = time.set_offset(7200).unwrap();
assert_eq!("14:32:01", with_offset.format("HH:mm:ss"));

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

Creates a new Time instance, assuming the current instance has the provided offset applied. The new instance will have the specified offset and the time itself will be converted to UTC.

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

Returns an OutOfRange error if the provided offset is not between UTC-23:59:59 and UTC+23:59:59.

let time = Time::from_hms(12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = time.as_offset_time(2, 0, 0, Offset::East).unwrap();
assert_eq!("12:32:01", with_offset.format("HH:mm:ss"));

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

Creates a new Time instance, assuming the current instance has the provided offset applied. The new instance will have the specified offset and the time itself will be converted to UTC.

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

Returns an OutOfRange error if the provided offset is not between UTC-23:59:59 and UTC+23:59:59.

let time = Time::from_hms(12, 32, 1).unwrap();
// Set offset to UTC+2
let with_offset = time.as_offset(7200).unwrap();
assert_eq!("12:32:01", with_offset.format("HH:mm:ss"));

pub fn get_offset(&self) -> i32

Returns the set offset in seconds.

let time = Time::now().set_offset(3600).unwrap();
assert_eq!(3600, time.get_offset());

Trait Implementations

impl Clone for Time

fn clone(&self) -> Time

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Time

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

Formats the value using the given formatter.

impl Default for Time

fn default() -> Time

Returns the “default value” for a type.

impl Display for Time

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

Formats the value using the given formatter.

impl From<&Time> for Time

fn from(time: &Time) -> Self

Converts to this type from the input type.

impl PartialEq<Time> for Time

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 Time

impl Eq for Time

impl StructuralEq for Time