contrib/bc/manuals/bcl.3.md

   1 <!---
   2
   3 SPDX-License-Identifier: BSD-2-Clause
   4
   5 Copyright (c) 2018-2020 Gavin D. Howard and contributors.
   6
   7 Redistribution and use in source and binary forms, with or without
   8 modification, are permitted provided that the following conditions are met:
   9
  10 * Redistributions of source code must retain the above copyright notice, this
  11   list of conditions and the following disclaimer.
  12
  13 * Redistributions in binary form must reproduce the above copyright notice,
  14   this list of conditions and the following disclaimer in the documentation
  15   and/or other materials provided with the distribution.
  16
  17 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  18 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
  21 LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  22 CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  23 SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  24 INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  25 CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  26 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  27 POSSIBILITY OF SUCH DAMAGE.
  28
  29 -->
  30
  31 # NAME
  32
  33 bcl - library of arbitrary precision decimal arithmetic
  34
  35 # SYNOPSIS
  36
  37 ## Use
  38
  39 *#include <bcl.h>*
  40
  41 Link with *-lbcl*.
  42
  43 ## Signals
  44
  45 This procedure will allow clients to use signals to interrupt computations
  46 running in bcl(3).
  47
  48 **void bcl_handleSignal(***void***);**
  49
  50 **bool bcl_running(***void***);**
  51
  52 ## Setup
  53
  54 These items allow clients to set up bcl(3).
  55
  56 **BclError bcl_init(***void***);**
  57
  58 **void bcl_free(***void***);**
  59
  60 **bool bcl_abortOnFatalError(***void***);**
  61
  62 **void bcl_setAbortOnFatalError(bool** *abrt***);**
  63
  64 **void bcl_gc(***void***);**
  65
  66 ## Contexts
  67
  68 These items will allow clients to handle contexts, which are isolated from each
  69 other. This allows more than one client to use bcl(3) in the same program.
  70
  71 **struct BclCtxt;**
  72
  73 **typedef struct BclCtxt\* BclContext;**
  74
  75 **BclContext bcl_ctxt_create(***void***);**
  76
  77 **void bcl_ctxt_free(BclContext** *ctxt***);**
  78
  79 **BclError bcl_pushContext(BclContext** *ctxt***);**
  80
  81 **void bcl_popContext(***void***);**
  82
  83 **BclContext bcl_context(***void***);**
  84
  85 **void bcl_ctxt_freeNums(BclContext** *ctxt***);**
  86
  87 **size_t bcl_ctxt_scale(BclContext** *ctxt***);**
  88
  89 **void bcl_ctxt_setScale(BclContext** *ctxt***, size_t** *scale***);**
  90
  91 **size_t bcl_ctxt_ibase(BclContext** *ctxt***);**
  92
  93 **void bcl_ctxt_setIbase(BclContext** *ctxt***, size_t** *ibase***);**
  94
  95 **size_t bcl_ctxt_obase(BclContext** *ctxt***);**
  96
  97 **void bcl_ctxt_setObase(BclContext** *ctxt***, size_t** *obase***);**
  98
  99 ## Errors
 100
 101 These items allow clients to handle errors.
 102
 103 **typedef enum BclError BclError;**
 104
 105 **BclError bcl_err(BclNumber** *n***);**
 106
 107 ## Numbers
 108
 109 These items allow clients to manipulate and query the arbitrary-precision
 110 numbers managed by bcl(3).
 111
 112 **typedef struct { size_t i; } BclNumber;**
 113
 114 **BclNumber bcl_num_create(***void***);**
 115
 116 **void bcl_num_free(BclNumber** *n***);**
 117
 118 **bool bcl_num_neg(BclNumber** *n***);**
 119
 120 **void bcl_num_setNeg(BclNumber** *n***, bool** *neg***);**
 121
 122 **size_t bcl_num_scale(BclNumber** *n***);**
 123
 124 **BclError bcl_num_setScale(BclNumber** *n***, size_t** *scale***);**
 125
 126 **size_t bcl_num_len(BclNumber** *n***);**
 127
 128 ## Conversion
 129
 130 These items allow clients to convert numbers into and from strings and integers.
 131
 132 **BclNumber bcl_parse(const char \*restrict** *val***);**
 133
 134 **char\* bcl_string(BclNumber** *n***);**
 135
 136 **BclError bcl_bigdig(BclNumber** *n***, BclBigDig \****result***);**
 137
 138 **BclNumber bcl_bigdig2num(BclBigDig** *val***);**
 139
 140 ## Math
 141
 142 These items allow clients to run math on numbers.
 143
 144 **BclNumber bcl_add(BclNumber** *a***, BclNumber** *b***);**
 145
 146 **BclNumber bcl_sub(BclNumber** *a***, BclNumber** *b***);**
 147
 148 **BclNumber bcl_mul(BclNumber** *a***, BclNumber** *b***);**
 149
 150 **BclNumber bcl_div(BclNumber** *a***, BclNumber** *b***);**
 151
 152 **BclNumber bcl_mod(BclNumber** *a***, BclNumber** *b***);**
 153
 154 **BclNumber bcl_pow(BclNumber** *a***, BclNumber** *b***);**
 155
 156 **BclNumber bcl_lshift(BclNumber** *a***, BclNumber** *b***);**
 157
 158 **BclNumber bcl_rshift(BclNumber** *a***, BclNumber** *b***);**
 159
 160 **BclNumber bcl_sqrt(BclNumber** *a***);**
 161
 162 **BclError bcl_divmod(BclNumber** *a***, BclNumber** *b***, BclNumber \****c***, BclNumber \****d***);**
 163
 164 **BclNumber bcl_modexp(BclNumber** *a***, BclNumber** *b***, BclNumber** *c***);**
 165
 166 ## Miscellaneous
 167
 168 These items are miscellaneous.
 169
 170 **void bcl_zero(BclNumber** *n***);**
 171
 172 **void bcl_one(BclNumber** *n***);**
 173
 174 **ssize_t bcl_cmp(BclNumber** *a***, BclNumber** *b***);**
 175
 176 **BclError bcl_copy(BclNumber** *d***, BclNumber** *s***);**
 177
 178 **BclNumber bcl_dup(BclNumber** *s***);**
 179
 180 ## Pseudo-Random Number Generator
 181
 182 These items allow clients to manipulate the seeded pseudo-random number
 183 generator in bcl(3).
 184
 185 **#define BCL_SEED_ULONGS**
 186
 187 **#define BCL_SEED_SIZE**
 188
 189 **typedef unsigned long BclBigDig;**
 190
 191 **typedef unsigned long BclRandInt;**
 192
 193 **BclNumber bcl_irand(BclNumber** *a***);**
 194
 195 **BclNumber bcl_frand(size_t** *places***);**
 196
 197 **BclNumber bcl_ifrand(BclNumber** *a***, size_t** *places***);**
 198
 199 **BclError bcl_rand_seedWithNum(BclNumber** *n***);**
 200
 201 **BclError bcl_rand_seed(unsigned char** *seed***[***BC_SEED_SIZE***]);**
 202
 203 **void bcl_rand_reseed(***void***);**
 204
 205 **BclNumber bcl_rand_seed2num(***void***);**
 206
 207 **BclRandInt bcl_rand_int(***void***);**
 208
 209 **BclRandInt bcl_rand_bounded(BclRandInt** *bound***);**
 210
 211 # DESCRIPTION
 212
 213 bcl(3) is a library that implements arbitrary-precision decimal math, as
 214 [standardized by POSIX][1] in bc(1).
 215
 216 bcl(3) is async-signal-safe if **bcl_handleSignal(***void***)** is used
 217 properly. (See the **SIGNAL HANDLING** section.)
 218
 219 All of the items in its interface are described below. See the documentation for
 220 each function for what each function can return.
 221
 222 ## Signals
 223
 224 **void bcl_handleSignal(***void***)**
 225
 226 :   An async-signal-safe function that can be called from a signal handler. If
 227     called from a signal handler on the same thread as any executing bcl(3)
 228     functions, it will interrupt the functions and force them to return early.
 229     It is undefined behavior if this function is called from a thread that is
 230     *not* executing any bcl(3) functions while any bcl(3) functions are
 231     executing.
 232
 233     If execution *is* interrupted, **bcl_handleSignal(***void***)** does *not*
 234     return to its caller.
 235
 236     See the **SIGNAL HANDLING** section.
 237
 238 **bool bcl_running(***void***)**
 239
 240 :   An async-signal-safe function that can be called from a signal handler. It
 241     will return **true** if any bcl(3) procedures are running, which means it is
 242     safe to call **bcl_handleSignal(***void***)**. Otherwise, it returns
 243     **false**.
 244
 245     See the **SIGNAL HANDLING** section.
 246
 247 ## Setup
 248
 249 **BclError bcl_init(***void***)**
 250
 251 :   Initializes this library. This function can be called multiple times, but
 252     each call must be matched by a call to **bcl_free(***void***)**. This is to
 253     make it possible for multiple libraries and applications to initialize
 254     bcl(3) without problem.
 255
 256     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 257     function can return:
 258
 259     * **BCL_ERROR_FATAL_ALLOC_ERR**
 260
 261     This function must be the first one clients call. Calling any other
 262     function without calling this one first is undefined behavior.
 263
 264 **void bcl_free(***void***)**
 265
 266 :   Decrements bcl(3)'s reference count and frees the data associated with it if
 267     the reference count is **0**.
 268
 269     This function must be the last one clients call. Calling this function
 270     before calling any other function is undefined behavior.
 271
 272 **bool bcl_abortOnFatalError(***void***)**
 273
 274 :   Queries and returns the current state of calling **abort()** on fatal
 275     errors. If **true** is returned, bcl(3) will cause a **SIGABRT** if a fatal
 276     error occurs.
 277
 278     If activated, clients do not need to check for fatal errors.
 279
 280 **void bcl_setAbortOnFatalError(bool** *abrt***)**
 281
 282 :   Sets the state of calling **abort()** on fatal errors. If *abrt* is
 283     **false**, bcl(3) will not cause a **SIGABRT** on fatal errors after the
 284     call. If *abrt* is **true**, bcl(3) will cause a **SIGABRT** on fatal errors
 285     after the call.
 286
 287     If activated, clients do not need to check for fatal errors.
 288
 289 **void bcl_gc(***void***)**
 290
 291 :   Garbage collects cached instances of arbitrary-precision numbers. This only
 292     frees the memory of numbers that are *not* in use, so it is safe to call at
 293     any time.
 294
 295 ## Contexts
 296
 297 All procedures that take a **BclContext** parameter a require a valid context as
 298 an argument.
 299
 300 **struct BclCtxt**
 301
 302 :   A forward declaration for a hidden **struct** type. Clients cannot access
 303     the internals of the **struct** type directly. All interactions with the
 304     type are done through pointers. See **BclContext** below.
 305
 306 **BclContext**
 307
 308 :   A typedef to a pointer of **struct BclCtxt**. This is the only handle
 309     clients can get to **struct BclCtxt**.
 310
 311     A **BclContext** contains the values **scale**, **ibase**, and **obase**, as
 312     well as a list of numbers.
 313
 314     **scale** is a value used to control how many decimal places calculations
 315     should use. A value of **0** means that calculations are done on integers
 316     only, where applicable, and a value of 20, for example, means that all
 317     applicable calculations return results with 20 decimal places. The default
 318     is **0**.
 319
 320     **ibase** is a value used to control the input base. The minimum **ibase**
 321     is **2**, and the maximum is **36**. If **ibase** is **2**, numbers are
 322     parsed as though they are in binary, and any digits larger than **1** are
 323     clamped. Likewise, a value of **10** means that numbers are parsed as though
 324     they are decimal, and any larger digits are clamped. The default is **10**.
 325
 326     **obase** is a value used to control the output base. The minimum **obase**
 327     is **0** and the maximum is **BC_BASE_MAX** (see the **LIMITS** section).
 328
 329     Numbers created in one context are not valid in another context. It is
 330     undefined behavior to use a number created in a different context. Contexts
 331     are meant to isolate the numbers used by different clients in the same
 332     application.
 333
 334 **BclContext bcl_ctxt_create(***void***)**
 335
 336 :   Creates a context and returns it. Returns **NULL** if there was an error.
 337
 338 **void bcl_ctxt_free(BclContext** *ctxt***)**
 339
 340 :   Frees *ctxt*, after which it is no longer valid. It is undefined behavior to
 341     attempt to use an invalid context.
 342
 343 **BclError bcl_pushContext(BclContext** *ctxt***)**
 344
 345 :   Pushes *ctxt* onto bcl(3)'s stack of contexts. *ctxt* must have been created
 346     with **bcl_ctxt_create(***void***)**.
 347
 348     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 349     function can return:
 350
 351     * **BCL_ERROR_FATAL_ALLOC_ERR**
 352
 353     There *must* be a valid context to do any arithmetic.
 354
 355 **void bcl_popContext(***void***)**
 356
 357 :   Pops the current context off of the stack, if one exists.
 358
 359 **BclContext bcl_context(***void***)**
 360
 361 :   Returns the current context, or **NULL** if no context exists.
 362
 363 **void bcl_ctxt_freeNums(BclContext** *ctxt***)**
 364
 365 :   Frees all numbers in use that are associated with *ctxt*. It is undefined
 366     behavior to attempt to use a number associated with *ctxt* after calling
 367     this procedure unless such numbers have been created with
 368     **bcl_num_create(***void***)** after calling this procedure.
 369
 370 **size_t bcl_ctxt_scale(BclContext** *ctxt***)**
 371
 372 :   Returns the **scale** for given context.
 373
 374 **void bcl_ctxt_setScale(BclContext** *ctxt***, size_t** *scale***)**
 375
 376 :   Sets the **scale** for the given context to the argument *scale*.
 377
 378 **size_t bcl_ctxt_ibase(BclContext** *ctxt***)**
 379
 380 :   Returns the **ibase** for the given context.
 381
 382 **void bcl_ctxt_setIbase(BclContext** *ctxt***, size_t** *ibase***)**
 383
 384 :   Sets the **ibase** for the given context to the argument *ibase*. If the
 385     argument *ibase* is invalid, it clamped, so an *ibase* of **0** or **1** is
 386     clamped to **2**, and any values above **36** are clamped to **36**.
 387
 388 **size_t bcl_ctxt_obase(BclContext** *ctxt***)**
 389
 390 :   Returns the **obase** for the given context.
 391
 392 **void bcl_ctxt_setObase(BclContext** *ctxt***, size_t** *obase***)**
 393
 394 :   Sets the **obase** for the given context to the argument *obase*.
 395
 396 ## Errors
 397
 398 **BclError**
 399
 400 :   An **enum** of possible error codes. See the **ERRORS** section for a
 401     complete listing the codes.
 402
 403 **BclError bcl_err(BclNumber** *n***)**
 404
 405 :   Checks for errors in a **BclNumber**. All functions that can return a
 406     **BclNumber** can encode an error in the number, and this function will
 407     return the error, if any. If there was no error, it will return
 408     **BCL_ERROR_NONE**.
 409
 410     There must be a valid current context.
 411
 412 ## Numbers
 413
 414 All procedures in this section require a valid current context.
 415
 416 **BclNumber**
 417
 418 :   A handle to an arbitrary-precision number. The actual number type is not
 419     exposed; the **BclNumber** handle is the only way clients can refer to
 420     instances of arbitrary-precision numbers.
 421
 422 **BclNumber bcl_num_create(***void***)**
 423
 424 :   Creates and returns a **BclNumber**.
 425
 426     bcl(3) will encode an error in the return value, if there was one. The error
 427     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 428
 429         * **BCL_ERROR_INVALID_CONTEXT**
 430     * **BCL_ERROR_FATAL_ALLOC_ERR**
 431
 432 **void bcl_num_free(BclNumber** *n***)**
 433
 434 :   Frees *n*. It is undefined behavior to use *n* after calling this function.
 435
 436 **bool bcl_num_neg(BclNumber** *n***)**
 437
 438 :   Returns **true** if *n* is negative, **false** otherwise.
 439
 440 **void bcl_num_setNeg(BclNumber** *n***, bool** *neg***)**
 441
 442 :   Sets *n*'s sign to *neg*, where **true** is negative, and **false** is
 443     positive.
 444
 445 **size_t bcl_num_scale(BclNumber** *n***)**
 446
 447 :   Returns the *scale* of *n*.
 448
 449     The *scale* of a number is the number of decimal places it has after the
 450     radix (decimal point).
 451
 452 **BclError bcl_num_setScale(BclNumber** *n***, size_t** *scale***)**
 453
 454 :   Sets the *scale* of *n* to the argument *scale*. If the argument *scale* is
 455     greater than the *scale* of *n*, *n* is extended. If the argument *scale* is
 456     less than the *scale* of *n*, *n* is truncated.
 457
 458     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 459     function can return:
 460
 461     * **BCL_ERROR_INVALID_NUM**
 462     * **BCL_ERROR_INVALID_CONTEXT**
 463     * **BCL_ERROR_FATAL_ALLOC_ERR**
 464
 465 **size_t bcl_num_len(BclNumber** *n***)**
 466
 467 :   Returns the number of *significant decimal digits* in *n*.
 468
 469 ## Conversion
 470
 471 All procedures in this section require a valid current context.
 472
 473 All procedures in this section consume the given **BclNumber** arguments that
 474 are not given to pointer arguments. See the **Consumption and Propagation**
 475 subsection below.
 476
 477 **BclNumber bcl_parse(const char \*restrict** *val***)**
 478
 479 :   Parses a number string according to the current context's **ibase** and
 480     returns the resulting number.
 481
 482     *val* must be non-**NULL** and a valid string. See
 483     **BCL_ERROR_PARSE_INVALID_STR** in the **ERRORS** section for more
 484     information.
 485
 486     bcl(3) will encode an error in the return value, if there was one. The error
 487     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 488
 489     * **BCL_ERROR_INVALID_NUM**
 490         * **BCL_ERROR_INVALID_CONTEXT**
 491     * **BCL_ERROR_PARSE_INVALID_STR**
 492     * **BCL_ERROR_FATAL_ALLOC_ERR**
 493
 494 **char\* bcl_string(BclNumber** *n***)**
 495
 496 :   Returns a string representation of *n* according the the current context's
 497     **ibase**. The string is dynamically allocated and must be freed by the
 498     caller.
 499
 500     *n* is consumed; it cannot be used after the call. See the
 501     **Consumption and Propagation** subsection below.
 502
 503 **BclError bcl_bigdig(BclNumber** *n***, BclBigDig \****result***)**
 504
 505 :   Converts *n* into a **BclBigDig** and returns the result in the space
 506     pointed to by *result*.
 507
 508     *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section.
 509
 510     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 511     function can return:
 512
 513     * **BCL_ERROR_INVALID_NUM**
 514     * **BCL_ERROR_INVALID_CONTEXT**
 515     * **BCL_ERROR_MATH_OVERFLOW**
 516
 517     *n* is consumed; it cannot be used after the call. See the
 518     **Consumption and Propagation** subsection below.
 519
 520 **BclNumber bcl_bigdig2num(BclBigDig** *val***)**
 521
 522 :   Creates a **BclNumber** from *val*.
 523
 524     bcl(3) will encode an error in the return value, if there was one. The error
 525     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 526
 527         * **BCL_ERROR_INVALID_CONTEXT**
 528     * **BCL_ERROR_FATAL_ALLOC_ERR**
 529
 530 ## Math
 531
 532 All procedures in this section require a valid current context.
 533
 534 All procedures in this section can return the following errors:
 535
 536 * **BCL_ERROR_INVALID_NUM**
 537 * **BCL_ERROR_INVALID_CONTEXT**
 538 * **BCL_ERROR_FATAL_ALLOC_ERR**
 539
 540 **BclNumber bcl_add(BclNumber** *a***, BclNumber** *b***)**
 541
 542 :   Adds *a* and *b* and returns the result. The *scale* of the result is the
 543     max of the *scale*s of *a* and *b*.
 544
 545     *a* and *b* are consumed; they cannot be used after the call. See the
 546     **Consumption and Propagation** subsection below.
 547
 548     *a* and *b* can be the same number.
 549
 550     bcl(3) will encode an error in the return value, if there was one. The error
 551     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 552
 553     * **BCL_ERROR_INVALID_NUM**
 554         * **BCL_ERROR_INVALID_CONTEXT**
 555     * **BCL_ERROR_FATAL_ALLOC_ERR**
 556
 557 **BclNumber bcl_sub(BclNumber** *a***, BclNumber** *b***)**
 558
 559 :   Subtracts *b* from *a* and returns the result. The *scale* of the result is
 560     the max of the *scale*s of *a* and *b*.
 561
 562     *a* and *b* are consumed; they cannot be used after the call. See the
 563     **Consumption and Propagation** subsection below.
 564
 565     *a* and *b* can be the same number.
 566
 567     bcl(3) will encode an error in the return value, if there was one. The error
 568     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 569
 570     * **BCL_ERROR_INVALID_NUM**
 571         * **BCL_ERROR_INVALID_CONTEXT**
 572     * **BCL_ERROR_FATAL_ALLOC_ERR**
 573
 574 **BclNumber bcl_mul(BclNumber** *a***, BclNumber** *b***)**
 575
 576 :   Multiplies *a* and *b* and returns the result. If *ascale* is the *scale* of
 577     *a* and *bscale* is the *scale* of *b*, the *scale* of the result is equal
 578     to **min(ascale+bscale,max(scale,ascale,bscale))**, where **min()** and
 579     **max()** return the obvious values.
 580
 581     *a* and *b* are consumed; they cannot be used after the call. See the
 582     **Consumption and Propagation** subsection below.
 583
 584     *a* and *b* can be the same number.
 585
 586     bcl(3) will encode an error in the return value, if there was one. The error
 587     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 588
 589     * **BCL_ERROR_INVALID_NUM**
 590         * **BCL_ERROR_INVALID_CONTEXT**
 591     * **BCL_ERROR_FATAL_ALLOC_ERR**
 592
 593 **BclNumber bcl_div(BclNumber** *a***, BclNumber** *b***)**
 594
 595 :   Divides *a* by *b* and returns the result. The *scale* of the result is the
 596     *scale* of the current context.
 597
 598     *b* cannot be **0**.
 599
 600     *a* and *b* are consumed; they cannot be used after the call. See the
 601     **Consumption and Propagation** subsection below.
 602
 603     *a* and *b* can be the same number.
 604
 605     bcl(3) will encode an error in the return value, if there was one. The error
 606     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 607
 608     * **BCL_ERROR_INVALID_NUM**
 609         * **BCL_ERROR_INVALID_CONTEXT**
 610         * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 611     * **BCL_ERROR_FATAL_ALLOC_ERR**
 612
 613 **BclNumber bcl_mod(BclNumber** *a***, BclNumber** *b***)**
 614
 615 :   Divides *a* by *b* to the *scale* of the current context, computes the
 616     modulus **a-(a/b)\*b**, and returns the modulus.
 617
 618     *b* cannot be **0**.
 619
 620     *a* and *b* are consumed; they cannot be used after the call. See the
 621     **Consumption and Propagation** subsection below.
 622
 623     *a* and *b* can be the same number.
 624
 625     bcl(3) will encode an error in the return value, if there was one. The error
 626     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 627
 628     * **BCL_ERROR_INVALID_NUM**
 629         * **BCL_ERROR_INVALID_CONTEXT**
 630         * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 631     * **BCL_ERROR_FATAL_ALLOC_ERR**
 632
 633 **BclNumber bcl_pow(BclNumber** *a***, BclNumber** *b***)**
 634
 635 :   Calculates *a* to the power of *b* to the *scale* of the current context.
 636     *b* must be an integer, but can be negative. If it is negative, *a* must
 637     be non-zero.
 638
 639     *b* must be an integer. If *b* is negative, *a* must not be **0**.
 640
 641     *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section.
 642
 643     *a* and *b* are consumed; they cannot be used after the call. See the
 644     **Consumption and Propagation** subsection below.
 645
 646     *a* and *b* can be the same number.
 647
 648     bcl(3) will encode an error in the return value, if there was one. The error
 649     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 650
 651     * **BCL_ERROR_INVALID_NUM**
 652         * **BCL_ERROR_INVALID_CONTEXT**
 653         * **BCL_ERROR_MATH_NON_INTEGER**
 654         * **BCL_ERROR_MATH_OVERFLOW**
 655         * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 656     * **BCL_ERROR_FATAL_ALLOC_ERR**
 657
 658 **BclNumber bcl_lshift(BclNumber** *a***, BclNumber** *b***)**
 659
 660 :   Shifts *a* left (moves the radix right) by *b* places and returns the
 661     result. This is done in decimal. *b* must be an integer.
 662
 663     *b* must be an integer.
 664
 665     *a* and *b* are consumed; they cannot be used after the call. See the
 666     **Consumption and Propagation** subsection below.
 667
 668     *a* and *b* can be the same number.
 669
 670     bcl(3) will encode an error in the return value, if there was one. The error
 671     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 672
 673     * **BCL_ERROR_INVALID_NUM**
 674         * **BCL_ERROR_INVALID_CONTEXT**
 675         * **BCL_ERROR_MATH_NON_INTEGER**
 676     * **BCL_ERROR_FATAL_ALLOC_ERR**
 677
 678 **BclNumber bcl_rshift(BclNumber** *a***, BclNumber** *b***)**
 679
 680 :   Shifts *a* right (moves the radix left) by *b* places and returns the
 681     result. This is done in decimal. *b* must be an integer.
 682
 683     *b* must be an integer.
 684
 685     *a* and *b* are consumed; they cannot be used after the call. See the
 686     **Consumption and Propagation** subsection below.
 687
 688     *a* and *b* can be the same number.
 689
 690     bcl(3) will encode an error in the return value, if there was one. The error
 691     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 692
 693     * **BCL_ERROR_INVALID_NUM**
 694         * **BCL_ERROR_INVALID_CONTEXT**
 695         * **BCL_ERROR_MATH_NON_INTEGER**
 696     * **BCL_ERROR_FATAL_ALLOC_ERR**
 697
 698 **BclNumber bcl_sqrt(BclNumber** *a***)**
 699
 700 :   Calculates the square root of *a* and returns the result. The *scale* of the
 701     result is equal to the **scale** of the current context.
 702
 703     *a* cannot be negative.
 704
 705     *a* is consumed; it cannot be used after the call. See the
 706     **Consumption and Propagation** subsection below.
 707
 708     bcl(3) will encode an error in the return value, if there was one. The error
 709     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 710
 711     * **BCL_ERROR_INVALID_NUM**
 712         * **BCL_ERROR_INVALID_CONTEXT**
 713         * **BCL_ERROR_MATH_NEGATIVE**
 714     * **BCL_ERROR_FATAL_ALLOC_ERR**
 715
 716 **BclError bcl_divmod(BclNumber** *a***, BclNumber** *b***, BclNumber \****c***, BclNumber \****d***)**
 717
 718 :   Divides *a* by *b* and returns the quotient in a new number which is put
 719     into the space pointed to by *c*, and puts the modulus in a new number which
 720     is put into the space pointed to by *d*.
 721
 722         *b* cannot be **0**.
 723
 724     *a* and *b* are consumed; they cannot be used after the call. See the
 725     **Consumption and Propagation** subsection below.
 726
 727     *c* and *d* cannot point to the same place, nor can they point to the space
 728     occupied by *a* or *b*.
 729
 730     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 731     function can return:
 732
 733     * **BCL_ERROR_INVALID_NUM**
 734         * **BCL_ERROR_INVALID_CONTEXT**
 735         * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 736     * **BCL_ERROR_FATAL_ALLOC_ERR**
 737
 738 **BclNumber bcl_modexp(BclNumber** *a***, BclNumber** *b***, BclNumber** *c***)**
 739
 740 :   Computes a modular exponentiation where *a* is the base, *b* is the
 741     exponent, and *c* is the modulus, and returns the result. The *scale* of the
 742     result is equal to the **scale** of the current context.
 743
 744     *a*, *b*, and *c* must be integers. *c* must not be **0**. *b* must not be
 745     negative.
 746
 747     *a*, *b*, and *c* are consumed; they cannot be used after the call. See the
 748     **Consumption and Propagation** subsection below.
 749
 750     bcl(3) will encode an error in the return value, if there was one. The error
 751     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 752
 753     * **BCL_ERROR_INVALID_NUM**
 754         * **BCL_ERROR_INVALID_CONTEXT**
 755         * **BCL_ERROR_MATH_NEGATIVE**
 756         * **BCL_ERROR_MATH_NON_INTEGER**
 757         * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 758     * **BCL_ERROR_FATAL_ALLOC_ERR**
 759
 760 ## Miscellaneous
 761
 762 **void bcl_zero(BclNumber** *n***)**
 763
 764 :   Sets *n* to **0**.
 765
 766 **void bcl_one(BclNumber** *n***)**
 767
 768 :   Sets *n* to **1**.
 769
 770 **ssize_t bcl_cmp(BclNumber** *a***, BclNumber** *b***)**
 771
 772 :   Compares *a* and *b* and returns **0** if *a* and *b* are equal, **<0** if
 773     *a* is less than *b*, and **>0** if *a* is greater than *b*.
 774
 775 **BclError bcl_copy(BclNumber** *d***, BclNumber** *s***)**
 776
 777 :   Copies *s* into *d*.
 778
 779     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 780     function can return:
 781
 782     * **BCL_ERROR_INVALID_NUM**
 783     * **BCL_ERROR_INVALID_CONTEXT**
 784     * **BCL_ERROR_FATAL_ALLOC_ERR**
 785
 786 **BclNumber bcl_dup(BclNumber** *s***)**
 787
 788 :   Creates and returns a new **BclNumber** that is a copy of *s*.
 789
 790     bcl(3) will encode an error in the return value, if there was one. The error
 791     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 792
 793     * **BCL_ERROR_INVALID_NUM**
 794         * **BCL_ERROR_INVALID_CONTEXT**
 795     * **BCL_ERROR_FATAL_ALLOC_ERR**
 796
 797 ## Pseudo-Random Number Generator
 798
 799 The pseudo-random number generator in bcl(3) is a *seeded* PRNG. Given the same
 800 seed twice, it will produce the same sequence of pseudo-random numbers twice.
 801
 802 By default, bcl(3) attempts to seed the PRNG with data from **/dev/urandom**. If
 803 that fails, it seeds itself with by calling **libc**'s **srand(time(NULL))** and
 804 then calling **rand()** for each byte, since **rand()** is only guaranteed to
 805 return **15** bits.
 806
 807 This should provide fairly good seeding in the standard case while also
 808 remaining fairly portable.
 809
 810 If necessary, the PRNG can be reseeded with one of the following functions:
 811
 812 * **bcl_rand_seedWithNum(BclNumber)**
 813 * **bcl_rand_seed(unsigned char[BC_SEED_SIZE])**
 814 * **bcl_rand_reseed(***void***)**
 815
 816 The following items allow clients to use the pseudo-random number generator. All
 817 procedures require a valid current context.
 818
 819 **BCL_SEED_ULONGS**
 820
 821 :   The number of **unsigned long**'s in a seed for bcl(3)'s random number
 822     generator.
 823
 824 **BCL_SEED_SIZE**
 825
 826 :   The size, in **char**'s, of a seed for bcl(3)'s random number generator.
 827
 828 **BclBigDig**
 829
 830 :   bcl(3)'s overflow type (see the **PERFORMANCE** section).
 831
 832 **BclRandInt**
 833
 834 :   An unsigned integer type returned by bcl(3)'s random number generator.
 835
 836 **BclNumber bcl_irand(BclNumber** *a***)**
 837
 838 :   Returns a random number that is not larger than *a* in a new number. If *a*
 839     is **0** or **1**, the new number is equal to **0**. The bound is unlimited,
 840     so it is not bound to the size of **BclRandInt**. This is done by generating
 841     as many random numbers as necessary, multiplying them by certain exponents,
 842     and adding them all together.
 843
 844     *a* must be an integer and non-negative.
 845
 846     *a* is consumed; it cannot be used after the call. See the
 847     **Consumption and Propagation** subsection below.
 848
 849     This procedure requires a valid current context.
 850
 851     bcl(3) will encode an error in the return value, if there was one. The error
 852     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 853
 854     * **BCL_ERROR_INVALID_NUM**
 855         * **BCL_ERROR_INVALID_CONTEXT**
 856         * **BCL_ERROR_MATH_NEGATIVE**
 857         * **BCL_ERROR_MATH_NON_INTEGER**
 858     * **BCL_ERROR_FATAL_ALLOC_ERR**
 859
 860 **BclNumber bcl_frand(size_t** *places***)**
 861
 862 :   Returns a random number between **0** (inclusive) and **1** (exclusive) that
 863     has *places* decimal digits after the radix (decimal point). There are no
 864     limits on *places*.
 865
 866     This procedure requires a valid current context.
 867
 868     bcl(3) will encode an error in the return value, if there was one. The error
 869     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 870
 871         * **BCL_ERROR_INVALID_CONTEXT**
 872     * **BCL_ERROR_FATAL_ALLOC_ERR**
 873
 874 **BclNumber bcl_ifrand(BclNumber** *a***, size_t** *places***)**
 875
 876 :   Returns a random number less than *a* with *places* decimal digits after the
 877     radix (decimal point). There are no limits on *a* or *places*.
 878
 879     *a* must be an integer and non-negative.
 880
 881     *a* is consumed; it cannot be used after the call. See the
 882     **Consumption and Propagation** subsection below.
 883
 884     This procedure requires a valid current context.
 885
 886     bcl(3) will encode an error in the return value, if there was one. The error
 887     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 888
 889     * **BCL_ERROR_INVALID_NUM**
 890         * **BCL_ERROR_INVALID_CONTEXT**
 891         * **BCL_ERROR_MATH_NEGATIVE**
 892         * **BCL_ERROR_MATH_NON_INTEGER**
 893     * **BCL_ERROR_FATAL_ALLOC_ERR**
 894
 895 **BclError bcl_rand_seedWithNum(BclNumber** *n***)**
 896
 897 :   Seeds the PRNG with *n*.
 898
 899     *n* is *not* consumed.
 900
 901     This procedure requires a valid current context.
 902
 903     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 904     function can return:
 905
 906     * **BCL_ERROR_INVALID_NUM**
 907         * **BCL_ERROR_INVALID_CONTEXT**
 908
 909     Note that if **bcl_rand_seed2num(***void***)** or
 910     **bcl_rand_seed2num_err(BclNumber)** are called right after this function,
 911     they are not guaranteed to return a number equal to *n*.
 912
 913 **BclError bcl_rand_seed(unsigned char** *seed***[***BC_SEED_SIZE***])**
 914
 915 :   Seeds the PRNG with the bytes in *seed*.
 916
 917     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 918     function can return:
 919
 920         * **BCL_ERROR_INVALID_CONTEXT**
 921
 922 **void bcl_rand_reseed(***void***)**
 923
 924 :   Reseeds the PRNG with the default reseeding behavior. First, it attempts to
 925     read data from **/dev/urandom** and falls back to **libc**'s **rand()**.
 926
 927     This procedure cannot fail.
 928
 929 **BclNumber bcl_rand_seed2num(***void***)**
 930
 931 :   Returns the current seed of the PRNG as a **BclNumber**.
 932
 933     This procedure requires a valid current context.
 934
 935     bcl(3) will encode an error in the return value, if there was one. The error
 936     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 937
 938         * **BCL_ERROR_INVALID_CONTEXT**
 939     * **BCL_ERROR_FATAL_ALLOC_ERR**
 940
 941 **BclRandInt bcl_rand_int(***void***)**
 942
 943 :   Returns a random integer between **0** and **BC_RAND_MAX** (inclusive).
 944
 945     This procedure cannot fail.
 946
 947 **BclRandInt bcl_rand_bounded(BclRandInt** *bound***)**
 948
 949 :   Returns a random integer between **0** and *bound* (exclusive). Bias is
 950     removed before returning the integer.
 951
 952     This procedure cannot fail.
 953
 954 ## Consumption and Propagation
 955
 956 Some functions are listed as consuming some or all of their arguments. This
 957 means that the arguments are freed, regardless of if there were errors or not.
 958
 959 This is to enable compact code like the following:
 960
 961     BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d));
 962
 963 If arguments to those functions were not consumed, memory would be leaked until
 964 reclaimed with **bcl_ctxt_freeNums(BclContext)**.
 965
 966 When errors occur, they are propagated through. The result should always be
 967 checked with **bcl_err(BclNumber)**, so the example above should properly
 968 be:
 969
 970     BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d));
 971     if (bc_num_err(n) != BCL_ERROR_NONE) {
 972         // Handle the error.
 973     }
 974
 975 # ERRORS
 976
 977 Most functions in bcl(3) return, directly or indirectly, any one of the error
 978 codes defined in **BclError**. The complete list of codes is the following:
 979
 980 **BCL_ERROR_NONE**
 981
 982 :   Success; no error occurred.
 983
 984 **BCL_ERROR_INVALID_NUM**
 985
 986 :   An invalid **BclNumber** was given as a parameter.
 987
 988 **BCL_ERROR_INVALID_CONTEXT**
 989
 990 :   An invalid **BclContext** is being used.
 991
 992 **BCL_ERROR_SIGNAL**
 993
 994 :   A signal interrupted execution.
 995
 996 **BCL_ERROR_MATH_NEGATIVE**
 997
 998 :   A negative number was given as an argument to a parameter that cannot accept
 999     negative numbers, such as for square roots.
1000
1001 **BCL_ERROR_MATH_NON_INTEGER**
1002
1003 :   A non-integer was given as an argument to a parameter that cannot accept
1004     non-integer numbers, such as for the second parameter of **bcl_num_pow()**.
1005
1006 **BCL_ERROR_MATH_OVERFLOW**
1007
1008 :   A number that would overflow its result was given as an argument, such as
1009     for converting a **BclNumber** to a **BclBigDig**.
1010
1011 **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
1012
1013 :   A divide by zero occurred.
1014
1015 **BCL_ERROR_PARSE_INVALID_STR**
1016
1017 :   An invalid number string was passed to a parsing function.
1018
1019     A valid number string can only be one radix (period). In addition, any
1020     lowercase ASCII letters, symbols, or non-ASCII characters are invalid. It is
1021     allowed for the first character to be a dash. In that case, the number is
1022     considered to be negative.
1023
1024     There is one exception to the above: one lowercase **e** is allowed in the
1025     number, after the radix, if it exists. If the letter **e** exists, the
1026     number is considered to be in scientific notation, where the part before the
1027     **e** is the number, and the part after, which must be an integer, is the
1028     exponent. There can be a dash right after the **e** to indicate a negative
1029     exponent.
1030
1031     **WARNING**: Both the number and the exponent in scientific notation are
1032     interpreted according to the current **ibase**, but the number is still
1033     multiplied by **10\^exponent** regardless of the current **ibase**. For
1034     example, if **ibase** is **16** and bcl(3) is given the number string
1035     **FFeA**, the resulting decimal number will be **2550000000000**, and if
1036     bcl(3) is given the number string **10e-4**, the resulting decimal number
1037     will be **0.0016**.
1038
1039 **BCL_ERROR_FATAL_ALLOC_ERR**
1040
1041 :   bcl(3) failed to allocate memory.
1042
1043     If clients call **bcl_setAbortOnFatalError()** with an **true** argument,
1044     this error will cause bcl(3) to throw a **SIGABRT**. This behavior can also
1045     be turned off later by calling that same function with a **false** argument.
1046     By default, this behavior is off.
1047
1048     It is highly recommended that client libraries do *not* activate this
1049     behavior.
1050
1051 **BCL_ERROR_FATAL_UNKNOWN_ERR**
1052
1053 :   An unknown error occurred.
1054
1055     If clients call **bcl_setAbortOnFatalError()** with an **true** argument,
1056     this error will cause bcl(3) to throw a **SIGABRT**. This behavior can also
1057     be turned off later by calling that same function with a **false** argument.
1058     By default, this behavior is off.
1059
1060     It is highly recommended that client libraries do *not* activate this
1061     behavior.
1062
1063 # ATTRIBUTES
1064
1065 When **bcl_handleSignal(***void***)** is used properly, bcl(3) is
1066 async-signal-safe.
1067
1068 bcl(3) is *MT-Unsafe*: it is unsafe to call any functions from more than one
1069 thread.
1070
1071 # PERFORMANCE
1072
1073 Most bc(1) implementations use **char** types to calculate the value of **1**
1074 decimal digit at a time, but that can be slow. bcl(3) does something
1075 different.
1076
1077 It uses large integers to calculate more than **1** decimal digit at a time. If
1078 built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is
1079 **64**, then each integer has **9** decimal digits. If built in an environment
1080 where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This
1081 value (the number of decimal digits per large integer) is called
1082 **BC_BASE_DIGS**.
1083
1084 In addition, this bcl(3) uses an even larger integer for overflow checking. This
1085 integer type depends on the value of **BC_LONG_BIT**, but is always at least
1086 twice as large as the integer type used to store digits.
1087
1088 # LIMITS
1089
1090 The following are the limits on bcl(3):
1091
1092 **BC_LONG_BIT**
1093
1094 :   The number of bits in the **long** type in the environment where bcl(3) was
1095     built. This determines how many decimal digits can be stored in a single
1096     large integer (see the **PERFORMANCE** section).
1097
1098 **BC_BASE_DIGS**
1099
1100 :   The number of decimal digits per large integer (see the **PERFORMANCE**
1101     section). Depends on **BC_LONG_BIT**.
1102
1103 **BC_BASE_POW**
1104
1105 :   The max decimal number that each large integer can store (see
1106     **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**.
1107
1108 **BC_OVERFLOW_MAX**
1109
1110 :   The max number that the overflow type (see the **PERFORMANCE** section) can
1111     hold. Depends on **BC_LONG_BIT**.
1112
1113 **BC_BASE_MAX**
1114
1115 :   The maximum output base. Set at **BC_BASE_POW**.
1116
1117 **BC_SCALE_MAX**
1118
1119 :   The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**.
1120
1121 **BC_NUM_MAX**
1122
1123 :   The maximum length of a number (in decimal digits), which includes digits
1124     after the decimal point. Set at **BC_OVERFLOW_MAX-1**.
1125
1126 **BC_RAND_MAX**
1127
1128 :   The maximum integer (inclusive) returned by the **bcl_rand_int()** function.
1129     Set at **2\^BC_LONG_BIT-1**.
1130
1131 Exponent
1132
1133 :   The maximum allowable exponent (positive or negative). Set at
1134     **BC_OVERFLOW_MAX**.
1135
1136 These limits are meant to be effectively non-existent; the limits are so large
1137 (at least on 64-bit machines) that there should not be any point at which they
1138 become a problem. In fact, memory should be exhausted before these limits should
1139 be hit.
1140
1141 # SIGNAL HANDLING
1142
1143 If a signal handler calls **bcl_handleSignal(***void***)** from the same thread
1144 that there are bcl(3) functions executing in, it will cause all execution to
1145 stop as soon as possible, interrupting long-running calculations, if necessary
1146 and cause the function that was executing to return. If possible, the error code
1147 **BC_ERROR_SIGNAL** is returned.
1148
1149 If execution *is* interrupted, **bcl_handleSignal(***void***)** does *not*
1150 return to its caller.
1151
1152 It is undefined behavior if **bcl_handleSignal(***void***)** is called from
1153 a thread that is not executing bcl(3) functions, if bcl(3) functions are
1154 executing.
1155
1156 # SEE ALSO
1157
1158 bc(1) and dc(1)
1159
1160 # STANDARDS
1161
1162 bcl(3) is compliant with the arithmetic defined in the
1163 [IEEE Std 1003.1-2017 (“POSIX.1-2017”)][1] specification for bc(1).
1164
1165 Note that the specification explicitly says that bc(1) only accepts numbers that
1166 use a period (**.**) as a radix point, regardless of the value of
1167 **LC_NUMERIC**. This is also true of bcl(3).
1168
1169 # BUGS
1170
1171 None are known. Report bugs at https://git.yzena.com/gavin/bc.
1172
1173 # AUTHORS
1174
1175 Gavin D. Howard <gavin@yzena.com> and contributors.
1176
1177 [1]: https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html