Struct Txt

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

TXT record data.

TXT records hold descriptive text. While it may appear as a single text, it internally consists of a sequence of one or more character strings. The type holds this sequence in its encoded form, i.e., each character string is at most 255 octets long and preceded by an octet with its length.

The type provides means to iterate over these strings, either as CharStrs via iter_charstrs or as plain octets slices via iter. There is a short cut for the most common case of there being exactly one character string in as_flat_slice. Finally, the two methods text and try_text allow combining the content into one single octets sequence.

The TXT record type is defined in RFC 1035, section 3.3.14.

Presentation format

TXT record data appears in zone files as the white-space delimited sequence of its constituent character strings. This means that if these strings are not quoted, each “word” results in a character string of its own. Thus, the quoted form of the character string’s presentation format is preferred.

Display

The Display implementation prints the sequence of character strings in their quoted presentation format separated by a single space.

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, the type serializes into a newtype Txt wrapping a sequence of serialized CharStrs. The deserializer supports a non-canonical form as a single string instead of the sequence. In this case the string is broken up into chunks of 255 octets if it is longer. However, not all format implementations support alternative deserialization based on the encountered type. In particular, serde-json doesn’t, so it will only accept sequences.

For compact formats, the type serializes as a newtype Txt that contains a byte array of the wire format representation of the content.

Implementations

impl<Octs: FromBuilder> Txt<Octs>

pub fn build_from_slice(text: &[u8]) -> Result<Self, TxtAppendError>

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

Creates a new Txt record from a single slice.

If the slice is longer than 255 octets, it will be broken up into multiple character strings where all but the last string will be 255 octets long.

If the slice is longer than 65,535 octets or longer than what fits into the octets type used, an error is returned.

impl<Octs> Txt<Octs>

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

where Octs: AsRef<[u8]>,

Creates new TXT record data from its encoded content.

The octets sequence most contain correctly encoded TXT record data. That is, it must contain a sequence of at least one character string of at most 255 octets each preceded by a length octet. An empty sequence is not allowed.

Returns an error if octets does not contain correctly encoded TXT record data.

impl Txt<[u8]>

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

Creates new TXT record data on an octets slice.

The slice must contain correctly encoded TXT record data, that is a sequence of encoded character strings. See

impl<Octs> Txt<Octs>

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

where Octs: AsRef<[u8]>,

Parses TXT record data from the beginning of a parser.

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

Scans TXT record data.

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

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

Returns an iterator over the character strings as slices.

The returned iterator will always return at least one octets slice.

pub fn iter_charstrs(&self) -> TxtCharStrIter<'_>

Returns an iterator over the character strings.

The returned iterator will always return at least one octets slice.

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

Returns the content if it consists of a single character string.

pub fn len(&self) -> usize

Returns the length of the TXT record data.

Note that this is the length of the encoded record data and therefore never the length of the text, not even if there is only a single character string – it is still preceded by a length octet.

Note further that TXT record data is not allowed to be empty, so there is no is_empty method.

pub fn try_text<T: FromBuilder>( &self, ) -> Result<T, <<T as FromBuilder>::Builder as OctetsBuilder>::AppendError>

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

Returns the text content.

The method appends the content of each character string to a newly created octets builder. It does not add any delimiters between the character string.

If your octets builder is not space limited, you can use text instead.

pub fn text<T: FromBuilder>(&self) -> T

where <T as FromBuilder>::Builder: EmptyBuilder, <<T as FromBuilder>::Builder as OctetsBuilder>::AppendError: Into<Infallible>,

Returns the text content.

The method appends the content of each character string to a newly created octets builder. It does not add any delimiters between the character string.

This method is only available for octets builder types that are not space limited. You can use try_text with all builder types.

Trait Implementations

impl<Octs, Other> CanonicalOrd<Txt<Other>> for Txt<Octs>

where Octs: AsRef<[u8]>, Other: AsRef<[u8]>,

fn canonical_cmp(&self, other: &Txt<Other>) -> 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 Txt<Octs>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Octs: AsRef<[u8]>> ComposeRecordData for Txt<Octs>

fn rdlen(&self, _compress: bool) -> Option<u16>

Returns the length of the record data if available.

fn compose_rdata<Target: Composer + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

Appends the wire format of the record data into target.

fn compose_canonical_rdata<Target: Composer + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

Appends the canonical wire format of the record data into target.

fn compose_len_rdata<Target: Composer + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

Appends the record data prefixed with its length.

fn compose_canonical_len_rdata<Target: Composer + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

Appends the record data prefixed with its length.

impl<Octs: AsRef<[u8]>> Debug for Txt<Octs>

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

Formats the value using the given formatter.

impl<Octs: AsRef<[u8]>> Display for Txt<Octs>

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

Formats the value using the given formatter.

impl<O, N> From<Txt<O>> for AllRecordData<O, N>

fn from(value: Txt<O>) -> Self

Converts to this type from the input type.

impl<O, N> From<Txt<O>> for ZoneRecordData<O, N>

fn from(value: Txt<O>) -> Self

Converts to this type from the input type.

impl<Octs: AsRef<[u8]>> Hash for Txt<Octs>

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, Octs: AsRef<[u8]>> IntoIterator for &'a Txt<Octs>

type Item = &'a [u8]

The type of the elements being iterated over.

type IntoIter = TxtIter<'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<Txt<SrcOcts>> for Txt<Octs>

where Octs: OctetsFrom<SrcOcts>,

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

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

Performs the conversion.

impl<Octs: AsRef<[u8]>> Ord for Txt<Octs>

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

This method returns an Ordering between self and other.

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

where Self: Sized,

Compares and returns the maximum of two values.

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

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<'a, Octs> ParseRecordData<'a, Octs> for Txt<Octs::Range<'a>>

where Octs: Octets + ?Sized,

fn parse_rdata( rtype: Rtype, parser: &mut Parser<'a, Octs>, ) -> Result<Option<Self>, ParseError>

Parses the record data.

impl<Octs, Other> PartialEq<Txt<Other>> for Txt<Octs>

where Octs: AsRef<[u8]>, Other: AsRef<[u8]>,

fn eq(&self, other: &Txt<Other>) -> 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, Other> PartialOrd<Txt<Other>> for Txt<Octs>

where Octs: AsRef<[u8]>, Other: AsRef<[u8]>,

fn partial_cmp(&self, other: &Txt<Other>) -> 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> RecordData for Txt<Octs>

fn rtype(&self) -> Rtype

Returns the record type associated with this record data instance.

impl<Octs: AsRef<[u8]>> Eq for Txt<Octs>