view release on metacpan or  search on metacpan

bundled/include/histo/sketch.h  view on Meta::CPAN

/**
 * @file sketch.h
 * @brief Public C API for DDSketch online quantile streaming sketches.
 */

#ifndef LIBHISTO_SKETCH_H
#define LIBHISTO_SKETCH_H

/**
 * @file sketch.h
 * @brief Online Dynamic Quantile Sketch (bounded relative-error, based on DDSketch).
 *
 * Provides dynamic logarithmic-binning quantile sketches capable of tracking
 * unbounded numeric ranges with mathematically guaranteed relative error bounds.
 */

#include "histo/types.h"
#include <stddef.h>
#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/** @brief Opaque sketch handle */
typedef struct histo_sketch histo_sketch_t;

/**
 * @brief Create a new dynamic quantile sketch with guaranteed relative error.
 *
 * @param[in] alpha    The relative error guarantee (e.g. 0.01 for +/- 1% accuracy). Must satisfy 0 < alpha < 1.
 * @param[in] max_bins Maximum number of bins before collapsing (limits memory consumption).
 * @return Pointer to new sketch handle, or NULL on memory failure or invalid arguments.
 *
 * @par Complexity:
 * O(1) time, O(max_bins) space.
 */
histo_sketch_t* histo_sketch_create(double alpha, uint32_t max_bins);

/**
 * @brief Destroy a sketch and release all allocated resources.
 *
 * Safe to call with NULL.
 *
 * @param[in,out] s The sketch handle to destroy.
 *
 * @par Complexity:
 * O(1) time and space.
 */
void histo_sketch_destroy(histo_sketch_t *s);

/**
 * @brief Insert a single value into the sketch with unit weight (1.0).
 *
 * @param[in,out] s     The sketch handle.
 * @param[in]     value The coordinate value to insert.
 * @return HISTO_OK on success, or HISTO_ERR_NON_FINITE if value is NaN/Inf.
 *
 * @par Complexity:
 * O(1) amortized time.
 */
histo_status_t histo_sketch_insert(histo_sketch_t *s, double value);