Add implementation and tests for new methods - array_key_first(array $a) Returns the key of the first element or null - array_key_last(array $a) Returns the key of the last element or null

10 files changed, 693 insertions, 0 deletions

diff --git a/UPGRADING b/UPGRADING
index 12ce73f737..0db37b27e7 100644
--- a/UPGRADING
+++ b/UPGRADING
@@ -363,6 +363,9 @@ Standard:
   . Added is_countable() function, to check whether a value may be passed to
     count().
     (RFC: https://wiki.php.net/rfc/is-countable)
+  . Added array_key_first() and array_key_last() which retrieve the first and
+    last key of an array, respectively.
+    (RFC: <https://wiki.php.net/rfc/array_key_first_last>)
 
 ========================================
 7. New Classes and Interfaces
diff --git a/ext/standard/array.c b/ext/standard/array.c
index 10831a4227..82e0833e34 100644
--- a/ext/standard/array.c
+++ b/ext/standard/array.c
@@ -3963,6 +3963,39 @@ PHP_FUNCTION(array_keys)
 }
 /* }}} */
 
+/* {{{ proto mixed array_key_first(array stack)
+   Get the key of the first element of the array */
+PHP_FUNCTION(array_key_first)
+{
+	zval *stack;    /* Input stack */
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_ARRAY_EX(stack, 0, 1)
+	ZEND_PARSE_PARAMETERS_END();
+
+	HashTable *target_hash = HASH_OF(stack);
+	HashPosition pos = 0;
+	zend_hash_get_current_key_zval_ex(target_hash, return_value, &pos);
+}
+/* }}} */
+
+/* {{{ proto mixed array_key_last(array stack)
+   Get the key of the last element of the array */
+PHP_FUNCTION(array_key_last)
+{
+	zval *stack;    /* Input stack */
+	HashPosition pos;
+
+	ZEND_PARSE_PARAMETERS_START(1, 1)
+		Z_PARAM_ARRAY_EX(stack, 0, 1)
+	ZEND_PARSE_PARAMETERS_END();
+
+	HashTable *target_hash = HASH_OF(stack);
+	zend_hash_internal_pointer_end_ex(target_hash, &pos);
+	zend_hash_get_current_key_zval_ex(target_hash, return_value, &pos);
+}
+/* }}} */
+
 /* {{{ proto array array_values(array input)
    Return just the values from the input array */
 PHP_FUNCTION(array_values)
diff --git a/ext/standard/basic_functions.c b/ext/standard/basic_functions.c
index b30fec0c5c..85092dea10 100644
--- a/ext/standard/basic_functions.c
+++ b/ext/standard/basic_functions.c
@@ -418,6 +418,15 @@ ZEND_BEGIN_ARG_INFO_EX(arginfo_array_keys, 0, 0, 1)
 	ZEND_ARG_INFO(0, strict)
 ZEND_END_ARG_INFO()
 
+ZEND_BEGIN_ARG_INFO(arginfo_array_key_first, 0)
+	ZEND_ARG_INFO(0, arg) /* ARRAY_INFO(0, arg, 0) */
+ZEND_END_ARG_INFO()
+
+ZEND_BEGIN_ARG_INFO(arginfo_array_key_last, 0)
+	ZEND_ARG_INFO(0, arg) /* ARRAY_INFO(0, arg, 0) */
+ZEND_END_ARG_INFO()
+
+
 ZEND_BEGIN_ARG_INFO(arginfo_array_values, 0)
 	ZEND_ARG_INFO(0, arg) /* ARRAY_INFO(0, arg, 0) */
 ZEND_END_ARG_INFO()
@@ -3362,6 +3371,8 @@ static const zend_function_entry basic_functions[] = { /* {{{ */
 	PHP_FE(array_replace,													arginfo_array_replace)
 	PHP_FE(array_replace_recursive,											arginfo_array_replace_recursive)
 	PHP_FE(array_keys,														arginfo_array_keys)
+	PHP_FE(array_key_first,													arginfo_array_key_first)
+	PHP_FE(array_key_last,													arginfo_array_key_last)
 	PHP_FE(array_values,													arginfo_array_values)
 	PHP_FE(array_count_values,												arginfo_array_count_values)
 	PHP_FE(array_column,													arginfo_array_column)
diff --git a/ext/standard/php_array.h b/ext/standard/php_array.h
index b438dd64f1..f227365a1f 100644
--- a/ext/standard/php_array.h
+++ b/ext/standard/php_array.h
@@ -69,6 +69,8 @@ PHP_FUNCTION(array_merge_recursive);
 PHP_FUNCTION(array_replace);
 PHP_FUNCTION(array_replace_recursive);
 PHP_FUNCTION(array_keys);
+PHP_FUNCTION(array_key_first);
+PHP_FUNCTION(array_key_last);
 PHP_FUNCTION(array_values);
 PHP_FUNCTION(array_count_values);
 PHP_FUNCTION(array_column);
diff --git a/ext/standard/tests/array/array_key_first.phpt b/ext/standard/tests/array/array_key_first.phpt
new file mode 100644
index 0000000000..6235386004
--- /dev/null
+++ b/ext/standard/tests/array/array_key_first.phpt
@@ -0,0 +1,234 @@
+--TEST--
+Test array_key_first() function
+--FILE--
+<?php
+
+array_key_first($GLOBALS);
+
+/* Various combinations of arrays to be used for the test */
+$mixed_array = array(
+  array(),
+  array( 1,2,3,4,5,6,7,8,9 ),
+  array( "One", "_Two", "Three", "Four", "Five" ),
+  array( 6, "six", 7, "seven", 8, "eight", 9, "nine" ),
+  array( "a" => "aaa", "A" => "AAA", "c" => "ccc", "d" => "ddd", "e" => "eee" ),
+  array( "1" => "one", "2" => "two", "3" => "three", "4" => "four", "5" => "five" ),
+  array( 1 => "one", 2 => "two", 3 => 7, 4 => "four", 5 => "five" ),
+  array( "f" => "fff", "1" => "one", 4 => 6, "" => "blank", 2.4 => "float", "F" => "FFF",
+         "blank" => "", 3.7 => 3.7, 5.4 => 7, 6 => 8.6, '5' => "Five", "4name" => "jonny", "a" => NULL, NULL => 3 ),
+  array( 12, "name", 'age', '45' ),
+  array( array("oNe", "tWo", 4), array(10, 20, 30, 40, 50), array() ),
+  array( "one" => 1, "one" => 2, "three" => 3, 3, 4, 3 => 33, 4 => 44, 5, 6,
+          5.4 => 54, 5.7 => 57, "5.4" => 554, "5.7" => 557 ),
+  array( "foo" ),
+  array( 1 => "42" )
+);
+
+/* Loop to test normal functionality with different arrays inputs */
+echo "\n*** Normal testing with various array inputs ***\n";
+
+$counter = 1;
+foreach( $mixed_array as $sub_array )
+{
+ echo "\n-- Input Array for Iteration $counter is --\n";
+ print_r( $sub_array );
+ echo "\nFirst key is :\n";
+ var_dump( array_key_first($sub_array) );
+ $counter++;
+}
+
+echo"\nDone";
+?>
+--EXPECT--
+*** Normal testing with various array inputs ***
+
+-- Input Array for Iteration 1 is --
+Array
+(
+)
+
+First key is :
+NULL
+
+-- Input Array for Iteration 2 is --
+Array
+(
+    [0] => 1
+    [1] => 2
+    [2] => 3
+    [3] => 4
+    [4] => 5
+    [5] => 6
+    [6] => 7
+    [7] => 8
+    [8] => 9
+)
+
+First key is :
+int(0)
+
+-- Input Array for Iteration 3 is --
+Array
+(
+    [0] => One
+    [1] => _Two
+    [2] => Three
+    [3] => Four
+    [4] => Five
+)
+
+First key is :
+int(0)
+
+-- Input Array for Iteration 4 is --
+Array
+(
+    [0] => 6
+    [1] => six
+    [2] => 7
+    [3] => seven
+    [4] => 8
+    [5] => eight
+    [6] => 9
+    [7] => nine
+)
+
+First key is :
+int(0)
+
+-- Input Array for Iteration 5 is --
+Array
+(
+    [a] => aaa
+    [A] => AAA
+    [c] => ccc
+    [d] => ddd
+    [e] => eee
+)
+
+First key is :
+string(1) "a"
+
+-- Input Array for Iteration 6 is --
+Array
+(
+    [1] => one
+    [2] => two
+    [3] => three
+    [4] => four
+    [5] => five
+)
+
+First key is :
+int(1)
+
+-- Input Array for Iteration 7 is --
+Array
+(
+    [1] => one
+    [2] => two
+    [3] => 7
+    [4] => four
+    [5] => five
+)
+
+First key is :
+int(1)
+
+-- Input Array for Iteration 8 is --
+Array
+(
+    [f] => fff
+    [1] => one
+    [4] => 6
+    [] => 3
+    [2] => float
+    [F] => FFF
+    [blank] => 
+    [3] => 3.7
+    [5] => Five
+    [6] => 8.6
+    [4name] => jonny
+    [a] => 
+)
+
+First key is :
+string(1) "f"
+
+-- Input Array for Iteration 9 is --
+Array
+(
+    [0] => 12
+    [1] => name
+    [2] => age
+    [3] => 45
+)
+
+First key is :
+int(0)
+
+-- Input Array for Iteration 10 is --
+Array
+(
+    [0] => Array
+        (
+            [0] => oNe
+            [1] => tWo
+            [2] => 4
+        )
+
+    [1] => Array
+        (
+            [0] => 10
+            [1] => 20
+            [2] => 30
+            [3] => 40
+            [4] => 50
+        )
+
+    [2] => Array
+        (
+        )
+
+)
+
+First key is :
+int(0)
+
+-- Input Array for Iteration 11 is --
+Array
+(
+    [one] => 2
+    [three] => 3
+    [0] => 3
+    [1] => 4
+    [3] => 33
+    [4] => 44
+    [5] => 57
+    [6] => 6
+    [5.4] => 554
+    [5.7] => 557
+)
+
+First key is :
+string(3) "one"
+
+-- Input Array for Iteration 12 is --
+Array
+(
+    [0] => foo
+)
+
+First key is :
+int(0)
+
+-- Input Array for Iteration 13 is --
+Array
+(
+    [1] => 42
+)
+
+First key is :
+int(1)
+
+Done
diff --git a/ext/standard/tests/array/array_key_first_errors.phpt b/ext/standard/tests/array/array_key_first_errors.phpt
new file mode 100644
index 0000000000..ad2c52b6a0
--- /dev/null
+++ b/ext/standard/tests/array/array_key_first_errors.phpt
@@ -0,0 +1,52 @@
+--TEST--
+Test array_key_first() function (errors)
+--FILE--
+<?php
+
+$empty_array = array();
+$number = 5;
+$str = "abc";
+
+/* Various combinations of arrays to be used for the test */
+$mixed_array = array(
+    array( 1,2,3,4,5,6,7,8,9 ),
+    array( "One", "_Two", "Three", "Four", "Five" )
+);
+
+/* Testing Error Conditions */
+echo "\n*** Testing Error Conditions ***\n";
+
+/* Zero argument  */
+var_dump( array_key_first() );
+
+/* Scalar argument */
+var_dump( array_key_first($number) );
+
+/* String argument */
+var_dump( array_key_first($str) );
+
+/* Invalid Number of arguments */
+var_dump( array_key_first($mixed_array[0],$mixed_array[1]) );
+
+/* Empty Array as argument */
+var_dump( array_key_first($empty_array) );
+
+echo"\nDone";
+?>
+--EXPECTF--
+*** Testing Error Conditions ***
+
+Warning: array_key_first() expects exactly 1 parameter, 0 given in %s on line %d
+NULL
+
+Warning: array_key_first() expects parameter 1 to be array, int given in %s on line %d
+NULL
+
+Warning: array_key_first() expects parameter 1 to be array, string given in %s on line %d
+NULL
+
+Warning: array_key_first() expects exactly 1 parameter, 2 given in %s on line %d
+NULL
+NULL
+
+Done
diff --git a/ext/standard/tests/array/array_key_first_variation.phpt b/ext/standard/tests/array/array_key_first_variation.phpt
new file mode 100644
index 0000000000..d619ed0122
--- /dev/null
+++ b/ext/standard/tests/array/array_key_first_variation.phpt
@@ -0,0 +1,36 @@
+--TEST--
+Test array_key_first() function (variation)
+--FILE--
+<?php
+
+/* Various combinations of arrays to be used for the test */
+$array = array( 1,2,3,4,5,6,7,8,9 );
+
+echo"\n*** Checking for internal array pointer not being changed by array_key_first ***\n";
+
+echo "\nCurrent Element is : ";
+var_dump( current($array) );
+
+echo "\nNext Element is : ";
+var_dump( next($array) );
+
+echo "\nFirst key is : ";
+var_dump( array_key_first($array) );
+
+echo "\nCurrent Element after array_key_first operation is: ";
+var_dump( current($array) );
+
+echo"\nDone";
+?>
+--EXPECT--
+*** Checking for internal array pointer not being changed by array_key_first ***
+
+Current Element is : int(1)
+
+Next Element is : int(2)
+
+First key is : int(0)
+
+Current Element after array_key_first operation is: int(2)
+
+Done
diff --git a/ext/standard/tests/array/array_key_last.phpt b/ext/standard/tests/array/array_key_last.phpt
new file mode 100644
index 0000000000..599d80eac4
--- /dev/null
+++ b/ext/standard/tests/array/array_key_last.phpt
@@ -0,0 +1,234 @@
+--TEST--
+Test array_key_last() function
+--FILE--
+<?php
+
+array_key_last($GLOBALS);
+
+/* Various combinations of arrays to be used for the test */
+$mixed_array = array(
+  array(),
+  array( 1,2,3,4,5,6,7,8,9 ),
+  array( "One", "_Two", "Three", "Four", "Five" ),
+  array( 6, "six", 7, "seven", 8, "eight", 9, "nine" ),
+  array( "a" => "aaa", "A" => "AAA", "c" => "ccc", "d" => "ddd", "e" => "eee" ),
+  array( "1" => "one", "2" => "two", "3" => "three", "4" => "four", "5" => "five" ),
+  array( 1 => "one", 2 => "two", 3 => 7, 4 => "four", 5 => "five" ),
+  array( "f" => "fff", "1" => "one", 4 => 6, "" => "blank", 2.4 => "float", "F" => "FFF",
+         "blank" => "", 3.7 => 3.7, 5.4 => 7, 6 => 8.6, '5' => "Five", "4name" => "jonny", "a" => NULL, NULL => 3 ),
+  array( 12, "name", 'age', '45' ),
+  array( array("oNe", "tWo", 4), array(10, 20, 30, 40, 50), array() ),
+  array( "one" => 1, "one" => 2, "three" => 3, 3, 4, 3 => 33, 4 => 44, 5, 6,
+          5.4 => 54, 5.7 => 57, "5.4" => 554, "5.7" => 557 ),
+  array( "foo" ),
+  array( 1 => "42" )
+);
+
+/* Loop to test normal functionality with different arrays inputs */
+echo "\n*** Normal testing with various array inputs ***\n";
+
+$counter = 1;
+foreach( $mixed_array as $sub_array )
+{
+ echo "\n-- Input Array for Iteration $counter is --\n";
+ print_r( $sub_array );
+ echo "\nLast key is :\n";
+ var_dump( array_key_last($sub_array) );
+ $counter++;
+}
+
+echo"\nDone";
+?>
+--EXPECT--
+*** Normal testing with various array inputs ***
+
+-- Input Array for Iteration 1 is --
+Array
+(
+)
+
+Last key is :
+NULL
+
+-- Input Array for Iteration 2 is --
+Array
+(
+    [0] => 1
+    [1] => 2
+    [2] => 3
+    [3] => 4
+    [4] => 5
+    [5] => 6
+    [6] => 7
+    [7] => 8
+    [8] => 9
+)
+
+Last key is :
+int(8)
+
+-- Input Array for Iteration 3 is --
+Array
+(
+    [0] => One
+    [1] => _Two
+    [2] => Three
+    [3] => Four
+    [4] => Five
+)
+
+Last key is :
+int(4)
+
+-- Input Array for Iteration 4 is --
+Array
+(
+    [0] => 6
+    [1] => six
+    [2] => 7
+    [3] => seven
+    [4] => 8
+    [5] => eight
+    [6] => 9
+    [7] => nine
+)
+
+Last key is :
+int(7)
+
+-- Input Array for Iteration 5 is --
+Array
+(
+    [a] => aaa
+    [A] => AAA
+    [c] => ccc
+    [d] => ddd
+    [e] => eee
+)
+
+Last key is :
+string(1) "e"
+
+-- Input Array for Iteration 6 is --
+Array
+(
+    [1] => one
+    [2] => two
+    [3] => three
+    [4] => four
+    [5] => five
+)
+
+Last key is :
+int(5)
+
+-- Input Array for Iteration 7 is --
+Array
+(
+    [1] => one
+    [2] => two
+    [3] => 7
+    [4] => four
+    [5] => five
+)
+
+Last key is :
+int(5)
+
+-- Input Array for Iteration 8 is --
+Array
+(
+    [f] => fff
+    [1] => one
+    [4] => 6
+    [] => 3
+    [2] => float
+    [F] => FFF
+    [blank] => 
+    [3] => 3.7
+    [5] => Five
+    [6] => 8.6
+    [4name] => jonny
+    [a] => 
+)
+
+Last key is :
+string(1) "a"
+
+-- Input Array for Iteration 9 is --
+Array
+(
+    [0] => 12
+    [1] => name
+    [2] => age
+    [3] => 45
+)
+
+Last key is :
+int(3)
+
+-- Input Array for Iteration 10 is --
+Array
+(
+    [0] => Array
+        (
+            [0] => oNe
+            [1] => tWo
+            [2] => 4
+        )
+
+    [1] => Array
+        (
+            [0] => 10
+            [1] => 20
+            [2] => 30
+            [3] => 40
+            [4] => 50
+        )
+
+    [2] => Array
+        (
+        )
+
+)
+
+Last key is :
+int(2)
+
+-- Input Array for Iteration 11 is --
+Array
+(
+    [one] => 2
+    [three] => 3
+    [0] => 3
+    [1] => 4
+    [3] => 33
+    [4] => 44
+    [5] => 57
+    [6] => 6
+    [5.4] => 554
+    [5.7] => 557
+)
+
+Last key is :
+string(3) "5.7"
+
+-- Input Array for Iteration 12 is --
+Array
+(
+    [0] => foo
+)
+
+Last key is :
+int(0)
+
+-- Input Array for Iteration 13 is --
+Array
+(
+    [1] => 42
+)
+
+Last key is :
+int(1)
+
+Done
diff --git a/ext/standard/tests/array/array_key_last_errors.phpt b/ext/standard/tests/array/array_key_last_errors.phpt
new file mode 100644
index 0000000000..88f8c9ffdd
--- /dev/null
+++ b/ext/standard/tests/array/array_key_last_errors.phpt
@@ -0,0 +1,52 @@
+--TEST--
+Test array_key_last() function (errors)
+--FILE--
+<?php
+
+$empty_array = array();
+$number = 5;
+$str = "abc";
+
+/* Various combinations of arrays to be used for the test */
+$mixed_array = array(
+    array( 1,2,3,4,5,6,7,8,9 ),
+    array( "One", "_Two", "Three", "Four", "Five" )
+);
+
+/* Testing Error Conditions */
+echo "\n*** Testing Error Conditions ***\n";
+
+/* Zero argument  */
+var_dump( array_key_last() );
+
+/* Scalar argument */
+var_dump( array_key_last($number) );
+
+/* String argument */
+var_dump( array_key_last($str) );
+
+/* Invalid Number of arguments */
+var_dump( array_key_last($mixed_array[0],$mixed_array[1]) );
+
+/* Empty Array as argument */
+var_dump( array_key_last($empty_array) );
+
+echo"\nDone";
+?>
+--EXPECTF--
+*** Testing Error Conditions ***
+
+Warning: array_key_last() expects exactly 1 parameter, 0 given in %s on line %d
+NULL
+
+Warning: array_key_last() expects parameter 1 to be array, int given in %s on line %d
+NULL
+
+Warning: array_key_last() expects parameter 1 to be array, string given in %s on line %d
+NULL
+
+Warning: array_key_last() expects exactly 1 parameter, 2 given in %s on line %d
+NULL
+NULL
+
+Done
diff --git a/ext/standard/tests/array/array_key_last_variation.phpt b/ext/standard/tests/array/array_key_last_variation.phpt
new file mode 100644
index 0000000000..3b2a48673e
--- /dev/null
+++ b/ext/standard/tests/array/array_key_last_variation.phpt
@@ -0,0 +1,36 @@
+--TEST--
+Test array_key_last() function (variation)
+--FILE--
+<?php
+
+/* Various combinations of arrays to be used for the test */
+$array = array( 1,2,3,4,5,6,7,8,9 );
+
+echo"\n*** Checking for internal array pointer not being changed by array_key_last ***\n";
+
+echo "\nCurrent Element is : ";
+var_dump( current($array) );
+
+echo "\nNext Element is : ";
+var_dump( next($array) );
+
+echo "\nLast key is : ";
+var_dump( array_key_last($array) );
+
+echo "\nCurrent Element after array_key_last operation is: ";
+var_dump( current($array) );
+
+echo"\nDone";
+?>
+--EXPECT--
+*** Checking for internal array pointer not being changed by array_key_last ***
+
+Current Element is : int(1)
+
+Next Element is : int(2)
+
+Last key is : int(8)
+
+Current Element after array_key_last operation is: int(2)
+
+Done