Java API reference
Every public function of the Java library (JNI, or FFM on Java 22 and newer), with its parameters and results (Kwker 0.1.0).
Kwker for Java: sorting, selection, argsort and top-k of primitive arrays, in place and without copies, with the fastest engine for the CPU chosen at run time.
Order: smallest first, or largest first with DESCENDING. char[] sorts as unsigned 16-bit numbers,
and the sortUnsigned methods order byte / short / int / long as unsigned numbers.
The native libraries load from -Dkwker.lib=<path to libkwker_jni.so>, else from
java.library.path, else from the jar.
Notes: floating-point keys sort as Arrays.sort(double[]) does: -0.0 before 0.0, NaNs last (first
with NANS_FIRST). Plain sorts are not stable; argsort and topK keep equal keys in index order.
ASCENDING, DESCENDING, NANS_FIRST Page
public static final int ASCENDING = 0, DESCENDING = 1, NANS_FIRST = 2;
Order flags.
isa Page
public static String isa();
The engine in use: "avx512", "avx2", "sse42", "neon", "sve" or "portable".
Remarks: The engine changes only the speed, never a result (rule 11).
version Page
public static String version();
The library version.
sort (whole array, a range, an order)
sort Page
public static void sort(byte[] a);
public static void sort(short[] a);
public static void sort(char[] a);
public static void sort(int[] a);
public static void sort(long[] a);
public static void sort(float[] a);
public static void sort(double[] a);
public static void sort(byte[] a, int order);
public static void sort(short[] a, int order);
public static void sort(char[] a, int order);
public static void sort(int[] a, int order);
public static void sort(long[] a, int order);
public static void sort(float[] a, int order);
public static void sort(double[] a, int order);
public static void sort(int[] a, int from, int to);
public static void sort(long[] a, int from, int to);
public static void sort(float[] a, int from, int to);
public static void sort(double[] a, int from, int to);
Sorts a in place, ascending or in order (DESCENDING, NANS_FIRST); the from, to overloads sort a[from, to) only (ArrayIndexOutOfBoundsException outside the array). Not stable: equal keys are identical.
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.
Examples: Quickstart: Kwker Core: Sort an array, Core concepts: In place or a copy, Runtime controls: Fallback switches, Sorting: Sort in place
sortUnsigned Page
public static void sortUnsigned(byte[] a);
public static void sortUnsigned(short[] a);
public static void sortUnsigned(int[] a);
public static void sortUnsigned(long[] a);
Sorts a in place, ascending, its elements read as unsigned numbers (byte 0 to 255, short 0 to 65535, int and long by their unsigned values, as {@link Integer#compareUnsigned(int, int)} orders them).
selection: a[k] gets the key a full sort would put there, neither side sorted
select Page
public static void select(int[] a, int k, int order);
public static void select(long[] a, int k, int order);
public static void select(float[] a, int k, int order);
public static void select(double[] a, int k, int order);
a[k] gets the key a full sort would put there; every key before it sorts before or equal to it, every key after it after or equal. Neither side is sorted. IllegalArgumentException unless 0 <= k < a.length.
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.
Examples: Quickstart: Kwker Core: The median, without a full sort, Top-k and selection: The median and other positions
partial sort: the first k keys in order, the rest in any order
partialSort Page
public static void partialSort(int[] a, int k, int order);
public static void partialSort(long[] a, int k, int order);
public static void partialSort(float[] a, int k, int order);
public static void partialSort(double[] a, int k, int order);
Puts the first k keys of the order, sorted, into a[0, k); the rest stay in a[k, n) in any order. IllegalArgumentException unless 0 <= k <= a.length.
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.
Examples: Top-k and selection: Sort only the beginning
argsort: the stable sorting permutation (a unchanged)
argsort Page
public static int[] argsort(int[] a, int order);
public static int[] argsort(long[] a, int order);
public static int[] argsort(float[] a, int order);
public static int[] argsort(double[] a, int order);
The stable sorting permutation r of a in the order: a[r[0]], a[r[1]], ... are sorted, equal keys by index; a is not modified.
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.
Examples: Quickstart: Kwker Core: Get the order, not the sorted data, Order and ranking: The order of an array: argsort, Languages: The same calls in every language, Order and ranking: Reorder several columns together
top-k: the indices of the stable order's first k keys, in order (a unchanged)
topK Page
public static int[] topK(int[] a, int k, int order);
public static int[] topK(long[] a, int k, int order);
public static int[] topK(float[] a, int k, int order);
public static int[] topK(double[] a, int k, int order);
The indices of the stable order's first k keys, in that order (equal keys by index); a is not modified. IllegalArgumentException unless 0 <= k <= a.length.
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.
Examples: Quickstart: Kwker Core: Find the top results, Use Kwker from Java: The program, Top-k and selection: The k largest or smallest values, Languages: The same calls in every language
TIES_ORDINAL, TIES_MIN, TIES_MAX, TIES_DENSE Page
public static final int TIES_ORDINAL = 0, TIES_MIN = 1, TIES_MAX = 2, TIES_DENSE = 3;
Rank ties for rank: distinct ranks in input order, the group's lowest rank, its highest, consecutive ranks per distinct key.
INTERSECTION, UNION, DIFFERENCE, SYMMETRIC_DIFFERENCE Page
public static final int INTERSECTION = 0, UNION = 1, DIFFERENCE = 2, SYMMETRIC_DIFFERENCE = 3;
Set operations for setOperation: keys in both, in either, in the first but not the second, in exactly one.
class Unique Page
public static final class Unique<A> {
public final A values;
public final int[] inverse;
public final int[] counts;
}
The result of unique: the distinct keys ascending, the group of every key and each group's size.
key-value: the values (any primitive array of the same length: int[], long[], double[], ...) move with their keys
sortKV Page
public static void sortKV(int[] keys, Object values, int order);
public static void sortKV(long[] keys, Object values, int order);
public static void sortKV(float[] keys, Object values, int order);
public static void sortKV(double[] keys, Object values, int order);
Sorts keys in place and moves each element of values with its key; equal keys' values end in unspecified order (sortKVStable keeps their input order).
Remarks: Unless the stable form is asked for, pairs with equal keys may come out in any order; the stable form keeps their input order (rule 6). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
Examples: Core concepts: In place or a copy, Sorting keys with values: Sort keys and values together
sortKVStable Page
public static void sortKVStable(int[] keys, Object values, int order);
public static void sortKVStable(long[] keys, Object values, int order);
public static void sortKVStable(float[] keys, Object values, int order);
public static void sortKVStable(double[] keys, Object values, int order);
sortKV, stable: equal keys keep their values in 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.
Examples: Sorting keys with values: Keep equal keys in order: the stable sort
partialSortKV Page
public static void partialSortKV(int[] keys, Object values, int k, int order);
public static void partialSortKV(long[] keys, Object values, int k, int order);
public static void partialSortKV(float[] keys, Object values, int k, int order);
public static void partialSortKV(double[] keys, Object values, int k, int order);
The first k keys of the order, sorted, each with its value; the rest in any order. IllegalArgumentException unless 0 <= k <= keys.length.
Remarks: The first k positions hold exactly what a full sort puts there; the rest hold the other keys in any order (rule 8). Unless the stable form is asked for, pairs with equal keys may come out in any order; the stable form keeps their input order (rule 6).
Examples: Sorting keys with values: Only the first k pairs
selectKV Page
public static void selectKV(int[] keys, Object values, int k, int order);
public static void selectKV(long[] keys, Object values, int k, int order);
public static void selectKV(float[] keys, Object values, int k, int order);
public static void selectKV(double[] keys, Object values, int k, int order);
keys[k] gets the key a full sort would put there, with its value; every key before it sorts before or equal to it, every key after it after or equal. Neither side is sorted. IllegalArgumentException unless 0 <= k < keys.length.
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). Unless the stable form is asked for, pairs with equal keys may come out in any order; the stable form keeps their input order (rule 6).
rows: a row-major array of rows of rowLength keys
sortRows Page
public static void sortRows(int[] a, int rowLength, int order);
public static void sortRows(long[] a, int rowLength, int order);
public static void sortRows(float[] a, int rowLength, int order);
public static void sortRows(double[] a, int rowLength, int order);
Sorts each row of a in place: a.length must be a multiple of rowLength (IllegalArgumentException otherwise).
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.
Examples: Sorting: Sort each row
searching: insertion positions in a sorted array
searchSorted Page
public static int[] searchSorted(int[] sorted, int[] queries, boolean right, int order);
public static int[] searchSorted(long[] sorted, long[] queries, boolean right, int order);
public static int[] searchSorted(float[] sorted, float[] queries, boolean right, int order);
public static int[] searchSorted(double[] sorted, double[] queries, boolean right, int order);
The position where each query goes in sorted, which must already be in order (not checked): before the keys equal to it (right false, the lower bound) or after them (right true, the upper bound). Values compare as in NumPy: -0.0 equals 0.0.
Remarks: -0.0 and +0.0 compare equal here, as in NumPy (rule 14).
Examples: Searching sorted data: Where does a value go? searchsorted, Searching sorted data: Which bucket? bucketize
ranks
rank Page
public static int[] rank(int[] a, int ties, int order);
public static int[] rank(long[] a, int ties, int order);
public static int[] rank(float[] a, int ties, int order);
public static int[] rank(double[] a, int ties, int order);
The 1-based rank of every key (r[i] is a[i]'s); equal keys ranked as ties says: TIES_ORDINAL (distinct, in input order), TIES_MIN, TIES_MAX or TIES_DENSE.
Remarks: Ordinal ranks give equal keys increasing ranks in input order (rule 6). Equal values are one key here, as in NumPy: -0.0 and +0.0 are equal, and so are all NaNs (rule 13).
Examples: Order and ranking: Ranks
rankAverage Page
public static double[] rankAverage(int[] a, int order);
public static double[] rankAverage(long[] a, int order);
public static double[] rankAverage(float[] a, int order);
public static double[] rankAverage(double[] a, int order);
The 1-based rank of every key, equal keys sharing the mean of their ranks (2 and 3 give 2.5 each).
Remarks: Equal values are one key here, as in NumPy: -0.0 and +0.0 are equal, and so are all NaNs (rule 13).
Examples: Order and ranking: Ranks
percentRank Page
public static double[] percentRank(int[] a, int order);
public static double[] percentRank(long[] a, int order);
public static double[] percentRank(float[] a, int order);
public static double[] percentRank(double[] a, int order);
Every key's percent rank, (min rank - 1) / (n - 1): 0 for the first key of the order, 1 for the last.
Remarks: Equal values are one key here, as in NumPy: -0.0 and +0.0 are equal, and so are all NaNs (rule 13).
Examples: Order and ranking: Ranks
unique keys and set operations
unique Page
public static Unique<int[]> unique(int[] a);
public static Unique<long[]> unique(long[] a);
public static Unique<float[]> unique(float[] a);
public static Unique<double[]> unique(double[] a);
The distinct keys ascending, the group of every key and each group's size. Floats: -0.0 and 0.0 are one key, every NaN its own.
Remarks: -0.0 and +0.0 are one value; every NaN is a value of its own, listed last (rule 15).
setOperation Page
public static int[] setOperation(int[] a, int[] b, int op, boolean multiset, int order);
public static long[] setOperation(long[] a, long[] b, int op, boolean multiset, int order);
public static float[] setOperation(float[] a, float[] b, int op, boolean multiset, int order);
public static double[] setOperation(double[] a, double[] b, int op, boolean multiset, int order);
A set operation on a and b, both already in order: INTERSECTION, UNION, DIFFERENCE (a without b) or SYMMETRIC_DIFFERENCE, in that order. Each key once, or with multiset the counts min, max, a - b or |a - b|.
Remarks: Equal values are one key here, as in NumPy: -0.0 and +0.0 are equal, and so are all NaNs (rule 13).
Examples: Groups, merges and sets: Set operations
engines
setIsa Page
public static String setIsa(String name);
Caps the engine of later calls ("avx512", "avx2", "sse42", "neon", "simd128", "portable"; null: the best the CPU and KWKER_ISA allow) and returns the engine now in use. Results never depend on the engine, only speed. Process-wide. IllegalArgumentException for an unknown name.
Remarks: The engine changes only the speed, never a result (rule 11).
Examples: Runtime controls: Fallback switches
several threads
sortMt Page
public static void sortMt(int[] a, int order, int threads);
public static void sortMt(long[] a, int order, int threads);
public static void sortMt(float[] a, int order, int threads);
public static void sortMt(double[] a, int order, int threads);
Sorts a in place on threads threads (0: the default count for the machine); the result is exactly {@link #sort(int[], int)}'s. IllegalArgumentException for threads < 0.
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. Threads change only the speed: the result follows the same rules on any thread count (rule 10).
Examples: Sorting: Big arrays: use more cores, Large data: Use several cores
extra memory
setScratchLimit Page
public static void setScratchLimit(long bytes);
Limits Kwker's extra memory for the calling thread's later calls to bytes (-1: no limit, the default; 0: sort, select, partialSort and sortKV allocate nothing). Results never change; some inputs sort slower. The limit belongs to the operating-system thread: a virtual thread can continue on another carrier thread after a blocking call, so set the limit again after one. IllegalArgumentException below -1.
Remarks: The scratch limit changes only the speed and memory use, never a result (rule 12).
Examples: Large data: Limit the extra memory
scratchLimit Page
public static long scratchLimit();
The calling thread's limit from setScratchLimit (-1: none).
Remarks: The scratch limit changes only the speed and memory use, never a result (rule 12).
Examples: Large data: Limit the extra memory
bucket counts: a histogram over boundaries you choose
bucketCounts Page
public static int[] bucketCounts(int[] values, int[] boundaries, boolean right, int order);
public static int[] bucketCounts(long[] values, long[] boundaries, boolean right, int order);
public static int[] bucketCounts(float[] values, float[] boundaries, boolean right, int order);
public static int[] bucketCounts(double[] values, double[] boundaries, boolean right, int order);
The number of values in each bucket of boundaries, which must already be in order (not checked): boundaries.length + 1 counts. With right false, v is in bucket i when boundaries[i-1] < v <= boundaries[i] (torch.bucketize); with right true when boundaries[i-1] <= v < boundaries[i]. No per-value array is built.
Remarks: -0.0 and +0.0 compare equal here, as in NumPy (rule 14).
Examples: Searching sorted data: How many in each bucket? bucket_counts
argselect: the positions of the first k keys, in no particular order
argselect Page
public static int[] argselect(int[] a, int k, int order);
public static int[] argselect(long[] a, int k, int order);
public static int[] argselect(float[] a, int k, int order);
public static int[] argselect(double[] a, int k, int order);
The positions of the order's first k keys, in no particular order (equal keys at the boundary taken by position); a is not modified. IllegalArgumentException unless 0 <= k <= a.length.
Remarks: The positions of the stable order's first k keys, in any order (rule 6). Keys follow the key order: -0.0 before +0.0, every NaN in one block, last unless NaNs-first is asked for.
Examples: Top-k and selection: Only the positions
top-k with a filter, top-k per group
class TopK Page
public static final class TopK<A> {
public final A values;
public final int[] indices;
}
The result of topKMasked: the keys in order and their positions in the input.
class Groups Page
public static final class Groups {
public final long[] labels;
public final int[] offsets;
public final int[] indices;
}
The result of topKByGroup: group i, label labels[i], owns indices[offsets[i]] .. indices[offsets[i + 1] - 1].
topKMasked Page
public static TopK<int[]> topKMasked(int[] a, boolean[] mask, int k, int order);
public static TopK<long[]> topKMasked(long[] a, boolean[] mask, int k, int order);
public static TopK<float[]> topKMasked(float[] a, boolean[] mask, int k, int order);
public static TopK<double[]> topKMasked(double[] a, boolean[] mask, int k, int order);
The order's first k keys among the positions where mask is true, sorted, with their positions in a (equal keys by position); fewer when fewer positions take part. mask has a's length.
Examples: Top-k and selection: Top-k with a filter
topKByGroup Page
public static Groups topKByGroup(int[] a, long[] groups, int k, int order);
public static Groups topKByGroup(long[] a, long[] groups, int k, int order);
public static Groups topKByGroup(float[] a, long[] groups, int k, int order);
public static Groups topKByGroup(double[] a, long[] groups, int k, int order);
For every distinct label in groups (ascending), the positions of that group's first k keys of the order (equal keys by position), like SQL ROW_NUMBER() OVER (PARTITION BY group ORDER BY key) <= k. groups has a's length.
Examples: Top-k and selection: Top-k per group
merging sorted arrays
kwayMerge Page
public static int[] kwayMerge(int order, int[]... runs);
public static long[] kwayMerge(int order, long[]... runs);
public static float[] kwayMerge(int order, float[]... runs);
public static double[] kwayMerge(int order, double[]... runs);
Merges arrays that are each already in the order (not checked) into one array in that order; equal keys keep the order of their runs.
Examples: Groups, merges and sets: Merge sorted lists: kway_merge
totals per key
SUM, MIN, MAX, FIRST, LAST Page
public static final int SUM = 0, MIN = 1, MAX = 2, FIRST = 3, LAST = 4;
Reductions for reduceByKey: the sum (integers wrap; floats add in input order), the minimum or the maximum (in the ascending order: -0.0 below 0.0, NaN above all), the key's first or last value in input order.
class ByKey Page
public static final class ByKey<K, V> {
public final K keys;
public final V values;
}
The result of reduceByKey and countByKey: the distinct keys in the order and one value per key.
reduceByKey Page
public static <V> ByKey<int[], V> reduceByKey(int[] keys, V values, int op, int order);
public static <V> ByKey<long[], V> reduceByKey(long[] keys, V values, int op, int order);
public static <V> ByKey<float[], V> reduceByKey(float[] keys, V values, int op, int order);
public static <V> ByKey<double[], V> reduceByKey(double[] keys, V values, int op, int order);
The distinct keys in the order and one reduction of their values each: SUM, MIN, MAX, FIRST or LAST, like SQL SELECT key, SUM(value) ... GROUP BY key. values: an int[], long[], float[] or double[] of keys.length elements; the result's values have its type.
Examples: Groups, merges and sets: Totals per key: reduce_by_key
countByKey Page
public static ByKey<int[], int[]> countByKey(int[] keys, int order);
public static ByKey<long[], int[]> countByKey(long[] keys, int order);
public static ByKey<float[], int[]> countByKey(float[] keys, int order);
public static ByKey<double[], int[]> countByKey(double[] keys, int order);
The distinct keys in the order and how often each occurs.
Examples: Groups, merges and sets: Totals per key: reduce_by_key
several key columns
class Column Page
public static final class Column {
}
One key column of lexsort and groupCodes: a primitive array (char[]: unsigned 16-bit) and its order.
class GroupCodes Page
public static final class GroupCodes {
public final int[] codes;
public final int[] first;
public final int[] sizes;
}
The result of groupCodes: the group of every row, and each group's first row and size.
lexsort Page
public static int[] lexsort(Column... cols);
The stable permutation that sorts the rows by the columns, the first column most significant, each in its own order (equal rows by position), like SQL ORDER BY a, b DESC.
Examples: Order and ranking: Sort by several columns
lexTopK Page
public static int[] lexTopK(int k, Column... cols);
The first min(k, n) rows of lexsort's order, without sorting every row (SQL ORDER BY .. LIMIT k). IllegalArgumentException for k < 0.
Examples: Order and ranking: Sort by several columns
groupCodes Page
public static GroupCodes groupCodes(Column... cols);
Numbers the rows' groups 0, 1, ... in the columns' lexicographic order (rows equal in every column share one): each row's group, and each group's first row and size.
Examples: Groups, merges and sets: Group several key columns: group_codes
reordering records
COLLATE_BYTES Page
public static final int COLLATE_BYTES = 0;
sortStrings / argsortStrings collation: byte order of the UTF-8 encoding (Unicode code point
order; String.compareTo orders UTF-16 units, which differs for characters above U+FFFF).
COLLATE_CASELESS Page
public static final int COLLATE_CASELESS = 1;
Collation: ASCII letters compare without case; other characters by their UTF-8 bytes.
COLLATE_NATURAL Page
public static final int COLLATE_NATURAL = 2;
Collation: digit runs compare as numbers ("file2" before "file10"), leading zeros ignored.
COLLATE_NATURAL_CASELESS Page
public static final int COLLATE_NATURAL_CASELESS = 3;
Collation: COLLATE_NATURAL and COLLATE_CASELESS together.
argsortStrings Page
public static int[] argsortStrings(String[] a, int collation);
The stable order of a in a collation (COLLATE_BYTES and the others): a[r[0]], a[r[1]], ...
is sorted, strings the collation treats as equal keep their input order; a is not modified.
Throws
NullPointerException: for a null string
Examples: Strings: The order of strings
sortStrings Page
public static void sortStrings(String[] a, int collation);
Sorts a in place in a collation (see argsortStrings); stable.
Examples: Strings: Sort a list of strings
permuteInPlace Page
public static <R> void permuteInPlace(R[] records, int[] perm);
Reorders records in place so that record j becomes the one at perm[j] (an argsort result applied), without a copy of the array (n bits of scratch). IllegalArgumentException, records unchanged, unless perm is a permutation of 0 .. records.length - 1.
Examples: Order and ranking: Reorder records in place
files larger than memory
sortFile Page
public static void sortFile(Class<?> type, String input, String output, long memory, int order, int threads) throws java.io.IOException;
Sorts the file input of native-endian keys of type (int.class, long.class, float.class, double.class, short.class, char.class - unsigned 16-bit - or byte.class) into output (may be the same path) with about memory bytes of buffers (0: 256 MiB) on threads threads (0: the default): files larger than memory included. IOException for an I/O error or a length that is not a whole number of keys.