Histograms

In histogram.cecil:

let var max_histogram_values_to_keep:int;
template object histogram[T <= hashable[T]] isa hash_CR_table[T,integer];
  field title(@:histogram[`T]):string;
  field individual_values(@:histogram[`T]):hash_table[T,m_bag[any]];
  method new_unsorted_histogram[T <= hashable[T]]():histogram[T];
  method new_unsorted_histogram[T <= hashable[T]](t:string):histogram[T];
  method increment(t@:histogram[`T], x:T):void;
  method increment_by_count(t@:histogram[`T], x:T, cnt:integer):void;
  method add_value(t@:histogram[`T], k:T, elem:any):void;
  method increment(t@:histogram[`T], x:T, elem:any):void;
  method print_statistics(t@:histogram[`T]):string;
  method print_statistics(t@:histogram[`T], some_key:T|string):string;
  method print_statistics(t@:histogram[`T <= num], some_key@num:T):string;
  method print_string(t@:histogram[`T]):string;
  method print(t@:histogram[`T]):void;
  method frequency_sorted_print_string(t@:histogram[`T]):string;
  method percent_print_string(t@:histogram[`T]):string;
  method truncated_percent_print_string(t@:histogram[`T <= ordered[T]],
                                        over:T):string;
  method unsorted_distribution[`T <= hashable[T]](
        nm:string, cl:&(increment:&(value:T):void,
                        add_value:&(value:T, elem:any):void):void
        ):histogram[T];
template representation sorted_histogram[T <= ordered_hashable[T]]
                                                        isa histogram[T];
  method new_histogram[T <= ordered_hashable[T]]():histogram[T];
  method new_histogram[T <= ordered_hashable[T]](t:string):histogram[T];
  method distribution[`T <= ordered_hashable[T]](
        nm:string, cl:&(increment:&(value:T):void,
                        add_value:&(value:T, elem:any):void):void
        ):histogram[T];
  method distribution(nm:string,
                      cl:&(increment:&(value:int):void,
                           add_value:&(value:int, elem:any):void):void
                      ):histogram[int];

A histogram supports accumulating counts for particular values and then printing out the results in a reasonable fashion. Abstractly, a histogram is a mapping from some domain of values to integers. The increment operation bumps the count associated with a particular value. To support the histogram's hash-table-based implementation, the values being counted by the histogram must be hashable. If the keys also are ordered, then nicer output is possible. The methods new_unsorted_histogram vs. new_histogram construct the two kinds of histograms.