Struct utc2k::Utc2k [−][src]
pub struct Utc2k { /* fields omitted */ }
Expand description
UTC2K.
This is a lightweight date/time object for UTC date ranges within the
current century (e.g. 2000-01-01 00:00:00
to 2099-12-31 23:59:59
).
Values outside this range are saturated to fit, unless using
Utc2k::checked_from_unixtime
.
To instantiate from a UTC unix timestamp, use From<u32>
. To try to parse
from a YYYY-MM-DD HH:MM:SS
string, use TryFrom<&str>
.
To manually construct from individual parts, you can just call Utc2k::new
.
A Utc2k
object can be turned back into its constituent parts via
Utc2k::parts
, or the individual methods like Utc2k::year
, Utc2k::month
,
etc.
It can be converted into a unix timestamp with Utc2k::unixtime
.
Examples
use utc2k::Utc2k;
let date = Utc2k::default(); // 2000-01-01 00:00:00
let date = Utc2k::now(); // The current time.
let date = Utc2k::from(4_102_444_799_u32); // 2099-12-31 23:59:59
// String parsing is fallible, but flexible. So long as the numbers we
// need are in the right place, it will be fine.
assert!(Utc2k::try_from("2099-12-31 23:59:59").is_ok()); // Fine.
assert!(Utc2k::try_from("2099-12-31T23:59:59.0000").is_ok()); // Also fine.
assert!(Utc2k::try_from("2099-12-31").is_ok()); // Also fine, but midnight.
assert!(Utc2k::try_from("January 1, 2010").is_err()); // Nope!
Implementations
Minimum Value.
This is equivalent to 2000-01-01 00:00:00
.
Examples
use utc2k::Utc2k;
let date = Utc2k::min();
assert_eq!(date.to_string(), "2000-01-01 00:00:00");
Maximum Value.
This is equivalent to 2099-12-31 23:59:59
.
Examples
use utc2k::Utc2k;
let date = Utc2k::max();
assert_eq!(date.to_string(), "2099-12-31 23:59:59");
New (From Parts).
This will create a new instance from individual year, month, etc., parts.
Overflowing units will be carried over where appropriate, so for example, 13 months becomes 1 year and 1 month.
Dates prior to 2000 or after 2099 will be saturated to fit.
Examples
use utc2k::Utc2k;
let date = Utc2k::new(2010, 5, 5, 16, 30, 1);
assert_eq!(date.to_string(), "2010-05-05 16:30:01");
Yesterday.
Create a new instance representing one day ago (present time).
Examples
use utc2k::Utc2k;
assert_eq!(Utc2k::yesterday(), Utc2k::now() - 86_400_u32);
From Date/Time.
Parse a string containing a date/time in YYYY-MM-DD HH:MM:SS
format.
This operation is naive and only looks at the positions where numbers
are expected.
In other words, 2020-01-01 00:00:00
will parse the same as
2020/01/01 00:00:00
or even 2020-01-01 00:00:00.0000 PDT
.
As with all the other methods, dates outside the 2000..=2099
range
will be saturated (non-failing), and overflows will be carried over to
the appropriate unit (e.g. 13 months will become +1 year and 1 month).
Examples
use utc2k::Utc2k;
// This isn't long enough.
assert!(Utc2k::from_datetime_str("2021/06/25").is_err());
// This is fine.
let date = Utc2k::from_datetime_str("2021-06-25 13:15:25.0000").unwrap();
assert_eq!(date.to_string(), "2021-06-25 13:15:25");
// This is all wrong.
assert!(Utc2k::from_datetime_str("Applebutter").is_err());
Errors
If any of the digits fail to parse, or if the string is insufficiently sized, an error will be returned.
From Date/Time.
Parse a string containing a date/time in YYYY-MM-DD
format. This
operation is naive and only looks at the positions where numbers are
expected.
In other words, 2020-01-01
will parse the same as 2020/01/01
or
even 2020-01-01 13:03:33.5900 PDT
.
As with all the other methods, dates outside the 2000..=2099
range
will be saturated (non-failing), and overflows will be carried over to
the appropriate unit (e.g. 13 months will become +1 year and 1 month).
The time will always be set to midnight when using this method.
Examples
use utc2k::Utc2k;
// This is fine.
let date = Utc2k::from_date_str("2021/06/25").unwrap();
assert_eq!(date.to_string(), "2021-06-25 00:00:00");
// This is fine, but the time will be ignored.
let date = Utc2k::from_date_str("2021-06-25 13:15:25.0000").unwrap();
assert_eq!(date.to_string(), "2021-06-25 00:00:00");
// This is all wrong.
assert!(Utc2k::from_date_str("Applebutter").is_err());
Errors
If any of the digits fail to parse, or if the string is insufficiently sized, an error will be returned.
Parts.
Return the year, month, etc., parts.
Alternatively, if you only want the date bits, use Utc2k::ymd
, or
if you only want the time bits, use Utc2k::hms
.
Examples
use utc2k::Utc2k;
let date = Utc2k::new(2010, 5, 4, 16, 30, 1);
assert_eq!(date.parts(), (2010, 5, 4, 16, 30, 1));
Date Parts.
Return the year, month, and day.
If you want the time too, call Utc2k::parts
instead.
Examples
use utc2k::Utc2k;
let date = Utc2k::new(2010, 5, 5, 16, 30, 1);
assert_eq!(date.ymd(), (2010, 5, 5));
Time Parts.
Return the hours, minutes, and seconds.
If you want the date too, call Utc2k::parts
instead.
Examples
use utc2k::Utc2k;
let date = Utc2k::new(2010, 5, 5, 16, 30, 1);
assert_eq!(date.hms(), (16, 30, 1));
Is Leap Year?
This returns true
if this date is/was in a leap year.
Examples
use utc2k::Utc2k;
let date = Utc2k::try_from("2020-05-10 00:00:00").unwrap();
assert!(date.leap_year());
let date = Utc2k::try_from("2021-03-15 00:00:00").unwrap();
assert!(! date.leap_year());
Abbreviated Month Name.
Return the abbreviated name of the month, nice and pretty.
Examples
use utc2k::Utc2k;
let date = Utc2k::try_from("2020-06-24 20:19:30").unwrap();
assert_eq!(date.month_abbreviation(), "Jun");
Month Name.
Return the name of the month, nice and pretty.
Examples
use utc2k::Utc2k;
let date = Utc2k::try_from("2020-06-24 20:19:30").unwrap();
assert_eq!(date.month_name(), "June");
Month Size (Days).
This returns the total number of days this month could hold, or put another way, the last day of this month.
The value will always be between 28..=31
, with leap Februaries
returning 29
.
Examples
use utc2k::Utc2k;
let date = Utc2k::try_from("2021-07-08 13:22:01").unwrap();
assert_eq!(date.month_size(), 31);
Ordinal.
Return the day-of-year value. This will be between 1..=365
(or 1..=366
for leap years).
Examples
use utc2k::Utc2k;
let date = Utc2k::try_from("2020-05-10 00:00:00").unwrap();
assert_eq!(date.ordinal(), 131);
let date = Utc2k::try_from("2021-01-15 00:00:00").unwrap();
assert_eq!(date.ordinal(), 15);
Seconds From Midnight.
Return the number of seconds since midnight. In other words, this adds up all of the time bits.
Examples
use utc2k::Utc2k;
let date = Utc2k::new(2010, 11, 30, 0, 0, 0);
assert_eq!(date.seconds_from_midnight(), 0);
let date = Utc2k::new(2010, 11, 30, 0, 0, 30);
assert_eq!(date.seconds_from_midnight(), 30);
let date = Utc2k::new(2010, 11, 30, 0, 1, 30);
assert_eq!(date.seconds_from_midnight(), 90);
let date = Utc2k::new(2010, 11, 30, 12, 30, 10);
assert_eq!(date.seconds_from_midnight(), 45_010);
Formatted.
This returns a FmtUtc2k
and is equivalent to calling
FmtUtc2k::from(self)
.
Examples
use utc2k::{FmtUtc2k, Utc2k};
let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.formatted(), FmtUtc2k::from(date));
To RFC3339.
Return a string formatted according to RFC3339.
Note: this method is allocating.
Examples
use utc2k::Utc2k;
let date = Utc2k::new(2021, 12, 13, 11, 56, 1);
assert_eq!(date.to_rfc3339(), "2021-12-13T11:56:01Z");
Unix Timestamp.
Return the unix timestamp for this object.
Examples
use utc2k::Utc2k;
let date = Utc2k::default(); // 2000-01-01 00:00:00
assert_eq!(date.unixtime(), Utc2k::MIN_UNIXTIME);
Change Time.
Return a new Utc2k
instance with the original date — unless there
is carry-over needed — and a new time.
Examples
use utc2k::Utc2k;
let date = Utc2k::default();
assert_eq!(date.to_string(), "2000-01-01 00:00:00");
// Change the time bits.
assert_eq!(date.with_time(13, 14, 15).to_string(), "2000-01-01 13:14:15");
Checked Add.
Return a new Utc2k
instance set n seconds into the future from
this one, returning none
(rather than saturating) on overflow.
If you’d rather saturate addition, you can just use std::ops::Add
.
Examples
use utc2k::Utc2k;
let date = Utc2k::max();
assert!(date.checked_add(1).is_none());
let date = Utc2k::new(2010, 1, 1, 0, 0, 0);
let added = date.checked_add(86_413).unwrap();
assert_eq!(added.to_string(), "2010-01-02 00:00:13");
From Unixtime (Checked).
This can be used instead of the usual From<u32>
if you’d like to
trigger an error when the timestamp is out of range (rather than just
saturating it).
Errors
An error will be returned if the timestamp is less than Utc2k::MIN_UNIXTIME
or greater than Utc2k::MAX_UNIXTIME
.
Examples
use utc2k::Utc2k;
// Too old.
assert!(Utc2k::checked_from_unixtime(0).is_err());
// Too new.
assert!(Utc2k::checked_from_unixtime(u32::MAX).is_err());
// This fits.
assert!(Utc2k::checked_from_unixtime(Utc2k::MIN_UNIXTIME).is_ok());
Checked Sub.
Return a new Utc2k
instance set n seconds before this one,
returning none
(rather than saturating) on overflow.
If you’d rather saturate subtraction, you can just use std::ops::Sub
.
Examples
use utc2k::Utc2k;
let date = Utc2k::min();
assert!(date.checked_sub(1).is_none());
let date = Utc2k::new(2010, 1, 1, 0, 0, 0);
let subbed = date.checked_sub(86_413).unwrap();
assert_eq!(subbed.to_string(), "2009-12-30 23:59:47");
Trait Implementations
Performs the +=
operation. Read more
From Timestamp.
Note, this will saturate to Utc2k::MIN_UNIXTIME
and
Utc2k::MAX_UNIXTIME
if the timestamp is out of range.
Examples
use utc2k::Utc2k;
assert_eq!(Utc2k::from(0).to_string(), "2000-01-01 00:00:00");
assert_eq!(Utc2k::from(u32::MAX).to_string(), "2099-12-31 23:59:59");
This method returns an ordering between self
and other
values if one exists. Read more
This method tests less than (for self
and other
) and is used by the <
operator. Read more
This method tests less than or equal to (for self
and other
) and is used by the <=
operator. Read more
This method tests greater than (for self
and other
) and is used by the >
operator. Read more
Performs the -=
operation. Read more
From OsStr
.
use std::ffi::OsStr;
use utc2k::Utc2k;
assert_eq!(
Utc2k::try_from(OsStr::new("2013-12-15 21:30:02")).unwrap().to_string(),
"2013-12-15 21:30:02"
);
assert_eq!(
Utc2k::try_from(OsStr::new("2013-12-15")).unwrap().to_string(),
"2013-12-15 00:00:00"
);
type Error = Utc2kError
type Error = Utc2kError
The type returned in the event of a conversion error.
Parse String.
This will attempt to construct a Utc2k
from a date/time or date
string. Parsing is naive; only the positions where numbers are
expected will be looked at.
String length is used to determine whether or not the value should be parsed as a full date/time (19) or just a date (10).
See Utc2k::from_datetime_str
and Utc2k::from_date_str
for more
information.
Examples
use utc2k::Utc2k;
let date = Utc2k::try_from("2021/06/25").unwrap();
assert_eq!(date.to_string(), "2021-06-25 00:00:00");
let date = Utc2k::try_from("2021-06-25 13:15:25.0000").unwrap();
assert_eq!(date.to_string(), "2021-06-25 13:15:25");
assert!(Utc2k::try_from("Applebutter").is_err());
type Error = Utc2kError
type Error = Utc2kError
The type returned in the event of a conversion error.
Auto Trait Implementations
impl RefUnwindSafe for Utc2k
impl UnwindSafe for Utc2k
Blanket Implementations
Mutably borrows from an owned value. Read more