Struct utc2k::Utc2k

pub struct Utc2k { /* fields omitted */ }

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

impl Utc2k

Min/Max.

pub const MIN_UNIXTIME: u32

Minimum Timestamp.

pub const MAX_UNIXTIME: u32

Maximum Timestamp.

pub const fn min() -> Self

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

pub const fn max() -> Self

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

impl Utc2k

Instantiation.

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

pub fn now() -> Self

Now.

Create a new instance representing the current UTC time.

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

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

impl Utc2k

String Parsing.

pub fn from_datetime_str(src: &str) -> Result<Self, Utc2kError>

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.

pub fn from_date_str(src: &str) -> Result<Self, Utc2kError>

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.

impl Utc2k

Get Parts.

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

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

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

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

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

pub const fn month(self) -> u8

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

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

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

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

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

impl Utc2k

Other Getters.

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

pub const fn month_abbreviation(self) -> &'static str

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

pub const fn month_name(self) -> &'static str

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

pub const fn month_size(self) -> u8

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

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

pub const fn seconds_from_midnight(self) -> u32

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

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

impl Utc2k

Conversion.

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

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

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

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

impl Utc2k

Checked Operations.

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

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

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

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

Trait Implementations

impl Add<u32> for Utc2k

type Output = Self

The resulting type after applying the + operator.

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

Performs the + operation.

impl AddAssign<u32> for Utc2k

fn add_assign(&mut self, other: u32)

Performs the += operation.

impl Clone for Utc2k

fn clone(&self) -> Utc2k

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Utc2k

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

Formats the value using the given formatter.

impl Default for Utc2k

fn default() -> Self

Returns the “default value” for a type.

impl Display for Utc2k

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

Formats the value using the given formatter.

impl From<Utc2k> for FmtUtc2k

fn from(src: Utc2k) -> Self

Performs the conversion.

impl From<Utc2k> for u32

fn from(src: Utc2k) -> Self

Performs the conversion.

impl From<Utc2k> for Weekday

fn from(src: Utc2k) -> Self

Performs the conversion.

impl From<u32> for Utc2k

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

impl Hash for Utc2k

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

Feeds this value into the given Hasher.

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

Feeds a slice of this type into the given Hasher.

impl Ord for Utc2k

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

Restrict a value to a certain interval.

impl PartialEq<Utc2k> for Utc2k

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

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

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

This method tests for !=.

impl PartialOrd<Utc2k> for Utc2k

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

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

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

This method tests less than (for self and other) and is used by the < operator.

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

This method tests less than or equal to (for self and other) and is used by the <= operator.

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

This method tests greater than (for self and other) and is used by the > operator.

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

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

impl Sub<u32> for Utc2k

type Output = Self

The resulting type after applying the - operator.

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

Performs the - operation.

impl SubAssign<u32> for Utc2k

fn sub_assign(&mut self, other: u32)

Performs the -= operation.

impl TryFrom<&'_ OsStr> for Utc2k

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

type Error = Utc2kError

The type returned in the event of a conversion error.

impl TryFrom<&'_ str> for Utc2k

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

The type returned in the event of a conversion error.

impl TryFrom<i32> for Utc2k

type Error = Utc2kError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<i64> for Utc2k

type Error = Utc2kError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<isize> for Utc2k

type Error = Utc2kError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<u64> for Utc2k

type Error = Utc2kError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl TryFrom<usize> for Utc2k

type Error = Utc2kError

The type returned in the event of a conversion error.

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

Performs the conversion.

impl Copy for Utc2k

impl Eq for Utc2k

impl StructuralEq for Utc2k

impl StructuralPartialEq for Utc2k