Struct std::net::Ipv6Addr
pub struct Ipv6Addr { /* fields omitted */ }
An IPv6 address.
IPv6 addresses are defined as 128-bit integers in IETF RFC 4291. They are usually represented as eight 16-bit segments.
The size of an Ipv6Addr struct may vary depending on the target operating system.
Embedding IPv4 Addresses
See IpAddr for a type encompassing both IPv4 and IPv6 addresses.
To assist in the transition from IPv4 to IPv6 two types of IPv6 addresses that embed an IPv4 address were defined: IPv4-compatible and IPv4-mapped addresses. Of these IPv4-compatible addresses have been officially deprecated.
Both types of addresses are not assigned any special meaning by this implementation, other than what the relevant standards prescribe. This means that an address like ::ffff:127.0.0.1, while representing an IPv4 loopback address, is not itself an IPv6 loopback address; only ::1 is. To handle these so called “IPv4-in-IPv6” addresses, they have to first be converted to their canonical IPv4 address.
IPv4-Compatible IPv6 Addresses
IPv4-compatible IPv6 addresses are defined in IETF RFC 4291 Section 2.5.5.1, and have been officially deprecated. The RFC describes the format of an “IPv4-Compatible IPv6 address” as follows:
| 80 bits | 16 | 32 bits | +--------------------------------------+--------------------------+ |0000..............................0000|0000| IPv4 address | +--------------------------------------+----+---------------------+
So ::a.b.c.d would be an IPv4-compatible IPv6 address representing the IPv4 address a.b.c.d.
To convert from an IPv4 address to an IPv4-compatible IPv6 address, use Ipv4Addr::to_ipv6_compatible. Use Ipv6Addr::to_ipv4 to convert an IPv4-compatible IPv6 address to the canonical IPv4 address.
IPv4-Mapped IPv6 Addresses
IPv4-mapped IPv6 addresses are defined in IETF RFC 4291 Section 2.5.5.2. The RFC describes the format of an “IPv4-Mapped IPv6 address” as follows:
| 80 bits | 16 | 32 bits | +--------------------------------------+--------------------------+ |0000..............................0000|FFFF| IPv4 address | +--------------------------------------+----+---------------------+
So ::ffff:a.b.c.d would be an IPv4-mapped IPv6 address representing the IPv4 address a.b.c.d.
To convert from an IPv4 address to an IPv4-mapped IPv6 address, use Ipv4Addr::to_ipv6_mapped. Use Ipv6Addr::to_ipv4 to convert an IPv4-mapped IPv6 address to the canonical IPv4 address.
Textual representation
Ipv6Addr provides a FromStr implementation. There are many ways to represent an IPv6 address in text, but in general, each segments is written in hexadecimal notation, and segments are separated by :. For more information, see IETF RFC 5952.
Examples
use std::net::Ipv6Addr;
let localhost = Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1);
assert_eq!("::1".parse(), Ok(localhost));
assert_eq!(localhost.is_loopback(), true);Implementations
impl Ipv6Addr
pub 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);
pub const LOCALHOST: Self
An IPv6 address representing localhost: ::1.
Examples
use std::net::Ipv6Addr; let addr = Ipv6Addr::LOCALHOST; assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 1));
pub const UNSPECIFIED: Self
An IPv6 address representing the unspecified address: ::
Examples
use std::net::Ipv6Addr; let addr = Ipv6Addr::UNSPECIFIED; assert_eq!(addr, Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0));
pub const fn segments(&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]);pub const fn is_unspecified(&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);
pub const fn is_loopback(&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);
pub fn is_global(&self) -> bool
Returns true if the address appears to be globally routable.
The following return false:
- the loopback address
- link-local and unique local unicast addresses
- interface-, link-, realm-, admin- and site-local multicast addresses
Examples
#![feature(ip)] use std::net::Ipv6Addr; assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff).is_global(), true); assert_eq!(Ipv6Addr::new(0, 0, 0, 0, 0, 0, 0, 0x1).is_global(), false); assert_eq!(Ipv6Addr::new(0, 0, 0x1c9, 0, 0, 0xafc8, 0, 0x1).is_global(), true);
pub fn is_unique_local(&self) -> bool
Returns true if this is a unique local address (fc00::/7).
This property is defined in IETF RFC 4193.
Examples
#![feature(ip)] 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);
pub fn is_unicast(&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);
pub fn is_unicast_link_local(&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
#![feature(ip)] 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);
pub fn is_documentation(&self) -> bool
Returns true if this is an address reserved for documentation (2001:db8::/32).
This property is defined in IETF RFC 3849.
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);
pub fn is_unicast_global(&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);
pub fn multicast_scope(&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);pub const fn is_multicast(&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);
pub fn to_ipv4_mapped(&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
#![feature(ip)]
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);pub const fn to_ipv4(&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.
::a.b.c.d and ::ffff:a.b.c.d become a.b.c.d 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)));pub fn to_canonical(&self) -> IpAddr
Converts this address to an IpAddr::V4 if it is an IPv4-mapped addresses, otherwise it returns self wrapped in an IpAddr::V6.
Examples
#![feature(ip)] 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);
pub const fn octets(&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(),
[255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]);Trait Implementations
impl Clone for Ipv6Addr
fn clone(&self) -> Ipv6Addr
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source. Read more
impl Debug for Ipv6Addr
fn fmt(&self, fmt: &mut Formatter<'_>) -> Result
Formats the value using the given formatter. Read more
impl Display for Ipv6Addr
Write an Ipv6Addr, conforming to the canonical style described by RFC 5952.
fn fmt(&self, f: &mut Formatter<'_>) -> Result
Formats the value using the given formatter. Read more
impl From<[u16; 8]> 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([
525u16, 524u16, 523u16, 522u16,
521u16, 520u16, 519u16, 518u16,
]);
assert_eq!(
Ipv6Addr::new(
0x20d, 0x20c,
0x20b, 0x20a,
0x209, 0x208,
0x207, 0x206
),
addr
);impl From<[u8; 16]> 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([
25u8, 24u8, 23u8, 22u8, 21u8, 20u8, 19u8, 18u8,
17u8, 16u8, 15u8, 14u8, 13u8, 12u8, 11u8, 10u8,
]);
assert_eq!(
Ipv6Addr::new(
0x1918, 0x1716,
0x1514, 0x1312,
0x1110, 0x0f0e,
0x0d0c, 0x0b0a
),
addr
);impl From<Ipv6Addr> for IpAddr
fn from(ipv6: Ipv6Addr) -> IpAddr
Copies this address to a new IpAddr::V6.
Examples
use std::net::{IpAddr, Ipv6Addr};
let addr = Ipv6Addr::new(0, 0, 0, 0, 0, 0xffff, 0xc00a, 0x2ff);
assert_eq!(
IpAddr::V6(addr),
IpAddr::from(addr)
);impl From<Ipv6Addr> for u128
fn from(ip: Ipv6Addr) -> u128
Convert an Ipv6Addr into a host byte order u128.
Examples
use std::net::Ipv6Addr;
let addr = Ipv6Addr::new(
0x1020, 0x3040, 0x5060, 0x7080,
0x90A0, 0xB0C0, 0xD0E0, 0xF00D,
);
assert_eq!(0x102030405060708090A0B0C0D0E0F00D_u128, u128::from(addr));impl From<u128> for Ipv6Addr
fn from(ip: u128) -> Ipv6Addr
Convert a host byte order u128 into an Ipv6Addr.
Examples
use std::net::Ipv6Addr;
let addr = Ipv6Addr::from(0x102030405060708090A0B0C0D0E0F00D_u128);
assert_eq!(
Ipv6Addr::new(
0x1020, 0x3040, 0x5060, 0x7080,
0x90A0, 0xB0C0, 0xD0E0, 0xF00D,
),
addr);impl FromStr for Ipv6Addr
type Err = AddrParseError
The associated error which can be returned from parsing.
fn from_str(s: &str) -> Result<Ipv6Addr, AddrParseError>
Parses a string s to return a value of this type. Read more
impl Hash for Ipv6Addr
fn hash<H: Hasher>(&self, s: &mut H)
impl Ord for Ipv6Addr
fn cmp(&self, other: &Ipv6Addr) -> Ordering
fn max(self, other: Self) -> Self
Compares and returns the maximum of two values. Read more
fn min(self, other: Self) -> Self
Compares and returns the minimum of two values. Read more
fn clamp(self, min: Self, max: Self) -> Self
Restrict a value to a certain interval. Read more
impl PartialEq<IpAddr> for Ipv6Addr
fn eq(&self, other: &IpAddr) -> bool
This method tests for self and other values to be equal, and is used by ==. Read more
fn ne(&self, other: &Rhs) -> bool
This method tests for !=.
impl PartialEq<Ipv6Addr> for Ipv6Addr
fn eq(&self, other: &Ipv6Addr) -> bool
This method tests for self and other values to be equal, and is used by ==. Read more
fn ne(&self, other: &Rhs) -> bool
This method tests for !=.
impl PartialEq<Ipv6Addr> for IpAddr
fn eq(&self, other: &Ipv6Addr) -> bool
This method tests for self and other values to be equal, and is used by ==. Read more
fn ne(&self, other: &Rhs) -> bool
This method tests for !=.
impl PartialOrd<IpAddr> for Ipv6Addr
fn partial_cmp(&self, other: &IpAddr) -> Option<Ordering>
This method returns an ordering between self and other values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self and other) and is used by the < operator. Read more
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
fn gt(&self, other: &Rhs) -> bool
This method tests greater than (for self and other) and is used by the > operator. Read more
fn ge(&self, other: &Rhs) -> bool
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
impl PartialOrd<Ipv6Addr> for Ipv6Addr
fn partial_cmp(&self, other: &Ipv6Addr) -> Option<Ordering>
This method returns an ordering between self and other values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self and other) and is used by the < operator. Read more
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
fn gt(&self, other: &Rhs) -> bool
This method tests greater than (for self and other) and is used by the > operator. Read more
fn ge(&self, other: &Rhs) -> bool
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
impl PartialOrd<Ipv6Addr> for IpAddr
fn partial_cmp(&self, other: &Ipv6Addr) -> Option<Ordering>
This method returns an ordering between self and other values if one exists. Read more
fn lt(&self, other: &Rhs) -> bool
This method tests less than (for self and other) and is used by the < operator. Read more
fn le(&self, other: &Rhs) -> bool
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
fn gt(&self, other: &Rhs) -> bool
This method tests greater than (for self and other) and is used by the > operator. Read more
fn ge(&self, other: &Rhs) -> bool
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
impl Copy for Ipv6Addr
impl Eq for Ipv6Addr
Auto Trait Implementations
impl RefUnwindSafe for Ipv6Addr
impl Send for Ipv6Addr
impl Sync for Ipv6Addr
impl Unpin for Ipv6Addr
impl UnwindSafe for Ipv6Addr
Blanket Implementations
impl<T> From<T> for T
pub fn from(t: T) -> T
Performs the conversion.
pub fn into(self) -> U
Performs the conversion.
type Owned = T
The resulting type after obtaining ownership.
pub fn to_owned(&self) -> T
Creates owned data from borrowed data, usually by cloning. Read more
pub fn clone_into(&self, target: &mut T)
toowned_clone_into #41263)recently added
Uses borrowed data to replace owned data, usually by cloning. Read more
type Error = Infallible
The type returned in the event of a conversion error.
pub fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
type Error = <U as TryFrom<T>>::Error
The type returned in the event of a conversion error.
pub fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>
Performs the conversion.
© 2010 The Rust Project Developers
Licensed under the Apache License, Version 2.0 or the MIT license, at your option.
https://doc.rust-lang.org/std/net/struct.Ipv6Addr.html