Struct source_span::Span

pub struct Span { /* fields omitted */ }

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;

#[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();

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);
    }
}

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

Methods

impl Span

#[must_use] 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.

#[must_use] pub const fn start(&self) -> Position

Return the position of the first character in the span.

#[must_use] pub const fn last(&self) -> Position

Return the last position included in the span.

#[must_use] pub const fn end(&self) -> Position

Return the position of the character directly following the span.

It is not included in the span.

#[must_use] pub fn is_empty(&self) -> bool

Checks if the span is empty.

#[must_use] pub fn overlaps(&self, other: &Self) -> bool

Checks if two span overlaps.

#[must_use] 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.

#[must_use] pub fn includes_line(&self, line: usize) -> bool

Checks if the span includes the given line.

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.

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.

pub fn push(&mut self, c: char)

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

#[must_use] 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.

#[must_use] 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.

pub fn append(&mut self, other: Self)

Extend the span to the end of the given span.

This is the in-place version of union, except that nothing happens if the input span finishes before the end of self.

#[must_use] pub const fn next(&self) -> Self

Return the next span (defined as [end, end]).

pub fn clear(&mut self)

Set the span to next ([end, end]).

#[must_use] pub const fn aligned(&self) -> Self

Return the span aligned on line boundaries.

This will compute the smallest span including self such that

• start is at the begining of a line (column 0),
• end is at the end of a line (column std::usize::MAX),
• last points to the last character of a line (column std::usize::MAX - 1).

Trait Implementations

impl Clone for Span

fn clone(&self) -> Span

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Copy for Span

impl Debug for Span

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Default for Span

fn default() -> Span

Returns the "default value" for a type.

impl Display for Span

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Eq for Span

impl From<Position> for Span

fn from(pos: Position) -> Self

Performs the conversion.

impl Hash for Span

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl Ord for Span

fn cmp(&self, other: &Self) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use] fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use] fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use] fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl PartialEq<Span> for Span

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

This method tests for self and other values to be equal, and is used by ==.

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

This method tests for !=.

impl PartialOrd<Span> for Span

fn partial_cmp(&self, other: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use] fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use] fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use] fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use] fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl StructuralEq for Span

impl StructuralPartialEq for Span