Struct Fqdn

Source

pub struct Fqdn(/* private fields */);

Expand description

A borrowed FQDN (as a slice).

&Fqdn is to FQDN as &str is to String: the former in each pair are borrowed references; the latter are owned data.

Implementations§

Source §

impl Fqdn

Source

pub fn is_root(&self) -> bool

Checks if this is the top domain.

The human-readable representation of the top domain is the single dot ..

Source

pub fn is_tld(&self) -> bool

Checks if this is a top level domain (TLD).

A TLD is the last part of a FQDN, so this test is equivalent to check is the depth of this FQDN equals 1.

§Example

assert![ ! fqdn!("github.com.").is_tld() ];
assert![ fqdn!("com").is_tld() ];

Source

pub fn is_subdomain_of(&self, parent: &Fqdn) -> bool

Checks if this domain is an descendant of another one.

§Example

assert![ fqdn!("github.com.").is_subdomain_of(&fqdn!("github.com.")) ];
assert![ fqdn!("www.rust-lang.github.com").is_subdomain_of(&fqdn!("github.com.")) ];

assert![ ! fqdn!("github.com.").is_subdomain_of(&fqdn!("www.rust-lang.github.com")) ];

Source

pub fn tld(&self) -> Option<&Fqdn>

Gets the top level domain.

The TLD is the last part of a FQDN. For instance, the TLD of rust-lang.github.io. is io.

If the FQDN is already a TLD, self is returned. If the FQDN is the top domain, None is returned.

§Example

assert_eq![ fqdn!("rust-lang.github.com.").tld(), Some(fqdn!("com.").as_ref()) ];
assert_eq![ fqdn!(".").tld(), None ];

Source

pub fn parent(&self) -> Option<&Fqdn>

Extracts a Fqdn slice with contains the immediate parent domain.

The parent is the domain after remaining the first label. If it is already the top domain, then None is returned.

To iterate over the hierarchy of a FQDN, consider Self::hierarchy

§Example

assert_eq![ fqdn!("github.com").parent(), Some(fqdn!("com").as_ref()) ];
assert_eq![ fqdn!("github.com").parent().unwrap().parent(), None ];
assert_eq![ fqdn!(".").parent(), None ];

Source

pub fn hierarchy(&self) -> impl '_ + Iterator<Item = &Fqdn>

Iterates over the parents of the FQDN.

§Example

let fqdn = fqdn!("rust-lang.github.com.");
let mut iter = fqdn.hierarchy();
assert_eq![ iter.next(), Some(fqdn!("rust-lang.github.com.").as_ref()) ];
assert_eq![ iter.next(), Some(fqdn!("github.com.").as_ref()) ];
assert_eq![ iter.next(), Some(fqdn!("com.").as_ref()) ];
assert_eq![ iter.next(), None ];

Source

pub fn depth(&self) -> usize

Computes the depth of this domain (i.e. counts the labels)

§Example

assert_eq![ fqdn!("rust-lang.github.com.").depth(), 3 ];
assert_eq![ fqdn!("github.com.").depth(), 2 ];
assert_eq![ fqdn!(".").depth(), 0 ];

Source

pub fn from_bytes(bytes: &[u8]) -> Result<&Self, Error>

Builds a FQDN from a byte sequence.

If the byte sequence does not follow the rules, an error is produced. See Error for more details on errors.

If one is sure that the sequence matches all the rules, then the unchecking version Self::from_bytes_unchecked could be use to be more efficient.

§Example

assert_eq![ Fqdn::from_bytes(b"\x06crates\x02io\x00"), Ok(fqdn!("crates.io.").as_ref()) ];

assert_eq![ Fqdn::from_bytes(b"\x06crates\x02io"),     Err(Error::TrailingNulCharMissing) ];
assert_eq![ Fqdn::from_bytes(b"\x06cr@tes\x02io\x00"), Err(Error::InvalidLabelChar) ];
assert_eq![ Fqdn::from_bytes(b"\x02crates\x02io\x00"), Err(Error::InvalidStructure) ];

Source

pub unsafe fn from_bytes_unchecked(bytes: &[u8]) -> &Self

Builds without any check a FQDN from a byte sequence.

§Safety

This function is unsafe because it does not check that the bytes passed to it are valid and are well-structured. It means that:

each label starts with a byte indicating its length
the bytes sequence ends with a nul-byte
only allowed ASCII characters are present in labels
the size limits should be respected

If one of these constraints is violated, it may cause memory unsafety issues with future users of the FQDN.

Consider Self::from_bytes for a safe version of this function.

§Example

let crates = unsafe {
    Fqdn::from_bytes_unchecked(b"\x06crates\x02io\x00")
};
assert_eq![ *crates, fqdn!("crates.io.") ];

Source

pub fn as_bytes(&self) -> &[u8] ⓘ

Returns the complete byte sequence of the FQDN.

The returned sequence is terminated by the nul byte.

§Example

assert_eq![ fqdn!("crates.io.").as_bytes(),  b"\x06crates\x02io\x00" ];

Source

pub fn as_c_str(&self) -> &CStr

Returns the FQDN as a C string.

Source

pub fn labels(&self) -> impl '_ + Iterator<Item = &str>

Iterates over the labels which constitutes the FQDN.

§Example

let fqdn = fqdn!("rust-lang.github.com.");
let mut iter = fqdn.labels();
assert_eq![ iter.next(), Some("rust-lang") ];
assert_eq![ iter.next(), Some("github") ];
assert_eq![ iter.next(), Some("com") ];
assert_eq![ iter.next(), None ];