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