impl Ipv6Addr

const fn new(a: u16, b: u16, c: u16, d: u16, e: u16, f: u16, g: u16, h: u16) -> Ipv6Addr

Creates a new IPv6 address from eight 16-bit segments.

The result will represent the IP address a:b:c:d:e:f:g:h.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff);

const fn to_bits(self: Self) -> u128

Converts an IPv6 address into a u128 representation using native byte order.

Although IPv6 addresses are big-endian, the u128 value will use the target platform's native byte order. That is, the u128 value is an integer representation of the IPv6 address and not an integer interpretation of the IPv6 address's big-endian bitstring. This means that the u128 value masked with 0xffffffffffffffffffffffffffff0000_u128 will set the last segment in the address to 0, regardless of the target platform's endianness.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::new(
    0x1020, 0x3040, 0x5060, 0x7080,
    0x90A0, 0xB0C0, 0xD0E0, 0xF00D,
);
assert_eq!(0x102030405060708090A0B0C0D0E0F00D_u128, addr.to_bits());

use std::net::Ipv6Addr;

let addr = Ipv6Addr::new(
    0x1020, 0x3040, 0x5060, 0x7080,
    0x90A0, 0xB0C0, 0xD0E0, 0xF00D,
);
let addr_bits = addr.to_bits() & 0xffffffffffffffffffffffffffff0000_u128;
assert_eq!(
    Ipv6Addr::new(
        0x1020, 0x3040, 0x5060, 0x7080,
        0x90A0, 0xB0C0, 0xD0E0, 0x0000,
    ),
    Ipv6Addr::from_bits(addr_bits));

const fn from_bits(bits: u128) -> Ipv6Addr

Converts a native byte order u128 into an IPv6 address.

See Ipv6Addr::to_bits for an explanation on endianness.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::from_bits(0x102030405060708090A0B0C0D0E0F00D_u128);
assert_eq!(
    Ipv6Addr::new(
        0x1020, 0x3040, 0x5060, 0x7080,
        0x90A0, 0xB0C0, 0xD0E0, 0xF00D,
    ),
    addr);

const fn segments(self: &Self) -> [u16; 8]

Returns the eight 16-bit segments that make up this address.

Examples

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).segments(),
           [0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff]);

const fn from_segments(segments: [u16; 8]) -> Ipv6Addr

Creates an Ipv6Addr from an eight element 16-bit array.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::from_segments([
    0x20du16, 0x20cu16, 0x20bu16, 0x20au16,
    0x209u16, 0x208u16, 0x207u16, 0x206u16,
]);
assert_eq!(
    Ipv6Addr::new(
        0x20d, 0x20c, 0x20b, 0x20a,
        0x209, 0x208, 0x207, 0x206,
    ),
    addr
);

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

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

This property is defined in IETF RFC 4291.

Examples

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unspecified(), false);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0).is_unspecified(), true);

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

Returns true if this is the loopback address (::1), as defined in IETF RFC 4291 section 2.5.3.

Contrary to IPv4, in IPv6 there is only one loopback address.

Examples

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_loopback(), false);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1).is_loopback(), true);

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

Returns true if the address appears to be globally reachable as specified by the IANA IPv6 Special-Purpose Address Registry.

Whether or not an address is practically reachable will depend on your network configuration. Most IPv6 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)
• The loopback address (is_loopback)
• IPv4-mapped addresses
• Addresses reserved for benchmarking (is_benchmarking)
• Addresses reserved for documentation (is_documentation)
• Unique local addresses (is_unique_local)
• Unicast addresses with link-local scope (is_unicast_link_local)

For the complete overview of which addresses are globally reachable, see the table at the IANA IPv6 Special-Purpose Address Registry.

Note that an address having global scope is not the same as being globally reachable, and there is no direct relation between the two concepts: There exist addresses with global scope that are not globally reachable (for example unique local addresses), and addresses that are globally reachable without having global scope (multicast addresses with non-global scope).

Examples

#![feature(ip)]

use std::net::Ipv6Addr;

// Most IPv6 addresses are globally reachable:
assert_eq!(Ipv6Addr::new(0x26, 0, 0x1c9, 0, 0, 0xafc8, 0x10, 0x1).is_global(), true);

// However some addresses have been assigned a special meaning
// that makes them not globally reachable. Some examples are:

// The unspecified address (`::`)
assert_eq!(Ipv6Addr::UNSPECIFIED.is_global(), false);

// The loopback address (`::1`)
assert_eq!(Ipv6Addr::LOCALHOST.is_global(), false);

// IPv4-mapped addresses (`::ffff:0:0/96`)
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_global(), false);

// Addresses reserved for benchmarking (`2001:2::/48`)
assert_eq!(Ipv6Addr::new(0x2001, 2, 0, 0, 0, 0, 0, 1,).is_global(), false);

// Addresses reserved for documentation (`2001:db8::/32` and `3fff::/20`)
assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 1).is_global(), false);
assert_eq!(Ipv6Addr::new(0x3fff, 0, 0, 0, 0, 0, 0, 0).is_global(), false);

// Unique local addresses (`fc00::/7`)
assert_eq!(Ipv6Addr::new(0xfc02, 0, 0, 0, 0, 0, 0, 1).is_global(), false);

// Unicast addresses with link-local scope (`fe80::/10`)
assert_eq!(Ipv6Addr::new(0xfe81, 0, 0, 0, 0, 0, 0, 1).is_global(), false);

// For a complete overview see the IANA IPv6 Special-Purpose Address Registry.

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

Returns true if this is a unique local address (fc00::/7).

This property is defined in IETF RFC 4193.

Examples

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unique_local(), false);
assert_eq!(Ipv6Addr::new(0xfc02, 0, 0, 0, 0, 0, 0, 0).is_unique_local(), true);

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

Returns true if this is a unicast address, as defined by IETF RFC 4291. Any address that is not a multicast address (ff00::/8) is unicast.

Examples

#![feature(ip)]

use std::net::Ipv6Addr;

// The unspecified and loopback addresses are unicast.
assert_eq!(Ipv6Addr::UNSPECIFIED.is_unicast(), true);
assert_eq!(Ipv6Addr::LOCALHOST.is_unicast(), true);

// Any address that is not a multicast address (`ff00::/8`) is unicast.
assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast(), true);
assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).is_unicast(), false);

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

Returns true if the address is a unicast address with link-local scope, as defined in RFC 4291.

A unicast address has link-local scope if it has the prefix fe80::/10, as per RFC 4291 section 2.4. Note that this encompasses more addresses than those defined in RFC 4291 section 2.5.6, which describes "Link-Local IPv6 Unicast Addresses" as having the following stricter format:

| 10 bits  |         54 bits         |          64 bits           |
+----------+-------------------------+----------------------------+
|1111111010|           0             |       interface ID         |
+----------+-------------------------+----------------------------+

So while currently the only addresses with link-local scope an application will encounter are all in fe80::/64, this might change in the future with the publication of new standards. More addresses in fe80::/10 could be allocated, and those addresses will have link-local scope.

Also note that while RFC 4291 section 2.5.3 mentions about the loopback address (::1) that "it is treated as having Link-Local scope", this does not mean that the loopback address actually has link-local scope and this method will return false on it.

Examples

use std::net::Ipv6Addr;

// The loopback address (`::1`) does not actually have link-local scope.
assert_eq!(Ipv6Addr::LOCALHOST.is_unicast_link_local(), false);

// Only addresses in `fe80::/10` have link-local scope.
assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), false);
assert_eq!(Ipv6Addr::new(0xfe80, 0, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), true);

// Addresses outside the stricter `fe80::/64` also have link-local scope.
assert_eq!(Ipv6Addr::new(0xfe80, 0, 0, 1, 0, 0, 0, 0).is_unicast_link_local(), true);
assert_eq!(Ipv6Addr::new(0xfe81, 0, 0, 0, 0, 0, 0, 0).is_unicast_link_local(), true);

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

Returns true if this is an address reserved for documentation (2001:db8::/32 and 3fff::/20).

This property is defined by IETF RFC 3849 and IETF RFC 9637.

Examples

#![feature(ip)]

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_documentation(), false);
assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_documentation(), true);
assert_eq!(Ipv6Addr::new(0x3fff, 0, 0, 0, 0, 0, 0, 0).is_documentation(), true);

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

Returns true if this is an address reserved for benchmarking (2001:2::/48).

This property is defined in IETF RFC 5180, where it is mistakenly specified as covering the range 2001:0200::/48. This is corrected in IETF RFC Errata 1752 to 2001:0002::/48.

#![feature(ip)]

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc613, 0x0).is_benchmarking(), false);
assert_eq!(Ipv6Addr::new(0x2001, 0x2, 0, 0, 0, 0, 0, 0).is_benchmarking(), true);

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

Returns true if the address is a globally routable unicast address.

The following return false:

• the loopback address
• the link-local addresses
• unique local addresses
• the unspecified address
• the address range reserved for documentation

This method returns true for site-local addresses as per RFC 4291 section 2.5.7

The special behavior of [the site-local unicast] prefix defined in [RFC3513] must no longer
be supported in new implementations (i.e., new implementations must treat this prefix as
Global Unicast).

Examples

#![feature(ip)]

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_unicast_global(), false);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_unicast_global(), true);

const fn multicast_scope(self: &Self) -> Option<Ipv6MulticastScope>

Returns the address's multicast scope if the address is multicast.

Examples

#![feature(ip)]

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

assert_eq!(
    Ipv6Addr::new(0xff0e, 0, 0, 0, 0, 0, 0, 0).multicast_scope(),
    Some(Ipv6MulticastScope::Global)
);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).multicast_scope(), None);

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

Returns true if this is a multicast address (ff00::/8).

This property is defined by IETF RFC 4291.

Examples

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).is_multicast(), true);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_multicast(), false);

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

Returns true if the address is an IPv4-mapped address (::ffff:0:0/96).

IPv4-mapped addresses can be converted to their canonical IPv4 address with to_ipv4_mapped.

Examples

#![feature(ip)]

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

let ipv4_mapped = Ipv4Addr::new(192, 0, 2, 255).to_ipv6_mapped();
assert_eq!(ipv4_mapped.is_ipv4_mapped(), true);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc000, 0x2ff).is_ipv4_mapped(), true);

assert_eq!(Ipv6Addr::new(0x2001, 0xdb8, 0, 0, 0, 0, 0, 0).is_ipv4_mapped(), false);

const fn to_ipv4_mapped(self: &Self) -> Option<Ipv4Addr>

Converts this address to an IPv4 address if it's an IPv4-mapped address, as defined in IETF RFC 4291 section 2.5.5.2, otherwise returns None.

::ffff:a.b.c.d becomes a.b.c.d. All addresses not starting with ::ffff will return None.

Examples

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

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4_mapped(), None);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4_mapped(),
           Some(Ipv4Addr::new(192, 10, 2, 255)));
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4_mapped(), None);

const fn to_ipv4(self: &Self) -> Option<Ipv4Addr>

Converts this address to an IPv4 address if it is either an IPv4-compatible address as defined in IETF RFC 4291 section 2.5.5.1, or an IPv4-mapped address as defined in IETF RFC 4291 section 2.5.5.2, otherwise returns None.

Note that this will return an IPv4 address for the IPv6 loopback address ::1. Use Ipv6Addr::to_ipv4_mapped to avoid this.

::a.b.c.d and ::ffff:a.b.c.d become a.b.c.d. ::1 becomes 0.0.0.1. All addresses not starting with either all zeroes or ::ffff will return None.

Examples

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

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).to_ipv4(), None);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).to_ipv4(),
           Some(Ipv4Addr::new(192, 10, 2, 255)));
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1).to_ipv4(),
           Some(Ipv4Addr::new(0, 0, 0, 1)));

const fn to_canonical(self: &Self) -> IpAddr

Converts this address to an IpAddr::V4 if it is an IPv4-mapped address, otherwise returns self wrapped in an IpAddr::V6.

Examples

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1).is_loopback(), false);
assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0x7f00, 0x1).to_canonical().is_loopback(), true);

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

Returns the sixteen eight-bit integers the IPv6 address consists of.

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).octets(),
           [0xff, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);

const fn from_octets(octets: [u8; 16]) -> Ipv6Addr

Creates an Ipv6Addr from a sixteen element byte array.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::from_octets([
    0x19u8, 0x18u8, 0x17u8, 0x16u8, 0x15u8, 0x14u8, 0x13u8, 0x12u8,
    0x11u8, 0x10u8, 0x0fu8, 0x0eu8, 0x0du8, 0x0cu8, 0x0bu8, 0x0au8,
]);
assert_eq!(
    Ipv6Addr::new(
        0x1918, 0x1716, 0x1514, 0x1312,
        0x1110, 0x0f0e, 0x0d0c, 0x0b0a,
    ),
    addr
);

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

Returns the sixteen eight-bit integers the IPv6 address consists of as a slice.

Examples

#![feature(ip_as_octets)]

use std::net::Ipv6Addr;

assert_eq!(Ipv6Addr::new(0xff00, 0, 0, 0, 0, 0, 0, 0).as_octets(),
           &[255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])

impl Ipv6Addr

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

Parse an IPv6 address from a slice of bytes.

#![feature(addr_parse_ascii)]

use std::net::Ipv6Addr;

let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);

assert_eq!(Ipv6Addr::parse_ascii(b"::1"), Ok(localhost));

impl BitAnd for Ipv6Addr

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

impl BitAnd for Ipv6Addr

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

impl BitAndAssign for Ipv6Addr

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

impl BitAndAssign for Ipv6Addr

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

impl BitOr for Ipv6Addr

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

impl BitOr for Ipv6Addr

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

impl BitOrAssign for Ipv6Addr

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

impl BitOrAssign for Ipv6Addr

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

impl Clone for Ipv6Addr

fn clone(self: &Self) -> Ipv6Addr

impl Copy for Ipv6Addr

impl Debug for Ipv6Addr

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

impl Display for Ipv6Addr

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

impl Eq for Ipv6Addr

impl Freeze for Ipv6Addr

impl From for Ipv6Addr

fn from(ip: u128) -> Ipv6Addr

Uses Ipv6Addr::from_bits to convert a host byte order u128 to an IPv6 address.

impl From for Ipv6Addr

fn from(octets: [u8; 16]) -> Ipv6Addr

Creates an Ipv6Addr from a sixteen element byte array.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::from([
    0x19u8, 0x18u8, 0x17u8, 0x16u8, 0x15u8, 0x14u8, 0x13u8, 0x12u8,
    0x11u8, 0x10u8, 0x0fu8, 0x0eu8, 0x0du8, 0x0cu8, 0x0bu8, 0x0au8,
]);
assert_eq!(
    Ipv6Addr::new(
        0x1918, 0x1716, 0x1514, 0x1312,
        0x1110, 0x0f0e, 0x0d0c, 0x0b0a,
    ),
    addr
);

impl From for Ipv6Addr

fn from(segments: [u16; 8]) -> Ipv6Addr

Creates an Ipv6Addr from an eight element 16-bit array.

Examples

use std::net::Ipv6Addr;

let addr = Ipv6Addr::from([
    0x20du16, 0x20cu16, 0x20bu16, 0x20au16,
    0x209u16, 0x208u16, 0x207u16, 0x206u16,
]);
assert_eq!(
    Ipv6Addr::new(
        0x20d, 0x20c, 0x20b, 0x20a,
        0x209, 0x208, 0x207, 0x206,
    ),
    addr
);

impl FromStr for Ipv6Addr

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

impl Hash for Ipv6Addr

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

impl Not for Ipv6Addr

fn not(self: Self) -> Ipv6Addr

impl Ord for Ipv6Addr

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

impl PartialEq for Ipv6Addr

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

impl PartialEq for Ipv6Addr

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

impl PartialOrd for Ipv6Addr

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

impl PartialOrd for Ipv6Addr

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

impl RefUnwindSafe for Ipv6Addr

impl Send for Ipv6Addr

impl Step for Ipv6Addr

fn steps_between(start: &Ipv6Addr, end: &Ipv6Addr) -> (usize, Option<usize>)

fn forward_checked(start: Ipv6Addr, count: usize) -> Option<Ipv6Addr>

fn backward_checked(start: Ipv6Addr, count: usize) -> Option<Ipv6Addr>

unsafe fn forward_unchecked(start: Ipv6Addr, count: usize) -> Ipv6Addr

unsafe fn backward_unchecked(start: Ipv6Addr, count: usize) -> Ipv6Addr

impl StructuralPartialEq for Ipv6Addr

impl Sync for Ipv6Addr

impl TrustedStep for Ipv6Addr

impl Unpin for Ipv6Addr

impl UnsafeUnpin for Ipv6Addr

impl UnwindSafe for Ipv6Addr

impl<T> Any for Ipv6Addr

fn type_id(self: &Self) -> TypeId

impl<T> Borrow for Ipv6Addr

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

impl<T> BorrowMut for Ipv6Addr

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

impl<T> CloneToUninit for Ipv6Addr

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

impl<T> From for Ipv6Addr

fn from(t: T) -> T

Returns the argument unchanged.

impl<T, U> Into for Ipv6Addr

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 Ipv6Addr

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

impl<T, U> TryInto for Ipv6Addr

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