Reference

Every public function in LZMath.h, one page each. The prototypes are taken from the header, and every example on these pages is what the engine printed.

What every function shares

Setup

Call lzu_setup once before the first calculation and lzu_takedown once after the last. Between them, any number of threads may compute at once.

Numbers

A CLZNumber is made from text, a long, a double or another number: CLZNumber x( "0.1" ). Text may name its base with a prefix, as "0x15" or "0b1010", and SetBase( 12 ) re-expresses a value in any base from 2 to 16. GetStringRep() gives the digits as text, which the caller releases with free(). A CLZComplex holds two numbers, m_real and m_imag, in one base.

Targets

Most functions take an optional target, the last parameter. Pass one and the answer lands there; leave it out and the answer replaces the left operand. A number marked constant is never written. A few functions require a target, because they have no operand of the right kind to write: the means of a list, the paired functions, and the complex functions whose answer is real.

Bases

Two operands need not share a base: the right one is brought into the left one's base on a copy, and never modified. Every answer comes back in the left operand's base, so the sine of a hexadecimal value is hexadecimal.

Precision and rounding

glWorkingPrecision sets how many places after the point an answer keeps, in its own base. It belongs to the thread, and starts at 36 in every new one. Every function rounds its answer correctly, half-even, however close the value comes to a rounding boundary. The four plain operations, lz_add, lz_subtract, lz_multiply and lz_divide, round in the target's own rounding mode instead, one of twelve. A small answer can keep its significant digits rather than rounding them away, and a quotient keeps a digit or two more; the examples on each page show what a function writes.

Angles

The circular functions and their inverses read or write angles in the thread's unit, geAngleUnit: AU_radians, the default, AU_degrees, AU_grads or AU_millicles. Outside radians an angle is reduced by whole turns exactly, so sin 30° is exactly 0.5 and tan 90° is a pole. The hyperbolic functions, the complex logarithm and the complex exponential always work in radians.

Errors and flags

A function answers kNoError (0) when it writes its answer. When there is no answer to give, it says so twice: it returns a code and flags the answer.

`kFailed` (1)	An operand outside the function's domain, such as the square root of −9, or a required target missing.
`kDivideByZero` (3)	A division by nought, or a pole such as tan 90°.
`kUndefinedResult` (4)	No value at all, such as ln 0 or Γ(0).
`kBaseMismatch` (5)	A complex value whose two parts are in different bases.
`kTooLarge` (6)	An answer that would need more than 100,000 places, refused before any work is done. `lzu_set_answer_limit` changes the limit.

The flags are kfInfinity, kfQNaN and kfDiv0, read with IsInfinity() and FlagIsOn(). They carry through later arithmetic, so a failure early in a calculation is still visible at its end. Infinities carry no sign: infinity minus infinity is not-a-number. A comparison with a flagged number answers kUnordered.

Threads

Each thread keeps its own precision and angle unit. A number may be read by several threads at once but not written by one while another reads it, so give each thread its own results.

The functions

Setup

Three calls that bracket everything else. Call lzu_setup once before the first calculation, and lzu_takedown once after the last.

`lzu_setup`	Builds the shared table of high-precision constants; call it before anything else.
`lzu_takedown`	Releases the shared table of constants; call it after the last calculation.
`lzu_set_answer_limit`	Sets how many places an answer may need before it is refused, for the whole process.

Arithmetic

The four operations, the whole quotient and its remainders, and the sign. These are the only functions that honour the target's own rounding mode.

`lz_add`	The sum of two numbers.
`lz_subtract`	The difference of two numbers, left minus right.
`lz_multiply`	The product of two numbers.
`lz_divide`	The quotient of two numbers, left over right.
`lz_divide_integer`	The whole part of the quotient, truncated toward nought.
`lz_modulo`	The remainder after the truncated whole quotient; the same operation as lz_remainder.
`lz_remainder`	The remainder after the truncated whole quotient, left − trunc(left ÷ right) × right.
`lz_remainder_near`	The remainder after the nearest whole quotient, ties to even.
`lz_abs`	The absolute value.
`lz_negate`	The number with its sign changed.
`lz_plus`	The number itself, unchanged: the decimal standard's unary plus.
`lz_reciprocal`	One over the number.

Comparison

These four answer with a code rather than writing a number. Each answers kUnordered when either side is a not-a-number or an infinity, since an infinity here carries no sign.

`lz_compare`	Whether the left number is less than, equal to or greater than the right.
`lz_max`	Which of two numbers is the larger.
`lz_min`	Which of two numbers is the smaller.
`lz_same_quantum`	Whether two numbers have the same number of places after the point.

Powers and roots

Whole powers are taken by repeated squaring, so their cost follows the number of digits in the exponent rather than its size. A root of whole order exactly on a half is decided exactly.

`lz_square`	The number times itself.
`lz_cube`	The number cubed.
`lz_power`	The left number raised to the power of the right.
`lz_raise_n`	The left number raised to a whole power, the right.
`lz_raise_e`	e raised to a whole power.
`lz_root_2`	The square root.
`lz_root_3`	The cube root.
`lz_root_n`	The root of the left number whose order is the right.

Exponentials

An answer too large to hold is refused before any work is done, and one that rounds to nought at the working precision is nought at once.

`lz_exp_e`	e raised to the power of the number.
`lz_exp_b`	The number's own base raised to the power of the number.
`lz_exp_n`	The left number raised to the power of the right.

Logarithms

The logarithm of nought or of a negative number has no real answer, and is refused with a flag.

`lz_log_e`	The natural logarithm.
`lz_log_b`	The logarithm to the number's own base.
`lz_log_n`	The logarithm of the right number to the base of the left.

Trigonometry

All fourteen read or write their angle in the thread's angle unit: radians, degrees, grads or millicles, set in geAngleUnit. Outside radians an angle is reduced by whole turns exactly, so sin 30° is exactly 0.5 and tan 90° is a pole.

`lz_sine`	The sine of an angle.
`lz_cosine`	The cosine of an angle.
`lz_tangent`	The tangent of an angle.
`lz_cotangent`	The cotangent of an angle, one over its tangent.
`lz_secant`	The secant of an angle, one over its cosine.
`lz_cosecant`	The cosecant of an angle, one over its sine.
`lz_sine_cosine`	The sine and the cosine of one angle together, for about half the cost of the two.
`lz_arcsine`	The angle whose sine is the number.
`lz_arccosine`	The angle whose cosine is the number.
`lz_arctangent`	The angle whose tangent is the number.
`lz_arccotangent`	The angle whose cotangent is the number, arctan(1/x).
`lz_arcsecant`	The angle whose secant is the number.
`lz_arccosecant`	The angle whose cosecant is the number.
`lz_arctangent2`	The angle of the point (x, y), with y first, as C's atan2 takes them.

Hyperbolic functions

Each forward function comes from a single e^x. The hyperbolic functions take no angle unit: they are always in radians.

`lz_hypersine`	The hyperbolic sine.
`lz_hypercosine`	The hyperbolic cosine.
`lz_hypertangent`	The hyperbolic tangent.
`lz_hypercotangent`	The hyperbolic cotangent, one over the hyperbolic tangent.
`lz_hypersecant`	The hyperbolic secant, one over the hyperbolic cosine.
`lz_hypercosecant`	The hyperbolic cosecant, one over the hyperbolic sine.
`lz_hypersine_hypercosine`	The hyperbolic sine and cosine of one number together, from one exponential.
`lz_archypersine`	The number whose hyperbolic sine is the operand.
`lz_archypercosine`	The number at or above nought whose hyperbolic cosine is the operand.
`lz_archypertangent`	The number whose hyperbolic tangent is the operand.
`lz_archypercotangent`	The number whose hyperbolic cotangent is the operand.
`lz_archypersecant`	The number at or above nought whose hyperbolic secant is the operand.
`lz_archypercosecant`	The number whose hyperbolic cosecant is the operand.

Gamma

A whole number is answered exactly, as a factorial. Anything else above nought comes from Stirling's series after a shift, and below nought by reflection. The poles are refused.

`lz_gamma`	The gamma function, Γ(x).
`lz_log_gamma`	The natural logarithm of the gamma function, ln Γ(x), for x above nought.

Combinatorics

On the whole numbers, and exact. Choosing or arranging more than there are is nought.

`lz_factorial`	The product of the whole numbers from one to the operand, n!.
`lz_combinations`	The number of ways to choose the right number of things from the left, n choose k.
`lz_permutations`	The number of ordered arrangements of the right number of things from the left, n!/(n − k)!.

Means

The three means of a list are the only functions that take one: an array of numbers and a count. Having no left operand to update, they require a target.

`lz_amean`	The arithmetic mean of a list.
`lz_gmean`	The geometric mean of a list.
`lz_hmean`	The harmonic mean of a list.
`lz_agm`	The arithmetic-geometric mean of two numbers that are not negative.

Decimal standard

Operations from the decimal arithmetic standards, on a number's places and its whole and fractional parts.

`lz_quantize`	The left number rounded to as many places as the right number has.
`lz_normalize`	The number with its trailing noughts after the point removed.
`lz_round`	The number rounded in its own rounding mode, half-even by default.
`lz_round_integral`	The number rounded to a whole number, half-even by default.
`lz_round_last_digit`	The number rounded at its own last place.
`lz_integer`	The whole part of the number, truncated toward nought.
`lz_fraction`	The fractional part of the number, its sign kept.

Complex arithmetic

A CLZComplex holds two CLZNumbers, m_real and m_imag, in one base. Each part of an answer is correctly rounded from exact intermediates.

`lzc_add`	The sum of two complex numbers.
`lzc_subtract`	The difference of two complex numbers, left minus right.
`lzc_negate`	The complex number with both signs changed.
`lzc_conjugate`	The complex conjugate: the same real part, the imaginary part negated.
`lzc_multiply`	The product of two complex numbers.
`lzc_square`	The complex number times itself.
`lzc_divide`	The quotient of two complex numbers, left over right.
`lzc_abs`	The modulus of a complex number, \|z\|, a real answer.
`lzc_arg`	The argument of a complex number, its angle, a real answer in the thread's angle unit.
`lzc_polar`	A complex number from its modulus and its angle, r cos θ + i r sin θ.

Complex exponentials, logarithms, powers and roots

The principal values, each part correctly rounded and exact where the mathematics is. The cut is the negative real axis, taken from the +0 side, as std::complex takes it.

`lzc_exp_e`	e raised to a complex power.
`lzc_log_e`	The principal natural logarithm of a complex number.
`lzc_root_2`	The principal square root of a complex number.
`lzc_root_3`	The cube root of a complex number; an odd root of a negative real is the real root.
`lzc_root_n`	The principal root of complex order w, z^(1/w).
`lzc_power`	A complex number raised to a complex power, the principal value e^(w ln z).
`lzc_raise_n`	A complex number raised to a whole power.
`lzc_exp_b`	The base the number is written in, raised to a complex power.
`lzc_log_b`	The principal logarithm to the base the number is written in.
`lzc_log_n`	The principal logarithm of the right complex number to the base of the left.

Complex circular and hyperbolic functions

The circular six read the whole complex angle in the thread's angle unit, so z degrees is zπ/180, both parts. The hyperbolic six are always in radians.

`lzc_sine`	The sine of a complex angle.
`lzc_cosine`	The cosine of a complex angle.
`lzc_tangent`	The tangent of a complex angle.
`lzc_cotangent`	The cotangent of a complex angle.
`lzc_secant`	The secant of a complex angle.
`lzc_cosecant`	The cosecant of a complex angle.
`lzc_hypersine`	The hyperbolic sine of a complex number.
`lzc_hypercosine`	The hyperbolic cosine of a complex number.
`lzc_hypertangent`	The hyperbolic tangent of a complex number.
`lzc_hypercotangent`	The hyperbolic cotangent of a complex number.
`lzc_hypersecant`	The hyperbolic secant of a complex number.
`lzc_hypercosecant`	The hyperbolic cosecant of a complex number.

Complex inverse functions

The principal values. On a branch cut each takes the operand's +0 side, as std::complex answers. The circular inverses write the whole complex angle in the thread's angle unit, the hyperbolic ones in radians.

`lzc_arcsine`	The principal arcsine of a complex number.
`lzc_arccosine`	The principal arccosine of a complex number.
`lzc_arctangent`	The principal arctangent of a complex number.
`lzc_arccotangent`	The principal arccotangent of a complex number, arctan(1/z).
`lzc_arcsecant`	The principal arcsecant of a complex number.
`lzc_arccosecant`	The principal arccosecant of a complex number.
`lzc_archypersine`	The principal inverse hyperbolic sine of a complex number.
`lzc_archypercosine`	The principal inverse hyperbolic cosine of a complex number.
`lzc_archypertangent`	The principal inverse hyperbolic tangent of a complex number.
`lzc_archypercotangent`	The principal inverse hyperbolic cotangent of a complex number.
`lzc_archypersecant`	The principal inverse hyperbolic secant of a complex number.
`lzc_archypercosecant`	The principal inverse hyperbolic cosecant of a complex number.