add all files

Author: Erikvv

.gitignore

@@ -0,0 +1 @@
+vendor

Readme.md

@@ -0,0 +1,4 @@
+
+# Array Utilities
+
+Useful functions for those programmers who like to do array transformations and like to think in higher-order concepts.

src/Ve/functions/categorize.php

@@ -0,0 +1,46 @@
+<?php
+
+namespace Ve;
+
+/**
+ * this function is for when the property is an object which should be compared by identity
+ * (this could be doctrine entities with a many-to-one relation to a type table)
+ *
+ * You would not be able to use the "group" functions because an object cannot be a key in an associative array
+ *
+ * @param Traversable $objects
+ * @param string $property to compare by object identity
+ * @param string $collectionName key under which the objects will be stored in the category
+ *
+ * @return [
+ * 		[
+ * 			$propertyName   => $propertyValue
+ * 			$collectionName => $categorizedObjects
+ * 		]
+ * 		...
+ * ]
+ */
+function categorizeByPropertyIdentity($objects, string $property, string $collectionName = 'objects'): array
+{
+	$result = [];
+
+	foreach ($objects as $obj)
+	{
+		foreach ($result as &$category)
+		{
+			if ($category[$property] === $obj->$property)
+			{
+                // add to existing category
+				$category[$collectionName][] = $obj;
+				continue 2;
+			}
+		}
+        // create a new category
+		$result[] = [
+			$property       => $obj->$property,
+			$collectionName => [$obj]
+		];
+	}
+
+	return $result;
+}

src/Ve/functions/filter.php

@@ -0,0 +1,181 @@
+<?php
+
+/**
+ * functions:
+ * - filter
+ * - reject
+ * - where
+ * - whereNot
+ * - find
+ * - findWhere
+ */
+
+namespace Ve;
+
+/**
+ * this exists because array_filter can't call methods
+ */
+function filter($objects, string $method): array
+{
+	$result = [];
+	foreach ($objects as $obj)
+	{
+		if (call_user_func([$obj, $method]))
+		{
+			$result[] = $obj;
+		}
+	}
+	return $result;
+}
+
+/**
+ * opposite of filter
+ */
+function reject($objects, string $method): array
+{
+	$result = [];
+	foreach ($objects as $obj)
+	{
+		if (! call_user_func([$obj, $method]))
+		{
+			$result[] = $obj;
+		}
+	}
+	return $result;
+}
+
+/**
+ * logic like filter but is guaranteed to return a single result, else an exeption is thrown
+ */
+function find($objects, callable $fn)
+{
+	foreach ($objects as $obj)
+	{
+		if (call_user_func($fn, $obj))
+		{
+			return $obj;
+		}
+	}
+	throw new \LengthException;
+}
+
+
+/**
+ * Same as self::where, except guarantees to find 1 instance else an exception is thrown
+ * Short-circuit optimization possible
+ */
+function findWhere($objects, array $keyValuePair)
+{
+	$resultCollection = where($objects, $keyValuePair);
+
+	if (count($resultCollection) !== 1)
+	{
+		throw new \LengthException;
+	}
+
+	return $resultCollection[0];
+}
+
+/**
+ * Filters the input by property
+ *
+ * Possible improvement: allow multiple key-value pairs
+ *
+ * @param array|Traversable $objects
+ */
+function where($objects, array $keyValuePair): array
+{
+	$property = array_keys($keyValuePair)[0];
+	$value = array_values($keyValuePair)[0];
+
+	$result = [];
+
+	foreach ($objects as $obj)
+	{
+		if (is_object($obj))
+		{
+			if (property_exists($obj, $property))
+			{
+				if ($obj->$property === $value)
+				{
+					$result[] = $obj;
+				}
+			}
+			elseif (method_exists($obj, $property))
+			{
+				if (call_user_func([$obj, $method]) === $value)
+				{
+					$result[] = $obj;
+				}
+			}
+			else
+			{
+				throw new \InvalidArgumentException;
+			}
+		}
+		elseif (is_array($obj))
+		{
+			if ($obj[$property] === $value)
+			{
+				$result[] = $obj;
+			}
+		}
+		else
+		{
+			throw new \InvalidArgumentException;
+		}
+	}
+	return $result;
+}
+
+/**
+ * Filters the input by property
+ *
+ * Possible improvement: allow multiple key-value pairs
+ *
+ * @param array|Traversable $objects
+ */
+function whereNot($objects, array $keyValuePair): array
+{
+	$property = array_keys($keyValuePair)[0];
+	$value = array_values($keyValuePair)[0];
+
+	$result = [];
+
+	foreach ($objects as $obj)
+	{
+		if (is_object($obj))
+		{
+			if (property_exists($obj, $property))
+			{
+				if ($obj->$property !== $value)
+				{
+					$result[] = $obj;
+				}
+			}
+			elseif (method_exists($obj, $property))
+			{
+				if (call_user_func([$obj, $method]) !== $value)
+				{
+					$result[] = $obj;
+				}
+			}
+			else
+			{
+				throw new \InvalidArgumentException;
+			}
+		}
+		elseif (is_array($obj))
+		{
+			if ($obj[$property] !== $value)
+			{
+				$result[] = $obj;
+			}
+		}
+		else
+		{
+			throw new \InvalidArgumentException;
+		}
+	}
+	return $result;
+}

src/Ve/functions/group.php

@@ -0,0 +1,68 @@
+<?php
+
+namespace Ve;
+
+/**
+ * @var objects array|traversable of objects
+ * @var $properties property to group by.
+ * 			If multiple are given they are treated as nested properties ($obj->prop1->prop2->prop3)
+ * @return array nested in groups
+ */
+function groupByProperty($objects, string ...$properties): array
+{
+	$result = [];
+	foreach ($objects as $obj)
+	{
+		$value = $obj;
+		foreach ($properties as $prop)
+		{
+			$value = $value->$prop;
+		}
+		$result[$value][] = $obj;
+	}
+	return $result;
+}
+
+function groupByMethod($objects, string $method): array
+{
+	$result = [];
+	foreach ($objects as $obj)
+	{
+		$result[call_user_func([$obj, $method])][] = $obj;
+	}
+	return $result;
+}
+
+function groupByCallable($list, callable $callable): array
+{
+	$result = [];
+	foreach ($list as $var)
+	{
+		$result[call_user_func($callable, $var)][] = $var;
+	}
+	return $result;
+}
+
+/**
+ * @param Traversable|array $list
+ * @param \Callable $equals
+ * --> with signature function(var1, var2): bool
+ * --> equality is assumed to be transitive
+ */
+function groupByEquality($list, callable $equals): array
+{
+	$result = [];
+	foreach ($list as $var)
+	{
+		foreach($result as &$group)
+		{
+			if (call_user_func($equals, $group[0], $var))
+			{
+				$group[] = $var;
+				continue 2;
+			}
+		}
+		$result[] = [$var]; // create a new group
+	}
+	return $result;
+}

src/Ve/functions/map.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Ve;
+
+/**
+ * calls a method on all objects
+ *
+ * @param $objects array|Traversable
+ * @param $method string
+ */
+function map($objects, string $method): array
+{
+    $result = [];
+
+    foreach ($objects as $obj)
+    {
+        $result[] = $obj->$method();
+    }
+
+    return $result;
+}
+
+/**
+ * gets a property from all objects
+ *
+ * @param $objects array|Traversable
+ * @param $property string
+ */
+function pluck($objects, string $property): array
+{
+    $result = [];
+
+    foreach ($objects as $obj)
+    {
+        $result[] = $obj->property;
+    }
+
+    return $result;
+}
+
+/**
+ * array_map does not allow us to
+ *         (1) access keys of the input or
+ *        (2) determine the keys of the output
+ * without getting rather creative with array_keys, array_flip
+ * or using array_walk, which is impure and does not allow to create new keys
+ *
+ * this function can do both
+ *
+ * the callback MUST return an array (because of the output key)
+ * the resulting arrays will be merged
+ */
+function mapWithKey(array $array, callable $fn)
+{
+	$result = [];
+
+	foreach ($array as $key => $value)
+	{
+		$result += $fn($value, $key);
+	}
+
+	return $result;
+}
+
+/**
+ * Helper to build and associative array of properties from a collection of objects,
+ * e.g. from object ID's to object properties
+ */
+function buildAssoc(array $objects, string $keyProperty, string $valueProperty): array
+{
+	$keys   = pluck($objects, $keyProperty);
+	$values = pluck($objects, $valueProperty);
+
+	return array_combine($keys, $values);
+}