view release on metacpan or  search on metacpan

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

/**
 * @brief Deserializes a histogram from a canonical binary byte buffer.
 *
 * @param[in]  buf   Pointer to serialized binary buffer.
 * @param[in]  size  Byte length of buffer.
 * @param[out] out_h Pointer receiving address of newly deserialized histogram.
 * @return HISTO_OK on success, or HISTO_ERR_DESERIALIZATION on format corruption.
 */
histo_status_t histo_deserialize_binary(const void *buf, size_t size, histo_t **out_h);

/**
 * @brief Serializes a histogram into a newly allocated JSON string.
 *
 * Buffer must be freed with histo_free_buffer().
 *
 * @param[in]  h        Histogram handle to serialize.
 * @param[out] out_json Pointer receiving address of newly allocated null-terminated JSON string.
 * @return HISTO_OK on success, or appropriate error code.
 */
histo_status_t histo_serialize_json(const histo_t *h, char **out_json);

/**
 * @brief Deserializes a histogram from a JSON string.
 *
 * @param[in]  json_str Null-terminated JSON string.
 * @param[out] out_h    Pointer receiving address of newly deserialized histogram.
 * @return HISTO_OK on success, or HISTO_ERR_DESERIALIZATION on format corruption.
 */
histo_status_t histo_deserialize_json(const char *json_str, histo_t **out_h);

/**
 * @brief Frees a heap buffer allocated by serialization routines. Safe with NULL.
 *
 * @param[in] buf Buffer pointer to free.
 */
void histo_free_buffer(void *buf);

/**
 * @brief Migrates a binary serialized histogram to the current format version.
 *
 * If the input buffer is already at the current format version, it allocates
 * an exact copy. The returned buffer must be freed with histo_free_buffer().
 *
 * @param[in]  in_buf   Pointer to serialized binary buffer.
 * @param[in]  in_size  Byte length of input buffer.
 * @param[out] out_buf  Pointer receiving address of newly allocated migrated buffer.
 * @param[out] out_size Pointer receiving byte length of migrated buffer.
 * @return HISTO_OK on success, or appropriate error code.
 */
histo_status_t histo_migrate_binary(const void *in_buf, size_t in_size, void **out_buf, size_t *out_size);

/* ========================================================================= */
/* Automated Optimal Bin Width Heuristics                                    */
/* ========================================================================= */

/**
 * @brief Binning estimation heuristic rules.
 */
typedef enum histo_bin_rule {
    HISTO_BIN_RULE_AUTO    = 0,  /**< Automatic selection: Freedman-Diaconis with fallback to Scott [Default] */
    HISTO_BIN_RULE_FD      = 1,  /**< Freedman-Diaconis: h = 2 * IQR * n^(-1/3) */
    HISTO_BIN_RULE_SCOTT   = 2,  /**< Scott's normal reference: h = 3.49 * std * n^(-1/3) */
    HISTO_BIN_RULE_STURGES = 3,  /**< Sturges' rule: k = ceil(log2(n) + 1) */
    HISTO_BIN_RULE_DOANE   = 4,  /**< Doane's rule: Sturges adjusted for skewness */
    HISTO_BIN_RULE_KNUTH   = 5   /**< Knuth's Bayesian optimal binning rule */
} histo_bin_rule_t;

/**
 * @brief Estimates optimal uniform bin parameters using the Freedman-Diaconis rule.
 *
 * @param[in]  n         Number of samples (n >= 1).
 * @param[in]  values    Array of sample coordinates.
 * @param[out] out_nbins Pointer to store computed number of bins.
 * @param[out] out_min   Pointer to store lower boundary coordinate.
 * @param[out] out_max   Pointer to store upper boundary coordinate.
 * @return HISTO_OK on success, or error status code.
 */
histo_status_t histo_estimate_bins_fd(size_t n, const double *values, uint32_t *out_nbins, double *out_min, double *out_max);

/**
 * @brief Estimates optimal uniform bin parameters using Scott's normal reference rule.
 *
 * @param[in]  n         Number of samples (n >= 1).
 * @param[in]  values    Array of sample coordinates.
 * @param[out] out_nbins Pointer to store computed number of bins.
 * @param[out] out_min   Pointer to store lower boundary coordinate.
 * @param[out] out_max   Pointer to store upper boundary coordinate.
 * @return HISTO_OK on success, or error status code.
 */
histo_status_t histo_estimate_bins_scott(size_t n, const double *values, uint32_t *out_nbins, double *out_min, double *out_max);

/**
 * @brief Estimates optimal uniform bin parameters using Sturges' rule.
 *
 * @param[in]  n         Number of samples (n >= 1).
 * @param[in]  values    Array of sample coordinates.
 * @param[out] out_nbins Pointer to store computed number of bins.
 * @param[out] out_min   Pointer to store lower boundary coordinate.
 * @param[out] out_max   Pointer to store upper boundary coordinate.
 * @return HISTO_OK on success, or error status code.
 */
histo_status_t histo_estimate_bins_sturges(size_t n, const double *values, uint32_t *out_nbins, double *out_min, double *out_max);

/**
 * @brief Estimates optimal uniform bin parameters using Doane's skewness-adjusted rule.
 *
 * @param[in]  n         Number of samples (n >= 1).
 * @param[in]  values    Array of sample coordinates.
 * @param[out] out_nbins Pointer to store computed number of bins.
 * @param[out] out_min   Pointer to store lower boundary coordinate.
 * @param[out] out_max   Pointer to store upper boundary coordinate.
 * @return HISTO_OK on success, or error status code.
 */
histo_status_t histo_estimate_bins_doane(size_t n, const double *values, uint32_t *out_nbins, double *out_min, double *out_max);

/**
 * @brief Estimates optimal uniform bin parameters using Knuth's Bayesian rule.
 *
 * @param[in]  n         Number of samples (n >= 1).
 * @param[in]  values    Array of sample coordinates.