README

Basic data structures used by WebFiori framework.

Supported PHP Versions

Build Status

Supported Collections

Linked List
Stack
Queue

Installation

You can install the library through Composer:

composer require webfiori/collections

Usage

LinkedList

The LinkedList class provides a doubly-linked list implementation with full iterator support.

<?php
use WebFiori\Collections\LinkedList;

// Create a new linked list
$list = new LinkedList();

// Add elements
$list->add("First");
$list->add("Second");
$list->add("Third");

// Access elements by index
echo $list->get(0); // "First"
echo $list->get(1); // "Second"

// Insert at specific position
$list->insert("Inserted", 1); // Insert at index 1

// Remove elements
$removed = $list->remove(0); // Remove first element
$removed = $list->removeElement("Second"); // Remove by value

// Check if element exists
if ($list->contains("Third")) {
    echo "Found Third!";
}

// Get element index
$index = $list->indexOf("Third");

// Iterate through the list
foreach ($list as $item) {
    echo $item . "\n";
}

// Convert to array
$array = $list->toArray();

// Sort the list (works with strings, numbers, and Comparable objects)
$list->insertionSort(); // Ascending
$list->insertionSort(false); // Descending

// Get list size
echo "Size: " . $list->size();

// Clear all elements
$list->clear();

LinkedList with Size Limit

// Create a list with maximum 5 elements
$limitedList = new LinkedList(5);

// This will return false if limit is reached
$success = $limitedList->add("Item");

Stack

The Stack class implements a Last-In-First-Out (LIFO) data structure.

<?php
use WebFiori\Collections\Stack;

// Create a new stack
$stack = new Stack();

// Push elements onto the stack
$stack->push("Bottom");
$stack->push("Middle");
$stack->push("Top");

// Peek at the top element without removing it
echo $stack->peek(); // "Top"

// Pop elements from the stack
$top = $stack->pop(); // "Top"
$middle = $stack->pop(); // "Middle"

// Check stack size
echo "Size: " . $stack->size();

// Convert to array
$array = $stack->toArray();

// You can also use add() method (alias for push)
$stack->add("New Top");

Stack with Size Limit

// Create a stack with maximum 10 elements
$limitedStack = new Stack(10);

// This will return false if limit is reached
$success = $limitedStack->push("Item");

Queue

The Queue class implements a First-In-First-Out (FIFO) data structure.

<?php
use WebFiori\Collections\Queue;

// Create a new queue
$queue = new Queue();

// Enqueue elements
$queue->enqueue("First");
$queue->enqueue("Second");
$queue->enqueue("Third");

// Peek at the front element without removing it
echo $queue->peek(); // "First"

// Dequeue elements
$first = $queue->dequeue(); // "First"
$second = $queue->dequeue(); // "Second"

// Check queue size
echo "Size: " . $queue->size();

// Convert to array
$array = $queue->toArray();

// You can also use add() method (alias for enqueue)
$queue->add("Fourth");

Queue with Size Limit

// Create a queue with maximum 100 elements
$limitedQueue = new Queue(100);

// This will return false if limit is reached
$success = $limitedQueue->enqueue("Item");

Advanced Usage

Custom Object Sorting

To sort custom objects in a LinkedList, implement the Comparable interface:

<?php
use WebFiori\Collections\Comparable;
use WebFiori\Collections\LinkedList;

class Person implements Comparable {
    private $name;
    private $age;
    
    public function __construct($name, $age) {
        $this->name = $name;
        $this->age = $age;
    }
    
    public function compare($other): int {
        if (!($other instanceof Person)) {
            return 1;
        }
        
        // Compare by age
        if ($this->age == $other->age) {
            return 0;
        }
        
        return $this->age > $other->age ? 1 : -1;
    }
    
    public function getName() {
        return $this->name;
    }
    
    public function getAge() {
        return $this->age;
    }
}

// Usage
$list = new LinkedList();
$list->add(new Person("Alice", 30));
$list->add(new Person("Bob", 25));
$list->add(new Person("Charlie", 35));

// Sort by age
$list->insertionSort(); // Ascending by age

Working with References

All collections work with references, allowing you to modify objects after adding them:

$data = ["key" => "value"];
$list = new LinkedList();
$list->add($data);

// Modify the original data
$data["key"] = "modified";

// The list contains the modified data
$retrieved = $list->get(0);
echo $retrieved["key"]; // "modified"

API Reference

Common Methods (All Collections)

add(&$element): bool - Add an element to the collection
size(): int - Get the number of elements
toArray(): array - Convert collection to array
count(): int - Get element count (implements Countable)

LinkedList Specific Methods

get($index): mixed - Get element at index
getFirst(): mixed - Get first element
getLast(): mixed - Get last element
remove($index): mixed - Remove element at index
removeFirst(): mixed - Remove first element
removeLast(): mixed - Remove last element
removeElement(&$element): mixed - Remove specific element
insert(&$element, $position): bool - Insert at position
indexOf($element): int - Find element index
contains(&$element): bool - Check if element exists
countElement(&$element): int - Count occurrences
replace(&$old, &$new): bool - Replace element
insertionSort($ascending = true): bool - Sort elements
clear(): void - Remove all elements
max(): int - Get maximum capacity (-1 for unlimited)

Stack Specific Methods

push($element): bool - Add element to top
pop(): mixed - Remove and return top element
peek(): mixed - View top element without removing
max(): int - Get maximum capacity (-1 for unlimited)

Queue Specific Methods

enqueue($element): bool - Add element to rear
dequeue(): mixed - Remove and return front element
peek(): mixed - View front element without removing
max(): int - Get maximum capacity (-1 for unlimited)

License

This library is licensed under the MIT License. See the LICENSE file for more details.

webfiori / collections

Maintainers

Details