API reference

This section documents the public C API of the library. The documentation is extracted from header comments and grouped using Doxygen.

Overview

  • Core structures and functions live in the statistics_core group.

  • Main header file: include/statistics.h.

Groups

_STAT_SUPPORT_TYPE_INT(uint8_t, U8)
_STAT_SUPPORT_TYPE_INT(int8_t, I8)
_STAT_SUPPORT_TYPE_INT(uint16_t, U16)
_STAT_SUPPORT_TYPE_INT(int16_t, I16)
_STAT_SUPPORT_TYPE_INT(uint32_t, U32)
_STAT_SUPPORT_TYPE_INT(int32_t, I32)
_STAT_SUPPORT_TYPE_FLOAT(float, F)
_STAT_SUPPORT_TYPE_INT(_type, _NameSuffix)
_STAT_SUPPORT_TYPE_FLOAT(_type, _NameSuffix)
uint32_t samplesCnt

Number of samples allocated in the buffer. Total capacity (number of items).

uint32_t sampleIdx

Index of the current write position in the buffer. Current write index [0..samplesCnt-1].

uint8_t itemSize

Size of a single sample in bytes. Bytes per sample.

uint8_t *samples

Pointer to contiguous storage of size samplesCnt * itemSize. Backing storage pointer.

bool enoughSamples

Flag indicating that at least samplesCnt samples have been written, i.e., a full cycle completed and statistics are meaningful for the full window.

bool valid

Internal validity flag. Set to true only if initialization allocated the samples buffer successfully. Public callers can query this via Statistics_IsValid and must not call statistic functions if false.

void Statistics_Init(Statistics *stat, uint8_t itemSize, uint32_t samplesCount)

Initialize a statistics instance.

Allocates internal storage for samplesCount elements of itemSize bytes each and resets internal indices.

Parameters:
  • stat – [out] Pointer to the instance to initialize.

  • itemSize – Size of a single sample in bytes.

  • samplesCount – Number of samples in the window (capacity).

void Statistics_Reset(Statistics *stat)

Resets the statistical data contained in the provided Statistics structure.

This function clears all sample data stored in the Statistics instance, resets the sample index, and indicates that not enough samples are available to calculate meaningful statistics. It safely handles a null pointer by exiting early without performing any operations.

Parameters:

stat – A pointer to the Statistics structure to reset. If the pointer is null, the function will safely exit without performing any operations.

void Statistics_Free(Statistics *stat)

Release resources held by a statistics instance.

Parameters:

stat – Pointer to the instance to deinitialize.

void Statistics_AddSample(Statistics *stat, const void *sample)

Append a single sample to the buffer at the current write index.

The data at sample must point to Statistics::itemSize bytes. After storing, the write index advances and wraps when it reaches capacity.

Parameters:
  • stat – Pointer to the instance.

  • sample – Pointer to the sample data to store.

bool Statistics_HaveEnoughSamples(Statistics *stat)

Indicate whether a full window of samples has been collected.

Parameters:

stat – Pointer to the instance.

Returns:

true if at least Statistics::samplesCnt samples have been written (i.e., a wrap-around occurred), false otherwise.

bool Statistics_IsValid(const Statistics *stat)

Check whether the statistics instance has been initialized successfully.

This becomes false if memory allocation during Statistics_Init failed or after Statistics_Free.

Parameters:

stat – Pointer to the instance.

Returns:

true if the instance is valid and ready to use, false otherwise.

struct Statistics
#include <statistics.h>

Statistics buffer descriptor.

The structure describes a ring-like buffer that stores samplesCnt elements each of size itemSize bytes. New samples are written at sampleIdx and the index is advanced with wrap-around.

Main structure

struct Statistics

Statistics buffer descriptor.

The structure describes a ring-like buffer that stores samplesCnt elements each of size itemSize bytes. New samples are written at sampleIdx and the index is advanced with wrap-around.

Header file

Warning

doxygenfile: Cannot find file “include/statistics.h

Exponential smoothing filter

  • Structures and functions live in the exponential_smoothing_core group.

  • Header file: include/exponential_smoothing.h.

void ExponentialSmoothing_Init(ExponentialSmoothing *filter, int factor, float initValue)

Initialize the filter with a smoothing factor and starting value.

factor must be positive. A non-positive value leaves the filter in an invalid state where ExponentialSmoothing_Process and ExponentialSmoothing_GetValue are no-ops (the latter returns 0).

Parameters:
  • filter – [out] Pointer to the filter instance to initialize.

  • factor – Smoothing factor, must be > 0 (larger = smoother, slower to react).

  • initValue – Initial filtered value.

void ExponentialSmoothing_Process(ExponentialSmoothing *filter, float sample)

Feed a new sample into the filter.

Parameters:
  • filter – Pointer to the filter instance.

  • sample – New sample value.

float ExponentialSmoothing_GetValue(ExponentialSmoothing *filter)

Get the current filtered value.

Parameters:

filter – Pointer to the filter instance.

Returns:

Current filtered value, or 0 if filter is NULL.

struct ExponentialSmoothing
#include <exponential_smoothing.h>

Exponential smoothing filter state.

Linear regression

  • Structures and functions live in the linear_regression_core group.

  • Header file: include/linear_regression.h.

void linReg_clear(linReg_t *reg)

Clear intermediate calculations and start a new regression.

Parameters:

reg – Pointer to the regression instance.

void linReg_process(linReg_t *reg, float x, float y)

Add one X/Y point to the linear regression.

Parameters:
  • reg – Pointer to the regression instance.

  • x – X value.

  • y – Y value.

bool linReg_hasResult(linReg_t *reg)

Check whether enough samples have been added to compute a result.

Parameters:

reg – Pointer to the regression instance.

Returns:

true if sufficient samples are present.

bool linReg_result(linReg_t *reg, float *pM, float *pB, float *pR, float *pJitter)

Calculate current regression parameters.

y = m*x + b

Parameters:
  • reg – Pointer to the regression instance.

  • pM – Pointer to m - slope (can be NULL).

  • pB – Pointer to b - intercept (can be NULL).

  • pR – Pointer to r - correlation coefficient (can be NULL).

  • pJitter – Pointer to regression jitter (can be NULL).

Returns:

true if sufficient number of samples are present to calculate m, b and jitter.

float linReg_mUncertainty(linReg_t *reg, int32_t k, float resY)

Calculate uncertainty of the slope.

Parameters:
  • reg – Pointer to the regression instance.

  • k – Extended uncertainty factor.

  • resY – Resolution of Y values.

Returns:

Uncertainty of the slope.

struct linReg_t
#include <linear_regression.h>

Online linear regression state.