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() -> Self where
    Octets: From<&'static [u8]>, 

Creates an empty relative domain name.

pub fn wildcard() -> Self where
    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<Octets: ?Sized> RelativeDname<Octets>

Conversions

pub fn as_octets(&self) -> &Octets

Returns a reference to the underlying octets.

pub fn into_octets(self) -> Octets where
    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 IntoOctets>::Octets>, PushError> where
    Octets: IntoBuilder,
    <Octets as IntoBuilder>::Builder: IntoOctets, 

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) -> Self where
    &'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) -> Self where
    &'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
    &'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) -> bool where
    &'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
    &'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

Performs the conversion.

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>(&self, target: &mut T) -> Result<(), ShortBuf>

Appends the concrete representation of the value to the target.

fn compose_canonical<T: OctetsBuilder>(
    &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<Octets: AsRef<[u8]> + ?Sized> Display for RelativeDname<Octets>

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

Formats the value using the given formatter.

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

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

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

Performs the conversion.

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

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

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

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

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: AsRef<[u8]> + ?Sized> Ord for RelativeDname<Octets>

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

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

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

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

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

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

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

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

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

#[must_use]fn lt(&self, other: &Rhs) -> bool

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

#[must_use]fn le(&self, other: &Rhs) -> bool

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

#[must_use]fn gt(&self, other: &Rhs) -> bool

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

#[must_use]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<'a, Octets: ?Sized> ToLabelIter<'a> for RelativeDname<Octets> where
    Octets: AsRef<[u8]>, 

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 chain<N: ToEitherDname>(
    self,
    suffix: N
) -> Result<Chain<Self, N>, LongChainError> where
    Self: Sized, 

Returns a chain of this name and the provided name.

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

Returns the absolute name by chaining it with the root label.

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.