Stack implementation class. Uses the following traits;

Implements the following interfaces;

Trait synopsis

class Stack implements Countable, IteratorAggregate, Comparable, Stringable
{
    use CoercionTrait;
    use ComparableTrait;
    use CountableTrait;
    use StackIteratorTrait;
    use StackTrait;
    use StringableTrait;
    use TypeTrait;

    /**
     * Constructor for Phrity\O\Queue.
     * @param mixed ...$args Input data.
     * @throws ArgumentCountError If too many arguments provided.
     */
    public function __construct(mixed ...$args);

    // CoercionTrait methods.

    /**
     * Internal coercion method.
     * @param mixed $value Value to coerce.
     * @return array Resulting value.
     * @throws TypeError If invalid value provided.
     */
    protected function coerce(mixed $value): array;

    // ComparableTrait methods.

    /**
     * Compare $this with provided instance of the same class.
     * @param  mixed $compare_with The instance to compare with.
     * @return int -1, 0 or +1 comparison result.
     */
    public function compare(mixed $compare_with): int;

    /**
     * If $this is equal to $compare_with.
     * @param  mixed $compare_with The instance to compare with.
     * @return boolean True if $this is equal to $compare_with.
     * @throws IncomparableException If $this can not be compared with $compare_with.
     */
    public function equals(mixed $compare_with): bool;

    /**
     * If $this is greater than $compare_with.
     * @param  mixed $compare_with The instance to compare with.
     * @return boolean True if $this is greater than $compare_with.
     * @throws IncomparableException If $this can not be compared with $compare_with.
     */
    public function greaterThan(mixed $compare_with): bool;

    /**
     * If $this is greater than or equal to $compare_with.
     * @param  mixed $compare_with The instance to compare with.
     * @return boolean True if $this is greater than or equal to $compare_with.
     * @throws IncomparableException If $this can not be compared with $compare_with.
     */
    public function greaterThanOrEqual(mixed $compare_with): bool;

    /**
     * If $this is less than $compare_with.
     * @param  mixed $compare_with The instance to compare with.
     * @return boolean True if $this is less than $compare_with.
     * @throws IncomparableException If $this can not be compared with $compare_with.
     */
    public function lessThan(mixed $compare_with): bool;

    /**
     * If $this is less than or equal to $compare_with.
     * @param  mixed $compare_with The instance to compare with.
     * @return boolean True if $this is less than or equal to $compare_with.
     * @throws IncomparableException If $this can not be compared with $compare_with.
     */
    public function lessThanOrEqual(mixed $compare_with): bool;

    // CountableTrait methods.

    /**
     * Count elements of instance.
     * @return int Number of elements.
     */
    public function count(): int;

    // StackIteratorTrait methods.

    /**
     * Consume array and yield key/value pair.
     * @return Generator The iterator function.
     */
    public function getIterator(): Generator;

    // StackTrait methods.

    /**
     * Add item to the top of stack.
     * @param mixed $item Item to add.
     */
    public function push(mixed $item): void;

    /**
     * Retrieve item from stack.
     * @return mixed $item Get and remove top item in stack.
     */
    public function pop(): mixed;

    // StringableTrait methods.

    /**
     * Return string representation.
     * @return string String representation.
     */
    public function __toString(): string;

    // TypeTrait methods.

    /**
     * Initializer, typically called in constructor.
     * @param array $value Initial value.
     */
    protected function initialize(array $value = []): void;
}

Examples

use Phrity\O\Stack;

$stack = new Stack([1, 2, 3]);
$stack->push(4);
$stack->pop();
count($stack); // Countable support
foreach ($stack as $key => $item) {
    // Consuming iterator support
}
$stack->equals(new Stack([2, 3, 4])); // Comparison support