diff options
| -rw-r--r-- | runtime/doc/api.txt | 36 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 34 |
2 files changed, 38 insertions, 32 deletions
diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 257515d737..36325fb0ba 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -2238,7 +2238,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start} First line index - {end} Last line index (exclusive) + {end} Last line index, exclusive {strict_indexing} Whether out-of-bounds should be an error. @@ -2309,16 +2309,18 @@ nvim_buf_get_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, This differs from |nvim_buf_get_lines()| in that it allows retrieving only portions of a line. - Indexing is zero-based. Column indices are end-exclusive. + Indexing is zero-based. Row indices are end-inclusive, and + column indices are end-exclusive. Prefer |nvim_buf_get_lines()| when retrieving entire lines. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start_row} First line index - {start_col} Starting byte offset of first line - {end_row} Last line index - {end_col} Ending byte offset of last line (exclusive) + {start_col} Starting column (byte offset) on first line + {end_row} Last line index, inclusive + {end_col} Ending column (byte offset) on last line, + exclusive {opts} Optional parameters. Currently unused. Return: ~ @@ -2398,7 +2400,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement}) Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start} First line index - {end} Last line index (exclusive) + {end} Last line index, exclusive {strict_indexing} Whether out-of-bounds should be an error. {replacement} Array of lines to use as replacement @@ -2448,25 +2450,27 @@ nvim_buf_set_text({buffer}, {start_row}, {start_col}, {end_row}, {end_col}, {replacement}) Sets (replaces) a range in the buffer - This is recommended over nvim_buf_set_lines when only + This is recommended over |nvim_buf_set_lines()| when only modifying parts of a line, as extmarks will be preserved on non-modified parts of the touched lines. - Indexing is zero-based and end-exclusive. + Indexing is zero-based. Row indices are end-inclusive, and + column indices are end-exclusive. - To insert text at a given index, set `start` and `end` ranges - to the same index. To delete a range, set `replacement` to an - array containing an empty string, or simply an empty array. + To insert text at a given `(row, column)` location, use + `start_row = end_row = row` and `start_col = end_col = col`. + To delete the text in a range, use `replacement = {}`. - Prefer nvim_buf_set_lines when adding or deleting entire lines - only. + Prefer |nvim_buf_set_lines()| if you are only adding or + deleting entire lines. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer {start_row} First line index - {start_col} First column - {end_row} Last line index - {end_col} Last column + {start_col} Starting column (byte offset) on first line + {end_row} Last line index, inclusive + {end_col} Ending column (byte offset) on last line, + exclusive {replacement} Array of lines to use as replacement nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 45dadae1dd..9842975d62 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -262,7 +262,7 @@ void nvim__buf_redraw_range(Buffer buffer, Integer first, Integer last, Error *e /// @param channel_id /// @param buffer Buffer handle, or 0 for current buffer /// @param start First line index -/// @param end Last line index (exclusive) +/// @param end Last line index, exclusive /// @param strict_indexing Whether out-of-bounds should be an error. /// @param[out] err Error details, if any /// @return Array of lines, or empty array for unloaded buffer. @@ -358,7 +358,7 @@ static bool check_string_array(Array arr, bool disallow_nl, Error *err) /// @param channel_id /// @param buffer Buffer handle, or 0 for current buffer /// @param start First line index -/// @param end Last line index (exclusive) +/// @param end Last line index, exclusive /// @param strict_indexing Whether out-of-bounds should be an error. /// @param replacement Array of lines to use as replacement /// @param[out] err Error details, if any @@ -514,24 +514,25 @@ end: /// Sets (replaces) a range in the buffer /// -/// This is recommended over nvim_buf_set_lines when only modifying parts of a -/// line, as extmarks will be preserved on non-modified parts of the touched +/// This is recommended over |nvim_buf_set_lines()| when only modifying parts of +/// a line, as extmarks will be preserved on non-modified parts of the touched /// lines. /// -/// Indexing is zero-based and end-exclusive. +/// Indexing is zero-based. Row indices are end-inclusive, and column indices +/// are end-exclusive. /// -/// To insert text at a given index, set `start` and `end` ranges to the same -/// index. To delete a range, set `replacement` to an array containing -/// an empty string, or simply an empty array. +/// To insert text at a given `(row, column)` location, use `start_row = end_row +/// = row` and `start_col = end_col = col`. To delete the text in a range, use +/// `replacement = {}`. /// -/// Prefer nvim_buf_set_lines when adding or deleting entire lines only. +/// Prefer |nvim_buf_set_lines()| if you are only adding or deleting entire lines. /// /// @param channel_id /// @param buffer Buffer handle, or 0 for current buffer /// @param start_row First line index -/// @param start_col First column -/// @param end_row Last line index -/// @param end_col Last column +/// @param start_col Starting column (byte offset) on first line +/// @param end_row Last line index, inclusive +/// @param end_col Ending column (byte offset) on last line, exclusive /// @param replacement Array of lines to use as replacement /// @param[out] err Error details, if any void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, Integer start_col, @@ -760,16 +761,17 @@ end: /// This differs from |nvim_buf_get_lines()| in that it allows retrieving only /// portions of a line. /// -/// Indexing is zero-based. Column indices are end-exclusive. +/// Indexing is zero-based. Row indices are end-inclusive, and column indices +/// are end-exclusive. /// /// Prefer |nvim_buf_get_lines()| when retrieving entire lines. /// /// @param channel_id /// @param buffer Buffer handle, or 0 for current buffer /// @param start_row First line index -/// @param start_col Starting byte offset of first line -/// @param end_row Last line index -/// @param end_col Ending byte offset of last line (exclusive) +/// @param start_col Starting column (byte offset) on first line +/// @param end_row Last line index, inclusive +/// @param end_col Ending column (byte offset) on last line, exclusive /// @param opts Optional parameters. Currently unused. /// @param[out] err Error details, if any /// @return Array of lines, or empty array for unloaded buffer. |