+/* Support for order statistics.
+
+ The kth order statistic of a statistical sample is equal to its kth-smallest
+ value. The minimum is the first order statistic and the maximum is the
+ largest. This code and data structure supplies infrastructure for
+ higher-level statistics that rely on order statistics. It is a kind of
+ "abstract base class" that is not useful on its own.
+
+ This is implemented here as a kind of "partial frequency table". The
+ order_stats_accumulate() and order_stats_accumulate_idx() functions
+ effectively generate all of the frequency table entries for the variable,
+ one by one, and pass them to the "accumulate" function, if any. They can
+ also record pairs of frequency tables entries surrounding desired target
+ cumulative weights in 'k' data structures.
+
+ Client use
+ ==========
+
+ The common pattern for clients to use statistics based on order statistics
+ is this:
+
+ - Create the higher-level statistic with, for example, percentile_create().
+
+ - Feed in all the data with order_stats_accumulate() or
+ order_stats_accumulate_idx(). The data must be in sorted order: if
+ necessary, use one of the sorting functions from sort.h to sort them.
+
+ - Obtain the desired results by examining the higher-level data structure or
+ by calling an appropriate function, e.g. percentile_calculate().
+
+ - Destroy the data structure with statistic_destroy().
+*/
+