thac0/vim
1
0
Fork 0
forked from aniani/vim
Code Activity

runtime(doc): deduplicate getpos(), line(), col(), virtcol()

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

closes: #14970

Signed-off-by: zeertzjq <zeertzjq@outlook.com>
Signed-off-by: Christian Brabandt <cb@256bit.org>
This commit is contained in:
zeertzjq
2024-06-12 20:45:24 +02:00
committed by Christian Brabandt
parent 31441d509a
commit 02f3ebacfb
1 changed files with 55 additions and 58 deletions
Download Patch File Download Diff File Expand all files Collapse all files

113
runtime/doc/builtin.txt
View File

@@ -1,4 +1,4 @@
*builtin.txt* For Vim version 9.1. Last change: 2024 Jun 11 *builtin.txt* For Vim version 9.1. Last change: 2024 Jun 12
VIM REFERENCE MANUAL by Bram Moolenaar VIM REFERENCE MANUAL by Bram Moolenaar
@@ -1727,33 +1727,30 @@ clearmatches([{win}]) *clearmatches()*
col({expr} [, {winid}]) *col()* col({expr} [, {winid}]) *col()*
The result is a Number, which is the byte index of the column The result is a Number, which is the byte index of the column
position given with {expr}. The accepted positions are: position given with {expr}.
. the cursor position For accepted positions see |getpos()|.
$ 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.
Additionally {expr} can be [lnum, col]: a |List| with the line Additionally {expr} can be [lnum, col]: a |List| with the line
and column number. Most useful when the column is "$", to get and column number. Most useful when the column is "$", to get
the last column of a specific line. When "lnum" or "col" is the last column of a specific line. When "lnum" or "col" is
out of range then col() returns zero. out of range then col() returns zero.
With the optional {winid} argument the values are obtained for With the optional {winid} argument the values are obtained for
that window instead of the current window. that window instead of the current window.
To get the line number use |line()|. To get both use To get the line number use |line()|. To get both use
|getpos()|. |getpos()|.
For the screen column position use |virtcol()|. For the For the screen column position use |virtcol()|. For the
character position use |charcol()|. character position use |charcol()|.
Note that only marks in the current file can be used. Note that only marks in the current file can be used.
Examples: > Examples: >
col(".") column of cursor col(".") column of cursor
col("$") length of cursor line plus one col("$") length of cursor line plus one
col("'t") column of mark t col("'t") column of mark t
col("'" .. markname) column of mark markname 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. the window with ID {winid} is not found.
For an uppercase mark the column may actually be in another For an uppercase mark the column may actually be in another
buffer. buffer.
@@ -4490,9 +4487,34 @@ getpid() *getpid()*
getpos({expr}) *getpos()* getpos({expr}) *getpos()*
Get the position for String {expr}. For possible values of Get the position for String {expr}.
{expr} see |line()|. For getting the cursor position see The accepted values for {expr} are: *E1209*
|getcurpos()|. . 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: The result is a |List| with four numbers:
[bufnum, lnum, col, off] [bufnum, lnum, col, off]
"bufnum" is zero, unless a mark like '0 or 'A is used, then it "bufnum" is zero, unless a mark like '0 or 'A is used, then it
@@ -4503,19 +4525,24 @@ getpos({expr}) *getpos()*
it is the offset in screen columns from the start of the 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. E.g., a position within a <Tab> or after the last
character. character.
Note that for '< and '> Visual mode matters: when it is "V"
(visual line mode) the column of '< is zero and the column of For getting the cursor position see |getcurpos()|.
'> is a large number equal to |v:maxcol|.
The column number in the returned List is the byte position The column number in the returned List is the byte position
within the line. To get the character position in the line, within the line. To get the character position in the line,
use |getcharpos()|. 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, A very large column number equal to |v:maxcol| can be returned,
in which case it means "after the end of the line". in which case it means "after the end of the line".
If {expr} is invalid, returns a list with all zeros. If {expr} is invalid, returns a list with all zeros.
This can be used to save and restore the position of a mark: > This can be used to save and restore the position of a mark: >
let save_a_mark = getpos("'a") let save_a_mark = getpos("'a")
... ...
call setpos("'a", save_a_mark) call setpos("'a", save_a_mark)
< Also see |getcharpos()|, |getcurpos()| and |setpos()|. < Also see |getcharpos()|, |getcurpos()| and |setpos()|.
Can also be used as a |method|: > Can also be used as a |method|: >
@@ -6182,37 +6209,16 @@ libcallnr({libname}, {funcname}, {argument})
line({expr} [, {winid}]) *line()* line({expr} [, {winid}]) *line()*
The result is a Number, which is the line number of the file The result is a Number, which is the line number of the file
position given with {expr}. The {expr} argument is a string. position given with {expr}. The {expr} argument is a string.
The accepted positions are: *E1209* See |getpos()| for accepted positions.
. 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.
To get the column number use |col()|. To get both use To get the column number use |col()|. To get both use
|getpos()|. |getpos()|.
With the optional {winid} argument the values are obtained for With the optional {winid} argument the values are obtained for
that window instead of the current window. that window instead of the current window.
Returns 0 for invalid values of {expr} and {winid}. Returns 0 for invalid values of {expr} and {winid}.
Examples: > Examples: >
line(".") line number of the cursor line(".") line number of the cursor
line(".", winid) idem, in window "winid" line(".", winid) idem, in window "winid"
@@ -11747,7 +11753,7 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
set to 8, it returns 8. |conceal| is ignored. set to 8, it returns 8. |conceal| is ignored.
For the byte position use |col()|. 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], When 'virtualedit' is used {expr} can be [lnum, col, off],
where "off" is the offset in screen columns from the start of where "off" is the offset in screen columns from the start of
@@ -11757,18 +11763,6 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
beyond the end of the line can be returned. Also see beyond the end of the line can be returned. Also see
|'virtualedit'| |'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 If {list} is present and non-zero then virtcol() returns a
List with the first and last screen position occupied by the List with the first and last screen position occupied by the
character. character.
@@ -11777,6 +11771,7 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
that window instead of the current window. that window instead of the current window.
Note that only marks in the current file can be used. Note that only marks in the current file can be used.
Examples: > Examples: >
" With text "foo^Lbar" and cursor on the "^L": " With text "foo^Lbar" and cursor on the "^L":
@@ -11787,7 +11782,9 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()*
" With text " there", with 't at 'h': " With text " there", with 't at 'h':
virtcol("'t") " returns 6 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 A more advanced example that echoes the maximum length of
all lines: > all lines: >
echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) echo max(map(range(1, line('$')), "virtcol([v:val, '$'])"))