Struct phantom_newtype::Amount

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

Amount<Unit> provides a type-safe way to keep an amount of some Unit.

E.g. the following code must not compile:

use phantom_newtype::Amount;

// These structs are just markers and have no semantic meaning.
enum Apples {}
enum Oranges {}

let trois_pommes = Amount::<Apples, u64>::from(3);
let five_oranges = Amount::<Oranges, u64>::from(5);

assert_eq!(8, (trois_pommes + five_oranges).get())

Amount<Unit, Repr> defines common boilerplate to make type-safe amounts more convenient. For example, you can compare amounts:

use phantom_newtype::Amount;

enum Apples {}
type NumApples = Amount<Apples, u64>;

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

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

You can do simple arithmetics with amounts:

use phantom_newtype::Amount;

enum Apples {}
enum Oranges {}

let x = Amount::<Apples, u64>::from(3);
let y = Amount::<Oranges, u64>::from(5);

assert_eq!(x + x, Amount::<Apples, u64>::from(6));
assert_eq!(y - y, Amount::<Oranges, u64>::from(0));

Multiplication of amounts is not supported: multiplying meters by meters gives square meters. However, you can scale an amount by a scalar or divide amounts:

use phantom_newtype::Amount;

enum Apples {}

let x = Amount::<Apples, u64>::from(3);
assert_eq!(x * 3, Amount::<Apples, u64>::from(9));
assert_eq!(1, x / x);
assert_eq!(3, (x * 3) / x);

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

use phantom_newtype::Amount;

enum Meters {}

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

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

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

let repr: u64 = 10;
let m_10 = Amount::<Meters, u64>::from(repr);
assert_eq!(serde_json::to_string(&m_10).unwrap(), serde_json::to_string(&repr).unwrap());

let copy: Amount<Meters, u64> = serde_json::from_str(&serde_json::to_string(&m_10).unwrap()).unwrap();
assert_eq!(copy, m_10);
}

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

use phantom_newtype::Amount;
enum Meters {}
type Distance = Amount<Meters, u64>;
const ASTRONOMICAL_UNIT: Distance = Distance::new(149_597_870_700);

assert!(ASTRONOMICAL_UNIT > Distance::from(0));

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

use phantom_newtype::Amount;

type Cell = std::cell::RefCell<i64>;
type NumCells = Amount<Cell, i64>;
const N: NumCells = NumCells::new(1);

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

Methods

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

pub fn get(&self) -> Repr

Returns the wrapped value.

use phantom_newtype::Amount;

enum Apples {}

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

impl<Unit, Repr> Amount<Unit, Repr>

pub const fn new(repr: Repr) -> Amount<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> Amount<Unit, Repr>

pub fn unit(&self) -> Unit

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

use phantom_newtype::Amount;

#[derive(Debug, Default)]
struct Seconds;
let duration = Amount::<Seconds, u64>::from(5);

assert_eq!("5 Seconds", format!("{} {:?}", duration, duration.unit()));

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

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

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

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

struct Cents;
type Money = Amount<Cents, u64>;

impl DisplayerOf<Money> for Cents {
  fn display(amount: &Money, f: &mut fmt::Formatter<'_>) -> fmt::Result {
    write!(f, "${}.{:02}", amount.get() / 100, amount.get() % 100)
  }
}

assert_eq!(format!("{}", Money::from(1005).display()), "$10.05");

Trait Implementations

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

fn from(repr: Repr) -> Self

Performs the conversion.

impl<Unit, Repr: Copy> Clone for Amount<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 Amount<Unit, Repr>

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

impl<Unit, Repr: Ord> Ord for Amount<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<Amount<Unit, Repr>> for Amount<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<Amount<Unit, Repr>> for Amount<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 Amount<Unit, Repr> where
    Repr: Display, 

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

Formats the value using the given formatter.

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

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

Formats the value using the given formatter.

impl<Unit, Repr> Div<Amount<Unit, Repr>> for Amount<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<Amount<Unit, Repr>> for Amount<Unit, Repr> where
    Repr: SubAssign + Copy, 

type Output = Self

The resulting type after applying the - operator.

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

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> Add<Amount<Unit, Repr>> for Amount<Unit, Repr> where
    Repr: AddAssign + Copy, 

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> 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 Amount<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> AddAssign<Amount<Unit, Repr>> for Amount<Unit, Repr> where
    Repr: AddAssign + Copy, 

fn add_assign(&mut self, rhs: 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> SubAssign<Amount<Unit, Repr>> for Amount<Unit, Repr> where
    Repr: SubAssign + Copy, 

fn sub_assign(&mut self, rhs: Self)

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 Amount<Unit, Repr> where
    Repr: MulAssign + Copy, 

fn mul_assign(&mut self, rhs: Repr)

Performs the *= operation.

impl<Unit, Repr: Hash> Hash for Amount<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 Amount<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 Amount<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.