--- @brief

---

--- [vim.iter()]() is an interface for [iterable]s: it wraps a table or function argument into an

--- [Iter]() object with methods (such as [Iter:filter()] and [Iter:map()]) that transform the

--- underlying source data. These methods can be chained to create iterator "pipelines": the output

--- of each pipeline stage is input to the next stage. The first stage depends on the type passed to

--- `vim.iter()`:

---

--- - Lists or arrays (|lua-list|) yield only the value of each element.

--- - Holes (nil values) are allowed (but discarded).

--- - Use pairs() to treat array/list tables as dicts (preserve holes and non-contiguous integer

--- keys): `vim.iter(pairs(…))`.

--- - Use |Iter:enumerate()| to also pass the index to the next stage.

--- - Or initialize with ipairs(): `vim.iter(ipairs(…))`.

--- - Non-list tables (|lua-dict|) yield both the key and value of each element.

--- - Function |iterator|s yield all values returned by the underlying function.

--- - Tables with a |__call()| metamethod are treated as function iterators.

---

--- The iterator pipeline terminates when the underlying |iterable| is exhausted (for function

--- iterators this means it returned nil).

---

--- Note: `vim.iter()` scans table input to decide if it is a list or a dict; to avoid this cost you

--- can wrap the table with an iterator e.g. `vim.iter(ipairs({…}))`, but that precludes the use of

--- |list-iterator| operations such as |Iter:rev()|).

---

--- Examples:

---

--- ```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" }

--- ```

--- LuaLS is bad at generics which this module mostly deals with

--- @diagnostic disable:no-unknown

---@nodoc

---@class IterMod

---@operator call:Iter

local M = {}

---@nodoc

---@class Iter

local Iter = {}

Iter.__index = Iter

Iter.__call = function(self)

return self:next()

end

--- Special case implementations for iterators on list tables.

---@nodoc

---@class ArrayIter : Iter

---@field _table table Underlying table data

---@field _head number Index to the front of a table iterator

---@field _tail number Index to the end of a table iterator (exclusive)

local ArrayIter = {}

ArrayIter.__index = setmetatable(ArrayIter, Iter)

ArrayIter.__call = function(self)

return self:next()

end

--- Packed tables use this as their metatable

local packedmt = {}

local function unpack(t)

end

local function pack(...)

end

local function sanitize(t)

end

--- Flattens a single array-like table. Errors if it attempts to flatten a

--- dict-like table

---@param t table table which should be flattened

---@param max_depth number depth to which the table should be flattened

---@param depth number current iteration depth

---@param result table output table that contains flattened result

---@return table|nil flattened table if it can be flattened, otherwise nil

local function flatten(t, max_depth, depth, result)

end

--- Determine if the current iterator stage should continue.

---

--- If any arguments are passed to this function, then return those arguments

--- and stop the current iterator stage. Otherwise, return true to signal that

--- the current stage should continue.

---

---@param ... any Function arguments.

---@return boolean True if the iterator stage should continue, false otherwise

---@return any Function arguments.

local function continue(...)

end

--- If no input arguments are given return false, indicating the current

--- iterator stage should stop. Otherwise, apply the arguments to the function

--- f. If that function returns no values, the current iterator stage continues.

--- Otherwise, those values are returned.

---

---@param f function Function to call with the given arguments

---@param ... any Arguments to apply to f

---@return boolean True if the iterator pipeline should continue, false otherwise

---@return any Return values of f

local function apply(f, ...)

end

--- Filters an iterator pipeline.

---

--- Example:

---

--- ```lua

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

--- ```

---

---@param f fun(...):boolean Takes all values returned from the previous stage

--- in the pipeline and returns false or nil if the

--- current iterator element should be removed.

---@return Iter

function Iter:filter(f)

end

---@private

function ArrayIter:filter(f)

end

--- Flattens a |list-iterator|, un-nesting nested values up to the given {depth}.

--- Errors if it attempts to flatten a dict-like value.

---

--- Examples:

---

--- ```lua

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

--- -- { 1, 2, { 3 } }

---

--- vim.iter({1, { { a = 2 } }, { 3 } }):flatten():totable()

--- -- { 1, { a = 2 }, 3 }

---

--- vim.iter({ 1, { { a = 2 } }, { 3 } }):flatten(math.huge):totable()

--- -- error: attempt to flatten a dict-like table

--- ```

---

---@param depth? number Depth to which |list-iterator| should be flattened

--- (defaults to 1)

---@return Iter

---@diagnostic disable-next-line:unused-local

function Iter:flatten(depth) -- luacheck: no unused args

error('flatten() requires an array-like table')

end

---@private

function ArrayIter:flatten(depth)

end

--- 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:

---

--- ```lua

--- 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 }

--- ```

---

---@param f fun(...):...:any Mapping function. Takes all values returned from

--- the previous stage in the pipeline as arguments

--- and returns one or more new values, which are used

--- in the next pipeline stage. Nil return values

--- are filtered from the output.

---@return Iter

function Iter:map(f)

end

---@private

function ArrayIter:map(f)

end

--- 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()|.

---

---@param f fun(...) Function to execute for each item in the pipeline.

--- Takes all of the values returned by the previous stage

--- in the pipeline as arguments.

function Iter:each(f)

end

---@private

function ArrayIter:each(f)

end

--- 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:

---

--- ```lua

--- 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()|.

---

---

---@return table

function Iter:totable()

end

---@private

function ArrayIter:totable()

end

--- Collect the iterator into a delimited string.

---

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

---

--- Consumes the iterator.

---

--- @param delim string Delimiter

--- @return string

function Iter:join(delim)

return table.concat(self:totable(), delim)

end

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

---

--- Examples:

---

--- ```lua

--- -- 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 }

--- ```

---

---@generic A

---

---@param init A Initial value of the accumulator.

---@param f fun(acc:A, ...):A Accumulation function.

---@return A

function Iter:fold(init, f)

end

---@private

function ArrayIter:fold(init, f)

end

--- Gets the next value from the iterator.

---

--- Example:

---

--- ```lua

---

--- local it = vim.iter(string.gmatch('1 2 3', '%d+')):map(tonumber)

--- it:next()

--- -- 1

--- it:next()

--- -- 2

--- it:next()

--- -- 3

---

--- ```

---

---@return any

function Iter:next()

-- This function is provided by the source iterator in Iter.new. This definition exists only for

-- the docstring

end

---@private

function ArrayIter:next()

end

--- Reverses a |list-iterator| pipeline.

---

--- Example:

---

--- ```lua

---

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

--- it:totable()

--- -- { 12, 9, 6, 3 }

---

--- ```

---

---@return Iter

function Iter:rev()

error('rev() requires an array-like table')

end

---@private

function ArrayIter:rev()

end

--- Gets the next value in a |list-iterator| without consuming it.

---

--- Example:

---

--- ```lua

---

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

--- it:peek()

--- -- 3

--- it:peek()

--- -- 3

--- it:next()

--- -- 3

---

--- ```

---

---@return any

function Iter:peek()

error('peek() requires an array-like table')

end

---@private

function ArrayIter:peek()

end

--- 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:

---

--- ```lua

---

--- 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

---

--- ```

---@param f any

---@return any

function Iter:find(f)

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.

---

--- Examples:

---

--- ```lua

---

--- local it = vim.iter({ 1, 2, 3, 2, 1 }):enumerate()

--- it:rfind(1)

--- -- 5 1

--- it:rfind(1)

--- -- 1 1

---

--- ```

---

---@see |Iter:find()|

---

---@param f any

---@return any

---@diagnostic disable-next-line: unused-local

function Iter:rfind(f) -- luacheck: no unused args

error('rfind() requires an array-like table')

end

---@private

function ArrayIter:rfind(f)

end

--- Transforms an iterator to yield only the first n values.

---

--- Example:

---

--- ```lua

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

--- it:next()

--- -- 1

--- it:next()

--- -- 2

--- it:next()

--- -- nil

--- ```

---

---@param n integer

---@return Iter

function Iter:take(n)

end

---@private

function ArrayIter:take(n)

end

--- "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:pop()

--- -- 4

--- it:pop()

--- -- 3

--- ```

---

---@return any

function Iter:pop()

error('pop() requires an array-like table')

end

--- @nodoc

function ArrayIter:pop()

end

--- 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

--- ```

---

---@see |Iter:last()|

---

---@return any

function Iter:rpeek()

error('rpeek() requires an array-like table')

end

---@nodoc

function ArrayIter:rpeek()

end

--- Skips `n` values of an iterator pipeline.

---

--- Example:

---

--- ```lua

---

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

--- it:next()

--- -- 9

---

--- ```

---

---@param n number Number of values to skip.

---@return Iter

function Iter:skip(n)

end

---@private

function ArrayIter:skip(n)

end

--- 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

--- ```

---

---@param n number Number of values to skip.

---@return Iter

---@diagnostic disable-next-line: unused-local

function Iter:rskip(n) -- luacheck: no unused args

error('rskip() requires an array-like table')

end

---@private

function ArrayIter:rskip(n)

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 Index of the value to return. May be negative if the source is a |list-iterator|.

---@return any

function Iter:nth(n)

end

--- Sets the start and end of a |list-iterator| pipeline.

---

--- Equivalent to `:skip(first - 1):rskip(len - last + 1)`.

---

---@param first number

---@param last number

---@return Iter

---@diagnostic disable-next-line: unused-local

function Iter:slice(first, last) -- luacheck: no unused args

error('slice() requires an array-like table')

end

---@private

function ArrayIter:slice(first, last)

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.

---

---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous

--- stage in the pipeline as arguments and returns true if the

--- predicate matches.

function Iter:any(pred)

end

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

---

---@param pred fun(...):boolean Predicate function. Takes all values returned from the previous

--- stage in the pipeline as arguments and returns true if the

--- predicate matches.

function Iter:all(pred)

end

--- Drains the iterator and returns the last item.

---

--- Example:

---

--- ```lua

---

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

--- it:last()

--- -- 'g'

---

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

--- it:last()

--- -- 15

---

--- ```

---

---@see |Iter:rpeek()|

---

---@return any

function Iter:last()

end

---@private

function ArrayIter:last()

end

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

---

--- For list tables, this is more efficient:

---

--- ```lua

--- vim.iter(ipairs(t))

--- ```

---

--- instead of:

---

--- ```lua

--- vim.iter(t):enumerate()

--- ```

---

--- Example:

---

--- ```lua

---

--- local it = vim.iter(vim.gsplit('abc', '')):enumerate()

--- it:next()

--- -- 1 'a'

--- it:next()

--- -- 2 'b'

--- it:next()

--- -- 3 'c'

---

--- ```

---

---@return Iter

function Iter:enumerate()