Struct utc2k::Utc2k

source · []
pub struct Utc2k { /* private fields */ }
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");
Now.

Create a new instance representing the current UTC time.

Tomorrow.

Create a new instance representing one day from now (present time).

Examples
use utc2k::Utc2k;

assert_eq!(Utc2k::tomorrow(), Utc2k::now() + 86_400_u32);
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.

Parse Time.

This method attempts to parse a time string in the HH:MM:SS format, returning the hours, minutes, and seconds as integers.

As with other methods in this library, only positions where numbers are expected will be looked at. 01:02:03 will parse the same way as 01-02-03.

Examples
use utc2k::Utc2k;

assert_eq!(
    Utc2k::parse_time_str("15:35:47"),
    Ok((15, 35, 47))
);

// The hours are out of range.
assert!(Utc2k::parse_time_str("30:35:47").is_err());
Errors

This method will return an error if any of the numeric bits are invalid or out of range (hours must be < 24, minutes and seconds < 60).

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));
Year.

This returns the year value.

Examples
use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.year(), 2010);
Month.

This returns the month value.

Examples
use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.month(), 5);
Month (enum).

This returns the month value as a Month.

Examples
use utc2k::{Month, Utc2k};

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.month_enum(), Month::May);
Day.

This returns the day value.

Examples
use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.day(), 15);
Hour.

This returns the hour value.

Examples
use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.hour(), 16);
Minute.

This returns the minute value.

Examples
use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.minute(), 30);
Second.

This returns the second value.

Examples
use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.second(), 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);
Weekday.

Return the Weekday corresponding to the given date.

Examples
use utc2k::{Utc2k, Weekday};

let date = Utc2k::try_from("2021-07-08 13:22:01").unwrap();
assert_eq!(date.weekday(), Weekday::Thursday);
assert_eq!(date.weekday().as_ref(), "Thursday");
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");
To RFC2822.

Return a string formatted according to RFC2822.

There are a couple things to consider:

  • This method is allocating;
  • The length of the resulting string will either be 30 or 31 depending on whether the day is double-digit;
Examples
use utc2k::Utc2k;

let date = Utc2k::new(2003, 7, 1, 10, 52, 37);
assert_eq!(date.to_rfc2822(), "Tue, 01 Jul 2003 10:52:37 +0000");

let date = Utc2k::new(2036, 12, 15, 16, 30, 55);
assert_eq!(date.to_rfc2822(), "Mon, 15 Dec 2036 16:30:55 +0000");
From RFC2822.

This method can be used to construct a Utc2k from an RFC2822-formatted string. Variations with and without a leading weekday, and with and without a trailing offset, are supported. If an offset is included, the datetime will be adjusted accordingly to make it properly UTC.

Note: missing offsets are meant to imply “localized” time, but as this library has no timezone handling, strings without any “+HHMM” at the end will be parsed as if they were already in UTC.

Examples
use utc2k::Utc2k;

assert_eq!(
    Utc2k::from_rfc2822("Tue, 1 Jul 2003 10:52:37 +0000"),
    Some(Utc2k::new(2003, 7, 1, 10, 52, 37)),
);

assert_eq!(
    Utc2k::from_rfc2822("Tue, 01 Jul 2003 10:52:37 +0000"),
    Some(Utc2k::new(2003, 7, 1, 10, 52, 37)),
);

assert_eq!(
    Utc2k::from_rfc2822("1 Jul 2003 10:52:37"),
    Some(Utc2k::new(2003, 7, 1, 10, 52, 37)),
);

assert_eq!(
    Utc2k::from_rfc2822("01 Jul 2003 10:52:37"),
    Some(Utc2k::new(2003, 7, 1, 10, 52, 37)),
);

assert_eq!(
    Utc2k::from_rfc2822("Tue, 10 Jul 2003 10:52:37 -0700"),
    Some(Utc2k::new(2003, 7, 10, 17, 52, 37)),
);

assert_eq!(
    Utc2k::from_rfc2822("Tue, 1 Jul 2003 10:52:37 +0430"),
    Some(Utc2k::new(2003, 7, 1, 6, 22, 37)),
);
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

The resulting type after applying the + operator.

Performs the + operation. Read more

Performs the += operation. Read more

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Formats the value using the given formatter. Read more

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

Converts to this type from the input type.

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");

Feeds this value into the given Hasher. Read more

Feeds a slice of this type into the given Hasher. Read more

This method returns an Ordering between self and other. Read more

Compares and returns the maximum of two values. Read more

Compares and returns the minimum of two values. Read more

Restrict a value to a certain interval. Read more

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

This method tests for !=.

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

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

Subtraction.

This method returns a new Utc2k object reduced by a given number of seconds.

Examples
use utc2k::Utc2k;

assert_eq!(
    Utc2k::new(2020, 1, 5, 0, 0, 0) - 86_400_u32,
    Utc2k::new(2020, 1, 4, 0, 0, 0),
);

assert_eq!(
    Utc2k::new(2020, 1, 5, 0, 0, 0) - 86_399_u32,
    Utc2k::new(2020, 1, 4, 0, 0, 1),
);

assert_eq!(
    Utc2k::new(2020, 1, 5, 3, 10, 20) - 14_400_u32,
    Utc2k::new(2020, 1, 4, 23, 10, 20),
);

assert_eq!(
    Utc2k::new(2020, 1, 1, 3, 10, 20) - 14_400_u32,
    Utc2k::new(2019, 12, 31, 23, 10, 20),
);

The resulting type after applying the - operator.

Performs the -= operation. Read more

Parse Slice.

This will attempt to construct a Utc2k from a date/time or date slice. See Utc2k::from_datetime_str and Utc2k::from_date_str for more information.

Examples
use utc2k::Utc2k;

let date = Utc2k::try_from(&b"2021/06/25"[..]).unwrap();
assert_eq!(date.to_string(), "2021-06-25 00:00:00");

let date = Utc2k::try_from(&b"2021-06-25 13:15:25.0000"[..]).unwrap();
assert_eq!(date.to_string(), "2021-06-25 13:15:25");

assert!(Utc2k::try_from(&b"2021-06-applesauces"[..]).is_err());

The type returned in the event of a conversion error.

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"
);

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("2021-06-applesauces").is_err());

The type returned in the event of a conversion error.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

Uses borrowed data to replace owned data, usually by cloning. Read more

Converts the given value to a String. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.