blob: 1aebf4ab3f66c1f6370a7150f69adeb7f741cc11 [file] [view] [edit]
---
name: libaom/prefer-clamp-over-nested-min-max-macros
description: When constraining values to a range, use clamp(), clamp64(), fclamp(), or clip_pixel() instead of nested AOMMIN/AOMMAX macros, ensuring low <= high for dynamic bounds
rubric: correctness
severity: blocking
---
**Rule.** When constraining integer, 64-bit, floating-point, or pixel values
between lower and upper limits, use standard inline helper functions clamp()
(for int), clamp64() (for int64_t), fclamp() (for double/float), or clip_pixel()
/ clip_pixel_highbd() from aom_dsp/aom_dsp_common.h rather than nesting or
chaining AOMMIN and AOMMAX macros. Additionally, when bounds are computed
dynamically and could invert (low > high), ensure low <= high holds or sanitize
the upper/lower bounds with AOMMAX/AOMMIN prior to calling clamp().
**Why.** AOMMIN and AOMMAX macros evaluate their arguments multiple times,
risking redundant computation and accidental side effects with complex
expressions. The inline helper functions evaluate arguments exactly once,
provide type safety, and improve readability across the codebase. Furthermore,
clamp(val, low, high) is implemented assuming low <= high; if dynamic bounds
invert (low > high), calling clamp() will produce values outside the intended
upper bound.
## Examples
Bad:
```cpp
// Nested macro calls cause redundant evaluations and side effects
const int val = AOMMAX(0, AOMMIN(QINDEX_RANGE - 1, input_val));
const double fval = AOMMAX(0.0, AOMMIN(1.0, rate_factor));
// Chained macros evaluate expressions multiple times
mv_limits->row_min = AOMMAX(mv_limits->row_min, -top_margin);
mv_limits->row_min = AOMMIN(mv_limits->row_min, mv_limits->row_max);
// If dynamic bounds can invert (-top_margin > row_max), clamp returns -top_margin (> row_max)
mv_limits->row_min = clamp(mv_limits->row_min, -top_margin, mv_limits->row_max);
```
Good:
```cpp
// Use inline helpers for concise, single-evaluation bounding
const int val = clamp(input_val, 0, QINDEX_RANGE - 1);
const double fval = fclamp(rate_factor, 0.0, 1.0);
// Sanitize dynamic bounds to guarantee low <= high before clamping
bottom_margin = AOMMAX(bottom_margin, -top_margin);
mv_limits->row_min = AOMMAX(mv_limits->row_min, -top_margin);
mv_limits->row_max = AOMMIN(mv_limits->row_max, bottom_margin);
```