Zig API reference

Every public function of the kwker Zig package (build.zig.zon, over the C library), with its parameters and results (Kwker 0.1.0).

Kwker for Zig: the C ABI (libkwker_c) over slices, sorted in place without copies. Key types: u8, i8, u16, i16, u32, i32, f32, u64, i64, f64 and f16. One ordering policy for every call: ascending or descending, NaNs last or first, -0.0 before +0.0, NaN payloads kept; index operations break ties by index (the stable order).

const kwk = @import("kwker");
kwk.sort(f64, values);                                     // ascending, NaNs last
kwk.sortOrder(i32, keys, .{ .descending = true });
try kwk.argsort(u32, keys, .{}, indices);                  // the stable sorting permutation
const m = try kwk.topK(f32, scores, 10, .{ .descending = true }, top_values, top_indices);

Types

Order Page

pub const Order = struct {
    descending: bool = false,
    nans_first: bool = false,
};

Sort direction and NaN placement.

Error Page

pub const Error = error{InvalidArgument};

A length that does not match (argsort / sortKV) or k out of range (select).

Functions

isa Page

pub fn isa() [:0]const u8;

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

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

version Page

pub fn version() [:0]const u8;

The library version, for example "0.1.0".

sort Page

pub fn sort(comptime T: type, v: []T) void;

Sorts v ascending (NaNs last).

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.

sortOrder Page

pub fn sortOrder(comptime T: type, v: []T, o: Order) void;

Sorts v in order o.

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.

select Page

pub fn select(comptime T: type, v: []T, k: usize, o: Order) Error!void;

v[k] gets the key a full sort in order o would put there; every key before it sorts before or equal to it, every key after it after or equal. Neither side is sorted (k < v.len).

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.

partialSort Page

pub fn partialSort(comptime T: type, v: []T, k: usize, o: Order) void;

Sorts the first min(k, v.len) positions (the k first keys of order o, in order), the rest in any 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.

argsort Page

pub fn argsort(comptime T: type, v: []const T, o: Order, out: []u64) Error!void;

The stable sorting permutation of v into out (out.len == v.len): v[out[0]], v[out[1]], .. is sorted.

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.

argsortAlloc Page

pub fn argsortAlloc(allocator: std.mem.Allocator, comptime T: type, v: []const T, o: Order) ![]u64;

argsort into a new slice from allocator (the caller frees it).

topK Page

pub fn topK(comptime T: type, v: []const T, k: usize, o: Order, values: ?[]T, indices: ?[]u64) Error!usize;

The first m = min(k, v.len) keys of the stable order o, in order, into values[0..m] and their indices into indices[0..m] (either may be null; given ones need m entries); returns m. v is not modified.

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.

sortKV Page

pub fn sortKV(comptime T: type, comptime V: type, keys: []T, values: []V, o: Order) Error!void;

Sorts keys in order o and moves values[i] (any type: its bytes move) with keys[i] (keys.len == values.len).

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.