1<!--- 2 3SPDX-License-Identifier: BSD-2-Clause 4 5Copyright (c) 2018-2024 Gavin D. Howard and contributors. 6 7Redistribution and use in source and binary forms, with or without 8modification, 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 17THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 18AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 19IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 20ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 21LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27POSSIBILITY OF SUCH DAMAGE. 28 29--> 30 31# NAME 32 33bcl - library of arbitrary precision decimal arithmetic 34 35# SYNOPSIS 36 37## Use 38 39*#include <bcl.h>* 40 41Link with *-lbcl*, and on POSIX systems, *-lpthread* is also required. 42 43## Setup 44 45These 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 71These items will allow clients to handle contexts, which are isolated from each 72other. 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 104These items allow clients to handle errors. 105 106**typedef enum BclError BclError;** 107 108**BclError bcl_err(BclNumber** _n_**);** 109 110## Numbers 111 112These items allow clients to manipulate and query the arbitrary-precision 113numbers 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 133These 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 149These 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 197These 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 211These items allow clients to manipulate the seeded pseudo-random number 212generator 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 248bcl(3) is a library that implements arbitrary-precision decimal math, as 249standardized by POSIX 250(https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html) in bc(1). 251 252bcl(3) assumes that it is allowed to use the **bcl**, **Bcl**, **bc**, and 253**Bc** prefixes for symbol names without collision. 254 255All of the items in its interface are described below. See the documentation for 256each 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 400All procedures that take a **BclContext** parameter a require a valid context as 401an 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 524All 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 581All procedures in this section require a valid current context. 582 583All procedures in this section without the **_keep** suffix in their name 584consume the given **BclNumber** arguments that are not given to pointer 585arguments. 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 662All procedures in this section require a valid current context. 663 664All procedures in this section without the **_keep** suffix in their name 665consume the given **BclNumber** arguments that are not given to pointer 666arguments. See the **Consumption and Propagation** subsection below. 667 668All 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 1120The pseudo-random number generator in bcl(3) is a *seeded* PRNG. Given the same 1121seed twice, it will produce the same sequence of pseudo-random numbers twice. 1122 1123By default, bcl(3) attempts to seed the PRNG with data from **/dev/urandom**. If 1124that fails, it seeds itself with by calling **libc**'s **srand(time(NULL))** and 1125then calling **rand()** for each byte, since **rand()** is only guaranteed to 1126return **15** bits. 1127 1128This should provide fairly good seeding in the standard case while also 1129remaining fairly portable. 1130 1131If 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 1137All procedures in this section without the **_keep** suffix in their name 1138consume the given **BclNumber** arguments that are not given to pointer 1139arguments. See the **Consumption and Propagation** subsection below. 1140 1141The following items allow clients to use the pseudo-random number generator. All 1142procedures 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 1336Some functions are listed as consuming some or all of their arguments. This 1337means that the arguments are freed, regardless of if there were errors or not. 1338 1339This 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 1343If arguments to those functions were not consumed, memory would be leaked until 1344reclaimed with **bcl_ctxt_freeNums(BclContext)**. 1345 1346When errors occur, they are propagated through. The result should always be 1347checked with **bcl_err(BclNumber)**, so the example above should properly 1348be: 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 1357Most functions in bcl(3) return, directly or indirectly, any one of the error 1358codes 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 1441bcl(3) is *MT-Safe*: it is safe to call any functions from more than one thread. 1442However, is is *not* safe to pass any data between threads except for strings 1443returned by **bcl_string()**. 1444 1445bcl(3) is not *async-signal-safe*. It was not possible to make bcl(3) safe with 1446signals and also make it safe with multiple threads. If it is necessary to be 1447able to interrupt bcl(3), spawn a separate thread to run the calculation. 1448 1449# PERFORMANCE 1450 1451Most bc(1) implementations use **char** types to calculate the value of **1** 1452decimal digit at a time, but that can be slow. bcl(3) does something 1453different. 1454 1455It uses large integers to calculate more than **1** decimal digit at a time. If 1456built 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 1458where **BC_LONG_BIT** is **32** then each integer has **4** decimal digits. This 1459value (the number of decimal digits per large integer) is called 1460**BC_BASE_DIGS**. 1461 1462In addition, this bcl(3) uses an even larger integer for overflow checking. This 1463integer type depends on the value of **BC_LONG_BIT**, but is always at least 1464twice as large as the integer type used to store digits. 1465 1466# LIMITS 1467 1468The 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 1509Exponent 1510 1511: The maximum allowable exponent (positive or negative). Set at 1512 **BC_OVERFLOW_MAX**. 1513 1514These 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 1516become a problem. In fact, memory should be exhausted before these limits should 1517be hit. 1518 1519# SEE ALSO 1520 1521bc(1) and dc(1) 1522 1523# STANDARDS 1524 1525bcl(3) is compliant with the arithmetic defined in the IEEE Std 1003.1-2017 1526(“POSIX.1-2017”) specification at 1527https://pubs.opengroup.org/onlinepubs/9699919799/utilities/bc.html for bc(1). 1528 1529Note that the specification explicitly says that bc(1) only accepts numbers that 1530use 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 1535None are known. Report bugs at https://git.gavinhoward.com/gavin/bc. 1536 1537# AUTHORS 1538 1539Gavin D. Howard <gavin@gavinhoward.com> and contributors. 1540