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")] 84 extern crate std; 85 86 #[cfg_attr(test, macro_use)] 87 extern crate alloc; 88 89 #[cfg(feature = "serde")] 90 extern crate serde; 91 #[cfg(feature = "schemars")] 92 extern crate schemars; 93 94 pub use self::ipext::{IpAdd, IpSub, IpBitAnd, IpBitOr, IpAddrRange, Ipv4AddrRange, Ipv6AddrRange}; 95 pub use self::ipnet::{IpNet, Ipv4Net, Ipv6Net, PrefixLenError, IpSubnets, Ipv4Subnets, Ipv6Subnets}; 96 pub use self::parser::AddrParseError; 97 pub use self::mask::{ip_mask_to_prefix, ipv4_mask_to_prefix, ipv6_mask_to_prefix}; 98 99 mod ipext; 100 mod ipnet; 101 mod parser; 102 mod mask; 103 #[cfg(feature = "serde")] 104 mod ipnet_serde; 105 #[cfg(feature = "schemars")] 106 mod ipnet_schemars; 107