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(_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

Public API for a lightweight statistics helper working with fixed-size samples.

This header exposes a small C API to collect samples of arbitrary, fixed size and compute basic statistics for a set of supported scalar types.

Design highlights

  • The storage is a raw contiguous byte buffer; the size of one sample is given by Statistics::itemSize.

  • Sample rotation policy is intentionally minimal: the write position is controlled by Statistics::sampleIdx and wraps to 0 when the configured capacity is reached. When a full wrap occurs, Statistics::enoughSamples is set to true.

  • Memory primitives are provided by the port layer in statistics_config.h.

See statistics.c for the implementation details.

Type-specific statistic functions

For each enabled scalar type, a set of functions is generated. Replace <T> with one of: U8, I8, U16, I16, U32, I32, F (float).

Integer types (U8, I8, U16, I16, U32, I32):

  • int64_t Statistics_Mean_<T>(Statistics* stat) - Returns mean * 1000

  • <base> Statistics_Max_<T>(Statistics* stat)

  • <base> Statistics_Min_<T>(Statistics* stat)

  • int64_t Statistics_Variance_<T>(Statistics* stat) - Returns variance * 1000

  • int64_t Statistics_Stdev_<T>(Statistics* stat) - Returns stdev * 1000

Float type (F):

  • float Statistics_Mean_F(Statistics* stat) - Returns mean as float

  • float Statistics_Max_F(Statistics* stat)

  • float Statistics_Min_F(Statistics* stat)

  • float Statistics_Variance_F(Statistics* stat) - Returns variance as float

  • float Statistics_Stdev_F(Statistics* stat) - Returns stdev as float

Where <base> is the underlying C type for <T> (e.g., uint16_t for U16).

Note: Integer types use fixed-point arithmetic scaled by 1000 to avoid floating-point operations. Divide the result by 1000 to get the actual value. This is much faster on CPUs without FPU (e.g., STM32F0, Cortex-M0).

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.