Newtypes

The newtypes crate is meant to ease the implementation of the Newtype pattern while trying to make as few assumptions as possible.

newtype! Macro

The newtype! macro creates a barebones newtype by wrapping an inner type with a struct, and, if possible, implementing some extra traits for it.

By default, all declared structs have visibility pub.

use newtypes::newtype;

newtype!(NewTypeName, underlying_type);

// In case we want to automatically derive traits (like serde's
// Serialize or Deserialize):
newtype!(NewTypeName, underlying_type; Trait1, ..., TraitN);

Example:

use newtypes::newtype;
use serde::{Deserialize, Serialize}

newtype!(UserId, u32);

newtype!(GroupId, u32; Serialize, Deserialize);

Implemented traits

• For all:
  • Debug
  • Into<inner_type>
• For integers:
  • Clone
  • Copy
  • Hash
  • PartialEq
  • Eq
• For floating point numbers:
  • Clone
  • Copy
  • PartialEq
• For String:
  • Clone
  • Hash
  • PartialEq
  • Eq

IMPORTANT: The inner value is private. If there are no constraints on the inner value, then we can rely on newtype_from! macro to implement the From and FromStr traits for us.

Otherwise we can choose to implement From, FromStr and TryFrom manually.

newtype_ord! Macro

The newtype_ord! macro extends the functionality provided with newtype! by implementing the PartialOrd and Ord traits (when possible).

Example:

use newtypes::newtype_ord;
use serde::{Deserialize, Serialize}

newtype_ord!(Rank, u16);

newtype_ord!(TicketNumber, u16; Serialize, Deserialize);

NOTE: It only works for integers, floating point numbers, and String.

newtype_unit! Macro

The newtype_unit! macro extends the functionality provided with newtype_ord! by implementing the Add, Sub, AddAssign, SubAssign, and Default traits.

Example:

use newtypes::newtype_unit;
use serde::Deserialize;

newtype_unit!(Weight, f32);

newtype_unit!(Length, f32; Deserialize);

NOTE: It only works for integers and floating point numbers.

NOTE: It does not implement arithmetic operations beyond addition and subtraction. Doing that properly would require a more complex library focused on dealing with "units" (example: multiplying lengths gives us an area).

newtype_from! Macro

The macro newtype_from! implements the From and FromStr traits for us in case it's possible.

It has to be used in combination with one of the other ones (newtype!, newtype_ord!, or newtype_unit!).

Example:

use newtypes::{newtype, newtype_from};

newtype!(Weight, f32);
newtype_from!(Weight, f32);

NOTE: It only works for integers, floating point numbers, and String.