Skip to content

✨ (minor) v6: Add hal::divide() with floor, ceil and round - #131

Merged
kammce merged 3 commits into
mainfrom
v6-divide-round-up
Nov 16, 2026
Merged

kammce merged 3 commits into
mainfrom
v6-divide-round-up

Conversation

@kammce

@kammce kammce commented Nov 14, 2026 •

Copy link
Copy Markdown
Member

Adds hal::divide<Mode, T>(), an integer division that rounds its quotient down, up or to the nearest integer, and removes hal::rounding_division(). Closes #127.

auto const counts = hal::divide<hal::rounding::ceil, hal::u64>(
  { .num = cycles, .den = max_count });

Changes

  • hal::rounding has three modes, which round the way std::chrono::floor, std::chrono::ceil and std::chrono::round round a duration:
Mode 7 / 2 -7 / 2 5 / 2 7 / 3
floor 3 -4 2 2
ceil 4 -3 3 3
round (a half to even) 4 -4 2 2
/, for comparison 3 -3 2 2

Truncation stays plain /, as std::chrono::duration_cast truncates, so it isn't a mode. For unsigned types, floor is the same as /.

  • hal::division<T> names the operands num and den, as std::ratio does. Every call names them, so they can't be swapped.
  • hal::divide<Mode, T>(division<T>) works on any integral T. Since T is given, the braced operands convert to it, and an operand that would narrow into T is a compile error. ceil can't overflow, unlike (num + den - 1) / den. The magnitudes are worked in the unsigned type, so the smallest signed value doesn't overflow either. The one exception is that value divided by -1, which doesn't fit in T, the same as for /.
  • A denominator of 0 divides by 1, so the result is the numerator. In a constant expression it is a compile error instead: the compiler reports a division by zero in hal::divide().
  • hal::rounding_division() is removed. It had no callers in the org and gave wrong results: 7 / 3 gave 3, 3 / 4 and 1 / 2 gave 0, and 1 / 0 gave 0.

Not in this PR

The hand-written round-ups listed in #127 still use their own code: cycles_per, and in libhal-arm-mcu the SPI prescaler, the ADC wait, the I2C timing and the SysTick counts. They can switch to divide<rounding::ceil> once this is released. v5's rounding_division() is unchanged.

Testing

tests/math.test.cpp covers each mode in every sign combination, exact division, halves rounding to even, the largest and smallest values of 8-, 32- and 64-bit types, a 64-bit numerator over a 32-bit denominator, a run-time zero denominator, and calls in constant expressions. All 17 test suites pass with Clang 23, ASan and clang-tidy as warnings-as-errors. I also checked by hand that a constant zero denominator in a static_assert fails to compile.

Clock dividers, prescalers and tick counts need a quotient that rounds
up, and every caller wrote its own. hal::divide_round_up() is that, and
can't overflow the way adding the denominator before dividing can.

hal::rounding_division() was wrong for some inputs: 7 / 3 gave 3, 10 / 7
gave 2, 3 / 4 and 1 / 2 gave 0, and a zero denominator gave 0. It now
calls the new hal::divide_round_nearest(), which rounds to the nearest
integer and a half away from zero, for any integral type.

@kammce kammce left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good but I'm think it might be better to have a single divide function that accepts a enum as a template parameter to decide the rounding type. Like div::ceil, round, floor.

hal::divide<Mode, T>() replaces hal::divide_round_up(),
hal::divide_round_nearest() and hal::rounding_division(). The mode is
rounding::floor, ceil or round, each rounding the exact quotient like
the <cmath> function of the same name. Truncation stays plain /.

The operands are always named, { .num = ..., .den = ... }, so a call
can't swap them, and giving T keeps a narrowing operand a compile error.
A denominator of 0 divides by 1, except in a constant expression, where
it fails to compile.
@kammce kammce changed the title ✨ (minor) v6: Add hal::divide_round_up and hal::divide_round_nearest ✨ (minor) v6: Add hal::divide() with floor, ceil and round Nov 16, 2026
rounding::round now takes an exact half to the even neighbor, as
std::chrono::round does, so 5 / 2 is 2 and 7 / 2 is 4. With floor and
ceil already rounding like std::chrono::floor and ceil, all three modes
match the chrono functions of the same name.

A zero denominator in a constant expression now fails by dividing by
zero, so the compiler reports a division by zero inside hal::divide(),
instead of a call to a helper function.

@kammce kammce left a comment

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

✅

@kammce
kammce merged commit e20af84 into main Nov 16, 2026
9 of 10 checks passed
@kammce
kammce deleted the v6-divide-round-up branch November 16, 2026 19:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

v6: Add integer division that rounds up

1 participant