mirror of https://github.com/neovim/neovim.git
refactor(vim.iter)!: rename xxback() => rxx() #28503
Problem:
vim.iter has both `rfind()` and various `*back()` methods, which work
in "reverse" or "backwards" order. It's inconsistent to have both kinds
of names, and "back" is fairly uncommon (rust) compared to python
(rfind, rstrip, rsplit, …).
Solution:
- Remove `nthback()` and let `nth()` take a negative index.
- Because `rnth()` looks pretty obscure, and because it's intuitive
for a function named `nth()` to take negative indexes.
- Rename `xxback()` methods to `rxx()`.
- This informally groups the "list-iterator" functions under a common
`r` prefix, which helps discoverability.
- Rename `peekback()` to `pop()`, in duality with the existing `peek`.
This commit is contained in:
Justin M. Keyes
GitHub
parent
b2c26a875b
commit
9b028bd64f
|
|
@ -4053,6 +4053,9 @@ Iter:last() *Iter:last()*
|
|||
Return: ~
|
||||
(`any`)
|
||||
|
||||
See also: ~
|
||||
• Iter.rpeek
|
||||
|
||||
Iter:map({f}) *Iter:map()*
|
||||
Maps the items of an iterator pipeline to the values returned by `f`.
|
||||
|
||||
|
|
@ -4094,53 +4097,28 @@ Iter:next() *Iter:next()*
|
|||
Return: ~
|
||||
(`any`)
|
||||
|
||||
Iter:nextback() *Iter:nextback()*
|
||||
"Pops" a value from a |list-iterator| (gets the last value and decrements
|
||||
the tail).
|
||||
|
||||
Example: >lua
|
||||
local it = vim.iter({1, 2, 3, 4})
|
||||
it:nextback()
|
||||
-- 4
|
||||
it:nextback()
|
||||
-- 3
|
||||
<
|
||||
|
||||
Return: ~
|
||||
(`any`)
|
||||
|
||||
Iter:nth({n}) *Iter:nth()*
|
||||
Gets the nth value of an iterator (and advances to it).
|
||||
|
||||
Example: >lua
|
||||
If `n` is negative, offsets from the end of a |list-iterator|.
|
||||
|
||||
Example: >lua
|
||||
local it = vim.iter({ 3, 6, 9, 12 })
|
||||
it:nth(2)
|
||||
-- 6
|
||||
it:nth(2)
|
||||
-- 12
|
||||
<
|
||||
|
||||
Parameters: ~
|
||||
• {n} (`number`) The index of the value to return.
|
||||
|
||||
Return: ~
|
||||
(`any`)
|
||||
|
||||
Iter:nthback({n}) *Iter:nthback()*
|
||||
Gets the nth value from the end of a |list-iterator| (and advances to it).
|
||||
|
||||
Example: >lua
|
||||
|
||||
local it = vim.iter({ 3, 6, 9, 12 })
|
||||
it:nthback(2)
|
||||
local it2 = vim.iter({ 3, 6, 9, 12 })
|
||||
it2:nth(-2)
|
||||
-- 9
|
||||
it:nthback(2)
|
||||
it2:nth(-2)
|
||||
-- 3
|
||||
<
|
||||
|
||||
Parameters: ~
|
||||
• {n} (`number`) The index of the value to return.
|
||||
• {n} (`number`) Index of the value to return. May be negative if the
|
||||
source is a |list-iterator|.
|
||||
|
||||
Return: ~
|
||||
(`any`)
|
||||
|
|
@ -4162,19 +4140,16 @@ Iter:peek() *Iter:peek()*
|
|||
Return: ~
|
||||
(`any`)
|
||||
|
||||
Iter:peekback() *Iter:peekback()*
|
||||
Gets the last value of a |list-iterator| without consuming it.
|
||||
|
||||
See also |Iter:last()|.
|
||||
Iter:pop() *Iter:pop()*
|
||||
"Pops" a value from a |list-iterator| (gets the last value and decrements
|
||||
the tail).
|
||||
|
||||
Example: >lua
|
||||
local it = vim.iter({1, 2, 3, 4})
|
||||
it:peekback()
|
||||
-- 4
|
||||
it:peekback()
|
||||
-- 4
|
||||
it:nextback()
|
||||
it:pop()
|
||||
-- 4
|
||||
it:pop()
|
||||
-- 3
|
||||
<
|
||||
|
||||
Return: ~
|
||||
|
|
@ -4194,8 +4169,8 @@ Iter:rev() *Iter:rev()*
|
|||
(`Iter`)
|
||||
|
||||
Iter:rfind({f}) *Iter:rfind()*
|
||||
Gets the first value in a |list-iterator| that satisfies a predicate,
|
||||
starting from the end.
|
||||
Gets the first value satisfying a predicate, from the end of a
|
||||
|list-iterator|.
|
||||
|
||||
Advances the iterator. Returns nil and drains the iterator if no value is
|
||||
found.
|
||||
|
|
@ -4218,6 +4193,42 @@ Iter:rfind({f}) *Iter:rfind()*
|
|||
See also: ~
|
||||
• Iter.find
|
||||
|
||||
Iter:rpeek() *Iter:rpeek()*
|
||||
Gets the last value of a |list-iterator| without consuming it.
|
||||
|
||||
Example: >lua
|
||||
local it = vim.iter({1, 2, 3, 4})
|
||||
it:rpeek()
|
||||
-- 4
|
||||
it:rpeek()
|
||||
-- 4
|
||||
it:pop()
|
||||
-- 4
|
||||
<
|
||||
|
||||
Return: ~
|
||||
(`any`)
|
||||
|
||||
See also: ~
|
||||
• Iter.last
|
||||
|
||||
Iter:rskip({n}) *Iter:rskip()*
|
||||
Discards `n` values from the end of a |list-iterator| pipeline.
|
||||
|
||||
Example: >lua
|
||||
local it = vim.iter({ 1, 2, 3, 4, 5 }):rskip(2)
|
||||
it:next()
|
||||
-- 1
|
||||
it:pop()
|
||||
-- 3
|
||||
<
|
||||
|
||||
Parameters: ~
|
||||
• {n} (`number`) Number of values to skip.
|
||||
|
||||
Return: ~
|
||||
(`Iter`)
|
||||
|
||||
Iter:skip({n}) *Iter:skip()*
|
||||
Skips `n` values of an iterator pipeline.
|
||||
|
||||
|
|
@ -4234,27 +4245,10 @@ Iter:skip({n}) *Iter:skip()*
|
|||
Return: ~
|
||||
(`Iter`)
|
||||
|
||||
Iter:skipback({n}) *Iter:skipback()*
|
||||
Skips `n` values backwards from the end of a |list-iterator| pipeline.
|
||||
|
||||
Example: >lua
|
||||
local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2)
|
||||
it:next()
|
||||
-- 1
|
||||
it:nextback()
|
||||
-- 3
|
||||
<
|
||||
|
||||
Parameters: ~
|
||||
• {n} (`number`) Number of values to skip.
|
||||
|
||||
Return: ~
|
||||
(`Iter`)
|
||||
|
||||
Iter:slice({first}, {last}) *Iter:slice()*
|
||||
Sets the start and end of a |list-iterator| pipeline.
|
||||
|
||||
Equivalent to `:skip(first - 1):skipback(len - last + 1)`.
|
||||
Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
|
||||
|
||||
Parameters: ~
|
||||
• {first} (`number`)
|
||||
|
|
|
|||
|
|
@ -159,6 +159,14 @@ unreleased features on Nvim HEAD.
|
|||
|
||||
• Changed |vim.ui.open()| return-signature to match pcall() convention.
|
||||
|
||||
• Renamed Iter:nextback() to Iter:pop()
|
||||
|
||||
• Renamed Iter:peekback() to Iter:rpeek()
|
||||
|
||||
• Renamed Iter:skipback() to Iter:rskip()
|
||||
|
||||
• Removed Iter:nthback(), use Iter:nth() with negative index instead.
|
||||
|
||||
==============================================================================
|
||||
NEW FEATURES *news-features*
|
||||
|
||||
|
|
|
|||
|
|
@ -630,7 +630,7 @@ function Iter:find(f)
|
|||
return unpack(result)
|
||||
end
|
||||
|
||||
--- Gets the first value in a |list-iterator| that satisfies a predicate, starting from the end.
|
||||
--- Gets the first value satisfying a predicate, from the end of a |list-iterator|.
|
||||
---
|
||||
--- Advances the iterator. Returns nil and drains the iterator if no value is found.
|
||||
---
|
||||
|
|
@ -717,19 +717,19 @@ end
|
|||
---
|
||||
--- ```lua
|
||||
--- local it = vim.iter({1, 2, 3, 4})
|
||||
--- it:nextback()
|
||||
--- it:pop()
|
||||
--- -- 4
|
||||
--- it:nextback()
|
||||
--- it:pop()
|
||||
--- -- 3
|
||||
--- ```
|
||||
---
|
||||
---@return any
|
||||
function Iter:nextback()
|
||||
error('nextback() requires a list-like table')
|
||||
function Iter:pop()
|
||||
error('pop() requires a list-like table')
|
||||
end
|
||||
|
||||
--- @nodoc
|
||||
function ListIter:nextback()
|
||||
function ListIter:pop()
|
||||
if self._head ~= self._tail then
|
||||
local inc = self._head < self._tail and 1 or -1
|
||||
self._tail = self._tail - inc
|
||||
|
|
@ -739,27 +739,27 @@ end
|
|||
|
||||
--- Gets the last value of a |list-iterator| without consuming it.
|
||||
---
|
||||
--- See also |Iter:last()|.
|
||||
---
|
||||
--- Example:
|
||||
---
|
||||
--- ```lua
|
||||
--- local it = vim.iter({1, 2, 3, 4})
|
||||
--- it:peekback()
|
||||
--- it:rpeek()
|
||||
--- -- 4
|
||||
--- it:peekback()
|
||||
--- it:rpeek()
|
||||
--- -- 4
|
||||
--- it:nextback()
|
||||
--- it:pop()
|
||||
--- -- 4
|
||||
--- ```
|
||||
---
|
||||
---@see Iter.last
|
||||
---
|
||||
---@return any
|
||||
function Iter:peekback()
|
||||
error('peekback() requires a list-like table')
|
||||
function Iter:rpeek()
|
||||
error('rpeek() requires a list-like table')
|
||||
end
|
||||
|
||||
---@nodoc
|
||||
function ListIter:peekback()
|
||||
function ListIter:rpeek()
|
||||
if self._head ~= self._tail then
|
||||
local inc = self._head < self._tail and 1 or -1
|
||||
return self._table[self._tail - inc]
|
||||
|
|
@ -797,27 +797,27 @@ function ListIter:skip(n)
|
|||
return self
|
||||
end
|
||||
|
||||
--- Skips `n` values backwards from the end of a |list-iterator| pipeline.
|
||||
--- Discards `n` values from the end of a |list-iterator| pipeline.
|
||||
---
|
||||
--- Example:
|
||||
---
|
||||
--- ```lua
|
||||
--- local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2)
|
||||
--- local it = vim.iter({ 1, 2, 3, 4, 5 }):rskip(2)
|
||||
--- it:next()
|
||||
--- -- 1
|
||||
--- it:nextback()
|
||||
--- it:pop()
|
||||
--- -- 3
|
||||
--- ```
|
||||
---
|
||||
---@param n number Number of values to skip.
|
||||
---@return Iter
|
||||
---@diagnostic disable-next-line: unused-local
|
||||
function Iter:skipback(n) -- luacheck: no unused args
|
||||
error('skipback() requires a list-like table')
|
||||
function Iter:rskip(n) -- luacheck: no unused args
|
||||
error('rskip() requires a list-like table')
|
||||
end
|
||||
|
||||
---@private
|
||||
function ListIter:skipback(n)
|
||||
function ListIter:rskip(n)
|
||||
local inc = self._head < self._tail and n or -n
|
||||
self._tail = self._tail - inc
|
||||
if (inc > 0 and self._head > self._tail) or (inc < 0 and self._head < self._tail) then
|
||||
|
|
@ -828,51 +828,37 @@ end
|
|||
|
||||
--- Gets the nth value of an iterator (and advances to it).
|
||||
---
|
||||
--- If `n` is negative, offsets from the end of a |list-iterator|.
|
||||
---
|
||||
--- Example:
|
||||
---
|
||||
--- ```lua
|
||||
---
|
||||
--- local it = vim.iter({ 3, 6, 9, 12 })
|
||||
--- it:nth(2)
|
||||
--- -- 6
|
||||
--- it:nth(2)
|
||||
--- -- 12
|
||||
---
|
||||
--- local it2 = vim.iter({ 3, 6, 9, 12 })
|
||||
--- it2:nth(-2)
|
||||
--- -- 9
|
||||
--- it2:nth(-2)
|
||||
--- -- 3
|
||||
--- ```
|
||||
---
|
||||
---@param n number The index of the value to return.
|
||||
---@param n number Index of the value to return. May be negative if the source is a |list-iterator|.
|
||||
---@return any
|
||||
function Iter:nth(n)
|
||||
if n > 0 then
|
||||
return self:skip(n - 1):next()
|
||||
end
|
||||
end
|
||||
|
||||
--- Gets the nth value from the end of a |list-iterator| (and advances to it).
|
||||
---
|
||||
--- Example:
|
||||
---
|
||||
--- ```lua
|
||||
---
|
||||
--- local it = vim.iter({ 3, 6, 9, 12 })
|
||||
--- it:nthback(2)
|
||||
--- -- 9
|
||||
--- it:nthback(2)
|
||||
--- -- 3
|
||||
---
|
||||
--- ```
|
||||
---
|
||||
---@param n number The index of the value to return.
|
||||
---@return any
|
||||
function Iter:nthback(n)
|
||||
if n > 0 then
|
||||
return self:skipback(n - 1):nextback()
|
||||
elseif n < 0 then
|
||||
return self:rskip(math.abs(n) - 1):pop()
|
||||
end
|
||||
end
|
||||
|
||||
--- Sets the start and end of a |list-iterator| pipeline.
|
||||
---
|
||||
--- Equivalent to `:skip(first - 1):skipback(len - last + 1)`.
|
||||
--- Equivalent to `:skip(first - 1):rskip(len - last + 1)`.
|
||||
---
|
||||
---@param first number
|
||||
---@param last number
|
||||
|
|
@ -884,7 +870,7 @@ end
|
|||
|
||||
---@private
|
||||
function ListIter:slice(first, last)
|
||||
return self:skip(math.max(0, first - 1)):skipback(math.max(0, self._tail - last - 1))
|
||||
return self:skip(math.max(0, first - 1)):rskip(math.max(0, self._tail - last - 1))
|
||||
end
|
||||
|
||||
--- Returns true if any of the items in the iterator match the given predicate.
|
||||
|
|
@ -950,6 +936,8 @@ end
|
|||
---
|
||||
--- ```
|
||||
---
|
||||
---@see Iter.rpeek
|
||||
---
|
||||
---@return any
|
||||
function Iter:last()
|
||||
local last = self:next()
|
||||
|
|
@ -1016,6 +1004,26 @@ function ListIter:enumerate()
|
|||
return self
|
||||
end
|
||||
|
||||
---@deprecated
|
||||
function Iter:nextback()
|
||||
error('Iter:nextback() was renamed to Iter:pop()')
|
||||
end
|
||||
|
||||
---@deprecated
|
||||
function Iter:peekback()
|
||||
error('Iter:peekback() was renamed to Iter:rpeek()')
|
||||
end
|
||||
|
||||
---@deprecated
|
||||
function Iter:skipback()
|
||||
error('Iter:skipback() was renamed to Iter:rskip()')
|
||||
end
|
||||
|
||||
---@deprecated
|
||||
function Iter:nthback()
|
||||
error('Iter:nthback() was removed, use Iter:nth() with negative index')
|
||||
end
|
||||
|
||||
--- Creates a new Iter object from a table or other |iterable|.
|
||||
---
|
||||
---@param src table|function Table or iterator to drain values from
|
||||
|
|
|
|||
|
|
@ -169,19 +169,19 @@ describe('vim.iter', function()
|
|||
end
|
||||
end)
|
||||
|
||||
it('skipback()', function()
|
||||
it('rskip()', function()
|
||||
do
|
||||
local q = { 4, 3, 2, 1 }
|
||||
eq(q, vim.iter(q):skipback(0):totable())
|
||||
eq({ 4, 3, 2 }, vim.iter(q):skipback(1):totable())
|
||||
eq({ 4, 3 }, vim.iter(q):skipback(2):totable())
|
||||
eq({ 4 }, vim.iter(q):skipback(#q - 1):totable())
|
||||
eq({}, vim.iter(q):skipback(#q):totable())
|
||||
eq({}, vim.iter(q):skipback(#q + 1):totable())
|
||||
eq(q, vim.iter(q):rskip(0):totable())
|
||||
eq({ 4, 3, 2 }, vim.iter(q):rskip(1):totable())
|
||||
eq({ 4, 3 }, vim.iter(q):rskip(2):totable())
|
||||
eq({ 4 }, vim.iter(q):rskip(#q - 1):totable())
|
||||
eq({}, vim.iter(q):rskip(#q):totable())
|
||||
eq({}, vim.iter(q):rskip(#q + 1):totable())
|
||||
end
|
||||
|
||||
local it = vim.iter(vim.gsplit('a|b|c|d', '|'))
|
||||
matches('skipback%(%) requires a list%-like table', pcall_err(it.skipback, it, 0))
|
||||
matches('rskip%(%) requires a list%-like table', pcall_err(it.rskip, it, 0))
|
||||
end)
|
||||
|
||||
it('slice()', function()
|
||||
|
|
@ -222,19 +222,19 @@ describe('vim.iter', function()
|
|||
end
|
||||
end)
|
||||
|
||||
it('nthback()', function()
|
||||
it('nth(-x) advances in reverse order starting from end', function()
|
||||
do
|
||||
local q = { 4, 3, 2, 1 }
|
||||
eq(nil, vim.iter(q):nthback(0))
|
||||
eq(1, vim.iter(q):nthback(1))
|
||||
eq(2, vim.iter(q):nthback(2))
|
||||
eq(3, vim.iter(q):nthback(3))
|
||||
eq(4, vim.iter(q):nthback(4))
|
||||
eq(nil, vim.iter(q):nthback(5))
|
||||
eq(nil, vim.iter(q):nth(0))
|
||||
eq(1, vim.iter(q):nth(-1))
|
||||
eq(2, vim.iter(q):nth(-2))
|
||||
eq(3, vim.iter(q):nth(-3))
|
||||
eq(4, vim.iter(q):nth(-4))
|
||||
eq(nil, vim.iter(q):nth(-5))
|
||||
end
|
||||
|
||||
local it = vim.iter(vim.gsplit('a|b|c|d', '|'))
|
||||
matches('skipback%(%) requires a list%-like table', pcall_err(it.nthback, it, 1))
|
||||
matches('rskip%(%) requires a list%-like table', pcall_err(it.nth, it, -1))
|
||||
end)
|
||||
|
||||
it('take()', function()
|
||||
|
|
@ -421,34 +421,34 @@ describe('vim.iter', function()
|
|||
end
|
||||
end)
|
||||
|
||||
it('nextback()', function()
|
||||
it('pop()', function()
|
||||
do
|
||||
local it = vim.iter({ 1, 2, 3, 4 })
|
||||
eq(4, it:nextback())
|
||||
eq(3, it:nextback())
|
||||
eq(2, it:nextback())
|
||||
eq(1, it:nextback())
|
||||
eq(nil, it:nextback())
|
||||
eq(nil, it:nextback())
|
||||
eq(4, it:pop())
|
||||
eq(3, it:pop())
|
||||
eq(2, it:pop())
|
||||
eq(1, it:pop())
|
||||
eq(nil, it:pop())
|
||||
eq(nil, it:pop())
|
||||
end
|
||||
|
||||
do
|
||||
local it = vim.iter(vim.gsplit('hi', ''))
|
||||
matches('nextback%(%) requires a list%-like table', pcall_err(it.nextback, it))
|
||||
matches('pop%(%) requires a list%-like table', pcall_err(it.pop, it))
|
||||
end
|
||||
end)
|
||||
|
||||
it('peekback()', function()
|
||||
it('rpeek()', function()
|
||||
do
|
||||
local it = vim.iter({ 1, 2, 3, 4 })
|
||||
eq(4, it:peekback())
|
||||
eq(4, it:peekback())
|
||||
eq(4, it:nextback())
|
||||
eq(4, it:rpeek())
|
||||
eq(4, it:rpeek())
|
||||
eq(4, it:pop())
|
||||
end
|
||||
|
||||
do
|
||||
local it = vim.iter(vim.gsplit('hi', ''))
|
||||
matches('peekback%(%) requires a list%-like table', pcall_err(it.peekback, it))
|
||||
matches('rpeek%(%) requires a list%-like table', pcall_err(it.rpeek, it))
|
||||
end
|
||||
end)
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue