Struct Span

#[repr(C)]
pub struct Span {
    pub start: u32,
    pub end: u32,
    /* private fields */
}

A range in text, represented by a zero-indexed start and end offset.

It is a logical error for end to be less than start.

let text = "foo bar baz";
let span = Span::new(4, 7);
assert_eq!(&text[span], "bar");

Spans use u32 for offsets, meaning only files up to 4GB are supported. This is sufficient for “all” reasonable programs. This tradeof cuts the size of Span in half, offering a sizeable performance improvement and memory footprint reduction.

Creating Spans

Span offers several constructors, each of which is more or less convenient depending on the context. In general, Span::new is sufficient for most cases. If you want to create a span starting at some point of a certain length, you can use Span::sized.

let a = Span::new(5, 10);  // Start and end offsets
let b = Span::sized(5, 5); // Start offset and size
assert_eq!(a, b);

Re-Sizing Spans

Span offsets can be mutated directly, but it is often more convenient to use one of the expand or shrink methods. Each of these create a new span without modifying the original.

let s = Span::new(5, 10);
assert_eq!(s.shrink(2), Span::new(7, 8));
assert_eq!(s.shrink(2), s.shrink_left(2).shrink_right(2));

assert_eq!(s.expand(5), Span::new(0, 15));
assert_eq!(s.expand(5), s.expand_left(5).expand_right(5));

Comparison

Span has a normal implementation of PartialEq. If you want to compare two AST nodes without considering their locations (e.g. to see if they have the same content), use ContentEq instead.

Implementation Notes

See the text-size crate for details. Utility methods can be copied from the text-size crate if they are needed.

Fields

start: u32

The zero-based start offset of the span

end: u32

The zero-based end offset of the span. This may be equal to start if the span is empty, but should not be less than it.

Implementations

impl Span

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

Create a new Span from a start and end position.

Invariants

The start position must be less than or equal to end. Note that this invariant is only checked in debug builds to avoid a performance penalty.

pub fn empty(at: u32) -> Self

Create a new empty Span that starts and ends at an offset position.

Examples

use oxc_span::Span;

let fifth = Span::empty(5);
assert!(fifth.is_empty());
assert_eq!(fifth, Span::sized(5, 0));
assert_eq!(fifth, Span::new(5, 5));

pub const fn sized(start: u32, size: u32) -> Self

Create a new Span starting at start and covering size bytes.

Example

use oxc_span::Span;

let span = Span::sized(2, 4);
assert_eq!(span.size(), 4);
assert_eq!(span, Span::new(2, 6));

pub const fn size(self) -> u32

Get the number of bytes covered by the Span.

Example

use oxc_span::Span;

assert_eq!(Span::new(1, 1).size(), 0);
assert_eq!(Span::new(0, 5).size(), 5);
assert_eq!(Span::new(5, 10).size(), 5);

pub const fn is_empty(self) -> bool

Returns true if self covers a range of zero length.

Example

use oxc_span::Span;

assert!(Span::new(0, 0).is_empty());
assert!(Span::new(5, 5).is_empty());
assert!(!Span::new(0, 5).is_empty());

pub const fn is_unspanned(self) -> bool

Returns true if self is not a real span. i.e. SPAN which is used for generated nodes which are not in source code.

Example

use oxc_span::{Span, SPAN};

assert!(SPAN.is_unspanned());
assert!(!Span::new(0, 5).is_unspanned());
assert!(!Span::new(5, 5).is_unspanned());

pub const fn contains_inclusive(self, span: Span) -> bool

Check if this Span contains another Span.

Spans that start & end at the same position as this Span are considered contained.

Examples

let span = Span::new(5, 10);

assert!(span.contains_inclusive(span)); // always true for itself
assert!(span.contains_inclusive(Span::new(5, 5)));
assert!(span.contains_inclusive(Span::new(6, 10)));
assert!(span.contains_inclusive(Span::empty(5)));

assert!(!span.contains_inclusive(Span::new(4, 10)));
assert!(!span.contains_inclusive(Span::empty(0)));

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

Create a Span covering the maximum range of two Spans.

Example

use oxc_span::Span;

let span1 = Span::new(0, 5);
let span2 = Span::new(3, 8);
let merged_span = span1.merge(span2);
assert_eq!(merged_span, Span::new(0, 8));

pub fn expand(self, offset: u32) -> Self

Create a Span that is grown by offset on either side.

This is equivalent to span.expand_left(offset).expand_right(offset). See expand_left and expand_right for more info.

Example

use oxc_span::Span;

let span = Span::new(3, 5);
assert_eq!(span.expand(1), Span::new(2, 6));
// start and end cannot be expanded past `0` and `u32::MAX`, respectively
assert_eq!(span.expand(5), Span::new(0, 10));

pub fn shrink(self, offset: u32) -> Self

Create a Span that has its start and end positions shrunk by offset amount.

It is a logical error to shrink the start of the Span past its end position. This will panic in debug builds.

This is equivalent to span.shrink_left(offset).shrink_right(offset). See shrink_left and shrink_right for more info.

Example

use oxc_span::Span;
let span = Span::new(5, 10);
assert_eq!(span.shrink(2), Span::new(7, 8));

pub const fn expand_left(self, offset: u32) -> Self

Create a Span that has its start position moved to the left by offset bytes.

Example

use oxc_span::Span;

let a = Span::new(5, 10);
assert_eq!(a.expand_left(5), Span::new(0, 10));

Bounds

The leftmost bound of the span is clamped to 0. It is safe to call this method with a value larger than the start position.

use oxc_span::Span;

let a = Span::new(0, 5);
assert_eq!(a.expand_left(5), Span::new(0, 5));

pub const fn shrink_left(self, offset: u32) -> Self

Create a Span that has its start position moved to the right by offset bytes.

It is a logical error to shrink the start of the Span past its end position.

Example

use oxc_span::Span;

let a = Span::new(5, 10);
let shrunk = a.shrink_left(5);
assert_eq!(shrunk, Span::new(10, 10));

// Shrinking past the end of the span is a logical error that will panic
// in debug builds.
std::panic::catch_unwind(|| {
   shrunk.shrink_left(5);
});

pub const fn expand_right(self, offset: u32) -> Self

Create a Span that has its end position moved to the right by offset bytes.

Example

use oxc_span::Span;

let a = Span::new(5, 10);
assert_eq!(a.expand_right(5), Span::new(5, 15));

Bounds

The rightmost bound of the span is clamped to u32::MAX. It is safe to call this method with a value larger than the end position.

use oxc_span::Span;

let a = Span::new(0, u32::MAX);
assert_eq!(a.expand_right(5), Span::new(0, u32::MAX));

pub const fn shrink_right(self, offset: u32) -> Self

Create a Span that has its end position moved to the left by offset bytes.

It is a logical error to shrink the end of the Span past its start position.

Example

use oxc_span::Span;

let a = Span::new(5, 10);
let shrunk = a.shrink_right(5);
assert_eq!(shrunk, Span::new(5, 5));

// Shrinking past the start of the span is a logical error that will panic
// in debug builds.
std::panic::catch_unwind(|| {
   shrunk.shrink_right(5);
});

pub fn source_text(self, source_text: &str) -> &str

Get a snippet of text from a source string that the Span covers.

Example

use oxc_span::Span;

let source = "function add (a, b) { return a + b; }";
let name_span = Span::new(9, 12);
let name = name_span.source_text(source);
assert_eq!(name_span.size(), name.len() as u32);

pub fn label<S: Into<String>>(self, label: S) -> LabeledSpan

Create a LabeledSpan covering this Span with the given label.

Use Span::primary_label if this is the primary span for the diagnostic.

pub fn primary_label<S: Into<String>>(self, label: S) -> LabeledSpan

Creates a primary LabeledSpan covering this Span with the given label.

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<'a> CloneIn<'a> for Span

type Cloned = Span

The type of the cloned object.

fn clone_in(&self, _: &'a Allocator) -> Self

Clone self into the given allocator. allocator may be the same one that self is already in.

fn clone_in_with_semantic_ids( &self, allocator: &'new_alloc Allocator, ) -> Self::Cloned

Almost identical as clone_in, but for some special type, it will also clone the semantic ids. Please use this method only if you make sure semantic info is synced with the ast node.

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<'a> Dummy<'a> for Span

fn dummy(_allocator: &'a Allocator) -> Self

Create a dummy Span.

impl From<Range<u32>> for Span

fn from(range: Range<u32>) -> Self

Converts to this type from the input type.

impl From<Span> for LabeledSpan

fn from(val: Span) -> Self

Converts to this type from the input type.

impl From<Span> for SourceSpan

fn from(val: Span) -> Self

Converts to this type from the input type.

impl GetSpan for Span

fn span(&self) -> Span

Get the Span for an AST node.

impl GetSpanMut for Span

fn span_mut(&mut self) -> &mut Span

Get a mutable reference to an AST node’s Span.

impl Hash for Span

fn hash<H: Hasher>(&self, hasher: &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 CompactStr

type Output = str

The returned type after indexing.

fn index(&self, index: Span) -> &Self::Output

Performs the indexing (container[index]) operation.

impl Index<Span> for str

type Output = str

The returned type after indexing.

fn index(&self, index: Span) -> &Self::Output

Performs the indexing (container[index]) operation.

impl IndexMut<Span> for str

fn index_mut(&mut self, index: Span) -> &mut Self::Output

Performs the mutable indexing (container[index]) operation.

impl Ord for Span

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl PartialEq for Span

fn eq(&self, other: &Self) -> 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 PartialOrd for Span

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

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

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

Tests less than (for self and other) and is used by the < operator.

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

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

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

Tests greater than (for self and other) and is used by the > operator.

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

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

impl Copy for Span

impl Eq for Span