Struct NameBuilder

pub struct NameBuilder<Builder> { /* private fields */ }

Builds a domain name step by step by appending data.

The domain name builder is the most fundamental way to construct a new domain name. It wraps an octets builder that assembles the name step by step.

The methods push and append_slice to add the octets of a label to end of the builder. Once a label is complete, end_label finishes the current label and starts a new one.

The method append_label combines this process and appends the given octets as a label.

The name builder currently is not aware of internationalized domain names. The octets passed to it are used as is and are not converted.

Implementations

impl<Builder> NameBuilder<Builder>

pub fn new() -> Self

where Builder: EmptyBuilder,

Creates a new, empty name builder.

pub fn with_capacity(capacity: usize) -> Self

where Builder: EmptyBuilder,

Creates a new, empty builder with a given capacity.

pub fn from_builder(builder: Builder) -> Result<Self, RelativeNameError>

where Builder: OctetsBuilder + AsRef<[u8]>,

Creates a new domain name builder atop an existing octets builder.

The function checks that whatever is in the builder already consititutes a correctly encoded relative domain name.

impl NameBuilder<Vec<u8>>

pub fn new_vec() -> Self

Creates an empty domain name builder atop a Vec<u8>.

pub fn vec_with_capacity(capacity: usize) -> Self

Creates an empty builder atop a Vec<u8> with given capacity.

Names are limited to a length of 255 octets, but you can provide any capacity you like here.

impl NameBuilder<BytesMut>

pub fn new_bytes() -> Self

Creates an empty domain name bulider atop a bytes value.

pub fn bytes_with_capacity(capacity: usize) -> Self

Creates an empty bulider atop a bytes value with given capacity.

Names are limited to a length of 255 octets, but you can provide any capacity you like here.

impl<Builder: AsRef<[u8]>> NameBuilder<Builder>

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

Returns the already assembled domain name as an octets slice.

pub fn len(&self) -> usize

Returns the length of the already assembled domain name.

pub fn is_empty(&self) -> bool

Returns whether the name is still empty.

impl<Builder> NameBuilder<Builder>

where Builder: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>,

pub fn in_label(&self) -> bool

Returns whether there currently is a label under construction.

This returns false if the name is still empty or if the last thing that happend was a call to end_label.

pub fn push(&mut self, ch: u8) -> Result<(), PushError>

Pushes an octet to the end of the domain name.

Starts a new label if necessary. Returns an error if pushing the octet would exceed the size limits for labels or domain names.

pub fn push_symbol(&mut self, sym: Symbol) -> Result<(), FromStrError>

Pushes a symbol to the end of the domain name.

The symbol is iterpreted as part of the presentation format of a domain name, i.e., an unescaped dot is considered a label separator.

pub fn append_slice(&mut self, slice: &[u8]) -> Result<(), PushError>

Appends the content of an octets slice to the end of the domain name.

Starts a new label if necessary. Returns an error if pushing would exceed the size limits for labels or domain names.

If slice is empty, does absolutely nothing.

pub fn end_label(&mut self)

Ends the current label.

If there isn’t a current label, does nothing.

pub fn append_label(&mut self, label: &[u8]) -> Result<(), PushError>

Appends an octets slice as a complete label.

If there currently is a label under construction, it will be ended before appending label.

Returns an error if label exceeds the label size limit of 63 bytes or appending the label would exceed the domain name size limit of 255 bytes.

pub fn append_dec_u8_label(&mut self, value: u8) -> Result<(), PushError>

Appends a label with the decimal representation of u8.

If there currently is a label under construction, it will be ended before appending label.

Returns an error if appending would result in a name longer than 254 bytes.

pub fn append_hex_digit_label(&mut self, nibble: u8) -> Result<(), PushError>

Appends a label with the hex digit.

If there currently is a label under construction, it will be ended before appending label.

Returns an error if appending would result in a name longer than 254 bytes.

pub fn append_name<N: ToRelativeName>( &mut self, name: &N, ) -> Result<(), PushNameError>

Appends a relative domain name.

If there currently is a label under construction, it will be ended before appending name.

Returns an error if appending would result in a name longer than 254 bytes.

pub fn append_symbols<Sym: IntoIterator<Item = Symbol>>( &mut self, symbols: Sym, ) -> Result<(), FromStrError>

Appends a name from a sequence of symbols.

If there currently is a label under construction, it will be ended before appending chars.

The character sequence must result in a domain name in representation format. That is, its labels should be separated by dots, actual dots, white space, backslashes and byte values that are not printable ASCII characters should be escaped.

The last label will only be ended if the last character was a dot. Thus, you can determine if that was the case via in_label.

pub fn append_chars<C: IntoIterator<Item = char>>( &mut self, chars: C, ) -> Result<(), FromStrError>

Appends a name from a sequence of characters.

If there currently is a label under construction, it will be ended before appending chars.

The character 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.

The last label will only be ended if the last character was a dot. Thus, you can determine if that was the case via in_label.

pub fn finish(self) -> RelativeName<Builder::Octets>

where Builder: FreezeBuilder,

Finishes building the name and returns the resulting relative name.

If there currently is a label being built, ends the label first before returning the name. I.e., you don’t have to call end_label explicitely.

This method converts the builder into a relative name. If you would like to turn it into an absolute name, use into_name which appends the root label before finishing.

pub fn into_name(self) -> Result<Name<Builder::Octets>, PushError>

where Builder: FreezeBuilder,

Appends the root label to the name and returns it as a Name.

If there currently is a label under construction, ends the label. Then adds the empty root label and transforms the name into a Name.

pub fn append_origin<N: ToName>( self, origin: &N, ) -> Result<Name<Builder::Octets>, PushNameError>

where Builder: FreezeBuilder,

Appends an origin and returns the resulting Name.

If there currently is a label under construction, ends the label. Then adds the origin and transforms the name into a Name.

Trait Implementations

impl<Builder: AsRef<[u8]>> AsRef<[u8]> for NameBuilder<Builder>

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

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

impl<Builder: Clone> Clone for NameBuilder<Builder>

fn clone(&self) -> NameBuilder<Builder>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Builder: EmptyBuilder> Default for NameBuilder<Builder>

fn default() -> Self

Returns the “default value” for a type.