xref: /third_party/rust/crates/rustix/src/net/ip.rs

7 //! This defines `IpAddr`, `Ipv4Addr`, and `Ipv6Addr`. Ideally, these should be
19 /// This enum can contain either an [`Ipv4Addr`] or an [`Ipv6Addr`], see their
25 /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
28 /// let localhost_v6 = IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
44     V6(#[cfg_attr(staged_api, stable(feature = "ip_addr", since = "1.7.0"))] Ipv6Addr),
117 /// Use [`Ipv6Addr::to_ipv4`] to convert an IPv4-compatible IPv6 address to the canonical IPv4 address.
135 /// Use [`Ipv6Addr::to_ipv4`] to convert an IPv4-mapped IPv6 address to the canonical IPv4 address.
137 /// [`Ipv6Addr::to_ipv4_mapped`] to avoid this.
143 /// `Ipv6Addr` provides a [`FromStr`] implementation. There are many ways to represent
154 /// use std::net::Ipv6Addr;
156 /// let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
162 pub struct Ipv6Addr {
178 /// use std::net::Ipv6Addr;
182 /// let address = Ipv6Addr::new(0xff0e, 0, 0, 0, 0, 0, 0, 0);
199 /// [IPv6 multicast address]: Ipv6Addr
225     /// [`Ipv6Addr::is_unspecified()`] for more details.
230     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
233     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0)).is_unspecified(), true);
252     /// [`Ipv6Addr::is_loopback()`] for more details.
257     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
260     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1)).is_loopback(), true);
279     /// [`Ipv6Addr::is_global()`] for more details.
286     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
289     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0x1c9, 0, 0, 0xafc8, 0, 0x1)).is_global(), true);
308     /// [`Ipv6Addr::is_multicast()`] for more details.
313     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
316     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0)).is_multicast(), true);
335     /// [`Ipv6Addr::is_documentation()`] for more details.
342     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
346     ///     IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0)).is_documentation(),
367     /// [`Ipv6Addr::is_benchmarking()`] for more details.
374     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
377     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0x2001, 0x2, 0, 0, 0, 0, 0, 0)).is_benchmarking(), true);
397     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
400     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0)).is_ipv4(), false);
421     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
424     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0)).is_ipv6(), true);
444     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
447     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1)).is_loopback(), false);
448     /// assert_eq!(IpAddr::V6(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1)).to_canonical().is_loopback(), true);
949     /// [IPv4-compatible]: Ipv6Addr#ipv4-compatible-ipv6-addresses
950     /// [`IPv6` address]: Ipv6Addr
955     /// use std::net::{Ipv4Addr, Ipv6Addr};
959     ///     Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc000, 0x2ff)
970     pub const fn to_ipv6_compatible(&self) -> Ipv6Addr {
972         Ipv6Addr {
981     /// [IPv4-mapped]: Ipv6Addr#ipv4-mapped-ipv6-addresses
982     /// [`IPv6` address]: Ipv6Addr
987     /// use std::net::{Ipv4Addr, Ipv6Addr};
990     ///            Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x2ff));
1000     pub const fn to_ipv6_mapped(&self) -> Ipv6Addr {
1002         Ipv6Addr {
1031 impl From<Ipv6Addr> for IpAddr {
1037     /// use std::net::{IpAddr, Ipv6Addr};
1039     /// let addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff);
1047     fn from(ipv6: Ipv6Addr) -> IpAddr {
1186 impl Ipv6Addr {
1194     /// use std::net::Ipv6Addr;
1196     /// let addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff);
1205     pub const fn new(a: u16, b: u16, c: u16, d: u16, e: u16, f: u16, g: u16, h: u16) -> Ipv6Addr {
1216         Ipv6Addr {
1228     /// use std::net::Ipv6Addr;
1230     /// let addr = Ipv6Addr::LOCALHOST;
1231     /// assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
1234     pub const LOCALHOST: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
1241     /// use std::net::Ipv6Addr;
1243     /// let addr = Ipv6Addr::UNSPECIFIED;
1244     /// assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0));
1247     pub const UNSPECIFIED: Self = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0);
1254     /// use std::net::Ipv6Addr;
1256     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).segments(),
1292     /// use std::net::Ipv6Addr;
1294     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unspecified(), false);
1295     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0).is_unspecified(), true);
1305         u128::from_be_bytes(self.octets()) == u128::from_be_bytes(Ipv6Addr::UNSPECIFIED.octets())
1313     /// [loopback address]: Ipv6Addr::LOCALHOST
1319     /// use std::net::Ipv6Addr;
1321     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_loopback(), false);
1322     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1).is_loopback(), true);
1332         u128::from_be_bytes(self.octets()) == u128::from_be_bytes(Ipv6Addr::LOCALHOST.octets())
1343     /// - The [unspecified address] ([`is_unspecified`](Ipv6Addr::is_unspecified))
1344     /// - The [loopback address] ([`is_loopback`](Ipv6Addr::is_loopback))
1347     /// - Addresses reserved for documentation ([`is_documentation`](Ipv6Addr::is_documentation))
1348     /// - Unique local addresses ([`is_unique_local`](Ipv6Addr::is_unique_local))
1349     /// - Unicast addresses with link-local scope ([`is_unicast_link_local`](Ipv6Addr::is_unicast_link_local))
1360     /// [unspecified address]: Ipv6Addr::UNSPECIFIED
1361     /// [loopback address]: Ipv6Addr::LOCALHOST
1368     /// use std::net::Ipv6Addr;
1371     /// assert_eq!(Ipv6Addr::new(0x26, 0, 0x1c9, 0, 0, 0xafc8, 0x10, 0x1).is_global(), true);
1377     /// assert_eq!(Ipv6Addr::UNSPECIFIED.is_global(), false);
1380     /// assert_eq!(Ipv6Addr::LOCALHOST.is_global(), false);
1383     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_global(), false);
1386     /// assert_eq!(Ipv6Addr::new(0x2001, 2, 0, 0, 0, 0, 0, 1,).is_global(), false);
1389     /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1).is_global(), false);
1392     /// assert_eq!(Ipv6Addr::new(0xfc02, 0, 0, 0, 0, 0, 0, 1).is_global(), false);
1395     /// assert_eq!(Ipv6Addr::new(0xfe81, 0, 0, 0, 0, 0, 0, 1).is_global(), false);
1445     /// use std::net::Ipv6Addr;
1447     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unique_local(), false);
1448     /// assert_eq!(Ipv6Addr::new(0xfc02, 0, 0, 0, 0, 0, 0, 0).is_unique_local(), true);
1465     /// [multicast address]: Ipv6Addr::is_multicast
1472     /// use std::net::Ipv6Addr;
1475     /// assert_eq!(Ipv6Addr::UNSPECIFIED.is_unicast(), true);
1476     /// assert_eq!(Ipv6Addr::LOCALHOST.is_unicast(), true);
1479     /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast(), true);
1480     /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).is_unicast(), false);
1517     /// [loopback address]: Ipv6Addr::LOCALHOST
1524     /// use std::net::Ipv6Addr;
1527     /// assert_eq!(Ipv6Addr::LOCALHOST.is_unicast_link_local(), false);
1530     /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), false);
1531     /// assert_eq!(Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), true);
1534     /// assert_eq!(Ipv6Addr::new(0xfe80, 0, 0, 1, 0, 0, 0, 0).is_unicast_link_local(), true);
1535     /// assert_eq!(Ipv6Addr::new(0xfe81, 0, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), true);
1560     /// use std::net::Ipv6Addr;
1562     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_documentation(), false);
1563     /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_documentation(), true);
1587     /// use std::net::Ipv6Addr;
1589     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc613, 0x0).is_benchmarking(), false);
1590     /// assert_eq!(Ipv6Addr::new(0x2001, 0x2, 0, 0, 0, 0, 0, 0).is_benchmarking(), true);
1624     /// use std::net::Ipv6Addr;
1626     /// assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast_global(), false);
1627     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unicast_global(), true);
1653     /// use std::net::{Ipv6Addr, Ipv6MulticastScope};
1656     ///     Ipv6Addr::new(0xff0e, 0, 0, 0, 0, 0, 0, 0).multicast_scope(),
1659     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).multicast_scope(), None);
1694     /// use std::net::Ipv6Addr;
1696     /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).is_multicast(), true);
1697     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_multicast(), false);
1717     /// [IPv4-mapped]: Ipv6Addr
1723     /// use std::net::{Ipv4Addr, Ipv6Addr};
1725     /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4_mapped(), None);
1726     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4_mapped(),
1728     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4_mapped(), None);
1753     /// [`Ipv6Addr::to_ipv4_mapped`] to avoid this.
1759     /// [IPv4-compatible]: Ipv6Addr#ipv4-compatible-ipv6-addresses
1760     /// [IPv4-mapped]: Ipv6Addr#ipv4-mapped-ipv6-addresses
1767     /// use std::net::{Ipv4Addr, Ipv6Addr};
1769     /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4(), None);
1770     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4(),
1772     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4(),
1800     /// use std::net::Ipv6Addr;
1802     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1).is_loopback(), false);
1803     /// assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1).to_canonical().is_loopback(), true);
1823     /// use std::net::Ipv6Addr;
1825     /// assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).octets(),
1841 impl PartialEq<IpAddr> for Ipv6Addr {
1852 impl PartialEq<Ipv6Addr> for IpAddr {
1854     fn eq(&self, other: &Ipv6Addr) -> bool {
1863 impl PartialOrd for Ipv6Addr {
1865     fn partial_cmp(&self, other: &Ipv6Addr) -> Option<Ordering> {
1871 impl PartialOrd<Ipv6Addr> for IpAddr {
1873     fn partial_cmp(&self, other: &Ipv6Addr) -> Option<Ordering> {
1882 impl PartialOrd<IpAddr> for Ipv6Addr {
1893 impl Ord for Ipv6Addr {
1895     fn cmp(&self, other: &Ipv6Addr) -> Ordering {
1901 impl From<Ipv6Addr> for u128 {
1902     /// Convert an `Ipv6Addr` into a host byte order `u128`.
1907     /// use std::net::Ipv6Addr;
1909     /// let addr = Ipv6Addr::new(
1916     fn from(ip: Ipv6Addr) -> u128 {
1921 impl From<u128> for Ipv6Addr {
1922     /// Convert a host byte order `u128` into an `Ipv6Addr`.
1927     /// use std::net::Ipv6Addr;
1929     /// let addr = Ipv6Addr::from(0x102030405060708090A0B0C0D0E0F00D_u128);
1931     ///     Ipv6Addr::new(
1938     fn from(ip: u128) -> Ipv6Addr {
1939         Ipv6Addr::from(ip.to_be_bytes())
1944 impl From<[u8; 16]> for Ipv6Addr {
1945     /// Creates an `Ipv6Addr` from a sixteen element byte array.
1950     /// use std::net::Ipv6Addr;
1952     /// let addr = Ipv6Addr::from([
1957     ///     Ipv6Addr::new(
1967     fn from(octets: [u8; 16]) -> Ipv6Addr {
1968         Ipv6Addr { octets }
1973 impl From<[u16; 8]> for Ipv6Addr {
1974     /// Creates an `Ipv6Addr` from an eight element 16-bit array.
1979     /// use std::net::Ipv6Addr;
1981     /// let addr = Ipv6Addr::from([
1986     ///     Ipv6Addr::new(
1996     fn from(segments: [u16; 8]) -> Ipv6Addr {
1998         Ipv6Addr::new(a, b, c, d, e, f, g, h)
2009     /// use std::net::{IpAddr, Ipv6Addr};
2016     ///     IpAddr::V6(Ipv6Addr::new(
2027         IpAddr::V6(Ipv6Addr::from(octets))
2038     /// use std::net::{IpAddr, Ipv6Addr};
2045     ///     IpAddr::V6(Ipv6Addr::new(
2056         IpAddr::V6(Ipv6Addr::from(segments))

Indexes created Thu Nov 07 10:32:03 CST 2024