Struct `Ipv4Addr`

struct Ipv4Addr { ... }

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

`impl Ipv4Addr`

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

use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(127, 0, 0, 1);

const fn to_bits(self: 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

use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(0x12, 0x34, 0x56, 0x78);
assert_eq!(0x12345678, addr.to_bits());

use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(0x12, 0x34, 0x56, 0x78);
let addr_bits = addr.to_bits() & 0xffffff00;
assert_eq!(Ipv4Addr::new(0x12, 0x34, 0x56, 0x00), Ipv4Addr::from_bits(addr_bits));

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

use std::net::Ipv4Addr;

let addr = Ipv4Addr::from_bits(0x12345678);
assert_eq!(Ipv4Addr::new(0x12, 0x34, 0x56, 0x78), addr);

const fn octets(self: &Self) -> [u8; 4]

Returns the four eight-bit integers that make up this address.

Examples

use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(127, 0, 0, 1);
assert_eq!(addr.octets(), [127, 0, 0, 1]);

const fn from_octets(octets: [u8; 4]) -> Ipv4Addr

Creates an Ipv4Addr from a four element byte array.

Examples

use std::net::Ipv4Addr;

let addr = Ipv4Addr::from_octets([13u8, 12u8, 11u8, 10u8]);
assert_eq!(Ipv4Addr::new(13, 12, 11, 10), addr);

const fn as_octets(self: &Self) -> &[u8; 4]

Returns the four eight-bit integers that make up this address as a slice.

Examples

#![feature(ip_as_octets)]

use std::net::Ipv4Addr;

let addr = Ipv4Addr::new(127, 0, 0, 1);
assert_eq!(addr.as_octets(), &[127, 0, 0, 1]);

const fn is_unspecified(self: &Self) -> bool

Returns true for the special 'unspecified' address (0.0.0.0).

This property is defined in UNIX Network Programming, Second Edition, W. Richard Stevens, p. 891; see also ip7.

Examples

use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(0, 0, 0, 0).is_unspecified(), true);
assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_unspecified(), false);

const fn is_loopback(self: &Self) -> bool

Returns true if this is a loopback address (127.0.0.0/8).

This property is defined by IETF RFC 1122.

Examples

use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(127, 0, 0, 1).is_loopback(), true);
assert_eq!(Ipv4Addr::new(45, 22, 13, 197).is_loopback(), false);

const fn is_private(self: &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);

const fn is_link_local(self: &Self) -> bool

Returns true if the address is link-local (169.254.0.0/16).

This property is defined by IETF RFC 3927.

Examples

use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(169, 254, 0, 0).is_link_local(), true);
assert_eq!(Ipv4Addr::new(169, 254, 10, 65).is_link_local(), true);
assert_eq!(Ipv4Addr::new(16, 89, 10, 65).is_link_local(), false);

const fn is_global(self: &Self) -> bool

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.

const fn is_shared(self: &Self) -> bool

Returns true if this address is part of the Shared Address Space defined in IETF RFC 6598 (100.64.0.0/10).

Examples

#![feature(ip)]
use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(100, 64, 0, 0).is_shared(), true);
assert_eq!(Ipv4Addr::new(100, 127, 255, 255).is_shared(), true);
assert_eq!(Ipv4Addr::new(100, 128, 0, 0).is_shared(), false);

const fn is_benchmarking(self: &Self) -> bool

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);

const fn is_reserved(self: &Self) -> bool

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);

const fn is_multicast(self: &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

use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(224, 254, 0, 0).is_multicast(), true);
assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_multicast(), true);
assert_eq!(Ipv4Addr::new(172, 16, 10, 65).is_multicast(), false);

const fn is_broadcast(self: &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

use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(255, 255, 255, 255).is_broadcast(), true);
assert_eq!(Ipv4Addr::new(236, 168, 10, 65).is_broadcast(), false);

const fn is_documentation(self: &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

use std::net::Ipv4Addr;

assert_eq!(Ipv4Addr::new(192, 0, 2, 255).is_documentation(), true);
assert_eq!(Ipv4Addr::new(198, 51, 100, 65).is_documentation(), true);
assert_eq!(Ipv4Addr::new(203, 0, 113, 6).is_documentation(), true);
assert_eq!(Ipv4Addr::new(193, 34, 17, 19).is_documentation(), false);

const fn to_ipv6_compatible(self: &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

use std::net::{Ipv4Addr, Ipv6Addr};

assert_eq!(
    Ipv4Addr::new(192, 0, 2, 255).to_ipv6_compatible(),
    Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0xc000, 0x2ff)
);

const fn to_ipv6_mapped(self: &Self) -> Ipv6Addr

Converts this address to an IPv4-mapped IPv6 address.

a.b.c.d becomes ::ffff:a.b.c.d

Examples

use std::net::{Ipv4Addr, Ipv6Addr};

assert_eq!(Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped(),
           Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x2ff));

`impl Ipv4Addr`

fn parse_ascii(b: &[u8]) -> Result<Self, AddrParseError>

Parse an IPv4 address from a slice of bytes.

#![feature(addr_parse_ascii)]

use std::net::Ipv4Addr;

let localhost = Ipv4Addr::new(127, 0, 0, 1);

assert_eq!(Ipv4Addr::parse_ascii(b"127.0.0.1"), Ok(localhost));

`impl BitAnd for Ipv4Addr`

fn bitand(self: Self, rhs: Ipv4Addr) -> Ipv4Addr

`impl BitAnd for Ipv4Addr`

fn bitand(self: Self, rhs: &Ipv4Addr) -> Ipv4Addr

`impl BitAndAssign for Ipv4Addr`

fn bitand_assign(self: &mut Self, rhs: Ipv4Addr)

`impl BitAndAssign for Ipv4Addr`

fn bitand_assign(self: &mut Self, rhs: &Ipv4Addr)

`impl BitOr for Ipv4Addr`

fn bitor(self: Self, rhs: Ipv4Addr) -> Ipv4Addr

`impl BitOr for Ipv4Addr`

fn bitor(self: Self, rhs: &Ipv4Addr) -> Ipv4Addr

`impl BitOrAssign for Ipv4Addr`

fn bitor_assign(self: &mut Self, rhs: Ipv4Addr)

`impl BitOrAssign for Ipv4Addr`

fn bitor_assign(self: &mut Self, rhs: &Ipv4Addr)

`impl Clone for Ipv4Addr`

fn clone(self: &Self) -> Ipv4Addr

`impl Copy for Ipv4Addr`

`impl Debug for Ipv4Addr`

fn fmt(self: &Self, fmt: &mut Formatter<'_>) -> Result

`impl Display for Ipv4Addr`

fn fmt(self: &Self, fmt: &mut Formatter<'_>) -> Result

`impl Eq for Ipv4Addr`

`impl Freeze for Ipv4Addr`

`impl From for Ipv4Addr`

fn from(ip: u32) -> Ipv4Addr: Uses Ipv4Addr::from_bits to convert a host byte order u32 into an IPv4 address.

`impl From for Ipv4Addr`

fn from(octets: [u8; 4]) -> Ipv4Addr

Creates an Ipv4Addr from a four element byte array.

Examples

use std::net::Ipv4Addr;

let addr = Ipv4Addr::from([13u8, 12u8, 11u8, 10u8]);
assert_eq!(Ipv4Addr::new(13, 12, 11, 10), addr);

`impl FromStr for Ipv4Addr`

fn from_str(s: &str) -> Result<Ipv4Addr, AddrParseError>

`impl Hash for Ipv4Addr`

fn hash<H: Hasher>(self: &Self, state: &mut H)

`impl Not for Ipv4Addr`

fn not(self: Self) -> Ipv4Addr

`impl Ord for Ipv4Addr`

fn cmp(self: &Self, other: &Ipv4Addr) -> Ordering

`impl PartialEq for Ipv4Addr`

fn eq(self: &Self, other: &IpAddr) -> bool

`impl PartialEq for Ipv4Addr`

fn eq(self: &Self, other: &Ipv4Addr) -> bool

`impl PartialOrd for Ipv4Addr`

fn partial_cmp(self: &Self, other: &Ipv4Addr) -> Option<Ordering>

`impl PartialOrd for Ipv4Addr`

fn partial_cmp(self: &Self, other: &IpAddr) -> Option<Ordering>

`impl RefUnwindSafe for Ipv4Addr`

`impl Send for Ipv4Addr`

`impl Step for Ipv4Addr`

fn steps_between(start: &Ipv4Addr, end: &Ipv4Addr) -> (usize, Option<usize>)
fn forward_checked(start: Ipv4Addr, count: usize) -> Option<Ipv4Addr>
fn backward_checked(start: Ipv4Addr, count: usize) -> Option<Ipv4Addr>
unsafe fn forward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr
unsafe fn backward_unchecked(start: Ipv4Addr, count: usize) -> Ipv4Addr

`impl StructuralPartialEq for Ipv4Addr`

`impl Sync for Ipv4Addr`

`impl TrustedStep for Ipv4Addr`

`impl Unpin for Ipv4Addr`

`impl UnsafeUnpin for Ipv4Addr`

`impl UnwindSafe for Ipv4Addr`

`impl<T> Any for Ipv4Addr`

fn type_id(self: &Self) -> TypeId

`impl<T> Borrow for Ipv4Addr`

fn borrow(self: &Self) -> &T

`impl<T> BorrowMut for Ipv4Addr`

fn borrow_mut(self: &mut Self) -> &mut T

`impl<T> CloneToUninit for Ipv4Addr`

unsafe fn clone_to_uninit(self: &Self, dest: *mut u8)

`impl<T> From for Ipv4Addr`

fn from(t: T) -> T: Returns the argument unchanged.

`impl<T, U> Into for Ipv4Addr`

fn into(self: Self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of [From]<T> for U chooses to do.

`impl<T, U> TryFrom for Ipv4Addr`

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

`impl<T, U> TryInto for Ipv4Addr`

fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error>