normalize the semantic syntax of methods and interface names

Author: walmir-silva

src/DataStructure/Behavioral/Comparable.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Behavioral;
+
+/**
+ * Interface Comparable.
+ *
+ * Defines the contract for objects that can be compared.
+ *
+ * @package   KaririCode\Contract\Behavioral
+ * @category  Interfaces
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ * @see       https://kariricode.org/
+ */
+interface Comparable
+{
+    /**
+     * Compares this object with the specified object for order.
+     *
+     * @param mixed $other The object to compare with
+     * @return int A negative integer, zero, or a positive integer as this object
+     *             is less than, equal to, or greater than the specified object.
+     */
+    public function compareTo(mixed $other): int;
+}

src/DataStructure/Behavioral/Countable.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Behavioral;
+
+/**
+ * Interface Countable.
+ *
+ * Defines the contract for counting elements.
+ *
+ * @package   KaririCode\Contract\Behavioral
+ * @category  Interfaces
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ * @see       https://kariricode.org/
+ */
+interface Countable
+{
+    /**
+     * Counts the elements.
+     *
+     * @return int The number of elements
+     */
+    public function count(): int;
+}

src/DataStructure/Behavioral/Indexable.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Behavioral;
+
+/**
+ * Interface Indexable.
+ *
+ * Defines the contract for indexed access to elements.
+ *
+ * @package   KaririCode\Contract\Behavioral
+ * @category  Interfaces
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ * @see       https://kariricode.org/
+ */
+interface Indexable
+{
+    /**
+     * Checks if an element exists at the given index.
+     *
+     * @param int $index The index to check
+     * @return bool True if the index exists, false otherwise
+     */
+    public function contains(int $index): bool;
+
+    /**
+     * Gets the element at the specified index.
+     *
+     * @param int $index The index of the element
+     * @return mixed The element at the specified index
+     */
+    public function get(int $index): mixed;
+
+    /**
+     * Sets the element at the specified index.
+     *
+     * @param int $index The index at which to set the element
+     * @param mixed $element The element to set
+     * @return void
+     */
+    public function set(int $index, mixed $element): void;
+
+    /**
+     * Removes the element at the specified index.
+     *
+     * @param int $index The index of the element to remove
+     * @return bool True if the element was removed, false otherwise
+     */
+    public function remove(int $index): bool;
+}

src/DataStructure/IterableCollection.php renamed to src/DataStructure/Behavioral/IterableCollection.php

@@ -4,22 +4,25 @@
 
 namespace KaririCode\Contract\DataStructure;
 
+use KaririCode\Contract\Behavioral\Iterator;
+
 /**
  * Interface IterableCollection.
  *
  * Provides the ability to iterate over a collection.
  *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
  *
  * @see      https://kariricode.org/
  */
-interface IterableCollection extends \IteratorAggregate
+interface IterableCollection extends \Traversable
 {
     /**
      * Gets an iterator for the collection.
      *
-     * @return \Traversable an iterator for the collection
+     * @return Iterator an iterator for the collection
      */
-    public function getIterator(): \Traversable;
+    public function getIterator(): Iterator;
 }

src/DataStructure/Behavioral/Iterator.php

@@ -0,0 +1,33 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Behavioral;
+
+/**
+ * Interface Iterator.
+ *
+ * Defines the contract for iterating over a collection of elements.
+ *
+ * @package   KaririCode\Contract\Behavioral
+ * @category  Interfaces
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ * @see       https://kariricode.org/
+ */
+interface Iterator
+{
+    /**
+     * Returns the next element in the iteration.
+     *
+     * @return mixed The next element
+     */
+    public function next(): mixed;
+
+    /**
+     * Checks if the iteration has more elements.
+     *
+     * @return bool True if the iteration has more elements, false otherwise
+     */
+    public function hasNext(): bool;
+}

src/DataStructure/Behavioral/Sortable.php

@@ -0,0 +1,28 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\Behavioral;
+
+/**
+ * Interface Sortable.
+ *
+ * Defines the contract for classes that can be sorted.
+ * Classes implementing this interface should provide an implementation
+ * for the sort method to allow sorting of their elements.
+ *
+ * @package   KaririCode\Contract\Behavioral
+ * @category  Interfaces
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ * @see       https://kariricode.org/
+ */
+interface Sortable
+{
+    /**
+     * Sorts the elements of the class.
+     *
+     * @return void
+     */
+    public function sort(): void;
+}

src/DataStructure/CollectionList.php

@@ -7,40 +7,54 @@
 /**
  * Interface Heap.
  *
- * Defines the contract for a heap data structure.
+ * Defines the contract for heap data structures.
+ * A heap is a specialized tree-based data structure that satisfies the heap property.
  *
+ *
+ * @package   KaririCode\Contract\DataStructure
+ * @category  Interfaces
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
- *
- * @see      https://kariricode.org/
+ * @see       https://kariricode.org/
  */
-interface Heap extends \Countable
+interface Heap
 {
     /**
-     * Inserts a value into the heap.
+     * Adds an element to the heap.
      *
-     * @param mixed $value the value to insert
+     * @param mixed $element The element to add.
+     * @return void
      */
-    public function insert(mixed $value): void;
+    public function add(mixed $element): void;
 
     /**
-     * Extracts the top value from the heap.
+     * Inserts an element into the heap at the specified position.
      *
-     * @return mixed the extracted value
+     * @param int $index The index at which to insert the element.
+     * @param mixed $element The element to insert.
+     * @return void
      */
-    public function extract(): mixed;
+    public function insert(int $index, mixed $element): void;
 
     /**
-     * Peeks at the top value of the heap without extracting it.
+     * Removes and returns the root element from the heap.
      *
-     * @return mixed the top value
+     * @return mixed The removed root element.
      */
-    public function peek(): mixed;
+    public function poll(): mixed;
+
+    /**
+     * Removes a specific element from the heap.
+     *
+     * @param mixed $element The element to remove.
+     * @return bool True if the element was removed, false otherwise.
+     */
+    public function remove(mixed $element): bool;
 
     /**
-     * Checks if the heap is empty.
+     * Returns the root element without removing it.
      *
-     * @return bool true if the heap is empty, false otherwise
+     * @return mixed The root element.
      */
-    public function isEmpty(): bool;
+    public function peek(): mixed;
 }

src/DataStructure/Heap.php

@@ -7,61 +7,38 @@
 /**
  * Interface Map.
  *
- * Defines the contract for a map data structure.
+ * Defines the contract for map data structures, which store key-value pairs.
  *
+ * @package   KaririCode\Contract\DataStructure
+ * @category  Interfaces
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
- *
- * @see      https://kariricode.org/
+ * @see       https://kariricode.org/
  */
-interface Map extends \Countable, \ArrayAccess
+interface Map
 {
     /**
      * Puts a key-value pair into the map.
      *
-     * @param mixed $key the key
-     * @param mixed $value the value
+     * @param mixed $key The key.
+     * @param mixed $value The value.
+     * @return void
      */
     public function put(mixed $key, mixed $value): void;
 
     /**
      * Gets a value by its key.
      *
-     * @param mixed $key the key
-     *
-     * @return mixed the value associated with the key
+     * @param mixed $key The key.
+     * @return mixed The value associated with the key.
      */
     public function get(mixed $key): mixed;
 
     /**
      * Removes a key-value pair from the map.
      *
-     * @param mixed $key the key to remove
-     *
-     * @return bool true if the pair was successfully removed, false otherwise
+     * @param mixed $key The key.
+     * @return bool True if the key-value pair was removed, false otherwise.
      */
     public function remove(mixed $key): bool;
-
-    /**
-     * Checks if the map contains a specific key.
-     *
-     * @param mixed $key the key to check
-     *
-     * @return bool true if the key exists, false otherwise
-     */
-    public function containsKey(mixed $key): bool;
-
-    /**
-     * Gets all keys in the map.
-     *
-     * @return array an array of all keys
-     */
-    public function keys(): array;
-
-    /**
-     * Gets all values in the map.
-     *
-     * @return array an array of all values
-     */
-    public function values(): array;
 }