Struct phantom_newtype::Instant

pub struct Instant<Unit, Repr>(_, _);

Instant<Unit> provides a type-safe way to keep absolute time of some events, expressed in Units (CPU ticks, seconds from epoch, years from birth, etc).

You can compare instants:

use phantom_newtype::Instant;

enum SecondsFromEpoch {}
type UnixTime = Instant<SecondsFromEpoch, i64>;

assert_eq!(true, UnixTime::from(3) < UnixTime::from(5));
assert_eq!(false, UnixTime::from(3) > UnixTime::from(5));
assert_eq!(true, UnixTime::from(3) != UnixTime::from(5));
assert_eq!(true, UnixTime::from(5) == UnixTime::from(5));
assert_eq!(false, UnixTime::from(5) != UnixTime::from(5));

assert_eq!(vec![UnixTime::from(3), UnixTime::from(5)].iter().max().unwrap(),
           &UnixTime::from(5));

Instants support basic arithmetics, you can:

• Subtract an instant from another instant to get amount of units between them.
• Add/subtract amount of units to/from an instant to get another instant.

use phantom_newtype::{Amount, Instant};

enum SecondsFromEpoch {}

type UnixTime = Instant<SecondsFromEpoch, i64>;
type TimeDiff = Amount<SecondsFromEpoch, i64>;

let epoch = UnixTime::from(0);
let some_date = UnixTime::from(123456789);
let diff = TimeDiff::from(123456789);

assert_eq!(some_date - epoch, diff);
assert_eq!(some_date - diff, epoch);
assert_eq!(epoch + diff, some_date);

Direct multiplication of instants is not supported, however, you can scale them by a scalar or divide to get a scalar back:

use phantom_newtype::Instant;

enum SecondsFromEpoch {}
type UnixTime = Instant<SecondsFromEpoch, i64>;

let x = UnixTime::from(123456);
assert_eq!(x * 3, UnixTime::from(3 * 123456));
assert_eq!(1, x / x);
assert_eq!(3, (x * 3) / x);

Note that the unit is only available at compile time, thus using Instant instead of u64 doesn't incur any runtime penalty:

use phantom_newtype::Instant;

enum SecondsFromEpoch {}

let ms = Instant::<SecondsFromEpoch, u64>::from(10);
assert_eq!(std::mem::size_of_val(&ms), std::mem::size_of::<u64>());

Instants can be serialized and deserialized with serde. Serialized forms of Instant<Unit, Repr> and Repr are identical.

#[cfg(feature = "serde")] {
use phantom_newtype::Instant;
use serde::{Serialize, Deserialize};
use serde_json;

enum SecondsFromEpoch {}
type UnixTime = Instant<SecondsFromEpoch, i64>;

let repr: u64 = 123456;
let time = UnixTime::from(repr);
assert_eq!(serde_json::to_string(&time).unwrap(), serde_json::to_string(&repr).unwrap());

let copy: UnitTime = serde_json::from_str(&serde_json::to_string(&time).unwrap()).unwrap();
assert_eq!(copy, time);
}

You can also declare constants of Instant<Unit, Repr> using new function:

use phantom_newtype::Instant;

enum SecondsFromEpoch {}
type UnixTime = Instant<SecondsFromEpoch, u64>;

const EPOCH: UnixTime = UnixTime::new(0);

Instants can be sent between threads if the Repr allows it, no matter which Unit is used.

use phantom_newtype::Instant;

type Cell = std::cell::RefCell<i64>;
type CellInstant = Instant<Cell, i64>;
const I: CellInstant = CellInstant::new(1234);

let instant_from_thread = std::thread::spawn(|| &I).join().unwrap();
assert_eq!(I, *instant_from_thread);

Methods

impl<Unit, Repr: Copy> Instant<Unit, Repr>

pub fn get(&self) -> Repr

Returns the wrapped value.

use phantom_newtype::Instant;

enum Apples {}

let three_apples = Instant::<Apples, u64>::from(3);
assert_eq!(9, (three_apples * 3).get());

impl<Unit, Repr> Instant<Unit, Repr>

pub const fn new(repr: Repr) -> Instant<Unit, Repr>

new is a synonym for from that can be evaluated in compile time. The main use-case of this functions is defining constants.

impl<Unit: Default, Repr: Copy> Instant<Unit, Repr>

pub fn unit(&self) -> Unit

Provides a useful shortcut to access units of an instant if they implement the Default trait:

use phantom_newtype::Instant;

#[derive(Debug, Default)]
struct SecondsFromEpoch;
let when = Instant::<SecondsFromEpoch, i64>::from(5);

assert_eq!("5 SecondsFromEpoch", format!("{} {:?}", when, when.unit()));

impl<Unit, Repr> Instant<Unit, Repr> where
    Unit: DisplayerOf<Instant<Unit, Repr>>, 

pub fn display(&self) -> DisplayProxy<Self, Unit>

display provides a machanism to implement a custom display for phantom types.

use phantom_newtype::{Instant, DisplayerOf};
use std::fmt;

struct YearUnit;
type YearAD = Instant<YearUnit, u64>;

impl DisplayerOf<YearAD> for YearUnit {
  fn display(year: &YearAD, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    write!(f, "{} AD", year.get())
  }
}

assert_eq!(format!("{}", YearAD::from(1221).display()), "1221 AD");

Trait Implementations

impl<Unit, Repr: Copy> From<Repr> for Instant<Unit, Repr>

fn from(repr: Repr) -> Self

Performs the conversion.

impl<Unit, Repr: Copy> Clone for Instant<Unit, Repr>

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Unit, Repr: Copy> Copy for Instant<Unit, Repr>

impl<Unit, Repr: Eq> Eq for Instant<Unit, Repr>

impl<Unit, Repr: Ord> Ord for Instant<Unit, Repr>

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

This method returns an Ordering between self and other.

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

Compares and returns the maximum of two values.

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

Compares and returns the minimum of two values.

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

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<Unit, Repr: PartialEq> PartialEq<Instant<Unit, Repr>> for Instant<Unit, Repr>

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

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

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Unit, Repr: PartialOrd> PartialOrd<Instant<Unit, Repr>> for Instant<Unit, Repr>

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

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

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] 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<Unit, Repr> Display for Instant<Unit, Repr> where
    Repr: Display, 

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

Formats the value using the given formatter.

impl<Unit, Repr> Debug for Instant<Unit, Repr> where
    Repr: Debug, 

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

Formats the value using the given formatter.

impl<Unit, Repr> Div<Instant<Unit, Repr>> for Instant<Unit, Repr> where
    Repr: Div<Repr> + Copy, 

type Output = <Repr as Div>::Output

The resulting type after applying the / operator.

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

Performs the / operation.

impl<Unit, Repr> Sub<Instant<Unit, Repr>> for Instant<Unit, Repr> where
    Repr: Sub + Copy, 

type Output = Amount<Unit, <Repr as Sub>::Output>

The resulting type after applying the - operator.

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

Performs the - operation.

impl<Unit, Repr, Repr2> Sub<Amount<Unit, Repr2>> for Instant<Unit, Repr> where
    Repr: SubAssign<Repr2> + Copy,
    Repr2: Copy, 

type Output = Self

The resulting type after applying the - operator.

fn sub(self, rhs: Amount<Unit, Repr2>) -> Self

Performs the - operation.

impl<Unit, Repr, Repr2> Add<Amount<Unit, Repr2>> for Instant<Unit, Repr> where
    Repr: AddAssign<Repr2> + Copy,
    Repr2: Copy, 

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: Amount<Unit, Repr2>) -> Self

Performs the + operation.

impl<Unit, Repr> Mul<Repr> for Instant<Unit, Repr> where
    Repr: MulAssign + Copy, 

type Output = Self

The resulting type after applying the * operator.

fn mul(self, rhs: Repr) -> Self

Performs the * operation.

impl<Unit, Repr, Repr2> AddAssign<Amount<Unit, Repr2>> for Instant<Unit, Repr> where
    Repr: AddAssign<Repr2> + Copy,
    Repr2: Copy, 

fn add_assign(&mut self, rhs: Amount<Unit, Repr2>)

Performs the += operation.

impl<Unit, Repr, Repr2> SubAssign<Amount<Unit, Repr2>> for Instant<Unit, Repr> where
    Repr: SubAssign<Repr2> + Copy,
    Repr2: Copy, 

fn sub_assign(&mut self, rhs: Amount<Unit, Repr2>)

Performs the -= operation.

impl<Unit, Repr> MulAssign<Repr> for Instant<Unit, Repr> where
    Repr: MulAssign + Copy, 

fn mul_assign(&mut self, rhs: Repr)

Performs the *= operation.

impl<Unit, Repr: Hash> Hash for Instant<Unit, Repr>

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, 

Feeds a slice of this type into the given [Hasher].

impl<Unit, Repr: Serialize> Serialize for Instant<Unit, Repr>

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

Serialize this value into the given Serde serializer.

impl<'de, Unit, Repr> Deserialize<'de> for Instant<Unit, Repr> where
    Repr: Deserialize<'de>, 

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

Deserialize this value from the given Serde deserializer.