Struct domain::base::name::Dname

pub struct Dname<Octets: ?Sized>(_);

An uncompressed, absolute domain name.

The type wraps an octets sequence and guarantees that it always contains a correctly encoded, absolute domain name. It provides an interface similar to a slice of the labels of the name, i.e., you can iterate over the labels, split them off, etc.

You can construct a domain name from a string via the FromStr trait or manually via a DnameBuilder. In addition, you can also parse it from a message. This will, however, require the name to be uncompressed. Otherwise, you would receive a ParsedDname which can be converted into Dname via ToDname::to_dname.

Implementations

impl<Octets> Dname<Octets>

Creating Values

pub const unsafe fn from_octets_unchecked(octets: Octets) -> Self

Creates a domain name from the underlying octets without any check.

Since this will allow to actually construct an incorrectly encoded domain name value, the function is unsafe.

Safety

The octets sequence passed in octets must contain a correctly encoded absolute domain name. It must be at most 255 octets long. It must contain the root label exactly once as its last label.

pub fn from_octets(octets: Octets) -> Result<Self, DnameError> where
    Octets: AsRef<[u8]>, 

Creates a domain name from an octet sequence.

This will only succeed if octets contains a properly encoded absolute domain name. Because the function checks, this will take a wee bit of time.

pub fn from_chars<C>(chars: C) -> Result<Self, FromStrError> where
    Octets: FromBuilder,
    <Octets as FromBuilder>::Builder: EmptyBuilder,
    C: IntoIterator<Item = char>, 

Creates a domain name from a sequence of characters.

The sequence must result in a domain name in master format representation. That is, its labels should be separated by dots. Actual dots, white space and backslashes should be escaped by a preceeding backslash, and any byte value that is not a printable ASCII character should be encoded by a backslash followed by its three digit decimal value.

The name will always be an absolute name. If the last character in the sequence is not a dot, the function will quietly add a root label, anyway. In most cases, this is likely what you want. If it isn’t, though, use UncertainDname instead to be able to check.

pub fn root() -> Self where
    Octets: From<&'static [u8]>, 

Returns a domain name consisting of the root label only.

This function will work for any kind octets sequence that can be created from an octets slice. Since this will require providing the type parameter in some cases, there are shortcuts methods for specific octets types: root_ref, root_vec, and root_bytes.

impl Dname<[u8]>

pub fn from_slice(slice: &[u8]) -> Result<&Self, DnameError>

Creates a domain name from an octets slice.

This will only succeed if slice contains a properly encoded absolute domain name.

pub fn root_slice() -> &'static Self

Creates a domain name for the root label only atop an octets slice.

impl Dname<&'static [u8]>

pub fn root_ref() -> Self

Creates a domain name for the root label only atop a slice reference.

impl Dname<Vec<u8>>

pub fn root_vec() -> Self

Creates a domain name for the root label only atop a Vec<u8>.

pub fn vec_from_str(s: &str) -> Result<Self, FromStrError>

Creates a domain name atop a Vec<u8> from its string representation.

impl<Octets: ?Sized> Dname<Octets>

Conversions

pub fn as_octets(&self) -> &Octets

Returns a reference to the underlying octets sequence.

pub fn into_octets(self) -> Octets where
    Octets: Sized, 

Converts the domain name into the underlying octets sequence.

pub fn into_relative(self) -> RelativeDname<Octets> where
    Octets: Sized + OctetsExt, 

Converts the name into a relative name by dropping the root label.

pub fn for_ref(&self) -> Dname<&Octets>

Returns a domain name using a reference to the octets.

pub fn as_slice(&self) -> &[u8] where
    Octets: AsRef<[u8]>, 

Returns a reference to the underlying octets slice.

pub fn for_slice(&self) -> Dname<&[u8]> where
    Octets: AsRef<[u8]>, 

Returns a domain name for the octets slice of the content.

impl<Octets: AsRef<[u8]> + ?Sized> Dname<Octets>

Properties

More of the usual methods on octets sequences, such as len, are available via the implementation of Deref<Target = Octets>.

pub fn is_root(&self) -> bool

Returns whether the name is the root label only.

impl<Octets: AsRef<[u8]> + ?Sized> Dname<Octets>

Working with Labels

All methods that split the name or cut off parts on the left side are only available on octets sequences that are their only range, e.g., &[u8] or Bytes, as these are the only types that can be split.

pub fn iter(&self) -> DnameIter

Returns an iterator over the labels of the domain name.

pub fn iter_suffixes(&self) -> SuffixIter<&Octets>

Returns an iterator over the suffixes of the name.

The returned iterator starts with the full name and then for each additional step returns a name with the left-most label stripped off until it reaches the root label.

pub fn label_count(&self) -> usize

Returns the number of labels in the domain name.

pub fn first(&self) -> &Label

Returns a reference to the first label.

pub fn last(&self) -> &'static Label

Returns a reference to the last label.

Because the last label in an absolute name is always the root label, this method can return a static reference. It is also a wee bit silly, but here for completeness.

pub fn starts_with<'a, N: ToLabelIter<'a> + ?Sized>(
    &'a self,
    base: &'a N
) -> bool

Determines whether base is a prefix of self.

pub fn ends_with<'a, N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool

Determines whether base is a suffix of self.

pub fn is_label_start(&self, index: usize) -> bool

Returns whether an index points to the first byte of a non-root label.

pub fn slice(&self, begin: usize, end: usize) -> &RelativeDname<[u8]>

Returns the part of the name indicated by start and end positions.

The returned name will start at position begin and end right before position end. Both positions are given as indexes into the underlying octets sequence and must point to the begining of a label.

The method returns a reference to an unsized relative domain name and is thus best suited for temporary referencing. If you want to keep the part of the name around, range is likely a better choice.

Panics

The method panics if either position is not the start of a label or is out of bounds.

Because the returned domain name is relative, the method will also panic if the end is equal to the length of the name. If you want to slice the entire end of the name including the final root label, you can use slice_from() instead.

pub fn slice_from(&self, begin: usize) -> &Dname<[u8]>

Returns the part of the name starting at the given position.

The returned name will start at the given postion and cover the remainder of the name. The position begin is provided as an index into the underlying octets sequence and must point to the beginning of a label.

The method returns a reference to an unsized domain name and is thus best suited for temporary referencing. If you want to keep the part of the name around, range_from is likely a better choice.

Panics

The method panics if begin isn’t the index of the beginning of a label or is out of bounds.

pub fn slice_to(&self, end: usize) -> &RelativeDname<[u8]>

Returns the part of the name ending at the given position.

The returned name will start at beginning of the name and continue until just before the given postion. The position end is considered as an index into the underlying octets sequence and must point to the beginning of a label.

The method returns a reference to an unsized domain name and is thus best suited for temporary referencing. If you want to keep the part of the name around, range_to is likely a better choice.

Panics

The method panics if end is not the beginning of a label or is out of bounds. Because the returned domain name is relative, the method will also panic if the end is equal to the length of the name.

pub fn range<'a>(
    &'a self,
    begin: usize,
    end: usize
) -> RelativeDname<<&'a Octets as OctetsRef>::Range> where
    &'a Octets: OctetsRef, 

Returns the part of the name indicated by start and end positions.

The returned name will start at position begin and end right before position end. Both positions are given as indexes into the underlying octets sequence and must point to the begining of a label.

Panics

The method panics if either position is not the start of a label or is out of bounds.

Because the returned domain name is relative, the method will also panic if the end is equal to the length of the name. If you want to slice the entire end of the name including the final root label, you can use range_from() instead.

pub fn range_from<'a>(
    &'a self,
    begin: usize
) -> Dname<<&'a Octets as OctetsRef>::Range> where
    &'a Octets: OctetsRef, 

Returns the part of the name starting at the given position.

The returned name will start at the given postion and cover the remainder of the name. The position begin is provided as an index into the underlying octets sequence and must point to the beginning of a label.

Panics

The method panics if begin isn’t the index of the beginning of a label or is out of bounds.

pub fn range_to<'a>(
    &'a self,
    end: usize
) -> RelativeDname<<&'a Octets as OctetsRef>::Range> where
    &'a Octets: OctetsRef, 

Returns the part of the name ending at the given position.

The returned name will start at beginning of the name and continue until just before the given postion. The position end is considered as an index into the underlying octets sequence and must point to the beginning of a label.

Panics

The method panics if end is not the beginning of a label or is out of bounds. Because the returned domain name is relative, the method will also panic if the end is equal to the length of the name.

impl<Octets: AsRef<[u8]>> Dname<Octets>

pub fn split_at(self, mid: usize) -> (RelativeDname<Octets>, Self) where
    &'a Octets: OctetsRef<Range = Octets>, 

Splits the name into two at the given position.

Returns a pair of the left and right part of the split name.

Panics

The method will panic if mid is not the index of the beginning of a label or if it is out of bounds.

pub fn split_to(&mut self, mid: usize) -> RelativeDname<Octets> where
    &'a Octets: OctetsRef<Range = Octets>, 

Splits the name into two at the given position.

Afterwards, self will contain the name starting at the position while the name ending right before it will be returned.

Panics

The method will panic if mid is not the start of a new label or is out of bounds.

pub fn truncate(self, len: usize) -> RelativeDname<Octets> where
    Octets: OctetsExt, 

Truncates the name before len.

Because truncating converts the name into a relative name, the method consumes self.

Panics

The method will panic if len is not the index of a new label or if it is out of bounds.

pub fn split_first(&mut self) -> Option<RelativeDname<Octets>> where
    &'a Octets: OctetsRef<Range = Octets>, 

Splits off the first label.

If this name is longer than just the root label, returns the first label as a relative name and removes it from the name itself. If the name is only the root label, returns None and does nothing.

pub fn parent(&mut self) -> bool where
    &'a Octets: OctetsRef<Range = Octets>, 

Reduces the name to the parent of the current name.

If the name consists of the root label only, returns false and does nothing. Otherwise, drops the first label and returns true.

pub fn strip_suffix<N: ToDname + ?Sized>(
    self,
    base: &N
) -> Result<RelativeDname<Octets>, Self> where
    Octets: OctetsExt, 

Strips the suffix base from the domain name.

If base is indeed a suffix, returns a relative domain name with the remainder of the name. Otherwise, returns an error with an unmodified self.

Trait Implementations

impl<Octets: AsRef<T> + ?Sized, T: ?Sized> AsRef<T> for Dname<Octets>

fn as_ref(&self) -> &T

Performs the conversion.

impl<Octets: ?Sized, N: ?Sized> CanonicalOrd<N> for Dname<Octets> where
    Octets: AsRef<[u8]>,
    N: ToDname, 

fn canonical_cmp(&self, other: &N) -> Ordering

Returns the canonical ordering between self and other.

#[must_use]fn canonical_lt(&self, other: &Rhs) -> bool

Returns whether self is canonically less than other.

#[must_use]fn canonical_le(&self, other: &Rhs) -> bool

Returns whether self is canonically less than or equal to other.

#[must_use]fn canonical_gt(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than other.

#[must_use]fn canonical_ge(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than or equal to other.

impl<Octets: Clone + ?Sized> Clone for Dname<Octets>

fn clone(&self) -> Dname<Octets>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Octets: AsRef<[u8]> + ?Sized> Compose for Dname<Octets>

fn compose<T: OctetsBuilder>(&self, target: &mut T) -> Result<(), ShortBuf>

Appends the concrete representation of the value to the target.

fn compose_canonical<T: OctetsBuilder>(
    &self,
    target: &mut T
) -> Result<(), ShortBuf>

Appends the canonical representation of the value to the target.

impl<Octets: AsRef<[u8]> + ?Sized> Debug for Dname<Octets>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<Octets: ?Sized> Deref for Dname<Octets>

type Target = Octets

The resulting type after dereferencing.

fn deref(&self) -> &Octets

Dereferences the value.

impl<Octets: AsRef<[u8]> + ?Sized> Display for Dname<Octets>

fn fmt(&self, f: &mut Formatter) -> Result

Formats the domain name.

This will produce the domain name in ‘common display format’ without the trailing dot.

impl<Octets: AsRef<[u8]> + ?Sized> Eq for Dname<Octets>

impl<Octets> From<Dname<Octets>> for UncertainDname<Octets>

fn from(src: Dname<Octets>) -> Self

Performs the conversion.

impl<Ref: AsRef<[u8]>> From<Dname<Ref>> for ParsedDname<Ref>

fn from(name: Dname<Ref>) -> ParsedDname<Ref>

Performs the conversion.

impl<Octets> FromStr for Dname<Octets> where
    Octets: FromBuilder,
    <Octets as FromBuilder>::Builder: EmptyBuilder, 

type Err = FromStrError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string into an absolute domain name.

The implementation assumes that the string refers to an absolute name whether it ends in a dot or not. If you need to be able to distinguish between those two cases, you can use UncertainDname instead.

impl<Octets: AsRef<[u8]> + ?Sized> Hash for Dname<Octets>

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

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<'a, Octets: ?Sized> IntoIterator for &'a Dname<Octets> where
    Octets: AsRef<[u8]>, 

type Item = &'a Label

The type of the elements being iterated over.

type IntoIter = DnameIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Octets: AsRef<[u8]> + ?Sized> Ord for Dname<Octets>

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

Returns the ordering between self and other.

Domain name order is determined according to the ‘canonical DNS name order’ as defined in section 6.1 of RFC 4034.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<Ref: OctetsRef> Parse<Ref> for Dname<Ref::Range>

fn parse(parser: &mut Parser<Ref>) -> Result<Self, ParseError>

Extracts a value from the beginning of parser.

fn skip(parser: &mut Parser<Ref>) -> Result<(), ParseError>

Skips over a value of this type at the beginning of parser.

impl<Octets: ?Sized, N: ?Sized> PartialEq<N> for Dname<Octets> where
    Octets: AsRef<[u8]>,
    N: ToDname, 

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Octets: ?Sized, N: ?Sized> PartialOrd<N> for Dname<Octets> where
    Octets: AsRef<[u8]>,
    N: ToDname, 

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

Returns the ordering between self and other.

Domain name order is determined according to the ‘canonical DNS name order’ as defined in section 6.1 of RFC 4034.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Octets: AsRef<[u8]> + ?Sized> ToDname for Dname<Octets>

fn as_flat_slice(&self) -> Option<&[u8]>

Returns an octets slice of the content if possible.

fn to_dname<Octets>(&self) -> Result<Dname<Octets>, PushError> where
    Octets: FromBuilder,
    <Octets as FromBuilder>::Builder: EmptyBuilder, 

Converts the name into a single, uncompressed name.

fn to_cow(&self) -> Dname<Cow<[u8]>>

Returns a cow of the domain name.

fn to_vec(&self) -> Dname<Vec<u8>>

Returns the domain name assembled into a Vec<u8>.

fn name_eq<N: ToDname + ?Sized>(&self, other: &N) -> bool

Tests whether self and other are equal.

fn name_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering

Returns the ordering between self and other.

fn composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering

Returns the composed name ordering.

fn lowercase_composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering

Returns the lowercase composed ordering.

fn rrsig_label_count(&self) -> u8

Returns the number of labels for the RRSIG Labels field.

impl<'a, Octets: ?Sized> ToLabelIter<'a> for Dname<Octets> where
    Octets: AsRef<[u8]>, 

type LabelIter = DnameIter<'a>

The type of the iterator over the labels.

fn iter_labels(&'a self) -> Self::LabelIter

Returns an iterator over the labels.

fn len(&self) -> usize

Returns the length in octets of the encoded name.

fn starts_with<N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool

Determines whether base is a prefix of self.

fn ends_with<N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool

Determines whether base is a suffix of self.