Struct SourceMap 

pub struct SourceMap { /* private fields */ }

Maps byte offsets back to proc_macro2 spans.

See the module documentation for the coordinate scheme.

Implementations

impl SourceMap

pub fn new() -> Self

Creates an empty map.

pub fn next_base(&self) -> Pos

The offset the next file added to this map will start at.

The preprocessor runs on a thread of its own, where a proc_macro2::Span — and therefore this map — cannot follow it, so it allocates the offsets of the files it opens itself and hands them back for SourceMap::add_included_file afterwards. This is what lets the two agree; see crate::analyze.

pub fn add_included_file( &mut self, name: impl Into<String>, text: String, directive_span: Span, ) -> FileId

Adds an #included file to the map.

The preprocessor uses this to bring headers into the same offset space as the macro body: positions inside the returned file resolve to directive_span — the span of the #include that pulled it in — and, since the file is not SourceFile::precise, diagnostics inside it carry their own file, line and column in the message.

pub fn files(&self) -> &[SourceFile]

All files, in insertion order.

pub fn file(&self, id: FileId) -> &SourceFile

Looks a file up by id.

Panics

Panics if id did not come from this map.

pub fn file_of(&self, pos: Pos) -> FileId

Returns the file that contains pos (the nearest one if pos falls in the gap between two files).

pub fn is_precise(&self, pos: Pos) -> bool

Whether diagnostics anywhere in the file holding pos can point at an exact location.

String-literal mode with a Subspan hook is precise range by range rather than file by file, so a diagnostic asks SourceMap::is_precise_at instead.

pub fn is_precise_at(&self, range: SourceRange) -> bool

Whether the span returned for range points at range itself.

pub fn line_col(&self, pos: Pos) -> (usize, usize)

The 1-based line and (character-counted) column of pos inside its file.

pub fn header_position(&self, pos: Pos) -> Option<(&str, usize, usize)>

(name, line, column) when pos is inside an #included file.

A diagnostic there is reported at the #include directive — that is the only place a procedural macro can point at — so the position inside the header travels in the message text instead, as header.h:12:5: message.

pub fn source_line(&self, pos: Pos) -> usize

The line number pos is named by in a diagnostic note, counted the way __LINE__ counts: a line of the enclosing .rs file for the macro’s own text, and a line of the header itself for an #included file.

pub fn span(&self, range: SourceRange) -> Span

The Rust span to blame for range.

See SourceMap::resolve for how it is found.

pub fn resolve(&self, range: SourceRange) -> (Span, bool)

The Rust span to blame for range, and whether it points at range itself rather than at something enclosing it.

A file whose caller supplied a Subspan hook asks it first: that is string-literal mode under the nightly feature, where the span can point at the exact bytes inside the literal.

Otherwise the resolution order is: the anchor containing range.start, then the first anchor overlapping range, then the anchor nearest to range.start, then the file’s fallback span. proc_macro::Span::join is unstable on every channel, so a range spanning several tokens resolves to its first token rather than to the whole range.

Trait Implementations

impl Default for SourceMap

fn default() -> Self

Returns the “default value” for a type.