Struct NewlineCache

pub struct NewlineCache { /* private fields */ }

Cache newlines from an input. These can be used to turn UTF-8 byte offsets into human-friendly line numbers (and vice versa) without having to store the full input. The cache stores only newline positions, and not the actual user input; the cache can only be filled incrementally using the NewlineCache::feed method.

It is easy to to intermix bytes and human-friendly line numbers so NewlineCache uses the following terminology:

• byte and bytes: a UTF-8 byte offset.
• line_byte and line_bytes: the UTF-8 byte offset of a line start or end.
• line_num: a human-friendly line number.
• col_num: a human-friendly column number.

Implementations

impl NewlineCache

pub fn new() -> Self

Create an empty NewlineCache.

pub fn feed(&mut self, src: &str)

Feed further input into the cache. This input is considered to be a direct continuation of any previous input fed into the cache. Feeding new data thus appends to the cache. If the previous input contained a partial line (i.e. did not end in a newline), then the new input (unless it starts with a newline) will be considered to be a continuation of that partial line.

pub fn byte_to_line_num(&self, byte: usize) -> Option<usize>

Convert a byte offset in the input to a logical line number (i.e. a “human friendly” line number, starting from 1). Returns None if the byte offset exceeds the known input length.

pub fn byte_to_line_byte(&self, byte: usize) -> Option<usize>

Convert a byte offset in the input to the byte offset of the beginning of its line. Returns None if the byte offset exceeds the known input length.

pub fn byte_to_line_num_and_col_num( &self, src: &str, byte: usize, ) -> Option<(usize, usize)>

A convenience method to return the logical line and logical column number of a byte. This requires passing a &str which must be equivalent to the string(s) passed to feed: if not, nondeterminstic results, including panics, are possible.

Panics

May panic if src is different than the string(s) passed to feed (or might not panic and return non-deterministic results).

pub fn span_line_bytes(&self, span: Span) -> (usize, usize)

Return the (start byte, end byte) of the lines containing span. This will always cover at least 1 logical line.

Trait Implementations

impl<'a> FromIterator<&'a str> for NewlineCache

fn from_iter<I>(iter: I) -> Self

where I: IntoIterator<Item = &'a str>,

Creates a value from an iterator.

impl FromStr for NewlineCache

fn from_str(s: &str) -> Result<Self, Self::Err>

Construct a NewlineCache directly from a &str. This is equivalent to creating a blank NewlineCache and Self::feed()ing the string directly in.

type Err = ()

The associated error which can be returned from parsing.