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};
27 /// let localhost_v4 = IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1));
41     V4(#[cfg_attr(staged_api, stable(feature = "ip_addr", since = "1.7.0"))] Ipv4Addr),
58 /// `Ipv4Addr` provides a [`FromStr`] implementation. The four octets are in decimal
69 /// use std::net::Ipv4Addr;
71 /// let localhost = Ipv4Addr::new(127, 0, 0, 1);
74 /// assert!("012.004.002.000".parse::<Ipv4Addr>().is_err()); // all octets are in octal
75 /// assert!("0000000.0.0.0".parse::<Ipv4Addr>().is_err()); // first octet is a zero in octal
76 /// assert!("0xcb.0x0.0x71.0x00".parse::<Ipv4Addr>().is_err()); // all octets are in hex
80 pub struct Ipv4Addr {
116 /// To convert from an IPv4 address to an IPv4-compatible IPv6 address, use [`Ipv4Addr::to_ipv6_compatible`].
134 /// To convert from an IPv4 address to an IPv4-mapped IPv6 address, use [`Ipv4Addr::to_ipv6_mapped`].
224     /// See the documentation for [`Ipv4Addr::is_unspecified()`] and
230     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
232     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(0, 0, 0, 0)).is_unspecified(), true);
251     /// See the documentation for [`Ipv4Addr::is_loopback()`] and
257     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
259     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)).is_loopback(), true);
278     /// See the documentation for [`Ipv4Addr::is_global()`] and
286     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
288     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(80, 9, 12, 3)).is_global(), true);
307     /// See the documentation for [`Ipv4Addr::is_multicast()`] and
313     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
315     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(224, 254, 0, 0)).is_multicast(), true);
334     /// See the documentation for [`Ipv4Addr::is_documentation()`] and
342     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
344     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 6)).is_documentation(), true);
366     /// See the documentation for [`Ipv4Addr::is_benchmarking()`] and
374     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
376     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(198, 19, 255, 255)).is_benchmarking(), true);
397     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
399     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 6)).is_ipv4(), true);
421     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
423     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(203, 0, 113, 6)).is_ipv6(), false);
444     /// use std::net::{IpAddr, Ipv4Addr, Ipv6Addr};
446     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1)).to_canonical().is_loopback(), true);
466 impl Ipv4Addr {
474     /// use std::net::Ipv4Addr;
476     /// let addr = Ipv4Addr::new(127, 0, 0, 1);
485     pub const fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr {
486         Ipv4Addr {
496     /// use std::net::Ipv4Addr;
498     /// let addr = Ipv4Addr::LOCALHOST;
499     /// assert_eq!(addr, Ipv4Addr::new(127, 0, 0, 1));
502     pub const LOCALHOST: Self = Ipv4Addr::new(127, 0, 0, 1);
511     /// use std::net::Ipv4Addr;
513     /// let addr = Ipv4Addr::UNSPECIFIED;
514     /// assert_eq!(addr, Ipv4Addr::new(0, 0, 0, 0));
518     pub const UNSPECIFIED: Self = Ipv4Addr::new(0, 0, 0, 0);
525     /// use std::net::Ipv4Addr;
527     /// let addr = Ipv4Addr::BROADCAST;
528     /// assert_eq!(addr, Ipv4Addr::new(255, 255, 255, 255));
531     pub const BROADCAST: Self = Ipv4Addr::new(255, 255, 255, 255);
538     /// use std::net::Ipv4Addr;
540     /// let addr = Ipv4Addr::new(127, 0, 0, 1);
564     /// use std::net::Ipv4Addr;
566     /// assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_unspecified(), true);
567     /// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_unspecified(), false);
589     /// use std::net::Ipv4Addr;
591     /// assert_eq!(Ipv4Addr::new(127, 0, 0, 1).is_loopback(), true);
592     /// assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_loopback(), false);
618     /// use std::net::Ipv4Addr;
620     /// assert_eq!(Ipv4Addr::new(10, 0, 0, 1).is_private(), true);
621     /// assert_eq!(Ipv4Addr::new(10, 10, 10, 10).is_private(), true);
622     /// assert_eq!(Ipv4Addr::new(172, 16, 10, 10).is_private(), true);
623     /// assert_eq!(Ipv4Addr::new(172, 29, 45, 14).is_private(), true);
624     /// assert_eq!(Ipv4Addr::new(172, 32, 0, 2).is_private(), false);
625     /// assert_eq!(Ipv4Addr::new(192, 168, 0, 2).is_private(), true);
626     /// assert_eq!(Ipv4Addr::new(192, 169, 0, 2).is_private(), false);
653     /// use std::net::Ipv4Addr;
655     /// assert_eq!(Ipv4Addr::new(169, 254, 0, 0).is_link_local(), true);
656     /// assert_eq!(Ipv4Addr::new(169, 254, 10, 65).is_link_local(), true);
657     /// assert_eq!(Ipv4Addr::new(16, 89, 10, 65).is_link_local(), false);
679     /// - The [unspecified address] ([`is_unspecified`](Ipv4Addr::is_unspecified))
680     /// - Addresses reserved for private use ([`is_private`](Ipv4Addr::is_private))
681     /// - Addresses in the shared address space ([`is_shared`](Ipv4Addr::is_shared))
682     /// - Loopback addresses ([`is_loopback`](Ipv4Addr::is_loopback))
683     /// - Link-local addresses ([`is_link_local`](Ipv4Addr::is_link_local))
684     /// - Addresses reserved for documentation ([`is_documentation`](Ipv4Addr::is_documentation))
685     /// - Addresses reserved for benchmarking ([`is_benchmarking`](Ipv4Addr::is_benchmarking))
686     /// - Reserved addresses ([`is_reserved`](Ipv4Addr::is_reserved))
687     /// - The [broadcast address] ([`is_broadcast`](Ipv4Addr::is_broadcast))
692     /// [unspecified address]: Ipv4Addr::UNSPECIFIED
693     /// [broadcast address]: Ipv4Addr::BROADCAST
701     /// use std::net::Ipv4Addr;
704     /// assert_eq!(Ipv4Addr::new(80, 9, 12, 3).is_global(), true);
710     /// assert_eq!(Ipv4Addr::UNSPECIFIED.is_global(), false);
713     /// assert_eq!(Ipv4Addr::new(10, 254, 0, 0).is_global(), false);
714     /// assert_eq!(Ipv4Addr::new(192, 168, 10, 65).is_global(), false);
715     /// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_global(), false);
718     /// assert_eq!(Ipv4Addr::new(100, 100, 0, 0).is_global(), false);
721     /// assert_eq!(Ipv4Addr::LOCALHOST.is_global(), false);
724     /// assert_eq!(Ipv4Addr::new(169, 254, 45, 1).is_global(), false);
727     /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_global(), false);
728     /// assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_global(), false);
729     /// assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_global(), false);
732     /// assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_global(), false);
735     /// assert_eq!(Ipv4Addr::new(250, 10, 20, 30).is_global(), false);
738     /// assert_eq!(Ipv4Addr::BROADCAST.is_global(), false);
772     /// use std::net::Ipv4Addr;
774     /// assert_eq!(Ipv4Addr::new(100, 64, 0, 0).is_shared(), true);
775     /// assert_eq!(Ipv4Addr::new(100, 127, 255, 255).is_shared(), true);
776     /// assert_eq!(Ipv4Addr::new(100, 128, 0, 0).is_shared(), false);
800     /// use std::net::Ipv4Addr;
802     /// assert_eq!(Ipv4Addr::new(198, 17, 255, 255).is_benchmarking(), false);
803     /// assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_benchmarking(), true);
804     /// assert_eq!(Ipv4Addr::new(198, 19, 255, 255).is_benchmarking(), true);
805     /// assert_eq!(Ipv4Addr::new(198, 20, 0, 0).is_benchmarking(), false);
836     /// use std::net::Ipv4Addr;
838     /// assert_eq!(Ipv4Addr::new(240, 0, 0, 0).is_reserved(), true);
839     /// assert_eq!(Ipv4Addr::new(255, 255, 255, 254).is_reserved(), true);
841     /// assert_eq!(Ipv4Addr::new(239, 255, 255, 255).is_reserved(), false);
843     /// assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_reserved(), false);
866     /// use std::net::Ipv4Addr;
868     /// assert_eq!(Ipv4Addr::new(224, 254, 0, 0).is_multicast(), true);
869     /// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_multicast(), true);
870     /// assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_multicast(), false);
892     /// use std::net::Ipv4Addr;
894     /// assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_broadcast(), true);
895     /// assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_broadcast(), false);
921     /// use std::net::Ipv4Addr;
923     /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_documentation(), true);
924     /// assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_documentation(), true);
925     /// assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_documentation(), true);
926     /// assert_eq!(Ipv4Addr::new(193, 34, 17, 19).is_documentation(), false);
955     /// use std::net::{Ipv4Addr, Ipv6Addr};
958     ///     Ipv4Addr::new(192, 0, 2, 255).to_ipv6_compatible(),
987     /// use std::net::{Ipv4Addr, Ipv6Addr};
989     /// assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped(),
1009 impl From<Ipv4Addr> for IpAddr {
1015     /// use std::net::{IpAddr, Ipv4Addr};
1017     /// let addr = Ipv4Addr::new(127, 0, 0, 1);
1025     fn from(ipv4: Ipv4Addr) -> IpAddr {
1053 impl PartialEq<Ipv4Addr> for IpAddr {
1055     fn eq(&self, other: &Ipv4Addr) -> bool {
1064 impl PartialEq<IpAddr> for Ipv4Addr {
1075 impl PartialOrd for Ipv4Addr {
1077     fn partial_cmp(&self, other: &Ipv4Addr) -> Option<Ordering> {
1083 impl PartialOrd<Ipv4Addr> for IpAddr {
1085     fn partial_cmp(&self, other: &Ipv4Addr) -> Option<Ordering> {
1094 impl PartialOrd<IpAddr> for Ipv4Addr {
1105 impl Ord for Ipv4Addr {
1107     fn cmp(&self, other: &Ipv4Addr) -> Ordering {
1113 impl From<Ipv4Addr> for u32 {
1114     /// Converts an `Ipv4Addr` into a host byte order `u32`.
1119     /// use std::net::Ipv4Addr;
1121     /// let addr = Ipv4Addr::new(0x12, 0x34, 0x56, 0x78);
1125     fn from(ip: Ipv4Addr) -> u32 {
1131 impl From<u32> for Ipv4Addr {
1132     /// Converts a host byte order `u32` into an `Ipv4Addr`.
1137     /// use std::net::Ipv4Addr;
1139     /// let addr = Ipv4Addr::from(0x12345678);
1140     /// assert_eq!(Ipv4Addr::new(0x12, 0x34, 0x56, 0x78), addr);
1143     fn from(ip: u32) -> Ipv4Addr {
1144         Ipv4Addr {
1151 impl From<[u8; 4]> for Ipv4Addr {
1152     /// Creates an `Ipv4Addr` from a four element byte array.
1157     /// use std::net::Ipv4Addr;
1159     /// let addr = Ipv4Addr::from([13u8, 12u8, 11u8, 10u8]);
1160     /// assert_eq!(Ipv4Addr::new(13, 12, 11, 10), addr);
1163     fn from(octets: [u8; 4]) -> Ipv4Addr {
1164         Ipv4Addr { octets }
1175     /// use std::net::{IpAddr, Ipv4Addr};
1178     /// assert_eq!(IpAddr::V4(Ipv4Addr::new(13, 12, 11, 10)), addr);
1182         IpAddr::V4(Ipv4Addr::from(octets))
1716     /// [`IPv4` address]: Ipv4Addr
1723     /// use std::net::{Ipv4Addr, Ipv6Addr};
1727     ///            Some(Ipv4Addr::new(192, 10, 2, 255)));
1738     pub const fn to_ipv4_mapped(&self) -> Option<Ipv4Addr> {
1741                 Some(Ipv4Addr::new(a, b, c, d))
1758     /// [`IPv4` address]: Ipv4Addr
1767     /// use std::net::{Ipv4Addr, Ipv6Addr};
1771     ///            Some(Ipv4Addr::new(192, 10, 2, 255)));
1773     ///            Some(Ipv4Addr::new(0, 0, 0, 1)));
1783     pub const fn to_ipv4(&self) -> Option<Ipv4Addr> {
1787             Some(Ipv4Addr::new(a, b, c, d))

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