BLI: Math: Add description and test to `ceil_to_multiple` and `divide_ceil`

I took the decision to assert on unexpected value as the behavior of these
functions are not consistent across the whole integer domain.

1 files changed, 13 insertions, 0 deletions

diff --git a/source/blender/blenlib/BLI_math_vector.hh b/source/blender/blenlib/BLI_math_vector.hh
index e5273d050a6..384c4b49070 100644
--- a/source/blender/blenlib/BLI_math_vector.hh
+++ b/source/blender/blenlib/BLI_math_vector.hh
@@ -159,21 +159,34 @@ inline T safe_mod(const vec_base<T, Size> &a, const T &b)
   return result;
 }
 
+/**
+ * Returns \a a if it is a multiple of \a b or the next multiple or \a b after \b a .
+ * In other words, it is equivalent to `divide_ceil(a, b) * b`.
+ * It is undefined if \a a is negative or \b b is not strictly positive.
+ */
 template<typename T, int Size, BLI_ENABLE_IF((is_math_integral_type<T>))>
 inline vec_base<T, Size> ceil_to_multiple(const vec_base<T, Size> &a, const vec_base<T, Size> &b)
 {
   vec_base<T, Size> result;
   for (int i = 0; i < Size; i++) {
+    BLI_assert(a[i] >= 0);
+    BLI_assert(b[i] > 0);
     result[i] = ((a[i] + b[i] - 1) / b[i]) * b[i];
   }
   return result;
 }
 
+/**
+ * Integer division that returns the ceiling, instead of flooring like normal C division.
+ * It is undefined if \a a is negative or \b b is not strictly positive.
+ */
 template<typename T, int Size, BLI_ENABLE_IF((is_math_integral_type<T>))>
 inline vec_base<T, Size> divide_ceil(const vec_base<T, Size> &a, const vec_base<T, Size> &b)
 {
   vec_base<T, Size> result;
   for (int i = 0; i < Size; i++) {
+    BLI_assert(a[i] >= 0);
+    BLI_assert(b[i] > 0);
     result[i] = (a[i] + b[i] - 1) / b[i];
   }
   return result;