Struct fundu::CustomTimeUnit

pub struct CustomTimeUnit<'a> { /* private fields */ }

Available on crate feature custom only.

A CustomTimeUnit is a completely customizable TimeUnit using an additional Multiplier.

Custom time units have a base TimeUnit (which has an inherent Multiplier) and an optional Multiplier which acts as an additional Multiplier to the multiplier of the base_unit. Using a multiplier with Multiplier(1, 0) is equivalent to using no multiplier at all but see also the Problems section. A CustomTimeUnit also consists of identifiers which are used to identify the CustomTimeUnit during the parsing process.

To create a CustomTimeUnit representing two weeks there are multiple solutions. Just to show two very obvious examples:

use fundu::TimeUnit::*;
use fundu::{CustomTimeUnit, Multiplier};

assert_ne!(
    (CustomTimeUnit::new(Week, &["fortnight", "fortnights"], Some(Multiplier(2, 0)))),
    (CustomTimeUnit::new(Day, &["fortnight", "fortnights"], Some(Multiplier(14, 0))))
);

Both would actually be equal in the sense, that they would resolve to the same result when multiplying the base_unit with the multiplier, however they are treated as not equal and it’s possible to choose freely between the definitions. Using both of the definitions in parallel within the crate::CustomDurationParser would be possible and produces the desired result, although it does not provide any benefits.

use std::time::Duration;

use fundu::TimeUnit::*;
use fundu::{CustomDurationParser, CustomTimeUnit, Multiplier};

let parser = CustomDurationParser::builder()
    .custom_time_units(&[
        CustomTimeUnit::new(Week, &["fortnight", "fortnights"], Some(Multiplier(2, 0))),
        CustomTimeUnit::new(Day, &["fortnight", "fortnights"], Some(Multiplier(14, 0))),
    ])
    .build();

assert_eq!(
    parser.parse("1fortnight").unwrap(),
    Duration::new(1209600, 0)
);

In summary, the best choice is to use the CustomTimeUnit with a base_unit having the lowest Multiplier but see also Problems below.

Equality of two CustomTimeUnit is defined as

base_unit == other.base_unit && multiplier == other.multiplier

Problems

For base_units other than Second there may occur an overflow (and panic) during the parsing process. The Multiplier boundaries are chosen as high as possible but if the base_unit multiplier multiplied with multiplier exceeds (u64::MAX, i16::MIN) or (u64::MAX, i16::MAX) this multiplication overflows. By example, with Multiplier(m, e) two multipliers x, y are multiplied as follows : m = x.m * y.m, e = x.e + y.e:

If the base_unit is Year, which has a multiplier of m = 31557600, e = 0, then this restricts the multiplier to m = u64::MAX / 31557600 = 584_542_046_090, e = 32767 or e = -32768.

If the base_unit is NanoSecond, which has a multiplier of m = 1, e = -9, then this restricts the multiplier to m = u64::MAX, e = -32768 + 9 = -32,759 or e = i16::MAX = 32767.

The base_units are Seconds based what results in the following table with limits for the multiplier:

base_unit	Multiplier	Limit m	Limit -e	Limit +e
Nanosecond	Multiplier(1, -9)	u64::MAX	-32,759	i16::MAX
Microsecond	Multiplier(1, -6)	u64::MAX	-32,762	i16::MAX
Millisecond	Multiplier(1, -3)	u64::MAX	-32,765	i16::MAX
Second	Multiplier(1, 0)	u64::MAX	i16::MIN	i16::MAX
Minute	Multiplier(60, 0)	307_445_734_561_825_860	i16::MIN	i16::MAX
Hour	Multiplier(3600, 0)	5_124_095_576_030_431	i16::MIN	i16::MAX
Day	Multiplier(86400, 0)	213_503_982_334_601	i16::MIN	i16::MAX
Week	Multiplier(604800, 0)	30_500_568_904_943	i16::MIN	i16::MAX
Month	Multiplier(2629800, 0)	7_014_504_553_087	i16::MIN	i16::MAX
Year	Multiplier(31557600, 0)	584_542_046_090	i16::MIN	i16::MAX

Implementations

impl<'a> CustomTimeUnit<'a>

pub const fn new( base_unit: TimeUnit, identifiers: &'a [&'a str], multiplier: Option<Multiplier> ) -> Self

Create a new CustomTimeUnit

See also the documentation for CustomTimeUnit.

Examples

use std::time::Duration;

use fundu::TimeUnit::*;
use fundu::{CustomDurationParser, CustomTimeUnit, Multiplier};

let time_unit = CustomTimeUnit::new(Second, &["shake", "shakes"], Some(Multiplier(1, -8)));
let parser = CustomDurationParser::builder()
    .custom_time_unit(time_unit)
    .build();

assert_eq!(parser.parse("1shake").unwrap(), Duration::new(0, 10));

Trait Implementations

impl<'a> Clone for CustomTimeUnit<'a>

fn clone(&self) -> CustomTimeUnit<'a>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for CustomTimeUnit<'a>

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

Formats the value using the given formatter.

impl<'a> PartialEq<CustomTimeUnit<'a>> for CustomTimeUnit<'a>

fn eq(&self, other: &Self) -> 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<'a> Copy for CustomTimeUnit<'a>

impl<'a> Eq for CustomTimeUnit<'a>

impl<'a> StructuralEq for CustomTimeUnit<'a>