Struct ipaddr::Ipv6Formatter

pub struct Ipv6Formatter<'writer, W: 'writer> { /* fields omitted */ }

Configurable IPv6 formatter. By default, this formatter will format IPv6 address as described in RFC5952:

• lower case
• the longest sequence of zeros is replaced by ::
• no leading zero (fe80::123 instead of fe80::0123)

Ipv6Formatter can be obtained from Ipv6Address.formatter().

Note that the write() method returns a fmt::Result, but as explained in the std::fmt documentation, string formatting is infaillible. What may fail is writing in the underlying buffer. That means in your underlying storage is a String for example, it is fine to assume the method won't fail.

Examples

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_0000_08d5_5325);
let mut s = String::with_capacity(40);

// Default formatting
ip.formatter(&mut s).write().unwrap();
assert_eq!(s, "fe80::8657:0:8d5:5325");

// The default formatting is the RFC5952 formatting
s.truncate(0);
ip.formatter(&mut s).rfc_5952().write().unwrap();
assert_eq!(s, "fe80::8657:0:8d5:5325");

// Use upper case letters
s.truncate(0);
ip.formatter(&mut s).upper_case(true).write().unwrap();
assert_eq!(s, "FE80::8657:0:8D5:5325");

// Do not reduce the longest 0 sequence to ::
s.truncate(0);
ip.formatter(&mut s).ellipsis(false).write().unwrap();
assert_eq!(s, "fe80:0:0:0:8657:0:8d5:5325");

// Like the previous one, but with upper case letters
s.truncate(0);
ip.formatter(&mut s).upper_case(true).ellipsis(false).write().unwrap();
assert_eq!(s, "FE80:0:0:0:8657:0:8D5:5325");

// Print leading zeros: 8d5 is now 08d5, and 0 is 0000
// Note that the longest 0 sequence is still shortened to ::
s.truncate(0);
ip.formatter(&mut s).leading_zeros(true).write().unwrap();
assert_eq!(s, "fe80::8657:0000:08d5:5325");

// Disable ellipsis, and print leading zeros. This is the most expanded form.
// With this settings, an IPv6 will always be 40 characters long.
s.truncate(0);
ip.formatter(&mut s).ellipsis(false).leading_zeros(true).write().unwrap();
assert_eq!(s, "fe80:0000:0000:0000:8657:0000:08d5:5325");

// A shortcut for the previous example:
s.truncate(0);
ip.formatter(&mut s).expanded().write().unwrap();
assert_eq!(s, "fe80:0000:0000:0000:8657:0000:08d5:5325");

// Expanded and upper case
s.truncate(0);
ip.formatter(&mut s)
    .upper_case(true)
    .ellipsis(false)
    .leading_zeros(true)
    .write()
    .unwrap();
assert_eq!(s, "FE80:0000:0000:0000:8657:0000:08D5:5325");

Methods

impl<'writer, W> Ipv6Formatter<'writer, W> where     W: Write,

pub fn rfc_5952(self) -> Self

Use the formatting described in RFC5952 (this is the default)

This is equivalent to:

formatter.ellipsis(true).leading_zeros(false).upper_case(false)

For example:

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
let mut s = String::with_capacity(40);
ip.formatter(&mut s).write().unwrap();
assert_eq!(s, "fe80::8657:e6fe:8d5:5325");

pub fn expanded(self) -> Self

Fully expanded representation:

• the longest sequence of zeros is not elided
• leading zeros are printed, so hextets are always four characters long

This is equivalent to:

formatter(&mut writer).ellipsis(false).leading_zeros(true)

For example:

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
let mut s = String::with_capacity(40);
ip.formatter(&mut s).expanded().write().unwrap();
assert_eq!(s, "fe80:0000:0000:0000:8657:e6fe:08d5:5325");

pub fn ellipsis(self, flag: bool) -> Self

Set whether the longest sequence of zeros should be elided or not. By default, this is true.

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
let mut s = String::with_capacity(40);
ip.formatter(&mut s).write().unwrap();
assert_eq!(s, "fe80::8657:e6fe:8d5:5325");

s.truncate(0);
ip.formatter(&mut s).ellipsis(false).write().unwrap();
assert_eq!(s, "fe80:0:0:0:8657:e6fe:8d5:5325");

pub fn leading_zeros(self, flag: bool) -> Self

Set whether leading zeros for hextets smaller than 0x1000 should be printed. By default, this is false:

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
let mut s = String::with_capacity(40);
ip.formatter(&mut s).write().unwrap();
assert_eq!(s, "fe80::8657:e6fe:8d5:5325");

s.truncate(0);
ip.formatter(&mut s).leading_zeros(true).write().unwrap();
assert_eq!(s, "fe80::8657:e6fe:08d5:5325");

Note that zeros are also expanded. For instace, the same address with no ellipsis:

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
let mut s = String::with_capacity(40);
ip.formatter(&mut s).ellipsis(false).leading_zeros(true).write().unwrap();
assert_eq!(s, "fe80:0000:0000:0000:8657:e6fe:08d5:5325");

pub fn upper_case(self, flag: bool) -> Self

Format the address with upper case letters. This is false by default.

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
let mut s = String::with_capacity(40);

ip.formatter(&mut s).write().unwrap();
assert_eq!(s, "fe80::8657:e6fe:8d5:5325");

s.truncate(0);
ip.formatter(&mut s).upper_case(true).write().unwrap();
assert_eq!(s, "FE80::8657:E6FE:8D5:5325");

pub fn write(&mut self) -> Result

Write a string with the current configuration.

The method can only return an error if the writer W fails. That means if the writer cannot fail (for instance if the writer is a String), this method won't fail.

let ip = Ipv6Address::from(0xfe80_0000_0000_0000_8657_e6fe_08d5_5325);
// our writer will be a string. We reserve just enough space for an IPv6 address.
let mut s = String::with_capacity(40);
// it is ok to unwrap here, writing into a String cannot fail
ip.formatter(&mut s).write().unwrap();