/** * @file util.h * * @brief Utilities relating around number string representation and protected arithmatic helper * functions */ #ifndef UTIL_H #define UTIL_H #include #ifdef MGBA_LOGGING #include "mgba_logger.h" #endif /** * @def GBAL_UNUSED * @brief A friendly wrapper around the not so friendly looking __attribute__ syntax for ((unused)) */ #define GBAL_UNUSED __attribute__((unused)) #define UNDEFINED -1 /** * @def MAX_BASE36 * @brief Hex value of "ZZZZZZ" in base 36 */ #define MAX_BASE36 0x81BF0FFF /** * @def SIGN * @brief Get the sign (signum) of an integer * * @return 1,-1,0 if the number is positive,negative, or 0, respectively. */ #define SIGN(x) ((x > 0) - (x < 0)) /** * @def NUM_ELEM_IN_ARR * @brief Get the number of elements in an array * * @param arr input array */ #define NUM_ELEM_IN_ARR(arr) (sizeof(arr) / sizeof((arr)[0])) #define INT_MAX_DIGITS 11 // strlen(str(INT_MAX)) = strlen("-2147483647") #define UINT_MAX_DIGITS 10 // strlen(str(UINT32_MAX)) = strlen("4294967295") #define UINT8_MAX_DIGITS 3 // strlen(str(UINT8_MAX)) = strlen("255") #define BASE36_MAX_DIGITS 6 // strlen("ZZZZZZ") #define ONE_K 1000 #define ONE_M 1000000 #define ONE_B 1000000000 #define ONE_K_ZEROS 3 #define ONE_M_ZEROS 6 #define ONE_B_ZEROS 9 // The suffix replaces everything past the third digit, e.g. "999K" -> "1M" // so it needs at least this number of chars to be able to display any suffixed number #define SUFFIXED_NUM_MIN_REQ_CHARS 4 #ifdef MGBA_LOGGING #define LOG_ERROR(...) MGBA_FUNC_ERROR(__VA_ARGS__) #else // TODO: Add a define to conditionally compile print error to console and add it to the tests? #define LOG_ERROR(...) ((void)(0)) #endif // TODO: Document and clean documentation /** * @brief Returns @p ret_val and logs error @p message if @p expression is false. * * @param ret_val The value to return in case @p expression is false. * Pass @ref RET_NONE in a void function * * @param message The message to log in @p expression is false. * See @ref GBAL_RETURN_IF_ASSERT_FAILS for a version with a default message */ #define GBAL_CUST_MSG_RETURN_IF_ASSERT_FAILS(expression, ret_val, message, ...) \ do \ { \ if (!(expression)) \ { \ LOG_ERROR(message __VA_OPT__(,) __VA_ARGS__); \ return ret_val; \ } \ } while (0) /** * @brief Returns @p ret_val and logs an error message if @p expression is false. * * @param ret_val The value to return in case @p expression is false. * Pass @ref RET_NONE in a void function * * See @ref GBAL_CUST_MSG_RETURN_IF_ASSERT_FAILS for a version that allows passing * any custom error message. */ #define GBAL_RETURN_IF_ASSERT_FAILS(expression, ret_val) \ GBAL_CUST_MSG_RETURN_IF_ASSERT_FAILS(expression, ret_val, "Assert failed: %s", #expression) /** * @brief Returns @p ret_val and prints error message if @p param is equal to NULL. * Useful for checking arguments or function return values during control flow. * * @param ret_val The value to return in case @p param is equal to NULL. * Pass @ref RET_NONE in a void function * * This version is for a function that returns a value while @ref GBAL_VOID_FUNC_RETURN_IF_NULL * is for a void function. */ #define GBAL_RETURN_IF_NULL(param, ret_val) \ GBAL_CUST_MSG_RETURN_IF_ASSERT_FAILS((param) != NULL, ret_val, "Unexpected %s == NULL", #param) /** * @brief An empty return value for RETURN_IF macros when used in void functions * Expands to nothing because macros expand normally with blank arguments so it's more * to show that the empty value is intended. */ #define RET_NONE /** * @brief Avoid overflow when adding two u32 integers * * @param a left operator **a + b** * @param b left operator **a + b** * * @return the result of **a + b** or **UINT32_MAX** in case of overflow */ uint32_t u32_protected_add(uint32_t a, uint32_t b); /** * @brief Avoid overflow when adding two u16 integers * * @param a left operator **a + b** * @param b left operator **a + b** * * @return the result of **a + b** or **UINT16_MAX** in case of overflow */ uint16_t u16_protected_add(uint16_t a, uint16_t b); /** * @brief Avoid overflow when multiplying two u32 integers * * @param a left operator **a * b** * @param b left operator **a * b** * * @return the result of **a * b** or **UINT32_MAX** in case of overflow */ uint32_t u32_protected_mult(uint32_t a, uint32_t b); /** * @brief Avoid overflow when multiplying two u16 integers * * @param a left operator **a * b** * @param b left operator **a * b** * * @return the result of **a * b** or **UINT16_MAX** in case of overflow */ uint16_t u16_protected_mult(uint16_t a, uint16_t b); /** * @brief Truncate an unsigned number into a suffixed string representation e.g. 12000 -> "12K" * The least significant digits are rounded down e.g. 12345 -> "12K", 12987 -> "12K" * * @param num The number to truncate, can be anything from 0 to UINT32_MAX. * * @param num_req_chars The number of characters to constrain the string to. * The function will use up as much characters as it can * in order to maintain as much accuracy as possible. * So numbers are not fully truncated if not necessary, * e.g. 123123000 -> "123123K" for example value 7, * and if num_req_chars > u32_get_digits(num) the number will not * be truncated at all. * Passing less than SUFFIXED_NUM_MIN_REQ_CHARS may result in an * output string longer than num_req_chars but * can be done to truncate 1000s -> "1K", 2000 -> "2K" etc. * which wouldn't be otherwise. * * @param out_str An output buffer to write the resulting string to. * Must be of size UINT_MAX_DIGITS + 1. + 1 for null-terminator. * At that size the suffix character will always be accounted for since * a number with more digits than UINT_MAX_DIGITS will not be handled nor * truncated. */ void truncate_uint_to_suffixed_str( uint32_t num, int num_req_chars, char out_str_buff[UINT_MAX_DIGITS + 1] ); /** * @brief Get the number of digits in a 32-bit unsigned number * https://stackoverflow.com/questions/1068849/how-do-i-determine-the-number-of-digits-of-an-integer-in-c * * @param n 32-bit unsigned value to find the number of decimal digits of * * @return the number of digits in a number */ static inline int u32_get_digits(uint32_t n) { if (n < 10) return 1; if (n < 100) return 2; if (n < 1000) return 3; if (n < 10000) return 4; if (n < 100000) return 5; if (n < 1000000) return 6; if (n < 10000000) return 7; if (n < 100000000) return 8; if (n < 1000000000) return 9; return 10; } /** * @brief Convert a base-36 string representation to a 32-bit unsigned integer. * Since we are dealing with base-36 instead of decimal, the 32-bit decimal * value of a base-36 string representation `b36` is equal to: * * \f( b36[0] * 36^0 + b36[1] * 36^1 + b36[2] * 36^2 ... \f) * * @param b36_str input char[] to convert to decimal, must be of size `BASE36_MAX_DIGITS+1` * * @returns the 32-bit unsigned value of `b36_str` */ uint32_t base36_to_u32(const char b36_str[]); /** * @brief Convert a 32-bit unsigned integer to its base-36 string representation. * This will perform 6 divisions, so it will be significantly more expensive * than its `base36_to_u32` counterpart. * * We will iterate over all digits from `BASE36_MAX_DIGITS-1` to 0 and determine * their values in base-36, to then construct the string representation `b36_str` * in base-36 or the integer `n` * * Initially set to `n`, the variable `acc` will contain any given stage `i`: * ``` * b32[i] * 36^i + b32[i-1] * 36^(i-1) + ... + b32[0] * ``` * * And we can thus extract the two following values: * ``` * b32[i] = acc / 36^i * acc = acc mod 36^i = b32[i-1] * 36^(i-1) + ... + b32[0] * ``` * * So that acc can now be used for the following step, until `i` hits 0 * * @param n integer value to convert to a base-36 representation * @param b36_str output char[], representation of `n` in base-36 * * @sa base36_to_u32 */ void u32_to_base36(uint32_t n, char b36_str[]); #endif // UTIL_H