You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1804 lines
57 KiB
1804 lines
57 KiB
<HTML>
|
|
<HEAD>
|
|
<!-- Created by texi2html 1.56k from cln.texi on 14 January 2000 -->
|
|
|
|
<TITLE>CLN, a Class Library for Numbers - 4. Functions on numbers</TITLE>
|
|
</HEAD>
|
|
<BODY>
|
|
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_3.html">previous</A>, <A HREF="cln_5.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
|
|
<P><HR><P>
|
|
|
|
|
|
<H1><A NAME="SEC15" HREF="cln_toc.html#TOC15">4. Functions on numbers</A></H1>
|
|
|
|
<P>
|
|
Each of the number classes declares its mathematical operations in the
|
|
corresponding include file. For example, if your code operates with
|
|
objects of type <CODE>cl_I</CODE>, it should <CODE>#include <cl_integer.h></CODE>.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC16" HREF="cln_toc.html#TOC16">4.1 Constructing numbers</A></H2>
|
|
|
|
<P>
|
|
Here is how to create number objects "from nothing".
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="SEC17" HREF="cln_toc.html#TOC17">4.1.1 Constructing integers</A></H3>
|
|
|
|
<P>
|
|
<CODE>cl_I</CODE> objects are most easily constructed from C integers and from
|
|
strings. See section <A HREF="cln_3.html#SEC14">3.4 Conversions</A>.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="SEC18" HREF="cln_toc.html#TOC18">4.1.2 Constructing rational numbers</A></H3>
|
|
|
|
<P>
|
|
<CODE>cl_RA</CODE> objects can be constructed from strings. The syntax
|
|
for rational numbers is described in section <A HREF="cln_5.html#SEC44">5.1 Internal and printed representation</A>.
|
|
Another standard way to produce a rational number is through application
|
|
of <SAMP>`operator /'</SAMP> or <SAMP>`recip'</SAMP> on integers.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="SEC19" HREF="cln_toc.html#TOC19">4.1.3 Constructing floating-point numbers</A></H3>
|
|
|
|
<P>
|
|
<CODE>cl_F</CODE> objects with low precision are most easily constructed from
|
|
C <SAMP>`float'</SAMP> and <SAMP>`double'</SAMP>. See section <A HREF="cln_3.html#SEC14">3.4 Conversions</A>.
|
|
|
|
|
|
<P>
|
|
To construct a <CODE>cl_F</CODE> with high precision, you can use the conversion
|
|
from <SAMP>`const char *'</SAMP>, but you have to specify the desired precision
|
|
within the string. (See section <A HREF="cln_5.html#SEC44">5.1 Internal and printed representation</A>.)
|
|
Example:
|
|
|
|
<PRE>
|
|
cl_F e = "0.271828182845904523536028747135266249775724709369996e+1_40";
|
|
</PRE>
|
|
|
|
<P>
|
|
will set <SAMP>`e'</SAMP> to the given value, with a precision of 40 decimal digits.
|
|
|
|
|
|
<P>
|
|
The programmatic way to construct a <CODE>cl_F</CODE> with high precision is
|
|
through the <CODE>cl_float</CODE> conversion function, see
|
|
section <A HREF="cln_4.html#SEC39">4.11.1 Conversion to floating-point numbers</A>. For example, to compute
|
|
<CODE>e</CODE> to 40 decimal places, first construct 1.0 to 40 decimal places
|
|
and then apply the exponential function:
|
|
|
|
<PRE>
|
|
cl_float_format_t precision = cl_float_format(40);
|
|
cl_F e = exp(cl_float(1,precision));
|
|
</PRE>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC20" HREF="cln_toc.html#TOC20">4.1.4 Constructing complex numbers</A></H3>
|
|
|
|
<P>
|
|
Non-real <CODE>cl_N</CODE> objects are normally constructed through the function
|
|
|
|
<PRE>
|
|
cl_N complex (const cl_R& realpart, const cl_R& imagpart)
|
|
</PRE>
|
|
|
|
<P>
|
|
See section <A HREF="cln_4.html#SEC23">4.4 Elementary complex functions</A>.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC21" HREF="cln_toc.html#TOC21">4.2 Elementary functions</A></H2>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> operator + (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Addition.
|
|
|
|
<DT><CODE><VAR>type</VAR> operator - (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Subtraction.
|
|
|
|
<DT><CODE><VAR>type</VAR> operator - (const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Returns the negative of the argument.
|
|
|
|
<DT><CODE><VAR>type</VAR> plus1 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>x + 1</CODE>.
|
|
|
|
<DT><CODE><VAR>type</VAR> minus1 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>x - 1</CODE>.
|
|
|
|
<DT><CODE><VAR>type</VAR> operator * (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Multiplication.
|
|
|
|
<DT><CODE><VAR>type</VAR> square (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>x * x</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> operator / (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Division.
|
|
|
|
<DT><CODE><VAR>type</VAR> recip (const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Returns the reciprocal of the argument.
|
|
</DL>
|
|
|
|
<P>
|
|
The class <CODE>cl_I</CODE> doesn't define a <SAMP>`/'</SAMP> operation because
|
|
in the C/C++ language this operator, applied to integral types,
|
|
denotes the <SAMP>`floor'</SAMP> or <SAMP>`truncate'</SAMP> operation (which one of these,
|
|
is implementation dependent). (See section <A HREF="cln_4.html#SEC25">4.6 Rounding functions</A>)
|
|
Instead, <CODE>cl_I</CODE> defines an "exact quotient" function:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I exquo (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Checks that <CODE>y</CODE> divides <CODE>x</CODE>, and returns the quotient <CODE>x</CODE>/<CODE>y</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
The following exponentiation functions are defined:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I expt_pos (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_RA expt_pos (const cl_RA& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<CODE>y</CODE> must be > 0. Returns <CODE>x^y</CODE>.
|
|
|
|
<DT><CODE>cl_RA expt (const cl_RA& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_R expt (const cl_R& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_N expt (const cl_N& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Returns <CODE>x^y</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> abs (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the absolute value of <CODE>x</CODE>.
|
|
This is <CODE>x</CODE> if <CODE>x >= 0</CODE>, and <CODE>-x</CODE> if <CODE>x <= 0</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
The class <CODE>cl_N</CODE> implements this as follows:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_R abs (const cl_N x)</CODE>
|
|
<DD>
|
|
Returns the absolute value of <CODE>x</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> signum (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the sign of <CODE>x</CODE>, in the same number format as <CODE>x</CODE>.
|
|
This is defined as <CODE>x / abs(x)</CODE> if <CODE>x</CODE> is non-zero, and
|
|
<CODE>x</CODE> if <CODE>x</CODE> is zero. If <CODE>x</CODE> is real, the value is either
|
|
0 or 1 or -1.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC22" HREF="cln_toc.html#TOC22">4.3 Elementary rational functions</A></H2>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE> defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I numerator (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the numerator of <CODE>x</CODE>.
|
|
|
|
<DT><CODE>cl_I denominator (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the denominator of <CODE>x</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
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.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC23" HREF="cln_toc.html#TOC23">4.4 Elementary complex functions</A></H2>
|
|
|
|
<P>
|
|
The class <CODE>cl_N</CODE> defines the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_N complex (const cl_R& a, const cl_R& b)</CODE>
|
|
<DD>
|
|
Returns the complex number <CODE>a+bi</CODE>, that is, the complex number with
|
|
real part <CODE>a</CODE> and imaginary part <CODE>b</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE> defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_R realpart (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the real part of <CODE>x</CODE>.
|
|
|
|
<DT><CODE>cl_R imagpart (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the imaginary part of <CODE>x</CODE>.
|
|
|
|
<DT><CODE><VAR>type</VAR> conjugate (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the complex conjugate of <CODE>x</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
We have the relations
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<CODE>x = complex(realpart(x), imagpart(x))</CODE>
|
|
<LI>
|
|
|
|
<CODE>conjugate(x) = complex(realpart(x), -imagpart(x))</CODE>
|
|
</UL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC24" HREF="cln_toc.html#TOC24">4.5 Comparisons</A></H2>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>bool operator == (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE>bool operator != (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Comparison, as in C and C++.
|
|
|
|
<DT><CODE>uint32 cl_equal_hashcode (const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Returns a 32-bit hash code that is the same for any two numbers which are
|
|
the same according to <CODE>==</CODE>. This hash code depends on the number's value,
|
|
not its type or precision.
|
|
|
|
<DT><CODE>cl_boolean zerop (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Compare against zero: <CODE>x == 0</CODE>
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_signean cl_compare (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Compares <CODE>x</CODE> and <CODE>y</CODE>. Returns +1 if <CODE>x</CODE>><CODE>y</CODE>,
|
|
-1 if <CODE>x</CODE><<CODE>y</CODE>, 0 if <CODE>x</CODE>=<CODE>y</CODE>.
|
|
|
|
<DT><CODE>bool operator <= (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE>bool operator < (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE>bool operator >= (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE>bool operator > (const <VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
Comparison, as in C and C++.
|
|
|
|
<DT><CODE>cl_boolean minusp (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Compare against zero: <CODE>x < 0</CODE>
|
|
|
|
<DT><CODE>cl_boolean plusp (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Compare against zero: <CODE>x > 0</CODE>
|
|
|
|
<DT><CODE><VAR>type</VAR> max (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Return the maximum of <CODE>x</CODE> and <CODE>y</CODE>.
|
|
|
|
<DT><CODE><VAR>type</VAR> min (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Return the minimum of <CODE>x</CODE> and <CODE>y</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
When a floating point number and a rational number are compared, the float
|
|
is first converted to a rational number using the function <CODE>rational</CODE>.
|
|
Since a floating point number actually represents an interval of real numbers,
|
|
the result might be surprising.
|
|
For example, <CODE>(cl_F)(cl_R)"1/3" == (cl_R)"1/3"</CODE> returns false because
|
|
there is no floating point number whose value is exactly <CODE>1/3</CODE>.
|
|
|
|
|
|
|
|
|
|
<H2><A NAME="SEC25" HREF="cln_toc.html#TOC25">4.6 Rounding functions</A></H2>
|
|
|
|
<P>
|
|
When a real number is to be converted to an integer, there is no "best"
|
|
rounding. The desired rounding function depends on the application.
|
|
The Common Lisp and ISO Lisp standards offer four rounding functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>floor(x)</CODE>
|
|
<DD>
|
|
This is the largest integer <=<CODE>x</CODE>.
|
|
|
|
<DT><CODE>ceiling(x)</CODE>
|
|
<DD>
|
|
This is the smallest integer >=<CODE>x</CODE>.
|
|
|
|
<DT><CODE>truncate(x)</CODE>
|
|
<DD>
|
|
Among the integers between 0 and <CODE>x</CODE> (inclusive) the one nearest to <CODE>x</CODE>.
|
|
|
|
<DT><CODE>round(x)</CODE>
|
|
<DD>
|
|
The integer nearest to <CODE>x</CODE>. If <CODE>x</CODE> is exactly halfway between two
|
|
integers, choose the even one.
|
|
</DL>
|
|
|
|
<P>
|
|
These functions have different advantages:
|
|
|
|
|
|
<P>
|
|
<CODE>floor</CODE> and <CODE>ceiling</CODE> are translation invariant:
|
|
<CODE>floor(x+n) = floor(x) + n</CODE> and <CODE>ceiling(x+n) = ceiling(x) + n</CODE>
|
|
for every <CODE>x</CODE> and every integer <CODE>n</CODE>.
|
|
|
|
|
|
<P>
|
|
On the other hand, <CODE>truncate</CODE> and <CODE>round</CODE> are symmetric:
|
|
<CODE>truncate(-x) = -truncate(x)</CODE> and <CODE>round(-x) = -round(x)</CODE>,
|
|
and furthermore <CODE>round</CODE> is unbiased: on the "average", it rounds
|
|
down exactly as often as it rounds up.
|
|
|
|
|
|
<P>
|
|
The functions are related like this:
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<CODE>ceiling(m/n) = floor((m+n-1)/n) = floor((m-1)/n)+1</CODE>
|
|
for rational numbers <CODE>m/n</CODE> (<CODE>m</CODE>, <CODE>n</CODE> integers, <CODE>n</CODE>>0), and
|
|
<LI>
|
|
|
|
<CODE>truncate(x) = sign(x) * floor(abs(x))</CODE>
|
|
</UL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I floor1 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>floor(x)</CODE>.
|
|
<DT><CODE>cl_I ceiling1 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>ceiling(x)</CODE>.
|
|
<DT><CODE>cl_I truncate1 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>truncate(x)</CODE>.
|
|
<DT><CODE>cl_I round1 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>round(x)</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I floor1 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Returns <CODE>floor(x/y)</CODE>.
|
|
<DT><CODE>cl_I ceiling1 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Returns <CODE>ceiling(x/y)</CODE>.
|
|
<DT><CODE>cl_I truncate1 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Returns <CODE>truncate(x/y)</CODE>.
|
|
<DT><CODE>cl_I round1 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
Returns <CODE>round(x/y)</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
These functions are called <SAMP>`floor1'</SAMP>, ... here instead of
|
|
<SAMP>`floor'</SAMP>, ..., because on some systems, system dependent include
|
|
files define <SAMP>`floor'</SAMP> and <SAMP>`ceiling'</SAMP> as macros.
|
|
|
|
|
|
<P>
|
|
In many cases, one needs both the quotient and the remainder of a division.
|
|
It is more efficient to compute both at the same time than to perform
|
|
two divisions, one for quotient and the next one for the remainder.
|
|
The following functions therefore return a structure containing both
|
|
the quotient and the remainder. The suffix <SAMP>`2'</SAMP> indicates the number
|
|
of "return values". The remainder is defined as follows:
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
for the computation of <CODE>quotient = floor(x)</CODE>,
|
|
<CODE>remainder = x - quotient</CODE>,
|
|
<LI>
|
|
|
|
for the computation of <CODE>quotient = floor(x,y)</CODE>,
|
|
<CODE>remainder = x - quotient*y</CODE>,
|
|
</UL>
|
|
|
|
<P>
|
|
and similarly for the other three operations.
|
|
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>struct <VAR>type</VAR>_div_t { cl_I quotient; <VAR>type</VAR> remainder; };</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t floor2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t ceiling2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t truncate2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t round2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>struct <VAR>type</VAR>_div_t { cl_I quotient; <VAR>type</VAR> remainder; };</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t floor2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t ceiling2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t truncate2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_div_t round2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
Sometimes, one wants the quotient as a floating-point number (of the
|
|
same format as the argument, if the argument is a float) instead of as
|
|
an integer. The prefix <SAMP>`f'</SAMP> indicates this.
|
|
|
|
|
|
<P>
|
|
Each of the classes
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> ffloor (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR> fceiling (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR> ftruncate (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR> fround (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
and similarly for class <CODE>cl_R</CODE>, but with return type <CODE>cl_F</CODE>.
|
|
|
|
|
|
<P>
|
|
The class <CODE>cl_R</CODE> defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F ffloor (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_F fceiling (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_F ftruncate (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_F fround (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
These functions also exist in versions which return both the quotient
|
|
and the remainder. The suffix <SAMP>`2'</SAMP> indicates this.
|
|
|
|
|
|
<P>
|
|
Each of the classes
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>struct <VAR>type</VAR>_fdiv_t { <VAR>type</VAR> quotient; <VAR>type</VAR> remainder; };</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t ffloor2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t fceiling2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t ftruncate2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t fround2 (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
</DL>
|
|
<P>
|
|
and similarly for class <CODE>cl_R</CODE>, but with quotient type <CODE>cl_F</CODE>.
|
|
|
|
|
|
<P>
|
|
The class <CODE>cl_R</CODE> defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>struct <VAR>type</VAR>_fdiv_t { cl_F quotient; cl_R remainder; };</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t ffloor2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t fceiling2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t ftruncate2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>_fdiv_t fround2 (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
Other applications need only the remainder of a division.
|
|
The remainder of <SAMP>`floor'</SAMP> and <SAMP>`ffloor'</SAMP> is called <SAMP>`mod'</SAMP>
|
|
(abbreviation of "modulo"). The remainder <SAMP>`truncate'</SAMP> and
|
|
<SAMP>`ftruncate'</SAMP> is called <SAMP>`rem'</SAMP> (abbreviation of "remainder").
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<CODE>mod(x,y) = floor2(x,y).remainder = x - floor(x/y)*y</CODE>
|
|
<LI>
|
|
|
|
<CODE>rem(x,y) = truncate2(x,y).remainder = x - truncate(x/y)*y</CODE>
|
|
</UL>
|
|
|
|
<P>
|
|
If <CODE>x</CODE> and <CODE>y</CODE> are both >= 0, <CODE>mod(x,y) = rem(x,y) >= 0</CODE>.
|
|
In general, <CODE>mod(x,y)</CODE> has the sign of <CODE>y</CODE> or is zero,
|
|
and <CODE>rem(x,y)</CODE> has the sign of <CODE>x</CODE> or is zero.
|
|
|
|
|
|
<P>
|
|
The classes <CODE>cl_R</CODE>, <CODE>cl_I</CODE> define the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> mod (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR> rem (const <VAR>type</VAR>& x, const <VAR>type</VAR>& y)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC26" HREF="cln_toc.html#TOC26">4.7 Roots</A></H2>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> sqrt (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
<CODE>x</CODE> must be >= 0. This function returns the square root of <CODE>x</CODE>,
|
|
normalized to be >= 0. If <CODE>x</CODE> is the square of a rational number,
|
|
<CODE>sqrt(x)</CODE> will be a rational number, else it will return a
|
|
floating-point approximation.
|
|
</DL>
|
|
|
|
<P>
|
|
The classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE> define the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_boolean sqrtp (const <VAR>type</VAR>& x, <VAR>type</VAR>* root)</CODE>
|
|
<DD>
|
|
This tests whether <CODE>x</CODE> is a perfect square. If so, it returns true
|
|
and the exact square root in <CODE>*root</CODE>, else it returns false.
|
|
</DL>
|
|
|
|
<P>
|
|
Furthermore, for integers, similarly:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_boolean isqrt (const <VAR>type</VAR>& x, <VAR>type</VAR>* root)</CODE>
|
|
<DD>
|
|
<CODE>x</CODE> should be >= 0. This function sets <CODE>*root</CODE> to
|
|
<CODE>floor(sqrt(x))</CODE> and returns the same value as <CODE>sqrtp</CODE>:
|
|
the boolean value <CODE>(expt(*root,2) == x)</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
For <CODE>n</CODE>th roots, the classes <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>
|
|
define the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_boolean rootp (const <VAR>type</VAR>& x, const cl_I& n, <VAR>type</VAR>* root)</CODE>
|
|
<DD>
|
|
<CODE>x</CODE> must be >= 0. <CODE>n</CODE> must be > 0.
|
|
This tests whether <CODE>x</CODE> is an <CODE>n</CODE>th power of a rational number.
|
|
If so, it returns true and the exact root in <CODE>*root</CODE>, else it returns
|
|
false.
|
|
</DL>
|
|
|
|
<P>
|
|
The only square root function which accepts negative numbers is the one
|
|
for class <CODE>cl_N</CODE>:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_N sqrt (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns the square root of <CODE>z</CODE>, as defined by the formula
|
|
<CODE>sqrt(z) = exp(log(z)/2)</CODE>. Conversion to a floating-point type
|
|
or to a complex number are done if necessary. The range of the result is the
|
|
right half plane <CODE>realpart(sqrt(z)) >= 0</CODE>
|
|
including the positive imaginary axis and 0, but excluding
|
|
the negative imaginary axis.
|
|
The result is an exact number only if <CODE>z</CODE> is an exact number.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC27" HREF="cln_toc.html#TOC27">4.8 Transcendental functions</A></H2>
|
|
|
|
<P>
|
|
The transcendental functions return an exact result if the argument
|
|
is exact and the result is exact as well. Otherwise they must return
|
|
inexact numbers even if the argument is exact.
|
|
For example, <CODE>cos(0) = 1</CODE> returns the rational number <CODE>1</CODE>.
|
|
|
|
|
|
|
|
|
|
<H3><A NAME="SEC28" HREF="cln_toc.html#TOC28">4.8.1 Exponential and logarithmic functions</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_R exp (const cl_R& x)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_N exp (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns the exponential function of <CODE>x</CODE>. This is <CODE>e^x</CODE> where
|
|
<CODE>e</CODE> is the base of the natural logarithms. The range of the result
|
|
is the entire complex plane excluding 0.
|
|
|
|
<DT><CODE>cl_R ln (const cl_R& x)</CODE>
|
|
<DD>
|
|
<CODE>x</CODE> must be > 0. Returns the (natural) logarithm of x.
|
|
|
|
<DT><CODE>cl_N log (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns the (natural) logarithm of x. If <CODE>x</CODE> is real and positive,
|
|
this is <CODE>ln(x)</CODE>. In general, <CODE>log(x) = log(abs(x)) + i*phase(x)</CODE>.
|
|
The range of the result is the strip in the complex plane
|
|
<CODE>-pi < imagpart(log(x)) <= pi</CODE>.
|
|
|
|
<DT><CODE>cl_R phase (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns the angle part of <CODE>x</CODE> in its polar representation as a
|
|
complex number. That is, <CODE>phase(x) = atan(realpart(x),imagpart(x))</CODE>.
|
|
This is also the imaginary part of <CODE>log(x)</CODE>.
|
|
The range of the result is the interval <CODE>-pi < phase(x) <= pi</CODE>.
|
|
The result will be an exact number only if <CODE>zerop(x)</CODE> or
|
|
if <CODE>x</CODE> is real and positive.
|
|
|
|
<DT><CODE>cl_R log (const cl_R& a, const cl_R& b)</CODE>
|
|
<DD>
|
|
<CODE>a</CODE> and <CODE>b</CODE> must be > 0. Returns the logarithm of <CODE>a</CODE> with
|
|
respect to base <CODE>b</CODE>. <CODE>log(a,b) = ln(a)/ln(b)</CODE>.
|
|
The result can be exact only if <CODE>a = 1</CODE> or if <CODE>a</CODE> and <CODE>b</CODE>
|
|
are both rational.
|
|
|
|
<DT><CODE>cl_N log (const cl_N& a, const cl_N& b)</CODE>
|
|
<DD>
|
|
Returns the logarithm of <CODE>a</CODE> with respect to base <CODE>b</CODE>.
|
|
<CODE>log(a,b) = log(a)/log(b)</CODE>.
|
|
|
|
<DT><CODE>cl_N expt (const cl_N& x, const cl_N& y)</CODE>
|
|
<DD>
|
|
Exponentiation: Returns <CODE>x^y = exp(y*log(x))</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
The constant e = exp(1) = 2.71828... is returned by the following functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F cl_exp1 (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns e as a float of format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_exp1 (const cl_F& y)</CODE>
|
|
<DD>
|
|
Returns e in the float format of <CODE>y</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_exp1 (void)</CODE>
|
|
<DD>
|
|
Returns e as a float of format <CODE>cl_default_float_format</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC29" HREF="cln_toc.html#TOC29">4.8.2 Trigonometric functions</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_R sin (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>sin(x)</CODE>. The range of the result is the interval
|
|
<CODE>-1 <= sin(x) <= 1</CODE>.
|
|
|
|
<DT><CODE>cl_N sin (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>sin(z)</CODE>. The range of the result is the entire complex plane.
|
|
|
|
<DT><CODE>cl_R cos (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>cos(x)</CODE>. The range of the result is the interval
|
|
<CODE>-1 <= cos(x) <= 1</CODE>.
|
|
|
|
<DT><CODE>cl_N cos (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>cos(z)</CODE>. The range of the result is the entire complex plane.
|
|
|
|
<DT><CODE>struct cl_cos_sin_t { cl_R cos; cl_R sin; };</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_cos_sin_t cl_cos_sin (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns both <CODE>sin(x)</CODE> and <CODE>cos(x)</CODE>. This is more efficient than
|
|
computing them separately. The relation <CODE>cos^2 + sin^2 = 1</CODE> will
|
|
hold only approximately.
|
|
|
|
<DT><CODE>cl_R tan (const cl_R& x)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_N tan (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>tan(x) = sin(x)/cos(x)</CODE>.
|
|
|
|
<DT><CODE>cl_N cis (const cl_R& x)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_N cis (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>exp(i*x)</CODE>. The name <SAMP>`cis'</SAMP> means "cos + i sin", because
|
|
<CODE>e^(i*x) = cos(x) + i*sin(x)</CODE>.
|
|
|
|
<DT><CODE>cl_N asin (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>arcsin(z)</CODE>. This is defined as
|
|
<CODE>arcsin(z) = log(iz+sqrt(1-z^2))/i</CODE> and satisfies
|
|
<CODE>arcsin(-z) = -arcsin(z)</CODE>.
|
|
The range of the result is the strip in the complex domain
|
|
<CODE>-pi/2 <= realpart(arcsin(z)) <= pi/2</CODE>, excluding the numbers
|
|
with <CODE>realpart = -pi/2</CODE> and <CODE>imagpart < 0</CODE> and the numbers
|
|
with <CODE>realpart = pi/2</CODE> and <CODE>imagpart > 0</CODE>.
|
|
|
|
<DT><CODE>cl_N acos (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>arccos(z)</CODE>. This is defined as
|
|
<CODE>arccos(z) = pi/2 - arcsin(z) = log(z+i*sqrt(1-z^2))/i</CODE>
|
|
and satisfies <CODE>arccos(-z) = pi - arccos(z)</CODE>.
|
|
The range of the result is the strip in the complex domain
|
|
<CODE>0 <= realpart(arcsin(z)) <= pi</CODE>, excluding the numbers
|
|
with <CODE>realpart = 0</CODE> and <CODE>imagpart < 0</CODE> and the numbers
|
|
with <CODE>realpart = pi</CODE> and <CODE>imagpart > 0</CODE>.
|
|
|
|
<DT><CODE>cl_R atan (const cl_R& x, const cl_R& y)</CODE>
|
|
<DD>
|
|
Returns the angle of the polar representation of the complex number
|
|
<CODE>x+iy</CODE>. This is <CODE>atan(y/x)</CODE> if <CODE>x>0</CODE>. The range of
|
|
the result is the interval <CODE>-pi < atan(x,y) <= pi</CODE>. The result will
|
|
be an exact number only if <CODE>x > 0</CODE> and <CODE>y</CODE> is the exact <CODE>0</CODE>.
|
|
WARNING: In Common Lisp, this function is called as <CODE>(atan y x)</CODE>,
|
|
with reversed order of arguments.
|
|
|
|
<DT><CODE>cl_R atan (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>arctan(x)</CODE>. This is the same as <CODE>atan(1,x)</CODE>. The range
|
|
of the result is the interval <CODE>-pi/2 < atan(x) < pi/2</CODE>. The result
|
|
will be an exact number only if <CODE>x</CODE> is the exact <CODE>0</CODE>.
|
|
|
|
<DT><CODE>cl_N atan (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>arctan(z)</CODE>. This is defined as
|
|
<CODE>arctan(z) = (log(1+iz)-log(1-iz)) / 2i</CODE> and satisfies
|
|
<CODE>arctan(-z) = -arctan(z)</CODE>. The range of the result is
|
|
the strip in the complex domain
|
|
<CODE>-pi/2 <= realpart(arctan(z)) <= pi/2</CODE>, excluding the numbers
|
|
with <CODE>realpart = -pi/2</CODE> and <CODE>imagpart >= 0</CODE> and the numbers
|
|
with <CODE>realpart = pi/2</CODE> and <CODE>imagpart <= 0</CODE>.
|
|
|
|
</DL>
|
|
|
|
<P>
|
|
The constant pi = 3.14... is returned by the following functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F cl_pi (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns pi as a float of format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_pi (const cl_F& y)</CODE>
|
|
<DD>
|
|
Returns pi in the float format of <CODE>y</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_pi (void)</CODE>
|
|
<DD>
|
|
Returns pi as a float of format <CODE>cl_default_float_format</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC30" HREF="cln_toc.html#TOC30">4.8.3 Hyperbolic functions</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_R sinh (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>sinh(x)</CODE>.
|
|
|
|
<DT><CODE>cl_N sinh (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>sinh(z)</CODE>. The range of the result is the entire complex plane.
|
|
|
|
<DT><CODE>cl_R cosh (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>cosh(x)</CODE>. The range of the result is the interval
|
|
<CODE>cosh(x) >= 1</CODE>.
|
|
|
|
<DT><CODE>cl_N cosh (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>cosh(z)</CODE>. The range of the result is the entire complex plane.
|
|
|
|
<DT><CODE>struct cl_cosh_sinh_t { cl_R cosh; cl_R sinh; };</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_cosh_sinh_t cl_cosh_sinh (const cl_R& x)</CODE>
|
|
<DD>
|
|
Returns both <CODE>sinh(x)</CODE> and <CODE>cosh(x)</CODE>. This is more efficient than
|
|
computing them separately. The relation <CODE>cosh^2 - sinh^2 = 1</CODE> will
|
|
hold only approximately.
|
|
|
|
<DT><CODE>cl_R tanh (const cl_R& x)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_N tanh (const cl_N& x)</CODE>
|
|
<DD>
|
|
Returns <CODE>tanh(x) = sinh(x)/cosh(x)</CODE>.
|
|
|
|
<DT><CODE>cl_N asinh (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>arsinh(z)</CODE>. This is defined as
|
|
<CODE>arsinh(z) = log(z+sqrt(1+z^2))</CODE> and satisfies
|
|
<CODE>arsinh(-z) = -arsinh(z)</CODE>.
|
|
The range of the result is the strip in the complex domain
|
|
<CODE>-pi/2 <= imagpart(arsinh(z)) <= pi/2</CODE>, excluding the numbers
|
|
with <CODE>imagpart = -pi/2</CODE> and <CODE>realpart > 0</CODE> and the numbers
|
|
with <CODE>imagpart = pi/2</CODE> and <CODE>realpart < 0</CODE>.
|
|
|
|
<DT><CODE>cl_N acosh (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>arcosh(z)</CODE>. This is defined as
|
|
<CODE>arcosh(z) = 2*log(sqrt((z+1)/2)+sqrt((z-1)/2))</CODE>.
|
|
The range of the result is the half-strip in the complex domain
|
|
<CODE>-pi < imagpart(arcosh(z)) <= pi, realpart(arcosh(z)) >= 0</CODE>,
|
|
excluding the numbers with <CODE>realpart = 0</CODE> and <CODE>-pi < imagpart < 0</CODE>.
|
|
|
|
<DT><CODE>cl_N atanh (const cl_N& z)</CODE>
|
|
<DD>
|
|
Returns <CODE>artanh(z)</CODE>. This is defined as
|
|
<CODE>artanh(z) = (log(1+z)-log(1-z)) / 2</CODE> and satisfies
|
|
<CODE>artanh(-z) = -artanh(z)</CODE>. The range of the result is
|
|
the strip in the complex domain
|
|
<CODE>-pi/2 <= imagpart(artanh(z)) <= pi/2</CODE>, excluding the numbers
|
|
with <CODE>imagpart = -pi/2</CODE> and <CODE>realpart <= 0</CODE> and the numbers
|
|
with <CODE>imagpart = pi/2</CODE> and <CODE>realpart >= 0</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC31" HREF="cln_toc.html#TOC31">4.8.4 Euler gamma</A></H3>
|
|
|
|
<P>
|
|
Euler's constant C = 0.577... is returned by the following functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F cl_eulerconst (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns Euler's constant as a float of format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_eulerconst (const cl_F& y)</CODE>
|
|
<DD>
|
|
Returns Euler's constant in the float format of <CODE>y</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_eulerconst (void)</CODE>
|
|
<DD>
|
|
Returns Euler's constant as a float of format <CODE>cl_default_float_format</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Catalan's constant G = 0.915... is returned by the following functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F cl_catalanconst (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns Catalan's constant as a float of format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_catalanconst (const cl_F& y)</CODE>
|
|
<DD>
|
|
Returns Catalan's constant in the float format of <CODE>y</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_catalanconst (void)</CODE>
|
|
<DD>
|
|
Returns Catalan's constant as a float of format <CODE>cl_default_float_format</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC32" HREF="cln_toc.html#TOC32">4.8.5 Riemann zeta</A></H3>
|
|
|
|
<P>
|
|
Riemann's zeta function at an integral point <CODE>s>1</CODE> is returned by the
|
|
following functions:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F cl_zeta (int s, cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns Riemann's zeta function at <CODE>s</CODE> as a float of format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_zeta (int s, const cl_F& y)</CODE>
|
|
<DD>
|
|
Returns Riemann's zeta function at <CODE>s</CODE> in the float format of <CODE>y</CODE>.
|
|
|
|
<DT><CODE>cl_F cl_zeta (int s)</CODE>
|
|
<DD>
|
|
Returns Riemann's zeta function at <CODE>s</CODE> as a float of format
|
|
<CODE>cl_default_float_format</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC33" HREF="cln_toc.html#TOC33">4.9 Functions on integers</A></H2>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC34" HREF="cln_toc.html#TOC34">4.9.1 Logical functions</A></H3>
|
|
|
|
<P>
|
|
Integers, when viewed as in two's complement notation, can be thought as
|
|
infinite bit strings where the bits' values eventually are constant.
|
|
For example,
|
|
|
|
<PRE>
|
|
17 = ......00010001
|
|
-6 = ......11111010
|
|
</PRE>
|
|
|
|
<P>
|
|
The logical operations view integers as such bit strings and operate
|
|
on each of the bit positions in parallel.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I lognot (const cl_I& x)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I operator ~ (const cl_I& x)</CODE>
|
|
<DD>
|
|
Logical not, like <CODE>~x</CODE> in C. This is the same as <CODE>-1-x</CODE>.
|
|
|
|
<DT><CODE>cl_I logand (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I operator & (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Logical and, like <CODE>x & y</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logior (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I operator | (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Logical (inclusive) or, like <CODE>x | y</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logxor (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I operator ^ (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Exclusive or, like <CODE>x ^ y</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logeqv (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Bitwise equivalence, like <CODE>~(x ^ y)</CODE> in C.
|
|
|
|
<DT><CODE>cl_I lognand (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Bitwise not and, like <CODE>~(x & y)</CODE> in C.
|
|
|
|
<DT><CODE>cl_I lognor (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Bitwise not or, like <CODE>~(x | y)</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logandc1 (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Logical and, complementing the first argument, like <CODE>~x & y</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logandc2 (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Logical and, complementing the second argument, like <CODE>x & ~y</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logorc1 (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Logical or, complementing the first argument, like <CODE>~x | y</CODE> in C.
|
|
|
|
<DT><CODE>cl_I logorc2 (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Logical or, complementing the second argument, like <CODE>x | ~y</CODE> in C.
|
|
</DL>
|
|
|
|
<P>
|
|
These operations are all available though the function
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I boole (cl_boole op, const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
</DL>
|
|
<P>
|
|
where <CODE>op</CODE> must have one of the 16 values (each one stands for a function
|
|
which combines two bits into one bit): <CODE>boole_clr</CODE>, <CODE>boole_set</CODE>,
|
|
<CODE>boole_1</CODE>, <CODE>boole_2</CODE>, <CODE>boole_c1</CODE>, <CODE>boole_c2</CODE>,
|
|
<CODE>boole_and</CODE>, <CODE>boole_ior</CODE>, <CODE>boole_xor</CODE>, <CODE>boole_eqv</CODE>,
|
|
<CODE>boole_nand</CODE>, <CODE>boole_nor</CODE>, <CODE>boole_andc1</CODE>, <CODE>boole_andc2</CODE>,
|
|
<CODE>boole_orc1</CODE>, <CODE>boole_orc2</CODE>.
|
|
|
|
|
|
<P>
|
|
Other functions that view integers as bit strings:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_boolean logtest (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Returns true if some bit is set in both <CODE>x</CODE> and <CODE>y</CODE>, i.e. if
|
|
<CODE>logand(x,y) != 0</CODE>.
|
|
|
|
<DT><CODE>cl_boolean logbitp (const cl_I& n, const cl_I& x)</CODE>
|
|
<DD>
|
|
Returns true if the <CODE>n</CODE>th bit (from the right) of <CODE>x</CODE> is set.
|
|
Bit 0 is the least significant bit.
|
|
|
|
<DT><CODE>uintL logcount (const cl_I& x)</CODE>
|
|
<DD>
|
|
Returns the number of one bits in <CODE>x</CODE>, if <CODE>x</CODE> >= 0, or
|
|
the number of zero bits in <CODE>x</CODE>, if <CODE>x</CODE> < 0.
|
|
</DL>
|
|
|
|
<P>
|
|
The following functions operate on intervals of bits in integers.
|
|
The type
|
|
|
|
<PRE>
|
|
struct cl_byte { uintL size; uintL position; };
|
|
</PRE>
|
|
|
|
<P>
|
|
represents the bit interval containing the bits
|
|
<CODE>position</CODE>...<CODE>position+size-1</CODE> of an integer.
|
|
The constructor <CODE>cl_byte(size,position)</CODE> constructs a <CODE>cl_byte</CODE>.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I ldb (const cl_I& n, const cl_byte& b)</CODE>
|
|
<DD>
|
|
extracts the bits of <CODE>n</CODE> described by the bit interval <CODE>b</CODE>
|
|
and returns them as a nonnegative integer with <CODE>b.size</CODE> bits.
|
|
|
|
<DT><CODE>cl_boolean ldb_test (const cl_I& n, const cl_byte& b)</CODE>
|
|
<DD>
|
|
Returns true if some bit described by the bit interval <CODE>b</CODE> is set in
|
|
<CODE>n</CODE>.
|
|
|
|
<DT><CODE>cl_I dpb (const cl_I& newbyte, const cl_I& n, const cl_byte& b)</CODE>
|
|
<DD>
|
|
Returns <CODE>n</CODE>, with the bits described by the bit interval <CODE>b</CODE>
|
|
replaced by <CODE>newbyte</CODE>. Only the lowest <CODE>b.size</CODE> bits of
|
|
<CODE>newbyte</CODE> are relevant.
|
|
</DL>
|
|
|
|
<P>
|
|
The functions <CODE>ldb</CODE> and <CODE>dpb</CODE> implicitly shift. The following
|
|
functions are their counterparts without shifting:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I mask_field (const cl_I& n, const cl_byte& b)</CODE>
|
|
<DD>
|
|
returns an integer with the bits described by the bit interval <CODE>b</CODE>
|
|
copied from the corresponding bits in <CODE>n</CODE>, the other bits zero.
|
|
|
|
<DT><CODE>cl_I deposit_field (const cl_I& newbyte, const cl_I& n, const cl_byte& b)</CODE>
|
|
<DD>
|
|
returns an integer where the bits described by the bit interval <CODE>b</CODE>
|
|
come from <CODE>newbyte</CODE> and the other bits come from <CODE>n</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
The following relations hold:
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<CODE>ldb (n, b) = mask_field(n, b) >> b.position</CODE>,
|
|
<LI>
|
|
|
|
<CODE>dpb (newbyte, n, b) = deposit_field (newbyte << b.position, n, b)</CODE>,
|
|
<LI>
|
|
|
|
<CODE>deposit_field(newbyte,n,b) = n ^ mask_field(n,b) ^ mask_field(new_byte,b)</CODE>.
|
|
</UL>
|
|
|
|
<P>
|
|
The following operations on integers as bit strings are efficient shortcuts
|
|
for common arithmetic operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_boolean oddp (const cl_I& x)</CODE>
|
|
<DD>
|
|
Returns true if the least significant bit of <CODE>x</CODE> is 1. Equivalent to
|
|
<CODE>mod(x,2) != 0</CODE>.
|
|
|
|
<DT><CODE>cl_boolean evenp (const cl_I& x)</CODE>
|
|
<DD>
|
|
Returns true if the least significant bit of <CODE>x</CODE> is 0. Equivalent to
|
|
<CODE>mod(x,2) == 0</CODE>.
|
|
|
|
<DT><CODE>cl_I operator << (const cl_I& x, const cl_I& n)</CODE>
|
|
<DD>
|
|
Shifts <CODE>x</CODE> by <CODE>n</CODE> bits to the left. <CODE>n</CODE> should be >=0.
|
|
Equivalent to <CODE>x * expt(2,n)</CODE>.
|
|
|
|
<DT><CODE>cl_I operator >> (const cl_I& x, const cl_I& n)</CODE>
|
|
<DD>
|
|
Shifts <CODE>x</CODE> by <CODE>n</CODE> bits to the right. <CODE>n</CODE> should be >=0.
|
|
Bits shifted out to the right are thrown away.
|
|
Equivalent to <CODE>floor(x / expt(2,n))</CODE>.
|
|
|
|
<DT><CODE>cl_I ash (const cl_I& x, const cl_I& y)</CODE>
|
|
<DD>
|
|
Shifts <CODE>x</CODE> by <CODE>y</CODE> bits to the left (if <CODE>y</CODE>>=0) or
|
|
by <CODE>-y</CODE> bits to the right (if <CODE>y</CODE><=0). In other words, this
|
|
returns <CODE>floor(x * expt(2,y))</CODE>.
|
|
|
|
<DT><CODE>uintL integer_length (const cl_I& x)</CODE>
|
|
<DD>
|
|
Returns the number of bits (excluding the sign bit) needed to represent <CODE>x</CODE>
|
|
in two's complement notation. This is the smallest n >= 0 such that
|
|
-2^n <= x < 2^n. If x > 0, this is the unique n > 0 such that
|
|
2^(n-1) <= x < 2^n.
|
|
|
|
<DT><CODE>uintL ord2 (const cl_I& x)</CODE>
|
|
<DD>
|
|
<CODE>x</CODE> must be non-zero. This function returns the number of 0 bits at the
|
|
right of <CODE>x</CODE> in two's complement notation. This is the largest n >= 0
|
|
such that 2^n divides <CODE>x</CODE>.
|
|
|
|
<DT><CODE>uintL power2p (const cl_I& x)</CODE>
|
|
<DD>
|
|
<CODE>x</CODE> must be > 0. This function checks whether <CODE>x</CODE> is a power of 2.
|
|
If <CODE>x</CODE> = 2^(n-1), it returns n. Else it returns 0.
|
|
(See also the function <CODE>logp</CODE>.)
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC35" HREF="cln_toc.html#TOC35">4.9.2 Number theoretic functions</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>uint32 gcd (uint32 a, uint32 b)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I gcd (const cl_I& a, const cl_I& b)</CODE>
|
|
<DD>
|
|
This function returns the greatest common divisor of <CODE>a</CODE> and <CODE>b</CODE>,
|
|
normalized to be >= 0.
|
|
|
|
<DT><CODE>cl_I xgcd (const cl_I& a, const cl_I& b, cl_I* u, cl_I* v)</CODE>
|
|
<DD>
|
|
This function ("extended gcd") returns the greatest common divisor <CODE>g</CODE> of
|
|
<CODE>a</CODE> and <CODE>b</CODE> and at the same time the representation of <CODE>g</CODE>
|
|
as an integral linear combination of <CODE>a</CODE> and <CODE>b</CODE>:
|
|
<CODE>u</CODE> and <CODE>v</CODE> with <CODE>u*a+v*b = g</CODE>, <CODE>g</CODE> >= 0.
|
|
<CODE>u</CODE> and <CODE>v</CODE> will be normalized to be of smallest possible absolute
|
|
value, in the following sense: If <CODE>a</CODE> and <CODE>b</CODE> are non-zero, and
|
|
<CODE>abs(a) != abs(b)</CODE>, <CODE>u</CODE> and <CODE>v</CODE> will satisfy the inequalities
|
|
<CODE>abs(u) <= abs(b)/(2*g)</CODE>, <CODE>abs(v) <= abs(a)/(2*g)</CODE>.
|
|
|
|
<DT><CODE>cl_I lcm (const cl_I& a, const cl_I& b)</CODE>
|
|
<DD>
|
|
This function returns the least common multiple of <CODE>a</CODE> and <CODE>b</CODE>,
|
|
normalized to be >= 0.
|
|
|
|
<DT><CODE>cl_boolean logp (const cl_I& a, const cl_I& b, cl_RA* l)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_boolean logp (const cl_RA& a, const cl_RA& b, cl_RA* l)</CODE>
|
|
<DD>
|
|
<CODE>a</CODE> must be > 0. <CODE>b</CODE> must be >0 and != 1. If log(a,b) is
|
|
rational number, this function returns true and sets *l = log(a,b), else
|
|
it returns false.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC36" HREF="cln_toc.html#TOC36">4.9.3 Combinatorial functions</A></H3>
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_I factorial (uintL n)</CODE>
|
|
<DD>
|
|
<CODE>n</CODE> must be a small integer >= 0. This function returns the factorial
|
|
<CODE>n</CODE>! = <CODE>1*2*...*n</CODE>.
|
|
|
|
<DT><CODE>cl_I doublefactorial (uintL n)</CODE>
|
|
<DD>
|
|
<CODE>n</CODE> must be a small integer >= 0. This function returns the
|
|
doublefactorial <CODE>n</CODE>!! = <CODE>1*3*...*n</CODE> or
|
|
<CODE>n</CODE>!! = <CODE>2*4*...*n</CODE>, respectively.
|
|
|
|
<DT><CODE>cl_I binomial (uintL n, uintL k)</CODE>
|
|
<DD>
|
|
<CODE>n</CODE> and <CODE>k</CODE> must be small integers >= 0. This function returns the
|
|
binomial coefficient
|
|
(<CODE>n</CODE> choose <CODE>k</CODE>) = <CODE>n</CODE>! / <CODE>k</CODE>! <CODE>(n-k)</CODE>!
|
|
for 0 <= k <= n, 0 else.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC37" HREF="cln_toc.html#TOC37">4.10 Functions on floating-point numbers</A></H2>
|
|
|
|
<P>
|
|
Recall that a floating-point number consists of a sign <CODE>s</CODE>, an
|
|
exponent <CODE>e</CODE> and a mantissa <CODE>m</CODE>. The value of the number is
|
|
<CODE>(-1)^s * 2^e * m</CODE>.
|
|
|
|
|
|
<P>
|
|
Each of the classes
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>
|
|
defines the following operations.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR> scale_float (const <VAR>type</VAR>& x, sintL delta)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR> scale_float (const <VAR>type</VAR>& x, const cl_I& delta)</CODE>
|
|
<DD>
|
|
Returns <CODE>x*2^delta</CODE>. This is more efficient than an explicit multiplication
|
|
because it copies <CODE>x</CODE> and modifies the exponent.
|
|
</DL>
|
|
|
|
<P>
|
|
The following functions provide an abstract interface to the underlying
|
|
representation of floating-point numbers.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>sintL float_exponent (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the exponent <CODE>e</CODE> of <CODE>x</CODE>.
|
|
For <CODE>x = 0.0</CODE>, this is 0. For <CODE>x</CODE> non-zero, this is the unique
|
|
integer with <CODE>2^(e-1) <= abs(x) < 2^e</CODE>.
|
|
|
|
<DT><CODE>sintL float_radix (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the base of the floating-point representation. This is always <CODE>2</CODE>.
|
|
|
|
<DT><CODE><VAR>type</VAR> float_sign (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the sign <CODE>s</CODE> of <CODE>x</CODE> as a float. The value is 1 for
|
|
<CODE>x</CODE> >= 0, -1 for <CODE>x</CODE> < 0.
|
|
|
|
<DT><CODE>uintL float_digits (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the number of mantissa bits in the floating-point representation
|
|
of <CODE>x</CODE>, including the hidden bit. The value only depends on the type
|
|
of <CODE>x</CODE>, not on its value.
|
|
|
|
<DT><CODE>uintL float_precision (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the number of significant mantissa bits in the floating-point
|
|
representation of <CODE>x</CODE>. Since denormalized numbers are not supported,
|
|
this is the same as <CODE>float_digits(x)</CODE> if <CODE>x</CODE> is non-zero, and
|
|
0 if <CODE>x</CODE> = 0.
|
|
</DL>
|
|
|
|
<P>
|
|
The complete internal representation of a float is encoded in the type
|
|
<CODE>cl_decoded_float</CODE> (or <CODE>cl_decoded_sfloat</CODE>, <CODE>cl_decoded_ffloat</CODE>,
|
|
<CODE>cl_decoded_dfloat</CODE>, <CODE>cl_decoded_lfloat</CODE>, respectively), defined by
|
|
|
|
<PRE>
|
|
struct cl_decoded_<VAR>type</VAR>float {
|
|
<VAR>type</VAR> mantissa; cl_I exponent; <VAR>type</VAR> sign;
|
|
};
|
|
</PRE>
|
|
|
|
<P>
|
|
and returned by the function
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_decoded_<VAR>type</VAR>float decode_float (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
For <CODE>x</CODE> non-zero, this returns <CODE>(-1)^s</CODE>, <CODE>e</CODE>, <CODE>m</CODE> with
|
|
<CODE>x = (-1)^s * 2^e * m</CODE> and <CODE>0.5 <= m < 1.0</CODE>. For <CODE>x</CODE> = 0,
|
|
it returns <CODE>(-1)^s</CODE>=1, <CODE>e</CODE>=0, <CODE>m</CODE>=0.
|
|
<CODE>e</CODE> is the same as returned by the function <CODE>float_exponent</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
A complete decoding in terms of integers is provided as type
|
|
|
|
<PRE>
|
|
struct cl_idecoded_float {
|
|
cl_I mantissa; cl_I exponent; cl_I sign;
|
|
};
|
|
</PRE>
|
|
|
|
<P>
|
|
by the following function:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_idecoded_float integer_decode_float (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
For <CODE>x</CODE> non-zero, this returns <CODE>(-1)^s</CODE>, <CODE>e</CODE>, <CODE>m</CODE> with
|
|
<CODE>x = (-1)^s * 2^e * m</CODE> and <CODE>m</CODE> an integer with <CODE>float_digits(x)</CODE>
|
|
bits. For <CODE>x</CODE> = 0, it returns <CODE>(-1)^s</CODE>=1, <CODE>e</CODE>=0, <CODE>m</CODE>=0.
|
|
WARNING: The exponent <CODE>e</CODE> is not the same as the one returned by
|
|
the functions <CODE>decode_float</CODE> and <CODE>float_exponent</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Some other function, implemented only for class <CODE>cl_F</CODE>:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F float_sign (const cl_F& x, const cl_F& y)</CODE>
|
|
<DD>
|
|
This returns a floating point number whose precision and absolute value
|
|
is that of <CODE>y</CODE> and whose sign is that of <CODE>x</CODE>. If <CODE>x</CODE> is
|
|
zero, it is treated as positive. Same for <CODE>y</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC38" HREF="cln_toc.html#TOC38">4.11 Conversion functions</A></H2>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC39" HREF="cln_toc.html#TOC39">4.11.1 Conversion to floating-point numbers</A></H3>
|
|
|
|
<P>
|
|
The type <CODE>cl_float_format_t</CODE> describes a floating-point format.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_float_format_t cl_float_format (uintL n)</CODE>
|
|
<DD>
|
|
Returns the smallest float format which guarantees at least <CODE>n</CODE>
|
|
decimal digits in the mantissa (after the decimal point).
|
|
|
|
<DT><CODE>cl_float_format_t cl_float_format (const cl_F& x)</CODE>
|
|
<DD>
|
|
Returns the floating point format of <CODE>x</CODE>.
|
|
|
|
<DT><CODE>cl_float_format_t cl_default_float_format</CODE>
|
|
<DD>
|
|
Global variable: the default float format used when converting rational numbers
|
|
to floats.
|
|
</DL>
|
|
|
|
<P>
|
|
To convert a real number to a float, each of the types
|
|
<CODE>cl_R</CODE>, <CODE>cl_F</CODE>, <CODE>cl_I</CODE>, <CODE>cl_RA</CODE>,
|
|
<CODE>int</CODE>, <CODE>unsigned int</CODE>, <CODE>float</CODE>, <CODE>double</CODE>
|
|
defines the following operations:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F cl_float (const <VAR>type</VAR>&x, cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns <CODE>x</CODE> as a float of format <CODE>f</CODE>.
|
|
<DT><CODE>cl_F cl_float (const <VAR>type</VAR>&x, const cl_F& y)</CODE>
|
|
<DD>
|
|
Returns <CODE>x</CODE> in the float format of <CODE>y</CODE>.
|
|
<DT><CODE>cl_F cl_float (const <VAR>type</VAR>&x)</CODE>
|
|
<DD>
|
|
Returns <CODE>x</CODE> as a float of format <CODE>cl_default_float_format</CODE> if
|
|
it is an exact number, or <CODE>x</CODE> itself if it is already a float.
|
|
</DL>
|
|
|
|
<P>
|
|
Of course, converting a number to a float can lose precision.
|
|
|
|
|
|
<P>
|
|
Every floating-point format has some characteristic numbers:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_F most_positive_float (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns the largest (most positive) floating point number in float format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F most_negative_float (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns the smallest (most negative) floating point number in float format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F least_positive_float (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns the least positive floating point number (i.e. > 0 but closest to 0)
|
|
in float format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F least_negative_float (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns the least negative floating point number (i.e. < 0 but closest to 0)
|
|
in float format <CODE>f</CODE>.
|
|
|
|
<DT><CODE>cl_F float_epsilon (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns the smallest floating point number e > 0 such that <CODE>1+e != 1</CODE>.
|
|
|
|
<DT><CODE>cl_F float_negative_epsilon (cl_float_format_t f)</CODE>
|
|
<DD>
|
|
Returns the smallest floating point number e > 0 such that <CODE>1-e != 1</CODE>.
|
|
</DL>
|
|
|
|
|
|
|
|
<H3><A NAME="SEC40" HREF="cln_toc.html#TOC40">4.11.2 Conversion to rational numbers</A></H3>
|
|
|
|
<P>
|
|
Each of the classes <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_F</CODE>
|
|
defines the following operation:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_RA rational (const <VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
Returns the value of <CODE>x</CODE> as an exact number. If <CODE>x</CODE> is already
|
|
an exact number, this is <CODE>x</CODE>. If <CODE>x</CODE> is a floating-point number,
|
|
the value is a rational number whose denominator is a power of 2.
|
|
</DL>
|
|
|
|
<P>
|
|
In order to convert back, say, <CODE>(cl_F)(cl_R)"1/3"</CODE> to <CODE>1/3</CODE>, there is
|
|
the function
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>cl_RA rationalize (const cl_R& x)</CODE>
|
|
<DD>
|
|
If <CODE>x</CODE> is a floating-point number, it actually represents an interval
|
|
of real numbers, and this function returns the rational number with
|
|
smallest denominator (and smallest numerator, in magnitude)
|
|
which lies in this interval.
|
|
If <CODE>x</CODE> is already an exact number, this function returns <CODE>x</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
If <CODE>x</CODE> is any float, one has
|
|
|
|
|
|
|
|
<UL>
|
|
<LI>
|
|
|
|
<CODE>cl_float(rational(x),x) = x</CODE>
|
|
<LI>
|
|
|
|
<CODE>cl_float(rationalize(x),x) = x</CODE>
|
|
</UL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC41" HREF="cln_toc.html#TOC41">4.12 Random number generators</A></H2>
|
|
|
|
<P>
|
|
A random generator is a machine which produces (pseudo-)random numbers.
|
|
The include file <CODE><cl_random.h></CODE> defines a class <CODE>cl_random_state</CODE>
|
|
which contains the state of a random generator. If you make a copy
|
|
of the random number generator, the original one and the copy will produce
|
|
the same sequence of random numbers.
|
|
|
|
|
|
<P>
|
|
The following functions return (pseudo-)random numbers in different formats.
|
|
Calling one of these modifies the state of the random number generator in
|
|
a complicated but deterministic way.
|
|
|
|
|
|
<P>
|
|
The global variable
|
|
|
|
<PRE>
|
|
cl_random_state cl_default_random_state
|
|
</PRE>
|
|
|
|
<P>
|
|
contains a default random number generator. It is used when the functions
|
|
below are called without <CODE>cl_random_state</CODE> argument.
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE>uint32 random32 (cl_random_state& randomstate)</CODE>
|
|
<DD>
|
|
<DT><CODE>uint32 random32 ()</CODE>
|
|
<DD>
|
|
Returns a random unsigned 32-bit number. All bits are equally random.
|
|
|
|
<DT><CODE>cl_I random_I (cl_random_state& randomstate, const cl_I& n)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_I random_I (const cl_I& n)</CODE>
|
|
<DD>
|
|
<CODE>n</CODE> must be an integer > 0. This function returns a random integer <CODE>x</CODE>
|
|
in the range <CODE>0 <= x < n</CODE>.
|
|
|
|
<DT><CODE>cl_F random_F (cl_random_state& randomstate, const cl_F& n)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_F random_F (const cl_F& n)</CODE>
|
|
<DD>
|
|
<CODE>n</CODE> must be a float > 0. This function returns a random floating-point
|
|
number of the same format as <CODE>n</CODE> in the range <CODE>0 <= x < n</CODE>.
|
|
|
|
<DT><CODE>cl_R random_R (cl_random_state& randomstate, const cl_R& n)</CODE>
|
|
<DD>
|
|
<DT><CODE>cl_R random_R (const cl_R& n)</CODE>
|
|
<DD>
|
|
Behaves like <CODE>random_I</CODE> if <CODE>n</CODE> is an integer and like <CODE>random_F</CODE>
|
|
if <CODE>n</CODE> is a float.
|
|
</DL>
|
|
|
|
|
|
|
|
<H2><A NAME="SEC42" HREF="cln_toc.html#TOC42">4.13 Obfuscating operators</A></H2>
|
|
|
|
<P>
|
|
The modifying C/C++ operators <CODE>+=</CODE>, <CODE>-=</CODE>, <CODE>*=</CODE>, <CODE>/=</CODE>,
|
|
<CODE>&=</CODE>, <CODE>|=</CODE>, <CODE>^=</CODE>, <CODE><<=</CODE>, <CODE>>>=</CODE>
|
|
are not available by default because their
|
|
use tends to make programs unreadable. It is trivial to get away without
|
|
them. However, if you feel that you absolutely need these operators
|
|
to get happy, then add
|
|
|
|
<PRE>
|
|
#define WANT_OBFUSCATING_OPERATORS
|
|
</PRE>
|
|
|
|
<P>
|
|
to the beginning of your source files, before the inclusion of any CLN
|
|
include files. This flag will enable the following operators:
|
|
|
|
|
|
<P>
|
|
For the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR>& operator += (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator -= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator *= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator /= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
For the class <CODE>cl_I</CODE>:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR>& operator += (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator -= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator *= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator &= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator |= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator ^= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator <<= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
<DT><CODE><VAR>type</VAR>& operator >>= (<VAR>type</VAR>&, const <VAR>type</VAR>&)</CODE>
|
|
<DD>
|
|
</DL>
|
|
|
|
<P>
|
|
For the classes <CODE>cl_N</CODE>, <CODE>cl_R</CODE>, <CODE>cl_RA</CODE>, <CODE>cl_I</CODE>,
|
|
<CODE>cl_F</CODE>, <CODE>cl_SF</CODE>, <CODE>cl_FF</CODE>, <CODE>cl_DF</CODE>, <CODE>cl_LF</CODE>:
|
|
|
|
|
|
<DL COMPACT>
|
|
|
|
<DT><CODE><VAR>type</VAR>& operator ++ (<VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
The prefix operator <CODE>++x</CODE>.
|
|
|
|
<DT><CODE>void operator ++ (<VAR>type</VAR>& x, int)</CODE>
|
|
<DD>
|
|
The postfix operator <CODE>x++</CODE>.
|
|
|
|
<DT><CODE><VAR>type</VAR>& operator -- (<VAR>type</VAR>& x)</CODE>
|
|
<DD>
|
|
The prefix operator <CODE>--x</CODE>.
|
|
|
|
<DT><CODE>void operator -- (<VAR>type</VAR>& x, int)</CODE>
|
|
<DD>
|
|
The postfix operator <CODE>x--</CODE>.
|
|
</DL>
|
|
|
|
<P>
|
|
Note that by using these obfuscating operators, you wouldn't gain efficiency:
|
|
In CLN <SAMP>`x += y;'</SAMP> is exactly the same as <SAMP>`x = x+y;'</SAMP>, not more
|
|
efficient.
|
|
|
|
|
|
<P><HR><P>
|
|
Go to the <A HREF="cln_1.html">first</A>, <A HREF="cln_3.html">previous</A>, <A HREF="cln_5.html">next</A>, <A HREF="cln_13.html">last</A> section, <A HREF="cln_toc.html">table of contents</A>.
|
|
</BODY>
|
|
</HTML>
|