Trait chumsky::span::Span

pub trait Span {
    type Context;
    type Offset;

    // Required methods
    fn new(context: Self::Context, range: Range<Self::Offset>) -> Self;
    fn context(&self) -> Self::Context;
    fn start(&self) -> Self::Offset;
    fn end(&self) -> Self::Offset;

    // Provided methods
    fn to_end(&self) -> Self
       where Self: Sized { ... }
    fn union(&self, other: Self) -> Self
       where Self::Context: PartialEq + Debug,
             Self::Offset: Ord,
             Self: Sized { ... }
}

A trait that describes a span over a particular range of inputs.

Spans typically consist of some context, such as the file they originated from, and a start/end offset. Spans are permitted to overlap one-another. The end offset must always be greater than or equal to the start offset.

Span is automatically implemented for Range<T> and [(C, Range<T>)].

Required Associated Types

type Context

Extra context used in a span.

This is usually some way to uniquely identity the source file that a span originated in such as the file’s path, URL, etc.

NOTE: Span contexts have no inherent meaning to Chumsky and can be anything. For example, Range<usize>’s implementation of Span simply uses [()] as its context.

type Offset

A type representing a span’s start or end offset from the start of the input.

Typically, usize is used.

NOTE: Offsets have no inherently meaning to Chumsky and are not used to decide how to prioritize errors. This means that it’s perfectly fine for tokens to have non-continuous spans that bear no relation to their actual location in the input stream. This is useful for languages with an AST-level macro system that need to correctly point to symbols in the macro input when producing errors.

Required Methods

fn new(context: Self::Context, range: Range<Self::Offset>) -> Self

Create a new span given a context and an offset range.

fn context(&self) -> Self::Context

Return the span’s context.

fn start(&self) -> Self::Offset

Return the start offset of the span.

fn end(&self) -> Self::Offset

Return the end offset of the span.

Provided Methods

fn to_end(&self) -> Self

where Self: Sized,

Turn this span into a zero-width span that starts and ends at the end of the original.

For example, an original span like 3..7 will result in a new span of 7..7.

This may be convenient in various circumstances, such as when specifying the ‘end of input’ span in Input::spanned.

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

where Self::Context: PartialEq + Debug, Self::Offset: Ord, Self: Sized,

Combine two assumed-contiguous spans together into a larger span that encompasses both (and anything between).

For example, spans like 3..5 and 7..8 will result in a unioned span of 3..8.

The spans may overlap one-another, but the start offset must come before the end offset for each span (i.e: each span must be ‘well-formed’). If this is not the case, the result is unspecified.

Panics

Panics if the Self::Contexts of both spans are not equal.

Object Safety

This trait is not object safe.

Implementations on Foreign Types

impl<C: Clone, S: Span<Context = ()>> Span for (C, S)

type Context = C

type Offset = <S as Span>::Offset

fn new(context: Self::Context, range: Range<Self::Offset>) -> Self

fn context(&self) -> Self::Context

fn start(&self) -> Self::Offset

fn end(&self) -> Self::Offset

impl<T: Clone> Span for Range<T>

type Context = ()

type Offset = T

fn new(_context: Self::Context, range: Range<Self::Offset>) -> Self

fn context(&self) -> Self::Context

fn start(&self) -> Self::Offset

fn end(&self) -> Self::Offset

Implementors

impl<T: Clone, C: Clone> Span for SimpleSpan<T, C>

type Context = C

type Offset = T