4. Functions on numbers

Each of the number classes declares its mathematical operations in the corresponding include file. For example, if your code operates with objects of type cl_I, it should #include <cln/integer.h>.

4.1 Constructing numbers

Here is how to create number objects "from nothing".

4.1.1 Constructing integers

cl_I objects are most easily constructed from C integers and from strings. See 3.4 Conversions.

4.1.2 Constructing rational numbers

cl_RA objects can be constructed from strings. The syntax for rational numbers is described in 5.1 Internal and printed representation. Another standard way to produce a rational number is through application of `operator /' or `recip' on integers.

4.1.3 Constructing floating-point numbers

cl_F objects with low precision are most easily constructed from C `float' and `double'. See 3.4 Conversions.

To construct a cl_F with high precision, you can use the conversion from `const char *', but you have to specify the desired precision within the string. (See 5.1 Internal and printed representation.) Example:

   cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";

The programmatic way to construct a cl_F with high precision is through the cl_float conversion function, see 4.11.1 Conversion to floating-point numbers. For example, to compute e to 40 decimal places, first construct 1.0 to 40 decimal places and then apply the exponential function:

   float_format_t precision = float_format(40);
   cl_F e = exp(cl_float(1,precision));

4.1.4 Constructing complex numbers

Non-real cl_N objects are normally constructed through the function

   cl_N complex (const cl_R& realpart, const cl_R& imagpart)

4.2 Elementary functions

Each of the classes cl_N, cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

type operator + (const type&, const type&)

Addition.

type operator - (const type&, const type&)

Subtraction.

type operator - (const type&)

Returns the negative of the argument.

type plus1 (const type& x)

Returns x + 1.

type minus1 (const type& x)

Returns x - 1.

type operator * (const type&, const type&)

Multiplication.

type square (const type& x)

Returns x * x.

Each of the classes cl_N, cl_R, cl_RA, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

type operator / (const type&, const type&)

Division.

type recip (const type&)

Returns the reciprocal of the argument.

The class cl_I doesn't define a `/' operation because in the C/C++ language this operator, applied to integral types, denotes the `floor' or `truncate' operation (which one of these, is implementation dependent). (See section 4.6 Rounding functions.) Instead, cl_I defines an "exact quotient" function:

cl_I exquo (const cl_I& x, const cl_I& y)

Checks that y divides x, and returns the quotient x/y.

The following exponentiation functions are defined:

cl_I expt_pos (const cl_I& x, const cl_I& y)

cl_RA expt_pos (const cl_RA& x, const cl_I& y)

y must be > 0. Returns x^y.

cl_RA expt (const cl_RA& x, const cl_I& y)

cl_R expt (const cl_R& x, const cl_I& y)

cl_N expt (const cl_N& x, const cl_I& y)

Returns x^y.

Each of the classes cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operation:

type abs (const type& x)

Returns the absolute value of x. This is x if x >= 0, and -x if x <= 0.

The class cl_N implements this as follows:

cl_R abs (const cl_N x)

Returns the absolute value of x.

Each of the classes cl_N, cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operation:

type signum (const type& x)

Returns the sign of x, in the same number format as x. This is defined as x / abs(x) if x is non-zero, and x if x is zero. If x is real, the value is either 0 or 1 or -1.

4.3 Elementary rational functions

Each of the classes cl_RA, cl_I defines the following operations:

cl_I numerator (const type& x)

Returns the numerator of x.

cl_I denominator (const type& x)

Returns the denominator of x.

The numerator and denominator of a rational number are normalized in such a way that they have no factor in common and the denominator is positive.

4.4 Elementary complex functions

The class cl_N defines the following operation:

cl_N complex (const cl_R& a, const cl_R& b)

Returns the complex number a+bi, that is, the complex number with real part a and imaginary part b.

Each of the classes cl_N, cl_R defines the following operations:

cl_R realpart (const type& x)

Returns the real part of x.

cl_R imagpart (const type& x)

Returns the imaginary part of x.

type conjugate (const type& x)

Returns the complex conjugate of x.

We have the relations

• x = complex(realpart(x), imagpart(x))
• conjugate(x) = complex(realpart(x), -imagpart(x))

4.5 Comparisons

Each of the classes cl_N, cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

bool operator == (const type&, const type&)

bool operator != (const type&, const type&)

Comparison, as in C and C++.

uint32 equal_hashcode (const type&)

Returns a 32-bit hash code that is the same for any two numbers which are the same according to ==. This hash code depends on the number's value, not its type or precision.

cl_boolean zerop (const type& x)

Compare against zero: x == 0

Each of the classes cl_R, cl_RA, cl_I, cl_F, cl_SF, cl_FF, cl_DF, cl_LF defines the following operations:

cl_signean compare (const type& x, const type& y)

Compares x and y. Returns +1 if x>y, -1 if x<y, 0 if x=y.

bool operator <= (const type&, const type&)

bool operator < (const type&, const type&)

bool operator >= (const type&, const type&)

bool operator > (const type&, const type&)

Comparison, as in C and C++.

cl_boolean minusp (const type& x)

Compare against zero: x < 0

cl_boolean plusp (const type& x)

Compare against zero: x > 0

type max (const type& x, const type& y)

Return the maximum of x and y.

type min (const type& x, const type& y)

Return the minimum of x and y.

When a floating point number and a rational number are compared, the float is first converted to a rational number using the function rational. Since a floating point number actually represents an interval of real numbers, the result might be surpris?