diff options
| -rw-r--r-- | runtime/doc/lua.txt | 102 | ||||
| -rw-r--r-- | runtime/doc/news.txt | 8 | ||||
| -rw-r--r-- | runtime/lua/vim/iter.lua | 100 | ||||
| -rw-r--r-- | test/functional/lua/iter_spec.lua | 58 |
4 files changed, 139 insertions, 129 deletions
diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt index 1411ac7436..51dcf99dd2 100644 --- a/runtime/doc/lua.txt +++ b/runtime/doc/lua.txt @@ -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,14 +4193,34 @@ Iter:rfind({f}) *Iter:rfind()* See also: ~ • Iter.find -Iter:skip({n}) *Iter:skip()* - Skips `n` values of an iterator pipeline. +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 +< - local it = vim.iter({ 3, 6, 9, 12 }):skip(2) + 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() - -- 9 + -- 1 + it:pop() + -- 3 < Parameters: ~ @@ -4234,15 +4229,14 @@ Iter:skip({n}) *Iter:skip()* Return: ~ (`Iter`) -Iter:skipback({n}) *Iter:skipback()* - Skips `n` values backwards from the end of a |list-iterator| pipeline. +Iter:skip({n}) *Iter:skip()* + Skips `n` values of an iterator pipeline. Example: >lua - local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2) + + local it = vim.iter({ 3, 6, 9, 12 }):skip(2) it:next() - -- 1 - it:nextback() - -- 3 + -- 9 < Parameters: ~ @@ -4254,7 +4248,7 @@ Iter:skipback({n}) *Iter:skipback()* 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`) diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt index b2e20e5405..5881d90358 100644 --- a/runtime/doc/news.txt +++ b/runtime/doc/news.txt @@ -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* diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua index 302463b136..04137e18d4 100644 --- a/runtime/lua/vim/iter.lua +++ b/runtime/lua/vim/iter.lua @@ -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 --- ---- ``` ---- ----@param n number The index of the value to return. ----@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) +--- local it2 = vim.iter({ 3, 6, 9, 12 }) +--- it2:nth(-2) --- -- 9 ---- it:nthback(2) +--- 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:nthback(n) +function Iter:nth(n) if n > 0 then - return self:skipback(n - 1):nextback() + return self:skip(n - 1):next() + 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 diff --git a/test/functional/lua/iter_spec.lua b/test/functional/lua/iter_spec.lua index 92e809d55c..676b83a801 100644 --- a/test/functional/lua/iter_spec.lua +++ b/test/functional/lua/iter_spec.lua @@ -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) |