Trait domain::base::scan::Scanner

source ·
pub trait Scanner {
    type Octets: AsRef<[u8]>;
    type OctetsBuilder: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]> + Truncate + FreezeBuilder<Octets = Self::Octets>;
    type Dname: ToDname;
    type Error: ScannerError;

Show 14 methods // Required methods fn has_space(&self) -> bool; fn continues(&mut self) -> bool; fn scan_symbols<F>(&mut self, op: F) -> Result<(), Self::Error> where F: FnMut(Symbol) -> Result<(), Self::Error>; fn scan_entry_symbols<F>(&mut self, op: F) -> Result<(), Self::Error> where F: FnMut(EntrySymbol) -> Result<(), Self::Error>; fn convert_token<C: ConvertSymbols<Symbol, Self::Error>>( &mut self, convert: C, ) -> Result<Self::Octets, Self::Error>; fn convert_entry<C: ConvertSymbols<EntrySymbol, Self::Error>>( &mut self, convert: C, ) -> Result<Self::Octets, Self::Error>; fn scan_octets(&mut self) -> Result<Self::Octets, Self::Error>; fn scan_ascii_str<F, T>(&mut self, op: F) -> Result<T, Self::Error> where F: FnOnce(&str) -> Result<T, Self::Error>; fn scan_dname(&mut self) -> Result<Self::Dname, Self::Error>; fn scan_charstr(&mut self) -> Result<CharStr<Self::Octets>, Self::Error>; fn scan_string(&mut self) -> Result<Str<Self::Octets>, Self::Error>; fn scan_charstr_entry(&mut self) -> Result<Self::Octets, Self::Error>; fn scan_opt_unknown_marker(&mut self) -> Result<bool, Self::Error>; fn octets_builder(&mut self) -> Result<Self::OctetsBuilder, Self::Error>;
}
Expand description

A type that can produce tokens of data in presentation format.

The presentation format is a relatively simple text format that provides a sequence of entries each consisting of a sequence of tokens. An implementation of the Scanner trait provides access to the tokens of a single entry.

Most methods of the trait process a single token to the caller. Exceptions are those methods suffixed with _entry, which process all the remaining tokens of the entry. In addition, has_space reports whether the token was prefixed with white space (which is relevant in some cases), and continues reports whether there are more tokens in the entry. It it returns `false, all the other token and entry methods will return an error. That is, calling these methods assumes that the caller requires at least one more token.

Because an implementation may be able to optimize the process of converting tokens into output data types, there are a number of methods for different output. Each of these methods assumes that the next token (or the remaining tokens in the entry) is required to contain the presentation format of the given type and is should produce an error if that is not the case.

This allows for instance to optimize the creation of domain names and avoid copying around data in the most usual cases.

As a consequence, an implementation gets to choose how to return tokens. This mostly concerns the octets types to be used, but also allows it to creatively employing the name::Chain type to deal with a zone’s changing origin.

Required Associated Types§

source

type Octets: AsRef<[u8]>

The type of octet sequences returned by the scanner.

source

type OctetsBuilder: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]> + Truncate + FreezeBuilder<Octets = Self::Octets>

The octets builder used internally and returned upon request.

source

type Dname: ToDname

The type of a domain name returned by the scanner.

source

type Error: ScannerError

The error type of the scanner.

Required Methods§

source

fn has_space(&self) -> bool

Returns whether the next token is preceded by white space.

source

fn continues(&mut self) -> bool

Returns whether there are more tokens in the entry.

This method takes a &mut self to allow implementations to peek on request.

source

fn scan_symbols<F>(&mut self, op: F) -> Result<(), Self::Error>
where F: FnMut(Symbol) -> Result<(), Self::Error>,

Scans a token into a sequence of symbols.

Each symbol is passed to the caller via the closure and can be processed there.

source

fn scan_entry_symbols<F>(&mut self, op: F) -> Result<(), Self::Error>
where F: FnMut(EntrySymbol) -> Result<(), Self::Error>,

Scans the remainder of the entry as symbols.

Each symbol is passed to the caller via the closure and can be processed there.

source

fn convert_token<C: ConvertSymbols<Symbol, Self::Error>>( &mut self, convert: C, ) -> Result<Self::Octets, Self::Error>

Converts the symbols of a token into an octets sequence.

Each symbol is passed to the provided converter which can return octet slices to be used to construct the returned value. When the token is complete, the converter is called again to ask for any remaining data to be added.

source

fn convert_entry<C: ConvertSymbols<EntrySymbol, Self::Error>>( &mut self, convert: C, ) -> Result<Self::Octets, Self::Error>

Converts the symbols of a token into an octets sequence.

Each symbol is passed to the provided converter which can return octet slices to be used to construct the returned value. When the token is complete, the converter is called again to ask for any remaining data to be added.

source

fn scan_octets(&mut self) -> Result<Self::Octets, Self::Error>

Scans a token into an octets sequence.

The returned sequence has all symbols converted into their octets. It can be of any length.

source

fn scan_ascii_str<F, T>(&mut self, op: F) -> Result<T, Self::Error>
where F: FnOnce(&str) -> Result<T, Self::Error>,

Scans a token as a borrowed ASCII string.

If the next token contains non-ascii characters, returns an error. The string is given to the caller via the provided closure.

source

fn scan_dname(&mut self) -> Result<Self::Dname, Self::Error>

Scans a token into a domain name.

source

fn scan_charstr(&mut self) -> Result<CharStr<Self::Octets>, Self::Error>

Scans a token into a character string.

Note that character strings have a length limit. If you want a sequence of indefinite length, use scan_octets instead.

source

fn scan_string(&mut self) -> Result<Str<Self::Octets>, Self::Error>

Scans a token as a UTF-8 string.

source

fn scan_charstr_entry(&mut self) -> Result<Self::Octets, Self::Error>

Scans a sequence of character strings until the end of the entry.

The returned octets will contain the sequence of character strings in wire format.

source

fn scan_opt_unknown_marker(&mut self) -> Result<bool, Self::Error>

Scans an optional unknown rdata marker.

If the next token is \#, i.e., an unquoted, escaped hash sign, consumes the token and returns Ok(true). If the next token is anything else or if there is no next token, does nothing and returns Ok(false). If there is an error, returns an error.

source

fn octets_builder(&mut self) -> Result<Self::OctetsBuilder, Self::Error>

Returns an empty octets builder.

This builder can be used to create octets sequences in cases where the other methods can’t be used.

Object Safety§

This trait is not object safe.

Implementors§

source§

impl<Iter, Item, Octets> Scanner for IterScanner<Iter, Octets>
where Item: AsRef<str>, Iter: Iterator<Item = Item>, Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder + Composer,

§

type Octets = Octets

§

type OctetsBuilder = <Octets as FromBuilder>::Builder

§

type Dname = Dname<Octets>

§

type Error = StrError