firmware-base/docs-c/core/xmath.md

title	description	keywords
XMath - Utility Functions for Mathematical Operations	Lightweight mathematical functions including template-based clamping and range checking	ESP-32 math clamp range normalize

XMath

Path: src/modbus/xmath.h

Revision History:

• Initial documentation

A lightweight utility header that provides essential mathematical operations for embedded systems. It includes a template-based clamp function and macros for range checking and normalized clamping.

REQUIREMENTS

• C++17 compiler support
• No hardware-specific requirements

PROVIDES

• clamp<T>() - Template function for clamping values within specified bounds
• RANGE() - Macro for checking if a value is within a specified range
• NCLAMP() - Macro for normalizing a value within a range to [0.0, 1.0]

FEATURES

• Type-generic clamping through template implementation
• Range checking for value validation
• Value normalization to a [0.0, 1.0] range
• Conditional compilation for C++ environments
• No standard library dependencies

DEPENDENCIES

• None

graph TD
    Application --> XMath

BEHAVIOUR

The XMath utilities provide deterministic mathematical operations:

graph LR
    A[Input Value] --> B{clamp}
    B --> |value < low| C[Return low]
    B --> |value > high| D[Return high]
    B --> |low ≤ value ≤ high| E[Return value]
    
    F[Input Value] --> G{RANGE}
    G --> |min < value < max| H[Return true]
    G --> |else| I[Return false]
    
    J[Input Value] --> K{NCLAMP}
    K --> L[Normalize to 0.0-1.0 range]

TODOS

PERFORMANCE

• Consider specialized implementations for common numeric types to avoid template instantiation overhead
• Evaluate potential for SIMD optimizations on compatible platforms

SECURITY

• No known security concerns as the utilities perform pure mathematical operations without side effects

COMPLIANCE

• Ensure all mathematical operations maintain expected precision for safety-critical applications
• Verify behavior with edge cases (e.g., handling of NaN, Inf values)

RECOMMENDATIONS

• Use clamp<T>() when working with specific types to leverage compile-time type checking
• Prefer the NCLAMP macro when normalizing sensor readings or other input values to a standardized range
• Consider adding additional mathematical utilities as needed for specific application domains