Struct oxc_span::Span

#[non_exhaustive]
#[repr(C)]
pub struct Span {
    pub start: u32,
    pub end: u32,
}

Newtype for working with text ranges

See the text-size crate for details. Utility methods can be copied from the text-size crate if they are needed. NOTE: u32 is sufficient for “all” reasonable programs. Larger than u32 is a 4GB JS file.

Hashing

Span’s implementation of Hash is a no-op so that AST nodes can be compared by hash. This makes them unsuitable for use as keys in a hash map.

use std::hash::{Hash, Hasher, DefaultHasher};
use oxc_span::Span;

let mut first = DefaultHasher::new();
let mut second = DefaultHasher::new();

Span::new(0, 5).hash(&mut first);
Span::new(10, 20).hash(&mut second);

assert_eq!(first.finish(), second.finish());

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

start: u32

end: u32

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<'a>(&self, source_text: &'a str) -> &'a 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.

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

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

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 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

impl GetSpanMut for Span

fn span_mut(&mut self) -> &mut 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 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 + PartialOrd,

Restrict a value to a certain interval.

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 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

impl StructuralPartialEq for Span