obitools4/autodoc/docmd/pkg/obiutils/minmultiset.md

MinMultiset[T] — A Lazy-Delete Min-Multiset Implementation

A generic, type-safe multiset data structure in Go that maintains elements with multiplicity and provides efficient access to the current minimum. Built on top of a min-heap (container/heap) with lazy deletion to support efficient removals without rebuilding the heap.

Core Features

• ✅ Generic over comparable types (T) with custom ordering via less comparator
• ✅ Multiset semantics: supports multiple occurrences of the same value
• ✅ O(log n) insertion (Add) and amortized O(1) minimum access
• ✅ Lazy deletion: RemoveOne marks items for removal; physical cleanup occurs on next Min() call
• ✅ Size tracking: logical size (Len()) excludes deleted items, even if still in heap
• ✅ Memory-efficient cleanup: shrink() and cleanTop() prevent tombstone accumulation

API Summary

Method	Description
NewMinMultiset(less)	Constructor; initializes heap, maps (count, pending), and sets ordering
Add(v)	Inserts one occurrence of v; increments logical size & count map
RemoveOne(v)	Removes one occurrence if present; returns success flag (false otherwise)
Min()	Returns current minimum (or zero value + ok=false) after cleaning stale top entries
Len()	Returns logical size (excludes pending deletions)

Internal Mechanism

• count[T]int: tracks how many times each value is logically present
• pending[T]int: tracks how many times each value is marked for removal
• Heap invariant maintained only up to logical size — stale entries are pruned lazily during Min() or after deletions
• No manual cleanup needed — the structure self-balances incrementally

Use Cases

Priority queues with deletable arbitrary elements (e.g., Dijkstra’s algorithm where distances are updated), sliding-window minima, event scheduling with cancellation.

⚠️ Note: less must define a strict total order (transitive, antisymmetric, connected) for correctness.