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<Octs> Dname<Octs>
impl<Octs> Dname<Octs>
sourcepub const unsafe fn from_octets_unchecked(octets: Octs) -> Self
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.
sourcepub fn from_octets(octets: Octs) -> Result<Self, DnameError>where
Octs: AsRef<[u8]>,
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.
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>,
sourcepub 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>,
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.
sourcepub fn scan<S: Scanner<Dname = Self>>(scanner: &mut S) -> Result<Self, S::Error>
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.
sourcepub fn root() -> Selfwhere
Octs: From<&'static [u8]>,
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]>
impl Dname<[u8]>
sourcepub fn from_slice(slice: &[u8]) -> Result<&Self, DnameError>
pub fn from_slice(slice: &[u8]) -> Result<&Self, DnameError>
sourcepub fn root_slice() -> &'static Self
pub fn root_slice() -> &'static Self
Creates a domain name for the root label only atop an octets slice.
source§impl Dname<Vec<u8>>
impl Dname<Vec<u8>>
sourcepub fn vec_from_str(s: &str) -> Result<Self, FromStrError>
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>
impl Dname<Bytes>
sourcepub fn root_bytes() -> Self
pub fn root_bytes() -> Self
Creates a domain name for the root label only atop a bytes values.
sourcepub fn bytes_from_str(s: &str) -> Result<Self, FromStrError>
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>
impl<Octs: ?Sized> Dname<Octs>
sourcepub fn as_octets(&self) -> &Octs
pub fn as_octets(&self) -> &Octs
Returns a reference to the underlying octets sequence.
These octets contain the domain name in wire format.
sourcepub fn into_octets(self) -> Octswhere
Octs: Sized,
pub fn into_octets(self) -> Octswhere Octs: Sized,
Converts the domain name into the underlying octets sequence.
sourcepub fn into_relative(self) -> RelativeDname<Octs>where
Octs: Sized + AsRef<[u8]> + Truncate,
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.
sourcepub fn as_slice(&self) -> &[u8] ⓘwhere
Octs: AsRef<[u8]>,
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.
sourcepub fn for_slice(&self) -> &Dname<[u8]>where
Octs: AsRef<[u8]>,
pub fn for_slice(&self) -> &Dname<[u8]>where Octs: AsRef<[u8]>,
Returns a domain name for the octets slice of the content.
sourcepub fn make_canonical(&mut self)where
Octs: AsMut<[u8]>,
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>
impl<Octs: AsRef<[u8]> + ?Sized> Dname<Octs>
sourcepub fn iter_suffixes(&self) -> SuffixIter<'_, Octs>
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.
sourcepub fn label_count(&self) -> usize
pub fn label_count(&self) -> usize
Returns the number of labels in the domain name.
sourcepub fn last(&self) -> &'static 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.
sourcepub fn starts_with<'a, N: ToLabelIter + ?Sized>(&'a self, base: &'a N) -> bool
pub fn starts_with<'a, N: ToLabelIter + ?Sized>(&'a self, base: &'a N) -> bool
Determines whether base
is a prefix of self
.
sourcepub fn ends_with<'a, N: ToLabelIter + ?Sized>(&'a self, base: &'a N) -> bool
pub fn ends_with<'a, N: ToLabelIter + ?Sized>(&'a self, base: &'a N) -> bool
Determines whether base
is a suffix of self
.
sourcepub fn is_label_start(&self, index: usize) -> bool
pub fn is_label_start(&self, index: usize) -> bool
Returns whether an index points to the first byte of a non-root label.
sourcepub fn slice(&self, range: impl RangeBounds<usize>) -> &RelativeDname<[u8]>
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.
sourcepub fn slice_from(&self, begin: usize) -> &Dname<[u8]>
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.
sourcepub fn range(
&self,
range: impl RangeBounds<usize>
) -> RelativeDname<<Octs as Octets>::Range<'_>>where
Octs: Octets,
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.
sourcepub fn range_from(&self, begin: usize) -> Dname<<Octs as Octets>::Range<'_>>where
Octs: Octets,
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>
impl<Octs: AsRef<[u8]> + ?Sized> Dname<Octs>
sourcepub fn split(
&self,
mid: usize
) -> (RelativeDname<Octs::Range<'_>>, Dname<Octs::Range<'_>>)where
Octs: Octets,
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.
sourcepub fn truncate(self, len: usize) -> RelativeDname<Octs>where
Octs: Truncate + Sized,
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.
sourcepub fn split_first(&self) -> Option<(&Label, Dname<Octs::Range<'_>>)>where
Octs: Octets,
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
.
sourcepub fn parent(&self) -> Option<Dname<Octs::Range<'_>>>where
Octs: Octets,
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
.
sourcepub fn strip_suffix<N: ToDname + ?Sized>(
self,
base: &N
) -> Result<RelativeDname<Octs>, Self>where
Octs: Truncate + Sized,
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
.
Trait Implementations§
source§impl<Octs: AsRef<[u8]>> Borrow<Dname<[u8]>> for Dname<Octs>
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§impl<Octs, N> CanonicalOrd<N> for Dname<Octs>where
Octs: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
impl<Octs, N> CanonicalOrd<N> for Dname<Octs>where Octs: AsRef<[u8]> + ?Sized, N: ToDname + ?Sized,
source§fn canonical_cmp(&self, other: &N) -> Ordering
fn canonical_cmp(&self, other: &N) -> Ordering
self
and other
.source§fn canonical_lt(&self, other: &Rhs) -> bool
fn canonical_lt(&self, other: &Rhs) -> bool
self
is canonically less than other
.source§fn canonical_le(&self, other: &Rhs) -> bool
fn canonical_le(&self, other: &Rhs) -> bool
self
is canonically less than or equal to other
.source§fn canonical_gt(&self, other: &Rhs) -> bool
fn canonical_gt(&self, other: &Rhs) -> bool
self
is canonically greater than other
.source§fn canonical_ge(&self, other: &Rhs) -> bool
fn canonical_ge(&self, other: &Rhs) -> bool
self
is canonically greater than or equal to other
.source§impl<Octets> From<Dname<Octets>> for UncertainDname<Octets>
impl<Octets> From<Dname<Octets>> for UncertainDname<Octets>
source§impl<Octs: AsRef<[u8]>> From<Dname<Octs>> for ParsedDname<Octs>
impl<Octs: AsRef<[u8]>> From<Dname<Octs>> for ParsedDname<Octs>
source§fn from(name: Dname<Octs>) -> ParsedDname<Octs>
fn from(name: Dname<Octs>) -> ParsedDname<Octs>
source§impl From<Dname<SmallVec<[u8; 24]>>> for SearchList
impl From<Dname<SmallVec<[u8; 24]>>> for SearchList
source§fn from(name: SearchSuffix) -> Self
fn from(name: SearchSuffix) -> Self
source§impl<Octs> FromStr for Dname<Octs>where
Octs: FromBuilder,
<Octs as FromBuilder>::Builder: EmptyBuilder + FreezeBuilder<Octets = Octs> + AsRef<[u8]> + AsMut<[u8]>,
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>
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
type Err = FromStrError
source§impl<Octs, SrcOcts> OctetsFrom<Dname<SrcOcts>> for Dname<Octs>where
Octs: OctetsFrom<SrcOcts>,
impl<Octs, SrcOcts> OctetsFrom<Dname<SrcOcts>> for Dname<Octs>where Octs: OctetsFrom<SrcOcts>,
type Error = <Octs as OctetsFrom<SrcOcts>>::Error
source§impl<Octs, N> PartialEq<N> for Dname<Octs>where
Octs: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
impl<Octs, N> PartialEq<N> for Dname<Octs>where Octs: AsRef<[u8]> + ?Sized, N: ToDname + ?Sized,
source§impl<Octs, N> PartialOrd<N> for Dname<Octs>where
Octs: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
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>
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 le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moresource§impl<Octs: AsRef<[u8]> + ?Sized> ToDname for Dname<Octs>
impl<Octs: AsRef<[u8]> + ?Sized> ToDname for Dname<Octs>
source§fn as_flat_slice(&self) -> Option<&[u8]>
fn as_flat_slice(&self) -> Option<&[u8]>
source§fn to_dname<Octets>(&self) -> Result<Dname<Octets>, PushError>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: EmptyBuilder,
fn to_dname<Octets>(&self) -> Result<Dname<Octets>, PushError>where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,
source§fn to_canonical_dname<Octets>(&self) -> Result<Dname<Octets>, PushError>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: EmptyBuilder,
fn to_canonical_dname<Octets>(&self) -> Result<Dname<Octets>, PushError>where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,
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>
source§fn composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
fn composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
source§fn lowercase_composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
fn lowercase_composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
source§fn rrsig_label_count(&self) -> u8
fn rrsig_label_count(&self) -> u8
source§impl<Octs> ToLabelIter for Dname<Octs>where
Octs: AsRef<[u8]> + ?Sized,
impl<Octs> ToLabelIter for Dname<Octs>where Octs: AsRef<[u8]> + ?Sized,
§type LabelIter<'a> = DnameIter<'a>
where
Octs: 'a
type LabelIter<'a> = DnameIter<'a> where Octs: 'a
source§fn iter_labels(&self) -> Self::LabelIter<'_>
fn iter_labels(&self) -> Self::LabelIter<'_>
source§fn compose_len(&self) -> u16
fn compose_len(&self) -> u16
source§fn starts_with<N: ToLabelIter + ?Sized>(&self, base: &N) -> bool
fn starts_with<N: ToLabelIter + ?Sized>(&self, base: &N) -> bool
base
is a prefix of self
.