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

vim-patch:02f3eba: runtime(doc): deduplicate getpos(), line(), col(), virtcol()

Browse Source 
Move the main description to getpos() and link to that from the other
functions.

closes: vim/vim#14970

02f3ebacfb
This commit is contained in:
zeertzjq 2024-06-13 04:31:59 +08:00
parent f75053a00a
commit fab3d4721f
3 changed files with 162 additions and 177 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
runtime/doc/builtin.txt generated
View File

@ -701,33 +701,31 @@ clearmatches([{win}]) *clearmatches()*
col({expr} [, {winid}]) *col()*
The result is a Number, which is the byte index of the column
position given with {expr}. The accepted positions are:
. the cursor position
$ the end of the cursor line (the result is the
number of bytes in the cursor line plus one)
'x position of mark x (if the mark is not set, 0 is
returned)
v In Visual mode: the start of the Visual area (the
cursor is the end). When not in Visual mode
returns the cursor position. Differs from |'<| in
that it's updated right away.
position given with {expr}.
For accepted positions see |getpos()|.
Additionally {expr} can be [lnum, col]: a |List| with the line
and column number. Most useful when the column is "$", to get
the last column of a specific line. When "lnum" or "col" is
out of range then col() returns zero.
With the optional {winid} argument the values are obtained for
that window instead of the current window.
To get the line number use |line()|. To get both use
|getpos()|.
For the screen column position use |virtcol()|. For the
character position use |charcol()|.
Note that only marks in the current file can be used.
Examples: >vim
echo col(".") " column of cursor
echo col("$") " length of cursor line plus one
echo col("'t") " column of mark t
echo col("'" .. markname) " column of mark markname
< The first column is 1. Returns 0 if {expr} is invalid or when
<
The first column is 1. Returns 0 if {expr} is invalid or when
the window with ID {winid} is not found.
For an uppercase mark the column may actually be in another
buffer.
@ -2739,9 +2737,34 @@ getpid() *getpid()*
This is a unique number, until Vim exits.
getpos({expr}) *getpos()*
Get the position for String {expr}. For possible values of
{expr} see |line()|. For getting the cursor position see
|getcurpos()|.
Get the position for String {expr}.
The accepted values for {expr} are:
. The cursor position.
$ The last line in the current buffer.
'x Position of mark x (if the mark is not set, 0 is
returned).
w0 First line visible in current window (one if the
display isn't updated, e.g. in silent Ex mode).
w$ Last line visible in current window (this is one
less than "w0" if no lines are visible).
v When not in Visual mode, returns the cursor
position. In Visual mode, returns the other end
of the Visual area. A good way to think about
this is that in Visual mode "v" and "." complement
each other. While "." refers to the cursor
position, "v" refers to where |v_o| would move the
cursor. As a result, you can use "v" and "."
together to work on all of a selection in
characterwise Visual mode. If the cursor is at
the end of a characterwise Visual area, "v" refers
to the start of the same Visual area. And if the
cursor is at the start of a characterwise Visual
area, "v" refers to the end of the same Visual
area. "v" differs from |'<| and |'>| in that it's
updated right away.
Note that a mark in another file can be used. The line number
then applies to another buffer.
The result is a |List| with four numbers:
[bufnum, lnum, col, off]
"bufnum" is zero, unless a mark like '0 or 'A is used, then it
@ -2752,19 +2775,24 @@ getpos({expr}) *getpos()*
it is the offset in screen columns from the start of the
character. E.g., a position within a <Tab> or after the last
character.
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
For getting the cursor position see |getcurpos()|.
The column number in the returned List is the byte position
within the line. To get the character position in the line,
use |getcharpos()|.
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
A very large column number equal to |v:maxcol| can be returned,
in which case it means "after the end of the line".
If {expr} is invalid, returns a list with all zeros.
This can be used to save and restore the position of a mark: >vim
let save_a_mark = getpos("'a")
" ...
call setpos("'a", save_a_mark)
< Also see |getcharpos()|, |getcurpos()| and |setpos()|.
getqflist([{what}]) *getqflist()*
@ -4091,39 +4119,16 @@ libcallnr({libname}, {funcname}, {argument}) *libcallnr()*
<
line({expr} [, {winid}]) *line()*
The result is a Number, which is the line number of the file
position given with {expr}. The {expr} argument is a string.
The accepted positions are:
. the cursor position
$ the last line in the current buffer
'x position of mark x (if the mark is not set, 0 is
returned)
w0 first line visible in current window (one if the
display isn't updated, e.g. in silent Ex mode)
w$ last line visible in current window (this is one
less than "w0" if no lines are visible)
v When not in Visual mode, returns the cursor
position. In Visual mode, returns the other end
of the Visual area. A good way to think about
this is that in Visual mode "v" and "." complement
each other. While "." refers to the cursor
position, "v" refers to where |v_o| would move the
cursor. As a result, you can use "v" and "."
together to work on all of a selection in
characterwise visual mode. If the cursor is at
the end of a characterwise visual area, "v" refers
to the start of the same visual area. And if the
cursor is at the start of a characterwise visual
area, "v" refers to the end of the same visual
area. "v" differs from |'<| and |'>| in that it's
updated right away.
Note that a mark in another file can be used. The line number
then applies to another buffer.
See |getpos()| for accepted positions.
To get the column number use |col()|. To get both use
|getpos()|.
With the optional {winid} argument the values are obtained for
that window instead of the current window.
Returns 0 for invalid values of {expr} and {winid}.
Examples: >vim
echo line(".") " line number of the cursor
echo line(".", winid) " idem, in window "winid"
@ -8746,7 +8751,7 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
set to 8, it returns 8. |conceal| is ignored.
For the byte position use |col()|.
For the use of {expr} see |col()|.
For the use of {expr} see |getpos()| and |col()|.
When 'virtualedit' is used {expr} can be [lnum, col, off],
where "off" is the offset in screen columns from the start of
@ -8756,18 +8761,6 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
beyond the end of the line can be returned. Also see
|'virtualedit'|
The accepted positions are:
. the cursor position
$ the end of the cursor line (the result is the
number of displayed characters in the cursor line
plus one)
'x position of mark x (if the mark is not set, 0 is
returned)
v In Visual mode: the start of the Visual area (the
cursor is the end). When not in Visual mode
returns the cursor position. Differs from |'<| in
that it's updated right away.
If {list} is present and non-zero then virtcol() returns a
List with the first and last screen position occupied by the
character.
@ -8786,7 +8779,9 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
" With text " there", with 't at 'h':
echo virtcol("'t") " returns 6
< The first column is 1. 0 or [0, 0] is returned for an error.
<
The first column is 1. 0 or [0, 0] is returned for an error.
A more advanced example that echoes the maximum length of
all lines: >vim
echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))

113
runtime/lua/vim/_meta/vimfn.lua generated
View File

@ -911,33 +911,31 @@ function vim.fn.cindent(lnum) end
function vim.fn.clearmatches(win) end
--- The result is a Number, which is the byte index of the column
--- position given with {expr}. The accepted positions are:
--- . the cursor position
--- $ the end of the cursor line (the result is the
--- number of bytes in the cursor line plus one)
--- 'x position of mark x (if the mark is not set, 0 is
--- returned)
--- v In Visual mode: the start of the Visual area (the
--- cursor is the end). When not in Visual mode
--- returns the cursor position. Differs from |'<| in
--- that it's updated right away.
--- position given with {expr}.
--- For accepted positions see |getpos()|.
--- Additionally {expr} can be [lnum, col]: a |List| with the line
--- and column number. Most useful when the column is "$", to get
--- the last column of a specific line. When "lnum" or "col" is
--- out of range then col() returns zero.
---
--- With the optional {winid} argument the values are obtained for
--- that window instead of the current window.
---
--- To get the line number use |line()|. To get both use
--- |getpos()|.
---
--- For the screen column position use |virtcol()|. For the
--- character position use |charcol()|.
---
--- Note that only marks in the current file can be used.
---
--- Examples: >vim
--- echo col(".") " column of cursor
--- echo col("$") " length of cursor line plus one
--- echo col("'t") " column of mark t
--- echo col("'" .. markname) " column of mark markname
--- <The first column is 1. Returns 0 if {expr} is invalid or when
--- <
--- The first column is 1. Returns 0 if {expr} is invalid or when
--- the window with ID {winid} is not found.
--- For an uppercase mark the column may actually be in another
--- buffer.
@ -3329,9 +3327,34 @@ function vim.fn.getmousepos() end
--- @return integer
function vim.fn.getpid() end
--- Get the position for String {expr}. For possible values of
--- {expr} see |line()|. For getting the cursor position see
--- |getcurpos()|.
--- Get the position for String {expr}.
--- The accepted values for {expr} are:
--- . The cursor position.
--- $ The last line in the current buffer.
--- 'x Position of mark x (if the mark is not set, 0 is
--- returned).
--- w0 First line visible in current window (one if the
--- display isn't updated, e.g. in silent Ex mode).
--- w$ Last line visible in current window (this is one
--- less than "w0" if no lines are visible).
--- v When not in Visual mode, returns the cursor
--- position. In Visual mode, returns the other end
--- of the Visual area. A good way to think about
--- this is that in Visual mode "v" and "." complement
--- each other. While "." refers to the cursor
--- position, "v" refers to where |v_o| would move the
--- cursor. As a result, you can use "v" and "."
--- together to work on all of a selection in
--- characterwise Visual mode. If the cursor is at
--- the end of a characterwise Visual area, "v" refers
--- to the start of the same Visual area. And if the
--- cursor is at the start of a characterwise Visual
--- area, "v" refers to the end of the same Visual
--- area. "v" differs from |'<| and |'>| in that it's
--- updated right away.
--- Note that a mark in another file can be used. The line number
--- then applies to another buffer.
---
--- The result is a |List| with four numbers:
--- [bufnum, lnum, col, off]
--- "bufnum" is zero, unless a mark like '0 or 'A is used, then it
@ -3342,19 +3365,24 @@ function vim.fn.getpid() end
--- it is the offset in screen columns from the start of the
--- character. E.g., a position within a <Tab> or after the last
--- character.
--- Note that for '< and '> Visual mode matters: when it is "V"
--- (visual line mode) the column of '< is zero and the column of
--- '> is a large number equal to |v:maxcol|.
---
--- For getting the cursor position see |getcurpos()|.
--- The column number in the returned List is the byte position
--- within the line. To get the character position in the line,
--- use |getcharpos()|.
---
--- Note that for '< and '> Visual mode matters: when it is "V"
--- (visual line mode) the column of '< is zero and the column of
--- '> is a large number equal to |v:maxcol|.
--- A very large column number equal to |v:maxcol| can be returned,
--- in which case it means "after the end of the line".
--- If {expr} is invalid, returns a list with all zeros.
---
--- This can be used to save and restore the position of a mark: >vim
--- let save_a_mark = getpos("'a")
--- " ...
--- call setpos("'a", save_a_mark)
---
--- <Also see |getcharpos()|, |getcurpos()| and |setpos()|.
---
--- @param expr string
@ -4960,39 +4988,16 @@ function vim.fn.libcall(libname, funcname, argument) end
--- @return any
function vim.fn.libcallnr(libname, funcname, argument) end
--- The result is a Number, which is the line number of the file
--- position given with {expr}. The {expr} argument is a string.
--- The accepted positions are:
--- . the cursor position
--- $ the last line in the current buffer
--- 'x position of mark x (if the mark is not set, 0 is
--- returned)
--- w0 first line visible in current window (one if the
--- display isn't updated, e.g. in silent Ex mode)
--- w$ last line visible in current window (this is one
--- less than "w0" if no lines are visible)
--- v When not in Visual mode, returns the cursor
--- position. In Visual mode, returns the other end
--- of the Visual area. A good way to think about
--- this is that in Visual mode "v" and "." complement
--- each other. While "." refers to the cursor
--- position, "v" refers to where |v_o| would move the
--- cursor. As a result, you can use "v" and "."
--- together to work on all of a selection in
--- characterwise visual mode. If the cursor is at
--- the end of a characterwise visual area, "v" refers
--- to the start of the same visual area. And if the
--- cursor is at the start of a characterwise visual
--- area, "v" refers to the end of the same visual
--- area. "v" differs from |'<| and |'>| in that it's
--- updated right away.
--- Note that a mark in another file can be used. The line number
--- then applies to another buffer.
--- See |getpos()| for accepted positions.
---
--- To get the column number use |col()|. To get both use
--- |getpos()|.
---
--- With the optional {winid} argument the values are obtained for
--- that window instead of the current window.
---
--- Returns 0 for invalid values of {expr} and {winid}.
---
--- Examples: >vim
--- echo line(".") " line number of the cursor
--- echo line(".", winid) " idem, in window "winid"
@ -10410,7 +10415,7 @@ function vim.fn.values(dict) end
--- set to 8, it returns 8. |conceal| is ignored.
--- For the byte position use |col()|.
---
--- For the use of {expr} see |col()|.
--- For the use of {expr} see |getpos()| and |col()|.
---
--- When 'virtualedit' is used {expr} can be [lnum, col, off],
--- where "off" is the offset in screen columns from the start of
@ -10420,18 +10425,6 @@ function vim.fn.values(dict) end
--- beyond the end of the line can be returned. Also see
--- |'virtualedit'|
---
--- The accepted positions are:
--- . the cursor position
--- $ the end of the cursor line (the result is the
--- number of displayed characters in the cursor line
--- plus one)
--- 'x position of mark x (if the mark is not set, 0 is
--- returned)
--- v In Visual mode: the start of the Visual area (the
--- cursor is the end). When not in Visual mode
--- returns the cursor position. Differs from |'<| in
--- that it's updated right away.
---
--- If {list} is present and non-zero then virtcol() returns a
--- List with the first and last screen position occupied by the
--- character.
@ -10450,7 +10443,9 @@ function vim.fn.values(dict) end
--- " With text " there", with 't at 'h':
---
--- echo virtcol("'t") " returns 6
--- <The first column is 1. 0 or [0, 0] is returned for an error.
--- <
--- The first column is 1. 0 or [0, 0] is returned for an error.
---
--- A more advanced example that echoes the maximum length of
--- all lines: >vim
--- echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))

113
src/nvim/eval.lua
View File

@ -1238,33 +1238,31 @@ M.funcs = {
base = 1,
desc = [=[
The result is a Number, which is the byte index of the column
position given with {expr}. The accepted positions are:
. the cursor position
$ the end of the cursor line (the result is the
number of bytes in the cursor line plus one)
'x position of mark x (if the mark is not set, 0 is
returned)
v In Visual mode: the start of the Visual area (the
cursor is the end). When not in Visual mode
returns the cursor position. Differs from |'<| in
that it's updated right away.
position given with {expr}.
For accepted positions see |getpos()|.
Additionally {expr} can be [lnum, col]: a |List| with the line
and column number. Most useful when the column is "$", to get
the last column of a specific line. When "lnum" or "col" is
out of range then col() returns zero.
With the optional {winid} argument the values are obtained for
that window instead of the current window.
To get the line number use |line()|. To get both use
|getpos()|.
For the screen column position use |virtcol()|. For the
character position use |charcol()|.
Note that only marks in the current file can be used.
Examples: >vim
echo col(".") " column of cursor
echo col("$") " length of cursor line plus one
echo col("'t") " column of mark t
echo col("'" .. markname) " column of mark markname
<The first column is 1. Returns 0 if {expr} is invalid or when
<
The first column is 1. Returns 0 if {expr} is invalid or when
the window with ID {winid} is not found.
For an uppercase mark the column may actually be in another
buffer.
@ -4141,9 +4139,34 @@ M.funcs = {
args = 1,
base = 1,
desc = [=[
Get the position for String {expr}. For possible values of
{expr} see |line()|. For getting the cursor position see
|getcurpos()|.
Get the position for String {expr}.
The accepted values for {expr} are:
. The cursor position.
$ The last line in the current buffer.
'x Position of mark x (if the mark is not set, 0 is
returned).
w0 First line visible in current window (one if the
display isn't updated, e.g. in silent Ex mode).
w$ Last line visible in current window (this is one
less than "w0" if no lines are visible).
v When not in Visual mode, returns the cursor
position. In Visual mode, returns the other end
of the Visual area. A good way to think about
this is that in Visual mode "v" and "." complement
each other. While "." refers to the cursor
position, "v" refers to where |v_o| would move the
cursor. As a result, you can use "v" and "."
together to work on all of a selection in
characterwise Visual mode. If the cursor is at
the end of a characterwise Visual area, "v" refers
to the start of the same Visual area. And if the
cursor is at the start of a characterwise Visual
area, "v" refers to the end of the same Visual
area. "v" differs from |'<| and |'>| in that it's
updated right away.
Note that a mark in another file can be used. The line number
then applies to another buffer.
The result is a |List| with four numbers:
[bufnum, lnum, col, off]
"bufnum" is zero, unless a mark like '0 or 'A is used, then it
@ -4154,19 +4177,24 @@ M.funcs = {
it is the offset in screen columns from the start of the
character. E.g., a position within a <Tab> or after the last
character.
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
For getting the cursor position see |getcurpos()|.
The column number in the returned List is the byte position
within the line. To get the character position in the line,
use |getcharpos()|.
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of
'> is a large number equal to |v:maxcol|.
A very large column number equal to |v:maxcol| can be returned,
in which case it means "after the end of the line".
If {expr} is invalid, returns a list with all zeros.
This can be used to save and restore the position of a mark: >vim
let save_a_mark = getpos("'a")
" ...
call setpos("'a", save_a_mark)
<Also see |getcharpos()|, |getcurpos()| and |setpos()|.
]=],
@ -6070,39 +6098,16 @@ M.funcs = {
args = { 1, 2 },
base = 1,
desc = [=[
The result is a Number, which is the line number of the file
position given with {expr}. The {expr} argument is a string.
The accepted positions are:
. the cursor position
$ the last line in the current buffer
'x position of mark x (if the mark is not set, 0 is
returned)
w0 first line visible in current window (one if the
display isn't updated, e.g. in silent Ex mode)
w$ last line visible in current window (this is one
less than "w0" if no lines are visible)
v When not in Visual mode, returns the cursor
position. In Visual mode, returns the other end
of the Visual area. A good way to think about
this is that in Visual mode "v" and "." complement
each other. While "." refers to the cursor
position, "v" refers to where |v_o| would move the
cursor. As a result, you can use "v" and "."
together to work on all of a selection in
characterwise visual mode. If the cursor is at
the end of a characterwise visual area, "v" refers
to the start of the same visual area. And if the
cursor is at the start of a characterwise visual
area, "v" refers to the end of the same visual
area. "v" differs from |'<| and |'>| in that it's
updated right away.
Note that a mark in another file can be used. The line number
then applies to another buffer.
See |getpos()| for accepted positions.
To get the column number use |col()|. To get both use
|getpos()|.
With the optional {winid} argument the values are obtained for
that window instead of the current window.
Returns 0 for invalid values of {expr} and {winid}.
Examples: >vim
echo line(".") " line number of the cursor
echo line(".", winid) " idem, in window "winid"
@ -12459,7 +12464,7 @@ M.funcs = {
set to 8, it returns 8. |conceal| is ignored.
For the byte position use |col()|.
For the use of {expr} see |col()|.
For the use of {expr} see |getpos()| and |col()|.
When 'virtualedit' is used {expr} can be [lnum, col, off],
where "off" is the offset in screen columns from the start of
@ -12469,18 +12474,6 @@ M.funcs = {
beyond the end of the line can be returned. Also see
|'virtualedit'|
The accepted positions are:
. the cursor position
$ the end of the cursor line (the result is the
number of displayed characters in the cursor line
plus one)
'x position of mark x (if the mark is not set, 0 is
returned)
v In Visual mode: the start of the Visual area (the
cursor is the end). When not in Visual mode
returns the cursor position. Differs from |'<| in
that it's updated right away.
If {list} is present and non-zero then virtcol() returns a
List with the first and last screen position occupied by the
character.
@ -12499,7 +12492,9 @@ M.funcs = {
" With text " there", with 't at 'h':
echo virtcol("'t") " returns 6
<The first column is 1. 0 or [0, 0] is returned for an error.
<
The first column is 1. 0 or [0, 0] is returned for an error.
A more advanced example that echoes the maximum length of
all lines: >vim
echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))