# Crate newtype_derive [−] [src]

This crate provides several macros for deriving implementations of various traits for "newtype" wrappers (i.e. tuple structs with a single element). That is, given a tuple struct with exactly one field (e.g. `struct Buckets(i32)`), these macros will derive "obvious" implementations of traits such as `Add`, `Neg`, `Index`, `Deref`, `From`, etc.

All of these macros are designed to be used with the `custom_derive` crate, though they can be used independent of it.

# Example

Create a simple integer wrapper with some arithmetic operators:

    #[macro_use] extern crate custom_derive;
    #[macro_use] extern crate newtype_derive;

    custom_derive! {
        #[derive(NewtypeFrom, NewtypeAdd, NewtypeMul(i32))]
        pub struct Happy(i32);
    }

    // Let's add some happy little ints.
    let a = Happy::from(6);
    let b = Happy::from(7);
    let c = (a + b) * 3;
    let d: i32 = c.into();
    assert_eq!(d, 39);

Create a "deref-transparent" wrapper around a type:

    #[macro_use] extern crate custom_derive;
    #[macro_use] extern crate newtype_derive;

    custom_derive! {
        #[derive(NewtypeFrom,
            NewtypeDeref, NewtypeDerefMut,
            NewtypeIndex(usize), NewtypeIndexMut(usize)
            )]
        pub struct I32Array(Vec<i32>);
    }

    let mut arr = I32Array::from(vec![1, 2, 3]);
    arr.push(4);
    arr[2] = 5;
    assert_eq!(&**arr, &[1, 2, 5, 4]);
    assert_eq!(arr.len(), 4);

# Overview

This crate provides macros to derive implementations of the following traits for newtype structs:

- Binary Arithmetic Operators: Add, BitAnd, BitOr, BitXor, Div, Mul, Rem, Sub, Shl, Shr.
- Unary Arithmetic Operators: Neg, Not.
- Other Operators: Deref, DerefMut, Index, IndexMut.
- Formatting: Binary, Debug, Display, LowerExp, LowerHex, Octal, Pointer, UpperExp, UpperHex.
- Miscellaneous: From.
- Unstable: One, Zero.

All of these macros are named `Newtype$Trait`.

None of these macros currently support generic newtype structs.

## Binary Arithmetic Operators

Each of the binary arithmetic operators accept several deriving forms. To use `Add` on a struct `T` as an example:

- `NewtypeAdd`: `impl Add<T, Output=T> for T`
- `NewtypeAdd(&self)`: `impl<'a> Add<&'a T, Output=T> for &'a T`
- `NewtypeAdd(U)`: `impl Add<U, Output=T> for T`
- `NewtypeAdd(&self, U)`: `impl<'a> Add<U, Output=T> for &'a T`
- `NewtypeAdd(*)`: All four combinations of `T` and `&T`

In all cases, the implementation unwraps the newtype (where necessary), forwards to the wrapped value's implementation, then re-wraps the result in the newtype.

## Unary Arithmetic Operators

Each of the binary arithmetic operators accept several deriving forms. To use `Neg` on a struct `T` as an example:

- `NewtypeNeg`: `impl Neg<Output=T> for T`
- `NewtypeNeg(&self)`: `impl<'a> Neg<Output=T> for &'a T`
- `NewtypeNeg(*)`: both of the above

In all cases, the implementation unwraps the newtype, forwards to the wrapped value's implementation, then re-wraps the result in the newtype.

## Other Operators

`NewtypeDeref` and `NewtypeDerefMut` only support the argument-less form, and implements the corresponding trait such that the newtype structure derefs to a pointer to the wrapped value.

`NewtypeIndex` and `NewtypeIndexMut` must be used as `NewtypeIndex(usize)`, where the argument is the type to use for indexing. The call is forwarded to the wrapped value's implementation.

## Formatting

The deriving macros for the formatting traits in `std::fmt` forward to the wrapped value's implementation.

## Miscellaneous

`NewtypeFrom` implements `std::convert::From` twice: once for converting from the wrapped type to the newtype, and once for converting from the newtype to the wrapped type.

## Using Without `custom_derive!`

Although designed to be used with `custom_derive!`, all of the macros in this crate can be used without it. The following:

    custom_derive! {
        #[derive(Copy, Clone, Debug, NewtypeFrom, NewtypeAdd, NewtypeAdd(f32))]
        pub struct Meters(f32);
    }

Can also be written as:

    #[derive(Copy, Clone, Debug)]
    pub struct Meters(f32);

    NewtypeFrom! { () pub struct Meters(f32); }
    NewtypeAdd! { () pub struct Meters(f32); }
    NewtypeAdd! { (f32) pub struct Meters(f32); }

## Macros

NewtypeAdd! |
NewtypeBinary! |
NewtypeBitAnd! |
NewtypeBitOr! |
NewtypeBitXor! |
NewtypeDebug! |
NewtypeDeref! |
NewtypeDerefMut! |
NewtypeDisplay! |
NewtypeDiv! |
NewtypeFrom! |
NewtypeIndex! |
NewtypeIndexMut! |
NewtypeLowerExp! |
NewtypeLowerHex! |
NewtypeMul! |
NewtypeNeg! |
NewtypeNot! |
NewtypeOctal! |
NewtypePointer! |
NewtypeRem! |
NewtypeShl! |
NewtypeShr! |
NewtypeSub! |
NewtypeUpperExp! |
NewtypeUpperHex! |

# Help

## Keyboard Shortcuts

?
  Show this help dialog
S
  Focus the search field
⇤
  Move up in search results
⇥
  Move down in search results
⏎
  Go to active search result

## Search Tricks

Prefix searches with a type followed by a colon (e.g. `fn:`) to restrict the search to a given type.

Accepted types are: `fn`, `mod`, `struct`, `enum`, `trait`, `type`, `macro`, and `const`.

Search functions by type signature (e.g. `vec -> usize` or `* -> vec`)