Newtypes

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

To use it, add the following use/import line:

// We have to import all macros at once because the "public" ones rely
// on "private" ones, and it would be too cumbersome to import them one
// by one.
use newtypes::*;

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.

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:

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 From, FromStr and TryFrom traits are not implemented, and 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.

newtype_ord! Macro

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

Example:

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:

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:

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

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