ramsey/collection

While you can use TypedMap directly, it is often preferable to subclass AbstractTypedMap to create a specialized typed map implementation. This allows you to hardcode the key and value types within the class definition.

There are two ways to extend the functionality:

1. Subclassing AbstractTypedMap: Best for creating a clean, custom implementation where you define getKeyType() and getValueType() methods.
2. Subclassing TypedMap: Best for creating a specialized version of the existing TypedMap by overriding the constructor to pass specific types to the parent.

// Option 1: Subclassing AbstractTypedMap
class FooTypedMap extends AbstractTypedMap
{
    public function getKeyType()
    {
        return 'int';
    }

    public function getValueType()
    {
         return Foo::class;
    }
}

// Option 2: Subclassing TypedMap
class FooTypedMap extends TypedMap
{
    public function __construct(array $data = [])
    {
        parent::__construct('int', Foo::class, $data);
    }
}

The NamedParameterMap class is a specialized map implementation designed to hold values associated with a predefined set of named keys. It enforces two constraints:

1. Key Restriction: You can only set values for keys that were explicitly defined in the $namedParameters array during construction. Attempting to set an unconfigured key throws a Ramsey\Collection\Exception\InvalidArgumentException.
2. Type Enforcement: If a type is specified for a named parameter, the map validates that any value assigned to that key matches the required type. If validation fails, it throws a Ramsey\Collection\Exception\InvalidArgumentException.

When constructing the map, the $namedParameters array can be defined in two ways:

• Keyed by name: ['param_name' => 'type'] (e.g., ['id' => 'int']).
• Indexed list: ['param_name_1', 'param_name_2'] (where types default to mixed).

use Ramsey\Collection\Map\NamedParameterMap;

// Define parameters: 'id' must be an int, 'name' must be a string, 'meta' is mixed
$config = [
    'id' => 'int',
    'name' => 'string',
    'meta'
];

$map = new NamedParameterMap($config, ['id' => 1, 'name' => 'John Doe']);

// Valid operations
$map['id'] = 2; 
$map['meta'] = ['foo' => 'bar'];

// This will throw InvalidArgumentException (unconfigured key)
// $map['unknown'] = 'value';

// This will throw InvalidArgumentException (type mismatch)
// $map['id'] = 'not-an-int';

// Retrieve the configuration
$params = $map->getNamedParameters();

The DoubleEndedQueue class is a concrete implementation of DoubleEndedQueueInterface that allows you to add or remove elements from both the front (head) and the back (tail) of the collection. It extends the base Queue class and enforces type safety based on a provided $queueType.

Key Operations

Adding Elements

• addFirst(mixed $element): bool: Adds an element to the front. Throws InvalidArgumentException if the type is incorrect.
• addLast(mixed $element): bool: Adds an element to the back (alias for add()).
• offerFirst(mixed $element): bool: Attempts to add to the front. Returns false instead of throwing an exception if the type is incorrect.
• offerLast(mixed $element): bool: Attempts to add to the back. Returns false if the type is incorrect.

Removing Elements

• removeFirst(): mixed: Removes and returns the first element. Throws NoSuchElementException if empty.
• removeLast(): mixed: Removes and returns the last element. Throws NoSuchElementException if empty.
• pollFirst(): mixed|null: Returns the first element or null if the queue is empty.
• pollLast(): mixed|null: Returns the last element or null if the queue is empty.

Inspecting Elements

• firstElement(): mixed: Returns the first element. Throws NoSuchElementException if empty.
• lastElement(): mixed: Returns the last element. Throws NoSuchElementException if empty.
• peekFirst(): mixed|null: Returns the first element or null if empty.
• peekLast(): mixed|null: Returns the last element or null if empty.

use Ramsey\Collection\DoubleEndedQueue;

// Initialize with a type (e.g., 'string') and optional initial data
$queue = new DoubleEndedQueue('string', ['a', 'b']);

$queue->addFirst('start'); // ['start', 'a', 'b']
$queue->addLast('end');   // ['start', 'a', 'b', 'end']

$first = $queue->removeFirst(); // 'start'
$last = $queue->removeLast();    // 'end'

The Ramsey\Collection\Queue class is a basic implementation of QueueInterface that extends AbstractArray. It is designed for First-In-First-Out (FIFO) data processing. When instantiating a Queue, you must provide a $queueType (a string representing the expected type or class name) to ensure type safety for all elements added to the queue.

Key behaviors:

• Type Safety: Adding an element of the wrong type via add() or array offset assignment will throw a Ramsey\Collection\Exception\InvalidArgumentException.
• Non-throwing Offer: The offer() method attempts to add an element but returns false instead of throwing an exception if the type is incorrect.
• Empty Queue Handling: Methods like element() and remove() throw a Ramsey\Collection\Exception\NoSuchElementException if called on an empty queue, whereas peek() and poll() return null.

use Ramsey\Collection\Queue;

// Create a queue for strings
$queue = new Queue('string');

// Add elements
$queue->add('first');
$queue->offer('second');

// Peek at the first element without removing it
echo $queue->peek(); // 'first'

// Remove and return the first element
echo $queue->poll(); // 'first'

// Get the current head element (throws exception if empty)
echo $queue->element();

The Ramsey\Collection\Queue class provides the following public methods for managing queue elements: