"Fossies" - the Fresh Open Source Software Archive

Member "pari-2.13.1/doc/usersch3.tex" (16 Jan 2021, 1308911 Bytes) of package /linux/misc/pari-2.13.1.tar.gz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) TeX and LaTeX source code syntax highlighting (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 % Copyright (c) 2000  The PARI Group
    2 %
    3 % This file is part of the PARI/GP documentation
    4 %
    5 % Permission is granted to copy, distribute and/or modify this document
    6 % under the terms of the GNU General Public License
    7 \chapter{Functions and Operations Available in PARI and GP}
    8 \label{se:functions}
    9 
   10 The functions and operators available in PARI and in the GP/PARI calculator
   11 are numerous and ever-expanding. Here is a description of the ones available
   12 in version \vers. It should be noted that many of these functions accept
   13 quite different types as arguments, but others are more restricted. The list
   14 of acceptable types will be given for each function or class of functions.
   15 Except when stated otherwise, it is understood that a function or operation
   16 which should make natural sense is legal.
   17 
   18 On the other hand, many routines list explicit preconditions for some of their
   19 argument, e.g. $p$ is a prime number, or $q$ is a positive definite quadratic
   20 form. For reasons of efficiency, all trust the user input and only perform
   21 minimal sanity checks. When a precondition is not satisfied, any of the
   22 following may occur: a regular exception is raised, the PARI stack overflows, a
   23 \kbd{SIGSEGV} or \kbd{SIGBUS} signal is generated, or we enter an infinite
   24 loop. The function can also quietly return a mathematically meaningless
   25 result: junk in, junk out.
   26 
   27 In this chapter, we will describe the functions according to a rough
   28 classification. The general entry looks something like:
   29 
   30 \key{foo}$(x,\{\fl=0\})$: short description.
   31 
   32 The library syntax is \kbd{GEN foo(GEN x, long fl = 0)}.
   33 
   34 \noindent
   35 This means that the GP function \kbd{foo} has one mandatory argument $x$, and
   36 an optional one, $\fl$, whose default value is 0. (The $\{\}$ should not be
   37 typed, it is just a convenient notation we will use throughout to denote
   38 optional arguments.) That is, you can type \kbd{foo(x,2)}, or \kbd{foo(x)},
   39 which is then understood to mean \kbd{foo(x,0)}. As well, a comma or closing
   40 parenthesis, where an optional argument should have been, signals to GP it
   41 should use the default. Thus, the syntax \kbd{foo(x,)} is also accepted as a
   42 synonym for our last expression. When a function has more than one optional
   43 argument, the argument list is filled with user supplied values, in order.
   44 When none are left, the defaults are used instead. Thus, assuming that
   45 \kbd{foo}'s prototype had been
   46 $$\hbox{%
   47 \key{foo}$(\{x=1\},\{y=2\},\{z=3\})$,%
   48 }$$
   49 typing in \kbd{foo(6,4)} would give
   50 you \kbd{foo(6,4,3)}. In the rare case when you want to set some far away
   51 argument, and leave the defaults in between as they stand, you can use the
   52 ``empty arg'' trick alluded to above: \kbd{foo(6,,1)} would yield
   53 \kbd{foo(6,2,1)}. By the way, \kbd{foo()} by itself yields
   54 \kbd{foo(1,2,3)} as was to be expected.
   55 
   56 In this rather special case of a function having no mandatory argument, you
   57 can even omit the $()$: a standalone \kbd{foo} would be enough (though we
   58 do not recommend it for your scripts, for the sake of clarity). In defining
   59 GP syntax, we strove to put optional arguments at the end of the argument
   60 list (of course, since they would not make sense otherwise), and in order of
   61 decreasing usefulness so that, most of the time, you will be able to ignore
   62 them.
   63 
   64 Finally, an optional argument (between braces) followed by a star, like
   65 $\{\var{x}\}*$, means that any number of such arguments (possibly none) can
   66 be given. This is in particular used by the various \kbd{print} routines.
   67 
   68 \misctitle{Flags} A \tev{flag} is an argument which, rather than conveying
   69 actual information to the routine, instructs it to change its default
   70 behavior, e.g.~return more or less information. All such
   71 flags are optional, and will be called \fl\ in the function descriptions to
   72 follow. There are two different kind of flags
   73 
   74 \item generic: all valid values for the flag are individually
   75 described (``If \fl\ is equal to $1$, then\dots'').
   76 
   77 \item binary:\sidx{binary flag} use customary binary notation as a
   78 compact way to represent many toggles with just one integer. Let
   79 $(p_0,\dots,p_n)$ be a list of switches (i.e.~of properties which take either
   80 the value $0$ or~$1$), the number $2^3 + 2^5 = 40$ means that $p_3$ and $p_5$
   81 are set (that is, set to $1$), and none of the others are (that is, they
   82 are set to $0$). This is announced as ``The binary digits of $\fl$ mean 1:
   83 $p_0$, 2: $p_1$, 4: $p_2$'', and so on, using the available consecutive
   84 powers of~$2$.
   85 
   86 \misctitle{Mnemonics for binary flags} Numeric flags as mentioned above are
   87 obscure, error-prone, and quite rigid: should the authors want to adopt a new
   88 flag numbering scheme, it would break backward compatibility. The only
   89 advantage of explicit numeric values is that they are fast to type, so their
   90 use is only advised when using the calculator \kbd{gp}.
   91 
   92 As an alternative, one can replace a binary flag by a character string
   93 containing symbolic identifiers (mnemonics). In the function description,
   94 mnemonics corresponding to the various toggles are given after each of them.
   95 They can be negated by prepending \kbd{no\_} to the mnemonic, or by removing
   96 such a prefix. These toggles are grouped together using any punctuation
   97 character (such as ',' or ';'). For instance (taken from description of
   98 $\tet{ploth}(X=a,b,\var{expr},\{\fl=0\},\{n=0\})$)
   99 
  100 \centerline{Binary digits of flags mean: $1=\kbd{Parametric}$,
  101 $2=\kbd{Recursive}$, \dots}
  102 
  103 \noindent so that, instead of $1$, one could use the mnemonic
  104 \kbd{"Parametric; no\_Recursive"}, or simply \kbd{"Parametric"} since
  105 \kbd{Recursive} is unset by default (default value of $\fl$ is $0$,
  106 i.e.~everything unset). People used to the bit-or notation in languages like
  107 C may also use the form \kbd{"Parametric | no\_Recursive"}.
  108 
  109 \misctitle{Pointers} \varsidx{pointer} If a parameter in the function
  110 prototype is prefixed with a \& sign, as in
  111 
  112 \key{foo}$(x,\&e)$
  113 
  114 \noindent it means that, besides the normal return value, the function may
  115 assign a value to $e$ as a side effect. When passing the argument, the \&
  116 sign has to be typed in explicitly. As of version \vers, this \tev{pointer}
  117 argument is optional for all documented functions, hence the \& will always
  118 appear between brackets as in \kbd{Z\_issquare}$(x,\{\&e\})$.
  119 
  120 \misctitle{About library programming}
  121 The \var{library} function \kbd{foo}, as defined at the beginning of this
  122 section, is seen to have two mandatory arguments, $x$ and \fl: no function
  123 seen in the present chapter has been implemented so as to accept a variable
  124 number of arguments, so all arguments are mandatory when programming with the
  125 library (usually, variants are provided corresponding to the various flag values).
  126 We include an \kbd{= default value} token in the prototype to signal how a missing
  127 argument should be encoded. Most of the time, it will be a \kbd{NULL} pointer, or
  128 -1 for a variable number. Refer to the \emph{User's Guide to the PARI library}
  129 for general background and details.
  130 
  131 \section{Programming in GP: control statements}
  132 \sidx{programming}\label{se:programming}
  133 
  134   A number of control statements are available in GP. They are simpler and
  135 have a syntax slightly different from their C counterparts, but are quite
  136 powerful enough to write any kind of program. Some of them are specific to
  137 GP, since they are made for number theorists. As usual, $X$ will denote any
  138 simple variable name, and \var{seq} will always denote a sequence of
  139 expressions, including the empty sequence.
  140 
  141 \misctitle{Caveat} In constructs like
  142 \bprog
  143     for (X = a,b, seq)
  144 @eprog\noindent
  145 the variable \kbd{X} is lexically scoped to the loop, leading to possibly
  146 unexpected behavior:
  147 \bprog
  148     n = 5;
  149     for (n = 1, 10,
  150       if (something_nice(), break);
  151     );
  152     \\ @com at this point \kbd{n} is 5 !
  153 @eprog\noindent
  154 If the sequence \kbd{seq} modifies the loop index, then the loop
  155 is modified accordingly:
  156 \bprog
  157     ? for (n = 1, 10, n += 2; print(n))
  158     3
  159     6
  160     9
  161     12
  162 @eprog
  163 
  164 \subsec{break$(\{n=1\})$}\kbdsidx{break}\label{se:break}
  165 Interrupts execution of current \var{seq}, and
  166 immediately exits from the $n$ innermost enclosing loops, within the
  167 current function call (or the top level loop); the integer $n$ must be
  168 positive. If $n$ is greater than the number of enclosing loops, all
  169 enclosing loops are exited.
  170 
  171 \subsec{breakpoint$()$}\kbdsidx{breakpoint}\label{se:breakpoint}
  172 Interrupt the program and enter the breakloop. The program continues when
  173 the breakloop is exited.
  174 \bprog
  175 ? f(N,x)=my(z=x^2+1);breakpoint();gcd(N,z^2+1-z);
  176 ? f(221,3)
  177   ***   at top-level: f(221,3)
  178   ***                 ^--------
  179   ***   in function f: my(z=x^2+1);breakpoint();gcd(N,z
  180   ***                              ^--------------------
  181   ***   Break loop: type <Return> to continue; 'break' to go back to GP
  182 break> z
  183 10
  184 break>
  185 %2 = 13
  186 @eprog
  187 
  188 \subsec{dbg\_down$(\{n=1\})$}\kbdsidx{dbg_down}\label{se:dbg_down}
  189 (In the break loop) go down n frames. This allows to cancel a previous
  190 call to \kbd{dbg\_up}.
  191 \bprog
  192 ? x = 0;
  193 ? g(x) = x-3;
  194 ? f(x) = 1 / g(x+1);
  195 ? for (x = 1, 5, f(x+1))
  196    ***   at top-level: for(x=1,5,f(x+1))
  197    ***                           ^-------
  198    ***   in function f: 1/g(x+1)
  199    ***                   ^-------
  200    *** _/_: impossible inverse in gdiv: 0.
  201    ***   Break loop: type 'break' to go back to GP prompt
  202 break> dbg_up(3) \\ go up 3 frames
  203   ***   at top-level: for(x=1,5,f(x+1))
  204   ***                 ^-----------------
  205 break> x
  206 0
  207 break> dbg_down()
  208   ***   at top-level: for(x=1,5,f(x+1))
  209   ***                           ^-------
  210 break> x
  211 1
  212 break> dbg_down()
  213   ***   at top-level: for(x=1,5,f(x+1))
  214   ***                           ^-------
  215 break> x
  216 1
  217 break> dbg_down()
  218   ***   at top-level: for(x=1,5,f(x+1))
  219   ***                           ^-------
  220   ***   in function f: 1/g(x+1)
  221   ***                   ^-------
  222 break> x
  223 2
  224 @eprog\noindent The above example shows that the notion of GP frame is
  225 finer than the usual stack of function calls (as given for instance by the
  226 GDB \kbd{backtrace} command): GP frames are attached to variable scopes
  227 and there are frames attached to control flow instructions such as a
  228 \kbd{for} loop above.
  229 
  230 \subsec{dbg\_err$()$}\kbdsidx{dbg_err}\label{se:dbg_err}
  231 In the break loop, return the error data of the current error, if any.
  232 See \tet{iferr} for details about error data.  Compare:
  233 \bprog
  234 ? iferr(1/(Mod(2,12019)^(6!)-1),E,Vec(E))
  235 %1 = ["e_INV", "Fp_inv", Mod(119, 12019)]
  236 ? 1/(Mod(2,12019)^(6!)-1)
  237   ***   at top-level: 1/(Mod(2,12019)^(6!)-
  238   ***                  ^--------------------
  239   *** _/_: impossible inverse in Fp_inv: Mod(119, 12019).
  240   ***   Break loop: type 'break' to go back to GP prompt
  241 break> Vec(dbg_err())
  242 ["e_INV", "Fp_inv", Mod(119, 12019)]
  243 @eprog
  244 
  245 \subsec{dbg\_up$(\{n=1\})$}\kbdsidx{dbg_up}\label{se:dbg_up}
  246 (In the break loop) go up n frames, which allows to inspect data of the
  247 parent function. To cancel a \tet{dbg_up} call, use \tet{dbg_down}.
  248 \bprog
  249 ? x = 0;
  250 ? g(x) = x-3;
  251 ? f(x) = 1 / g(x+1);
  252 ? for (x = 1, 5, f(x+1))
  253    ***   at top-level: for(x=1,5,f(x+1))
  254    ***                           ^-------
  255    ***   in function f: 1/g(x+1)
  256    ***                   ^-------
  257    *** _/_: impossible inverse in gdiv: 0.
  258    ***   Break loop: type 'break' to go back to GP prompt
  259  break> x
  260  2
  261  break> dbg_up()
  262    ***   at top-level: for(x=1,5,f(x+1))
  263    ***                           ^-------
  264  break> x
  265  1
  266  break> dbg_up()
  267    ***   at top-level: for(x=1,5,f(x+1))
  268    ***                           ^-------
  269  break> x
  270  1
  271  break> dbg_up()
  272    ***   at top-level: for(x=1,5,f(x+1))
  273    ***                 ^-----------------
  274  break> x
  275  0
  276  break> dbg_down()    \\ back up once
  277    ***   at top-level: for(x=1,5,f(x+1))
  278    ***                           ^-------
  279  break> x
  280  1
  281 @eprog\noindent The above example shows that the notion of GP frame is
  282 finer than the usual stack of function calls (as given for instance by the
  283 GDB \kbd{backtrace} command): GP frames are attached to variable scopes
  284 and there are frames attached to control flow instructions such as a
  285 \kbd{for} loop above.
  286 
  287 \subsec{dbg\_x$(A,\{n\})$}\kbdsidx{dbg_x}\label{se:dbg_x}
  288 Print the inner structure of \kbd{A}, complete if \kbd{n} is omitted, up
  289 to level \kbd{n} otherwise. This is useful for debugging. This is similar to
  290 \b{x} but does not require \kbd{A} to be an history entry. In particular,
  291 it can be used in the break loop.
  292 
  293 \subsec{for$(X=a,b,\var{seq})$}\kbdsidx{for}\label{se:for}
  294 Evaluates \var{seq}, where
  295 the formal variable $X$ goes from $a$ to $b$. Nothing is done if $a>b$.
  296 $a$ and $b$ must be in $\R$. If $b$ is set to \kbd{+oo}, the loop will not
  297 stop; it is expected that the caller will break out of the loop itself at some
  298 point, using \kbd{break} or \kbd{return}.
  299 
  300 \subsec{forcomposite$(n=a,\{b\},\var{seq})$}\kbdsidx{forcomposite}\label{se:forcomposite}
  301 Evaluates \var{seq},
  302 where the formal variable $n$ ranges over the composite numbers between the
  303 nonnegative real numbers $a$ to $b$, including $a$ and $b$ if they are
  304 composite. Nothing is done if $a>b$.
  305 \bprog
  306 ? forcomposite(n = 0, 10, print(n))
  307 4
  308 6
  309 8
  310 9
  311 10
  312 @eprog\noindent Omitting $b$ means we will run through all composites $\geq a$,
  313 starting an infinite loop; it is expected that the user will break out of
  314 the loop himself at some point, using \kbd{break} or \kbd{return}.
  315 
  316 Note that the value of $n$ cannot be modified within \var{seq}:
  317 \bprog
  318 ? forcomposite(n = 2, 10, n = [])
  319  ***   at top-level: forcomposite(n=2,10,n=[])
  320  ***                                      ^---
  321  ***   index read-only: was changed to [].
  322 @eprog
  323 
  324 \subsec{fordiv$(n,X,\var{seq})$}\kbdsidx{fordiv}\label{se:fordiv}
  325 Evaluates \var{seq}, where
  326 the formal variable $X$ ranges through the divisors of $n$
  327 (see \tet{divisors}, which is used as a subroutine). It is assumed that
  328 \kbd{factor} can handle $n$, without negative exponents. Instead of $n$,
  329 it is possible to input a factorization matrix, i.e. the output of
  330 \kbd{factor(n)}.
  331 
  332 This routine uses \kbd{divisors} as a subroutine, then loops over the
  333 divisors. In particular, if $n$ is an integer, divisors are sorted by
  334 increasing size.
  335 
  336 To avoid storing all divisors, possibly using a lot of memory, the following
  337 (slower) routine loops over the divisors using essentially constant space:
  338 \bprog
  339 FORDIV(N)=
  340 { my(F = factor(N), P = F[,1], E = F[,2]);
  341 
  342   forvec(v = vector(#E, i, [0,E[i]]), X = factorback(P, v));
  343 }
  344 ? for(i=1, 10^6, FORDIV(i))
  345 time = 11,180 ms.
  346 ? for(i=1, 10^6, fordiv(i, d, ))
  347 time = 2,667 ms.
  348 @eprog\noindent Of course, the divisors are no longer sorted by inreasing
  349 size.
  350 
  351 \subsec{fordivfactored$(n,X,\var{seq})$}\kbdsidx{fordivfactored}\label{se:fordivfactored}
  352 Evaluates \var{seq}, where
  353 the formal variable $X$ ranges through $[d, \kbd{factor}(d)]$,
  354 where $d$ is a divisors of $n$
  355 (see \tet{divisors}, which is used as a subroutine). Note that such a pair
  356 is accepted as argument to all multiplicative functions.
  357 
  358 It is assumed that
  359 \kbd{factor} can handle $n$, without negative exponents. Instead of $n$,
  360 it is possible to input a factorization matrix, i.e. the output of
  361 \kbd{factor(n)}. This routine uses \kbd{divisors}$(,1)$ as a subroutine,
  362 then loops over the divisors. In particular, if $n$ is an integer, divisors
  363 are sorted by increasing size.
  364 
  365 This function is particularly useful when $n$ is hard to factor and one
  366 must evaluate multiplicative function on its divisors: we avoid
  367 refactoring each divisor in turn. It also provides a small speedup
  368 when $n$ is easy to factor; compare
  369 \bprog
  370 ? A = 10^8; B = A + 10^5;
  371 ? for (n = A, B, fordiv(n, d, eulerphi(d)));
  372 time = 2,091 ms.
  373 ? for (n = A, B, fordivfactored(n, d, eulerphi(d)));
  374 time = 1,298 ms. \\ avoid refactoring the divisors
  375 ? forfactored (n = A, B, fordivfactored(n, d, eulerphi(d)));
  376 time = 1,270 ms. \\ also avoid factoring the consecutive n's !
  377 @eprog
  378 
  379 \subsec{foreach$(V,X,\var{seq})$}\kbdsidx{foreach}\label{se:foreach}
  380 Evaluates \var{seq}, where the formal variable $X$ ranges through the
  381 components of $V$ (\typ{VEC}, \typ{COL}, \typ{LIST} or \typ{MAT}). A matrix
  382 argument is interpreted as a vector containing column vectors, as in
  383 \kbd{Vec}$(V)$.
  384 
  385 \subsec{forell$(E,a,b,\var{seq},\{\fl=0\})$}\kbdsidx{forell}\label{se:forell}
  386 Evaluates \var{seq}, where the formal variable $E = [\var{name}, M, G]$
  387 ranges through all elliptic curves of conductors from $a$ to $b$. In this
  388 notation \var{name} is the curve name in Cremona's elliptic  curve  database,
  389 $M$ is the minimal model, $G$ is a $\Z$-basis of the free part of the
  390 Mordell-Weil group $E(\Q)$. If flag is nonzero, select
  391 only the first curve in each isogeny class.
  392 \bprog
  393 ? forell(E, 1, 500, my([name,M,G] = E); \
  394     if (#G > 1, print(name)))
  395 389a1
  396 433a1
  397 446d1
  398 ? c = 0; forell(E, 1, 500, c++); c   \\ number of curves
  399 %2 = 2214
  400 ? c = 0; forell(E, 1, 500, c++, 1); c \\ number of isogeny classes
  401 %3 = 971
  402 @eprog\noindent
  403 The \tet{elldata} database must be installed and contain data for the
  404 specified conductors.
  405 
  406 \synt{forell}{void *data, long (*f)(void*,GEN), long a, long b, long flag}.
  407 
  408 \subsec{forfactored$(N=a,b,\var{seq})$}\kbdsidx{forfactored}\label{se:forfactored}
  409 Evaluates \var{seq}, where
  410 the formal variable $N$ is $[n, \kbd{factor}(n)]$ and $n$ goes from
  411 $a$ to $b$; $a$ and $b$ must be integers. Nothing is done if $a>b$.
  412 
  413 This function is only implemented for $|a|, |b| < 2^{64}$ ($2^{32}$ on a 32-bit
  414 machine). It uses a sieve and runs in time $O(\sqrt{b} + b-a)$. It should
  415 be at least 3 times faster than regular factorization as long as the interval
  416 length $b-a$ is much larger than $\sqrt{b}$ and get relatively faster as
  417 the bounds increase. The function slows down dramatically
  418 if $\kbd{primelimit} < \sqrt{b}$.
  419 
  420 \bprog
  421 ? B = 10^9;
  422 ? for (N = B, B+10^6, factor(N))
  423 time = 4,538 ms.
  424 ? forfactored (N = B, B+10^6, [n,fan] = N)
  425 time = 1,031 ms.
  426 
  427 ? B = 10^11;
  428 ? for (N = B, B+10^6, factor(N))
  429 time = 15,575 ms.
  430 ? forfactored (N = B, B+10^6, [n,fan] = N)
  431 time = 2,375 ms.
  432 
  433 ? B = 10^14;
  434 ? for (N = B, B+10^6, factor(N))
  435 time = 1min, 4,948 ms.
  436 ? forfactored (N = B, B+10^6, [n,fan] = N)
  437 time = 58,601 ms.
  438 @eprog\noindent The last timing is with the default \kbd{primelimit}
  439 (500000) which is much less than $\sqrt{B+10^6}$; it goes down
  440 to \kbd{26,750ms} if \kbd{primelimit} gets bigger than that bound.
  441 In any case $\sqrt{B+10^6}$ is much larger than the interval length $10^6$
  442 so \kbd{forfactored} gets relatively slower for that reason as well.
  443 
  444 Note that all PARI multiplicative functions accept the \kbd{[n,fan]}
  445 argument natively:
  446 \bprog
  447 ? s = 0; forfactored(N = 1, 10^7, s += moebius(N)*eulerphi(N)); s
  448 time = 6,001 ms.
  449 %1 = 6393738650
  450 ? s = 0; for(N = 1, 10^7, s += moebius(N)*eulerphi(N)); s
  451 time = 28,398 ms. \\ slower, we must factor N. Twice.
  452 %2 = 6393738650
  453 @eprog
  454 
  455 The following loops over the fundamental dicriminants less than $X$:
  456 \bprog
  457 ? X = 10^8;
  458 ? forfactored(d=1,X, if (isfundamental(d),));
  459 time = 34,030 ms.
  460 ? for(d=1,X, if (isfundamental(d),))
  461 time = 1min, 24,225 ms.
  462 @eprog
  463 
  464 \subsec{forpart$(X=k,\var{seq},\{a=k\},\{n=k\})$}\kbdsidx{forpart}\label{se:forpart}
  465 Evaluate \var{seq} over the partitions $X=[x_1,\dots x_n]$ of the
  466 integer $k$, i.e.~increasing sequences $x_1\leq x_2\dots \leq x_n$ of sum
  467 $x_1+\dots + x_n=k$. By convention, $0$ admits only the empty partition and
  468 negative numbers have no partitions. A partition is given by a
  469 \typ{VECSMALL}, where parts are sorted in nondecreasing order. The
  470 partitions are listed by increasing size and in lexicographic order when
  471 sizes are equal:
  472 \bprog
  473 ? forpart(X=4, print(X))
  474 Vecsmall([4])
  475 Vecsmall([1, 3])
  476 Vecsmall([2, 2])
  477 Vecsmall([1, 1, 2])
  478 Vecsmall([1, 1, 1, 1])
  479 @eprog\noindent Optional parameters $n$ and $a$ are as follows:
  480 
  481 \item $n=\var{nmax}$ (resp. $n=[\var{nmin},\var{nmax}]$) restricts
  482 partitions to length less than $\var{nmax}$ (resp. length between
  483 $\var{nmin}$ and $nmax$), where the \emph{length} is the number of nonzero
  484 entries.
  485 
  486 \item $a=\var{amax}$ (resp. $a=[\var{amin},\var{amax}]$) restricts the parts
  487 to integers less than $\var{amax}$ (resp. between $\var{amin}$ and
  488 $\var{amax}$).
  489 
  490 By default, parts are positive and we remove zero entries unless $amin\leq0$,
  491 in which case we fix the size $\#X = \var{nmax}$:
  492 \bprog
  493 \\ at most 3 nonzero parts, all <= 4
  494 ? forpart(v=5,print(Vec(v)), 4, 3)
  495 [1, 4]
  496 [2, 3]
  497 [1, 1, 3]
  498 [1, 2, 2]
  499 
  500 \\ between 2 and 4 parts less than 5, fill with zeros
  501 ? forpart(v=5,print(Vec(v)),[0,5],[2,4])
  502 [0, 0, 1, 4]
  503 [0, 0, 2, 3]
  504 [0, 1, 1, 3]
  505 [0, 1, 2, 2]
  506 [1, 1, 1, 2]
  507 
  508 \\ no partitions of 1 with 2 to 4 nonzero parts
  509 ? forpart(v=1,print(v),[0,5],[2,4])
  510 ?
  511 @eprog\noindent
  512 The behavior is unspecified if $X$ is modified inside the loop.
  513 
  514 \synt{forpart}{void *data, long (*call)(void*,GEN), long k, GEN a, GEN n}.
  515 
  516 \subsec{forperm$(a,p,\var{seq})$}\kbdsidx{forperm}\label{se:forperm}
  517 Evaluates \var{seq}, where the formal variable $p$ goes through some
  518 permutations given by a \typ{VECSMALL}. If $a$ is a positive integer then
  519 $P$ goes through the permutations of $\{1, 2, ..., a\}$ in lexicographic
  520 order and if $a$ is a small vector then $p$ goes through the
  521 (multi)permutations lexicographically larger than or equal to $a$.
  522 \bprog
  523 ? forperm(3, p, print(p))
  524 Vecsmall([1, 2, 3])
  525 Vecsmall([1, 3, 2])
  526 Vecsmall([2, 1, 3])
  527 Vecsmall([2, 3, 1])
  528 Vecsmall([3, 1, 2])
  529 Vecsmall([3, 2, 1])
  530 @eprog\noindent
  531 
  532 When $a$ is itself a \typ{VECSMALL} or a \typ{VEC} then $p$ iterates through
  533 multipermutations
  534 \bprog
  535 ? forperm([2,1,1,3], p, print(p))
  536 Vecsmall([2, 1, 1, 3])
  537 Vecsmall([2, 1, 3, 1])
  538 Vecsmall([2, 3, 1, 1])
  539 Vecsmall([3, 1, 1, 2])
  540 Vecsmall([3, 1, 2, 1])
  541 Vecsmall([3, 2, 1, 1])
  542 @eprog\noindent
  543 
  544 \subsec{forprime$(p=a,\{b\},\var{seq})$}\kbdsidx{forprime}\label{se:forprime}
  545 Evaluates \var{seq},
  546 where the formal variable $p$ ranges over the prime numbers between the real
  547 numbers $a$ to $b$, including $a$ and $b$ if they are prime. More precisely,
  548 the value of
  549 $p$ is incremented to \kbd{nextprime($p$ + 1)}, the smallest prime strictly
  550 larger than $p$, at the end of each iteration. Nothing is done if $a>b$.
  551 \bprog
  552 ? forprime(p = 4, 10, print(p))
  553 5
  554 7
  555 @eprog\noindent Setting $b$ to \kbd{+oo} means we will run through all primes
  556 $\geq a$, starting an infinite loop; it is expected that the caller will break
  557 out of the loop itself at some point, using \kbd{break} or \kbd{return}.
  558 
  559 Note that the value of $p$ cannot be modified within \var{seq}:
  560 \bprog
  561 ? forprime(p = 2, 10, p = [])
  562  ***   at top-level: forprime(p=2,10,p=[])
  563  ***                                   ^---
  564  ***   prime index read-only: was changed to [].
  565 @eprog
  566 
  567 \subsec{forprimestep$(p=a,b,q,\var{seq})$}\kbdsidx{forprimestep}\label{se:forprimestep}
  568 Evaluates \var{seq},
  569 where the formal variable $p$ ranges over the prime numbers $p$
  570 in an arithmetic progression in $[a,b]$: $q$ is either an integer
  571 ($p \equiv a \pmod{q}$) or an intmod \kbd{Mod(c,N)} and we restrict
  572 to that congruence class. Nothing is done if $a>b$.
  573 \bprog
  574 ? forprimestep(p = 4, 30, 5, print(p))
  575 19
  576 29
  577 ? forprimestep(p = 4, 30, Mod(1,5), print(p))
  578 11
  579 @eprog\noindent Setting $b$ to \kbd{+oo} means we will run through all primes
  580 $\geq a$, starting an infinite loop; it is expected that the caller will break
  581 out of the loop itself at some point, using \kbd{break} or \kbd{return}.
  582 
  583 The current implementation restricts the modulus of the arithmetic
  584 progression to an unsigned long (64 or 32 bits).
  585 \bprog
  586 ? forprimestep(p=2,oo,2^64,print(p))
  587  ***   at top-level: forprimestep(p=2,oo,2^64,print(p))
  588  ***                 ^----------------------------------
  589  *** forprimestep: overflow in t_INT-->ulong assignment.
  590 @eprog
  591 
  592 Note that the value of $p$ cannot be modified within \var{seq}:
  593 \bprog
  594 ? forprimestep(p = 2, 10, 3, p = [])
  595  ***   at top-level: forprimestep(p=2,10,3,p=[])
  596  ***                                         ^---
  597  ***   prime index read-only: was changed to [].
  598 @eprog
  599 
  600 \subsec{forsquarefree$(N=a,b,\var{seq})$}\kbdsidx{forsquarefree}\label{se:forsquarefree}
  601 Evaluates \var{seq}, where the formal variable $N$ is $[n,
  602 \kbd{factor}(n)]$ and $n$ goes through squarefree integers from $a$ to $b$;
  603 $a$ and $b$ must be integers. Nothing is done if $a>b$.
  604 
  605 \bprog
  606 ? forsquarefree(N=-3,9,print(N))
  607 [-3, [-1, 1; 3, 1]]
  608 [-2, [-1, 1; 2, 1]]
  609 [-1, Mat([-1, 1])]
  610 [1, matrix(0,2)]
  611 [2, Mat([2, 1])]
  612 [3, Mat([3, 1])]
  613 [5, Mat([5, 1])]
  614 [6, [2, 1; 3, 1]]
  615 [7, Mat([7, 1])]
  616 @eprog
  617 
  618 This function is only implemented for $|a|, |b| < 2^{64}$ ($2^{32}$ on a 32-bit
  619 machine). It uses a sieve and runs in time $O(\sqrt{b} + b-a)$. It should
  620 be at least 5 times faster than regular factorization as long as the interval
  621 length $b-a$ is much larger than $\sqrt{b}$ and get relatively faster as
  622 the bounds increase. The function slows down dramatically
  623 if $\kbd{primelimit} < \sqrt{b}$. It is comparable to \kbd{forfactored}, but
  624 about $\zeta(2) = \pi^2/6$ times faster due to the relative density
  625 of squarefree integers.
  626 
  627 \bprog
  628 ? B = 10^9;
  629 ? for (N = B, B+10^6, factor(N))
  630 time = 4,392 ms.
  631 ? forfactored (N = B, B+10^6, [n,fan] = N)
  632 time = 915 ms.
  633 ? forsquarefree (N = B, B+10^6, [n,fan] = N)
  634 time = 532 ms.
  635 
  636 ? B = 10^11;
  637 ? for (N = B, B+10^6, factor(N))
  638 time = 13,053 ms.
  639 ? forfactored (N = B, B+10^6, [n,fan] = N)
  640 time = 1,976 ms.
  641 ? forsquarefree (N = B, B+10^6, [n,fan] = N)
  642 time = 1,245 ms.
  643 
  644 ? B = 10^14;
  645 ? for (N = B, B+10^6, factor(N))
  646 time = 50,612 ms.
  647 ? forsquarefree (N = B, B+10^6, [n,fan] = N)
  648 time = 46,309 ms.
  649 @eprog\noindent The last timing is with the default \kbd{primelimit}
  650 (500000) which is much less than $\sqrt{B+10^6}$; it goes down
  651 to \kbd{20,396ms} if \kbd{primelimit} gets bigger than that bound.
  652 In any case $\sqrt{B+10^6}$ is much larger than the interval length $10^6$
  653 so \kbd{forsquarefree} gets relatively slower for that reason as well.
  654 
  655 Note that all PARI multiplicative functions accept the \kbd{[n,fan]}
  656 argument natively:
  657 \bprog
  658 ? s = 0; forsquarefree(N = 1, 10^7, s += moebius(N)*eulerphi(N)); s
  659 time = 3,788 ms.
  660 %1 = 6393738650
  661 ? s = 0; for(N = 1, 10^7, s += moebius(N)*eulerphi(N)); s
  662 time = 28,630 ms. \\ slower, we must factor N. Twice.
  663 %2 = 6393738650
  664 @eprog
  665 
  666 The following loops over the fundamental dicriminants less than $X$:
  667 \bprog
  668 ? X = 10^8;
  669 ? for(d=1,X, if (isfundamental(d),))
  670 time = 1min, 29,066 ms.
  671 ? forfactored(d=1,X, if (isfundamental(d),));
  672 time = 42,387 ms.
  673 ? forsquarefree(d=1,X, D = quaddisc(d); if (D <= X, ));
  674 time = 32,479 ms.
  675 @eprog\noindent Note that in the last loop, the fundamental discriminants
  676 $D$ are not evaluated in order (since \kbd{quaddisc(d)} for squarefree $d$
  677 is either $d$ or $4d$). This is the price we pay for a faster evaluation,
  678 and the set of numbers we run through is the same.
  679 
  680 We can run through negative fundamental discriminants in the same way
  681 \bprog
  682 ? forsquarefree(d=-X,-1, D = quaddisc(d); if (D >= -X, ));
  683 @eprog
  684 
  685 \subsec{forstep$(X=a,b,s,\var{seq})$}\kbdsidx{forstep}\label{se:forstep}
  686 Evaluates \var{seq}, where the formal variable $X$ goes from $a$ to $b$
  687 in increments of $s$. Nothing is done if $s>0$ and $a>b$ or if $s<0$
  688 and $a<b$. $s$ must be in $\R^*$ or an intmod \kbd{Mod(c,N)} (restrict to
  689 the corresponding arithmetic progression) or a vector of steps
  690 $[s_1,\dots,s_n]$ (the successive steps in $\R^*$ are used in the order they
  691 appear in $s$).
  692 
  693 \bprog
  694 ? forstep(x=5, 10, 2, print(x))
  695 5
  696 7
  697 9
  698 ? forstep(x=5, 10, Mod(1,3), print(x))
  699 7
  700 10
  701 ? forstep(x=5, 10, [1,2], print(x))
  702 5
  703 6
  704 8
  705 9
  706 @eprog\noindent Setting $b$ to \kbd{+oo} will start an infinite loop; it is
  707 expected that the caller will break out of the loop itself at some point,
  708 using \kbd{break} or \kbd{return}.
  709 
  710 \subsec{forsubgroup$(H=G,\{\var{bound}\},\var{seq})$}\kbdsidx{forsubgroup}\label{se:forsubgroup}
  711 Evaluates \var{seq} for
  712 each subgroup $H$ of the \emph{abelian} group $G$ (given in
  713 SNF\sidx{Smith normal form} form or as a vector of elementary divisors).
  714 
  715 If \var{bound} is present, and is a positive integer, restrict the output to
  716 subgroups of index less than \var{bound}. If \var{bound} is a vector
  717 containing a single positive integer $B$, then only subgroups of index
  718 exactly equal to $B$ are computed
  719 
  720 The subgroups are not ordered in any
  721 obvious way, unless $G$ is a $p$-group in which case Birkhoff's algorithm
  722 produces them by decreasing index. A \idx{subgroup} is given as a matrix
  723 whose columns give its generators on the implicit generators of $G$. For
  724 example, the following prints all subgroups of index less than 2 in $G =
  725 \Z/2\Z g_1 \times \Z/2\Z g_2$:
  726 
  727 \bprog
  728 ? G = [2,2]; forsubgroup(H=G, 2, print(H))
  729 [1; 1]
  730 [1; 2]
  731 [2; 1]
  732 [1, 0; 1, 1]
  733 @eprog\noindent
  734 The last one, for instance is generated by $(g_1, g_1 + g_2)$. This
  735 routine is intended to treat huge groups, when \tet{subgrouplist} is not an
  736 option due to the sheer size of the output.
  737 
  738 For maximal speed the subgroups have been left as produced by the algorithm.
  739 To print them in canonical form (as left divisors of $G$ in HNF form), one
  740 can for instance use
  741 \bprog
  742 ? G = matdiagonal([2,2]); forsubgroup(H=G, 2, print(mathnf(concat(G,H))))
  743 [2, 1; 0, 1]
  744 [1, 0; 0, 2]
  745 [2, 0; 0, 1]
  746 [1, 0; 0, 1]
  747 @eprog\noindent
  748 Note that in this last representation, the index $[G:H]$ is given by the
  749 determinant. See \tet{galoissubcyclo} and \tet{galoisfixedfield} for
  750 applications to \idx{Galois} theory.
  751 
  752 \synt{forsubgroup}{void *data, long (*call)(void*,GEN), GEN G, GEN bound}.
  753 
  754 \subsec{forsubset$(\var{nk}, s, \var{seq})$}\kbdsidx{forsubset}\label{se:forsubset}
  755 If \var{nk} is a nonnegative integer $n$, evaluates \kbd{seq}, where
  756 the formal variable $s$ goes through all subsets of $\{1, 2, \ldots, n\}$;
  757 if \var{nk} is a pair $[n,k]$ of integers, $s$ goes through subsets
  758 of size $k$ of $\{1, 2, \ldots, n\}$. In both cases $s$ goes through subsets
  759 in lexicographic order among subsets of the same size and smaller subsets
  760 come first.
  761 \bprog
  762 ? forsubset([5,3], s, print(s))
  763 Vecsmall([1, 2, 3])
  764 Vecsmall([1, 2, 4])
  765 Vecsmall([1, 2, 5])
  766 Vecsmall([1, 3, 4])
  767 Vecsmall([1, 3, 5])
  768 Vecsmall([1, 4, 5])
  769 Vecsmall([2, 3, 4])
  770 Vecsmall([2, 3, 5])
  771 Vecsmall([2, 4, 5])
  772 Vecsmall([3, 4, 5])
  773 @eprog
  774 
  775 \bprog
  776 ? forsubset(3, s, print(s))
  777 Vecsmall([])
  778 Vecsmall([1])
  779 Vecsmall([2])
  780 Vecsmall([3])
  781 Vecsmall([1, 2])
  782 Vecsmall([1, 3])
  783 Vecsmall([2, 3])
  784 Vecsmall([1, 2, 3])
  785 @eprog\noindent The running time is proportional to the number
  786 of subsets enumerated, respectively $2^n$ and \kbd{binomial}$(n,k)$:
  787 \bprog
  788 ? c = 0; forsubset([40,35],s,c++); c
  789 time = 128 ms.
  790 %4 = 658008
  791 ? binomial(40,35)
  792 %5 = 658008
  793 @eprog
  794 
  795 \subsec{forvec$(X=v,\var{seq},\{\fl=0\})$}\kbdsidx{forvec}\label{se:forvec}
  796 Let $v$ be an $n$-component vector (where $n$ is arbitrary) of
  797 two-component vectors $[a_i,b_i]$ for $1\le i\le n$, where all entries $a_i$,
  798 $b_i$ are real numbers. This routine lets $X$ vary over the $n$-dimensional
  799 box given by $v$ with unit steps: $X$ is an $n$-dimensional vector whose $i$-th
  800 entry $X[i]$ runs through $a_i, a_i+1, a_i+2, \dots $ stopping with the
  801 first value greater than $b_i$ (note that neither $a_i$ nor $b_i - a_i$
  802 are required to be integers). The values of $X$ are ordered
  803 lexicographically, like embedded \kbd{for} loops, and the expression
  804 \var{seq} is evaluated with the successive values of $X$. The type of $X$ is
  805 the same as the type of $v$: \typ{VEC} or \typ{COL}.
  806 
  807 If $\fl=1$, generate only nondecreasing vectors $X$, and
  808 if $\fl=2$, generate only strictly increasing vectors $X$.
  809 \bprog
  810 ? forvec (X=[[0,1],[-1,1]], print(X));
  811 [0, -1]
  812 [0, 0]
  813 [0, 1]
  814 [1, -1]
  815 [1, 0]
  816 [1, 1]
  817 ? forvec (X=[[0,1],[-1,1]], print(X), 1);
  818 [0, 0]
  819 [0, 1]
  820 [1, 1]
  821 ? forvec (X=[[0,1],[-1,1]], print(X), 2)
  822 [0, 1]
  823 @eprog
  824 
  825 \subsec{if$(a,\{\var{seq1}\},\{\var{seq2}\})$}\kbdsidx{if}\label{se:if}
  826 Evaluates the expression sequence \var{seq1} if $a$ is nonzero, otherwise
  827 the expression \var{seq2}. Of course, \var{seq1} or \var{seq2} may be empty:
  828 
  829 \kbd{if ($a$,\var{seq})} evaluates \var{seq} if $a$ is not equal to zero
  830 (you don't have to write the second comma), and does nothing otherwise,
  831 
  832 \kbd{if ($a$,,\var{seq})} evaluates \var{seq} if $a$ is equal to zero, and
  833 does nothing otherwise. You could get the same result using the \kbd{!}
  834 (\kbd{not}) operator: \kbd{if (!$a$,\var{seq})}.
  835 
  836 The value of an \kbd{if} statement is the value of the branch that gets
  837 evaluated: for instance
  838 \bprog
  839 x = if(n % 4 == 1, y, z);
  840 @eprog\noindent sets $x$ to $y$ if $n$ is $1$ modulo $4$, and to $z$
  841 otherwise.
  842 
  843 Successive 'else' blocks can be abbreviated in a single compound \kbd{if}
  844 as follows:
  845 \bprog
  846 if (test1, seq1,
  847     test2, seq2,
  848     ...
  849     testn, seqn,
  850     seqdefault);
  851 @eprog\noindent is equivalent to
  852 \bprog
  853 if (test1, seq1
  854          , if (test2, seq2
  855                     , ...
  856                       if (testn, seqn, seqdefault)...));
  857 @eprog For instance, this allows to write traditional switch / case
  858 constructions:
  859 \bprog
  860 if (x == 0, do0(),
  861     x == 1, do1(),
  862     x == 2, do2(),
  863     dodefault());
  864 @eprog
  865 
  866 \misctitle{Remark}
  867 The boolean operators \kbd{\&\&} and \kbd{||} are evaluated
  868 according to operator precedence as explained in \secref{se:operators}, but,
  869 contrary to other operators, the evaluation of the arguments is stopped
  870 as soon as the final truth value has been determined. For instance
  871 \bprog
  872 if (x != 0 && f(1/x), ...)
  873 @eprog
  874 \noindent is a perfectly safe statement.
  875 
  876 \misctitle{Remark} Functions such as \kbd{break} and \kbd{next} operate on
  877 \emph{loops}, such as \kbd{for$xxx$}, \kbd{while}, \kbd{until}. The \kbd{if}
  878 statement is \emph{not} a loop. (Obviously!)
  879 
  880 \subsec{iferr$(\var{seq1},E,\var{seq2},\{\var{pred}\})$}\kbdsidx{iferr}\label{se:iferr}
  881 Evaluates the expression sequence \var{seq1}. If an error occurs,
  882 set the formal parameter \var{E} set to the error data.
  883 If \var{pred} is not present or evaluates to true, catch the error
  884 and evaluate \var{seq2}. Both \var{pred} and \var{seq2} can reference \var{E}.
  885 The error type is given by \kbd{errname(E)}, and other data can be
  886 accessed using the \tet{component} function. The code \var{seq2} should check
  887 whether the error is the one expected. In the negative the error can be
  888 rethrown using \tet{error(E)} (and possibly caught by an higher \kbd{iferr}
  889 instance). The following uses \kbd{iferr} to implement Lenstra's ECM factoring
  890  method
  891 \bprog
  892 ? ecm(N, B = 1000!, nb = 100)=
  893   {
  894     for(a = 1, nb,
  895       iferr(ellmul(ellinit([a,1]*Mod(1,N)), [0,1]*Mod(1,N), B),
  896         E, return(gcd(lift(component(E,2)),N)),
  897         errname(E)=="e_INV" && type(component(E,2)) == "t_INTMOD"))
  898   }
  899 ? ecm(2^101-1)
  900 %2 = 7432339208719
  901 @eprog
  902 The return value of \kbd{iferr} itself is the value of \var{seq2} if an
  903 error occurs, and the value of \var{seq1} otherwise. We now describe the
  904 list of valid error types, and the attached error data \var{E}; in each
  905 case, we list in order the components of \var{E}, accessed via
  906 \kbd{component(E,1)}, \kbd{component(E,2)}, etc.
  907 
  908  \misctitle{Internal errors, ``system'' errors}
  909 
  910  \item \kbd{"e\_ARCH"}. A requested feature $s$ is not available on this
  911  architecture or operating system.
  912  \var{E} has one component (\typ{STR}): the missing feature name $s$.
  913 
  914  \item \kbd{"e\_BUG"}. A bug in the PARI library, in function $s$.
  915  \var{E} has one component (\typ{STR}): the function name $s$.
  916 
  917  \item \kbd{"e\_FILE"}. Error while trying to open a file.
  918  \var{E} has two components, 1 (\typ{STR}): the file type (input, output,
  919  etc.), 2 (\typ{STR}): the file name.
  920 
  921  \item \kbd{"e\_IMPL"}. A requested feature $s$ is not implemented.
  922  \var{E} has one component, 1 (\typ{STR}): the feature name $s$.
  923 
  924  \item \kbd{"e\_PACKAGE"}. Missing optional package $s$.
  925  \var{E} has one component, 1 (\typ{STR}): the package name $s$.
  926 
  927  \misctitle{Syntax errors, type errors}
  928 
  929  \item \kbd{"e\_DIM"}. The dimensions of arguments $x$ and $y$ submitted
  930  to function $s$ does not match up.
  931  E.g., multiplying matrices of inconsistent dimension, adding vectors of
  932  different lengths,\dots
  933  \var{E} has three component, 1 (\typ{STR}): the function name $s$, 2: the
  934  argument $x$, 3: the argument $y$.
  935 
  936  \item \kbd{"e\_FLAG"}. A flag argument is out of bounds in function $s$.
  937  \var{E} has one component, 1 (\typ{STR}): the function name $s$.
  938 
  939  \item \kbd{"e\_NOTFUNC"}. Generated by the PARI evaluator; tried to use a
  940 \kbd{GEN} $x$ which is not a \typ{CLOSURE} in a function call syntax (as in
  941 \kbd{f = 1; f(2);}).
  942  \var{E} has one component, 1: the offending \kbd{GEN} $x$.
  943 
  944  \item \kbd{"e\_OP"}. Impossible operation between two objects than cannot
  945  be typecast to a sensible common domain for deeper reasons than a type
  946  mismatch, usually for arithmetic reasons. As in \kbd{O(2) + O(3)}: it is
  947  valid to add two \typ{PADIC}s, provided the underlying prime is the same; so
  948  the addition is not forbidden a priori for type reasons, it only becomes so
  949  when inspecting the objects and trying to perform the operation.
  950  \var{E} has three components, 1 (\typ{STR}): the operator name \var{op},
  951  2: first argument, 3: second argument.
  952 
  953  \item \kbd{"e\_TYPE"}. An argument $x$ of function $s$ had an unexpected type.
  954  (As in \kbd{factor("blah")}.)
  955  \var{E} has two components, 1 (\typ{STR}): the function name $s$,
  956  2: the offending argument $x$.
  957 
  958  \item \kbd{"e\_TYPE2"}. Forbidden operation between two objects than cannot be
  959  typecast to a sensible common domain, because their types do not match up.
  960  (As in \kbd{Mod(1,2) + Pi}.)
  961  \var{E} has three components, 1 (\typ{STR}): the operator name \var{op},
  962  2: first argument, 3: second argument.
  963 
  964  \item \kbd{"e\_PRIORITY"}. Object $o$ in function $s$ contains
  965  variables whose priority is incompatible with the expected operation.
  966  E.g.~\kbd{Pol([x,1], 'y)}: this raises an error because it's not possible to
  967  create a polynomial whose coefficients involve variables with higher priority
  968  than the main variable. $E$ has four components: 1 (\typ{STR}): the function
  969  name $s$, 2: the offending argument $o$, 3 (\typ{STR}): an operator
  970  $\var{op}$ describing the priority error, 4 (\typ{POL}):
  971  the variable $v$ describing the priority error. The argument
  972  satisfies $\kbd{variable}(x)~\var{op} \kbd{variable}(v)$.
  973 
  974  \item \kbd{"e\_VAR"}. The variables of arguments $x$ and $y$ submitted
  975  to function $s$ does not match up. E.g., considering the algebraic number
  976  \kbd{Mod(t,t\pow2+1)} in \kbd{nfinit(x\pow2+1)}.
  977  \var{E} has three component, 1 (\typ{STR}): the function name $s$, 2
  978  (\typ{POL}): the argument $x$, 3 (\typ{POL}): the argument $y$.
  979 
  980  \misctitle{Overflows}
  981 
  982  \item \kbd{"e\_COMPONENT"}. Trying to access an inexistent component in a
  983  vector/matrix/list in a function: the index is less than $1$ or greater
  984  than the allowed length.
  985  \var{E} has four components,
  986  1 (\typ{STR}): the function name
  987  2 (\typ{STR}): an operator $\var{op}$ ($<$ or $>$),
  988  2 (\typ{GEN}): a numerical limit $l$ bounding the allowed range,
  989  3 (\kbd{GEN}): the index $x$. It satisfies $x$ \var{op} $l$.
  990 
  991  \item \kbd{"e\_DOMAIN"}. An argument is not in the function's domain.
  992  \var{E} has five components, 1 (\typ{STR}): the function name,
  993  2 (\typ{STR}): the mathematical name of the out-of-domain argument
  994  3 (\typ{STR}): an operator $\var{op}$ describing the domain error,
  995  4 (\typ{GEN}): the numerical limit $l$ describing the domain error,
  996  5 (\kbd{GEN}): the out-of-domain argument $x$. The argument satisfies $x$
  997  \var{op} $l$, which prevents it from belonging to the function's domain.
  998 
  999  \item \kbd{"e\_MAXPRIME"}. A function using the precomputed list of prime
 1000  numbers ran out of primes.
 1001  \var{E} has one component, 1 (\typ{INT}): the requested prime bound, which
 1002  overflowed \kbd{primelimit} or $0$ (bound is unknown).
 1003 
 1004  \item \kbd{"e\_MEM"}. A call to \tet{pari_malloc} or \tet{pari_realloc}
 1005  failed. \var{E} has no component.
 1006 
 1007  \item \kbd{"e\_OVERFLOW"}. An object in function $s$ becomes too large to be
 1008  represented within PARI's hardcoded limits. (As in \kbd{2\pow2\pow2\pow10} or
 1009  \kbd{exp(1e100)}, which overflow in \kbd{lg} and \kbd{expo}.)
 1010  \var{E} has one component, 1 (\typ{STR}): the function name $s$.
 1011 
 1012  \item \kbd{"e\_PREC"}. Function $s$ fails because input accuracy is too low.
 1013  (As in \kbd{floor(1e100)} at default accuracy.)
 1014  \var{E} has one component, 1 (\typ{STR}): the function name $s$.
 1015 
 1016  \item \kbd{"e\_STACK"}. The PARI stack overflows.
 1017  \var{E} has no component.
 1018 
 1019  \misctitle{Errors triggered intentionally}
 1020 
 1021  \item \kbd{"e\_ALARM"}. A timeout, generated by the \tet{alarm} function.
 1022  \var{E} has one component (\typ{STR}): the error message to print.
 1023 
 1024  \item \kbd{"e\_USER"}. A user error, as triggered by
 1025  \tet{error}($g_1,\dots,g_n)$.
 1026  \var{E} has one component, 1 (\typ{VEC}): the vector of $n$ arguments given
 1027  to \kbd{error}.
 1028 
 1029  \misctitle{Mathematical errors}
 1030 
 1031  \item \kbd{"e\_CONSTPOL"}. An argument of function $s$ is a constant
 1032  polynomial, which does not make sense. (As in \kbd{galoisinit(Pol(1))}.)
 1033  \var{E} has one component, 1 (\typ{STR}): the function name $s$.
 1034 
 1035  \item \kbd{"e\_COPRIME"}. Function $s$ expected coprime arguments,
 1036  and did receive $x,y$, which were not.
 1037  \var{E} has three component, 1 (\typ{STR}): the function name $s$,
 1038  2: the argument $x$, 3: the argument $y$.
 1039 
 1040  \item \kbd{"e\_INV"}. Tried to invert a noninvertible object $x$ in
 1041  function $s$.
 1042  \var{E} has two components, 1 (\typ{STR}): the function name $s$,
 1043  2: the noninvertible $x$. If $x = \kbd{Mod}(a,b)$
 1044  is a \typ{INTMOD} and $a$ is not $0$ mod $b$, this allows to factor
 1045  the modulus, as \kbd{gcd}$(a,b)$ is a nontrivial divisor of $b$.
 1046 
 1047  \item \kbd{"e\_IRREDPOL"}. Function $s$ expected an irreducible polynomial,
 1048  and did receive $T$, which was not. (As in \kbd{nfinit(x\pow2-1)}.)
 1049  \var{E} has two component, 1 (\typ{STR}): the function name $s$,
 1050  2 (\typ{POL}): the polynomial $x$.
 1051 
 1052  \item \kbd{"e\_MISC"}. Generic uncategorized error.
 1053  \var{E} has one component (\typ{STR}): the error message to print.
 1054 
 1055  \item \kbd{"e\_MODULUS"}. moduli $x$ and $y$ submitted to function $s$ are
 1056  inconsistent. As in
 1057  \bprog
 1058    nfalgtobasis(nfinit(t^3-2), Mod(t,t^2+1)
 1059  @eprog\noindent
 1060  \var{E} has three component, 1 (\typ{STR}): the function $s$,
 1061  2: the argument $x$, 3: the argument $x$.
 1062 
 1063  \item \kbd{"e\_PRIME"}. Function $s$ expected a prime number,
 1064  and did receive $p$, which was not. (As in \kbd{idealprimedec(nf, 4)}.)
 1065  \var{E} has two component, 1 (\typ{STR}): the function name $s$,
 1066  2: the argument $p$.
 1067 
 1068  \item \kbd{"e\_ROOTS0"}. An argument of function $s$ is a zero polynomial,
 1069  and we need to consider its roots. (As in \kbd{polroots(0)}.) \var{E} has
 1070  one component, 1 (\typ{STR}): the function name $s$.
 1071 
 1072  \item \kbd{"e\_SQRTN"}. Trying to compute an $n$-th root of $x$, which does
 1073  not exist, in function $s$. (As in \kbd{sqrt(Mod(-1,3))}.)
 1074  \var{E} has two components, 1 (\typ{STR}): the function name $s$,
 1075  2: the argument $x$.
 1076 
 1077 \subsec{next$(\{n=1\})$}\kbdsidx{next}\label{se:next}
 1078 Interrupts execution of current $seq$,
 1079 resume the next iteration of the innermost enclosing loop, within the
 1080 current function call (or top level loop). If $n$ is specified, resume at
 1081 the $n$-th enclosing loop. If $n$ is bigger than the number of enclosing
 1082 loops, all enclosing loops are exited.
 1083 
 1084 \subsec{return$(\{x=0\})$}\kbdsidx{return}\label{se:return}
 1085 Returns from current subroutine, with
 1086 result $x$. If $x$ is omitted, return the \kbd{(void)} value (return no
 1087 result, like \kbd{print}).
 1088 
 1089 \subsec{until$(a,\var{seq})$}\kbdsidx{until}\label{se:until}
 1090 Evaluates \var{seq} until $a$ is not
 1091 equal to 0 (i.e.~until $a$ is true). If $a$ is initially not equal to 0,
 1092 \var{seq} is evaluated once (more generally, the condition on $a$ is tested
 1093 \emph{after} execution of the \var{seq}, not before as in \kbd{while}).
 1094 
 1095 \subsec{while$(a,\var{seq})$}\kbdsidx{while}\label{se:while}
 1096 While $a$ is nonzero, evaluates the expression sequence \var{seq}. The
 1097 test is made \emph{before} evaluating the $seq$, hence in particular if $a$
 1098 is initially equal to zero the \var{seq} will not be evaluated at all.
 1099 
 1100 \section{Programming in GP: other specific functions}
 1101 \label{se:gp_program}
 1102 
 1103   In addition to the general PARI functions, it is necessary to have some
 1104 functions which will be of use specifically for \kbd{gp}, though a few of these
 1105 can be accessed under library mode. Before we start describing these, we recall
 1106 the difference between \emph{strings} and \emph{keywords} (see
 1107 \secref{se:strings}): the latter don't get expanded at all, and you can type
 1108 them without any enclosing quotes. The former are dynamic objects, where
 1109 everything outside quotes gets immediately expanded.
 1110 
 1111 \subsec{Strchr$(x)$}\kbdsidx{Strchr}\label{se:Strchr}
 1112 Deprecated alias for strchr.
 1113 
 1114 The library syntax is \fun{GEN}{pari_strchr}{GEN x}.
 1115 
 1116 \subsec{Strexpand$(\{x\}*)$}\kbdsidx{Strexpand}\label{se:Strexpand}
 1117 Deprecated alias for strexpand
 1118 
 1119 The library syntax is \fun{GEN}{strexpand}{const char *x*}.
 1120 
 1121 \subsec{Strprintf$(\var{fmt},\{x\}*)$}\kbdsidx{Strprintf}\label{se:Strprintf}
 1122 Deprecated alias for strprintf.
 1123 
 1124 The library syntax is \fun{GEN}{Strprintf}{const char *fmt, const char *x*}.
 1125 
 1126 \subsec{Strtex$(\{x\}*)$}\kbdsidx{Strtex}\label{se:Strtex}
 1127 Deprecated alias for strtex.
 1128 
 1129 The library syntax is \fun{GEN}{strtex}{const char *x*}.
 1130 
 1131 \subsec{addhelp$(\var{sym},\var{str})$}\kbdsidx{addhelp}\label{se:addhelp}
 1132 Changes the help message for the symbol \kbd{sym}. The string \var{str}
 1133 is expanded on the spot and stored as the online help for \kbd{sym}. It is
 1134 recommended to document global variables and user functions in this way,
 1135 although \kbd{gp} will not protest if you don't.
 1136 
 1137 You can attach a help text to an alias, but it will never be
 1138 shown: aliases are expanded by the \kbd{?} help operator and we get the help
 1139 of the symbol the alias points to. Nothing prevents you from modifying the
 1140 help of built-in PARI functions. But if you do, we would like to hear why you
 1141 needed it!
 1142 
 1143 Without \tet{addhelp}, the standard help for user functions consists of its
 1144 name and definition.
 1145 \bprog
 1146 gp> f(x) = x^2;
 1147 gp> ?f
 1148 f =
 1149   (x)->x^2
 1150 
 1151 @eprog\noindent Once addhelp is applied to $f$, the function code is no
 1152 longer included. It can still be consulted by typing the function name:
 1153 \bprog
 1154 gp> addhelp(f, "Square")
 1155 gp> ?f
 1156 Square
 1157 
 1158 gp> f
 1159 %2 = (x)->x^2
 1160 @eprog
 1161 
 1162 The library syntax is \fun{void}{addhelp}{const char *sym, const char *str}.
 1163 
 1164 \subsec{alarm$(\{s = 0\},\{\var{code}\})$}\kbdsidx{alarm}\label{se:alarm}
 1165 If \var{code} is omitted, trigger an \var{e\_ALARM} exception after $s$
 1166 seconds (wall-clock time), cancelling any previously set alarm; stop a pending
 1167 alarm if $s = 0$ or is omitted.
 1168 
 1169 Otherwise, if $s$ is positive, the function evaluates \var{code},
 1170 aborting after $s$ seconds. The return value is the value of \var{code} if
 1171 it ran to completion before the alarm timeout, and a \typ{ERROR} object
 1172 otherwise.
 1173 \bprog
 1174   ? p = nextprime(10^25); q = nextprime(10^26); N = p*q;
 1175   ? E = alarm(1, factor(N));
 1176   ? type(E)
 1177   %3 = "t_ERROR"
 1178   ? print(E)
 1179   %4 = error("alarm interrupt after 964 ms.")
 1180   ? alarm(10, factor(N));   \\ enough time
 1181   %5 =
 1182   [ 10000000000000000000000013 1]
 1183 
 1184   [100000000000000000000000067 1]
 1185 @eprog\noindent Here is a more involved example: the function
 1186 \kbd{timefact(N,sec)} below tries to factor $N$ and gives up after \var{sec}
 1187 seconds, returning a partial factorization.
 1188 \bprog
 1189 \\ Time-bounded partial factorization
 1190 default(factor_add_primes,1);
 1191 timefact(N,sec)=
 1192 {
 1193   F = alarm(sec, factor(N));
 1194   if (type(F) == "t_ERROR", factor(N, 2^24), F);
 1195 }
 1196 @eprog\noindent We either return the factorization directly, or replace the
 1197 \typ{ERROR} result by a simple bounded factorization \kbd{factor(N, 2\pow 24)}.
 1198 Note the \tet{factor_add_primes} trick: any prime larger than $2^{24}$
 1199 discovered while attempting the initial factorization is stored and
 1200 remembered. When the alarm rings, the subsequent bounded factorization finds
 1201 it right away.
 1202 
 1203 \misctitle{Caveat} It is not possible to set a new alarm \emph{within}
 1204 another \kbd{alarm} code: the new timer erases the parent one.
 1205 
 1206 The library syntax is \fun{GEN}{gp_alarm}{long s, GEN code = NULL}.
 1207 
 1208 \subsec{alias$(\var{newsym},\var{sym})$}\kbdsidx{alias}\label{se:alias}
 1209 Defines the symbol \var{newsym} as an alias for the symbol \var{sym}:
 1210 \bprog
 1211 ? alias("det", "matdet");
 1212 ? det([1,2;3,4])
 1213 %1 = -2
 1214 @eprog\noindent
 1215 You are not restricted to ordinary functions, as in the above example:
 1216 to alias (from/to) member functions, prefix them with `\kbd{\_.}';
 1217 to alias operators, use their internal name, obtained by writing
 1218 \kbd{\_} in lieu of the operators argument: for instance, \kbd{\_!} and
 1219 \kbd{!\_} are the internal names of the factorial and the
 1220 logical negation, respectively.
 1221 \bprog
 1222 ? alias("mod", "_.mod");
 1223 ? alias("add", "_+_");
 1224 ? alias("_.sin", "sin");
 1225 ? mod(Mod(x,x^4+1))
 1226 %2 = x^4 + 1
 1227 ? add(4,6)
 1228 %3 = 10
 1229 ? Pi.sin
 1230 %4 = 0.E-37
 1231 @eprog
 1232 Alias expansion is performed directly by the internal GP compiler.
 1233 Note that since alias is performed at compilation-time, it does not
 1234 require any run-time processing, however it only affects GP code
 1235 compiled \emph{after} the alias command is evaluated. A slower but more
 1236 flexible alternative is to use variables. Compare
 1237 \bprog
 1238 ? fun = sin;
 1239 ? g(a,b) = intnum(t=a,b,fun(t));
 1240 ? g(0, Pi)
 1241 %3 = 2.0000000000000000000000000000000000000
 1242 ? fun = cos;
 1243 ? g(0, Pi)
 1244 %5 = 1.8830410776607851098 E-39
 1245 @eprog\noindent
 1246 with
 1247 \bprog
 1248 ? alias(fun, sin);
 1249 ? g(a,b) = intnum(t=a,b,fun(t));
 1250 ? g(0,Pi)
 1251 %2 = 2.0000000000000000000000000000000000000
 1252 ? alias(fun, cos);  \\ Oops. Does not affect *previous* definition!
 1253 ? g(0,Pi)
 1254 %3 = 2.0000000000000000000000000000000000000
 1255 ? g(a,b) = intnum(t=a,b,fun(t)); \\ Redefine, taking new alias into account
 1256 ? g(0,Pi)
 1257 %5 = 1.8830410776607851098 E-39
 1258 @eprog
 1259 
 1260 A sample alias file \kbd{misc/gpalias} is provided with
 1261 the standard distribution.
 1262 
 1263 The library syntax is \fun{void}{alias0}{const char *newsym, const char *sym}.
 1264 
 1265 \subsec{allocatemem$(\{s=0\})$}\kbdsidx{allocatemem}\label{se:allocatemem}
 1266 This special operation changes the stack size \emph{after}
 1267 initialization. The argument $s$ must be a nonnegative integer.
 1268 If $s > 0$, a new stack of at least $s$ bytes is allocated. We may allocate
 1269 more than $s$ bytes if $s$ is way too small, or for alignment reasons: the
 1270 current formula is $\max(16*\ceil{s/16}, 500032)$ bytes.
 1271 
 1272 If $s=0$, the size of the new stack is twice the size of the old one.
 1273 
 1274 This command is much more useful if \tet{parisizemax} is nonzero, and we
 1275 describe this case first. With \kbd{parisizemax} enabled, there are three
 1276 sizes of interest:
 1277 
 1278 \item a virtual stack size, \tet{parisizemax}, which is an absolute upper
 1279 limit for the stack size; this is set by \kbd{default(parisizemax, ...)}.
 1280 
 1281 \item the desired typical stack size, \tet{parisize}, that will grow as
 1282 needed, up to \tet{parisizemax}; this is set by \kbd{default(parisize, ...)}.
 1283 
 1284 \item the current stack size, which is less that \kbd{parisizemax},
 1285 typically equal to \kbd{parisize} but possibly larger and increasing
 1286 dynamically as needed; \kbd{allocatemem} allows to change that one
 1287 explicitly.
 1288 
 1289 The \kbd{allocatemem} command forces stack
 1290 usage to increase temporarily (up to \kbd{parisizemax} of course); for
 1291 instance if you notice using \kbd{\bs gm2} that we seem to collect garbage a
 1292 lot, e.g.
 1293 \bprog
 1294 ? \gm2
 1295   debugmem = 2
 1296 ? default(parisize,"32M")
 1297  ***   Warning: new stack size = 32000000 (30.518 Mbytes).
 1298 ? bnfinit('x^2+10^30-1)
 1299  *** bnfinit: collecting garbage in hnffinal, i = 1.
 1300  *** bnfinit: collecting garbage in hnffinal, i = 2.
 1301  *** bnfinit: collecting garbage in hnffinal, i = 3.
 1302 @eprog\noindent and so on for hundred of lines. Then, provided the
 1303 \tet{breakloop} default is set, you can interrupt the computation, type
 1304 \kbd{allocatemem(100*10\pow6)} at the break loop prompt, then let the
 1305 computation go on by typing \kbd{<Enter>}. Back at the \kbd{gp} prompt,
 1306 the desired stack size of \kbd{parisize} is restored. Note that changing either
 1307 \kbd{parisize} or \kbd{parisizemax} at the break loop prompt would interrupt
 1308 the computation, contrary to the above.
 1309 
 1310 In most cases, \kbd{parisize} will increase automatically (up to
 1311 \kbd{parisizemax}) and there is no need to perform the above maneuvers.
 1312 But that the garbage collector is sufficiently efficient that
 1313 a given computation can still run without increasing the stack size,
 1314 albeit very slowly due to the frequent garbage collections.
 1315 
 1316 \misctitle{Deprecated: when \kbd{parisizemax} is unset}
 1317 This is currently still the default behavior in order not to break backward
 1318 compatibility. The rest of this section documents the
 1319 behavior of \kbd{allocatemem} in that (deprecated) situation: it becomes a
 1320 synonym for \kbd{default(parisize,...)}. In that case, there is no
 1321 notion of a virtual stack, and the stack size is always equal to
 1322 \kbd{parisize}. If more memory is needed, the PARI stack overflows, aborting
 1323 the computation.
 1324 
 1325 Thus, increasing \kbd{parisize} via \kbd{allocatemem} or
 1326 \kbd{default(parisize,...)} before a big computation is important.
 1327 Unfortunately, either must be typed at the \kbd{gp} prompt in
 1328 interactive usage, or left by itself at the start of batch files.
 1329 They cannot be used meaningfully in loop-like constructs, or as part of a
 1330 larger expression sequence, e.g
 1331 \bprog
 1332    allocatemem(); x = 1;   \\@com This will not set \kbd{x}!
 1333 @eprog\noindent
 1334 In fact, all loops are immediately exited, user functions terminated, and
 1335 the rest of the sequence following \kbd{allocatemem()} is silently
 1336 discarded, as well as all pending sequences of instructions. We just go on
 1337 reading the next instruction sequence from the file we are in (or from the
 1338 user). In particular, we have the following possibly unexpected behavior: in
 1339 \bprog
 1340    read("file.gp"); x = 1
 1341 @eprog\noindent were \kbd{file.gp} contains an \kbd{allocatemem} statement,
 1342 the \kbd{x = 1} is never executed, since all pending instructions in the
 1343 current sequence are discarded.
 1344 
 1345 The reason for these unfortunate side-effects is that, with
 1346 \kbd{parisizemax} disabled, increasing the stack size physically
 1347 moves the stack, so temporary objects created during the current expression
 1348 evaluation are not correct anymore. (In particular byte-compiled expressions,
 1349 which are allocated on the stack.) To avoid accessing obsolete pointers to
 1350 the old stack, this routine ends by a \kbd{longjmp}.
 1351 
 1352 The library syntax is \fun{void}{gp_allocatemem}{GEN s = NULL}.
 1353 
 1354 \subsec{apply$(f, A)$}\kbdsidx{apply}\label{se:apply}
 1355 Apply the \typ{CLOSURE} \kbd{f} to the entries of \kbd{A}.
 1356 
 1357 \item If \kbd{A} is a scalar, return \kbd{f(A)}.
 1358 
 1359 \item If \kbd{A} is a polynomial or power series $\sum a_i x^i$ ($+
 1360 O(x^N)$), apply \kbd{f} on all coefficients and return $\sum f(a_i) x^i$ ($+
 1361 O(x^N)$).
 1362 
 1363 \item If \kbd{A} is a vector or list $[a_1,\dots,a_n]$, return the vector
 1364 or list $[f(a_1),\dots, f(a_n)]$. If \kbd{A} is a matrix, return the matrix
 1365 whose entries are the $f(\kbd{A[i,j]})$.
 1366 
 1367 \bprog
 1368 ? apply(x->x^2, [1,2,3,4])
 1369 %1 = [1, 4, 9, 16]
 1370 ? apply(x->x^2, [1,2;3,4])
 1371 %2 =
 1372 [1 4]
 1373 
 1374 [9 16]
 1375 ? apply(x->x^2, 4*x^2 + 3*x+ 2)
 1376 %3 = 16*x^2 + 9*x + 4
 1377 ? apply(sign, 2 - 3* x + 4*x^2 + O(x^3))
 1378 %4 = 1 - x + x^2 + O(x^3)
 1379 @eprog\noindent Note that many functions already act componentwise on
 1380 vectors or matrices, but they almost never act on lists; in this case,
 1381 \kbd{apply} is a good solution:
 1382 \bprog
 1383 ? L = List([Mod(1,3), Mod(2,4)]);
 1384 ? lift(L)
 1385   ***   at top-level: lift(L)
 1386   ***                 ^-------
 1387   *** lift: incorrect type in lift.
 1388 ? apply(lift, L);
 1389 %2 = List([1, 2])
 1390 @eprog
 1391 \misctitle{Remark} For $v$ a \typ{VEC}, \typ{COL}, \typ{VECSMALL},
 1392 \typ{LIST} or \typ{MAT}, the alternative set-notations
 1393 \bprog
 1394 [g(x) | x <- v, f(x)]
 1395 [x | x <- v, f(x)]
 1396 [g(x) | x <- v]
 1397 @eprog\noindent
 1398 are available as shortcuts for
 1399 \bprog
 1400 apply(g, select(f, Vec(v)))
 1401 select(f, Vec(v))
 1402 apply(g, Vec(v))
 1403 @eprog\noindent respectively:
 1404 \bprog
 1405 ? L = List([Mod(1,3), Mod(2,4)]);
 1406 ? [ lift(x) | x<-L ]
 1407 %2 = [1, 2]
 1408 @eprog
 1409 
 1410 \synt{genapply}{void *E, GEN (*fun)(void*,GEN), GEN a}.
 1411 
 1412 \subsec{arity$(C)$}\kbdsidx{arity}\label{se:arity}
 1413 Return the arity of the closure $C$, i.e., the number of its arguments.
 1414 \bprog
 1415 ? f1(x,y=0)=x+y;
 1416 ? arity(f1)
 1417 %1 = 2
 1418 ? f2(t,s[..])=print(t,":",s);
 1419 ? arity(f2)
 1420 %2 = 2
 1421 @eprog\noindent Note that a variadic argument, such as $s$ in \kbd{f2} above,
 1422 is counted as a single argument.
 1423 
 1424 The library syntax is \fun{GEN}{arity0}{GEN C}.
 1425 
 1426 \subsec{call$(f, A)$}\kbdsidx{call}\label{se:call}
 1427 $A=[a_1,\dots, a_n]$ being a vector and $f$ being a function, returns the
 1428 evaluation of $f(a_1,\dots,a_n)$.
 1429 $f$ can also be the name of a built-in GP function.
 1430 If $\# A =1$, \tet{call}($f,A$) = \tet{apply}($f,A$)[1].
 1431 If $f$ is variadic, the variadic arguments must grouped in a vector in
 1432 the last component of $A$.
 1433 
 1434 This function is useful
 1435 
 1436 \item when writing a variadic function, to call another one:
 1437 \bprog
 1438 fprintf(file,format,args[..]) = write(file,call(strprintf,[format,args]))
 1439 @eprog
 1440 
 1441 \item when dealing with function arguments with unspecified arity
 1442 
 1443 The function below implements a global memoization interface:
 1444 \bprog
 1445 memo=Map();
 1446 memoize(f,A[..])=
 1447 {
 1448   my(res);
 1449   if(!mapisdefined(memo, [f,A], &res),
 1450     res = call(f,A);
 1451     mapput(memo,[f,A],res));
 1452  res;
 1453 }
 1454 @eprog
 1455 for example:
 1456 \bprog
 1457 ? memoize(factor,2^128+1)
 1458 %3 = [59649589127497217,1;5704689200685129054721,1]
 1459 ? ##
 1460   ***   last result computed in 76 ms.
 1461 ? memoize(factor,2^128+1)
 1462 %4 = [59649589127497217,1;5704689200685129054721,1]
 1463 ? ##
 1464   ***   last result computed in 0 ms.
 1465 ? memoize(ffinit,3,3)
 1466 %5 = Mod(1,3)*x^3+Mod(1,3)*x^2+Mod(1,3)*x+Mod(2,3)
 1467 ? fibo(n)=if(n==0,0,n==1,1,memoize(fibo,n-2)+memoize(fibo,n-1));
 1468 ? fibo(100)
 1469 %7 = 354224848179261915075
 1470 @eprog
 1471 
 1472 \item to call operators through their internal names without using
 1473 \kbd{alias}
 1474 \bprog
 1475 matnbelts(M) = call("_*_",matsize(M))
 1476 @eprog
 1477 
 1478 The library syntax is \fun{GEN}{call0}{GEN f, GEN A}.
 1479 
 1480 \subsec{default$(\{\var{key}\},\{\var{val}\})$}\kbdsidx{default}\label{se:default}
 1481 Returns the default corresponding to keyword \var{key}. If \var{val} is
 1482 present, sets the default to \var{val} first (which is subject to string
 1483 expansion first). Typing \kbd{default()} (or \b{d}) yields the complete
 1484 default list as well as their current values. See \secref{se:defaults} for an
 1485 introduction to GP defaults, \secref{se:gp_defaults} for a
 1486 list of available defaults, and \secref{se:meta} for some shortcut
 1487 alternatives. Note that the shortcuts are meant for interactive use and
 1488 usually display more information than \kbd{default}.
 1489 
 1490 The library syntax is \fun{GEN}{default0}{const char *key = NULL, const char *val = NULL}.
 1491 
 1492 \subsec{errname$(E)$}\kbdsidx{errname}\label{se:errname}
 1493 Returns the type of the error message \kbd{E} as a string.
 1494 \bprog
 1495 ? iferr(1 / 0, E, print(errname(E)))
 1496 e_INV
 1497 ? ?? e_INV
 1498 [...]
 1499 * "e_INV".  Tried to invert a noninvertible object x in function s.
 1500 [...]
 1501 @eprog
 1502 
 1503 The library syntax is \fun{GEN}{errname}{GEN E}.
 1504 
 1505 \subsec{error$(\{\var{str}\}*)$}\kbdsidx{error}\label{se:error}
 1506 Outputs its argument list (each of
 1507 them interpreted as a string), then interrupts the running \kbd{gp} program,
 1508 returning to the input prompt. For instance
 1509 \bprog
 1510 error("n = ", n, " is not squarefree!")
 1511 @eprog\noindent
 1512  % \syn{NO}
 1513 
 1514 \subsec{export$(x\{=...\},...,z\{=...\})$}\kbdsidx{export}\label{se:export}
 1515 Export the variables $x,\ldots, z$ to the parallel world.
 1516 Such variables are visible inside parallel sections in place of global
 1517 variables, but cannot be modified inside a parallel section.
 1518 \kbd{export(a)} set the variable $a$ in the parallel world to current value of $a$.
 1519 \kbd{export(a=z)} set the variable $a$ in the parallel world to $z$, without
 1520 affecting the current value of $a$.
 1521 \bprog
 1522 ? fun(x)=x^2+1;
 1523 ? parvector(10,i,fun(i))
 1524   ***   mt: please use export(fun).
 1525 ? export(fun)
 1526 ? parvector(10,i,fun(i))
 1527 %4 = [2,5,10,17,26,37,50,65,82,101]
 1528 @eprog
 1529 
 1530 \subsec{exportall$()$}\kbdsidx{exportall}\label{se:exportall}
 1531 Declare all current dynamic variables as exported variables.
 1532 Such variables are visible inside parallel sections in place of global variables.
 1533 \bprog
 1534 ? fun(x)=x^2+1;
 1535 ? parvector(10,i,fun(i))
 1536   ***   mt: please use export(fun).
 1537 ? exportall()
 1538 ? parvector(10,i,fun(i))
 1539 %4 = [2,5,10,17,26,37,50,65,82,101]
 1540 @eprog
 1541 
 1542 The library syntax is \fun{void}{exportall}{}.
 1543 
 1544 \subsec{extern$(\var{str})$}\kbdsidx{extern}\label{se:extern}
 1545 The string \var{str} is the name of an external command (i.e.~one you
 1546 would type from your UNIX shell prompt). This command is immediately run and
 1547 its output fed into \kbd{gp}, just as if read from a file.
 1548 
 1549 The library syntax is \fun{GEN}{gpextern}{const char *str}.
 1550 
 1551 \subsec{externstr$(\var{str})$}\kbdsidx{externstr}\label{se:externstr}
 1552 The string \var{str} is the name of an external command (i.e.~one you
 1553 would type from your UNIX shell prompt). This command is immediately run and
 1554 its output is returned as a vector of GP strings, one component per output
 1555 line.
 1556 
 1557 The library syntax is \fun{GEN}{externstr}{const char *str}.
 1558 
 1559 \subsec{fileclose$(n)$}\kbdsidx{fileclose}\label{se:fileclose}
 1560 Close the file descriptor $n$, created via \kbd{fileopen} or
 1561 \kbd{fileextern}. Finitely many files can be opened at a given time,
 1562 closing them recycles file descriptors and avoids running out of them:
 1563 \bprog
 1564 ? n = 0; while(n++, fileopen("/tmp/test", "w"))
 1565  ***   at top-level: n=0;while(n++,fileopen("/tmp/test","w"))
 1566  ***                               ^--------------------------
 1567  *** fileopen: error opening requested file: `/tmp/test'.
 1568  ***   Break loop: type 'break' to go back to GP prompt
 1569 break> n
 1570 65533
 1571 @eprog\noindent This is a limitation of the operating system and does not
 1572 depend on PARI: if you open too many files in \kbd{gp} without closing them,
 1573 the operating system will also prevent unrelated applications from opening
 1574 files. Independently, your operating system (e.g. Windows) may prevent other
 1575 applications from accessing or deleting your file while it is opened by
 1576 \kbd{gp}. Quitting \kbd{gp} implicitly calls this function on all opened
 1577 file descriptors.
 1578 
 1579 On files opened for writing, this function also forces a write of all
 1580 buffered data to the file system and completes all pending write operations.
 1581 This function is implicitly called for all open file descriptors when
 1582 exiting \kbd{gp} but it is cleaner and safer to call it explicitly, for
 1583 instance in case of a \kbd{gp} crash or general system failure, which could
 1584 cause data loss.
 1585 \bprog
 1586 ? n = fileopen("./here");
 1587 ? while(l = fileread(n), print(l));
 1588 ? fileclose(n);
 1589 
 1590 ? n = fileopen("./there", "w");
 1591 ? for (i = 1, 100, filewrite(n, i^2+1))
 1592 ? fileclose(n)
 1593 @eprog Until a \kbd{fileclose}, there is no guarantee that the file on disk
 1594 contains all the expected data from previous \kbd{filewrite}s. (And even
 1595 then the operating system may delay the actual write to hardware.)
 1596 
 1597 Closing a file twice raises an exception:
 1598 \bprog
 1599 ? n = fileopen("/tmp/test");
 1600 ? fileclose(n)
 1601 ? fileclose(n)
 1602  ***   at top-level: fileclose(n)
 1603  ***                 ^------------
 1604  *** fileclose: invalid file descriptor 0
 1605 @eprog
 1606 
 1607 The library syntax is \fun{void}{gp_fileclose}{long n}.
 1608 
 1609 \subsec{fileextern$(\var{str})$}\kbdsidx{fileextern}\label{se:fileextern}
 1610 The string \var{str} is the name of an external command, i.e.~one you
 1611 would type from your UNIX shell prompt. This command is immediately run and
 1612 the function returns a file descriptor attached to the command output as if
 1613 it were read from a file.
 1614 \bprog
 1615 ? n = fileextern("ls -l");
 1616 ? while(l = filereadstr(n), print(l))
 1617 ? fileclose(n)
 1618 @eprog\noindent If the \kbd{secure} default is set, this function will raise
 1619 en exception.
 1620 
 1621 The library syntax is \fun{long}{gp_fileextern}{const char *str}.
 1622 
 1623 \subsec{fileflush$(\{n\})$}\kbdsidx{fileflush}\label{se:fileflush}
 1624 Flushes the file descriptor $n$, created via \kbd{fileopen} or
 1625 \kbd{fileextern}. On files opened for writing, this function forces a write
 1626 of all buffered data to the file system and completes all pending write
 1627 operations. This function is implicitly called by \kbd{fileclose} but you may
 1628 want to call it explicitly at synchronization points, for instance after
 1629 writing a large result to file and before printing diagnostics on screen.
 1630 (In order to be sure that the file contains the expected content on
 1631 inspection.)
 1632 
 1633 If $n$ is omitted, flush all descriptors to output streams.
 1634 
 1635 \bprog
 1636 ? n = fileopen("./here", "w");
 1637 ? for (i = 1, 10^5,      \
 1638     filewrite(n, i^2+1); \
 1639     if (i % 10000 == 0, fileflush(n)))
 1640 @eprog Until a \kbd{fileflush} or \kbd{fileclose}, there is no guarantee
 1641 that the file contains all the expected data from previous \kbd{filewrite}s.
 1642 
 1643 The library syntax is \fun{void}{gp_fileflush0}{GEN n = NULL}.
 1644 But the direct and more specific variant
 1645 \fun{void}{gp_fileflush}{long n} is also available.
 1646 
 1647 \subsec{fileopen$(\var{path}, \var{mode})$}\kbdsidx{fileopen}\label{se:fileopen}
 1648 Open the file pointed to by 'path' and return a file descriptor which
 1649 can be used with other file functions.
 1650 
 1651 The mode can be
 1652 
 1653 \item \kbd{"r"} (default): open for reading; allow \kbd{fileread} and
 1654 \kbd{filereadstr}.
 1655 
 1656 \item \kbd{"w"}: open for writing, discarding existing content; allow
 1657 \kbd{filewrite}, \kbd{filewrite1}.
 1658 
 1659 \item \kbd{"a"}: open for writing, appending to existing content; same
 1660 operations allowed as \kbd{"w"}.
 1661 
 1662 Eventually, the file should be closed and the descriptor recycled using
 1663 \kbd{fileclose}.
 1664 
 1665 \bprog
 1666 ? n = fileopen("./here");  \\ "r" by default
 1667 ? while (l = filereadstr(n), print(l))  \\ print successive lines
 1668 ? fileclose(n) \\ done
 1669 @eprog\noindent In \emph{read} mode, raise an exception if the file does not
 1670 exist or the user does not have read permission. In \emph{write} mode, raise
 1671 an exception if the file cannot be written to. Trying to read or write to a
 1672 file that was not opend with the right mode raises an exception.
 1673 \bprog
 1674 ? n = fileopen("./read", "r");
 1675 ? filewrite(n, "test")      \\ not open for writing
 1676  ***   at top-level: filewrite(n,"test")
 1677  ***                 ^-------------------
 1678  *** filewrite: invalid file descriptor 0
 1679 @eprog
 1680 
 1681 The library syntax is \fun{long}{gp_fileopen}{const char *path, const char *mode}.
 1682 
 1683 \subsec{fileread$(n)$}\kbdsidx{fileread}\label{se:fileread}
 1684 Read a logical line from the file attached to the descriptor $n$, opened
 1685 for reading with \kbd{fileopen}. Return 0 at end of file.
 1686 
 1687 A logical line is a full command as it is prepared by gp's
 1688 preprocessor (skipping blanks and comments or assembling multiline commands
 1689 between braces) before being fed to the interpreter. The function
 1690 \kbd{filereadstr} would read a \emph{raw} line exactly as input, up to the
 1691 next carriage return \kbd{\bs n}.
 1692 
 1693 Compare raw lines
 1694 \bprog
 1695 ? n = fileopen("examples/bench.gp");
 1696 ? while(l = filereadstr(n), print(l));
 1697 {
 1698   u=v=p=q=1;
 1699   for (k=1, 2000,
 1700     [u,v] = [v,u+v];
 1701     p *= v; q = lcm(q,v);
 1702     if (k%50 == 0,
 1703       print(k, " ", log(p)/log(q))
 1704     )
 1705   )
 1706 }
 1707 @eprog\noindent and logical lines
 1708 \bprog
 1709 ? n = fileopen("examples/bench.gp");
 1710 ? while(l = fileread(n), print(l));
 1711 u=v=p=q=1;for(k=1,2000,[u,v]=[v,u+v];p*=v;q=lcm(q,v);[...]
 1712 @eprog
 1713 
 1714 The library syntax is \fun{GEN}{gp_fileread}{long n}.
 1715 
 1716 \subsec{filereadstr$(n)$}\kbdsidx{filereadstr}\label{se:filereadstr}
 1717 Read a raw line from the file attached to the descriptor $n$, opened
 1718 for reading with \kbd{fileopen}, discarding the terminating newline.
 1719 In other words the line is read exactly as input, up to the
 1720 next carriage return \kbd{\bs n}. By comparison, \kbd{fileread} would
 1721 read a logical line, as assembled by gp's preprocessor (skipping blanks
 1722 and comments for instance).
 1723 
 1724 The library syntax is \fun{GEN}{gp_filereadstr}{long n}.
 1725 
 1726 \subsec{filewrite$(n, s)$}\kbdsidx{filewrite}\label{se:filewrite}
 1727 Write the string $s$ to the file attached to descriptor $n$, ending with
 1728 a newline. The file must have been opened with \kbd{fileopen} in
 1729 \kbd{"w"} or \kbd{"a"} mode. There is no guarantee that $s$ is completely
 1730 written to disk until \kbd{fileclose$(n)$} is executed, which is automatic
 1731 when quitting \kbd{gp}.
 1732 
 1733 If the newline is not desired, use \kbd{filewrite1}.
 1734 
 1735 \misctitle{Variant} The high-level function \kbd{write} is expensive when many
 1736 consecutive writes are expected because it cannot use buffering. The low-level
 1737 interface \kbd{fileopen} / \kbd{filewrite} / \kbd{fileclose} is more efficient:
 1738 \bprog
 1739 ? f = "/tmp/bigfile";
 1740 ? for (i = 1, 10^5, write(f, i^2+1))
 1741 time = 240 ms.
 1742 
 1743 ? v = vector(10^5, i, i^2+1);
 1744 time = 10 ms. \\ computing the values is fast
 1745 ? write("/tmp/bigfile2",v)
 1746 time = 12 ms. \\ writing them in one operation is fast
 1747 
 1748 ? n = fileopen("/tmp/bigfile", "w");
 1749 ? for (i = 1, 10^5, filewrite(n, i^2+1))
 1750 time = 24 ms.  \\ low-level write is ten times faster
 1751 ? fileclose(n);
 1752 @eprog\noindent In the final example, the file needs not be in a consistent
 1753 state until the ending \kbd{fileclose} is evaluated, e.g. some lines might be
 1754 half-written or not present at all even though the corresponding
 1755 \kbd{filewrite} was executed already. Both a single high-level \kbd{write}
 1756 and a succession of low-level \kbd{filewrite}s achieve the same efficiency,
 1757 but the latter is often more natural. In fact, concatenating naively
 1758 the entries to be written is quadratic in the number of entries, hence
 1759 much more expensive than the original write operations:
 1760 \bprog
 1761 ? v = []; for (i = 1, 10^5, v = concat(v,i))
 1762 time = 1min, 41,456 ms.
 1763 @eprog
 1764 
 1765 The library syntax is \fun{void}{gp_filewrite}{long n, const char *s}.
 1766 
 1767 \subsec{filewrite1$(n, s)$}\kbdsidx{filewrite1}\label{se:filewrite1}
 1768 Write the string $s$ to the file attached to descriptor $n$.
 1769 The file must have been opened with \kbd{fileopen} in \kbd{"w"} or \kbd{"a"}
 1770 mode.
 1771 
 1772 If you want to append a newline at the end of $s$, you can use
 1773 \kbd{Str(s,"\bs n")} or \kbd{filewrite}.
 1774 
 1775 The library syntax is \fun{void}{gp_filewrite1}{long n, const char *s}.
 1776 
 1777 \subsec{fold$(f, A)$}\kbdsidx{fold}\label{se:fold}
 1778 Apply the \typ{CLOSURE} \kbd{f} of arity $2$ to the entries of \kbd{A},
 1779 in order to return \kbd{f(\dots f(f(A[1],A[2]),A[3])\dots ,A[\#A])}.
 1780 \bprog
 1781 ? fold((x,y)->x*y, [1,2,3,4])
 1782 %1 = 24
 1783 ? fold((x,y)->[x,y], [1,2,3,4])
 1784 %2 = [[[1, 2], 3], 4]
 1785 ? fold((x,f)->f(x), [2,sqr,sqr,sqr])
 1786 %3 = 256
 1787 ? fold((x,y)->(x+y)/(1-x*y),[1..5])
 1788 %4 = -9/19
 1789 ? bestappr(tan(sum(i=1,5,atan(i))))
 1790 %5 = -9/19
 1791 @eprog
 1792 
 1793 The library syntax is \fun{GEN}{fold0}{GEN f, GEN A}.
 1794 Also available is
 1795 \fun{GEN}{genfold}{void *E, GEN (*fun)(void*,GEN, GEN), GEN A}.
 1796 
 1797 \subsec{getabstime$()$}\kbdsidx{getabstime}\label{se:getabstime}
 1798 Returns the CPU time (in milliseconds) elapsed since \kbd{gp} startup.
 1799 This provides a reentrant version of \kbd{gettime}:
 1800 \bprog
 1801 my (t = getabstime());
 1802 ...
 1803 print("Time: ", strtime(getabstime() - t));
 1804 @eprog
 1805 For a version giving wall-clock time, see \tet{getwalltime}.
 1806 
 1807 The library syntax is \fun{long}{getabstime}{}.
 1808 
 1809 \subsec{getenv$(s)$}\kbdsidx{getenv}\label{se:getenv}
 1810 Return the value of the environment variable \kbd{s} if it is defined, otherwise return 0.
 1811 
 1812 The library syntax is \fun{GEN}{gp_getenv}{const char *s}.
 1813 
 1814 \subsec{getheap$()$}\kbdsidx{getheap}\label{se:getheap}
 1815 Returns a two-component row vector giving the
 1816 number of objects on the heap and the amount of memory they occupy in long
 1817 words. Useful mainly for debugging purposes.
 1818 
 1819 The library syntax is \fun{GEN}{getheap}{}.
 1820 
 1821 \subsec{getlocalbitprec$()$}\kbdsidx{getlocalbitprec}\label{se:getlocalbitprec}
 1822 Returns the current dynamic bit precision.
 1823 %\syn{NO}
 1824 
 1825 \subsec{getlocalprec$()$}\kbdsidx{getlocalprec}\label{se:getlocalprec}
 1826 Returns the current dynamic precision, in decimal digits.
 1827 %\syn{NO}
 1828 
 1829 \subsec{getrand$()$}\kbdsidx{getrand}\label{se:getrand}
 1830 Returns the current value of the seed used by the
 1831 pseudo-random number generator \tet{random}. Useful mainly for debugging
 1832 purposes, to reproduce a specific chain of computations. The returned value
 1833 is technical (reproduces an internal state array), and can only be used as an
 1834 argument to \tet{setrand}.
 1835 
 1836 The library syntax is \fun{GEN}{getrand}{}.
 1837 
 1838 \subsec{getstack$()$}\kbdsidx{getstack}\label{se:getstack}
 1839 Returns the current value of $\kbd{top}-\kbd{avma}$, i.e.~the number of
 1840 bytes used up to now on the stack. Useful mainly for debugging purposes.
 1841 
 1842 The library syntax is \fun{long}{getstack}{}.
 1843 
 1844 \subsec{gettime$()$}\kbdsidx{gettime}\label{se:gettime}
 1845 Returns the CPU time (in milliseconds) used since either the last call to
 1846 \kbd{gettime}, or to the beginning of the containing GP instruction (if
 1847 inside \kbd{gp}), whichever came last.
 1848 
 1849 For a reentrant version, see \tet{getabstime}.
 1850 
 1851 For a version giving wall-clock time, see \tet{getwalltime}.
 1852 
 1853 The library syntax is \fun{long}{gettime}{}.
 1854 
 1855 \subsec{getwalltime$()$}\kbdsidx{getwalltime}\label{se:getwalltime}
 1856 Returns the time (in milliseconds) elapsed since
 1857 00:00:00 UTC Thursday 1, January 1970 (the Unix epoch).
 1858 \bprog
 1859 my (t = getwalltime());
 1860 ...
 1861 print("Time: ", strtime(getwalltime() - t));
 1862 @eprog
 1863 
 1864 The library syntax is \fun{GEN}{getwalltime}{}.
 1865 
 1866 \subsec{global$(\var{list} \var{of} \var{variables})$}\kbdsidx{global}\label{se:global}
 1867 Obsolete. Scheduled for deletion.
 1868 % \syn{NO}
 1869 
 1870 \subsec{inline$(x,...,z)$}\kbdsidx{inline}\label{se:inline}
 1871 Declare $x,\ldots, z$ as inline variables. Such variables
 1872 behave like lexically scoped variable (see my()) but with unlimited scope.
 1873 It is however possible to exit the scope by using \kbd{uninline()}.
 1874 When used in a GP script, it is recommended to call \kbd{uninline()} before
 1875 the script's end to avoid inline variables leaking outside the script.
 1876 DEPRECATED, use \kbd{export}.
 1877 
 1878 \subsec{input$()$}\kbdsidx{input}\label{se:input}
 1879 Reads a string, interpreted as a GP expression,
 1880 from the input file, usually standard input (i.e.~the keyboard). If a
 1881 sequence of expressions is given, the result is the result of the last
 1882 expression of the sequence. When using this instruction, it is useful to
 1883 prompt for the string by using the \kbd{print1} function. Note that in the
 1884 present version 2.19 of \kbd{pari.el}, when using \kbd{gp} under GNU Emacs (see
 1885 \secref{se:emacs}) one \emph{must} prompt for the string, with a string
 1886 which ends with the same prompt as any of the previous ones (a \kbd{"? "}
 1887 will do for instance).
 1888 
 1889 The library syntax is \fun{GEN}{gp_input}{}.
 1890 
 1891 \subsec{install$(\var{name},\var{code},\{\var{gpname}\},\{\var{lib}\})$}\kbdsidx{install}\label{se:install}
 1892 Loads from dynamic library \var{lib} the function \var{name}. Assigns to it
 1893 the name \var{gpname} in this \kbd{gp} session, with \emph{prototype}
 1894 \var{code} (see below). If \var{gpname} is omitted, uses \var{name}.
 1895 If \var{lib} is omitted, all symbols known to \kbd{gp} are available: this
 1896 includes the whole of \kbd{libpari.so} and possibly others (such as
 1897 \kbd{libc.so}).
 1898 
 1899 Most importantly, \kbd{install} gives you access to all nonstatic functions
 1900 defined in the PARI library. For instance, the function
 1901 \bprog
 1902   GEN addii(GEN x, GEN y)
 1903 @eprog\noindent adds two PARI integers, and is not directly accessible under
 1904 \kbd{gp} (it is eventually called by the \kbd{+} operator of course):
 1905 \bprog
 1906 ? install("addii", "GG")
 1907 ? addii(1, 2)
 1908 %1 = 3
 1909 @eprog\noindent
 1910 It also allows to add external functions to the \kbd{gp} interpreter.
 1911 For instance, it makes the function \tet{system} obsolete:
 1912 \bprog
 1913 ? install(system, vs, sys,/*omitted*/)
 1914 ? sys("ls gp*")
 1915 gp.c            gp.h            gp_rl.c
 1916 @eprog\noindent This works because \kbd{system} is part of \kbd{libc.so},
 1917 which is linked to \kbd{gp}. It is also possible to compile a shared library
 1918 yourself and provide it to gp in this way: use \kbd{gp2c}, or do it manually
 1919 (see the \kbd{modules\_build} variable in \kbd{pari.cfg} for hints).
 1920 
 1921 Re-installing a function will print a warning and update the prototype code
 1922 if needed. However, it will not reload a symbol from the library, even if the
 1923 latter has been recompiled.
 1924 
 1925 \misctitle{Prototype} We only give a simplified description here, covering
 1926 most functions, but there are many more possibilities. The full documentation
 1927 is available in \kbd{libpari.dvi}, see
 1928 \bprog
 1929   ??prototype
 1930 @eprog
 1931 
 1932 \item First character \kbd{i}, \kbd{l}, \kbd{v} : return type int / long /
 1933 void. (Default: \kbd{GEN})
 1934 
 1935 \item One letter for each mandatory argument, in the same order as they appear
 1936 in the argument list: \kbd{G} (\kbd{GEN}), \kbd{\&}
 1937 (\kbd{GEN*}), \kbd{L} (\kbd{long}), \kbd{s} (\kbd{char *}), \kbd{n}
 1938 (variable).
 1939 
 1940  \item \kbd{p} to supply \kbd{realprecision} (usually \kbd{long prec} in the
 1941  argument list), \kbd{P} to supply \kbd{seriesprecision}
 1942  (usually \kbd{long precdl}).
 1943 
 1944  \noindent We also have special constructs for optional arguments and default
 1945  values:
 1946 
 1947  \item \kbd{DG} (optional \kbd{GEN}, \kbd{NULL} if omitted),
 1948 
 1949  \item \kbd{D\&} (optional \kbd{GEN*}, \kbd{NULL} if omitted),
 1950 
 1951  \item \kbd{Dn} (optional variable, $-1$ if omitted),
 1952 
 1953 For instance the prototype corresponding to
 1954 \bprog
 1955   long issquareall(GEN x, GEN *n = NULL)
 1956 @eprog\noindent is \kbd{lGD\&}.
 1957 
 1958 \misctitle{Caution} This function may not work on all systems, especially
 1959 when \kbd{gp} has been compiled statically. In that case, the first use of an
 1960 installed function will provoke a Segmentation Fault (this should never
 1961 happen with a dynamically linked executable). If you intend to use this
 1962 function, please check first on some harmless example such as the one above
 1963 that it works properly on your machine.
 1964 
 1965 The library syntax is \fun{void}{gpinstall}{const char *name, const char *code, const char *gpname, const char *lib}.
 1966 
 1967 \subsec{kill$(\var{sym})$}\kbdsidx{kill}\label{se:kill}
 1968 Restores the symbol \kbd{sym} to its ``undefined'' status, and deletes any
 1969 help messages attached to \kbd{sym} using \kbd{addhelp}. Variable names
 1970 remain known to the interpreter and keep their former priority: you cannot
 1971 make a variable ``less important" by killing it!
 1972 \bprog
 1973 ? z = y = 1; y
 1974 %1 = 1
 1975 ? kill(y)
 1976 ? y            \\ restored to ``undefined'' status
 1977 %2 = y
 1978 ? variable()
 1979 %3 = [x, y, z] \\ but the variable name y is still known, with y > z !
 1980 @eprog\noindent
 1981 For the same reason, killing a user function (which is an ordinary
 1982 variable holding a \typ{CLOSURE}) does not remove its name from the list of
 1983 variable names.
 1984 
 1985 If the symbol is attached to a variable --- user functions being an
 1986 important special case ---, one may use the \idx{quote} operator
 1987 \kbd{a = 'a} to reset variables to their starting values. However, this
 1988 will not delete a help message attached to \kbd{a}, and is also slightly
 1989 slower than \kbd{kill(a)}.
 1990 \bprog
 1991 ? x = 1; addhelp(x, "foo"); x
 1992 %1 = 1
 1993 ? x = 'x; x   \\ same as 'kill', except we don't delete help.
 1994 %2 = x
 1995 ? ?x
 1996 foo
 1997 @eprog\noindent
 1998 On the other hand, \kbd{kill} is the only way to remove aliases and installed
 1999 functions.
 2000 \bprog
 2001 ? alias(fun, sin);
 2002 ? kill(fun);
 2003 
 2004 ? install(addii, GG);
 2005 ? kill(addii);
 2006 @eprog
 2007 
 2008 The library syntax is \fun{void}{kill0}{const char *sym}.
 2009 
 2010 \subsec{listcreate$(\{n\})$}\kbdsidx{listcreate}\label{se:listcreate}
 2011 This function is obsolete, use \kbd{List}.
 2012 
 2013 Creates an empty list. This routine used to have a mandatory argument,
 2014 which is now ignored (for backward compatibility).
 2015 % \syn{NO}
 2016 
 2017 \subsec{listinsert$(~L,x,n)$}\kbdsidx{listinsert}\label{se:listinsert}
 2018 Inserts the object $x$ at
 2019 position $n$ in $L$ (which must be of type \typ{LIST}).
 2020 This has complexity $O(\#L - n + 1)$: all the
 2021 remaining elements of \var{list} (from position $n+1$ onwards) are shifted
 2022 to the right. If $n$ is greater than the list length, appends $x$.
 2023 \bprog
 2024 ? L = List([1,2,3]);
 2025 ? listput(~L, 4); L \\ listput inserts at end
 2026 %4 = List([1, 2, 3, 4])
 2027 ? listinsert(~L, 5, 1); L \\insert at position 1
 2028 %5 = List([5, 1, 2, 3, 4])
 2029 ? listinsert(~L, 6, 1000); L  \\ trying to insert beyond position #L
 2030 %6 = List([5, 1, 2, 3, 4, 6]) \\ ... inserts at the end
 2031 @eprog\noindent Note the \kbd{\til L}: this means that the function is
 2032 called with a \emph{reference} to \kbd{L} and changes \kbd{L} in place.
 2033 
 2034 The library syntax is \fun{GEN}{listinsert}{GEN ~L, GEN x, long n}.
 2035 
 2036 \subsec{listkill$(~L)$}\kbdsidx{listkill}\label{se:listkill}
 2037 Obsolete, retained for backward compatibility. Just use \kbd{L = List()}
 2038 instead of \kbd{listkill(L)}. In most cases, you won't even need that, e.g.
 2039 local variables are automatically cleared when a user function returns.
 2040 
 2041 The library syntax is \fun{void}{listkill}{GEN ~L}.
 2042 
 2043 \subsec{listpop$(~\var{list},\{n\})$}\kbdsidx{listpop}\label{se:listpop}
 2044 Removes the $n$-th element of the list
 2045 \var{list} (which must be of type \typ{LIST}). If $n$ is omitted,
 2046 or greater than the list current length, removes the last element.
 2047 If the list is already empty, do nothing. This runs in time $O(\#L - n + 1)$.
 2048 \bprog
 2049 ? L = List([1,2,3,4]);
 2050 ? listpop(~L); L  \\ remove last entry
 2051 %2 = List([1, 2, 3])
 2052 ? listpop(~L, 1); L \\ remove first entry
 2053 %3 = List([2, 3])
 2054 @eprog\noindent Note the \kbd{\til L}: this means that the function is
 2055 called with a \emph{reference} to \kbd{L} and changes \kbd{L} in place.
 2056 
 2057 The library syntax is \fun{void}{listpop0}{GEN ~list, long n}.
 2058 
 2059 \subsec{listput$(~\var{list},x,\{n\})$}\kbdsidx{listput}\label{se:listput}
 2060 Sets the $n$-th element of the list
 2061 \var{list} (which must be of type \typ{LIST}) equal to $x$. If $n$ is omitted,
 2062 or greater than the list length, appends $x$. The function returns the
 2063 inserted element.
 2064 \bprog
 2065 ? L = List();
 2066 ? listput(~L, 1)
 2067 %2 = 1
 2068 ? listput(~L, 2)
 2069 %3 = 2
 2070 ? L
 2071 %4 = List([1, 2])
 2072 @eprog\noindent Note the \kbd{\til L}: this means that the function is
 2073 called with a \emph{reference} to \kbd{L} and changes \kbd{L} in place.
 2074 
 2075 You may put an element into an occupied cell (not changing the
 2076 list length), but it is easier to use the standard \kbd{list[n] = x}
 2077 construct.
 2078 \bprog
 2079 ? listput(~L, 3, 1) \\ insert at position 1
 2080 %5 = 3
 2081 ? L
 2082 %6 = List([3, 2])
 2083 ? L[2] = 4 \\ simpler
 2084 %7 = List([3, 4])
 2085 ? L[10] = 1  \\ can't insert beyond the end of the list
 2086  ***   at top-level: L[10]=1
 2087  ***                  ^------
 2088  ***   nonexistent component: index > 2
 2089 ? listput(L, 1, 10) \\ but listput can
 2090 %8 = 1
 2091 ? L
 2092 %9 = List([3, 2, 1])
 2093 @eprog
 2094 
 2095 This function runs in time $O(\#L)$ in the worst case (when the list must
 2096 be reallocated), but in time $O(1)$ on average: any number of successive
 2097 \kbd{listput}s run in time $O(\#L)$, where $\#L$ denotes the list
 2098 \emph{final} length.
 2099 
 2100 The library syntax is \fun{GEN}{listput0}{GEN ~list, GEN x, long n}.
 2101 
 2102 \subsec{listsort$(~L,\{\fl=0\})$}\kbdsidx{listsort}\label{se:listsort}
 2103 Sorts the \typ{LIST} \var{list} in place, with respect to the (somewhat
 2104 arbitrary) universal comparison function \tet{cmp}. In particular, the
 2105 ordering is the same as for sets and \tet{setsearch} can be used on a sorted
 2106 list. No value is returned. If $\fl$ is nonzero, suppresses all repeated
 2107 coefficients.
 2108 \bprog
 2109 ? L = List([1,2,4,1,3,-1]); listsort(~L); L
 2110 %1 = List([-1, 1, 1, 2, 3, 4])
 2111 ? setsearch(L, 4)
 2112 %2 = 6
 2113 ? setsearch(L, -2)
 2114 %3 = 0
 2115 ? listsort(~L, 1); L \\ remove duplicates
 2116 %4 = List([-1, 1, 2, 3, 4])
 2117 @eprog\noindent Note the \kbd{\til L}: this means that the function is
 2118 called with a \emph{reference} to \kbd{L} and changes \kbd{L} in place:
 2119 this is faster than the \kbd{vecsort} command since the list
 2120 is sorted in place and we avoid unnecessary copies.
 2121 \bprog
 2122 ? v = vector(100,i,random); L = List(v);
 2123 ? for(i=1,10^4, vecsort(v))
 2124 time = 162 ms.
 2125 ? for(i=1,10^4, vecsort(L))
 2126 time = 162 ms.
 2127 ? for(i=1,10^4, listsort(~L))
 2128 time = 63 ms.
 2129 @eprog
 2130 
 2131 The library syntax is \fun{void}{listsort}{GEN ~L, long flag}.
 2132 
 2133 \subsec{localbitprec$(p)$}\kbdsidx{localbitprec}\label{se:localbitprec}
 2134 Set the real precision to $p$ bits in the dynamic scope.
 2135 All computations are performed as if \tet{realbitprecision} was $p$:
 2136 transcendental constants (e.g.~\kbd{Pi}) and
 2137 conversions from exact to floating point inexact data use $p$ bits, as well as
 2138 iterative routines implicitly using a floating point
 2139 accuracy as a termination criterion (e.g.~\tet{solve} or \tet{intnum}).
 2140 But \kbd{realbitprecision} itself is unaffected
 2141 and is ``unmasked'' when we exit the dynamic (\emph{not} lexical) scope.
 2142 In effect, this is similar to
 2143 \bprog
 2144 my(bit = default(realbitprecision));
 2145 default(realbitprecision,p);
 2146 ...
 2147 default(realbitprecision, bit);
 2148 @eprog\noindent but is both less cumbersome, cleaner (no need to manipulate
 2149 a global variable, which in fact never changes and is only temporarily masked)
 2150 and more robust: if the above computation is interrupted or an exception
 2151 occurs, \kbd{realbitprecision} will not be restored as intended.
 2152 
 2153 Such \kbd{localbitprec} statements can be nested, the innermost one taking
 2154 precedence as expected. Beware that \kbd{localbitprec} follows the semantic of
 2155 \tet{local}, not \tet{my}: a subroutine called from \kbd{localbitprec} scope
 2156 uses the local accuracy:
 2157 \bprog
 2158 ? f()=bitprecision(1.0);
 2159 ? f()
 2160 %2 = 128
 2161 ? localbitprec(1000); f()
 2162 %3 = 1024
 2163 @eprog\noindent Note that the bit precision of \emph{data} (\kbd{1.0} in the
 2164 above example) increases by steps of 64 (32 on a 32-bit machine) so we get
 2165 $1024$ instead of the expected $1000$; \kbd{localbitprec} bounds the
 2166 relative error exactly as specified in functions that support that
 2167 granularity (e.g.~\kbd{lfun}), and rounded to the next multiple of 64
 2168 (resp.~32) everywhere else.
 2169 
 2170 \misctitle{Warning} Changing \kbd{realbitprecision} or \kbd{realprecision}
 2171 in programs is deprecated in favor of \kbd{localbitprec} and
 2172 \kbd{localprec}. Think about the \kbd{realprecision} and
 2173 \kbd{realbitprecision} defaults as interactive commands for the \kbd{gp}
 2174 interpreter, best left out of GP programs. Indeed, the above rules imply that
 2175 mixing both constructs yields surprising results:
 2176 
 2177 \bprog
 2178 ? \p38
 2179 ? localprec(19); default(realprecision,1000); Pi
 2180 %1 = 3.141592653589793239
 2181 ? \p
 2182   realprecision = 1001 significant digits (1000 digits displayed)
 2183 @eprog\noindent Indeed, \kbd{realprecision} itself is ignored within
 2184 \kbd{localprec} scope, so \kbd{Pi} is computed to a low accuracy. And when
 2185 we leave the \kbd{localprec} scope, \kbd{realprecision} only regains precedence,
 2186 it is not ``restored'' to the original value.
 2187 %\syn{NO}
 2188 
 2189 \subsec{localprec$(p)$}\kbdsidx{localprec}\label{se:localprec}
 2190 Set the real precision to $p$ in the dynamic scope and return $p$.
 2191 All computations are performed as if \tet{realprecision} was $p$:
 2192 transcendental constants (e.g.~\kbd{Pi}) and
 2193 conversions from exact to floating point inexact data use $p$ decimal
 2194 digits, as well as iterative routines implicitly using a floating point
 2195 accuracy as a termination criterion (e.g.~\tet{solve} or \tet{intnum}).
 2196 But \kbd{realprecision} itself is unaffected
 2197 and is ``unmasked'' when we exit the dynamic (\emph{not} lexical) scope.
 2198 In effect, this is similar to
 2199 \bprog
 2200 my(prec = default(realprecision));
 2201 default(realprecision,p);
 2202 ...
 2203 default(realprecision, prec);
 2204 @eprog\noindent but is both less cumbersome, cleaner (no need to manipulate
 2205 a global variable, which in fact never changes and is only temporarily masked)
 2206 and more robust: if the above computation is interrupted or an exception
 2207 occurs, \kbd{realprecision} will not be restored as intended.
 2208 
 2209 Such \kbd{localprec} statements can be nested, the innermost one taking
 2210 precedence as expected. Beware that \kbd{localprec} follows the semantic of
 2211 \tet{local}, not \tet{my}: a subroutine called from \kbd{localprec} scope
 2212 uses the local accuracy:
 2213 \bprog
 2214 ? f()=precision(1.);
 2215 ? f()
 2216 %2 = 38
 2217 ? localprec(19); f()
 2218 %3 = 19
 2219 @eprog\noindent
 2220 \misctitle{Warning} Changing \kbd{realprecision} itself in programs is
 2221 now deprecated in favor of \kbd{localprec}. Think about the
 2222 \kbd{realprecision} default as an interactive command for the \kbd{gp}
 2223 interpreter, best left out of GP programs. Indeed, the above rules
 2224 imply that mixing both constructs yields surprising results:
 2225 \bprog
 2226 ? \p38
 2227 ? localprec(19); default(realprecision,100); Pi
 2228 %1 = 3.141592653589793239
 2229 ? \p
 2230     realprecision = 115 significant digits (100 digits displayed)
 2231 @eprog\noindent Indeed, \kbd{realprecision} itself is ignored within
 2232 \kbd{localprec} scope, so \kbd{Pi} is computed to a low accuracy. And when
 2233 we leave \kbd{localprec} scope, \kbd{realprecision} only regains precedence,
 2234 it is not ``restored'' to the original value.
 2235 %\syn{NO}
 2236 
 2237 \subsec{mapdelete$(~M,x)$}\kbdsidx{mapdelete}\label{se:mapdelete}
 2238 Removes $x$ from the domain of the map $M$.
 2239 \bprog
 2240 ? M = Map(["a",1; "b",3; "c",7]);
 2241 ? mapdelete(M,"b");
 2242 ? Mat(M)
 2243 ["a" 1]
 2244 
 2245 ["c" 7]
 2246 @eprog
 2247 
 2248 The library syntax is \fun{void}{mapdelete}{GEN ~M, GEN x}.
 2249 
 2250 \subsec{mapget$(M,x)$}\kbdsidx{mapget}\label{se:mapget}
 2251 Returns the image of $x$ by the map $M$.
 2252 \bprog
 2253 ? M=Map(["a",23;"b",43]);
 2254 ? mapget(M,"a")
 2255 %2 = 23
 2256 ? mapget(M,"b")
 2257 %3 = 43
 2258 @eprog\noindent Raises an exception when the key $x$ is not present in $M$.
 2259 \bprog
 2260 ? mapget(M,"c")
 2261   ***   at top-level: mapget(M,"c")
 2262   ***                 ^-------------
 2263   *** mapget: nonexistent component in mapget: index not in map
 2264 @eprog
 2265 
 2266 The library syntax is \fun{GEN}{mapget}{GEN M, GEN x}.
 2267 
 2268 \subsec{mapisdefined$(M,x,\{\&z\})$}\kbdsidx{mapisdefined}\label{se:mapisdefined}
 2269 Returns true ($1$) if \kbd{x} has an image by the map $M$, false ($0$)
 2270 otherwise. If \kbd{z} is present, set \kbd{z} to the image of $x$, if it exists.
 2271 \bprog
 2272 ? M1 = Map([1, 10; 2, 20]);
 2273 ? mapisdefined(M1,3)
 2274 %1 = 0
 2275 ? mapisdefined(M1, 1, &z)
 2276 %2 = 1
 2277 ? z
 2278 %3 = 10
 2279 @eprog
 2280 
 2281 \bprog
 2282 ? M2 = Map(); N = 19;
 2283 ? for (a=0, N-1, mapput(M2, a^3%N, a));
 2284 ? {for (a=0, N-1,
 2285      if (mapisdefined(M2, a, &b),
 2286        printf("%d is the cube of %d mod %d\n",a,b,N)));}
 2287 0 is the cube of 0 mod 19
 2288 1 is the cube of 11 mod 19
 2289 7 is the cube of 9 mod 19
 2290 8 is the cube of 14 mod 19
 2291 11 is the cube of 17 mod 19
 2292 12 is the cube of 15 mod 19
 2293 18 is the cube of 18 mod 19
 2294 @eprog
 2295 
 2296 The library syntax is \fun{GEN}{mapisdefined}{GEN M, GEN x, GEN *z = NULL}.
 2297 
 2298 \subsec{mapput$(~M,x,y)$}\kbdsidx{mapput}\label{se:mapput}
 2299 Associates $x$ to $y$ in the map $M$. The value $y$ can be retrieved
 2300 with \tet{mapget}.
 2301 \bprog
 2302 ? M = Map();
 2303 ? mapput(~M, "foo", 23);
 2304 ? mapput(~M, 7718, "bill");
 2305 ? mapget(M, "foo")
 2306 %4 = 23
 2307 ? mapget(M, 7718)
 2308 %5 = "bill"
 2309 ? Vec(M)  \\ keys
 2310 %6 = [7718, "foo"]
 2311 ? Mat(M)
 2312 %7 =
 2313 [ 7718 "bill"]
 2314 
 2315 ["foo"     23]
 2316 @eprog
 2317 
 2318 The library syntax is \fun{void}{mapput}{GEN ~M, GEN x, GEN y}.
 2319 
 2320 \subsec{print$(\{\var{str}\}*)$}\kbdsidx{print}\label{se:print}
 2321 Outputs its arguments in raw format ending with a newline.
 2322 The arguments are converted to strings following the rules in
 2323 \secref{se:strings}.
 2324 \bprog
 2325 ? m = matid(2);
 2326 ? print(m)  \\ raw format
 2327 [1, 0; 0, 1]
 2328 ? printp(m) \\ prettymatrix format
 2329 
 2330 [1 0]
 2331 
 2332 [0 1]
 2333 @eprog
 2334 %\syn{NO}
 2335 
 2336 \subsec{print1$(\{\var{str}\}*)$}\kbdsidx{print1}\label{se:print1}
 2337 Outputs its arguments in raw
 2338 format, without ending with a newline. Note that you can still embed newlines
 2339 within your strings, using the \b{n} notation~!
 2340 The arguments are converted to strings following the rules in
 2341 \secref{se:strings}.
 2342 %\syn{NO}
 2343 
 2344 \subsec{printf$(\var{fmt},\{x\}*)$}\kbdsidx{printf}\label{se:printf}
 2345 This function is based on the C library command of the same name.
 2346 It prints its arguments according to the format \var{fmt}, which specifies how
 2347 subsequent arguments are converted for output. The format is a
 2348 character string composed of zero or more directives:
 2349 
 2350 \item ordinary characters (not \kbd{\%}), printed unchanged,
 2351 
 2352 \item conversions specifications (\kbd{\%} followed by some characters)
 2353 which fetch one argument from the list and prints it according to the
 2354 specification.
 2355 
 2356 More precisely, a conversion specification consists in a \kbd{\%}, one or more
 2357 optional flags (among \kbd{\#}, \kbd{0}, \kbd{-}, \kbd{+}, ` '), an optional
 2358 decimal digit string specifying a minimal field width, an optional precision
 2359 in the form of a period (`\kbd{.}') followed by a decimal digit string, and
 2360 the conversion specifier (among \kbd{d},\kbd{i}, \kbd{o}, \kbd{u},
 2361 \kbd{x},\kbd{X}, \kbd{p}, \kbd{e},\kbd{E}, \kbd{f}, \kbd{g},\kbd{G}, \kbd{s}).
 2362 
 2363 \misctitle{The flag characters} The character \kbd{\%} is followed by zero or
 2364 more of the following flags:
 2365 
 2366 \item \kbd{\#}: the value is converted to an ``alternate form''. For
 2367 \kbd{o} conversion (octal), a \kbd{0} is prefixed to the string. For \kbd{x}
 2368 and \kbd{X} conversions (hexa), respectively \kbd{0x} and \kbd{0X} are
 2369 prepended. For other conversions, the flag is ignored.
 2370 
 2371 \item \kbd{0}: the value should be zero padded. For
 2372 \kbd{d},
 2373 \kbd{i},
 2374 \kbd{o},
 2375 \kbd{u},
 2376 \kbd{x},
 2377 \kbd{X}
 2378 \kbd{e},
 2379 \kbd{E},
 2380 \kbd{f},
 2381 \kbd{F},
 2382 \kbd{g}, and
 2383 \kbd{G} conversions, the value is padded on the left with zeros rather than
 2384 blanks. (If the \kbd{0} and \kbd{-} flags both appear, the \kbd{0} flag is
 2385 ignored.)
 2386 
 2387 \item \kbd{-}: the value is left adjusted on the field boundary. (The
 2388 default is right justification.) The value is padded on the right with
 2389 blanks, rather than on the left with blanks or zeros. A \kbd{-} overrides a
 2390 \kbd{0} if both are given.
 2391 
 2392 \item \kbd{` '} (a space): a blank is left before a positive number
 2393 produced by a signed conversion.
 2394 
 2395 \item \kbd{+}: a sign (+ or -) is placed before a number produced by a
 2396 signed conversion. A \kbd{+} overrides a space if both are used.
 2397 
 2398 \misctitle{The field width} An optional decimal digit string (whose first
 2399 digit is nonzero) specifying a \emph{minimum} field width. If the value has
 2400 fewer characters than the field width, it is padded with spaces on the left
 2401 (or right, if the left-adjustment flag has been given). In no case does a
 2402 small field width cause truncation of a field; if the value is wider than
 2403 the field width, the field is expanded to contain the conversion result.
 2404 Instead of a decimal digit string, one may write \kbd{*} to specify that the
 2405 field width is given in the next argument.
 2406 
 2407 \misctitle{The precision} An optional precision in the form of a period
 2408 (`\kbd{.}') followed by a decimal digit string. This gives
 2409 the number of digits to appear after the radix character for \kbd{e},
 2410 \kbd{E}, \kbd{f}, and \kbd{F} conversions, the maximum number of significant
 2411 digits for \kbd{g} and \kbd{G} conversions, and the maximum number of
 2412 characters to be printed from an \kbd{s} conversion.
 2413 Instead of a decimal digit string, one may write \kbd{*} to specify that the
 2414 field width is given in the next argument.
 2415 
 2416 \misctitle{The length modifier} This is ignored under \kbd{gp}, but
 2417 necessary for \kbd{libpari} programming. Description given here for
 2418 completeness:
 2419 
 2420 \item \kbd{l}: argument is a \kbd{long} integer.
 2421 
 2422 \item \kbd{P}: argument is a \kbd{GEN}.
 2423 
 2424 \misctitle{The conversion specifier} A character that specifies the type of
 2425 conversion to be applied.
 2426 
 2427 \item \kbd{d}, \kbd{i}: a signed integer.
 2428 
 2429 \item \kbd{o}, \kbd{u}, \kbd{x}, \kbd{X}: an unsigned integer, converted
 2430 to unsigned octal (\kbd{o}), decimal (\kbd{u}) or hexadecimal (\kbd{x} or
 2431 \kbd{X}) notation. The letters \kbd{abcdef} are used for \kbd{x}
 2432 conversions;  the letters \kbd{ABCDEF} are used for \kbd{X} conversions.
 2433 
 2434 \item \kbd{e}, \kbd{E}: the (real) argument is converted in the style
 2435 \kbd{[ -]d.ddd e[ -]dd}, where there is one digit before the decimal point,
 2436 and the number of digits after it is equal to the precision; if the
 2437 precision is missing, use the current \kbd{realprecision} for the total
 2438 number of printed digits. If the precision is explicitly 0, no decimal-point
 2439 character appears. An \kbd{E} conversion uses the letter \kbd{E} rather
 2440 than \kbd{e} to introduce the exponent.
 2441 
 2442 \item \kbd{f}, \kbd{F}: the (real) argument is converted in the style
 2443 \kbd{[ -]ddd.ddd}, where the number of digits after the decimal point
 2444 is equal to the precision; if the precision is missing, use the current
 2445 \kbd{realprecision} for the total number of printed digits. If the precision
 2446 is explicitly 0, no decimal-point character appears. If a decimal point
 2447 appears, at least one digit appears before it.
 2448 
 2449 \item \kbd{g}, \kbd{G}: the (real) argument is converted in style
 2450 \kbd{e} or \kbd{f} (or \kbd{E} or \kbd{F} for \kbd{G} conversions)
 2451 \kbd{[ -]ddd.ddd}, where the total number of digits printed
 2452 is equal to the precision; if the precision is missing, use the current
 2453 \kbd{realprecision}. If the precision is explicitly 0, it is treated as 1.
 2454 Style \kbd{e} is used when
 2455 the decimal exponent is $< -4$, to print \kbd{0.}, or when the integer
 2456 part cannot be decided given the known significant digits, and the \kbd{f}
 2457 format otherwise.
 2458 
 2459 \item \kbd{c}: the integer argument is converted to an unsigned char, and the
 2460 resulting character is written.
 2461 
 2462 \item \kbd{s}: convert to a character string. If a precision is given, no
 2463 more than the specified number of characters are written.
 2464 
 2465 \item \kbd{p}: print the address of the argument in hexadecimal (as if by
 2466 \kbd{\%\#x}).
 2467 
 2468 \item \kbd{\%}: a \kbd{\%} is written. No argument is converted. The complete
 2469 conversion specification is \kbd{\%\%}.
 2470 
 2471 \noindent Examples:
 2472 
 2473 \bprog
 2474 ? printf("floor: %d, field width 3: %3d, with sign: %+3d\n", Pi, 1, 2);
 2475 floor: 3, field width 3:   1, with sign:  +2
 2476 
 2477 ? printf("%.5g %.5g %.5g\n",123,123/456,123456789);
 2478 123.00 0.26974 1.2346 e8
 2479 
 2480 ? printf("%-2.5s:%2.5s:%2.5s\n", "P", "PARI", "PARIGP");
 2481 P :PARI:PARIG
 2482 
 2483 \\ min field width and precision given by arguments
 2484 ? x = 23; y=-1/x; printf("x=%+06.2f y=%+0*.*f\n", x, 6, 2, y);
 2485 x=+23.00 y=-00.04
 2486 
 2487 \\ minimum fields width 5, pad left with zeroes
 2488 ? for (i = 2, 5, printf("%05d\n", 10^i))
 2489 00100
 2490 01000
 2491 10000
 2492 100000  \\@com don't truncate fields whose length is larger than the minimum width
 2493 ? printf("%.2f  |%06.2f|", Pi,Pi)
 2494 3.14  |  3.14|
 2495 @eprog\noindent All numerical conversions apply recursively to the entries
 2496 of vectors and matrices:
 2497 \bprog
 2498 ? printf("%4d", [1,2,3]);
 2499 [   1,   2,   3]
 2500 ? printf("%5.2f", mathilbert(3));
 2501 [ 1.00  0.50  0.33]
 2502 
 2503 [ 0.50  0.33  0.25]
 2504 
 2505 [ 0.33  0.25  0.20]
 2506 @eprog
 2507 \misctitle{Technical note} Our implementation of \tet{printf}
 2508 deviates from the C89 and C99 standards in a few places:
 2509 
 2510 \item whenever a precision is missing, the current \kbd{realprecision} is
 2511 used to determine the number of printed digits (C89: use 6 decimals after
 2512 the radix character).
 2513 
 2514 \item in conversion style \kbd{e}, we do not impose that the
 2515 exponent has at least two digits; we never write a \kbd{+} sign in the
 2516 exponent; 0 is printed in a special way, always as \kbd{0.E\var{exp}}.
 2517 
 2518 \item in conversion style \kbd{f}, we switch to style \kbd{e} if the
 2519 exponent is greater or equal to the precision.
 2520 
 2521 \item in conversion \kbd{g} and \kbd{G}, we do not remove trailing zeros
 2522  from the fractional part of the result; nor a trailing decimal point;
 2523  0 is printed in a special way, always as \kbd{0.E\var{exp}}.
 2524 %\syn{NO}
 2525 
 2526 \subsec{printp$(\{\var{str}\}*)$}\kbdsidx{printp}\label{se:printp}
 2527 Outputs its arguments in prettymatrix format, ending with a
 2528 newline. The arguments are converted to strings following the rules in
 2529 \secref{se:strings}.
 2530 \bprog
 2531 ? m = matid(2);
 2532 ? print(m)  \\ raw format
 2533 [1, 0; 0, 1]
 2534 ? printp(m) \\ prettymatrix format
 2535 
 2536 [1 0]
 2537 
 2538 [0 1]
 2539 @eprog
 2540 %\syn{NO}
 2541 
 2542 \subsec{printsep$(\var{sep},\{\var{str}\}*)$}\kbdsidx{printsep}\label{se:printsep}
 2543 Outputs its arguments in raw format, ending with a newline.
 2544 The arguments are converted to strings following the rules in
 2545 \secref{se:strings}. Successive entries are separated by \var{sep}:
 2546 \bprog
 2547 ? printsep(":", 1,2,3,4)
 2548 1:2:3:4
 2549 @eprog
 2550 %\syn{NO}
 2551 
 2552 \subsec{printsep1$(\var{sep},\{\var{str}\}*)$}\kbdsidx{printsep1}\label{se:printsep1}
 2553 Outputs its arguments in raw format, without ending with a
 2554 newline. The arguments are converted to strings following the rules in
 2555 \secref{se:strings}. Successive entries are separated by \var{sep}:
 2556 \bprog
 2557 ? printsep1(":", 1,2,3,4);print("|")
 2558 1:2:3:4|
 2559 @eprog
 2560 %\syn{NO}
 2561 
 2562 \subsec{printtex$(\{\var{str}\}*)$}\kbdsidx{printtex}\label{se:printtex}
 2563 Outputs its arguments in \TeX\ format. This output can then be
 2564 used in a \TeX\ manuscript, see \kbd{strtex} for details. The arguments are
 2565 converted to strings following the rules in \secref{se:strings}. The printing
 2566 is done on the standard output. If you want to print it to a file you should
 2567 use \kbd{writetex} (see there).
 2568 
 2569 Another possibility is to enable the \tet{log} default
 2570 (see~\secref{se:defaults}).
 2571 You could for instance do:\sidx{logfile}
 2572 %
 2573 \bprog
 2574 default(logfile, "new.tex");
 2575 default(log, 1);
 2576 printtex(result);
 2577 @eprog
 2578 %\syn{NO}
 2579 
 2580 \subsec{quit$(\{\var{status} = 0\})$}\kbdsidx{quit}\label{se:quit}
 2581 Exits \kbd{gp} and return to the system with exit status
 2582 \kbd{status}, a small integer. A nonzero exit status normally indicates
 2583 abnormal termination. (Note: the system actually sees only
 2584 \kbd{status} mod $256$, see your man pages for \kbd{exit(3)} or \kbd{wait(2)}).
 2585 
 2586 \subsec{read$(\{\var{filename}\})$}\kbdsidx{read}\label{se:read}
 2587 Reads in the file
 2588 \var{filename} (subject to string expansion). If \var{filename} is
 2589 omitted, re-reads the last file that was fed into \kbd{gp}. The return
 2590 value is the result of the last expression evaluated.
 2591 
 2592 If a GP \tet{binary file} is read using this command (see
 2593 \secref{se:writebin}), the file is loaded and the last object in the file
 2594 is returned.
 2595 
 2596 In case the file you read in contains an \tet{allocatemem} statement (to be
 2597 generally avoided), you should leave \kbd{read} instructions by themselves,
 2598 and not part of larger instruction sequences.
 2599 
 2600 \misctitle{Variants} \kbd{readvec} allows to read a whole file at once;
 2601 \kbd{fileopen} followed by either \kbd{fileread} (evaluated lines) or
 2602 \kbd{filereadstr} (lines as nonevaluated strings) allows to read a file
 2603 one line at a time.
 2604 
 2605 The library syntax is \fun{GEN}{gp_read_file}{const char *filename}.
 2606 
 2607 \subsec{readstr$(\{\var{filename}\})$}\kbdsidx{readstr}\label{se:readstr}
 2608 Reads in the file \var{filename} and return a vector of GP strings,
 2609 each component containing one line from the file. If \var{filename} is
 2610 omitted, re-reads the last file that was fed into \kbd{gp}.
 2611 
 2612 The library syntax is \fun{GEN}{readstr}{const char *filename}.
 2613 
 2614 \subsec{readvec$(\{\var{filename}\})$}\kbdsidx{readvec}\label{se:readvec}
 2615 Reads in the file
 2616 \var{filename} (subject to string expansion). If \var{filename} is
 2617 omitted, re-reads the last file that was fed into \kbd{gp}. The return
 2618 value is a vector whose components are the evaluation of all sequences
 2619 of instructions contained in the file. For instance, if \var{file} contains
 2620 \bprog
 2621 1
 2622 2
 2623 3
 2624 @eprog\noindent
 2625 then we will get:
 2626 \bprog
 2627 ? \r a
 2628 %1 = 1
 2629 %2 = 2
 2630 %3 = 3
 2631 ? read(a)
 2632 %4 = 3
 2633 ? readvec(a)
 2634 %5 = [1, 2, 3]
 2635 @eprog
 2636 In general a sequence is just a single line, but as usual braces and
 2637 \kbd{\bs} may be used to enter multiline sequences.
 2638 
 2639 The library syntax is \fun{GEN}{gp_readvec_file}{const char *filename}.
 2640 The underlying library function
 2641 \fun{GEN}{gp_readvec_stream}{FILE *f} is usually more flexible.
 2642 
 2643 \subsec{select$(f, A, \{\fl = 0\})$}\kbdsidx{select}\label{se:select}
 2644 We first describe the default behavior, when $\fl$ is 0 or omitted.
 2645 Given a vector or list \kbd{A} and a \typ{CLOSURE} \kbd{f}, \kbd{select}
 2646 returns the elements $x$ of \kbd{A} such that $f(x)$ is nonzero. In other
 2647 words, \kbd{f} is seen as a selection function returning a boolean value.
 2648 \bprog
 2649 ? select(x->isprime(x), vector(50,i,i^2+1))
 2650 %1 = [2, 5, 17, 37, 101, 197, 257, 401, 577, 677, 1297, 1601]
 2651 ? select(x->(x<100), %)
 2652 %2 = [2, 5, 17, 37]
 2653 @eprog\noindent returns the primes of the form $i^2+1$ for some $i\leq 50$,
 2654 then the elements less than 100 in the preceding result. The \kbd{select}
 2655 function also applies to a matrix \kbd{A}, seen as a vector of columns, i.e. it
 2656 selects columns instead of entries, and returns the matrix whose columns are
 2657 the selected ones.
 2658 
 2659 \misctitle{Remark} For $v$ a \typ{VEC}, \typ{COL}, \typ{VECSMALL},
 2660 \typ{LIST} or \typ{MAT}, the alternative set-notations
 2661 \bprog
 2662 [g(x) | x <- v, f(x)]
 2663 [x | x <- v, f(x)]
 2664 [g(x) | x <- v]
 2665 @eprog\noindent
 2666 are available as shortcuts for
 2667 \bprog
 2668 apply(g, select(f, Vec(v)))
 2669 select(f, Vec(v))
 2670 apply(g, Vec(v))
 2671 @eprog\noindent respectively:
 2672 \bprog
 2673 ? [ x | x <- vector(50,i,i^2+1), isprime(x) ]
 2674 %1 = [2, 5, 17, 37, 101, 197, 257, 401, 577, 677, 1297, 1601]
 2675 @eprog
 2676 
 2677 \noindent If $\fl = 1$, this function returns instead the \emph{indices} of
 2678 the selected elements, and not the elements themselves (indirect selection):
 2679 \bprog
 2680 ? V = vector(50,i,i^2+1);
 2681 ? select(x->isprime(x), V, 1)
 2682 %2 = Vecsmall([1, 2, 4, 6, 10, 14, 16, 20, 24, 26, 36, 40])
 2683 ? vecextract(V, %)
 2684 %3 = [2, 5, 17, 37, 101, 197, 257, 401, 577, 677, 1297, 1601]
 2685 @eprog\noindent
 2686 The following function lists the elements in $(\Z/N\Z)^*$:
 2687 \bprog
 2688 ? invertibles(N) = select(x->gcd(x,N) == 1, [1..N])
 2689 @eprog
 2690 
 2691 \noindent Finally
 2692 \bprog
 2693 ? select(x->x, M)
 2694 @eprog\noindent selects the nonzero entries in \kbd{M}. If the latter is a
 2695 \typ{MAT}, we extract the matrix of nonzero columns. Note that \emph{removing}
 2696 entries instead of selecting them just involves replacing the selection
 2697 function \kbd{f} with its negation:
 2698 \bprog
 2699 ? select(x->!isprime(x), vector(50,i,i^2+1))
 2700 @eprog
 2701 
 2702 \synt{genselect}{void *E, long (*fun)(void*,GEN), GEN a}. Also available
 2703 is \fun{GEN}{genindexselect}{void *E, long (*fun)(void*, GEN), GEN a},
 2704 corresponding to $\fl = 1$.
 2705 
 2706 \subsec{self$()$}\kbdsidx{self}\label{se:self}
 2707 Return the calling function or closure as a \typ{CLOSURE} object.
 2708 This is useful for defining anonymous recursive functions.
 2709 \bprog
 2710 ? (n -> if(n==0,1,n*self()(n-1)))(5)
 2711 %1 = 120  \\ 5!
 2712 
 2713 ? (n -> if(n<=1, n, self()(n-1)+self()(n-2)))(20)
 2714 %2 = 6765 \\ Fibonacci(20)
 2715 @eprog
 2716 
 2717 The library syntax is \fun{GEN}{pari_self}{}.
 2718 
 2719 \subsec{setrand$(n)$}\kbdsidx{setrand}\label{se:setrand}
 2720 Reseeds the random number generator using the seed $n$. No value is
 2721 returned. The seed is a small positive integer $0 < n < 2^{64}$ used to
 2722 generate deterministically a suitable state array. All gp session start
 2723 by an implicit \kbd{setrand(1)}, so resetting the seed to this value allows
 2724 to replay all computations since the session start. Alternatively,
 2725 running a randomized computation starting by \kbd{setrand}($n$)
 2726 twice with the same $n$ will generate the exact same output.
 2727 
 2728 In the other direction, including a call to \kbd{setrand(getwalltime())}
 2729 from your gprc will cause GP to produce different streams of random numbers
 2730 in each session. (Unix users may want to use \kbd{/dev/urandom} instead
 2731 of \kbd{getwalltime}.)
 2732 
 2733 For debugging purposes, one can also record a particular random state
 2734 using \kbd{getrand} (the value is encoded as a huge integer) and feed it to
 2735 \kbd{setrand}:
 2736 \bprog
 2737 ? state = getrand(); \\ record seed
 2738 ...
 2739 ? setrand(state); \\ we can now replay the exact same computations
 2740 @eprog
 2741 
 2742 The library syntax is \fun{void}{setrand}{GEN n}.
 2743 
 2744 \subsec{strchr$(x)$}\kbdsidx{strchr}\label{se:strchr}
 2745 Converts integer or vector of integers $x$ to a string, translating each
 2746 integer (in the range $[1,255]$) into a character using ASCII encoding.
 2747 \bprog
 2748 ? strchr(97)
 2749 %1 = "a"
 2750 ? Vecsmall("hello world")
 2751 %2 = Vecsmall([104, 101, 108, 108, 111, 32, 119, 111, 114, 108, 100])
 2752 ? strchr(%)
 2753 %3 = "hello world"
 2754 @eprog
 2755 
 2756 The library syntax is \fun{GEN}{pari_strchr}{GEN x}.
 2757 
 2758 \subsec{strexpand$(\{x\}*)$}\kbdsidx{strexpand}\label{se:strexpand}
 2759 Converts its argument list into a
 2760 single character string (type \typ{STR}, the empty string if $x$ is omitted).
 2761 Then perform \idx{environment expansion}, see \secref{se:envir}.
 2762 This feature can be used to read \idx{environment variable} values.
 2763 \bprog
 2764 ? strexpand("$HOME/doc")
 2765 %1 = "/home/pari/doc"
 2766 
 2767 ? module = "aprcl"; n = 10;
 2768 ? strexpand("$HOME/doc/", module, n, ".tex")
 2769 %3 = "/home/pari/doc/aprcl10.tex"
 2770 @eprog
 2771 
 2772 The individual arguments are read in string context, see \secref{se:strings}.
 2773 %\syn{NO}
 2774 
 2775 \subsec{strjoin$(v,\{p = ""\})$}\kbdsidx{strjoin}\label{se:strjoin}
 2776 Joins the strings in vector $v$, separating them with delimiter $p$.
 2777 The reverse operation is \kbd{strsplit}.
 2778 \bprog
 2779 ? v = ["abc", "def", "ghi"]
 2780 ? strjoin(v, "/")
 2781 %2 = "abc/def/ghi"
 2782 ? strjoin(v)
 2783 %3 = "abcdefghi"
 2784 @eprog
 2785 
 2786 The library syntax is \fun{GEN}{strjoin}{GEN v, GEN p = NULL}.
 2787 
 2788 \subsec{strprintf$(\var{fmt},\{x\}*)$}\kbdsidx{strprintf}\label{se:strprintf}
 2789 Returns a string built from the remaining arguments according to the
 2790 format fmt. The format consists of ordinary characters (not \%), printed
 2791 unchanged, and conversions specifications. See \kbd{printf}.
 2792 \bprog
 2793 ? dir = "/home/pari"; file = "aprcl"; n = 10;
 2794 ? strprintf("%s/%s%ld.tex", dir, file, n)
 2795 %2 = "/home/pari/aprcl10.tex"
 2796 @eprog
 2797 %\syn{NO}
 2798 
 2799 \subsec{strsplit$(s,\{p = ""\})$}\kbdsidx{strsplit}\label{se:strsplit}
 2800 Splits the string $s$ into a vector of strings, with $p$ acting as a
 2801 delimiter. If $p$ is empty or omitted, split the string into characters.
 2802 \bprog
 2803 ? strsplit("abc::def::ghi", "::")
 2804 %1 = ["abc", "def", "ghi"]
 2805 ? strsplit("abc", "")
 2806 %2 = ["a", "b", "c"]
 2807 ? strsplit("aba", "a")
 2808 @eprog\noindent If $s$ starts (resp.~ends) with the pattern $p$, then the
 2809 first (resp.~last) entry in the vector is the empty string:
 2810 \bprog
 2811 ? strsplit("aba", "a")
 2812 %3 = ["", "b", ""]
 2813 @eprog
 2814 
 2815 The library syntax is \fun{GEN}{strsplit}{GEN s, GEN p = NULL}.
 2816 
 2817 \subsec{strtex$(\{x\}*)$}\kbdsidx{strtex}\label{se:strtex}
 2818 Translates its arguments to TeX format, and concatenates the results into a
 2819 single character string (type \typ{STR}, the empty string if $x$ is omitted).
 2820 
 2821 The individual arguments are read in string context, see \secref{se:strings}.
 2822 \bprog
 2823 ? v = [1, 2, 3]
 2824 %1 [1, 2, 3]
 2825 ? strtex(v)
 2826 %2 = "\\pmatrix{ 1&2&3\\cr}\n"
 2827 @eprog
 2828 
 2829 \misctitle{\TeX-nical notes} The TeX output engine was originally written
 2830 for plain TeX and designed for maximal portability. Unfortunately later
 2831 \kbd{LaTeX} packages have obsoleted valid \TeX\ primitives, leading us
 2832 to replace TeX's \kbd{\bs{}over} by LaTeX's \kbd{\bs{}frac} in PARI's TeX
 2833 output. We have decided not to update further our TeX markup and let the
 2834 users of various LaTeX engines customize their preambles. The following
 2835 documents the precise changes you may need to include in your style files to
 2836 incorporate PARI TeX output verbatim:
 2837 
 2838 \item if you enabled bit 4 in \tet{TeXstyle} default, you must define
 2839 \kbd{\bs{}PARIbreak}; see \kbd{??TeXstyle};
 2840 
 2841 \item if you use plain TeX only: you must define \kbd{\bs{}frac} as follows
 2842 \bprog
 2843   \def\frac#1#2{{#1\over#2}}
 2844 @eprog
 2845 
 2846 \item if you use LaTeX and \kbd{amsmath}, \kbd{\bs{}pmatrix} is
 2847 obsoleted in favor of the \kbd{pmatrix} environment; see
 2848 \kbd{examples/parigp.sty} for how to re-enable the deprecated construct.
 2849 
 2850 %\syn{NO}
 2851 
 2852 \subsec{strtime$(t)$}\kbdsidx{strtime}\label{se:strtime}
 2853 Return a string describing the time t in milliseconds in the format used by
 2854  the GP timer.
 2855 \bprog
 2856 ? print(strtime(12345678))
 2857 3h, 25min, 45,678 ms
 2858 ? {
 2859     my(t=getabstime());
 2860     F=factor(2^256+1);t=getabstime()-t;
 2861     print("factor(2^256+1) took ",strtime(t));
 2862   }
 2863 factor(2^256+1) took 1,320 ms
 2864 @eprog
 2865 
 2866 The library syntax is \fun{GEN}{strtime}{long t}.
 2867 
 2868 \subsec{system$(\var{str})$}\kbdsidx{system}\label{se:system}
 2869 \var{str} is a string representing a system command. This command is
 2870 executed, its output written to the standard output (this won't get into your
 2871 logfile), and control returns to the PARI system. This simply calls the C
 2872 \kbd{system} command.
 2873 
 2874 The library syntax is \fun{void}{gpsystem}{const char *str}.
 2875 
 2876 \subsec{trap$(\{e\}, \{\var{rec}\}, \var{seq})$}\kbdsidx{trap}\label{se:trap}
 2877 This function is obsolete, use \tet{iferr}, which has a nicer and much
 2878 more powerful interface. For compatibility's sake we now describe the
 2879 \emph{obsolete} function \tet{trap}.
 2880 
 2881 This function tries to
 2882 evaluate \var{seq}, trapping runtime error $e$, that is effectively preventing
 2883 it from aborting computations in the usual way; the recovery sequence
 2884 \var{rec} is executed if the error occurs and the evaluation of \var{rec}
 2885 becomes the result of the command. If $e$ is omitted, all exceptions are
 2886 trapped. See \secref{se:errorrec} for an introduction to error recovery
 2887 under \kbd{gp}.
 2888 
 2889 \bprog
 2890 ? \\@com trap division by 0
 2891 ? inv(x) = trap (e_INV, INFINITY, 1/x)
 2892 ? inv(2)
 2893 %1 = 1/2
 2894 ? inv(0)
 2895 %2 = INFINITY
 2896 @eprog\noindent
 2897 Note that \var{seq} is effectively evaluated up to the point that produced
 2898 the error, and the recovery sequence is evaluated starting from that same
 2899 context, it does not "undo" whatever happened in the other branch (restore
 2900 the evaluation context):
 2901 \bprog
 2902 ? x = 1; trap (, /* recover: */ x, /* try: */ x = 0; 1/x)
 2903 %1 = 0
 2904 @eprog
 2905 
 2906 \misctitle{Note} The interface is currently not adequate for trapping
 2907 individual exceptions. In the current version \vers, the following keywords
 2908 are recognized, but the name list will be expanded and changed in the
 2909 future (all library mode errors can be trapped: it's a matter of defining
 2910 the keywords to \kbd{gp}):
 2911 
 2912 \kbd{e\_ALARM}: alarm time-out
 2913 
 2914 \kbd{e\_ARCH}: not available on this architecture or operating system
 2915 
 2916 \kbd{e\_STACK}: the PARI stack overflows
 2917 
 2918 \kbd{e\_INV}: impossible inverse
 2919 
 2920 \kbd{e\_IMPL}: not yet implemented
 2921 
 2922 \kbd{e\_OVERFLOW}: all forms of arithmetic overflow, including length
 2923 or exponent overflow (when a larger value is supplied than the
 2924 implementation can handle).
 2925 
 2926 \kbd{e\_SYNTAX}: syntax error
 2927 
 2928 \kbd{e\_MISC}: miscellaneous error
 2929 
 2930 \kbd{e\_TYPE}: wrong type
 2931 
 2932 \kbd{e\_USER}: user error (from the \kbd{error} function)
 2933 
 2934 The library syntax is \fun{GEN}{trap0}{const char *e = NULL, GEN rec = NULL, GEN seq = NULL}.
 2935 
 2936 \subsec{type$(x)$}\kbdsidx{type}\label{se:type}
 2937 This is useful only under \kbd{gp}. Returns the internal type name of
 2938 the PARI object $x$ as a  string. Check out existing type names with the
 2939 metacommand \b{t}. For example \kbd{type(1)} will return "\typ{INT}".
 2940 
 2941 The library syntax is \fun{GEN}{type0}{GEN x}.
 2942 The macro \kbd{typ} is usually simpler to use since it returns a
 2943 \kbd{long} that can easily be matched with the symbols \typ{*}. The name
 2944 \kbd{type} was avoided since it is a reserved identifier for some compilers.
 2945 
 2946 \subsec{unexport$(x,...,z)$}\kbdsidx{unexport}\label{se:unexport}
 2947 Remove $x,\ldots, z$ from the list of variables exported
 2948 to the parallel world.  See \key{export}.
 2949 
 2950 \subsec{unexportall$()$}\kbdsidx{unexportall}\label{se:unexportall}
 2951 Empty the list of variables exported to the parallel world.
 2952 
 2953 The library syntax is \fun{void}{unexportall}{}.
 2954 
 2955 \subsec{uninline$()$}\kbdsidx{uninline}\label{se:uninline}
 2956 Exit the scope of all current \kbd{inline} variables. DEPRECATED, use
 2957 \kbd{export} / \kbd{unexport}.
 2958 
 2959 \subsec{version$()$}\kbdsidx{version}\label{se:version}
 2960 Returns the current version number as a \typ{VEC} with three integer
 2961 components (major version number, minor version number and patchlevel);
 2962 if your sources were obtained through our version control system, this will
 2963 be followed by further more precise arguments, including
 2964 e.g.~a~\kbd{git} \emph{commit hash}.
 2965 
 2966 This function is present in all versions of PARI following releases 2.3.4
 2967 (stable) and 2.4.3 (testing).
 2968 
 2969 Unless you are working with multiple development versions, you probably only
 2970 care about the 3 first numeric components. In any case, the \kbd{lex} function
 2971 offers a clever way to check against a particular version number, since it will
 2972 compare each successive vector entry, numerically or as strings, and will not
 2973 mind if the vectors it compares have different lengths:
 2974 \bprog
 2975    if (lex(version(), [2,3,5]) >= 0,
 2976      \\ code to be executed if we are running 2.3.5 or more recent.
 2977    ,
 2978      \\ compatibility code
 2979    );
 2980 @eprog\noindent On a number of different machines, \kbd{version()} could return either of
 2981 \bprog
 2982  %1 = [2, 3, 4]    \\ released version, stable branch
 2983  %1 = [2, 4, 3]    \\ released version, testing branch
 2984  %1 = [2, 6, 1, 15174, ""505ab9b"] \\ development
 2985 @eprog
 2986 
 2987 In particular, if you are only working with released versions, the first
 2988 line of the gp introductory message can be emulated by
 2989 \bprog
 2990    [M,m,p] = version();
 2991    printf("GP/PARI CALCULATOR Version %s.%s.%s", M,m,p);
 2992  @eprog\noindent If you \emph{are} working with many development versions of
 2993  PARI/GP, the 4th and/or 5th components can be profitably included in the
 2994  name of your logfiles, for instance.
 2995 
 2996  \misctitle{Technical note} For development versions obtained via \kbd{git},
 2997  the 4th and 5th components are liable to change eventually, but we document
 2998  their current meaning for completeness. The 4th component counts the number
 2999  of reachable commits in the branch (analogous to \kbd{svn}'s revision
 3000  number), and the 5th is the \kbd{git} commit hash. In particular, \kbd{lex}
 3001  comparison still orders correctly development versions with respect to each
 3002  others or to released versions (provided we stay within a given branch,
 3003  e.g. \kbd{master})!
 3004 
 3005 The library syntax is \fun{GEN}{pari_version}{}.
 3006 
 3007 \subsec{warning$(\{\var{str}\}*)$}\kbdsidx{warning}\label{se:warning}
 3008 Outputs the message ``user warning''
 3009 and the argument list (each of them interpreted as a string).
 3010 If colors are enabled, this warning will be in a different color,
 3011 making it easy to distinguish.
 3012 \bprog
 3013 warning(n, " is very large, this might take a while.")
 3014 @eprog
 3015 % \syn{NO}
 3016 
 3017 \subsec{whatnow$(\var{key})$}\kbdsidx{whatnow}\label{se:whatnow}
 3018 If keyword \var{key} is the name of a function that was present in GP
 3019 version 1.39.15, outputs the new function name and syntax, if it
 3020 changed at all. Functions that where introduced since then, then modified
 3021 are also recognized.
 3022 \bprog
 3023 ? whatnow("mu")
 3024 New syntax: mu(n) ===> moebius(n)
 3025 
 3026 moebius(x): Moebius function of x.
 3027 
 3028 ? whatnow("sin")
 3029 This function did not change
 3030 @eprog When a function was removed and the underlying functionality
 3031 is not available under a compatible interface, no equivalent is mentioned:
 3032 \bprog
 3033 ? whatnow("buchfu")
 3034 This function no longer exists
 3035 @eprog\noindent (The closest equivalent would be to set \kbd{K = bnfinit(T)}
 3036 then access \kbd{K.fu}.)
 3037 
 3038 \subsec{write$(\var{filename},\{\var{str}\}*)$}\kbdsidx{write}\label{se:write}
 3039 Writes (appends) to \var{filename} the remaining arguments, and appends a
 3040 newline (same output as \kbd{print}).
 3041 
 3042 \misctitle{Variant} The high-level function \kbd{write} is expensive when many
 3043 consecutive writes are expected because it cannot use buffering. The low-level
 3044 interface \kbd{fileopen} / \kbd{filewrite} / \kbd{fileclose} is more efficient.
 3045 It also allows to truncate existing files and replace their contents.
 3046 %\syn{NO}
 3047 
 3048 \subsec{write1$(\var{filename},\{\var{str}\}*)$}\kbdsidx{write1}\label{se:write1}
 3049 Writes (appends) to \var{filename} the remaining arguments without a
 3050 trailing newline (same output as \kbd{print1}).
 3051 %\syn{NO}
 3052 
 3053 \subsec{writebin$(\var{filename},\{x\})$}\kbdsidx{writebin}\label{se:writebin}
 3054 Writes (appends) to
 3055 \var{filename} the object $x$ in binary format. This format is not human
 3056 readable, but contains the exact internal structure of $x$, and is much
 3057 faster to save/load than a string expression, as would be produced by
 3058 \tet{write}. The binary file format includes a magic number, so that such a
 3059 file can be recognized and correctly input by the regular \tet{read} or \b{r}
 3060 function. If saved objects refer to polynomial variables that are not
 3061 defined in the new session, they will be displayed as \kbd{t$n$} for some
 3062 integer $n$ (the attached variable number).
 3063 Installed functions and history objects can not be saved via this function.
 3064 
 3065 If $x$ is omitted, saves all user variables from the session, together with
 3066 their names. Reading such a ``named object'' back in a \kbd{gp} session will set
 3067 the corresponding user variable to the saved value. E.g after
 3068 \bprog
 3069 x = 1; writebin("log")
 3070 @eprog\noindent
 3071 reading \kbd{log} into a clean session will set \kbd{x} to $1$.
 3072 The relative variables priorities (see \secref{se:priority}) of new variables
 3073 set in this way remain the same (preset variables retain their former
 3074 priority, but are set to the new value). In particular, reading such a
 3075 session log into a clean session will restore all variables exactly as they
 3076 were in the original one.
 3077 
 3078 Just as a regular input file, a binary file can be compressed
 3079 using \tet{gzip}, provided the file name has the standard \kbd{.gz}
 3080 extension.\sidx{binary file}
 3081 
 3082 In the present implementation, the binary files are architecture dependent
 3083 and compatibility with future versions of \kbd{gp} is not guaranteed. Hence
 3084 binary files should not be used for long term storage (also, they are
 3085 larger and harder to compress than text files).
 3086 
 3087 The library syntax is \fun{void}{gpwritebin}{const char *filename, GEN x = NULL}.
 3088 
 3089 \subsec{writetex$(\var{filename},\{\var{str}\}*)$}\kbdsidx{writetex}\label{se:writetex}
 3090 As \kbd{write}, in \TeX\ format. See \tet{strtex} for details:
 3091 this function is essentially equivalent to calling \kbd{strtex} on remaining
 3092 arguments and writing them to file.
 3093 %\syn{NO}
 3094 
 3095 \section{Parallel programming}
 3096 
 3097 These function are only available if PARI was configured using
 3098 \kbd{Configure --mt=\dots}. Two multithread interfaces are supported:
 3099 
 3100 \item POSIX threads
 3101 
 3102 \item Message passing interface (MPI)
 3103 
 3104 As a rule, POSIX threads are well-suited for single systems, while MPI is used
 3105 by most clusters. However the parallel GP interface does not depend on the
 3106 chosen multithread interface: a properly written GP program will work
 3107 identically with both.
 3108 
 3109 \subsec{parapply$(f, x)$}\kbdsidx{parapply}\label{se:parapply}
 3110 Parallel evaluation of \kbd{f} on the elements of \kbd{x}.
 3111 The function \kbd{f} must not access global variables or variables
 3112 declared with local(), and must be free of side effects.
 3113 \bprog
 3114 parapply(factor,[2^256 + 1, 2^193 - 1])
 3115 @eprog
 3116 factors $2^{256} + 1$ and $2^{193} - 1$ in parallel.
 3117 \bprog
 3118 {
 3119   my(E = ellinit([1,3]), V = vector(12,i,randomprime(2^200)));
 3120   parapply(p->ellcard(E,p), V)
 3121 }
 3122 @eprog
 3123 computes the order of $E(\F_p)$ for $12$ random primes of $200$ bits.
 3124 
 3125 The library syntax is \fun{GEN}{parapply}{GEN f, GEN x}.
 3126 
 3127 \subsec{pareval$(x)$}\kbdsidx{pareval}\label{se:pareval}
 3128 Parallel evaluation of the elements of \kbd{x}, where \kbd{x} is a
 3129 vector of closures. The closures must be of arity $0$, must not access
 3130 global variables or variables declared with \kbd{local} and must be
 3131 free of side effects.
 3132 
 3133 Here is an artificial example explaining the MOV attack on the elliptic
 3134 discrete log problem (by reducing it to a standard discrete log over a
 3135 finite field):
 3136 \bprog
 3137 {
 3138   my(q = 2^30 + 3, m = 40 * q; p = 1 + m^2); \\ p, q are primes
 3139   my(E = ellinit([0,0,0,1,0] * Mod(1,p)));
 3140   my([P, Q] = ellgenerators(E));
 3141   \\ E(F_p) ~ Z/m P + Z/m Q and the order of the
 3142   \\ Weil pairing <P,Q> in (Z/p)^* is m
 3143   my(F = [m,factor(m)], e = random(m), R, wR, wQ);
 3144   R = ellpow(E, Q, e);
 3145   wR = ellweilpairing(E,P,R,m);
 3146   wQ = ellweilpairing(E,P,Q,m); \\ wR = wQ^e
 3147   pareval([()->znlog(wR,wQ,F), ()->elllog(E,R,Q), ()->e])
 3148 }
 3149 @eprog\noindent Note the use of \kbd{my} to pass "arguments" to the
 3150 functions we need to evaluate while satisfying the listed requirements:
 3151 closures of arity $0$ and no global variables (another possibility would be
 3152 to use \kbd{export}). As a result, the final three statements satisfy all
 3153 the listed requirements and are run in parallel. (Which is silly for
 3154 this computation but illustrates the use of pareval.) The function
 3155 \kbd{parfor} is more powerful but harder to use.
 3156 
 3157 The library syntax is \fun{GEN}{pareval}{GEN x}.
 3158 
 3159 \subsec{parfor$(i=a,\{b\},\var{expr1},\{r\},\{\var{expr2}\})$}\kbdsidx{parfor}\label{se:parfor}
 3160 Evaluates in parallel the expression \kbd{expr1} in the formal
 3161 argument $i$ running from $a$ to $b$.
 3162 If $b$ is set to \kbd{+oo}, the loop runs indefinitely.
 3163 If $r$ and \kbd{expr2} are present, the expression \kbd{expr2} in the
 3164 formal variables $r$ and $i$ is evaluated with $r$ running through all
 3165 the different results obtained for \kbd{expr1} and $i$ takes the
 3166 corresponding argument.
 3167 
 3168 The computations of \kbd{expr1} are \emph{started} in increasing order
 3169 of $i$; otherwise said, the computation for $i=c$ is started after those
 3170 for $i=1, \ldots, c-1$ have been started, but before the computation for
 3171 $i=c+1$ is started. Notice that the order of \emph{completion}, that is,
 3172 the order in which the different $r$ become available, may be different;
 3173 \kbd{expr2} is evaluated sequentially on each $r$ as it appears.
 3174 
 3175 The following example computes the sum of the squares of the integers
 3176 from $1$ to $10$ by computing the squares in parallel and is equivalent
 3177 to \kbd{parsum (i=1, 10, i\^{}2)}:
 3178 \bprog
 3179 ? s=0;
 3180 ? parfor (i=1, 10, i^2, r, s=s+r)
 3181 ? s
 3182 %3 = 385
 3183 @eprog
 3184 More precisely, apart from a potentially different order of evaluation
 3185 due to the parallelism, the line containing \kbd{parfor} is equivalent to
 3186 \bprog
 3187 ? my (r); for (i=1, 10, r=i^2; s=s+r)
 3188 @eprog
 3189 The sequentiality of the evaluation of \kbd{expr2} ensures that the
 3190 variable \kbd{s} is not modified concurrently by two different additions,
 3191 although the order in which the terms are added is nondeterministic.
 3192 
 3193 It is allowed for \kbd{expr2} to exit the loop using
 3194 \kbd{break}/\kbd{next}/\kbd{return}. If that happens for $i=c$,
 3195 then the evaluation of \kbd{expr1} and \kbd{expr2} is continued
 3196 for all values $i<c$, and the return value is the one obtained for
 3197 the smallest $i$ causing an interruption in \kbd{expr2} (it may be
 3198 undefined if this is a \kbd{break}/\kbd{next}).
 3199 In that case, using side-effects
 3200 in \kbd{expr2} may lead to undefined behavior, as the exact
 3201 number of values of $i$ for which it is executed is nondeterministic.
 3202 The following example computes \kbd{nextprime(1000)} in parallel:
 3203 \bprog
 3204 ? parfor (i=1000, , isprime (i), r, if (r, return (i)))
 3205 %1 = 1009
 3206 @eprog
 3207 
 3208 %\syn{NO}
 3209 
 3210 \subsec{parforeach$(V,x,\var{expr1},\{r\},\{\var{expr2}\})$}\kbdsidx{parforeach}\label{se:parforeach}
 3211 Evaluates in parallel the expression \kbd{expr1} in the formal
 3212 argument $x$, where $x$ runs through all components of $V$.
 3213 If $r$ and \kbd{expr2} are present, evaluate sequentially the expression
 3214 \kbd{expr2}, in which the formal variables $x$ and $r$ are replaced
 3215 by the successive arguments and corresponding values. The sequential
 3216 evaluation ordering is not specified:
 3217 \bprog
 3218 ? parforeach([50..100], x,isprime(x), r, if(r,print(x)))
 3219 53
 3220 67
 3221 71
 3222 79
 3223 83
 3224 89
 3225 97
 3226 73
 3227 59
 3228 61
 3229 @eprog
 3230 %\syn{NO}
 3231 
 3232 \subsec{parforprime$(p=a,\{b\},\var{expr1},\{r\},\{\var{expr2}\})$}\kbdsidx{parforprime}\label{se:parforprime}
 3233 Behaves exactly as \kbd{parfor}, but loops only over prime values $p$.
 3234 Precisely, the functions evaluates in parallel the expression \kbd{expr1}
 3235 in the formal
 3236 argument $p$ running through the primes from $a$ to $b$.
 3237 If $b$ is set to \kbd{+oo}, the loop runs indefinitely.
 3238 If $r$ and \kbd{expr2} are present, the expression \kbd{expr2} in the
 3239 formal variables $r$ and $p$ is evaluated with $r$ running through all
 3240 the different results obtained for \kbd{expr1} and $p$ takes the
 3241 corresponding argument.
 3242 
 3243 It is allowed fo \kbd{expr2} to exit the loop using
 3244 \kbd{break}/\kbd{next}/\kbd{return}; see the remarks in the documentation
 3245 of \kbd{parfor} for details.
 3246 
 3247 %\syn{NO}
 3248 
 3249 \subsec{parforprimestep$(p=a,\{b\},q,\var{expr1},\{r\},\{\var{expr2}\})$}\kbdsidx{parforprimestep}\label{se:parforprimestep}
 3250 Behaves exactly as \kbd{parfor}, but loops only over prime values $p$
 3251 in an arithmetic progression
 3252 Precisely, the functions evaluates in parallel the expression \kbd{expr1}
 3253 in the formal argument $p$ running through the primes from $a$ to $b$
 3254 in an arithmetic progression of the form $a + k\*q$.
 3255 ($p \equiv a \pmod{q}$) or an intmod \kbd{Mod(c,N)}.
 3256 If $b$ is set to \kbd{+oo}, the loop runs indefinitely.
 3257 If $r$ and \kbd{expr2} are present, the expression \kbd{expr2} in the
 3258 formal variables $r$ and $p$ is evaluated with $r$ running through all
 3259 the different results obtained for \kbd{expr1} and $p$ takes the
 3260 corresponding argument.
 3261 
 3262 It is allowed fo \kbd{expr2} to exit the loop using
 3263 \kbd{break}/\kbd{next}/\kbd{return}; see the remarks in the documentation
 3264 of \kbd{parfor} for details.
 3265 
 3266 %\syn{NO}
 3267 
 3268 \subsec{parforvec$(X=v,\var{expr1},\{j\},\{\var{expr2}\},\{\fl\})$}\kbdsidx{parforvec}\label{se:parforvec}
 3269 Evaluates the sequence \kbd{expr2} (dependent on $X$ and $j$) for $X$
 3270 as generated by \kbd{forvec}, in random order, computed in parallel. Substitute
 3271 for $j$ the value of \kbd{expr1} (dependent on $X$).
 3272 
 3273 It is allowed fo \kbd{expr2} to exit the loop using
 3274 \kbd{break}/\kbd{next}/\kbd{return}, however in that case, \kbd{expr2} will
 3275 still be evaluated for all remaining value of $p$ less than the current one,
 3276 unless a subsequent \kbd{break}/\kbd{next}/\kbd{return} happens.
 3277 %\syn{NO}
 3278 
 3279 \subsec{parselect$(f, A, \{\fl = 0\})$}\kbdsidx{parselect}\label{se:parselect}
 3280 Selects elements of $A$ according to the selection function $f$, done in
 3281 parallel.  If \fl is $1$, return the indices of those elements (indirect
 3282 selection) The function \kbd{f} must not access global variables or
 3283 variables declared with local(), and must be free of side effects.
 3284 
 3285 The library syntax is \fun{GEN}{parselect}{GEN f, GEN A, long flag}.
 3286 
 3287 \subsec{parsum$(i=a,b,\var{expr})$}\kbdsidx{parsum}\label{se:parsum}
 3288 Sum of expression \var{expr}, the formal parameter
 3289 going from $a$ to $b$, evaluated in parallel in random order.
 3290 The expression \kbd{expr} must not access global variables or
 3291 variables declared with \kbd{local()}, and must be free of side effects.
 3292 \bprog
 3293 ? parsum(i=1,1000,ispseudoprime(2^prime(i)-1))
 3294 cpu time = 1min, 26,776 ms, real time = 5,854 ms.
 3295 %1 = 20
 3296 @eprog
 3297 returns the number of prime numbers among the first $1000$ Mersenne numbers.
 3298 %\syn{NO}
 3299 
 3300 \subsec{parvector$(N,i,\var{expr})$}\kbdsidx{parvector}\label{se:parvector}
 3301 As \kbd{vector(N,i,expr)} but the evaluations of \kbd{expr} are done in
 3302 parallel. The expression \kbd{expr} must not access global variables or
 3303 variables declared with \kbd{local()}, and must be free of side effects.
 3304 \bprog
 3305 parvector(10,i,quadclassunit(2^(100+i)+1).no)
 3306 @eprog\noindent
 3307 computes the class numbers in parallel.
 3308 %\syn{NO}
 3309 
 3310 \section{GP defaults}
 3311 \label{se:gp_defaults} This section documents the GP defaults,
 3312 that can be set either by the GP function \tet{default} or in your GPRC.
 3313 Be sure to check out \tet{parisize} and \tet{parisizemax} !
 3314 
 3315 \subsec{TeXstyle}\kbdsidx{TeXstyle}\label{se:def,TeXstyle}
 3316 The bits of this default allow
 3317 \kbd{gp} to use less rigid TeX formatting commands in the logfile. This
 3318 default is only taken into account when $\kbd{log} = 3$. The bits of
 3319 \kbd{TeXstyle} have the following meaning
 3320 
 3321 2: insert \kbd{{\bs}right} / \kbd{{\bs}left} pairs where appropriate.
 3322 
 3323 4: insert discretionary breaks in polynomials, to enhance the probability of
 3324 a good line break. You \emph{must} then define \kbd{{\bs}PARIbreak} as
 3325 follows:
 3326 \bprog
 3327    \def\PARIbreak{\hskip 0pt plus \hsize\relax\discretionary{}{}{}}
 3328 @eprog
 3329 
 3330 The default value is \kbd{0}.
 3331 
 3332 \subsec{breakloop}\kbdsidx{breakloop}\label{se:def,breakloop}
 3333 If true, enables the ``break loop'' debugging mode, see
 3334 \secref{se:break_loop}.
 3335 
 3336 The default value is \kbd{1} if we are running an interactive \kbd{gp}
 3337 session, and \kbd{0} otherwise.
 3338 
 3339 \subsec{colors}\kbdsidx{colors}\label{se:def,colors}
 3340 This default is only usable if \kbd{gp}
 3341 is running within certain color-capable terminals. For instance \kbd{rxvt},
 3342 \kbd{color\_xterm} and modern versions of \kbd{xterm} under X Windows, or
 3343 standard Linux/DOS text consoles. It causes \kbd{gp} to use a small palette of
 3344 colors for its output. With xterms, the colormap used corresponds to the
 3345 resources \kbd{Xterm*color$n$} where $n$ ranges from $0$ to $15$ (see the
 3346 file \kbd{misc/color.dft} for an example). Accepted values for this
 3347 default are strings \kbd{"$a_1$,\dots,$a_k$"} where $k\le7$ and each
 3348 $a_i$ is either
 3349 
 3350 \noindent\item the keyword \kbd{no} (use the default color, usually
 3351 black on transparent background)
 3352 
 3353 \noindent\item an integer between 0 and 15 corresponding to the
 3354 aforementioned colormap
 3355 
 3356 \noindent\item a triple $[c_0,c_1,c_2]$ where $c_0$ stands for foreground
 3357 color, $c_1$ for background color, and $c_2$ for attributes (0 is default, 1
 3358 is bold, 4 is underline).
 3359 
 3360 The output objects thus affected are respectively error messages,
 3361 history numbers, prompt, input line, output, help messages, timer (that's
 3362 seven of them). If $k < 7$, the remaining $a_i$ are assumed to be $no$. For
 3363 instance
 3364 %
 3365 \bprog
 3366 default(colors, "9, 5, no, no, 4")
 3367 @eprog
 3368 \noindent
 3369 typesets error messages in color $9$, history numbers in color $5$, output in
 3370 color $4$, and does not affect the rest.
 3371 
 3372 A set of default colors for dark (reverse video or PC console) and light
 3373 backgrounds respectively is activated when \kbd{colors} is set to
 3374 \kbd{darkbg}, resp.~\kbd{lightbg} (or any proper prefix: \kbd{d} is
 3375 recognized as an abbreviation for \kbd{darkbg}). A bold variant of
 3376 \kbd{darkbg}, called \kbd{boldfg}, is provided if you find the former too
 3377 pale.
 3378 
 3379 \emacs In the present version, this default is incompatible with PariEmacs.
 3380 Changing it will just fail silently (the alternative would be to display
 3381 escape sequences as is, since Emacs will refuse to interpret them).
 3382 You must customize color highlighting from the PariEmacs side, see its
 3383 documentation.
 3384 
 3385 The default value is \kbd{""} (no colors).
 3386 
 3387 \subsec{compatible}\kbdsidx{compatible}\label{se:def,compatible}
 3388 Obsolete. This default is now a no-op.
 3389 
 3390 \subsec{datadir}\kbdsidx{datadir}\label{se:def,datadir}
 3391 The name of directory containing the optional data files. For now,
 3392 this includes the \kbd{elldata}, \kbd{galdata}, \kbd{galpol}, \kbd{seadata}
 3393 packages.
 3394 
 3395 The default value is \kbd{/usr/local/share/pari}, or the override specified
 3396 via \kbd{Configure --datadir=}.
 3397 
 3398 \misctitle{Windows-specific note} On Windows operating systems, the
 3399 special value \kbd{@} stands for ``the directory where the \kbd{gp}
 3400 binary is installed''. This is the default value.
 3401 
 3402 \subsec{debug}\kbdsidx{debug}\label{se:def,debug}
 3403 Debugging level. If it is nonzero, some extra messages may be printed,
 3404 according to what is going on (see~\b{g}).
 3405 
 3406 The default value is \kbd{0} (no debugging messages).
 3407 
 3408 \subsec{debugfiles}\kbdsidx{debugfiles}\label{se:def,debugfiles}
 3409 File usage debugging level. If it is nonzero, \kbd{gp} will print
 3410 information on file descriptors in use, from PARI's point of view
 3411 (see~\b{gf}).
 3412 
 3413 The default value is \kbd{0} (no debugging messages).
 3414 
 3415 \subsec{debugmem}\kbdsidx{debugmem}\label{se:def,debugmem}
 3416 Memory debugging level (see \b{gm}). If this is nonzero, \kbd{gp} will
 3417 print increasingly precise notifications about memory use:
 3418 
 3419 \item $\kbd{debugmem} > 0$, notify when \kbd{parisize} changes (within the
 3420 boundaries set by \kbd{parisizemax});
 3421 
 3422 \item $\kbd{debugmem} > 1$, indicate any important garbage collection and the
 3423 function it is taking place in;
 3424 
 3425 \item $\kbd{debugmem} > 2$, indicate the creation/destruction of
 3426 ``blocks'' (or clones); expect lots of messages.
 3427 
 3428 \noindent {\bf Important Note:}
 3429 if you are running a version compiled for debugging (see Appendix~A) and
 3430 $\kbd{debugmem} > 1$, \kbd{gp} will further regularly print information on
 3431 memory usage, notifying whenever stack usage goes up or down by 1 MByte.
 3432 This functionality is disabled on non-debugging builds as it noticeably
 3433 slows down the performance.
 3434 
 3435 The default value is \kbd{1}.
 3436 
 3437 \subsec{echo}\kbdsidx{echo}\label{se:def,echo}
 3438 This default can be 0 (off), 1 (on) or 2 (on, raw). When \kbd{echo}
 3439 mode is on, each command is reprinted before being executed. This can be
 3440 useful when reading a file with the \b{r} or \kbd{read} commands. For
 3441 example, it is turned on at the beginning of the test files used to check
 3442 whether \kbd{gp} has been built correctly (see \b{e}). When \kbd{echo} is set
 3443 to 1 the input is cleaned up, removing white space and comments and uniting
 3444 multi-line input. When set to 2 (raw), the input is written as-is, without any
 3445 pre-processing.
 3446 
 3447 The default value is \kbd{0} (no echo).
 3448 
 3449 \subsec{factor\_add\_primes}\kbdsidx{def,factor_add_primes}\label{se:def,factor_add_primes}
 3450 This toggle is either 1 (on) or 0 (off). If on,
 3451 the integer factorization machinery calls \tet{addprimes} on prime
 3452 factors that were difficult to find (larger than $2^{24}$), so they are
 3453 automatically tried first in other factorizations. If a routine is performing
 3454 (or has performed) a factorization and is interrupted by an error or via
 3455 Control-C, this lets you recover the prime factors already found. The
 3456 downside is that a huge \kbd{addprimes} table unrelated to the current
 3457 computations will slow down arithmetic functions relying on integer
 3458 factorization; one should then empty the table using \tet{removeprimes}.
 3459 
 3460 The default value is \kbd{0}.
 3461 
 3462 \subsec{factor\_proven}\kbdsidx{def,factor_proven}\label{se:def,factor_proven}
 3463 This toggle is either 1 (on) or 0 (off). By
 3464 default, the factors output by the integer factorization machinery are
 3465 only pseudo-primes, not proven primes. If this toggle is
 3466 set, a primality proof is done for each factor and all results depending on
 3467 integer factorization are fully proven. This flag does not affect partial
 3468 factorization when it is explicitly requested. It also does not affect the
 3469 private table managed by \tet{addprimes}: its entries are included as is in
 3470 factorizations, without being tested for primality.
 3471 
 3472 The default value is \kbd{0}.
 3473 
 3474 \subsec{format}\kbdsidx{format}\label{se:def,format}
 3475 Of the form x$.n$, where x (conversion style)
 3476 is a letter in $\{\kbd{e},\kbd{f},\kbd{g}\}$, and $n$ (precision) is an
 3477 integer; this affects the way real numbers are printed:
 3478 
 3479 \item If the conversion style is \kbd{e}, real numbers are printed in
 3480 \idx{scientific format}, always with an explicit exponent,
 3481 e.g.~\kbd{3.3 E-5}.
 3482 
 3483 \item In style \kbd{f}, real numbers are generally printed in
 3484 \idx{fixed floating point format} without exponent, e.g.~\kbd{0.000033}. A
 3485 large real number, whose integer part is not well defined (not enough
 3486 significant digits), is printed in style~\kbd{e}. For instance
 3487 \kbd{10.\pow 100} known to ten significant digits is always printed in style
 3488 \kbd{e}.
 3489 
 3490 \item In style \kbd{g}, nonzero real numbers are printed in \kbd{f} format,
 3491 except when their decimal exponent is $< -4$, in which case they are printed
 3492 in \kbd{e} format. Real zeroes (of arbitrary exponent) are printed in \kbd{e}
 3493 format.
 3494 
 3495 The precision $n$ is the number of significant digits printed for real
 3496 numbers, except if $n<0$ where all the significant digits will be printed
 3497 (initial default 28, or 38 for 64-bit machines). For more powerful formatting
 3498 possibilities, see \tet{printf} and \tet{strprintf}.
 3499 
 3500 The default value is \kbd{"g.28"} and \kbd{"g.38"} on 32-bit and
 3501 64-bit machines, respectively.
 3502 
 3503 \subsec{graphcolormap}\kbdsidx{graphcolormap}\label{se:def,graphcolormap}
 3504 A vector of colors, to be used by hi-res graphing routines. Its length is
 3505 arbitrary, but it must contain at least 3 entries: the first 3 colors are
 3506 used for background, frame/ticks and axes respectively. All colors in the
 3507 colormap may be freely used in \tet{plotcolor} calls.
 3508 
 3509 A color is either given as in the default by character strings or by an RGB
 3510 code. For valid color names, see the standard \kbd{rgb.txt} file in X11
 3511 distributions, where we restrict to lowercase letters and remove all
 3512 whitespace from color names. An RGB code is a vector with 3 integer entries
 3513 between 0 and 255 or a \kbd{\#} followed by 6 hexadecimal digits.
 3514 For instance \kbd{[250, 235, 215]}, \kbd{"\#faebd7"}  and
 3515 \kbd{"antiquewhite"} all represent the same color.
 3516 
 3517 The default value is [\kbd{"white"}, \kbd{"black"}, \kbd{"blue"},
 3518 \kbd{"violetred"}, \kbd{"red"}, \kbd{"green"}, \kbd{"grey"},
 3519 \kbd{"gainsboro"}].
 3520 
 3521 \subsec{graphcolors}\kbdsidx{graphcolors}\label{se:def,graphcolors}
 3522 Entries in the
 3523 \tet{graphcolormap} that will be used to plot multi-curves. The successive
 3524 curves are drawn in colors
 3525 
 3526 \kbd{graphcolormap[graphcolors[1]]}, \kbd{graphcolormap[graphcolors[2]]},
 3527   \dots
 3528 
 3529 cycling when the \kbd{graphcolors} list is exhausted.
 3530 
 3531 The default value is \kbd{[4,5]}.
 3532 
 3533 \subsec{help}\kbdsidx{help}\label{se:def,help}
 3534 Name of the external help program to use from within \kbd{gp} when
 3535 extended help is invoked, usually through a \kbd{??} or \kbd{???} request
 3536 (see \secref{se:exthelp}), or \kbd{M-H} under readline (see
 3537 \secref{se:readline}).
 3538 
 3539 \misctitle{Windows-specific note} On Windows operating systems, if the
 3540 first character of \kbd{help} is \kbd{@}, it is replaced by ``the directory
 3541 where the \kbd{gp} binary is installed''.
 3542 
 3543 The default value is the path to the \kbd{gphelp} script we install.
 3544 
 3545 \subsec{histfile}\kbdsidx{histfile}\label{se:def,histfile}
 3546 Name of a file where
 3547 \kbd{gp} will keep a history of all \emph{input} commands (results are
 3548 omitted). If this file exists when the value of \kbd{histfile} changes,
 3549 it is read in and becomes part of the session history. Thus, setting this
 3550 default in your gprc saves your readline history between sessions. Setting
 3551 this default to the empty string \kbd{""} changes it to
 3552 \kbd{$<$undefined$>$}. Note that, by default, the number of history entries
 3553 saved is not limited: set \kbd{history-size} in readline's \kbd{.inputrc}
 3554 to limit the file size.
 3555 
 3556 The default value is \kbd{$<$undefined$>$} (no history file).
 3557 
 3558 \subsec{histsize}\kbdsidx{histsize}\label{se:def,histsize}
 3559 \kbd{gp} keeps a history of the last
 3560 \kbd{histsize} results computed so far, which you can recover using the
 3561 \kbd{\%} notation (see \secref{se:history}). When this number is exceeded,
 3562 the oldest values are erased. Tampering with this default is the only way to
 3563 get rid of the ones you do not need anymore.
 3564 
 3565 The default value is \kbd{5000}.
 3566 
 3567 \subsec{lines}\kbdsidx{lines}\label{se:def,lines}
 3568 If set to a positive value, \kbd{gp} prints at
 3569 most that many lines from each result, terminating the last line shown with
 3570 \kbd{[+++]} if further material has been suppressed. The various \kbd{print}
 3571 commands (see \secref{se:gp_program}) are unaffected, so you can always type
 3572 \kbd{print(\%)} or \b{a} to view the full result. If the actual screen width
 3573 cannot be determined, a ``line'' is assumed to be 80 characters long.
 3574 
 3575 The default value is \kbd{0}.
 3576 
 3577 \subsec{linewrap}\kbdsidx{linewrap}\label{se:def,linewrap}
 3578 If set to a positive value, \kbd{gp} wraps every single line after
 3579 printing that many characters.
 3580 
 3581 The default value is \kbd{0} (unset).
 3582 
 3583 \subsec{log}\kbdsidx{log}\label{se:def,log}
 3584 This can be either 0 (off) or 1, 2, 3
 3585 (on, see below for the various modes). When logging mode is turned on, \kbd{gp}
 3586 opens a log file, whose exact name is determined by the \kbd{logfile}
 3587 default. Subsequently, all the commands and results will be written to that
 3588 file (see \b{l}). In case a file with this precise name already existed, it
 3589 will not be erased: your data will be \emph{appended} at the end.
 3590 
 3591 The specific positive values of \kbd{log} have the following meaning
 3592 
 3593 1: plain logfile
 3594 
 3595 2: emit color codes to the logfile (if \kbd{colors} is set).
 3596 
 3597 3: write LaTeX output to the logfile (can be further customized using
 3598 \tet{TeXstyle}).
 3599 
 3600 The default value is \kbd{0}.
 3601 
 3602 \misctitle{Note} Logging starts as soon as \kbd{log} is set to a nonzero
 3603 value. In particular, when \kbd{log} is set in \kbd{gprc}, warnings and
 3604 errors triggered from the rest of the file will be written in the logfile.
 3605 For instance, on clean startup, the logfile will start by \kbd{Done.}
 3606 (from the \kbd{Reading GPRC:\dots Done.} diagnostic printed when starting
 3607 \kbd{gp}), then the \kbd{gp} header and prompt.
 3608 
 3609 \subsec{logfile}\kbdsidx{logfile}\label{se:def,logfile}
 3610 Name of the log file to be used when the \kbd{log} toggle is on.
 3611 Environment and time expansion are performed.
 3612 
 3613 The default value is \kbd{"pari.log"}.
 3614 
 3615 \subsec{nbthreads}\kbdsidx{nbthreads}\label{se:def,nbthreads}
 3616 This default is specific to the \emph{parallel} version of PARI and gp
 3617 (built via \kbd{Configure --mt=prthread} or \kbd{mpi}) and is ignored
 3618 otherwise. In parallel mode, it governs the number of threads to use for
 3619 parallel computing. The exact meaning and default value depend on the
 3620 \kbd{mt} engine used:
 3621 
 3622 \item \kbd{single}: not used (always a single thread).
 3623 
 3624 \item \kbd{pthread}: number of threads (unlimited, default: number of cores)
 3625 
 3626 \item \kbd{mpi}: number of MPI processes to use (limited to the number
 3627 allocated by \kbd{mpirun}, default: use all allocated processes).
 3628 
 3629 See also \kbd{threadsize} and \kbd{threadsizemax}.
 3630 
 3631 \subsec{new\_galois\_format}\kbdsidx{def,new_galois_format}\label{se:def,new_galois_format}
 3632 This toggle is either 1 (on) or 0 (off). If on,
 3633 the \tet{polgalois} command will use a different, more
 3634 consistent, naming scheme for Galois groups. This default is provided to
 3635 ensure that scripts can control this behavior and do not break unexpectedly.
 3636 
 3637 The default value is \kbd{0}. This value will change to $1$ (set) in the next
 3638 major version.
 3639 
 3640 \subsec{output}\kbdsidx{output}\label{se:def,output}
 3641 There are three possible values: 0
 3642 (=~\var{raw}), 1 (=~\var{prettymatrix}), or 3
 3643 (=~\var{external} \var{prettyprint}). This
 3644 means that, independently of the default \kbd{format} for reals which we
 3645 explained above, you can print results in three ways:
 3646 
 3647 \item \tev{raw format}, i.e.~a format which is equivalent to what you
 3648 input, including explicit multiplication signs, and everything typed on a
 3649 line instead of two dimensional boxes. This can have several advantages, for
 3650 instance it allows you to pick the result with a mouse or an editor, and to
 3651 paste it somewhere else.
 3652 
 3653 \item \tev{prettymatrix format}: this is identical to raw format, except
 3654 that matrices are printed as boxes instead of horizontally. This is
 3655 prettier, but takes more space and cannot be used for input. Column vectors
 3656 are still printed horizontally.
 3657 
 3658 \item \tev{external prettyprint}: pipes all \kbd{gp}
 3659 output in TeX format to an external prettyprinter, according to the value of
 3660 \tet{prettyprinter}. The default script (\tet{tex2mail}) converts its input
 3661 to readable two-dimensional text.
 3662 
 3663 Independently of the setting of this default, an object can be printed
 3664 in any of the three formats at any time using the commands \b{a} and \b{m}
 3665 and \b{B} respectively.
 3666 
 3667 The default value is \kbd{1} (\var{prettymatrix}).
 3668 
 3669 \subsec{parisize}\kbdsidx{parisize}\label{se:def,parisize}
 3670 \kbd{gp}, and in fact any program using the PARI
 3671 library, needs a \tev{stack} in which to do its computations; \kbd{parisize}
 3672 is the stack size, in bytes. It is recommended to increase this
 3673 default using a \tet{gprc}, to the value you believe PARI should be happy
 3674 with, given your typical computation. We strongly recommend to also
 3675 set \tet{parisizemax} to a much larger value in your \kbd{gprc}, about what
 3676 you believe your machine can stand: PARI will then try to fit its
 3677 computations within about \kbd{parisize} bytes, but will increase the stack
 3678 size if needed (up to \kbd{parisizemax}). Once the memory intensive
 3679 computation is over, PARI will restore the stack size to the originally
 3680 requested \kbd{parisize}.
 3681 
 3682 The default value is 4M, resp.~8M on a 32-bit, resp.~64-bit machine.
 3683 
 3684 \subsec{parisizemax}\kbdsidx{parisizemax}\label{se:def,parisizemax}
 3685 \kbd{gp}, and in fact any program using the PARI library, needs a
 3686 \tev{stack} in which to do its computations.  If nonzero,  \tet{parisizemax}
 3687 is the maximum size the stack can grow to, in bytes.  If zero, the stack will
 3688 not automatically grow, and will be limited to the value of \kbd{parisize}.
 3689 
 3690 When \kbd{parisizemax} is set, PARI tries to fit its
 3691 computations within about \kbd{parisize} bytes, but will increase the stack
 3692 size if needed, roughly doubling it each time (up to \kbd{parisizemax}
 3693 of course!) and printing a message such as \kbd{Warning: increasing stack size to}
 3694 \var{some value}. Once the memory intensive computation is over, PARI
 3695 will restore the stack size to the originally requested \kbd{parisize}
 3696 without printing further messages.
 3697 
 3698 We \emph{strongly} recommend to set \tet{parisizemax} permanently to a large
 3699 nonzero value in your \tet{gprc}, about what you believe your machine can
 3700 stand. It is possible to increase or decrease \kbd{parisizemax} inside a
 3701 running \kbd{gp} session, just use \kbd{default} as usual.
 3702 
 3703 The default value is $0$, for backward compatibility reasons.
 3704 
 3705 \subsec{path}\kbdsidx{path}\label{se:def,path}
 3706 This is a list of directories, separated by colons ':'
 3707 (semicolons ';' in the DOS world, since colons are preempted for drive names).
 3708 When asked to read a file whose name is not given by an absolute path
 3709 (does not start with \kbd{/}, \kbd{./} or \kbd{../}), \kbd{gp} will look for
 3710 it in these directories, in the order they were written in \kbd{path}. Here,
 3711 as usual, \kbd{.} means the current directory, and \kbd{..} its immediate
 3712 parent. Environment expansion is performed.
 3713 
 3714 The default value is \kbd{".:\til:\til/gp"} on UNIX systems,
 3715 \kbd{".;C:\bs;C:\bs GP"} on DOS, OS/2 and Windows, and \kbd{"."} otherwise.
 3716 
 3717 \subsec{plothsizes}\kbdsidx{plothsizes}\label{se:def,plothsizes}
 3718 If the graphic driver allows it, the array contains the size of the
 3719 terminal, the size of the font, the size of the ticks.
 3720 
 3721 \subsec{prettyprinter}\kbdsidx{prettyprinter}\label{se:def,prettyprinter}
 3722 The name of an external prettyprinter to use when
 3723 \kbd{output} is~3 (alternate prettyprinter). Note that the default
 3724 \tet{tex2mail} looks much nicer than the built-in ``beautified
 3725 format'' ($\kbd{output} = 2$).
 3726 
 3727 The default value is \kbd{"tex2mail -TeX -noindent -ragged -by\_par"}.
 3728 
 3729 \subsec{primelimit}\kbdsidx{primelimit}\label{se:def,primelimit}
 3730 \kbd{gp} precomputes a list of
 3731 all primes less than \kbd{primelimit} at initialization time, and can build
 3732 fast sieves on demand to quickly iterate over primes up to the \emph{square}
 3733 of \kbd{primelimit}. These are used by many arithmetic functions, usually for
 3734 trial division purposes. The maximal value is $2^{32} - 2049$ (resp $2^{64} -
 3735 2049$) on a 32-bit (resp.~64-bit) machine, but values beyond $10^8$,
 3736 allowing to iterate over primes up to $10^{16}$, do not seem useful.
 3737 
 3738 Since almost all arithmetic functions eventually require some table of prime
 3739 numbers, PARI guarantees that the first 6547 primes, up to and
 3740 including 65557, are precomputed, even if \kbd{primelimit} is $1$.
 3741 
 3742 This default is only used on startup: changing it will not recompute a new
 3743 table.
 3744 
 3745 \misctitle{Deprecated feature} \kbd{primelimit} was used in some
 3746 situations by algebraic number theory functions using the
 3747 \tet{nf_PARTIALFACT} flag (\tet{nfbasis}, \tet{nfdisc}, \tet{nfinit}, \dots):
 3748 this assumes that all primes $p > \kbd{primelimit}$ have a certain
 3749 property (the equation order is $p$-maximal). This is never done by default,
 3750 and must be explicitly set by the user of such functions. Nevertheless,
 3751 these functions now provide a more flexible interface, and their use
 3752 of the global default \kbd{primelimit} is deprecated.
 3753 
 3754 \misctitle{Deprecated feature} \kbd{factor(N, 0)} was used to partially
 3755 factor integers by removing all prime factors $\leq$ \kbd{primelimit}.
 3756 Don't use this, supply an explicit bound: \kbd{factor(N, bound)},
 3757 which avoids relying on an unpredictable global variable.
 3758 
 3759 The default value is \kbd{500k}.
 3760 
 3761 \subsec{prompt}\kbdsidx{prompt}\label{se:def,prompt}
 3762 A string that will be printed as
 3763 prompt. Note that most usual escape sequences are available there: \b{e} for
 3764 Esc, \b{n} for Newline, \dots, \kbd{\bs\bs} for \kbd{\bs}. Time expansion is
 3765 performed.
 3766 
 3767 This string is sent through the library function \tet{strftime} (on a
 3768 Unix system, you can try \kbd{man strftime} at your shell prompt). This means
 3769 that \kbd{\%} constructs have a special meaning, usually related to the time
 3770 and date. For instance, \kbd{\%H} = hour (24-hour clock) and \kbd{\%M} =
 3771 minute [00,59] (use \kbd{\%\%} to get a real \kbd{\%}).
 3772 
 3773 If you use \kbd{readline}, escape sequences in your prompt will result in
 3774 display bugs. If you have a relatively recent \kbd{readline} (see the comment
 3775 at the end of \secref{se:def,colors}), you can brace them with special sequences
 3776 (\kbd{\bs[} and \kbd{\bs]}), and you will be safe. If these just result in
 3777 extra spaces in your prompt, then you'll have to get a more recent
 3778 \kbd{readline}. See the file \kbd{misc/gprc.dft} for an example.
 3779 
 3780 \emacs {\bf Caution}: PariEmacs needs to know about the prompt pattern to
 3781 separate your input from previous \kbd{gp} results, without ambiguity. It is
 3782 not a trivial problem to adapt automatically this regular expression to an
 3783 arbitrary prompt (which can be self-modifying!). See PariEmacs's
 3784 documentation.
 3785 
 3786 The default value is \kbd{"? "}.
 3787 
 3788 \subsec{prompt\_cont}\kbdsidx{def,prompt_cont}\label{se:def,prompt_cont}
 3789 A string that will be printed
 3790 to prompt for continuation lines (e.g. in between braces, or after a
 3791 line-terminating backslash). Everything that applies to \kbd{prompt}
 3792 applies to \kbd{prompt\_cont} as well.
 3793 
 3794 The default value is \kbd{""}.
 3795 
 3796 \subsec{psfile}\kbdsidx{psfile}\label{se:def,psfile}
 3797 This default is obsolete, use one of plotexport, plothexport or
 3798 plothrawexport functions and write the result to file.
 3799 
 3800 \subsec{readline}\kbdsidx{readline}\label{se:def,readline}
 3801 Switches readline line-editing
 3802 facilities on and off. This may be useful if you are running \kbd{gp} in a Sun
 3803 \tet{cmdtool}, which interacts badly with readline. Of course, until readline
 3804 is switched on again, advanced editing features like automatic completion
 3805 and editing history are not available.
 3806 
 3807 The default value is \kbd{1}.
 3808 
 3809 \subsec{realbitprecision}\kbdsidx{realbitprecision}\label{se:def,realbitprecision}
 3810 The number of significant bits used to convert exact inputs given to
 3811 transcendental functions (see \secref{se:trans}), or to create
 3812 absolute floating point constants (input as \kbd{1.0} or \kbd{Pi} for
 3813 instance). Unless you tamper with the \tet{format} default, this is also
 3814 the number of significant bits used to print a \typ{REAL} number;
 3815 \kbd{format} will override this latter behavior, and allow you to have a
 3816 large internal precision while outputting few digits for instance.
 3817 
 3818 Note that most PARI's functions currently handle precision on a word basis (by
 3819 increments of 32 or 64 bits), hence bit precision may be a little larger
 3820 than the number of bits you expected. For instance to get 10 bits of
 3821 precision, you need one word of precision which, on a 64-bit machine,
 3822 correspond to 64 bits. To make things even more confusing, this internal bit
 3823 accuracy is converted to decimal digits when printing floating point numbers:
 3824 now 64 bits correspond to 19 printed decimal digits
 3825 ($19 <  \log_{10}(2^{64}) < 20$).
 3826 
 3827 The value returned when typing \kbd{default(realbitprecision)} is the internal
 3828 number of significant bits, not the number of printed decimal digits:
 3829 \bprog
 3830 ? default(realbitprecision, 10)
 3831 ? \pb
 3832       realbitprecision = 64 significant bits
 3833 ? default(realbitprecision)
 3834 %1 = 64
 3835 ? \p
 3836       realprecision = 3 significant digits
 3837 ? default(realprecision)
 3838 %2 = 19
 3839 @eprog\noindent Note that \tet{realprecision} and \kbd{\bs p} allow
 3840 to view and manipulate the internal precision in decimal digits.
 3841 
 3842 The default value is \kbd{128}, resp.~\kbd{96}, on a 64-bit, resp~.32-bit,
 3843 machine.
 3844 
 3845 \subsec{realprecision}\kbdsidx{realprecision}\label{se:def,realprecision}
 3846 The number of significant digits used to convert exact inputs given to
 3847 transcendental functions (see \secref{se:trans}), or to create
 3848 absolute floating point constants (input as \kbd{1.0} or \kbd{Pi} for
 3849 instance). Unless you tamper with the \tet{format} default, this is also
 3850 the number of significant digits used to print a \typ{REAL} number;
 3851 \kbd{format} will override this latter behavior, and allow you to have a
 3852 large internal precision while outputting few digits for instance.
 3853 
 3854 Note that PARI's internal precision works on a word basis (by increments of
 3855 32 or 64 bits), hence may be a little larger than the number of decimal
 3856 digits you expected. For instance to get 2 decimal digits you need one word
 3857 of precision which, on a 64-bit machine, actually gives you 19 digits ($19 <
 3858 \log_{10}(2^{64}) < 20$). The value returned when typing
 3859 \kbd{default(realprecision)} is the internal number of significant digits,
 3860 not the number of printed digits:
 3861 \bprog
 3862 ? default(realprecision, 2)
 3863       realprecision = 19 significant digits (2 digits displayed)
 3864 ? default(realprecision)
 3865 %1 = 19
 3866 @eprog
 3867 The default value is \kbd{38}, resp.~\kbd{28}, on a 64-bit, resp.~32-bit,
 3868 machine.
 3869 
 3870 \subsec{recover}\kbdsidx{recover}\label{se:def,recover}
 3871 This toggle is either 1 (on) or 0 (off). If you change this to $0$, any
 3872 error becomes fatal and causes the gp interpreter to exit immediately. Can be
 3873 useful in batch job scripts.
 3874 
 3875 The default value is \kbd{1}.
 3876 
 3877 \subsec{secure}\kbdsidx{secure}\label{se:def,secure}
 3878 This toggle is either 1 (on) or 0 (off). If on, the \tet{system} and
 3879 \tet{extern} command are disabled. These two commands are potentially
 3880 dangerous when you execute foreign scripts since they let \kbd{gp} execute
 3881 arbitrary UNIX commands. \kbd{gp} will ask for confirmation before letting
 3882 you (or a script) unset this toggle.
 3883 
 3884 The default value is \kbd{0}.
 3885 
 3886 \subsec{seriesprecision}\kbdsidx{seriesprecision}\label{se:def,seriesprecision}
 3887 Number of significant terms
 3888 when converting a polynomial or rational function to a power series
 3889 (see~\b{ps}).
 3890 
 3891 The default value is \kbd{16}.
 3892 
 3893 \subsec{simplify}\kbdsidx{simplify}\label{se:def,simplify}
 3894 This toggle is either 1 (on) or 0 (off). When the PARI library computes
 3895 something, the type of the
 3896 result is not always the simplest possible. The only type conversions which
 3897 the PARI library does automatically are rational numbers to integers (when
 3898 they are of type \typ{FRAC} and equal to integers), and similarly rational
 3899 functions to polynomials (when they are of type \typ{RFRAC} and equal to
 3900 polynomials). This feature is useful in many cases, and saves time, but can
 3901 be annoying at times. Hence you can disable this and, whenever you feel like
 3902 it, use the function \kbd{simplify} (see Chapter 3) which allows you to
 3903 simplify objects to the simplest possible types recursively (see~\b{y}).
 3904 \sidx{automatic simplification}
 3905 
 3906 The default value is \kbd{1}.
 3907 
 3908 \subsec{sopath}\kbdsidx{sopath}\label{se:def,sopath}
 3909 This is a list of directories, separated by colons ':'
 3910 (semicolons ';' in the DOS world, since colons are preempted for drive names).
 3911 When asked to \tet{install} an external symbol from a shared library whose
 3912 name is not given by an absolute path (does not start with \kbd{/}, \kbd{./}
 3913 or \kbd{../}), \kbd{gp} will look for it in these directories, in the order
 3914 they were written in \kbd{sopath}. Here, as usual, \kbd{.} means the current
 3915 directory, and \kbd{..} its immediate parent. Environment expansion is
 3916 performed.
 3917 
 3918 The default value is \kbd{""}, corresponding to an empty list of
 3919 directories: \tet{install} will use the library name as input (and look in
 3920 the current directory if the name is not an absolute path).
 3921 
 3922 \subsec{strictargs}\kbdsidx{strictargs}\label{se:def,strictargs}
 3923 This toggle is either 1 (on) or 0 (off). If on, all arguments to \emph{new}
 3924 user functions are mandatory unless the function supplies an explicit default
 3925 value.
 3926 Otherwise arguments have the default value $0$.
 3927 
 3928 In this example,
 3929 \bprog
 3930   fun(a,b=2)=a+b
 3931 @eprog
 3932 \kbd{a} is mandatory, while \kbd{b} is optional. If \kbd{strictargs} is on:
 3933 \bprog
 3934 ? fun()
 3935  ***   at top-level: fun()
 3936  ***                 ^-----
 3937  ***   in function fun: a,b=2
 3938  ***                    ^-----
 3939  ***   missing mandatory argument 'a' in user function.
 3940 @eprog
 3941 This applies to functions defined while \kbd{strictargs} is on. Changing \kbd{strictargs}
 3942 does not affect the behavior of previously defined functions.
 3943 
 3944 The default value is \kbd{0}.
 3945 
 3946 \subsec{strictmatch}\kbdsidx{strictmatch}\label{se:def,strictmatch}
 3947 Obsolete. This toggle is now a no-op.
 3948 
 3949 \subsec{threadsize}\kbdsidx{threadsize}\label{se:def,threadsize}
 3950 This default is specific to the \emph{parallel} version of PARI and gp
 3951 (built via \kbd{Configure --mt=prthread} or \kbd{mpi}) and is ignored
 3952 otherwise. In parallel mode,
 3953 each thread allocates its own private \tev{stack} for its
 3954 computations, see \kbd{parisize}. This value determines the size in bytes of
 3955 the stacks of each thread, so the total memory allocated will be
 3956 $\kbd{parisize}+\kbd{nbthreads}\times\kbd{threadsize}$.
 3957 
 3958 If set to $0$, the value used is the same as \kbd{parisize}. It is not
 3959 easy to estimate reliably a sufficient value for this parameter because PARI
 3960 itself will parallelize computations and we recommend to not set this value
 3961 explicitly unless it solves a specific problem for you. For instance if you
 3962 see frequent messages of the form
 3963 \bprog
 3964  *** Warning: not enough memory, new thread stack 10000002048
 3965 @eprog (Meaning that \kbd{threadsize} had to be temporarily increased.)
 3966 On the other hand we strongly recommend to set \kbd{parisizemax} and
 3967 \kbd{threadsizemax} to a nonzero value.
 3968 
 3969 The default value is $0$.
 3970 
 3971 \subsec{threadsizemax}\kbdsidx{threadsizemax}\label{se:def,threadsizemax}
 3972 This default is specific to the \emph{parallel} version of PARI and gp
 3973 (built via \kbd{Configure --mt=pthread} or \kbd{mpi}) and is ignored
 3974 otherwise. In parallel mode,
 3975 each threads allocates its own private \tev{stack} for
 3976 its computations, see \kbd{parisize} and \kbd{parisizemax}. The
 3977 values of \kbd{threadsize} and \kbd{threadsizemax} determine the usual
 3978 and maximal size in bytes of the stacks of each thread, so the total memory
 3979 allocated will
 3980 be between $\kbd{parisize}+\kbd{nbthreads}\times\kbd{threadsize}$. and
 3981 $\kbd{parisizemax}+\kbd{nbthreads}\times\kbd{threadsizemax}$.
 3982 
 3983 If set to $0$, the value used is the same as \kbd{threadsize}. We strongy
 3984 recommend to set both \kbd{parisizemax} and \kbd{threadsizemax} to a
 3985 nonzero value.
 3986 
 3987 The default value is $0$.
 3988 
 3989 \subsec{timer}\kbdsidx{timer}\label{se:def,timer}
 3990 This toggle is either 1 (on) or 0 (off). Every instruction sequence
 3991 in the gp calculator (anything ended by a newline in your input) is timed,
 3992 to some accuracy depending on the hardware and operating system. When
 3993 \tet{timer} is on, each such timing is printed immediately before the
 3994 output as follows:
 3995 \bprog
 3996 ? factor(2^2^7+1)
 3997 time = 108 ms.     \\ this line omitted if 'timer' is 0
 3998 %1 =
 3999 [     59649589127497217 1]
 4000 
 4001 [5704689200685129054721 1]
 4002 @eprog\noindent (See also \kbd{\#} and \kbd{\#\#}.)
 4003 
 4004 The time measured is the user \idx{CPU time}, \emph{not} including the time
 4005 for printing the results. If the time is negligible ($< 1$ ms.), nothing is
 4006 printed: in particular, no timing should be printed when defining a user
 4007 function or an alias, or installing a symbol from the library.
 4008 
 4009 The default value is \kbd{0} (off).
 4010 
 4011 \section{Standard monadic or dyadic operators}
 4012 
 4013 \subsec{Boolean operators}\sidx{Boolean operators}
 4014 
 4015 Any nonzero value is interpreted as \var{true} and any zero as \var{false}
 4016 (this includes empty vectors or matrices). The standard boolean operators
 4017 \kbd{||} (\idx{inclusive or}), \kbd{\&\&} (\idx{and})\sidx{or} and \kbd{!}
 4018 in prefix notation (\idx{not}) are available.
 4019 Their value is $1$ (true) or $0$ (false):
 4020 \bprog
 4021 ? a && b  \\ 1 iff a and b are nonzero
 4022 ? a || b  \\ 1 iff a or b is nonzero
 4023 ? !a      \\ 1 iff a is zero
 4024 @eprog
 4025 
 4026 \subsec{Comparison}
 4027 The standard real \idx{comparison operators} \kbd{<=}, \kbd{<}, \kbd{>=},
 4028 \kbd{>}, are available in GP. The result is 1 if the comparison is true, 0
 4029 if it is false. These operators allow to compare integers (\typ{INT}),
 4030 rational (\typ{FRAC}) or real (\typ{REAL}) numbers,
 4031 real quadratic numbers (\typ{QUAD} of positive discriminant) and infinity
 4032 (\kbd{oo}, \typ{INFINITY}).
 4033 
 4034 By extension, two character strings (\typ{STR}) are compared using
 4035 the standard lexicographic order. Comparing a string to an object of a
 4036 different type raises an exception. See also the \tet{cmp} universal
 4037 comparison function.
 4038 
 4039 \subsec{Equality}
 4040 Two operators allow to test for equality: \kbd{==} (equality up to type
 4041 coercion) and \kbd{===} (identity). The result is $1$ if equality is decided,
 4042 else $0$.
 4043 
 4044 The operator \kbd{===} is strict: objects of different type or length are
 4045 never identical, polynomials in different variables are never identical,
 4046 even if constant. On the contrary, \kbd{==} is very liberal: $a~\kbd{==}~b$
 4047 decides whether there is a natural map sending $a$ to the domain of $b$
 4048 or sending $b$ to the domain of $a$, such that the comparison makes sense
 4049 and equality holds. For instance
 4050 \bprog
 4051 ? 4 == Mod(1,3) \\ equal
 4052 %1 = 1
 4053 ? 4 === Mod(1,3) \\ but not identical
 4054 %2 = 0
 4055 
 4056 ? 'x == 'y   \\ not equal (nonconstant and different variables)
 4057 %3 = 0
 4058 ? Pol(0,'x) == Pol(0,'y)  \\ equal (constant: ignore variable)
 4059 %4 = 1
 4060 ? Pol(0,'x) == Pol(0,'y)  \\ not identical
 4061 %5 = 0
 4062 
 4063 ? 0 == Pol(0) \\ equal
 4064 %6 = 1
 4065 ? [0] == 0     \\ equal
 4066 %7 = 1
 4067 ? [0, 0] == 0  \\ equal
 4068 %8 = 1
 4069 ? [0] == [0,0] \\ not equal
 4070 %9 = 1
 4071 @eprog\noindent In particular \kbd{==} is not transitive in general; it is
 4072 transitive when used to compare objects known to have the same type. The
 4073 operator \kbd{===} is transitive. The \kbd{==} operator allows two
 4074 equivalent negated forms: \kbd{!=} or \kbd{<>}; there is no negated form for
 4075 \kbd{===}.
 4076 
 4077 Do not mistake \kbd{=} for \kbd{==}: it is the assignment statement.
 4078 
 4079 \subseckbd{+$/$-} The expressions \kbd{+}$x$ and \kbd{-}$x$ refer
 4080 to monadic operators: the first does nothing, the second negates $x$.
 4081 
 4082 The library syntax is \fun{GEN}{gneg}{GEN x} for \kbd{-}$x$.
 4083 
 4084 \subseckbd{+} The expression $x$ \kbd{+} $y$ is the \idx{sum} of $x$ and $y$.
 4085 Addition between a scalar type $x$ and a \typ{COL} or \typ{MAT} $y$ returns
 4086 respectively $[y[1] + x, y[2],\dots]$ and $y + x \text{Id}$. Other additions
 4087 between a scalar type and a vector or a matrix, or between vector/matrices of
 4088 incompatible sizes are forbidden.
 4089 
 4090 The library syntax is \fun{GEN}{gadd}{GEN x, GEN y}.
 4091 
 4092 \subseckbd{-} The expression $x$ \kbd{-} $y$ is the \idx{difference} of $x$
 4093 and $y$. Subtraction between a scalar type $x$ and a \typ{COL} or \typ{MAT}
 4094 $y$ returns respectively $[y[1] - x, y[2],\dots]$ and $y - x \text{Id}$.
 4095 Other subtractions between a scalar type and a vector or a matrix, or
 4096 between vector/matrices of incompatible sizes are forbidden.
 4097 
 4098 The library syntax is \fun{GEN}{gsub}{GEN x, GEN y} for $x$ \kbd{-} $y$.
 4099 
 4100 \subseckbd{*} The expression $x$ \kbd{*} $y$ is the \idx{product} of $x$
 4101 and $y$. Among the prominent impossibilities are multiplication between
 4102 vector/matrices of incompatible sizes, between a \typ{INTMOD} or \typ{PADIC}
 4103 Restricted to scalars, \kbd{*} is commutative; because of vector and matrix
 4104 operations, it is not commutative in general.
 4105 
 4106 Multiplication between two \typ{VEC}s or two \typ{COL}s is not
 4107 allowed; to take the \idx{scalar product} of two vectors of the same length,
 4108 transpose one of the vectors (using the operator \kbd{\til} or the function
 4109 \kbd{mattranspose}, see \secref{se:linear_algebra}) and multiply a line vector
 4110 by a column vector:
 4111 \bprog
 4112 ? a = [1,2,3];
 4113 ? a * a
 4114   ***   at top-level: a*a
 4115   ***                  ^--
 4116   *** _*_: forbidden multiplication t_VEC * t_VEC.
 4117 ? a * a~
 4118 %2 = 14
 4119 @eprog
 4120 
 4121 If $x,y$ are binary quadratic forms, compose them; see also
 4122 \kbd{qfbnucomp} and \kbd{qfbnupow}. If $x,y$ are \typ{VECSMALL} of the same
 4123 length, understand them as permutations and compose them.
 4124 
 4125 The library syntax is \fun{GEN}{gmul}{GEN x, GEN y} for $x$ \kbd{*} $y$.
 4126 Also available is \fun{GEN}{gsqr}{GEN x} for $x$ \kbd{*} $x$.
 4127 
 4128 \subseckbd{/} The expression $x$ \kbd{/} $y$ is the \idx{quotient} of $x$
 4129 and $y$. In addition to the impossibilities for multiplication, note that if
 4130 the divisor is a matrix, it must be an invertible square matrix, and in that
 4131 case the result is $x*y^{-1}$. Furthermore note that the result is as exact
 4132 as possible: in particular, division of two integers always gives a rational
 4133 number (which may be an integer if the quotient is exact) and \emph{not} the
 4134 Euclidean quotient (see $x$ \kbd{\bs} $y$ for that), and similarly the
 4135 quotient of two polynomials is a rational function in general. To obtain the
 4136 approximate real value of the quotient of two integers, add \kbd{0.} to the
 4137 result; to obtain the approximate $p$-adic value of the quotient of two
 4138 integers, add \kbd{O(p\pow k)} to the result; finally, to obtain the
 4139 \idx{Taylor series} expansion of the quotient of two polynomials, add
 4140 \kbd{O(X\pow k)} to the result or use the \kbd{taylor} function
 4141 (see \secref{se:taylor}). \label{se:gdiv}
 4142 
 4143 The library syntax is \fun{GEN}{gdiv}{GEN x, GEN y} for $x$ \kbd{/} $y$.
 4144 
 4145 \subseckbd{\bs} The expression \kbd{$x$ \bs\ $y$} is the
 4146 \idx{Euclidean quotient} of $x$ and $y$. If $y$ is a real scalar, this is
 4147 defined as \kbd{floor($x$/$y$)} if $y > 0$, and \kbd{ceil($x$/$y$)} if
 4148 $y < 0$ and the division is not exact. Hence the remainder
 4149 \kbd{$x$ - ($x$\bs$y$)*$y$} is in $[0, |y|[$.
 4150 
 4151 Note that when $y$ is an integer and $x$ a polynomial, $y$ is first promoted
 4152 to a polynomial of degree $0$. When $x$ is a vector or matrix, the operator
 4153 is applied componentwise.
 4154 
 4155 The library syntax is \fun{GEN}{gdivent}{GEN x, GEN y}
 4156 for $x$ \kbd{\bs} $y$.
 4157 
 4158 \subseckbd{\bs/} The expression $x$ \b{/} $y$ evaluates to the rounded
 4159 \idx{Euclidean quotient} of $x$ and $y$. This is the same as \kbd{$x$ \bs\ $y$}
 4160 except for scalar division: the quotient is such that the corresponding
 4161 remainder is smallest in absolute value and in case of a tie the quotient
 4162 closest to $+\infty$ is chosen (hence the remainder would belong to
 4163 $[{-}|y|/2, |y|/2[$).
 4164 
 4165 When $x$ is a vector or matrix, the operator is applied componentwise.
 4166 
 4167 The library syntax is \fun{GEN}{gdivround}{GEN x, GEN y}
 4168 for $x$ \b{/} $y$.
 4169 
 4170 \subseckbd{\%} The expression \kbd{$x$ \% $y$} evaluates to the modular
 4171 \idx{Euclidean remainder} of $x$ and $y$, which we now define. When $x$ or $y$
 4172 is a nonintegral real number, \kbd{$x$\%$y$} is defined as
 4173 \kbd{$x$ - ($x$\bs$y$)*$y$}. Otherwise, if $y$ is an integer, this is
 4174 the smallest
 4175 nonnegative integer congruent to $x$ modulo $y$. (This actually coincides
 4176 with the previous definition if and only if $x$ is an integer.) If $y$ is a
 4177 polynomial, this is the polynomial of smallest degree congruent to
 4178 $x$ modulo $y$. For instance:
 4179 \bprog
 4180 ? (1/2) % 3
 4181 %1 = 2
 4182 ? 0.5 % 3
 4183 %2 = 0.5000000000000000000000000000
 4184 ? (1/2) % 3.0
 4185 %3 = 1/2
 4186 @eprog
 4187 Note that when $y$ is an integer and $x$ a polynomial, $y$ is first promoted
 4188 to a polynomial of degree $0$. When $x$ is a vector or matrix, the operator
 4189 is applied componentwise.
 4190 
 4191 The library syntax is \fun{GEN}{gmod}{GEN x, GEN y}
 4192 for $x$ \kbd{\%} $y$.
 4193 
 4194 \subseckbd{\var{op}=} When \var{op} is a binary arithmetic operator among
 4195 \kbd{+}, \kbd{-}, \kbd{\%}, \kbd{/}, \kbd{\bs} or \kbd{\bs/}, the construct
 4196 $x \var{op}= y$ is a shortcut for $x = x \var{op} y$.
 4197 \bprog
 4198 ? v[1] += 10  \\ increment v[1] by 10
 4199 ? a /= 2 \\ divide a by 2
 4200 @eprog
 4201 
 4202 \subseckbd{++} \kbd{$x$++} is a shortcut for \kbd{$x$ = $x$ + 1}.
 4203 
 4204 \subseckbd{--} \kbd{$x$--} is a shortcut for \kbd{$x$ = $x$ - 1}.
 4205 
 4206 \subseckbd{\pow} The expression $x\hbox{\kbd{\pow}}n$ is \idx{powering}.
 4207 
 4208 \item If the exponent $n$ is an integer, then exact operations are performed
 4209 using binary (left-shift) powering techniques. By definition, $x^0$ is
 4210 (an empty product interpreted as) an exact $1$ in the underlying prime
 4211 ring:
 4212 \bprog
 4213 ? 0.0 ^ 0
 4214 %1 = 1
 4215 ? (1 + O(2^3)) ^ 0
 4216 %2 = 1
 4217 ? (1 + O(x)) ^ 0
 4218 %3 = 1
 4219 ? Mod(2,4)^0
 4220 %4 = Mod(1,4)
 4221 ? Mod(x,x^2)^0
 4222 %5 = Mod(1, x^2)
 4223 @eprog\noindent
 4224 If $x$ is a $p$-adic number, its precision will increase if $v_p(n) > 0$ and
 4225 $n \neq 0$. Powering a binary quadratic form (types \typ{QFI} and
 4226 \typ{QFR}) returns a representative of the class, which is reduced if the
 4227 input was. (In particular, \kbd{x \pow 1} returns $x$ itself, whether it is
 4228 reduced or not.)
 4229 
 4230 PARI rewrites the multiplication $x * x$ of two \emph{identical}
 4231 objects as $x^2$. Here, identical means the operands are reference the same
 4232 chunk of memory; no equality test is performed. This is no longer true when
 4233 more than two arguments are involved.
 4234 \bprog
 4235 ? a = 1 + O(2); b = a;
 4236 ? a * a  \\ = a^2, precision increases
 4237 %2 = 1 + O(2^3)
 4238 ? a * b \\ not rewritten as a^2
 4239 %3 = 1 + O(2)
 4240 ? a*a*a \\ not rewritten as a^3
 4241 %4 = 1 + O(2)
 4242 @eprog
 4243 
 4244 \item If the exponent is a rational number $p/q$ the behaviour depends
 4245 on~$x$. If $x$ is a complex number, return $\exp(n \log x)$ (principal
 4246 branch), in an exact form if possible:
 4247 \bprog
 4248 ? 4^(1/2)  \\ 4 being a square, this is exact
 4249 %1 = 2
 4250 ? 2^(1/2)  \\ now inexact
 4251 %2 = 1.4142135623730950488016887242096980786
 4252 ? (-1/4)^(1/2) \\ exact again
 4253 %3 = 1/2*I
 4254 ? (-1)^(1/3)
 4255 %4 = 0.500...+ 0.866...*I
 4256 @eprog\noindent Note that even though $-1$ is an exact cube root of $-1$,
 4257 it is not $\exp(\log(-1)/3)$; the latter is returned.
 4258 
 4259 Otherwise return a solution $y$ of $y^q = x^p$ if it exists; beware that
 4260 this is defined up to $q$-th roots of 1 in the base field. Intmods modulo
 4261 composite numbers are not supported.
 4262 \bprog
 4263 ? Mod(7,19)^(1/2)
 4264 %1 = Mod(11, 19) \\ is any square root
 4265 ? sqrt(Mod(7,19))
 4266 %2 = Mod(8, 19)  \\ is the smallest square root
 4267 ? Mod(1,4)^(1/2)
 4268  ***   at top-level: Mod(1,4)^(1/2)
 4269  ***                         ^------
 4270  *** _^_: not a prime number in gpow: 4.
 4271 @eprog
 4272 
 4273 \item If the exponent is a negative integer or rational number,
 4274 an \idx{inverse} must be computed. For noninvertible \typ{INTMOD} $x$, this
 4275 will fail and (for $n$ an integer) implicitly exhibit a factor of the modulus:
 4276 \bprog
 4277 ? Mod(4,6)^(-1)
 4278   ***   at top-level: Mod(4,6)^(-1)
 4279   ***                         ^-----
 4280   *** _^_: impossible inverse modulo: Mod(2, 6).
 4281 @eprog\noindent
 4282 Here, a factor 2 is obtained directly. In general, take the gcd of the
 4283 representative and the modulus. This is most useful when performing
 4284 complicated operations modulo an integer $N$ whose factorization is
 4285 unknown. Either the computation succeeds and all is well, or a factor $d$
 4286 is discovered and the computation may be restarted modulo $d$ or $N/d$.
 4287 
 4288 For noninvertible \typ{POLMOD} $x$, the behavior is the same:
 4289 \bprog
 4290 ? Mod(x^2, x^3-x)^(-1)
 4291   ***   at top-level: Mod(x^2,x^3-x)^(-1)
 4292   ***                               ^-----
 4293   *** _^_: impossible inverse in RgXQ_inv: Mod(x^2, x^3 - x).
 4294 @eprog\noindent Note that the underlying algorihm (subresultant) assumes
 4295 that the base ring is a domain:
 4296 \bprog
 4297 ? a = Mod(3*y^3+1, 4); b = y^6+y^5+y^4+y^3+y^2+y+1; c = Mod(a,b);
 4298 ? c^(-1)
 4299   ***   at top-level: Mod(a,b)^(-1)
 4300   ***                         ^-----
 4301   *** _^_: impossible inverse modulo: Mod(2, 4).
 4302 @eprog\noindent
 4303 In fact $c$ is invertible, but $\Z/4\Z$ is not a domain and the algorithm
 4304 fails. It is possible for the algorithm to succeed in such situations
 4305 and any returned result will be correct, but chances are that an error
 4306 will occur first. In this specific case, one should work with $2$-adics.
 4307 In general, one can also try the following approach
 4308 \bprog
 4309 ? inversemod(a, b) =
 4310 { my(m, v = variable(b));
 4311   m = polsylvestermatrix(polrecip(a), polrecip(b));
 4312   m = matinverseimage(m, matid(#m)[,1]);
 4313   Polrev(m[1..poldegree(b)], v);
 4314 }
 4315 ? inversemod(a,b)
 4316 %2 = Mod(2,4)*y^5 + Mod(3,4)*y^3 + Mod(1,4)*y^2 + Mod(3,4)*y + Mod(2,4)
 4317 @eprog\noindent
 4318 This is not guaranteed to work either since \kbd{matinverseimage} must also
 4319 invert pivots. See \secref{se:linear_algebra}.
 4320 
 4321 For a \typ{MAT} $x$, the matrix is expected to be square and invertible, except
 4322 in the special case \kbd{x\pow(-1)} which returns a left inverse if one exists
 4323 (rectangular $x$ with full column rank).
 4324 \bprog
 4325 ? x = Mat([1;2])
 4326 %1 =
 4327 [1]
 4328 
 4329 [2]
 4330 
 4331 ? x^(-1)
 4332 %2 =
 4333 [1 0]
 4334 @eprog
 4335 
 4336 \item Finally, if the exponent $n$ is not an rational number, powering is
 4337 treated as the transcendental function $\exp(n\log x)$, although it will be
 4338 more precise than the latter when $n$ and $x$ are exact:
 4339 \bprog
 4340 ? s = 1/2 + 10^14 * I
 4341 ? localprec(200); z = 2^s  \\ for reference
 4342 ? exponent(2^s - z)
 4343 %3 = -127  \\ perfect
 4344 ? exponent(exp(s * log(2)) - z)
 4345 %4 = -84 \\ not so good
 4346 @eprog\noindent The second computation is less precise because $\log(2)$ is
 4347 first computed to $38$ decimal digits, then multiplied by $s$, which has a
 4348 huge imaginary part amplifying the error.
 4349 
 4350 In this case, $x \mapsto x^n$ is treated as a transcendental function and
 4351 and in particular acts
 4352 componentwise on vector or matrices, even square matrices ! (See
 4353 \secref{se:trans}.) If $x$ is $0$ and $n$ is an inexact $0$, this will raise
 4354 an exception:
 4355 \bprog
 4356 ? 4 ^ 1.0
 4357 %1 = 4.0000000000000000000000000000000000000
 4358 ? 0^ 0.0
 4359  ***   at top-level: 0^0.0
 4360  ***                  ^----
 4361  *** _^_: domain error in gpow(0,n): n <= 0
 4362 @eprog
 4363 
 4364 The library syntax is \fun{GEN}{gpow}{GEN x, GEN n, long prec}
 4365 for $x\hbox{\kbd{\pow}}n$.
 4366 
 4367 \subsec{cmp$(x,y)$}\kbdsidx{cmp}\label{se:cmp}
 4368 Gives the result of a comparison between arbitrary objects $x$ and $y$
 4369 (as $-1$, $0$ or $1$). The underlying order relation is transitive,
 4370 the function returns $0$ if and only if $x~\kbd{===}~y$. It has no
 4371 mathematical meaning but satisfies the following properties when comparing
 4372 entries of the same type:
 4373 
 4374 \item two \typ{INT}s compare as usual (i.e. \kbd{cmp}$(x,y) < 0$ if and only
 4375 if $x < y$);
 4376 
 4377 \item two \typ{VECSMALL}s of the same length compare lexicographically;
 4378 
 4379 \item two \typ{STR}s compare lexicographically.
 4380 
 4381 In case all components are equal up to the smallest length of the operands,
 4382 the more complex is considered to be larger. More precisely, the longest is
 4383 the largest; when lengths are equal, we have matrix $>$ vector $>$ scalar.
 4384 For example:
 4385 \bprog
 4386 ? cmp(1, 2)
 4387 %1 = -1
 4388 ? cmp(2, 1)
 4389 %2 = 1
 4390 ? cmp(1, 1.0)   \\ note that 1 == 1.0, but (1===1.0) is false.
 4391 %3 = -1
 4392 ? cmp(x + Pi, [])
 4393 %4 = -1
 4394 @eprog\noindent This function is mostly useful to handle sorted lists or
 4395 vectors of arbitrary objects. For instance, if $v$ is a vector, the
 4396 construction \kbd{vecsort(v, cmp)} is equivalent to \kbd{Set(v)}.
 4397 
 4398 The library syntax is \fun{GEN}{cmp_universal}{GEN x, GEN y}.
 4399 
 4400 \subsec{divrem$(x,y,\{v\})$}\kbdsidx{divrem}\label{se:divrem}
 4401 Creates a column vector with two components, the first being the Euclidean
 4402 quotient (\kbd{$x$ \bs\ $y$}), the second the Euclidean remainder
 4403 (\kbd{$x$ - ($x$\bs$y$)*$y$}), of the division of $x$ by $y$. This avoids the
 4404 need to do two divisions if one needs both the quotient and the remainder.
 4405 If $v$ is present, and $x$, $y$ are multivariate
 4406 polynomials, divide with respect to the variable $v$.
 4407 
 4408 Beware that \kbd{divrem($x$,$y$)[2]} is in general not the same as
 4409 \kbd{$x$ \% $y$}; no GP operator corresponds to it:
 4410 \bprog
 4411 ? divrem(1/2, 3)[2]
 4412 %1 = 1/2
 4413 ? (1/2) % 3
 4414 %2 = 2
 4415 ? divrem(Mod(2,9), 3)[2]
 4416  ***   at top-level: divrem(Mod(2,9),3)[2
 4417  ***                 ^--------------------
 4418  ***   forbidden division t_INTMOD \ t_INT.
 4419 ? Mod(2,9) % 6
 4420 %3 = Mod(2,3)
 4421 @eprog
 4422 
 4423 The library syntax is \fun{GEN}{divrem}{GEN x, GEN y, long v = -1} where \kbd{v} is a variable number.
 4424 Also available is \fun{GEN}{gdiventres}{GEN x, GEN y} when $v$ is
 4425 not needed.
 4426 
 4427 \subsec{lex$(x,y)$}\kbdsidx{lex}\label{se:lex}
 4428 Gives the result of a lexicographic comparison
 4429 between $x$ and $y$ (as $-1$, $0$ or $1$). This is to be interpreted in quite
 4430 a wide sense: it is admissible to compare objects of different types
 4431 (scalars, vectors, matrices), provided the scalars can be compared, as well
 4432 as vectors/matrices of different lengths; finally, when comparing two scalars,
 4433 a complex number $a + I*b$ is interpreted as a vector $[a,b]$ and a real
 4434 number $a$ as $[a,0]$. The comparison is recursive.
 4435 
 4436 In case all components are equal up to the smallest length of the operands,
 4437 the more complex is considered to be larger. More precisely, the longest is
 4438 the largest; when lengths are equal, we have matrix $>$ vector $>$ scalar.
 4439 For example:
 4440 \bprog
 4441 ? lex([1,3], [1,2,5])
 4442 %1 = 1
 4443 ? lex([1,3], [1,3,-1])
 4444 %2 = -1
 4445 ? lex([1], [[1]])
 4446 %3 = -1
 4447 ? lex([1], [1]~)
 4448 %4 = 0
 4449 ? lex(2 - I, 1)
 4450 %5 = 1
 4451 ? lex(2 - I, 2)
 4452 %6 = 2
 4453 @eprog
 4454 
 4455 The library syntax is \fun{GEN}{lexcmp}{GEN x, GEN y}.
 4456 
 4457 \subsec{max$(x,y)$}\kbdsidx{max}\label{se:max}
 4458 Creates the maximum of $x$ and $y$ when they can be compared.
 4459 
 4460 The library syntax is \fun{GEN}{gmax}{GEN x, GEN y}.
 4461 
 4462 \subsec{min$(x,y)$}\kbdsidx{min}\label{se:min}
 4463 Creates the minimum of $x$ and $y$ when they can be compared.
 4464 
 4465 The library syntax is \fun{GEN}{gmin}{GEN x, GEN y}.
 4466 
 4467 \subsec{shift$(x,n)$}\kbdsidx{shift}\label{se:shift}
 4468 Shifts $x$ componentwise left by $n$ bits if $n\ge0$ and right by $|n|$
 4469 bits if $n<0$. May be abbreviated as $x$ \kbd{<<} $n$ or $x$ \kbd{>>} $(-n)$.
 4470 A left shift by $n$ corresponds to multiplication by $2^n$. A right shift of an
 4471 integer $x$ by $|n|$ corresponds to a Euclidean division of $x$ by $2^{|n|}$
 4472 with a remainder of the same sign as $x$, hence is not the same (in general) as
 4473 $x \kbd{\bs} 2^n$.
 4474 
 4475 The library syntax is \fun{GEN}{gshift}{GEN x, long n}.
 4476 
 4477 \subsec{shiftmul$(x,n)$}\kbdsidx{shiftmul}\label{se:shiftmul}
 4478 Multiplies $x$ by $2^n$. The difference with
 4479 \kbd{shift} is that when $n<0$, ordinary division takes place, hence for
 4480 example if $x$ is an integer the result may be a fraction, while for shifts
 4481 Euclidean division takes place when $n<0$ hence if $x$ is an integer the result
 4482 is still an integer.
 4483 
 4484 The library syntax is \fun{GEN}{gmul2n}{GEN x, long n}.
 4485 
 4486 \subsec{sign$(x)$}\kbdsidx{sign}\label{se:sign}
 4487 \idx{sign} ($0$, $1$ or $-1$) of $x$, which must be of
 4488 type integer, real or fraction; \typ{QUAD} with positive discriminants and
 4489 \typ{INFINITY} are also supported.
 4490 
 4491 The library syntax is \fun{GEN}{gsigne}{GEN x}.
 4492 
 4493 \subsec{vecmax$(x,\{\&v\})$}\kbdsidx{vecmax}\label{se:vecmax}
 4494 If $x$ is a vector or a matrix, returns the largest entry of $x$,
 4495 otherwise returns a copy of $x$. Error if $x$ is empty.
 4496 
 4497 If $v$ is given, set it to the index of a largest entry (indirect maximum),
 4498 when $x$ is a vector. If $x$ is a matrix, set $v$ to coordinates $[i,j]$
 4499 such that $x[i,j]$ is a largest entry. This flag is ignored if $x$ is not a
 4500 vector or matrix.
 4501 
 4502 \bprog
 4503 ? vecmax([10, 20, -30, 40])
 4504 %1 = 40
 4505 ? vecmax([10, 20, -30, 40], &v); v
 4506 %2 = 4
 4507 ? vecmax([10, 20; -30, 40], &v); v
 4508 %3 = [2, 2]
 4509 @eprog
 4510 
 4511 The library syntax is \fun{GEN}{vecmax0}{GEN x, GEN *v = NULL}.
 4512 When $v$ is not needed, the function \fun{GEN}{vecmax}{GEN x} is
 4513 also available.
 4514 
 4515 \subsec{vecmin$(x,\{\&v\})$}\kbdsidx{vecmin}\label{se:vecmin}
 4516 If $x$ is a vector or a matrix, returns the smallest entry of $x$,
 4517 otherwise returns a copy of $x$. Error if $x$ is empty.
 4518 
 4519 If $v$ is given, set it to the index of a smallest entry (indirect minimum),
 4520 when $x$ is a vector. If $x$ is a matrix, set $v$ to coordinates $[i,j]$ such
 4521 that $x[i,j]$ is a smallest entry. This is ignored if $x$ is not a vector or
 4522 matrix.
 4523 
 4524 \bprog
 4525 ? vecmin([10, 20, -30, 40])
 4526 %1 = -30
 4527 ? vecmin([10, 20, -30, 40], &v); v
 4528 %2 = 3
 4529 ? vecmin([10, 20; -30, 40], &v); v
 4530 %3 = [2, 1]
 4531 @eprog
 4532 
 4533 The library syntax is \fun{GEN}{vecmin0}{GEN x, GEN *v = NULL}.
 4534 When $v$ is not needed, the function \fun{GEN}{vecmin}{GEN x} is also
 4535 available.
 4536 
 4537 \section{Conversions and similar elementary functions or commands}
 4538 \label{se:conversion}
 4539 
 4540 \noindent
 4541 Many of the conversion functions are rounding or truncating operations. In
 4542 this case, if the argument is a rational function, the result is the
 4543 Euclidean quotient of the numerator by the denominator, and if the argument
 4544 is a vector or a matrix, the operation is done componentwise. This will not
 4545 be restated for every function.
 4546 
 4547 \subsec{Col$(x, \{n\})$}\kbdsidx{Col}\label{se:Col}
 4548 Transforms the object $x$ into a column vector. The dimension of the
 4549 resulting vector can be optionally specified via the extra parameter $n$.
 4550 
 4551 If $n$ is omitted or $0$, the dimension depends on the type of $x$; the
 4552 vector has a single component, except when $x$ is
 4553 
 4554 \item a vector or a quadratic form (in which case the resulting vector
 4555 is simply the initial object considered as a row vector),
 4556 
 4557 \item a polynomial or a power series. In the case of a polynomial, the
 4558 coefficients of the vector start with the leading coefficient of the
 4559 polynomial, while for power series only the significant coefficients are
 4560 taken into account, but this time by increasing order of degree.
 4561 In this last case, \kbd{Vec} is the reciprocal function of \kbd{Pol} and
 4562 \kbd{Ser} respectively,
 4563 
 4564 \item a matrix (the column of row vector comprising the matrix is returned),
 4565 
 4566 \item a character string (a vector of individual characters is returned).
 4567 
 4568 In the last two cases (matrix and character string), $n$ is meaningless and
 4569 must be omitted or an error is raised. Otherwise, if $n$ is given, $0$
 4570 entries are appended at the end of the vector if $n > 0$, and prepended at
 4571 the beginning if $n < 0$. The dimension of the resulting vector is $|n|$.
 4572 
 4573 See ??Vec for examples.
 4574 
 4575 The library syntax is \fun{GEN}{gtocol0}{GEN x, long n}.
 4576 \fun{GEN}{gtocol}{GEN x} is also available.
 4577 
 4578 \subsec{Colrev$(x, \{n\})$}\kbdsidx{Colrev}\label{se:Colrev}
 4579 As $\kbd{Col}(x, -n)$, then reverse the result. In particular,
 4580 \kbd{Colrev} is the reciprocal function of \kbd{Polrev}: the
 4581 coefficients of the vector start with the constant coefficient of the
 4582 polynomial and the others follow by increasing degree.
 4583 
 4584 The library syntax is \fun{GEN}{gtocolrev0}{GEN x, long n}.
 4585 \fun{GEN}{gtocolrev}{GEN x} is also available.
 4586 
 4587 \subsec{List$(\{x=[\,]\})$}\kbdsidx{List}\label{se:List}
 4588 Transforms a (row or column) vector $x$ into a list, whose components are
 4589 the entries of $x$. Similarly for a list, but rather useless in this case.
 4590 For other types, creates a list with the single element $x$.
 4591 
 4592 The library syntax is \fun{GEN}{gtolist}{GEN x = NULL}.
 4593 The variant \fun{GEN}{mklist}{void} creates an empty list.
 4594 
 4595 \subsec{Map$(\{x\})$}\kbdsidx{Map}\label{se:Map}
 4596 A ``Map'' is an associative array, or dictionary: a data
 4597 type composed of a collection of (\emph{key}, \emph{value}) pairs, such that
 4598 each key appears just once in the collection. This function
 4599 converts the matrix $[a_1,b_1;a_2,b_2;\dots;a_n,b_n]$ to the map $a_i\mapsto
 4600 b_i$.
 4601 \bprog
 4602 ? M = Map(factor(13!));
 4603 ? mapget(M,3)
 4604 %2 = 5
 4605 @eprog\noindent If the argument $x$ is omitted, creates an empty map, which
 4606 may be filled later via \tet{mapput}.
 4607 
 4608 The library syntax is \fun{GEN}{gtomap}{GEN x = NULL}.
 4609 
 4610 \subsec{Mat$(\{x=[\,]\})$}\kbdsidx{Mat}\label{se:Mat}
 4611 Transforms the object $x$ into a matrix.
 4612 If $x$ is already a matrix, a copy of $x$ is created.
 4613 If $x$ is a row (resp. column) vector, this creates a 1-row (resp.
 4614 1-column) matrix, \emph{unless} all elements are column (resp.~row) vectors
 4615 of the same length, in which case the vectors are concatenated sideways
 4616 and the attached big matrix is returned.
 4617 If $x$ is a binary quadratic form, creates the attached $2\times 2$
 4618 matrix. Otherwise, this creates a $1\times 1$ matrix containing $x$.
 4619 
 4620 \bprog
 4621 ? Mat(x + 1)
 4622 %1 =
 4623 [x + 1]
 4624 ? Vec( matid(3) )
 4625 %2 = [[1, 0, 0]~, [0, 1, 0]~, [0, 0, 1]~]
 4626 ? Mat(%)
 4627 %3 =
 4628 [1 0 0]
 4629 
 4630 [0 1 0]
 4631 
 4632 [0 0 1]
 4633 ? Col( [1,2; 3,4] )
 4634 %4 = [[1, 2], [3, 4]]~
 4635 ? Mat(%)
 4636 %5 =
 4637 [1 2]
 4638 
 4639 [3 4]
 4640 ? Mat(Qfb(1,2,3))
 4641 %6 =
 4642 [1 1]
 4643 
 4644 [1 3]
 4645 @eprog
 4646 
 4647 The library syntax is \fun{GEN}{gtomat}{GEN x = NULL}.
 4648 
 4649 \subsec{Mod$(a,b)$}\kbdsidx{Mod}\label{se:Mod}
 4650 In its basic form, create an intmod or a polmod $(a \mod b)$; $b$ must
 4651 be an integer or a polynomial. We then obtain a \typ{INTMOD} and a
 4652 \typ{POLMOD} respectively:
 4653 \bprog
 4654 ? t = Mod(2,17); t^8
 4655 %1 = Mod(1, 17)
 4656 ? t = Mod(x,x^2+1); t^2
 4657 %2 = Mod(-1, x^2+1)
 4658 @eprog\noindent If $a \% b$ makes sense and yields a result of the
 4659 appropriate type (\typ{INT} or scalar/\typ{POL}), the operation succeeds as
 4660 well:
 4661 \bprog
 4662 ? Mod(1/2, 5)
 4663 %3 = Mod(3, 5)
 4664 ? Mod(7 + O(3^6), 3)
 4665 %4 = Mod(1, 3)
 4666 ? Mod(Mod(1,12), 9)
 4667 %5 = Mod(1, 3)
 4668 ? Mod(1/x, x^2+1)
 4669 %6 = Mod(-x, x^2+1)
 4670 ? Mod(exp(x), x^4)
 4671 %7 = Mod(1/6*x^3 + 1/2*x^2 + x + 1, x^4)
 4672 @eprog
 4673 If $a$ is a complex object, ``base change'' it to $\Z/b\Z$ or $K[x]/(b)$,
 4674 which is equivalent to, but faster than, multiplying it by \kbd{Mod(1,b)}:
 4675 \bprog
 4676 ? Mod([1,2;3,4], 2)
 4677 %8 =
 4678 [Mod(1, 2) Mod(0, 2)]
 4679 
 4680 [Mod(1, 2) Mod(0, 2)]
 4681 ? Mod(3*x+5, 2)
 4682 %9 = Mod(1, 2)*x + Mod(1, 2)
 4683 ? Mod(x^2 + y*x + y^3, y^2+1)
 4684 %10 = Mod(1, y^2 + 1)*x^2 + Mod(y, y^2 + 1)*x + Mod(-y, y^2 + 1)
 4685 @eprog
 4686 
 4687 This function is not the same as $x$ \kbd{\%} $y$, the result of which
 4688 has no knowledge of the intended modulus $y$. Compare
 4689 \bprog
 4690 ? x = 4 % 5; x + 1
 4691 %11 = 5
 4692 ? x = Mod(4,5); x + 1
 4693 %12 = Mod(0,5)
 4694 @eprog Note that such ``modular'' objects can be lifted via \tet{lift} or
 4695 \tet{centerlift}. The modulus of a \typ{INTMOD} or \typ{POLMOD} $z$ can
 4696 be recovered via \kbd{$z$.mod}.
 4697 
 4698 The library syntax is \fun{GEN}{gmodulo}{GEN a, GEN b}.
 4699 
 4700 \subsec{Pol$(t,\{v='x\})$}\kbdsidx{Pol}\label{se:Pol}
 4701 Transforms the object $t$ into a polynomial with main variable $v$. If $t$
 4702 is a scalar, this gives a constant polynomial. If $t$ is a power series with
 4703 nonnegative valuation or a rational function, the effect is similar to
 4704 \kbd{truncate}, i.e.~we chop off the $O(X^k)$ or compute the Euclidean
 4705 quotient of the numerator by the denominator, then change the main variable
 4706 of the result to $v$.
 4707 
 4708 The main use of this function is when $t$ is a vector: it creates the
 4709 polynomial whose coefficients are given by $t$, with $t[1]$ being the leading
 4710 coefficient (which can be zero). It is much faster to evaluate
 4711 \kbd{Pol} on a vector of coefficients in this way, than the corresponding
 4712 formal expression $a_n X^n + \dots + a_0$, which is evaluated naively exactly
 4713 as written (linear versus quadratic time in $n$). \tet{Polrev} can be used if
 4714 one wants $x[1]$ to be the constant coefficient:
 4715 \bprog
 4716 ? Pol([1,2,3])
 4717 %1 = x^2 + 2*x + 3
 4718 ? Polrev([1,2,3])
 4719 %2 = 3*x^2 + 2*x + 1
 4720 @eprog\noindent
 4721 The reciprocal function of \kbd{Pol} (resp.~\kbd{Polrev}) is \kbd{Vec} (resp.~
 4722 \kbd{Vecrev}).
 4723 \bprog
 4724 ? Vec(Pol([1,2,3]))
 4725 %1 = [1, 2, 3]
 4726 ? Vecrev( Polrev([1,2,3]) )
 4727 %2 = [1, 2, 3]
 4728 @eprog\noindent
 4729 
 4730 \misctitle{Warning} This is \emph{not} a substitution function. It will not
 4731 transform an object containing variables of higher priority than~$v$.
 4732 \bprog
 4733 ? Pol(x + y, y)
 4734   ***   at top-level: Pol(x+y,y)
 4735   ***                 ^----------
 4736   *** Pol: variable must have higher priority in gtopoly.
 4737 @eprog
 4738 
 4739 The library syntax is \fun{GEN}{gtopoly}{GEN t, long v = -1} where \kbd{v} is a variable number.
 4740 
 4741 \subsec{Polrev$(t,\{v='x\})$}\kbdsidx{Polrev}\label{se:Polrev}
 4742 Transform the object $t$ into a polynomial
 4743 with main variable $v$. If $t$ is a scalar, this gives a constant polynomial.
 4744 If $t$ is a power series, the effect is identical to \kbd{truncate}, i.e.~it
 4745 chops off the $O(X^k)$.
 4746 
 4747 The main use of this function is when $t$ is a vector: it creates the
 4748 polynomial whose coefficients are given by $t$, with $t[1]$ being the
 4749 constant term. \tet{Pol} can be used if one wants $t[1]$ to be the leading
 4750 coefficient:
 4751 \bprog
 4752 ? Polrev([1,2,3])
 4753 %1 = 3*x^2 + 2*x + 1
 4754 ? Pol([1,2,3])
 4755 %2 = x^2 + 2*x + 3
 4756 @eprog
 4757 The reciprocal function of \kbd{Pol} (resp.~\kbd{Polrev}) is \kbd{Vec} (resp.~
 4758 \kbd{Vecrev}).
 4759 
 4760 The library syntax is \fun{GEN}{gtopolyrev}{GEN t, long v = -1} where \kbd{v} is a variable number.
 4761 
 4762 \subsec{Qfb$(a,b,c,\{D=0.\})$}\kbdsidx{Qfb}\label{se:Qfb}
 4763 Creates the binary quadratic form\sidx{binary quadratic form}
 4764 $ax^2+bxy+cy^2$. If $b^2-4ac>0$, initialize \idx{Shanks}' distance
 4765 function to $D$. Negative definite forms are not implemented,
 4766 use their positive definite counterpart instead.
 4767 
 4768 The library syntax is \fun{GEN}{Qfb0}{GEN a, GEN b, GEN c, GEN D = NULL, long prec}.
 4769 Also available are
 4770 \fun{GEN}{qfi}{GEN a, GEN b, GEN c} (assumes $b^2-4ac<0$) and
 4771 \fun{GEN}{qfr}{GEN a, GEN b, GEN c, GEN D} (assumes $b^2-4ac>0$).
 4772 
 4773 \subsec{Ser$(s,\{v='x\},\{d=\var{seriesprecision}\})$}\kbdsidx{Ser}\label{se:Ser}
 4774 Transforms the object $s$ into a power series with main variable $v$
 4775 ($x$ by default) and precision (number of significant terms) equal to
 4776 $d \geq 0$ ($d = \kbd{seriesprecision}$ by default). If $s$ is a
 4777 scalar, this gives a constant power series in $v$ with precision \kbd{d}.
 4778 If $s$ is a polynomial, the polynomial is truncated to $d$ terms if needed
 4779 \bprog
 4780 ? \ps
 4781   seriesprecision = 16 significant terms
 4782 ? Ser(1)  \\ 16 terms by default
 4783 %1 = 1 + O(x^16)
 4784 ? Ser(1, 'y, 5)
 4785 %2 = 1 + O(y^5)
 4786 ? Ser(x^2,, 5)
 4787 %3 = x^2 + O(x^7)
 4788 ? T = polcyclo(100)
 4789 %4 = x^40 - x^30 + x^20 - x^10 + 1
 4790 ? Ser(T, 'x, 11)
 4791 %5 = 1 - x^10 + O(x^11)
 4792 @eprog\noindent The function is more or less equivalent with multiplication by
 4793 $1 + O(v^d)$ in theses cases, only faster.
 4794 
 4795 For the remaining types, vectors and power series, we first explain what
 4796 occurs if $d$ is omitted. In this case, the function uses exactly the amount
 4797 of information given in the input:
 4798 
 4799 \item If $s$ is already a power series in $v$, we return it verbatim;
 4800 
 4801 \item If $s$ is a vector, the coefficients of the vector are
 4802 understood to be the coefficients of the power series starting from the
 4803 constant term (as in \tet{Polrev}$(x)$); in other words we convert
 4804 \typ{VEC} / \typ{COL} to the power series whose significant terms are exactly
 4805 given by the vector entries.
 4806 
 4807 On the other hand, if $d$ is explicitly given, we abide by its value
 4808 and return a series, truncated or extended with zeros as needed, with
 4809 $d$ significant terms.
 4810 
 4811 \bprog
 4812 ? v = [1,2,3];
 4813 ? Ser(v, t) \\ 3 terms: seriesprecision is ignored!
 4814 %7 = 1 + 2*t + 3*t^2 + O(t^3)
 4815 ? Ser(v, t, 7)  \\ 7 terms as explicitly requested
 4816 %8 = 1 + 2*t + 3*t^2 + O(t^7)
 4817 ? s = 1+x+O(x^2);
 4818 ? Ser(s)
 4819 %10 = 1 + x + O(x^2)  \\ 2 terms: seriesprecision is ignored
 4820 ? Ser(s, x, 7)  \\ extend to 7 terms
 4821 %11 = 1 + x + O(x^7)
 4822 ? Ser(s, x, 1)  \\ truncate to 1 term
 4823 %12 = 1 + O(x)
 4824 @eprog\noindent
 4825 The warning given for \kbd{Pol} also applies here: this is not a substitution
 4826 function.
 4827 
 4828 The library syntax is \fun{GEN}{Ser0}{GEN s, long v = -1, GEN d = NULL, long precdl} where \kbd{v} is a variable number.
 4829 
 4830 \subsec{Set$(\{x=[\,]\})$}\kbdsidx{Set}\label{se:Set}
 4831 Converts $x$ into a set, i.e.~into a row vector, with strictly increasing
 4832 entries with respect to the (somewhat arbitrary) universal comparison function
 4833 \tet{cmp}. Standard container types \typ{VEC}, \typ{COL}, \typ{LIST} and
 4834 \typ{VECSMALL} are converted to the set with corresponding elements. All
 4835 others are converted to a set with one element.
 4836 \bprog
 4837 ? Set([1,2,4,2,1,3])
 4838 %1 = [1, 2, 3, 4]
 4839 ? Set(x)
 4840 %2 = [x]
 4841 ? Set(Vecsmall([1,3,2,1,3]))
 4842 %3 = [1, 2, 3]
 4843 @eprog
 4844 
 4845 The library syntax is \fun{GEN}{gtoset}{GEN x = NULL}.
 4846 
 4847 \subsec{Str$(\{x\}*)$}\kbdsidx{Str}\label{se:Str}
 4848 Converts its argument list into a
 4849 single character string (type \typ{STR}, the empty string if $x$ is omitted).
 4850 To recover an ordinary \kbd{GEN} from a string, apply \kbd{eval} to it. The
 4851 arguments of \kbd{Str} are evaluated in string context, see \secref{se:strings}.
 4852 
 4853 \bprog
 4854 ? x2 = 0; i = 2; Str(x, i)
 4855 %1 = "x2"
 4856 ? eval(%)
 4857 %2 = 0
 4858 @eprog\noindent
 4859 This function is mostly useless in library mode. Use the pair
 4860 \tet{strtoGEN}/\tet{GENtostr} to convert between \kbd{GEN} and \kbd{char*}.
 4861 The latter returns a malloced string, which should be freed after usage.
 4862 %\syn{NO}
 4863 
 4864 \subsec{Vec$(x, \{n\})$}\kbdsidx{Vec}\label{se:Vec}
 4865 Transforms the object $x$ into a row vector. The dimension of the
 4866 resulting vector can be optionally specified via the extra parameter $n$.
 4867 If $n$ is omitted or $0$, the dimension depends on the type of $x$; the
 4868 vector has a single component, except when $x$ is
 4869 
 4870 \item a vector or a quadratic form: returns the initial object considered as a
 4871 row vector,
 4872 
 4873 \item a polynomial or a power series: returns a vector consisting of the
 4874 coefficients. In the case of a polynomial, the coefficients of the vector
 4875 start with the leading coefficient of the polynomial, while for power series
 4876 only the significant coefficients are taken into account, but this time by
 4877 increasing order of degree. In particular the valuation is ignored
 4878 (which makes the function useful for series of negative valuation):
 4879 \bprog
 4880 ? Vec(3*x^2 + x)
 4881 %1 = [3, 1, 0]
 4882 ? Vec(x^2 + 3*x^3 + O(x^5))
 4883 %2 = [1, 3, 0]
 4884 ? Vec(x^-2 + 3*x^-1 + O(x))
 4885 %3 = [1, 3, 0]
 4886 @eprog\noindent \kbd{Vec} is the reciprocal function of \kbd{Pol} for a
 4887 polynomial and of \kbd{Ser} for power series of valuation $0$.
 4888 
 4889 \item a matrix: returns the vector of columns comprising the matrix,
 4890 \bprog
 4891 ? m = [1,2,3;4,5,6]
 4892 %4 =
 4893 [1 2 3]
 4894 
 4895 [4 5 6]
 4896 ? Vec(m)
 4897 %5 = [[1, 4]~, [2, 5]~, [3, 6]~]
 4898 @eprog
 4899 
 4900 \item a character string: returns the vector of individual characters,
 4901 \bprog
 4902 ? Vec("PARI")
 4903 %6 = ["P", "A", "R", "I"]
 4904 @eprog
 4905 
 4906 \item a map: returns the vector of the domain of the map,
 4907 
 4908 \item an error context (\typ{ERROR}): returns the error components, see
 4909 \tet{iferr}.
 4910 
 4911 In the last four cases (matrix, character string, map, error), $n$ is
 4912 meaningless and must be omitted or an error is raised. Otherwise, if $n$ is
 4913 given, $0$ entries are appended at the end of the vector if $n > 0$, and
 4914 prepended at the beginning if $n < 0$. The dimension of the resulting vector
 4915 is $|n|$. This allows to write a conversion function for series that
 4916 takes positive valuations into account:
 4917 \bprog
 4918 ? serVec(s) = Vec(s, -serprec(s,variable(s)));
 4919 ? Vec(x^2 + 3*x^3 + O(x^5))
 4920 %2 = [0, 0, 1, 3, 0]
 4921 @eprog (That function is not intended for series of negative valuation.)
 4922 
 4923 The library syntax is \fun{GEN}{gtovec0}{GEN x, long n}.
 4924 \fun{GEN}{gtovec}{GEN x} is also available.
 4925 
 4926 \subsec{Vecrev$(x, \{n\})$}\kbdsidx{Vecrev}\label{se:Vecrev}
 4927 As $\kbd{Vec}(x, -n)$, then reverse the result. In particular,
 4928 \kbd{Vecrev} is the reciprocal function of \kbd{Polrev}: the
 4929 coefficients of the vector start with the constant coefficient of the
 4930 polynomial and the others follow by increasing degree.
 4931 
 4932 The library syntax is \fun{GEN}{gtovecrev0}{GEN x, long n}.
 4933 \fun{GEN}{gtovecrev}{GEN x} is also available.
 4934 
 4935 \subsec{Vecsmall$(x, \{n\})$}\kbdsidx{Vecsmall}\label{se:Vecsmall}
 4936 Transforms the object $x$ into a row vector of type \typ{VECSMALL}. The
 4937 dimension of the resulting vector can be optionally specified via the extra
 4938 parameter $n$.
 4939 
 4940 This acts as \kbd{Vec}$(x,n)$, but only on a limited set of objects:
 4941 the result must be representable as a vector of small integers.
 4942 If $x$ is a character string, a vector of individual characters in ASCII
 4943 encoding is returned (\tet{strchr} yields back the character string).
 4944 
 4945 The library syntax is \fun{GEN}{gtovecsmall0}{GEN x, long n}.
 4946 \fun{GEN}{gtovecsmall}{GEN x} is also available.
 4947 
 4948 \subsec{binary$(x)$}\kbdsidx{binary}\label{se:binary}
 4949 Outputs the vector of the binary digits of $|x|$. Here $x$ can be an
 4950 integer, a real number (in which case the result has two components, one for
 4951 the integer part, one for the fractional part) or a vector/matrix.
 4952 \bprog
 4953 ? binary(10)
 4954 %1 = [1, 0, 1, 0]
 4955 
 4956 ? binary(3.14)
 4957 %2 = [[1, 1], [0, 0, 1, 0, 0, 0, [...]]
 4958 
 4959 ? binary([1,2])
 4960 %3 = [[1], [1, 0]]
 4961 @eprog\noindent For integer $x\ge1$, the number of bits is
 4962 $\kbd{logint}(x,2) + 1$. By convention, $0$ has no digits:
 4963 \bprog
 4964 ? binary(0)
 4965 %4 = []
 4966 @eprog
 4967 
 4968 The library syntax is \fun{GEN}{binaire}{GEN x}.
 4969 
 4970 \subsec{bitand$(x,y)$}\kbdsidx{bitand}\label{se:bitand}
 4971 Bitwise \tet{and}
 4972 \sidx{bitwise and}of two integers $x$ and $y$, that is the integer
 4973 $$\sum_i (x_i~\kbd{and}~y_i) 2^i$$
 4974 
 4975 Negative numbers behave $2$-adically, i.e.~the result is the $2$-adic limit
 4976 of \kbd{bitand}$(x_n,y_n)$, where $x_n$ and $y_n$ are nonnegative integers
 4977 tending to $x$ and $y$ respectively. (The result is an ordinary integer,
 4978 possibly negative.)
 4979 
 4980 \bprog
 4981 ? bitand(5, 3)
 4982 %1 = 1
 4983 ? bitand(-5, 3)
 4984 %2 = 3
 4985 ? bitand(-5, -3)
 4986 %3 = -7
 4987 @eprog
 4988 
 4989 The library syntax is \fun{GEN}{gbitand}{GEN x, GEN y}.
 4990 Also available is
 4991 \fun{GEN}{ibitand}{GEN x, GEN y}, which returns the bitwise \emph{and}
 4992 of $|x|$ and $|y|$, two integers.
 4993 
 4994 \subsec{bitneg$(x,\{n=-1\})$}\kbdsidx{bitneg}\label{se:bitneg}
 4995 \idx{bitwise negation} of an integer $x$,
 4996 truncated to $n$ bits, $n\geq 0$, that is the integer
 4997 $$\sum_{i=0}^{n-1} \kbd{not}(x_i) 2^i.$$
 4998 The special case $n=-1$ means no truncation: an infinite sequence of
 4999 leading $1$ is then represented as a negative number.
 5000 
 5001 See \secref{se:bitand} for the behavior for negative arguments.
 5002 
 5003 The library syntax is \fun{GEN}{gbitneg}{GEN x, long n}.
 5004 
 5005 \subsec{bitnegimply$(x,y)$}\kbdsidx{bitnegimply}\label{se:bitnegimply}
 5006 Bitwise negated imply of two integers $x$ and
 5007 $y$ (or \kbd{not} $(x \Rightarrow y)$), that is the integer $$\sum
 5008 (x_i~\kbd{and not}(y_i)) 2^i$$
 5009 
 5010 See \secref{se:bitand} for the behavior for negative arguments.
 5011 
 5012 The library syntax is \fun{GEN}{gbitnegimply}{GEN x, GEN y}.
 5013 Also available is
 5014 \fun{GEN}{ibitnegimply}{GEN x, GEN y}, which returns the bitwise negated
 5015 imply of $|x|$ and $|y|$, two integers.
 5016 
 5017 \subsec{bitor$(x,y)$}\kbdsidx{bitor}\label{se:bitor}
 5018 \sidx{bitwise inclusive or}bitwise (inclusive)
 5019 \tet{or} of two integers $x$ and $y$, that is the integer $$\sum
 5020 (x_i~\kbd{or}~y_i) 2^i$$
 5021 
 5022 See \secref{se:bitand} for the behavior for negative arguments.
 5023 
 5024 The library syntax is \fun{GEN}{gbitor}{GEN x, GEN y}.
 5025 Also available is
 5026 \fun{GEN}{ibitor}{GEN x, GEN y}, which returns the bitwise \emph{or}
 5027 of $|x|$ and $|y|$, two integers.
 5028 
 5029 \subsec{bitprecision$(x,\{n\})$}\kbdsidx{bitprecision}\label{se:bitprecision}
 5030 The function behaves differently according to whether $n$ is
 5031 present or not. If $n$ is missing, the function returns
 5032 the (floating point) precision in bits of the PARI object $x$.
 5033 
 5034 If $x$ is an exact object, the function returns \kbd{+oo}.
 5035 \bprog
 5036 ? bitprecision(exp(1e-100))
 5037 %1 = 512                 \\ 512 bits
 5038 ? bitprecision( [ exp(1e-100), 0.5 ] )
 5039 %2 = 128                 \\ minimal accuracy among components
 5040 ? bitprecision(2 + x)
 5041 %3 = +oo                  \\ exact object
 5042 @eprog\noindent Use \kbd{getlocalbitprec()} to retrieve the
 5043 working bit precision (as modified by possible \kbd{localbitprec}
 5044 statements).
 5045 
 5046 If $n$ is present and positive, the function creates a new object equal to $x$
 5047 with the new bit-precision roughly $n$. In fact, the smallest multiple of 64
 5048 (resp.~32 on a 32-bit machine) larger than or equal to $n$.
 5049 
 5050 For $x$ a vector or a matrix, the operation is
 5051 done componentwise; for series and polynomials, the operation is done
 5052 coefficientwise. For real $x$, $n$ is the number of desired significant
 5053 \emph{bits}. If $n$ is smaller than the precision of $x$, $x$ is truncated,
 5054 otherwise $x$ is extended with zeros. For exact or non-floating-point types,
 5055 no change.
 5056 \bprog
 5057 ? bitprecision(Pi, 10)    \\ actually 64 bits ~ 19 decimal digits
 5058 %1 = 3.141592653589793239
 5059 ? bitprecision(1, 10)
 5060 %2 = 1
 5061 ? bitprecision(1 + O(x), 10)
 5062 %3 = 1 + O(x)
 5063 ? bitprecision(2 + O(3^5), 10)
 5064 %4 = 2 + O(3^5)
 5065 @eprog\noindent
 5066 
 5067 The library syntax is \fun{GEN}{bitprecision00}{GEN x, GEN n = NULL}.
 5068 
 5069 \subsec{bittest$(x,n)$}\kbdsidx{bittest}\label{se:bittest}
 5070 Outputs the $n^{\text{th}}$ bit of $x$ starting
 5071 from the right (i.e.~the coefficient of $2^n$ in the binary expansion of $x$).
 5072 The result is 0 or 1. For $x\ge1$, the highest 1-bit is at $n =
 5073 \kbd{logint}(x)$ (and bigger $n$ gives $0$).
 5074 \bprog
 5075 ? bittest(7, 0)
 5076 %1 = 1 \\ the bit 0 is 1
 5077 ? bittest(7, 2)
 5078 %2 = 1 \\ the bit 2 is 1
 5079 ? bittest(7, 3)
 5080 %3 = 0 \\ the bit 3 is 0
 5081 @eprog\noindent
 5082 See \secref{se:bitand} for the behavior at negative arguments.
 5083 
 5084 The library syntax is \fun{GEN}{gbittest}{GEN x, long n}.
 5085 For a \typ{INT} $x$, the variant \fun{long}{bittest}{GEN x, long n} is
 5086 generally easier to use, and if furthermore $n\ge 0$ the low-level function
 5087 \fun{ulong}{int_bit}{GEN x, long n} returns \kbd{bittest(abs(x),n)}.
 5088 
 5089 \subsec{bitxor$(x,y)$}\kbdsidx{bitxor}\label{se:bitxor}
 5090 Bitwise (exclusive) \tet{or}
 5091 \sidx{bitwise exclusive or}of two integers $x$ and $y$, that is the integer
 5092 $$\sum (x_i~\kbd{xor}~y_i) 2^i$$
 5093 
 5094 See \secref{se:bitand} for the behavior for negative arguments.
 5095 
 5096 The library syntax is \fun{GEN}{gbitxor}{GEN x, GEN y}.
 5097 Also available is
 5098 \fun{GEN}{ibitxor}{GEN x, GEN y}, which returns the bitwise \emph{xor}
 5099 of $|x|$ and $|y|$, two integers.
 5100 
 5101 \subsec{ceil$(x)$}\kbdsidx{ceil}\label{se:ceil}
 5102 Ceiling of $x$. When $x$ is in $\R$, the result is the
 5103 smallest integer greater than or equal to $x$. Applied to a rational
 5104 function, $\kbd{ceil}(x)$ returns the Euclidean quotient of the numerator by
 5105 the denominator.
 5106 
 5107 The library syntax is \fun{GEN}{gceil}{GEN x}.
 5108 
 5109 \subsec{centerlift$(x,\{v\})$}\kbdsidx{centerlift}\label{se:centerlift}
 5110 Same as \tet{lift}, except that \typ{INTMOD} and \typ{PADIC} components
 5111 are lifted using centered residues:
 5112 
 5113 \item for a \typ{INTMOD} $x\in \Z/n\Z$, the lift $y$ is such that
 5114 $-n/2<y\le n/2$.
 5115 
 5116 \item  a \typ{PADIC} $x$ is lifted in the same way as above (modulo
 5117 $p^\kbd{padicprec(x)}$) if its valuation $v$ is nonnegative; if not, returns
 5118 the fraction $p^v$ \kbd{centerlift}$(x p^{-v})$; in particular, rational
 5119 reconstruction is not attempted. Use \tet{bestappr} for this.
 5120 
 5121 For backward compatibility, \kbd{centerlift(x,'v)} is allowed as an alias
 5122 for \kbd{lift(x,'v)}.
 5123 
 5124 \synt{centerlift}{GEN x}.
 5125 
 5126 \subsec{characteristic$(x)$}\kbdsidx{characteristic}\label{se:characteristic}
 5127 Returns the characteristic of the base ring over which $x$ is defined (as
 5128 defined by \typ{INTMOD} and \typ{FFELT} components). The function raises an
 5129 exception if incompatible primes arise from \typ{FFELT} and \typ{PADIC}
 5130 components.
 5131 \bprog
 5132 ? characteristic(Mod(1,24)*x + Mod(1,18)*y)
 5133 %1 = 6
 5134 @eprog
 5135 
 5136 The library syntax is \fun{GEN}{characteristic}{GEN x}.
 5137 
 5138 \subsec{component$(x,n)$}\kbdsidx{component}\label{se:component}
 5139 Extracts the $n^{\text{th}}$-component of $x$. This is to be understood
 5140 as follows: every PARI type has one or two initial \idx{code words}. The
 5141 components are counted, starting at 1, after these code words. In particular
 5142 if $x$ is a vector, this is indeed the $n^{\text{th}}$-component of $x$, if
 5143 $x$ is a matrix, the $n^{\text{th}}$ column, if $x$ is a polynomial, the
 5144 $n^{\text{th}}$ coefficient (i.e.~of degree $n-1$), and for power series,
 5145 the $n^{\text{th}}$ significant coefficient.
 5146 
 5147 For polynomials and power series, one should rather use \tet{polcoeff}, and
 5148 for vectors and matrices, the \kbd{[$\,$]} operator. Namely, if $x$ is a
 5149 vector, then \tet{x[n]} represents the $n^{\text{th}}$ component of $x$. If
 5150 $x$ is a matrix, \tet{x[m,n]} represents the coefficient of row \kbd{m} and
 5151 column \kbd{n} of the matrix, \tet{x[m,]} represents the $m^{\text{th}}$
 5152 \emph{row} of $x$, and \tet{x[,n]} represents the $n^{\text{th}}$
 5153 \emph{column} of $x$.
 5154 
 5155 Using of this function requires detailed knowledge of the structure of the
 5156 different PARI types, and thus it should almost never be used directly.
 5157 Some useful exceptions:
 5158 \bprog
 5159     ? x = 3 + O(3^5);
 5160     ? component(x, 2)
 5161     %2 = 81   \\ p^(p-adic accuracy)
 5162     ? component(x, 1)
 5163     %3 = 3    \\ p
 5164     ? q = Qfb(1,2,3);
 5165     ? component(q, 1)
 5166     %5 = 1
 5167 @eprog
 5168 
 5169 The library syntax is \fun{GEN}{compo}{GEN x, long n}.
 5170 
 5171 \subsec{conj$(x)$}\kbdsidx{conj}\label{se:conj}
 5172 Conjugate of $x$. The meaning of this
 5173 is clear, except that for real quadratic numbers, it means conjugation in the
 5174 real quadratic field. This function has no effect on integers, reals,
 5175 intmods, fractions or $p$-adics. The only forbidden type is polmod
 5176 (see \kbd{conjvec} for this).
 5177 
 5178 The library syntax is \fun{GEN}{gconj}{GEN x}.
 5179 
 5180 \subsec{conjvec$(z)$}\kbdsidx{conjvec}\label{se:conjvec}
 5181 Conjugate vector representation of $z$. If $z$ is a
 5182 polmod, equal to \kbd{Mod}$(a,T)$, this gives a vector of length
 5183 $\text{degree}(T)$ containing:
 5184 
 5185 \item the complex embeddings of $z$ if $T$ has rational coefficients,
 5186 i.e.~the $a(r[i])$ where $r = \kbd{polroots}(T)$;
 5187 
 5188 \item the conjugates of $z$ if $T$ has some intmod coefficients;
 5189 
 5190 \noindent if $z$ is a finite field element, the result is the vector of
 5191 conjugates $[z,z^p,z^{p^2},\ldots,z^{p^{n-1}}]$ where $n=\text{degree}(T)$.
 5192 
 5193 \noindent If $z$ is an integer or a rational number, the result is~$z$. If
 5194 $z$ is a (row or column) vector, the result is a matrix whose columns are
 5195 the conjugate vectors of the individual elements of $z$.
 5196 
 5197 The library syntax is \fun{GEN}{conjvec}{GEN z, long prec}.
 5198 
 5199 \subsec{denominator$(f,\{D\})$}\kbdsidx{denominator}\label{se:denominator}
 5200 Denominator of $f$. The meaning of this is clear when $f$ is a rational number
 5201 or function. If $f$ is an integer or a polynomial, it is treated as a rational
 5202 number or function, respectively, and the result is equal to $1$. For
 5203 polynomials, you probably want to use
 5204 \bprog
 5205 denominator( content(f) )
 5206 @eprog\noindent instead. As for modular objects, \typ{INTMOD} and \typ{PADIC}
 5207 have denominator $1$, and the denominator of a \typ{POLMOD} is the
 5208 denominator of its lift.
 5209 
 5210 If $f$ is a recursive structure, for instance a vector or matrix, the lcm
 5211 of the denominators of its components (a common denominator) is computed.
 5212 This also applies for \typ{COMPLEX}s and \typ{QUAD}s.
 5213 
 5214 \misctitle{Warning} Multivariate objects are created according to variable
 5215 priorities, with possibly surprising side effects ($x/y$ is a polynomial, but
 5216 $y/x$ is a rational function). See \secref{se:priority}.
 5217 
 5218 The optional argument $D$ allows to control over which ring we compute the
 5219 denominator and get a more predictable behaviour:
 5220 
 5221 \item $1$: we only consider the underlying $\Q$-structure and the
 5222 denominator is a (positive) rational integer
 5223 
 5224 \item a simple variable, say \kbd{'x}: all entries as rational functions
 5225 in $K(x)$ and the denominator is a polynomial in $x$.
 5226 
 5227 \bprog
 5228 ? f = x + 1/y + 1/2;
 5229 ? denominator(f) \\ a t_POL in x
 5230 %2 = 1
 5231 ? denominator(f, 1) \\ Q-denominator
 5232 %3 = 2
 5233 ? denominator(f, x) \\ as a t_POL in x, seen above
 5234 %4 = 1
 5235 ? denominator(f, y) \\ as a rational function in y
 5236 %5 = 2*y
 5237 @eprog
 5238 
 5239 The library syntax is \fun{GEN}{denominator}{GEN f, GEN D = NULL}.
 5240 Also available are
 5241 \fun{GEN}{denom}{GEN x}  which implements the not very useful default
 5242 behaviour ($D$ is \kbd{NULL}) and \fun{GEN}{Q_denom}{GEN x} ($D = 1$).
 5243 
 5244 \subsec{digits$(x,\{b=10\})$}\kbdsidx{digits}\label{se:digits}
 5245 Outputs the vector of the digits of $|x|$ in base $b$, where $x$ and $b$ are
 5246 integers ($b = 10$ by default). For $x\ge1$, the number of digits is
 5247 $\kbd{logint}(x,b) + 1$. See \kbd{fromdigits} for the reverse operation.
 5248 \bprog
 5249 ? digits(1230)
 5250 %1 = [1, 2, 3, 0]
 5251 
 5252 ? digits(10, 2) \\ base 2
 5253 %2 = [1, 0, 1, 0]
 5254 @eprog\noindent By convention, $0$ has no digits:
 5255 \bprog
 5256 ? digits(0)
 5257 %3 = []
 5258 @eprog
 5259 
 5260 The library syntax is \fun{GEN}{digits}{GEN x, GEN b = NULL}.
 5261 
 5262 \subsec{exponent$(x)$}\kbdsidx{exponent}\label{se:exponent}
 5263 When $x$ is a \typ{REAL}, the result is the binary exponent $e$ of $x$.
 5264 For a nonzero $x$, this is the unique integer $e$ such that
 5265 $2^e \leq |x| < 2^{e+1}$. For a real $0$, this returns the PARI exponent $e$
 5266 attached to $x$ (which may represent any floating-point number less than
 5267 $2^e$ in absolute value).
 5268 \bprog
 5269 ? exponent(Pi)
 5270 %1 = 1
 5271 ? exponent(4.0)
 5272 %2 = 2
 5273 ? exponent(0.0)
 5274 %3 = -128
 5275 ? default(realbitprecision)
 5276 %4 = 128
 5277 @eprog\noindent This definition extends naturally to nonzero integers,
 5278 and the exponent of an exact $0$ is $-\kbd{oo}$ by convention.
 5279 
 5280 For convenience, we \emph{define} the exponent of a \typ{FRAC} $a/b$ as
 5281 the difference of \kbd{exponent}$(a)$ and \kbd{exponent}$(b)$; note that,
 5282 if $e'$ denotes the exponent of \kbd{$a/b$ * 1.0}, then the exponent $e$
 5283 we return is either $e'$ or $e'+1$, thus $2^{e+1}$ is an upper bound for
 5284 $|a/b|$.
 5285 \bprog
 5286 ? [ exponent(9), exponent(10), exponent(9/10), exponent(9/10*1.) ]
 5287 %5 = [3, 3, 0, -1]
 5288 @eprog
 5289 
 5290 For a PARI object of type \typ{COMPLEX}, \typ{POL}, \typ{SER}, \typ{VEC},
 5291 \typ{COL}, \typ{MAT} this returns the largest exponent found among the
 5292 components of $x$. Hence $2^{e+1}$ is a quick upper bound for the sup norm
 5293 of real matrices or polynomials; and $2^{e+(3/2)}$ for complex ones.
 5294 
 5295 \bprog
 5296 ? exponent(3*x^2 + 15*x - 100)
 5297 %5 = 6
 5298 ? exponent(0)
 5299 %6 = -oo
 5300 @eprog
 5301 
 5302 The library syntax is \fun{GEN}{gpexponent}{GEN x}.
 5303 
 5304 \subsec{floor$(x)$}\kbdsidx{floor}\label{se:floor}
 5305 Floor of $x$. When $x$ is in $\R$, the result is the
 5306 largest integer smaller than or equal to $x$. Applied to a rational function,
 5307 $\kbd{floor}(x)$ returns the Euclidean quotient of the numerator by the
 5308 denominator.
 5309 
 5310 The library syntax is \fun{GEN}{gfloor}{GEN x}.
 5311 
 5312 \subsec{frac$(x)$}\kbdsidx{frac}\label{se:frac}
 5313 Fractional part of $x$. Identical to
 5314 $x-\text{floor}(x)$. If $x$ is real, the result is in $[0,1[$.
 5315 
 5316 The library syntax is \fun{GEN}{gfrac}{GEN x}.
 5317 
 5318 \subsec{fromdigits$(x,\{b=10\})$}\kbdsidx{fromdigits}\label{se:fromdigits}
 5319 Gives the integer formed by the elements of $x$ seen as the digits of a
 5320 number in base $b$ ($b = 10$ by default).  This is the reverse of \kbd{digits}:
 5321 \bprog
 5322 ? digits(1234,5)
 5323 %1 = [1,4,4,1,4]
 5324 ? fromdigits([1,4,4,1,4],5)
 5325 %2 = 1234
 5326 @eprog\noindent By convention, $0$ has no digits:
 5327 \bprog
 5328 ? fromdigits([])
 5329 %3 = 0
 5330 @eprog
 5331 
 5332 The library syntax is \fun{GEN}{fromdigits}{GEN x, GEN b = NULL}.
 5333 
 5334 \subsec{imag$(x)$}\kbdsidx{imag}\label{se:imag}
 5335 Imaginary part of $x$. When $x$ is a quadratic number, this is the
 5336 coefficient of $\omega$ in the ``canonical'' integral basis $(1,\omega)$.
 5337 \bprog
 5338 ? imag(3 + I)
 5339 %1 = 1
 5340 ? x = 3 + quadgen(-23);
 5341 ? imag(x) \\ as a quadratic number
 5342 %3 = 1
 5343 ? imag(x * 1.) \\ as a complex number
 5344 %4 = 2.3979157616563597707987190320813469600
 5345 @eprog
 5346 
 5347 The library syntax is \fun{GEN}{gimag}{GEN x}.
 5348 
 5349 \subsec{length$(x)$}\kbdsidx{length}\label{se:length}
 5350 Length of $x$; \kbd{\#}$x$ is a shortcut for \kbd{length}$(x)$.
 5351 This is mostly useful for
 5352 
 5353 \item vectors: dimension (0 for empty vectors),
 5354 
 5355 \item lists: number of entries (0 for empty lists),
 5356 
 5357 \item maps: number of entries (0 for empty maps),
 5358 
 5359 \item matrices: number of columns,
 5360 
 5361 \item character strings: number of actual characters (without
 5362 trailing \kbd{\bs 0}, should you expect it from $C$ \kbd{char*}).
 5363 \bprog
 5364  ? #"a string"
 5365  %1 = 8
 5366  ? #[3,2,1]
 5367  %2 = 3
 5368  ? #[]
 5369  %3 = 0
 5370  ? #matrix(2,5)
 5371  %4 = 5
 5372  ? L = List([1,2,3,4]); #L
 5373  %5 = 4
 5374  ? M = Map([a,b; c,d; e,f]); #M
 5375  %6 = 3
 5376 @eprog
 5377 
 5378 The routine is in fact defined for arbitrary GP types, but is awkward and
 5379 useless in other cases: it returns the number of non-code words in $x$, e.g.
 5380 the effective length minus 2 for integers since the \typ{INT} type has two code
 5381 words.
 5382 
 5383 The library syntax is \fun{long}{glength}{GEN x}.
 5384 
 5385 \subsec{lift$(x,\{v\})$}\kbdsidx{lift}\label{se:lift}
 5386 If $v$ is omitted, lifts intmods from $\Z/n\Z$ in $\Z$,
 5387 $p$-adics from $\Q_p$ to $\Q$ (as \tet{truncate}), and polmods to
 5388 polynomials. Otherwise, lifts only polmods whose modulus has main
 5389 variable~$v$. \typ{FFELT} are not lifted, nor are List elements: you may
 5390 convert the latter to vectors first, or use \kbd{apply(lift,L)}. More
 5391 generally, components for which such lifts are meaningless (e.g. character
 5392 strings) are copied verbatim.
 5393 \bprog
 5394 ? lift(Mod(5,3))
 5395 %1 = 2
 5396 ? lift(3 + O(3^9))
 5397 %2 = 3
 5398 ? lift(Mod(x,x^2+1))
 5399 %3 = x
 5400 ? lift(Mod(x,x^2+1))
 5401 %4 = x
 5402 @eprog
 5403 Lifts are performed recursively on an object components, but only
 5404 by \emph{one level}: once a \typ{POLMOD} is lifted, the components of
 5405 the result are \emph{not} lifted further.
 5406 \bprog
 5407 ? lift(x * Mod(1,3) + Mod(2,3))
 5408 %4 = x + 2
 5409 ? lift(x * Mod(y,y^2+1) + Mod(2,3))
 5410 %5 = y*x + Mod(2, 3)   \\@com do you understand this one?
 5411 ? lift(x * Mod(y,y^2+1) + Mod(2,3), 'x)
 5412 %6 = Mod(y, y^2 + 1)*x + Mod(Mod(2, 3), y^2 + 1)
 5413 ? lift(%, y)
 5414 %7 = y*x + Mod(2, 3)
 5415 @eprog\noindent To recursively lift all components not only by one level,
 5416 but as long as possible, use \kbd{liftall}. To lift only \typ{INTMOD}s and
 5417 \typ{PADIC}s components, use \tet{liftint}. To lift only \typ{POLMOD}s
 5418 components, use \tet{liftpol}. Finally, \tet{centerlift} allows to lift
 5419 \typ{INTMOD}s and \typ{PADIC}s using centered residues (lift of smallest
 5420 absolute value).
 5421 
 5422 The library syntax is \fun{GEN}{lift0}{GEN x, long v = -1} where \kbd{v} is a variable number.
 5423 Also available is \fun{GEN}{lift}{GEN x} corresponding to
 5424 \kbd{lift0(x,-1)}.
 5425 
 5426 \subsec{liftall$(x)$}\kbdsidx{liftall}\label{se:liftall}
 5427 Recursively lift all components of $x$ from $\Z/n\Z$ to $\Z$,
 5428 from $\Q_p$ to $\Q$ (as \tet{truncate}), and polmods to
 5429 polynomials. \typ{FFELT} are not lifted, nor are List elements: you may
 5430 convert the latter to vectors first, or use \kbd{apply(liftall,L)}. More
 5431 generally, components for which such lifts are meaningless (e.g. character
 5432 strings) are copied verbatim.
 5433 \bprog
 5434 ? liftall(x * (1 + O(3)) + Mod(2,3))
 5435 %1 = x + 2
 5436 ? liftall(x * Mod(y,y^2+1) + Mod(2,3)*Mod(z,z^2))
 5437 %2 = y*x + 2*z
 5438 @eprog
 5439 
 5440 The library syntax is \fun{GEN}{liftall}{GEN x}.
 5441 
 5442 \subsec{liftint$(x)$}\kbdsidx{liftint}\label{se:liftint}
 5443 Recursively lift all components of $x$ from $\Z/n\Z$ to $\Z$ and
 5444 from $\Q_p$ to $\Q$ (as \tet{truncate}).
 5445 \typ{FFELT} are not lifted, nor are List elements: you may
 5446 convert the latter to vectors first, or use \kbd{apply(liftint,L)}. More
 5447 generally, components for which such lifts are meaningless (e.g. character
 5448 strings) are copied verbatim.
 5449 \bprog
 5450 ? liftint(x * (1 + O(3)) + Mod(2,3))
 5451 %1 = x + 2
 5452 ? liftint(x * Mod(y,y^2+1) + Mod(2,3)*Mod(z,z^2))
 5453 %2 = Mod(y, y^2 + 1)*x + Mod(Mod(2*z, z^2), y^2 + 1)
 5454 @eprog
 5455 
 5456 The library syntax is \fun{GEN}{liftint}{GEN x}.
 5457 
 5458 \subsec{liftpol$(x)$}\kbdsidx{liftpol}\label{se:liftpol}
 5459 Recursively lift all components of $x$ which are polmods to
 5460 polynomials. \typ{FFELT} are not lifted, nor are List elements: you may
 5461 convert the latter to vectors first, or use \kbd{apply(liftpol,L)}. More
 5462 generally, components for which such lifts are meaningless (e.g. character
 5463 strings) are copied verbatim.
 5464 \bprog
 5465 ? liftpol(x * (1 + O(3)) + Mod(2,3))
 5466 %1 = (1 + O(3))*x + Mod(2, 3)
 5467 ? liftpol(x * Mod(y,y^2+1) + Mod(2,3)*Mod(z,z^2))
 5468 %2 = y*x + Mod(2, 3)*z
 5469 @eprog
 5470 
 5471 The library syntax is \fun{GEN}{liftpol}{GEN x}.
 5472 
 5473 \subsec{norm$(x)$}\kbdsidx{norm}\label{se:norm}
 5474 Algebraic norm of $x$, i.e.~the product of $x$ with
 5475 its conjugate (no square roots are taken), or conjugates for polmods. For
 5476 vectors and matrices, the norm is taken componentwise and hence is not the
 5477 $L^2$-norm (see \kbd{norml2}). Note that the norm of an element of
 5478 $\R$ is its square, so as to be compatible with the complex norm.
 5479 
 5480 The library syntax is \fun{GEN}{gnorm}{GEN x}.
 5481 
 5482 \subsec{numerator$(f,\{D\})$}\kbdsidx{numerator}\label{se:numerator}
 5483 Numerator of $f$. This is defined as \kbd{f * denominator(f,D)}, see
 5484 \kbd{denominator} for details. The optional argument $D$ allows to control
 5485 over which ring we compute the denominator:
 5486 
 5487 \item $1$: we only consider the underlying $\Q$-structure and the
 5488 denominator is a (positive) rational integer
 5489 
 5490 \item a simple variable, say \kbd{'x}: all entries as rational functions
 5491 in $K(x)$ and the denominator is a polynomial in $x$.
 5492 
 5493 \bprog
 5494 ? f = x + 1/y + 1/2;
 5495 ? numerator(f) \\ a t_POL in x
 5496 %2 = x + ((y + 2)/(2*y))
 5497 ? numerator(f, 1) \\ Q-denominator is 2
 5498 %3 = x + ((y + 2)/y)
 5499 ? numerator(f, y) \\ as a rational function in y
 5500 %5 = 2*y*x + (y + 2)
 5501 @eprog
 5502 
 5503 The library syntax is \fun{GEN}{numerator}{GEN f, GEN D = NULL}.
 5504 Also available are
 5505 \fun{GEN}{numer}{GEN x}  which implements the not very useful default
 5506 behaviour ($D$ is \kbd{NULL}) and
 5507 \fun{GEN}{Q_remove_denom}{GEN x, GEN *ptd} ($D = 1$) and also returns the
 5508 denominator (coding $1$ as \kbd{NULL}).
 5509 
 5510 \subsec{oo}\kbdsidx{oo}\label{se:oo}
 5511 Returns an object meaning $+\infty$, for use in functions such as
 5512 \kbd{intnum}. It can be negated (\kbd{-oo} represents $-\infty$), and
 5513 compared to real numbers (\typ{INT}, \typ{FRAC}, \typ{REAL}), with the
 5514 expected meaning: $+\infty$ is greater than any real number and $-\infty$ is
 5515 smaller.
 5516 
 5517 The library syntax is \fun{GEN}{mkoo}{}.
 5518 
 5519 \subsec{padicprec$(x,p)$}\kbdsidx{padicprec}\label{se:padicprec}
 5520 Returns the absolute $p$-adic precision of the object $x$; this is the
 5521 minimum precision of the components of $x$. The result is \tet{+oo} if $x$
 5522 is an exact object (as a $p$-adic):
 5523 \bprog
 5524 ? padicprec((1 + O(2^5)) * x + (2 + O(2^4)), 2)
 5525 %1 = 4
 5526 ? padicprec(x + 2, 2)
 5527 %2 = +oo
 5528 ? padicprec(2 + x + O(x^2), 2)
 5529 %3 = +oo
 5530 @eprog\noindent The function raises an exception if it encounters
 5531 an object incompatible with $p$-adic computations:
 5532 \bprog
 5533 ? padicprec(O(3), 2)
 5534  ***   at top-level: padicprec(O(3),2)
 5535  ***                 ^-----------------
 5536  *** padicprec: inconsistent moduli in padicprec: 3 != 2
 5537 
 5538 ? padicprec(1.0, 2)
 5539  ***   at top-level: padicprec(1.0,2)
 5540  ***                 ^----------------
 5541  *** padicprec: incorrect type in padicprec (t_REAL).
 5542 @eprog
 5543 
 5544 The library syntax is \fun{GEN}{gppadicprec}{GEN x, GEN p}.
 5545 Also available is the function \fun{long}{padicprec}{GEN x, GEN p},
 5546 which returns \tet{LONG_MAX} if $x = 0$ and the $p$-adic precision as a
 5547 \kbd{long} integer.
 5548 
 5549 \subsec{precision$(x,\{n\})$}\kbdsidx{precision}\label{se:precision}
 5550 The function behaves differently according to whether $n$ is
 5551 present or not. If $n$ is missing, the function returns
 5552 the floating point precision in decimal digits of the PARI object $x$. If $x$
 5553 has no floating point component, the function returns \kbd{+oo}.
 5554 \bprog
 5555 ? precision(exp(1e-100))
 5556 %1 = 154                \\ 154 significant decimal digits
 5557 ? precision(2 + x)
 5558 %2 = +oo                \\ exact object
 5559 ? precision(0.5 + O(x))
 5560 %3 = 38                 \\ floating point accuracy, NOT series precision
 5561 ? precision( [ exp(1e-100), 0.5 ] )
 5562 %4 = 38                 \\ minimal accuracy among components
 5563 @eprog\noindent Using \kbd{getlocalprec()} allows to retrieve
 5564 the working precision (as modified by possible \kbd{localprec}
 5565 statements).
 5566 
 5567 If $n$ is present, the function creates a new object equal to $x$ with a new
 5568 floating point precision $n$: $n$ is the number of desired significant
 5569 \emph{decimal} digits. If $n$ is smaller than the precision of a \typ{REAL}
 5570 component of $x$, it is truncated, otherwise it is extended with zeros.
 5571 For non-floating-point types, no change.
 5572 
 5573 The library syntax is \fun{GEN}{precision00}{GEN x, GEN n = NULL}.
 5574 Also available are \fun{GEN}{gprec}{GEN x, long n} and
 5575 \fun{long}{precision}{GEN x}. In both, the accuracy is expressed in
 5576 \emph{words} (32-bit or 64-bit depending on the architecture).
 5577 
 5578 \subsec{random$(\{N=2^{31}\})$}\kbdsidx{random}\label{se:random}
 5579 Returns a random element in various natural sets depending on the
 5580 argument $N$.
 5581 
 5582 \item \typ{INT}: returns an integer
 5583 uniformly distributed between $0$ and $N-1$. Omitting the argument
 5584 is equivalent to \kbd{random(2\pow31)}.
 5585 
 5586 \item \typ{REAL}: returns a real number in $[0,1[$ with the same accuracy as
 5587 $N$ (whose mantissa has the same number of significant words).
 5588 
 5589 \item \typ{INTMOD}: returns a random intmod for the same modulus.
 5590 
 5591 \item \typ{FFELT}: returns a random element in the same finite field.
 5592 
 5593 \item \typ{VEC} of length $2$, $N = [a,b]$: returns an integer uniformly
 5594 distributed between $a$ and $b$.
 5595 
 5596 \item \typ{VEC} generated by \kbd{ellinit} over a finite field $k$
 5597 (coefficients are \typ{INTMOD}s modulo a prime or \typ{FFELT}s): returns a
 5598 ``random'' $k$-rational \emph{affine} point on the curve. More precisely
 5599 if the curve has a single point (at infinity!) we return it; otherwise
 5600 we return an affine point by drawing an abscissa uniformly at
 5601 random until \tet{ellordinate} succeeds. Note that this is definitely not a
 5602 uniform distribution over $E(k)$, but it should be good enough for
 5603 applications.
 5604 
 5605 \item \typ{POL} return a random polynomial of degree at most the degree of $N$.
 5606 The coefficients are drawn by applying \kbd{random} to the leading
 5607 coefficient of $N$.
 5608 
 5609 \bprog
 5610 ? random(10)
 5611 %1 = 9
 5612 ? random(Mod(0,7))
 5613 %2 = Mod(1, 7)
 5614 ? a = ffgen(ffinit(3,7), 'a); random(a)
 5615 %3 = a^6 + 2*a^5 + a^4 + a^3 + a^2 + 2*a
 5616 ? E = ellinit([3,7]*Mod(1,109)); random(E)
 5617 %4 = [Mod(103, 109), Mod(10, 109)]
 5618 ? E = ellinit([1,7]*a^0); random(E)
 5619 %5 = [a^6 + a^5 + 2*a^4 + 2*a^2, 2*a^6 + 2*a^4 + 2*a^3 + a^2 + 2*a]
 5620 ? random(Mod(1,7)*x^4)
 5621 %6 = Mod(5, 7)*x^4 + Mod(6, 7)*x^3 + Mod(2, 7)*x^2 + Mod(2, 7)*x + Mod(5, 7)
 5622 
 5623 @eprog
 5624 These variants all depend on a single internal generator, and are
 5625 independent from your operating system's random number generators.
 5626 A random seed may be obtained via \tet{getrand}, and reset
 5627 using \tet{setrand}: from a given seed, and given sequence of \kbd{random}s,
 5628 the exact same values will be generated. The same seed is used at each
 5629 startup, reseed the generator yourself if this is a problem. Note that
 5630 internal functions also call the random number generator; adding such a
 5631 function call in the middle of your code will change the numbers produced.
 5632 
 5633 \misctitle{Technical note}
 5634 Up to
 5635 version 2.4 included, the internal generator produced pseudo-random numbers
 5636 by means of linear congruences, which were not well distributed in arithmetic
 5637 progressions. We now
 5638 use Brent's XORGEN algorithm, based on Feedback Shift Registers, see
 5639 \url{http://wwwmaths.anu.edu.au/~brent/random.html}. The generator has period
 5640 $2^{4096}-1$, passes the Crush battery of statistical tests of L'Ecuyer and
 5641 Simard, but is not suitable for cryptographic purposes: one can reconstruct
 5642 the state vector from a small sample of consecutive values, thus predicting
 5643 the entire sequence.
 5644 
 5645 The library syntax is \fun{GEN}{genrand}{GEN N = NULL}.
 5646 
 5647  Also available: \fun{GEN}{ellrandom}{GEN E} and \fun{GEN}{ffrandom}{GEN a}.
 5648 
 5649 \subsec{real$(x)$}\kbdsidx{real}\label{se:real}
 5650 Real part of $x$. When $x$ is a quadratic number, this is the
 5651 coefficient of $1$ in the ``canonical'' integral basis $(1,\omega)$.
 5652 \bprog
 5653 ? real(3 + I)
 5654 %1 = 3
 5655 ? x = 3 + quadgen(-23);
 5656 ? real(x) \\ as a quadratic number
 5657 %3 = 3
 5658 ? real(x * 1.) \\ as a complex number
 5659 %4 = 3.5000000000000000000000000000000000000
 5660 @eprog
 5661 
 5662 The library syntax is \fun{GEN}{greal}{GEN x}.
 5663 
 5664 \subsec{round$(x,\{\&e\})$}\kbdsidx{round}\label{se:round}
 5665 If $x$ is in $\R$, rounds $x$ to the nearest integer (rounding to
 5666 $+\infty$ in case of ties), then and sets $e$ to the number of error bits,
 5667 that is the binary exponent of the difference between the original and the
 5668 rounded value (the ``fractional part''). If the exponent of $x$ is too large
 5669 compared to its precision (i.e.~$e>0$), the result is undefined and an error
 5670 occurs if $e$ was not given.
 5671 
 5672 \misctitle{Important remark} Contrary to the other truncation functions,
 5673 this function operates on every coefficient at every level of a PARI object.
 5674 For example
 5675 $$\text{truncate}\left(\dfrac{2.4*X^2-1.7}{X}\right)=2.4*X,$$
 5676 whereas
 5677 $$\text{round}\left(\dfrac{2.4*X^2-1.7}{X}\right)=\dfrac{2*X^2-2}{X}.$$
 5678 An important use of \kbd{round} is to get exact results after an approximate
 5679 computation, when theory tells you that the coefficients must be integers.
 5680 
 5681 The library syntax is \fun{GEN}{round0}{GEN x, GEN *e = NULL}.
 5682 Also available are \fun{GEN}{grndtoi}{GEN x, long *e} and
 5683 \fun{GEN}{ground}{GEN x}.
 5684 
 5685 \subsec{serchop$(s,\{n=0\})$}\kbdsidx{serchop}\label{se:serchop}
 5686 Remove all terms of degree strictly less than $n$ in series $s$. When
 5687 the series contains no terms of degree $< n$, return $O(x^n)$.
 5688 \bprog
 5689 ? s = 1/x + x + 2*x^2 + O(x^3);
 5690 ? serchop(s)
 5691 %2 = x + 2*x^3 + O(x^3)
 5692 ? serchop(s, 2)
 5693 %3 = 2*x^2 + O(x^3)
 5694 ? serchop(s, 100)
 5695 %4 = O(x^100)
 5696 @eprog
 5697 
 5698 The library syntax is \fun{GEN}{serchop}{GEN s, long n}.
 5699 
 5700 \subsec{serprec$(x,v)$}\kbdsidx{serprec}\label{se:serprec}
 5701 Returns the absolute precision of $x$ with respect to power series
 5702 in the variable $v$; this is the
 5703 minimum precision of the components of $x$. The result is \tet{+oo} if $x$
 5704 is an exact object (as a series in $v$):
 5705 \bprog
 5706 ? serprec(x + O(y^2), y)
 5707 %1 = 2
 5708 ? serprec(x + 2, x)
 5709 %2 = +oo
 5710 ? serprec(2 + x + O(x^2), y)
 5711 %3 = +oo
 5712 @eprog
 5713 
 5714 The library syntax is \fun{GEN}{gpserprec}{GEN x, long v} where \kbd{v} is a variable number.
 5715 Also available is \fun{long}{serprec}{GEN x, GEN p}, which returns
 5716 \tet{LONG_MAX} if $x = 0$, otherwise the series precision as a \kbd{long} integer.
 5717 
 5718 \subsec{simplify$(x)$}\kbdsidx{simplify}\label{se:simplify}
 5719 This function simplifies $x$ as much as it can. Specifically, a complex or
 5720 quadratic number whose imaginary part is the integer 0 (i.e.~not \kbd{Mod(0,2)}
 5721 or \kbd{0.E-28}) is converted to its real part, and a polynomial of degree $0$
 5722 is converted to its constant term. Simplifications occur recursively.
 5723 
 5724 This function is especially useful before using arithmetic functions,
 5725 which expect integer arguments:
 5726 \bprog
 5727 ? x = 2 + y - y
 5728 %1 = 2
 5729 ? isprime(x)
 5730   ***   at top-level: isprime(x)
 5731   ***                 ^----------
 5732   *** isprime: not an integer argument in an arithmetic function
 5733 ? type(x)
 5734 %2 = "t_POL"
 5735 ? type(simplify(x))
 5736 %3 = "t_INT"
 5737 @eprog
 5738 Note that GP results are simplified as above before they are stored in the
 5739 history. (Unless you disable automatic simplification with \b{y}, that is.)
 5740 In particular
 5741 \bprog
 5742 ? type(%1)
 5743 %4 = "t_INT"
 5744 @eprog
 5745 
 5746 The library syntax is \fun{GEN}{simplify}{GEN x}.
 5747 
 5748 \subsec{sizebyte$(x)$}\kbdsidx{sizebyte}\label{se:sizebyte}
 5749 Outputs the total number of bytes occupied by the tree representing the
 5750 PARI object $x$.
 5751 
 5752 The library syntax is \fun{long}{gsizebyte}{GEN x}.
 5753 Also available is \fun{long}{gsizeword}{GEN x} returning a
 5754 number of \emph{words}.
 5755 
 5756 \subsec{sizedigit$(x)$}\kbdsidx{sizedigit}\label{se:sizedigit}
 5757 This function is DEPRECATED, essentially meaningless, and provided for
 5758 backwards compatibility only. Don't use it!
 5759 
 5760 outputs a quick upper bound for the number of decimal digits of (the
 5761 components of) $x$, off by at most $1$. More precisely, for a positive
 5762 integer $x$, it computes (approximately) the ceiling of
 5763 $$\kbd{floor}(1 + \log_2 x) \log_{10}2,$$
 5764 
 5765 To count the number of decimal digits of a positive integer $x$, use
 5766 \kbd{\#digits(x)}. To estimate (recursively) the size of $x$, use
 5767 \kbd{normlp(x)}.
 5768 
 5769 The library syntax is \fun{long}{sizedigit}{GEN x}.
 5770 
 5771 \subsec{truncate$(x,\{\&e\})$}\kbdsidx{truncate}\label{se:truncate}
 5772 Truncates $x$ and sets $e$ to the number of
 5773 error bits. When $x$ is in $\R$, this means that the part after the decimal
 5774 point is chopped away, $e$ is the binary exponent of the difference between
 5775 the original and the truncated value (the ``fractional part''). If the
 5776 exponent of $x$ is too large compared to its precision (i.e.~$e>0$), the
 5777 result is undefined and an error occurs if $e$ was not given. The function
 5778 applies componentwise on vector / matrices; $e$ is then the maximal number of
 5779 error bits. If $x$ is a rational function, the result is the ``integer part''
 5780 (Euclidean quotient of numerator by denominator) and $e$ is not set.
 5781 
 5782 Note a very special use of \kbd{truncate}: when applied to a power series, it
 5783 transforms it into a polynomial or a rational function with denominator
 5784 a power of $X$, by chopping away the $O(X^k)$. Similarly, when applied to
 5785 a $p$-adic number, it transforms it into an integer or a rational number
 5786 by chopping away the $O(p^k)$.
 5787 
 5788 The library syntax is \fun{GEN}{trunc0}{GEN x, GEN *e = NULL}.
 5789 The following functions are also available: \fun{GEN}{gtrunc}{GEN x}
 5790 and \fun{GEN}{gcvtoi}{GEN x, long *e}.
 5791 
 5792 \subsec{valuation$(x,p)$}\kbdsidx{valuation}\label{se:valuation}
 5793 Computes the highest
 5794 exponent of $p$ dividing $x$. If $p$ is of type integer, $x$ must be an
 5795 integer, an intmod whose modulus is divisible by $p$, a fraction, a
 5796 $q$-adic number with $q=p$, or a polynomial or power series in which case the
 5797 valuation is the minimum of the valuation of the coefficients.
 5798 
 5799 If $p$ is of type polynomial, $x$ must be of type polynomial or rational
 5800 function, and also a power series if $x$ is a monomial. Finally, the
 5801 valuation of a vector, complex or quadratic number is the minimum of the
 5802 component valuations.
 5803 
 5804 If $x=0$, the result is \kbd{+oo} if $x$ is an exact object. If $x$ is a
 5805 $p$-adic numbers or power series, the result is the exponent of the zero.
 5806 Any other type combinations gives an error.
 5807 
 5808 The library syntax is \fun{GEN}{gpvaluation}{GEN x, GEN p}.
 5809 Also available is
 5810 \fun{long}{gvaluation}{GEN x, GEN p}, which returns \tet{LONG_MAX} if $x = 0$
 5811 and the valuation as a \kbd{long} integer.
 5812 
 5813 \subsec{varhigher$(\var{name},\{v\})$}\kbdsidx{varhigher}\label{se:varhigher}
 5814 Return a variable \emph{name} whose priority is higher
 5815 than the priority of $v$ (of all existing variables if $v$ is omitted).
 5816 This is a counterpart to \tet{varlower}.
 5817 \bprog
 5818 ? Pol([x,x], t)
 5819  ***   at top-level: Pol([x,x],t)
 5820  ***                 ^------------
 5821  *** Pol: incorrect priority in gtopoly: variable x <= t
 5822 ? t = varhigher("t", x);
 5823 ? Pol([x,x], t)
 5824 %3 = x*t + x
 5825 @eprog\noindent This routine is useful since new GP variables directly
 5826 created by the interpreter always have lower priority than existing
 5827 GP variables. When some basic objects already exist in a variable
 5828 that is incompatible with some function requirement, you can now
 5829 create a new variable with a suitable priority instead of changing variables
 5830 in existing objects:
 5831 \bprog
 5832 ? K = nfinit(x^2+1);
 5833 ? rnfequation(K,y^2-2)
 5834  ***   at top-level: rnfequation(K,y^2-2)
 5835  ***                 ^--------------------
 5836  *** rnfequation: incorrect priority in rnfequation: variable y >= x
 5837 ? y = varhigher("y", x);
 5838 ? rnfequation(K, y^2-2)
 5839 %3 = y^4 - 2*y^2 + 9
 5840 @eprog\noindent
 5841 \misctitle{Caution 1}
 5842 The \emph{name} is an arbitrary character string, only used for display
 5843 purposes and need not be related to the GP variable holding the result, nor
 5844 to be a valid variable name. In particular the \emph{name} can
 5845 not be used to retrieve the variable, it is not even present in the parser's
 5846 hash tables.
 5847 \bprog
 5848 ? x = varhigher("#");
 5849 ? x^2
 5850 %2 = #^2
 5851 @eprog
 5852 \misctitle{Caution 2} There are a limited number of variables and if no
 5853 existing variable with the given display name has the requested
 5854 priority, the call to \kbd{varhigher} uses up one such slot. Do not create
 5855 new variables in this way unless it's absolutely necessary,
 5856 reuse existing names instead and choose sensible priority requirements:
 5857 if you only need a variable with higher priority than $x$, state so
 5858 rather than creating a new variable with highest priority.
 5859 \bprog
 5860 \\ quickly use up all variables
 5861 ? n = 0; while(1,varhigher("tmp"); n++)
 5862  ***   at top-level: n=0;while(1,varhigher("tmp");n++)
 5863  ***                             ^-------------------
 5864  *** varhigher: no more variables available.
 5865  ***   Break loop: type 'break' to go back to GP prompt
 5866 break> n
 5867 65510
 5868 \\ infinite loop: here we reuse the same 'tmp'
 5869 ? n = 0; while(1,varhigher("tmp", x); n++)
 5870 @eprog
 5871 
 5872 The library syntax is \fun{GEN}{varhigher}{const char *name, long v = -1} where \kbd{v} is a variable number.
 5873 
 5874 \subsec{variable$(\{x\})$}\kbdsidx{variable}\label{se:variable}
 5875 Gives the main variable of the object $x$ (the variable with the highest
 5876 priority used in $x$), and $p$ if $x$ is a $p$-adic number. Return $0$ if
 5877 $x$ has no variable attached to it.
 5878 \bprog
 5879 ? variable(x^2 + y)
 5880 %1 = x
 5881 ? variable(1 + O(5^2))
 5882 %2 = 5
 5883 ? variable([x,y,z,t])
 5884 %3 = x
 5885 ? variable(1)
 5886 %4 = 0
 5887 @eprog\noindent The construction
 5888 \bprog
 5889    if (!variable(x),...)
 5890 @eprog\noindent can be used to test whether a variable is attached to $x$.
 5891 
 5892 If $x$ is omitted, returns the list of user variables known to the
 5893 interpreter, by order of decreasing priority. (Highest priority is initially
 5894 $x$, which come first until \tet{varhigher} is used.) If \kbd{varhigher}
 5895 or \kbd{varlower} are used, it is quite possible to end up with different
 5896 variables (with different priorities) printed in the same way: they
 5897 will then appear multiple times in the output:
 5898 \bprog
 5899 ? varhigher("y");
 5900 ? varlower("y");
 5901 ? variable()
 5902 %4 = [y, x, y]
 5903 @eprog\noindent Using \kbd{v = variable()} then \kbd{v[1]}, \kbd{v[2]},
 5904 etc.~allows to recover and use existing variables.
 5905 
 5906 The library syntax is \fun{GEN}{gpolvar}{GEN x = NULL}.
 5907 However, in library mode, this function should not be used for $x$
 5908 non-\kbd{NULL}, since \tet{gvar} is more appropriate. Instead, for
 5909 $x$ a $p$-adic (type \typ{PADIC}), $p$ is $gel(x,2)$; otherwise, use
 5910 \fun{long}{gvar}{GEN x} which returns the variable number of $x$ if
 5911 it exists, \kbd{NO\_VARIABLE} otherwise, which satisfies the property
 5912 $\kbd{varncmp}(\kbd{NO\_VARIABLE}, v) > 0$ for all valid variable number
 5913 $v$, i.e. it has lower priority than any variable.
 5914 
 5915 \subsec{variables$(\{x\})$}\kbdsidx{variables}\label{se:variables}
 5916 Returns the list of all variables occurring in object $x$ (all user
 5917 variables known to the interpreter if $x$ is omitted), sorted by
 5918 decreasing priority.
 5919 \bprog
 5920 ? variables([x^2 + y*z + O(t), a+x])
 5921 %1 = [x, y, z, t, a]
 5922 @eprog\noindent The construction
 5923 \bprog
 5924    if (!variables(x),...)
 5925 @eprog\noindent can be used to test whether a variable is attached to $x$.
 5926 
 5927 If \kbd{varhigher} or \kbd{varlower} are used, it is quite possible to end up
 5928 with different variables (with different priorities) printed in the same
 5929 way: they will then appear multiple times in the output:
 5930 \bprog
 5931 ? y1 = varhigher("y");
 5932 ? y2 = varlower("y");
 5933 ? variables(y*y1*y2)
 5934 %4 = [y, y, y]
 5935 @eprog
 5936 
 5937 The library syntax is \fun{GEN}{variables_vec}{GEN x = NULL}.
 5938 
 5939 Also available is \fun{GEN}{variables_vecsmall}{GEN x} which returns
 5940 the (sorted) variable numbers instead of the attached monomials of degree 1.
 5941 
 5942 \subsec{varlower$(\var{name},\{v\})$}\kbdsidx{varlower}\label{se:varlower}
 5943 Return a variable \emph{name} whose priority is lower
 5944 than the priority of $v$ (of all existing variables if $v$ is omitted).
 5945 This is a counterpart to \tet{varhigher}.
 5946 
 5947 New GP variables directly created by the interpreter always
 5948 have lower priority than existing GP variables, but it is not easy
 5949 to check whether an identifier is currently unused, so that the
 5950 corresponding variable has the expected priority when it's created!
 5951 Thus, depending on the session history, the same command may fail or succeed:
 5952 \bprog
 5953 ? t; z;  \\ now t > z
 5954 ? rnfequation(t^2+1,z^2-t)
 5955  ***   at top-level: rnfequation(t^2+1,z^
 5956  ***                 ^--------------------
 5957  *** rnfequation: incorrect priority in rnfequation: variable t >= t
 5958 @eprog\noindent Restart and retry:
 5959 \bprog
 5960 ? z; t;  \\ now z > t
 5961 ? rnfequation(t^2+1,z^2-t)
 5962 %2 = z^4 + 1
 5963 @eprog\noindent It is quite annoying for package authors, when trying to
 5964 define a base ring, to notice that the package may fail for some users
 5965 depending on their session history. The safe way to do this is as follows:
 5966 \bprog
 5967 ? z; t;  \\ In new session: now z > t
 5968 ...
 5969 ? t = varlower("t", 'z);
 5970 ? rnfequation(t^2+1,z^2-2)
 5971 %2 = z^4 - 2*z^2 + 9
 5972 ? variable()
 5973 %3 = [x, y, z, t]
 5974 @eprog
 5975 \bprog
 5976 ? t; z;  \\ In new session: now t > z
 5977 ...
 5978 ? t = varlower("t", 'z); \\ create a new variable, still printed "t"
 5979 ? rnfequation(t^2+1,z^2-2)
 5980 %2 = z^4 - 2*z^2 + 9
 5981 ? variable()
 5982 %3 = [x, y, t, z, t]
 5983 @eprog\noindent Now both constructions succeed. Note that in the
 5984 first case, \kbd{varlower} is essentially a no-op, the existing variable $t$
 5985 has correct priority. While in the second case, two different variables are
 5986 displayed as \kbd{t}, one with higher priority than $z$ (created in the first
 5987  line) and another one with lower priority (created by \kbd{varlower}).
 5988 
 5989 \misctitle{Caution 1}
 5990 The \emph{name} is an arbitrary character string, only used for display
 5991 purposes and need not be related to the GP variable holding the result, nor
 5992 to be a valid variable name. In particular the \emph{name} can
 5993 not be used to retrieve the variable, it is not even present in the parser's
 5994 hash tables.
 5995 \bprog
 5996 ? x = varlower("#");
 5997 ? x^2
 5998 %2 = #^2
 5999 @eprog
 6000 \misctitle{Caution 2} There are a limited number of variables and if no
 6001 existing variable with the given display name has the requested
 6002 priority, the call to \kbd{varlower} uses up one such slot. Do not create
 6003 new variables in this way unless it's absolutely necessary,
 6004 reuse existing names instead and choose sensible priority requirements:
 6005 if you only need a variable with higher priority than $x$, state so
 6006 rather than creating a new variable with highest priority.
 6007 \bprog
 6008 \\ quickly use up all variables
 6009 ? n = 0; while(1,varlower("x"); n++)
 6010  ***   at top-level: n=0;while(1,varlower("x");n++)
 6011  ***                             ^-------------------
 6012  *** varlower: no more variables available.
 6013  ***   Break loop: type 'break' to go back to GP prompt
 6014 break> n
 6015 65510
 6016 \\ infinite loop: here we reuse the same 'tmp'
 6017 ? n = 0; while(1,varlower("tmp", x); n++)
 6018 @eprog
 6019 
 6020 The library syntax is \fun{GEN}{varlower}{const char *name, long v = -1} where \kbd{v} is a variable number.
 6021 
 6022 \section{Combinatorics}\label{se:combinat}
 6023 
 6024 Permutations are represented in gp as \typ{VECSMALL}s and can be input
 6025 directly as \kbd{Vecsmall([1,3,2,4])} or obtained from the iterator
 6026 \kbd{forperm}:
 6027 \bprog
 6028 ? forperm(3, p, print(p))  \\ iterate through S_3
 6029 Vecsmall([1, 2, 3])
 6030 Vecsmall([1, 3, 2])
 6031 Vecsmall([2, 1, 3])
 6032 Vecsmall([2, 3, 1])
 6033 Vecsmall([3, 1, 2])
 6034 Vecsmall([3, 2, 1])
 6035 @eprog
 6036 
 6037 Permutations can be multiplied via \kbd{*}, raised to some power using
 6038 \kbd{\pow}, inverted using \kbd{\pow(-1)}, conjugated as
 6039 \kbd{p * q * p\pow(-1)}. Their order and signature is available via
 6040 \kbd{permorder} and \kbd{permsign}.
 6041 
 6042 \subsec{bernfrac$(n)$}\kbdsidx{bernfrac}\label{se:bernfrac}
 6043 Bernoulli number\sidx{Bernoulli numbers} $B_n$,
 6044 where $B_0=1$, $B_1=-1/2$, $B_2=1/6$,\dots, expressed as a rational number.
 6045 The argument $n$ should be a nonnegative integer. The function \tet{bervec}
 6046 creates a cache of successive Bernoulli numbers which greatly speeds up
 6047 later calls to \kbd{bernfrac}:
 6048 \bprog
 6049 ? bernfrac(20000);
 6050 time = 107 ms.
 6051 ? bernvec(10000); \\ cache B_0, B_2, ..., B_20000
 6052 time = 35,957 ms.
 6053 ? bernfrac(20000); \\ now instantaneous
 6054 ?
 6055 @eprog
 6056 
 6057 The library syntax is \fun{GEN}{bernfrac}{long n}.
 6058 
 6059 \subsec{bernpol$(n, \{v = 'x\})$}\kbdsidx{bernpol}\label{se:bernpol}
 6060 \idx{Bernoulli polynomial} $B_n$ in variable $v$.
 6061 \bprog
 6062 ? bernpol(1)
 6063 %1 = x - 1/2
 6064 ? bernpol(3)
 6065 %2 = x^3 - 3/2*x^2 + 1/2*x
 6066 @eprog
 6067 
 6068 The library syntax is \fun{GEN}{bernpol}{long n, long v = -1} where \kbd{v} is a variable number.
 6069 
 6070 \subsec{bernreal$(n)$}\kbdsidx{bernreal}\label{se:bernreal}
 6071 Bernoulli number\sidx{Bernoulli numbers}
 6072 $B_n$, as \kbd{bernfrac}, but $B_n$ is returned as a real number
 6073 (with the current precision). The argument $n$ should be a nonnegative
 6074 integer. The function slows down as the precision increases:
 6075 \bprog
 6076 ? \p1000
 6077 ? bernreal(200000);
 6078 time = 5 ms.
 6079 ? \p10000
 6080 ? bernreal(200000);
 6081 time = 18 ms.
 6082 ? \p100000
 6083 ? bernreal(200000);
 6084 time = 84 ms.
 6085 @eprog
 6086 
 6087 The library syntax is \fun{GEN}{bernreal}{long n, long prec}.
 6088 
 6089 \subsec{bernvec$(n)$}\kbdsidx{bernvec}\label{se:bernvec}
 6090 Returns a vector containing, as rational numbers,
 6091 the \idx{Bernoulli numbers} $B_0$, $B_2$,\dots, $B_{2n}$:
 6092 \bprog
 6093 ? bernvec(5) \\ B_0, B_2..., B_10
 6094 %1 = [1, 1/6, -1/30, 1/42, -1/30, 5/66]
 6095 ? bernfrac(10)
 6096 %2 = 5/66
 6097 @eprog\noindent This routine uses a lot of memory but is much faster than
 6098 repeated calls to \kbd{bernfrac}:
 6099 \bprog
 6100 ? forstep(n = 2, 10000, 2, bernfrac(n))
 6101 time = 41,522 ms.
 6102 ? bernvec(5000);
 6103 time = 4,784 ms.
 6104 @eprog\noindent The computed Bernoulli numbers are stored in an incremental
 6105 cache which makes later calls to \kbd{bernfrac} and \kbd{bernreal}
 6106 instantaneous in the cache range: re-running the same previous \kbd{bernfrac}s
 6107 after the \kbd{bernvec} call gives:
 6108 \bprog
 6109 ? forstep(n = 2, 10000, 2, bernfrac(n))
 6110 time = 1 ms.
 6111 @eprog\noindent The time and space complexity of this function are
 6112 $\tilde{O}(n^2)$; in the feasible range $n \leq 10^5$ (requires about 2 hours),
 6113 the practical time complexity is closer to $\tilde{O}(n^{\log_2 6})$.
 6114 
 6115 The library syntax is \fun{GEN}{bernvec}{long n}.
 6116 
 6117 \subsec{binomial$(x,\{k\})$}\kbdsidx{binomial}\label{se:binomial}
 6118 \idx{binomial coefficient} $\binom{x}{k}$.
 6119 Here $k$ must be an integer, but $x$ can be any PARI object.
 6120 \bprog
 6121 ? binomial(4,2)
 6122 %1 = 6
 6123 ? n = 4; vector(n+1, k, binomial(n,k-1))
 6124 %2 = [1, 4, 6, 4, 1]
 6125 @eprog\noindent The argument $k$ may be omitted if $x = n$ is a
 6126 nonnegative integer; in this case, return the vector with $n+1$
 6127 components whose $k+1$-th entry is \kbd{binomial}$(n,k)$
 6128 \bprog
 6129 ? binomial(4)
 6130 %3 = [1, 4, 6, 4, 1]
 6131 @eprog
 6132 
 6133 The library syntax is \fun{GEN}{binomial0}{GEN x, GEN k = NULL}.
 6134 
 6135 \subsec{eulerfrac$(n)$}\kbdsidx{eulerfrac}\label{se:eulerfrac}
 6136 Euler number\sidx{Euler numbers} $E_n$,
 6137 where $E_0=1$, $E_1=0$, $E_2=-1$, \dots, are integers such that
 6138 $$ \dfrac{1}{\cosh t} = \sum_{n\geq 0} \dfrac{E_n}{n!} t^n. $$
 6139 The argument $n$ should be a nonnegative integer.
 6140 \bprog
 6141 ? vector(10,i,eulerfrac(i))
 6142 %1 = [0, -1, 0, 5, 0, -61, 0, 1385, 0, -50521]
 6143 ? eulerfrac(20000);
 6144 ? sizedigit(%))
 6145 %3 = 73416
 6146 @eprog
 6147 
 6148 The library syntax is \fun{GEN}{eulerfrac}{long n}.
 6149 
 6150 \subsec{eulerianpol$(n, \{v = 'x\})$}\kbdsidx{eulerianpol}\label{se:eulerianpol}
 6151 \idx{Eulerian polynomial} $A_n$ in variable $v$.
 6152 \bprog
 6153 ? eulerianpol(2)
 6154 %1 = x + 1
 6155 ? eulerianpol(5, 't)
 6156 %2 = t^4 + 26*t^3 + 66*t^2 + 26*t + 1
 6157 
 6158 @eprog
 6159 
 6160 The library syntax is \fun{GEN}{eulerianpol}{long n, long v = -1} where \kbd{v} is a variable number.
 6161 
 6162 \subsec{eulerpol$(n, \{v = 'x\})$}\kbdsidx{eulerpol}\label{se:eulerpol}
 6163 \idx{Euler polynomial} $E_n$ in variable $v$.
 6164 \bprog
 6165 ? eulerpol(1)
 6166 %1 = x - 1/2
 6167 ? eulerpol(3)
 6168 %2 = x^3 - 3/2*x^2 + 1/4
 6169 @eprog
 6170 
 6171 The library syntax is \fun{GEN}{eulerpol}{long n, long v = -1} where \kbd{v} is a variable number.
 6172 
 6173 \subsec{eulervec$(n)$}\kbdsidx{eulervec}\label{se:eulervec}
 6174 Returns a vector containing, as rational numbers,
 6175 the nonzero \idx{Euler numbers} $E_0$, $E_2$,\dots, $E_{2n}$:
 6176 \bprog
 6177 ? eulervec(5) \\ E_0, E_2..., E_10
 6178 %1 = [1, -1, 5, -61, 1385, -50521]
 6179 ? eulerfrac(10)
 6180 %2 = -50521
 6181 @eprog\noindent This routine uses more memory but is a little faster than
 6182 repeated calls to \kbd{eulerfrac}:
 6183 \bprog
 6184 ? forstep(n = 2, 8000, 2, eulerfrac(n))
 6185 time = 46,851 ms.
 6186 ? eulervec(4000);
 6187 time = 30,588 ms.
 6188 @eprog
 6189 
 6190 The library syntax is \fun{GEN}{eulervec}{long n}.
 6191 
 6192 \subsec{fibonacci$(x)$}\kbdsidx{fibonacci}\label{se:fibonacci}
 6193 $x^{\text{th}}$ Fibonacci number.
 6194 
 6195 The library syntax is \fun{GEN}{fibo}{long x}.
 6196 
 6197 \subsec{hammingweight$(x)$}\kbdsidx{hammingweight}\label{se:hammingweight}
 6198 If $x$ is a \typ{INT}, return the binary Hamming weight of $|x|$. Otherwise
 6199 $x$ must be of type \typ{POL}, \typ{VEC}, \typ{COL}, \typ{VECSMALL}, or
 6200 \typ{MAT} and the function returns the number of nonzero coefficients of
 6201 $x$.
 6202 \bprog
 6203 ? hammingweight(15)
 6204 %1 = 4
 6205 ? hammingweight(x^100 + 2*x + 1)
 6206 %2 = 3
 6207 ? hammingweight([Mod(1,2), 2, Mod(0,3)])
 6208 %3 = 2
 6209 ? hammingweight(matid(100))
 6210 %4 = 100
 6211 @eprog
 6212 
 6213 The library syntax is \fun{long}{hammingweight}{GEN x}.
 6214 
 6215 \subsec{numbpart$(n)$}\kbdsidx{numbpart}\label{se:numbpart}
 6216 Gives the number of unrestricted partitions of
 6217 $n$, usually called $p(n)$ in the literature; in other words the number of
 6218 nonnegative integer solutions to $a+2b+3c+\cdots=n$. $n$ must be of type
 6219 integer and $n<10^{15}$ (with trivial values $p(n) = 0$ for $n < 0$ and
 6220 $p(0) = 1$). The algorithm uses the Hardy-Ramanujan-Rademacher formula.
 6221 To explicitly enumerate them, see \tet{partitions}.
 6222 
 6223 The library syntax is \fun{GEN}{numbpart}{GEN n}.
 6224 
 6225 \subsec{numtoperm$(n,k)$}\kbdsidx{numtoperm}\label{se:numtoperm}
 6226 Generates the $k$-th permutation (as a row vector of length $n$) of the
 6227 numbers $1$ to $n$. The number $k$ is taken modulo $n!\,$, i.e.~inverse
 6228 function of \tet{permtonum}. The numbering used is the standard lexicographic
 6229 ordering, starting at $0$.
 6230 
 6231 The library syntax is \fun{GEN}{numtoperm}{long n, GEN k}.
 6232 
 6233 \subsec{partitions$(k,\{a=k\},\{n=k\})$}\kbdsidx{partitions}\label{se:partitions}
 6234 Returns the vector of partitions of the integer $k$ as a sum of positive
 6235 integers (parts); for $k < 0$, it returns the empty set \kbd{[]}, and for $k
 6236 = 0$ the trivial partition (no parts). A partition is given by a
 6237 \typ{VECSMALL}, where parts are sorted in nondecreasing order:
 6238 \bprog
 6239 ? partitions(3)
 6240 %1 = [Vecsmall([3]), Vecsmall([1, 2]), Vecsmall([1, 1, 1])]
 6241 @eprog\noindent correspond to $3$, $1+2$ and $1+1+1$. The number
 6242 of (unrestricted) partitions of $k$ is given
 6243 by \tet{numbpart}:
 6244 \bprog
 6245 ? #partitions(