feat: extend vim.Pos, vim.Range #36397

Problem:
Using nested `vim.Pos` objects to represent each `vim.Range` object
requires 3 tables for each `vim.Range`, which may be undesirable in
performance critical code. Using key-value tables performs worse than
using array-like tables (lists).

Solution:
Use array-like indices for the internal fields of both `vim.Pos` and
`vim.Range` objects. Use a metatable to allow users to access them like
if they were key-value tables.

---

Problem:
The `vim.Pos` conversion interface for `extmark` indexing does not take
into account the difference in how a position on top of a newline is
represented in `vim.Pos` and `extmark`.
- `vim.Pos`: for a newline at the end of row `n`, `row` takes the value
  `n + 1` and `col` takes the value `0`.
- `extmark`: for a newline at the end of for `n`, `row` takes the value
  `n` and `col` takes the value `#row_text`.

Solution:
Handle this in the `extmark` interface.

---

Problem:
Not all `to_xxx` interfaces have wrapping objects like `to_lsp`.

Solution:
Return unwrapped values in `to_xxx` interfaces where it makes sense.
Accept unwrapped values in "from" interfaces where it makes sense.

---

Problem:
`start` and `end` positions have different semantics, so they can't be
compared. `vim.Range` relies on comparing the `end` and `start` of two
ranges to decide which one is greater, which doesn't work as expected
because this of the different semantics.

For example, for the ranges:

    local a = {
      start = { row = 0, col = 22, },
      end_ = { row = 0, col = 24, },
    }
    local b = {
      start = { row = 0, col = 17, },
      end_ = { row = 0, col = 22, },
    }

in this code:

    local foo, bar = "foo",  "bar"
    --               |---||-|
    --                 b  a

The range `b` is smaller than the range `a`, but the current
implementation compares `b._end` (`col = 22`) and `a.start` (`col = 22`)
and concludes that, since `b.col` is not smaller than `a.col`, `b`
should be greater than `a`.

Solution:
- Use a `to_inclusive_pos` to normalize end positions inside of
  `vim.Range` whenever a comparison between a start and an end position
  is necessary.

runtime/lua/vim/lsp/inline_completion.lua

@@ -219,9 +219,12 @@ function Completor:show(hint)
     table.insert(lines[#lines], { hint, 'ComplHintMore' })
   end
 
-  local pos = current.range and current.range.start:to_extmark()
-    or vim.pos.cursor(api.nvim_win_get_cursor(vim.fn.bufwinid(self.bufnr))):to_extmark()
-  local row, col = unpack(pos)
+  local row, col ---@type integer, integer
+  if current.range then
+    row, col = current.range:to_extmark()
+  else
+    row, col = vim.pos.cursor(api.nvim_win_get_cursor(vim.fn.bufwinid(self.bufnr))):to_extmark()
+  end
 
   -- To ensure that virtual text remains visible continuously (without flickering)
   -- while the user is editing the buffer, we allow displaying expired virtual text.
@@ -242,7 +245,7 @@ function Completor:show(hint)
   -- At least, characters before the cursor should be skipped.
   if api.nvim_win_get_buf(winid) == self.bufnr then
     local cursor_row, cursor_col =
-      unpack(vim.pos.cursor(api.nvim_win_get_cursor(winid)):to_extmark())
+      vim.pos.cursor(api.nvim_win_get_cursor(winid), { buf = self.bufnr }):to_extmark()
     if row == cursor_row then
       skip = math.max(skip, cursor_col - col + 1)
     end
@@ -338,23 +341,16 @@ end
 function Completor:accept(item)
   local insert_text = item.insert_text
   if type(insert_text) == 'string' then
-    local range = item.range
-    if range then
+    if item.range then
+      local start_row, start_col, end_row, end_col = item.range:to_extmark()
       local lines = vim.split(insert_text, '\n')
-      api.nvim_buf_set_text(
-        self.bufnr,
-        range.start.row,
-        range.start.col,
-        range.end_.row,
-        range.end_.col,
-        lines
-      )
-      local pos = item.range.start:to_cursor()
+      api.nvim_buf_set_text(self.bufnr, start_row, start_col, end_row, end_col, lines)
       local win = api.nvim_get_current_win()
       win = api.nvim_win_get_buf(win) == self.bufnr and win or vim.fn.bufwinid(self.bufnr)
+      local row, col = item.range:to_cursor()
       api.nvim_win_set_cursor(win, {
-        pos[1] + #lines - 1,
-        (#lines == 1 and pos[2] or 0) + #lines[#lines],
+        row + #lines - 1,
+        (#lines == 1 and col or 0) + #lines[#lines],
       })
     else
       api.nvim_paste(insert_text, false, 0)