Struct Name

pub struct Name<Octs: ?Sized>(/* private fields */);

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 NameBuilder. In addition, you can also parse it from a message. This will, however, require the name to be uncompressed. Otherwise, you would receive a ParsedName which can be converted into Name via ToName::to_name.

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

impl Name<()>

pub const MAX_LEN: usize = 255usize

Domain names have a maximum length of 255 octets.

impl<Octs> Name<Octs>

Creating Values

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.

pub fn from_octets(octets: Octs) -> Result<Self, NameError>

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.

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>,

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 UncertainName instead to be able to check.

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

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

pub fn root() -> Self

where 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.

pub fn reverse_from_addr(addr: IpAddr) -> Result<Self, PushError>

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

Creates a domain name for reverse IP address lookup.

The returned name will use the standard suffixes of in-addr.arpa. for IPv4 addresses and ip6.arpa. for IPv6.

impl Name<[u8]>

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

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::Name;
Name::from_slice(b"\x07example\x03com\x00");

Errors

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 Name<&'static [u8]>

pub fn root_ref() -> Self

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

impl Name<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 Name<Bytes>

pub fn root_bytes() -> Self

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

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

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

impl<Octs: ?Sized> Name<Octs>

Conversions

pub fn as_octets(&self) -> &Octs

Returns a reference to the underlying octets sequence.

These octets contain the domain name in wire format.

pub fn into_octets(self) -> Octs

where Octs: Sized,

Converts the domain name into the underlying octets sequence.

pub fn into_relative(self) -> RelativeName<Octs>

where Octs: Sized + AsRef<[u8]> + Truncate,

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

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

Returns a domain name using a reference to the octets.

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.

pub fn for_slice(&self) -> &Name<[u8]>

where Octs: AsRef<[u8]>,

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

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.

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

Properties

pub fn is_root(&self) -> bool

Returns whether the name is the root label only.

pub fn len(&self) -> usize

Returns the length of the domain name.

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

Returns an object that displays the name with a final dot.

The name itself displays without a final dot unless the name is the root label only. Because this means you can’t just unconditionally add a dot after the name, this method can be used to display the name always ending in a single dot.

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

Working with Labels

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

Returns an iterator over the labels of the domain name.

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.

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 + ?Sized>(&'a self, base: &'a N) -> bool

Determines whether base is a prefix of self.

pub fn ends_with<'a, N: ToLabelIter + ?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, range: impl RangeBounds<usize>) -> &RelativeName<[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) -> &Name<[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 range( &self, range: impl RangeBounds<usize>, ) -> RelativeName<<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.

pub fn range_from(&self, begin: usize) -> Name<<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.

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

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

pub fn truncate(self, len: usize) -> RelativeName<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.

pub fn split_first(&self) -> Option<(&Label, Name<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.

pub fn parent(&self) -> Option<Name<Octs::Range<'_>>>

where Octs: Octets,

Returns the parent of the current name.

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

pub fn strip_suffix<N: ToName + ?Sized>( self, base: &N, ) -> Result<RelativeName<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.

impl<Octs> Name<Octs>

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

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

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

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

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

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

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

impl<Octs> AsRef<Octs> for Name<Octs>

fn as_ref(&self) -> &Octs

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

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

Borrow a domain name.

Containers holding an owned Name<_> 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::Name;

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

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

Immutably borrows from an owned value.

impl<Octs, N> CanonicalOrd<N> for Name<Octs>

where Octs: AsRef<[u8]> + ?Sized, N: ToName + ?Sized,

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

Returns the canonical ordering between self and other.

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

Returns whether self is canonically less than other.

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

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

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

Returns whether self is canonically greater than other.

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

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

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

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

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

Formats the value using the given formatter.

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

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.

impl<L, R, Target> FlattenInto<Name<Target>> for Chain<L, R>

where L: ToRelativeName, R: ToName + FlattenInto<Name<Target>, AppendError = BuilderAppendError<Target>>, Target: FromBuilder, <Target as FromBuilder>::Builder: EmptyBuilder,

type AppendError = <<Target as FromBuilder>::Builder as OctetsBuilder>::AppendError

fn try_flatten_into(self) -> Result<Name<Target>, Self::AppendError>

impl<Octs, Target> FlattenInto<Name<Target>> for Name<Octs>

where Target: OctetsFrom<Octs>,

type AppendError = <Target as OctetsFrom<Octs>>::Error

fn try_flatten_into(self) -> Result<Name<Target>, Self::AppendError>

impl<Octs, Target> FlattenInto<Name<Target>> for ParsedName<Octs>

where Octs: Octets, Target: FromBuilder, <Target as FromBuilder>::Builder: EmptyBuilder,

type AppendError = <<Target as FromBuilder>::Builder as OctetsBuilder>::AppendError

fn try_flatten_into(self) -> Result<Name<Target>, Self::AppendError>

impl<Octets> From<Name<Octets>> for UncertainName<Octets>

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

Converts to this type from the input type.

impl<Octs: AsRef<[u8]>> From<Name<Octs>> for ParsedName<Octs>

fn from(name: Name<Octs>) -> ParsedName<Octs>

Converts to this type from the input type.

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

fn from(name: SearchSuffix) -> Self

Converts to this type from the input type.

impl<Octs> FromStr for Name<Octs>

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

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.

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

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

Feeds this value into the given Hasher.

impl<'a, Octs> IntoIterator for &'a Name<Octs>

where Octs: AsRef<[u8]> + ?Sized,

type Item = &'a Label

The type of the elements being iterated over.

type IntoIter = NameIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Octs, SrcOcts> OctetsFrom<Name<SrcOcts>> for Name<Octs>

where Octs: OctetsFrom<SrcOcts>,

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

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

Performs the conversion.

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

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.

impl<Octs, N> PartialEq<N> for Name<Octs>

where Octs: AsRef<[u8]> + ?Sized, N: ToName + ?Sized,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Octs, N> PartialOrd<N> for Name<Octs>

where Octs: AsRef<[u8]> + ?Sized, N: ToName + ?Sized,

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.

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl<Octs> ToLabelIter for Name<Octs>

where Octs: AsRef<[u8]> + ?Sized,

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

The type of the iterator over the labels.

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

Returns an iterator over the labels.

fn compose_len(&self) -> u16

Returns the length in octets of the encoded name.

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

Determines whether base is a prefix of self.

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

Determines whether base is a suffix of self.

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

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

Returns an octets slice of the content if possible.

fn try_to_name<Octets>( &self, ) -> Result<Name<Octets>, BuilderAppendError<Octets>>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,

Converts the name into a single, uncompressed name.

fn to_name<Octets>(&self) -> Name<Octets>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: OctetsBuilder<AppendError = Infallible> + EmptyBuilder,

Converts the name into a single, uncompressed name.

fn try_to_canonical_name<Octets>( &self, ) -> Result<Name<Octets>, BuilderAppendError<Octets>>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,

Converts the name into a single name in canonical form.

fn to_canonical_name<Octets>(&self) -> Name<Octets>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: OctetsBuilder<AppendError = Infallible> + EmptyBuilder,

Converts the name into a single name in canonical form.

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

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

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

Returns a cow of the domain name.

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

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

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

Returns the domain name assembled into a bytes value.

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

Tests whether self and other are equal.

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

Returns the ordering between self and other.

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

Returns the composed name ordering.

fn lowercase_composed_cmp<N: ToName + ?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<Octs: AsRef<[u8]> + ?Sized> Eq for Name<Octs>