@@ -71,18 +71,27 @@ pub fn coords_at_pos(text: RopeSlice, pos: usize) -> Position {
72/// Convert (line, column) coordinates to a character index.
72/// Convert (line, column) coordinates to a character index.
74−/// `is_1_width` specifies whether the position should be treated
74+/// If the `line` coordinate is beyond the end of the file, the EOF
75−/// as a block cursor or not. This effects how line-ends are handled.
75+/// position will be returned.
76−/// `false` corresponds to properly round-tripping with `coords_at_pos()`,
76+///
77−/// whereas `true` will ensure that block cursors don't jump off the
77+/// If the `column` coordinate is past the end of the given line, the
78−/// end of the line.
78+/// line-end position will be returned. What constitutes the "line-end
79+/// position" depends on the parameter `limit_before_line_ending`. If it's
80+/// `true`, the line-end position will be just *before* the line ending
81+/// character. If `false` it will be just *after* the line ending
82+/// character--on the border between the current line and the next.
84+/// Usually you only want `limit_before_line_ending` to be `true` if you're working
85+/// with left-side block-cursor positions, as this prevents the the block cursor
86+/// from jumping to the next line. Otherwise you typically want it to be `false`,
87+/// such as when dealing with raw anchor/head positions.
80/// TODO: this should be changed to work in terms of visual row/column, not
89/// TODO: this should be changed to work in terms of visual row/column, not
81/// graphemes.
90/// graphemes.
82−pub fn pos_at_coords(text: RopeSlice, coords: Position, is_1_width: bool) -> usize {
91+pub fn pos_at_coords(text: RopeSlice, coords: Position, limit_before_line_ending: bool) -> usize {
83 let Position { row, col } = coords;
92 let Position { row, col } = coords;
84 let line_start = text.line_to_char(row);
93 let line_start = text.line_to_char(row);
85− let line_end = if is_1_width {
94+ let line_end = if limit_before_line_ending {
86 line_end_char_index(&text, row)
95 line_end_char_index(&text, row)
88 text.line_to_char((row + 1).min(text.len_lines()))
97 text.line_to_char((row + 1).min(text.len_lines()))