IntenseFinance/neovim
3
0
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2025-02-25 18:55:25 -06:00
Code Issues Packages Projects Releases Wiki Activity

docs: nvim_buf_[get|set]_[text|lines] (#18404)

Browse Source 
- Use consistent formatting for args docs.
- Clarify inclusivity/exclusivity in `nvim_buf_[get|set]_text`.
This commit is contained in:
Andrey Mishchenko 2022-05-11 20:05:56 -04:00 committed by GitHub
parent 7900a8b713
commit 60b1e314ed
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
2 changed files with 38 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
runtime/doc/api.txt
View File

@ -2238,7 +2238,7 @@ nvim_buf_get_lines({buffer}, {start}, {end}, {strict_indexing})
Parameters: ~ Parameters: ~
{buffer} Buffer handle, or 0 for current buffer {buffer} Buffer handle, or 0 for current buffer
{start} First line index {start} First line index
{end} Last line index (exclusive) {end} Last line index, exclusive
{strict_indexing} Whether out-of-bounds should be an {strict_indexing} Whether out-of-bounds should be an
error. 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 This differs from |nvim_buf_get_lines()| in that it allows
retrieving only portions of a line. 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. Prefer |nvim_buf_get_lines()| when retrieving entire lines.
Parameters: ~ Parameters: ~
{buffer} Buffer handle, or 0 for current buffer {buffer} Buffer handle, or 0 for current buffer
{start_row} First line index {start_row} First line index
{start_col} Starting byte offset of first line {start_col} Starting column (byte offset) on first line
{end_row} Last line index {end_row} Last line index, inclusive
{end_col} Ending byte offset of last line (exclusive) {end_col} Ending column (byte offset) on last line,
exclusive
{opts} Optional parameters. Currently unused. {opts} Optional parameters. Currently unused.
Return: ~ Return: ~
@ -2398,7 +2400,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement})
Parameters: ~ Parameters: ~
{buffer} Buffer handle, or 0 for current buffer {buffer} Buffer handle, or 0 for current buffer
{start} First line index {start} First line index
{end} Last line index (exclusive) {end} Last line index, exclusive
{strict_indexing} Whether out-of-bounds should be an {strict_indexing} Whether out-of-bounds should be an
error. error.
{replacement} Array of lines to use as replacement {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}) {replacement})
Sets (replaces) a range in the buffer 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 modifying parts of a line, as extmarks will be preserved on
non-modified parts of the touched lines. 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 insert text at a given `(row, column)` location, use
to the same index. To delete a range, set `replacement` to an `start_row = end_row = row` and `start_col = end_col = col`.
array containing an empty string, or simply an empty array. To delete the text in a range, use `replacement = {}`.
Prefer nvim_buf_set_lines when adding or deleting entire lines Prefer |nvim_buf_set_lines()| if you are only adding or
only. deleting entire lines.
Parameters: ~ Parameters: ~
{buffer} Buffer handle, or 0 for current buffer {buffer} Buffer handle, or 0 for current buffer
{start_row} First line index {start_row} First line index
{start_col} First column {start_col} Starting column (byte offset) on first line
{end_row} Last line index {end_row} Last line index, inclusive
{end_col} Last column {end_col} Ending column (byte offset) on last line,
exclusive
{replacement} Array of lines to use as replacement {replacement} Array of lines to use as replacement
nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()* nvim_buf_set_var({buffer}, {name}, {value}) *nvim_buf_set_var()*

34
src/nvim/api/buffer.c
View File

@ -262,7 +262,7 @@ void nvim__buf_redraw_range(Buffer buffer, Integer first, Integer last, Error *e
/// @param channel_id /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer /// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index /// @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 strict_indexing Whether out-of-bounds should be an error.
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Array of lines, or empty array for unloaded buffer. /// @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 channel_id
/// @param buffer Buffer handle, or 0 for current buffer /// @param buffer Buffer handle, or 0 for current buffer
/// @param start First line index /// @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 strict_indexing Whether out-of-bounds should be an error.
/// @param replacement Array of lines to use as replacement /// @param replacement Array of lines to use as replacement
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
@ -514,24 +514,25 @@ end:
/// Sets (replaces) a range in the buffer /// Sets (replaces) a range in the buffer
/// ///
/// This is recommended over nvim_buf_set_lines when only modifying parts of a /// This is recommended over |nvim_buf_set_lines()| when only modifying parts of
/// line, as extmarks will be preserved on non-modified parts of the touched /// a line, as extmarks will be preserved on non-modified parts of the touched
/// lines. /// 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 /// To insert text at a given `(row, column)` location, use `start_row = end_row
/// index. To delete a range, set `replacement` to an array containing /// = row` and `start_col = end_col = col`. To delete the text in a range, use
/// an empty string, or simply an empty array. /// `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 channel_id
/// @param buffer Buffer handle, or 0 for current buffer /// @param buffer Buffer handle, or 0 for current buffer
/// @param start_row First line index /// @param start_row First line index
/// @param start_col First column /// @param start_col Starting column (byte offset) on first line
/// @param end_row Last line index /// @param end_row Last line index, inclusive
/// @param end_col Last column /// @param end_col Ending column (byte offset) on last line, exclusive
/// @param replacement Array of lines to use as replacement /// @param replacement Array of lines to use as replacement
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
void nvim_buf_set_text(uint64_t channel_id, Buffer buffer, Integer start_row, Integer start_col, 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 /// This differs from |nvim_buf_get_lines()| in that it allows retrieving only
/// portions of a line. /// 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. /// Prefer |nvim_buf_get_lines()| when retrieving entire lines.
/// ///
/// @param channel_id /// @param channel_id
/// @param buffer Buffer handle, or 0 for current buffer /// @param buffer Buffer handle, or 0 for current buffer
/// @param start_row First line index /// @param start_row First line index
/// @param start_col Starting byte offset of first line /// @param start_col Starting column (byte offset) on first line
/// @param end_row Last line index /// @param end_row Last line index, inclusive
/// @param end_col Ending byte offset of last line (exclusive) /// @param end_col Ending column (byte offset) on last line, exclusive
/// @param opts Optional parameters. Currently unused. /// @param opts Optional parameters. Currently unused.
/// @param[out] err Error details, if any /// @param[out] err Error details, if any
/// @return Array of lines, or empty array for unloaded buffer. /// @return Array of lines, or empty array for unloaded buffer.