*/ final class Stack implements StackInterface { /** * @var list $items */ private array $items = []; /** * Provides a default instance of the {@see Stack}. * * @return static A new instance of {@see Stack}, devoid of any items. * * @pure */ public static function default(): static { return new self(); } /** * Adds an item to the stack. * * @param T $item * * @psalm-external-mutation-free */ public function push(mixed $item): void { $this->items[] = $item; } /** * Retrieves, but does remove, the most recently added item that was not yet removed, * or returns null if this queue is empty. * * @return null|T * * @psalm-mutation-free */ public function peek(): mixed { $items = $this->items; return array_pop($items); } /** * Retrieves and removes the most recently added item that was not yet removed, * or returns null if this queue is empty. * * @return null|T * * @psalm-external-mutation-free */ public function pull(): mixed { return array_pop($this->items); } /** * Retrieve and removes the most recently added item that was not yet removed. * * @throws Exception\UnderflowException If the stack is empty. * * @return T * * @psalm-external-mutation-free */ public function pop(): mixed { if ([] === $this->items) { throw new Exception\UnderflowException('Cannot pop an item from an empty stack.'); } /** @var T */ return array_pop($this->items); } /** * Count the items in the stack. * * @return int<0, max> * * @psalm-mutation-free */ public function count(): int { return count($this->items); } }