Struct Span 

pub struct Span { /* private fields */ }

Where syntax originated and, when available, the source buffer it indexes.

Source-derived tokens retain only this value. Their spelling is recovered by slicing the shared source buffer; it is never copied into token or syntax node storage. Spans constructed only from offsets remain useful for diagnostics and synthetic trees, but naturally cannot yield source text.

Implementations

impl Span

pub const Detached: Self

A detached span without source text.

pub fn detached() -> Self

Creates a span with no source location.

Examples found in repository

examples/parse_emit_walkthrough.rs (line 14)

    fn parse(input: &mut ParseStream) -> Result<Self, TokenParseError> {
        let Some(token) = input.next_token() else {
            return Err(TokenParseError::UnexpectedEnd {
                expected: "identifier",
                span: Span::detached(),
            });
        };

        let span = token.span();
        match token {
            TokenTree::Ident(identifier) => Ok(Self(identifier)),
            token => Err(TokenParseError::UnexpectedToken {
                expected: "identifier",
                found: token.spelling().unwrap_or("group or trivia").to_owned(),
                span,
            }),
        }
    }

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

Builds a span covering start..end, where end is the offset past the last byte.

An inverted pair collapses to Detached rather than fabricating a range.

pub fn from_offset(offset: Offset) -> Self

A zero-width span at one boundary, for syntax that occupies no bytes.

pub fn with_text(self, text: impl Into<Arc<str>>) -> Self

Attaches the complete source fragment covered by this span.

Existing source backing is retained. For an offset-only span, text must have the same byte width as the span; its first byte is associated with the span’s opening offset. Detached syntax may also carry a source fragment, which is useful for programmatically constructed syntax.

Panics

Panics when an offset-only span and text have different byte widths.

pub fn replaced_text(&self, text: impl Into<Arc<str>>) -> Self

Replaces this span’s source fragment while retaining its opening location and updating its width.

pub fn source(text: impl Into<Arc<str>>) -> Self

Creates a source-backed span covering an entire source buffer.

pub fn subspan(&self, start: Offset, end: Offset) -> Self

Returns a subspan at byte offsets relative to this span’s opening.

The returned span shares the same source buffer. Invalid or detached ranges become detached spans.

pub fn text(&self) -> Option<&str>

Returns the exact source text covered by this span when source backing is available.

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

Reports whether both spans slice the same shared source buffer.

pub fn start(&self) -> Option<Offset>

The boundary this span opens at, or None when it is detached.

pub fn end(&self) -> Option<Offset>

The boundary this span closes at, past its last byte.

pub fn bounds(&self) -> Option<(Offset, Offset)>

The boundaries this span lies between.

Examples found in repository

examples/live_parser.rs (line 41)

fn write_diagnostic(output: &mut String, diagnostic: &LexError) {
    let span = diagnostic.span();
    output.push_str(&format!("- {diagnostic} at {:?}\n", span.bounds()));
}

pub fn len(&self) -> Option<usize>

How many bytes this span covers, or None when it is detached.

pub fn is_empty(&self) -> bool

Reports whether this span covers no bytes, as the virtual marker tokens do. Detached syntax covers no bytes either.

pub fn contains(&self, offset: Offset) -> bool

Returns whether offset lies inside this span, excluding its closing boundary.

Boundaries sit between bytes, so the closing one belongs to whatever follows: in a+b the boundary after a is contained by +, not by a. This is the predicate to use when exactly one span must own a position. A zero-width span contains nothing, having no interior.

pub fn touches(&self, offset: Offset) -> bool

Returns whether offset lies inside this span or on either boundary.

Adjacent spans both touch the boundary between them, so this answers “which syntax is the cursor at” rather than “which syntax owns this position” — a cursor just past an identifier still touches it, and a zero-width marker is touched at its own position.

pub fn shifted(&self, edit: &TextEdit) -> Self

Returns this span’s position in the buffer produced by edit.

Both boundaries move under the same rule, so nothing here decides which side of an insertion a boundary belongs to. Because that rule is monotone the pair can never invert, and a zero-width span needs no special case: its two equal boundaries stay equal.

Text inserted at a span’s closing boundary therefore extends the span, which is what an unclosed group wants — it keeps reaching whatever now follows it. A span wholly removed by a deletion collapses to a zero-width span at the deletion point rather than becoming Self::Detached, because it still records where the syntax used to be.

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

The smallest span covering both, ignoring detached operands.

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

The overlap of both, or Detached when they do not overlap.

pub fn join_all(spans: impl IntoIterator<Item = Span>) -> Self

Joins every span in an iterator, ignoring detached spans.

Trait Implementations

impl Clone for Span

fn clone(&self) -> Span

Returns a duplicate of the value.

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

Performs copy-assignment from source.

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 Eq for Span

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Index<&Span> for str

type Output = str

The returned type after indexing.

fn index(&self, span: &Span) -> &str

Performs the indexing (container[index]) operation.

impl Index<&Span> for String

type Output = str

The returned type after indexing.

fn index(&self, span: &Span) -> &str

Performs the indexing (container[index]) operation.

impl Index<Span> for str

Indexes the buffer, panicking when the span does not name text in it.

This is legal despite Index and str both being foreign because Span is local, and it cannot overlap str’s own impl<I: SliceIndex<str>> Index<I> for str because Span does not implement SliceIndex.

type Output = str

The returned type after indexing.

fn index(&self, span: Span) -> &str

Performs the indexing (container[index]) operation.

impl Index<Span> for String

String needs its own implementation rather than reaching str’s through deref: it already has an Index impl of its own, so operator resolution stops there instead of falling through.

type Output = str

The returned type after indexing.

fn index(&self, span: Span) -> &str

Performs the indexing (container[index]) operation.

impl PartialEq for Span

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

Equality operator ==.

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

Inequality operator !=.

impl Spanned for Span

fn span(&self) -> Span

Returns the smallest span covering this value.