contrib/bc/manuals/bcl.3.md

   1 <!---
   2
   3 SPDX-License-Identifier: BSD-2-Clause
   4
   5 Copyright (c) 2018-2023 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*, and on POSIX systems, *-lpthread* is also required.
  42
  43 ## Setup
  44
  45 These items allow clients to set up bcl(3).
  46
  47 **BclError bcl_start(**_void_**);**
  48
  49 **void bcl_end(**_void_**);**
  50
  51 **BclError bcl_init(**_void_**);**
  52
  53 **void bcl_free(**_void_**);**
  54
  55 **bool bcl_abortOnFatalError(**_void_**);**
  56
  57 **void bcl_setAbortOnFatalError(bool** _abrt_**);**
  58
  59 **bool bcl_leadingZeroes(**_void_**);**
  60
  61 **void bcl_setLeadingZeroes(bool** _leadingZeroes_**);**
  62
  63 **void bcl_gc(**_void_**);**
  64
  65 **bool bcl_digitClamp(**_void_**);**
  66
  67 **void bcl_setDigitClamp(bool** _digitClamp_**);**
  68
  69 ## Contexts
  70
  71 These items will allow clients to handle contexts, which are isolated from each
  72 other. This allows more than one client to use bcl(3) in the same program.
  73
  74 **struct BclCtxt;**
  75
  76 **typedef struct BclCtxt\* BclContext;**
  77
  78 **BclContext bcl_ctxt_create(**_void_**);**
  79
  80 **void bcl_ctxt_free(BclContext** _ctxt_**);**
  81
  82 **BclError bcl_pushContext(BclContext** _ctxt_**);**
  83
  84 **void bcl_popContext(**_void_**);**
  85
  86 **BclContext bcl_context(**_void_**);**
  87
  88 **void bcl_ctxt_freeNums(BclContext** _ctxt_**);**
  89
  90 **size_t bcl_ctxt_scale(BclContext** _ctxt_**);**
  91
  92 **void bcl_ctxt_setScale(BclContext** _ctxt_**, size_t** _scale_**);**
  93
  94 **size_t bcl_ctxt_ibase(BclContext** _ctxt_**);**
  95
  96 **void bcl_ctxt_setIbase(BclContext** _ctxt_**, size_t** _ibase_**);**
  97
  98 **size_t bcl_ctxt_obase(BclContext** _ctxt_**);**
  99
 100 **void bcl_ctxt_setObase(BclContext** _ctxt_**, size_t** _obase_**);**
 101
 102 ## Errors
 103
 104 These items allow clients to handle errors.
 105
 106 **typedef enum BclError BclError;**
 107
 108 **BclError bcl_err(BclNumber** _n_**);**
 109
 110 ## Numbers
 111
 112 These items allow clients to manipulate and query the arbitrary-precision
 113 numbers managed by bcl(3).
 114
 115 **typedef struct { size_t i; } BclNumber;**
 116
 117 **BclNumber bcl_num_create(**_void_**);**
 118
 119 **void bcl_num_free(BclNumber** _n_**);**
 120
 121 **bool bcl_num_neg(BclNumber** _n_**);**
 122
 123 **void bcl_num_setNeg(BclNumber** _n_**, bool** _neg_**);**
 124
 125 **size_t bcl_num_scale(BclNumber** _n_**);**
 126
 127 **BclError bcl_num_setScale(BclNumber** _n_**, size_t** _scale_**);**
 128
 129 **size_t bcl_num_len(BclNumber** _n_**);**
 130
 131 ## Conversion
 132
 133 These items allow clients to convert numbers into and from strings and integers.
 134
 135 **BclNumber bcl_parse(const char \*restrict** _val_**);**
 136
 137 **char\* bcl_string(BclNumber** _n_**);**
 138
 139 **char\* bcl_string_keep(BclNumber** _n_**);**
 140
 141 **BclError bcl_bigdig(BclNumber** _n_**, BclBigDig \***_result_**);**
 142
 143 **BclError bcl_bigdig_keep(BclNumber** _n_**, BclBigDig \***_result_**);**
 144
 145 **BclNumber bcl_bigdig2num(BclBigDig** _val_**);**
 146
 147 ## Math
 148
 149 These items allow clients to run math on numbers.
 150
 151 **BclNumber bcl_add(BclNumber** _a_**, BclNumber** _b_**);**
 152
 153 **BclNumber bcl_add_keep(BclNumber** _a_**, BclNumber** _b_**);**
 154
 155 **BclNumber bcl_sub(BclNumber** _a_**, BclNumber** _b_**);**
 156
 157 **BclNumber bcl_sub_keep(BclNumber** _a_**, BclNumber** _b_**);**
 158
 159 **BclNumber bcl_mul(BclNumber** _a_**, BclNumber** _b_**);**
 160
 161 **BclNumber bcl_mul_keep(BclNumber** _a_**, BclNumber** _b_**);**
 162
 163 **BclNumber bcl_div(BclNumber** _a_**, BclNumber** _b_**);**
 164
 165 **BclNumber bcl_div_keep(BclNumber** _a_**, BclNumber** _b_**);**
 166
 167 **BclNumber bcl_mod(BclNumber** _a_**, BclNumber** _b_**);**
 168
 169 **BclNumber bcl_mod_keep(BclNumber** _a_**, BclNumber** _b_**);**
 170
 171 **BclNumber bcl_pow(BclNumber** _a_**, BclNumber** _b_**);**
 172
 173 **BclNumber bcl_pow_keep(BclNumber** _a_**, BclNumber** _b_**);**
 174
 175 **BclNumber bcl_lshift(BclNumber** _a_**, BclNumber** _b_**);**
 176
 177 **BclNumber bcl_lshift_keep(BclNumber** _a_**, BclNumber** _b_**);**
 178
 179 **BclNumber bcl_rshift(BclNumber** _a_**, BclNumber** _b_**);**
 180
 181 **BclNumber bcl_rshift_keep(BclNumber** _a_**, BclNumber** _b_**);**
 182
 183 **BclNumber bcl_sqrt(BclNumber** _a_**);**
 184
 185 **BclNumber bcl_sqrt_keep(BclNumber** _a_**);**
 186
 187 **BclError bcl_divmod(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**);**
 188
 189 **BclError bcl_divmod_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**);**
 190
 191 **BclNumber bcl_modexp(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**);**
 192
 193 **BclNumber bcl_modexp_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**);**
 194
 195 ## Miscellaneous
 196
 197 These items are miscellaneous.
 198
 199 **void bcl_zero(BclNumber** _n_**);**
 200
 201 **void bcl_one(BclNumber** _n_**);**
 202
 203 **ssize_t bcl_cmp(BclNumber** _a_**, BclNumber** _b_**);**
 204
 205 **BclError bcl_copy(BclNumber** _d_**, BclNumber** _s_**);**
 206
 207 **BclNumber bcl_dup(BclNumber** _s_**);**
 208
 209 ## Pseudo-Random Number Generator
 210
 211 These items allow clients to manipulate the seeded pseudo-random number
 212 generator in bcl(3).
 213
 214 **#define BCL_SEED_ULONGS**
 215
 216 **#define BCL_SEED_SIZE**
 217
 218 **typedef unsigned long BclBigDig;**
 219
 220 **typedef unsigned long BclRandInt;**
 221
 222 **BclNumber bcl_irand(BclNumber** _a_**);**
 223
 224 **BclNumber bcl_irand_keep(BclNumber** _a_**);**
 225
 226 **BclNumber bcl_frand(size_t** _places_**);**
 227
 228 **BclNumber bcl_ifrand(BclNumber** _a_**, size_t** _places_**);**
 229
 230 **BclNumber bcl_ifrand_keep(BclNumber** _a_**, size_t** _places_**);**
 231
 232 **BclError bcl_rand_seedWithNum(BclNumber** _n_**);**
 233
 234 **BclError bcl_rand_seedWithNum_keep(BclNumber** _n_**);**
 235
 236 **BclError bcl_rand_seed(unsigned char** _seed_**[**_BCL_SEED_SIZE_**]);**
 237
 238 **void bcl_rand_reseed(**_void_**);**
 239
 240 **BclNumber bcl_rand_seed2num(**_void_**);**
 241
 242 **BclRandInt bcl_rand_int(**_void_**);**
 243
 244 **BclRandInt bcl_rand_bounded(BclRandInt** _bound_**);**
 245
 246 # DESCRIPTION
 247
 248 bcl(3) is a library that implements arbitrary-precision decimal math, as
 249 standardized by POSIX
 250 (https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) in bc(1).
 251
 252 bcl(3) assumes that it is allowed to use the **bcl**, **Bcl**, **bc**, and
 253 **Bc** prefixes for symbol names without collision.
 254
 255 All of the items in its interface are described below. See the documentation for
 256 each function for what each function can return.
 257
 258 ## Setup
 259
 260 **BclError bcl_start(**_void_**)**
 261
 262 :   Initializes this library. This function can be called multiple times, but
 263     **bcl_end()** must only be called *once*. This is to make it possible for
 264     multiple libraries and applications to initialize bcl(3) without problem.
 265
 266     It is suggested that client libraries call this function, but do not call
 267     **bcl_end()**, and client applications should call both.
 268
 269     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 270     function can return:
 271
 272     * **BCL_ERROR_FATAL_ALLOC_ERR**
 273
 274     This function must be the first one clients call. Calling any other
 275     function without calling this one first is undefined behavior.
 276
 277 **void bcl_end(**_void_**)**
 278
 279 :   Deinitializes this library. This function must only be called *once*.
 280
 281     All data must have been freed before calling this function.
 282
 283     This function must be the last one clients call. Calling this function
 284     before calling any other function is undefined behavior.
 285
 286 **BclError bcl_init(**_void_**)**
 287
 288 :   Initializes the library for the current thread. This function can be called
 289     multiple times, but each call must be matched by a call to
 290     **bcl_free(**_void_**)**. This is to make it possible for multiple libraries
 291     and applications to initialize threads for bcl(3) without problem.
 292
 293     This function *must* be called from the thread that it is supposed to
 294     initialize.
 295
 296     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 297     function can return:
 298
 299     * **BCL_ERROR_FATAL_ALLOC_ERR**
 300
 301     This function must be the second one clients call. Calling any other
 302     function without calling **bcl_start()** and then this one first is
 303     undefined behavior, except in the case of new threads. New threads can
 304     safely call this function without calling **bcl_start()** if another thread
 305     has previously called **bcl_start()**. But this function must still be the
 306     first function in bcl(3) called by that new thread.
 307
 308 **void bcl_free(**_void_**)**
 309
 310 :   Decrements bcl(3)'s reference count and frees the data associated with it if
 311     the reference count is **0**.
 312
 313     This function *must* be called from the thread that it is supposed to
 314     deinitialize.
 315
 316     This function must be the second to last one clients call. Calling this
 317     function before calling any other function besides **bcl_end()** is
 318     undefined behavior.
 319
 320 **bool bcl_abortOnFatalError(**_void_**)**
 321
 322 :   Queries and returns the current state of calling **abort()** on fatal
 323     errors. If **true** is returned, bcl(3) will cause a **SIGABRT** if a fatal
 324     error occurs.
 325
 326     If activated, clients do not need to check for fatal errors.
 327
 328     This value is *thread-local*; it applies to just the thread it is read on.
 329
 330     The default is **false**.
 331
 332 **void bcl_setAbortOnFatalError(bool** _abrt_**)**
 333
 334 :   Sets the state of calling **abort()** on fatal errors. If *abrt* is
 335     **false**, bcl(3) will not cause a **SIGABRT** on fatal errors after the
 336     call. If *abrt* is **true**, bcl(3) will cause a **SIGABRT** on fatal errors
 337     after the call.
 338
 339     This value is *thread-local*; it applies to just the thread it is set on.
 340
 341     If activated, clients do not need to check for fatal errors.
 342
 343 **bool bcl_leadingZeroes(**_void_**)**
 344
 345 :   Queries and returns the state of whether leading zeroes are added to strings
 346     returned by **bcl_string()** when numbers are greater than **-1**, less than
 347     **1**, and not equal to **0**. If **true** is returned, then leading zeroes
 348     will be added.
 349
 350     This value is *thread-local*; it applies to just the thread it is read on.
 351
 352     The default is **false**.
 353
 354 **void bcl_setLeadingZeroes(bool** _leadingZeroes_**)**
 355
 356 :   Sets the state of whether leading zeroes are added to strings returned by
 357     **bcl_string()** when numbers are greater than **-1**, less than **1**, and
 358     not equal to **0**. If *leadingZeroes* is **true**, leading zeroes will be
 359     added to strings returned by **bcl_string()**.
 360
 361     This value is *thread-local*; it applies to just the thread it is set on.
 362
 363 **bool bcl_digitClamp(**_void_**)**
 364
 365 :   Queries and returns the state of whether digits in number strings that are
 366     greater than or equal to the current **ibase** are clamped or not.
 367
 368     If **true** is returned, then digits are treated as though they are equal to
 369     the value of **ibase** minus **1**. If this is *not* true, then digits are
 370     treated as though they are equal to the value they would have if **ibase**
 371     was large enough. They are then multiplied by the appropriate power of
 372     **ibase**.
 373
 374     For example, with clamping off and an **ibase** of **3**, the string "AB"
 375     would equal **3\^1\*A+3\^0\*B**, which is **3** times **10** plus **11**, or
 376     **41**, while with clamping on and an **ibase** of **3**, the string "AB"
 377     would be equal to **3\^1\*2+3\^0\*2**, which is **3** times **2** plus
 378     **2**, or **8**.
 379
 380     This value is *thread-local*; it applies to just the thread it is read on.
 381
 382     The default is **true**.
 383
 384 **void bcl_setDigitClamp(bool** _digitClamp_**)**
 385
 386 :   Sets the state of whether digits in number strings that are greater than or
 387     equal to the current **ibase** are clamped or not. For more information, see
 388     the **bcl_digitClamp(**_void_**)** function.
 389
 390     This value is *thread-local*; it applies to just the thread it is set on.
 391
 392 **void bcl_gc(**_void_**)**
 393
 394 :   Garbage collects cached instances of arbitrary-precision numbers. This only
 395     frees the memory of numbers that are *not* in use, so it is safe to call at
 396     any time.
 397
 398 ## Contexts
 399
 400 All procedures that take a **BclContext** parameter a require a valid context as
 401 an argument.
 402
 403 **struct BclCtxt**
 404
 405 :   A forward declaration for a hidden **struct** type. Clients cannot access
 406     the internals of the **struct** type directly. All interactions with the
 407     type are done through pointers. See **BclContext** below.
 408
 409 **BclContext**
 410
 411 :   A typedef to a pointer of **struct BclCtxt**. This is the only handle
 412     clients can get to **struct BclCtxt**.
 413
 414     A **BclContext** contains the values **scale**, **ibase**, and **obase**, as
 415     well as a list of numbers.
 416
 417     **scale** is a value used to control how many decimal places calculations
 418     should use. A value of **0** means that calculations are done on integers
 419     only, where applicable, and a value of 20, for example, means that all
 420     applicable calculations return results with 20 decimal places. The default
 421     is **0**.
 422
 423     **ibase** is a value used to control the input base. The minimum **ibase**
 424     is **2**, and the maximum is **36**. If **ibase** is **2**, numbers are
 425     parsed as though they are in binary, and any digits larger than **1** are
 426     clamped. Likewise, a value of **10** means that numbers are parsed as though
 427     they are decimal, and any larger digits are clamped. The default is **10**.
 428
 429     **obase** is a value used to control the output base. The minimum **obase**
 430     is **0** and the maximum is **BC_BASE_MAX** (see the **LIMITS** section).
 431
 432     Numbers created in one context are not valid in another context. It is
 433     undefined behavior to use a number created in a different context. Contexts
 434     are meant to isolate the numbers used by different clients in the same
 435     application.
 436
 437     Different threads also have different contexts, so any numbers created in
 438     one thread are not valid in another thread. To pass values between contexts
 439     and threads, use **bcl_string()** to produce a string to pass around, and
 440     use **bcl_parse()** to parse the string. It is suggested that the **obase**
 441     used to create the string be passed around with the string and used as the
 442     **ibase** for **bcl_parse()** to ensure that the number will be the same.
 443
 444 **BclContext bcl_ctxt_create(**_void_**)**
 445
 446 :   Creates a context and returns it. Returns **NULL** if there was an error.
 447
 448 **void bcl_ctxt_free(BclContext** _ctxt_**)**
 449
 450 :   Frees *ctxt*, after which it is no longer valid. It is undefined behavior to
 451     attempt to use an invalid context.
 452
 453 **BclError bcl_pushContext(BclContext** _ctxt_**)**
 454
 455 :   Pushes *ctxt* onto bcl(3)'s stack of contexts. *ctxt* must have been created
 456     with **bcl_ctxt_create(**_void_**)**.
 457
 458     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 459     function can return:
 460
 461     * **BCL_ERROR_FATAL_ALLOC_ERR**
 462
 463     There *must* be a valid context to do any arithmetic.
 464
 465 **void bcl_popContext(**_void_**)**
 466
 467 :   Pops the current context off of the stack, if one exists.
 468
 469 **BclContext bcl_context(**_void_**)**
 470
 471 :   Returns the current context, or **NULL** if no context exists.
 472
 473 **void bcl_ctxt_freeNums(BclContext** _ctxt_**)**
 474
 475 :   Frees all numbers in use that are associated with *ctxt*. It is undefined
 476     behavior to attempt to use a number associated with *ctxt* after calling
 477     this procedure unless such numbers have been created with
 478     **bcl_num_create(**_void_**)** after calling this procedure.
 479
 480 **size_t bcl_ctxt_scale(BclContext** _ctxt_**)**
 481
 482 :   Returns the **scale** for given context.
 483
 484 **void bcl_ctxt_setScale(BclContext** _ctxt_**, size_t** _scale_**)**
 485
 486 :   Sets the **scale** for the given context to the argument *scale*.
 487
 488 **size_t bcl_ctxt_ibase(BclContext** _ctxt_**)**
 489
 490 :   Returns the **ibase** for the given context.
 491
 492 **void bcl_ctxt_setIbase(BclContext** _ctxt_**, size_t** _ibase_**)**
 493
 494 :   Sets the **ibase** for the given context to the argument *ibase*. If the
 495     argument *ibase* is invalid, it clamped, so an *ibase* of **0** or **1** is
 496     clamped to **2**, and any values above **36** are clamped to **36**.
 497
 498 **size_t bcl_ctxt_obase(BclContext** _ctxt_**)**
 499
 500 :   Returns the **obase** for the given context.
 501
 502 **void bcl_ctxt_setObase(BclContext** _ctxt_**, size_t** _obase_**)**
 503
 504 :   Sets the **obase** for the given context to the argument *obase*.
 505
 506 ## Errors
 507
 508 **BclError**
 509
 510 :   An **enum** of possible error codes. See the **ERRORS** section for a
 511     complete listing the codes.
 512
 513 **BclError bcl_err(BclNumber** _n_**)**
 514
 515 :   Checks for errors in a **BclNumber**. All functions that can return a
 516     **BclNumber** can encode an error in the number, and this function will
 517     return the error, if any. If there was no error, it will return
 518     **BCL_ERROR_NONE**.
 519
 520     There must be a valid current context.
 521
 522 ## Numbers
 523
 524 All procedures in this section require a valid current context.
 525
 526 **BclNumber**
 527
 528 :   A handle to an arbitrary-precision number. The actual number type is not
 529     exposed; the **BclNumber** handle is the only way clients can refer to
 530     instances of arbitrary-precision numbers.
 531
 532 **BclNumber bcl_num_create(**_void_**)**
 533
 534 :   Creates and returns a **BclNumber**.
 535
 536     bcl(3) will encode an error in the return value, if there was one. The error
 537     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 538
 539     * **BCL_ERROR_INVALID_CONTEXT**
 540     * **BCL_ERROR_FATAL_ALLOC_ERR**
 541
 542 **void bcl_num_free(BclNumber** _n_**)**
 543
 544 :   Frees *n*. It is undefined behavior to use *n* after calling this function.
 545
 546 **bool bcl_num_neg(BclNumber** _n_**)**
 547
 548 :   Returns **true** if *n* is negative, **false** otherwise.
 549
 550 **void bcl_num_setNeg(BclNumber** _n_**, bool** _neg_**)**
 551
 552 :   Sets *n*'s sign to *neg*, where **true** is negative, and **false** is
 553     positive.
 554
 555 **size_t bcl_num_scale(BclNumber** _n_**)**
 556
 557 :   Returns the *scale* of *n*.
 558
 559     The *scale* of a number is the number of decimal places it has after the
 560     radix (decimal point).
 561
 562 **BclError bcl_num_setScale(BclNumber** _n_**, size_t** _scale_**)**
 563
 564 :   Sets the *scale* of *n* to the argument *scale*. If the argument *scale* is
 565     greater than the *scale* of *n*, *n* is extended. If the argument *scale* is
 566     less than the *scale* of *n*, *n* is truncated.
 567
 568     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 569     function can return:
 570
 571     * **BCL_ERROR_INVALID_NUM**
 572     * **BCL_ERROR_INVALID_CONTEXT**
 573     * **BCL_ERROR_FATAL_ALLOC_ERR**
 574
 575 **size_t bcl_num_len(BclNumber** _n_**)**
 576
 577 :   Returns the number of *significant decimal digits* in *n*.
 578
 579 ## Conversion
 580
 581 All procedures in this section require a valid current context.
 582
 583 All procedures in this section without the **_keep** suffix in their name
 584 consume the given **BclNumber** arguments that are not given to pointer
 585 arguments. See the **Consumption and Propagation** subsection below.
 586
 587 **BclNumber bcl_parse(const char \*restrict** _val_**)**
 588
 589 :   Parses a number string according to the current context's **ibase** and
 590     returns the resulting number.
 591
 592     *val* must be non-**NULL** and a valid string. See
 593     **BCL_ERROR_PARSE_INVALID_STR** in the **ERRORS** section for more
 594     information.
 595
 596     bcl(3) will encode an error in the return value, if there was one. The error
 597     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 598
 599     * **BCL_ERROR_INVALID_NUM**
 600     * **BCL_ERROR_INVALID_CONTEXT**
 601     * **BCL_ERROR_PARSE_INVALID_STR**
 602     * **BCL_ERROR_FATAL_ALLOC_ERR**
 603
 604 **char\* bcl_string(BclNumber** _n_**)**
 605
 606 :   Returns a string representation of *n* according the the current context's
 607     **ibase**. The string is dynamically allocated and must be freed by the
 608     caller.
 609
 610     *n* is consumed; it cannot be used after the call. See the
 611     **Consumption and Propagation** subsection below.
 612
 613 **char\* bcl_string_keep(BclNumber** _n_**)**
 614
 615 :   Returns a string representation of *n* according the the current context's
 616     **ibase**. The string is dynamically allocated and must be freed by the
 617     caller.
 618
 619 **BclError bcl_bigdig(BclNumber** _n_**, BclBigDig \***_result_**)**
 620
 621 :   Converts *n* into a **BclBigDig** and returns the result in the space
 622     pointed to by *result*.
 623
 624     *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section.
 625
 626     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 627     function can return:
 628
 629     * **BCL_ERROR_INVALID_NUM**
 630     * **BCL_ERROR_INVALID_CONTEXT**
 631     * **BCL_ERROR_MATH_OVERFLOW**
 632
 633     *n* is consumed; it cannot be used after the call. See the
 634     **Consumption and Propagation** subsection below.
 635
 636 **BclError bcl_bigdig_keep(BclNumber** _n_**, BclBigDig \***_result_**)**
 637
 638 :   Converts *n* into a **BclBigDig** and returns the result in the space
 639     pointed to by *result*.
 640
 641     *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section.
 642
 643     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
 644     function can return:
 645
 646     * **BCL_ERROR_INVALID_NUM**
 647     * **BCL_ERROR_INVALID_CONTEXT**
 648     * **BCL_ERROR_MATH_OVERFLOW**
 649
 650 **BclNumber bcl_bigdig2num(BclBigDig** _val_**)**
 651
 652 :   Creates a **BclNumber** from *val*.
 653
 654     bcl(3) will encode an error in the return value, if there was one. The error
 655     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 656
 657     * **BCL_ERROR_INVALID_CONTEXT**
 658     * **BCL_ERROR_FATAL_ALLOC_ERR**
 659
 660 ## Math
 661
 662 All procedures in this section require a valid current context.
 663
 664 All procedures in this section without the **_keep** suffix in their name
 665 consume the given **BclNumber** arguments that are not given to pointer
 666 arguments. See the **Consumption and Propagation** subsection below.
 667
 668 All procedures in this section can return the following errors:
 669
 670 * **BCL_ERROR_INVALID_NUM**
 671 * **BCL_ERROR_INVALID_CONTEXT**
 672 * **BCL_ERROR_FATAL_ALLOC_ERR**
 673
 674 **BclNumber bcl_add(BclNumber** _a_**, BclNumber** _b_**)**
 675
 676 :   Adds *a* and *b* and returns the result. The *scale* of the result is the
 677     max of the *scale*s of *a* and *b*.
 678
 679     *a* and *b* are consumed; they cannot be used after the call. See the
 680     **Consumption and Propagation** subsection below.
 681
 682     *a* and *b* can be the same number.
 683
 684     bcl(3) will encode an error in the return value, if there was one. The error
 685     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 686
 687     * **BCL_ERROR_INVALID_NUM**
 688     * **BCL_ERROR_INVALID_CONTEXT**
 689     * **BCL_ERROR_FATAL_ALLOC_ERR**
 690
 691 **BclNumber bcl_add_keep(BclNumber** _a_**, BclNumber** _b_**)**
 692
 693 :   Adds *a* and *b* and returns the result. The *scale* of the result is the
 694     max of the *scale*s of *a* and *b*.
 695
 696     *a* and *b* can be the same number.
 697
 698     bcl(3) will encode an error in the return value, if there was one. The error
 699     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 700
 701     * **BCL_ERROR_INVALID_NUM**
 702     * **BCL_ERROR_INVALID_CONTEXT**
 703     * **BCL_ERROR_FATAL_ALLOC_ERR**
 704
 705 **BclNumber bcl_sub(BclNumber** _a_**, BclNumber** _b_**)**
 706
 707 :   Subtracts *b* from *a* and returns the result. The *scale* of the result is
 708     the max of the *scale*s of *a* and *b*.
 709
 710     *a* and *b* are consumed; they cannot be used after the call. See the
 711     **Consumption and Propagation** subsection below.
 712
 713     *a* and *b* can be the same number.
 714
 715     bcl(3) will encode an error in the return value, if there was one. The error
 716     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 717
 718     * **BCL_ERROR_INVALID_NUM**
 719     * **BCL_ERROR_INVALID_CONTEXT**
 720     * **BCL_ERROR_FATAL_ALLOC_ERR**
 721
 722 **BclNumber bcl_sub_keep(BclNumber** _a_**, BclNumber** _b_**)**
 723
 724 :   Subtracts *b* from *a* and returns the result. The *scale* of the result is
 725     the max of the *scale*s of *a* and *b*.
 726
 727     *a* and *b* can be the same number.
 728
 729     bcl(3) will encode an error in the return value, if there was one. The error
 730     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 731
 732     * **BCL_ERROR_INVALID_NUM**
 733     * **BCL_ERROR_INVALID_CONTEXT**
 734     * **BCL_ERROR_FATAL_ALLOC_ERR**
 735
 736 **BclNumber bcl_mul(BclNumber** _a_**, BclNumber** _b_**)**
 737
 738 :   Multiplies *a* and *b* and returns the result. If *ascale* is the *scale* of
 739     *a* and *bscale* is the *scale* of *b*, the *scale* of the result is equal
 740     to **min(ascale+bscale,max(scale,ascale,bscale))**, where **min()** and
 741     **max()** return the obvious values.
 742
 743     *a* and *b* are consumed; they cannot be used after the call. See the
 744     **Consumption and Propagation** subsection below.
 745
 746     *a* and *b* can be the same number.
 747
 748     bcl(3) will encode an error in the return value, if there was one. The error
 749     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 750
 751     * **BCL_ERROR_INVALID_NUM**
 752     * **BCL_ERROR_INVALID_CONTEXT**
 753     * **BCL_ERROR_FATAL_ALLOC_ERR**
 754
 755 **BclNumber bcl_mul_keep(BclNumber** _a_**, BclNumber** _b_**)**
 756
 757 :   Multiplies *a* and *b* and returns the result. If *ascale* is the *scale* of
 758     *a* and *bscale* is the *scale* of *b*, the *scale* of the result is equal
 759     to **min(ascale+bscale,max(scale,ascale,bscale))**, where **min()** and
 760     **max()** return the obvious values.
 761
 762     *a* and *b* can be the same number.
 763
 764     bcl(3) will encode an error in the return value, if there was one. The error
 765     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 766
 767     * **BCL_ERROR_INVALID_NUM**
 768     * **BCL_ERROR_INVALID_CONTEXT**
 769     * **BCL_ERROR_FATAL_ALLOC_ERR**
 770
 771 **BclNumber bcl_div(BclNumber** _a_**, BclNumber** _b_**)**
 772
 773 :   Divides *a* by *b* and returns the result. The *scale* of the result is the
 774     *scale* of the current context.
 775
 776     *b* cannot be **0**.
 777
 778     *a* and *b* are consumed; they cannot be used after the call. See the
 779     **Consumption and Propagation** subsection below.
 780
 781     *a* and *b* can be the same number.
 782
 783     bcl(3) will encode an error in the return value, if there was one. The error
 784     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 785
 786     * **BCL_ERROR_INVALID_NUM**
 787     * **BCL_ERROR_INVALID_CONTEXT**
 788     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 789     * **BCL_ERROR_FATAL_ALLOC_ERR**
 790
 791 **BclNumber bcl_div_keep(BclNumber** _a_**, BclNumber** _b_**)**
 792
 793 :   Divides *a* by *b* and returns the result. The *scale* of the result is the
 794     *scale* of the current context.
 795
 796     *b* cannot be **0**.
 797
 798     *a* and *b* can be the same number.
 799
 800     bcl(3) will encode an error in the return value, if there was one. The error
 801     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 802
 803     * **BCL_ERROR_INVALID_NUM**
 804     * **BCL_ERROR_INVALID_CONTEXT**
 805     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 806     * **BCL_ERROR_FATAL_ALLOC_ERR**
 807
 808 **BclNumber bcl_mod(BclNumber** _a_**, BclNumber** _b_**)**
 809
 810 :   Divides *a* by *b* to the *scale* of the current context, computes the
 811     modulus **a-(a/b)\*b**, and returns the modulus.
 812
 813     *b* cannot be **0**.
 814
 815     *a* and *b* are consumed; they cannot be used after the call. See the
 816     **Consumption and Propagation** subsection below.
 817
 818     *a* and *b* can be the same number.
 819
 820     bcl(3) will encode an error in the return value, if there was one. The error
 821     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 822
 823     * **BCL_ERROR_INVALID_NUM**
 824     * **BCL_ERROR_INVALID_CONTEXT**
 825     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 826     * **BCL_ERROR_FATAL_ALLOC_ERR**
 827
 828 **BclNumber bcl_mod_keep(BclNumber** _a_**, BclNumber** _b_**)**
 829
 830 :   Divides *a* by *b* to the *scale* of the current context, computes the
 831     modulus **a-(a/b)\*b**, and returns the modulus.
 832
 833     *b* cannot be **0**.
 834
 835     *a* and *b* can be the same number.
 836
 837     bcl(3) will encode an error in the return value, if there was one. The error
 838     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 839
 840     * **BCL_ERROR_INVALID_NUM**
 841     * **BCL_ERROR_INVALID_CONTEXT**
 842     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 843     * **BCL_ERROR_FATAL_ALLOC_ERR**
 844
 845 **BclNumber bcl_pow(BclNumber** _a_**, BclNumber** _b_**)**
 846
 847 :   Calculates *a* to the power of *b* to the *scale* of the current context.
 848     *b* must be an integer, but can be negative. If it is negative, *a* must
 849     be non-zero.
 850
 851     *b* must be an integer. If *b* is negative, *a* must not be **0**.
 852
 853     *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section.
 854
 855     *a* and *b* are consumed; they cannot be used after the call. See the
 856     **Consumption and Propagation** subsection below.
 857
 858     *a* and *b* can be the same number.
 859
 860     bcl(3) will encode an error in the return value, if there was one. The error
 861     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 862
 863     * **BCL_ERROR_INVALID_NUM**
 864     * **BCL_ERROR_INVALID_CONTEXT**
 865     * **BCL_ERROR_MATH_NON_INTEGER**
 866     * **BCL_ERROR_MATH_OVERFLOW**
 867     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 868     * **BCL_ERROR_FATAL_ALLOC_ERR**
 869
 870 **BclNumber bcl_pow_keep(BclNumber** _a_**, BclNumber** _b_**)**
 871
 872 :   Calculates *a* to the power of *b* to the *scale* of the current context.
 873     *b* must be an integer, but can be negative. If it is negative, *a* must
 874     be non-zero.
 875
 876     *b* must be an integer. If *b* is negative, *a* must not be **0**.
 877
 878     *a* must be smaller than **BC_OVERFLOW_MAX**. See the **LIMITS** section.
 879
 880     *a* and *b* can be the same number.
 881
 882     bcl(3) will encode an error in the return value, if there was one. The error
 883     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 884
 885     * **BCL_ERROR_INVALID_NUM**
 886     * **BCL_ERROR_INVALID_CONTEXT**
 887     * **BCL_ERROR_MATH_NON_INTEGER**
 888     * **BCL_ERROR_MATH_OVERFLOW**
 889     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
 890     * **BCL_ERROR_FATAL_ALLOC_ERR**
 891
 892 **BclNumber bcl_lshift(BclNumber** _a_**, BclNumber** _b_**)**
 893
 894 :   Shifts *a* left (moves the radix right) by *b* places and returns the
 895     result. This is done in decimal. *b* must be an integer.
 896
 897     *b* must be an integer.
 898
 899     *a* and *b* are consumed; they cannot be used after the call. See the
 900     **Consumption and Propagation** subsection below.
 901
 902     *a* and *b* can be the same number.
 903
 904     bcl(3) will encode an error in the return value, if there was one. The error
 905     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 906
 907     * **BCL_ERROR_INVALID_NUM**
 908     * **BCL_ERROR_INVALID_CONTEXT**
 909     * **BCL_ERROR_MATH_NON_INTEGER**
 910     * **BCL_ERROR_FATAL_ALLOC_ERR**
 911
 912 **BclNumber bcl_lshift_keep(BclNumber** _a_**, BclNumber** _b_**)**
 913
 914 :   Shifts *a* left (moves the radix right) by *b* places and returns the
 915     result. This is done in decimal. *b* must be an integer.
 916
 917     *b* must be an integer.
 918
 919     *a* and *b* can be the same number.
 920
 921     bcl(3) will encode an error in the return value, if there was one. The error
 922     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 923
 924     * **BCL_ERROR_INVALID_NUM**
 925     * **BCL_ERROR_INVALID_CONTEXT**
 926     * **BCL_ERROR_MATH_NON_INTEGER**
 927     * **BCL_ERROR_FATAL_ALLOC_ERR**
 928
 929 **BclNumber bcl_rshift(BclNumber** _a_**, BclNumber** _b_**)**
 930
 931 :   Shifts *a* right (moves the radix left) by *b* places and returns the
 932     result. This is done in decimal. *b* must be an integer.
 933
 934     *b* must be an integer.
 935
 936     *a* and *b* are consumed; they cannot be used after the call. See the
 937     **Consumption and Propagation** subsection below.
 938
 939     *a* and *b* can be the same number.
 940
 941     bcl(3) will encode an error in the return value, if there was one. The error
 942     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 943
 944     * **BCL_ERROR_INVALID_NUM**
 945     * **BCL_ERROR_INVALID_CONTEXT**
 946     * **BCL_ERROR_MATH_NON_INTEGER**
 947     * **BCL_ERROR_FATAL_ALLOC_ERR**
 948
 949 **BclNumber bcl_rshift_keep(BclNumber** _a_**, BclNumber** _b_**)**
 950
 951 :   Shifts *a* right (moves the radix left) by *b* places and returns the
 952     result. This is done in decimal. *b* must be an integer.
 953
 954     *b* must be an integer.
 955
 956     *a* and *b* can be the same number.
 957
 958     bcl(3) will encode an error in the return value, if there was one. The error
 959     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 960
 961     * **BCL_ERROR_INVALID_NUM**
 962     * **BCL_ERROR_INVALID_CONTEXT**
 963     * **BCL_ERROR_MATH_NON_INTEGER**
 964     * **BCL_ERROR_FATAL_ALLOC_ERR**
 965
 966 **BclNumber bcl_sqrt(BclNumber** _a_**)**
 967
 968 :   Calculates the square root of *a* and returns the result. The *scale* of the
 969     result is equal to the **scale** of the current context.
 970
 971     *a* cannot be negative.
 972
 973     *a* is consumed; it cannot be used after the call. See the
 974     **Consumption and Propagation** subsection below.
 975
 976     bcl(3) will encode an error in the return value, if there was one. The error
 977     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 978
 979     * **BCL_ERROR_INVALID_NUM**
 980     * **BCL_ERROR_INVALID_CONTEXT**
 981     * **BCL_ERROR_MATH_NEGATIVE**
 982     * **BCL_ERROR_FATAL_ALLOC_ERR**
 983
 984 **BclNumber bcl_sqrt_keep(BclNumber** _a_**)**
 985
 986 :   Calculates the square root of *a* and returns the result. The *scale* of the
 987     result is equal to the **scale** of the current context.
 988
 989     *a* cannot be negative.
 990
 991     bcl(3) will encode an error in the return value, if there was one. The error
 992     can be queried with **bcl_err(BclNumber)**. Possible errors include:
 993
 994     * **BCL_ERROR_INVALID_NUM**
 995     * **BCL_ERROR_INVALID_CONTEXT**
 996     * **BCL_ERROR_MATH_NEGATIVE**
 997     * **BCL_ERROR_FATAL_ALLOC_ERR**
 998
 999 **BclError bcl_divmod(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**)**
1000
1001 :   Divides *a* by *b* and returns the quotient in a new number which is put
1002     into the space pointed to by *c*, and puts the modulus in a new number which
1003     is put into the space pointed to by *d*.
1004
1005     *b* cannot be **0**.
1006
1007     *a* and *b* are consumed; they cannot be used after the call. See the
1008     **Consumption and Propagation** subsection below.
1009
1010     *c* and *d* cannot point to the same place, nor can they point to the space
1011     occupied by *a* or *b*.
1012
1013     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
1014     function can return:
1015
1016     * **BCL_ERROR_INVALID_NUM**
1017     * **BCL_ERROR_INVALID_CONTEXT**
1018     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
1019     * **BCL_ERROR_FATAL_ALLOC_ERR**
1020
1021 **BclError bcl_divmod_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber \***_c_**, BclNumber \***_d_**)**
1022
1023 :   Divides *a* by *b* and returns the quotient in a new number which is put
1024     into the space pointed to by *c*, and puts the modulus in a new number which
1025     is put into the space pointed to by *d*.
1026
1027     *b* cannot be **0**.
1028
1029     *c* and *d* cannot point to the same place, nor can they point to the space
1030     occupied by *a* or *b*.
1031
1032     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
1033     function can return:
1034
1035     * **BCL_ERROR_INVALID_NUM**
1036     * **BCL_ERROR_INVALID_CONTEXT**
1037     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
1038     * **BCL_ERROR_FATAL_ALLOC_ERR**
1039
1040 **BclNumber bcl_modexp(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**)**
1041
1042 :   Computes a modular exponentiation where *a* is the base, *b* is the
1043     exponent, and *c* is the modulus, and returns the result. The *scale* of the
1044     result is equal to the **scale** of the current context.
1045
1046     *a*, *b*, and *c* must be integers. *c* must not be **0**. *b* must not be
1047     negative.
1048
1049     *a*, *b*, and *c* are consumed; they cannot be used after the call. See the
1050     **Consumption and Propagation** subsection below.
1051
1052     bcl(3) will encode an error in the return value, if there was one. The error
1053     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1054
1055     * **BCL_ERROR_INVALID_NUM**
1056     * **BCL_ERROR_INVALID_CONTEXT**
1057     * **BCL_ERROR_MATH_NEGATIVE**
1058     * **BCL_ERROR_MATH_NON_INTEGER**
1059     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
1060     * **BCL_ERROR_FATAL_ALLOC_ERR**
1061
1062 **BclNumber bcl_modexp_keep(BclNumber** _a_**, BclNumber** _b_**, BclNumber** _c_**)**
1063
1064 :   Computes a modular exponentiation where *a* is the base, *b* is the
1065     exponent, and *c* is the modulus, and returns the result. The *scale* of the
1066     result is equal to the **scale** of the current context.
1067
1068     *a*, *b*, and *c* must be integers. *c* must not be **0**. *b* must not be
1069     negative.
1070
1071     bcl(3) will encode an error in the return value, if there was one. The error
1072     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1073
1074     * **BCL_ERROR_INVALID_NUM**
1075     * **BCL_ERROR_INVALID_CONTEXT**
1076     * **BCL_ERROR_MATH_NEGATIVE**
1077     * **BCL_ERROR_MATH_NON_INTEGER**
1078     * **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
1079     * **BCL_ERROR_FATAL_ALLOC_ERR**
1080
1081 ## Miscellaneous
1082
1083 **void bcl_zero(BclNumber** _n_**)**
1084
1085 :   Sets *n* to **0**.
1086
1087 **void bcl_one(BclNumber** _n_**)**
1088
1089 :   Sets *n* to **1**.
1090
1091 **ssize_t bcl_cmp(BclNumber** _a_**, BclNumber** _b_**)**
1092
1093 :   Compares *a* and *b* and returns **0** if *a* and *b* are equal, **<0** if
1094     *a* is less than *b*, and **>0** if *a* is greater than *b*.
1095
1096 **BclError bcl_copy(BclNumber** _d_**, BclNumber** _s_**)**
1097
1098 :   Copies *s* into *d*.
1099
1100     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
1101     function can return:
1102
1103     * **BCL_ERROR_INVALID_NUM**
1104     * **BCL_ERROR_INVALID_CONTEXT**
1105     * **BCL_ERROR_FATAL_ALLOC_ERR**
1106
1107 **BclNumber bcl_dup(BclNumber** _s_**)**
1108
1109 :   Creates and returns a new **BclNumber** that is a copy of *s*.
1110
1111     bcl(3) will encode an error in the return value, if there was one. The error
1112     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1113
1114     * **BCL_ERROR_INVALID_NUM**
1115     * **BCL_ERROR_INVALID_CONTEXT**
1116     * **BCL_ERROR_FATAL_ALLOC_ERR**
1117
1118 ## Pseudo-Random Number Generator
1119
1120 The pseudo-random number generator in bcl(3) is a *seeded* PRNG. Given the same
1121 seed twice, it will produce the same sequence of pseudo-random numbers twice.
1122
1123 By default, bcl(3) attempts to seed the PRNG with data from **/dev/urandom**. If
1124 that fails, it seeds itself with by calling **libc**'s **srand(time(NULL))** and
1125 then calling **rand()** for each byte, since **rand()** is only guaranteed to
1126 return **15** bits.
1127
1128 This should provide fairly good seeding in the standard case while also
1129 remaining fairly portable.
1130
1131 If necessary, the PRNG can be reseeded with one of the following functions:
1132
1133 * **bcl_rand_seedWithNum(BclNumber)**
1134 * **bcl_rand_seed(unsigned char[**_BCL_SEED_SIZE_**])**
1135 * **bcl_rand_reseed(**_void_**)**
1136
1137 All procedures in this section without the **_keep** suffix in their name
1138 consume the given **BclNumber** arguments that are not given to pointer
1139 arguments. See the **Consumption and Propagation** subsection below.
1140
1141 The following items allow clients to use the pseudo-random number generator. All
1142 procedures require a valid current context.
1143
1144 **BCL_SEED_ULONGS**
1145
1146 :   The number of **unsigned long**'s in a seed for bcl(3)'s random number
1147     generator.
1148
1149 **BCL_SEED_SIZE**
1150
1151 :   The size, in **char**'s, of a seed for bcl(3)'s random number generator.
1152
1153 **BclBigDig**
1154
1155 :   bcl(3)'s overflow type (see the **PERFORMANCE** section).
1156
1157 **BclRandInt**
1158
1159 :   An unsigned integer type returned by bcl(3)'s random number generator.
1160
1161 **BclNumber bcl_irand(BclNumber** _a_**)**
1162
1163 :   Returns a random number that is not larger than *a* in a new number. If *a*
1164     is **0** or **1**, the new number is equal to **0**. The bound is unlimited,
1165     so it is not bound to the size of **BclRandInt**. This is done by generating
1166     as many random numbers as necessary, multiplying them by certain exponents,
1167     and adding them all together.
1168
1169     *a* must be an integer and non-negative.
1170
1171     *a* is consumed; it cannot be used after the call. See the **Consumption and
1172     Propagation** subsection below.
1173
1174     This procedure requires a valid current context.
1175
1176     bcl(3) will encode an error in the return value, if there was one. The error
1177     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1178
1179     * **BCL_ERROR_INVALID_NUM**
1180     * **BCL_ERROR_INVALID_CONTEXT**
1181     * **BCL_ERROR_MATH_NEGATIVE**
1182     * **BCL_ERROR_MATH_NON_INTEGER**
1183     * **BCL_ERROR_FATAL_ALLOC_ERR**
1184
1185 **BclNumber bcl_irand_keep(BclNumber** _a_**)**
1186
1187 :   Returns a random number that is not larger than *a* in a new number. If *a*
1188     is **0** or **1**, the new number is equal to **0**. The bound is unlimited,
1189     so it is not bound to the size of **BclRandInt**. This is done by generating
1190     as many random numbers as necessary, multiplying them by certain exponents,
1191     and adding them all together.
1192
1193     *a* must be an integer and non-negative.
1194
1195     This procedure requires a valid current context.
1196
1197     bcl(3) will encode an error in the return value, if there was one. The error
1198     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1199
1200     * **BCL_ERROR_INVALID_NUM**
1201     * **BCL_ERROR_INVALID_CONTEXT**
1202     * **BCL_ERROR_MATH_NEGATIVE**
1203     * **BCL_ERROR_MATH_NON_INTEGER**
1204     * **BCL_ERROR_FATAL_ALLOC_ERR**
1205
1206 **BclNumber bcl_frand(size_t** _places_**)**
1207
1208 :   Returns a random number between **0** (inclusive) and **1** (exclusive) that
1209     has *places* decimal digits after the radix (decimal point). There are no
1210     limits on *places*.
1211
1212     This procedure requires a valid current context.
1213
1214     bcl(3) will encode an error in the return value, if there was one. The error
1215     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1216
1217     * **BCL_ERROR_INVALID_CONTEXT**
1218     * **BCL_ERROR_FATAL_ALLOC_ERR**
1219
1220 **BclNumber bcl_ifrand(BclNumber** _a_**, size_t** _places_**)**
1221
1222 :   Returns a random number less than *a* with *places* decimal digits after the
1223     radix (decimal point). There are no limits on *a* or *places*.
1224
1225     *a* must be an integer and non-negative.
1226
1227     *a* is consumed; it cannot be used after the call. See the **Consumption and
1228     Propagation** subsection below.
1229
1230     This procedure requires a valid current context.
1231
1232     bcl(3) will encode an error in the return value, if there was one. The error
1233     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1234
1235     * **BCL_ERROR_INVALID_NUM**
1236     * **BCL_ERROR_INVALID_CONTEXT**
1237     * **BCL_ERROR_MATH_NEGATIVE**
1238     * **BCL_ERROR_MATH_NON_INTEGER**
1239     * **BCL_ERROR_FATAL_ALLOC_ERR**
1240
1241 **BclNumber bcl_ifrand_keep(BclNumber** _a_**, size_t** _places_**)**
1242
1243 :   Returns a random number less than *a* with *places* decimal digits after the
1244     radix (decimal point). There are no limits on *a* or *places*.
1245
1246     *a* must be an integer and non-negative.
1247
1248     This procedure requires a valid current context.
1249
1250     bcl(3) will encode an error in the return value, if there was one. The error
1251     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1252
1253     * **BCL_ERROR_INVALID_NUM**
1254     * **BCL_ERROR_INVALID_CONTEXT**
1255     * **BCL_ERROR_MATH_NEGATIVE**
1256     * **BCL_ERROR_MATH_NON_INTEGER**
1257     * **BCL_ERROR_FATAL_ALLOC_ERR**
1258
1259 **BclError bcl_rand_seedWithNum(BclNumber** _n_**)**
1260
1261 :   Seeds the PRNG with *n*.
1262
1263     *n* is consumed.
1264
1265     This procedure requires a valid current context.
1266
1267     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
1268     function can return:
1269
1270     * **BCL_ERROR_INVALID_NUM**
1271     * **BCL_ERROR_INVALID_CONTEXT**
1272
1273     Note that if **bcl_rand_seed2num(**_void_**)** or
1274     **bcl_rand_seed2num_err(BclNumber)** are called right after this function,
1275     they are not guaranteed to return a number equal to *n*.
1276
1277 **BclError bcl_rand_seedWithNum_keep(BclNumber** _n_**)**
1278
1279 :   Seeds the PRNG with *n*.
1280
1281     This procedure requires a valid current context.
1282
1283     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
1284     function can return:
1285
1286     * **BCL_ERROR_INVALID_NUM**
1287     * **BCL_ERROR_INVALID_CONTEXT**
1288
1289     Note that if **bcl_rand_seed2num(**_void_**)** or
1290     **bcl_rand_seed2num_err(BclNumber)** are called right after this function,
1291     they are not guaranteed to return a number equal to *n*.
1292
1293 **BclError bcl_rand_seed(unsigned char** _seed_**[**_BCL_SEED_SIZE_**])**
1294
1295 :   Seeds the PRNG with the bytes in *seed*.
1296
1297     If there was no error, **BCL_ERROR_NONE** is returned. Otherwise, this
1298     function can return:
1299
1300     * **BCL_ERROR_INVALID_CONTEXT**
1301
1302 **void bcl_rand_reseed(**_void_**)**
1303
1304 :   Reseeds the PRNG with the default reseeding behavior. First, it attempts to
1305     read data from **/dev/urandom** and falls back to **libc**'s **rand()**.
1306
1307     This procedure cannot fail.
1308
1309 **BclNumber bcl_rand_seed2num(**_void_**)**
1310
1311 :   Returns the current seed of the PRNG as a **BclNumber**.
1312
1313     This procedure requires a valid current context.
1314
1315     bcl(3) will encode an error in the return value, if there was one. The error
1316     can be queried with **bcl_err(BclNumber)**. Possible errors include:
1317
1318     * **BCL_ERROR_INVALID_CONTEXT**
1319     * **BCL_ERROR_FATAL_ALLOC_ERR**
1320
1321 **BclRandInt bcl_rand_int(**_void_**)**
1322
1323 :   Returns a random integer between **0** and **BC_RAND_MAX** (inclusive).
1324
1325     This procedure cannot fail.
1326
1327 **BclRandInt bcl_rand_bounded(BclRandInt** _bound_**)**
1328
1329 :   Returns a random integer between **0** and *bound* (exclusive). Bias is
1330     removed before returning the integer.
1331
1332     This procedure cannot fail.
1333
1334 ## Consumption and Propagation
1335
1336 Some functions are listed as consuming some or all of their arguments. This
1337 means that the arguments are freed, regardless of if there were errors or not.
1338
1339 This is to enable compact code like the following:
1340
1341     BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d));
1342
1343 If arguments to those functions were not consumed, memory would be leaked until
1344 reclaimed with **bcl_ctxt_freeNums(BclContext)**.
1345
1346 When errors occur, they are propagated through. The result should always be
1347 checked with **bcl_err(BclNumber)**, so the example above should properly
1348 be:
1349
1350     BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d));
1351     if (bcl_err(n) != BCL_ERROR_NONE) {
1352         // Handle the error.
1353     }
1354
1355 # ERRORS
1356
1357 Most functions in bcl(3) return, directly or indirectly, any one of the error
1358 codes defined in **BclError**. The complete list of codes is the following:
1359
1360 **BCL_ERROR_NONE**
1361
1362 :   Success; no error occurred.
1363
1364 **BCL_ERROR_INVALID_NUM**
1365
1366 :   An invalid **BclNumber** was given as a parameter.
1367
1368 **BCL_ERROR_INVALID_CONTEXT**
1369
1370 :   An invalid **BclContext** is being used.
1371
1372 **BCL_ERROR_MATH_NEGATIVE**
1373
1374 :   A negative number was given as an argument to a parameter that cannot accept
1375     negative numbers, such as for square roots.
1376
1377 **BCL_ERROR_MATH_NON_INTEGER**
1378
1379 :   A non-integer was given as an argument to a parameter that cannot accept
1380     non-integer numbers, such as for the second parameter of **bcl_num_pow()**.
1381
1382 **BCL_ERROR_MATH_OVERFLOW**
1383
1384 :   A number that would overflow its result was given as an argument, such as
1385     for converting a **BclNumber** to a **BclBigDig**.
1386
1387 **BCL_ERROR_MATH_DIVIDE_BY_ZERO**
1388
1389 :   A divide by zero occurred.
1390
1391 **BCL_ERROR_PARSE_INVALID_STR**
1392
1393 :   An invalid number string was passed to a parsing function.
1394
1395     A valid number string can only be one radix (period). In addition, any
1396     lowercase ASCII letters, symbols, or non-ASCII characters are invalid. It is
1397     allowed for the first character to be a dash. In that case, the number is
1398     considered to be negative.
1399
1400     There is one exception to the above: one lowercase **e** is allowed in the
1401     number, after the radix, if it exists. If the letter **e** exists, the
1402     number is considered to be in scientific notation, where the part before the
1403     **e** is the number, and the part after, which must be an integer, is the
1404     exponent. There can be a dash right after the **e** to indicate a negative
1405     exponent.
1406
1407     **WARNING**: Both the number and the exponent in scientific notation are
1408     interpreted according to the current **ibase**, but the number is still
1409     multiplied by **10\^exponent** regardless of the current **ibase**. For
1410     example, if **ibase** is **16** and bcl(3) is given the number string
1411     **FFeA**, the resulting decimal number will be **2550000000000**, and if
1412     bcl(3) is given the number string **10e-4**, the resulting decimal number
1413     will be **0.0016**.
1414
1415 **BCL_ERROR_FATAL_ALLOC_ERR**
1416
1417 :   bcl(3) failed to allocate memory.
1418
1419     If clients call **bcl_setAbortOnFatalError()** with an **true** argument,
1420     this error will cause bcl(3) to throw a **SIGABRT**. This behavior can also
1421     be turned off later by calling that same function with a **false** argument.
1422     By default, this behavior is off.
1423
1424     It is highly recommended that client libraries do *not* activate this
1425     behavior.
1426
1427 **BCL_ERROR_FATAL_UNKNOWN_ERR**
1428
1429 :   An unknown error occurred.
1430
1431     If clients call **bcl_setAbortOnFatalError()** with an **true** argument,
1432     this error will cause bcl(3) to throw a **SIGABRT**. This behavior can also
1433     be turned off later by calling that same function with a **false** argument.
1434     By default, this behavior is off.
1435
1436     It is highly recommended that client libraries do *not* activate this
1437     behavior.
1438
1439 # ATTRIBUTES
1440
1441 bcl(3) is *MT-Safe*: it is safe to call any functions from more than one thread.
1442 However, is is *not* safe to pass any data between threads except for strings
1443 returned by **bcl_string()**.
1444
1445 bcl(3) is not *async-signal-safe*. It was not possible to make bcl(3) safe with
1446 signals and also make it safe with multiple threads. If it is necessary to be
1447 able to interrupt bcl(3), spawn a separate thread to run the calculation.
1448
1449 # PERFORMANCE
1450
1451 Most bc(1) implementations use **char** types to calculate the value of **1**
1452 decimal digit at a time, but that can be slow. bcl(3) does something
1453 different.
1454
1455 It uses large integers to calculate more than **1** decimal digit at a time. If
1456 built in a environment where **BC_LONG_BIT** (see the **LIMITS** section) is
1457 **64**, then each integer has **9** decimal digits. If built in an environment
1458 where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This
1459 value (the number of decimal digits per large integer) is called
1460 **BC_BASE_DIGS**.
1461
1462 In addition, this bcl(3) uses an even larger integer for overflow checking. This
1463 integer type depends on the value of **BC_LONG_BIT**, but is always at least
1464 twice as large as the integer type used to store digits.
1465
1466 # LIMITS
1467
1468 The following are the limits on bcl(3):
1469
1470 **BC_LONG_BIT**
1471
1472 :   The number of bits in the **long** type in the environment where bcl(3) was
1473     built. This determines how many decimal digits can be stored in a single
1474     large integer (see the **PERFORMANCE** section).
1475
1476 **BC_BASE_DIGS**
1477
1478 :   The number of decimal digits per large integer (see the **PERFORMANCE**
1479     section). Depends on **BC_LONG_BIT**.
1480
1481 **BC_BASE_POW**
1482
1483 :   The max decimal number that each large integer can store (see
1484     **BC_BASE_DIGS**) plus **1**. Depends on **BC_BASE_DIGS**.
1485
1486 **BC_OVERFLOW_MAX**
1487
1488 :   The max number that the overflow type (see the **PERFORMANCE** section) can
1489     hold. Depends on **BC_LONG_BIT**.
1490
1491 **BC_BASE_MAX**
1492
1493 :   The maximum output base. Set at **BC_BASE_POW**.
1494
1495 **BC_SCALE_MAX**
1496
1497 :   The maximum **scale**. Set at **BC_OVERFLOW_MAX-1**.
1498
1499 **BC_NUM_MAX**
1500
1501 :   The maximum length of a number (in decimal digits), which includes digits
1502     after the decimal point. Set at **BC_OVERFLOW_MAX-1**.
1503
1504 **BC_RAND_MAX**
1505
1506 :   The maximum integer (inclusive) returned by the **bcl_rand_int()** function.
1507     Set at **2\^BC_LONG_BIT-1**.
1508
1509 Exponent
1510
1511 :   The maximum allowable exponent (positive or negative). Set at
1512     **BC_OVERFLOW_MAX**.
1513
1514 These limits are meant to be effectively non-existent; the limits are so large
1515 (at least on 64-bit machines) that there should not be any point at which they
1516 become a problem. In fact, memory should be exhausted before these limits should
1517 be hit.
1518
1519 # SEE ALSO
1520
1521 bc(1) and dc(1)
1522
1523 # STANDARDS
1524
1525 bcl(3) is compliant with the arithmetic defined in the IEEE Std 1003.1-2017
1526 (“POSIX.1-2017”) specification at
1527 https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for bc(1).
1528
1529 Note that the specification explicitly says that bc(1) only accepts numbers that
1530 use a period (**.**) as a radix point, regardless of the value of
1531 **LC_NUMERIC**. This is also true of bcl(3).
1532
1533 # BUGS
1534
1535 None are known. Report bugs at https://git.gavinhoward.com/gavin/bc.
1536
1537 # AUTHORS
1538
1539 Gavin D. Howard <gavin@gavinhoward.com> and contributors.