Struct DnameBuilder

pub struct DnameBuilder { /* 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 a BytesMut value and allows adding single bytes, byte slices, or entire labels.

Unlike a BytesMut, the name builder will take care of growing the buffer if there isn’t enough space. It will, however, do so only once. If it runs out of space, it will grow the buffer to 255 bytes, since that is the maximum length of a domain name.

Implementations

impl DnameBuilder

pub fn new() -> Self

Creates a domain name builder with default capacity.

The capacity will be just large enough that the underlying BytesMut value does not need to allocate. On a 64 bit system, that will be 31 bytes, with 15 bytes on a 32 bit system. Either should be enough to hold most common domain names.

pub fn with_capacity(capacity: usize) -> Self

Creates a domain name builder with a given capacity.

The capacity may be larger than 255, even if the resulting domain name will never be.

pub fn len(&self) -> usize

Returns the current length of the domain name.

pub fn is_empty(&self) -> bool

Returns whether the builder is empty.

pub fn capacity(&self) -> usize

Returns the capacity of the underlying bytes buffer.

A domain name can be up to 255 bytes in size independently of what this method returns.

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 a byte to the end of the domain name.

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

pub fn append<T: AsRef<[u8]>>(&mut self, bytes: T) -> Result<(), PushError>

Appends a byte 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 bytes 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<T: AsRef<[u8]>>( &mut self, label: T, ) -> Result<(), PushError>

Appends a byte 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_name<N: ToRelativeDname>( &mut self, name: &N, ) -> Result<(), PushNameError>

Appends a relative domain name.

If there currently is a lable 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 finish(self) -> RelativeDname

Finishes building the name and returns the resulting domain 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.

pub fn into_dname(self) -> Result<Dname, PushNameError>

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

If there currently is a label under construction, ends the label. Then adds the empty root label and transforms the name into a Dname. As adding the root label may push the name over the size limit, this may return an error.

pub fn append_origin<N: ToDname>( self, origin: &N, ) -> Result<Dname, PushNameError>

Appends an origin and returns the resulting Dname. If there currently is a label under construction, ends the label. Then adds the origin and transforms the name into a Dname.

Trait Implementations

impl Clone for DnameBuilder

fn clone(&self) -> DnameBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Default for DnameBuilder

fn default() -> Self

Returns the “default value” for a type.