version 1.1.1.1, 2001/10/02 11:16:58 |
version 1.2, 2002/09/11 07:26:43 |
Line 46 statement of a main program should be to initialize th |
|
Line 46 statement of a main program should be to initialize th |
|
particular the PARI stack which will be both a scratchboard and a repository |
particular the PARI stack which will be both a scratchboard and a repository |
for computed objects. This is done with a call to the function |
for computed objects. This is done with a call to the function |
|
|
\fun{void}{pari_init}{long size, long maxprime)} |
\fun{void}{pari_init}{long size, ulong maxprime)} |
|
|
\noindent The first argument is the number of bytes given to PARI to work |
\noindent The first argument is the number of bytes given to PARI to work |
with (it should not reasonably be taken below 500000), and the second is the |
with (it should not reasonably be taken below 500000), and the second is the |
Line 105 $\bullet$ access to all the built-in functions of the |
|
Line 105 $\bullet$ access to all the built-in functions of the |
|
These are declared to the outside world when you include \kbd{pari.h}, but |
These are declared to the outside world when you include \kbd{pari.h}, but |
need the above things to function properly. So if you forget the call to |
need the above things to function properly. So if you forget the call to |
\tet{pari_init}, you will immediately get a fatal error when running your |
\tet{pari_init}, you will immediately get a fatal error when running your |
program (usually a segmentation fault). |
program. |
|
|
\section{Important technical notes} |
\section{Important technical notes} |
|
|
|
|
\kbdsidx{un}% |
\kbdsidx{un}% |
\kbdsidx{lpolx} |
\kbdsidx{lpolx} |
In general, replacing a leading \kbd{g} by an \kbd{l} in the name of a PARI |
In general, replacing a leading \kbd{g} by an \kbd{l} in the name of a PARI |
function will typecast the result to \kbd{long}. Note that \kbd{ldiv} is an |
function will typecast the result to \kbd{long}. Note that \kbd{ldiv} is an ANSI C |
ANSI C function which is is hidden in PARI by a macro of the same name |
function which is hidden in PARI by a macro of the same name representing |
representing \kbd{(long)gdiv}. |
\kbd{(long)gdiv}. |
|
|
The macro $\teb{coeff}(x,m,n)$ exists with exactly the meaning of \kbd{x[m,n]} |
The macro $\teb{coeff}(x,m,n)$ exists with exactly the meaning of \kbd{x[m,n]} |
under GP when \kbd{x} is a matrix. This is a purely syntactical trick |
under GP when \kbd{x} is a matrix. This is a purely syntactical trick |
Line 344 of efficiency, no checking is done in the function \kb |
|
Line 344 of efficiency, no checking is done in the function \kb |
|
disasters will occur if you give an incorrect length. |
disasters will occur if you give an incorrect length. |
|
|
\misctitle{Notes}: |
\misctitle{Notes}: |
1) The main use of this function is to prepare for later assigments |
1) The main use of this function is to prepare for later assignments |
(see \secref{se:assign}). Most of the time you will use \kbd{GEN} objects |
(see \secref{se:assign}). Most of the time you will use \kbd{GEN} objects |
as they are created and returned by PARI functions. In this case you don't need |
as they are created and returned by PARI functions. In this case you don't need |
to use \kbd{cgetg} to create space to hold them. |
to use \kbd{cgetg} to create space to hold them. |
|
|
|
|
\fun{void}{gaffsg}{long s, GEN y} |
\fun{void}{gaffsg}{long s, GEN y} |
|
|
\misctitle{Note}: due to the requirements mentionned above, it's usually |
\misctitle{Note}: due to the requirements mentioned above, it's usually |
a bad idea to use \tet{gaffect} statements. Two exceptions: |
a bad idea to use \tet{gaffect} statements. Two exceptions: |
|
|
$\bullet$ for simple objects (e.g.~leaves) whose size is controlled, they can |
$\bullet$ for simple objects (e.g.~leaves) whose size is controlled, they can |
Line 723 is less efficient than either \tet{gerepileupto} or \t |
|
Line 723 is less efficient than either \tet{gerepileupto} or \t |
|
To cope with complicated cases where many objects have to be |
To cope with complicated cases where many objects have to be |
preserved, you can use |
preserved, you can use |
|
|
\fun{void}{gerepilemany}{ulong ltop, GEN *gptr[], long n)} |
\fun{void}{gerepileall}{ulong ltop, int n, ...} |
|
|
\noindent which cleans up the most recent part of the stack (between |
\noindent where the routine expects $n$ further arguments, which are the {\it |
\kbd{ltop} and \kbd{avma}). All the \kbd{GEN}s pointed at by the elements of |
addresses} of the \kbd{GEN}s you want to preserve. It cleans up the most |
the array \kbd{gptr} (of length \kbd{n}) are updated. A copy is done just |
recent part of the stack (between \kbd{ltop} and \kbd{avma}), updating all |
before the cleaning to preserve them, so they don't need to be connected |
the \kbd{GEN}s added to the argument list. A copy is done just before the |
before the call. With \kbd{gerepilecopy}, this is the most robust of the |
cleaning to preserve them, so they don't need to be connected before the |
\kbd{gerepile} functions (the less prone to user error), but also the |
call. With \kbd{gerepilecopy}, this is the most robust of the \kbd{gerepile} |
slowest. |
functions (the less prone to user error), but also the slowest. |
|
|
|
An alternative, unnecessarily complicated, syntax is given by |
|
|
|
\fun{void}{gerepilemany}{ulong ltop, GEN *gptr[], int n} |
|
|
|
\noindent which works exactly as above, except that the preserved \kbd{GEN}s |
|
are the elements of the array \kbd{gptr} (of length $n$): \kbd{gptr[0]}, |
|
\kbd{gptr[1]}, \dots, \kbd{gptr[$n$-1]}. |
|
|
\noindent$\bullet$ More efficient, but tricky to use is |
\noindent$\bullet$ More efficient, but tricky to use is |
|
|
\fun{void}{gerepilemanysp}{ulong ltop, ulong lbot, GEN *gptr[], long n} |
\fun{void}{gerepilemanysp}{ulong ltop, ulong lbot, GEN *gptr[], int n} |
|
|
\noindent which cleans the stack between \kbd{lbot} and \kbd{ltop} and |
\noindent which cleans the stack between \kbd{lbot} and \kbd{ltop} and |
updates the \kbd{GEN}s pointed at by the elements of \kbd{gptr} without doing |
updates the \kbd{GEN}s pointed at by the elements of \kbd{gptr} without doing |
Line 907 assume anything about the stack: the garbage can be di |
|
Line 915 assume anything about the stack: the garbage can be di |
|
\kbd{z1}, \kbd{z2} need not be at the bottom of the stack. If all of these |
\kbd{z1}, \kbd{z2} need not be at the bottom of the stack. If all of these |
assumptions are in fact satisfied, then we can call \kbd{gerepilemanysp} |
assumptions are in fact satisfied, then we can call \kbd{gerepilemanysp} |
instead, which will usually be faster since we don't need the initial copy |
instead, which will usually be faster since we don't need the initial copy |
(on the other hand, it is less cache friendly). |
(on the other hand, it is less cache friendly). The whole thing could (and |
|
should) be abbreviated as |
|
\bprog |
|
gerepileall(ltop, 2, &z1, &z2) |
|
@eprog |
|
so that the array \kbd{gptr} is not needed anymore. |
|
|
Another important usage is ``random'' garbage collection during loops |
Another important usage is ``random'' garbage collection during loops |
whose size requirements we cannot (or don't bother to) control in advance: |
whose size requirements we cannot (or don't bother to) control in advance: |
Line 921 whose size requirements we cannot (or don't bother to) |
|
Line 934 whose size requirements we cannot (or don't bother to) |
|
garbage(); y = anything() |
garbage(); y = anything() |
garbage(); |
garbage(); |
if (avma < limit) /*@Ccom memory is running low (half spent since entry) */ |
if (avma < limit) /*@Ccom memory is running low (half spent since entry) */ |
{ |
gerepileall(ltop, 2, &x, &y); |
GEN *gptr[2]; |
|
gptr[0] = &x; gptr[1] = &y; |
|
gerepilemany(ltop, gptr, 2); |
|
} |
|
} |
} |
@eprog |
@eprog |
\noindent Here we assume that only \kbd{x} and \kbd{y} are needed from one |
\noindent Here we assume that only \kbd{x} and \kbd{y} are needed from one |
Line 1081 the highest order longword. |
|
Line 1090 the highest order longword. |
|
|
|
\fun{long}{mod2}{GEN x}, \fun{}{mod4}{x}, and so on up to \fun{}{mod64}{x}, |
\fun{long}{mod2}{GEN x}, \fun{}{mod4}{x}, and so on up to \fun{}{mod64}{x}, |
which give the residue class of \kbd{x} modulo the corresponding power of |
which give the residue class of \kbd{x} modulo the corresponding power of |
2, for {\it positive\/}~\kbd{x} (you will obtain weird results if you use |
2, for {\it positive\/}~\kbd{x}. By definition, $\kbd{mod}n(x) := |
these on the integer 0 or on negative numbers). |
\kbd{mod}n(|x|)$ for $x < 0$ (the macros disregard the sign), and the |
|
result is undefined if $x = 0$. |
|
|
These macros directly access the binary data and are thus much faster than |
These macros directly access the binary data and are thus much faster than |
the generic modulo functions. Besides, they return long integers instead of |
the generic modulo functions. Besides, they return long integers instead of |
Line 1090 the generic modulo functions. Besides, they return lon |
|
Line 1100 the generic modulo functions. Besides, they return lon |
|
|
|
\subsec{Type \typ{REAL} (real number):}\kbdsidx{t_REAL}\sidx{real number} |
\subsec{Type \typ{REAL} (real number):}\kbdsidx{t_REAL}\sidx{real number} |
this type has a second codeword z[1] which also encodes its sign (obtained |
this type has a second codeword z[1] which also encodes its sign (obtained |
or set using the same functions as for the integers), and a biased binary |
or set using the same functions as for the integers), and a binary |
exponent (i.e.~the actual exponent value plus some constant bias, actually |
exponent. This exponent can be handled using the following macros: |
a power of~2, whose value is given by \kbd{HIGHEXPOBIT}). This exponent can |
|
be handled using the following macros: |
|
|
|
\fun{long}{expo}{GEN z} returns the true (unbiased) exponent of \kbd{z}. |
\fun{long}{expo}{GEN z} returns the exponent of \kbd{z}. |
This is defined even when \kbd{z} is equal to zero, see |
This is defined even when \kbd{z} is equal to zero, see |
\secref{se:whatzero}. |
\secref{se:whatzero}. |
|
|
\fun{void}{setexpo}{GEN z, long e} sets the exponent of \kbd{z} to \kbd{e}, |
\fun{void}{setexpo}{GEN z, long e} sets the exponent of \kbd{z} to \kbd{e}. |
of course after adding the bias. |
|
|
|
\noindent Note the functions: |
\noindent Note the functions: |
|
|
Line 1110 even if \kbd{z} is not a real number. |
|
Line 1117 even if \kbd{z} is not a real number. |
|
\fun{long}{gsigne}{GEN z} which returns a sign for \kbd{z}, even when |
\fun{long}{gsigne}{GEN z} which returns a sign for \kbd{z}, even when |
\kbd{z} is neither real nor integer (a rational number for instance). |
\kbd{z} is neither real nor integer (a rational number for instance). |
|
|
The real zero is characterized by having its sign equal to 0. However, |
The real zero is characterized by having its sign equal to 0. If \kbd{z} is |
usually the first mantissa word \kbd{z[2]} is defined and equal to~0. This |
not equal to~0, then is is represented as $2^e M$, where $e$ is the exponent, |
fact must {\it never\/} be used to recognize a real~0. If \kbd{z} is not |
and $M\in [1, 2[$ is the mantissa of $z$, whose digits are stored in |
equal to~0, the first mantissa word \kbd{z[2]} is normalized, i.e.~its most |
$\kbd{z[2]},\dots, \kbd{z[lg(z)-1]}$. |
significant bit is~1. The mantissa is (\kbd{z[2]},\kbd{z[3]},\dots,% |
|
\kbd{z[lg(z]-1]}) in base \kbd{2\pow BITS\_IN\_LONG}. Here, \kbd{z[2]} is |
|
the most significant longword, and the mantissa takes values between |
|
1 (included) and 2 (excluded). Thus, assume that \kbd{sizeof(long)} is 32 and |
|
the length is 4, the real number $3.5$ is represented as \kbd{z[0]} (encoding |
|
$\kbd{type} = \typ{REAL}$, $\kbd{lg} = 4$), \kbd{z[1]} (encoding $\kbd{sign} = |
|
1$, $\kbd{expo} = 1$), $\kbd{z[2]} = \kbd{0xe0000000}$, |
|
$\kbd{z[3]} = \kbd{0x0}$. |
|
|
|
|
More precisely, let $m$ be the integer (\kbd{z[2]},\dots, \kbd{z[lg(z)-1]}) |
|
in base \kbd{2\pow BITS\_IN\_LONG}; here, \kbd{z[2]} is the most significant |
|
longword and is normalized, i.e.~its most significant bit is~1. Then we have |
|
$M := m \cdot 2^{1 - \kbd{bit\_accuracy(lg(z))}}$. |
|
|
|
Thus, the real number $3.5$ to accuracy \kbd{bit\_accuracy(lg(z))} is |
|
represented as \kbd{z[0]} (encoding $\kbd{type} = \typ{REAL}$, \kbd{lg(z)}), |
|
\kbd{z[1]} (encoding $\kbd{sign} = 1$, $\kbd{expo} = 1$), $\kbd{z[2]} = |
|
\kbd{0xe0000000}$, $\kbd{z[3]} =\dots = \kbd{z[lg(z)-1]} = \kbd{0x0}$. |
|
|
\subsec{Type \typ{INTMOD} (integermod):}\kbdsidx{t_INTMOD}\sidx{integermod} |
\subsec{Type \typ{INTMOD} (integermod):}\kbdsidx{t_INTMOD}\sidx{integermod} |
\kbd{z[1]} points to the modulus, and \kbd{z[2]} at the number representing |
\kbd{z[1]} points to the modulus, and \kbd{z[2]} at the number representing |
the class \kbd{z}. Both are separate \kbd{GEN} objects, and both must be of |
the class \kbd{z}. Both are separate \kbd{GEN} objects, and both must be of |
Line 1151 are useful and make sense. |
|
Line 1160 are useful and make sense. |
|
\kbd{[1]} which contains the following information: the $p$-adic precision |
\kbd{[1]} which contains the following information: the $p$-adic precision |
(the exponent of $p$ modulo which the $p$-adic unit corresponding to |
(the exponent of $p$ modulo which the $p$-adic unit corresponding to |
\kbd{z} is defined if \kbd{z} is not~0), i.e.~one less than the number of |
\kbd{z} is defined if \kbd{z} is not~0), i.e.~one less than the number of |
significant $p$-adic digits, and the biased exponent of \kbd{z} (the bias |
significant $p$-adic digits, and the exponent of \kbd{z}. This information |
being equal to \kbd{HIGHVALPBIT} here). This information can be handled |
can be handled using the following functions: |
using the following functions: |
|
|
|
\fun{long}{precp}{GEN z} returns the $p$-adic precision of \kbd{z}. |
\fun{long}{precp}{GEN z} returns the $p$-adic precision of \kbd{z}. |
|
|
Line 1161 using the following functions: |
|
Line 1169 using the following functions: |
|
to \kbd{l}. |
to \kbd{l}. |
|
|
\fun{long}{valp}{GEN z} returns the $p$-adic valuation of \kbd{z} (i.e. the |
\fun{long}{valp}{GEN z} returns the $p$-adic valuation of \kbd{z} (i.e. the |
unbiased exponent). This is defined even if \kbd{z} is equal to~0, see |
exponent). This is defined even if \kbd{z} is equal to~0, see |
\secref{se:whatzero}. |
\secref{se:whatzero}. |
|
|
\fun{void}{setvalp}{GEN z, long e} sets the $p$-adic valuation of \kbd{z} |
\fun{void}{setvalp}{GEN z, long e} sets the $p$-adic valuation of \kbd{z} |
Line 1189 polynomial representing the class of~\kbd{z}. Both mus |
|
Line 1197 polynomial representing the class of~\kbd{z}. Both mus |
|
\typ{POL} in the same variable. However, \kbd{z[2]} is allowed to be a |
\typ{POL} in the same variable. However, \kbd{z[2]} is allowed to be a |
simplification of such a polynomial, e.g a scalar. This is quite tricky |
simplification of such a polynomial, e.g a scalar. This is quite tricky |
considering the hierarchical structure of the variables; in particular, a |
considering the hierarchical structure of the variables; in particular, a |
polynomial in variable of \var{lesser} priority than the modulus variable |
polynomial in variable of \var{lesser} priority (see \secref{se:priority}) |
is valid, since it can be considered as the constant term of a polynomial |
than the modulus variable is valid, since it can be considered as the |
of degree 0 in the correct variable. On the other hand a variable of |
constant term of a polynomial of degree 0 in the correct variable. On the |
\var{greater} priority would not be acceptable. |
other hand a variable of \var{greater} priority would not be acceptable. |
|
|
\subsec{Type \typ{POL} (polynomial):}\kbdsidx{t_POL}\sidx{polynomial} this |
\subsec{Type \typ{POL} (polynomial):}\kbdsidx{t_POL}\sidx{polynomial} this |
type has a second codeword which is analogous to the one for integers. It |
type has a second codeword which is analogous to the one for integers. It |
Line 1214 not (see however the important remark below), a {\it v |
|
Line 1222 not (see however the important remark below), a {\it v |
|
\fun{void}{setvarn}{GEN z, long v} sets the variable number of \kbd{z} to |
\fun{void}{setvarn}{GEN z, long v} sets the variable number of \kbd{z} to |
\kbd{v}. |
\kbd{v}. |
|
|
|
The variable numbers encode the relative priorities of variables as discussed |
|
in \secref{se:priority}. We will give more details in \secref{se:vars}. |
Note also the function \fun{long}{gvar}{GEN z} which tries to return a |
Note also the function \fun{long}{gvar}{GEN z} which tries to return a |
\idx{variable number} for \kbd{z}, even if \kbd{z} is not a polynomial or |
\idx{variable number} for \kbd{z}, even if \kbd{z} is not a polynomial or |
power series. The variable number of a scalar type is set by definition |
power series. The variable number of a scalar type is set by definition |
Line 1238 term \kbd{z[lgef(z)-1]} is not an exact zero. |
|
Line 1248 term \kbd{z[lgef(z)-1]} is not an exact zero. |
|
\subsec{Type \typ{SER} (power series):}\kbdsidx{t_SER}\sidx{power series} This |
\subsec{Type \typ{SER} (power series):}\kbdsidx{t_SER}\sidx{power series} This |
type also has a second codeword, which encodes a ``{\it sign\/}'', i.e.~0 |
type also has a second codeword, which encodes a ``{\it sign\/}'', i.e.~0 |
if the power series is 0, and 1 if not, a {\it variable number\/} as for |
if the power series is 0, and 1 if not, a {\it variable number\/} as for |
polynomials, and a {\it biased exponent\/} with a bias of |
polynomials, and an {\it exponent\/}. This information can be handled with |
\kbd{HIGHVALPBIT}. This information can be handled with the following |
the following functions: \teb{signe}, \teb{setsigne}, \teb{varn}, |
functions: \teb{signe}, \teb{setsigne}, \teb{varn}, \teb{setvarn} as for |
\teb{setvarn} as for polynomials, and \teb{valp}, \teb{setvalp} for the |
polynomials, and \teb{valp}, \teb{setvalp} for the exponent as for $p$-adic |
exponent as for $p$-adic numbers. Beware: do {\it not\/} use \teb{expo} and |
numbers. Beware: do {\it not\/} use \teb{expo} and \teb{setexpo} on power |
\teb{setexpo} on power series. |
series. |
|
|
|
If the power series is non-zero, \kbd{z[2]}, \kbd{z[3]},\dots |
If the power series is non-zero, \kbd{z[2]}, \kbd{z[3]},\dots |
\kbd{z[lg(z)-1]} point to the coefficients of \kbd{z} in ascending order, |
\kbd{z[lg(z)-1]} point to the coefficients of \kbd{z} in ascending order, |
Line 1293 contain the components of the list. |
|
Line 1302 contain the components of the list. |
|
\fun{char *}{GSTR}{z} (= \kbd{(z+1)}) points to the first character of the |
\fun{char *}{GSTR}{z} (= \kbd{(z+1)}) points to the first character of the |
(\kbd{NULL}-terminated) string. |
(\kbd{NULL}-terminated) string. |
|
|
|
\misctitle{Implementation note:} for the types including an exponent (or a |
|
valuation), we actually store a biased non-negative exponent (bit-ORing the |
|
biased exponent to the codeword), obtained by adding a constant to the true |
|
exponent: either \kbd{HIGHEXPOBIT} (for \typ{REAL}) or \kbd{HIGHVALPBIT} (for |
|
\typ{PADIC} and \typ{SER}). Of course, this is encapsulated by the |
|
exponent/valuation-handling macros and need not concern the library user. |
|
|
\section{PARI variables}\label{se:vars} |
\section{PARI variables}\label{se:vars} |
\subsec{Multivariate objects} |
\subsec{Multivariate objects}\sidx{variable (priority)} |
|
|
\noindent |
\noindent |
We now consider variables and formal computations. As we have seen in |
We now consider variables and formal computations, and give the technical |
\secref{se:impl}, the codewords for types \typ{POL} and \typ{SER} |
details corresponding to the general discussion in \secref{se:priority}. As |
encode a ``variable number''. This is an integer, ranging from $0$ to |
we have seen in \secref{se:impl}, the codewords for types \typ{POL} and |
\kbd{MAXVARN}. The lower it is, the higher the variable priority. PARI does |
\typ{SER} encode a ``variable number''. This is an integer, ranging from $0$ |
not know anything about intelligent ``sparse'' representation of polynomials. |
to \kbd{MAXVARN}. The lower it is, the higher the variable priority. |
So a multivariate polynomial in PARI is just a polynomial (in one variable), |
|
whose coefficients are themselves (arbitrary) polynomials. All computations |
|
are then just done formally on the coefficients as if the polynomial was |
|
univariate. |
|
|
|
In fact, the way an object will be considered in formal computations depends |
In fact, the way an object will be considered in formal computations depends |
entirely on its ``principal variable number'' which is given by the function |
entirely on its ``principal variable number'' which is given by the function |
Line 1317 is not a polynomial or power series. The variable numb |
|
Line 1329 is not a polynomial or power series. The variable numb |
|
set by definition equal to \tet{BIGINT} which is bigger than any legal |
set by definition equal to \tet{BIGINT} which is bigger than any legal |
variable number. The variable number of a recursive type which is not a |
variable number. The variable number of a recursive type which is not a |
polynomial or power series is the minimal variable number of its components. |
polynomial or power series is the minimal variable number of its components. |
But for polynomials and power series only the ``outermost'' number counts: |
But for polynomials and power series only the ``outermost'' number counts (we |
the representation is not symmetrical at all. |
directly access $\tet{varn}(x)$ in the codewords): the representation is not |
|
symmetrical at all. |
|
|
Under GP, one need not worry too much since the interpreter will define |
Under GP, one need not worry too much since the interpreter will define |
the variables as it sees them and do the right thing with the polynomials |
the variables as it sees them\footnote{*}{ |
produced (however, have a look at the remark in \secref{se:rempolmod}). But |
More precisely, the first time a given identifier is read by the GP parser |
in library mode, they are tricky objects if you intend to build polynomials |
(and is not immediately interpreted as a function) a new variable is created, |
yourself (and not just let PARI functions produce them, which is usually less |
and it is assigned a strictly lower priority than any variable in use at this |
efficient). For instance, it does not make sense to have a variable number |
point. On startup, before any user input has taken place, 'x' is defined in |
occur in the components of a polynomial whose main variable has a higher |
this way and will thus always have maximal priority (and variable number $0$).} |
number (lower priority), even though there's nothing PARI can do to prevent |
% |
you from doing it. |
and do the right thing with the polynomials produced (however, have a look at |
|
the remark in \secref{se:rempolmod}). |
|
|
|
But in library mode, they are tricky objects if you intend to build |
|
polynomials yourself (and not just let PARI functions produce them, which is |
|
usually less efficient). For instance, it does not make sense to have a |
|
variable number occur in the components of a polynomial whose main variable |
|
has a higher number (lower priority), even though there's nothing PARI can do |
|
to prevent you from doing it. |
|
|
\subsec{Creating variables} |
\subsec{Creating variables} |
A basic difficulty is to ``create'' a variable. As we have seen in |
A basic difficulty is to ``create'' a variable. As we have seen in |
\secref{se:intro4}, a plethora of objects is associated to variable |
\secref{se:intro4}, a plethora of objects is associated to variable |
Line 1342 properly defined before you can use a given integer as |
|
Line 1363 properly defined before you can use a given integer as |
|
|
|
Initially, this is done for $0$ (the variable \kbd{x} under GP), and |
Initially, this is done for $0$ (the variable \kbd{x} under GP), and |
\tet{MAXVARN}, which is there to address the need for a ``temporary'' new |
\tet{MAXVARN}, which is there to address the need for a ``temporary'' new |
variable, which would not be used in regular objects (created by the |
variable in library mode and cannot be input under GP. |
library). We call the latter type a ``temporary variable''. The regular |
No documented library function can create from scratch an object involving |
variables meant to be used in regular objects, are called ``user |
\tet{MAXVARN} (of course, if the operands originally involve \kbd{MAXVARN}, |
|
the function will abide). We call the latter type a ``temporary variable''. |
|
The regular variables meant to be used in regular objects, are called ``user |
variables\sidx{variable (user)}''. |
variables\sidx{variable (user)}''. |
|
|
\subsubsec{User variables}\sidx{variable (user)}: |
\subsubsec{User variables}\sidx{variable (user)}: |
Line 1633 computation, just print the requested message and go o |
|
Line 1656 computation, just print the requested message and go o |
|
|
|
\noindent which is the exact equivalent of \kbd{err(talker,...)} except that |
\noindent which is the exact equivalent of \kbd{err(talker,...)} except that |
you certainly don't want to stop the program at this point, just inform the |
you certainly don't want to stop the program at this point, just inform the |
user that something important has occured (in particular, this output would be |
user that something important has occurred (in particular, this output would be |
suitably highlighted under GP, whereas a simple \kbd{printf} would not). |
suitably highlighted under GP, whereas a simple \kbd{printf} would not). |
|
|
\subsec{Debugging output}.\sidx{debugging}\sidx{format}\label{se:dbg_output} |
\subsec{Debugging output}.\sidx{debugging}\sidx{format}\label{se:dbg_output} |
Line 1681 prints \kbd{Time}, then the remaining arguments as spe |
|
Line 1704 prints \kbd{Time}, then the remaining arguments as spe |
|
\kbd{format} (which is a PARI format), then the output of \kbd{timer2}. |
\kbd{format} (which is a PARI format), then the output of \kbd{timer2}. |
|
|
This mechanism is simple to use but not foolproof. If some other function |
This mechanism is simple to use but not foolproof. If some other function |
uses these timers, and many PARI functions do when DEBUGLEVEL is high enough, |
uses these timers, and many PARI functions do use \kbd{timer2} when |
the timings will be meaningless. The functions \fun{long}{gentimer}{long |
\tet{DEBUGLEVEL} is high enough, the timings will be meaningless. To handle |
id} or \fun{long}{genmsgtimer}{long id, char *format,...} are equivalent to |
timing in a reentrant way, PARI defines a dedicated datatype, |
\kbd{timer} and \kbd{msgtimer} respectively, except they will use a unique |
\tet{pari_timer}. The functions |
timer denoted by \kbd{id}. To get a valid identifier, use |
|
\kbd{id = }\tet{get_timer}\kbd{(0)}. |
|
|
|
This timer has to be deleted when it's not needed anymore |
\fun{long}{TIMER}{pari\_timer *T} |
(i.e.~when the main function returns), with a call to \kbd{get\_timer(id)}. |
|
After such a call, the reserved identifier becomes available again. |
|
|
|
|
\fun{long}{msgTIMER}{pari\_timer *T, char *format,...} |
|
|
|
\noindent are equivalent to \kbd{timer} and \kbd{msgtimer} respectively, |
|
except they use a unique timer \kbd{T} containing all the information needed, |
|
so that no other function can mess with your timings. They are used as |
|
follows: |
|
\bprog |
|
pari_timer T; |
|
|
|
(void)TIMER(&T); /* initialize timer */ |
|
... |
|
printf("Total time: %ld\n", TIMER(&T)); |
|
@eprog |
|
or |
|
\bprog |
|
pari_timer T; |
|
long i; |
|
GEN L; |
|
|
|
(void)TIMER(&T); /* initialize timer */ |
|
for (i = 1; i < 10; i++) { |
|
... |
|
msgTIMER(&T, "for i = %ld (L[i] = %Z)", i, L[i]); |
|
} |
|
@eprog |
|
|
\section{A complete program} |
\section{A complete program} |
\label{se:prog} |
\label{se:prog} |
|
|
Line 1882 where \kbd{n} can be positive or negative. This is muc |
|
Line 1927 where \kbd{n} can be positive or negative. This is muc |
|
There is another function \teb{gshift} with exactly the same syntax. |
There is another function \teb{gshift} with exactly the same syntax. |
When \kbd{n} is non-negative, the effects of these two functions are the same. |
When \kbd{n} is non-negative, the effects of these two functions are the same. |
However, when \kbd{n} is negative, \kbd{gshift} acts like a right shift of |
However, when \kbd{n} is negative, \kbd{gshift} acts like a right shift of |
\kbd{-n}, hence does not noramlly perform an exact division on integers. The |
\kbd{-n}, hence does not normally perform an exact division on integers. The |
function \kbd{gshift} is the PARI analogue of the C or GP operators \kbd{<<} |
function \kbd{gshift} is the PARI analogue of the C or GP operators \kbd{<<} |
and~\kbd{>>}. |
and~\kbd{>>}. |
|
|
|
|
|
|
Roughly four types of modifications can be made. The first type includes all |
Roughly four types of modifications can be made. The first type includes all |
improvements to the documentation, in a broad sense. This includes correcting |
improvements to the documentation, in a broad sense. This includes correcting |
typos or inacurracies of course, but also items which are not really covered |
typos or inaccurracies of course, but also items which are not really covered |
in this document, e.g.~if you happen to write a tutorial, or pieces of code |
in this document, e.g.~if you happen to write a tutorial, or pieces of code |
exemplifying some fine points that you think were unduly omitted. |
exemplifying some fine points that you think were unduly omitted. |
|
|
|
|
\noindent$\bullet$ Optional arguments: |
\noindent$\bullet$ Optional arguments: |
% |
% |
\+& \kbd{s*} & any number of strings, possibly 0 (see \kbd{s})\cr |
\+& \kbd{s*} & any number of strings, possibly 0 (see \kbd{s})\cr |
\+& \kbd{s*p} & idem, setting $\kbd{prettyp} = 1$ (i.e.~in beautified |
|
format)\cr |
|
\+& \kbd{s*t} & idem, in \TeX\ format\cr |
|
\+& \kbd{D\var{xxx}} & argument has a default value\cr |
\+& \kbd{D\var{xxx}} & argument has a default value\cr |
|
|
|
The \kbd{s*} code is technical and you probably do not need it, but we give |
|
its description for completeness. It reads all remaining arguments in |
|
\tev{string context} (see \secref{se:strings}), and sends a |
|
(\kbd{NULL}-terminated) list of \kbd{GEN*} pointing to these. The automatic |
|
concatenation rules in string context are implemented so that adjacent strings |
|
are read as different arguments, as if they had been comma-separated. For |
|
instance, if the remaining argument sequence is: \kbd{"xx" 1, "yy"}, the |
|
\kbd{s*} atom will send a \kbd{GEN *g = \obr \&a, \&b, \&c, NULL\cbr}, where |
|
$a$, $b$, $c$ are \kbd{GEN}s of type \typ{STR} (content \kbd{xx}), \typ{INT} |
|
and \typ{STR} (content \kbd{yy}). |
|
|
The format to indicate a default value (atom starts with a \kbd{D}) is |
The format to indicate a default value (atom starts with a \kbd{D}) is |
``\kbd{D\var{value},\var{type},}'', where \var{type} is the code for any |
``\kbd{D\var{value},\var{type},}'', where \var{type} is the code for any |
mandatory atom (previous group), \var{value} is any valide GP expression |
mandatory atom (previous group), \var{value} is any valid GP expression |
which is converted according to \var{type}, and the ending comma is |
which is converted according to \var{type}, and the ending comma is |
mandatory. For instance \kbd{D0,L,} stands for ``this optional argument will |
mandatory. For instance \kbd{D0,L,} stands for ``this optional argument will |
be converted to a \kbd{long}, and is \kbd{0} by default''. So if the |
be converted to a \kbd{long}, and is \kbd{0} by default''. So if the |
user-given argument reads \kbd{1 + 3} at this point, \kbd{(long)4} is sent to |
user-given argument reads \kbd{1 + 3} at this point, \kbd{(long)4} is sent to |
the function (via \tet{itos}$()$); and \kbd{(long)0} if the argument is |
the function (via \tet{itos}$()$); and \kbd{(long)0} if the argument is |
ommitted. The following special syntaxes are available: |
omitted. The following special syntaxes are available: |
|
|
\settabs\+\indent\indent&\kbd{Dxxx}\quad& optional \kbd{*GEN},&\cr |
\settabs\+\indent\indent&\kbd{Dxxx}\quad& optional \kbd{*GEN},&\cr |
\+&\kbd{DG}& optional \kbd{GEN}, & send \kbd{NULL} if argument omitted.\cr |
\+&\kbd{DG}& optional \kbd{GEN}, & send \kbd{NULL} if argument omitted.\cr |