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/nvm.h"
  20
  21 /* Anti-C++. */
  22 #ifdef __cplusplus
  23         #ifndef SJME_CXX_IS_EXTERNED
  24                 #define SJME_CXX_IS_EXTERNED
  25                 #define SJME_CXX_SQUIRRELJME_UTIL_H
  26 extern "C" {
  27         #endif /* #ifdef SJME_CXX_IS_EXTERNED */
  28 #endif     /* #ifdef __cplusplus */
  29
  30 /*--------------------------------------------------------------------------*/
  31
  32 /**
  33  * Function for returning the number of entries within a tree.
  34  *
  35  * @param in The tree to get the size of.
  36  * @return The number of items in the tree.
  37  * @since 2023/07/26
  38  */
  39 typedef sjme_jint (*sjme_tree_findCount)(sjme_pointer tree);
  40
  41 /**
  42  * Function for returning the hash of the search item.
  43  *
  44  * @param what What to get the hash of.
  45  * @return The hash of the given search item.
  46  * @since 2023/07/26
  47  */
  48 typedef sjme_jint (*sjme_tree_findHash)(void* what);
  49
  50 /**
  51  * Compares an entry in the tree at the given index with the given hash and
  52  * item.
  53  *
  54  * @param tree The tree to search in.
  55  * @param what What to being searched for in the tree.
  56  * @param hash The hash generated from @c sjme_tree_findHash .
  57  * @param withIndex Compare @c hash and @c what against the given tree.
  58  * @return A negative value if lower, zero if equal, or a positive value if
  59  * greater.
  60  * @since 2023/07/26
  61  */
  62 typedef sjme_jint (*sjme_tree_findCompare)(void* tree, void* what,
  63         sjme_jint hash, sjme_jint withIndex);
  64
  65 /**
  66  * Random number state.
  67  *
  68  * @since 2023/12/02
  69  */
  70 typedef struct sjme_random
  71 {
  72         /** The current seed value. */
  73         sjme_jlong seed;
  74 } sjme_random;
  75
  76 /**
  77  * Tree finding functions, used with @c sjme_tree_find to determine how to
  78  * search through a given tree.
  79  *
  80  * @since 2023/07/26
  81  */
  82 typedef struct sjme_tree_findFunc
  83 {
  84         /** Count function. */
  85         sjme_tree_findCount count;
  86
  87         /** Hash function. */
  88         sjme_tree_findHash hash;
  89
  90         /** Compare function. */
  91         sjme_tree_findCompare compare;
  92 } sjme_tree_findFunc;
  93
  94 /**
  95  * Compares two null values, nulls are placed before non-nulls.
  96  *
  97  * @param a The first value.
  98  * @param b The second value.
  99  * @return The resultant comparison.
 100  * @since 2024/02/14
 101  */
 102 sjme_jint sjme_compare_null(
 103         sjme_attrInNullable sjme_cpointer a,
 104         sjme_attrInNullable sjme_cpointer b);
 105
 106 /**
 107  * Initializes the random number generator.
 108  *
 109  * @param outRandom The random state to initialize.
 110  * @param seedHi The high seed value.
 111  * @param seedLo The low seed value.
 112  * @return Returns @c SJME_JNI_TRUE on success.
 113  * @since 2023/12/02
 114  */
 115 sjme_errorCode sjme_randomInit(
 116         sjme_attrInOutNotNull sjme_random* outRandom,
 117         sjme_attrInValue sjme_jint seedHi,
 118         sjme_attrInValue sjme_jint seedLo);
 119
 120 /**
 121  * Initializes the random number generator.
 122  *
 123  * @param outRandom The random state to initialize.
 124  * @param seed The seed value.
 125  * @return Returns @c SJME_JNI_TRUE on success.
 126  * @since 2023/12/02
 127  */
 128 sjme_errorCode sjme_randomInitL(
 129         sjme_attrInOutNotNull sjme_random* outRandom,
 130         sjme_attrInValue sjme_jlong seed);
 131
 132 /**
 133  * Returns the next random value.
 134  *
 135  * @param random The random state.
 136  * @param outValue The output value.
 137  * @return Returns @c SJME_JNI_TRUE on success.
 138  * @since 2023/12/02
 139  */
 140 sjme_errorCode sjme_randomNextInt(
 141         sjme_attrInOutNotNull sjme_random* random,
 142         sjme_attrOutNotNull sjme_jint* outValue);
 143
 144 /**
 145  * Returns the next random value within the given range.
 146  *
 147  * @param random The random state.
 148  * @param outValue The output value.
 149  * @param maxValue The maximum exclusive value.
 150  * @return Returns @c SJME_JNI_TRUE on success.
 151  * @since 2023/12/02
 152  */
 153 sjme_errorCode sjme_randomNextIntMax(
 154         sjme_attrInOutNotNull sjme_random* random,
 155         sjme_attrOutNotNull sjme_jint* outValue,
 156         sjme_attrInPositiveNonZero sjme_jint maxValue);
 157
 158 /**
 159  * Returns the character at the given index.
 160  *
 161  * @param string The string to get from.
 162  * @param index The index within the string.
 163  * @return The given character or @c -1 if not valid.
 164  * @since 2023/12/16
 165  */
 166 sjme_jint sjme_string_charAt(sjme_lpcstr string, sjme_jint index);
 167
 168 /**
 169  * Compares two strings up to the given number of characters each, nulls are
 170  * in the same order as @c sjme_compare_null() .
 171  *
 172  * @param aString A string.
 173  * @param aLen A length.
 174  * @param bString B string.
 175  * @param bLen B length.
 176  * @return The comparison between the two.
 177  * @since 2024/02/22
 178  */
 179 sjme_jint sjme_string_compareN(sjme_lpcstr aString, sjme_jint aLen,
 180         sjme_lpcstr bString, sjme_jint bLen);
 181
 182 /**
 183  * Decodes the given UTF-8 character.
 184  *
 185  * @param at The character sequence to decode.
 186  * @param stringP Adjustable pointer to the string, when the character is
 187  * decoded then this will increment accordingly.
 188  * @return The decoded character or @c -1 if
 189  * it is not valid.
 190  * @since 2023/07/27
 191  */
 192 sjme_jint sjme_string_decodeChar(sjme_lpcstr at, sjme_lpcstr* stringP);
 193
 194 /**
 195  * Hashes the given string in accordance to @c String::hashCode() .
 196  *
 197  * @param string The string to hash.
 198  * @return The hashcode of the given string.
 199  * @since 2023/07/26
 200  */
 201 sjme_jint sjme_string_hash(sjme_lpcstr string);
 202
 203 /**
 204  * Hashes the given string in accordance to @c String::hashCode() .
 205  *
 206  * @param string The string to hash.
 207  * @param limit The string limit.
 208  * @return The hashcode of the given string.
 209  * @since 2024/02/20
 210  */
 211 sjme_jint sjme_string_hashN(sjme_lpcstr string, sjme_jint limit);
 212
 213 /**
 214  * Returns the length of the string in accordance to @c String::length() .
 215  *
 216  * @param string The string to get the length of.
 217  * @return The string length or @c -1 if it is not valid.
 218  * @since 2023/07/29
 219  */
 220 sjme_jint sjme_string_length(sjme_lpcstr string);
 221
 222 /**
 223  * Returns the length of the string in accordance to @c String::length() .
 224  *
 225  * @param string The string to get the length of.
 226  * @param limit The length limit of the C string.
 227  * @return The string length or @c -1 if it is not valid.
 228  * @since 2024/02/20
 229  */
 230 sjme_jint sjme_string_lengthN(sjme_lpcstr string, sjme_jint limit);
 231
 232 /**
 233  * Swaps an unsigned integer value.
 234  *
 235  * @param in The input value.
 236  * @return The swapped value.
 237  * @since 2024/01/05
 238  */
 239 static sjme_inline sjme_attrArtificial sjme_juint sjme_swap_uint(
 240         sjme_juint in)
 241 {
 242         // 0xAABBCCDD -> 0xBBAADDCC
 243         in = (((in & 0xFF00FF00) >> 8) | ((in & 0x00FF00FF) << 8));
 244
 245         // 0xBBAADDCC -> 0xDDCCBBAA
 246         return (in >> 16) | (in << 16);
 247 }
 248
 249 /**
 250  * Swaps an integer value.
 251  *
 252  * @param in The input value.
 253  * @return The swapped value.
 254  * @since 2024/01/05
 255  */
 256 static sjme_inline sjme_attrArtificial sjme_jint sjme_swap_int(
 257         sjme_jint in)
 258 {
 259         return (sjme_jint)sjme_swap_uint((sjme_juint)in);
 260 }
 261
 262 /**
 263  * Swaps a long value.
 264  *
 265  * @param in The input value.
 266  * @return The swapped value.
 267  * @since 2024/01/05
 268  */
 269 static sjme_inline sjme_attrArtificial sjme_jlong sjme_swap_long(
 270         sjme_jlong in)
 271 {
 272         sjme_juint temp;
 273
 274         /* Swap high and low first. */
 275         temp = in.part.hi;
 276         in.part.hi = (sjme_jint)in.part.lo;
 277         in.part.lo = temp;
 278
 279         /* Then finish swap each side. */
 280         in.part.hi = sjme_swap_int(in.part.hi);
 281         in.part.lo = sjme_swap_uint(in.part.lo);
 282
 283         /* Return the result. */
 284         return in;
 285 }
 286
 287 /**
 288  * Swaps an unsigned short value.
 289  *
 290  * @param in The input value.
 291  * @return The swapped value.
 292  * @since 2024/01/05
 293  */
 294 static sjme_inline sjme_attrArtificial sjme_jchar sjme_swap_ushort(
 295         sjme_jchar in)
 296 {
 297         return ((in >> 8) | (in << 8));
 298 }
 299
 300 /**
 301  * Swaps a short value.
 302  *
 303  * @param in The input value.
 304  * @return The swapped value.
 305  * @since 2024/01/05
 306  */
 307 static sjme_inline sjme_attrArtificial sjme_jshort sjme_swap_short(
 308         sjme_jshort in)
 309 {
 310         return (sjme_jchar)sjme_swap_ushort((sjme_jchar)in);
 311 }
 312
 313 /**
 314  * Performs @c memmove() followed by shifting up by 8 the destination buffer,
 315  * then following a byte swap.
 316  *
 317  * @param dest The destination.
 318  * @param src The source.
 319  * @param n The number of bytes to copy.
 320  * @return Any resultant error, if any.
 321  * @since 2024/07/10
 322  */
 323 sjme_errorCode sjme_swap_shu8_uint_memmove(
 324         sjme_attrInNotNull void* dest,
 325         sjme_attrInNotNull void* src,
 326         sjme_attrInPositiveNonZero sjme_jint n);
 327
 328 /**
 329  * Performs @c memmove() followed by swapping the destination buffer.
 330  *
 331  * @param dest The destination.
 332  * @param src The source.
 333  * @param n The number of bytes to copy.
 334  * @return Any resultant error, if any.
 335  * @since 2024/07/10
 336  */
 337 sjme_errorCode sjme_swap_uint_memmove(
 338         sjme_attrInNotNull void* dest,
 339         sjme_attrInNotNull void* src,
 340         sjme_attrInPositiveNonZero sjme_jint n);
 341
 342 /**
 343  * Locates an item within a tree.
 344  *
 345  * @param tree The tree to search in.
 346  * @param what What is being searched for.
 347  * @param functions Functions used for the tree search logic.
 348  * @return The index where the item was found.
 349  * @since 2023/07/26
 350  */
 351 sjme_jint sjme_tree_find(void* tree, void* what,
 352         const sjme_tree_findFunc* functions);
 353
 354 /*--------------------------------------------------------------------------*/
 355
 356 /* Anti-C++. */
 357 #ifdef __cplusplus
 358         #ifdef SJME_CXX_SQUIRRELJME_UTIL_H
 359 }
 360                 #undef SJME_CXX_SQUIRRELJME_UTIL_H
 361                 #undef SJME_CXX_IS_EXTERNED
 362         #endif /* #ifdef SJME_CXX_SQUIRRELJME_UTIL_H */
 363 #endif     /* #ifdef __cplusplus */
 364
 365 #endif /* SQUIRRELJME_UTIL_H */