Generic Stack (VBA, Array-Backed)

A lightweight LIFO stack implemented on top of a dynamic array with chunked growth/shrink.
Designed for speed and memory efficiency versus a Collection-backed stack, while preserving a clean API.

---

📦 Features

• Fast push/pop using a dynamic array with headspace (ChunkSize)
• Lower memory use than Collection (≈2× less per item on x64; extra headspace applies)
• Shrink logic: reclaims capacity when headspace grows to 2 * ChunkSize
• Enumeration: For Each (top → bottom) via an intermediate Collection
• Utility export: Items([base]) returns a 0- or 1-based array copy
• Pure VBA, no external references

---

⚙️ Public Interface

Member	Type	Description
Push(Item)	Sub	Adds an item at the top.
Pop()	Function	Returns and removes the top item. Raises error 5 if empty.
Peek (Default)	Property	Returns the top item without removing it. Raises error 5 if empty.
Count	Property	Number of items currently stored.
IsEmpty	Property	True if empty, else False.
Clear	Sub	Clears the stack and resets capacity to one ChunkSize.
Items([base])	Function	Copies items into Variant(); order is top → bottom.
For Each	Enumerator	Iterates top → bottom. (Don’t mutate while iterating.)

Errors

• Empty stack on Peek/Pop raises vbErrorInvalidProcedureCall (=5) with source "Stack.Peek" / "Stack.Pop".

---

🚀 Quick Start

Dim s As New Stack

s.Push "alpha"
s.Push "beta"
Debug.Print s.Peek        ' -> beta
Debug.Print s.Pop         ' -> beta (removed)
Debug.Print s.Pop         ' -> alpha (removed)
Debug.Print s.IsEmpty     ' -> True

⚡ Performance Notes

The array-based implementation provides constant-time O(1) Push and Pop operations for normal workloads,
while outperforming the Collection-based version in speed and memory use.

Timings (ms) per Push + Pop cycle

Count	Array	Collection
10	0.00025	0.00049
100	0.00025	0.00049
1 000	0.00025	0.00050
10 000	0.00025	0.00049
100 000	0.00281	0.00050

Observations

• The array version is roughly 2× faster than the Collection version at small to medium stack sizes.
• It uses about half the memory per stored item on x64 systems (excluding the headspace buffer).
• When the stack grows beyond several hundred thousand items, occasional ReDim Preserve operations cause timing spikes.
  These are amortized and remain negligible for practical workloads.
• The collection version stays stable at very large sizes but pays a constant late-binding penalty internally.
• Resizing follows a chunked strategy (ChunkSize = 100) to balance allocation overhead and memory fragmentation.

Practical Guidance

• For computational stacks, recursion simulations, or evaluation engines where typical depth ≤ 100 000,
  prefer the array stack for speed and memory efficiency.
• For unbounded or long-lived stacks (e.g., message buffers), the collection stack may offer smoother scalability.
• Increasing ChunkSize reduces the frequency of ReDim Preserve calls at the cost of higher idle headspace.

All timings were measured in VBA 7 (x64) on Windows 11 using a high-resolution Stopwatch based on QueryPerformanceCounter.

---