feat: Normalize Interfaces (#15)

* add size method

* feat: Normalize Interfaces

- Refined and standardized interface definitions across the project
- Applied Single Responsibility Principle (SRP) to ensure each interface has a clear, singular purpose
- Consistent naming conventions were implemented for better readability and maintainability
- Added thorough documentation for each interface, including method descriptions and expected behaviors
- Organized interfaces within appropriate namespaces to prevent naming collisions and maintain a logical structure
- Ensured parameter names in interface methods are consistent with implementing classes
- Avoided including constructors in interfaces to maintain flexibility

These changes enhance the overall clarity, maintainability, and professional quality of the codebase.

Author: walmir-silva

src/DataStructure/Behavioral/Countable.php

@@ -23,5 +23,5 @@ interface Countable
      *
      * @return int The number of elements
      */
-    public function count(): int;
+    public function size(): int;
 }

src/DataStructure/Behavioral/Indexable.php

@@ -19,37 +19,19 @@
 interface Indexable
 {
     /**
-     * Checks if an element exists at the given index.
+     * Retrieves an element at the specified 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
+     * @param int $index The index of the element to retrieve
      *
      * @return mixed The element at the specified index
      */
     public function get(int $index): mixed;
 
     /**
-     * Sets the element at the specified index.
+     * Sets an element at the specified index.
      *
-     * @param int $index The index at which to set the element
+     * @param int $index The index where the element should be set
      * @param mixed $element The element to set
      */
     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/Behavioral/IterableCollection.php

@@ -9,7 +9,8 @@
  *
  * Provides the ability to iterate over a collection.
  *
- * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @category  Interfaces
+ *
  * @author    Walmir Silva <walmir.silva@kariricode.org>
  * @license   MIT
  *

src/DataStructure/Behavioral/Modifiable.php

@@ -0,0 +1,41 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DataStructure\Behavioral;
+
+/**
+ * Interface Modifiable.
+ *
+ * Defines the contract for modifying elements in a collection.
+ *
+ * @category  Interfaces
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Modifiable
+{
+    /**
+     * Adds an element to the collection.
+     *
+     * @param mixed $element The element to add
+     */
+    public function add(mixed $element): void;
+
+    /**
+     * Removes an element from the collection.
+     *
+     * @param mixed $element The element to remove
+     *
+     * @return bool True if the element was removed, false otherwise
+     */
+    public function remove(mixed $element): bool;
+
+    /**
+     * Clears all elements from the collection.
+     */
+    public function clear(): void;
+}

src/DataStructure/Behavioral/Searchable.php

@@ -0,0 +1,38 @@
+<?php
+
+declare(strict_types=1);
+
+namespace KaririCode\Contract\DataStructure\Behavioral;
+
+/**
+ * Interface Searchable.
+ *
+ * Defines the contract for searching elements in a collection.
+ *
+ * @category  Interfaces
+ *
+ * @author    Walmir Silva <walmir.silva@kariricode.org>
+ * @license   MIT
+ *
+ * @see       https://kariricode.org/
+ */
+interface Searchable
+{
+    /**
+     * Checks if the collection contains a specific element.
+     *
+     * @param mixed $element The element to check for
+     *
+     * @return bool True if the element is present, false otherwise
+     */
+    public function contains(mixed $element): bool;
+
+    /**
+     * Finds the index of a specific element in the collection.
+     *
+     * @param mixed $element The element to find
+     *
+     * @return int The index of the element
+     */
+    public function find(mixed $element): mixed;
+}

src/DataStructure/Map.php

@@ -4,6 +4,9 @@
 
 namespace KaririCode\Contract\DataStructure;
 
+use KaririCode\Contract\DataStructure\Behavioral\Countable;
+use KaririCode\Contract\DataStructure\Behavioral\IterableCollection;
+
 /**
  * Interface Map.
  *
@@ -16,37 +19,59 @@
  *
  * @see       https://kariricode.org/
  */
-interface Map
+interface Map extends Countable, IterableCollection
 {
     /**
-     * Puts a key-value pair into the map.
+     * Adds a key-value pair to the map.
      *
-     * @param mixed $key the key
-     * @param mixed $value the value
+     * @param mixed $key The key to add
+     * @param mixed $value The value to add
      */
     public function put(mixed $key, mixed $value): void;
 
     /**
-     * Gets a value by its key.
+     * Retrieves a value by its key.
      *
-     * @param mixed $key the key
+     * @param mixed $key The key to retrieve the value for
      *
-     * @return mixed the value associated with 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
+     * @param mixed $key The key to remove
      *
      * @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 for
+     *
+     * @return bool true if the key is present, false otherwise
+     */
+    public function containsKey(mixed $key): bool;
+
     /**
-     * Returns the number of key-value mappings in the map.
+     * Returns all keys in the map.
      *
-     * @return int the number of key-value mappings
+     * @return array The keys in the map
+     */
+    public function keys(): array;
+
+    /**
+     * Returns all values in the map.
+     *
+     * @return array The values in the map
+     */
+    public function values(): array;
+
+    /**
+     * Clears all key-value pairs from the map.
      */
-    public function size(): int;
+    public function clear(): void;
 }

src/DataStructure/Queue.php

@@ -4,6 +4,8 @@
 
 namespace KaririCode\Contract\DataStructure;
 
+use KaririCode\Contract\DataStructure\Behavioral\Modifiable;
+
 /**
  * Interface Queue.
  *
@@ -16,7 +18,7 @@
  *
  * @see       https://kariricode.org/
  */
-interface Queue
+interface Queue extends Modifiable
 {
     /**
      * Enqueues an element into the queue.

src/DataStructure/Set.php

@@ -4,6 +4,9 @@
 
 namespace KaririCode\Contract\DataStructure;
 
+use KaririCode\Contract\DataStructure\Behavioral\Modifiable;
+use KaririCode\Contract\DataStructure\Behavioral\Searchable;
+
 /**
  * Interface Set.
  *
@@ -16,51 +19,32 @@
  *
  * @see       https://kariricode.org/
  */
-interface Set
+interface Set extends Modifiable, Searchable
 {
     /**
-     * Adds an element to the set.
-     *
-     * @param mixed $element The element to add
-     *
-     * @return bool True if the element was added, false if it was already present
-     */
-    public function add(mixed $element): bool;
-
-    /**
-     * Removes an element from the set.
+     * Performs a union of this set with another set.
      *
-     * @param mixed $element The element to remove
+     * @param Set $other The other set to union with
      *
-     * @return bool True if the element was removed, false if it was not present
+     * @return Set The resulting set after the union
      */
-    public function remove(mixed $element): bool;
+    public function union(Set $other): Set;
 
     /**
-     * Checks if the set contains a specific element.
+     * Performs an intersection of this set with another set.
      *
-     * @param mixed $element The element to check for
+     * @param Set $other The other set to intersect with
      *
-     * @return bool True if the element is present, false otherwise
+     * @return Set The resulting set after the intersection
      */
-    public function contains(mixed $element): bool;
+    public function intersection(Set $other): Set;
 
     /**
-     * Removes all elements from the set.
-     */
-    public function clear(): void;
-
-    /**
-     * Returns the number of elements in the set.
+     * Performs a difference of this set with another set.
      *
-     * @return int The number of elements in the set
-     */
-    public function size(): int;
-
-    /**
-     * Checks if the set is empty.
+     * @param Set $other The other set to differentiate with
      *
-     * @return bool True if the set is empty, false otherwise
+     * @return Set The resulting set after the difference
      */
-    public function isEmpty(): bool;
+    public function difference(Set $other): Set;
 }

src/DataStructure/Structural/Collection.php

@@ -6,6 +6,8 @@
 
 use KaririCode\Contract\DataStructure\Behavioral\Countable;
 use KaririCode\Contract\DataStructure\Behavioral\Indexable;
+use KaririCode\Contract\DataStructure\Behavioral\Modifiable;
+use KaririCode\Contract\DataStructure\Behavioral\Searchable;
 
 /**
  * Interface Collection.
@@ -19,56 +21,12 @@
  *
  * @see       https://kariricode.org/
  */
-interface Collection extends Countable, Indexable
+interface Collection extends Countable, Indexable, Modifiable, Searchable
 {
-    /**
-     * Adds an element to the collection.
-     *
-     * @param mixed $element The element to add
-     */
-    public function add(mixed $element): void;
-
     /**
      * Adds all elements from another collection to this collection.
      *
      * @param Collection $collection The collection whose elements are to be added
      */
     public function addAll(Collection $collection): void;
-
-    /**
-     * Removes the first occurrence of a specific element from the collection.
-     *
-     * @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 collection contains a specific element.
-     *
-     * @param mixed $element The element to check for
-     *
-     * @return bool True if the element is present, false otherwise
-     */
-    public function contains(mixed $element): bool;
-
-    /**
-     * Removes all elements from the collection.
-     */
-    public function clear(): void;
-
-    /**
-     * Checks if the collection is empty.
-     *
-     * @return bool True if the collection is empty, false otherwise
-     */
-    public function isEmpty(): bool;
-
-    /**
-     * Returns all elements of the collection as an array.
-     *
-     * @return array The elements of the collection
-     */
-    public function getItems(): array;
 }