newtypes 0.1.0

Macros that ease the implementation of the Newtype pattern
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

# Newtypes

The `newtypes` crate is meant to ease the implementation of the
[Newtype](https://rust-unofficial.github.io/patterns/patterns/behavioural/newtype.html)
pattern while trying to make as few assumptions as possible.

To use it, add the following use/import line:
```rust
// 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.

```rust
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:
```rust
newtype!(UserId, u32);

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

### Implemented traits

- For all:
  - [`Debug`](https://doc.rust-lang.org/std/fmt/trait.Debug.html)
  - [`Into<inner_type>`](https://doc.rust-lang.org/std/convert/trait.Into.html)
- For integers:
  - [`Clone`](https://doc.rust-lang.org/std/clone/trait.Clone.html)
  - [`Copy`](https://doc.rust-lang.org/std/marker/trait.Copy.html)
  - [`Hash`](https://doc.rust-lang.org/std/hash/trait.Hash.html)
  - [`PartialEq`](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html)
  - [`Eq`](https://doc.rust-lang.org/std/cmp/trait.Eq.html)
- For floating point numbers:
  - [`Clone`](https://doc.rust-lang.org/std/clone/trait.Clone.html)
  - [`Copy`](https://doc.rust-lang.org/std/marker/trait.Copy.html)
  - [`PartialEq`](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html)
- For `String`:
  - [`Clone`](https://doc.rust-lang.org/std/clone/trait.Clone.html)
  - [`Hash`](https://doc.rust-lang.org/std/hash/trait.Hash.html)
  - [`PartialEq`](https://doc.rust-lang.org/std/cmp/trait.PartialEq.html)
  - [`Eq`](https://doc.rust-lang.org/std/cmp/trait.Eq.html)

> **IMPORTANT:** The
> [`From`](https://doc.rust-lang.org/std/convert/trait.From.html),
> [`FromStr`](https://doc.rust-lang.org/std/str/trait.FromStr.html) and
> [`TryFrom`](https://doc.rust-lang.org/std/convert/trait.TryFrom.html) 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!`](#newtype_from-macro) macro to implement the `From` and
> `FromStr` traits for us.

## `newtype_ord!` Macro

The `newtype_ord!` macro extends the functionality provided with
[`newtype!`](#newtype-macro) by implementing the
[`PartialOrd`](https://doc.rust-lang.org/std/cmp/trait.PartialOrd.html) and
[`Ord`](https://doc.rust-lang.org/std/cmp/trait.Ord.html) traits
(when possible).

Example:
```rust
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!`](#newtype_ord-macro) by implementing the
[`Add`](https://doc.rust-lang.org/std/ops/trait.Add.html),
[`Sub`](https://doc.rust-lang.org/std/ops/trait.Sub.html),
[`AddAssign`](https://doc.rust-lang.org/std/ops/trait.AddAssign.html),
[`SubAssign`](https://doc.rust-lang.org/std/ops/trait.SubAssign.html), and
[`Default`](https://doc.rust-lang.org/std/default/trait.Default.html) traits.

Example:
```rust
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-macro), [`newtype_ord!`](#newtype_ord-macro), or
[`newtype_unit!`](#newtype_unit-macro)).

Example:
```rust
newtype!(Weight, f32);
newtype_unit!(Weight, f32);
```

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