view release on metacpan or  search on metacpan

lib/Algorithm/SlidingWindow.pm  view on Meta::CPAN

sub oldest {
    my $self = $_[0];
    return undef if $self->{_size} == 0;
    return $self->{_buf}[ $self->{_head} ];
}

sub newest {
    my $self = $_[0];

    my $size = $self->{_size};
    return undef if $size == 0;

    my $cap  = $self->{_cap};
    my $head = $self->{_head};

    my $i = $head + $size - 1;
    $i -= $cap if $i >= $cap;

    return $self->{_buf}[$i];
}

1;

__END__

=head1 NAME

Algorithm::SlidingWindow - Fixed-capacity sliding window (overwrite-oldest)

=head1 SYNOPSIS

    use Algorithm::SlidingWindow;

    my $w = Algorithm::SlidingWindow->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;

=head1 DESCRIPTION

C<Algorithm::SlidingWindow> implements a fixed-capacity sliding 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:

=over 4

=item *

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

=item *

Release references immediately when elements are evicted or cleared

=item *

Avoid unnecessary method calls and minimize call stack depth

=item *

Provide predictable O(1) insertion and access behavior

=back

=head1 CONSTRUCTOR

=head2 new

    my $w = Algorithm::SlidingWindow->new(%args);

Creates a new sliding window.

=head3 Arguments

=over 4

=item capacity => INT (required)

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

=item 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 C<$old_value> is the exact scalar being evicted.

=back

=head3 Returns

A new C<Algorithm::SlidingWindow> object.

=head1 METHODS

=head2 add