view release on metacpan or  search on metacpan

README.md  view on Meta::CPAN

Creates a new sliding window.

- `capacity` (required): positive integer greater than zero
- `on_evict` (optional): called as `on_evict->($old_value)` on eviction

### Methods

#### `add(@items) -> $self`
Adds one or more scalars as newest elements.  
If the window is full, the oldest elements are evicted.

#### `values() -> @items`
Returns a snapshot of the window from **oldest to newest**.

#### `get($index) -> $item | undef`
Random access by logical index:

- index `0` is the **oldest**
- index `size - 1` is the **newest**

Returns `undef` if the index is invalid or out of range.

> Negative indices are intentionally not supported.

#### `clear() -> $self`
Removes all elements and clears storage slots immediately.

#### `capacity() -> INT`
Returns the fixed capacity of the window.

#### `size() -> INT`
Returns the number of elements currently stored.

#### `is_empty() -> BOOL`
True if the window contains no elements.

#### `is_full() -> BOOL`
True if the window is at full capacity.

#### `oldest() -> $item | undef`
Returns the oldest element without removing it.

#### `newest() -> $item | undef`
Returns the newest element without removing it.

## Behavior notes

- Eviction policy is deterministic: **overwrite-oldest**
- Order is preserved at all times
- Slots are cleared on eviction and `clear()` to help free references promptly
- This module does **not** attempt to emulate Perl array semantics

## Development

### Run tests
```sh
prove -l
```

or CPAN-style:
```sh
perl Makefile.PL
make test
```

## License

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