diff options
Diffstat (limited to 'runtime/lua/vim/iter.lua')
| -rw-r--r-- | runtime/lua/vim/iter.lua | 187 |
1 files changed, 105 insertions, 82 deletions
diff --git a/runtime/lua/vim/iter.lua b/runtime/lua/vim/iter.lua index 56c130dd0c..595baa7019 100644 --- a/runtime/lua/vim/iter.lua +++ b/runtime/lua/vim/iter.lua @@ -15,44 +15,45 @@ --- (for function iterators, this means that the first value returned by the function is nil). --- --- Examples: ---- <pre>lua ---- local it = vim.iter({ 1, 2, 3, 4, 5 }) ---- it:map(function(v) ---- return v * 3 ---- end) ---- it:rev() ---- it:skip(2) ---- it:totable() ---- -- { 9, 6, 3 } ---- ---- -- ipairs() is a function iterator which returns both the index (i) and the value (v) ---- vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v) ---- if i > 2 then return v end ---- end):totable() ---- -- { 3, 4, 5 } ---- ---- local it = vim.iter(vim.gsplit('1,2,3,4,5', ',')) ---- it:map(function(s) return tonumber(s) end) ---- for i, d in it:enumerate() do ---- print(string.format("Column %d is %d", i, d)) ---- end ---- -- Column 1 is 1 ---- -- Column 2 is 2 ---- -- Column 3 is 3 ---- -- Column 4 is 4 ---- -- Column 5 is 5 ---- ---- vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v) ---- return k == 'z' ---- end) ---- -- true ---- ---- local rb = vim.ringbuf(3) ---- rb:push("a") ---- rb:push("b") ---- vim.iter(rb):totable() ---- -- { "a", "b" } ---- </pre> +--- +--- ```lua +--- local it = vim.iter({ 1, 2, 3, 4, 5 }) +--- it:map(function(v) +--- return v * 3 +--- end) +--- it:rev() +--- it:skip(2) +--- it:totable() +--- -- { 9, 6, 3 } +--- +--- -- ipairs() is a function iterator which returns both the index (i) and the value (v) +--- vim.iter(ipairs({ 1, 2, 3, 4, 5 })):map(function(i, v) +--- if i > 2 then return v end +--- end):totable() +--- -- { 3, 4, 5 } +--- +--- local it = vim.iter(vim.gsplit('1,2,3,4,5', ',')) +--- it:map(function(s) return tonumber(s) end) +--- for i, d in it:enumerate() do +--- print(string.format("Column %d is %d", i, d)) +--- end +--- -- Column 1 is 1 +--- -- Column 2 is 2 +--- -- Column 3 is 3 +--- -- Column 4 is 4 +--- -- Column 5 is 5 +--- +--- vim.iter({ a = 1, b = 2, c = 3, z = 26 }):any(function(k, v) +--- return k == 'z' +--- end) +--- -- true +--- +--- local rb = vim.ringbuf(3) +--- rb:push("a") +--- rb:push("b") +--- vim.iter(rb):totable() +--- -- { "a", "b" } +--- ``` --- --- In addition to the |vim.iter()| function, the |vim.iter| module provides --- convenience functions like |vim.iter.filter()| and |vim.iter.totable()|. @@ -140,9 +141,10 @@ end --- Add a filter step to the iterator pipeline. --- --- Example: ---- <pre>lua +--- +--- ```lua --- local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded) ---- </pre> +--- ``` --- ---@param f function(...):bool Takes all values returned from the previous stage --- in the pipeline and returns false or nil if the @@ -176,7 +178,8 @@ end --- If the map function returns nil, the value is filtered from the iterator. --- --- Example: ---- <pre>lua +--- +--- ```lua --- local it = vim.iter({ 1, 2, 3, 4 }):map(function(v) --- if v % 2 == 0 then --- return v * 3 @@ -184,7 +187,7 @@ end --- end) --- it:totable() --- -- { 6, 12 } ---- </pre> +--- ``` --- ---@param f function(...):any Mapping function. Takes all values returned from --- the previous stage in the pipeline as arguments @@ -288,7 +291,8 @@ end --- pipeline, each value will be included in a table. --- --- Examples: ---- <pre>lua +--- +--- ```lua --- vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable() --- -- { 100, 20, 50 } --- @@ -297,7 +301,7 @@ end --- --- vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable() --- -- { { 'a', 1 }, { 'c', 3 } } ---- </pre> +--- ``` --- --- The generated table is a list-like table with consecutive, numeric indices. --- To create a map-like table with arbitrary keys, use |Iter:fold()|. @@ -352,7 +356,8 @@ end --- Fold ("reduce") an iterator or table into a single value. --- --- Examples: ---- <pre>lua +--- +--- ```lua --- -- Create a new table with only even values --- local t = { a = 1, b = 2, c = 3, d = 4 } --- local it = vim.iter(t) @@ -362,7 +367,7 @@ end --- return t --- end) --- -- { b = 2, d = 4 } ---- </pre> +--- ``` --- ---@generic A --- @@ -398,7 +403,8 @@ end --- Return the next value from the iterator. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber) --- it:next() @@ -408,7 +414,7 @@ end --- it:next() --- -- 3 --- ---- </pre> +--- ``` --- ---@return any function Iter.next(self) -- luacheck: no unused args @@ -431,13 +437,14 @@ end --- Only supported for iterators on list-like tables. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 3, 6, 9, 12 }):rev() --- it:totable() --- -- { 12, 9, 6, 3 } --- ---- </pre> +--- ``` --- ---@return Iter function Iter.rev(self) @@ -457,7 +464,8 @@ end --- Only supported for iterators on list-like tables. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 3, 6, 9, 12 }) --- it:peek() @@ -467,7 +475,7 @@ end --- it:next() --- -- 3 --- ---- </pre> +--- ``` --- ---@return any function Iter.peek(self) -- luacheck: no unused args @@ -486,7 +494,8 @@ end --- Advances the iterator. Returns nil and drains the iterator if no value is found. --- --- Examples: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 3, 6, 9, 12 }) --- it:find(12) @@ -500,7 +509,7 @@ end --- it:find(function(v) return v % 4 == 0 end) --- -- 12 --- ---- </pre> +--- ``` --- ---@return any function Iter.find(self, f) @@ -536,7 +545,8 @@ end --- Only supported for iterators on list-like tables. --- --- Examples: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate() --- it:rfind(1) @@ -544,7 +554,7 @@ end --- it:rfind(1) --- -- 1 1 --- ---- </pre> +--- ``` --- ---@see Iter.find --- @@ -578,13 +588,14 @@ end --- Only supported for iterators on list-like tables. --- --- Example: ---- <pre>lua +--- +--- ```lua --- local it = vim.iter({1, 2, 3, 4}) --- it:nextback() --- -- 4 --- it:nextback() --- -- 3 ---- </pre> +--- ``` --- ---@return any function Iter.nextback(self) -- luacheck: no unused args @@ -604,7 +615,8 @@ end --- Only supported for iterators on list-like tables. --- --- Example: ---- <pre>lua +--- +--- ```lua --- local it = vim.iter({1, 2, 3, 4}) --- it:peekback() --- -- 4 @@ -612,7 +624,7 @@ end --- -- 4 --- it:nextback() --- -- 4 ---- </pre> +--- ``` --- ---@return any function Iter.peekback(self) -- luacheck: no unused args @@ -629,13 +641,14 @@ end --- Skip values in the iterator. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 3, 6, 9, 12 }):skip(2) --- it:next() --- -- 9 --- ---- </pre> +--- ``` --- ---@param n number Number of values to skip. ---@return Iter @@ -661,13 +674,14 @@ end --- Only supported for iterators on list-like tables. --- --- Example: ---- <pre>lua +--- +--- ```lua --- local it = vim.iter({ 1, 2, 3, 4, 5 }):skipback(2) --- it:next() --- -- 1 --- it:nextback() --- -- 3 ---- </pre> +--- ``` --- ---@param n number Number of values to skip. ---@return Iter @@ -691,7 +705,8 @@ end --- This function advances the iterator. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 3, 6, 9, 12 }) --- it:nth(2) @@ -699,7 +714,7 @@ end --- it:nth(2) --- -- 12 --- ---- </pre> +--- ``` --- ---@param n number The index of the value to return. ---@return any @@ -716,7 +731,8 @@ end --- Only supported for iterators on list-like tables. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter({ 3, 6, 9, 12 }) --- it:nthback(2) @@ -724,7 +740,7 @@ end --- it:nthback(2) --- -- 3 --- ---- </pre> +--- ``` --- ---@param n number The index of the value to return. ---@return any @@ -805,7 +821,8 @@ end --- Drains the iterator. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter(vim.gsplit('abcdefg', '')) --- it:last() @@ -815,7 +832,7 @@ end --- it:last() --- -- 15 --- ---- </pre> +--- ``` --- ---@return any function Iter.last(self) @@ -839,19 +856,22 @@ end --- Add an iterator stage that returns the current iterator count as well as the iterator value. --- --- For list tables, prefer ---- <pre>lua +--- +--- ```lua --- vim.iter(ipairs(t)) ---- </pre> +--- ``` --- --- over ---- <pre>lua +--- +--- ```lua --- vim.iter(t):enumerate() ---- </pre> +--- ``` --- --- as the former is faster. --- --- Example: ---- <pre>lua +--- +--- ```lua --- --- local it = vim.iter(vim.gsplit('abc', '')):enumerate() --- it:next() @@ -861,7 +881,7 @@ end --- it:next() --- -- 3 'c' --- ---- </pre> +--- ``` --- ---@return Iter function Iter.enumerate(self) @@ -959,9 +979,10 @@ end --- Collect an iterator into a table. --- --- This is a convenience function that performs: ---- <pre>lua +--- +--- ```lua --- vim.iter(f):totable() ---- </pre> +--- ``` --- ---@param f function Iterator function ---@return table @@ -972,9 +993,10 @@ end --- Filter a table or iterator. --- --- This is a convenience function that performs: ---- <pre>lua +--- +--- ```lua --- vim.iter(src):filter(f):totable() ---- </pre> +--- ``` --- ---@see |Iter:filter()| --- @@ -990,9 +1012,10 @@ end --- Map and filter a table or iterator. --- --- This is a convenience function that performs: ---- <pre>lua +--- +--- ```lua --- vim.iter(src):map(f):totable() ---- </pre> +--- ``` --- ---@see |Iter:map()| --- |