Struct readable::Time

pub struct Time(_, _);

Human-readable std::time::Duration.

The input is always assumed to be in seconds.

Time::from input can be:

• u8, u16, u32, u64, usize
• std::time::Duration, std::time::Instant

The lowest unit is second, the highest is year, and week is skipped in favor of 7 days.

Inlining

If the feature flag inline_time is enabled, inputs ranging from 0..3660 into Time::from will return inlined static bytes, the max string representation of this is 1 hour, 1 minute.

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

Cloning

Clone may be expensive:

// Cheap (stack allocated string).
let a = Time::from(60_u8);
assert!(a == "1 minute");
let b = a.clone();

// Expensive (heap allocated string).
let a = Time::from(3234815_u64);
assert!(a == "1 month, 6 days, 23 hours, 59 minutes, 59 seconds");
let b = a.clone();

The actual string used internally is not a String, but a CompactString so that any string 24 bytes (12 bytes on 32-bit) or less are stack allocated instead of heap allocated.

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

Math

These operators are overloaded. They will always output a new Self:

• Add +
• Sub -
• Div /
• Mul *
• Rem %

They can either be:

• Combined with another Self: Time::from(1) + Time::from(1)
• Or with the inner number itself: Time::from(1) + 1

They also have the same panic!() behavior on overflow as the normal ones, because internally, it is just calling .inner() $OPERATOR $NUMBER.

assert!(Time::from(10_u64) + 10 == Time::from(20_u64));
assert!(Time::from(10_u64) - 10 == Time::from(0_u64));
assert!(Time::from(10_u64) / 10 == Time::from(1_u64));
assert!(Time::from(10_u64) * 10 == Time::from(100_u64));
assert!(Time::from(10_u64) % 10 == Time::from(0_u64));

Overflow example:

let n = Time::from(u64::MAX) + u64::MAX;

Examples

assert!(Time::from(0_u64)        == "0 seconds");
assert!(Time::from(1_u64)        == "1 second");
assert!(Time::from(2_u64)        == "2 seconds");
assert!(Time::from(59_u64)       == "59 seconds");
assert!(Time::from(60_u64)       == "1 minute");
assert!(Time::from(61_u64)       == "1 minute, 1 second");
assert!(Time::from(62_u64)       == "1 minute, 2 seconds");
assert!(Time::from(120_u64)      == "2 minutes");
assert!(Time::from(121_u64)      == "2 minutes, 1 second");
assert!(Time::from(122_u64)      == "2 minutes, 2 seconds");
assert!(Time::from(179_u64)      == "2 minutes, 59 seconds");
assert!(Time::from(3599_u64)     == "59 minutes, 59 seconds");
assert!(Time::from(3600_u64)     == "1 hour");
assert!(Time::from(3601_u64)     == "1 hour, 1 second");
assert!(Time::from(3602_u64)     == "1 hour, 2 seconds");
assert!(Time::from(3660_u64)     == "1 hour, 1 minute");
assert!(Time::from(3720_u64)     == "1 hour, 2 minutes");
assert!(Time::from(86399_u64)    == "23 hours, 59 minutes, 59 seconds");
assert!(Time::from(86400_u64)    == "1 day");
assert!(Time::from(86401_u64)    == "1 day, 1 second");
assert!(Time::from(86402_u64)    == "1 day, 2 seconds");
assert!(Time::from(86460_u64)    == "1 day, 1 minute");
assert!(Time::from(86520_u64)    == "1 day, 2 minutes");
assert!(Time::from(90000_u64)    == "1 day, 1 hour");
assert!(Time::from(93600_u64)    == "1 day, 2 hours");
assert!(Time::from(604799_u64)   == "6 days, 23 hours, 59 minutes, 59 seconds");
assert!(Time::from(604800_u64)   == "7 days");
assert!(Time::from(2630016_u64)  == "1 month");
assert!(Time::from(3234815_u64)  == "1 month, 6 days, 23 hours, 59 minutes, 59 seconds");
assert!(Time::from(5260032_u64)  == "2 months");
assert!(Time::from(31557600_u64) == "1 year");
assert!(Time::from(63115200_u64) == "2 years");
assert_eq!(
    Time::from(u64::MAX),
    "584542046090 years, 7 months, 15 days, 17 hours, 5 minutes, 3 seconds",
);

Credit

This code is forked from https://docs.rs/humantime, edited to remove sub-second time, change spacing and some words.

Implementations

impl Time

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

Returns the inner number.

pub fn into_string(self) -> String

Consumes Self, returning the inner String.

pub fn into_raw(self) -> (u64, 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 fn len(&self) -> usize

The length of the inner String

pub fn is_empty(&self) -> bool

If the inner String is empty or not

pub const fn zero() -> Self

assert!(Time::zero() == 0_u64);
assert!(Time::zero() == "0 seconds");

pub const fn second() -> Self

assert!(Time::second() == 1_u64);
assert!(Time::second() == "1 second");

pub const fn minute() -> Self

assert!(Time::minute() == 60_u64);
assert!(Time::minute() == "1 minute");

pub const fn hour() -> Self

assert!(Time::hour() == 3600_u64);
assert!(Time::hour() == "1 hour");

pub const fn day() -> Self

assert!(Time::day() == 86400_u64);
assert!(Time::day() == "1 day");

pub const fn month() -> Self

assert!(Time::month() == 2630016_u64);
assert!(Time::month() == "1 month");

pub const fn year() -> Self

assert!(Time::year() == 31557600_u64);
assert!(Time::year() == "1 year");

Trait Implementations

impl Add<&Time> for Time

type Output = Time

The resulting type after applying the + operator.

fn add(self, other: &Time) -> Self

Performs the + operation.

impl Add<&Time> for u64

type Output = u64

The resulting type after applying the + operator.

fn add(self, other: &Time) -> Self

Performs the + operation.

impl Add<&u64> for Time

type Output = Time

The resulting type after applying the + operator.

fn add(self, other: &u64) -> Self

Performs the + operation.

impl Add<Time> for Time

type Output = Time

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<Time> for u64

type Output = u64

The resulting type after applying the + operator.

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

Performs the + operation.

impl Add<u64> for Time

type Output = Time

The resulting type after applying the + operator.

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

Performs the + operation.

impl<'__de> BorrowDecode<'__de> for Time

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

Attempt to decode this type with the given BorrowDecode.

impl Clone for Time

fn clone(&self) -> Time

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Time

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

Formats the value using the given formatter.

impl Decode for Time

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

Attempt to decode this type with the given Decode.

impl Default for Time

fn default() -> Self

Calls Self::zero

impl<'de> Deserialize<'de> for Time

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

Deserialize this value from the given Serde deserializer.

impl Display for Time

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

Formats the value using the given formatter.

impl Div<&Time> for Time

type Output = Time

The resulting type after applying the / operator.

fn div(self, other: &Time) -> Self

Performs the / operation.

impl Div<&Time> for u64

type Output = u64

The resulting type after applying the / operator.

fn div(self, other: &Time) -> Self

Performs the / operation.

impl Div<&u64> for Time

type Output = Time

The resulting type after applying the / operator.

fn div(self, other: &u64) -> Self

Performs the / operation.

impl Div<Time> for Time

type Output = Time

The resulting type after applying the / operator.

fn div(self, other: Time) -> Self

Performs the / operation.

impl Div<Time> for u64

type Output = u64

The resulting type after applying the / operator.

fn div(self, other: Time) -> Self

Performs the / operation.

impl Div<u64> for Time

type Output = Time

The resulting type after applying the / operator.

fn div(self, other: u64) -> Self

Performs the / operation.

impl Encode for Time

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

Encode a given type.

impl From<&Duration> for Time

fn from(duration: &Duration) -> Self

Converts to this type from the input type.

impl From<&Instant> for Time

fn from(instant: &Instant) -> Self

Converts to this type from the input type.

impl From<Duration> for Time

fn from(duration: Duration) -> Self

Converts to this type from the input type.

impl From<Instant> for Time

fn from(instant: Instant) -> Self

Converts to this type from the input type.

impl From<u16> for Time

fn from(number: u16) -> Self

Converts to this type from the input type.

impl From<u32> for Time

fn from(number: u32) -> Self

Converts to this type from the input type.

impl From<u64> for Time

fn from(secs: u64) -> Self

Converts to this type from the input type.

impl From<u8> for Time

fn from(number: u8) -> Self

Converts to this type from the input type.

impl From<usize> for Time

fn from(number: usize) -> Self

Converts to this type from the input type.

impl Hash for Time

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 Mul<&Time> for Time

type Output = Time

The resulting type after applying the * operator.

fn mul(self, other: &Time) -> Self

Performs the * operation.

impl Mul<&Time> for u64

type Output = u64

The resulting type after applying the * operator.

fn mul(self, other: &Time) -> Self

Performs the * operation.

impl Mul<&u64> for Time

type Output = Time

The resulting type after applying the * operator.

fn mul(self, other: &u64) -> Self

Performs the * operation.

impl Mul<Time> for Time

type Output = Time

The resulting type after applying the * operator.

fn mul(self, other: Time) -> Self

Performs the * operation.

impl Mul<Time> for u64

type Output = u64

The resulting type after applying the * operator.

fn mul(self, other: Time) -> Self

Performs the * operation.

impl Mul<u64> for Time

type Output = Time

The resulting type after applying the * operator.

fn mul(self, other: u64) -> Self

Performs the * operation.

impl Ord for Time

fn cmp(&self, other: &Time) -> 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<&Time> for str

fn eq(&self, other: &&Time) -> 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<&Time> for u64

fn eq(&self, other: &&Time) -> 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 Time

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<Time> for Time

fn eq(&self, other: &Time) -> 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<Time> for str

fn eq(&self, other: &Time) -> 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<Time> for u64

fn eq(&self, other: &Time) -> 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 Time

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<u64> for &Time

fn eq(&self, other: &u64) -> 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<u64> for Time

fn eq(&self, other: &u64) -> 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<&Time> for str

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

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

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<Time> for Time

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

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

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

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<u64> for &Time

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

fn partial_cmp(&self, other: &u64) -> 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 Rem<&Time> for Time

type Output = Time

The resulting type after applying the % operator.

fn rem(self, other: &Time) -> Self

Performs the % operation.

impl Rem<&Time> for u64

type Output = u64

The resulting type after applying the % operator.

fn rem(self, other: &Time) -> Self

Performs the % operation.

impl Rem<&u64> for Time

type Output = Time

The resulting type after applying the % operator.

fn rem(self, other: &u64) -> Self

Performs the % operation.

impl Rem<Time> for Time

type Output = Time

The resulting type after applying the % operator.

fn rem(self, other: Time) -> Self

Performs the % operation.

impl Rem<Time> for u64

type Output = u64

The resulting type after applying the % operator.

fn rem(self, other: Time) -> Self

Performs the % operation.

impl Rem<u64> for Time

type Output = Time

The resulting type after applying the % operator.

fn rem(self, other: u64) -> Self

Performs the % operation.

impl Serialize for Time

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

Serialize this value into the given Serde serializer.

impl Sub<&Time> for Time

type Output = Time

The resulting type after applying the - operator.

fn sub(self, other: &Time) -> Self

Performs the - operation.

impl Sub<&Time> for u64

type Output = u64

The resulting type after applying the - operator.

fn sub(self, other: &Time) -> Self

Performs the - operation.

impl Sub<&u64> for Time

type Output = Time

The resulting type after applying the - operator.

fn sub(self, other: &u64) -> Self

Performs the - operation.

impl Sub<Time> for Time

type Output = Time

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<Time> for u64

type Output = u64

The resulting type after applying the - operator.

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

Performs the - operation.

impl Sub<u64> for Time

type Output = Time

The resulting type after applying the - operator.

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

Performs the - operation.

impl Eq for Time

impl StructuralEq for Time

impl StructuralPartialEq for Time