From 02f3ebacfbfa1f892347d7532278f24620e68300 Mon Sep 17 00:00:00 2001 From: zeertzjq Date: Wed, 12 Jun 2024 20:45:24 +0200 Subject: runtime(doc): deduplicate getpos(), line(), col(), virtcol() Move the main description to getpos() and link to that from the other functions. closes: #14970 Signed-off-by: zeertzjq Signed-off-by: Christian Brabandt --- runtime/doc/builtin.txt | 113 +++++++++++++++++++++++------------------------- 1 file changed, 55 insertions(+), 58 deletions(-) diff --git a/runtime/doc/builtin.txt b/runtime/doc/builtin.txt index 66f1bae132..8f2d132e29 100644 --- a/runtime/doc/builtin.txt +++ b/runtime/doc/builtin.txt @@ -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 @@ -1727,33 +1727,30 @@ 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: > col(".") column of cursor col("$") length of cursor line plus one col("'t") column of mark t 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. @@ -4490,9 +4487,34 @@ getpid() *getpid()* 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: *E1209* + . 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 @@ -4503,19 +4525,24 @@ getpos({expr}) *getpos()* it is the offset in screen columns from the start of the character. E.g., a position within a 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: > let save_a_mark = getpos("'a") ... call setpos("'a", save_a_mark) + < Also see |getcharpos()|, |getcurpos()| and |setpos()|. Can also be used as a |method|: > @@ -6182,37 +6209,16 @@ libcallnr({libname}, {funcname}, {argument}) 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: *E1209* - . 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: > line(".") line number of the cursor line(".", winid) idem, in window "winid" @@ -11747,7 +11753,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 @@ -11757,18 +11763,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. @@ -11777,6 +11771,7 @@ virtcol({expr} [, {list} [, {winid}]]) *virtcol()* that window instead of the current window. Note that only marks in the current file can be used. + Examples: > " 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': 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: > echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) -- cgit v1.2.3