@@ -71,18 +71,27 @@ pub fn coords_at_pos(text: RopeSlice, pos: usize) -> Position {
7171
7272/// Convert (line, column) coordinates to a character index.
7373///
74−/// `is_1_width` specifies whether the position should be treated
75−/// as a block cursor or not. This effects how line-ends are handled.
76−/// `false` corresponds to properly round-tripping with `coords_at_pos()`,
77−/// whereas `true` will ensure that block cursors don't jump off the
78−/// end of the line.
74+/// If the `line` coordinate is beyond the end of the file, the EOF
75+/// position will be returned.
76+///
77+/// If the `column` coordinate is past the end of the given line, the
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.
83+///
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.
7988///
8089/// TODO: this should be changed to work in terms of visual row/column, not
8190/// 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 {
8392 let Position { row, col } = coords;
8493 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 {
8695 line_end_char_index(&text, row)
8796 } else {
8897 text.line_to_char((row + 1).min(text.len_lines()))