1#![doc(html_root_url = "https://docs.rs/ipnet/2.11.0")]
2//! Types for IPv4 and IPv6 network addresses.
3//!
4//! This module provides types and useful methods for working with IPv4
5//! and IPv6 network addresses, commonly called IP prefixes. The new
6//! [`IpNet`], [`Ipv4Net`], and [`Ipv6Net`] types build on the existing
7//! [`IpAddr`], [`Ipv4Addr`], and [`Ipv6Addr`] types already provided in
8//! Rust's standard library and align to their design to stay
9//! consistent.
10//!
11//! The module also provides the [`IpSubnets`], [`Ipv4Subnets`], and
12//! [`Ipv6Subnets`] types for iterating over the subnets contained in
13//! an IP address range. The [`IpAddrRange`], [`Ipv4AddrRange`], and
14//! [`Ipv6AddrRange`] types for iterating over IP addresses in a range.
15//! And traits that extend `Ipv4Addr` and `Ipv6Addr` with methods for
16//! addition, subtraction, bitwise-and, and bitwise-or operations that
17//! are missing in Rust's standard library.
18//!
19//! The module only uses stable features so it is guaranteed to compile
20//! using the stable toolchain.
21//!
22//! # Organization
23//!
24//! * [`IpNet`] represents an IP network address, either IPv4 or IPv6.
25//! * [`Ipv4Net`] and [`Ipv6Net`] are respectively IPv4 and IPv6 network
26//! addresses.
27//! * [`IpSubnets`], [`Ipv4Subnets`], and [`Ipv6Subnets`] are iterators
28//! that generate the smallest set of IP network addresses bound by an
29//! IP address range and minimum prefix length. These can be created
30//! using their constructors. They are also returned by the
31//! [`subnets()`] methods and used within the [`aggregate()`] methods.
32//! * [`IpAddrRange`], [`Ipv4AddrRange`], and [`Ipv6AddrRange`] are
33//! iterators that generate IP addresses. These can be created using
34//! their constructors. They are also returned by the [`hosts()`]
35//! methods.
36//! * The [`IpAdd`], [`IpSub`], [`IpBitAnd`], [`IpBitOr`] traits extend
37//! the [`Ipv4Addr`] and [`Ipv6Addr`] types with methods to perform
38//! these operations.
39//!
40//! [`IpNet`]: enum.IpNet.html
41//! [`Ipv4Net`]: struct.Ipv4Net.html
42//! [`Ipv6Net`]: struct.Ipv6Net.html
43//! [`IpAddr`]: https://doc.rust-lang.org/std/net/enum.IpAddr.html
44//! [`Ipv4Addr`]: https://doc.rust-lang.org/std/net/struct.Ipv4Addr.html
45//! [`Ipv6Addr`]: https://doc.rust-lang.org/std/net/struct.Ipv6Addr.html
46//! [`IpSubnets`]: enum.IpSubnets.html
47//! [`Ipv4Subnets`]: struct.Ipv4Subnets.html
48//! [`Ipv6Subnets`]: struct.Ipv6Subnets.html
49//! [`subnets()`]: enum.IpNet.html#method.subnets
50//! [`aggregate()`]: enum.IpNet.html#method.aggregate
51//! [`IpAddrRange`]: enum.IpAddrRange.html
52//! [`Ipv4AddrRange`]: struct.Ipv4AddrRange.html
53//! [`Ipv6AddrRange`]: struct.Ipv6AddrRange.html
54//! [`hosts()`]: enum.IpNet.html#method.hosts
55//! [`IpAdd`]: trait.IpAdd.html
56//! [`IpSub`]: trait.IpSub.html
57//! [`IpBitAnd`]: trait.IpBitAnd.html
58//! [`IpBitOr`]: trait.IpBitOr.html
59//!
60//! # Serde support
61//!
62//! This library comes with support for [serde](https://serde.rs) but
63//! it's not enabled by default. Use the `serde` [feature] to enable.
64//!
65//! ```toml
66//! [dependencies]
67//! ipnet = { version = "2", features = ["serde"] }
68//! ```
69//!
70//! For human readable formats (e.g. JSON) the `IpNet`, `Ipv4Net`, and
71//! `Ipv6Net` types will serialize to their `Display` strings.
72//!
73//! For compact binary formats (e.g. Bincode) the `Ipv4Net` and
74//! `Ipv6Net` types will serialize to a string of 5 and 17 bytes that
75//! consist of the network address octects followed by the prefix
76//! length. The `IpNet` type will serialize to an Enum with the V4 or V6
77//! variant index prepending the above string of 5 or 17 bytes.
78//!
79//! [feature]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-features-section
80
81#![no_std]
82
83#[cfg(feature = "std")]
84extern crate std;
85
86#[cfg_attr(test, macro_use)]
87extern crate alloc;
88
89#[cfg(feature = "serde")]
90extern crate serde;
91#[cfg(feature = "schemars")]
92extern crate schemars;
93
94pub use self::ipext::{IpAdd, IpSub, IpBitAnd, IpBitOr, IpAddrRange, Ipv4AddrRange, Ipv6AddrRange};
95pub use self::ipnet::{IpNet, Ipv4Net, Ipv6Net, PrefixLenError, IpSubnets, Ipv4Subnets, Ipv6Subnets};
96pub use self::parser::AddrParseError;
97pub use self::mask::{ip_mask_to_prefix, ipv4_mask_to_prefix, ipv6_mask_to_prefix};
98
99mod ipext;
100mod ipnet;
101mod parser;
102mod mask;
103#[cfg(feature = "serde")]
104mod ipnet_serde;
105#[cfg(feature = "schemars")]
106mod ipnet_schemars;
107