Struct rustc_span::Span

source ·
pub struct Span {
    lo_or_index: u32,
    len_with_tag_or_marker: u16,
    ctxt_or_parent_or_marker: u16,
}
Expand description

A compressed span.

SpanData is 16 bytes, which is too big to stick everywhere. Span only takes up 8 bytes, with less space for the length, parent and context. The vast majority (99.9%+) of SpanData instances can be made to fit within those 8 bytes. Any SpanData whose fields don’t fit into a Span are stored in a separate interner table, and the Span will index into that table. Interning is rare enough that the cost is low, but common enough that the code is exercised regularly.

An earlier version of this code used only 4 bytes for Span, but that was slower because only 80–90% of spans could be stored inline (even less in very large crates) and so the interner was used a lot more. That version of the code also predated the storage of parents.

There are four different span forms.

Inline-context format (requires non-huge length, non-huge context, and no parent):

  • span.lo_or_index == span_data.lo
  • span.len_with_tag_or_marker == len == span_data.hi - span_data.lo (must be <= MAX_LEN)
  • span.ctxt_or_parent_or_marker == span_data.ctxt (must be <= MAX_CTXT)

Inline-parent format (requires non-huge length, root context, and non-huge parent):

  • span.lo_or_index == span_data.lo
  • span.len_with_tag_or_marker & !PARENT_TAG == len == span_data.hi - span_data.lo (must be <= MAX_LEN)
  • span.len_with_tag_or_marker has top bit (PARENT_TAG) set
  • span.ctxt_or_parent_or_marker == span_data.parent (must be <= MAX_CTXT)

Partially-interned format (requires non-huge context):

  • span.lo_or_index == index (indexes into the interner table)
  • span.len_with_tag_or_marker == BASE_LEN_INTERNED_MARKER
  • span.ctxt_or_parent_or_marker == span_data.ctxt (must be <= MAX_CTXT)

Fully-interned format (all cases not covered above):

  • span.lo_or_index == index (indexes into the interner table)
  • span.len_with_tag_or_marker == BASE_LEN_INTERNED_MARKER
  • span.ctxt_or_parent_or_marker == CTXT_INTERNED_MARKER

The partially-interned form requires looking in the interning table for lo and length, but the context is stored inline as well as interned. This is useful because context lookups are often done in isolation, and inline lookups are quicker.

Notes about the choice of field sizes:

  • lo is 32 bits in both Span and SpanData, which means that lo values never cause interning. The number of bits needed for lo depends on the crate size. 32 bits allows up to 4 GiB of code in a crate. Having no compression on this field means there is no performance cliff if a crate exceeds a particular size.
  • len is ~15 bits in Span (a u16, minus 1 bit for PARENT_TAG) and 32 bits in SpanData, which means that large len values will cause interning. The number of bits needed for len does not depend on the crate size. The most common numbers of bits for len are from 0 to 7, with a peak usually at 3 or 4, and then it drops off quickly from 8 onwards. 15 bits is enough for 99.99%+ of cases, but larger values (sometimes 20+ bits) might occur dozens of times in a typical crate.
  • ctxt_or_parent_or_marker is 16 bits in Span and two 32 bit fields in SpanData, which means intering will happen if ctxt is large, if parent is large, or if both values are non-zero. The number of bits needed for ctxt values depend partly on the crate size and partly on the form of the code. No crates in rustc-perf need more than 15 bits for ctxt_or_parent_or_marker, but larger crates might need more than 16 bits. The number of bits needed for parent hasn’t been measured, because parent isn’t currently used by default.

In order to reliably use parented spans in incremental compilation, the dependency to the parent definition’s span. This is performed using the callback SPAN_TRACK to access the query engine.

Fields§

§lo_or_index: u32§len_with_tag_or_marker: u16§ctxt_or_parent_or_marker: u16

Implementations§

source§

impl Span

source

pub fn fresh_expansion(self, expn_id: LocalExpnId) -> Span

Creates a fresh expansion with given properties. Expansions are normally created by macros, but in some cases expansions are created for other compiler-generated code to set per-span properties like allowed unstable features. The returned span belongs to the created expansion and has the new properties, but its location is inherited from the current span.

source

pub fn mark_with_reason( self, allow_internal_unstable: Option<Lrc<[Symbol]>>, reason: DesugaringKind, edition: Edition, ctx: impl HashStableContext ) -> Span

Reuses the span but adds information like the kind of the desugaring and features that are allowed inside this span.

source§

impl Span

source

pub fn new( lo: BytePos, hi: BytePos, ctxt: SyntaxContext, parent: Option<LocalDefId> ) -> Self

source

pub fn data(self) -> SpanData

source

pub fn data_untracked(self) -> SpanData

Internal function to translate between an encoded span and the expanded representation. This function must not be used outside the incremental engine.

source

pub fn is_dummy(self) -> bool

Returns true if this is a dummy span with any hygienic context.

source

pub fn ctxt(self) -> SyntaxContext

This function is used as a fast path when decoding the full SpanData is not necessary. It’s a cut-down version of data_untracked.

source§

impl Span

source

pub fn lo(self) -> BytePos

source

pub fn with_lo(self, lo: BytePos) -> Span

source

pub fn hi(self) -> BytePos

source

pub fn with_hi(self, hi: BytePos) -> Span

source

pub fn eq_ctxt(self, other: Span) -> bool

source

pub fn with_ctxt(self, ctxt: SyntaxContext) -> Span

source

pub fn parent(self) -> Option<LocalDefId>

source

pub fn with_parent(self, ctxt: Option<LocalDefId>) -> Span

source

pub fn is_visible(self, sm: &SourceMap) -> bool

source

pub fn from_expansion(self) -> bool

Returns true if this span comes from any kind of macro, desugaring or inlining.

source

pub fn in_macro_expansion_with_collapse_debuginfo(self) -> bool

Returns true if span originates in a macro’s expansion where debuginfo should be collapsed.

source

pub fn in_derive_expansion(self) -> bool

Returns true if span originates in a derive-macro’s expansion.

source

pub fn can_be_used_for_suggestions(self) -> bool

Gate suggestions that would not be appropriate in a context the user didn’t write.

source

pub fn with_root_ctxt(lo: BytePos, hi: BytePos) -> Span

source

pub fn shrink_to_lo(self) -> Span

Returns a new span representing an empty span at the beginning of this span.

source

pub fn shrink_to_hi(self) -> Span

Returns a new span representing an empty span at the end of this span.

source

pub fn is_empty(self) -> bool

Returns true if hi == lo.

source

pub fn substitute_dummy(self, other: Span) -> Span

Returns self if self is not the dummy span, and other otherwise.

source

pub fn contains(self, other: Span) -> bool

Returns true if self fully encloses other.

source

pub fn overlaps(self, other: Span) -> bool

Returns true if self touches other.

source

pub fn source_equal(self, other: Span) -> bool

Returns true if the spans are equal with regards to the source text.

Use this instead of == when either span could be generated code, and you only care that they point to the same bytes of source text.

source

pub fn trim_start(self, other: Span) -> Option<Span>

Returns Some(span), where the start is trimmed by the end of other.

source

pub fn source_callsite(self) -> Span

Returns the source span – this is either the supplied span, or the span for the macro callsite that expanded to it.

source

pub fn parent_callsite(self) -> Option<Span>

The Span for the tokens in the previous macro expansion from which self was generated, if any.

source

pub fn find_ancestor_inside(self, outer: Span) -> Option<Span>

Walk down the expansion ancestors to find a span that’s contained within outer.

The span returned by this method may have a different SyntaxContext as outer. If you need to extend the span, use find_ancestor_inside_same_ctxt instead, because joining spans with different syntax contexts can create unexpected results.

source

pub fn find_ancestor_in_same_ctxt(self, other: Span) -> Option<Span>

Walk down the expansion ancestors to find a span with the same SyntaxContext as other.

Like find_ancestor_inside_same_ctxt, but specifically for when spans might not overlap. Take care when using this, and prefer find_ancestor_inside or find_ancestor_inside_same_ctxt when you know that the spans are nested (modulo macro expansion).

source

pub fn find_ancestor_inside_same_ctxt(self, outer: Span) -> Option<Span>

Walk down the expansion ancestors to find a span that’s contained within outer and has the same SyntaxContext as outer.

This method is the combination of find_ancestor_inside and find_ancestor_in_same_ctxt and should be preferred when extending the returned span. If you do not need to modify the span, use find_ancestor_inside instead.

source

pub fn edition(self) -> Edition

Edition of the crate from which this span came.

source

pub fn is_rust_2015(self) -> bool

Is this edition 2015?

source

pub fn at_least_rust_2018(self) -> bool

Are we allowed to use features from the Rust 2018 edition?

source

pub fn at_least_rust_2021(self) -> bool

Are we allowed to use features from the Rust 2021 edition?

source

pub fn at_least_rust_2024(self) -> bool

Are we allowed to use features from the Rust 2024 edition?

source

pub fn source_callee(self) -> Option<ExpnData>

Returns the source callee.

Returns None if the supplied span has no expansion trace, else returns the ExpnData for the macro definition corresponding to the source callsite.

source

pub fn allows_unstable(self, feature: Symbol) -> bool

Checks if a span is “internal” to a macro in which #[unstable] items can be used (that is, a macro marked with #[allow_internal_unstable]).

source

pub fn is_desugaring(self, kind: DesugaringKind) -> bool

Checks if this span arises from a compiler desugaring of kind kind.

source

pub fn desugaring_kind(self) -> Option<DesugaringKind>

Returns the compiler desugaring that created this span, or None if this span is not from a desugaring.

source

pub fn allows_unsafe(self) -> bool

Checks if a span is “internal” to a macro in which unsafe can be used without triggering the unsafe_code lint. (that is, a macro marked with #[allow_internal_unsafe]).

source

pub fn macro_backtrace(self) -> impl Iterator<Item = ExpnData>

source

pub fn split_at(self, pos: u32) -> (Span, Span)

Splits a span into two composite spans around a certain position.

source

pub fn to(self, end: Span) -> Span

Returns a Span that would enclose both self and end.

Note that this can also be used to extend the span “backwards”: start.to(end) and end.to(start) return the same Span.

    ____             ___
    self lorem ipsum end
    ^^^^^^^^^^^^^^^^^^^^
source

pub fn between(self, end: Span) -> Span

Returns a Span between the end of self to the beginning of end.

    ____             ___
    self lorem ipsum end
        ^^^^^^^^^^^^^
source

pub fn until(self, end: Span) -> Span

Returns a Span from the beginning of self until the beginning of end.

    ____             ___
    self lorem ipsum end
    ^^^^^^^^^^^^^^^^^
source

pub fn from_inner(self, inner: InnerSpan) -> Span

source

pub fn with_def_site_ctxt(self, expn_id: ExpnId) -> Span

Equivalent of Span::def_site from the proc macro API, except that the location is taken from the self span.

source

pub fn with_call_site_ctxt(self, expn_id: ExpnId) -> Span

Equivalent of Span::call_site from the proc macro API, except that the location is taken from the self span.

source

pub fn with_mixed_site_ctxt(self, expn_id: ExpnId) -> Span

Equivalent of Span::mixed_site from the proc macro API, except that the location is taken from the self span.

source

pub(crate) fn with_ctxt_from_mark( self, expn_id: ExpnId, transparency: Transparency ) -> Span

Produces a span with the same location as self and context produced by a macro with the given ID and transparency, assuming that macro was defined directly and not produced by some other macro (which is the case for built-in and procedural macros).

source

pub fn apply_mark(self, expn_id: ExpnId, transparency: Transparency) -> Span

source

pub fn remove_mark(&mut self) -> ExpnId

source

pub fn adjust(&mut self, expn_id: ExpnId) -> Option<ExpnId>

source

pub fn normalize_to_macros_2_0_and_adjust( &mut self, expn_id: ExpnId ) -> Option<ExpnId>

source

pub fn glob_adjust( &mut self, expn_id: ExpnId, glob_span: Span ) -> Option<Option<ExpnId>>

source

pub fn reverse_glob_adjust( &mut self, expn_id: ExpnId, glob_span: Span ) -> Option<Option<ExpnId>>

source

pub fn normalize_to_macros_2_0(self) -> Span

source

pub fn normalize_to_macro_rules(self) -> Span

Trait Implementations§

source§

impl Clone for Span

source§

fn clone(&self) -> Span

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

impl Debug for Span

source§

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

Formats the value using the given formatter. Read more
source§

impl<D: Decoder> Decodable<D> for Span

source§

default fn decode(s: &mut D) -> Span

source§

impl Default for Span

source§

fn default() -> Self

Returns the “default value” for a type. Read more
source§

impl<E: Encoder> Encodable<E> for Span

source§

default fn encode(&self, s: &mut E)

source§

impl Hash for Span

source§

fn hash<__H: Hasher>(&self, state: &mut __H)

Feeds this value into the given Hasher. Read more
1.3.0 · source§

fn hash_slice<H>(data: &[Self], state: &mut H)
where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher. Read more
source§

impl<CTX> HashStable<CTX> for Span
where CTX: HashStableContext,

source§

fn hash_stable(&self, ctx: &mut CTX, hasher: &mut StableHasher)

Hashes a span in a stable way. We can’t directly hash the span’s BytePos fields (that would be similar to hashing pointers, since those are just offsets into the SourceMap). Instead, we hash the (file name, line, column) triple, which stays the same even if the containing SourceFile has moved within the SourceMap.

Also note that we are hashing byte offsets for the column, not unicode codepoint offsets. For the purpose of the hash that’s sufficient. Also, hashing filenames is expensive so we avoid doing it twice when the span starts and ends in the same file, which is almost always the case.

source§

impl Ord for Span

source§

fn cmp(&self, rhs: &Self) -> Ordering

This method returns an Ordering between self and other. Read more
1.21.0 · source§

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

Compares and returns the maximum of two values. Read more
1.21.0 · source§

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

Compares and returns the minimum of two values. Read more
1.50.0 · source§

fn clamp(self, min: Self, max: Self) -> Self
where Self: Sized + PartialOrd,

Restrict a value to a certain interval. Read more
source§

impl PartialEq for Span

source§

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

This method tests for self and other values to be equal, and is used by ==.
1.0.0 · source§

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

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
source§

impl PartialOrd for Span

source§

fn partial_cmp(&self, rhs: &Self) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · source§

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

This method tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · source§

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

This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · source§

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

This method tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · source§

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

This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more
source§

impl Copy for Span

source§

impl Eq for Span

source§

impl !Send for Span

source§

impl StructuralEq for Span

source§

impl StructuralPartialEq for Span

source§

impl !Sync for Span

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T> ToOwned for T
where T: Clone,

§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.

Layout§

Note: Most layout information is completely unstable and may even differ between compilations. The only exception is types with certain repr(...) attributes. Please see the Rust Reference's “Type Layout” chapter for details on type layout guarantees.

Size: 8 bytes