Trait Analyzer

Source

pub trait Analyzer {
    type Content: Content;
    type Error: Error;

    // Required methods
    fn next(&mut self) -> Token;
    fn pos(&self) -> &Pos;
    fn try_content(&self) -> Result<Self::Content, Self::Error>;

    // Provided methods
    fn content(&self) -> Self::Content { ... }
    fn err(&self) -> Self::Error { ... }
}

Expand description

Lexical analyzer for JSON text.

Converts JSON text into a stream of lexical tokens.

Required Associated Types§

Source

type Content: Content

The type that contains token content, returned by the content and try_content methods.

Source

type Error: Error

The type that reports errors during the lexical analysis process, returned by the err and try_content methods.

Required Methods§

Source

fn next(&mut self) -> Token

Recognizes the next lexical token in the JSON text.

Returns the type of the token recognized. After this method returns, the text content of the recognized token can be obtained by calling the content method.

If the end of the JSON text is reached, without encountering an error, the token type returned is Token::Eof; and this token type is also returned on all subsequent calls. For Token::Eof, the content method returns a value containing empty text.

If an error is encountered while analyzing the JSON text, the token type returned is Token::Err; and this token type is also returned on all subsequent calls. For Token::Err, the content method panics.

§Performance considerations

Implementations of this method should not trigger an allocation unless an allocation is required to read in more input from an underlying source of JSON text, e.g. a file or stream. Outside this singular scenario, the process of recognizing the next JSON token should never allocate.

Source

fn pos(&self) -> &Pos

Returns the position of the lexical analyzer’s cursor within the JSON text.

Before the first call to next, the return value is Pos::default.

After next is called, the return value is the position of the first character of the recognized token. In the case where next returns Token::Err, the return value is the position of the first character of the token that was being recognized at the time when the error was detected.

Source

fn try_content(&self) -> Result<Self::Content, Self::Error>

Returns the content or error value associated with the token most recently recognized by next.

If the most recent call to next returned Token::Err, an Err result is returned. Otherwise, an Ok result containing the text content of the recognized lexical token is returned.

If called before any call to next, this method returns an Ok result containing empty text.

If called repeatedly between calls to next, subsequent calls return a value equivalent to the value returned by the first call.

When the value of the most recent token is known, calling content or err directly, as the case may be, will produce cleaner and more compact code than calling this method and unwrapping the result.

§Performance considerations

A call to this method may allocate, although implementations should avoid allocation if possible. Therefore, it is best to cache the result of this method rather than calling it repeatedly to fetch the same value between calls to next. If the text content of the last token is not needed for some reason, the best course is not to call this method at all.

Provided Methods§

Source

fn content(&self) -> Self::Content

Returns the text content of the non-error token most recently recognized by next.

If called before any call to next, returns empty content.

If called repeatedly between calls to next, subsequent calls return a value equivalent to the value returned by the first call.

§Panics

Panics if the token most recently returned by next was Token::Err.

§Performance considerations

A call to this method may allocate, although implementations should avoid allocation if possible. Therefore, it is best to cache the result of this method rather than calling it repeatedly to fetch the same value between calls to next. If the text content of the last token is not needed for some reason, the best course is not to call this method at all.

Source

fn err(&self) -> Self::Error

Returns the error value associated with the error token most recently returned by next.

If called repeatedly after a call to next that returned Token::Err, subsequent calls return a value equivalent to the value returned by the first call.