-rw-r--r-- 3313 djbsort-20260127/doc/man/djbsort.3 raw
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "djbsort" "3" "" "" ""
.hy
.SS NAME
.PP
djbsort - sort array of integers or floating-point numbers
.SS SYNOPSIS
.PP
Using djbsort:
.IP
.nf
\f[C]
#include <djbsort.h>
\f[R]
.fi
.PP
Link with \f[V]-ldjbsort\f[R].
.PP
Sorting:
.IP
.nf
\f[C]
int32_t x[n];
\&...
djbsort_int32(x,n);
djbsort_int32down(x,n);

uint32_t x[n];
\&...
djbsort_uint32(x,n);
djbsort_uint32down(x,n);

float x[n];
\&...
djbsort_float32(x,n);
djbsort_float32down(x,n);

int64_t x[n];
\&...
djbsort_int64(x,n);
djbsort_int64down(x,n);

uint64_t x[n];
\&...
djbsort_uint64(x,n);
djbsort_uint64down(x,n);

double x[n];
\&...
djbsort_float64(x,n);
djbsort_float64down(x,n);
\f[R]
.fi
.SS DESCRIPTION
.PP
djbsort sorts an array \f[V]x\f[R] of \f[V]n\f[R] numeric elements,
placing the sorted result in the same array.
The \f[V]down\f[R] functions sort in reverse order.
.PP
The djbsort functions guarantee success: they sort in place, not
allocating memory beyond a small amount of stack space.
.PP
Each function returns without doing anything if \f[V]n\f[R] is
\f[V]1\f[R] or \f[V]0\f[R].
The \f[V]n\f[R] type is a signed \f[V]long long\f[R] and thus can also
be negative, in which case the function also returns without doing
anything.
(For any sorting library, a caller might sort all elements of a
size-\f[V]n\f[R] array past the \f[V]m\f[R]th by sorting
\f[V]x+m,n-m\f[R]; but what happens if \f[V]n\f[R] happens to be smaller
than \f[V]m\f[R] and the caller does not check for this?
Returning immediately on negative inputs is much more likely to be the
desired behavior than crashing.
Beware that this still does not deal with the problem of caller
arithmetic overflowing if, e.g., \f[V]m\f[R] and \f[V]n\f[R] are
\f[V]size_t\f[R] on a 32-bit machine.)
.PP
Each function guarantees that the outputs are exactly the inputs
permuted into non-decreasing order, or non-increasing order for the
\f[V]down\f[R] functions.
Some sorting libraries do not provide this guarantee for floating-point
arrays: they might replace some types of NaNs with other types of NaNs,
or might even crash for floating-point inputs containing NaNs.
.PP
Other libraries include sorting functions that are typically slower than
djbsort but that have the flexibility of being able to sort other data
types: \f[V]heapsort\f[R] (in libc; sorts arbitrary types in place using
a comparison callback); \f[V]mergesort\f[R] (in libbsd; sorts arbitrary
types using a comparison callback; typically faster than
\f[V]heapsort\f[R] but does not sort in place); \f[V]qsort\f[R] (in
libc; sorts arbitrary types in place using a comparison callback;
typically faster than \f[V]mergesort\f[R] but much slower for some
inputs); \f[V]radixsort\f[R] (in libbsd; sorts pointers to strings in
place); \f[V]std::sort\f[R] (in the C++ standard library; sorts
arbitrary comparable types using templates).
.SS SEE ALSO
.PP
\f[B]djbsort-fulltest\f[R](1), \f[B]djbsort-speed\f[R](1),
\f[B]djbsort-test\f[R](1), \f[B]heapsort\f[R](3),
\f[B]mergesort\f[R](3), \f[B]qsort\f[R](3), \f[B]radixsort\f[R](3)