Struct domain::base::RelativeDname

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

An uncompressed, relative domain name.

A relative domain name is one that doesn’t end with the root label. As the name suggests, it is relative to some other domain name. This type wraps a octets sequence containing such a relative name similarly to the way Dname wraps an absolute one. In fact, it behaves very similarly to Dname taking into account differences when slicing and dicing names.

RelativeDname guarantees that the name is at most 254 bytes long. As the length limit for a domain name is actually 255 bytes, this means that you can always safely turn a RelativeDname into a Dname by adding the root label (which is exactly one byte long).

Implementations

impl<Octets> RelativeDname<Octets>

Creating Values

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

Creates a relative domain name from octets without checking.

Since the content of the octets sequence can be anything, really, this is an unsafe function.

Safety

The octets sequence passed via octets must contain a correctly encoded relative domain name. It must be at most 254 octets long. There must be no root labels anywhere in the name.

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

Creates a relative domain name from an octets sequence.

This checks that octets contains a properly encoded relative domain name and fails if it doesn’t.

pub fn empty() -> Selfwhere
    Octets: From<&'static [u8]>,

Creates an empty relative domain name.

pub fn wildcard() -> Selfwhere
    Octets: From<&'static [u8]>,

Creates a relative domain name representing the wildcard label.

The wildcard label is intended to match any label. There are special rules for names with wildcard labels. Note that the comparison traits implemented for domain names do not consider wildcards and treat them as regular labels.

impl RelativeDname<[u8]>

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

Creates a relative domain name from an octet slice.

pub fn empty_slice() -> &'static Self

Returns an empty relative name atop a unsized slice.

pub fn wildcard_slice() -> &'static Self

impl RelativeDname<&'static [u8]>

pub fn empty_ref() -> Self

Creates an empty relative name atop a slice reference.

pub fn wildcard_ref() -> Self

Creates a wildcard relative name atop a slice reference.

impl RelativeDname<Vec<u8>>

pub fn empty_vec() -> Self

Creates an empty relative name atop a Vec<u8>.

pub fn wildcard_vec() -> Self

Creates a wildcard relative name atop a Vec<u8>.

impl RelativeDname<Bytes>

pub fn empty_bytes() -> Self

Creates an empty relative name atop a bytes value.

pub fn wildcard_bytes() -> Self

Creates a wildcard relative name atop a bytes value.

impl<Octets: ?Sized> RelativeDname<Octets>

Conversions

pub fn as_octets(&self) -> &Octets

Returns a reference to the underlying octets.

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

Converts the name into the underlying octets.

pub fn for_ref(&self) -> RelativeDname<&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 an octets slice with the content of the name.

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

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

impl<Octets> RelativeDname<Octets>

pub fn into_builder(self) -> DnameBuilder<<Octets as IntoBuilder>::Builder>where
    Octets: IntoBuilder,

Converts the name into a domain name builder for appending data.

This method is only available for octets sequences that have an associated octets builder such as Vec<u8> or Bytes.

pub fn into_absolute(
    self
) -> Result<Dname<<<Octets as IntoBuilder>::Builder as OctetsBuilder>::Octets>, PushError>where
    Octets: IntoBuilder,
    <Octets as IntoBuilder>::Builder: AsMut<[u8]>,

Converts the name into an absolute name by appending the root label.

This manipulates the name itself and thus is only available for octets sequences that can be converted into an octets builer and back such as Vec<u8>.

pub fn chain<N: ToEitherDname>(
    self,
    other: N
) -> Result<Chain<Self, N>, LongChainError>where
    Octets: AsRef<[u8]>,

Chains another name to the end of this name.

Depending on whether other is an absolute or relative domain name, the resulting name will behave like an absolute or relative name.

The method will fail if the combined length of the two names is greater than the size limit of 255. Note that in this case you will loose both self and other, so it might be worthwhile to check first.

pub fn chain_root(self) -> Chain<Self, Dname<&'static [u8]>>where
    Octets: AsRef<[u8]>,

Creates an absolute name by chaining the root label to it.

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

Working with Labels

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

Returns an iterator over the labels of the domain name.

pub fn label_count(&self) -> usize

Returns the number of labels in the name.

pub fn first(&self) -> Option<&Label>

Returns a reference to the first label if the name isn’t empty.

pub fn last(&self) -> Option<&Label>

Returns a reference to the last label if the name isn’t empty.

pub fn ndots(&self) -> usize

Returns the number of dots in the string representation of the name.

Specifically, returns a value equal to the number of labels minus one, except for an empty name where it returns a zero, also.

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

Determines whether base is a prefix of self.

pub fn ends_with<'a, N: ToLabelIter<'a>>(&'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 octet of a label.

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

Returns a 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 beginning of a label or is out of bounds.

pub fn slice_from(&self, begin: usize) -> &RelativeDname<[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 the position is not the beginning of a label or is beyond the end of the name.

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

Returns the part of the name ending before 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 the position is not the beginning of a label or is beyond the end of the name.

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

Returns a 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 beginning of a label or is out of bounds.

pub fn range_from<'a>(
    &'a self,
    begin: usize
) -> RelativeDname<<&'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 the position is not the beginning of a label or is beyond the end of the name.

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 before 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 the position is not the beginning of a label or is beyond the end of the name.

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

pub fn split_off(&mut self, mid: usize) -> Selfwhere
    for<'a> &'a Octets: OctetsRef<Range = Octets>,

Splits the name into two at the given position.

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

Panics

The method panics if the position is not the beginning of a label or is beyond the end of the name.

pub fn split_to(&mut self, mid: usize) -> Selfwhere
    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 panics if the position is not the beginning of a label or is beyond the end of the name.

pub fn truncate(&mut self, len: usize)where
    Octets: OctetsExt,

Truncates the name to the given length.

Panics

The method panics if the position is not the beginning of a label or is beyond the end of the name.

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

Splits off the first label.

If there is at least one label in the name, returns the first label as a relative domain name with exactly one label and makes self contain the domain name starting after that first label. If the name is empty, returns None.

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

Reduces the name to its parent.

Returns whether that actually happened, since an empty name doesn’t have a parent.

pub fn strip_suffix<N: ToRelativeDname>(
    &mut self,
    base: &N
) -> Result<(), StripSuffixError>where
    for<'a> &'a Octets: OctetsRef<Range = Octets>,

Strips the suffix base from the domain name.

This will fail if base isn’t actually a suffix, i.e., if ends_with doesn’t return true.

Trait Implementations

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

fn as_ref(&self) -> &T

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

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

fn clone(&self) -> RelativeDname<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 RelativeDname<Octets>

fn compose<T: OctetsBuilder + AsMut<[u8]>>(
    &self,
    target: &mut T
) -> Result<(), ShortBuf>

Appends the concrete representation of the value to the target.

fn compose_canonical<T: OctetsBuilder + AsMut<[u8]>>(
    &self,
    target: &mut T
) -> Result<(), ShortBuf>

Appends the canonical representation of the value to the target.

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

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

Formats the value using the given formatter.

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

type Target = Octets

The resulting type after dereferencing.

fn deref(&self) -> &Octets

Dereferences the value.

impl<'de, Octets> Deserialize<'de> for RelativeDname<Octets>where
    Octets: FromBuilder + DeserializeOctets<'de>,
    <Octets as FromBuilder>::Builder: EmptyBuilder + AsMut<[u8]>,

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

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

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

Formats the value using the given formatter.

impl<Octets> From<RelativeDname<Octets>> for UncertainDname<Octets>

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

Converts to this type from the input type.

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

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

Feeds this value into the given Hasher.

impl<'a, Octets> IntoIterator for &'a RelativeDname<Octets>where
    Octets: 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?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Octets, SrcOctets> OctetsFrom<RelativeDname<SrcOctets>> for RelativeDname<Octets>where
    Octets: OctetsFrom<SrcOctets>,

fn octets_from(source: RelativeDname<SrcOctets>) -> Result<Self, ShortBuf>

Performs the conversion.

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

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

This method returns an Ordering between self and other.

impl<Octets, N> PartialEq<N> for RelativeDname<Octets>where
    Octets: AsRef<[u8]> + ?Sized,
    N: ToRelativeDname + ?Sized,

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

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

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.

impl<Octets, N> PartialOrd<N> for RelativeDname<Octets>where
    Octets: AsRef<[u8]> + ?Sized,
    N: ToRelativeDname + ?Sized,

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

This method returns an ordering between self and other values if one exists.

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

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

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

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

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

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

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> Serialize for RelativeDname<Octets>where
    Octets: AsRef<[u8]> + SerializeOctets,

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

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

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.

impl<Octets: AsRef<[u8]> + ?Sized> ToRelativeDname for RelativeDname<Octets>

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

Returns a byte slice of the content if possible.

fn is_empty(&self) -> bool

Returns whether the name is empty.

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

Converts the name into a single, continous name.

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

Returns a cow of the relative domain name.

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

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

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

Returns the domain name assembled into a bytes value.

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

Tests whether self and other are equal.

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

Returns the ordering between self and other.

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