Array - chung-leong/qb GitHub Wiki

Arrays in PHP are sophisticated data containers. You can put anything into them. Elements can be referenced to by a text string or a number. Different elements could in fact be the same object. An array can even contain itself. Very complicated and useful structures can be built with PHP arrays. This power and flexibility are not cost-free, however. Performance and memory overhead could become unbearably high when working with elements numbered in the millions.

Arrays in PHP+QB are extremely simple by comparison. They are what’re commonly called C-arrays. Essentially, an array in PHP+QB is just a blob of memory. Elements are stored one after another. You can only refer to them using a numeric index. Order of insertion also does not matter in PHP+QB unlike in regular PHP. $array[0] will always come before $array[1] in a foreach loop in PHP+QB.

Arrays in PHP+QB can either be fixed- or variable-length. The dimensions of an array are declared in a function’s Doc Comment section. If a dimension is omitted, '?', or '*', then the array is variable-length.

Fixed Length Array

The use of fixed-length arrays will generally result in better-performing code. Where possible, use them instead of variable-length arrays. The type declaration of an fixed-length array should resemble the following:

/**
 * @engine qb
 * @local int32[4]  $array
 */

or for a class variable:

/** @var int32[4] */

Constants can be used in place of numbers. Starting from version 1.4, QB will look for a class constant with a given name before checking the global namespace.

If a PHP array passed to a PHP+QB function has more elements than declared, QB will raise a fatal error. If it has less, the missing elements will be initialized to zero.

Array with Named Elements

Instead of a number, you can place a list of comma-delimited names between the brackets. Doing so allows you to access array elements by name. For example, both float32[4] and float32[r,b,g,a] are four-element arrays, but the use of latter means you can specify its first element with $pixel->r instead of $pixel[0].

There must be at least two names on the list. Otherwise the parser will think that you're employing a constant to declare the dimension.

A string constant may be used to specify the list of names.

Multidimensional Array

Unlike in regular PHP, subarrays of multidimensional arrays in PHP+QB must all share the same length. A multidimensional array is in reality just a linear array. For example, if $a is declared to be int32[4][4], under the hood $a is really an int32[16]. When you access $a[$i][$j], QB will calculate the actual index by multiplying $i by 4 and add $j to it.

Currently, it's possible to have arrays with up to 8 dimensions.

Variable-length Array

There are two kinds of variable-length arrays in PHP+QB: autovivificious and non-autovivificious. The difference lies in how QB handles assignment to elements at indices beyond the current size. Autovivificious arrays expand automatically to accommodate the operation, whereas non-autovivificious arrays do not--a fatal error arises instead. Use '*' as the dimension to request autovivification.