kevin/neovim
1
Fork 0
mirror of https://github.com/neovim/neovim.git synced 2024-12-23 20:55:18 -07:00
Code Issues Packages Projects Releases Wiki Activity

doc/API: document indexing behavior #10058

Browse Source 
close #10058
This commit is contained in:
KillTheMule 2019-05-24 18:07:16 +02:00 committed by Justin M. Keyes
parent 55419a6904
commit 52215f5752
4 changed files with 33 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
ISSUE_TEMPLATE.md
View File

@ -10,6 +10,8 @@
```
nvim -u NORC
# Alternative for shell-related problems:
# env -i TERM=ansi-256color "$(which nvim)"
```

30
runtime/doc/api.txt
View File

@ -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

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

@ -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.

4
src/nvim/api/window.c
View File

@ -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