/ 
Hax-Alg-RollingWindow-0.910
/ Hax::Alg::RollingWindow

NAME

Hax::Alg::RollingWindow - Fixed-capacity rolling window (overwrite-oldest)

SYNOPSIS

use Hax::Alg::RollingWindow;

my $w = Hax::Alg::RollingWindow->new(
    capacity => 5,
    on_evict => sub {
        my ($old) = @_;
        warn "evicted $old\n";
    },
);

$w->add(1, 2, 3);
$w->add(4, 5, 6);   # evicts 1

my @vals = $w->values;   # (2, 3, 4, 5, 6)

my $oldest = $w->oldest; # 2
my $newest = $w->newest; # 6

my $x = $w->get(1);      # 3

$w->clear;

DESCRIPTION

Hax::Alg::RollingWindow implements a fixed-capacity rolling window using an array-backed circular buffer.

When the window reaches capacity and new elements are added, the oldest elements are automatically evicted. Eviction is normal behavior and is not considered an error.

The module is designed to:

  • Handle all Perl scalar types equally (numbers, strings, references, objects)

  • Release references immediately when elements are evicted or cleared

  • Avoid unnecessary method calls and minimize call stack depth

  • Provide predictable O(1) insertion and access behavior

CONSTRUCTOR

new

my $w = Hax::Alg::RollingWindow->new(%args);

Creates a new rolling window.

Arguments

capacity => INT (required)

The maximum number of elements the window can hold. Must be a positive integer greater than zero.

on_evict => CODEREF (optional)

A callback invoked whenever an element is evicted due to overflow.

The callback is called as:

$on_evict->($old_value);

where $old_value is the exact scalar being evicted.

Returns

A new Hax::Alg::RollingWindow object.

METHODS

add

$w->add(@items);

Adds one or more elements to the window.

Arguments

@items

One or more Perl scalars to add. Scalars may be numbers, strings, references, or objects.

Behavior

If the window is full, the oldest element is evicted for each new element added. Evicted elements:

  • Are passed to the on_evict callback (if provided)

  • Have their storage slots cleared immediately to release references

Returns

The window object itself (allowing method chaining).

values

my @values = $w->values;

Returns all elements currently stored in the window.

Returns

A list of elements in logical order from oldest to newest.

The returned values are the exact scalars stored in the window; no copying, cloning, or stringification is performed.

get

my $value = $w->get($index);

Retrieves a single element by logical index.

Arguments

$index

A non-negative integer index. Index 0 refers to the oldest element.

Returns

The stored scalar at the given index, or undef if the index is out of range or invalid.

Negative indices are not supported.

clear

$w->clear;

Removes all elements from the window.

Returns

The window object itself.

capacity

my $cap = $w->capacity;

Returns

The fixed capacity of the window as an integer.

size

my $size = $w->size;

Returns

The number of elements currently stored in the window.

is_empty

if ($w->is_empty) { ... }

Returns

True if the window contains no elements.

is_full

if ($w->is_full) { ... }

Returns

True if the window is at full capacity.

oldest

my $oldest = $w->oldest;

Returns

The oldest element in the window, or undef if the window is empty.

newest

my $newest = $w->newest;

Returns

The newest element in the window, or undef if the window is empty.

NOTES

  • Eviction is deterministic and always removes the oldest element.

  • Capacity is immutable after construction.

  • This module does not attempt to emulate Perl array semantics.

AUTHOR

Joshua Day

LICENSE

This library is free software; you may redistribute it and/or modify it under the same terms as Perl itself.