Constants¶

Overview¶

tiny_constants.h defines the fundamental constants and utility macros used throughout TinyMath — from mathematical constants like \(\pi\) and \(\sqrt{2}\) to bit manipulation helpers and fixed-point scaling factors.

All constants are wrapped in #ifndef guards where appropriate, ensuring they don't conflict with definitions from other libraries.

Reference¶

Logical Constants¶

These are defined only if not already provided by the compiler or platform headers:

Constant	Value	Description
`TRUE`	`1`	Boolean true
`FALSE`	`0`	Boolean false
`NULL`	`((void *)0)`	Null pointer constant

Why #ifndef?

Some toolchains (e.g., FreeRTOS, ESP-IDF) already define TRUE/FALSE/NULL. The #ifndef guards prevent redefinition warnings.

Mathematical Constants¶

Floating-point constants for common mathematical values, suffixed with f for single-precision safety:

Macro	Value	Description
`TINY_PI`	\(3.14159265358979323846f\)	\(\pi\)
`TINY_TWO_PI`	\(6.28318530717958647692f\)	\(2\pi\)
`TINY_HALF_PI`	\(1.57079632679489661923f\)	\(\pi / 2\)
`TINY_E`	\(2.71828182845904523536f\)	Euler's number \(e\)
`TINY_SQRT2`	\(1.41421356237309504880f\)	\(\sqrt{2}\)
`TINY_INV_SQRT2`	\(0.70710678118654752440f\)	\(1 / \sqrt{2}\)

Angle conversion macros:

Macro	Formula	Example
`TINY_DEG2RAD(x)`	\(x \cdot \dfrac{\pi}{180^\circ}\)	`TINY_DEG2RAD(180.0f)` = \(3.14159\)
`TINY_RAD2DEG(x)`	\(x \cdot \dfrac{180^\circ}{\pi}\)	`TINY_RAD2DEG(TINY_PI)` = \(180.0\)

Usage

float circumference = 2.0f * TINY_PI * radius;
float sin_45 = sinf(TINY_DEG2RAD(45.0f));  // ≈ 0.707

Bit Manipulation Macros¶

Low-level bit operations for embedded register manipulation and flag handling:

Macro	Operation	Example
`TINY_BIT(n)`	Create bitmask \((1 \ll n)\)	`TINY_BIT(3)` = `0b00001000`
`TINY_BIT_SET(x, n)`	Set bit \(n\) of \(x\)	`TINY_BIT_SET(flags, 3)`
`TINY_BIT_CLEAR(x, n)`	Clear bit \(n\) of \(x\)	`TINY_BIT_CLEAR(flags, 3)`
`TINY_BIT_TOGGLE(x, n)`	Toggle bit \(n\) of \(x\)	`TINY_BIT_TOGGLE(flags, 3)`
`TINY_BIT_CHECK(x, n)`	Test bit \(n\) of \(x\) (returns `0` or `1`)	`TINY_BIT_CHECK(flags, 3)`

Common bitmask constants:

Macro	Mask	Width
`TINY_MASK_4BIT`	`0x0F`	4 bits
`TINY_MASK_8BIT`	`0xFF`	8 bits
`TINY_MASK_16BIT`	`0xFFFF`	16 bits
`TINY_MASK_32BIT`	`0xFFFFFFFF`	32 bits

Usage

uint8_t reg = 0;

TINY_BIT_SET(reg, 0);   // reg = 0b00000001
TINY_BIT_SET(reg, 7);   // reg = 0b10000001
TINY_BIT_CLEAR(reg, 0); // reg = 0b10000000

if (TINY_BIT_CHECK(reg, 7)) {
    // bit 7 is set
}

// Extract lower nibble
uint8_t lower = reg & TINY_MASK_4BIT;  // = 0x00

Fixed-Point Scaling Factors¶

For MCUs without a hardware FPU, fixed-point arithmetic can be orders of magnitude faster. These constants provide standard Q-format scaling factors:

Macro	Value	Format
`TINY_Q7_SCALE`	\(2^7 = 128\)	Q7 (1 byte)
`TINY_Q15_SCALE`	\(2^{15} = 32768\)	Q15 (2 bytes)
`TINY_Q31_SCALE`	\(2^{31} = 2147483648\)	Q31 (4 bytes)

When to Use Fixed-Point

On ESP32 (which has a hardware FPU), fixed-point is usually unnecessary. On simpler MCUs or for performance-critical inner loops, Q15 and Q31 formats provide excellent precision without floating-point overhead.

Safety Constants¶

These define numerical safety bounds used across all mathematical submodules:

Macro	Value	Purpose
`TINY_MATH_MIN_DENOMINATOR`	\(1 \times 10^{-6}\)	Minimum allowed denominator in divisions to prevent overflow / division by zero
`TINY_MATH_MIN_POSITIVE_INPUT_F32`	\(1 \times 10^{-12}\)	Minimum positive input for operations like `sqrt()` or `log()` — avoids domain errors
`TINY_MATH_LARGE_VALUE_F32`	\(1 \times 10^{38}\)	A "large number" safe for IEEE 754 single precision (max ≈ \(3.4 \times 10^{38}\)), used as a sentinel or infinity-like value

Source Code¶

/**
 * @file tiny_constants.h
 * @author SHUAIWEN CUI (SHUAIWEN001@e.ntu.edu.sg)
 * @brief This file contains the constants used in the tiny_math middleware.
 * @version 1.0
 * @date 2025-04-15
 * @copyright Copyright (c) 2025
 */

#pragma once

#ifdef __cplusplus
extern "C"
{
#endif

// =======================================
//  Logical Constants
// =======================================
#ifndef TRUE
#define TRUE 1
#endif

#ifndef FALSE
#define FALSE 0
#endif

#ifndef NULL
#define NULL ((void *)0)
#endif

// =======================================
//  Math Constants (float/double safe)
// =======================================
#define TINY_PI 3.14159265358979323846f
#define TINY_TWO_PI 6.28318530717958647692f
#define TINY_HALF_PI 1.57079632679489661923f
#define TINY_E 2.71828182845904523536f
#define TINY_SQRT2 1.41421356237309504880f
#define TINY_INV_SQRT2 0.70710678118654752440f

#define TINY_DEG2RAD(x) ((x) * TINY_PI / 180.0f)
#define TINY_RAD2DEG(x) ((x) * 180.0f / TINY_PI)

// =======================================
//  Bitmask & Bit Manipulation
// =======================================

// Bitwise operations
#define TINY_BIT(n) (1U << (n)) // e.g. TINY_BIT(3) = 0b00001000
#define TINY_BIT_SET(x, n) ((x) |= TINY_BIT(n))
#define TINY_BIT_CLEAR(x, n) ((x) &= ~TINY_BIT(n))
#define TINY_BIT_TOGGLE(x, n) ((x) ^= TINY_BIT(n))
#define TINY_BIT_CHECK(x, n) (((x) >> (n)) & 0x1U)

// Common bit masks
#define TINY_MASK_4BIT 0x0FU
#define TINY_MASK_8BIT 0xFFU
#define TINY_MASK_16BIT 0xFFFFU
#define TINY_MASK_32BIT 0xFFFFFFFFU

// =======================================
//  Fixed-Point Scaling Factors
// =======================================
#define TINY_Q7_SCALE 128          // 2^7
#define TINY_Q15_SCALE 32768       // 2^15
#define TINY_Q31_SCALE 2147483648U // 2^31

// =======================================
//  User-Defined Constants (Optional)
// =======================================
#define TINY_MATH_MIN_DENOMINATOR 1e-6f         // Minimum denominator for safe division
#define TINY_MATH_MIN_POSITIVE_INPUT_F32 1e-12f // Minimum positive input for float operations
#define TINY_MATH_LARGE_VALUE_F32 1e38f         // Large value used to represent infinity-like results (safe for IEEE 754 float, max ~3.4e38)

#ifdef __cplusplus
}
#endif