PHP API reference
Every public function of the kwker PHP extension and its Composer package, which have the same functions, with its parameters and results (Kwker 0.1.0).
Constants
KWKER_DESC Page
const KWKER_DESC = 1;
Flag: largest first (descending order). NaNs stay last unless KWKER_NANS_FIRST is also given.
KWKER_NANS_FIRST Page
const KWKER_NANS_FIRST = 2;
Flag: NaN values first instead of last (float arrays). Combine flags with |.
Functions
kwker_sort Page
function kwker_sort(array &$a, int $flags = 0): bool;
Sorts an array of ints or floats in place, smallest first. The array becomes a list (keys 0..n-1).
Arguments
$a: the values: ints only or floats only (a mix throws TypeError)$flags: KWKER_DESC for largest first, KWKER_NANS_FIRST to put NaNs first; combine with |
Returns
True
Example
$a = [3, 1, 2]; kwker_sort($a); // [1, 2, 3]
Remarks: Not stable (rule 5): keys that are equal but can be told apart (NaNs with different bits) may change places. Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
kwker_select Page
function kwker_select(array &$a, int $k, int $flags = 0): bool;
Puts the value a full sort would put at index k into $a[k], smaller or equal values before it and larger or equal values after it. With k = intdiv(count($a), 2) that is the median.
Arguments
$a: the values: ints only or floats only$k: the index to fill, 0 <= k < count($a) (else ValueError)$flags: KWKER_DESC and / or KWKER_NANS_FIRST
Returns
True
Example
$a = [50, 10, 40, 20, 30]; kwker_select($a, 2); // $a[2] is 30
Notes
- Only $a[k] is in its sorted place; the values on either side are in no particular order.
Remarks: Position k holds the key a full sort puts there; the keys before it are ordered before or equal to it, the keys after it after or equal (rule 7). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
kwker_partial_sort Page
function kwker_partial_sort(array &$a, int $k, int $flags = 0): bool;
Puts the k smallest values, sorted, at the front of the array.
Arguments
$a: the values: ints only or floats only$k: how many to sort, 0 <= k <= count($a) (else ValueError)$flags: KWKER_DESC (the k largest) and / or KWKER_NANS_FIRST
Returns
True
Notes
- The values after the first k are in no particular order.
Remarks: The first k positions hold exactly what a full sort puts there; the rest hold the other keys in any order (rule 8). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
kwker_argsort Page
function kwker_argsort(array $a, int $flags = 0): array;
Returns the positions (0-based) that sort the array. Equal values keep their input order; the array is not changed.
Arguments
$a: the values: ints only or floats only, taken in iteration order$flags: KWKER_DESC and / or KWKER_NANS_FIRST
Returns
A list of ints, one position per value
Example
kwker_argsort([30, 10, 20]); // [1, 2, 0]
Remarks: Stable (rule 6): equal keys keep their input order, so the same input always gives the same positions. Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
kwker_top_k Page
function kwker_top_k(array $a, int $k, int $flags = 0): array;
Returns the k smallest values in order with their positions (KWKER_DESC: the k largest).
Arguments
$a: the values: ints only or floats only; not changed$k: how many, 0 <= k <= count($a) (else ValueError)$flags: KWKER_DESC and / or KWKER_NANS_FIRST
Returns
['values' => list, 'indices' => list of ints]; equal values go to the earlier position first
Example
kwker_top_k([12, 7, 30, 18], 2, KWKER_DESC); // values [30, 18], indices [2, 3]
Remarks: The first k keys of the stable order and their positions; equal keys keep their input order (rule 9). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
kwker_isa Page
function kwker_isa(): string;
The engine in use: "avx512", "avx2", "sse42", "neon", "sve" or "portable".
Remarks: The engine changes only the speed, never a result (rule 11).
kwker_version Page
function kwker_version(): string;
The Kwker C library's version, for example "0.1.0".