Perl API reference

Every public function of the Kwker Perl module, for lists and PDL piddles, with its parameters and results (Kwker 0.1.0).

Kwker - SIMD numeric sorting, argsort and top-k for Perl lists and PDL piddles, through the Kwker C library.

Lists sort as int64 when every value is an integer, otherwise as doubles: NaNs last (NANS_FIRST puts them first) and -0.0 before 0.0. Values that a double cannot hold exactly (integers past 2**53, numeric strings) come back as the original scalars, in sorted order. Flags combine with |: DESC (largest first) and NANS_FIRST.

Functions

nsort Page

nsort(@numbers)

Returns a sorted copy of the numbers, smallest first, like sort { $a <=> $b } @numbers.

Example

my @s = nsort(3, 1, 2);  # (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.

nsort_desc Page

nsort_desc(@numbers)

Returns a sorted copy of the numbers, largest first.

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.

nsort_inplace Page

nsort_inplace(\@numbers, $flags = 0)

Sorts an array of numbers in place.

Arguments

• \@numbers: a reference to the array.
• $flags: DESC for largest first, NANS_FIRST to put NaNs first; combine with |.

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.

argsort Page

argsort(\@numbers, $flags = 0)

Returns the positions (0-based) that sort the array. Equal values keep their input order; the array is not changed.

Arguments

• \@numbers: a reference to the array.
• $flags: DESC and / or NANS_FIRST.

Example

my @ix = 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.

top_k Page

top_k(\@numbers, $k, $flags = 0)

Returns the $k smallest values in order and their positions (with DESC: the $k largest).

Arguments

• \@numbers: a reference to the array; not changed.
• $k: how many; more than the array's length returns them all.
• $flags: DESC and / or NANS_FIRST.

Returns

Two array references, values and positions; equal values go to the earlier position first.

Example

my ($v, $i) = Kwker::top_k([12, 7, 30, 18], 2, Kwker::DESC);  # [30, 18], [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.

DESC Page

DESC, NANS_FIRST

Flag constants: DESC (1) sorts largest first; NANS_FIRST (2) puts NaNs first instead of last.

pdl_sort Page

pdl_sort($piddle, $flags = 0)

Returns a sorted copy of a piddle of any integer or float type, of the same type and dims (sorted in flat order).

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.

pdl_sort_inplace Page

pdl_sort_inplace($piddle, $flags = 0)

Sorts a piddle in place; a slice is written back into its parent.

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.

pdl_argsort Page

pdl_argsort($piddle, $flags = 0)

Returns an indx piddle of the positions that sort the piddle's flat elements. Equal values keep their input order.

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.

pdl_top_k Page

pdl_top_k($piddle, $k, $flags = 0)

Returns two piddles: the $k first values in sorted order (the input's type) and their indx positions.

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.

pdl_select_inplace Page

pdl_select_inplace($piddle, $k, $flags = 0)

Puts the element a full sort would put at flat position $k there, smaller or equal elements before it and the rest after it.

Arguments

• $piddle: the piddle.
• $k: the flat position to fill, from 0 to nelem - 1 (it croaks otherwise).
• $flags: DESC and / or NANS_FIRST.

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.

pdl_partial_sort_inplace Page

pdl_partial_sort_inplace($piddle, $k, $flags = 0)

Puts the $k first elements of the sorted order, in order, at the front; the rest follow 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.

isa Page

isa()

The engine in use: avx512, avx2, neon, sve or portable.

Remarks: The engine changes only the speed, never a result (rule 11).

version Page

version()

The Kwker C library's version, for example 0.1.0.