Summation Collection
A collection of numeric values, which are typically a product of processing multiple items, e.g. database records. Most commonly, you would use this component in combination with an Items Processor.
Within this context, the term "summation" is referred to as a "[...] cumulative action or effect [...]" (Merriam Webster).
Basic Example
use Aedart\Collections\Summation;
$collection = Summation::make([
'points' => 0
]);
$result = $collection
->increase('points', 5)
->decrease('points', 1)
->get('points');
echo $result; // 4
Setting initial values
To work with a Summation
collection, you must first set the initial value(s), which you later wish to process in some way. You can either state them when you create a new instance (e.g. via the make()
method), or by using the set()
method.
$collection = Summation::make([
'strength' => 15,
'agility' => 22,
'intelligence' => 19,
]);
// Or...
$collection = Summation::make()
->set('strength', 15)
->set('agility', 22)
->set('intelligence', 19);
Processing values
Increase
Use the increase()
or add()
method to increase a key's value with a given amount.
$result = Summation::make()
->set('points', 0)
->increase('points', 5)
->add('points', 1)
->get('points');
echo $result; // 6
Decrease
To decrease a key's value, you can use the decrease()
or subtract()
method.
$result = Summation::make()
->set('points', 25)
->decrease('points', 5)
->subtract('points', 1)
->get('points');
echo $result; // 19
Multiply
You can multiple an existing key's value using the multiply()
method.
$result = Summation::make()
->set('points', 5)
->multiply('points', 5)
->get('points');
echo $result; // 25
Divide
To divide and existing key's value, use the divide()
method.
$result = Summation::make()
->set('points', 25)
->divide('points', 3)
->get('points');
echo $result; // 8.3333
Apply Callback
All processing methods accept a callable
as a value, in which you can process a given key's value, however you want. The result of the given callback is the used as the key's new value.
$result = Summation::make()
->set('points', 25)
->set('amount', 8)
->set('points', function($value, Summation $summation) {
return $value / $summation->get('amount');
})
->get('points');
echo $result; // 3.125
Dot notation
Laravel's "dot notation" is also supported by the Summation
collection component.
$result = Summation::make()
->set('player.strength', 16)
->increase('player.strength', 2)
->get('player.strength');
echo $result; // 18
Determine keys and values
Has key
The has()
method can be used to determine whether a key exists in the collection or not.
$collection->has('score'); // true or false
Note
The has()
will return true
if a key exists, even if the key's value is zero (empty).
Has value
To determine if a key exists and has a value (nonempty value), use the hasValue()
method.
$collection->hasValue('score'); // true if key exists and has a nonempty value
Removing keys
A key and it's associated value can be deleted by using the remove()
method.
$collection->remove('player.intelligence');
Exporting
To Array
The toArray()
method will export all keys and values to a native php array
.
$arr = $collection->toArray();
To Json
If you wish to retrieve a Json representation of the collection, you can either use the toJson()
method or invoke json_encode()
directly on the collection.
$result = $collection->toJson();
// Or...
$result = json_encode($collection);
Debugging
Prerequisite
To use the debugging methods, you must have symfony/var-dumper
installed.
The dd()
method will dump the collection's keys and values and stop further script execution.
$collection->dd(); // Dumps keys and values and STOPS script execution!
The dump()
method, on the other hand, will only dump the collection's keys and values.
$result = $collection
->set('points', 5)
->increase('points', 1)
->dump() // Dumps keys and values
->decrease('points', 2)
->get('points');
echo $result; // 4