balatro-gba/include/util.h

/**
 * @file util.h
 *
 * @brief Utilities relating around number string representation and protected arithmatic helper
 * functions
 */
#ifndef UTIL_H
#define UTIL_H

#include <stdint.h>

/**
 * @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

/**
 * @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