Struct Span

#[repr(C)]
pub struct Span<'ast> { /* private fields */ }

A region of code, used for snipping, lint emission, and the retrieval of context information.

Spans provide context information, like the file location or macro expansion that created this span. SpanPos values from different sources or files should not be mixed. Check out the documentation of SpanPos for more information.

Spans don’t provide any way to map back to the AST nodes, that they belonged to. If you require this information, consider passing the nodes instead or alongside the Span.

Spans with invalid positions in the start or end value can cause panics in the driver. Please handle them with care, and also consider that UTF-8 allows multiple bytes per character. Instances provided by the API or driver directly, are always valid.

Handling macros during linting can be difficult, generally it’s advised to abort, if the code originates from a macro. The API provides an automatic way by setting the MacroReport value during lint creation. If your lint is targeting code from macro expansions, please consider that users might not be able to influence the generated code. It’s also worth checking that all linted nodes originate from the same macro expansion. Check out the documentation of ExpnInfo.

Implementations

impl<'ast> Span<'ast>

pub fn is_from_expansion(&self) -> bool

Returns true, if this Span comes from a macro expansion.

pub fn snippet(&self) -> Option<&'ast str>

Returns the code snippet that this Span refers to or None if the snippet is unavailable.

let variable = 15_000;
//             ^^^^^^
//             lit_span

lit_span.snippet(); // -> Some("15_000")

There are several reasons, why a snippet might be unavailable. Also depend on the used driver. You can also checkout the other snippet methods to better deal with these cases:

• snippet_or
• snippet_with_applicability

pub fn snippet_or<'a, 'b>(&self, default: &'a str) -> &'b str

where 'a: 'b, 'ast: 'b,

Returns the code snippet that this Span refers to or the given default if the snippet is unavailable.

For placeholders, it’s recommended to use angle brackets with information should be filled out. For example, if you want to snip an expression, you should use <expr> as the default value.

If you’re planning to use this snippet in a suggestion, consider using snippet_with_applicability instead.

pub fn snippet_with_applicability<'a, 'b>( &self, placeholder: &'a str, applicability: &mut Applicability, ) -> &'b str

where 'a: 'b, 'ast: 'b,

Adjusts the given Applicability according to the context and returns the code snippet that this Span refers to or the given default if the snippet is unavailable.

For the placeholder, it’s recommended to use angle brackets with information should be filled out. A placeholder for an expression should look like this: <expr>

The applicability will never be upgraded by this method. When you draft suggestions, you’ll generally start with the highest Applicability your suggestion should have, and then use it with this snippet function to adjust it accordingly. The applicability is then used to submit the suggestion to the driver.

Here is an example, for constructing a string with two expressions a and b:

let mut app = Applicability::MachineApplicable;
let sugg = format!(
    "{}..{}",
    a.span().snippet_with_applicability("<expr-a>", &mut app),
    b.span().snippet_with_applicability("<expr-b>", &mut app),
);

pub fn len(&self) -> usize

Returns the length of the this Span in bytes.

pub fn is_empty(&self) -> bool

Returns true if the span has a length of 0. This means that no bytes are inside the span.

pub fn start(&self) -> SpanPos

Returns the start position of this Span.

pub fn set_start(&mut self, start: SpanPos)

Sets the start position of this Span.

pub fn with_start(&self, start: SpanPos) -> Span<'ast>

Returns a new Span with the given start position.

pub fn end(&self) -> SpanPos

Returns the end position of this Span.

pub fn set_end(&mut self, end: SpanPos)

Sets the end position of this Span.

pub fn with_end(&self, end: SpanPos) -> Span<'ast>

Returns a new Span with the given end position.

pub fn source(&self) -> SpanSource<'ast>

Trait Implementations

impl<'ast> Clone for Span<'ast>

fn clone(&self) -> Span<'ast>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'ast> Debug for Span<'ast>

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

Formats the value using the given formatter.

impl<'ast> HasSpan<'ast> for Span<'ast>

fn span(&self) -> &Span<'ast>

This returns the Span of the implementing AST node.