Struct 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 (i.e. 2000-01-01 00:00:00..=2099-12-31 23:59:59).

Values outside this range are saturated to fit, unless using methods like Utc2k::checked_from_ascii or Utc2k::checked_from_unixtime.

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-31").is_ok()); // Also fine, but midnight.
assert!(Utc2k::try_from("2099-12-31T23:59:59.1234").is_ok()); // Also fine, but floored.
assert!(Utc2k::try_from("January 1, 2010").is_err()); // Nope!

Implementations§

Source §

impl Utc2k

§Instantiation.

Source

pub const fn new(y: u16, m: u8, d: u8, hh: u8, mm: u8, ss: u8) -> Self

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

Source

pub const fn from_ascii(src: &[u8]) -> Option<Self>

§From ASCII Date/Time Slice.

Try to parse a date/time value from an ASCII slice, returning a Utc2k instance if successful, None if not.

Note that this method will automatically clamp dates outside the supported 2000..=2099 range to Utc2k::MIN/Utc2k::MAX.

If you’d rather out-of-range values “fail” instead, use Utc2k::checked_from_ascii.

§Supported Formats.

This method can be used to parse dates and datetimes — but not times by themselves — from formats that A) order the components biggest to smallest; and B) use four digits to express the year, and two digits for everything else.

Digits can either be squished together like YYYYMMDD or YYYYMMDDhhmmss, or separated by single non-digit bytes, like YYYY/MM/DD or YYYY-MM-DD hh:mm:ss.

(Times can technically end …ss.ffff, but Utc2k doesn’t support fractional seconds; they’re ignored if present.)

Complete datetimes can optionally end with “Z”, “ UT“, “ UTC“, or “ GMT“ — all of which are ignored — or a fixed UTC offset of the ±hhmm/±hh:mm varieties which, if present, will be parsed and factored into the result. (Fixed offsets can also be written like “GMT±hhmm” or “UTC±hhmm”.)

Parsing will fail for sources containing any other random trailing data, including things like “CST”-style time zone abbreviations.

§Examples

use utc2k::Utc2k;

// Separators are flexible.
let dates: [&[u8]; 5] = [
    b"20250615",   // Squished.
    b"2025 06 15", // Spaced.
    b"2025/06/15", // Slashed.
    b"2025-06-15", // Dashed.
    b"2025#06#15", // Hashed? Haha.
];
for raw in dates {
    assert_eq!(
        Utc2k::from_ascii(raw).unwrap().parts(),
        (2025, 6, 15, 0, 0, 0),
//                    ^  ^  ^ Time defaults to midnight.
    );
}

// Same for datetimes.
let datetimes: [&[u8]; 14] = [
    b"20250615123001",
    b"2025-06-15 12:30:01",
    b"2025-06-15T12:30:01Z",
    b"2025/06/15:12:30:01 GMT",
    b"2025/06/15:12:30:01 GMT+0000", // Redundant.
    b"2025/06/15:12:30:01gmt", // Space/case-insensitive.
    b"2025/06/15:12:30:01 UT",
    b"2025/06/15:12:30:01 UTC",
    b"2025/06/15:12:30:01 UTC+0000", // Redundant.
    b"2025/06/15 12:30:01.000 +0000",
    b"2025/06/15 12:30:01+0000",
    b"2025/06/15T16:30:01+04:00", // Colon in offset
    b"2025/06/15T16:30:01UTC+04:00",
    b"2025/06/15T05:30:01-07:00",
];
for raw in datetimes {
    assert_eq!(
        Utc2k::from_ascii(raw).unwrap().parts(),
        (2025, 6, 15, 12, 30, 1),
    );
}

// Not everything will work out…
let bad: [&[u8]; 9] = [
    b"2025-06-15 123001", // Formats cannot mix-and-match
    b"2025-06-15123001",  // squished/separated.
    b"20250615 12:30:01",
    b"2025061512:30:01",
    b"2025-01-01Z",       // Date-only strings cannot contain
    b"2025-01-01 +0000",  // tz/offset details.
    b"2025-01-01 UTC",
    b"2025-01-01 00:00:00 PDT", // Only UTC-related identifiers are
    b"2025-01-01 00:00:00 EST", // supported.
];
for raw in bad {
    assert!(Utc2k::from_ascii(raw).is_none());
}

// UTC offsets will get factored in accordingly.
assert_eq!(
    Utc2k::from_ascii(b"2025-06-15 12:30:01 +0330")
        .unwrap()
        .parts(),
    (2025, 6, 15, 9, 0, 1),
);
assert_eq!(
    Utc2k::from_ascii(b"2025-06-15T12:30:01.54321-0700")
        .unwrap() //                       ^----^ Ignored.
        .parts(),
    (2025, 6, 15, 19, 30, 1),
);

// The input doesn't have to follow calendar/clock grouping
// conventions, but the output always will.
assert_eq!(
    Utc2k::from_ascii(b"2000-13-10 24:60:61")
        .unwrap() //         ^     ^  ^  ^ Logical "overflow".
        .parts(),
    (2001, 1, 11, 1, 1, 1),
//   ^     ^  ^   ^  ^  ^ Realigned.
);
assert_eq!(
    Utc2k::from_ascii(b"2050-02-00")
        .unwrap() //            ^ Logical "underflow".
        .parts(),
    (2050, 1, 31, 0, 0, 0),
//         ^  ^ Realigned.
);

// Returned values are clamped to the `2000..=2099` range.
assert_eq!(
    Utc2k::from_ascii(b"1994 04 08"),
    Some(Utc2k::MIN), // 2000-01-01 00:00:00
);
assert_eq!(
    Utc2k::from_ascii(b"3000/01/01"),
    Some(Utc2k::MAX), // 2099-12-31 23:59:59
);

Source

pub const fn from_rfc2822(src: &[u8]) -> Option<Self>

§From RFC2822 Date/Time Slice.

Try to parse a date/time value from a RFC2822-formatted byte slice, returning a Utc2k instance if successful, None if not.

§Examples

use utc2k::Utc2k;

// This spec tolerates a lot of variation…
let dates: [&[u8]; 7] = [
    b"Tue, 1 Jul 2003 10:52:37 +0000",  // Single-digit day.
    b"Tue,  1 Jul 2003 10:52:37 +0000", // Digit/space substitution.
    b"Tue, 01 Jul 2003 10:52:37 +0000", // Leading zero.
    b"1 Jul 2003 10:52:37",             // No weekday or offset.
    b"01 Jul 2003 10:52:37",            // Same, but w/ leading zero.
    b"Tue, 01 Jul 2003 03:52:37 -0700", // Negative UTC offset.
    b"Tue, 1 Jul 2003 15:22:37 +0430",  // Positive UTC offset.
];

for raw in dates {
    assert_eq!(
        Utc2k::from_rfc2822(raw).unwrap().parts(),
        (2003, 7, 1, 10, 52, 37),
    );
}

// The same variation exists for date-only representations too.
let dates: [&[u8]; 5] = [
    b"Tue, 1 Jul 2003",  // Single-digit day.
    b"Tue,  1 Jul 2003", // Digit/space substitution.
    b"Tue, 01 Jul 2003", // Leading zero.
    b"1 Jul 2003",       // No weekday or offset.
    b"01 Jul 2003",      // Same, but w/ leading zero.
];

for raw in dates {
    assert_eq!(
        Utc2k::from_rfc2822(raw).unwrap().parts(),
        (2003, 7, 1, 0, 0, 0), // Default time is midnight.
    );
}

Source

pub const fn from_unixtime(src: u32) -> Self

§From Timestamp.

Initialize a new Utc2k from a unix timestamp, saturating to Utc2k::MIN_UNIXTIME or Utc2k::MAX_UNIXTIME if out of range.

For a non-saturating alternative, see Utc2k::checked_from_unixtime.

§Examples

use utc2k::Utc2k;

assert_eq!(
    Utc2k::from_unixtime(1_748_672_925).to_string(),
    "2025-05-31 06:28:45",
);

// Same as the above, but using the `From<u32>` impl.
assert_eq!(
    Utc2k::from(1_748_672_925_u32).to_string(),
    "2025-05-31 06:28:45",
);

// Out of range values will saturate to the boundaries of the
// century.
assert_eq!(
    Utc2k::from_unixtime(0).to_string(),
    "2000-01-01 00:00:00",
);
assert_eq!(
    Utc2k::from_unixtime(u32::MAX).to_string(),
    "2099-12-31 23:59:59",
);

Source

pub fn now() -> Self

§Now.

Create a new instance representing the current UTC time.

Source

pub fn tomorrow() -> Self

§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,
);

Source

pub fn yesterday() -> Self

§Yesterday.

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

§Examples

use utc2k::Utc2k;

assert_eq!(
    Utc2k::yesterday(),
    Utc2k::now() - 86_400_u32,
);

Source §

impl Utc2k

§Get Parts.

Source

pub const fn parts(self) -> (u16, u8, u8, u8, u8, u8)

§Parts.

Return the individual numerical components of the datetime, from years down to seconds.

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

Source

pub const fn ymd(self) -> (u16, u8, u8)

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

Source

pub const fn hms(self) -> (u8, u8, u8)

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

Source

pub const fn year(self) -> u16

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

Source

pub const fn month(self) -> Month

§Month.

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(), Month::May);

Source

pub const fn day(self) -> u8

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

Source

pub const fn hour(self) -> u8

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

Source

pub const fn hour_12(self) -> u8

§12-Hour Hour.

Return the hour in unholy 12-hour format.

Utc2k::hour_period can be used to disambiguate the result.

§Examples

use utc2k::Utc2k;

let date = Utc2k::new(2010, 5, 15, 4, 30, 1);
assert_eq!(date.hour_12(), 4); // AM.

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.hour_12(), 4); // PM.

Source

pub const fn hour_period(self) -> Period

§Period (AM or PM).

If the hour is less than 12, returns AM; otherwise PM.

§Examples

use utc2k::{Period, Utc2k};

let date = Utc2k::new(2010, 5, 15, 4, 30, 1);
assert_eq!(date.hour_period(), Period::Am);

let date = Utc2k::new(2010, 5, 15, 16, 30, 1);
assert_eq!(date.hour_period(), Period::Pm);

Source

pub const fn minute(self) -> u8

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

Source

pub const fn second(self) -> u8

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

Source §

impl Utc2k

§Other Getters.

Source

pub const fn leap_year(self) -> bool

§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());

Source

pub const fn month_size(self) -> u8

§Month Size (Days).

This method returns the “size” of the datetime’s month, or its last day, whichever way you prefer to think of it.

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

let date = Utc2k::try_from("2020-02-01").unwrap();
assert_eq!(date.month_size(), 29); // Leap!

Source

pub const fn ordinal(self) -> u16

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

Source

pub const fn seconds_from_midnight(self) -> u32

§Seconds From Midnight.

Return the number of seconds since (the current day’s) 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);

Source

pub const fn weekday(self) -> Weekday

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

Source §

impl Utc2k

§Conversion.

Source

pub const fn formatted(self) -> FmtUtc2k

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

Source

pub const fn to_midnight(self) -> Self

§To Midnight.

Return a new instance with zeroed-out time pieces, i.e. truncated to the date’s midnight.

§Examples

use utc2k::Utc2k;

let date1 = Utc2k::new(2022, 7, 22, 20, 52, 41);
assert_eq!(date1.to_midnight(), date1.with_time(0, 0, 0));

Source

pub fn to_rfc2822(&self) -> String

§To RFC2822.

Return a string formatted according to RFC2822.

§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",
//        ^ This implementation zero-pads short day
//          numbers rather than truncating them…
);

let date = Utc2k::new(2036, 12, 15, 16, 30, 55);
assert_eq!(
    date.to_rfc2822(),
    "Mon, 15 Dec 2036 16:30:55 +0000",
//   ^-----------------------------^ …to keep the output
//                                   length consistent.
);

Source

pub fn to_rfc3339(&self) -> String

§To RFC3339.

Return a string formatted according to RFC3339.

§Examples

use utc2k::Utc2k;

let date = Utc2k::new(2021, 12, 13, 11, 56, 1);
assert_eq!(date.to_rfc3339(), "2021-12-13T11:56:01Z");

// The reverse operation — parsing an RFC3339 datetime string into
// a Utc2k — can be done using `Utc2k::from_ascii`.
assert_eq!(
    Utc2k::from_ascii(date.to_rfc3339().as_bytes()).unwrap(),
    date,
);

Source

pub const fn unixtime(self) -> u32

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

Source

pub const fn with_time(self, hh: u8, mm: u8, ss: u8) -> Self

§With a New 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");

Source §

impl Utc2k

§Fancy Formatting.

Source

pub fn formatted_custom(self, fmt: &str) -> Result<String, Utc2kFormatError>

§Arbitrarily-Formatted Date/Time.

This method can be used to format a Utc2k date/time value just about any which way.

§Syntax

The formatting syntax is similar to the one used by the time crate, but a bit more compact and consistent.

Date/time “components” are specified as []-enclosed tags with optional space-separated “modifiers”. Everything else is treated as a literal and passed through as-is.

To include a literal "[", escape it with another, i.e. "[[".

Note: format strings must be valid ASCII.

§Components

Component	Modifier	Description	Example
`year`		Four-digit year.	`"2000"`
	`@2`	Two-digit year.	`"00"`
	`@2 @space`	Two-digit year, space-padded.	`" 0"`
	`@2 @trim`	Two-digit year, unpadded.	`"0"`
`month`		Two-digit month.	`"01"`
	`@space`	Two-digit month, space-padded.	`" 1"`
	`@trim`	Two-digit month, unpadded.	`"1"`
	`@name`	Month name.	`"January"`
	`@abbr`	Month abbreviation.	`"Jan"`
`day`		Two-digit day.	`"01"`
	`@space`	Two-digit day, space-padded.	`" 1"`
	`@trim`	Two-digit day, unpadded.	`"1"`
	`@name`	Weekday.	`"Saturday"`
	`@abbr`	Weekday abbreviation.	`"Sat"`
`hour`		Two-digit hour (24).	`"00"`
	`@space`	Two-digit hour (24), space-padded.	`" 0"`
	`@trim`	Two-digit hour (24), unpadded.	`"0"`
	`@12`	Two-digit hour (12).	`"12"`
	`@12 @space`	Two-digit hour (12), space-padded.	`"12"`
	`@12 @trim`	Two-digit hour (12), unpadded.	`"12"`
`minute`		Two-digit minute.	`"00"`
	`@space`	Two-digit minute, space-padded.	`" 0"`
	`@trim`	Two-digit minute, unpadded.	`"0"`
`second`		Two-digit second.	`"00"`
	`@space`	Two-digit second, space-padded.	`" 0"`
	`@trim`	Two-digit second, unpadded.	`"0"`
`ordinal`		Ordinal.	`"001"`
	`@space`	Ordinal, space-padded.	`" 1"`
	`@trim`	Ordinal, unpadded.	`"1"`
`period`		Lowercase.	`"am"`
	`@ap`	AP Style (punctuated).	`"a.m."`
	`@upper`	UPPERCASE.	`"AM"`
`unixtime`		Unix timestamp.	`"946684800"`

§Examples

use utc2k::Utc2k;

// Same as `Utc2k::to_rfc2822`, but slower and fallible. Haha.
assert_eq!(
    Utc2k::MAX.formatted_custom(
        "[day @abbr], [day] [month @abbr] [year] [hour]:[minute]:[second] +0000"
    ).unwrap(),
    Utc2k::MAX.to_rfc2822(),
);

// Literal '[' require escape.
assert_eq!(
    Utc2k::MAX.formatted_custom("[[[year]]").unwrap(),
    "[2099]",
);

// Whitespace between the '[]' doesn't matter, but outside it's literal.
assert_eq!(
    Utc2k::MAX.formatted_custom("  +[  period  @upper  ]+  ").unwrap(),
    "  +PM+  ",
);

// Arbitrary to the extreme…
assert_eq!(
    Utc2k::MAX.formatted_custom("Hello World").unwrap(),
    "Hello World",
);

// Format strings must be ASCII, however.
assert!(Utc2k::MAX.formatted_custom("Björk like it's [year]!").is_err());

§Errors

This method will return an error if the format string contains non-ASCII characters or is otherwise malformed.

Source §

impl Utc2k

§Checked Operations.

Source

pub const fn checked_add(self, secs: u32) -> Option<Self>

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

Source

pub const fn checked_from_ascii(src: &[u8]) -> Result<Self, Utc2kError>

§From ASCII Date/Time Slice (Checked).

Same as Utc2k::from_ascii, but will return an error if the resulting date is too old or new to be represented faithfully (rather than clamping it to Utc2k::MIN/Utc2k::MAX).

§Examples

use utc2k::{Utc2k, Utc2kError};

assert_eq!(
    Utc2k::checked_from_ascii(b"1990-01-15 10:20:00"),
    Err(Utc2kError::Underflow), // Too old.
);

assert_eq!(
    Utc2k::checked_from_ascii(b"3000-12-01 13:00:00"),
    Err(Utc2kError::Overflow), // Too new.
);

assert_eq!(
    Utc2k::checked_from_ascii(b"2025-06-17 00:00:00")
        .map(Utc2k::parts),
    Ok((2025, 6, 17, 0, 0, 0)), // Just right!
);

§Errors

This method will return an error if the slice cannot be parsed, or the parsed value is too big or small to fit within our century.

Source

pub const fn checked_from_unixtime(src: u32) -> Result<Self, Utc2kError>

§From Unixtime (Checked).

This can be used instead of the usual Utc2k::from_unixtime or 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, Utc2kError};

assert_eq!(
    Utc2k::checked_from_unixtime(u32::MIN),
    Err(Utc2kError::Underflow), // Too old.
);

assert_eq!(
    Utc2k::checked_from_unixtime(u32::MAX),
    Err(Utc2kError::Overflow), // Too new.
);

assert_eq!(
    Utc2k::checked_from_unixtime(1_750_187_543)
        .map(Utc2k::parts),
    Ok((2025, 6, 17, 19, 12, 23)), // Just right!
);

Source

pub const fn checked_sub(self, secs: u32) -> Option<Self>

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

Source §

impl Utc2k

§Comparison.

Source

pub const fn abs_diff(self, other: Self) -> u32

§Absolute Difference.

This returns the (absolute) number of seconds between two datetimes.

§Examples.

use utc2k::Utc2k;

let date1 = Utc2k::new(2022, 10, 15, 11, 30, 0);
let date2 = Utc2k::new(2022, 10, 15, 11, 31, 0);

// ABS means the ordering does not matter.
assert_eq!(date1.abs_diff(date2), 60);
assert_eq!(date2.abs_diff(date1), 60);

// If the dates are equal, the difference is zero.
assert_eq!(date1.abs_diff(date1), 0);

// Because we're only dealing with a single century, there is an
// upper limit to the possible return values…
assert_eq!(Utc2k::MIN.abs_diff(Utc2k::MAX), 3_155_759_999);

Source

pub const fn cmp(a: Self, b: Self) -> Ordering

§Compare Two Date/Times.

Same as Ord/PartialOrd, but constant.

§Examples

use std::cmp::Ordering;
use utc2k::Utc2k;

let date1 = Utc2k::new(2020, 1, 2, 12, 0, 0);
let date2 = Utc2k::new(2021, 12, 31, 15, 30, 0);

assert_eq!(Utc2k::cmp(date1, date1), Ordering::Equal);
assert_eq!(Utc2k::cmp(date1, date1), date1.cmp(&date1));

assert_eq!(Utc2k::cmp(date1, date2), Ordering::Less);
assert_eq!(Utc2k::cmp(date1, date2), date1.cmp(&date2));

assert_eq!(Utc2k::cmp(date2, date1), Ordering::Greater);
assert_eq!(Utc2k::cmp(date2, date1), date2.cmp(&date1));

Source

pub const fn cmp_date(a: Self, b: Self) -> Ordering

§Compare (Only) Dates.

Compare self to another Utc2k instance, ignoring the time components of each.

§Examples

use utc2k::Utc2k;
use std::cmp::Ordering;

// The times are different, but the dates match.
let date1 = Utc2k::new(2020, 3, 15, 0, 0, 0);
let date2 = Utc2k::new(2020, 3, 15, 16, 30, 20);
assert_eq!(Utc2k::cmp_date(date1, date2), Ordering::Equal);

// If the dates don't match, it's what you'd expect.
let date3 = Utc2k::new(2022, 10, 31, 0, 0, 0);
assert_eq!(Utc2k::cmp_date(date1, date3), Ordering::Less);

Source

pub const fn cmp_time(a: Self, b: Self) -> Ordering

§Compare (Only) Times.

Compare self to another Utc2k instance, ignoring the date components of each.

§Examples

use utc2k::Utc2k;
use std::cmp::Ordering;

// The dates match, but the times are different.
let date1 = Utc2k::new(2020, 3, 15, 0, 0, 0);
let date2 = Utc2k::new(2020, 3, 15, 16, 30, 20);
assert_eq!(Utc2k::cmp_time(date1, date2), Ordering::Less);

// If the times match, it's what you'd expect.
let date3 = Utc2k::new(2022, 10, 31, 0, 0, 0);
assert_eq!(Utc2k::cmp_time(date1, date3), Ordering::Equal);

Trait Implementations§

Source §

impl Add<u32> for Utc2k

Source §

fn add(self, other: u32) -> Self

§Add Seconds.

use utc2k::{DAY_IN_SECONDS, Utc2k};

let utc = Utc2k::from(1_750_620_170);
assert_eq!(
    utc.parts(),
    (2025, 6, 22, 19, 22, 50),
);

assert_eq!(
    (utc + DAY_IN_SECONDS * 2).parts(),
    (2025, 6, 24, 19, 22, 50),
);

Source §

type Output = Utc2k

The resulting type after applying the + operator.

Source §

impl AddAssign<u32> for Utc2k

Source §

fn add_assign(&mut self, other: u32)

§Add Seconds.

use utc2k::{DAY_IN_SECONDS, Utc2k};

let mut utc = Utc2k::from(1_750_620_170);
assert_eq!(
    utc.parts(),
    (2025, 6, 22, 19, 22, 50),
);

utc += DAY_IN_SECONDS * 2;
assert_eq!(
    utc.parts(),
    (2025, 6, 24, 19, 22, 50),
);

Source §

impl Clone for Utc2k

Source §

fn clone(&self) -> Utc2k

Returns a duplicate of the value. Read more

1.0.0 · Source§

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

Performs copy-assignment from source. Read more

Source §

impl Debug for Utc2k

Source §

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

Formats the value using the given formatter. Read more

Source §

impl Default for Utc2k

Source §

fn default() -> Self

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

Source §

impl<'de> Deserialize<'de> for Utc2k

Available on crate feature serde only.

Source §

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where D: Deserializer<'de>,

§Deserialize.

Use the optional serde crate feature to enable serialization support.

Source §

impl Display for Utc2k

Source §

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

§Display.

use utc2k::Utc2k;

let utc = Utc2k::from(1_750_620_170);
assert_eq!(
    utc.to_string(),
    "2025-06-22 19:22:50",
);

Source §

impl From<&FmtUtc2k> for Utc2k

Source §

fn from(src: &FmtUtc2k) -> Self

Converts to this type from the input type.

Source §

impl From<&Local2k> for Utc2k

Available on crate feature local only.

Source §

fn from(src: &Local2k) -> Self

Converts to this type from the input type.

Source §

impl From<&Utc2k> for FmtUtc2k

Source §

fn from(src: &Utc2k) -> Self

Converts to this type from the input type.

Source §

impl From<&Utc2k> for Local2k

Available on crate feature local only.

Source §

fn from(src: &Utc2k) -> Self

Converts to this type from the input type.

Source §

impl From<FmtUtc2k> for Utc2k

Source §

fn from(src: FmtUtc2k) -> Self

§From `FmtUtc2k`.

use utc2k::{FmtUtc2k, Utc2k};

let fmt = FmtUtc2k::from(1_750_620_170);
let utc = Utc2k::from(fmt);
assert_eq!(
    utc.parts(),
    (2025, 6, 22, 19, 22, 50),
);

Source §

impl From<Local2k> for Utc2k

Available on crate feature local only.

Source §

fn from(src: Local2k) -> Self

Converts to this type from the input type.

Source §

impl From<Utc2k> for FmtUtc2k

Source §

fn from(src: Utc2k) -> Self

§From `Utc2k`

use utc2k::{FmtUtc2k, Utc2k};

let utc = Utc2k::new(2025, 6, 22, 19, 22, 50);
assert_eq!(
    FmtUtc2k::from(utc),
    "2025-06-22 19:22:50",
);

Source §

impl From<Utc2k> for Local2k

Available on crate feature local only.

Source §

fn from(src: Utc2k) -> Self

Converts to this type from the input type.

Source §

impl From<Utc2k> for Month

Source §

fn from(src: Utc2k) -> Self

§From `Utc2k`.

This is equivalent to calling Utc2k::month.

§Examples

use utc2k::{Month, Utc2k};

let utc = Utc2k::new(2030, 1, 6, 0, 0, 0);
assert_eq!(Month::January, Month::from(utc));
assert_eq!(Month::January, utc.month());

Source §

impl From<Utc2k> for String

Source §

fn from(src: Utc2k) -> Self

§Into String.

use utc2k::Utc2k;

let utc = Utc2k::from(1_750_620_170);
assert_eq!(
    String::from(utc),
    "2025-06-22 19:22:50",
);

Source §

impl From<Utc2k> for Weekday

Source §

fn from(src: Utc2k) -> Self

§From `Utc2k`.

This is equivalent to calling Utc2k::weekday.

§Examples

use utc2k::{Weekday, Utc2k};

let utc = Utc2k::new(2030, 1, 6, 0, 0, 0);
assert_eq!(Weekday::Sunday, Weekday::from(utc));
assert_eq!(Weekday::Sunday, utc.weekday());

Source §

impl From<Utc2k> for u32

Source §

fn from(src: Utc2k) -> Self

§From Unixtime.

use utc2k::Utc2k;

let utc = Utc2k::from(1_750_620_170_u32);
assert_eq!(
    utc.parts(),
    (2025, 6, 22, 19, 22, 50),
);

Source §

impl From<u32> for Utc2k

Source §

fn from(src: u32) -> Self

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

Source §

impl FromStr for Utc2k

Source §

type Err = Utc2kError

The associated error which can be returned from parsing.

Source §

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

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

Source §

impl Hash for Utc2k

Source §

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher. Read more

1.3.0 · Source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

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

Source §

impl Ord for Utc2k

Source §

fn cmp(&self, other: &Self) -> Ordering

§Compare.

Compare two date/times.

§Examples

use utc2k::Utc2k;

let date1 = Utc2k::new(2020, 10, 15, 20, 25, 30);
let date2 = Utc2k::new(2020, 10, 15, 0, 0, 0);
let date3 = Utc2k::new(2022, 10, 15, 0, 0, 0);

assert!(date1 > date2);
assert!(date1 < date3);
assert!(date2 < date3);

1.21.0 · Source§

fn max(self, other: Self) -> Self
where Self: Sized,

Compares and returns the maximum of two values. Read more

1.21.0 · Source§

fn min(self, other: Self) -> Self
where Self: Sized,

Compares and returns the minimum of two values. Read more

1.50.0 · Source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized,

Restrict a value to a certain interval. Read more

Source §

impl PartialEq<Local2k> for Utc2k

Available on crate feature local only.

Source §

fn eq(&self, other: &Local2k) -> bool

Tests for self and other values to be equal, and is used by ==.

1.0.0 · Source§

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

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

Source §

impl PartialEq<Utc2k> for Local2k

Available on crate feature local only.

Source §

fn eq(&self, other: &Utc2k) -> bool

§Cross-Offset Equality.

Local and UTC dates are compared as unix timestamps, so should always match up.

§Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2025, 1, 1, 0, 0, 0);
let local = Local2k::from(utc);
assert_eq!(utc, local);

// String representations, however, will only be equal if there's
// no offset.
assert_eq!(
    utc.to_string() == local.to_string(),
    local.offset().is_none(),
);

1.0.0 · Source§

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

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

Source §

impl PartialEq for Utc2k

Source §

fn eq(&self, other: &Utc2k) -> bool

Tests for self and other values to be equal, and is used by ==.

1.0.0 · Source§

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

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

Source §

impl PartialOrd for Utc2k

Source §

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more

1.0.0 · Source§

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

Tests less than (for self and other) and is used by the < operator. Read more

1.0.0 · Source§

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

Tests less than or equal to (for self and other) and is used by the <= operator. Read more

1.0.0 · Source§

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

Tests greater than (for self and other) and is used by the > operator. Read more

1.0.0 · Source§

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

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

Source §

impl Serialize for Utc2k

Available on crate feature serde only.

Source §

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

§Serialize.

Use the optional serde crate feature to enable serialization support.

Source §

impl Sub<u32> for Utc2k

Source §

fn sub(self, other: u32) -> Self

§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),
);

Source §

type Output = Utc2k

The resulting type after applying the - operator.

Source §

impl SubAssign<u32> for Utc2k

Source §

fn sub_assign(&mut self, other: u32)

Performs the -= operation. Read more

Source §

impl TryFrom<&[u8]> for Utc2k

Source §

type Error = Utc2kError

The type returned in the event of a conversion error.

Source §

fn try_from(src: &[u8]) -> Result<Self, Self::Error>

Performs the conversion.

Source §

impl TryFrom<&OsStr> for Utc2k

Source §

fn try_from(src: &OsStr) -> Result<Self, Self::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"
);

Source §

type Error = Utc2kError

The type returned in the event of a conversion error.

Source §

impl TryFrom<&str> for Utc2k

Source §

fn try_from(src: &str) -> Result<Self, Self::Error>

§From String.

use utc2k::Utc2k;

let utc = Utc2k::try_from("2025-06-22 19:22:50");
assert_eq!(
    utc.unwrap().parts(),
    (2025, 6, 22, 19, 22, 50),
);

Source §

type Error = Utc2kError

The type returned in the event of a conversion error.

Source §

impl Copy for Utc2k

Source §

impl Eq for Utc2k

Source §

impl StructuralPartialEq for Utc2k

Auto Trait Implementations§

§

impl UnwindSafe for Utc2k

Blanket Implementations§

Source §

impl<T> Any for T
where T: 'static + ?Sized,

Source §

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

Source §

impl<T> Borrow<T> for T
where T: ?Sized,

Source §

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

Source §

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source §

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

Source §

impl<T> CloneToUninit for T
where T: Clone,

Source §

unsafe fn clone_to_uninit(&self, dest: *mut u8)

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

Performs copy-assignment from self to dest. Read more

Source §

impl<T> From<T> for T

Source §

fn from(t: T) -> T

Returns the argument unchanged.

Source §

impl<T, U> Into for T
where U: From<T>,

Source §

fn into(self) -> U

Calls U::from(self).

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

Source §

impl<T> ToOwned for T
where T: Clone,

Source §

type Owned = T

The resulting type after obtaining ownership.

Source §

fn to_owned(&self) -> T

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

Source §

fn clone_into(&self, target: &mut T)

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

Source §

impl<T> ToString for T
where T: Display + ?Sized,

Source §

fn to_string(&self) -> String

Converts the given value to a String. Read more

Source §

impl<T, U> TryFrom for T
where U: Into<T>,

Source §

type Error = Infallible

The type returned in the event of a conversion error.

Source §

fn try_from(value: U) -> Result<T, <T as TryFrom>::Error>

Performs the conversion.

Source §

impl<T, U> TryInto for T
where U: TryFrom<T>,

Source §

type Error = >::Error

The type returned in the event of a conversion error.

Source §

fn try_into(self) -> Result<U, >::Error>

Performs the conversion.

Source §

Struct Utc2k Copy item path

§UTC2K.

§Examples

Implementations§

impl Utc2k

§Min/Max.

pub const MIN: Self

§Minimum Date/Time.

pub const MAX: Self

§Maximum Date/Time.

pub const MIN_UNIXTIME: u32 = 946_684_800u32

§Minimum Unix Timestamp.

pub const MAX_UNIXTIME: u32 = 4_102_444_799u32

§Maximum Unix Timestamp.

impl Utc2k

§Instantiation.

pub const fn new(y: u16, m: u8, d: u8, hh: u8, mm: u8, ss: u8) -> Self

§New (From Parts).

§Examples

pub const fn from_ascii(src: &[u8]) -> Option<Self>

§From ASCII Date/Time Slice.

§Supported Formats.

§Examples

pub const fn from_rfc2822(src: &[u8]) -> Option<Self>

§From RFC2822 Date/Time Slice.

§Examples

pub const fn from_unixtime(src: u32) -> Self

§From Timestamp.

§Examples

pub fn now() -> Self

§Now.

pub fn tomorrow() -> Self

§Tomorrow.

§Examples

pub fn yesterday() -> Self

§Yesterday.

§Examples

impl Utc2k

§Get Parts.

pub const fn parts(self) -> (u16, u8, u8, u8, u8, u8)

§Parts.

§Examples

pub const fn ymd(self) -> (u16, u8, u8)

§Date Parts.

§Examples

pub const fn hms(self) -> (u8, u8, u8)

§Time Parts.

§Examples

pub const fn year(self) -> u16

§Year.

§Examples

pub const fn month(self) -> Month

§Month.

§Examples

pub const fn day(self) -> u8

§Day.

§Examples

pub const fn hour(self) -> u8

§Hour.

§Examples

pub const fn hour_12(self) -> u8

§12-Hour Hour.

§Examples

pub const fn hour_period(self) -> Period

§Period (AM or PM).

§Examples

pub const fn minute(self) -> u8

§Minute.

§Examples

pub const fn second(self) -> u8

§Second.

§Examples

impl Utc2k

§Other Getters.

pub const fn leap_year(self) -> bool

§Is Leap Year?

§Examples

pub const fn month_size(self) -> u8

§Month Size (Days).

§Examples

Struct Utc2k