utils/dev.kindling.utils.state/KCircularBuffer

KCircularBuffer

class KCircularBuffer<T>(val capacity: Int, initialItems: List<T> = emptyList())(source)

A fixed-capacity ring buffer (Circular Buffer).

When the buffer is full, adding a new item silently drops the oldest entry. This implementation is ideal for bounded logs, recent-search history, rolling telemetry windows, or any scenario where you only need to keep the last N items.

The buffer state is exposed as a StateFlow, making it easy to observe changes in a reactive UI.

Example usage:

val log = KCircularBuffer<String>(capacity = 3)
log.add("a")  // Buffer: [a]
log.add("b")  // Buffer: [a, b]
log.add("c")  // Buffer: [a, b, c]
log.add("d")  // Buffer: [b, c, d]  ← "a" is automatically dropped

println(log.toList()) // Prints: [b, c, d]
println(log.latest()) // Prints: "d"

// In a Composable:
val items by log.state.collectAsState()
LazyColumn {
    items(items) { Text(it) }
}

Parameters

capacity

The maximum number of items the buffer can retain. Must be ≥ 1.

initialItems

Optional list of items to pre-populate the buffer with (ordered oldest to newest). If the list size exceeds capacity, only the last capacity items are kept.