vim.Range

Represents a range based on [api-indexing] (0-indexed, end-exclusive). Call vim.range() to create a new range by passing start and end positions (|vim.Pos|).

Both positions must have the same optional fields, which may enable additional capabilities (such as format conversions).

Example:

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

-- Create a range from two positions.
local range1 = vim.range(pos1, pos2)
-- Or create a range from four integers representing start and end positions.
local range2 = vim.range(0, 3, 5, 4, 0)

-- Because `vim.Range` is end exclusive, `range1` and `range2` both represent
-- a range starting at the row 3, column 5 and ending at where the row 3 ends
-- (including the newline at the end of line 3).

-- Operators are overloaded for comparing two `vim.Pos` objects.
if range1 == range2 then
  print("range1 and range2 are the same range")
end

Methods9

function Range.is_empty(range: vim.Range) -> boolean

Checks whether the given range is empty; i.e., start >= end.

Parameters

rangevim.Range

Returns

boolean: true if the given range is empty.

function Range.has(outer: vim.Range, inner: vim.Range | vim.Pos) -> boolean

Checks whether {outer} range contains {inner} range or position.

Parameters

outervim.Range
innervim.Range | vim.Pos

Returns

boolean: true if {outer} range fully contains {inner} range or position.

function Range.intersect(r1: vim.Range, r2: vim.Range) -> range vim.Range | nil

Computes the common range shared by the given ranges.

Parameters

r1vim.Range: First range to intersect.
r2vim.Range: Second range to intersect

Returns

rangevim.Range | nil: that is present inside both r1 and r2. nil if such range does not exist.

function Range.to_lsp(range: vim.Range, position_encoding: lsp.PositionEncodingKind) -> lsp.Range

Converts |vim.Range| to lsp.Range.

Example:

local range = vim.range(0, 3, 5, 4, 0)

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

function Range.lsp(buf: integer, range: lsp.Range, position_encoding: lsp.PositionEncodingKind) -> vim.Range

Creates a new |vim.Range| from lsp.Range.

Example:

local lsp_range = {
  ['start'] = { line = 3, character = 5 },
  ['end'] = { line = 4, character = 0 }
}

local range = vim.range.lsp(0, lsp_range, 'utf-16')

function Range.to_mark(range: vim.Range) -> (start_lnum integer, start_col integer, end_lnum integer, end_col integer)

Converts |vim.Range| to extmark range (see |api-indexing|).

Example:

local range = vim.range(0, 3, 5, 4, 0)

-- Convert to mark range, you can call it in a method style.
local start_lnum, start_col, end_lnum, end_col = range:to_mark()

function Range.mark(buf: integer, start_lnum: integer, start_col: integer, end_lnum: integer, end_col: integer) -> vim.Range

Creates a new |vim.Range| from "mark-indexed" range (see |api-indexing|).

Example:

-- A range represented by marks may be end-inclusive (decided by 'selection' option).
local start_lnum, start_col = unpack(api.nvim_buf_get_mark(bufnr, '<'))
local end_lnum, end_col = unpack(api.nvim_buf_get_mark(bufnr, '>'))

-- Create an end-exclusive range.
local range = vim.range.mark(0, start_lnum, start_col, end_lnum, end_col)

function Range.to_extmark(range: vim.Range) -> (start_row integer, start_col integer, end_row integer, end_col integer)

Converts |vim.Range| to extmark range (see |api-indexing|).

Example:

local range = vim.range(0, 3, 5, 4, 0)

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

function Range.extmark(buf: integer, start_row: integer, start_col: integer, end_row: integer, end_col: integer) -> vim.Range

Creates a new |vim.Range| from extmark range (see |api-indexing|).

Example:

local range = vim.range.extmark(0, 3, 5, 4, 0)

Fields5

Range.start_row : integer

0-based byte index.

Range.start_col : integer

0-based byte index.

Range.end_row : integer

0-based byte index.

Range.end_col : integer

0-based byte index.

Range.buf : integer

Optional buffer handle.