Add is_list function

This function tests if an array contains only sequential integer keys. While
this isn't an official type, this usage is consistent with the community usage
of "list" as an annotation type, cf.
https://psalm.dev/docs/annotating_code/type_syntax/array_types/#lists

Rebased version of php#4886

- Use .stub.php files
- Add opcache constant evaluation when argument is a constant

Co-Authored-By: Tyson Andre <[email protected]>
Co-Authored-By: Dusk <[email protected]>

Author: duskwuff

ext/standard/basic_functions.stub.php

@@ -1443,6 +1443,8 @@ function is_string(mixed $value): bool {}
 
 function is_array(mixed $value): bool {}
 
+function is_list(mixed $value): bool {}
+
 function is_object(mixed $value): bool {}
 
 function is_scalar(mixed $value): bool {}

ext/standard/basic_functions_arginfo.h

@@ -1,5 +1,5 @@
 /* This is a generated file, edit the .stub.php file instead.
- * Stub hash: 8b6ef365e9635c92ef86adb40b2aba077867f3b2 */
+ * Stub hash: c82b5b9e9bab13ae814ff29994f2822f73431d1c */
 
 ZEND_BEGIN_ARG_WITH_RETURN_TYPE_INFO_EX(arginfo_set_time_limit, 0, 1, _IS_BOOL, 0)
 	ZEND_ARG_TYPE_INFO(0, seconds, IS_LONG, 0)
@@ -2102,6 +2102,8 @@ ZEND_END_ARG_INFO()
 
 #define arginfo_is_array arginfo_boolval
 
+#define arginfo_is_list arginfo_boolval
+
 #define arginfo_is_object arginfo_boolval
 
 #define arginfo_is_scalar arginfo_boolval
@@ -2811,6 +2813,7 @@ ZEND_FUNCTION(is_float);
 ZEND_FUNCTION(is_numeric);
 ZEND_FUNCTION(is_string);
 ZEND_FUNCTION(is_array);
+ZEND_FUNCTION(is_list);
 ZEND_FUNCTION(is_object);
 ZEND_FUNCTION(is_scalar);
 ZEND_FUNCTION(is_callable);
@@ -3462,6 +3465,7 @@ static const zend_function_entry ext_functions[] = {
 	ZEND_FE(is_numeric, arginfo_is_numeric)
 	ZEND_FE(is_string, arginfo_is_string)
 	ZEND_FE(is_array, arginfo_is_array)
+	ZEND_FE(is_list, arginfo_is_list)
 	ZEND_FE(is_object, arginfo_is_object)
 	ZEND_FE(is_scalar, arginfo_is_scalar)
 	ZEND_FE(is_callable, arginfo_is_callable)

ext/standard/tests/general_functions/is_list.phpt

@@ -0,0 +1,94 @@
+--TEST--
+Test is_list() function
+--FILE--
+<?php
+
+function test_is_list(string $desc, $val) : void {
+	printf("%s: %s\n", $desc, is_list($val) ? "true" : "false");
+}
+
+test_is_list("empty", []);
+test_is_list("one", [1]);
+test_is_list("two", [1,2]);
+test_is_list("three", [1,2,3]);
+test_is_list("four", [1,2,3,4]);
+test_is_list("ten", range(0, 10));
+
+test_is_list("null", null);
+test_is_list("int", 123);
+test_is_list("float", 1.23);
+test_is_list("string", "string");
+test_is_list("object", new stdclass);
+test_is_list("true", true);
+test_is_list("false", false);
+
+test_is_list("string key", ["a" => 1]);
+test_is_list("mixed keys", [0 => 0, "a" => 1]);
+test_is_list("ordered keys", [0 => 0, 1 => 1]);
+test_is_list("shuffled keys", [1 => 0, 0 => 1]);
+test_is_list("skipped keys", [0 => 0, 2 => 2]);
+
+$arr = [1, 2, 3];
+unset($arr[0]);
+test_is_list("unset first", $arr);
+
+$arr = [1, 2, 3];
+unset($arr[1]);
+test_is_list("unset middle", $arr);
+
+$arr = [1, 2, 3];
+unset($arr[2]);
+test_is_list("unset end", $arr);
+
+$arr = [1, "a" => "a", 2];
+unset($arr["a"]);
+test_is_list("unset string key", $arr);
+
+$arr = [1 => 1, 0 => 0];
+unset($arr[1]);
+test_is_list("unset into order", $arr);
+
+$arr = ["a" => 1];
+unset($arr["a"]);
+test_is_list("unset to empty", $arr);
+
+$arr = [1, 2, 3];
+$arr[] = 4;
+test_is_list("append implicit", $arr);
+
+$arr = [1, 2, 3];
+$arr[3] = 4;
+test_is_list("append explicit", $arr);
+
+$arr = [1, 2, 3];
+$arr[4] = 5;
+test_is_list("append with gap", $arr);
+
+--EXPECT--
+empty: true
+one: true
+two: true
+three: true
+four: true
+ten: true
+null: false
+int: false
+float: false
+string: false
+object: false
+true: false
+false: false
+string key: false
+mixed keys: false
+ordered keys: true
+shuffled keys: false
+skipped keys: false
+unset first: false
+unset middle: false
+unset end: true
+unset string key: true
+unset into order: true
+unset to empty: true
+append implicit: true
+append explicit: true
+append with gap: false

ext/standard/type.c

@@ -321,6 +321,41 @@ PHP_FUNCTION(is_array)
 }
 /* }}} */
 
+/* {{{ Returns true if variable is an array whose keys are all numeric, sequential, and start at 0 */
+PHP_FUNCTION(is_list)
+{
+	zval *arg;
+	zend_array *arrval;
+	zend_ulong num_idx, expected_idx = 0;
+	zend_string *str_idx;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_ZVAL(arg)
+	ZEND_PARSE_PARAMETERS_END();
+
+	if (Z_TYPE_P(arg) != IS_ARRAY)
+		RETURN_FALSE;
+
+	arrval = Z_ARRVAL_P(arg);
+
+	/* Empty arrays are lists */
+	if (zend_hash_num_elements(arrval) == 0)
+		RETURN_TRUE;
+
+	/* Packed arrays are lists */
+	if (HT_IS_PACKED(arrval) && HT_IS_WITHOUT_HOLES(arrval))
+		RETURN_TRUE;
+
+	/* Check if the list could theoretically be repacked */
+	ZEND_HASH_FOREACH_KEY(arrval, num_idx, str_idx) {
+		if (str_idx != NULL || num_idx != expected_idx++)
+			RETURN_FALSE;
+	} ZEND_HASH_FOREACH_END();
+
+	RETURN_TRUE;
+}
+/* }}} */
+
 /* {{{ Returns true if variable is an object
    Warning: This function is special-cased by zend_compile.c and so is usually bypassed */
 PHP_FUNCTION(is_object)