pub struct Span {
    base_or_index: u32,
    len_or_tag: u16,
    ctxt_or_zero: u16,
}
Expand description

A compressed span.

Whereas SpanData is 12 bytes, which is a bit too big to stick everywhere, Span is a form that only takes up 8 bytes, with less space for the length and context. The vast majority (99.9%+) of SpanData instances will 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.

Inline (compressed) format:

  • span.base_or_index == span_data.lo
  • span.len_or_tag == len == span_data.hi - span_data.lo (must be <= MAX_LEN)
  • span.ctxt == span_data.ctxt (must be <= MAX_CTXT)

Interned format:

  • span.base_or_index == index (indexes into the interner table)
  • span.len_or_tag == LEN_TAG (high bit set, all other bits are zero)
  • span.ctxt == 0

The inline form uses 0 for the tag value (rather than 1) so that we don’t need to mask out the tag bit when getting the length, and so that the dummy span can be all zeroes.

Notes about the choice of field sizes:

  • base is 32 bits in both Span and SpanData, which means that base values never cause interning. The number of bits needed for base depends on the crate size. 32 bits allows up to 4 GiB of code in a crate.
  • len is 15 bits in Span (a u16, minus 1 bit for the 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 is 16 bits in Span and 32 bits in SpanData, which means that large ctxt values will cause interning. 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, but larger crates might need more than 16 bits.

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

base_or_index: u32len_or_tag: u16ctxt_or_zero: u16

Implementations

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.

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

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

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

Returns true if this span comes from a macro or desugaring.

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

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

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

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

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

Returns true if hi == lo.

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

Returns true if self fully encloses other.

Returns true if self touches other.

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.

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

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

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

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

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

Edition of the crate from which this span came.

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.

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]).

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

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

Checks if a span is “internal” to a macro in which unsafe can be used without triggering the unsafe_code lint.

Returns a Span that would enclose both self and end.

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

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

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

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

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

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

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

Equivalent of Span::mixed_site from the proc macro API, except that the location is taken from the self 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).

Trait Implementations

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Returns the “default value” for a type. Read more
Feeds this value into the given Hasher. Read more
Feeds a slice of this type into the given Hasher. Read more

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.

This method returns an Ordering between self and other. Read more
Compares and returns the maximum of two values. Read more
Compares and returns the minimum of two values. Read more
Restrict a value to a certain interval. Read more
This method tests for self and other values to be equal, and is used by ==. Read more
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason. Read more
This method returns an ordering between self and other values if one exists. Read more
This method tests less than (for self and other) and is used by the < operator. Read more
This method tests less than or equal to (for self and other) and is used by the <= operator. Read more
This method tests greater than (for self and other) and is used by the > operator. Read more
This method tests greater than or equal to (for self and other) and is used by the >= operator. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

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

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion 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