diff options
| -rw-r--r-- | ISSUE_TEMPLATE.md | 2 | ||||
| -rw-r--r-- | runtime/doc/api.txt | 30 | ||||
| -rw-r--r-- | src/nvim/api/buffer.c | 10 | ||||
| -rw-r--r-- | src/nvim/api/window.c | 4 |
4 files changed, 33 insertions, 13 deletions
diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index 1a7268a51e..4126f66d6c 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -10,6 +10,8 @@ ``` nvim -u NORC +# Alternative for shell-related problems: +# env -i TERM=ansi-256color "$(which nvim)" ``` diff --git a/runtime/doc/api.txt b/runtime/doc/api.txt index 3d95dd58f7..22ad8e0633 100644 --- a/runtime/doc/api.txt +++ b/runtime/doc/api.txt @@ -14,8 +14,9 @@ Applications can also embed libnvim to work with the C API directly. Type |gO| to see the table of contents. ============================================================================== -API Types *api-types* +API Definitions *api-definitions* + *api-types* The Nvim C API defines custom types for all function parameters. Some are just typedefs around C99 standard types, others are Nvim-defined data structures. @@ -34,6 +35,17 @@ discriminated as separate types in an Object: Window -> enum value kObjectTypeWindow Tabpage -> enum value kObjectTypeTabpage + *api-indexing* +Most of the API uses 0-based indices, and ranges are end-exclusive. For the +end of a range, -1 denotes the last line/column. + +Exception: the following API functions use "mark-like" indexing (1-based +lines, 0-based columns): + + |nvim_buf_get_mark()| + |nvim_win_get_cursor()| + |nvim_win_set_cursor()| + ============================================================================== API metadata *api-metadata* @@ -1293,7 +1305,7 @@ nvim_buf_set_lines({buffer}, {start}, {end}, {strict_indexing}, {replacement} Array of lines to use as replacement nvim_buf_get_offset({buffer}, {index}) *nvim_buf_get_offset()* - Returns the byte offset for a line. + Returns the byte offset of a line (0-indexed). |api-indexing| Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. 'fileformat' and 'fileencoding' are ignored. The @@ -1445,7 +1457,9 @@ nvim_buf_is_valid({buffer}) *nvim_buf_is_valid()* nvim_buf_get_mark({buffer}, {name}) *nvim_buf_get_mark()* Return a tuple (row,col) representing the position of the - named mark + named mark. + + Marks are (1,0)-indexed. |api-indexing| Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1500,8 +1514,8 @@ nvim_buf_clear_namespace({buffer}, {ns_id}, {line_start}, {line_end}) Clears namespaced objects, highlights and virtual text, from a line range - To clear the namespace in the entire buffer, pass in 0 and -1 - to line_start and line_end respectively. + Lines are 0-indexed. |api-indexing| To clear the namespace in + the entire buffer, specify line_start=0 and line_end=-1. Parameters: ~ {buffer} Buffer handle, or 0 for current buffer @@ -1570,7 +1584,8 @@ nvim_win_set_buf({window}, {buffer}) *nvim_win_set_buf()* {buffer} Buffer handle nvim_win_get_cursor({window}) *nvim_win_get_cursor()* - Gets the cursor position in the window + Gets the (1,0)-indexed cursor position in the window. + |api-indexing| Parameters: ~ {window} Window handle @@ -1579,7 +1594,8 @@ nvim_win_get_cursor({window}) *nvim_win_get_cursor()* (row, col) tuple nvim_win_set_cursor({window}, {pos}) *nvim_win_set_cursor()* - Sets the cursor position in the window + Sets the (1,0)-indexed cursor position in the window. + |api-indexing| Parameters: ~ {window} Window handle diff --git a/src/nvim/api/buffer.c b/src/nvim/api/buffer.c index 9a5ffecad4..06d7c1810c 100644 --- a/src/nvim/api/buffer.c +++ b/src/nvim/api/buffer.c @@ -487,7 +487,7 @@ end: try_end(err); } -/// Returns the byte offset for a line. +/// Returns the byte offset of a line (0-indexed). |api-indexing| /// /// Line 1 (index=0) has offset 0. UTF-8 bytes are counted. EOL is one byte. /// 'fileformat' and 'fileencoding' are ignored. The line index just after the @@ -879,7 +879,9 @@ void buffer_insert(Buffer buffer, nvim_buf_set_lines(0, buffer, lnum, lnum, true, lines, err); } -/// Return a tuple (row,col) representing the position of the named mark +/// Return a tuple (row,col) representing the position of the named mark. +/// +/// Marks are (1,0)-indexed. |api-indexing| /// /// @param buffer Buffer handle, or 0 for current buffer /// @param name Mark name @@ -993,8 +995,8 @@ Integer nvim_buf_add_highlight(Buffer buffer, /// Clears namespaced objects, highlights and virtual text, from a line range /// -/// To clear the namespace in the entire buffer, pass in 0 and -1 to -/// line_start and line_end respectively. +/// Lines are 0-indexed. |api-indexing| To clear the namespace in the entire +/// buffer, specify line_start=0 and line_end=-1. /// /// @param buffer Buffer handle, or 0 for current buffer /// @param ns_id Namespace to clear, or -1 to clear all namespaces. diff --git a/src/nvim/api/window.c b/src/nvim/api/window.c index e1c50cb89d..9fd1818a5c 100644 --- a/src/nvim/api/window.c +++ b/src/nvim/api/window.c @@ -74,7 +74,7 @@ void nvim_win_set_buf(Window window, Buffer buffer, Error *err) restore_win(save_curwin, save_curtab, false); } -/// Gets the cursor position in the window +/// Gets the (1,0)-indexed cursor position in the window. |api-indexing| /// /// @param window Window handle /// @param[out] err Error details, if any @@ -93,7 +93,7 @@ ArrayOf(Integer, 2) nvim_win_get_cursor(Window window, Error *err) return rv; } -/// Sets the cursor position in the window +/// Sets the (1,0)-indexed cursor position in the window. |api-indexing| /// /// @param window Window handle /// @param pos (row, col) tuple representing the new position |