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
) setspan.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 bothSpan
andSpanData
, which means thatlo
values never cause interning. The number of bits needed forlo
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 inSpan
(a u16, minus 1 bit for PARENT_TAG) and 32 bits inSpanData
, which means that largelen
values will cause interning. The number of bits needed forlen
does not depend on the crate size. The most common numbers of bits forlen
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 inSpan
and two 32 bit fields inSpanData
, which means intering will happen ifctxt
is large, ifparent
is large, or if both values are non-zero. The number of bits needed forctxt
values depend partly on the crate size and partly on the form of the code. No crates inrustc-perf
need more than 15 bits forctxt_or_parent_or_marker
, but larger crates might need more than 16 bits. The number of bits needed forparent
hasn’t been measured, becauseparent
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
impl Span
sourcepub fn mark_with_reason(
self,
allow_internal_unstable: Option<Lrc<[Symbol]>>,
reason: DesugaringKind,
edition: Edition,
ctx: impl HashStableContext,
) -> Span
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
impl Span
pub fn new( lo: BytePos, hi: BytePos, ctxt: SyntaxContext, parent: Option<LocalDefId>, ) -> Self
pub fn data(self) -> SpanData
sourcepub fn data_untracked(self) -> SpanData
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.
pub fn map_ctxt(self, map: impl FnOnce(SyntaxContext) -> SyntaxContext) -> Span
fn inline_ctxt(self) -> Result<SyntaxContext, usize>
sourcepub fn ctxt(self) -> SyntaxContext
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
.
pub fn eq_ctxt(self, other: Span) -> bool
pub fn with_parent(self, parent: Option<LocalDefId>) -> Span
pub fn parent(self) -> Option<LocalDefId>
source§impl Span
impl Span
pub fn lo(self) -> BytePos
pub fn with_lo(self, lo: BytePos) -> Span
pub fn hi(self) -> BytePos
pub fn with_hi(self, hi: BytePos) -> Span
pub fn with_ctxt(self, ctxt: SyntaxContext) -> Span
pub fn is_visible(self, sm: &SourceMap) -> bool
sourcepub fn from_expansion(self) -> bool
pub fn from_expansion(self) -> bool
Returns true
if this span comes from any kind of macro, desugaring or inlining.
sourcepub fn in_derive_expansion(self) -> bool
pub fn in_derive_expansion(self) -> bool
Returns true
if span
originates in a derive-macro’s expansion.
sourcepub fn can_be_used_for_suggestions(self) -> bool
pub fn can_be_used_for_suggestions(self) -> bool
Gate suggestions that would not be appropriate in a context the user didn’t write.
pub fn with_root_ctxt(lo: BytePos, hi: BytePos) -> Span
sourcepub fn shrink_to_lo(self) -> Span
pub fn shrink_to_lo(self) -> Span
Returns a new span representing an empty span at the beginning of this span.
sourcepub fn shrink_to_hi(self) -> Span
pub fn shrink_to_hi(self) -> Span
Returns a new span representing an empty span at the end of this span.
sourcepub fn substitute_dummy(self, other: Span) -> Span
pub fn substitute_dummy(self, other: Span) -> Span
Returns self
if self
is not the dummy span, and other
otherwise.
sourcepub fn overlaps_or_adjacent(self, other: Span) -> bool
pub fn overlaps_or_adjacent(self, other: Span) -> bool
Returns true
if self
touches or adjoins other
.
sourcepub fn source_equal(self, other: Span) -> bool
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.
sourcepub fn trim_start(self, other: Span) -> Option<Span>
pub fn trim_start(self, other: Span) -> Option<Span>
Returns Some(span)
, where the start is trimmed by the end of other
.
sourcepub fn trim_end(self, other: Span) -> Option<Span>
pub fn trim_end(self, other: Span) -> Option<Span>
Returns Some(span)
, where the end is trimmed by the start of other
.
sourcepub fn source_callsite(self) -> Span
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.
sourcepub fn parent_callsite(self) -> Option<Span>
pub fn parent_callsite(self) -> Option<Span>
The Span
for the tokens in the previous macro expansion from which self
was generated,
if any.
sourcepub fn find_ancestor_inside(self, outer: Span) -> Option<Span>
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.
sourcepub fn find_ancestor_in_same_ctxt(self, other: Span) -> Option<Span>
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).
sourcepub fn find_ancestor_inside_same_ctxt(self, outer: Span) -> Option<Span>
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.
sourcepub fn find_oldest_ancestor_in_same_ctxt(self) -> Span
pub fn find_oldest_ancestor_in_same_ctxt(self) -> Span
Recursively walk down the expansion ancestors to find the oldest ancestor span with the same
SyntaxContext
the initial span.
This method is suitable for peeling through local macro expansions to find the “innermost”
span that is still local and shares the same SyntaxContext
. For example, given
macro_rules! outer {
($x: expr) => {
inner!($x)
}
}
macro_rules! inner {
($x: expr) => {
format!("error: {}", $x)
//~^ ERROR mismatched types
}
}
fn bar(x: &str) -> Result<(), Box<dyn std::error::Error>> {
Err(outer!(x))
}
if provided the initial span of outer!(x)
inside bar
, this method will recurse
the parent callsites until we reach format!("error: {}", $x)
, at which point it is the
oldest ancestor span that is both still local and shares the same SyntaxContext
as the
initial span.
sourcepub fn is_rust_2015(self) -> bool
pub fn is_rust_2015(self) -> bool
Is this edition 2015?
sourcepub fn at_least_rust_2018(self) -> bool
pub fn at_least_rust_2018(self) -> bool
Are we allowed to use features from the Rust 2018 edition?
sourcepub fn at_least_rust_2021(self) -> bool
pub fn at_least_rust_2021(self) -> bool
Are we allowed to use features from the Rust 2021 edition?
sourcepub fn at_least_rust_2024(self) -> bool
pub fn at_least_rust_2024(self) -> bool
Are we allowed to use features from the Rust 2024 edition?
sourcepub fn source_callee(self) -> Option<ExpnData>
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.
sourcepub fn allows_unstable(self, feature: Symbol) -> bool
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]
).
sourcepub fn is_desugaring(self, kind: DesugaringKind) -> bool
pub fn is_desugaring(self, kind: DesugaringKind) -> bool
Checks if this span arises from a compiler desugaring of kind kind
.
sourcepub fn desugaring_kind(self) -> Option<DesugaringKind>
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.
sourcepub fn allows_unsafe(self) -> bool
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]
).
pub fn macro_backtrace(self) -> impl Iterator<Item = ExpnData>
sourcepub fn split_at(self, pos: u32) -> (Span, Span)
pub fn split_at(self, pos: u32) -> (Span, Span)
Splits a span into two composite spans around a certain position.
sourcepub(crate) fn try_metavars(
a: SpanData,
b: SpanData,
a_orig: Span,
b_orig: Span,
) -> (SpanData, SpanData)
pub(crate) fn try_metavars( a: SpanData, b: SpanData, a_orig: Span, b_orig: Span, ) -> (SpanData, SpanData)
Check if you can select metavar spans for the given spans to get matching contexts.
sourcepub(crate) fn prepare_to_combine(
a_orig: Span,
b_orig: Span,
) -> Result<(SpanData, SpanData, Option<LocalDefId>), Span>
pub(crate) fn prepare_to_combine( a_orig: Span, b_orig: Span, ) -> Result<(SpanData, SpanData, Option<LocalDefId>), Span>
Prepare two spans to a combine operation like to
or between
.
sourcepub fn with_neighbor(self, neighbor: Span) -> Span
pub fn with_neighbor(self, neighbor: Span) -> Span
This span, but in a larger context, may switch to the metavariable span if suitable.
sourcepub fn to(self, end: Span) -> Span
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
^^^^^^^^^^^^^^^^^^^^
sourcepub fn between(self, end: Span) -> Span
pub fn between(self, end: Span) -> Span
Returns a Span
between the end of self
to the beginning of end
.
____ ___
self lorem ipsum end
^^^^^^^^^^^^^
sourcepub fn until(self, end: Span) -> Span
pub fn until(self, end: Span) -> Span
Returns a Span
from the beginning of self
until the beginning of end
.
____ ___
self lorem ipsum end
^^^^^^^^^^^^^^^^^
pub fn from_inner(self, inner: InnerSpan) -> Span
sourcepub fn with_def_site_ctxt(self, expn_id: ExpnId) -> Span
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.
sourcepub fn with_call_site_ctxt(self, expn_id: ExpnId) -> Span
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.
sourcepub fn with_mixed_site_ctxt(self, expn_id: ExpnId) -> Span
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.
sourcepub(crate) fn with_ctxt_from_mark(
self,
expn_id: ExpnId,
transparency: Transparency,
) -> Span
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).
pub fn apply_mark(self, expn_id: ExpnId, transparency: Transparency) -> Span
pub fn remove_mark(&mut self) -> ExpnId
pub fn adjust(&mut self, expn_id: ExpnId) -> Option<ExpnId>
pub fn normalize_to_macros_2_0_and_adjust( &mut self, expn_id: ExpnId, ) -> Option<ExpnId>
pub fn glob_adjust( &mut self, expn_id: ExpnId, glob_span: Span, ) -> Option<Option<ExpnId>>
pub fn reverse_glob_adjust( &mut self, expn_id: ExpnId, glob_span: Span, ) -> Option<Option<ExpnId>>
pub fn normalize_to_macros_2_0(self) -> Span
pub fn normalize_to_macro_rules(self) -> Span
Trait Implementations§
source§impl<CTX> HashStable<CTX> for Spanwhere
CTX: HashStableContext,
impl<CTX> HashStable<CTX> for Spanwhere
CTX: HashStableContext,
source§fn hash_stable(&self, ctx: &mut CTX, hasher: &mut StableHasher)
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
impl Ord for Span
source§impl PartialEq for Span
impl PartialEq for Span
source§impl PartialOrd for Span
impl PartialOrd for Span
1.0.0 · source§fn le(&self, other: &Rhs) -> bool
fn le(&self, other: &Rhs) -> bool
self
and other
) and is used by the <=
operator. Read moreimpl Copy for Span
impl Eq for Span
impl !Send for Span
impl StructuralPartialEq for Span
impl !Sync for Span
Auto Trait Implementations§
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
source§impl<T> CloneToUninit for Twhere
T: Copy,
impl<T> CloneToUninit for Twhere
T: Copy,
source§unsafe fn clone_to_uninit(&self, dst: *mut T)
unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<T> CloneToUninit for Twhere
T: Clone,
impl<T> CloneToUninit for Twhere
T: Clone,
source§default unsafe fn clone_to_uninit(&self, dst: *mut T)
default unsafe fn clone_to_uninit(&self, dst: *mut T)
clone_to_uninit
)source§impl<Q, K> Comparable<K> for Q
impl<Q, K> Comparable<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§impl<Q, K> Equivalent<K> for Q
impl<Q, K> Equivalent<K> for Q
source§fn equivalent(&self, key: &K) -> bool
fn equivalent(&self, key: &K) -> bool
key
and return true
if they are equal.source§impl<T> Instrument for T
impl<T> Instrument for T
source§fn instrument(self, span: Span) -> Instrumented<Self>
fn instrument(self, span: Span) -> Instrumented<Self>
source§fn in_current_span(self) -> Instrumented<Self>
fn in_current_span(self) -> Instrumented<Self>
source§impl<T> IntoEither for T
impl<T> IntoEither for T
source§fn into_either(self, into_left: bool) -> Either<Self, Self>
fn into_either(self, into_left: bool) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left
is true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
self
into a Left
variant of Either<Self, Self>
if into_left(&self)
returns true
.
Converts self
into a Right
variant of Either<Self, Self>
otherwise. Read moresource§impl<T> WithSubscriber for T
impl<T> WithSubscriber for T
source§fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
source§fn with_current_subscriber(self) -> WithDispatch<Self>
fn with_current_subscriber(self) -> WithDispatch<Self>
impl<'a, T> Captures<'a> for Twhere
T: ?Sized,
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