Skip to content

Latest commit

 

History

History
317 lines (265 loc) · 42.5 KB

MethodsByCategory.md

File metadata and controls

317 lines (265 loc) · 42.5 KB
Raw

Collection Methods by Category

Accessing or Extracting Keys and / or Items in a Collection

  • VersatileCollections\CollectionInterface

    • __get: Retrieves an item associated with a specified key in the collection.
    • column: 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.
    • diff: Returns a new collection containing items in an existing collection that are not present in the specified array of items.
    • diffAssoc: Returns a new collection containing items in an existing collection whose keys and values are not present in the specified array of items.
    • diffAssocUsing: 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.
    • diffKeys: Returns a new collection containing items in an existing collection whose keys are not present in the specified array of items.
    • diffKeysUsing: 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.
    • diffUsing: 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.
    • each: Iterates through a collection and executes a callback over each item.
    • firstItem: Returns the first item in the collection or null if the collection is empty.
    • getAllWhereKeysIn: Returns a new collection of items from an existing collection whose keys are present in the specified keys.
    • getAllWhereKeysNotIn: Returns a new collection of items from an existing collection whose keys are not present in the specified keys.
    • getAndRemoveFirstItem: Returns and removes the first item in a collection.
    • getAndRemoveLastItem: Removes and returns the last item from a collection.
    • getIfExists: Returns the item in the collection with the specified key (if such an item exists) or the specified default value otherwise.
    • getItems: 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.
    • getKeys: Returns a new instance of \VersatileCollections\GenericCollection containing all the keys in the original collection.
    • intersectByItems: Returns a new collection of items from an existing collection that are present in an array of specified items.
    • intersectByItemsUsingCallback: 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.
    • intersectByKeys: Returns a new collection of items from an existing collection whose keys are present in an array of specified keys.
    • intersectByKeysAndItems: Returns a new collection of items from an existing collection whose keys and corresponding items are present in an array of specified items.
    • intersectByKeysAndItemsUsingCallbacks: 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.
    • intersectByKeysUsingCallback: 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.
    • lastItem: Returns the last item in the collection or null if the collection is empty.
    • map: 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.
    • offsetGet: Retrieves an item associated with a specified key in the collection.
    • paginate: Returns a new collection of at most a specified number of items present in the specified page.
    • pull: Removes and returns the item with the specified key from a collection (if it exists) or returns a default value.
    • randomItem: Gets one item randomly from a collection.
    • randomItems: Gets a specified number of items randomly from a collection and returns them in a new collection.
    • randomKey: Gets one key randomly from a collection.
    • randomKeys: Gets a specified number of unique keys randomly from a collection and returns them in a new collection.
    • reduce: Iteratively reduces the collection items to a single value using a callback function.
    • reduceWithKeyAccess: Iteratively reduces the collection items to a single value using a callback function.
    • searchAllByVal: 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.
    • searchByCallback: 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.
    • searchByVal: 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.
    • slice: Extracts a slice from a collection and returns the slice as a new collection. The original collection is not modified.
    • splice: Removes and returns in a new collection, a portion of a collection and optionally replaces the removed portion with some specified items.
    • take: Returns the first or last specified number of items in a collection in a new collection. Original collection is not modified.
    • toArray: Returns all items in the collection and their corresponding keys in an array.
    • unique: 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.

  • VersatileCollections\ScalarsCollection

    • uniqueNonStrict: 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.

Adding Items to a Collection

  • VersatileCollections\CollectionInterface
    • __set: Adds an item with a specified key to the collection.
    • appendCollection: Appends all items from a specified collection to the end of a collection. Note that appended items will be assigned numeric keys.
    • appendItem: Appends a specified item to the end of a collection.
    • mergeMeWith: 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.
    • mergeWith: 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.
    • offsetSet: Adds an item with a specified key to the collection.
    • prependCollection: Prepends all items from a specified collection to the front of a collection.
    • prependItem: Prepends a specified item (with a specified key, if specified) to the front of a collection.
    • push: Appends a specified item to the end of a collection.
    • put: Adds a specified key and item pair to a collection. If the specified key already exists, the specified item will overwrite the existing item.
    • unionMeWith: 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.
    • unionWith: 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.

Adding Methods to a Collection at Runtime

  • VersatileCollections\CollectionInterfaceImplementationTrait
    • addMethod: 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.
    • addMethodForAllInstances: 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.
    • addStaticMethod: 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.

Checking if Item(s) exist in a Collection

  • VersatileCollections\CollectionInterface
    • __isset: Checks if an item with a specified key exists in the collection.
    • containsItem: Checks if a collection contains a specified item (using strict comparison).
    • containsItemWithKey: Checks if a collection contains a specified item (using strict comparison) together with the specified key.
    • containsItems: Checks if a collection contains all specified items (using strict comparison for each comparison).
    • getIfExists: Returns the item in the collection with the specified key (if such an item exists) or the specified default value otherwise.
    • offsetExists: Checks if an item with a specified key exists in the collection.

Checking if Key(s) exist in a Collection

  • VersatileCollections\CollectionInterface
    • containsItemWithKey: Checks if a collection contains a specified item (using strict comparison) together with the specified key.
    • containsKey: Checks if a collection contains a specified key.
    • containsKeys: Checks if a collection contains all specified keys.

Creating Collections

  • VersatileCollections\CollectionInterface

    • diff: Returns a new collection containing items in an existing collection that are not present in the specified array of items.
    • diffAssoc: Returns a new collection containing items in an existing collection whose keys and values are not present in the specified array of items.
    • diffAssocUsing: 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.
    • diffKeys: Returns a new collection containing items in an existing collection whose keys are not present in the specified array of items.
    • diffKeysUsing: 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.
    • diffUsing: 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.
    • everyNth: Creates a new collection consisting of every n-th element in a collection.
    • filterAll: Filters out items in the collection via a callback function and returns filtered items in a new collection.
    • filterFirstN: Filters out the first N items in the collection via a callback function and returns filtered items in a new collection.
    • getAllWhereKeysIn: Returns a new collection of items from an existing collection whose keys are present in the specified keys.
    • getAllWhereKeysNotIn: Returns a new collection of items from an existing collection whose keys are not present in the specified keys.
    • getAsNewType: 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.
    • getCollectionsOfSizeN: Returns a collection of collections; with each sub-collection having a specified maximum number of items. Original keys are preserved in each sub-collection.
    • getItems: 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.
    • getKeys: Returns a new instance of \VersatileCollections\GenericCollection containing all the keys in the original collection.
    • intersectByItems: Returns a new collection of items from an existing collection that are present in an array of specified items.
    • intersectByItemsUsingCallback: 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.
    • intersectByKeys: Returns a new collection of items from an existing collection whose keys are present in an array of specified keys.
    • intersectByKeysAndItems: Returns a new collection of items from an existing collection whose keys and corresponding items are present in an array of specified items.
    • intersectByKeysAndItemsUsingCallbacks: 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.
    • intersectByKeysUsingCallback: 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.
    • makeNew: Creates a new collection from an iterable of items. Items must be rightly typed if collection class is strictly typed.
    • map: 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.
    • mergeWith: 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.
    • paginate: Returns a new collection of at most a specified number of items present in the specified page.
    • reverse: Reverses the order of items in the collection and returns the reversed items in a new collection.
    • shuffle: Shuffles all the items in a collection and returns the shuffled items in a new collection. The original collection is not modified.
    • slice: Extracts a slice from a collection and returns the slice as a new collection. The original collection is not modified.
    • sort: 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.
    • sortByKey: 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.
    • sortByMultipleFields: 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.
    • sortDesc: 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.
    • sortDescByKey: 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.
    • splice: Removes and returns in a new collection, a portion of a collection and optionally replaces the removed portion with some specified items.
    • split: Splits a collection into a specified number of collections and returns a collection containing those collections.
    • take: Returns the first or last specified number of items in a collection in a new collection. Original collection is not modified.
    • unionWith: 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.
    • unique: 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.
    • yieldCollectionsOfSizeN: Returns a generator that yields collections each having a specified maximum number of items. Original keys are preserved in each returned collection.

  • VersatileCollections\ScalarsCollection

    • uniqueNonStrict: 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.

  • VersatileCollections\SpecificObjectsCollection

    • makeNewForSpecifiedClassName: 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).

Deleting Items from a Collection

  • VersatileCollections\CollectionInterface
    • __unset: Removes an item associated with the specified key from the collection.
    • getAndRemoveFirstItem: Returns and removes the first item in a collection.
    • getAndRemoveLastItem: Removes and returns the last item from a collection.
    • offsetUnset: Removes an item associated with the specified key from the collection.
    • pull: Removes and returns the item with the specified key from a collection (if it exists) or returns a default value.
    • removeAll: Removes items from a collection (whose keys are specified) or (all items if no keys were specified).
    • splice: Removes and returns in a new collection, a portion of a collection and optionally replaces the removed portion with some specified items.

Finding or Searching for Items in a Collection

  • VersatileCollections\CollectionInterface
    • diff: Returns a new collection containing items in an existing collection that are not present in the specified array of items.
    • diffAssoc: Returns a new collection containing items in an existing collection whose keys and values are not present in the specified array of items.
    • diffAssocUsing: 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.
    • diffKeys: Returns a new collection containing items in an existing collection whose keys are not present in the specified array of items.
    • diffKeysUsing: 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.
    • diffUsing: 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.
    • filterAll: Filters out items in the collection via a callback function and returns filtered items in a new collection.
    • filterFirstN: Filters out the first N items in the collection via a callback function and returns filtered items in a new collection.
    • getAllWhereKeysIn: Returns a new collection of items from an existing collection whose keys are present in the specified keys.
    • getAllWhereKeysNotIn: Returns a new collection of items from an existing collection whose keys are not present in the specified keys.
    • intersectByItems: Returns a new collection of items from an existing collection that are present in an array of specified items.
    • intersectByItemsUsingCallback: 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.
    • intersectByKeys: Returns a new collection of items from an existing collection whose keys are present in an array of specified keys.
    • intersectByKeysAndItems: Returns a new collection of items from an existing collection whose keys and corresponding items are present in an array of specified items.
    • intersectByKeysAndItemsUsingCallbacks: 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.
    • intersectByKeysUsingCallback: 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.
    • searchAllByVal: 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.
    • searchByCallback: 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.
    • searchByVal: 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.

Getting Information about a Collection

  • VersatileCollections\CollectionInterface
    • count: Returns the number of items in the collection.
    • getKeys: Returns a new instance of \VersatileCollections\GenericCollection containing all the keys in the original collection.
    • isEmpty: Returns true if there are one or more items in the collection or false otherwise.

Looping / Iterating through a Collection

  • VersatileCollections\CollectionInterface
    • each: Iterates through a collection and executes a callback over each item.
    • getIterator: Returns an Iterator object that can be used to iterate through the collection.
    • map: 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.
    • reduce: Iteratively reduces the collection items to a single value using a callback function.
    • reduceWithKeyAccess: Iteratively reduces the collection items to a single value using a callback function.
    • transform: Transforms each item in the collection via a callback function.

Mathematical Operations on Numeric Collections

  • VersatileCollections\NumericsCollection
    • average: Returns the average of all of the values(a.k.a items) in the collection or null if collection is empty.
    • max: Returns the maximum of all of the values(a.k.a items) in the collection or null if collection is empty.
    • median: Returns the median of all of the values(a.k.a items) in the collection or null if collection is empty.
    • min: Returns the minimum of all of the values(a.k.a items) in the collection or null if collection is empty.
    • mode: Returns an array of modal values(a.k.a items) in the collection or null if collection is empty.
    • product: Returns the product of all of the values(a.k.a items) in the collection or one if collection is empty.
    • sum: Returns the sum of all of the values(a.k.a items) in the collection or zero if collection is empty.

Modifying the Item(s) in a Collection

  • VersatileCollections\CollectionInterface
    • setValForEachItem: Sets the specified field in each array or object in the collection to a specified value.
    • splice: Removes and returns in a new collection, a portion of a collection and optionally replaces the removed portion with some specified items.
    • transform: Transforms each item in the collection via a callback function.

Modifying the Key(s) in a Collection

  • VersatileCollections\CollectionInterface

    • getItems: 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.
    • makeAllKeysNumeric: Converts all keys in a collection to consecutive integer keys starting from the specified integer value.
    • unique: 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.

  • VersatileCollections\ScalarsCollection

    • uniqueNonStrict: 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.

Ordering or Sorting or Shuffling / Randomizing Items in a Collection

  • VersatileCollections\CollectionInterface
    • randomItem: Gets one item randomly from a collection.
    • randomItems: Gets a specified number of items randomly from a collection and returns them in a new collection.
    • randomKey: Gets one key randomly from a collection.
    • randomKeys: Gets a specified number of unique keys randomly from a collection and returns them in a new collection.
    • reverse: Reverses the order of items in the collection and returns the reversed items in a new collection.
    • reverseMe: Reverses the order of items in the collection. Original collection is modified.
    • shuffle: Shuffles all the items in a collection and returns the shuffled items in a new collection. The original collection is not modified.
    • sort: 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.
    • sortByKey: 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.
    • sortByMultipleFields: 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.
    • sortDesc: 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.
    • sortDescByKey: 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.
    • sortMe: Sorts a collection's items in ascending order while maintaining key association. The original collection is modified.
    • sortMeByKey: Sorts a collection's items by keys in ascending order while maintaining key association. The original collection is modified.
    • sortMeByMultipleFields: Sorts a collection of associative arrays or objects by specified field name(s) while maintaining key association. The original collection is modified.
    • sortMeDesc: Sorts a collection's items in descending order while maintaining key association. The original collection is modified.
    • sortMeDescByKey: Sorts a collection's items by keys in descending order while maintaining key association. The original collection is modified.

Other Collection Operations

  • VersatileCollections\CollectionInterface

    • allSatisfyConditions: 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.
    • pipeAndReturnCallbackResult: Executes the given callback on a collection and returns whatever value the callback returned.
    • pipeAndReturnSelf: Executes the given callback on a collection and returns the collection itself.
    • tap: Invokes a specified callback on a copy of a collection and returns the original collection.
    • whenFalse: 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.
    • whenTrue: 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.

  • VersatileCollections\ObjectsCollection

    • __call: 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.

  • VersatileCollections\CollectionInterfaceImplementationTrait

    • __call: 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.
    • __callStatic: 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.