Struct Position 

pub struct Position {
    pub line: usize,
    pub column: usize,
    pub offset: usize,
}

Position in a source document using multiple coordinate systems.

This struct tracks a position using three different representations:

• Line/Column: CommonMark-style 1-based coordinates
• Absolute Offset: Byte offset from document start

Coordinate Systems

Line/Column (Primary for GTK Integration)

• line: 1-based line number (CommonMark convention)
• column: 1-based byte offset from the start of the line

Important: column is a BYTE offset, not a character offset!

• For ASCII: byte offset == character offset
• For UTF-8: Multi-byte characters cause divergence
  • Example: “Tëst” has ‘ë’ at byte columns 3-4, but char column 2
  • Example: “🎨” (emoji) occupies 4 bytes but is 1 character

Absolute Offset (For Debugging Only)

• offset: Absolute byte offset from document start
• Do NOT use for GTK TextIter positioning!
• Use line and column instead for robust conversion

Usage with GTK

When converting to GTK TextIter:

1. Convert line: parser_line (1-based) → gtk_line (0-based)
2. Get line text from GTK buffer
3. Convert column: byte_offset → char_offset using char_indices()
4. Set position: iter_at_line(gtk_line).set_line_offset(char_offset)

See the host editor’s cursor-conversion bridge for a reference implementation of byte-to-character offset mapping.

Fields

line: usize

Line number (1-based, CommonMark convention)

column: usize

Column as byte offset from line start (1-based, CommonMark convention)

Note: This is NOT a character offset! Multi-byte UTF-8 characters cause byte offsets to differ from character positions.

offset: usize

Absolute byte offset from document start

For debugging/logging only - do not use for GTK positioning!

Implementations

impl Position

pub fn new(line: usize, column: usize, offset: usize) -> Self

Create a new source position from 1-based line/column and absolute offset.

pub fn line_start_offset(&self) -> usize

Compute the absolute byte offset of the start of this position’s line.

Uses the invariant that column is a 1-based byte offset from the start of the line, and offset is the absolute byte offset from the start of the document. The formula is:

line_start_offset = offset - (column - 1)

This function uses saturating math to avoid underflow in case of malformed positions.

Trait Implementations

impl Clone for Position

fn clone(&self) -> Position

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Position

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for Position

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for Position

fn eq(&self, other: &Position) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Position

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Copy for Position

impl Eq for Position

impl StructuralPartialEq for Position