Struct Local2k 

pub struct Local2k { /* private fields */ }

Available on crate feature local only.

Local UTC2K.

This struct brings barebones locale awareness to Utc2k, allowing date/time digits to be carved up according to the user’s local time zone instead of the usual UTC.

Time zone detection is automatic, but only supported on unix platforms. If the lookup fails or the user is running something weird like Windows, it’ll stick with UTC.

UTC is also used in cases where the local offset would cause the date/time to be clamped to the 2000..=2099 range. (This is only applicable to the first and final hours of the century, so shouldn’t come up very often!)

To keep things simple, Local2k is effectively read-only, requiring Utc2k as a go-between for both instantiation and modification, except for a few convenience methods like Local2k::now, Local2k::tomorrow, and Local2k::yesterday.

Note that offsets, or the lack thereof, have no effect on date/time equality, hashing, or ordering. Local2k objects can be freely compared with one another and/or Utc2k date/times.

Implementations

impl Local2k

Instantiation.

pub fn from_utc2k(src: Utc2k) -> Self

From UTC.

Convert a UTC date/time into a local one.

Refer to the main Local2k for limitations and gotchas.

pub fn now() -> Self

Now.

Create a new instance representing the current local time.

use utc2k::{Local2k, Utc2k};

// Equivalent.
assert_eq!(
    Local2k::now(),
    Local2k::from(Utc2k::now()),
);

pub fn tomorrow() -> Self

Tomorrow.

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

Examples

use utc2k::{Local2k, Utc2k};

// Equivalent.
assert_eq!(
    Local2k::tomorrow(),
    Local2k::from(Utc2k::tomorrow()),
);

pub fn yesterday() -> Self

Yesterday.

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

Examples

use utc2k::{Local2k, Utc2k};

// Equivalent.
assert_eq!(
    Local2k::yesterday(),
    Local2k::from(Utc2k::yesterday()),
);

impl Local2k

Conversion.

pub const fn formatted(self) -> FmtLocal2k

Formatted.

This returns a FmtLocal2k and is equivalent to calling FmtLocal2k::from(self).

Examples

use utc2k::{FmtLocal2k, Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.formatted(), FmtLocal2k::from(local));

pub fn to_rfc2822(&self) -> String

To RFC2822.

Return a string formatted according to RFC2822.

Examples

use utc2k::{Local2k, Utc2k};

// A proper UTC date in RFC2822.
let utc = Utc2k::new(2021, 12, 13, 04, 56, 1);
assert_eq!(
    utc.to_rfc2822(),
    "Mon, 13 Dec 2021 04:56:01 +0000",
);

// The same date localized to, say, California.
let local = Local2k::from(utc);
assert_eq!(
    local.to_rfc2822(),
    "Sun, 12 Dec 2021 20:56:01 -0800",
);

The RFC2822 date/time format is portable, whether local or UTC.

let utc_2822 = utc.to_rfc2822();
let local_2822 = local.to_rfc2822();

// The RFC2822 representations will vary if there's an offset, but
// if parsed back into a Utc2k, that'll get sorted and they'll match!
assert_eq!(
    Utc2k::from_rfc2822(utc_2822.as_bytes()),
    Some(utc),
);
assert_eq!(
    Utc2k::from_rfc2822(local_2822.as_bytes()),
    Some(utc),
);

pub fn to_rfc3339(&self) -> String

To RFC3339.

Return a string formatted according to RFC3339.

Examples

use utc2k::{Local2k, Utc2k};

// A proper UTC date in RFC3339.
let utc = Utc2k::new(2021, 12, 13, 11, 56, 1);
assert_eq!(utc.to_rfc3339(), "2021-12-13T11:56:01Z");

// The same date localized to, say, California.
let local = Local2k::from(utc);
assert_eq!(local.to_rfc3339(), "2021-12-13T03:56:01-0800");

The RFC3339 date/time format is portable, whether local or UTC.

let utc_3339 = utc.to_rfc3339();
let local_3339 = local.to_rfc3339();

// The RFC3339 representations will vary if there's an offset, but
// if parsed back into a Utc2k, that'll get sorted and they'll match!
assert_eq!(
    Utc2k::from_ascii(utc_3339.as_bytes()),
    Some(utc),
);
assert_eq!(
    Utc2k::from_ascii(local_3339.as_bytes()),
    Some(utc),
);

pub const fn to_utc2k(&self) -> Utc2k

Into UTC.

Convert a local date/time back into UTC one.

use utc2k::{Utc2k, Local2k};

let utc = Utc2k::now();
let local = Local2k::from(utc);
assert_eq!(
    local.to_utc2k(),
    utc,
);

pub const fn unixtime(&self) -> u32

Unixtime.

Return the (original) unix timestamp used to create this instance.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::from_unixtime(1_434_765_671_u32);
let local = Local2k::from(utc);

assert_eq!(utc.unixtime(),   1_434_765_671);
assert_eq!(local.unixtime(), 1_434_765_671, "local {:?}", local.offset());

impl Local2k

Get Parts.

pub const fn is_utc(&self) -> bool

Is UTC?

Returns true if there is no offset applied to the “local” date/time.

Examples

use utc2k::Local2k;

let date = Local2k::now();
assert_eq!(
    date.is_utc(),
    date.offset().is_none(),
);

pub const fn offset(&self) -> Option<NonZeroI32>

Offset.

Return the UTC offset in seconds, if any.

Examples

use std::num::NonZeroI32;
use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2005, 1, 1, 12, 0, 0);
let local = Local2k::from(utc);
assert_eq!(
    local.offset(),
    NonZeroI32::new(-28_800), // e.g. California.
);

// Don't forget about Daylight Saving! 🕱
let utc = Utc2k::new(2005, 6, 1, 12, 0, 0);
let local = Local2k::from(utc);
assert_eq!(
    local.offset(),
    NonZeroI32::new(-25_200), // e.g. California.
);

// Remember, 1999 and 2100 DO NOT EXIST. To prevent a loss of
// precision, UTC will be used to represent the first or final hours
// of the century to prevent precision loss.
let local = Local2k::from(Utc2k::MIN);
assert!(local.offset().is_none()); // Can't apply a -0800 offset
                                   // without leaving the century!

let local = Local2k::from(Utc2k::MAX);
assert!(local.offset().is_some()); // The -0800 is no problem on the
                                   // other end, though.

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 Local2k::ymd, or if you only want the time bits, use Local2k::hms.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 4, 16, 30, 1);
assert_eq!(
    utc.parts(),
    (2010, 5, 4, 16, 30, 1),
);

let local = Local2k::from(utc);
assert_eq!(
    local.parts(),
    (2010, 5, 4, 9, 30, 1), // e.g. California.
//               ^ -0700
);

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::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 5, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.ymd(), (2010, 5, 5)); // e.g. California.

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::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 5, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.hms(), (9, 30, 1)); // e.g. California.

pub const fn year(&self) -> u16

Year.

This returns the year value.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.year(), 2010);

pub const fn month(&self) -> Month

Month (enum).

This returns the month value as a Month.

Examples

use utc2k::{Local2k, Month, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.month(), Month::May);

pub const fn day(&self) -> u8

Day.

This returns the day value.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.day(), 15);

pub const fn hour(&self) -> u8

Hour.

This returns the hour value.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.hour(), 9); // e.g. California.

pub const fn minute(&self) -> u8

Minute.

This returns the minute value.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.minute(), 30);

pub const fn second(&self) -> u8

Second.

This returns the second value.

Examples

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2010, 5, 15, 16, 30, 1);
let local = Local2k::from(utc);
assert_eq!(local.second(), 1);

impl Local2k

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::{Local2k, Utc2k};

let date = Local2k::from(
    Utc2k::try_from("2020-05-10").unwrap()
);
assert!(date.leap_year());

let date = Local2k::from(
    Utc2k::try_from("2021-03-15").unwrap()
);
assert!(! date.leap_year());

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::{Local2k, Utc2k};

let utc = Utc2k::new(2021, 7, 8, 0, 0, 0);
let local = Local2k::from(utc);
assert_eq!(local.month_size(), 31);

let utc = Utc2k::new(2020, 2, 20, 0, 0, 0);
let local = Local2k::from(utc);
assert_eq!(local.month_size(), 29); // Leap!

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::{Local2k, Utc2k};

let utc = Utc2k::new(2020, 5, 10, 12, 0, 0);
let local = Local2k::from(utc);
assert_eq!(local.ordinal(), 131);

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::{DAY_IN_SECONDS, Local2k, Utc2k};

let utc = Utc2k::new(2010, 11, 01, 0, 0, 0);
assert_eq!(utc.seconds_from_midnight(), 0); // It _is_ midnight!

// In California, though, it's still Halloween!
let local = Local2k::from(utc);
assert_eq!(
    local.parts(),
    (2010, 10, 31, 16, 0, 0),
);

// The distance from _its_ midnight is very different!
assert_eq!(local.seconds_from_midnight(), 57_600);

pub const fn weekday(&self) -> Weekday

Weekday.

Return the Weekday corresponding to the given date.

Examples

use utc2k::{Local2k, Utc2k, Weekday};

let utc = Utc2k::new(2021, 7, 8, 5, 22, 1);
assert_eq!(utc.weekday(), Weekday::Thursday);

// Local date/times may differ. In California, for example, it'd
// still be the night before.
let local = Local2k::from(utc);
assert_eq!(local.weekday(), Weekday::Wednesday);

Trait Implementations

impl Clone for Local2k

fn clone(&self) -> Local2k

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Local2k

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

Formats the value using the given formatter.

impl Display for Local2k

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

Formats the value using the given formatter.

impl From<&FmtLocal2k> for Local2k

fn from(src: &FmtLocal2k) -> Self

Converts to this type from the input type.

impl From<&Local2k> for Utc2k

fn from(src: &Local2k) -> Self

Converts to this type from the input type.

impl From<&Utc2k> for Local2k

fn from(src: &Utc2k) -> Self

Converts to this type from the input type.

impl From<FmtLocal2k> for Local2k

fn from(src: FmtLocal2k) -> Self

Converts to this type from the input type.

impl From<Local2k> for FmtLocal2k

fn from(src: Local2k) -> Self

Converts to this type from the input type.

impl From<Local2k> for String

fn from(src: Local2k) -> Self

Converts to this type from the input type.

impl From<Local2k> for Utc2k

fn from(src: Local2k) -> Self

Converts to this type from the input type.

impl From<Utc2k> for Local2k

fn from(src: Utc2k) -> Self

Converts to this type from the input type.

impl Hash for Local2k

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Ord for Local2k

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

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

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq<Local2k> for Utc2k

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

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

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

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

impl PartialEq<Utc2k> for Local2k

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

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

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

impl PartialEq for Local2k

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

Equality.

use utc2k::{Local2k, Utc2k};

let utc = Utc2k::new(2001, 1, 15, 0, 0, 0);
let local = Local2k::from(utc);

// Offsets don't affect equality.
assert_eq!(utc, local);
assert_eq!(local, local);

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

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

impl PartialOrd for Local2k

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

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

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

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

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

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

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

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

impl Copy for Local2k

impl Eq for Local2k