From 341cd1813d3192bc3b91b02544cf90ab4caf6339 Mon Sep 17 00:00:00 2001 From: Rotimi Ade Date: Sat, 1 Feb 2020 22:59:28 -0700 Subject: [PATCH] Rector tweaks --- src/ArraysCollection.php | 4 +- src/CallablesCollection.php | 4 +- src/CollectionInterface.php | 1962 ++++++++--------- ...CollectionInterfaceImplementationTrait.php | 454 ++-- src/FloatsCollection.php | 4 +- src/IntsCollection.php | 4 +- src/NumericsCollection.php | 98 +- src/ObjectsCollection.php | 20 +- src/ResourcesCollection.php | 6 +- src/ScalarsCollection.php | 26 +- src/SpecificObjectsCollection.php | 26 +- src/StrictlyTypedCollectionInterface.php | 12 +- ...CollectionInterfaceImplementationTrait.php | 26 +- src/StringsCollection.php | 4 +- src/helper-functions.php | 56 +- 15 files changed, 1354 insertions(+), 1352 deletions(-) diff --git a/src/ArraysCollection.php b/src/ArraysCollection.php index d658d53..a9b7d7b 100644 --- a/src/ArraysCollection.php +++ b/src/ArraysCollection.php @@ -4,10 +4,10 @@ /** * Description of ArraysCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime diff --git a/src/CallablesCollection.php b/src/CallablesCollection.php index 73efc6c..597a9dc 100644 --- a/src/CallablesCollection.php +++ b/src/CallablesCollection.php @@ -4,10 +4,10 @@ /** * Description of CallablesCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime diff --git a/src/CollectionInterface.php b/src/CollectionInterface.php index 059bfdf..75cf96f 100644 --- a/src/CollectionInterface.php +++ b/src/CollectionInterface.php @@ -6,7 +6,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this interface: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -22,1553 +22,1553 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author rotimi */ interface CollectionInterface extends \ArrayAccess, \Countable, \IteratorAggregate { /** - * + * * A factory method to help create a new collection. - * + * * The purpose is to act as a shortcut to __construct(...$items) * Calling this method eliminates the need to unpack the items .e.g * new \VersatileCollections\NumericsCollection(...[1,2,3]) * vs \VersatileCollections\NumericsCollection::makeNew([1,2,3]) - * + * * @param array $items an array of items for the new collection to be created. * @param bool $preserve_keys true if keys in $items will be preserved in the created collection. - * + * * @return \VersatileCollections\CollectionInterface newly created collection - * + * * @used-for: creating-new-collections - * + * * @title: Creates a new collection from an array of items. Items must be rightly typed if collection class is strictly typed. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public static function makeNew(array $items=[], bool $preserve_keys=true): \VersatileCollections\CollectionInterface; /** - * + * * Get a key's value. - * + * * https://www.php.net/manual/en/language.oop5.overloading.php#object.get * NOTE: __get() is never called when chaining assignments together like this: $a = $obj->b = 8; - * + * * @param string $key The requested key. - * + * * @return mixed - * + * * @used-for: accessing-or-extracting-keys-or-items - * + * * @title: Retrieves an item associated with a specified key in the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function __get(string $key); /** - * + * * Does the requested key exist? - * + * * @param string $key The requested key. - * + * * @return bool - * + * * @used-for: checking-items-presence - * + * * @title: Checks if an item with a specified key exists in the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function __isset(string $key): bool; /** - * + * * Set a key's value. - * + * * @param string $key The requested key. - * + * * @param mixed $val The value to set it to. - * + * * @return void - * + * * @used-for: adding-items - * + * * @title: Adds an item with a specified key to the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function __set(string $key, $val): void; /** - * + * * Unset a key. - * + * * @param string $key The requested key. - * + * * @return void - * + * * @used-for: deleting-items - * + * * @title: Removes an item associated with the specified key from the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function __unset(string $key): void; /** - * + * * ArrayAccess: does the requested key exist? - * + * * @param mixed $key The requested key. - * + * * @return bool - * + * * @used-for: checking-items-presence - * + * * @title: Checks if an item with a specified key exists in the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function offsetExists($key): bool; /** - * + * * ArrayAccess: get a key's value. - * + * * @param mixed $key The requested key. - * + * * @return mixed - * + * * @used-for: accessing-or-extracting-keys-or-items - * + * * @title: Retrieves an item associated with a specified key in the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function offsetGet($key); /** - * + * * ArrayAccess: set a key's value. - * + * * @param mixed $key The requested key. - * + * * @param mixed $val The value to set it to. - * + * * @return void - * + * * @used-for: adding-items - * + * * @title: Adds an item with a specified key to the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function offsetSet($key, $val): void; /** - * + * * ArrayAccess: unset a key. - * + * * @param mixed $key The requested key. - * + * * @return void - * + * * @used-for: deleting-items - * + * * @title: Removes an item associated with the specified key from the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function offsetUnset($key): void; /** - * + * * @return array an array containing all items in the collection object - * + * * @used-for: accessing-or-extracting-keys-or-items - * + * * @title: Returns all items in the collection and their corresponding keys in an array. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function toArray(): array; /** - * + * * @return \Iterator an iterator - * + * * @used-for: iteration - * + * * @title: Returns an Iterator object that can be used to iterate through the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getIterator(): \Iterator; /** - * + * * @return int number of items in collection - * + * * @used-for: getting-collection-meta-data - * + * * @title: Returns the number of items in the collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function count(): int; //////////////////////////////////////////////////////////////////////////// ////////// OTHER COLLECTION METHODS //////////////////////////////////////// /** - * + * * Retrieves and returns the first item in this collection. - * + * * @return mixed The first item in this collection or null if collection is empty. - * + * * @used-for: accessing-or-extracting-keys-or-items - * + * * @title: Returns the first item in the collection or null if the collection is empty. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function firstItem(); /** - * + * * Retrieves and returns the last item in this collection. - * + * * @return mixed The last item in this collection or null if collection is empty. - * + * * @used-for: accessing-or-extracting-keys-or-items - * + * * @title: Returns the last item in the collection or null if the collection is empty. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function lastItem(); /** - * + * * @return \VersatileCollections\GenericCollection keys to this collection - * + * * @used-for: accessing-or-extracting-keys-or-items, getting-collection-meta-data, creating-new-collections - * + * * @title: Returns a new instance of **`\VersatileCollections\GenericCollection`** containing all the keys in the original collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getKeys(): \VersatileCollections\GenericCollection; /** - * + * * This method works only on collections of arrays and / or objects. * It set's the specified field in each array or property in each object * to the given value. - * + * * @param string $field_name * @param mixed $field_val * @param bool $add_field_if_not_present - * + * * @return $this - * + * * @used-for: modifying-items - * + * * @title: Sets the specified field in each array or object in the collection to a specified value. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function setValForEachItem(string $field_name, $field_val, bool $add_field_if_not_present=false): \VersatileCollections\CollectionInterface; /** - * + * * Filter out items in the collection via a callback function and return filtered items in a new collection. - * - * @param callable $filterer a callback with the following signature + * + * @param callable $filterer a callback with the following signature * function($key, $item) that must return true if an item should be filtered out, or false if not - * + * * @param bool $copy_keys true if key for each filtered item in $this should be copied into the collection to be returned - * + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $filterer should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $filterer. - * - * @param bool $remove_filtered_items true if the filtered items should be removed from - * the collection this method is being invoked on, - * else false if the filtered items should not be - * removed from the collection this method is + * + * @param bool $remove_filtered_items true if the filtered items should be removed from + * the collection this method is being invoked on, + * else false if the filtered items should not be + * removed from the collection this method is * being invoked on. - * + * * @return \VersatileCollections\CollectionInterface a collection of filtered items or an empty collection - * + * * @used-for: finding-or-searching-for-items, creating-new-collections - * + * * @title: Filters out items in the collection via a callback function and returns filtered items in a new collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function filterAll(callable $filterer, bool $copy_keys=false, bool $bind_callback_to_this=true, bool $remove_filtered_items=false): \VersatileCollections\CollectionInterface; /** - * + * * Filter out the first N items in the collection via a callback function and return filtered items in a new collection. - * - * @param callable $filterer a callback with the following signature + * + * @param callable $filterer a callback with the following signature * function($key, $item) that must return true if an item should be filtered out, or false if not - * + * * @param int $max_number_of_filtered_items_to_return Number of filtered items to be returned. Null means return all filtered items - * + * * @param bool $copy_keys true if key for each filtered item in $this should be copied into the collection to be returned - * + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $filterer should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $filterer. - * - * @param bool $remove_filtered_items true if the filtered items should be removed from - * the collection this method is being invoked on, - * else false if the filtered items should not be - * removed from the collection this method is + * + * @param bool $remove_filtered_items true if the filtered items should be removed from + * the collection this method is being invoked on, + * else false if the filtered items should not be + * removed from the collection this method is * being invoked on. - * + * * @return \VersatileCollections\CollectionInterface a collection of filtered items or an empty collection - * + * * @used-for: finding-or-searching-for-items, creating-new-collections - * + * * @title: Filters out the first N items in the collection via a callback function and returns filtered items in a new collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function filterFirstN(callable $filterer, ?int $max_number_of_filtered_items_to_return=null, bool $copy_keys=false, bool $bind_callback_to_this=true, bool $remove_filtered_items=false): \VersatileCollections\CollectionInterface; /** - * + * * Transform each item in the collection via a callback function. - * - * @param callable $transformer a callback with the following signature + * + * @param callable $transformer a callback with the following signature * function($key, $item):mixed that returns a value that will replace $this[$key] - * + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $transformer should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $transformer. - * + * * @return $this - * + * * @used-for: modifying-items, iteration - * + * * @title: Transforms each item in the collection via a callback function. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function transform(callable $transformer, bool $bind_callback_to_this=true): \VersatileCollections\CollectionInterface; /** - * + * * Iteratively reduce the collection items to a single value using a callback function. - * + * * @see http://php.net/manual/en/function.array-reduce.php array_reduce - * + * * @param callable $reducer function(mixed $carry , mixed $item): mixed * $carry: Holds the return value of the previous iteration; in the case of the first iteration it instead holds the value of initial. * $item: Holds the value of the current iteration. - * + * * @param mixed $initial_value If the optional initial is available, it will be used at the beginning of the process, or as a final result in case the collection is empty. - * + * * @return mixed a value that all items in the collection have been reduced to by applying the $reducer callback on each item. - * + * * @used-for: accessing-or-extracting-keys-or-items, iteration - * + * * @title: Iteratively reduces the collection items to a single value using a callback function. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function reduce(callable $reducer, $initial_value=NULL); /** - * + * * Iteratively reduce the collection items to a single value using a callback function. * The callback function will have access to the key for each item. - * + * * @param callable $reducer function(mixed $carry , mixed $item, string|int $key): mixed * $carry: Holds the return value of the previous iteration; in the case of the first iteration it instead holds the value of initial. * $item: Holds the value of the current iteration. * $key: Holds the corresponding key of the current iteration. - * + * * @param mixed $initial_value If the optional initial is available, it will be used at the beginning of the process, or as a final result in case the collection is empty. - * + * * @return mixed a value that all items in the collection have been reduced to by applying the $reducer callback on each item. - * + * * @used-for: accessing-or-extracting-keys-or-items, iteration - * + * * @title: Iteratively reduces the collection items to a single value using a callback function. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function reduceWithKeyAccess(callable $reducer, $initial_value=NULL); /** - * + * * Reverse order of items in the collection and return the reversed items in a new collection. - * + * * @return \VersatileCollections\CollectionInterface a collection of reversed items - * + * * @used-for: ordering-or-sorting-items, creating-new-collections - * + * * @title: Reverses the order of items in the collection and returns the reversed items in a new collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function reverse(): \VersatileCollections\CollectionInterface; /** - * + * * Reverse order of items in the collection. Original collection will be modified. - * + * * @return $this - * + * * @used-for: ordering-or-sorting-items - * + * * @title: Reverses the order of items in the collection. Original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function reverseMe(): \VersatileCollections\CollectionInterface; /** - * + * * Return true if there are one or more items in the collection or false otherwise - * + * * @return bool - * + * * @used-for: getting-collection-meta-data - * + * * @title: Returns true if there are one or more items in the collection or false otherwise. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function isEmpty(): bool; /** - * + * * Try to get an item with the specified key ($key) or return $default_value if key does not exist. - * + * * @param string|int $key * @param mixed $default_value - * + * * @return mixed - * + * * @used-for: accessing-or-extracting-keys-or-items, checking-items-presence - * + * * @title: Returns the item in the collection with the specified key (if such an item exists) or the specified default value otherwise. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getIfExists($key, $default_value=null); /** - * + * * Check if a collection contains an item using strict comparison. - * + * * @param mixed $item item whose existence in the collection is to be checked - * + * * @return bool true if collection contains item, false otherwise - * + * * @used-for: checking-items-presence - * + * * @title: Checks if a collection contains a specified item (using strict comparison). - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function containsItem($item): bool; /** - * + * * Check if a collection contains an item with the specified key using strict comparison for the item. * Strict comparison is used for checking each item. - * + * * @param string|int $key key whose existence in the collection is to be checked * @param mixed $item item whose existence in the collection is to be checked - * + * * @return bool true if collection contains item with the specified key, false otherwise - * + * * @used-for: checking-items-presence, checking-keys-presence - * + * * @title: Checks if a collection contains a specified item (using strict comparison) together with the specified key. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function containsItemWithKey($key, $item): bool; /** - * + * * Check if all the specified items exist in a collection. * Strict comparison is used for checking each item. - * + * * @param array $items specified items whose existence is to be checked in the collection - * + * * @return bool true if all specified items exist in collection, false otherwise - * + * * @used-for: checking-items-presence - * + * * @title: Checks if a collection contains all specified items (using strict comparison for each comparison). - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function containsItems(array $items): bool; /** - * + * * Check if a key exists in a collection - * + * * @param mixed $key key whose existence in the collection is to be checked - * + * * @return bool true if key exists in collection, false otherwise - * + * * @used-for: checking-keys-presence - * + * * @title: Checks if a collection contains a specified key. - * - * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector * + * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector + * */ public function containsKey($key): bool; /** - * + * * Check if all the specified keys exist in a collection - * + * * @param array $keys specified keys whose existence is to be checked in the collection - * + * * @return bool true if all specified keys exist in collection, false otherwise - * + * * @used-for: checking-keys-presence - * + * * @title: Checks if a collection contains all specified keys. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function containsKeys(array $keys): bool; /** - * + * * Appends all items from $other collection to the end of $this collection. * Note that appended items will be assigned numeric keys. - * + * * @param \VersatileCollections\CollectionInterface $other - * + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Appends all items from a specified collection to the end of a collection. Note that appended items will be assigned numeric keys. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function appendCollection(CollectionInterface $other): \VersatileCollections\CollectionInterface; /** - * + * * Appends an $item to the end of $this collection. - * + * * @param mixed $item - * + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Appends a specified item to the end of a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function appendItem($item): \VersatileCollections\CollectionInterface; /** - * + * * Prepends all items from $other collection to the front of $this collection. * Note that all numeric keys will be modified to start counting from zero while literal keys won't be changed. - * + * * @param \VersatileCollections\CollectionInterface $other - * + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Prepends all items from a specified collection to the front of a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function prependCollection(CollectionInterface $other): \VersatileCollections\CollectionInterface; /** - * + * * Prepends an $item to the front of $this collection. - * + * * @param mixed $item * @param string|int $key - * + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Prepends a specified item (with a specified key, if specified) to the front of a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function prependItem($item, $key=null): \VersatileCollections\CollectionInterface; /** - * + * * Adds all items from $items to $this collection and returns a new collection * containing the result. The original collection will not be modified. * Items in $items with existing keys in $this will overwrite the existing items in $this. - * + * * Use unionWith() and unionMeWith() if you want items from $this to be used * when same keys exist in both $items and $this. - * + * * @see \VersatileCollections\CollectionInterface::unionWith() * @see \VersatileCollections\CollectionInterface::unionMeWith() - * + * * @param array $items - * - * @return \VersatileCollections\CollectionInterface a new collection containing - * the result of merging all + * + * @return \VersatileCollections\CollectionInterface a new collection containing + * the result of merging all * items from $items with * $this collection - * + * * @used-for: adding-items, creating-new-collections - * + * * @title: Adds all specified items to a collection and returns a new collection containing the result. The original collection is not modified. New items with the same keys as existing items will overwrite the existing items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function mergeWith(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Adds all items from $items to $this collection. * Items in $items with existing keys in $this will overwrite the existing items in $this. - * + * * Use unionWith() and unionMeWith() if you want items from $this to be used * when same keys exist in both $items and $this. - * + * * @see \VersatileCollections\CollectionInterface::unionWith() * @see \VersatileCollections\CollectionInterface::unionMeWith() - * + * * @param array $items - * + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Adds all specified items to a collection. The original collection is modified. New items with the same keys as existing items will overwrite the existing items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function mergeMeWith(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Returns a generator that yields collections each having a maximum of $num_of_items. Original keys are preserved in each returned collection. - * + * * If $this contains [1,2,3,4,5,6] - * + * * foreach( $this->yieldCollectionsOfSizeN(2) as $batch ) { - * + * * var_dump($batch); * } - * + * * will output - * + * * [0=>1,1=>2] * [2=>3,3=>4] * [4=>5,5=>6] - * + * * @param int $max_size_of_each_collection - * + * * @return \Generator a generator that yields sub-collections - * + * * @used-for: creating-new-collections - * + * * @title: Returns a generator that yields collections each having a specified maximum number of items. Original keys are preserved in each returned collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function yieldCollectionsOfSizeN(int $max_size_of_each_collection=1): \Generator; /** - * + * * Returns a collection of collections each having a maximum of $num_of_items. Original keys are preserved in each sub-collection. - * + * * If $this contains [1,2,3,4,5,6] - * + * * foreach( $this->getCollectionsOfSizeN(2) as $batch ) { - * + * * var_dump($batch); * } - * + * * will output - * + * * [0=>1,1=>2] * [2=>3,3=>4] * [4=>5,5=>6] - * + * * @param int $max_size_of_each_collection - * + * * @return \VersatileCollections\CollectionInterface a collection of sub-collections - * + * * @used-for: creating-new-collections - * + * * @title: Returns a collection of collections; with each sub-collection having a specified maximum number of items. Original keys are preserved in each sub-collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getCollectionsOfSizeN(int $max_size_of_each_collection=1): \VersatileCollections\CollectionInterface; /** - * + * * Convert all keys in the collection to consecutive integer keys starting from $starting_key - * - * @param int $starting_key a positive integer value that will be the value of the first key. + * + * @param int $starting_key a positive integer value that will be the value of the first key. * A negative integer value should be forced to zero. - * + * * @return $this - * + * * @used-for: modifying-keys - * + * * @title: Converts all keys in a collection to consecutive integer keys starting from the specified integer value. - * + * * @throws \InvalidArgumentException if $starting_key is not an integer - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function makeAllKeysNumeric(int $starting_key=0): \VersatileCollections\CollectionInterface; /** - * + * * Create a new collection with all the items in the original collection. * All the keys in the new collection will be consecutive integer keys * starting from zero. * * @return \VersatileCollections\CollectionInterface new collection with all the items in the original collection - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, modifying-keys - * + * * @title: Returns a new collection with all items in the original collection. All the keys in the new collection will be consecutive integer keys starting from zero. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getItems(): \VersatileCollections\CollectionInterface; /** - * + * * Iterate through a collection and execute a callback over each item during the iteration. - * - * @param callable $callback a callback with the following signature - * function($key, $item). To stop iteration at any - * point, the callback should return the value - * specified via $termination_value. For example, - * if you wanted to loop through the first half of - * a collection you should return false in the + * + * @param callable $callback a callback with the following signature + * function($key, $item). To stop iteration at any + * point, the callback should return the value + * specified via $termination_value. For example, + * if you wanted to loop through the first half of + * a collection you should return false in the * callback when you reach the ($this->count()/2)th item. - * - * @param mixed $termination_value a value that should be returned by $callback - * signifying that iteration through a collection + * + * @param mixed $termination_value a value that should be returned by $callback + * signifying that iteration through a collection * should stop. - * + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $callback should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $callback. - * + * * @return $this - * + * * @used-for: accessing-or-extracting-keys-or-items, iteration - * + * * @title: Iterates through a collection and executes a callback over each item. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function each(callable $callback, $termination_value=false, bool $bind_callback_to_this=true): \VersatileCollections\CollectionInterface; /** - * + * * Applies the callback to the items in the collection and returns a new * collection containing all the items in the original collection after * applying the callback function to each one. The original collection * is not modified. - * - * - * - * @param callable $callback a callback with the following signature - * function($key, $item): mixed. It should perform an - * operation on each item and return the result + * + * + * + * @param callable $callback a callback with the following signature + * function($key, $item): mixed. It should perform an + * operation on each item and return the result * of the operation on each item. - * - * @param bool $preserve_keys true if keys in the returned collection should - * match the keys in the original collection, else + * + * @param bool $preserve_keys true if keys in the returned collection should + * match the keys in the original collection, else * false for sequentially incrementing integer keys * (starting from 0) in the returned collection. - * + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $callback should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $callback. - * + * * @return \VersatileCollections\CollectionInterface - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, iteration - * + * * @title: Applies a callback to the items in a collection and returns a new collection containing all items in the original collection after applying the callback function to each one. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function map(callable $callback, bool $preserve_keys=true, bool $bind_callback_to_this=true): \VersatileCollections\CollectionInterface; /** - * + * * Create a new collection consisting of every n-th element. * - * @param int $n the number representing n - * @param int $position_of_first_nth_item position in the collection to + * @param int $n the number representing n + * @param int $position_of_first_nth_item position in the collection to * start counting for the nth elements. * 0 represents the position of * the first item in the collection. - * + * * @return \VersatileCollections\CollectionInterface (a new collection consisting of every n-th element) - * + * * @used-for: creating-new-collections - * + * * @title: Creates a new collection consisting of every n-th element in a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function everyNth(int $n, int $position_of_first_nth_item = 0): \VersatileCollections\CollectionInterface; /** - * + * * Pass the collection to the given callback and return whatever value is * returned from executing the given callback. * - * @param callable $callback a callback with the following signature - * function($collection):mixed. The $collection - * argument in the callback's signature is - * collection object this - * pipeAndReturnCallbackResult + * @param callable $callback a callback with the following signature + * function($collection):mixed. The $collection + * argument in the callback's signature is + * collection object this + * pipeAndReturnCallbackResult * method is being invoked on. - * + * * @return mixed whatever is returned by $callback - * + * * @used-for: other-operations - * + * * @title: Executes the given callback on a collection and returns whatever value the callback returned. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function pipeAndReturnCallbackResult(callable $callback); /** - * + * * Pass the collection to the given callback and return the collection. * - * @param callable $callback a callback with the following signature - * function($collection). The $collection - * argument in the callback's signature is - * collection object this pipeAndReturnSelf + * @param callable $callback a callback with the following signature + * function($collection). The $collection + * argument in the callback's signature is + * collection object this pipeAndReturnSelf * method is being invoked on. - * + * * @return $this - * + * * @used-for: other-operations - * + * * @title: Executes the given callback on a collection and returns the collection itself. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function pipeAndReturnSelf(callable $callback): \VersatileCollections\CollectionInterface; /** - * + * * Get and remove the last item from the collection. * * @return mixed - * + * * @used-for: accessing-or-extracting-keys-or-items, deleting-items - * + * * @title: Removes and returns the last item from a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getAndRemoveLastItem(); /** - * + * * Get and remove an item from the collection. * * @param mixed $key * @param mixed $default * @return mixed - * + * * @used-for: accessing-or-extracting-keys-or-items, deleting-items - * + * * @title: Removes and returns the item with the specified key from a collection (if it exists) or returns a default value. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function pull($key, $default = null); /** - * + * * Alias of appendItem($item) * - * @param mixed $item + * @param mixed $item * @return $this - * + * * @used-for: adding-items - * + * * @title: Appends a specified item to the end of a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function push($item): \VersatileCollections\CollectionInterface; /** - * + * * Put an item in the collection by key. * - * @param mixed $key - * @param mixed $value - * + * @param mixed $key + * @param mixed $value + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Adds a specified key and item pair to a collection. If the specified key already exists, the specified item will overwrite the existing item. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function put($key, $value): \VersatileCollections\CollectionInterface; /** - * + * * Get one key randomly from the collection. * A length exception (\LengthException) should be thrown if this method is called on an empty collection. - * + * * @return mixed a random key from the collection if there is at least an item in the collection - * + * * @throws \LengthException - * + * * @used-for: accessing-or-extracting-keys-or-items, ordering-or-sorting-items - * + * * @title: Gets one key randomly from a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function randomKey(); /** - * + * * Get one item randomly from the collection. * A length exception (\LengthException) should be thrown if this method is called on an empty collection. - * + * * @return mixed a random item from the collection if there is at least an item in the collection - * + * * @used-for: accessing-or-extracting-keys-or-items, ordering-or-sorting-items - * + * * @title: Gets one item randomly from a collection. - * + * * @throws \LengthException - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function randomItem(); /** - * + * * Get a specified number of unique keys randomly from the collection and return them in a new collection. - * + * * A \LengthException should be thrown if this method is called on an empty collection. * An \InvalidArgumentException should be thrown if $number is either not an int or if it is bigger than the number of items in the collection. * * @param int $number number of random keys to be returned - * + * * @return \VersatileCollections\GenericCollection (a new collection containing the random keys) - * + * * @used-for: accessing-or-extracting-keys-or-items, ordering-or-sorting-items * * @title: Gets a specified number of unique keys randomly from a collection and returns them in a new collection. - * + * * @throws \InvalidArgumentException * @throws \LengthException - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function randomKeys(int $number = 1): \VersatileCollections\CollectionInterface; /** - * + * * Get a specified number of items randomly from the collection and return them in a new collection. - * + * * A \LengthException should be thrown if this method is called on an empty collection. * An \InvalidArgumentException should be thrown if $number is either not an int or if it is bigger than the number of items in the collection. * * @param int $number number of random items to be returned - * @param bool $preserve_keys true if the key associated with each random item should be used in the new collection returned by this method, + * @param bool $preserve_keys true if the key associated with each random item should be used in the new collection returned by this method, * otherwise false if the new collection returned should have sequential integer keys starting at zero. - * + * * @return \VersatileCollections\CollectionInterface (a new collection containing the random items) - * + * * @used-for: accessing-or-extracting-keys-or-items, ordering-or-sorting-items * * @title: Gets a specified number of items randomly from a collection and returns them in a new collection. - * + * * @throws \InvalidArgumentException * @throws \LengthException - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function randomItems(int $number = 1, bool $preserve_keys=false): \VersatileCollections\CollectionInterface; /** - * + * * Shuffle all the items in the collection and return shuffled items in a new collection. * If collection is empty, this method should also return an empty collection. - * - * @param bool $preserve_keys true if the key associated with each shuffled item should be used in the new collection returned by this method, + * + * @param bool $preserve_keys true if the key associated with each shuffled item should be used in the new collection returned by this method, * otherwise false if the new collection returned should have sequential integer keys starting at zero. - * + * * @return \VersatileCollections\CollectionInterface (a new collection containing the shuffled items) - * + * * @used-for: creating-new-collections, ordering-or-sorting-items - * + * * @title: Shuffles all the items in a collection and returns the shuffled items in a new collection. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function shuffle(bool $preserve_keys=true): \VersatileCollections\CollectionInterface; /** - * + * * Search the collection for a given value and return the first corresponding key * in the collection whose item matches the given value if successful or false if not. - * + * * @param mixed $value the value to be searched for - * @param bool $strict true if strict comparison should be used when searching, + * @param bool $strict true if strict comparison should be used when searching, * else false for loose comparison - * - * @return mixed the first key in the collection whose item matches $value + * + * @return mixed the first key in the collection whose item matches $value * or false if $value is not found in the collection - * + * * @used-for: accessing-or-extracting-keys-or-items, finding-or-searching-for-items - * + * * @title: Searches the collection for a given value and returns the first corresponding key in the collection whose item matches the given value if successful or false if not. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function searchByVal( $value, bool $strict = false ); /** - * + * * Search the collection for a given value and return an array of all * corresponding key(s) in the collection whose item(s) match the given value, * if successful. - * - * + * + * * @param mixed $value the value to be searched for - * @param bool $strict true if strict comparison should be used when searching, + * @param bool $strict true if strict comparison should be used when searching, * else false for loose comparison - * - * @return mixed an array of all key(s) in the collection whose item(s) match $value + * + * @return mixed an array of all key(s) in the collection whose item(s) match $value * or false if $value is not found in the collection - * + * * @used-for: accessing-or-extracting-keys-or-items, finding-or-searching-for-items - * + * * @title: Searches the collection for a given value and returns an array of all corresponding key(s) in the collection whose item(s) match the given value or else returns false. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function searchAllByVal( $value, bool $strict = false ); /** - * + * * Search the collection using a callback. The callback will be executed on * each item and corresponding key in the collection. Returns an array of all * corresponding key(s) in the collection for which the callback returns * true. - * - * @param callable $callback a callback with the following signature - * function($key, $item):bool. It should return true - * if a $key should be returned or false otherwise. * + * @param callable $callback a callback with the following signature + * function($key, $item):bool. It should return true + * if a $key should be returned or false otherwise. + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $callback should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $callback. - * - * @return mixed an array of all key(s) in the collection for which the callback - * returned true or false if the callback did not return true for + * + * @return mixed an array of all key(s) in the collection for which the callback + * returned true or false if the callback did not return true for * any iteration over the collection - * + * * @used-for: accessing-or-extracting-keys-or-items, finding-or-searching-for-items - * + * * @title: Searches the collection using a callback. Returns an array of all corresponding key(s) in the collection for which the callback returns true or else returns false. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function searchByCallback(callable $callback, bool $bind_callback_to_this=true); /** - * + * * Get and remove the first item from the collection. * * @return mixed - * + * * @used-for: accessing-or-extracting-keys-or-items, deleting-items - * + * * @title: Returns and removes the first item in a collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getAndRemoveFirstItem (); /** - * + * * Extract a slice of the collection. - * + * * The collection itself should not be modified (i.e. sliced items will * still remain in the collection this method is being called with). - * + * * @see http://php.net/manual/en/function.array-slice.php array_slice - * - * @param int $offset If offset is non-negative, the sequence will start at - * that offset in the array. If offset is negative, the + * + * @param int $offset If offset is non-negative, the sequence will start at + * that offset in the array. If offset is negative, the * sequence will start that far from the end of the array. - * - * @param int $length If length is given and is positive, then the sequence - * will have up to that many elements in it. If the array - * is shorter than the length, then only the available - * array elements will be present. If length is given and - * is negative then the sequence will stop that many - * elements from the end of the array. If it is omitted, - * then the sequence will have everything from offset up + * + * @param int $length If length is given and is positive, then the sequence + * will have up to that many elements in it. If the array + * is shorter than the length, then only the available + * array elements will be present. If length is given and + * is negative then the sequence will stop that many + * elements from the end of the array. If it is omitted, + * then the sequence will have everything from offset up * until the end of the array. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the sliced items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections - * + * * @title: Extracts a slice from a collection and returns the slice as a new collection. The original collection is not modified. - * + * * @throws \InvalidArgumentException if $offset is non-int and / or if $length is non-null and non-int - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function slice(int $offset, ?int $length = null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items in ascending order while maintaining key association. * A new collection containing the sorted items is returned. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * first argument is considered to be respectively - * less than, equal to, or greater than the second. - * If callback is not supplied, a native php sorting - * function that maintains key association should be + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * first argument is considered to be respectively + * less than, equal to, or greater than the second. + * If callback is not supplied, a native php sorting + * function that maintains key association should be * used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the sorted items - * + * * @used-for: ordering-or-sorting-items, creating-new-collections - * + * * @title: Sorts a collection's items in ascending order while maintaining key association. A new collection containing the sorted items is returned. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sort(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items in descending order while maintaining key association. * A new collection containing the sorted items is returned. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * second argument is considered to be respectively - * less than, equal to, or greater than the first. - * If callback is not supplied, a native php sorting - * function that maintains key association should be + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * second argument is considered to be respectively + * less than, equal to, or greater than the first. + * If callback is not supplied, a native php sorting + * function that maintains key association should be * used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the sorted items - * + * * @used-for: ordering-or-sorting-items, creating-new-collections - * + * * @title: Sorts a collection's items in descending order while maintaining key association. A new collection containing the sorted items is returned. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortDesc(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items by keys in ascending order while maintaining key association. * A new collection containing the sorted items is returned. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * first argument is considered to be respectively - * less than, equal to, or greater than the second. - * If callback is not supplied, a native php sorting - * function that sorts by key and maintains key + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * first argument is considered to be respectively + * less than, equal to, or greater than the second. + * If callback is not supplied, a native php sorting + * function that sorts by key and maintains key * association should be used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the sorted items - * + * * @used-for: ordering-or-sorting-items, creating-new-collections - * + * * @title: Sorts a collection's items by keys in ascending order while maintaining key association. A new collection containing the sorted items is returned. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items by keys in descending order while maintaining key association. * A new collection containing the sorted items is returned. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * second argument is considered to be respectively - * less than, equal to, or greater than the first. - * If callback is not supplied, a native php sorting - * function that sorts by key and maintains key + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * second argument is considered to be respectively + * less than, equal to, or greater than the first. + * If callback is not supplied, a native php sorting + * function that sorts by key and maintains key * association should be used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the sorted items - * + * * @used-for: ordering-or-sorting-items, creating-new-collections - * + * * @title: Sorts a collection's items by keys in descending order while maintaining key association. A new collection containing the sorted items is returned. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortDescByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort a collection of associative arrays or objects by * specified field name(s) and return a new collection containing the sorted items * with their original key associations preserved. - * + * * This method should throw a \RuntimeException if any of the items in the * collection is not an associative array or an object. - * + * * Example: * $data = []; * $data[0] = [ 'volume' => 67, 'edition' => 2 ];
* $data[1] = [ 'volume' => 86, 'edition' => 1 ];
* $data[2] = [ 'volume' => 85, 'edition' => 6 ];
- * + * * $collection = new \VersatileCollections\GenericCollection(...$data); * $sort_param = new \VersatileCollections\MultiSortParameters('volume', SORT_ASC, SORT_NUMERIC); * $sorted_collection = $collection->SortByMultipleFields($sort_param); - * + * * // $sorted_collection->toArray() will look like: - * + * * [ * 0 => [ 'volume' => 67, 'edition' => 2 ], * 2 => [ 'volume' => 85, 'edition' => 6 ], * 1 => [ 'volume' => 86, 'edition' => 1 ], * ] - * + * * @param \VersatileCollections\MultiSortParameters $param * ........ * ........ * @param \VersatileCollections\MultiSortParameters $param * See \VersatileCollections\MultiSortParameters::$valid_sort_types for available sort types for each field. * See \VersatileCollections\MultiSortParameters::$valid_sort_directions for available sort directions for each field. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the sorted items - * + * * @used-for: ordering-or-sorting-items, creating-new-collections - * + * * @title: Sorts a collection of associative arrays or objects by specified field name(s) while maintaining key association. A new collection containing the sorted items is returned. The original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortByMultipleFields(\VersatileCollections\MultiSortParameters ...$param): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items in ascending order while maintaining key association. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * first argument is considered to be respectively - * less than, equal to, or greater than the second. - * If callback is not supplied, a native php sorting - * function that maintains key association should be + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * first argument is considered to be respectively + * less than, equal to, or greater than the second. + * If callback is not supplied, a native php sorting + * function that maintains key association should be * used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return $this - * + * * @used-for: ordering-or-sorting-items - * + * * @title: Sorts a collection's items in ascending order while maintaining key association. The original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortMe(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items in descending order while maintaining key association. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * second argument is considered to be respectively - * less than, equal to, or greater than the first. - * If callback is not supplied, a native php sorting - * function that maintains key association should be + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * second argument is considered to be respectively + * less than, equal to, or greater than the first. + * If callback is not supplied, a native php sorting + * function that maintains key association should be * used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return $this - * + * * @used-for: ordering-or-sorting-items - * + * * @title: Sorts a collection's items in descending order while maintaining key association. The original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortMeDesc(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items by keys in ascending order while maintaining key association. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * first argument is considered to be respectively - * less than, equal to, or greater than the second. - * If callback is not supplied, a native php sorting - * function that sorts by key and maintains key + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * first argument is considered to be respectively + * less than, equal to, or greater than the second. + * If callback is not supplied, a native php sorting + * function that sorts by key and maintains key * association should be used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return $this - * + * * @used-for: ordering-or-sorting-items - * + * * @title: Sorts a collection's items by keys in ascending order while maintaining key association. The original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortMeByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort the collection's items by keys in descending order while maintaining key association. - * - * @param callable $callable a callback with the following signature - * function(mixed $a, mixed $b): int. - * The callback function must return an INTEGER - * less than, equal to, or greater than zero if the - * second argument is considered to be respectively - * less than, equal to, or greater than the first. - * If callback is not supplied, a native php sorting - * function that sorts by key and maintains key + * + * @param callable $callable a callback with the following signature + * function(mixed $a, mixed $b): int. + * The callback function must return an INTEGER + * less than, equal to, or greater than zero if the + * second argument is considered to be respectively + * less than, equal to, or greater than the first. + * If callback is not supplied, a native php sorting + * function that sorts by key and maintains key * association should be used for the sorting. - * - * @param \VersatileCollections\SortType $type an object indicating the sort type. - * See \VersatileCollections\SortType::$valid_sort_types + * + * @param \VersatileCollections\SortType $type an object indicating the sort type. + * See \VersatileCollections\SortType::$valid_sort_types * for available sort types. - * + * * @return $this - * + * * @used-for: ordering-or-sorting-items - * + * * @title: Sorts a collection's items by keys in descending order while maintaining key association. The original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortMeDescByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface; /** - * + * * Sort a collection of associative arrays or objects by * specified field name(s) while preserving original key associations. - * + * * This method should throw a \RuntimeException if any of the items in the * collection is not an associative array or an object. - * + * * Example: * $data = []; * $data[0] = [ 'volume' => 67, 'edition' => 2 ];
* $data[1] = [ 'volume' => 86, 'edition' => 1 ];
* $data[2] = [ 'volume' => 85, 'edition' => 6 ];
- * + * * $collection = new \VersatileCollections\GenericCollection(...$data); * $sort_param = new \VersatileCollections\MultiSortParameters('volume', SORT_ASC, SORT_NUMERIC); * $collection->SortMeByMultipleFields($sort_param); - * + * * // $collection->toArray() will look like: - * + * * [ * 0 => [ 'volume' => 67, 'edition' => 2 ], * 2 => [ 'volume' => 85, 'edition' => 6 ], * 1 => [ 'volume' => 86, 'edition' => 1 ], * ] - * + * * @param \VersatileCollections\MultiSortParameters $param * ........ * ........ * @param \VersatileCollections\MultiSortParameters $param - * + * * @return $this - * + * * @used-for: ordering-or-sorting-items - * + * * @title: Sorts a collection of associative arrays or objects by specified field name(s) while maintaining key association. The original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function sortMeByMultipleFields(\VersatileCollections\MultiSortParameters ...$param): \VersatileCollections\CollectionInterface; /** - * + * * Remove a portion of the collection and optionally replace with items in $replacement. * This method modifies the original collection. - * + * * @see http://php.net/manual/en/function.array-splice.php array_splice * - * @param int $offset If offset is positive then the start of removed portion - * is at that offset from the beginning of the collection. - * If offset is negative then it starts that far from the + * @param int $offset If offset is positive then the start of removed portion + * is at that offset from the beginning of the collection. + * If offset is negative then it starts that far from the * end of the collection. - * - * @param int|null $length If length is omitted, removes everything from offset + * + * @param int|null $length If length is omitted, removes everything from offset * to the end of the collection. If length is specified * & is positive, then that many elements will be removed. * If length is specified and is negative then the end @@ -1578,276 +1578,276 @@ public function sortMeByMultipleFields(\VersatileCollections\MultiSortParameters * everything from offset to the end of the collection * when replacement is also specified, use $this->count() * for length. - * - * @param array $replacement If replacement array is specified, then the removed items + * + * @param array $replacement If replacement array is specified, then the removed items * are replaced with items from this array. - * + * * If offset and length are such that nothing is removed, * then the items from the replacement array are inserted * in the place specified by the offset. Note that keys in * replacement array are not preserved. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing the removed items. - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, deleting-items, modifying-items - * + * * @title: Removes and returns in a new collection, a portion of a collection and optionally replaces the removed portion with some specified items. - * + * * @throws \InvalidArgumentException if $offset is non-int and / or if $length is non-null and non-int - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function splice(int $offset, ?int $length=null, array $replacement=[]): \VersatileCollections\CollectionInterface; /** - * + * * Split a collection into a certain number of groups. - * + * * Throw an excption if * !is_int($numberOfGroups) or * $numberOfGroups > $this->count() or * $numberOfGroups < 0 * - * @param int $numberOfGroups - * + * @param int $numberOfGroups + * * @return \VersatileCollections\CollectionInterface A new collection containing $numberOfGroups collections - * + * * @used-for: creating-new-collections - * + * * @title: Splits a collection into a specified number of collections and returns a collection containing those collections. * * @throws \InvalidArgumentException - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function split(int $numberOfGroups): \VersatileCollections\CollectionInterface; /** - * + * * Take the first or last {$limit} items and return them in a new collection. * The items will not be removed from the original collection. * - * @param int $limit If positive, then first {$limit} items will be returned. - * If negative, then last {$limit} items will be returned. + * @param int $limit If positive, then first {$limit} items will be returned. + * If negative, then last {$limit} items will be returned. * If zero, then empty collection will be returned. - * + * * @return \VersatileCollections\CollectionInterface A new collection containing first or last {$limit} items. - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections - * + * * @title: Returns the first or last specified number of items in a collection in a new collection. Original collection is not modified. - * + * * @throws \InvalidArgumentException - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function take(int $limit): \VersatileCollections\CollectionInterface; /** * Pass a copy of collection to the given callback and then return $this. * - * @param callable $callback a callback with the following signature: + * @param callable $callback a callback with the following signature: * function(\VersatileCollections\CollectionInterface $collection):void * @return $this - * + * * @used-for: other-operations - * + * * @title: Invokes a specified callback on a copy of a collection and returns the original collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function tap(callable $callback): \VersatileCollections\CollectionInterface; /** - * + * * Union the collection with the given items by trying to append all items * from $items to $this collection and return the result in a new collection. * This method does not modify the original collection. - * + * * For keys that exist in both $items and $this, the items from $this * will be used, and the matching items from $items will be ignored. - * + * * For example: * $a = \VersatileCollections\GenericCollection::makeNew( * [ "a"=>"apple", "b"=>"banana" ] * ); * $b = [ "a"=>"pear", "b"=>"strawberry", "c"=>"cherry" ]; - * + * * // result * $a->unionWith($b)->toArray() === [ "a"=>"apple", "b"=>"banana", "c"=>"cherry" ] + * * - * * Use mergeWith() and mergeMeWith() if you want items from $items to be used * when same keys exist in both $items and $this. * * @see \VersatileCollections\CollectionInterface::mergeWith() * @see \VersatileCollections\CollectionInterface::mergeMeWith() - * - * @param array $items - * + * + * @param array $items + * * @return \VersatileCollections\CollectionInterface A new collection containing items in the original collection unioned with $items. - * + * * @used-for: adding-items, creating-new-collections - * + * * @title: Appends specified items to a collection and returns the result in a new collection. New items with the same keys as existing items will not overwrite the existing items. Original collection is not modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function unionWith(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Union the collection with the given items by trying to append all items * from $items to $this collection. * This method modifies the original collection. - * + * * For keys that exist in both $items and $this, the items from $this * will be used, and the matching items from $items will be ignored. - * + * * For example: * $a = \VersatileCollections\GenericCollection::makeNew( * [ "a"=>"apple", "b"=>"banana" ] * ); * $b = [ "a"=>"pear", "b"=>"strawberry", "c"=>"cherry" ]; - * + * * // result * $a->unionMeWith($b)->toArray() === [ "a"=>"apple", "b"=>"banana", "c"=>"cherry" ] + * * - * * Use mergeWith() and mergeMeWith() if you want items from $items to be used * when same keys exist in both $items and $this. - * + * * @see \VersatileCollections\CollectionInterface::mergeWith() * @see \VersatileCollections\CollectionInterface::mergeMeWith() * - * @param array $items - * + * @param array $items + * * @return $this - * + * * @used-for: adding-items - * + * * @title: Appends specified items to a collection. New items with the same keys as existing items will not overwrite the existing items. Original collection is modified. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function unionMeWith(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Get a collection of unique items from an existing collection. The keys * are not preserved in the returned collection. The uniqueness test must be * done via strict comparison (===). - * + * * Non-strict comparison is unsafe for collections containing objects, for * example you can't cast an object to a double or int. To get unique items * using non-strict comparison see * \VersatileCollections\ScalarsCollection::uniqueNonStrict(). - * + * * @see \VersatileCollections\ScalarsCollection::uniqueNonStrict() - * + * * @return \VersatileCollections\CollectionInterface - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, modifying-keys - * + * * @title: Returns a new collection of unique items from an existing collection. This method uses strict comparison for testing uniqueness. The keys are not preserved in the returned collection. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function unique(): \VersatileCollections\CollectionInterface; /** - * + * * Execute $callback on $this and return its return value if $truthy_value is truthy * or execute $default on $this and return its return value if $default is not null * or return NULL as a last resort. - * + * * @param bool $truthy_value - * - * @param callable $callback a callback with the following signature - * function(\VersatileCollections\CollectionInterface $collection): mixed - * It will be invoked on the collection object from which this method + * + * @param callable $callback a callback with the following signature + * function(\VersatileCollections\CollectionInterface $collection): mixed + * It will be invoked on the collection object from which this method * is being called. - * - * @param callable|null $default a callback with the following signature - * function(\VersatileCollections\CollectionInterface $collection): mixed - * It will be invoked on the collection object from which this method - * is being called. - * If $default is null and $truthy_value is not truthy, NULL will + * + * @param callable|null $default a callback with the following signature + * function(\VersatileCollections\CollectionInterface $collection): mixed + * It will be invoked on the collection object from which this method + * is being called. + * If $default is null and $truthy_value is not truthy, NULL will * be returned by this method. - * + * * @return mixed - * + * * @used-for: other-operations - * + * * @title: Conditionally executes a specified callback on a collection if first argument is truthy or executes a specified default callback otherwise and returns the value returned by the executed callback. If no callback could be executed, null is returned. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function whenTrue( $truthy_value, callable $callback, callable $default=null); /** - * + * * Execute $callback on $this and return its return value if $falsy_value is falsy * or execute $default on $this and return its return value if $default is not null * or return NULL as a last resort. - * + * * @param bool $falsy_value - * - * @param callable $callback a callback with the following signature - * function(\VersatileCollections\CollectionInterface $collection): mixed - * It will be invoked on the collection object from which this method + * + * @param callable $callback a callback with the following signature + * function(\VersatileCollections\CollectionInterface $collection): mixed + * It will be invoked on the collection object from which this method * is being called. - * - * @param callable|null $default a callback with the following signature - * function(\VersatileCollections\CollectionInterface $collection): mixed - * It will be invoked on the collection object from which this method - * is being called. - * If $default is null and $falsy_value is not falsy, NULL will + * + * @param callable|null $default a callback with the following signature + * function(\VersatileCollections\CollectionInterface $collection): mixed + * It will be invoked on the collection object from which this method + * is being called. + * If $default is null and $falsy_value is not falsy, NULL will * be returned by this method. - * + * * @return mixed - * + * * @used-for: other-operations - * + * * @title: Conditionally executes a specified callback on a collection if first argument is falsy or executes a specified default callback otherwise and returns the value returned by the executed callback. If no callback could be executed, null is returned. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function whenFalse( $falsy_value, callable $callback, callable $default=null); /** - * + * * Return the values from a single column in the collection. - * + * * Will only work on collections containing items that are * arrays and/or objects. - * + * * Must throw an exception if either $column_key and / or $index_key * contain(s) non-string and non-int value(s). * NOTE: $index_key can be null, meaning that the collection returned by * this method will have sequential integer keys starting at 0. - * + * * Must throw an exception if any item in the collection is not an array * or object. - * + * * Must throw an exception if $column_key is not a key in at least one array * in the collection. - * + * * Must throw an exception if $column_key is not an accessible property in * at least one object in the collection. * * Must throw an exception if $index_key is not null and is not a key in * at least one array in the collection. - * + * * Must throw an exception if $index_key is not null and is not an * accessible property in at least one object in the collection. * @@ -1858,466 +1858,466 @@ public function whenFalse( $falsy_value, callable $callback, callable $default=n * Must throw an exception if $index_key is not null and at least one * object in the collection has a non-int and non-string value for the * property named $index_key. - * + * * @param string|int $column_key name of field in each item to be used as values / items in the collection to be returned - * @param string|int $index_key name of field in each item to be used as key in the collection to be returned. - * If null, the returned collection will have sequential integer keys starting from 0. - * Be aware that only string or integer values are usuable as keys in the collection - * to be returned by this method and as a result an excpetion will be thrown if any - * item in the collection has a non-string and non-integer value for the field + * @param string|int $index_key name of field in each item to be used as key in the collection to be returned. + * If null, the returned collection will have sequential integer keys starting from 0. + * Be aware that only string or integer values are usuable as keys in the collection + * to be returned by this method and as a result an excpetion will be thrown if any + * item in the collection has a non-string and non-integer value for the field * specified in $index_key. - * + * * @return \VersatileCollections\GenericCollection A new collection containing the values from a single column in this collection * * @used-for: accessing-or-extracting-keys-or-items - * + * * @title: Returns a new collection containing the values from a specified field in each item in a collection. Corresponding keys in the returned collection could be specified as another field in each item in the collection. MUST be a collection whose items are arrays and / or objects. - * + * * @throws \InvalidArgumentException * @throws \RuntimeException - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function column($column_key, $index_key=null): \VersatileCollections\GenericCollection; /** - * + * * Create a new collection of the specified type with the keys and items in this collection. * Only keys and items will be copied into the new collection, other properties * of the original collection like methods added via addMethod(), * addMethodForAllInstances() and addStaticMethod() will not be * copied. * Original collection should not be modified. - * - * - * @param string|\VersatileCollections\CollectionInterface $new_collection_class name of a collection class that implements - * \VersatileCollections\CollectionInterface or an + * + * + * @param string|\VersatileCollections\CollectionInterface $new_collection_class name of a collection class that implements + * \VersatileCollections\CollectionInterface or an * instance of \VersatileCollections\CollectionInterface - * - * @return \VersatileCollections\CollectionInterface a new collection of the specified type - * containing the exact same keys and items + * + * @return \VersatileCollections\CollectionInterface a new collection of the specified type + * containing the exact same keys and items * as the original collection. - * + * * @used-for: creating-new-collections - * + * * @title: Creates a new collection of the specified type with the keys and items from an existing collection. The specified collection type MUST be compatible with the existing collection's type. - * - * @throws \VersatileCollections\Exceptions\InvalidItemException if one or more items in the original collection does not satisfy - * the specified new type. For example you cannot get a collection + * + * @throws \VersatileCollections\Exceptions\InvalidItemException if one or more items in the original collection does not satisfy + * the specified new type. For example you cannot get a collection * of Objects as a collection of Floats. - * - * @throws \InvalidArgumentException if $new_collection_class is not a string and is not an object + * + * @throws \InvalidArgumentException if $new_collection_class is not a string and is not an object * of if $new_collection_class is not an instanceof \VersatileCollections\CollectionInterface - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getAsNewType($new_collection_class=\VersatileCollections\GenericCollection::class): \VersatileCollections\CollectionInterface; /** - * + * * Remove items from the collection (whose keys are present in $keys) or (all items if $keys is empty) and return $this. - * + * * @param array $keys optional array of keys for the items to be removed. - * + * * @return $this - * + * * @used-for: deleting-items - * + * * @title: Removes items from a collection (whose keys are specified) or (all items if no keys were specified). - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function removeAll(array $keys=[]): \VersatileCollections\CollectionInterface; /** - * + * * Return a collection of items whose keys are present in $keys. * Keys are preserved in the new collection. - * + * * Key presence is determined via strict comparison (i.e. ===) - * + * * @param array $keys - * + * * @return \VersatileCollections\CollectionInterface a new collection of items whose keys are present in $keys - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection whose keys are present in the specified keys. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getAllWhereKeysIn(array $keys): \VersatileCollections\CollectionInterface; /** - * + * * Return a collection of items whose keys are not present in $keys. * Keys are preserved in the new collection. - * + * * Key presence is determined via strict comparison (i.e. ===) - * - * + * + * * @param array $keys - * - * @return \VersatileCollections\CollectionInterface a new collection of items whose keys are not present in $keys * + * @return \VersatileCollections\CollectionInterface a new collection of items whose keys are not present in $keys + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection whose keys are not present in the specified keys. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function getAllWhereKeysNotIn(array $keys): \VersatileCollections\CollectionInterface; /** - * + * * This method assumes positions in the collection are 1-indexed rather * than zero-indexed. For example item 'a' in this array (['a', 'b', 'c']) * is at the first position as far as the documentation of this method is * concerned as opposed to the zeroeth position (which is how you would * actually reference it php code). - * + * * Get a collection of at most $num_items_per_page items starting from the * (($page_number * $num_items_per_page) - $num_items_per_page + 1)th position * in the collection. - * + * * For example given a collection containing: - * + * * [ 'a', 'b', 'c', 'd', 'e', 'f', 'g', 'h' ] * ^ ^ ^ ^ ^ ^ ^ ^ * position 1 2 3 4 5 6 7 8 - * + * * calling paginate(2, 3) on that collection means you want to get a collection * of at most 3 items starting from the (((2 * 3) - 3 + 1) == 4th) position * in that collection which should return a collection containing: - * + * * [ 'd', 'e', 'f' ] - * - * @param int $page_number Page number. + * + * @param int $page_number Page number. * It must be a positive integer starting from 1. - * + * * If a value less than 1 is supplied, it should * be bumped up to 1. - * + * * If it has a value larger than the total number of * available pages (i.e. ($this->count() / $num_items_per_page) * assuming 1 <= $num_items_per_page <= $this->count()), * an empty collection will be returned. - * + * * @param int $num_items_per_page The number of items in the collection to be returned. - * + * * It must be a positive integer starting from 1. - * + * * If a value less than 1 is supplied, it should - * be bumped up to 1. - * + * be bumped up to 1. + * * If it has a value larger than $this->count(), * all items from position $page_number in the * collection till the end of the collection * will be returned. - * + * * @return \VersatileCollections\CollectionInterface a new collection of at most `$num_items_per_page` items present in the specified page - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections - * + * * @title: Returns a new collection of at most a specified number of items present in the specified page. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function paginate(int $page_number, int $num_items_per_page): \VersatileCollections\CollectionInterface; /** - * + * * Get the items in the collection that are not present in the given items. * - * @param array $items items in the collection that are not present in $items are returned by this method - * + * @param array $items items in the collection that are not present in $items are returned by this method + * * @return \VersatileCollections\CollectionInterface a new collection containing items in the collection that are not present in the given items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection containing items in an existing collection that are not present in the specified array of items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function diff(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Get the items in the collection that are not present in the given items using a callback for the comparison. * - * @param array $items items in the collection that are not present in $items are returned by this method - * @param callable $callback a callback used to check if an item in the collection is equal to an item in $item - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * @param array $items items in the collection that are not present in $items are returned by this method + * @param callable $callback a callback used to check if an item in the collection is equal to an item in $item + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * + * * @return \VersatileCollections\CollectionInterface a new collection containing items in the collection that are not present in the given items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection containing items in an existing collection that are not present in the specified array of items using a specified callback to test for item presence. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function diffUsing(array $items, callable $callback): \VersatileCollections\CollectionInterface; /** - * + * * Get the items in the collection whose keys and values are not present in the given items. * - * @param array $items items in the collection whose keys and values are not present in $items are returned by this method - * + * @param array $items items in the collection whose keys and values are not present in $items are returned by this method + * * @return \VersatileCollections\CollectionInterface a new collection containing items in the collection whose keys and values are not present in the given items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection containing items in an existing collection whose keys and values are not present in the specified array of items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function diffAssoc(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Get the items in the collection whose keys and values are not present in the given items. * - * @param array $items - * @param callable $key_comparator a callback used to check if a key for an item in the collection is equal to a key for an item in $item - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * @param array $items + * @param callable $key_comparator a callback used to check if a key for an item in the collection is equal to a key for an item in $item + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * + * * @return \VersatileCollections\CollectionInterface a new collection containing items in the collection whose keys and values are not present in the given items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection containing items in an existing collection whose keys and values are not present in the specified array of items using a callback to test for key presence. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function diffAssocUsing(array $items, callable $key_comparator): \VersatileCollections\CollectionInterface; /** - * + * * Get the items in the collection whose keys are not present in the given items. * - * @param array $items items in the collection whose keys are not present in $items are returned by this method - * + * @param array $items items in the collection whose keys are not present in $items are returned by this method + * * @return \VersatileCollections\CollectionInterface a new collection containing items in the collection whose keys are not present in $items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection containing items in an existing collection whose keys are not present in the specified array of items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function diffKeys(array $items): \VersatileCollections\CollectionInterface; /** - * + * * Get the items in the collection whose keys are not present in the given items using a callback for the key comparison. * - * @param array $items items in the collection whose keys are not present in $items are returned by this method - * @param callable $key_comparator a callback used to check if a key for an item in the collection is equal to a key for an item in $item - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * @param array $items items in the collection whose keys are not present in $items are returned by this method + * @param callable $key_comparator a callback used to check if a key for an item in the collection is equal to a key for an item in $item + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * + * * @return \VersatileCollections\CollectionInterface a new collection containing items in the collection whose keys are not present in $items - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection containing items in an existing collection whose keys are not present in the specified array of items using a specified callback to test for key presence. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function diffKeysUsing(array $items, callable $key_comparator): \VersatileCollections\CollectionInterface; /** - * + * * Iterate through a collection and execute a callback over each item (the callback * checks if each item satisfies one or more condition(s) and returns true if an item * satisfies the condition(s) or false if not) and return true if all items satisfy * the condition(s) tested in the callback or false otherwise. - * - * @param callable $callback a callback with the following signature - * function($key, $item):bool - * It should return true if the current item `$item` + * + * @param callable $callback a callback with the following signature + * function($key, $item):bool + * It should return true if the current item `$item` * satisfies one or more condition(s) or false otherwise. - * + * * @param bool $bind_callback_to_this true if the variable $this inside the supplied * $callback should refer to the collection object * this method is being invoked on, else false if * you want the variable $this to be undefined * inside the supplied $callback. - * + * * @return bool - * + * * @used-for: other-operations - * + * * @title: Iterates through a collection and executes a callback (that returns a boolean) over each item and returns true if the callback returns true for all items or false otherwise. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function allSatisfyConditions(callable $callback, bool $bind_callback_to_this=true): bool; /** - * + * * Create a collection of items from the original collection whose keys are present in $arr - * + * * @param array $arr - * + * * @return \VersatileCollections\CollectionInterface new collection of items from the original collection whose keys are present in $arr - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection whose keys are present in an array of specified keys. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function intersectByKeys(array $arr): \VersatileCollections\CollectionInterface; /** - * + * * Create a collection of items from the original collection that are present in $arr - * + * * @param array $arr - * + * * @return \VersatileCollections\CollectionInterface new collection of items from the original collection that are present in $arr - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection that are present in an array of specified items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function intersectByItems(array $arr): \VersatileCollections\CollectionInterface; /** - * + * * Create a collection of items from the original collection whose keys and corresponding items /values are present in $arr - * + * * @param array $arr - * + * * @return \VersatileCollections\CollectionInterface new collection of items from the original collection whose keys and corresponding items /values are present in $arr - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection whose keys and corresponding items are present in an array of specified items. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function intersectByKeysAndItems(array $arr): \VersatileCollections\CollectionInterface; /** - * + * * Create a collection of items from the original collection whose keys are present in $arr using a callback for the key comparison - * + * * @param array $arr - * @param callable $key_comparator a callback used to check if a key in the collection is equal to a key in $arr - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * @param callable $key_comparator a callback used to check if a key in the collection is equal to a key in $arr + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * + * * @return \VersatileCollections\CollectionInterface new collection of items from the original collection whose keys are present in $arr - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection whose keys are present in an array of specified keys using a specified callback for testing key presence. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function intersectByKeysUsingCallback(array $arr, callable $key_comparator): \VersatileCollections\CollectionInterface; /** - * + * * Create a collection of items from the original collection that are present in $arr using a callback for the item comparison - * + * * @param array $arr - * @param callable $item_comparator a callback used to check if an item in the collection is equal to an item in $arr - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * @param callable $item_comparator a callback used to check if an item in the collection is equal to an item in $arr + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * + * * @return \VersatileCollections\CollectionInterface new collection of items from the original collection that are present in $arr - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection that are present in an array of specified items using a specified callback for testing item presence. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function intersectByItemsUsingCallback(array $arr, callable $item_comparator): \VersatileCollections\CollectionInterface; /** - * + * * Create a collection of items from the original collection whose keys and corresponding items /values are present in $arr using callbacks for key and item comparisons - * + * * @param array $arr - * - * @param callable $key_comparator a callback used to check if a key in the collection is equal to a key in $arr - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * + * @param callable $key_comparator a callback used to check if a key in the collection is equal to a key in $arr + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * - * @param callable $item_comparator a callback used to check if an item in the collection is equal to an item in $arr - * The function must have the following signature: - * int callback ( mixed $a, mixed $b ): - * The comparison function must return an integer less than, - * equal to, or greater than zero if the first argument is - * considered to be respectively less than, equal to, + * + * @param callable $item_comparator a callback used to check if an item in the collection is equal to an item in $arr + * The function must have the following signature: + * int callback ( mixed $a, mixed $b ): + * The comparison function must return an integer less than, + * equal to, or greater than zero if the first argument is + * considered to be respectively less than, equal to, * or greater than the second. - * + * * !is_null($key_comparator) && is_null($item_comparator) use array_intersect_uassoc * is_null($key_comparator) && !is_null($item_comparator) use array_uintersect_assoc * !is_null($key_comparator) && !is_null($item_comparator) use array_uintersect_uassoc * is_null($key_comparator) && is_null($item_comparator) use array_intersect_assoc - * + * * @return \VersatileCollections\CollectionInterface new collection of items from the original collection whose keys and corresponding items /values are present in $arr - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, finding-or-searching-for-items - * + * * @title: Returns a new collection of items from an existing collection whose keys and corresponding items are present in an array of specified items using one specified callback for testing key presence and another specified callback for testing item presence. - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * + * */ public function intersectByKeysAndItemsUsingCallbacks(array $arr, callable $key_comparator=null, callable $item_comparator=null): \VersatileCollections\CollectionInterface; } diff --git a/src/CollectionInterfaceImplementationTrait.php b/src/CollectionInterfaceImplementationTrait.php index e42d7eb..bcd98b1 100644 --- a/src/CollectionInterfaceImplementationTrait.php +++ b/src/CollectionInterfaceImplementationTrait.php @@ -5,7 +5,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this trait: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -21,7 +21,7 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author Rotimi Ade */ trait CollectionInterfaceImplementationTrait { @@ -29,28 +29,28 @@ trait CollectionInterfaceImplementationTrait { /** * * @var array - * + * */ protected $versatile_collections_items = []; /** * * @var array - * + * */ protected static $versatile_collections_methods_for_all_instances = []; /** * * @var array - * + * */ protected $versatile_collections_methods_for_this_instance = []; /** * * @var array - * + * */ protected static $versatile_collections_static_methods = []; @@ -94,15 +94,15 @@ protected static function validateMethodName(string $name, $method_name_was_pass } /** - * + * * @param string $name name of the method being added * @param callable $callable method being added * @param bool $has_return_val true means $callable returns a value, else false if $callable returns no value - * + * * @used-for: adding-methods-at-runtime - * + * * @title: Registers a specified `callable` with a specified name to a Collection class, so that the registered callable can be later called as a static method with the specified name on the Collection class or any of its sub-classes. - * + * */ public static function addStaticMethod( string $name, @@ -119,16 +119,16 @@ public static function addStaticMethod( } /** - * + * * @param string $name name of the method being added * @param callable $callable method being added * @param bool $has_return_val true means $callable returns a value, else false if $callable returns no value * @param bool $bind_to_this_on_invocation true means $callable will be bound to $this before invocation, else false if $callable should not be explicitly bound to $this before invocation - * + * * @used-for: adding-methods-at-runtime - * + * * @title: Registers a specified `callable` with a specified name to a Collection class, so that the registered callable can be later called as an instance method with the specified name on any instance of the Collection class or any of its sub-classes. - * + * */ public static function addMethodForAllInstances( string $name, @@ -147,18 +147,18 @@ public static function addMethodForAllInstances( } /** - * + * * @param string $name name of the method being added * @param callable $callable method being added * @param bool $has_return_val true means $callable returns a value, else false if $callable returns no value * @param bool $bind_to_this true means $callable will be bound to $this, else false if $callable should not be explicitly bound to $this - * + * * @used-for: adding-methods-at-runtime - * + * * @title: Registers a specified `callable` with a specified name to a single instance of a Collection class, so that the registered callable can be later called as an instance method with the specified name on the instance of the Collection class the callable was registered to. - * + * * @return $this - * + * */ public function addMethod( string $name, @@ -211,18 +211,18 @@ protected static function getKeyForDynamicMethod($name, array &$methods_array, $ } /** - * + * * @param string $method_name * @param array $arguments - * + * * @return mixed - * + * * @used-for: other-operations - * + * * @title: Tries to call the specified method with the specified arguments and return its return value if it was registered via either `addMethod` or `addMethodForAllInstances` . An exception of type **\BadMethodCallException** is thrown if the method could not be called. - * + * * @throws \BadMethodCallException - * + * */ public function __call(string $method_name, array $arguments=[]) { @@ -271,18 +271,18 @@ public function __call(string $method_name, array $arguments=[]) { } /** - * + * * @param string $method_name * @param array $arguments - * + * * @return mixed - * + * * @used-for: other-operations - * + * * @title: Tries to call the specified method with the specified arguments and return its return value if it was registered via `addStaticMethod`. An exception of type **\BadMethodCallException** is thrown if the method could not be called. - * + * * @throws \BadMethodCallException - * + * */ public static function __callStatic(string $method_name, array $arguments=[]) { @@ -331,9 +331,9 @@ public function __unset(string $key): void { } /** - * + * * @see \VersatileCollections\CollectionInterface::makeNew() - * + * */ public static function makeNew(array $items=[], bool $preserve_keys=true): \VersatileCollections\CollectionInterface { @@ -358,9 +358,9 @@ public static function makeNew(array $items=[], bool $preserve_keys=true): \Vers } /** - * + * * @see \VersatileCollections\CollectionInterface::offsetExists() - * + * */ public function offsetExists($key): bool { @@ -368,9 +368,9 @@ public function offsetExists($key): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::offsetGet() - * + * */ public function offsetGet($key) { @@ -385,9 +385,9 @@ public function offsetGet($key) { } /** - * + * * @see \VersatileCollections\CollectionInterface::offsetSet() - * + * */ public function offsetSet($key, $val): void { @@ -402,9 +402,9 @@ public function offsetSet($key, $val): void { } /** - * + * * @see \VersatileCollections\CollectionInterface::offsetUnset() - * + * */ public function offsetUnset($key): void { @@ -413,9 +413,9 @@ public function offsetUnset($key): void { } /** - * + * * @see \VersatileCollections\CollectionInterface::toArray() - * + * * @return mixed[] */ public function toArray(): array { @@ -424,9 +424,9 @@ public function toArray(): array { } /** - * + * * @see \VersatileCollections\CollectionInterface::getIterator() - * + * */ public function getIterator(): \Iterator { @@ -434,9 +434,9 @@ public function getIterator(): \Iterator { } /** - * + * * @see \VersatileCollections\CollectionInterface::count() - * + * */ public function count(): int { @@ -452,11 +452,10 @@ public function __construct(...$items) { //////////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////////// ////////// OTHER COLLECTION METHODS //////////////////////////////////////// - /** - * + * * @see \VersatileCollections\CollectionInterface::firstItem() - * + * */ public function firstItem(){ @@ -466,9 +465,9 @@ public function firstItem(){ } /** - * + * * @see \VersatileCollections\CollectionInterface::lastItem() - * + * */ public function lastItem(){ @@ -478,9 +477,9 @@ public function lastItem(){ } /** - * + * * @see \VersatileCollections\CollectionInterface::getKeys() - * + * */ public function getKeys(): \VersatileCollections\GenericCollection { @@ -488,9 +487,9 @@ public function getKeys(): \VersatileCollections\GenericCollection { } /** - * + * * @see \VersatileCollections\CollectionInterface::setValForEachItem() - * + * */ public function setValForEachItem(string $field_name, $field_val, bool $add_field_if_not_present=false): \VersatileCollections\CollectionInterface { @@ -545,9 +544,9 @@ public function setValForEachItem(string $field_name, $field_val, bool $add_fiel } /** - * + * * @see \VersatileCollections\CollectionInterface::filterAll() - * + * */ public function filterAll(callable $filterer, bool $copy_keys=false, bool $bind_callback_to_this=true, bool $remove_filtered_items=false): \VersatileCollections\CollectionInterface { @@ -555,9 +554,9 @@ public function filterAll(callable $filterer, bool $copy_keys=false, bool $bind_ } /** - * + * * @see \VersatileCollections\CollectionInterface::filterFirstN() - * + * */ public function filterFirstN(callable $filterer, ?int $max_number_of_filtered_items_to_return =null, bool $copy_keys=false, bool $bind_callback_to_this=true, bool $remove_filtered_items=false): \VersatileCollections\CollectionInterface { @@ -614,9 +613,9 @@ public function filterFirstN(callable $filterer, ?int $max_number_of_filtered_it } /** - * + * * @see \VersatileCollections\CollectionInterface::transform() - * + * */ public function transform(callable $transformer, bool $bind_callback_to_this=true): \VersatileCollections\CollectionInterface { @@ -641,9 +640,9 @@ public function transform(callable $transformer, bool $bind_callback_to_this=tru } /** - * + * * @see \VersatileCollections\CollectionInterface::reduce() - * + * */ public function reduce(callable $reducer, $initial_value=NULL) { @@ -651,9 +650,9 @@ public function reduce(callable $reducer, $initial_value=NULL) { } /** - * + * * @see \VersatileCollections\CollectionInterface::reduceWithKeyAccess() - * + * */ public function reduceWithKeyAccess(callable $reducer, $initial_value=NULL) { @@ -668,9 +667,9 @@ public function reduceWithKeyAccess(callable $reducer, $initial_value=NULL) { } /** - * + * * @see \VersatileCollections\CollectionInterface::reverse() - * + * */ public function reverse(): \VersatileCollections\CollectionInterface { @@ -680,9 +679,9 @@ public function reverse(): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::reverseMe() - * + * */ public function reverseMe(): \VersatileCollections\CollectionInterface { @@ -693,9 +692,9 @@ public function reverseMe(): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::slice() - * + * */ public function slice(int $offset, ?int $length = null): \VersatileCollections\CollectionInterface { @@ -705,9 +704,9 @@ public function slice(int $offset, ?int $length = null): \VersatileCollections\C } /** - * + * * @see \VersatileCollections\CollectionInterface::isEmpty() - * + * */ public function isEmpty(): bool { @@ -715,9 +714,9 @@ public function isEmpty(): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::getIfExists() - * + * */ public function getIfExists($key, $default_value=null) { @@ -737,9 +736,9 @@ public function getIfExists($key, $default_value=null) { } /** - * + * * @see \VersatileCollections\CollectionInterface::containsItem() - * + * */ public function containsItem($item): bool { @@ -747,9 +746,9 @@ public function containsItem($item): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::containsKey() - * + * */ public function containsKey($key): bool { @@ -762,9 +761,9 @@ public function containsKey($key): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::containsItemWithKey() - * + * */ public function containsItemWithKey($key, $item): bool { @@ -778,9 +777,9 @@ public function containsItemWithKey($key, $item): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::containsItems() - * + * */ public function containsItems(array $items): bool { @@ -801,9 +800,9 @@ public function containsItems(array $items): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::containsKeys() - * + * */ public function containsKeys(array $keys): bool { @@ -824,9 +823,9 @@ public function containsKeys(array $keys): bool { } /** - * + * * @see \VersatileCollections\CollectionInterface::appendCollection() - * + * */ public function appendCollection(CollectionInterface $other): \VersatileCollections\CollectionInterface { @@ -842,9 +841,9 @@ public function appendCollection(CollectionInterface $other): \VersatileCollecti } /** - * + * * @see \VersatileCollections\CollectionInterface::appendItem() - * + * */ public function appendItem($item): \VersatileCollections\CollectionInterface { @@ -854,9 +853,9 @@ public function appendItem($item): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::mergeWith() - * + * */ public function mergeWith(array $items): \VersatileCollections\CollectionInterface { @@ -877,9 +876,9 @@ public function mergeWith(array $items): \VersatileCollections\CollectionInterfa } /** - * + * * @see \VersatileCollections\CollectionInterface::mergeMeWith() - * + * */ public function mergeMeWith(array $items): \VersatileCollections\CollectionInterface { @@ -897,9 +896,9 @@ public function mergeMeWith(array $items): \VersatileCollections\CollectionInter } /** - * + * * @see \VersatileCollections\CollectionInterface::prependCollection() - * + * */ public function prependCollection(CollectionInterface $other): \VersatileCollections\CollectionInterface { @@ -912,9 +911,9 @@ public function prependCollection(CollectionInterface $other): \VersatileCollect } /** - * + * * @see \VersatileCollections\CollectionInterface::prependItem() - * + * */ public function prependItem($item, $key=null): \VersatileCollections\CollectionInterface { @@ -941,9 +940,9 @@ public function prependItem($item, $key=null): \VersatileCollections\CollectionI } /** - * + * * @see \VersatileCollections\CollectionInterface::getCollectionsOfSizeN() - * + * */ public function getCollectionsOfSizeN(int $max_size_of_each_collection=1): \VersatileCollections\CollectionInterface { @@ -983,9 +982,9 @@ public function getCollectionsOfSizeN(int $max_size_of_each_collection=1): \Vers } /** - * + * * @see \VersatileCollections\CollectionInterface::yieldCollectionsOfSizeN() - * + * */ public function yieldCollectionsOfSizeN(int $max_size_of_each_collection=1): \Generator { @@ -1022,9 +1021,9 @@ public function yieldCollectionsOfSizeN(int $max_size_of_each_collection=1): \Ge } /** - * + * * @see \VersatileCollections\CollectionInterface::makeAllKeysNumeric() - * + * */ public function makeAllKeysNumeric(int $starting_key=0): \VersatileCollections\CollectionInterface { @@ -1051,9 +1050,9 @@ public function makeAllKeysNumeric(int $starting_key=0): \VersatileCollections\C } /** - * + * * @see \VersatileCollections\CollectionInterface::each() - * + * */ public function each( callable $callback, $termination_value=false, bool $bind_callback_to_this=true @@ -1079,9 +1078,9 @@ public function each( } /** - * + * * @see \VersatileCollections\CollectionInterface::map() - * + * */ public function map( callable $callback, bool $preserve_keys = true, bool $bind_callback_to_this=true @@ -1117,9 +1116,9 @@ public function map( } /** - * + * * @see \VersatileCollections\CollectionInterface::everyNth() - * + * */ public function everyNth(int $n, int $position_of_first_nth_item = 0): \VersatileCollections\CollectionInterface { @@ -1140,9 +1139,9 @@ public function everyNth(int $n, int $position_of_first_nth_item = 0): \Versatil } /** - * + * * @see \VersatileCollections\CollectionInterface::pipeAndReturnCallbackResult() - * + * */ public function pipeAndReturnCallbackResult(callable $callback) { @@ -1150,9 +1149,9 @@ public function pipeAndReturnCallbackResult(callable $callback) { } /** - * + * * @see \VersatileCollections\CollectionInterface::pipeAndReturnSelf() - * + * */ public function pipeAndReturnSelf(callable $callback): \VersatileCollections\CollectionInterface { @@ -1162,9 +1161,9 @@ public function pipeAndReturnSelf(callable $callback): \VersatileCollections\Col } /** - * + * * @see \VersatileCollections\CollectionInterface::tap() - * + * */ public function tap(callable $callback): \VersatileCollections\CollectionInterface { @@ -1174,19 +1173,19 @@ public function tap(callable $callback): \VersatileCollections\CollectionInterfa } /** - * + * * @see \VersatileCollections\CollectionInterface::getAndRemoveFirstItem() - * - */ + * + */ public function getAndRemoveFirstItem() { return array_shift($this->versatile_collections_items); } /** - * + * * @see \VersatileCollections\CollectionInterface::getAndRemoveLastItem() - * + * */ public function getAndRemoveLastItem() { @@ -1194,9 +1193,9 @@ public function getAndRemoveLastItem() } /** - * + * * @see \VersatileCollections\CollectionInterface::pull() - * + * */ public function pull($key, $default = null) { @@ -1208,9 +1207,9 @@ public function pull($key, $default = null) { } /** - * + * * @see \VersatileCollections\CollectionInterface::push() - * + * */ public function push($item): \VersatileCollections\CollectionInterface { @@ -1218,9 +1217,9 @@ public function push($item): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::put() - * + * */ public function put($key, $value): \VersatileCollections\CollectionInterface { @@ -1230,9 +1229,9 @@ public function put($key, $value): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::randomKey() - * + * */ public function randomKey() { @@ -1248,9 +1247,9 @@ public function randomKey() { } /** - * + * * @see \VersatileCollections\CollectionInterface::randomItem() - * + * */ public function randomItem() { @@ -1266,9 +1265,9 @@ public function randomItem() { } /** - * + * * @see \VersatileCollections\CollectionInterface::randomKeys() - * + * */ public function randomKeys(int $number = 1): \VersatileCollections\CollectionInterface { @@ -1297,9 +1296,9 @@ public function randomKeys(int $number = 1): \VersatileCollections\CollectionInt } /** - * + * * @see \VersatileCollections\CollectionInterface::randomItems() - * + * */ public function randomItems(int $number = 1, bool $preserve_keys=false): \VersatileCollections\CollectionInterface { @@ -1339,10 +1338,10 @@ public function randomItems(int $number = 1, bool $preserve_keys=false): \Versat } /** - * + * * @see \VersatileCollections\CollectionInterface::shuffle() - * - */ + * + */ public function shuffle(bool $preserve_keys=true): \VersatileCollections\CollectionInterface { if( $this->isEmpty() ) { @@ -1374,20 +1373,20 @@ public function shuffle(bool $preserve_keys=true): \VersatileCollections\Collect } /** - * + * * @see \VersatileCollections\CollectionInterface::searchByVal() - * - */ + * + */ public function searchByVal( $value, bool $strict = false ) { return array_search($value, $this->versatile_collections_items, $strict); } /** - * + * * @see \VersatileCollections\CollectionInterface::searchAllByVal() - * - */ + * + */ public function searchAllByVal( $value, bool $strict = false ){ $result = array_keys($this->versatile_collections_items, $value, $strict); @@ -1402,10 +1401,10 @@ public function searchAllByVal( $value, bool $strict = false ){ } /** - * + * * @see \VersatileCollections\CollectionInterface::searchByCallback() - * - */ + * + */ public function searchByCallback(callable $callback, bool $bind_callback_to_this=true) { $results = []; @@ -1451,6 +1450,9 @@ protected function performSort( } } + /** + * @return mixed[] + */ protected function performMultiSort(array $array_to_be_sorted, \VersatileCollections\MultiSortParameters ...$param) { $multi_sort_args = []; @@ -1558,9 +1560,9 @@ protected function performMultiSort(array $array_to_be_sorted, \VersatileCollect } /** - * + * * @see \VersatileCollections\CollectionInterface::sort() - * + * */ public function sort(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1579,9 +1581,9 @@ public function sort(callable $callable=null, \VersatileCollections\SortType $ty } /** - * + * * @see \VersatileCollections\CollectionInterface::sortDesc() - * + * */ public function sortDesc(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1600,9 +1602,9 @@ public function sortDesc(callable $callable=null, \VersatileCollections\SortType } /** - * + * * @see \VersatileCollections\CollectionInterface::sortByKey() - * + * */ public function sortByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1621,9 +1623,9 @@ public function sortByKey(callable $callable=null, \VersatileCollections\SortTyp } /** - * + * * @see \VersatileCollections\CollectionInterface::sortDescByKey() - * + * */ public function sortDescByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1643,12 +1645,12 @@ public function sortDescByKey(callable $callable=null, \VersatileCollections\Sor /** - * + * * Can also sort by private and / or protected field(s) in each object in * the collection. - * + * * @see \VersatileCollections\CollectionInterface::sortByMultipleFields() - * + * */ public function sortByMultipleFields(\VersatileCollections\MultiSortParameters ...$param): \VersatileCollections\CollectionInterface { @@ -1669,9 +1671,9 @@ public function sortByMultipleFields(\VersatileCollections\MultiSortParameters . } /** - * + * * @see \VersatileCollections\CollectionInterface::sortMe() - * + * */ public function sortMe(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1687,9 +1689,9 @@ public function sortMe(callable $callable=null, \VersatileCollections\SortType $ } /** - * + * * @see \VersatileCollections\CollectionInterface::sortMeDesc() - * + * */ public function sortMeDesc(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1705,9 +1707,9 @@ public function sortMeDesc(callable $callable=null, \VersatileCollections\SortTy } /** - * + * * @see \VersatileCollections\CollectionInterface::sortMeByKey() - * + * */ public function sortMeByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1723,9 +1725,9 @@ public function sortMeByKey(callable $callable=null, \VersatileCollections\SortT } /** - * + * * @see \VersatileCollections\CollectionInterface::sortMeDescByKey() - * + * */ public function sortMeDescByKey(callable $callable=null, \VersatileCollections\SortType $type=null): \VersatileCollections\CollectionInterface { @@ -1741,12 +1743,12 @@ public function sortMeDescByKey(callable $callable=null, \VersatileCollections\S } /** - * + * * Can also sort by private and / or protected field(s) in each object in * the collection. - * + * * @see \VersatileCollections\CollectionInterface::sortMeByMultipleFields() - * + * */ public function sortMeByMultipleFields(\VersatileCollections\MultiSortParameters ...$param): \VersatileCollections\CollectionInterface { @@ -1769,9 +1771,9 @@ public function sortMeByMultipleFields(\VersatileCollections\MultiSortParameters } /** - * + * * @see \VersatileCollections\CollectionInterface::splice() - * + * */ public function splice(int $offset, ?int $length=null, array $replacement=[]): \VersatileCollections\CollectionInterface { @@ -1784,9 +1786,9 @@ public function splice(int $offset, ?int $length=null, array $replacement=[]): \ } /** - * + * * @see \VersatileCollections\CollectionInterface::split() - * + * */ public function split(int $numberOfGroups): \VersatileCollections\CollectionInterface { @@ -1826,9 +1828,9 @@ public function split(int $numberOfGroups): \VersatileCollections\CollectionInte } /** - * + * * @see \VersatileCollections\CollectionInterface::take() - * + * */ public function take(int $limit): \VersatileCollections\CollectionInterface { @@ -1840,9 +1842,9 @@ public function take(int $limit): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::unique() - * + * */ public function unique(): \VersatileCollections\CollectionInterface { @@ -1864,9 +1866,9 @@ function($carry, $item) { } /** - * + * * @see \VersatileCollections\CollectionInterface::unionWith() - * + * */ public function unionWith(array $items): \VersatileCollections\CollectionInterface { @@ -1874,9 +1876,9 @@ public function unionWith(array $items): \VersatileCollections\CollectionInterfa } /** - * + * * @see \VersatileCollections\CollectionInterface::unionMeWith() - * + * */ public function unionMeWith(array $items): \VersatileCollections\CollectionInterface { @@ -1886,12 +1888,12 @@ public function unionMeWith(array $items): \VersatileCollections\CollectionInter } /** - * + * * Can also extract values from private and / or protected properties * of each object in the collection. - * + * * @see \VersatileCollections\CollectionInterface::column() - * + * */ public function column($column_key, $index_key=null): \VersatileCollections\GenericCollection { @@ -2073,9 +2075,9 @@ public function column($column_key, $index_key=null): \VersatileCollections\Gene } /** - * + * * @see \VersatileCollections\CollectionInterface::getItems() - * + * */ public function getItems(): \VersatileCollections\CollectionInterface { @@ -2083,9 +2085,9 @@ public function getItems(): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::whenTrue() - * + * */ public function whenTrue( $truthy_value, callable $callback, callable $default=null @@ -2103,9 +2105,9 @@ public function whenTrue( } /** - * + * * @see \VersatileCollections\CollectionInterface::whenFalse() - * + * */ public function whenFalse( $falsy_value, callable $callback, callable $default=null @@ -2114,9 +2116,9 @@ public function whenFalse( } /** - * + * * @see \VersatileCollections\CollectionInterface::getAsNewType() - * + * */ public function getAsNewType($new_collection_class=\VersatileCollections\GenericCollection::class): \VersatileCollections\CollectionInterface { @@ -2157,9 +2159,9 @@ public function getAsNewType($new_collection_class=\VersatileCollections\Generic } /** - * + * * @see \VersatileCollections\CollectionInterface::removeAll() - * + * */ public function removeAll(array $keys=[]): \VersatileCollections\CollectionInterface { @@ -2184,9 +2186,9 @@ public function removeAll(array $keys=[]): \VersatileCollections\CollectionInter } /** - * + * * @see \VersatileCollections\CollectionInterface::getAllWhereKeysIn() - * + * */ public function getAllWhereKeysIn(array $keys): \VersatileCollections\CollectionInterface { @@ -2204,9 +2206,9 @@ public function getAllWhereKeysIn(array $keys): \VersatileCollections\Collection } /** - * + * * @see \VersatileCollections\CollectionInterface::getAllWhereKeysNotIn() - * + * */ public function getAllWhereKeysNotIn(array $keys): \VersatileCollections\CollectionInterface { @@ -2224,9 +2226,9 @@ public function getAllWhereKeysNotIn(array $keys): \VersatileCollections\Collect } /** - * + * * @see \VersatileCollections\CollectionInterface::paginate() - * + * */ public function paginate(int $page_number, int $num_items_per_page): \VersatileCollections\CollectionInterface { @@ -2253,9 +2255,9 @@ public function paginate(int $page_number, int $num_items_per_page): \VersatileC } /** - * + * * @see \VersatileCollections\CollectionInterface::diff() - * + * */ public function diff(array $items): \VersatileCollections\CollectionInterface { @@ -2263,9 +2265,9 @@ public function diff(array $items): \VersatileCollections\CollectionInterface { } /** - * + * * @see \VersatileCollections\CollectionInterface::diffUsing() - * + * */ public function diffUsing(array $items, callable $callback): \VersatileCollections\CollectionInterface { @@ -2273,9 +2275,9 @@ public function diffUsing(array $items, callable $callback): \VersatileCollectio } /** - * + * * @see \VersatileCollections\CollectionInterface::diffAssoc() - * + * */ public function diffAssoc(array $items): \VersatileCollections\CollectionInterface { @@ -2283,9 +2285,9 @@ public function diffAssoc(array $items): \VersatileCollections\CollectionInterfa } /** - * + * * @see \VersatileCollections\CollectionInterface::diffAssocUsing() - * + * */ public function diffAssocUsing(array $items, callable $key_comparator): \VersatileCollections\CollectionInterface { @@ -2293,9 +2295,9 @@ public function diffAssocUsing(array $items, callable $key_comparator): \Versati } /** - * + * * @see \VersatileCollections\CollectionInterface::diffKeys() - * + * */ public function diffKeys(array $items): \VersatileCollections\CollectionInterface { @@ -2303,9 +2305,9 @@ public function diffKeys(array $items): \VersatileCollections\CollectionInterfac } /** - * + * * @see \VersatileCollections\CollectionInterface::diffKeysUsing() - * + * */ public function diffKeysUsing(array $items, callable $key_comparator): \VersatileCollections\CollectionInterface { @@ -2313,9 +2315,9 @@ public function diffKeysUsing(array $items, callable $key_comparator): \Versatil } /** - * + * * @see \VersatileCollections\CollectionInterface::allSatisfyConditions() - * + * */ public function allSatisfyConditions(callable $callback, bool $bind_callback_to_this=true): bool { @@ -2337,9 +2339,9 @@ function($carry, $item, $key) use ($callback){ } /** - * + * * @see \VersatileCollections\CollectionInterface::intersectByKeys() - * + * */ public function intersectByKeys(array $arr): \VersatileCollections\CollectionInterface { @@ -2347,9 +2349,9 @@ public function intersectByKeys(array $arr): \VersatileCollections\CollectionInt } /** - * + * * @see \VersatileCollections\CollectionInterface::intersectByItems() - * + * */ public function intersectByItems(array $arr): \VersatileCollections\CollectionInterface { @@ -2357,9 +2359,9 @@ public function intersectByItems(array $arr): \VersatileCollections\CollectionIn } /** - * + * * @see \VersatileCollections\CollectionInterface::intersectByKeysAndItems() - * + * */ public function intersectByKeysAndItems(array $arr): \VersatileCollections\CollectionInterface { @@ -2367,9 +2369,9 @@ public function intersectByKeysAndItems(array $arr): \VersatileCollections\Colle } /** - * + * * @see \VersatileCollections\CollectionInterface::intersectByKeysUsingCallback() - * + * */ public function intersectByKeysUsingCallback(array $arr, callable $key_comparator): \VersatileCollections\CollectionInterface { @@ -2377,9 +2379,9 @@ public function intersectByKeysUsingCallback(array $arr, callable $key_comparato } /** - * + * * @see \VersatileCollections\CollectionInterface::intersectByItemsUsingCallback() - * + * */ public function intersectByItemsUsingCallback(array $arr, callable $item_comparator): \VersatileCollections\CollectionInterface { @@ -2387,9 +2389,9 @@ public function intersectByItemsUsingCallback(array $arr, callable $item_compara } /** - * + * * @see \VersatileCollections\CollectionInterface::intersectByKeysAndItemsUsingCallbacks() - * + * */ public function intersectByKeysAndItemsUsingCallbacks(array $arr, callable $key_comparator=null, callable $item_comparator=null): \VersatileCollections\CollectionInterface{ diff --git a/src/FloatsCollection.php b/src/FloatsCollection.php index 1978d78..0563341 100644 --- a/src/FloatsCollection.php +++ b/src/FloatsCollection.php @@ -4,10 +4,10 @@ /** * Description of FloatsCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime diff --git a/src/IntsCollection.php b/src/IntsCollection.php index fc51851..477d2f9 100644 --- a/src/IntsCollection.php +++ b/src/IntsCollection.php @@ -4,10 +4,10 @@ /** * Description of IntsCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime diff --git a/src/NumericsCollection.php b/src/NumericsCollection.php index 5576c6b..4c5555e 100644 --- a/src/NumericsCollection.php +++ b/src/NumericsCollection.php @@ -7,7 +7,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -23,19 +23,19 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author rotimi */ class NumericsCollection extends ScalarsCollection { /** - * + * * @return int|float|null average all of the values in the collection or null if collection is empty - * + * * @used-for: mathematical-operations - * + * * @title: Returns the average of all of the values(a.k.a items) in the collection or null if collection is empty. - * + * */ public function average(): ?float { @@ -43,12 +43,12 @@ public function average(): ?float { } /** - * + * * This method should be overridden in sub-classes of this class - * + * * @param mixed $item * @return bool - * + * */ public function checkType($item): bool { @@ -56,11 +56,11 @@ public function checkType($item): bool { } /** - * + * * This method should be overridden in sub-classes of this class - * + * * @return string - * + * */ public function getType() { @@ -68,13 +68,13 @@ public function getType() { } /** - * + * * This method should be overridden in sub-classes of this class - * + * * @param string $str a string representation of an item in this collection - * + * * @return float|int an item in this collection that was just created from its string representation - * + * */ protected function itemFromString($str) { @@ -87,13 +87,13 @@ protected function itemFromString($str) { } /** - * + * * This method should be overridden in sub-classes of this class - * + * * @param mixed $item an item in this collection - * + * * @return string representation of an item in this collection - * + * */ protected function itemToString($item) { @@ -101,13 +101,13 @@ protected function itemToString($item) { } /** - * + * * @return int|float|null maximum of the values in the collection or null if collection is empty - * + * * @used-for: mathematical-operations - * + * * @title: Returns the maximum of all of the values(a.k.a items) in the collection or null if collection is empty. - * + * */ public function max(): ?float { @@ -115,13 +115,13 @@ public function max(): ?float { } /** - * + * * @return int|float|null median of the values in the collection or null if collection is empty - * + * * @used-for: mathematical-operations - * + * * @title: Returns the median of all of the values(a.k.a items) in the collection or null if collection is empty. - * + * */ public function median(): ?float { @@ -146,13 +146,13 @@ public function median(): ?float } /** - * + * * @return int|float|null minimum of the values in the collection or null if collection is empty - * + * * @used-for: mathematical-operations - * + * * @title: Returns the minimum of all of the values(a.k.a items) in the collection or null if collection is empty. - * + * */ public function min(): ?float { @@ -160,20 +160,20 @@ public function min(): ?float { } /** - * - * @return array|null an array of modal values in the collection. - * Returned array will have modal items in the same - * order as in the collection. + * + * @return array|null an array of modal values in the collection. + * Returned array will have modal items in the same + * order as in the collection. * Null is returned if the collection is empty. - * + * * Modal Items in the the collection that are floats like * `5.0`, `7.0` (i.e point zero) will be returned without * `.0`, in essence they are returned in integer format. - * + * * @used-for: mathematical-operations - * + * * @title: Returns an array of modal values(a.k.a items) in the collection or null if collection is empty. - * + * */ public function mode(): ?array { @@ -216,13 +216,13 @@ public function mode(): ?array { } /** - * + * * @return int|float the product of all values in the collection. - * + * * @used-for: mathematical-operations - * + * * @title: Returns the product of all of the values(a.k.a items) in the collection or one if collection is empty. - * + * */ public function product(): float { @@ -230,15 +230,15 @@ public function product(): float { } /** - * + * * Sum of all the values in this collection - * + * * @return float|int sum of all the values in this collection or zero if the collection is empty - * + * * @used-for: mathematical-operations - * + * * @title: Returns the sum of all of the values(a.k.a items) in the collection or zero if collection is empty. - * + * */ public function sum(): float { diff --git a/src/ObjectsCollection.php b/src/ObjectsCollection.php index 9e4d11b..9aa388f 100644 --- a/src/ObjectsCollection.php +++ b/src/ObjectsCollection.php @@ -4,10 +4,10 @@ /** * Description of ObjectsCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -23,7 +23,7 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author Rotimi Ade */ class ObjectsCollection implements \VersatileCollections\StrictlyTypedCollectionInterface { @@ -38,21 +38,21 @@ public function __construct(object ...$objects) { } /** - * + * * Call a method on each object in the collection. - * + * * The return value of each call (if any) is stored in an array keyed * on the object's key in the collection and this array is returned. - * + * * @param string $method_name * @param array $arguments - * + * * @used-for: other-operations - * + * * @title: Tries to call the specified method with the specified arguments and return its return value if it was registered via either `addMethod` or `addMethodForAllInstances` or tries to call the specified method with the specified arguments on each item in the collection and returns an array of return values keyed by each item's key in the collection. An exception of type **\VersatileCollections\Exceptions\InvalidCollectionOperationException** is thrown if the method could not be called. - * + * * @throws \Exception - * + * */ public function __call(string $method_name, array $arguments=[]) { diff --git a/src/ResourcesCollection.php b/src/ResourcesCollection.php index 0de55bd..19ad25a 100644 --- a/src/ResourcesCollection.php +++ b/src/ResourcesCollection.php @@ -3,12 +3,12 @@ namespace VersatileCollections; /** - * + * * Description of ResourcesCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime diff --git a/src/ScalarsCollection.php b/src/ScalarsCollection.php index 15a77ed..af48070 100644 --- a/src/ScalarsCollection.php +++ b/src/ScalarsCollection.php @@ -7,7 +7,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -23,7 +23,7 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author Rotimi Ade */ class ScalarsCollection implements \VersatileCollections\StrictlyTypedCollectionInterface { @@ -31,13 +31,13 @@ class ScalarsCollection implements \VersatileCollections\StrictlyTypedCollection use StrictlyTypedCollectionInterfaceImplementationTrait; /** - * + * * This method should be overridden in sub-classes of this class - * + * * @param mixed $item - * + * * @return bool - * + * */ public function checkType($item): bool { @@ -46,9 +46,9 @@ public function checkType($item): bool { /** * This method should be overridden in sub-classes of this class - * + * * @return string - * + * */ public function getType() { @@ -56,17 +56,17 @@ public function getType() { } /** - * + * * Get a collection of unique items from an existing collection. The keys * are not preserved in the returned collection. The uniqueness test is * done via loose comparison (==). - * + * * @return \VersatileCollections\CollectionInterface - * + * * @used-for: accessing-or-extracting-keys-or-items, creating-new-collections, modifying-keys - * + * * @title: Returns a new collection of unique items from an existing collection. This method uses non-strict comparison for testing uniqueness. The keys are not preserved in the returned collection. - * + * */ public function uniqueNonStrict(): \VersatileCollections\CollectionInterface { diff --git a/src/SpecificObjectsCollection.php b/src/SpecificObjectsCollection.php index 8c7cf40..c4eb2ac 100644 --- a/src/SpecificObjectsCollection.php +++ b/src/SpecificObjectsCollection.php @@ -4,10 +4,10 @@ /** * Description of SpecificObjectsCollection - * + * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -23,7 +23,7 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * */ final class SpecificObjectsCollection extends ObjectsCollection { @@ -53,17 +53,17 @@ protected function __construct(object ...$objects) { * its sub-classes or a new collection that stores any kind of object if no fully qualified class name * was specified (Essentially works like ObjectsCollection in the latter case). * - * @param string|null $class_name fully qualified name of the class whose instances or instances of its sub-classes alone would be stored in the collection. + * @param string|null $class_name fully qualified name of the class whose instances or instances of its sub-classes alone would be stored in the collection. * Set it to null to make the collection work exactly like an instance of ObjectsCollection * @param array $items an array of objects to be stored in the new collection * @param bool $preserve_keys true to use the same keys in $items in the collection, , else false to use sequentially incrementing numeric keys starting from zero - * + * * @return \VersatileCollections\StrictlyTypedCollectionInterface - * + * * @used-for: creating-new-collections - * + * * @title: Create a new collection that only stores instances of the specified fully qualified class name or its sub-classes or a new collection that stores any kind of object if no fully qualified class name was specified (Essentially works like ObjectsCollection in the latter case). - * + * */ public static function makeNewForSpecifiedClassName(?string $class_name=null, array $items =[], bool $preserve_keys=true): \VersatileCollections\StrictlyTypedCollectionInterface { @@ -108,9 +108,9 @@ public static function makeNewForSpecifiedClassName(?string $class_name=null, ar } /** - * + * * @return bool true if $item is of the expected type, else false - * + * */ public function checkType($item): bool { @@ -120,11 +120,11 @@ public function checkType($item): bool { } /** - * + * * @noRector \Rector\TypeDeclaration\Rector\ClassMethod\AddArrayReturnDocTypeRector - * - * @return string|array a string or array of strings of type name(s) for items acceptable in a collection * + * @return string|array a string or array of strings of type name(s) for items acceptable in a collection + * */ public function getType() { diff --git a/src/StrictlyTypedCollectionInterface.php b/src/StrictlyTypedCollectionInterface.php index f0bb3d4..590ce90 100644 --- a/src/StrictlyTypedCollectionInterface.php +++ b/src/StrictlyTypedCollectionInterface.php @@ -6,7 +6,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this interface: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -22,22 +22,22 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author Rotimi Ade */ interface StrictlyTypedCollectionInterface extends CollectionInterface { /** - * + * * @return bool true if $item is of the expected type, else false - * + * */ public function checkType($item): bool; /** - * + * * @return string|array a string or array of strings of type name(s) for items acceptable in a collection - * + * */ public function getType(); } diff --git a/src/StrictlyTypedCollectionInterfaceImplementationTrait.php b/src/StrictlyTypedCollectionInterfaceImplementationTrait.php index 93b8e03..1aee5e0 100644 --- a/src/StrictlyTypedCollectionInterfaceImplementationTrait.php +++ b/src/StrictlyTypedCollectionInterfaceImplementationTrait.php @@ -5,7 +5,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this trait: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -21,9 +21,9 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author Rotimi Ade - * + * */ trait StrictlyTypedCollectionInterfaceImplementationTrait { @@ -47,9 +47,9 @@ public function __construct(...$arr_objs) { } /** - * + * * @see \VersatileCollections\CollectionInterface::appendCollection() - * + * */ public function appendCollection(CollectionInterface $other): \VersatileCollections\CollectionInterface { @@ -93,9 +93,9 @@ protected function isRightTypeOrThrowInvalidTypeException($item, string $calling } /** - * + * * @see \VersatileCollections\CollectionInterface::offsetSet() - * + * */ public function offsetSet($key, $val): void { @@ -105,9 +105,9 @@ public function offsetSet($key, $val): void { } /** - * + * * @see \VersatileCollections\CollectionInterface::prependCollection() - * + * */ public function prependCollection(CollectionInterface $other): \VersatileCollections\CollectionInterface { @@ -129,9 +129,9 @@ public function prependCollection(CollectionInterface $other): \VersatileCollect } /** - * + * * @see \VersatileCollections\CollectionInterface::prependItem() - * + * */ public function prependItem($item, $key=null): \VersatileCollections\CollectionInterface { @@ -141,9 +141,9 @@ public function prependItem($item, $key=null): \VersatileCollections\CollectionI } /** - * + * * @see \VersatileCollections\CollectionInterface::unionMeWith() - * + * */ public function unionMeWith(array $items): \VersatileCollections\CollectionInterface { diff --git a/src/StringsCollection.php b/src/StringsCollection.php index f17a7e4..bf70f1a 100644 --- a/src/StringsCollection.php +++ b/src/StringsCollection.php @@ -7,7 +7,7 @@ * * Below is a list of acceptable value(s), that could be comma separated, * for the @used-for tag in phpdoc blocks for public methods in this class: - * + * * - accessing-or-extracting-keys-or-items * - adding-items * - adding-methods-at-runtime @@ -23,7 +23,7 @@ * - modifying-items * - ordering-or-sorting-items * - other-operations - * + * * @author rotimi */ class StringsCollection extends ScalarsCollection { diff --git a/src/helper-functions.php b/src/helper-functions.php index d07969f..fab030c 100644 --- a/src/helper-functions.php +++ b/src/helper-functions.php @@ -3,25 +3,25 @@ namespace VersatileCollections { /** - * + * * A robust way of retrieving the value of a specified property in * an instance of a class. - * + * * Works with \stdClass objects created from arrays with numeric key(s) * (the value of the propertie(s) with numeric key(s) in such \stdClass * objects will be retrieved by this function). - * + * * @param object $obj * @param string|int $property * @param mixed $default_val - * @param bool $access_private_or_protected true if value associated with private or protected property should be returned. - * If false is specified and you try to access a private or protected property, a + * @param bool $access_private_or_protected true if value associated with private or protected property should be returned. + * If false is specified and you try to access a private or protected property, a * \RuntimeException will be thrown. * @return mixed - * + * * @throws \InvalidArgumentException * @throws \RuntimeException - * + * */ function get_object_property_value(object $obj, $property, $default_val=null, bool $access_private_or_protected=false) { @@ -83,17 +83,17 @@ function get_object_property_value(object $obj, $property, $default_val=null, bo } /** - * + * * A more robust way than property_exists of checking if an instance of a class * has a specified property. - * + * * @param object $obj * @param string|int $property - * + * * @return bool - * + * * @throws \InvalidArgumentException - * + * */ function object_has_property(object $obj, $property) { @@ -131,7 +131,7 @@ function object_has_property(object $obj, $property) { } /** - * + * * A potentially more cryptographically secure way (as opposed to array_rand) * of getting a random key from an array. * If the system contains sources of randomness like: @@ -141,11 +141,11 @@ function object_has_property(object $obj, $property) { * If none of the aforementioned sources are available, then array_rand will be used. * * @param array $array array from which a random key is to be extracted - * + * * @return string|int a random key from the specified array - * + * * @throws \LengthException - * + * */ function random_array_key(array $array) { @@ -203,19 +203,19 @@ function random_array_key(array $array) { } /** - * + * * A potentially more cryptographically secure way (as opposed to array_rand) * of getting unique random keys from an array. - * + * * If the system contains sources of randomness like: * On Windows, » CryptGenRandom() will always be used. * On Linux, the » getrandom(2) syscall will be used if available. * On other platforms, /dev/urandom will be used. * If none of the aforementioned sources are available, then array_rand will be used. - * + * * @param array $array array from which a random keys are to be extracted * @param int $number_of_random_keys number of unique random keys to return - * + * * @return array an array of random keys * @throws \LengthException * @throws \InvalidArgumentException @@ -258,13 +258,13 @@ function random_array_keys(array $array, int $number_of_random_keys = 1): array } /** - * + * * Generate a (screen/user)-friendly string representation of a variable. - * + * * @param mixed $var - * + * * @return string a (screen / user)-friendly string representation of a variable - * + * */ function var_to_string($var): string { @@ -272,13 +272,13 @@ function var_to_string($var): string { } /** - * + * * Generate a (screen/user)-friendly string representation of a variable and print it out to the screen. - * + * * @param mixed $var - * + * * @return void - * + * */ function dump_var($var): void {