Struct Span 

pub struct Span(/* private fields */);

Defines a range of text in a Typst source file.

Spans are used throughout the compiler to track which source section an element stems from or an error/warning applies to. Errors and warnings use the DiagSpan type which can contain either a normal span or a range targeting a location in a non-Typst file, such as a JSON parsing error.

• The .id() method can be used to get the FileId for the span and, by extension, its file system path.
• The WorldExt::range function can be used to map the span to a Range<usize>.

This type is stored compactly in 8 bytes, and is copyable and null-optimized (i.e. Option<Span> also takes 8 bytes), but can be expanded for easier usage into the SpanKind enum via Self::get().

Spans internally distinguish between four kinds of values, these are accessible as the SpanKind or DiagSpanKind enums via the Span::get or DiagSpan::get methods.

1. They can be detached, originating from nowhere or from the compiler itself.
2. They can be numbered values, corresponding to a node in a Typst source file’s concrete syntax tree. These are the most common span type and are explained more below.
3. They can be raw range spans, containing a range of two indices that came from parsing a text as Typst syntax. The file itself is not necessarily a Typst source file. The maximum value for the start/end of these ranges is 2^23-1, larger values will be saturated.
4. They can be an external start index, used for diagnostics on externally loaded text files. These are only accessible as part of a DiagSpan which also contains the end index. The maximum value for the start/end of these ranges is 2^46-1, larger values will be saturated.

Numbered spans

Typst source files use numbered spans. Rather than using byte ranges, which shift a lot as you type, each syntax tree node gets a unique number.

During editing, the span numbers stay mostly stable, even for nodes behind an insertion. This is not true for simple ranges as they would shift. This allows spans to be used as inputs to memoized functions without hurting cache performance when text is inserted somewhere in the document other than the end.

Span numbers are ordered in the syntax tree to enable quickly finding the node of a known span:

• The span number of a parent node is always smaller than the number of any of its children
• The span numbers of sibling nodes always increase from left to right

Combining those guarantees, we have that for siblings in order [A, B, C], the span numbers for node A and all of A’s children are less than node B’s span number, and the numbers for node C and all of C’s children are greater than B’s span number.

Implementations

impl Span

pub const fn detached() -> Self

The detached span that does not point into any file.

pub const fn from_raw(v: NonZeroU64) -> Self

Construct from a raw number.

Should only be used with numbers retrieved via into_raw. Misuse may results in panics, but no unsafety.

pub const fn is_detached(self) -> bool

Whether the span is detached.

pub const fn id(self) -> Option<FileId>

The id of the file the span points into.

Returns None if the span is detached.

pub const fn get(self) -> SpanKind

Unpack the span into the variants of a SpanKind for easier use.

To access a range, you may want to use WorldExt::range instead.

pub const fn into_raw(self) -> NonZeroU64

Extract the raw underlying number.

pub fn or(self, other: Self) -> Self

Return other if self is detached and self otherwise.

pub fn find(iter: impl IntoIterator<Item = Self>) -> Self

Find the first non-detached span in the iterator.

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

impl Debug for Span

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

Formats the value using the given formatter.

impl Eq for Span

impl From<Span> for DiagSpan

fn from(span: Span) -> Self

Converts to this type from the input type.

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

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Span