Stabilize proc_macro::Span::{start,end,line,column}.

[m-ou-se]

This stabilizes part of #54725

Specifically, the part related to getting the location of a span:

impl Span {
    pub fn start(&self) -> Span; // Empty span at the start of this span
    pub fn end(&self) -> Span; // Empty span at the end of this span

    pub fn line(&self) -> usize; // Line where the span starts
    pub fn column(&self) -> usize; // Column where the span starts
}

History of this part of the API:

Originally, start and end returned a LineColumn struct (containing the line and column).

This has been simplified/changed:

• No more LineColumn: Span now directly has .line() and .column() methods. This means we can easily add .byte_offset() or .byte_range() in the future if we want to.
• Span::start() and Span::end() are now the equivalent of rustc's internal shrink_to_lo() and shrink_to_hi(). This means you can do e.g. span.end().column(), removing the need for a span.end_column() or similar.

[m-ou-se]

@rfcbot merge

[rfcbot]

Team member @m-ou-se has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @dtolnay
• @joshtriplett
• @m-ou-se

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[sam0x17]

This is the most exciting thing I've seen for the state of proc macros in years hahaha

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[Aloso]

Does Span::column() count code points, grapheme clusters, or something else? Does it include zero-width characters? It would be nice to have this documented.

[mamekoro]

Has there been a discussion about whether to change the return values of line() and column() from usize to NonZero<usize>?

I believe that using NonZero would have the advantage of eliminating confusion about whether it is 0-based or 1-based.

[m-ou-se]

Does Span::column() count code points, grapheme clusters, or something else? Does it include zero-width characters? It would be nice to have this documented.

Same as everywhere else in Rust, such as in format!("{x:40}") and .chars().count() etc.: codepoints (including zero width chars).

I'll document it.

[m-ou-se]

Has there been a discussion about whether to change the return values of line() and column() from usize to NonZero<usize>?

I believe that using NonZero would have the advantage of eliminating confusion about whether it is 0-based or 1-based.

The NonZero types can sometimes be a bit annoying to work with. In places where it is important for optimization (e.g. Option<NonZeroUsize> in perf-sensitive code) or correctness (e.g. avoid dividing by zero) it makes sense to pay the (small) ergonomics cost of using NonZero. But in this case, I don't think we're improving anyones lives by using NonZero for these methods.

I don't think there will be a lot of confusion: the line+column numbers are exactly what rustc would show for a diagnostic, and the line number matches you see in your editor. In text editors, code listings, compiler diagnostics, etc., line numbers always start at one.

Just documenting it seems more than enough.

[rfcbot]

The final comment period, with a disposition to merge, as per the review above, is now complete.

As the automated representative of the governance process, I would like to thank the author for their work and everyone else who contributed.

This will be merged soon.

[tgross35]

FCP completed above

r? tgross35
@bors r+ rollup

[bors]

📌 Commit c5c9362 has been approved by tgross35

It is now in the queue for this repository.