contrib/bc/include/bcl.h

   1 /*
   2  * *****************************************************************************
   3  *
   4  * SPDX-License-Identifier: BSD-2-Clause
   5  *
   6  * Copyright (c) 2018-2023 Gavin D. Howard and contributors.
   7  *
   8  * Redistribution and use in source and binary forms, with or without
   9  * modification, are permitted provided that the following conditions are met:
  10  *
  11  * * Redistributions of source code must retain the above copyright notice, this
  12  *   list of conditions and the following disclaimer.
  13  *
  14  * * Redistributions in binary form must reproduce the above copyright notice,
  15  *   this list of conditions and the following disclaimer in the documentation
  16  *   and/or other materials provided with the distribution.
  17  *
  18  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  19  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21  * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  22  * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23  * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24  * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25  * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26  * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27  * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28  * POSSIBILITY OF SUCH DAMAGE.
  29  *
  30  * *****************************************************************************
  31  *
  32  * The public header for the bc library.
  33  *
  34  */
  35
  36 #ifndef BC_BCL_H
  37 #define BC_BCL_H
  38
  39 // TODO: Add a generation index when building with Valgrind to check for
  40 // use-after-free's or double frees.
  41
  42 #include <stdbool.h>
  43 #include <stdlib.h>
  44 #include <limits.h>
  45 #include <stdint.h>
  46
  47 #ifndef NDEBUG
  48 #define BC_DEBUG (1)
  49 #else // NDEBUG
  50 #define BC_DEBUG (0)
  51 #endif // NDEBUG
  52
  53 #ifdef _WIN32
  54 #include <Windows.h>
  55 #include <BaseTsd.h>
  56 #include <stdio.h>
  57 #include <io.h>
  58 #endif // _WIN32
  59
  60 #ifdef _WIN32
  61 #define ssize_t SSIZE_T
  62 #endif // _WIN32
  63
  64 #define BCL_SEED_ULONGS (4)
  65 #define BCL_SEED_SIZE (sizeof(long) * BCL_SEED_ULONGS)
  66
  67 // For some reason, LONG_BIT is not defined in some versions of gcc.
  68 // I define it here to the minimum accepted value in the POSIX standard.
  69 #ifndef LONG_BIT
  70 #define LONG_BIT (32)
  71 #endif // LONG_BIT
  72
  73 #ifndef BC_LONG_BIT
  74 #define BC_LONG_BIT LONG_BIT
  75 #endif // BC_LONG_BIT
  76
  77 #if BC_LONG_BIT > LONG_BIT
  78 #error BC_LONG_BIT cannot be greater than LONG_BIT
  79 #endif // BC_LONG_BIT > LONG_BIT
  80
  81 // For more information about the items here, see the either the
  82 // manuals/bcl.3.md or manuals/bcl.3 manuals.
  83
  84 // BclBigDig is a fixed-size integer type that bcl can convert numbers to.
  85 //
  86 // BclRandInt is the type of fixed-size integer natively returned by the
  87 // pseudo-random number generator.
  88 #if BC_LONG_BIT >= 64
  89
  90 typedef uint64_t BclBigDig;
  91 typedef uint64_t BclRandInt;
  92
  93 #elif BC_LONG_BIT >= 32
  94
  95 typedef uint32_t BclBigDig;
  96 typedef uint32_t BclRandInt;
  97
  98 #else
  99
 100 #error BC_LONG_BIT must be at least 32
 101
 102 #endif // BC_LONG_BIT >= 64
 103
 104 #ifndef BC_ENABLE_LIBRARY
 105 #define BC_ENABLE_LIBRARY (1)
 106 #endif // BC_ENABLE_LIBRARY
 107
 108 #if BC_ENABLE_LIBRARY
 109
 110 typedef enum BclError
 111 {
 112         BCL_ERROR_NONE,
 113
 114         BCL_ERROR_INVALID_NUM,
 115         BCL_ERROR_INVALID_CONTEXT,
 116         BCL_ERROR_SIGNAL,
 117
 118         BCL_ERROR_MATH_NEGATIVE,
 119         BCL_ERROR_MATH_NON_INTEGER,
 120         BCL_ERROR_MATH_OVERFLOW,
 121         BCL_ERROR_MATH_DIVIDE_BY_ZERO,
 122
 123         BCL_ERROR_PARSE_INVALID_STR,
 124
 125         BCL_ERROR_FATAL_ALLOC_ERR,
 126         BCL_ERROR_FATAL_UNKNOWN_ERR,
 127
 128         BCL_ERROR_NELEMS,
 129
 130 } BclError;
 131
 132 typedef struct BclNumber
 133 {
 134         size_t i;
 135
 136 } BclNumber;
 137
 138 struct BclCtxt;
 139
 140 typedef struct BclCtxt* BclContext;
 141
 142 BclError
 143 bcl_start(void);
 144
 145 void
 146 bcl_end(void);
 147
 148 BclError
 149 bcl_init(void);
 150
 151 void
 152 bcl_free(void);
 153
 154 bool
 155 bcl_abortOnFatalError(void);
 156
 157 void
 158 bcl_setAbortOnFatalError(bool abrt);
 159
 160 bool
 161 bcl_leadingZeroes(void);
 162
 163 void
 164 bcl_setLeadingZeroes(bool leadingZeroes);
 165
 166 bool
 167 bcl_digitClamp(void);
 168
 169 void
 170 bcl_setDigitClamp(bool digitClamp);
 171
 172 void
 173 bcl_gc(void);
 174
 175 BclError
 176 bcl_pushContext(BclContext ctxt);
 177
 178 void
 179 bcl_popContext(void);
 180
 181 BclContext
 182 bcl_context(void);
 183
 184 BclContext
 185 bcl_ctxt_create(void);
 186
 187 void
 188 bcl_ctxt_free(BclContext ctxt);
 189
 190 void
 191 bcl_ctxt_freeNums(BclContext ctxt);
 192
 193 size_t
 194 bcl_ctxt_scale(BclContext ctxt);
 195
 196 void
 197 bcl_ctxt_setScale(BclContext ctxt, size_t scale);
 198
 199 size_t
 200 bcl_ctxt_ibase(BclContext ctxt);
 201
 202 void
 203 bcl_ctxt_setIbase(BclContext ctxt, size_t ibase);
 204
 205 size_t
 206 bcl_ctxt_obase(BclContext ctxt);
 207
 208 void
 209 bcl_ctxt_setObase(BclContext ctxt, size_t obase);
 210
 211 BclError
 212 bcl_err(BclNumber n);
 213
 214 BclNumber
 215 bcl_num_create(void);
 216
 217 void
 218 bcl_num_free(BclNumber n);
 219
 220 bool
 221 bcl_num_neg(BclNumber n);
 222
 223 void
 224 bcl_num_setNeg(BclNumber n, bool neg);
 225
 226 size_t
 227 bcl_num_scale(BclNumber n);
 228
 229 BclError
 230 bcl_num_setScale(BclNumber n, size_t scale);
 231
 232 size_t
 233 bcl_num_len(BclNumber n);
 234
 235 BclError
 236 bcl_copy(BclNumber d, BclNumber s);
 237
 238 BclNumber
 239 bcl_dup(BclNumber s);
 240
 241 BclError
 242 bcl_bigdig(BclNumber n, BclBigDig* result);
 243
 244 BclError
 245 bcl_bigdig_keep(BclNumber n, BclBigDig* result);
 246
 247 BclNumber
 248 bcl_bigdig2num(BclBigDig val);
 249
 250 BclNumber
 251 bcl_add(BclNumber a, BclNumber b);
 252
 253 BclNumber
 254 bcl_add_keep(BclNumber a, BclNumber b);
 255
 256 BclNumber
 257 bcl_sub(BclNumber a, BclNumber b);
 258
 259 BclNumber
 260 bcl_sub_keep(BclNumber a, BclNumber b);
 261
 262 BclNumber
 263 bcl_mul(BclNumber a, BclNumber b);
 264
 265 BclNumber
 266 bcl_mul_keep(BclNumber a, BclNumber b);
 267
 268 BclNumber
 269 bcl_div(BclNumber a, BclNumber b);
 270
 271 BclNumber
 272 bcl_div_keep(BclNumber a, BclNumber b);
 273
 274 BclNumber
 275 bcl_mod(BclNumber a, BclNumber b);
 276
 277 BclNumber
 278 bcl_mod_keep(BclNumber a, BclNumber b);
 279
 280 BclNumber
 281 bcl_pow(BclNumber a, BclNumber b);
 282
 283 BclNumber
 284 bcl_pow_keep(BclNumber a, BclNumber b);
 285
 286 BclNumber
 287 bcl_lshift(BclNumber a, BclNumber b);
 288
 289 BclNumber
 290 bcl_lshift_keep(BclNumber a, BclNumber b);
 291
 292 BclNumber
 293 bcl_rshift(BclNumber a, BclNumber b);
 294
 295 BclNumber
 296 bcl_rshift_keep(BclNumber a, BclNumber b);
 297
 298 BclNumber
 299 bcl_sqrt(BclNumber a);
 300
 301 BclNumber
 302 bcl_sqrt_keep(BclNumber a);
 303
 304 BclError
 305 bcl_divmod(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d);
 306
 307 BclError
 308 bcl_divmod_keep(BclNumber a, BclNumber b, BclNumber* c, BclNumber* d);
 309
 310 BclNumber
 311 bcl_modexp(BclNumber a, BclNumber b, BclNumber c);
 312
 313 BclNumber
 314 bcl_modexp_keep(BclNumber a, BclNumber b, BclNumber c);
 315
 316 ssize_t
 317 bcl_cmp(BclNumber a, BclNumber b);
 318
 319 void
 320 bcl_zero(BclNumber n);
 321
 322 void
 323 bcl_one(BclNumber n);
 324
 325 BclNumber
 326 bcl_parse(const char* restrict val);
 327
 328 char*
 329 bcl_string(BclNumber n);
 330
 331 char*
 332 bcl_string_keep(BclNumber n);
 333
 334 BclNumber
 335 bcl_irand(BclNumber a);
 336
 337 BclNumber
 338 bcl_irand_keep(BclNumber a);
 339
 340 BclNumber
 341 bcl_frand(size_t places);
 342
 343 BclNumber
 344 bcl_ifrand(BclNumber a, size_t places);
 345
 346 BclNumber
 347 bcl_ifrand_keep(BclNumber a, size_t places);
 348
 349 BclError
 350 bcl_rand_seedWithNum(BclNumber n);
 351
 352 BclError
 353 bcl_rand_seedWithNum_keep(BclNumber n);
 354
 355 BclError
 356 bcl_rand_seed(unsigned char seed[BCL_SEED_SIZE]);
 357
 358 void
 359 bcl_rand_reseed(void);
 360
 361 BclNumber
 362 bcl_rand_seed2num(void);
 363
 364 BclRandInt
 365 bcl_rand_int(void);
 366
 367 BclRandInt
 368 bcl_rand_bounded(BclRandInt bound);
 369
 370 #endif // BC_ENABLE_LIBRARY
 371
 372 #endif // BC_BCL_H