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