feat(lua): add ringbuffer (#22894)

https://en.wikipedia.org/wiki/Circular_buffer

2 files changed, 56 insertions, 0 deletions

diff --git a/runtime/doc/lua.txt b/runtime/doc/lua.txt
index 5e0a1edc11..babd9b801c 100644
--- a/runtime/doc/lua.txt
+++ b/runtime/doc/lua.txt
@@ -1847,6 +1847,60 @@ pesc({s})                                                         *vim.pesc()*
     See also: ~
       • https://github.com/rxi/lume
 
+ringbuf({size})                                                *vim.ringbuf()*
+    Create a ring buffer limited to a maximal number of items. Once the buffer
+    is full, adding a new entry overrides the oldest entry.
+>
+
+    local ringbuf = vim.ringbuf(4)
+    ringbuf:push("a")
+    ringbuf:push("b")
+    ringbuf:push("c")
+    ringbuf:push("d")
+    ringbuf:push("e")    -- overrides "a"
+    print(ringbuf:pop()) -- returns "b"
+    print(ringbuf:pop()) -- returns "c"
+
+    -- Can be used as iterator. Pops remaining items:
+    for val in ringbuf do
+      print(val)
+    end
+<
+
+    Returns a Ringbuf instance with the following methods:
+
+    • |Ringbuf:push()|
+    • |Ringbuf:pop()|
+    • |Ringbuf:peek()|
+    • |Ringbuf:clear()|
+
+    Parameters: ~
+      • {size}  (integer)
+
+    Return: ~
+        (table)
+
+Ringbuf:clear({self})                                        *Ringbuf:clear()*
+    Clear all items.
+
+Ringbuf:peek({self})                                          *Ringbuf:peek()*
+    Returns the first unread item without removing it
+
+    Return: ~
+        any?|ni
+
+Ringbuf:pop({self})                                            *Ringbuf:pop()*
+    Removes and returns the first unread item
+
+    Return: ~
+        any?|ni
+
+Ringbuf:push({self}, {item})                                  *Ringbuf:push()*
+    Adds an item, overriding the oldest item if the buffer is full.
+
+    Parameters: ~
+      • {item}  any
+
 spairs({t})                                                     *vim.spairs()*
     Enumerate a table sorted by its keys.
 
diff --git a/runtime/doc/news.txt b/runtime/doc/news.txt
index 4afb3429f4..dbf5b131eb 100644
--- a/runtime/doc/news.txt
+++ b/runtime/doc/news.txt
@@ -59,6 +59,8 @@ The following new APIs or features were added.
 • |vim.iter()| provides a generic iterator interface for tables and Lua
   iterators |luaref-in|.
 
+• Added |vim.ringbuf()| to create ring buffers.
+
 • Added |vim.keycode()| for translating keycodes in a string.
 
 • Added |vim.treesitter.query.omnifunc()| for treesitter query files (set by