Proposal: Add final class Vector to PHP

See spl_vector.stub.php for the userland API.

Earlier work on the implementation can be found at
https://github.com/TysonAndre/pecl-teds
and it can be tested out at https://pecl.php.net/package/teds as `Teds\Vector`
(currently the same apart from reusing spl's conversion of mixed to `int $offset`)

This was originally based on spl_fixedarray.c and previous work I did on an RFC.

Notable features:
- Roughly half the memory usage of (non-constant) arrays
  due to not needing a list of indexes of buckets separately
  from the zval buckets themselves.
- Same memory usage as SplFixedArray in 8.2 for a given **capacity**
- Lower memory usage and better performance than SplDoublyLinkedList
  or its subclasses (SplStack) due to being an array instead of a linked list
- More efficient resizing than SplFixedArray's setSize(getSize+1)

```php
final class Vector implements IteratorAggregate, Countable, JsonSerializable, ArrayAccess
{
	public function __construct(
		iterable $iterator = [],
		bool $preserveKeys = true
	) {}
	public function getIterator(): InternalIterator {}
	public function count(): int {}
	public function capacity(): int {}
	public function clear(): void {}
	public function setSize(int $size): void {}

	public function __serialize(): array {}
	public function __unserialize(array $data): void {}
	public static function __set_state(array $array): Vector {}

	public function push(mixed $value): void {}
	public function pop(): mixed {}

	public function toArray(): array {}
	// Strictly typed, unlike offsetGet/offsetSet
	public function valueAt(int $offset): mixed {}
	public function setValueAt(int $offset, mixed $value): void {}

	public function offsetGet(mixed $offset): mixed {}
	public function offsetExists(mixed $offset): bool {}
	public function offsetSet(mixed $offset, mixed $value): void {}
	// Throws because unset and null are different things.
	public function offsetUnset(mixed $offset): void {}

	public function indexOf(mixed $value): int|false {}
	public function contains(mixed $value): bool {}

	public function shrinkToFit(): void {}

	public function jsonSerialize(): array {}
}
```

Author: TysonAndre

ext/spl/config.m4

@@ -1,5 +1,5 @@
-PHP_NEW_EXTENSION(spl, php_spl.c spl_functions.c spl_iterators.c spl_array.c spl_directory.c spl_exceptions.c spl_observer.c spl_dllist.c spl_heap.c spl_fixedarray.c, no,, -DZEND_ENABLE_STATIC_TSRMLS_CACHE=1)
-PHP_INSTALL_HEADERS([ext/spl], [php_spl.h spl_array.h spl_directory.h spl_engine.h spl_exceptions.h spl_functions.h spl_iterators.h spl_observer.h spl_dllist.h spl_heap.h spl_fixedarray.h])
+PHP_NEW_EXTENSION(spl, php_spl.c spl_functions.c spl_iterators.c spl_array.c spl_directory.c spl_exceptions.c spl_observer.c spl_dllist.c spl_heap.c spl_fixedarray.c spl_vector.c, no,, -DZEND_ENABLE_STATIC_TSRMLS_CACHE=1)
+PHP_INSTALL_HEADERS([ext/spl], [php_spl.h spl_array.h spl_directory.h spl_engine.h spl_exceptions.h spl_functions.h spl_iterators.h spl_observer.h spl_dllist.h spl_heap.h spl_fixedarray.h spl_vector.h])
 PHP_ADD_EXTENSION_DEP(spl, pcre, true)
 PHP_ADD_EXTENSION_DEP(spl, standard, true)
 PHP_ADD_EXTENSION_DEP(spl, json)

ext/spl/config.w32

@@ -1,5 +1,5 @@
 // vim:ft=javascript
 
-EXTENSION("spl", "php_spl.c spl_functions.c spl_iterators.c spl_array.c spl_directory.c spl_exceptions.c spl_observer.c spl_dllist.c spl_heap.c spl_fixedarray.c", false /*never shared */, "/DZEND_ENABLE_STATIC_TSRMLS_CACHE=1");
+EXTENSION("spl", "php_spl.c spl_functions.c spl_iterators.c spl_array.c spl_directory.c spl_exceptions.c spl_observer.c spl_dllist.c spl_heap.c spl_fixedarray.c spl_vector.c", false /*never shared */, "/DZEND_ENABLE_STATIC_TSRMLS_CACHE=1");
 PHP_SPL="yes";
-PHP_INSTALL_HEADERS("ext/spl", "php_spl.h spl_array.h spl_directory.h spl_engine.h spl_exceptions.h spl_functions.h spl_iterators.h spl_observer.h spl_dllist.h spl_heap.h spl_fixedarray.h");
+PHP_INSTALL_HEADERS("ext/spl", "php_spl.h spl_array.h spl_directory.h spl_engine.h spl_exceptions.h spl_functions.h spl_iterators.h spl_observer.h spl_dllist.h spl_heap.h spl_fixedarray.h spl_vector.h");

ext/spl/php_spl.c

@@ -33,6 +33,7 @@
 #include "spl_observer.h"
 #include "spl_dllist.h"
 #include "spl_fixedarray.h"
+#include "spl_vector.h"
 #include "spl_heap.h"
 #include "zend_exceptions.h"
 #include "zend_interfaces.h"
@@ -708,6 +709,7 @@ PHP_MINIT_FUNCTION(spl)
 	PHP_MINIT(spl_dllist)(INIT_FUNC_ARGS_PASSTHRU);
 	PHP_MINIT(spl_heap)(INIT_FUNC_ARGS_PASSTHRU);
 	PHP_MINIT(spl_fixedarray)(INIT_FUNC_ARGS_PASSTHRU);
+	PHP_MINIT(spl_vector)(INIT_FUNC_ARGS_PASSTHRU);
 	PHP_MINIT(spl_observer)(INIT_FUNC_ARGS_PASSTHRU);
 
 	return SUCCESS;

ext/spl/spl_fixedarray.c

@@ -31,6 +31,7 @@
 #include "spl_fixedarray.h"
 #include "spl_exceptions.h"
 #include "spl_iterators.h"
+#include "spl_util.h"
 #include "ext/json/php_json.h"
 
 zend_object_handlers spl_handler_SplFixedArray;
@@ -310,37 +311,6 @@ static zend_object *spl_fixedarray_object_clone(zend_object *old_object)
 	return new_object;
 }
 
-static zend_long spl_offset_convert_to_long(zval *offset) /* {{{ */
-{
-	try_again:
-	switch (Z_TYPE_P(offset)) {
-		case IS_STRING: {
-			zend_ulong index;
-			if (ZEND_HANDLE_NUMERIC(Z_STR_P(offset), index)) {
-				return (zend_long) index;
-			}
-			break;
-		}
-		case IS_DOUBLE:
-			return zend_dval_to_lval_safe(Z_DVAL_P(offset));
-		case IS_LONG:
-			return Z_LVAL_P(offset);
-		case IS_FALSE:
-			return 0;
-		case IS_TRUE:
-			return 1;
-		case IS_REFERENCE:
-			offset = Z_REFVAL_P(offset);
-			goto try_again;
-		case IS_RESOURCE:
-			zend_use_resource_as_offset(offset);
-			return Z_RES_HANDLE_P(offset);
-	}
-
-	zend_type_error("Illegal offset type");
-	return 0;
-}
-
 static zval *spl_fixedarray_object_read_dimension_helper(spl_fixedarray_object *intern, zval *offset)
 {
 	zend_long index;

ext/spl/spl_util.h

@@ -0,0 +1,37 @@
+#ifndef SPL_UTIL
+#define SPL_UTIL
+
+#include "zend_types.h"
+
+static zend_long spl_offset_convert_to_long(zval *offset) /* {{{ */
+{
+	try_again:
+	switch (Z_TYPE_P(offset)) {
+		case IS_STRING: {
+			zend_ulong index;
+			if (ZEND_HANDLE_NUMERIC(Z_STR_P(offset), index)) {
+				return (zend_long) index;
+			}
+			break;
+		}
+		case IS_DOUBLE:
+			return zend_dval_to_lval_safe(Z_DVAL_P(offset));
+		case IS_LONG:
+			return Z_LVAL_P(offset);
+		case IS_FALSE:
+			return 0;
+		case IS_TRUE:
+			return 1;
+		case IS_REFERENCE:
+			offset = Z_REFVAL_P(offset);
+			goto try_again;
+		case IS_RESOURCE:
+			zend_use_resource_as_offset(offset);
+			return Z_RES_HANDLE_P(offset);
+	}
+
+	zend_type_error("Illegal offset type");
+	return 0;
+}
+
+#endif