Objective-C API reference

Every public function of the Kwker Objective-C class (Apple Foundation or GNUstep, over the C library), with its parameters and results (Kwker 0.1.0).

Kwker for Objective-C: class methods over Kwker's C ABI (libkwker_c). C buffers are sorted in place without copies; Foundation conveniences take NSMutableData (raw keys of an SSKeyType) and NSArray<NSNumber *>. Every method returns NO on a bad argument (k out of range, an unknown order) and leaves the data unchanged then. Results are the C library's: the engine is chosen at run time (AVX-512, AVX2, NEON, portable); floats in total order (-0.0 before +0.0, NaNs last unless SSOrderNaNsFirst); argsort / top-k are stable (equal keys by index).

Types

SSOrder Page

typedef NS_OPTIONS(uint32_t, SSOrder) {
    SSOrderAscending = 0,
    SSOrderDescending = 1,
    SSOrderNaNsFirst = 2,
};

Sort order flags, combined with |: ascending (0, the default), descending, NaNs first (floats; else NaNs come last).

SSKeyType Page

typedef NS_ENUM(NSInteger, SSKeyType) {
    SSKeyTypeUInt8, SSKeyTypeInt8, SSKeyTypeUInt16, SSKeyTypeInt16, SSKeyTypeUInt32, SSKeyTypeInt32,
    SSKeyTypeFloat, SSKeyTypeUInt64, SSKeyTypeInt64, SSKeyTypeDouble,
};

Key types of the NSMutableData methods.

Methods

+sortData:type:order: Page

+ (BOOL)sortData:(NSMutableData *)data type:(SSKeyType)type order:(SSOrder)order;

The keys of data (a whole number of type elements) sorted in place.

+argsortData:type:order: Page

+ (SS_NUMBERS *)argsortData:(NSData *)data type:(SSKeyType)type order:(SSOrder)order;

The stable sorting permutation of the keys of data (NSNumber indices, 64-bit unsigned), nil on a bad argument.

+sortedNumbers:order: Page

+ (SS_NUMBERS *)sortedNumbers:(SS_NUMBERS *)numbers order:(SSOrder)order;

numbers sorted (stable): compared as int64 when every number is an integer within int64, as uint64 when all are nonnegative integers and some exceed INT64_MAX, else as doubles; the result holds the input objects themselves.

+argsortNumbers:order: Page

+ (SS_NUMBERS *)argsortNumbers:(SS_NUMBERS *)numbers order:(SSOrder)order;

The stable sorting permutation of numbers (compared as sortedNumbers: does).

+isa Page

+ (NSString *)isa;

The engine the C library chose ("avx512", "avx2", "sse42", "neon", "portable", ...).

+version Page

+ (NSString *)version;

The C library's version (for example "0.1.0").

Typed C buffers

+sort<N>:count:order: Page

+ (BOOL)sort<N>:(<T> *)a count:(NSUInteger)n order:(SSOrder)order;

Sorts a[0..n) in place.

N / T: UInt8 (uint8_t), Int8 (int8_t), UInt16 (uint16_t), Int16 (int16_t), UInt32 (uint32_t), Int32 (int32_t), Float (float), UInt64 (uint64_t), Int64 (int64_t), Double (double).

+select<N>:count:k:order: Page

+ (BOOL)select<N>:(<T> *)a count:(NSUInteger)n k:(NSUInteger)k order:(SSOrder)order;

Puts at a[k] the key a full sort would put there (k < n); neither side is sorted.

N / T: UInt8 (uint8_t), Int8 (int8_t), UInt16 (uint16_t), Int16 (int16_t), UInt32 (uint32_t), Int32 (int32_t), Float (float), UInt64 (uint64_t), Int64 (int64_t), Double (double).

+partialSort<N>:count:k:order: Page

+ (BOOL)partialSort<N>:(<T> *)a count:(NSUInteger)n k:(NSUInteger)k order:(SSOrder)order;

Puts the first k keys of the order, sorted, at the front (k <= n).

N / T: UInt8 (uint8_t), Int8 (int8_t), UInt16 (uint16_t), Int16 (int16_t), UInt32 (uint32_t), Int32 (int32_t), Float (float), UInt64 (uint64_t), Int64 (int64_t), Double (double).

+argsort<N>:count:order:indices: Page

+ (BOOL)argsort<N>:(const <T> *)a count:(NSUInteger)n order:(SSOrder)order indices:(uint64_t *)indices;

Writes the stable sorting permutation into indices[0..n).

N / T: UInt8 (uint8_t), Int8 (int8_t), UInt16 (uint16_t), Int16 (int16_t), UInt32 (uint32_t), Int32 (int32_t), Float (float), UInt64 (uint64_t), Int64 (int64_t), Double (double).

+topK<N>:count:k:order:sorted:values:indices: Page

+ (BOOL)topK<N>:(const <T> *)a count:(NSUInteger)n k:(NSUInteger)k order:(SSOrder)order sorted:(BOOL)sorted values:(<T> *)values indices:(uint64_t *)indices;

Writes the first k keys of the stable order and their indices (sorted: in order); values or indices may be NULL.

N / T: UInt8 (uint8_t), Int8 (int8_t), UInt16 (uint16_t), Int16 (int16_t), UInt32 (uint32_t), Int32 (int32_t), Float (float), UInt64 (uint64_t), Int64 (int64_t), Double (double).