Permalink
Browse files

Merge pull request #7 from xi-project/move-and-groove

Added methods to Collection and updated documentation
  • Loading branch information...
2 parents be2faf0 + e42962d commit 6a47ac42fd49f4f68a1b8b3a573ae27c9f7b4e19 @Ezku Ezku committed Jan 23, 2013
View
112 README.md
@@ -12,7 +12,7 @@ Xi Collections aims to rectify the situation and inject your workflow with a hea
- _Object immutability._ The collections' methods do not manipulate the collections' contents, but return a new collection instead.
-- _API chainability._ No operation will return void and leave you in the dark; you'll always be able to continue where you left off.
+- _API chainability._ Most operations will return a new collection except specific reduces and size informations.
- _Embracing functional programming._ The Collections API is chosen to facilitate a functional workflow. Existing FP-compatible functionality in PHP is prioritized for inclusion to the API, and other important concepts that are missing are stolen from other languages and libraries.
@@ -156,50 +156,98 @@ Below is a short description of the APIs provided by Enumerable and Collection.
## Enumerable
-`tap`: Calls a provided callback with this object as a parameter
-`each`: Performs an operation once per key-value pair
-`reduce`: Uses a given callback to reduce the collection's elements to a single value, starting from a provided initial value
-`find`: Returns the first value that satisfies a given predicate
-`exists`: Checks whether the collection has at least one element satisfying a given predicate
-`forAll`: Checks whether all of the elements in the collection satisfy a given predicate
-`countAll`: Counts the amount of elements in the collection that satisfy a given predicate
+### Element retrieval
+
+- `first`: Returns the first element in the collection
+- `last`: Returns the last element in the collection
+- `find`: Returns the first value that satisfies a given predicate
+
+### Element conditions
+
+- `exists`: Checks whether the collection has at least one element satisfying a given predicate
+- `forAll`: Checks whether all of the elements in the collection satisfy a given predicate
+- `countAll`: Counts the amount of elements in the collection that satisfy a given predicate
+
+### Size information
+
+- `count`: Counts the amount of elements in the collection
+
+### Reduces
+
+- `reduce`: Uses a given callback to reduce the collection's elements to a single value, starting from a provided initial value
+
+### Invocations
+
+- `tap`: Calls a provided callback with this object as a parameter
+- `each`: Performs an operation once per key-value pair
## Collection
-`view`: Provides a Collection where transformer operations are applied lazily
-`apply`: Creates a new Collection of this type from the output of a given callback that takes this Collection as its argument
-`take`: Creates a new Collection with up to $number first elements from this one
-`map`: Applies a callback for each value-key-pair in the Collection and returns a new one with values replaced by the return values from the callback
-`filter`: Creates a Collection with the values of this collection that match a given predicate
-`concatenate`: Creates a Collection with elements from this and another one
-`union`: Creates a Collection with key-value pairs in the `$other` Collection overriding ones in `$this` Collection
-`values`: Get a Collection with just the values from this Collection
-`keys`: Get a Collection with the keys from this one as values
-`indexBy`: Reindex the Collection using a given callback
-`groupBy`: Group the values in the Collection into nested Collections according to a given callback
-`pick`: Get a Collection with a key or member property picked from each value
-`invoke`: Map this Collection by invoking a method on every value
-`flatten`: Flatten nested arrays and Traversables
-`unique`: Get a Collection with only the unique values from this one
-`sortWith`: Get this Collection sorted with a given comparison function
-`sortBy`: Get this Collection sorted with a given metric
+### Maps
+
+- `map`: Applies a callback for each value-key-pair in the Collection and returns a new one with values replaced by the return values from the callback
+- `flatMap`: Applies a callback for each key-value-pair in the Collection assuming that the callback result value is iterable and returns a new one with values from those iterable
+- `pick`: Get a Collection with a key or member property picked from each value
+- `values`: Get a Collection with just the values from this Collection
+- `keys`: Get a Collection with the keys from this one as values
+- `invoke`: Map this Collection by invoking a method on every value
+- `apply`: Creates a new Collection of this type from the output of a given callback that takes this Collection as its argument
+
+### Subcollections
+
+- `take`: Creates a new Collection with up to $number first elements from this one
+- `rest`: Creates a new Collection with the rest of the elements except first
+- `filter`: Creates a Collection with the values of this collection that match a given predicate
+- `filterNot`: Creates a collection with the values of this collection that do not match a given predicate
+- `unique`: Get a Collection with only the unique values from this one
+
+### Subdivisions
+
+- `partition`: Split a collection into a pair of two collections; one with elements that match a given predicate, the other with the elements that do not.
+- `groupBy`: Group the values in the Collection into nested Collections according to a given callback
+
+### Additions
+
+- `concatenate`: Creates a Collection with elements from this and another one
+- `union`: Creates a Collection with key-value pairs in the `$other` Collection overriding ones in `$this` Collection
+- `flatten`: Flatten nested arrays and Traversables
+- `add`: Get a new Collection with given value and optionally key appended
+
+### Size information
+
+- `isEmpty`: Checks whether the collection is empty
+
+### Sorts
+
+- `indexBy`: Reindex the Collection using a given callback
+- `sortWith`: Get this Collection sorted with a given comparison function
+- `sortBy`: Get this Collection sorted with a given metric
+
+### Views
+
+- `view`: Provides a Collection where transformer operations are applied lazily
+
+### Specific reduces
+
+- `min`: Returns the minimum value in the collection
+- `max`: Returns the maximum value in the collection
+- `sum`: Returns the sum of values in the collection
+- `product`: Returns the product of values in the collection
## CollectionView
-`force`: Coerces this view back into the underlying Collection type
+- `force`: Coerces this view back into the underlying Collection type
## Collection implementations
-`ArrayCollection`: Basic Collection backed by a plain PHP array.
-`OuterCollection`: A decorator for a Collection. Can easily be extended to provide more collection operations without locking down the implementation specifics.
+- `ArrayCollection`: Basic Collection backed by a plain PHP array.
+- `OuterCollection`: A decorator for a Collection. Can easily be extended to provide more collection operations without locking down the implementation specifics.
# Running the unit tests
- cd tests
- phpunit --bootstrap bootstrap.php Xi
+ phpunit -c tests
# TODO
- Collection implementations backed by SPL (SplFixedArray, SplDoublyLinkedList?)
-- Once PHP 5.4 is feasible to use, implementations can be significantly simplified using traits
-
+- Use traits?
@@ -1,44 +0,0 @@
-<?php
-
-namespace Xi\Collections;
-
-use Traversable;
-
-/**
- * Extends the Enumerable collection with aggregatable operations.
- *
- * @author Mikko Hirvonen <mikko.petteri.hirvonen@gmail.com>
- */
-interface Aggregatable extends Enumerable
-{
- /**
- * Create a new Aggregatable of this type. Implementations should take
- * advantage of late static binding, ie. this method should return an
- * instance of the class that is the receiver of the static method call.
- *
- * @param array|Traversable $elements
- * @return Aggregatable
- */
- public static function create($elements);
-
- /**
- * Returns the minimum value in the collection.
- *
- * @return mixed|null
- */
- public function min();
-
- /**
- * Returns the maximum value in the collection.
- *
- * @return mixed|null
- */
- public function max();
-
- /**
- * Returns the the sum of values in the collection.
- *
- * @return mixed|null
- */
- public function sum();
-}
@@ -1,70 +0,0 @@
-<?php
-
-namespace Xi\Collections\Aggregatable;
-
-use Xi\Collections\Aggregatable,
- Xi\Collections\Enumerable\ArrayEnumerable,
- Traversable;
-
-/**
- * Implements the Aggregatable operations with native array functions.
- *
- * @author Mikko Hirvonen <mikko.petteri.hirvonen@gmail.com>
- */
-class ArrayAggregatable extends ArrayEnumerable implements Aggregatable
-{
- /**
- * @param array|Traversable $elements
- * @return Aggregatable
- */
- public static function create($elements)
- {
- if ($elements instanceof Traversable) {
- $elements = iterator_to_array($elements, true);
- }
-
- return new static((array) $elements);
- }
-
- /**
- * Returns the minimum value in the collection.
- *
- * @return mixed|null
- */
- public function min()
- {
- return $this->applyOrNull('min');
- }
-
- /**
- * Returns the maximum value in the collection.
- *
- * @return mixed|null
- */
- public function max()
- {
- return $this->applyOrNull('max');
- }
-
- /**
- * Returns the the sum of values in the collection.
- *
- * @return mixed|null
- */
- public function sum()
- {
- return $this->applyOrNull('array_sum');
- }
-
- /**
- * Returns the value of the callback applied to the elements or null if
- * there are no elements.
- *
- * @param callback($elements) $callback
- * @return mixed|null
- */
- private function applyOrNull($callback)
- {
- return !empty($this->_elements) ? $callback($this->_elements) : null;
- }
-}
@@ -57,6 +57,14 @@ public function apply($callback);
public function take($number);
/**
+ * Creates a new Collection with the rest of the elements except first.
+ * Maintains index associations.
+ *
+ * @return Collection
+ */
+ public function rest();
+
+ /**
* Applies a callback for each value-key-pair in the Collection and returns
* a new one with values replaced by the return values from the callback.
* Maintains index associations.
@@ -77,6 +85,26 @@ public function map($callback);
public function filter($predicate = null);
/**
+ * Creates a collection with the values of this collection that do not match
+ * a given predicate. If the predicate is omitted, the values will simply be
+ * checked for falsiness. Maintains index associations.
+ *
+ * @param callable($value, $key) $predicate
+ * @return mixed
+ */
+ public function filterNot($predicate = null);
+
+ /**
+ * Split a collection into a pair of two collections; one with elements that
+ * match a given predicate, the other with the elements that do not.
+ * Maintains index associations.
+ *
+ * @param callable($value, $key) $predicate
+ * @return Collection
+ */
+ public function partition($predicate);
+
+ /**
* Creates a Collection with elements from this and another one. Does not
* maintain index associations.
*
@@ -191,4 +219,39 @@ public function sortBy($metric);
* @return Collection
*/
public function add($value, $key = null);
+
+ /**
+ * Returns the minimum value in the collection.
+ *
+ * @return mixed|null
+ */
+ public function min();
+
+ /**
+ * Returns the maximum value in the collection.
+ *
+ * @return mixed|null
+ */
+ public function max();
+
+ /**
+ * Returns the sum of values in the collection.
+ *
+ * @return mixed|null
+ */
+ public function sum();
+
+ /**
+ * Returns the product of values in the collection.
+ *
+ * @return mixed|null
+ */
+ public function product();
+
+ /**
+ * Checks whether the collection is empty.
+ *
+ * @return boolean
+ */
+ public function isEmpty();
}
Oops, something went wrong.

0 comments on commit 6a47ac4

Please sign in to comment.