Struct domain_core::bits::name::RelativeDname

pub struct RelativeDname { /* fields omitted */ }

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 Bytes value 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).

Methods

impl RelativeDname

Creation and Conversion

pub fn empty() -> Self

Creates an empty relative domain name.

Determining what this could possibly be useful for is left as an excercise to the reader.

pub fn wildcard() -> Self

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.

pub fn from_bytes(bytes: Bytes) -> Result<Self, RelativeDnameError>

Creates a relative domain name from a bytes value.

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

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

Creates a relative domain name from a byte slice.

The function will create a new bytes value from the slice’s content. If the slice does not contain a correctly encoded, relative domain name, the function will fail.

pub fn as_bytes(&self) -> &Bytes

Returns a reference to the underlying bytes value.

pub fn as_slice(&self) -> &[u8]

Returns a reference to the underlying byte slice.

pub fn into_bytes(self) -> Bytes

Converts the name into the underlying bytes value.

pub fn into_builder(self) -> DnameBuilder

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

If the underlying bytes value can be converted into a BytesMut (via its try_mut method), the builder will use that directly. Otherwise, it will create an all new BytesMut from the name’s content.

pub fn into_absolute(self) -> Dname

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

This manipulates the name itself and thus may have to copy it. If you just need an absolute name, you can perhaps use chain_root instead.

pub fn chain<N: Compose>(
    self,
    other: N
) -> Result<Chain<Self, N>, LongChainError>

Creates a domain name by concatenating self with other.

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>

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

impl RelativeDname

Working with Labels

Important traits for DnameIter<'a>

impl<'a> Iterator for DnameIter<'a> type Item = &'a Label;

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 byte of a label.

pub fn slice(&self, begin: usize, end: usize) -> Self

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 need to be the beginning of a label.

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) -> Self

Returns the part of the name starting at the given position.

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) -> Self

Returns the part of the name ending before the given position.

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_off(&mut self, mid: usize) -> Self

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

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)

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>

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

Reduces the name to its parent.

Returns whether that actually happened, since if the name is already empty it can’t.

pub fn strip_suffix<N: ToRelativeDname>(
    &mut self,
    base: &N
) -> Result<(), StripSuffixError>

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.

Methods from Deref<Target = Bytes>

pub fn len(&self) -> usize

Returns the number of bytes contained in this Bytes.

Examples

use bytes::Bytes;

let b = Bytes::from(&b"hello"[..]);
assert_eq!(b.len(), 5);

pub fn is_empty(&self) -> bool

Returns true if the Bytes has a length of 0.

Examples

use bytes::Bytes;

let b = Bytes::new();
assert!(b.is_empty());

pub fn slice(&self, begin: usize, end: usize) -> Bytes

Returns a slice of self for the index range [begin..end).

This will increment the reference count for the underlying memory and return a new Bytes handle set to the slice.

This operation is O(1).

Examples

use bytes::Bytes;

let a = Bytes::from(&b"hello world"[..]);
let b = a.slice(2, 5);

assert_eq!(&b[..], b"llo");

Panics

Requires that begin <= end and end <= self.len(), otherwise slicing will panic.

pub fn slice_from(&self, begin: usize) -> Bytes

Returns a slice of self for the index range [begin..self.len()).

This will increment the reference count for the underlying memory and return a new Bytes handle set to the slice.

This operation is O(1) and is equivalent to self.slice(begin, self.len()).

Examples

use bytes::Bytes;

let a = Bytes::from(&b"hello world"[..]);
let b = a.slice_from(6);

assert_eq!(&b[..], b"world");

Panics

Requires that begin <= self.len(), otherwise slicing will panic.

pub fn slice_to(&self, end: usize) -> Bytes

Returns a slice of self for the index range [0..end).

This will increment the reference count for the underlying memory and return a new Bytes handle set to the slice.

This operation is O(1) and is equivalent to self.slice(0, end).

Examples

use bytes::Bytes;

let a = Bytes::from(&b"hello world"[..]);
let b = a.slice_to(5);

assert_eq!(&b[..], b"hello");

Panics

Requires that end <= self.len(), otherwise slicing will panic.

pub fn slice_ref(&self, subset: &[u8]) -> Bytes

Returns a slice of self that is equivalent to the given subset.

When processing a Bytes buffer with other tools, one often gets a &[u8] which is in fact a slice of the Bytes, i.e. a subset of it. This function turns that &[u8] into another Bytes, as if one had called self.slice() with the offsets that correspond to subset.

This operation is O(1).

Examples

use bytes::Bytes;

let bytes = Bytes::from(&b"012345678"[..]);
let as_slice = bytes.as_ref();
let subset = &as_slice[2..6];
let subslice = bytes.slice_ref(&subset);
assert_eq!(&subslice[..], b"2345");

Panics

Requires that the given sub slice is in fact contained within the Bytes buffer; otherwise this function will panic.

Trait Implementations

impl Compose for RelativeDname

fn compose_len(&self) -> usize

Returns the number of bytes this value will need without compression.

fn compose<B: BufMut>(&self, buf: &mut B)

Appends the uncompressed representation of this value to buf.

impl<'a> ToLabelIter<'a> for RelativeDname

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 starts_with<N: ToLabelIter<'a>>(&'a self, base: &'a N) -> bool

Determines whether base is a prefix of self.

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

Determines whether base is a suffix of self.

impl ToRelativeDname for RelativeDname

fn to_name(&self) -> RelativeDname

Creates an uncompressed value of the domain name.

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

Returns a byte slice of the content if possible.

fn chain<N: Compose>(self, suffix: N) -> Result<Chain<Self, N>, LongChainError> where
    Self: Sized, 

Returns a chain of this name and the provided absolute name.

fn chain_root(self) -> Chain<Self, Dname> where
    Self: Sized, 

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

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

Tests whether self and other are equal.

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

Returns the ordering between self and other.

impl<'a> IntoIterator for &'a RelativeDname

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 Eq for RelativeDname

impl Clone for RelativeDname

fn clone(&self) -> RelativeDname

Returns a copy of the value.

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

Performs copy-assignment from source.

impl PartialOrd<RelativeDname> for RelativeDname

fn partial_cmp(&self, other: &Self) -> 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<N: ToRelativeDname> PartialEq<N> for RelativeDname

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 AsRef<Bytes> for RelativeDname

fn as_ref(&self) -> &Bytes

Performs the conversion.

impl AsRef<[u8]> for RelativeDname

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

Performs the conversion.

impl Ord for RelativeDname

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

impl From<RelativeDname> for UncertainDname

fn from(name: RelativeDname) -> Self

Performs the conversion.

impl Deref for RelativeDname

type Target = Bytes

The resulting type after dereferencing.

fn deref(&self) -> &Bytes

Dereferences the value.

impl Hash for RelativeDname

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 Debug for RelativeDname

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

Formats the value using the given formatter.

impl Display for RelativeDname

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

Formats the value using the given formatter.