netip 0.3.0

IPv4/IPv6 network types with non-contiguous masks support
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
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149

# netip

[![crates.io](https://img.shields.io/crates/v/netip.svg)](https://crates.io/crates/netip)
[![docs.rs](https://docs.rs/netip/badge.svg)](https://docs.rs/netip)
[![License](https://img.shields.io/crates/l/netip.svg)](LICENSE)

**Zero-dependency** Rust library for IPv4/IPv6 networks and MAC addresses — with first-class support for **non-contiguous subnet masks**.

## Why netip?

Most networking libraries assume subnet masks are contiguous (a run of 1-bits followed by 0-bits, like `255.255.255.0`). Real-world network hardware — routers, firewalls, packet classifiers — often uses **non-contiguous masks** like `255.0.255.0` or even `170.85.170.85` to match on arbitrary bit patterns.

`netip` treats every network as a `(address, mask)` pair where the mask can be *any* bit pattern. All operations — containment, intersection, difference, iteration — work correctly with non-contiguous masks.

If your masks happen to be contiguous, the `Contiguous<T>` wrapper gives you a compile-time guarantee and CIDR prefix access.

### Key features

- **Non-contiguous mask support** — the only open-source Rust library that handles arbitrary subnet masks
- **Full set algebra** — `contains`, `intersection`, `difference`, `merge`, `is_adjacent` on networks as sets of addresses
- **Correct iteration** — iterate over addresses in a non-contiguous network in host-index order
- **Zero dependencies** — only `core`, nothing else
- **Performance-first** — `const fn` where possible, `#[inline]` on hot paths, minimal instruction count
- **Type-safe** — `Contiguous<T>` enforces contiguous masks at parse time; mismatched IPv4/IPv6 operations are compile errors

## Quick start

Add to your `Cargo.toml`:

```toml
[dependencies]
netip = "0.3"
```

### Parsing and basic operations

```rust
use netip::{Ipv4Network, IpNetwork};

// Standard CIDR notation.
let net: Ipv4Network = Ipv4Network::parse("10.0.0.0/8").unwrap();
assert_eq!(net.prefix(), Some(8));

// Dotted-mask notation — including non-contiguous masks.
let net = Ipv4Network::parse("192.168.0.0/255.0.255.0").unwrap();
assert!(!net.is_contiguous());

// IpNetwork parses both IPv4 and IPv6.
let net: IpNetwork = IpNetwork::parse("2001:db8::/32").unwrap();
```

### Set operations on networks

Networks are sets of addresses. `netip` gives you the algebra:

```rust
use netip::Ipv4Network;

let a = Ipv4Network::parse("10.0.0.0/255.0.0.0").unwrap();
let b = Ipv4Network::parse("10.1.0.0/255.255.0.0").unwrap();

// Containment: is every address in b also in a?
assert!(a.contains(&b));

// Intersection: the set of addresses in both networks.
let ab = a.intersection(&b).unwrap();
assert_eq!(ab, b);

// Difference: addresses in a but not in b — returns an iterator of networks.
for net in a.difference(&b) {
    println!("{net}"); // each chunk of the remaining address space
}
```

### Non-contiguous masks in action

This is where `netip` shines. Non-contiguous masks let you express bit-pattern matching that CIDR cannot:

```rust
use netip::Ipv4Network;

// Match all addresses where the first and third octets are 10 and 0.
// Second and fourth octets can be anything.
let pattern = Ipv4Network::parse("10.0.0.0/255.0.255.0").unwrap();
let specific = Ipv4Network::parse("10.42.0.99/255.255.255.255").unwrap();
assert!(pattern.contains(&specific)); // 10.42.0.99 matches 10.*.0.*

// Intersection of two non-contiguous networks — always a single network.
let a = Ipv4Network::parse("10.0.0.0/255.0.255.0").unwrap();
let b = Ipv4Network::parse("10.0.5.0/255.255.0.255").unwrap();
let ab = a.intersection(&b).unwrap();
assert_eq!(ab.to_string(), "10.0.5.0/255.255.255.255");

// Iterate over all addresses in a non-contiguous network.
let small = Ipv4Network::parse("192.168.0.0/255.255.255.252").unwrap();
let addrs: Vec<_> = small.addrs().collect();
assert_eq!(addrs.len(), 4);
```

### Contiguous wrapper

When you need the CIDR guarantee, `Contiguous<T>` enforces it at parse time:

```rust
use netip::Contiguous;
use netip::Ipv4Network;

let net: Contiguous<Ipv4Network> = Contiguous::parse("10.0.0.0/8").unwrap();
assert_eq!(net.prefix(), 8); // guaranteed to succeed — no Option

// Non-contiguous mask is rejected at parse time.
assert!(Contiguous::<Ipv4Network>::parse("10.0.0.0/255.0.255.0").is_err());

// Contiguous<T> derefs to T — all network methods are available.
assert!(net.contains(&Ipv4Network::parse("10.1.2.3/32").unwrap()));
```

### MAC addresses

```rust
use netip::MacAddr;

let mac = MacAddr::parse("aa:bb:cc:dd:ee:ff").unwrap();
assert_eq!(mac.to_string(), "aa:bb:cc:dd:ee:ff");
```

## Types

| Type | Description |
|------|-------------|
| `Ipv4Network` | IPv4 network — `(address, mask)` pair, arbitrary masks |
| `Ipv6Network` | IPv6 network — `(address, mask)` pair, arbitrary masks |
| `IpNetwork` | Enum over `Ipv4Network` / `Ipv6Network` |
| `Contiguous<T>` | Newtype that enforces contiguous masks at parse time |
| `MacAddr` | MAC address (EUI-48), stored as lower 48 bits of `u64` |

## Roadmap

`netip` is on the path to a stable 1.0. Current version: **0.3.0**.

- ~~**v0.3** — API cleanup: `#[must_use]`, `#[deny(missing_docs)]`~~ ✓
- **v0.4** — Complete set algebra: `complement`, `Contiguous<T>` merge/adjacent
- **v0.5** — Testing hardening: fuzz targets, exhaustive non-contiguous edge cases
- **v0.6+** — Documentation polish, API review, CHANGELOG
- **v1.0** — Stable release

## License

Apache-2.0