Struct readable::Date

pub struct Date(_, _);

A recent date that is in YEAR-MONTH-DAY format

The inner “integer” type is a tuple of: (u16, u8, u8) representing the (Year, Month, Day)

Any value being 0 means it is invalid:

let a = Date::from_str("2020-12").unwrap();

assert!(a == (2020, 12, 0));

• The year must be 1000-9999
• The month must be 1-12
• The day must be 1-31

Example:

let (y, m, d) = (2020_u16, 12_u8, 1_u8);

let d1 = Date::from_ymd(y, m, d).unwrap();
let d2 = Date::from_ym(y, m).unwrap();
let d3 = Date::from_y(y).unwrap();

assert!(d1 == "2020-12-01");
assert!(d2 == "2020-12");
assert!(d3 == "2020");

String parsing and format

To parse an abitrary string into a Date, use: Date::from_str.

You can input a string that is just numbers, or separated by a single byte, e.g:

let dates = [
    Date::from_str("2020-12-31").unwrap(),
    Date::from_str("2020/12/31").unwrap(),
    Date::from_str("2020.12.31").unwrap(),
    Date::from_str("2020_12_31").unwrap(),
    Date::from_str("2020 12 31").unwrap(),
    Date::from_str("20201231").unwrap(),
];

for date in dates {
    assert!(date == (2020, 12, 31));
    assert!(date == "2020-12-31");
}

Given an ambiguous date, the parsing function will prioritize:

• YEAR-MONTH-DAY
• MONTH-DAY-YEAR
• DAY-MONTH-YEAR

Example:

// This could be:
//   - 1111-11-11 (YMD)
//   - 11-11-1111 (MDY)
//   - 11-11-1111 (DMY)
let ambiguous = "11111111";
// Although, we prioritize YMD.
assert!(Date::from_str(ambiguous).unwrap() == "1111-11-11");

// This could be:
//   - MDY
//   - DMY
let ambiguous = "12-12-1111";
// We prioritize MDY over DMY.
assert!(Date::from_str(ambiguous).unwrap() == "1111-12-12");

// This cannot be MDY, so it must be DMY.
let dmy = "13-11-1111";
assert!(Date::from_str(dmy).unwrap() == "1111-11-13");

Some errors can occur during string parsing:

• Year is less than 1000, a signed number, or greater than u16::MAX
• Month is not in-between 1-12
• Day is not in-between 1-31

Good Example:

let d1 = Date::from_str("2020-12-31").unwrap();
let d2 = Date::from_str("11_30_2012").unwrap();
let d3 = Date::from_str("1980.5").unwrap();

assert!(d1 == "2020-12-31");
assert!(d2 == "2012-11-30");
assert!(d3 == "1980-05");

Bad Example:

let d1 = Date::from_str("10000-57-99").unwrap();
let d2 = Date::from_str("2022.31.31").unwrap();
let d3 = Date::from_str("-1231").unwrap();

Inlining

If the feature flag inline_date is enabled, inputs that are in YYYY-MM-DD format that range from year 1900-2100 will cause Date::from_str to match on inlined static bytes.

Warning: This feature is disabled by default. While it increases speed, it also heavily increases build time and binary size.

Cloning

Copy is available.

The actual string used internally is not a String, but a 10 byte array buffer, literally: [u8; 10].

Since the max valid date is: 9999-12-31 (10 characters), a 10 byte buffer is used and enables this type to have Copy.

The documentation will still refer to the inner buffer as a String. Anything returned will also be a String.

let a = Date::from_str("2014-04-22").unwrap();

// Copy 'a', use 'b'.
let b = a;
assert!(b == "2014-04-22");

// We can still use 'a'
assert!(a == "2014-04-22");

Implementations

impl Date

pub fn as_str(&self) -> &str

Return a borrowed str without consuming Self.

pub fn as_bytes(&self) -> &[u8]

Returns the valid byte slice of the inner String

These bytes can always safely be used for std::str::from_utf8_unchecked.

pub fn to_vec(&self) -> Vec<u8>

Return the bytes of the inner String as a Vec

pub fn into_vec(self) -> Vec<u8>

Return the bytes of the inner String as a Vec, consuming Self

pub const fn inner(&self) -> (u16, u8, u8)

Returns the inner number.

pub fn into_string(self) -> String

Consumes Self, returning the inner String.

pub fn into_raw(self) -> ((u16, u8, u8), String)

Consumes Self, returning the inner parts.

pub fn head(&self, len: usize) -> &str

Return the first len bytes of this str.

This will return the full str if the len is longer than the actual inner str.

Since all readable types happen to only contain ASCII characters, all char’s are equal to 1 byte.

let date = Date::from_str("2021-12-11").unwrap();

assert!(date.head(5) == "2021-");

pub fn head_dot(&self, len: usize) -> String

Same as Self::head but returns a String ending with ...

This will return the full string without ... if the len is longer than the actual inner str.

let date = Date::from_str("2021-12-11").unwrap();

assert!(date.head_dot(4) == "2021...");

pub fn tail(&self, len: usize) -> &str

Return the last len bytes of this str.

This will return the full str if the len is longer than the actual inner str.

Since all readable types happen to only contain ASCII characters, all char’s are equal to 1 byte.

let date = Date::from_str("2021-12-11").unwrap();

assert!(date.tail(5) == "12-11");

pub fn tail_dot(&self, len: usize) -> String

Same as Self::tail but returns a String starting with ...

This will return the full string without ... if the len is longer than the actual inner str.

let date = Date::from_str("2021-12-11").unwrap();

assert!(date.tail_dot(5) == "...12-11");

pub fn head_tail(&self, head: usize, tail: usize) -> String

Return the first head bytes and last tail bytes of this string separated with ....

Since all readable types happen to only contain ASCII characters, all char’s are equal to 1 byte.

let date = Date::from_str("2021-12-11").unwrap();

assert!(date.head_tail(3, 2) == "202...11");
assert!(date.head_tail(3, 3) == "202...-11");
assert!(date.head_tail(3, 5) == "202...12-11");

pub const fn len(&self) -> usize

The length of the inner String

pub const fn is_empty(&self) -> bool

If the inner String is empty or not

pub const fn to_buf(&self) -> [u8; 10]

Return the full inner buffer that represents the String.

These are guaranteed to be valid UTF-8 bytes.

Not all bytes are necessarily used, however. To find the valid portion of the string, use Self::len.

let u           = Unsigned::from(123_u8);
let buffer      = u.to_buf();
let valid_bytes = &buffer[0..u.len()];

// SAFETY: These bytes are always be valid UTF-8.
unsafe {
    let specified = std::str::from_utf8_unchecked(&valid_bytes);
    let all_bytes = std::str::from_utf8_unchecked(&buffer);

    // Bunch of trailing `\0\0\0`'s at the end.
    assert!(all_bytes != "123");
    assert!(specified == "123");
}

pub const fn into_buf(self) -> [u8; 10]

Same as Self::to_buf but consumes self.

pub const fn as_buf(&self) -> &[u8; 10]

Same as Self::to_buf but returns a borrowed array.

pub const fn to_buf_parts(&self) -> ([u8; 10], usize)

Same as Self::to_buf but returns the length as well.

pub const fn into_buf_parts(self) -> ([u8; 10], usize)

Same as Self::into_buf but returns the length as well.

pub const fn unknown() -> Self

Returns a Self with the date values set to (0, 0, 0)

The String is set to UNKNOWN_DATE.

pub const fn zero() -> Self

Same as Self::unknown

pub const fn year(&self) -> u16

Return the inner year (1000-9999)

pub const fn month(&self) -> u8

Return the inner month (1-12)

pub const fn day(&self) -> u8

Return the inner day (1-31)

pub const fn ok_year(&self) -> bool

Returns true if the inner year is valid.

let a = Date::from_y(2022).unwrap();
let b = Date::unknown();

assert!(a.ok_year());
assert!(!b.ok_year());

pub const fn ok_month(&self) -> bool

Returns true if the inner month is valid.

let a = Date::from_ym(2022, 12).unwrap();
let b = Date::unknown();

assert!(a.ok_month());
assert!(!b.ok_month());

pub const fn ok_day(&self) -> bool

Returns true if the inner day is valid.

let a = Date::from_ymd(2022, 12, 31).unwrap();
let b = Date::unknown();

assert!(a.ok_day());
assert!(!b.ok_day());

pub const fn ok(&self) -> bool

Returns true if the inner (year, month, day) are all valid.

let a = Date::from_ymd(2022, 12, 31).unwrap();
let b = Date::unknown();

assert!(a.ok());
assert!(!b.ok());

pub fn from_y(year: u16) -> Result<Self, Self>

Parse a u16 for a year.

Errors

• The year must be in-between 1000-9999

If an Err is returned, it will contain a Date set with UNKNOWN_DATE which looks like: ????-??-??.

pub fn from_ym(year: u16, month: u8) -> Result<Self, Self>

Parse u16, u8 for a year and month.

Errors

• The year must be in-between 1000-9999
• The month must be in-between 1-12

If an Err is returned, it will contain a Date set with UNKNOWN_DATE which looks like: ????-??-??.

pub fn from_ymd(year: u16, month: u8, day: u8) -> Result<Self, Self>

Parse u16, u8, u8 for a year, month and day.

Errors

• The year must be in-between 1000-9999
• The month must be in-between 1-12
• The day must be in-between 1-31

If an Err is returned, it will contain a Date set with UNKNOWN_DATE which looks like: ????-??-??.

pub fn from_y_silent(year: u16) -> Self

Same as Self::from_y but silently errors

Errors

• The year must be in-between 1000-9999

UNKNOWN_DATE will be returned silently if an error occurs.

pub fn from_ym_silent(year: u16, month: u8) -> Self

Same as Self::from_ym but silently errors

Errors

• The year must be in-between 1000-9999
• The month must be in-between 1-12

UNKNOWN_DATE will be returned silently if an error occurs.

pub fn from_ymd_silent(year: u16, month: u8, day: u8) -> Self

Same as Self::from_ymd but silently errors

Errors

• The year must be in-between 1000-9999
• The month must be in-between 1-12
• The day must be in-between 1-31 or Err is returned.

UNKNOWN_DATE will be returned silently if an error occurs.

pub fn from_str(string: &str) -> Result<Self, Self>

Parse arbitrary strings for a date.

If the complete date cannot be parsed, this function will attempt to extract at least the year, e.g:

let a = Date::from_str("2022-99-99").unwrap();
let b = Date::from_str("2022-03-32").unwrap();
let c = Date::from_str("2022-32-00").unwrap();
let d = Date::from_str("2022-00-31").unwrap();

assert!(a == "2022");
assert!(b == "2022");
assert!(c == "2022");
assert!(d == "2022");

If an Err is returned, it will contain a Date set with UNKNOWN_DATE which looks like: ????-??-??.

Examples:

let a = Date::from_str("2022-3-31").unwrap();
assert!(a == "2022-03-31");

pub fn from_str_silent(string: &str) -> Self

Same as Date::from_str but silently returns an UNKNOWN_DATE on error that isn’t wrapped in a Result::Err.

Trait Implementations

impl<'__de> BorrowDecode<'__de> for Date

fn borrow_decode<__D: BorrowDecoder<'__de>>( decoder: &mut __D ) -> Result<Self, DecodeError>

Attempt to decode this type with the given BorrowDecode.

impl Clone for Date

fn clone(&self) -> Date

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Date

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

Formats the value using the given formatter.

impl Decode for Date

fn decode<__D: Decoder>(decoder: &mut __D) -> Result<Self, DecodeError>

Attempt to decode this type with the given Decode.

impl Default for Date

fn default() -> Self

Calls Self::zero

impl<'de> Deserialize<'de> for Date

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

Deserialize this value from the given Serde deserializer.

impl Display for Date

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

Formats the value using the given formatter.

impl Encode for Date

fn encode<__E: Encoder>(&self, encoder: &mut __E) -> Result<(), EncodeError>

Encode a given type.

impl Hash for Date

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 Date

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Selfwhere Self: Sized + PartialOrd<Self>,

Restrict a value to a certain interval.

impl PartialEq<&Date> for (u16, u8, u8)

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

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

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

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

impl PartialEq<&Date> for str

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

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

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

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

impl PartialEq<&str> for Date

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

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

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

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

impl PartialEq<(u16, u8, u8)> for &Date

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

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

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

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

impl PartialEq<(u16, u8, u8)> for Date

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

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

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

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

impl PartialEq<Date> for (u16, u8, u8)

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

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

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

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

impl PartialEq<Date> for Date

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

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

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

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

impl PartialEq<Date> for str

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

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

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

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

impl PartialEq<str> for Date

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

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

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

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

impl PartialOrd<&Date> for (u16, u8, u8)

fn partial_cmp(&self, other: &&Date) -> 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 PartialOrd<&Date> for str

fn partial_cmp(&self, other: &&Date) -> 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 PartialOrd<&str> for Date

fn partial_cmp(&self, other: &&str) -> 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 PartialOrd<(u16, u8, u8)> for &Date

fn partial_cmp(&self, other: &(u16, u8, u8)) -> 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 PartialOrd<(u16, u8, u8)> for Date

fn partial_cmp(&self, other: &(u16, u8, u8)) -> 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 PartialOrd<Date> for (u16, u8, u8)

fn partial_cmp(&self, other: &Date) -> 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 PartialOrd<Date> for Date

fn partial_cmp(&self, other: &Date) -> 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 PartialOrd<Date> for str

fn partial_cmp(&self, other: &Date) -> 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 PartialOrd<str> for Date

fn partial_cmp(&self, other: &str) -> 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 Serialize for Date

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

Serialize this value into the given Serde serializer.

impl Copy for Date

impl Eq for Date

impl StructuralEq for Date

impl StructuralPartialEq for Date