vim.Pos

Represents a buffer position based on [api-indexing] (0-indexed, end-exclusive ranges). Call vim.pos() to create a new vim.Pos by passing the {buf}, {row}, and {col} of a position.

Example:

local pos1 = vim.pos(0, 3, 5)
local pos2 = vim.pos(0, 4, 0)

-- Operators are overloaded for comparing two `vim.Pos` objects.
if pos1 < pos2 then
  print("pos1 comes before pos2")
end

if pos1 ~= pos2 then
  print("pos1 and pos2 are different positions")
end

It may include optional fields that enable additional capabilities, such as format conversions.

Methods10

function Pos.to_lsp(pos: vim.Pos, position_encoding: lsp.PositionEncodingKind) -> lsp.Position

Converts |vim.Pos| to lsp.Position.

Example:

local pos = vim.pos(0, 3, 5)

-- Convert to LSP position, you can call it in a method style.
local lsp_pos = pos:to_lsp('utf-16')

function Pos.lsp(buf: integer, pos: lsp.Position, position_encoding: lsp.PositionEncodingKind) -> vim.Pos

Creates a new |vim.Pos| from lsp.Position.

Example:

local lsp_pos = {
  line = 3,
  character = 5
}

local pos = vim.pos.lsp(0, lsp_pos, 'utf-16')

function Pos.to_cursor(pos: vim.Pos) -> (integer, integer)

Converts |vim.Pos| to cursor position (see |api-indexing|).

Example:

local pos = vim.pos(0, 3, 5)

-- Convert to cursor position, you can call it in a method style.
local cursor_pos = pos:to_cursor()
vim.api.nvim_win_set_cursor(0, cursor_pos)

Parameters

posvim.Pos

Returns

(integer, integer): (lnum, col) tuple

function Pos.cursor(buf: integer, pos: (integer, integer)) -> vim.Pos

Creates a new |vim.Pos| from cursor position (see |api-indexing|).

If {pos} is omitted, the first argument is treated as {win} instead of {buf}, and the current cursor position of {win} is used. If {win} is also omitted, it defaults to the current window.

Example:

local buf = vim.api.nvim_win_get_buf(0)
local cursor_pos = vim.api.nvim_win_get_cursor(0)
local pos = vim.pos.cursor(buf, cursor_pos)
-- This is equivalent:
local pos = vim.pos.cursor(0)

Overloads

function Pos.cursor(win: nil | integer) -> vim.Pos

Parameters

bufinteger
pos(integer, integer): (lnum, col) tuple

Returns

vim.Pos

function Pos.to_mark(pos: vim.Pos) -> (lnum integer, col integer)

Converts |vim.Pos| to mark position (see |api-indexing|).

Example:

local pos = vim.pos(0, 3, 5)

-- Convert to mark position, you can call it in a method style.
local lnum, col = pos:to_mark()
vim.api.nvim_buf_set_mark(0, 'M', lnum, col)

function Pos.mark(buf: integer, lnum: integer, col: integer) -> vim.Pos

Creates a new |vim.Pos| from mark position (see |api-indexing|).

Example:

local mark_info = vim.api.nvim_get_mark('M')
local lnum, col, buf, name = unpack(mark_info)

if lnum == 0 and col == 0 and buf == 0 then
  return -- mark 'M' is not set.
end

local pos = vim.pos.mark(buf, lnum, col)

function Pos.to_extmark(pos: vim.Pos) -> (row integer, col integer)

Converts |vim.Pos| to extmark position (see |api-indexing|).

Example:

local pos = vim.pos(0, 3, 5)

-- Convert to extmark position, you can call it in a method style.
local extmark_pos = pos:to_extmark()

function Pos.extmark(buf: integer, row: integer, col: integer) -> vim.Pos

Creates a new |vim.Pos| from extmark position (see |api-indexing|).

Example:

local pos = vim.pos.extmark(0, 3, 5)

function Pos.to_offset(pos: vim.Pos) -> integer

Converts |vim.Pos| to buffer (bytes) offset.

Example:

local p1 = vim.pos(0, 3, 5)
local p2 = vim.pos(0, 4, 0)

-- Convert to buffer offset, you can call it in a method style.
local offset1 = p1:to_offset()
local offset2 = p2:to_offset()
-- Can be used to calculate the distance between two locations.
local distance = offset2 - offset1

function Pos.offset(buf: integer, offset: integer) -> vim.Pos

Creates a new |vim.Pos| from buffer (bytes) offset.

Example:

local offset = vim.api.nvim_buf_get_offset(0, vim.api.nvim_buf_line_count(0))
local pos = vim.pos.offset(0, offset)

Fields3

Pos.row : integer

0-based byte index.

Pos.col : integer

0-based byte index.

Pos.buf : integer

buffer handle.