src/core/math_func.hpp

   1 /* $Id$ */
   2
   3 /*
   4  * This file is part of OpenTTD.
   5  * OpenTTD is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 2.
   6  * OpenTTD is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
   7  * See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with OpenTTD. If not, see <http://www.gnu.org/licenses/>.
   8  */
   9
  10 /** @file math_func.hpp Integer math functions */
  11
  12 #ifndef MATH_FUNC_HPP
  13 #define MATH_FUNC_HPP
  14
  15 /**
  16  * Returns the maximum of two values.
  17  *
  18  * This function returns the greater value of two given values.
  19  * If they are equal the value of a is returned.
  20  *
  21  * @param a The first value
  22  * @param b The second value
  23  * @return The greater value or a if equals
  24  */
  25 template <typename T>
  26 static inline T max(const T a, const T b)
  27 {
  28         return (a >= b) ? a : b;
  29 }
  30
  31 /**
  32  * Returns the minimum of two values.
  33  *
  34  * This function returns the smaller value of two given values.
  35  * If they are equal the value of b is returned.
  36  *
  37  * @param a The first value
  38  * @param b The second value
  39  * @return The smaller value or b if equals
  40  */
  41 template <typename T>
  42 static inline T min(const T a, const T b)
  43 {
  44         return (a < b) ? a : b;
  45 }
  46
  47 /**
  48  * Returns the minimum of two integer.
  49  *
  50  * This function returns the smaller value of two given integers.
  51  *
  52  * @param a The first integer
  53  * @param b The second integer
  54  * @return The smaller value
  55  */
  56 static inline int min(const int a, const int b)
  57 {
  58         return min<int>(a, b);
  59 }
  60
  61 /**
  62  * Returns the minimum of two unsigned integers.
  63  *
  64  * This function returns the smaller value of two given unsigned integers.
  65  *
  66  * @param a The first unsigned integer
  67  * @param b The second unsigned integer
  68  * @return The smaller value
  69  */
  70 static inline uint minu(const uint a, const uint b)
  71 {
  72         return min<uint>(a, b);
  73 }
  74
  75 /**
  76  * Returns the absolute value of (scalar) variable.
  77  *
  78  * @note assumes variable to be signed
  79  * @param a The value we want to unsign
  80  * @return The unsigned value
  81  */
  82 template <typename T>
  83 static inline T abs(const T a)
  84 {
  85         return (a < (T)0) ? -a : a;
  86 }
  87
  88 /**
  89  * Return the smallest multiple of n equal or greater than x
  90  *
  91  * @note n must be a power of 2
  92  * @param x The min value
  93  * @param n The base of the number we are searching
  94  * @return The smallest multiple of n equal or greater than x
  95  */
  96 template <typename T>
  97 static inline T Align(const T x, uint n)
  98 {
  99         assert((n & (n - 1)) == 0 && n != 0);
 100         n--;
 101         return (T)((x + n) & ~((T)n));
 102 }
 103
 104 /**
 105  * Return the smallest multiple of n equal or greater than x
 106  * Applies to pointers only
 107  *
 108  * @note n must be a power of 2
 109  * @param x The min value
 110  * @param n The base of the number we are searching
 111  * @return The smallest multiple of n equal or greater than x
 112  * @see Align()
 113  */
 114 template <typename T>
 115 static inline T *AlignPtr(T *x, uint n)
 116 {
 117         assert_compile(sizeof(size_t) == sizeof(void *));
 118         return (T *)Align((size_t)x, n);
 119 }
 120
 121 /**
 122  * Clamp a value between an interval.
 123  *
 124  * This function returns a value which is between the given interval of
 125  * min and max. If the given value is in this interval the value itself
 126  * is returned otherwise the border of the interval is returned, according
 127  * which side of the interval was 'left'.
 128  *
 129  * @note The min value must be less or equal of max or you get some
 130  *       unexpected results.
 131  * @param a The value to clamp/truncate.
 132  * @param min The minimum of the interval.
 133  * @param max the maximum of the interval.
 134  * @returns A value between min and max which is closest to a.
 135  * @see ClampU(uint, uint, uint)
 136  * @see Clamp(int, int, int)
 137  */
 138 template <typename T>
 139 static inline T Clamp(const T a, const T min, const T max)
 140 {
 141         assert(min <= max);
 142         if (a <= min) return min;
 143         if (a >= max) return max;
 144         return a;
 145 }
 146
 147 /**
 148  * Clamp an integer between an interval.
 149  *
 150  * This function returns a value which is between the given interval of
 151  * min and max. If the given value is in this interval the value itself
 152  * is returned otherwise the border of the interval is returned, according
 153  * which side of the interval was 'left'.
 154  *
 155  * @note The min value must be less or equal of max or you get some
 156  *       unexpected results.
 157  * @param a The value to clamp/truncate.
 158  * @param min The minimum of the interval.
 159  * @param max the maximum of the interval.
 160  * @returns A value between min and max which is closest to a.
 161  * @see ClampU(uint, uint, uint)
 162  */
 163 static inline int Clamp(const int a, const int min, const int max)
 164 {
 165         return Clamp<int>(a, min, max);
 166 }
 167
 168 /**
 169  * Clamp an unsigned integer between an interval.
 170  *
 171  * This function returns a value which is between the given interval of
 172  * min and max. If the given value is in this interval the value itself
 173  * is returned otherwise the border of the interval is returned, according
 174  * which side of the interval was 'left'.
 175  *
 176  * @note The min value must be less or equal of max or you get some
 177  *       unexpected results.
 178  * @param a The value to clamp/truncate.
 179  * @param min The minimum of the interval.
 180  * @param max the maximum of the interval.
 181  * @returns A value between min and max which is closest to a.
 182  * @see Clamp(int, int, int)
 183  */
 184 static inline uint ClampU(const uint a, const uint min, const uint max)
 185 {
 186         return Clamp<uint>(a, min, max);
 187 }
 188
 189 /**
 190  * Reduce a signed 64-bit int to a signed 32-bit one
 191  *
 192  * This function clamps a 64-bit integer to a 32-bit integer.
 193  * If the 64-bit value is smaller than the smallest 32-bit integer
 194  * value 0x80000000 this value is returned (the left one bit is the sign bit).
 195  * If the 64-bit value is greater than the greatest 32-bit integer value 0x7FFFFFFF
 196  * this value is returned. In all other cases the 64-bit value 'fits' in a
 197  * 32-bits integer field and so the value is casted to int32 and returned.
 198  *
 199  * @param a The 64-bit value to clamps
 200  * @return The 64-bit value reduced to a 32-bit value
 201  * @see Clamp(int, int, int)
 202  */
 203 static inline int32 ClampToI32(const int64 a)
 204 {
 205         return (int32)Clamp<int64>(a, INT32_MIN, INT32_MAX);
 206 }
 207
 208 /**
 209  * Reduce an unsigned 64-bit int to an unsigned 16-bit one
 210  *
 211  * @param a The 64-bit value to clamp
 212  * @return The 64-bit value reduced to a 16-bit value
 213  * @see ClampU(uint, uint, uint)
 214  */
 215 static inline uint16 ClampToU16(const uint64 a)
 216 {
 217         /* MSVC thinks, in its infinite wisdom, that int min(int, int) is a better
 218          * match for min(uint64, uint) than uint64 min(uint64, uint64). As such we
 219          * need to cast the UINT16_MAX to prevent MSVC from displaying its
 220          * infinite loads of warnings. */
 221         return (uint16)min<uint64>(a, (uint64)UINT16_MAX);
 222 }
 223
 224 /**
 225  * Returns the (absolute) difference between two (scalar) variables
 226  *
 227  * @param a The first scalar
 228  * @param b The second scalar
 229  * @return The absolute difference between the given scalars
 230  */
 231 template <typename T>
 232 static inline T Delta(const T a, const T b)
 233 {
 234         return (a < b) ? b - a : a - b;
 235 }
 236
 237 /**
 238  * Checks if a value is between a window started at some base point.
 239  *
 240  * This function checks if the value x is between the value of base
 241  * and base+size. If x equals base this returns true. If x equals
 242  * base+size this returns false.
 243  *
 244  * @param x The value to check
 245  * @param base The base value of the interval
 246  * @param size The size of the interval
 247  * @return True if the value is in the interval, false else.
 248  */
 249 template <typename T>
 250 static inline bool IsInsideBS(const T x, const uint base, const uint size)
 251 {
 252         return (uint)(x - base) < size;
 253 }
 254
 255 /**
 256  * Checks if a value is in an interval.
 257  *
 258  * Returns true if a value is in the interval of [min, max).
 259  *
 260  * @param x The value to check
 261  * @param min The minimum of the interval
 262  * @param max The maximum of the interval
 263  * @see IsInsideBS()
 264  */
 265 template <typename T>
 266 static inline bool IsInsideMM(const T x, const uint min, const uint max)
 267 {
 268         return (uint)(x - min) < (max - min);
 269 }
 270
 271 /**
 272  * Type safe swap operation
 273  * @param a variable to swap with b
 274  * @param b variable to swap with a
 275  */
 276 template <typename T>
 277 static inline void Swap(T &a, T &b)
 278 {
 279         T t = a;
 280         a = b;
 281         b = t;
 282 }
 283
 284 /**
 285  * Converts a "fract" value 0..255 to "percent" value 0..100
 286  * @param i value to convert, range 0..255
 287  * @return value in range 0..100
 288  */
 289 static inline uint ToPercent8(uint i)
 290 {
 291         assert(i < 256);
 292         return i * 101 >> 8;
 293 }
 294
 295 /**
 296  * Converts a "fract" value 0..65535 to "percent" value 0..100
 297  * @param i value to convert, range 0..65535
 298  * @return value in range 0..100
 299  */
 300 static inline uint ToPercent16(uint i)
 301 {
 302         assert(i < 65536);
 303         return i * 101 >> 16;
 304 }
 305
 306 int LeastCommonMultiple(int a, int b);
 307 int GreatestCommonDivisor(int a, int b);
 308 int DivideApprox(int a, int b);
 309
 310 /**
 311  * Computes ceil(a / b) for non-negative a and b.
 312  * @param a Numerator
 313  * @param b Denominator
 314  * @return Quotient, rounded up
 315  */
 316 static inline uint CeilDiv(uint a, uint b)
 317 {
 318         return (a + b - 1) / b;
 319 }
 320
 321 /**
 322  * Computes ceil(a / b) * b for non-negative a and b.
 323  * @param a Numerator
 324  * @param b Denominator
 325  * @return a rounded up to the nearest multiple of b.
 326  */
 327 static inline uint Ceil(uint a, uint b)
 328 {
 329         return CeilDiv(a, b) * b;
 330 }
 331
 332 /**
 333  * Computes round(a / b) for signed a and unsigned b.
 334  * @param a Numerator
 335  * @param b Denominator
 336  * @return Quotient, rounded to nearest
 337  */
 338 static inline int RoundDivSU(int a, uint b)
 339 {
 340         if (a > 0) {
 341                 /* 0.5 is rounded to 1 */
 342                 return (a + (int)b / 2) / (int)b;
 343         } else {
 344                 /* -0.5 is rounded to 0 */
 345                 return (a - ((int)b - 1) / 2) / (int)b;
 346         }
 347 }
 348
 349 uint32 IntSqrt(uint32 num);
 350
 351 #endif /* MATH_FUNC_HPP */