Struct CharStr

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

The content of a DNS character string.

A character string consists of up to 255 octets of binary data. This type wraps an octets sequence. It is guaranteed to always be at most 255 octets in length. It derefs into the underlying octets for working with the content in a familiar way.

As per RFC 1035, character strings compare ignoring ASCII case. CharStr’s implementations of the std::cmp traits act accordingly.

Presentation format

The text representation of a character string comes in two flavors: Quoted and unquoted. In both cases, the content is interpreted as ASCII text and those octets that aren’t printable ASCII characters, as well as some special symbols, are escaped.

There are two escaping mechanisms: octets that are printable ASCII characters but need to be escaped anyway use what we call a “simple escape” that precedes the character with an ASCII backslash. For all non-printable octets “decimal escapes” are used: an ASCII backslash is followed by three decimal digits representing the decimal value of the octet. A consequence if this is that you cannot escape the digits 0, 1, and 2 using simple escapes and you probably shouldn’t do it for the other digits.

In the quoted form, the content is preceded and followed by exactly one ASCII double quote. Inside, only double quotes, backslashes, and non-printable octets need to be escaped.

In the unquoted form, the content is formatted without any explicit delimiters. Instead, it ends at the first ASCII space or any other delimiting symbol, normally ASCII control characters or an ASCII semicolon which marks the start of a comment. These characters, as well as the double quote, also need to be escaped.

Display and FromStr

When formatting a character string using the Display trait, a variation of the unquoted form is used where only backslashes and non-printable octets are escaped. Two methods are available that make it possible to format the character string in quoted and unquoted formats, display_quoted and display_unquoted. They return a temporary value that can be given to a formatting macro.

The FromStr implementation reads a character string from a Rust string in the format created by Display but is more relaxed about escape sequences – it accepts all of them as long as they lead to a valid character string.

Serde support

When the serde feature is enabled, the type supports serialization and deserialization. The format differs for human readable and compact serialization formats.

For human readable formats, character strings are serialized as a newtype CharStr wrapping a string with the content as an ASCII string. Non-printable ASCII characters (i.e., those with a byte value below 32 and above 176) are escaped using the decimal escape sequences as used by the presentation format. In addition, backslashes are escaped using a simple escape sequence and thus are doubled.

This leads to a slightly unfortunate situation in serialization formats that in turn use backslash as an escape sequence marker in their own string representation, such as JSON, where a backslash ends up as four backslashes.

When deserializing, escape sequences are excepted for all octets and translated. Non-ASCII characters are not accepted and lead to error.

For compact formats, character strings are serialized as a newtype CharStr wrapping a byte array with the content as is.

Implementations

impl CharStr<()>

pub const MAX_LEN: usize = 255usize

Character strings have a maximum length of 255 octets.

impl<Octs: ?Sized> CharStr<Octs>

pub fn empty() -> Self

where Octs: From<&'static [u8]>,

Creates a new empty character string.

pub fn from_octets(octets: Octs) -> Result<Self, CharStrError>

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

Creates a new character string from an octets value.

Returns succesfully if octets can indeed be used as a character string, i.e., it is not longer than 255 bytes.

pub unsafe fn from_octets_unchecked(octets: Octs) -> Self

where Octs: Sized,

Creates a character string from octets without length check.

Safety

The caller has to make sure that octets is at most 255 octets long. Otherwise, the behavior is undefined.

impl CharStr<[u8]>

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

Creates a character string from an octets slice.

pub fn empty_slice() -> &'static Self

Creates a new empty character string on an octets slice.

pub unsafe fn from_slice_unchecked(slice: &[u8]) -> &Self

Creates a character string from an octets slice without checking.

Safety

The caller has to make sure that octets is at most 255 octets long. Otherwise, the behaviour is undefined.

impl<Octs: ?Sized> CharStr<Octs>

pub fn builder() -> CharStrBuilder<Octs::Builder>

where Octs: IntoBuilder, Octs::Builder: EmptyBuilder,

Creates a new empty builder for this character string type.

pub fn into_builder(self) -> CharStrBuilder<Octs::Builder>

where Octs: IntoBuilder + Sized, <Octs as IntoBuilder>::Builder: AsRef<[u8]>,

Converts the character string into a builder.

pub fn into_octets(self) -> Octs

where Octs: Sized,

Converts the character string into its underlying octets value.

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

where Octs: AsRef<[u8]>,

Returns a character string atop a slice of the content.

pub fn for_slice_mut(&mut self) -> &mut CharStr<[u8]>

where Octs: AsMut<[u8]>,

Returns a character string atop a mutable slice of the content.

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

where Octs: AsRef<[u8]>,

Returns a reference to a slice of the character string’s data.

pub fn as_slice_mut(&mut self) -> &mut [u8]

where Octs: AsMut<[u8]>,

Returns a reference to a mutable slice of the character string’s data.

pub fn parse<'a, Src: Octets<Range<'a> = Octs> + ?Sized>( parser: &mut Parser<'a, Src>, ) -> Result<Self, ParseError>

where Octs: Sized,

Parses a character string from the beginning of a parser.

impl CharStr<[u8]>

pub fn parse_slice<'a>( parser: &mut Parser<'a, [u8]>, ) -> Result<&'a Self, ParseError>

Parses a character string from a parser atop a slice.

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

pub fn len(&self) -> usize

Returns the length of the character string.

This is the length of the content only, i.e., without the extra length octet added for the wire format.

pub fn is_empty(&self) -> bool

Returns whether the character string is empty.

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

Returns an iterator over the octets of the character string.

impl CharStr<[u8]>

pub fn skip<Src: Octets + ?Sized>( parser: &mut Parser<'_, Src>, ) -> Result<(), ParseError>

Skips over a character string at the beginning of a parser.

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

pub fn compose_len(&self) -> u16

Returns the length of the wire format representation.

pub fn compose<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

Appends the wire format representation to an octets builder.

impl<Octs> CharStr<Octs>

pub fn scan<S: Scanner<Octets = Octs>>( scanner: &mut S, ) -> Result<Self, S::Error>

Scans the presentation format from a scanner.

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

pub fn display_quoted(&self) -> DisplayQuoted<'_>

Returns an object that formats in quoted presentation format.

The returned object will display the content surrounded by double quotes. It will escape double quotes, backslashes, and non-printable octets only.

pub fn display_unquoted(&self) -> DisplayUnquoted<'_>

Returns an object that formats in unquoted presentation format.

The returned object will display the content without explicit delimiters and escapes space, double quotes, semicolons, backslashes, and non-printable octets.

Trait Implementations

impl<Octets: AsMut<U> + ?Sized, U: ?Sized> AsMut<U> for CharStr<Octets>

fn as_mut(&mut self) -> &mut U

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

impl<Octets: AsRef<U> + ?Sized, U: ?Sized> AsRef<U> for CharStr<Octets>

fn as_ref(&self) -> &U

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

impl<T, U> CanonicalOrd<CharStr<U>> for CharStr<T>

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

fn canonical_cmp(&self, other: &CharStr<U>) -> Ordering

Returns the canonical ordering between self and other.

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

Returns whether self is canonically less than other.

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

Returns whether self is canonically less than or equal to other.

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

Returns whether self is canonically greater than other.

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

Returns whether self is canonically greater than or equal to other.

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

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<T: AsRef<[u8]> + ?Sized> Debug for CharStr<T>

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

Formats the value using the given formatter.

impl<T: AsRef<[u8]> + ?Sized> Display for CharStr<T>

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

Formats the value using the given formatter.

impl<Octets> FromStr for CharStr<Octets>

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

type Err = FromStrError

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl<T: AsRef<[u8]> + ?Sized> Hash for CharStr<T>

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

Feeds this value into the given Hasher.

impl<'a, T: AsRef<[u8]> + ?Sized + 'a> IntoIterator for &'a CharStr<T>

type Item = u8

The type of the elements being iterated over.

type IntoIter = Iter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: AsRef<[u8]>> IntoIterator for CharStr<T>

type Item = u8

The type of the elements being iterated over.

type IntoIter = IntoIter<T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<T: AsRef<[u8]> + ?Sized> LowerHex for CharStr<T>

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

Formats the value using the given formatter.

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

where Octs: OctetsFrom<SrcOcts>,

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

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

Performs the conversion.

impl<T: AsRef<[u8]> + ?Sized> Ord for CharStr<T>

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

This method returns an Ordering between self and other.

impl<T, U> PartialEq<U> for CharStr<T>

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

fn eq(&self, other: &U) -> 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<T, U> PartialOrd<U> for CharStr<T>

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

fn partial_cmp(&self, other: &U) -> 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<T: AsRef<[u8]> + ?Sized> UpperHex for CharStr<T>

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

Formats the value using the given formatter.

impl<T: AsRef<[u8]> + ?Sized> Eq for CharStr<T>