contrib/bc/manuals/bcl.3

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