Struct Span

pub struct Span {
    pub seconds: u64,
}

Timespan (Duration)

Simply an unsigned count of seconds. Debug, Display and FromStr implementations break this number, which is often incomprehensibly large, down into understandable units. So instead of Span { seconds: 108030 } you get 1d6h30s.

These are the units used:

Scale	unit	seconds
Years	y	31556952
Months	mo	2629746
Weeks	w	604800
Days	d	86400
Hours	h	3600
Minutes	m	60
Seconds	s	1

As explained in the documentation for Scale, the amount of seconds for y and mo is the average for each of these scales.

The Span can be parsed from the terse duration format using parse or try_parse. These methods are also const, so they can be used to define constants.

use greg::Span;

const TIMEOUT: Span = Span::parse("30s");

assert_eq!(Span::parse("0s"), Span::from_seconds(0));
assert_eq!(Span::parse("1m30s"), Span::MINUTE + Span::SECOND * 30);
assert_eq!(Span::parse("1d10h"), Span::DAY + Span::HOUR * 10);
assert_eq!(Span::try_parse("48h"), Ok(Span::DAY * 2));
assert_eq!(
    Span::parse("3w2h10m30s"),
    Span::WEEK * 3 + Span::HOUR * 2 + Span::MINUTE * 10 + Span::SECOND * 30
);

The alternate form for Display (with {:#}) produces a string where each number/unit pair is separated by a space. Additionally, if a precision is specified (with {:.2}), at most the requested number of number/unit pairs are printed, truncating smaller units.

use greg::Span;
let span = Span::parse("1w2d8h33m12s");

assert_eq!(span.to_string(), "1w2d8h33m12s");
assert_eq!(format!("{span:#}"), "1w 2d 8h 33m 12s");
assert_eq!(format!("{span:#.2}"), "1w 2d");

Fields

seconds: u64

Duration in seconds

Implementations

impl Span

pub const fn from_seconds(seconds: u64) -> Self

Same as constructing Span {seconds} directly

impl Span

pub const SCALES: [(u64, &'static str, Scale); 7]

pub const WEEK: Self

pub const DAY: Self

pub const HOUR: Self

pub const MINUTE: Self

pub const SECOND: Self

pub const ZERO: Self

pub const MAX: Self

The largest possible Span

impl Span

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

Checked addition: computes self + other, returning None if overflow occurred.

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

Checked subtraction: computes self - other, returning None if overflow occurred.

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

Saturating addition: computes self + other, saturating at the numeric bounds instead of overflowing.

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

Saturating subtraction: computes self - other, saturating at the numeric bounds instead of overflowing.

pub fn scale_div(self) -> (Scale, u64)

Break down into a Scale and count

Returns the biggest Scale that divides the Span without a remainder as well as the result of this division. One exception is the empty Span::ZERO, because the count is 0 for every Scale. Instead of returning (Scale::Years, 0), which would be counter-intuitive, the zero-second Span always returns the more natural (Scale::Seconds, 0).

Remember that Scale::Years and Scale::Months are special, because they represent an average, they do not cleanly divide into weeks, days or even minutes! See the Scale documentation for details.

use greg::{Span, Scale};

assert_eq!(Span::from_seconds(600).scale_div(), (Scale::Minutes, 10));
assert_eq!(Span::ZERO.scale_div(), (Scale::Seconds, 0));
let one_and_a_half: Span = "1h30m".parse().unwrap();
assert_eq!(one_and_a_half.scale_div(), (Scale::Minutes, 90));

impl Span

pub const fn parse(from: &str) -> Self

Try to parse terse duration format and panic if invalid

 use greg::Span;
 const CHILIAD: Span = Span::parse("1000y");

 assert_eq!(Span::parse("0s"), Span::ZERO);
 assert_eq!(Span::parse("10s").seconds, 10);
 assert_eq!(Span::parse("1m30s").seconds, 90);
 let _ = Span::parse("3mo2h10m30s");

This is mainly useful in const contexts, since the panic gets caught at compile-time.

 use greg::Span;
 const DECADE: Span = Span::parse("10t"); // typo: "t" instead of "y"

pub const fn try_parse(from: &str) -> Result<Self, ParseSpanError>

Try to parse terse duration format

 use greg::Span;

 assert_eq!(Span::try_parse("0s"), Ok(Span::ZERO));
 assert_eq!(Span::try_parse("1w"), Ok(Span::WEEK));
 assert_eq!(Span::try_parse("1m30s"), Ok(Span::MINUTE + Span::SECOND * 30));
 let _ = Span::try_parse("3mo2h10m30s").unwrap();

 assert!(Span::try_parse("10 hours").is_err(), "long-form units don't work");

Trait Implementations

impl Add<Span> for Point

type Output = Point

The resulting type after applying the + operator.

fn add(self, rhs: Span) -> Self::Output

Performs the + operation.

impl Add for Span

type Output = Span

The resulting type after applying the + operator.

fn add(self, rhs: Span) -> Self::Output

Performs the + operation.

impl Clone for Span

fn clone(&self) -> Span

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Span

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Span

Available on crate feature serde only.

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Span

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

Formats the value using the given formatter.

impl Div<Scale> for Span

type Output = u64

The resulting type after applying the / operator.

fn div(self, rhs: Scale) -> Self::Output

Performs the / operation.

impl Div<u64> for Span

type Output = u64

The resulting type after applying the / operator.

fn div(self, rhs: u64) -> Self::Output

Performs the / operation.

impl From<Scale> for Span

fn from(scale: Scale) -> Self

Converts to this type from the input type.

impl FromSql for Span

Available on crate feature rusqlite only.

fn column_result(value: ValueRef<'_>) -> FromSqlResult<Self>

Converts SQLite value into Rust value.

impl FromStr for Span

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

Parse terse duration format

See try_parse for a const method and some more details.

type Err = ParseSpanError

The associated error which can be returned from parsing.

impl Hash for Span

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<u64> for Span

type Output = Span

The resulting type after applying the * operator.

fn mul(self, rhs: u64) -> Self::Output

Performs the * operation.

impl Ord for Span

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

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

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

const 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 Span

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

type Output = Span

The resulting type after applying the % operator.

fn rem(self, rhs: Scale) -> Self::Output

Performs the % operation.

impl Serialize for Span

Available on crate feature serde only.

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

where S: Serializer,

Serialize this value into the given Serde serializer.

impl Sub<Span> for Point

type Output = Point

The resulting type after applying the - operator.

fn sub(self, rhs: Span) -> Self::Output

Performs the - operation.

impl Sub for Span

type Output = Span

The resulting type after applying the - operator.

fn sub(self, rhs: Span) -> Self::Output

Performs the - operation.

impl ToSql for Span

Available on crate feature rusqlite only.

fn to_sql(&self) -> SqlResult<ToSqlOutput<'_>>

Converts Rust value to SQLite value

impl Copy for Span

impl Eq for Span

impl StructuralPartialEq for Span