Brickworks > API documentation > bw_math

bw_math

Description

A collection of mathematical routines that strive to be better suited to DSP than, e.g., those supplied by your C standard library.

Such a goal is hopefully accomplished by:

• being as branchless as reasonable/convenient;
• not handling uninteresting corner cases, such as out-of-range, NaN, and sometimes infinity input values (out-of-range and NaN inputs are always considered invalid and lead to undefined behavior);
• returning approximated results (indicated in this documentation);
• making no distinction between `0.f` and `-0.f`.

In practice they should guarantee fast and consistent performance, but always do your own benchmarking.

All functions in this module are reentrant, RT-safe, thread-safe, and have no side effects.

Info

Module type: utility

Version: 1.0.1

Requires:

API

bw_signfilli32()

``````static inline int32_t bw_signfilli32(
int32_t x);
``````

Returns `~0` if `x` is negative, `0` otherwise.

bw_mini32()

``````static inline int32_t bw_mini32(
int32_t a,
int32_t b);
``````

Returns the minimum of `a` and `b`.

bw_maxi32()

``````static inline int32_t bw_maxi32(
int32_t a,
int32_t b);
``````

Returns the maximum of `a` and `b`.

bw_clipi32()

``````static inline int32_t bw_clipi32(
int32_t x,
int32_t m,
int32_t M);
``````

Returns `x` unless it is smaller than `m`, in which case it returns `m`, or bigger than `M`, in which case it returns `M`.

bw_minu32()

``````static inline uint32_t bw_minu32(
uint32_t a,
uint32_t b);
``````

Returns the minimum of `a` and `b`.

bw_maxu32()

``````static inline uint32_t bw_maxu32(
uint32_t a,
uint32_t b);
``````

Returns the maximum of `a` and `b`.

bw_clipu32()

``````static inline uint32_t bw_clipu32(
uint32_t x,
uint32_t m,
uint32_t M);
``````

Returns `x` unless it is smaller than `m`, in which case it returns `m`, or bigger than `M`, in which case it returns `M`.

bw_copysignf()

``````static inline float bw_copysignf(
float x,
float y);
``````

Returns a value that has the absolute value of `x` and the sign of `y`.

bw_signf()

``````static inline float bw_signf(
float x);
``````

Returns `1.f` if `x > 0.f`, `-1.f` if `x < 0.f` and `0.f` if `x == 0.f`.

bw_absf()

``````static inline float bw_absf(
float x);
``````

Returns the absolute value of `x`.

bw_min0f()

``````static inline float bw_min0f(
float x);
``````

Returns the minimum of `0.f` and `x`.

bw_max0f()

``````static inline float bw_max0f(
float x);
``````

Returns the maximum of `0.f` and `x`.

bw_minf()

``````static inline float bw_minf(
float a,
float b);
``````

Returns the minimum of `a` and `b`.

bw_maxf()

``````static inline float bw_maxf(
float a,
float b);
``````

Returns the maximum of `a` and `b`.

bw_clipf()

``````static inline float bw_clipf(
float x,
float m,
float M);
``````

Returns `x` unless it is smaller than `m`, in which case it returns `m`, or bigger than `M`, in which case it returns `M`.

`M` must be greater than or equal to `m`.

bw_truncf()

``````static inline float bw_truncf(
float x);
``````

Returns `x` with its fractional part set to zero (i.e., rounded towards zero).

`x` must be finite.

bw_roundf()

``````static inline float bw_roundf(
float x);
``````

Returns `x` rounded to the nearest integer.

Halfway cases are rounded away from zero. E.g., `bw_roundf(0.5f)` gives `1.f` and `bw_roundf(-0.5f)` gives `-1.f`.

`x` must be finite.

bw_floorf()

``````static inline float bw_floorf(
float x);
``````

Returns the biggest integer less or equal than `x` (i.e., `x` is rounded down).

`x` must be finite.

bw_ceilf()

``````static inline float bw_ceilf(
float x);
``````

Returns the smallest integer greater or equal than `x` (i.e., `x` is rounded up).

`x` must be finite.

bw_intfracf()

``````static inline void bw_intfracf(
float               x,
float * BW_RESTRICT i,
float * BW_RESTRICT f);
``````

Puts the integer part (floor) of `x` in `i` and the fractional part in `f`.

`x` must be finite.

bw_rcpf()

``````static inline float bw_rcpf(
float x);
``````

Returns the reciprocal of `x` (i.e., `1.f / x`).

|`x`| must be in [`8.077935669463161e-28f`, `1.237940039285380e+27`].

Relative error < 0.0013%.

bw_sin2pif()

``````static inline float bw_sin2pif(
float x);
``````

Returns an approximation of the sine of 2 * pi * `x`, where `x` is given in radians.

`x` must be finite.

Absolute error < 0.011 or relative error < 1.7%, whatever is worse.

bw_sinf()

``````static inline float bw_sinf(
float x);
``````

Returns an approximation of the sine of `x`, where `x` is given in radians.

`x` must be finite.

Absolute error < 0.011 or relative error < 1.7%, whatever is worse.

bw_cos2pif()

``````static inline float bw_cos2pif(
float x);
``````

Returns an approximation of the cosine of 2 * pi * `x`, where `x` is given in radians.

`x` must be finite.

Absolute error < 0.011 or relative error < 1.7%, whatever is worse.

bw_cosf()

``````static inline float bw_cosf(
float x);
``````

Returns an approximation of the cosine of `x`, where `x` is given in radians.

`x` must be finite.

Absolute error < 0.011 or relative error < 1.7%, whatever is worse.

bw_tan2pif()

``````static inline float bw_tan2pif(
float x);
``````

Returns an approximation of the tangent of 2 * pi * `x`, where `x` is given in radians.

`x` must be finite and in [-1/4 + 5e-4f / pi, 1/4 - 5e-4f / pi] + k / 2, where k is any integer number.

Absolute error < 0.06 or relative error < 0.8%, whatever is worse.

bw_tanf()

``````static inline float bw_tanf(
float x);
``````

Returns an approximation of the tangent of `x`, where `x` is given in radians.

`x` must be finite and in [-pi/2 + 1e-3f, pi/2 - 1e-3f] + k * pi, where k is any integer number.

Absolute error < 0.06 or relative error < 0.8%, whatever is worse.

bw_log2f()

``````static inline float bw_log2f(
float x);
``````

Returns an approximation of the base-2 logarithm of `x`.

`x` must be finite and greater than or equal to `1.175494350822287e-38f`.

Absolute error < 0.0055 or relative error < 1.2%, whatever is worse.

bw_logf()

``````static inline float bw_logf(
float x);
``````

Returns an approximation of the natural logarithm of `x`.

`x` must be finite and greater than or equal to `1.175494350822287e-38f`.

Absolute error < 0.0038 or relative error < 1.2%, whatever is worse.

bw_log10f()

``````static inline float bw_log10f(
float x);
``````

Returns an approximation of the base-10 logarithm of `x`.

`x` must be finite and greater than or equal to `1.175494350822287e-38f`.

Absolute error < 0.0017 or relative error < 1.2%, whatever is worse.

bw_pow2f()

``````static inline float bw_pow2f(
float x);
``````

Returns an approximation of 2 raised to the power of `x`. For `x < -126.f` it just returns `0.f`.

`x` must be less than or equal to `127.999f`.

Relative error < 0.062%.

bw_expf()

``````static inline float bw_expf(
float x);
``````

Returns an approximation of e (Euler's number) raised to the power of `x`. For `x < -87.3365447505531f` it just returns `0`.

`x` must be less than or equal to `88.722f`.

Relative error < 0.062%.

bw_pow10f()

``````static inline float bw_pow10f(
float x);
``````

Returns an approximation of 10 raised to the power of `x`. For `x < -37.92977945366162f` it just returns `0`.

`x` must be less than or equal to `38.531f`.

Relative error < 0.062%.

bw_dB2linf()

``````static inline float bw_dB2linf(
float x);
``````

Returns an approximation of 10 raised to the power of `x` / 20 (dB to linear ratio conversion). For `x < -758.5955890732315f` it just returns `0.f`.

`x` must be less than or equal to `770.630f`.

Relative error < 0.062%.

bw_lin2dBf()

``````static inline float bw_lin2dBf(
float x);
``````

Returns an approximation of 20 times the base-10 logarithm of `x` (linear ratio to dB conversion).

`x` must be finite and greater than or equal to `1.175494350822287e-38f`.

Absolute error < 0.032 or relative error < 1.2%, whatever is worse.

bw_sqrtf()

``````static inline float bw_sqrtf(
float x);
``````

Returns an approximation of the square root of `x`.

`x` must be finite and non-negative.

Absolute error < 1.09e-19 or relative error < 0.0007%, whatever is worse.

bw_tanhf()

``````static inline float bw_tanhf(
float x);
``````

Returns an approximation of the hyperbolic tangent of `x`.

Absolute error < 0.035 or relative error < 6.5%, whatever is worse.

bw_sinhf()

``````static inline float bw_sinhf(
float x);
``````

Returns an approximation of the hyperbolic sine of `x`.

|`x`| must less than or equal to `88.722f`.

Absolute error < 1e-7 or relative error < 0.07%, whatever is worse.

bw_coshf()

``````static inline float bw_coshf(
float x);
``````

Returns an approximation of the hyperbolic cosine of `x`.

|`x`| must less than or equal to `88.722f`.

Relative error < 0.07%.

bw_asinhf()

``````static inline float bw_asinhf(
float x);
``````

Returns an approximation of the hyperbolic arcsine of `x`.

|`x`| must less than or equal to `8.507059173023462e+37f`.

Absolute error < 0.004 or relative error < 1.2%, whatever is worse.

bw_acoshf()

``````static inline float bw_acoshf(
float x);
``````

Returns an approximation of the hyperbolic arccosine of `x`.

`x` must be in [1.f, 8.507059173023462e+37f].

Absolute error < 0.004 or relative error < 0.8%, whatever is worse.

ChangeLog

• Version 1.0.1:
• Now using `BW_NULL`.
• Fixed sign-related warnings in `bw_truncf()`, `bw_roundf()`, and `bw_sqrtf()`.
• Version 1.0.0:
• Renamed `bw_min0xf()` as `bw_min0f()` and `bw_max0xf()` as `bw_max0f()`.
• Removed precision suffixes from function names.
• New implementations for `bw_min0f()`, `bw_max0f()`, `bw_minf()`, `bw_maxf()`, and `bw_clipf()`.
• Fixed rounding bug in `bw_roundf()` when absolute value of input was in [`0.5f`, `1.f`].
• Fixed `bw_ceilf()` for negative input values.
• Fixed `bw_sqrtf()` for very large input values and improved implementation.
• Fixed input validity ranges in `bw_asinhf()` and `bw_acoshf()`.
• Added `BW_RESTRICT` specifiers to input arguments of `bw_intfracf()`.
• Removed usage of reserved identifiers and designated initializers.
• Added `extern "C"` to functions.
• Added more debugging checks in `bw_intfracf()`.
• Improved documentation w.r.t. validity of input values and approximation errors.
• Version 0.6.0:
• Removed `bw_omega_3log()` and `bw_omega_3lognr()`.
• Fixed `bw_pow10f_3()` and `bw_acoshf_3()`.
• Added `bw_ceilf()`, `bw_intfracf()`, `bw_sinhf_3()`, `bw_coshf_3()`, `bw_asinhf_3()`, and `bw_acoshf_3()`.
• Added `bw_log10f_3()`, `bw_pow10f_3()`, `bw_dB2linf_3()`, and `bw_lin2dBf_3()`.
• Fixed computation bug in `bw_sqrtf_2()`.
• Added `bw_sin2pif_3()`, `bw_cos2pif_3()`, `bw_tan2pif_3()`, `bw_omega_3lognr()`, and `bw_tanhf_3()`.