pub struct Dname<Octets: ?Sized>(_);
Expand description
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
sourceimpl<Octets> Dname<Octets>
impl<Octets> Dname<Octets>
sourcepub const unsafe fn from_octets_unchecked(octets: Octets) -> Self
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.
sourcepub fn from_octets(octets: Octets) -> Result<Self, DnameError>where
Octets: AsRef<[u8]>,
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.
sourcepub fn from_chars<C>(chars: C) -> Result<Self, FromStrError>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,
C: IntoIterator<Item = char>,
pub fn from_chars<C>(chars: C) -> Result<Self, FromStrError>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,
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.
sourcepub fn root() -> Selfwhere
Octets: From<&'static [u8]>,
pub fn root() -> Selfwhere
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
.
sourceimpl Dname<[u8]>
impl Dname<[u8]>
sourcepub fn from_slice(slice: &[u8]) -> Result<&Self, DnameError>
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.
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.
sourceimpl 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.
sourceimpl 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.
sourceimpl<Octets: ?Sized> Dname<Octets>
impl<Octets: ?Sized> Dname<Octets>
sourcepub fn into_octets(self) -> Octetswhere
Octets: Sized,
pub fn into_octets(self) -> Octetswhere
Octets: Sized,
Converts the domain name into the underlying octets sequence.
sourcepub fn into_relative(self) -> RelativeDname<Octets>where
Octets: Sized + OctetsExt,
pub fn into_relative(self) -> RelativeDname<Octets>where
Octets: Sized + OctetsExt,
Converts the name into a relative name by dropping the root label.
sourceimpl<Octets: AsRef<[u8]> + ?Sized> Dname<Octets>
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>
.
sourceimpl<Octets: AsRef<[u8]> + ?Sized> Dname<Octets>
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.
sourcepub fn iter(&self) -> DnameIter<'_>ⓘNotable traits for DnameIter<'a>impl<'a> Iterator for DnameIter<'a> type Item = &'a Label;
pub fn iter(&self) -> DnameIter<'_>ⓘNotable traits for DnameIter<'a>impl<'a> Iterator for DnameIter<'a> type Item = &'a Label;
Returns an iterator over the labels of the domain name.
sourcepub fn iter_suffixes(&self) -> SuffixIter<&Octets>
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.
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<'a> + ?Sized>(
&'a self,
base: &'a N
) -> bool
pub fn starts_with<'a, N: ToLabelIter<'a> + ?Sized>(
&'a self,
base: &'a N
) -> bool
Determines whether base
is a prefix of self
.
sourcepub fn ends_with<'a, N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool
pub fn ends_with<'a, N: ToLabelIter<'a> + ?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, begin: usize, end: usize) -> &RelativeDname<[u8]>
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.
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 slice_to(&self, end: usize) -> &RelativeDname<[u8]>
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.
sourcepub fn range<'a>(
&'a self,
begin: usize,
end: usize
) -> RelativeDname<<&'a Octets as OctetsRef>::Range>where
&'a Octets: OctetsRef,
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.
sourcepub fn range_from<'a>(
&'a self,
begin: usize
) -> Dname<<&'a Octets as OctetsRef>::Range>where
&'a Octets: OctetsRef,
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.
sourcepub fn range_to<'a>(
&'a self,
end: usize
) -> RelativeDname<<&'a Octets as OctetsRef>::Range>where
&'a Octets: OctetsRef,
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.
sourceimpl<Octets: AsRef<[u8]>> Dname<Octets>
impl<Octets: AsRef<[u8]>> Dname<Octets>
sourcepub fn split_at(self, mid: usize) -> (RelativeDname<Octets>, Self)where
for<'a> &'a Octets: OctetsRef<Range = Octets>,
pub fn split_at(self, mid: usize) -> (RelativeDname<Octets>, Self)where
for<'a> &'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.
sourcepub fn split_to(&mut self, mid: usize) -> RelativeDname<Octets>where
for<'a> &'a Octets: OctetsRef<Range = Octets>,
pub fn split_to(&mut self, mid: usize) -> RelativeDname<Octets>where
for<'a> &'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.
sourcepub fn truncate(self, len: usize) -> RelativeDname<Octets>where
Octets: OctetsExt,
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.
sourcepub fn split_first(&mut self) -> Option<RelativeDname<Octets>>where
for<'a> &'a Octets: OctetsRef<Range = Octets>,
pub fn split_first(&mut self) -> Option<RelativeDname<Octets>>where
for<'a> &'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.
sourcepub fn parent(&mut self) -> boolwhere
for<'a> &'a Octets: OctetsRef<Range = Octets>,
pub fn parent(&mut self) -> boolwhere
for<'a> &'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
.
sourcepub fn strip_suffix<N: ToDname + ?Sized>(
self,
base: &N
) -> Result<RelativeDname<Octets>, Self>where
Octets: OctetsExt,
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
sourceimpl<Octets, N> CanonicalOrd<N> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
impl<Octets, N> CanonicalOrd<N> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
sourcefn canonical_cmp(&self, other: &N) -> Ordering
fn canonical_cmp(&self, other: &N) -> Ordering
Returns the canonical ordering between self
and other
.
sourcefn canonical_lt(&self, other: &Rhs) -> bool
fn canonical_lt(&self, other: &Rhs) -> bool
Returns whether self
is canonically less than other
.
sourcefn canonical_le(&self, other: &Rhs) -> bool
fn canonical_le(&self, other: &Rhs) -> bool
Returns whether self
is canonically less than or equal to other
.
sourcefn canonical_gt(&self, other: &Rhs) -> bool
fn canonical_gt(&self, other: &Rhs) -> bool
Returns whether self
is canonically greater than other
.
sourcefn canonical_ge(&self, other: &Rhs) -> bool
fn canonical_ge(&self, other: &Rhs) -> bool
Returns whether self
is canonically greater than or equal to other
.
sourceimpl<Octets: AsRef<[u8]> + ?Sized> Compose for Dname<Octets>
impl<Octets: AsRef<[u8]> + ?Sized> Compose for Dname<Octets>
sourcefn compose<T: OctetsBuilder + AsMut<[u8]>>(
&self,
target: &mut T
) -> Result<(), ShortBuf>
fn compose<T: OctetsBuilder + AsMut<[u8]>>(
&self,
target: &mut T
) -> Result<(), ShortBuf>
Appends the concrete representation of the value to the target. Read more
sourcefn compose_canonical<T: OctetsBuilder + AsMut<[u8]>>(
&self,
target: &mut T
) -> Result<(), ShortBuf>
fn compose_canonical<T: OctetsBuilder + AsMut<[u8]>>(
&self,
target: &mut T
) -> Result<(), ShortBuf>
Appends the canonical representation of the value to the target. Read more
sourceimpl<'de, Octets> Deserialize<'de> for Dname<Octets>where
Octets: FromBuilder + DeserializeOctets<'de>,
<Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,
impl<'de, Octets> Deserialize<'de> for Dname<Octets>where
Octets: FromBuilder + DeserializeOctets<'de>,
<Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,
sourcefn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>
Deserialize this value from the given Serde deserializer. Read more
sourceimpl<Octets> From<Dname<Octets>> for UncertainDname<Octets>
impl<Octets> From<Dname<Octets>> for UncertainDname<Octets>
sourceimpl<Ref: AsRef<[u8]>> From<Dname<Ref>> for ParsedDname<Ref>
impl<Ref: AsRef<[u8]>> From<Dname<Ref>> for ParsedDname<Ref>
sourcefn from(name: Dname<Ref>) -> ParsedDname<Ref>
fn from(name: Dname<Ref>) -> ParsedDname<Ref>
Converts to this type from the input type.
sourceimpl From<Dname<SmallVec<[u8; 24]>>> for SearchList
Available on crate feature resolv
only.
impl From<Dname<SmallVec<[u8; 24]>>> for SearchList
resolv
only.sourcefn from(name: SearchSuffix) -> Self
fn from(name: SearchSuffix) -> Self
Converts to this type from the input type.
sourceimpl<Octets> FromStr for Dname<Octets>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,
impl<Octets> FromStr for Dname<Octets>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,
sourcefn 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 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
The associated error which can be returned from parsing.
sourceimpl<Octets, SrcOctets> OctetsFrom<Dname<SrcOctets>> for Dname<Octets>where
Octets: OctetsFrom<SrcOctets>,
impl<Octets, SrcOctets> OctetsFrom<Dname<SrcOctets>> for Dname<Octets>where
Octets: OctetsFrom<SrcOctets>,
sourcefn octets_from(source: Dname<SrcOctets>) -> Result<Self, ShortBuf>
fn octets_from(source: Dname<SrcOctets>) -> Result<Self, ShortBuf>
Performs the conversion.
sourceimpl<Octets: AsRef<[u8]> + ?Sized> Ord for Dname<Octets>
impl<Octets: AsRef<[u8]> + ?Sized> Ord for Dname<Octets>
sourcefn cmp(&self, other: &Self) -> Ordering
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.
sourceimpl<Octets, N> PartialEq<N> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
impl<Octets, N> PartialEq<N> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
sourceimpl<Octets, N> PartialOrd<N> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
impl<Octets, N> PartialOrd<N> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
N: ToDname + ?Sized,
sourcefn 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 · sourcefn lt(&self, other: &Rhs) -> bool
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 · sourcefn le(&self, other: &Rhs) -> bool
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
sourceimpl<Octets: AsRef<[u8]> + ?Sized> ToDname for Dname<Octets>
impl<Octets: AsRef<[u8]> + ?Sized> ToDname for Dname<Octets>
sourcefn as_flat_slice(&self) -> Option<&[u8]>
fn as_flat_slice(&self) -> Option<&[u8]>
Returns an octets slice of the content if possible. Read more
sourcefn to_dname<Octets>(&self) -> Result<Dname<Octets>, PushError>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: OctetsBuilder + EmptyBuilder,
fn to_dname<Octets>(&self) -> Result<Dname<Octets>, PushError>where
Octets: FromBuilder,
<Octets as FromBuilder>::Builder: OctetsBuilder + EmptyBuilder,
Converts the name into a single, uncompressed name. Read more
sourcefn name_eq<N: ToDname + ?Sized>(&self, other: &N) -> bool
fn name_eq<N: ToDname + ?Sized>(&self, other: &N) -> bool
Tests whether self
and other
are equal. Read more
sourcefn name_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
fn name_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
Returns the ordering between self
and other
. Read more
sourcefn composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
fn composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
Returns the composed name ordering.
sourcefn lowercase_composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
fn lowercase_composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering
Returns the lowercase composed ordering.
sourcefn rrsig_label_count(&self) -> u8
fn rrsig_label_count(&self) -> u8
Returns the number of labels for the RRSIG Labels field. Read more
sourceimpl<'a, Octets> ToLabelIter<'a> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
impl<'a, Octets> ToLabelIter<'a> for Dname<Octets>where
Octets: AsRef<[u8]> + ?Sized,
sourcefn iter_labels(&'a self) -> Self::LabelIter
fn iter_labels(&'a self) -> Self::LabelIter
Returns an iterator over the labels.
sourcefn starts_with<N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool
fn starts_with<N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool
Determines whether base
is a prefix of self
.
impl<Octets: AsRef<[u8]> + ?Sized> Eq for Dname<Octets>
Auto Trait Implementations
impl<Octets: ?Sized> RefUnwindSafe for Dname<Octets>where
Octets: RefUnwindSafe,
impl<Octets: ?Sized> Send for Dname<Octets>where
Octets: Send,
impl<Octets: ?Sized> Sync for Dname<Octets>where
Octets: Sync,
impl<Octets: ?Sized> Unpin for Dname<Octets>where
Octets: Unpin,
impl<Octets: ?Sized> UnwindSafe for Dname<Octets>where
Octets: UnwindSafe,
Blanket Implementations
sourceimpl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
const: unstable · sourcefn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
Mutably borrows from an owned value. Read more
sourceimpl<Source, Target> OctetsInto<Target> for Sourcewhere
Target: OctetsFrom<Source>,
impl<Source, Target> OctetsInto<Target> for Sourcewhere
Target: OctetsFrom<Source>,
sourcefn octets_into(self) -> Result<Target, ShortBuf>
fn octets_into(self) -> Result<Target, ShortBuf>
Performs the conversion.