vim.Iter

Filters an iterator pipeline.

Example:

local bufs = vim.iter(vim.api.nvim_list_bufs()):filter(vim.api.nvim_buf_is_loaded)

Removes duplicate values from an iterator pipeline.

Only the first occurrence of each value is kept.

Accepts an optional key argument, which if provided is called for each value in the iterator to compute a hash key for uniqueness comparison. This is useful for deduplicating table values or complex objects. If key returns nil for a value, that value will be considered unique, even if multiple values return nil.

If a function-based iterator returns multiple arguments, uniqueness is checked based on the first return value. To change this behavior, specify key.

Examples:

vim.iter({ 1, 2, 2, 3, 2 }):unique():totable()
-- { 1, 2, 3 }

vim.iter({ {id=1}, {id=2}, {id=1} })
  :unique(function(x)
    return x.id
  end)
  :totable()
-- { {id=1}, {id=2} }

Maps the items of an iterator pipeline to the values returned by f.

If the map function returns nil, the value is filtered from the iterator.

Example:

local it = vim.iter({ 1, 2, 3, 4 }):map(function(v)
  if v % 2 == 0 then
    return v * 3
  end
end)
it:totable()
-- { 6, 12 }

Calls a function once for each item in the pipeline, draining the iterator.

For functions with side effects. To modify the values in the iterator, use |Iter:map()|.

Collect the iterator into a table.

The resulting table depends on the initial source in the iterator pipeline. Array-like tables and function iterators will be collected into an array-like table. If multiple values are returned from the final stage in the iterator pipeline, each value will be included in a table.

Examples:

vim.iter(string.gmatch('100 20 50', '%d+')):map(tonumber):totable()
-- { 100, 20, 50 }

vim.iter({ 1, 2, 3 }):map(function(v) return v, 2 * v end):totable()
-- { { 1, 2 }, { 2, 4 }, { 3, 6 } }

vim.iter({ a = 1, b = 2, c = 3 }):filter(function(k, v) return v % 2 ~= 0 end):totable()
-- { { 'a', 1 }, { 'c', 3 } }

The generated table is an array-like table with consecutive, numeric indices. To create a map-like table with arbitrary keys, use |Iter:fold()|.

Collect the iterator into a delimited string.

Each element in the iterator is joined into a string separated by {delim}.

Consumes the iterator.

Folds ("reduces") an iterator into a single value. Iter:reduce()

Examples:

-- Create a new table with only even values
vim.iter({ a = 1, b = 2, c = 3, d = 4 })
  :filter(function(k, v) return v % 2 == 0 end)
  :fold({}, function(acc, k, v)
    acc[k] = v
    return acc
  end) --> { b = 2, d = 4 }

-- Get the "maximum" item of an iterable.
vim.iter({ -99, -4, 3, 42, 0, 0, 7 })
  :fold({}, function(acc, v)
    acc.max = math.max(v, acc.max or v)
    return acc
  end) --> { max = 42 }

Gets the next value from the iterator without consuming it.

The value returned by |Iter:peek()| will be returned again by the next call to |Iter:next()|.

Example:

local it = vim.iter({ 3, 6, 9, 12 })
it:peek()
-- 3
it:peek()
-- 3
it:next()
-- 3

Find the first value in the iterator that satisfies the given predicate.

Advances the iterator. Returns nil and drains the iterator if no value is found.

Examples:

local it = vim.iter({ 3, 6, 9, 12 })
it:find(12)
-- 12

local it = vim.iter({ 3, 6, 9, 12 })
it:find(20)
-- nil

local it = vim.iter({ 3, 6, 9, 12 })
it:find(function(v) return v % 4 == 0 end)
-- 12

Transforms an iterator to yield only the first n values, or all values satisfying a predicate.

Example:

local it = vim.iter({ 1, 2, 3, 4 }):take(2)
it:next()
-- 1
it:next()
-- 2
it:next()
-- nil

local function pred(x) return x < 2 end
local it2 = vim.iter({ 1, 2, 3, 4 }):take(pred)
it2:next()
-- 1
it2:next()
-- nil

Skips n values of an iterator pipeline, or skips values while a predicate returns |lua-truthy|.

When a predicate is used, skipping stops at the first value for which the predicate returns non-truthy. That value is not consumed and will be returned by the next call to |Iter:next()|

Example:

local it = vim.iter({ 3, 6, 9, 12 }):skip(2)
it:next()
-- 9

local function pred(x) return x < 10 end
local it2 = vim.iter({ 3, 6, 9, 12 }):skip(pred)
it2:next()
-- 12

Gets the nth value of an iterator (and advances to it).

If n is negative, offsets from the end of a |list-iterator|.

Example:

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

Returns true if any of the items in the iterator match the given predicate.

Returns true if all items in the iterator match the given predicate.

Drains the iterator and returns the last item.

Example:

local it = vim.iter(vim.gsplit('abcdefg', ''))
it:last()
-- 'g'

local it = vim.iter({ 3, 6, 9, 12, 15 })
it:last()
-- 15

Yields the item index (count) and value for each item of an iterator pipeline.

For list tables, this is more efficient:

vim.iter(ipairs(t))

instead of:

vim.iter(t):enumerate()

Example:

local it = vim.iter(vim.gsplit('abc', '')):enumerate()
it:next()
-- 1	'a'
it:next()
-- 2	'b'
it:next()
-- 3	'c'

Drains the iterator, counting the number of iterations and returning it.