Struct domain::base::name::Dname

source ·
pub struct Dname<Octs: ?Sized>(_);
Expand description

An uncompressed, absolute domain name.

The type wraps an octets sequence that contains an absolute domain name in wire-format encoding. 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.

The canonical way to convert a domain name into its presentation format is using to_string or by using its Display implementation (which performs no allocations).

Implementations§

source§

impl Dname<()>

source

pub const MAX_LEN: usize = 255usize

Domain names have a maximum length of 255 octets.

source§

impl<Octs> Dname<Octs>

source

pub const unsafe fn from_octets_unchecked(octets: Octs) -> 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.

source

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

Creates a domain name from an octet sequence.

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

source

pub fn from_symbols<Sym>(symbols: Sym) -> Result<Self, FromStrError>where Octs: FromBuilder, <Octs as FromBuilder>::Builder: EmptyBuilder + FreezeBuilder<Octets = Octs> + AsRef<[u8]> + AsMut<[u8]>, Sym: IntoIterator<Item = Symbol>,

source

pub fn from_chars<C>(chars: C) -> Result<Self, FromStrError>where Octs: FromBuilder, <Octs as FromBuilder>::Builder: EmptyBuilder + FreezeBuilder<Octets = Octs> + AsRef<[u8]> + AsMut<[u8]>, C: IntoIterator<Item = char>,

Creates a domain name from a sequence of characters.

The sequence must result in a domain name in representation format. 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.

If Internationalized Domain Names are to be used, the labels already need to be in punycode-encoded form.

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.

source

pub fn scan<S: Scanner<Dname = Self>>(scanner: &mut S) -> Result<Self, S::Error>

Reads a name in presentation format from the beginning of a scanner.

source

pub fn root() -> Selfwhere Octs: 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.

source§

impl Dname<[u8]>

source

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

Creates a domain name from an octets slice.

Note that the input must be in wire format, as shown below.

Examples
use domain::base::name::Dname;
Dname::from_slice(b"\x07example\x03com");
Errors

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

source

pub fn root_slice() -> &'static Self

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

source§

impl Dname<&'static [u8]>

source

pub fn root_ref() -> Self

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

source§

impl Dname<Vec<u8>>

source

pub fn root_vec() -> Self

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

source

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

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

source§

impl Dname<Bytes>

source

pub fn root_bytes() -> Self

Creates a domain name for the root label only atop a bytes values.

source

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

Creates a domain name atop a Bytes from its string representation.

source§

impl<Octs: ?Sized> Dname<Octs>

source

pub fn as_octets(&self) -> &Octs

Returns a reference to the underlying octets sequence.

These octets contain the domain name in wire format.

source

pub fn into_octets(self) -> Octswhere Octs: Sized,

Converts the domain name into the underlying octets sequence.

source

pub fn into_relative(self) -> RelativeDname<Octs>where Octs: Sized + AsRef<[u8]> + Truncate,

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

source

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

Returns a domain name using a reference to the octets.

source

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

Returns a reference to the underlying octets slice.

The slice will contain the domain name in wire format.

source

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

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

source

pub fn make_canonical(&mut self)where Octs: AsMut<[u8]>,

Converts the domain name into its canonical form.

This will convert all octets that are upper case ASCII characters into their lower case equivalent.

source§

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

source

pub fn is_root(&self) -> bool

Returns whether the name is the root label only.

source

pub fn len(&self) -> usize

Returns the length of the domain name.

source

pub fn fmt_with_dot(&self) -> impl Display + '_

source§

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

source

pub fn iter(&self) -> DnameIter<'_>

Returns an iterator over the labels of the domain name.

source

pub fn iter_suffixes(&self) -> SuffixIter<'_, Octs>

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.

source

pub fn label_count(&self) -> usize

Returns the number of labels in the domain name.

source

pub fn first(&self) -> &Label

Returns a reference to the first label.

source

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.

source

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

Determines whether base is a prefix of self.

source

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

Determines whether base is a suffix of self.

source

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

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

source

pub fn slice(&self, range: impl RangeBounds<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.

source

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.

source

pub fn range( &self, range: impl RangeBounds<usize> ) -> RelativeDname<<Octs as Octets>::Range<'_>>where Octs: Octets,

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.

source

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

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.

source§

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

source

pub fn split( &self, mid: usize ) -> (RelativeDname<Octs::Range<'_>>, Dname<Octs::Range<'_>>)where Octs: 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.

source

pub fn truncate(self, len: usize) -> RelativeDname<Octs>where Octs: Truncate + Sized,

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.

source

pub fn split_first(&self) -> Option<(&Label, Dname<Octs::Range<'_>>)>where Octs: Octets,

Splits off the first label.

If this name is longer than just the root label, returns a pair of that label and the remaining name. If the name is only the root label, returns None.

source

pub fn parent(&self) -> Option<Dname<Octs::Range<'_>>>where Octs: Octets,

Returns the parent of the current name.

If the name consists of the root label only, returns None.

source

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

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.

source§

impl<Octs> Dname<Octs>

source

pub fn parse<'a, Src: Octets<Range<'a> = Octs> + ?Sized>( parser: &mut Parser<'a, Src> ) -> Result<Self, ParseError>

Reads a name in wire format from the beginning of a parser.

Trait Implementations§

source§

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

source§

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl<Octs: AsRef<[u8]>> AsRef<Dname<[u8]>> for Dname<Octs>

source§

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

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl<Octs> AsRef<Octs> for Dname<Octs>

source§

fn as_ref(&self) -> &Octs

Converts this type into a shared reference of the (usually inferred) input type.
source§

impl<Octs: AsRef<[u8]>> Borrow<Dname<[u8]>> for Dname<Octs>

Borrow a domain name.

Containers holding an owned Dname<_> may be queried with name over a slice. This Borrow<_> impl supports user code querying containers with compatible-but-different types like the following example:

use std::collections::HashMap;

use domain::base::Dname;

fn get_description(
    hash: &HashMap<Dname<Vec<u8>>, String>
) -> Option<&str> {
    let lookup_name: &Dname<[u8]> =
        Dname::from_slice(b"\x03www\x07example\x03com\0").unwrap();
    hash.get(lookup_name).map(|x| x.as_ref())
}
source§

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

Immutably borrows from an owned value. Read more
source§

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

source§

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

Returns the canonical ordering between self and other.
source§

fn canonical_lt(&self, other: &Rhs) -> bool

Returns whether self is canonically less than other.
source§

fn canonical_le(&self, other: &Rhs) -> bool

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

fn canonical_gt(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than other.
source§

fn canonical_ge(&self, other: &Rhs) -> bool

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

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

source§

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

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

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 with the exception of a root name which will be just a dot.

source§

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

source§

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

Converts to this type from the input type.
source§

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

source§

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

Converts to this type from the input type.
source§

impl From<Dname<SmallVec<[u8; 24]>>> for SearchList

source§

fn from(name: SearchSuffix) -> Self

Converts to this type from the input type.
source§

impl<Octs> FromStr for Dname<Octs>where Octs: FromBuilder, <Octs as FromBuilder>::Builder: EmptyBuilder + FreezeBuilder<Octets = Octs> + AsRef<[u8]> + AsMut<[u8]>,

source§

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

Parses a string into an absolute domain name.

The name needs to be formatted in representation format, i.e., as a sequence of labels separated by dots. If Internationalized Domain Name (IDN) labels are to be used, these need to be given in punycode encoded form.

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.

§

type Err = FromStrError

The associated error which can be returned from parsing.
source§

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

source§

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

Feeds this value into the given Hasher. Read more
source§

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

§

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?
source§

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value. Read more
source§

impl<Octs, SrcOcts> OctetsFrom<Dname<SrcOcts>> for Dname<Octs>where Octs: OctetsFrom<SrcOcts>,

§

type Error = <Octs as OctetsFrom<SrcOcts>>::Error

source§

fn try_octets_from(source: Dname<SrcOcts>) -> Result<Self, Self::Error>

Performs the conversion.
source§

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

source§

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.

source§

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

source§

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

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

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

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

source§

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.

1.0.0 · source§

fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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
1.0.0 · source§

fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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
source§

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

source§

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

Returns an octets slice of the content if possible. Read more
source§

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. Read more
source§

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

Converts the name into a single name in canonical form.
source§

fn compose<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target ) -> Result<(), Target::AppendError>

source§

fn compose_canonical<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target ) -> Result<(), Target::AppendError>

source§

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

Returns a cow of the domain name. Read more
source§

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

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

fn to_bytes(&self) -> Dname<Bytes>

Returns the domain name assembled into a bytes value.
source§

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

Tests whether self and other are equal. Read more
source§

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

Returns the ordering between self and other. Read more
source§

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

Returns the composed name ordering.
source§

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

Returns the lowercase composed ordering.
source§

fn rrsig_label_count(&self) -> u8

Returns the number of labels for the RRSIG Labels field. Read more
source§

impl<Octs> ToLabelIter for Dname<Octs>where Octs: AsRef<[u8]> + ?Sized,

§

type LabelIter<'a> = DnameIter<'a> where Octs: 'a

The type of the iterator over the labels. Read more
source§

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

Returns an iterator over the labels.
source§

fn compose_len(&self) -> u16

Returns the length in octets of the encoded name.
source§

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

Determines whether base is a prefix of self.
source§

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

Determines whether base is a suffix of self.
source§

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

Auto Trait Implementations§

§

impl<Octs: ?Sized> RefUnwindSafe for Dname<Octs>where Octs: RefUnwindSafe,

§

impl<Octs: ?Sized> Send for Dname<Octs>where Octs: Send,

§

impl<Octs: ?Sized> Sync for Dname<Octs>where Octs: Sync,

§

impl<Octs: ?Sized> Unpin for Dname<Octs>where Octs: Unpin,

§

impl<Octs: ?Sized> UnwindSafe for Dname<Octs>where Octs: UnwindSafe,

Blanket Implementations§

source§

impl<T> Any for Twhere T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for Twhere T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for Twhere T: ?Sized,

source§

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

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for Twhere U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<Source, Target> OctetsInto<Target> for Sourcewhere Target: OctetsFrom<Source>,

§

type Error = <Target as OctetsFrom<Source>>::Error

source§

fn try_octets_into( self ) -> Result<Target, <Source as OctetsInto<Target>>::Error>

Performs the conversion.
source§

fn octets_into(self) -> Targetwhere Self::Error: Into<Infallible>,

Performs an infallible conversion.
source§

impl<T> ToOwned for Twhere T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T> ToString for Twhere T: Display + ?Sized,

source§

default fn to_string(&self) -> String

Converts the given value to a String. Read more
source§

impl<T, U> TryFrom<U> for Twhere U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<T, U> TryInto<U> for Twhere U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

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

Performs the conversion.
source§

impl<V, T> VZip<V> for Twhere V: MultiLane<T>,

source§

fn vzip(self) -> V