nanocoat/include/sjme/util.h

   1 /* -*- Mode: C; indent-tabs-mode: t; tab-width: 4 -*-
   2 // ---------------------------------------------------------------------------
   3 // SquirrelJME
   4 //     Copyright (C) Stephanie Gawroriski <xer@multiphasicapps.net>
   5 // ---------------------------------------------------------------------------
   6 // SquirrelJME is under the Mozilla Public License Version 2.0.
   7 // See license.mkd for licensing and copyright information.
   8 // -------------------------------------------------------------------------*/
   9
  10 /**
  11  * Utilities.
  12  *
  13  * @since 2023/07/26
  14  */
  15
  16 #ifndef SQUIRRELJME_UTIL_H
  17 #define SQUIRRELJME_UTIL_H
  18
  19 #include "sjme/error.h"
  20 #include "sjme/stdTypes.h"
  21
  22 /* Anti-C++. */
  23 #ifdef __cplusplus
  24         #ifndef SJME_CXX_IS_EXTERNED
  25                 #define SJME_CXX_IS_EXTERNED
  26                 #define SJME_CXX_SQUIRRELJME_UTIL_H
  27 extern "C" {
  28         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  29 #endif     /* #ifdef __cplusplus */
  30
  31 /*--------------------------------------------------------------------------*/
  32
  33 /**
  34  * Function for returning the number of entries within a tree.
  35  *
  36  * @param in The tree to get the size of.
  37  * @return The number of items in the tree.
  38  * @since 2023/07/26
  39  */
  40 typedef sjme_jint (*sjme_tree_findCount)(sjme_pointer tree);
  41
  42 /**
  43  * Function for returning the hash of the search item.
  44  *
  45  * @param what What to get the hash of.
  46  * @return The hash of the given search item.
  47  * @since 2023/07/26
  48  */
  49 typedef sjme_jint (*sjme_tree_findHash)(void* what);
  50
  51 /**
  52  * Compares an entry in the tree at the given index with the given hash and
  53  * item.
  54  *
  55  * @param tree The tree to search in.
  56  * @param what What to being searched for in the tree.
  57  * @param hash The hash generated from @c sjme_tree_findHash .
  58  * @param withIndex Compare @c hash and @c what against the given tree.
  59  * @return A negative value if lower, zero if equal, or a positive value if
  60  * greater.
  61  * @since 2023/07/26
  62  */
  63 typedef sjme_jint (*sjme_tree_findCompare)(void* tree, void* what,
  64         sjme_jint hash, sjme_jint withIndex);
  65
  66 /**
  67  * Random number state.
  68  *
  69  * @since 2023/12/02
  70  */
  71 typedef struct sjme_random
  72 {
  73         /** The current seed value. */
  74         sjme_jlong seed;
  75 } sjme_random;
  76
  77 /**
  78  * Tree finding functions, used with @c sjme_tree_find to determine how to
  79  * search through a given tree.
  80  *
  81  * @since 2023/07/26
  82  */
  83 typedef struct sjme_tree_findFunc
  84 {
  85         /** Count function. */
  86         sjme_tree_findCount count;
  87
  88         /** Hash function. */
  89         sjme_tree_findHash hash;
  90
  91         /** Compare function. */
  92         sjme_tree_findCompare compare;
  93 } sjme_tree_findFunc;
  94
  95 /**
  96  * Compares two null values, nulls are placed before non-nulls.
  97  *
  98  * @param a The first value.
  99  * @param b The second value.
 100  * @return The resultant comparison.
 101  * @since 2024/02/14
 102  */
 103 sjme_jint sjme_compare_null(
 104         sjme_attrInNullable sjme_cpointer a,
 105         sjme_attrInNullable sjme_cpointer b);
 106
 107 /**
 108  * Initializes the random number generator.
 109  *
 110  * @param outRandom The random state to initialize.
 111  * @param seedHi The high seed value.
 112  * @param seedLo The low seed value.
 113  * @return Returns @c SJME_JNI_TRUE on success.
 114  * @since 2023/12/02
 115  */
 116 sjme_errorCode sjme_randomInit(
 117         sjme_attrInOutNotNull sjme_random* outRandom,
 118         sjme_attrInValue sjme_jint seedHi,
 119         sjme_attrInValue sjme_jint seedLo);
 120
 121 /**
 122  * Initializes the random number generator.
 123  *
 124  * @param outRandom The random state to initialize.
 125  * @param seed The seed value.
 126  * @return Returns @c SJME_JNI_TRUE on success.
 127  * @since 2023/12/02
 128  */
 129 sjme_errorCode sjme_randomInitL(
 130         sjme_attrInOutNotNull sjme_random* outRandom,
 131         sjme_attrInValue sjme_jlong seed);
 132
 133 /**
 134  * Returns the next random value.
 135  *
 136  * @param random The random state.
 137  * @param outValue The output value.
 138  * @return Returns @c SJME_JNI_TRUE on success.
 139  * @since 2023/12/02
 140  */
 141 sjme_errorCode sjme_randomNextInt(
 142         sjme_attrInOutNotNull sjme_random* random,
 143         sjme_attrOutNotNull sjme_jint* outValue);
 144
 145 /**
 146  * Returns the next random value within the given range.
 147  *
 148  * @param random The random state.
 149  * @param outValue The output value.
 150  * @param maxValue The maximum exclusive value.
 151  * @return Returns @c SJME_JNI_TRUE on success.
 152  * @since 2023/12/02
 153  */
 154 sjme_errorCode sjme_randomNextIntMax(
 155         sjme_attrInOutNotNull sjme_random* random,
 156         sjme_attrOutNotNull sjme_jint* outValue,
 157         sjme_attrInPositiveNonZero sjme_jint maxValue);
 158
 159 /**
 160  * Returns the character at the given index.
 161  *
 162  * @param string The string to get from.
 163  * @param index The index within the string.
 164  * @return The given character or @c -1 if not valid.
 165  * @since 2023/12/16
 166  */
 167 sjme_jint sjme_string_charAt(sjme_lpcstr string, sjme_jint index);
 168
 169 /**
 170  * Compares two strings up to the given number of characters each, nulls are
 171  * in the same order as @c sjme_compare_null() .
 172  *
 173  * @param aString A string.
 174  * @param aLen A length.
 175  * @param bString B string.
 176  * @param bLen B length.
 177  * @return The comparison between the two.
 178  * @since 2024/02/22
 179  */
 180 sjme_jint sjme_string_compareN(sjme_lpcstr aString, sjme_jint aLen,
 181         sjme_lpcstr bString, sjme_jint bLen);
 182
 183 /**
 184  * Decodes the given UTF-8 character.
 185  *
 186  * @param at The character sequence to decode.
 187  * @param stringP Adjustable pointer to the string, when the character is
 188  * decoded then this will increment accordingly.
 189  * @return The decoded character or @c -1 if
 190  * it is not valid.
 191  * @since 2023/07/27
 192  */
 193 sjme_jint sjme_string_decodeChar(sjme_lpcstr at, sjme_lpcstr* stringP);
 194
 195 /**
 196  * Hashes the given string in accordance to @c String::hashCode() .
 197  *
 198  * @param string The string to hash.
 199  * @return The hashcode of the given string.
 200  * @since 2023/07/26
 201  */
 202 sjme_jint sjme_string_hash(sjme_lpcstr string);
 203
 204 /**
 205  * Hashes the given string in accordance to @c String::hashCode() .
 206  *
 207  * @param string The string to hash.
 208  * @param limit The string limit.
 209  * @return The hashcode of the given string.
 210  * @since 2024/02/20
 211  */
 212 sjme_jint sjme_string_hashN(sjme_lpcstr string, sjme_jint limit);
 213
 214 /**
 215  * Returns the length of the string in accordance to @c String::length() .
 216  *
 217  * @param string The string to get the length of.
 218  * @return The string length or @c -1 if it is not valid.
 219  * @since 2023/07/29
 220  */
 221 sjme_jint sjme_string_length(sjme_lpcstr string);
 222
 223 /**
 224  * Returns the length of the string in accordance to @c String::length() .
 225  *
 226  * @param string The string to get the length of.
 227  * @param limit The length limit of the C string.
 228  * @return The string length or @c -1 if it is not valid.
 229  * @since 2024/02/20
 230  */
 231 sjme_jint sjme_string_lengthN(sjme_lpcstr string, sjme_jint limit);
 232
 233 /**
 234  * Swaps an unsigned integer value.
 235  *
 236  * @param in The input value.
 237  * @return The swapped value.
 238  * @since 2024/01/05
 239  */
 240 static sjme_inline sjme_attrArtificial sjme_juint sjme_swap_uint(
 241         sjme_juint in)
 242 {
 243         // 0xAABBCCDD -> 0xBBAADDCC
 244         in = (((in & 0xFF00FF00) >> 8) | ((in & 0x00FF00FF) << 8));
 245
 246         // 0xBBAADDCC -> 0xDDCCBBAA
 247         return (in >> 16) | (in << 16);
 248 }
 249
 250 /**
 251  * Swaps an integer value.
 252  *
 253  * @param in The input value.
 254  * @return The swapped value.
 255  * @since 2024/01/05
 256  */
 257 static sjme_inline sjme_attrArtificial sjme_jint sjme_swap_int(
 258         sjme_jint in)
 259 {
 260         return (sjme_jint)sjme_swap_uint((sjme_juint)in);
 261 }
 262
 263 /**
 264  * Swaps a long value.
 265  *
 266  * @param in The input value.
 267  * @return The swapped value.
 268  * @since 2024/01/05
 269  */
 270 static sjme_inline sjme_attrArtificial sjme_jlong sjme_swap_long(
 271         sjme_jlong in)
 272 {
 273         sjme_juint temp;
 274
 275         /* Swap high and low first. */
 276         temp = in.part.hi;
 277         in.part.hi = (sjme_jint)in.part.lo;
 278         in.part.lo = temp;
 279
 280         /* Then finish swap each side. */
 281         in.part.hi = sjme_swap_int(in.part.hi);
 282         in.part.lo = sjme_swap_uint(in.part.lo);
 283
 284         /* Return the result. */
 285         return in;
 286 }
 287
 288 /**
 289  * Swaps an unsigned short value.
 290  *
 291  * @param in The input value.
 292  * @return The swapped value.
 293  * @since 2024/01/05
 294  */
 295 static sjme_inline sjme_attrArtificial sjme_jchar sjme_swap_ushort(
 296         sjme_jchar in)
 297 {
 298         return ((in >> 8) | (in << 8));
 299 }
 300
 301 /**
 302  * Swaps a short value.
 303  *
 304  * @param in The input value.
 305  * @return The swapped value.
 306  * @since 2024/01/05
 307  */
 308 static sjme_inline sjme_attrArtificial sjme_jshort sjme_swap_short(
 309         sjme_jshort in)
 310 {
 311         return (sjme_jchar)sjme_swap_ushort((sjme_jchar)in);
 312 }
 313
 314 /**
 315  * Performs @c memmove() followed by shifting up by 8 the destination buffer,
 316  * then following a byte swap.
 317  *
 318  * @param dest The destination.
 319  * @param src The source.
 320  * @param n The number of bytes to copy.
 321  * @return Any resultant error, if any.
 322  * @since 2024/07/10
 323  */
 324 sjme_errorCode sjme_swap_shu8_uint_memmove(
 325         sjme_attrInNotNull void* dest,
 326         sjme_attrInNotNull void* src,
 327         sjme_attrInPositiveNonZero sjme_jint n);
 328
 329 /**
 330  * Performs @c memmove() followed by swapping the destination buffer.
 331  *
 332  * @param dest The destination.
 333  * @param src The source.
 334  * @param n The number of bytes to copy.
 335  * @return Any resultant error, if any.
 336  * @since 2024/07/10
 337  */
 338 sjme_errorCode sjme_swap_uint_memmove(
 339         sjme_attrInNotNull void* dest,
 340         sjme_attrInNotNull void* src,
 341         sjme_attrInPositiveNonZero sjme_jint n);
 342
 343 /**
 344  * Locates an item within a tree.
 345  *
 346  * @param tree The tree to search in.
 347  * @param what What is being searched for.
 348  * @param functions Functions used for the tree search logic.
 349  * @return The index where the item was found.
 350  * @since 2023/07/26
 351  */
 352 sjme_jint sjme_tree_find(void* tree, void* what,
 353         const sjme_tree_findFunc* functions);
 354
 355 /**
 356  * Returns the number of bits in the value.
 357  *
 358  * @param v The value to get the number of bits in.
 359  * @return The number of bits in the value.
 360  * @since 2024/08/22
 361  */
 362 sjme_juint sjme_util_intBitCountU(
 363         sjme_attrInValue sjme_juint v);
 364
 365 /**
 366  * Returns the value with the highest bit set.
 367  *
 368  * @param v The value to return the highest bit of.
 369  * @return The highest bit of the value.
 370  * @since 2024/08/22
 371  */
 372 sjme_juint sjme_util_intHighestOneBit(
 373         sjme_attrInValue sjme_juint v);
 374
 375 /**
 376  * Returns the number of leading zeroes in the value.
 377  *
 378  * @param v The value to check.
 379  * @return The resultant number of leading zeroes.
 380  * @since 2024/08/22
 381  */
 382 sjme_juint sjme_util_intLeadingZeroesU(
 383         sjme_attrInValue sjme_juint v);
 384
 385 /**
 386  * Allows for shifting left/right by 32 for certain CPUs.
 387  *
 388  * @param v The value to shift.
 389  * @param sh The shift amount, positive is left shift and negative is right
 390  * shift.
 391  * @return The resultant shifted value.
 392  * @since 2024/08/29
 393  */
 394 sjme_juint sjme_util_intOverShiftU(
 395         sjme_attrInValue sjme_juint v,
 396         sjme_attrInRange(-32, 32) sjme_jint sh);
 397
 398 /**
 399  * Reverses the bits in the given integer value.
 400  *
 401  * @param v The input value.
 402  * @return The value with the reversed bits.
 403  * @since 2024/08/18
 404  */
 405 sjme_jint sjme_util_intReverse(
 406         sjme_attrInValue sjme_jint v);
 407
 408 /**
 409  * Reverses the bits in the given integer value.
 410  *
 411  * @param v The input value.
 412  * @return The value with the reversed bits.
 413  * @since 2024/08/18
 414  */
 415 sjme_juint sjme_util_intReverseU(
 416         sjme_attrInValue sjme_juint v);
 417
 418 /**
 419  * Converts integer value to binary.
 420  *
 421  * @param destBuf The destination buffer.
 422  * @param destLen The destination length.
 423  * @param inVal The value to convert to binary.
 424  * @param bitCount The number of bits to output, if zero then this is all bits.
 425  * @return Any resultant error, if any.
 426  * @since 2024/08/24
 427  */
 428 sjme_errorCode sjme_util_intToBinary(
 429         sjme_attrInNotNullBuf(destLen) sjme_lpstr destBuf,
 430         sjme_attrInPositiveNonZero sjme_jint destLen,
 431         sjme_attrInValue sjme_juint inVal,
 432         sjme_attrInPositiveNonZero sjme_juint bitCount);
 433
 434 /**
 435  * Trims ending whitespace from the end of the string.
 436  *
 437  * @param buf The buffer to trim from.
 438  * @param length The length of the input buffer.
 439  * @return On any resultant error, if any.
 440  * @since 2024/09/06
 441  */
 442 sjme_errorCode sjme_util_lpstrTrimEnd(
 443         sjme_attrInNotNullBuf(length) sjme_lpstr buf,
 444         sjme_attrInPositiveNonZero sjme_jint length);
 445
 446 /*--------------------------------------------------------------------------*/
 447
 448 /* Anti-C++. */
 449 #ifdef __cplusplus
 450         #ifdef SJME_CXX_SQUIRRELJME_UTIL_H
 451 }
 452                 #undef SJME_CXX_SQUIRRELJME_UTIL_H
 453                 #undef SJME_CXX_IS_EXTERNED
 454         #endif /* #ifdef SJME_CXX_SQUIRRELJME_UTIL_H */
 455 #endif     /* #ifdef __cplusplus */
 456
 457 #endif /* SQUIRRELJME_UTIL_H */