Struct RelativeName

pub struct RelativeName<Octs: ?Sized>(/* private fields */);

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 Name wraps an absolute one. In fact, it behaves very similarly to Name taking into account differences when slicing and dicing names.

RelativeName 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 RelativeName into a Name by adding the root label (which is exactly one byte long).

Implementations

impl<Octs> RelativeName<Octs>

Creating Values

pub const unsafe fn from_octets_unchecked(octets: Octs) -> 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: Octs) -> Result<Self, RelativeNameError>

where Octs: 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 Octs: From<&'static [u8]>,

Creates an empty relative domain name.

pub fn wildcard() -> Self

where Octs: 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.

pub fn from_chars<C>(chars: C) -> Result<Self, RelativeFromStrError>

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.

impl RelativeName<[u8]>

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

Creates a relative domain name from an octet slice.

Note that the input must be in wire format, as shown below.

Example

use domain::base::name::RelativeName;
RelativeName::from_slice(b"\x0c_submissions\x04_tcp");

pub fn empty_slice() -> &'static Self

Returns an empty relative name atop a unsized slice.

pub fn wildcard_slice() -> &'static Self

impl RelativeName<&'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 RelativeName<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>.

pub fn vec_from_str(s: &str) -> Result<Self, RelativeFromStrError>

Parses a string into a relative name atop a Vec<u8>.

impl RelativeName<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.

pub fn bytes_from_str(s: &str) -> Result<Self, RelativeFromStrError>

Parses a string into a relative name atop a Bytes.

impl<Octs: ?Sized> RelativeName<Octs>

Conversions

pub fn as_octets(&self) -> &Octs

Returns a reference to the underlying octets.

pub fn into_octets(self) -> Octs

where Octs: Sized,

Converts the name into the underlying octets.

pub fn for_ref(&self) -> RelativeName<&Octs>

Returns a domain name using a reference to the octets.

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

where Octs: AsRef<[u8]>,

Returns a reference to an octets slice with the content of the name.

pub fn for_slice(&self) -> &RelativeName<[u8]>

where Octs: AsRef<[u8]>,

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

pub fn make_canonical(&mut self)

where Octs: AsMut<[u8]>,

Converts the name into its canonical form.

impl<Octs> RelativeName<Octs>

pub fn into_builder(self) -> NameBuilder<<Octs as IntoBuilder>::Builder>

where Octs: 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<Name<Octs>, PushError>

where Octs: IntoBuilder, <Octs as IntoBuilder>::Builder: FreezeBuilder<Octets = Octs> + AsRef<[u8]> + 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 builder and back such as Vec<u8>.

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

where Octs: 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, Name<&'static [u8]>>

where Octs: AsRef<[u8]>,

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

impl<Octs: AsRef<[u8]> + ?Sized> RelativeName<Octs>

Properties

pub fn len(&self) -> usize

Returns the length of the name.

pub fn is_empty(&self) -> bool

Returns whether the name is empty.

impl<Octs: AsRef<[u8]> + ?Sized> RelativeName<Octs>

Working with Labels

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

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

Determines whether base is a prefix of self.

pub fn ends_with<N: ToLabelIter>(&self, base: &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, range: impl RangeBounds<usize>) -> &RelativeName<[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 range( &self, range: impl RangeBounds<usize>, ) -> RelativeName<<Octs as Octets>::Range<'_>>

where Octs: Octets,

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.

impl<Octs: AsRef<[u8]> + ?Sized> RelativeName<Octs>

pub fn split( &self, mid: usize, ) -> (RelativeName<Octs::Range<'_>>, RelativeName<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 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 Octs: Truncate,

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(&self) -> Option<(&Label, RelativeName<Octs::Range<'_>>)>

where Octs: 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(&self) -> Option<RelativeName<Octs::Range<'_>>>

where Octs: Octets,

Returns the parent name.

Returns None if the name was empty.

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

where Octs: Truncate,

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<Octs: AsRef<[u8]> + ?Sized> AsRef<[u8]> for RelativeName<Octs>

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

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

impl<Octs> AsRef<Octs> for RelativeName<Octs>

fn as_ref(&self) -> &Octs

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

impl<Octs> AsRef<RelativeName<[u8]>> for RelativeName<Octs>

where Octs: AsRef<[u8]> + ?Sized,

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

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

impl<Octs> Borrow<RelativeName<[u8]>> for RelativeName<Octs>

where Octs: AsRef<[u8]>,

Borrow a relative domain name.

Containers holding an owned RelativeName<_> 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::RelativeName;

fn get_description(
    hash: &HashMap<RelativeName<Vec<u8>>, String>
) -> Option<&str> {
    let lookup_name: &RelativeName<[u8]> =
        RelativeName::from_slice(b"\x03ftp").unwrap();
    hash.get(lookup_name).map(|x| x.as_ref())
}

fn borrow(&self) -> &RelativeName<[u8]>

Immutably borrows from an owned value.

impl<Octs: Clone + ?Sized> Clone for RelativeName<Octs>

fn clone(&self) -> RelativeName<Octs>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Octs: AsRef<[u8]> + ?Sized> Debug for RelativeName<Octs>

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

Formats the value using the given formatter.

impl<Octs: AsRef<[u8]> + ?Sized> Display for RelativeName<Octs>

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

Formats the value using the given formatter.

impl<Octets> From<RelativeName<Octets>> for UncertainName<Octets>

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

Converts to this type from the input type.

impl<Octs> FromStr for RelativeName<Octs>

where Octs: FromBuilder, <Octs as FromBuilder>::Builder: EmptyBuilder + FreezeBuilder<Octets = Octs> + AsRef<[u8]> + AsMut<[u8]>,

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.

This implementation will error if the name ends in a dot since that indicates an absolute name.

type Err = RelativeFromStrError

The associated error which can be returned from parsing.

impl<Octs: AsRef<[u8]> + ?Sized> Hash for RelativeName<Octs>

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

Feeds this value into the given Hasher.

impl<'a, Octs> IntoIterator for &'a RelativeName<Octs>

where Octs: AsRef<[u8]> + ?Sized,

type Item = &'a Label

The type of the elements being iterated over.

type IntoIter = NameIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Octs, SrcOcts> OctetsFrom<RelativeName<SrcOcts>> for RelativeName<Octs>

where Octs: OctetsFrom<SrcOcts>,

type Error = <Octs as OctetsFrom<SrcOcts>>::Error

fn try_octets_from(source: RelativeName<SrcOcts>) -> Result<Self, Self::Error>

Performs the conversion.

impl<Octs: AsRef<[u8]> + ?Sized> Ord for RelativeName<Octs>

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

This method returns an Ordering between self and other.

impl<Octs, N> PartialEq<N> for RelativeName<Octs>

where Octs: AsRef<[u8]> + ?Sized, N: ToRelativeName + ?Sized,

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Octs, N> PartialOrd<N> for RelativeName<Octs>

where Octs: AsRef<[u8]> + ?Sized, N: ToRelativeName + ?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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

Tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Octs> ToLabelIter for RelativeName<Octs>

where Octs: AsRef<[u8]> + ?Sized,

type LabelIter<'a> = NameIter<'a> where Octs: 'a

The type of the iterator over the labels.

fn iter_labels(&self) -> Self::LabelIter<'_>

Returns an iterator over the labels.

fn compose_len(&self) -> u16

Returns the length in octets of the encoded name.

fn starts_with<N: ToLabelIter + ?Sized>(&self, base: &N) -> bool

Determines whether base is a prefix of self.

fn ends_with<N: ToLabelIter + ?Sized>(&self, base: &N) -> bool

Determines whether base is a suffix of self.

impl<Octs: AsRef<[u8]> + ?Sized> ToRelativeName for RelativeName<Octs>

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 try_to_relative_name<Octets>( &self, ) -> Result<RelativeName<Octets>, BuilderAppendError<Octets>>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,

Converts the name into a single, continous name.

fn to_relative_name<Octets>(&self) -> RelativeName<Octets>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: OctetsBuilder<AppendError = Infallible> + EmptyBuilder,

Converts the name into a single, continous name.

fn try_to_canonical_relative_name<Octets>( &self, ) -> Result<RelativeName<Octets>, BuilderAppendError<Octets>>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,

Converts the name into a single name in canonical form.

fn to_canonical_relative_name<Octets>(&self) -> RelativeName<Octets>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: OctetsBuilder<AppendError = Infallible> + EmptyBuilder,

Converts the name into a single name in canonical form.

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>

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

Returns a cow of the relative domain name.

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

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

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

Returns the domain name assembled into a bytes value.

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

Tests whether self and other are equal.

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

Returns the ordering between self and other.

impl<Octs: AsRef<[u8]> + ?Sized> Eq for RelativeName<Octs>