pub struct Ipv4Addr { /* private fields */ }
Expand description
An IPv4 address.
IPv4 addresses are defined as 32-bit integers in IETF RFC 791. They are usually represented as four octets.
See IpAddr
for a type encompassing both IPv4 and IPv6 addresses.
§Textual representation
Ipv4Addr
provides a FromStr
implementation. The four octets are in decimal
notation, divided by .
(this is called “dot-decimal notation”).
Notably, octal numbers (which are indicated with a leading 0
) and hexadecimal numbers (which
are indicated with a leading 0x
) are not allowed per IETF RFC 6943.
§Examples
use std::net::Ipv4Addr;
let localhost = Ipv4Addr::new(127, 0, 0, 1);
assert_eq!("127.0.0.1".parse(), Ok(localhost));
assert_eq!(localhost.is_loopback(), true);
assert!("012.004.002.000".parse::<Ipv4Addr>().is_err()); // all octets are in octal
assert!("0000000.0.0.0".parse::<Ipv4Addr>().is_err()); // first octet is a zero in octal
assert!("0xcb.0x0.0x71.0x00".parse::<Ipv4Addr>().is_err()); // all octets are in hex
Implementations§
source§impl Ipv4Addr
impl Ipv4Addr
1.30.0 · sourcepub const LOCALHOST: Self = _
pub const LOCALHOST: Self = _
An IPv4 address with the address pointing to localhost: 127.0.0.1
§Examples
1.30.0 · sourcepub const UNSPECIFIED: Self = _
pub const UNSPECIFIED: Self = _
An IPv4 address representing an unspecified address: 0.0.0.0
This corresponds to the constant INADDR_ANY
in other languages.
§Examples
1.30.0 · sourcepub const BROADCAST: Self = _
pub const BROADCAST: Self = _
An IPv4 address representing the broadcast address: 255.255.255.255
.
§Examples
1.0.0 (const: 1.32.0) · sourcepub const fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr
pub const fn new(a: u8, b: u8, c: u8, d: u8) -> Ipv4Addr
Creates a new IPv4 address from four eight-bit octets.
The result will represent the IP address a
.b
.c
.d
.
§Examples
1.80.0 (const: 1.80.0) · sourcepub const fn to_bits(self) -> u32
pub const fn to_bits(self) -> u32
Converts an IPv4 address into a u32
representation using native byte order.
Although IPv4 addresses are big-endian, the u32
value will use the target platform’s
native byte order. That is, the u32
value is an integer representation of the IPv4
address and not an integer interpretation of the IPv4 address’s big-endian bitstring. This
means that the u32
value masked with 0xffffff00
will set the last octet in the address
to 0, regardless of the target platform’s endianness.
§Examples
1.80.0 (const: 1.80.0) · sourcepub const fn from_bits(bits: u32) -> Ipv4Addr
pub const fn from_bits(bits: u32) -> Ipv4Addr
Converts a native byte order u32
into an IPv4 address.
See Ipv4Addr::to_bits
for an explanation on endianness.
§Examples
1.0.0 (const: 1.50.0) · sourcepub const fn octets(&self) -> [u8; 4]
pub const fn octets(&self) -> [u8; 4]
Returns the four eight-bit integers that make up this address.
§Examples
sourcepub const fn from_octets(octets: [u8; 4]) -> Ipv4Addr
🔬This is a nightly-only experimental API. (ip_from
#131360)
pub const fn from_octets(octets: [u8; 4]) -> Ipv4Addr
ip_from
#131360)Creates an Ipv4Addr
from a four element byte array.
§Examples
1.12.0 (const: 1.32.0) · sourcepub const fn is_unspecified(&self) -> bool
pub const fn is_unspecified(&self) -> bool
1.7.0 (const: 1.50.0) · sourcepub const fn is_loopback(&self) -> bool
pub const fn is_loopback(&self) -> bool
Returns true
if this is a loopback address (127.0.0.0/8
).
This property is defined by IETF RFC 1122.
§Examples
1.7.0 (const: 1.50.0) · sourcepub const fn is_private(&self) -> bool
pub const fn is_private(&self) -> bool
Returns true
if this is a private address.
The private address ranges are defined in IETF RFC 1918 and include:
10.0.0.0/8
172.16.0.0/12
192.168.0.0/16
§Examples
use std::net::Ipv4Addr;
assert_eq!(Ipv4Addr::new(10, 0, 0, 1).is_private(), true);
assert_eq!(Ipv4Addr::new(10, 10, 10, 10).is_private(), true);
assert_eq!(Ipv4Addr::new(172, 16, 10, 10).is_private(), true);
assert_eq!(Ipv4Addr::new(172, 29, 45, 14).is_private(), true);
assert_eq!(Ipv4Addr::new(172, 32, 0, 2).is_private(), false);
assert_eq!(Ipv4Addr::new(192, 168, 0, 2).is_private(), true);
assert_eq!(Ipv4Addr::new(192, 169, 0, 2).is_private(), false);
1.7.0 (const: 1.50.0) · sourcepub const fn is_link_local(&self) -> bool
pub const fn is_link_local(&self) -> bool
Returns true
if the address is link-local (169.254.0.0/16
).
This property is defined by IETF RFC 3927.
§Examples
sourcepub const fn is_global(&self) -> bool
🔬This is a nightly-only experimental API. (ip
#27709)
pub const fn is_global(&self) -> bool
ip
#27709)Returns true
if the address appears to be globally reachable
as specified by the IANA IPv4 Special-Purpose Address Registry.
Whether or not an address is practically reachable will depend on your network configuration. Most IPv4 addresses are globally reachable, unless they are specifically defined as not globally reachable.
Non-exhaustive list of notable addresses that are not globally reachable:
- The unspecified address (
is_unspecified
) - Addresses reserved for private use (
is_private
) - Addresses in the shared address space (
is_shared
) - Loopback addresses (
is_loopback
) - Link-local addresses (
is_link_local
) - Addresses reserved for documentation (
is_documentation
) - Addresses reserved for benchmarking (
is_benchmarking
) - Reserved addresses (
is_reserved
) - The broadcast address (
is_broadcast
)
For the complete overview of which addresses are globally reachable, see the table at the IANA IPv4 Special-Purpose Address Registry.
§Examples
#![feature(ip)]
use std::net::Ipv4Addr;
// Most IPv4 addresses are globally reachable:
assert_eq!(Ipv4Addr::new(80, 9, 12, 3).is_global(), true);
// However some addresses have been assigned a special meaning
// that makes them not globally reachable. Some examples are:
// The unspecified address (`0.0.0.0`)
assert_eq!(Ipv4Addr::UNSPECIFIED.is_global(), false);
// Addresses reserved for private use (`10.0.0.0/8`, `172.16.0.0/12`, 192.168.0.0/16)
assert_eq!(Ipv4Addr::new(10, 254, 0, 0).is_global(), false);
assert_eq!(Ipv4Addr::new(192, 168, 10, 65).is_global(), false);
assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_global(), false);
// Addresses in the shared address space (`100.64.0.0/10`)
assert_eq!(Ipv4Addr::new(100, 100, 0, 0).is_global(), false);
// The loopback addresses (`127.0.0.0/8`)
assert_eq!(Ipv4Addr::LOCALHOST.is_global(), false);
// Link-local addresses (`169.254.0.0/16`)
assert_eq!(Ipv4Addr::new(169, 254, 45, 1).is_global(), false);
// Addresses reserved for documentation (`192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24`)
assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_global(), false);
assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_global(), false);
assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_global(), false);
// Addresses reserved for benchmarking (`198.18.0.0/15`)
assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_global(), false);
// Reserved addresses (`240.0.0.0/4`)
assert_eq!(Ipv4Addr::new(250, 10, 20, 30).is_global(), false);
// The broadcast address (`255.255.255.255`)
assert_eq!(Ipv4Addr::BROADCAST.is_global(), false);
// For a complete overview see the IANA IPv4 Special-Purpose Address Registry.
🔬This is a nightly-only experimental API. (ip
#27709)
ip
#27709)Returns true
if this address is part of the Shared Address Space defined in
IETF RFC 6598 (100.64.0.0/10
).
§Examples
sourcepub const fn is_benchmarking(&self) -> bool
🔬This is a nightly-only experimental API. (ip
#27709)
pub const fn is_benchmarking(&self) -> bool
ip
#27709)Returns true
if this address part of the 198.18.0.0/15
range, which is reserved for
network devices benchmarking.
This range is defined in IETF RFC 2544 as 192.18.0.0
through
198.19.255.255
but errata 423 corrects it to 198.18.0.0/15
.
§Examples
#![feature(ip)]
use std::net::Ipv4Addr;
assert_eq!(Ipv4Addr::new(198, 17, 255, 255).is_benchmarking(), false);
assert_eq!(Ipv4Addr::new(198, 18, 0, 0).is_benchmarking(), true);
assert_eq!(Ipv4Addr::new(198, 19, 255, 255).is_benchmarking(), true);
assert_eq!(Ipv4Addr::new(198, 20, 0, 0).is_benchmarking(), false);
sourcepub const fn is_reserved(&self) -> bool
🔬This is a nightly-only experimental API. (ip
#27709)
pub const fn is_reserved(&self) -> bool
ip
#27709)Returns true
if this address is reserved by IANA for future use.
IETF RFC 1112 defines the block of reserved addresses as 240.0.0.0/4
.
This range normally includes the broadcast address 255.255.255.255
, but
this implementation explicitly excludes it, since it is obviously not
reserved for future use.
§Warning
As IANA assigns new addresses, this method will be updated. This may result in non-reserved addresses being treated as reserved in code that relies on an outdated version of this method.
§Examples
#![feature(ip)]
use std::net::Ipv4Addr;
assert_eq!(Ipv4Addr::new(240, 0, 0, 0).is_reserved(), true);
assert_eq!(Ipv4Addr::new(255, 255, 255, 254).is_reserved(), true);
assert_eq!(Ipv4Addr::new(239, 255, 255, 255).is_reserved(), false);
// The broadcast address is not considered as reserved for future use by this implementation
assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_reserved(), false);
1.7.0 (const: 1.50.0) · sourcepub const fn is_multicast(&self) -> bool
pub const fn is_multicast(&self) -> bool
Returns true
if this is a multicast address (224.0.0.0/4
).
Multicast addresses have a most significant octet between 224
and 239
,
and is defined by IETF RFC 5771.
§Examples
1.7.0 (const: 1.50.0) · sourcepub const fn is_broadcast(&self) -> bool
pub const fn is_broadcast(&self) -> bool
Returns true
if this is a broadcast address (255.255.255.255
).
A broadcast address has all octets set to 255
as defined in IETF RFC 919.
§Examples
1.7.0 (const: 1.50.0) · sourcepub const fn is_documentation(&self) -> bool
pub const fn is_documentation(&self) -> bool
Returns true
if this address is in a range designated for documentation.
This is defined in IETF RFC 5737:
192.0.2.0/24
(TEST-NET-1)198.51.100.0/24
(TEST-NET-2)203.0.113.0/24
(TEST-NET-3)
§Examples
1.0.0 (const: 1.50.0) · sourcepub const fn to_ipv6_compatible(&self) -> Ipv6Addr
pub const fn to_ipv6_compatible(&self) -> Ipv6Addr
Converts this address to an IPv4-compatible IPv6
address.
a.b.c.d
becomes ::a.b.c.d
Note that IPv4-compatible addresses have been officially deprecated.
If you don’t explicitly need an IPv4-compatible address for legacy reasons, consider using to_ipv6_mapped
instead.
§Examples
1.0.0 (const: 1.50.0) · sourcepub const fn to_ipv6_mapped(&self) -> Ipv6Addr
pub const fn to_ipv6_mapped(&self) -> Ipv6Addr
source§impl Ipv4Addr
impl Ipv4Addr
sourcepub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError>
🔬This is a nightly-only experimental API. (addr_parse_ascii
#101035)
pub fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError>
addr_parse_ascii
#101035)Trait Implementations§
1.75.0 · source§impl BitAndAssign<&Ipv4Addr> for Ipv4Addr
impl BitAndAssign<&Ipv4Addr> for Ipv4Addr
source§fn bitand_assign(&mut self, rhs: &Ipv4Addr)
fn bitand_assign(&mut self, rhs: &Ipv4Addr)
&=
operation. Read more1.75.0 · source§impl BitAndAssign for Ipv4Addr
impl BitAndAssign for Ipv4Addr
source§fn bitand_assign(&mut self, rhs: Ipv4Addr)
fn bitand_assign(&mut self, rhs: Ipv4Addr)
&=
operation. Read more1.75.0 · source§impl BitOrAssign<&Ipv4Addr> for Ipv4Addr
impl BitOrAssign<&Ipv4Addr> for Ipv4Addr
source§fn bitor_assign(&mut self, rhs: &Ipv4Addr)
fn bitor_assign(&mut self, rhs: &Ipv4Addr)
|=
operation. Read more1.75.0 · source§impl BitOrAssign for Ipv4Addr
impl BitOrAssign for Ipv4Addr
source§fn bitor_assign(&mut self, rhs: Ipv4Addr)
fn bitor_assign(&mut self, rhs: Ipv4Addr)
|=
operation. Read more1.6.0 · source§impl Ord for Ipv4Addr
impl Ord for Ipv4Addr
1.16.0 · source§impl PartialOrd<IpAddr> for Ipv4Addr
impl PartialOrd<IpAddr> for Ipv4Addr
1.16.0 · source§impl PartialOrd<Ipv4Addr> for IpAddr
impl PartialOrd<Ipv4Addr> for IpAddr
1.6.0 · source§impl PartialOrd for Ipv4Addr
impl PartialOrd for Ipv4Addr
source§impl Step for Ipv4Addr
impl Step for Ipv4Addr
source§fn steps_between(start: &Ipv4Addr, end: &Ipv4Addr) -> Option<usize>
fn steps_between(start: &Ipv4Addr, end: &Ipv4Addr) -> Option<usize>
step_trait
#42168)source§fn forward_checked(start: Ipv4Addr, count: usize) -> Option<Ipv4Addr>
fn forward_checked(start: Ipv4Addr, count: usize) -> Option<Ipv4Addr>
step_trait
#42168)source§fn backward_checked(start: Ipv4Addr, count: usize) -> Option<Ipv4Addr>
fn backward_checked(start: Ipv4Addr, count: usize) -> Option<Ipv4Addr>
step_trait
#42168)source§unsafe fn forward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr
unsafe fn forward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr
step_trait
#42168)source§unsafe fn backward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr
unsafe fn backward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr
step_trait
#42168)