mirror of
https://github.com/cellos51/balatro-gba.git
synced 2026-09-08 17:06:33 -05:00
266 lines
8.8 KiB
C
266 lines
8.8 KiB
C
/**
|
|
* @file util.h
|
|
*
|
|
* @brief Utilities relating around number string representation and protected arithmatic helper
|
|
* functions
|
|
*/
|
|
#ifndef UTIL_H
|
|
#define UTIL_H
|
|
|
|
#include <stdint.h>
|
|
#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
|