Merge pull request #7 from seboettg/improvements

Further improvements

src/Assert/Functions.php

@@ -24,21 +24,21 @@
 
 final class Functions
 {
-    public static final function assertScalar($value, string $message): void
+    final public static function assertScalar($value, string $message): void
     {
         if (!is_scalar($value)) {
             throw new TypeIsNotAScalarException($message);
         }
     }
 
-    public static final function assertType($value, string $fqcn, string $message)
+    final public static function assertType($value, string $fqcn, string $message)
     {
         if (!$value instanceof $fqcn) {
             throw new WrongTypeException($message);
         }
     }
 
-    public static final function assertStringable($value, string $message)
+    final public static function assertStringable($value, string $message)
     {
         if (!is_scalar($value)) {
             if (!self::isStrigableObject($value)) {
@@ -52,7 +52,7 @@ private static function isStrigableObject($value): bool
         return is_object($value) && method_exists($value, "__toString");
     }
 
-    public static function assertValidCallable(callable $callable, array $parameters)
+    final public static function assertValidCallable(callable $callable, array $parameters)
     {
         $reflected = new ReflectionFunction($callable);
         if (count($reflected->getParameters()) !== count($parameters)) {
@@ -97,7 +97,7 @@ private static function throwNotApplicableCallableException($paramNumber, $expec
      * @param string $message
      * @return void
      */
-    public static function assertComparable($object, string $message): void {
+    final public static function assertComparable($object, string $message): void {
         if (is_scalar($object)) {
             return;
         }

src/Common/Functions.php

@@ -21,7 +21,7 @@ final public static function strval($value): string
         if (is_double($value)) {
             $str = \strval($value);
             if (strlen($str) === 1) {
-                return sprintf("%1\$.1f",$value);
+                return sprintf("%1\$.1f", $value);
             }
             return $str;
         }
@@ -65,7 +65,7 @@ final public static function in_array($needle, $array): bool
         }
         if (isStringable($needle)) {
             foreach ($array as $item) {
-                if (strcmp((string)$needle, (string) $item) === 0) {
+                if (strcmp((string) $needle, (string) $item) === 0) {
                     return true;
                 }
             }
@@ -74,27 +74,54 @@ final public static function in_array($needle, $array): bool
     }
 }
 
-
+/**
+ * Get string value of a variable. It differs from the original function in that it is also – next to scalar values – able to handle objects.
+ * @param mixed $value
+ * @return string
+ */
 function strval($value): string
 {
     return Functions::strval($value);
 }
 
+/**
+ * Returns true when $object is a scalar value or when `isStringable` returns true for $object
+ * @param mixed $object
+ * @return bool
+ */
 function isScalarOrStringable($object): bool
 {
     return Functions::isScalarOrStringable($object);
 }
 
+/**
+ * Returns `true` when $object implements `__toString` or `$object` is a scalar value
+ * @param mixed $object
+ * @return bool
+ */
 function isStringable($object): bool
 {
     return Functions::isStringable($object);
 }
 
+/**
+ * Returns true when `$object` implements the `Comparable` interface.
+ * @param mixed $object
+ * @return bool
+ */
 function isComparable($object): bool
 {
     return Functions::isComparable($object);
 }
 
+/**
+ * Returns `true` when the given `$array` contains `$needle`. It differs from the original function in that 
+ * it is also – next to scalar values – able to handle objects by using either `compareTo` method, when `$object`
+ * is an instance of Comparable or `strcmp`, when `$object` is a string or `$object` implements the Stringable interface.
+ * @param string $needle
+ * @param array $array
+ * @return bool
+ */
 function in_array($needle, $array): bool
 {
     return Functions::in_array($needle, $array);

src/Comparable/Comparable.php

@@ -16,9 +16,6 @@
  *
  * This interface imposes a total ordering on the objects of each class that implements it. This ordering is referred
  * to as the class's natural ordering, and the class's compareTo method is referred to as its natural comparison method.
- *
- * @package Seboettg\Collection
- * @author Sebastian Böttger <[email protected]>
  */
 interface Comparable
 {

src/Lists/ArrayListTrait.php

@@ -201,15 +201,6 @@ public function joinToString(string $delimiter, string $prefix = null, string $s
         return $result;
     }
 
-    /**
-     * @inheritDoc
-     * @deprecated use joinToString instead
-     */
-    public function collectToString(string $delimiter): string
-    {
-        return $this->joinToString($delimiter);
-    }
-
     /**
      * @inheritDoc
      * @return int

src/Lists/Functions.php

@@ -1,4 +1,13 @@
 <?php
+declare(strict_types=1);
+/*
+ * Copyright (C) 2022 Sebastian Böttger <[email protected]>
+ * You may use, distribute and modify this code under the
+ * terms of the MIT license.
+ *
+ * You should have received a copy of the MIT license with
+ * this file. If not, please visit: https://opensource.org/licenses/mit-license.php
+ */
 
 namespace Seboettg\Collection\Lists;
 
@@ -32,21 +41,33 @@ public static function isList($value): bool
     }
 }
 
+/**
+ * Returns an implmentation of `ListInterface` with no entries.
+ */
 function emptyList(): ListInterface
 {
     return Functions::emptyList();
 }
 
+/**
+ * Returns an implementation of `ListInterface` containing passed elements
+ */
 function listOf(...$elements): ListInterface
 {
     return Functions::listOf(...$elements);
 }
 
+/**
+ * Returns an implementation of `ListInterface` containing all values of the passed array. The array keys are discarded.
+ */
 function listFromArray(array $elements): ListInterface
 {
     return Functions::listFromArray($elements);
 }
 
+/**
+ * Returns true when `$value` is an instance of `ListInterface`, otherwise false.
+ */
 function isList($value): bool
 {
     return Functions::isList($value);

src/Lists/ListFeatures/ListOperationsInterface.php

@@ -1,4 +1,12 @@
 <?php
+/*
+ * Copyright (C) 2016 Sebastian Böttger <[email protected]>
+ * You may use, distribute and modify this code under the
+ * terms of the MIT license.
+ *
+ * You should have received a copy of the MIT license with
+ * this file. If not, please visit: https://opensource.org/licenses/mit-license.php
+ */
 
 namespace Seboettg\Collection\Lists\ListFeatures;
 
@@ -33,4 +41,4 @@ public function plus(iterable $elements): ListInterface;
      * @return ListInterface
      */
     public function intersect(ListInterface $other): ListInterface;
-}
+}

src/Lists/ListFeatures/ListOperationsTrait.php

@@ -1,16 +1,27 @@
 <?php
+/*
+ * Copyright (C) 2022 Sebastian Böttger <[email protected]>
+ * You may use, distribute and modify this code under the
+ * terms of the MIT license.
+ *
+ * You should have received a copy of the MIT license with
+ * this file. If not, please visit: https://opensource.org/licenses/mit-license.php
+ */
 
 namespace Seboettg\Collection\Lists\ListFeatures;
 
 use Seboettg\Collection\Lists\ListInterface;
 use function Seboettg\Collection\Lists\emptyList;
 use function Seboettg\Collection\Lists\listOf;
 
+/**
+ * @property array $array
+ */
 trait ListOperationsTrait
 {
-
-
-
+    /**
+     * @inheritDoc
+     */
     public function plus(iterable $other): ListInterface
     {
         $list = listOf(...$this->array);
@@ -51,4 +62,4 @@ public function intersect(ListInterface $list): ListInterface
         }
         return $result;
     }
-}
+}

src/Lists/ListInterface.php

@@ -124,11 +124,6 @@ public function flatten(): ListInterface;
      */
     public function collect(callable $collectionFunction);
 
-    /**
-     * @deprecated use joinToString instead
-     */
-    public function collectToString(string $delimiter): string;
-
     /**
      * Tries to convert each element of the list to a string and concatenates them with given delimiter.
      * Throws a <code>NotConvertibleToStringException</code> if any of the objects in the list is not a

src/Lists/MapFeatures/MapFeaturesTrait.php

@@ -110,6 +110,9 @@ public function associateWith(callable $valueSelector): MapInterface
         return $map;
     }
 
+    /**
+     * @inheritDoc
+     */
     public function toMap(): MapInterface
     {
         $result = emptyMap();

src/Lists/ToArrayInterface.php

@@ -1,4 +1,5 @@
 <?php
+declare(strict_types=1);
 /*
  * Copyright (C) 2016 Sebastian Böttger <[email protected]>
  * You may use, distribute and modify this code under the

src/Map/Functions.php

@@ -57,6 +57,7 @@ public static function isMap($value): bool
 }
 
 /**
+ * Returns an instance of `MapInterface` containing no entries.
  * @return MapInterface
  */
 function emptyMap(): MapInterface
@@ -65,6 +66,7 @@ function emptyMap(): MapInterface
 }
 
 /**
+ * Returns an implemenation of MapInterface from the passed pairs.
  * @param array<Pair> ...$pairs
  * @return MapInterface
  */
@@ -74,6 +76,7 @@ function mapOf(...$pairs): MapInterface
 }
 
 /**
+ * Returns a Pair object from `$key` and `$value`.
  * @param scalar $key
  * @param mixed $value
  * @return Pair
@@ -83,6 +86,10 @@ function pair($key, $value): Pair
     return Functions::pair($key, $value);
 }
 
+/**
+ * Returns `true` when the passed `$value` is an instance of `MapInterface`, `false` otherwise.
+ * @return bool
+ */
 function isMap($value): bool
 {
     return Functions::isMap($value);

tests/ArrayListTest.php

@@ -427,11 +427,11 @@ public function testJoinToStringWithSuffix()
         $this->assertEquals("2#3.1#true###", $result);
     }
 
-    public function testShouldThrowExceptionWhenCollectToStringIsCalledOnListWithNotStringableObjects()
+    public function testShouldThrowExceptionWhenJoinToStringIsCalledOnListWithNotStringableObjects()
     {
         $arrayList = new ArrayList(new Element("0", "a"), new Element("1", "b"), new Element("2", "c"));
         $this->expectException(NotConvertibleToStringException::class);
-        $arrayList->collectToString("; ");
+        $arrayList->joinToString("; ");
     }
 
     public function testPartitionShouldSplitListIntoAMapOfTwoEntries()