contrib/bc/manuals/bcl.3

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