Struct Span

Source

pub struct Span { /* private fields */ }

Expand description

Span in a source file.

A span points to a range of caracters between two cursor Position.

§Span construction with the `push*` methods

A span can be directly created using the new method, however in the context of parsing (or lexing) it might be useful to build spans incrementally. The push* methods family will help you do that.

push will extend the span to include the given character located at the spans end.
push_column will extend the span to include the next column. Note that this does not necessarily correspond to the next character (if it is a NL, or a full-width character for instance).
push_line will extend the span to include the rest of the line. The end of the span will be placed at the begining of the next line.
The next method can finally be used to create the span to [end, end] (when a token has been read entirely for instance) and start building the next span. The clear method does the same but in place.

§Example

Here is a basic example computing the span of every word/token in a char stream.

use source_span::{Span, DEFAULT_METRICS};

#[derive(Clone, Default)]
pub struct Token {
	string: String,
	span: Span,
}

let string = "This is an example String.".to_string();
let mut tokens = Vec::new();
let mut current = Token::default();
let metrics = &DEFAULT_METRICS;

for c in string.chars() {
	if c.is_whitespace() {
		// save the current token.
		if !current.string.is_empty() {
			tokens.push(current.clone());
		}

		// reset current token.
		current.string.clear();
		current.span.clear(); // the span here is moved to the end of itself.
	} else {
		current.string.push(c);
		current.span.push(c, metrics);
	}
}

if !current.string.is_empty() {
	tokens.push(current);
}

Implementations§

Source §

impl Span

Source

pub fn new(start: Position, last: Position, end: Position) -> Self

Create a new span from three positions.

If the end position or the last position is before the start position then the returned span will be [start, start]. If the last position is equal to end while the span is not empty, it will panic.

Source

pub fn of_string<M: Metrics>(str: &str, metrics: &M) -> Self

Source

pub const fn start(&self) -> Position

Return the position of the first character in the span.

Source

pub const fn last(&self) -> Position

Return the last position included in the span.

Source

pub const fn end(&self) -> Position

Return the position of the character directly following the span.

It is not included in the span.

Source

pub fn is_empty(&self) -> bool

Checks if the span is empty.

Source

pub fn overlaps(&self, other: &Span) -> bool

Checks if two span overlaps.

Source

pub fn includes(&self, other: &Span) -> bool

Checks if the given span is included it this span.

Source

pub const fn line_count(&self) -> usize

The number of lines covered by the span.

It is at least one, even if the span is empty.

Source

pub fn includes_line(&self, line: usize) -> bool

Checks if the span includes the given line.

Source

pub fn push_column(&mut self)

Extends the span to include the next column.

Note that this does not necessarily correspond to the next character (if it is a NL, or a full-width character for instance). To do that you can use the push method.

Source

pub fn push_line(&mut self)

Extends the span to include the rest of the line.

The end of the span will be placed at the begining of the next line.

Source

pub fn push<M: Metrics>(&mut self, c: char, metrics: &M)

Extend the span to include the given character located at the spans end position.

Source

pub fn union(&self, other: Self) -> Self

Compute the union of two spans.

If the two spans do not overlap, all positions in between will be included in the resulting span.

Source

pub fn inter(&self, other: Self) -> Self

Computes the intersection of the two spans.

If the two spans do not overlap, then the empty span located at the start of the most advanced span (maximum of the start of the two spans) is returned.

Source