histogram.h File Reference

Keep counts of doubles that fall in some given bucket size. More...

`#include "int_sizes.h"`

Go to the source code of this file.

## Functions

struct histogram * | histogram_create (double bucket_size)
| Create a new histogram.
void | histogram_clear (struct histogram *h)
| Remove all entries from a histogram.
void | histogram_delete (struct histogram *h)
| Delete a histogram.
int | histogram_size (struct histogram *h)
| Count the number of active buckets.
double * | histogram_buckets (struct histogram *h)
| Returns an ordered array with the start values of the active buckets.
double | histogram_bucket_size (struct histogram *h)
| Returns the bucket size.
int | histogram_insert (struct histogram *h, double value)
| Add value to histogram.
int | histogram_count (struct histogram *h, double value)
| Look up the count for the bucket of the given value.
void | histogram_set_bucket (struct histogram *h, double value, int count)
| Manually set the count for a bucket.
void | histogram_attach_data (struct histogram *h, double value, void *data)
| Attach custom data to bucket.
void * | histogram_get_data (struct histogram *h, double value)
| Retrieved custom data attached to the bucket.
int | histogram_total_count (struct histogram *h)
| Return the total number of samples in the histogram.
double | histogram_max_value (struct histogram *h)
| Return the maximum value inserted in the histogram.
double | histogram_min_value (struct histogram *h)
| Return the minimum value inserted in the histogram.
double | histogram_round_up (struct histogram *h, double test_value)
| Return the largest value of the bucket that test_value would faill in.
double | histogram_mode (struct histogram *h)
| Return the mode of the histogram.

## Detailed Description

Keep counts of doubles that fall in some given bucket size.

    struct histogram *h;
    double bucket_size = .5;
    h = histogram_create(bucket_size);

    // same bucket
    histogram_insert(h, 3.0);
    histogram_insert(h, 3.1415);

    // same bucket
    histogram_insert(h, 21.999);

    // same bucket
    histogram_insert(h, 22.0);
    histogram_insert(h, 22.2);
    histogram_insert(h, 22.499);

    // same bucket
    histogram_insert(h, 22.5);

    // same bucket
    histogram_insert(h, -21.999);

    // same bucket
    histogram_insert(h, -22.0);
    histogram_insert(h, -22.2);
    histogram_insert(h, -22.499);

    // same bucket
    histogram_insert(h, -22.5);

    double *buckets = histogram_buckets(h);
    double b        = histogram_bucket_size(h);

    int i;
    for(i = 0; i < histogram_size(h); i++) {

            double start = buckets[i];

            fprintf(stdout, "[%lf, $lf) has %d elements.\n", start, start + b, histogram_count(h, start));
    }

    free(buckets);
    histogram_delete(h);

## Function Documentation

## histogram_create()

struct histogram * histogram_create | ( | double | bucket_size | ) |

Create a new histogram.

Parameters

  bucket_size | Numbers are grouped according to [n*bucket_size, (n+1)*bucket_size), n in Z.

Returns
  A pointer to a new histogram.

## histogram_clear()

void histogram_clear | ( | struct histogram * | h | ) |

Remove all entries from a histogram.

Parameters

  h | The histogram to clear.

## histogram_delete()

void histogram_delete | ( | struct histogram * | h | ) |

Delete a histogram.

Parameters

  h | The histogram to delete.

## histogram_size()

int histogram_size | ( | struct histogram * | h | ) |

Count the number of active buckets.

Returns
  The number of active buckets in the histogram.

Parameters

  h | A pointer to a histogram.

## histogram_buckets()

double * histogram_buckets | ( | struct histogram * | h | ) |

Returns an ordered array with the start values of the active buckets.

## histogram_bucket_size()

double histogram_bucket_size | ( | struct histogram * | h | ) |

Returns the bucket size.

## histogram_insert()

int histogram_insert | ( | struct histogram * | h,
|  | double | value )

Add value to histogram.

Parameters

  h | A pointer to a histogram.
  value | A number to add to the histogram.

Returns
  The updated count of the respective bucket.

## histogram_count()

int histogram_count | ( | struct histogram * | h,
|  | double | value )

Look up the count for the bucket of the given value.

Parameters

  h | A pointer to a histogram.
  value | A number that would fall inside the desired bucket.

Returns
  The count for the bucket.

## histogram_set_bucket()

void histogram_set_bucket | ( | struct histogram * | h,
|  | double | value,
|  | int | count )

Manually set the count for a bucket.

Parameters

  h | A pointer to a histogram.
  value | A number that would fall inside the desired bucket.
  count | The desired count.

## histogram_attach_data()

void histogram_attach_data | ( | struct histogram * | h,
|  | double | value,
|  | void * | data )

Attach custom data to bucket.

Parameters

  h | A pointer to a histogram.
  value | A number that would fall inside the desired bucket.
  data | A pointer to external data.

## histogram_get_data()

void * histogram_get_data | ( | struct histogram * | h,
|  | double | value )

Retrieved custom data attached to the bucket.

Parameters

  h | A pointer to a histogram.
  value | A number that would fall inside the desired bucket.

Returns
  A pointer to external data.

## histogram_total_count()

int histogram_total_count | ( | struct histogram * | h | ) |

Return the total number of samples in the histogram.

Parameters

  h | A pointer to a histogram.

Returns
  Count of all the samples.

## histogram_max_value()

double histogram_max_value | ( | struct histogram * | h | ) |

Return the maximum value inserted in the histogram.

Parameters

  h | A pointer to a histogram.

Returns
  Maximum value inserted.

## histogram_min_value()

double histogram_min_value | ( | struct histogram * | h | ) |

Return the minimum value inserted in the histogram.

Parameters

  h | A pointer to a histogram.

Returns
  Minimum value inserted.

## histogram_round_up()

double histogram_round_up | ( | struct histogram * | h,
|  | double | test_value )

Return the largest value of the bucket that test_value would faill in.

Parameters

  h | A pointer to a histogram.
  test_value | value to round up

Returns
  test_value rounded up according to bucket size.

## histogram_mode()

double histogram_mode | ( | struct histogram * | h | ) |

Return the mode of the histogram.

Parameters

  h | A pointer to a histogram.

Returns
  Histogram mode.