Vimscript Built-in Functions: Buffer Windows and Byte Position

buffer number, force it to be a Number by adding zero to it: >vim echo bufname("3" + 0) < If the buffer doesn't exist, or doesn't have a name, an empty string is returned. >vim echo bufname("#") " alternate buffer name echo bufname(3) " name of buffer 3 echo bufname("%") " name of current buffer echo bufname("file2") " name of buffer where "file2" matches. < Parameters: ~ • {buf} (`integer|string?`) Return: ~ (`string`) bufnr([{buf} [, {create}]]) *bufnr()* The result is the number of a buffer, as it is displayed by the `:ls` command. For the use of {buf}, see |bufname()| above. If the buffer doesn't exist, -1 is returned. Or, if the {create} argument is present and TRUE, a new, unlisted, buffer is created and its number is returned. bufnr("$") is the last buffer: >vim let last_buffer = bufnr("$") < The result is a Number, which is the highest buffer number of existing buffers. Note that not all buffers with a smaller number necessarily exist, because ":bwipeout" may have removed them. Use bufexists() to test for the existence of a buffer. Parameters: ~ • {buf} (`integer|string?`) • {create} (`any?`) Return: ~ (`integer`) bufwinid({buf}) *bufwinid()* The result is a Number, which is the |window-ID| of the first window associated with buffer {buf}. For the use of {buf}, see |bufname()| above. If buffer {buf} doesn't exist or there is no such window, -1 is returned. Example: >vim echo "A window containing buffer 1 is " .. (bufwinid(1)) < Only deals with the current tab page. See |win_findbuf()| for finding more. Parameters: ~ • {buf} (`any`) Return: ~ (`integer`) bufwinnr({buf}) *bufwinnr()* Like |bufwinid()| but return the window number instead of the |window-ID|. If buffer {buf} doesn't exist or there is no such window, -1 is returned. Example: >vim echo "A window containing buffer 1 is " .. (bufwinnr(1)) < The number can be used with |CTRL-W_w| and ":wincmd w" |:wincmd|. Parameters: ~ • {buf} (`any`) Return: ~ (`integer`) byte2line({byte}) *byte2line()* Return the line number that contains the character at byte count {byte} in the current buffer. This includes the end-of-line character, depending on the 'fileformat' option for the current buffer. The first character has byte count one. Also see |line2byte()|, |go| and |:goto|. Returns -1 if the {byte} value is invalid. Parameters: ~ • {byte} (`any`) Return: ~ (`integer`) byteidx({expr}, {nr} [, {utf16}]) *byteidx()* Return byte index of the {nr}th character in the String {expr}. Use zero for the first character, it then returns zero. If there are no multibyte characters the returned value is equal to {nr}. Composing characters are not counted separately, their byte length is added to the preceding base character. See |byteidxcomp()| below for counting composing characters separately. When {utf16} is present and TRUE, {nr} is used as the UTF-16 index in the String {expr} instead of as the character index. The UTF-16 index is the index in the string when it is encoded with 16-bit words. If the specified UTF-16 index is in the middle of a character (e.g. in a 4-byte character), then the byte index of the first byte in the character is returned. Refer to |string-offset-encoding| for more information. Example : >vim echo matchstr(str, ".", byteidx(str,

This section describes functions for working with buffers, windows, and byte positions in Vimscript. It covers `bufnr()` for getting the buffer number, `bufwinid()` and `bufwinnr()` for obtaining window IDs and numbers associated with a buffer, `byte2line()` for finding the line number of a byte position, and `byteidx()` for determining the byte index of a character in a string.