Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:120451
Content-Type: multipart/alternative;
	boundary="Apple-Mail=_3B4D8BC6-6256-4AB6-BC9D-B71E2D803898"
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3731.600.7\))
Message-ID: <289E585B-EF8B-4B17-89BE-BE8295FD9FE1@gmail.com>
Date: Tue, 30 May 2023 13:34:49 +0200
To: internals@lists.php.net
Subject: [RFC] [Discussion] Add new function `array_group`
From: buritomath@gmail.com (Boro Sitnikovski)

--Apple-Mail=_3B4D8BC6-6256-4AB6-BC9D-B71E2D803898
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain;
	charset=utf-8

Hello all,

As per the How To Create an RFC <https://wiki.php.net/rfc/howto> =
instructions, I am sending this e-mail in order to get your feedback on =
my proposal.

I propose introducing a function to PHP core named `array_group`. This =
function takes an array and a function and returns an array that =
contains arrays - groups of consecutive elements. This is very similar =
to Haskell's `groupBy` function =
<https://hackage.haskell.org/package/groupBy-0.1.0.0/docs/Data-List-GroupB=
y.html>.

For some background as to why - usually, when people want to do grouping =
in PHP, they use hash maps, so something like:

```
<?php
$array =3D [
	[ 'id' =3D> 1, 'value' =3D> 'foo' ],
	[ 'id' =3D> 1, 'value' =3D> 'bar' ],
	[ 'id' =3D> 2, 'value' =3D> 'baz' ],
];

$groups =3D [];
foreach ( $array as $element ) {
    $groups[ $element['id'] ][] =3D $element;
}

var_dump( $groups );
```

This can now be achieved as follows (not preserving keys):

```
<?php
$array =3D [
	[ 'id' =3D> 1, 'value' =3D> 'foo' ],
	[ 'id' =3D> 1, 'value' =3D> 'bar' ],
	[ 'id' =3D> 2, 'value' =3D> 'baz' ],
];

$groups =3D array_group( $array, function( $a, $b ) {
	return $a['id'] =3D=3D $b['id'];
} );
```

The disadvantage of the first approach is that we are only limited to =
using equality check, and we cannot group by, say, `<` or other =
functions.
Similarly, the advantage of the first approach is that the keys are =
preserved, and elements needn't be consecutive.

In any case, I think a utility function such as `array_group` will be =
widely useful.

Please find attached a patch with a proposed implementation. Curious =
about your feedback.

Best,

Boro Sitnikovski <https://people.php.net/bor0>

=EF=BF=BC=

--Apple-Mail=_3B4D8BC6-6256-4AB6-BC9D-B71E2D803898
Content-Type: multipart/mixed;
	boundary="Apple-Mail=_7312EF78-3546-44DC-B65E-7C2DCBF69A36"


--Apple-Mail=_7312EF78-3546-44DC-B65E-7C2DCBF69A36
Content-Transfer-Encoding: quoted-printable
Content-Type: text/html;
	charset=us-ascii

<html><head><meta http-equiv=3D"content-type" content=3D"text/html; =
charset=3Dus-ascii"></head><body style=3D"overflow-wrap: break-word; =
-webkit-nbsp-mode: space; line-break: after-white-space;"><div>Hello =
all,</div><div><br></div><div>As per the&nbsp;<a =
href=3D"https://wiki.php.net/rfc/howto">How To Create an =
RFC</a>&nbsp;instructions, I am sending this e-mail in order to get your =
feedback on my proposal.</div><div><br></div><div>I propose introducing =
a function to PHP core named `array_group`. This function takes an array =
and a function and returns an array that contains arrays - groups of =
consecutive elements. This is very similar to Haskell's&nbsp;<a =
href=3D"https://hackage.haskell.org/package/groupBy-0.1.0.0/docs/Data-List=
-GroupBy.html">`groupBy` function</a>.</div><div><br></div><div>For some =
background as to why - usually, when people want to do grouping in PHP, =
they use hash maps, so something =
like:</div><div><br></div><div>```</div><div><div>&lt;?php</div><div>$arra=
y =3D [</div><div><span class=3D"Apple-tab-span" style=3D"white-space: =
pre;">	</span>[ 'id' =3D&gt; 1, 'value' =3D&gt; 'foo' =
],</div><div><span class=3D"Apple-tab-span" style=3D"white-space: pre;">	=
</span>[ 'id' =3D&gt; 1, 'value' =3D&gt; 'bar' ],</div><div><span =
class=3D"Apple-tab-span" style=3D"white-space: pre;">	</span>[ 'id' =
=3D&gt; 2, 'value' =3D&gt; 'baz' =
],</div><div>];</div><div><br></div><div>$groups =3D =
[];</div><div>foreach ( $array as $element ) {</div><div>&nbsp; &nbsp; =
$groups[ $element['id'] ][] =3D =
$element;</div><div>}</div><div><br></div><div>var_dump( $groups =
);</div></div><div>```</div><div><br></div><div>This can now be achieved =
as follows (not preserving =
keys):</div><div><br></div><div>```</div><div><div>&lt;?php</div><div>$arr=
ay =3D [</div><div><span class=3D"Apple-tab-span" style=3D"white-space: =
pre;">	</span>[ 'id' =3D&gt; 1, 'value' =3D&gt; 'foo' =
],</div><div><span class=3D"Apple-tab-span" style=3D"white-space: pre;">	=
</span>[ 'id' =3D&gt; 1, 'value' =3D&gt; 'bar' ],</div><div><span =
class=3D"Apple-tab-span" style=3D"white-space: pre;">	</span>[ 'id' =
=3D&gt; 2, 'value' =3D&gt; 'baz' =
],</div><div>];</div><div><br></div><div>$groups =3D array_group( =
$array, function( $a, $b ) {</div><div><span class=3D"Apple-tab-span" =
style=3D"white-space: pre;">	</span>return $a['id'] =3D=3D =
$b['id'];</div><div>} =
);</div><div>```</div></div><div><br></div><div>The disadvantage of the =
first approach is that we are only limited to using equality check, and =
we cannot group by, say, `&lt;` or other functions.</div><div>Similarly, =
the advantage of the first approach is that the keys are preserved, and =
elements needn't be consecutive.</div><div><br></div><div>In any case, I =
think a utility function such as `array_group` will be widely =
useful.</div><div><br></div><div>Please find attached a patch with a =
proposed implementation. Curious about your =
feedback.</div><div><br></div><div>Best,</div><div><br></div><div><a =
href=3D"https://people.php.net/bor0">Boro =
Sitnikovski</a></div><div><br></div></body></html>=

--Apple-Mail=_7312EF78-3546-44DC-B65E-7C2DCBF69A36
Content-Disposition: attachment;
	filename=array_group.patch
Content-Type: application/octet-stream;
	x-unix-mode=0644;
	name="array_group.patch"
Content-Transfer-Encoding: 7bit

diff --git a/Zend/zend_hash.h b/Zend/zend_hash.h
index 5726c8a919..c462de2850 100644
--- a/Zend/zend_hash.h
+++ b/Zend/zend_hash.h
@@ -1087,6 +1087,10 @@ static zend_always_inline void *zend_hash_get_current_data_ptr_ex(HashTable *ht,
 	_ZEND_HASH_FOREACH_VAL(ht); \
 	_val = _z;
 
+#define ZEND_HASH_FOREACH_VAL_FROM(ht, _val, _from) \
+	ZEND_HASH_FOREACH_FROM(ht, 0, _from); \
+	_val = _z;
+
 #define ZEND_HASH_REVERSE_FOREACH_VAL(ht, _val) \
 	_ZEND_HASH_REVERSE_FOREACH_VAL(ht); \
 	_val = _z;
diff --git a/ext/standard/array.c b/ext/standard/array.c
index 46c2c882b8..171482113a 100644
--- a/ext/standard/array.c
+++ b/ext/standard/array.c
@@ -6394,6 +6394,75 @@ PHP_FUNCTION(array_map)
 }
 /* }}} */
 
+/* {{{ Groups consecutive elements from the array via the callback. */
+PHP_FUNCTION(array_group)
+{
+	zval *array;
+	zend_fcall_info fci;
+	zend_fcall_info_cache fci_cache = empty_fcall_info_cache;
+
+	zval args[2];
+	zval *prev_val;
+	zval *curr_val;
+	zval chunk;
+	zval retval;
+
+	ZEND_PARSE_PARAMETERS_START(2, 2)
+		Z_PARAM_ARRAY(array)
+		Z_PARAM_FUNC(fci, fci_cache)
+	ZEND_PARSE_PARAMETERS_END();
+
+	if (zend_hash_num_elements(Z_ARRVAL_P(array)) == 0) {
+		RETVAL_EMPTY_ARRAY();
+		return;
+	}
+
+	// The array is guaranteed to have at least one element.
+	prev_val = ZEND_HASH_ELEMENT(Z_ARRVAL_P(array), 0);
+
+	// Generate the initial group.
+	array_init(&chunk);
+	zend_hash_next_index_insert_new(Z_ARRVAL_P(&chunk), prev_val);
+
+	array_init(return_value);
+
+	fci.retval = &retval;
+	fci.param_count = 2;
+
+	ZEND_HASH_FOREACH_VAL_FROM(Z_ARRVAL_P(array), curr_val, 1) {
+		ZVAL_COPY(&args[0], prev_val);
+		ZVAL_COPY(&args[1], curr_val);
+		fci.params = args;
+
+		if (zend_call_function(&fci, &fci_cache) == SUCCESS && Z_TYPE(retval) != IS_UNDEF) {
+			int retval_true;
+
+			zval_ptr_dtor(&args[1]);
+			zval_ptr_dtor(&args[0]);
+
+			retval_true = zend_is_true(&retval);
+
+			zval_ptr_dtor(&retval);
+
+			// Perform grouping - add the current group and create a new one.
+			if (!retval_true) {
+				zend_hash_next_index_insert_new(Z_ARRVAL_P(return_value), &chunk);
+				array_init(&chunk);
+			}
+
+			zend_hash_next_index_insert_new(Z_ARRVAL_P(&chunk), curr_val);
+		} else {
+			zval_ptr_dtor(&args[1]);
+			zval_ptr_dtor(&args[0]);
+			RETURN_NULL();
+		}
+	} ZEND_HASH_FOREACH_END();
+
+	// Add the last group.
+	zend_hash_next_index_insert_new(Z_ARRVAL_P(return_value), &chunk);
+}
+/* }}} */
+
 /* {{{ Checks if the given key or index exists in the array */
 PHP_FUNCTION(array_key_exists)
 {
diff --git a/ext/standard/basic_functions.stub.php b/ext/standard/basic_functions.stub.php
index effb05ff9f..a6a8408dc9 100755
--- a/ext/standard/basic_functions.stub.php
+++ b/ext/standard/basic_functions.stub.php
@@ -1870,6 +1870,8 @@ function array_filter(array $array, ?callable $callback = null, int $mode = 0):
 
 function array_map(?callable $callback, array $array, array ...$arrays): array {}
 
+function array_group(array $array, callable $callback): array {}
+
 /**
  * @param string|int $key
  * @compile-time-eval
diff --git a/ext/standard/basic_functions_arginfo.h b/ext/standard/basic_functions_arginfo.h
index 5612ee2186..40600762f7 100644
--- a/ext/standard/basic_functions_arginfo.h
+++ b/ext/standard/basic_functions_arginfo.h
@@ -342,6 +342,11 @@ ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_array_map, 0, 2, IS_ARRAY, 0)
 	ZEND_ARG_VARIADIC_TYPE_INFO(0, arrays, IS_ARRAY, 0)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_array_group, 0, 2, IS_ARRAY, 0)
+	ZEND_ARG_TYPE_INFO(0, array, IS_ARRAY, 0)
+	ZEND_ARG_TYPE_INFO(0, callback, IS_CALLABLE, 0)
+ZEND_END_ARG_INFO()
+
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_array_key_exists, 0, 2, _IS_BOOL, 0)
 	ZEND_ARG_INFO(0, key)
 	ZEND_ARG_TYPE_INFO(0, array, IS_ARRAY, 0)
@@ -2292,6 +2297,7 @@ ZEND_FUNCTION(array_product);
 ZEND_FUNCTION(array_reduce);
 ZEND_FUNCTION(array_filter);
 ZEND_FUNCTION(array_map);
+ZEND_FUNCTION(array_group);
 ZEND_FUNCTION(array_key_exists);
 ZEND_FUNCTION(array_chunk);
 ZEND_FUNCTION(array_combine);
@@ -2915,6 +2921,7 @@ static const zend_function_entry ext_functions[] = {
 	ZEND_FE(array_reduce, arginfo_array_reduce)
 	ZEND_FE(array_filter, arginfo_array_filter)
 	ZEND_FE(array_map, arginfo_array_map)
+	ZEND_FE(array_group, arginfo_array_group)
 	ZEND_SUPPORTS_COMPILE_TIME_EVAL_FE(array_key_exists, arginfo_array_key_exists)
 	ZEND_FALIAS(key_exists, array_key_exists, arginfo_key_exists)
 	ZEND_SUPPORTS_COMPILE_TIME_EVAL_FE(array_chunk, arginfo_array_chunk)
diff --git a/ext/standard/tests/array/array_group_basic.phpt b/ext/standard/tests/array/array_group_basic.phpt
new file mode 100644
index 0000000000..9db0e7afe3
--- /dev/null
+++ b/ext/standard/tests/array/array_group_basic.phpt
@@ -0,0 +1,130 @@
+--TEST--
+Test array_group() function : basic functionality
+--FILE--
+<?php
+echo "*** Testing array_group() : basic functionality ***\n";
+
+function less_than( $a, $b ) {
+	return $a < $b;
+}
+
+function equal( $a, $b ) {
+	return $a == $b;
+}
+
+function equal_obj( $a, $b ) {
+	return $a->name == $b->name;
+}
+
+$arr1 = array(1, 2, 3);
+
+echo "-- With an integer array for < --\n";
+var_dump( array_group($arr1, 'less_than') );
+
+echo "-- With an integer array for == --\n";
+var_dump( array_group($arr1, 'equal') );
+
+echo "-- With an empty integer array for == --\n";
+var_dump( array_group($arr1, 'equal') );
+
+echo "-- With a singleton integer array for == --\n";
+var_dump( array_group(array(1), 'equal') );
+
+$obj1 = (object)array('id'=>3,'name'=>'foo');
+$obj2 = (object)array('id'=>4,'name'=>'foo');
+$obj3 = (object)array('id'=>5,'name'=>'baz');
+
+echo "-- With a singleton integer array for == --\n";
+var_dump( array_group(array($obj1, $obj2, $obj3), 'equal_obj') );
+
+echo "Done";
+?>
+--EXPECT--
+*** Testing array_group() : basic functionality ***
+-- With an integer array for < --
+array(1) {
+  [0]=>
+  array(3) {
+    [0]=>
+    int(1)
+    [1]=>
+    int(2)
+    [2]=>
+    int(3)
+  }
+}
+-- With an integer array for == --
+array(3) {
+  [0]=>
+  array(1) {
+    [0]=>
+    int(1)
+  }
+  [1]=>
+  array(1) {
+    [0]=>
+    int(2)
+  }
+  [2]=>
+  array(1) {
+    [0]=>
+    int(3)
+  }
+}
+-- With an empty integer array for == --
+array(3) {
+  [0]=>
+  array(1) {
+    [0]=>
+    int(1)
+  }
+  [1]=>
+  array(1) {
+    [0]=>
+    int(2)
+  }
+  [2]=>
+  array(1) {
+    [0]=>
+    int(3)
+  }
+}
+-- With a singleton integer array for == --
+array(1) {
+  [0]=>
+  array(1) {
+    [0]=>
+    int(1)
+  }
+}
+-- With a singleton integer array for == --
+array(2) {
+  [0]=>
+  array(2) {
+    [0]=>
+    object(stdClass)#1 (2) {
+      ["id"]=>
+      int(3)
+      ["name"]=>
+      string(3) "foo"
+    }
+    [1]=>
+    object(stdClass)#2 (2) {
+      ["id"]=>
+      int(4)
+      ["name"]=>
+      string(3) "foo"
+    }
+  }
+  [1]=>
+  array(1) {
+    [0]=>
+    object(stdClass)#3 (2) {
+      ["id"]=>
+      int(5)
+      ["name"]=>
+      string(3) "baz"
+    }
+  }
+}
+Done

--Apple-Mail=_7312EF78-3546-44DC-B65E-7C2DCBF69A36
Content-Transfer-Encoding: 7bit
Content-Type: text/html;
	charset=us-ascii

<html><head><meta http-equiv="content-type" content="text/html; charset=us-ascii"></head><body style="overflow-wrap: break-word; -webkit-nbsp-mode: space; line-break: after-white-space;"></body></html>
--Apple-Mail=_7312EF78-3546-44DC-B65E-7C2DCBF69A36--

--Apple-Mail=_3B4D8BC6-6256-4AB6-BC9D-B71E2D803898--