Crate lsp_positions

Defines LSP-compatible positioning information for source code.

When writing a tool that analyzes or operates on source code, there’s a good chance you need to interoperate with the Language Server Protocol. This seemingly simple requirement makes it surprisingly difficult to deal with character locations. This is because Rust stores Unicode string content (i.e., the source code you’re analyzing) in UTF-8, while LSP specifies character locations using UTF-16 code units.

For some background, Unicode characters, or code points, are encoded as one or more code units. In UTF-8 a code unit is 1 byte, and a character is encoded in 1–4 code units (1–4 bytes). In UTF-16 a code unit is 2 bytes, and characters are encoded in 1–2 code units (2 or 4 bytes). Rust strings are encoded as UTF-8, and indexed by byte (which is the same as by code unit). Indices are only valid if they point to the first code unit of a code point.

We keep track of each source code position using two units: the UTF-8 byte position within the file or containing line, which can be used to index into UTF-8 encoded str and [u8] data, and the UTF-16 code unit position within the line, which can be used to generate Position values for LSP.

Structs

Offset

The offset of a character within a string (typically a line of source code), using several different units

Position

All of the position information that we have about a character in a source file

PositionedSubstring

A substring and information about where that substring occurs in a larger string. (Most often, this is a “line” and information about where that line occurs within a “file”.)

Span

All of the position information that we have about a range of content in a source file

SpanCalculator

Automates the construction of Span instances for content within a string.