Use

Link with -lbcl.

Signals

void bcl_handleSignal(void);

bool bcl_running(void);

Setup

BclError bcl_init(void);

void bcl_free(void);

bool bcl_abortOnFatalError(void);

void bcl_setAbortOnFatalError(bool abrt);

bool bcl_leadingZeroes(void);

void bcl_setLeadingZeroes(bool leadingZeroes);

void bcl_gc(void);

Contexts

struct BclCtxt;

typedef struct BclCtxt* BclContext;

BclContext bcl_ctxt_create(void);

void bcl_ctxt_free(BclContext ctxt);

BclError bcl_pushContext(BclContext ctxt);

void bcl_popContext(void);

BclContext bcl_context(void);

void bcl_ctxt_freeNums(BclContext ctxt);

size_t bcl_ctxt_scale(BclContext ctxt);

void bcl_ctxt_setScale(BclContext ctxt, size_t scale);

size_t bcl_ctxt_ibase(BclContext ctxt);

void bcl_ctxt_setIbase(BclContext ctxt, size_t ibase);

size_t bcl_ctxt_obase(BclContext ctxt);

void bcl_ctxt_setObase(BclContext ctxt, size_t obase);

Errors

typedef enum BclError BclError;

BclError bcl_err(BclNumber n);

Numbers

typedef struct { size_t i; } BclNumber;

BclNumber bcl_num_create(void);

void bcl_num_free(BclNumber n);

bool bcl_num_neg(BclNumber n);

void bcl_num_setNeg(BclNumber n, bool neg);

size_t bcl_num_scale(BclNumber n);

BclError bcl_num_setScale(BclNumber n, size_t scale);

size_t bcl_num_len(BclNumber n);

Conversion

BclNumber bcl_parse(const char *restrict val);

char* bcl_string(BclNumber n);

BclError bcl_bigdig(BclNumber n, BclBigDig *result);

BclNumber bcl_bigdig2num(BclBigDig val);

Math

BclNumber bcl_add(BclNumber a, BclNumber b);

BclNumber bcl_sub(BclNumber a, BclNumber b);

BclNumber bcl_mul(BclNumber a, BclNumber b);

BclNumber bcl_div(BclNumber a, BclNumber b);

BclNumber bcl_mod(BclNumber a, BclNumber b);

BclNumber bcl_pow(BclNumber a, BclNumber b);

BclNumber bcl_lshift(BclNumber a, BclNumber b);

BclNumber bcl_rshift(BclNumber a, BclNumber b);

BclNumber bcl_sqrt(BclNumber a);

BclError bcl_divmod(BclNumber a, BclNumber b, BclNumber *c, BclNumber *d);

BclNumber bcl_modexp(BclNumber a, BclNumber b, BclNumber c);

Miscellaneous

void bcl_zero(BclNumber n);

void bcl_one(BclNumber n);

ssize_t bcl_cmp(BclNumber a, BclNumber b);

BclError bcl_copy(BclNumber d, BclNumber s);

BclNumber bcl_dup(BclNumber s);

Pseudo-Random Number Generator

#define BCL_SEED_ULONGS

#define BCL_SEED_SIZE

typedef unsigned long BclBigDig;

typedef unsigned long BclRandInt;

BclNumber bcl_irand(BclNumber a);

BclNumber bcl_frand(size_t places);

BclNumber bcl_ifrand(BclNumber a, size_t places);

BclError bcl_rand_seedWithNum(BclNumber n);

BclError bcl_rand_seed(unsigned char seed[BCL_SEED_SIZE]);

void bcl_rand_reseed(void);

BclNumber bcl_rand_seed2num(void);

BclRandInt bcl_rand_int(void);

BclRandInt bcl_rand_bounded(BclRandInt bound);

Signals

void bcl_handleSignal(void)

An async-signal-safe function that can be called from a signal handler. If called from a signal handler on the same thread as any executing bcl(3) functions, it will interrupt the functions and force them to return early. It is undefined behavior if this function is called from a thread that is not executing any bcl(3) functions while any bcl(3) functions are executing.

bool bcl_running(void)

An async-signal-safe function that can be called from a signal handler. It will return true if any bcl(3) procedures are running, which means it is safe to call bcl_handleSignal(void). Otherwise, it returns false.

Setup

BclError bcl_init(void)

Initializes this library. This function can be called multiple times, but each call must be matched by a call to bcl_free(void). This is to make it possible for multiple libraries and applications to initialize bcl(3) without problem.

void bcl_free(void)

Decrements bcl(3)’s reference count and frees the data associated with it if the reference count is 0.

bool bcl_abortOnFatalError(void)

Queries and returns the current state of calling abort() on fatal errors. If true is returned, bcl(3) will cause a SIGABRT if a fatal error occurs.

void bcl_setAbortOnFatalError(bool abrt)

Sets the state of calling abort() on fatal errors. If abrt is false, bcl(3) will not cause a SIGABRT on fatal errors after the call. If abrt is true, bcl(3) will cause a SIGABRT on fatal errors after the call.

bool bcl_leadingZeroes(void)

Queries and returns the state of whether leading zeroes are added to strings returned by bcl_string() when numbers are greater than -1, less than 1, and not equal to 0. If true is returned, then leading zeroes will be added.

void bcl_setLeadingZeroes(bool leadingZeroes)

Sets the state of whether leading zeroes are added to strings returned by bcl_string() when numbers are greater than -1, less than 1, and not equal to 0. If leadingZeroes is true, leading zeroes will be added to strings returned by bcl_string().

void bcl_gc(void)

Garbage collects cached instances of arbitrary-precision numbers. This only frees the memory of numbers that are not in use, so it is safe to call at any time.

Contexts

struct BclCtxt

A forward declaration for a hidden struct type. Clients cannot access the internals of the struct type directly. All interactions with the type are done through pointers. See BclContext below.

BclContext

A typedef to a pointer of struct BclCtxt. This is the only handle clients can get to struct BclCtxt.

BclContext bcl_ctxt_create(void)

Creates a context and returns it. Returns NULL if there was an error.

void bcl_ctxt_free(BclContext ctxt)

Frees ctxt, after which it is no longer valid. It is undefined behavior to attempt to use an invalid context.

BclError bcl_pushContext(BclContext ctxt)

Pushes ctxt onto bcl(3)’s stack of contexts. ctxt must have been created with bcl_ctxt_create(void).

void bcl_popContext(void)

Pops the current context off of the stack, if one exists.

BclContext bcl_context(void)

Returns the current context, or NULL if no context exists.

void bcl_ctxt_freeNums(BclContext ctxt)

Frees all numbers in use that are associated with ctxt. It is undefined behavior to attempt to use a number associated with ctxt after calling this procedure unless such numbers have been created with bcl_num_create(void) after calling this procedure.

size_t bcl_ctxt_scale(BclContext ctxt)

Returns the scale for given context.

void bcl_ctxt_setScale(BclContext ctxt, size_t scale)

Sets the scale for the given context to the argument scale.

size_t bcl_ctxt_ibase(BclContext ctxt)

Returns the ibase for the given context.

void bcl_ctxt_setIbase(BclContext ctxt, size_t ibase)

Sets the ibase for the given context to the argument ibase. If the argument ibase is invalid, it clamped, so an ibase of 0 or 1 is clamped to 2, and any values above 36 are clamped to 36.

size_t bcl_ctxt_obase(BclContext ctxt)

Returns the obase for the given context.

void bcl_ctxt_setObase(BclContext ctxt, size_t obase)

Sets the obase for the given context to the argument obase.

Errors

BclError

An enum of possible error codes. See the ERRORS section for a complete listing the codes.

BclError bcl_err(BclNumber n)

Checks for errors in a BclNumber. All functions that can return a BclNumber can encode an error in the number, and this function will return the error, if any. If there was no error, it will return BCL_ERROR_NONE.

Numbers

BclNumber

A handle to an arbitrary-precision number. The actual number type is not exposed; the BclNumber handle is the only way clients can refer to instances of arbitrary-precision numbers.

BclNumber bcl_num_create(void)

Creates and returns a BclNumber.

void bcl_num_free(BclNumber n)

Frees n. It is undefined behavior to use n after calling this function.

bool bcl_num_neg(BclNumber n)

Returns true if n is negative, false otherwise.

void bcl_num_setNeg(BclNumber n, bool neg)

Sets n’s sign to neg, where true is negative, and false is positive.

size_t bcl_num_scale(BclNumber n)

Returns the scale of n.

BclError bcl_num_setScale(BclNumber n, size_t scale)

Sets the scale of n to the argument scale. If the argument scale is greater than the scale of n, n is extended. If the argument scale is less than the scale of n, n is truncated.

size_t bcl_num_len(BclNumber n)

Returns the number of significant decimal digits in n.

Conversion

All procedures in this section consume the given BclNumber arguments that are not given to pointer arguments. See the Consumption and Propagation subsection below.

BclNumber bcl_parse(const char *restrict val)

Parses a number string according to the current context’s ibase and returns the resulting number.

char* bcl_string(BclNumber n)

Returns a string representation of n according the the current context’s ibase. The string is dynamically allocated and must be freed by the caller.

BclError bcl_bigdig(BclNumber n, BclBigDig *result)

Converts n into a BclBigDig and returns the result in the space pointed to by result.

BclNumber bcl_bigdig2num(BclBigDig val)

Creates a BclNumber from val.

Math

All procedures in this section can return the following errors:

•

BCL_ERROR_INVALID_NUM

•

BCL_ERROR_INVALID_CONTEXT

•

BCL_ERROR_FATAL_ALLOC_ERR

BclNumber bcl_add(BclNumber a, BclNumber b)

Adds a and b and returns the result. The scale of the result is the max of the scales of a and b.

BclNumber bcl_sub(BclNumber a, BclNumber b)

Subtracts b from a and returns the result. The scale of the result is the max of the scales of a and b.

BclNumber bcl_mul(BclNumber a, BclNumber b)

Multiplies a and b and returns the result. If ascale is the scale of a and bscale is the scale of b, the scale of the result is equal to min(ascale+bscale,max(scale,ascale,bscale)), where min() and max() return the obvious values.

BclNumber bcl_div(BclNumber a, BclNumber b)

Divides a by b and returns the result. The scale of the result is the scale of the current context.

BclNumber bcl_mod(BclNumber a, BclNumber b)

Divides a by b to the scale of the current context, computes the modulus a-(a/b)*b, and returns the modulus.

BclNumber bcl_pow(BclNumber a, BclNumber b)

Calculates a to the power of b to the scale of the current context. b must be an integer, but can be negative. If it is negative, a must be non-zero.

BclNumber bcl_lshift(BclNumber a, BclNumber b)

Shifts a left (moves the radix right) by b places and returns the result. This is done in decimal. b must be an integer.

BclNumber bcl_rshift(BclNumber a, BclNumber b)

Shifts a right (moves the radix left) by b places and returns the result. This is done in decimal. b must be an integer.

BclNumber bcl_sqrt(BclNumber a)

Calculates the square root of a and returns the result. The scale of the result is equal to the scale of the current context.

BclError bcl_divmod(BclNumber a, BclNumber b, BclNumber *c, BclNumber *d)

Divides a by b and returns the quotient in a new number which is put into the space pointed to by c, and puts the modulus in a new number which is put into the space pointed to by d.

BclNumber bcl_modexp(BclNumber a, BclNumber b, BclNumber c)

Computes a modular exponentiation where a is the base, b is the exponent, and c is the modulus, and returns the result. The scale of the result is equal to the scale of the current context.

Miscellaneous

void bcl_zero(BclNumber n)

Sets n to 0.

void bcl_one(BclNumber n)

Sets n to 1.

ssize_t bcl_cmp(BclNumber a, BclNumber b)

Compares a and b and returns 0 if a and b are equal, <0 if a is less than b, and >0 if a is greater than b.

BclError bcl_copy(BclNumber d, BclNumber s)

Copies s into d.

BclNumber bcl_dup(BclNumber s)

Creates and returns a new BclNumber that is a copy of s.

Pseudo-Random Number Generator

By default, bcl(3) attempts to seed the PRNG with data from /dev/urandom. If that fails, it seeds itself with by calling libc’s srand(time(NULL)) and then calling rand() for each byte, since rand() is only guaranteed to return 15 bits.

This should provide fairly good seeding in the standard case while also remaining fairly portable.

If necessary, the PRNG can be reseeded with one of the following functions:

•

bcl_rand_seedWithNum(BclNumber)

•

bcl_rand_seed(unsigned char[BCL_SEED_SIZE])

•

bcl_rand_reseed(void)

The following items allow clients to use the pseudo-random number generator. All procedures require a valid current context.

BCL_SEED_ULONGS

The number of unsigned long’s in a seed for bcl(3)’s random number generator.

BCL_SEED_SIZE

The size, in char’s, of a seed for bcl(3)’s random number generator.

BclBigDig

bcl(3)’s overflow type (see the PERFORMANCE section).

BclRandInt

An unsigned integer type returned by bcl(3)’s random number generator.

BclNumber bcl_irand(BclNumber a)

Returns a random number that is not larger than a in a new number. If a is 0 or 1, the new number is equal to 0. The bound is unlimited, so it is not bound to the size of BclRandInt. This is done by generating as many random numbers as necessary, multiplying them by certain exponents, and adding them all together.

BclNumber bcl_frand(size_t places)

Returns a random number between 0 (inclusive) and 1 (exclusive) that has places decimal digits after the radix (decimal point). There are no limits on places.

BclNumber bcl_ifrand(BclNumber a, size_t places)

Returns a random number less than a with places decimal digits after the radix (decimal point). There are no limits on a or places.

BclError bcl_rand_seedWithNum(BclNumber n)

Seeds the PRNG with n.

BclError bcl_rand_seed(unsigned char seed[BCL_SEED_SIZE])

Seeds the PRNG with the bytes in seed.

void bcl_rand_reseed(void)

Reseeds the PRNG with the default reseeding behavior. First, it attempts to read data from /dev/urandom and falls back to libc’s rand().

BclNumber bcl_rand_seed2num(void)

Returns the current seed of the PRNG as a BclNumber.

BclRandInt bcl_rand_int(void)

Returns a random integer between 0 and BC_RAND_MAX (inclusive).

BclRandInt bcl_rand_bounded(BclRandInt bound)

Returns a random integer between 0 and bound (exclusive). Bias is removed before returning the integer.

Consumption and Propagation

This is to enable compact code like the following:

BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d));

    

If arguments to those functions were not consumed, memory would be leaked until reclaimed with bcl_ctxt_freeNums(BclContext).

When errors occur, they are propagated through. The result should always be checked with bcl_err(BclNumber), so the example above should properly be:

BclNumber n = bcl_num_add(bcl_num_mul(a, b), bcl_num_div(c, d));
if (bc_num_err(n) != BCL_ERROR_NONE) {
    // Handle the error.
}