BSD-3-Clause licensed by Dominik Schrempf
Maintained by [email protected]
This version can be pinned in stack with:circular-,1842

Module documentation for

Used by 1 package in nightly-2024-02-22(full list with versions):


Circular stacks of fixed size.

Circular stacks are just normal vectors with a pointer to the last element.

Circular stacks may not be what you need because:

  • You need all values at a later time anyways.
  • You don’t want a monadic work flow, because circular stacks use mutable vectors.

Circular stacks are useful to you because:

  • They have a fixed size and consequently have constant memory usage. Constant memory usage is important if values are gathered continuously but only a specific number of values is needed at a later time.
  • They are fast, especially when summary statistics need to be computed across the stack.

Elements pushed on a circular stack replace the oldest (deepest) elements on the stack. QuickCheck and unit tests with HSpec give promising results — have a look yourself.

I use circular stacks, for example, as the data type for traces of Markov chains. In this case, lists cannot be used reliably, because the space requirement increases linearly with the chain length.

Circular is actively developed and functions may be removed, renamed, or changed. Ideas are welcome!


Revision history for circular

Unreleased changes

  • Tooling and compilation with GHC 9.2.3.

  • Tooling updates related to GHC 9.2.1.

  • Minor changes mostly related to tooling.
  • Nix support.

  • Do not export data constructors nor record fields.
  • fromVectorWith.

Cabal changes, versioning changes.


  • Change monadic folds so that commutativity is not anymore required.
  • Provide foldKM, a fold over the last k elements on the stack.


  • Bugfix take.
  • Make functions more consistent (fromVector and toVector now both work on mutable stacks).
  • Sort functions.
  • Improve documentation.


  • Complete rewrite using mutable vectors. A monadic interface is required now, but it is much cleaner in every other sense.


  • Remove mean.
  • Add benchmark.
  • Many small improvements.