Annotation of OpenXM_contrib/pari-2.2/doc/usersch5.tex, Revision 1.1
1.1 ! noro 1: % $Id: usersch5.tex,v 1.7 2001/03/26 11:54:34 karim Exp $
! 2: % Copyright (c) 2000 The PARI Group
! 3: %
! 4: % This file is part of the PARI/GP documentation
! 5: %
! 6: % Permission is granted to copy, distribute and/or modify this document
! 7: % under the terms of the GNU Free Documentation License
! 8: \chapter{Technical Reference Guide for Low-Level Functions}
! 9:
! 10: In this chapter, we give a description all public low-level functions of the
! 11: PARI system. These essentially include functions for handling all the PARI
! 12: types. Higher level functions, such as arithmetic or transcendental
! 13: functions, are described fully in Chapter~3 of this manual.
! 14:
! 15: Many other undocumented functions can be found throughout the source code.
! 16: These private functions are more efficient than the library functions that
! 17: call them, but much sloppier on argument checking and damage control. Use
! 18: them at your own risk!
! 19:
! 20: \section{Level 0 kernel (operations on unsigned longs)}
! 21:
! 22: \noindent
! 23: For the non-68k versions, we need level 0 operations simulating basic
! 24: operations of the 68020 processor (on which PARI was originally
! 25: implemented). The type \tet{ulong} is defined in the file \kbd{parigen.h} as
! 26: \kbd{unsigned long}. Note that in the prototypes below a \kbd{ulong} is
! 27: sometimes implicitly typecast to \kbd{int} or \kbd{long}.
! 28:
! 29: The global \kbd{ulong} variables \kbd{overflow} (which will contain
! 30: only 0 or 1) and \kbd{hiremainder} used to be declared in the file
! 31: \kbd{pariinl.h}. However, for certain architectures they are no longer
! 32: needed, and/or have been replaced with local variables for efficiency;
! 33: and the `functions' mentioned below are really chunks of assembler code which
! 34: will be inlined at each invocation by the compiler. If you really need to
! 35: use these lowest-level operations directly, make sure you know your way
! 36: through the PARI kernel sources, and understand the architecture dependencies.
! 37:
! 38: To make the following descriptions valid both for 32-bit and 64-bit
! 39: machines, we will set \B\ to be equal to 32 (resp.~64), an abbreviation of
! 40: \kbd{BITS\_IN\_LONG}, which is what is actually used in the source code.
! 41:
! 42: \fun{int}{addll}{int x, int y} adds the ulongs \kbd{x} and \kbd{y},
! 43: returns the lower \B\ bits and puts the carry bit into \kbd{overflow}.
! 44:
! 45: \fun{int}{addllx}{int x, int y} adds \kbd{overflow} to the sum of the
! 46: ulongs \kbd{x} and \kbd{y}, returns the lower \B\ bits and puts the
! 47: carry bit into \kbd{overflow}.
! 48:
! 49: \fun{int}{subll}{int x, int y} subtracts the ulongs \kbd{x} and \kbd{y},
! 50: returns the lower \B\ bits and put the carry (borrow) bit into \kbd{overflow}.
! 51:
! 52: \fun{int}{subllx}{int x, int y} subtracts \kbd{overflow} from the
! 53: difference of the ulongs \kbd{x} and \kbd{y}, returns the lower \B\ bits
! 54: and puts the carry (borrow) bit into \kbd{overflow}.
! 55:
! 56: \fun{int}{shiftl}{ulong x, ulong y} shifts the ulong \kbd{x} left by \kbd{y}
! 57: bits, returns the lower \B\ bits and stores the high-order \B\ bits into
! 58: \kbd{hiremainder}. We must have $1\le\kbd{y}\le\B$. In particular, \kbd{y}
! 59: must be non-zero; the caller is responsible for testing this.
! 60:
! 61: \fun{int}{shiftlr}{ulong x, ulong y} shifts the ulong \kbd{x << \B} right
! 62: by \kbd{y} bits, returns the higher \B\ bits and stores the low-order
! 63: \B\ bits into \kbd{hiremainder}. We must have $1\le\kbd{y}\le\B$. In
! 64: particular, \kbd{y} must be non-zero.
! 65:
! 66: \fun{int}{bfffo}{ulong x} returns the number of leading zero bits in the
! 67: ulong \kbd{x} (i.e. the number of bit positions by which it would have to be
! 68: shifted left until its leftmost bit first becomes equal to~1, which can be
! 69: between 0 and $\B-1$ for nonzero \kbd{x}). When \kbd{x} is~0, \B\ is returned.
! 70:
! 71: \fun{int}{mulll}{ulong x, ulong y} multiplies the ulong \kbd{x} by the ulong
! 72: \kbd{y}, returns the lower \B\ bits and stores the high-order \B\ bits into
! 73: \kbd{hiremainder}.
! 74:
! 75: \fun{int}{addmul}{ulong x, ulong y} adds \kbd{hiremainder} to the product
! 76: of the ulongs \kbd{x} and \kbd{y}, returns the lower \B\ bits and stores the
! 77: high-order \B\ bits into \kbd{hiremainder}.
! 78:
! 79: \fun{int}{divll}{ulong x, ulong y} returns the Euclidean quotient of
! 80: (\kbd{hiremainder << \B})${}+{}$\kbd{x} and the ulong divisor \kbd{y} and
! 81: stores the remainder into \kbd{hiremainder}. An error occurs if the quotient
! 82: cannot be represented by a ulong, i.e.~if $\kbd{hiremainder}\ge\kbd{y}$
! 83: initially.
! 84:
! 85: \section{Level 1 kernel (operations on longs, integers and reals)}
! 86:
! 87: \noindent
! 88: In this section as elsewhere, \kbd{long} denotes a \B-bit signed C-integer,
! 89: ``integer'' denotes a PARI multiprecise integer (type \typ{INT}), ``real''
! 90: denotes a PARI multiprecise real (type \typ{REAL}). Refer to Chapters
! 91: 1--2 and~4 for general background.
! 92:
! 93: \misctitle{Note:} Many functions consist of an elementary operation,
! 94: immediately followed by an assignment statement. All such functions are
! 95: obtained using macros (see the file \kbd{paricom.h}), hence you can easily
! 96: extend the list. Below, they will be introduced like in the following
! 97: example:
! 98:
! 99: \fun{GEN}{gadd[z]}{GEN x, GEN y[, GEN z]} followed by the explicit
! 100: description of the function
! 101:
! 102: \kbd{GEN \key{gadd}(GEN x, GEN y)}
! 103:
! 104: \noindent which creates its result on the stack, returning a \kbd{GEN} pointer
! 105: to it, and the parts in brackets indicate that there exists also a function
! 106:
! 107: \kbd{void \key{gaddz}(GEN x, GEN y, GEN z)}
! 108:
! 109: \noindent which assigns its result to the pre-existing object
! 110: \kbd{z}, leaving the stack unchanged.
! 111:
! 112: \subsec{Basic unit and subunit handling functions}
! 113:
! 114: \fun{long}{typ}{GEN x} returns the type number of~\kbd{x}. (The header files
! 115: included through \kbd{pari.h} will give you access to the symbolic constants
! 116: \typ{INT} etc., so you should never need to know the actual numerical values.)
! 117:
! 118: \fun{long}{lg}{GEN x} returns the length of~\kbd{x} in \B-bit words.
! 119:
! 120: \fun{long}{lgef}{GEN x} returns the effective length of the polynomial \kbd{x}
! 121: in \B-bit words.
! 122:
! 123: \fun{long}{lgefint}{GEN x} returns the effective length of the integer \kbd{x}
! 124: in \B-bit words.
! 125:
! 126: \fun{long}{signe}{GEN x} returns the sign ($-1$, 0 or 1) of~\kbd{x}. Can be
! 127: used for integers, reals, polynomials and power series (for the last two
! 128: types, only 0 or 1 are possible).
! 129:
! 130: \fun{long}{gsigne}{GEN x} same as \kbd{signe}, but also valid for rational
! 131: numbers (and marginally less efficient for the other types).
! 132:
! 133: \fun{long}{expo}{GEN x} returns the unbiased binary exponent of the real
! 134: number~\kbd{x}.
! 135:
! 136: \fun{long}{gexpo}{GEN x} same as \kbd{expo}, but also valid when \kbd{x}
! 137: is not a real number. When \kbd{x} is an exact~0, this returns
! 138: \hbox{\kbd{-HIGHEXPOBIT}}.
! 139:
! 140: \fun{long}{expi}{GEN x} returns the binary exponent of the real number equal
! 141: to the integer~\kbd{x}. This is a special case of \kbd{gexpo} above, covering
! 142: the case where \kbd{x} is of type~\typ{INT}.
! 143:
! 144: \fun{long}{valp}{GEN x} returns the unbiased 16-bit $p$-adic valuation (for
! 145: a $p$-adic) or $X$-adic valuation (for a power series, taken with respect
! 146: to the main variable) of~\kbd{x}.
! 147:
! 148: \fun{long}{precp}{GEN x} returns the precision of the $p$-adic~\kbd{x}.
! 149:
! 150: \fun{long}{varn}{GEN x} returns the variable number of \kbd{x} (between 0 and
! 151: \kbd{MAXVARN}). Should be used only for polynomials and power series.
! 152:
! 153: \fun{long}{gvar}{(GEN x)} returns the main variable number when any variable
! 154: at all occurs in the composite object~\kbd{x} (the smallest variable number
! 155: which occurs), and \kbd{BIGINT} otherwise.
! 156:
! 157: \fun{void}{settyp}{GEN x, long s} sets the type number of~\kbd{x} to~\kbd{s}.
! 158: This should be used with extreme care since usually the type is set
! 159: otherwise, and the components and further codeword fields (which are left
! 160: unchanged) may not match the PARI conventions for the new type.
! 161:
! 162: \fun{void}{setlg}{GEN x, long s} sets the length of~\kbd{x} to~\kbd{s}. Again
! 163: this should be used with extreme care since usually the length is set
! 164: otherwise, and increasing the length joins previously unrelated memory words
! 165: to the root node of~\kbd{x}. This is, however, an extremely efficient way of
! 166: truncating vectors or polynomials.
! 167:
! 168: \fun{void}{setlgef}{GEN x, long s} sets the effective length of \kbd{x}
! 169: to~\kbd{s}, where \kbd{x} is a polynomial. The number \kbd{s} must be less
! 170: than or equal to the length of~\kbd{x}.
! 171:
! 172: \fun{void}{setlgefint}{GEN x, long s} sets the effective length
! 173: of the integer \kbd{x} to~\kbd{s}. The number \kbd{s} must be less than or
! 174: equal to the length of~\kbd{x}.
! 175:
! 176: \fun{void}{setsigne}{GEN x, long s} sets the sign of~\kbd{x} to~\kbd{s}.
! 177: If \kbd{x} is an integer or real, \kbd{s} must be equal to $-1$, 0 or~1,
! 178: and if \kbd{x} is a polynomial or a power series, \kbd{s} must be equal to
! 179: 0 or~1.
! 180:
! 181: \fun{void}{setexpo}{GEN x, long s} sets the binary exponent of the real
! 182: number~\kbd{x} to \kbd{s}, after adding the appropriate bias. The unbiased
! 183: value \kbd{s} must be a 24-bit signed number.
! 184:
! 185: \fun{void}{setvalp}{GEN x, long s} sets the $p$-adic or $X$-adic valuation
! 186: of~\kbd{x} to~\kbd{s}, if \kbd{x} is a $p$-adic or a power series,
! 187: respectively.
! 188:
! 189: \fun{void}{setprecp}{GEN x, long s} sets the $p$-adic precision of the
! 190: $p$-adic number~\kbd{x} to~\kbd{s}.
! 191:
! 192: \fun{void}{setvarn}{GEN x, long s} sets the variable number of the polynomial
! 193: or power series~\kbd{x} to~\kbd{s} (where $0\le \kbd{s}\le\kbd{MAXVARN}$).
! 194:
! 195:
! 196: \subsec{Memory allocation on the PARI stack}
! 197:
! 198: \fun{GEN}{cgetg}{long n, long t} allocates memory on the PARI stack for
! 199: an object of length \kbd{n} and type~\kbd{t}, and initializes its first
! 200: codeword.
! 201:
! 202: \fun{GEN}{cgeti}{long n} allocates memory on the PARI stack for an
! 203: integer of length~\kbd{n}, and initializes its first codeword. Identical to
! 204: {\tt cgetg(n,\typ{INT})}.
! 205:
! 206: \fun{GEN}{cgetr}{long n} allocates memory on the PARI stack for a real
! 207: of length~\kbd{n}, and initializes its first codeword. Identical to
! 208: {\tt cgetg(n,\typ{REAL})}.
! 209:
! 210: \fun{void}{cgiv}{GEN x} frees object \kbd{x} if it is the last created on the
! 211: PARI stack (otherwise disaster occurs).
! 212:
! 213: \fun{GEN}{gerepile}{long p, long q, GEN x} general garbage collector
! 214: for the PARI stack. See \secref{se:garbage} for a detailed explanation and
! 215: many examples.
! 216:
! 217: \subsec{Assignments, conversions and integer parts}
! 218:
! 219: \fun{void}{mpaff}{GEN x, GEN z} assigns \kbd{x} into~\kbd{z} (where
! 220: \kbd{x} and \kbd{z} are integers or reals).
! 221:
! 222: \fun{void}{affsz}{long s, GEN z} assigns the long \kbd{s} into the integer or
! 223: real~\kbd{z}.
! 224:
! 225: \fun{void}{affsi}{long s, GEN z} assigns the long \kbd{s} into the
! 226: integer~\kbd{z}.
! 227:
! 228: \fun{void}{affsr}{long s, GEN z} assigns the long \kbd{s} into the
! 229: real~\kbd{z}.
! 230:
! 231: \fun{void}{affii}{GEN x, GEN z} assigns the integer \kbd{x} into the
! 232: integer~\kbd{z}.
! 233:
! 234: \fun{void}{affir}{GEN x, GEN z} assigns the integer \kbd{x} into the
! 235: real~\kbd{z}.
! 236:
! 237: \fun{void}{affrs}{GEN x, long s} assigns the real \kbd{x} into the
! 238: long~\kbd{s}\dots not. This is a forbidden assignment in PARI, so an error
! 239: message is issued.
! 240:
! 241: \fun{void}{affri}{GEN x, GEN z} assigns the real \kbd{x} into the
! 242: integer~\kbd{z}\dots no it doesn't. This is a forbidden assignment in PARI,
! 243: so an error message is issued.
! 244:
! 245: \fun{void}{affrr}{GEN x, GEN z} assigns the real \kbd{x} into the real~\kbd{z}.
! 246: \smallskip
! 247:
! 248: \fun{GEN}{stoi}{long s} creates the PARI integer corresponding to the
! 249: long~\kbd{s}.
! 250:
! 251: \fun{long}{itos}{GEN x} converts the PARI integer \kbd{x} to a C long (if
! 252: possible, otherwise an error message is issued).
! 253: \smallskip
! 254:
! 255: \fun{GEN}{mptrunc[z]}{GEN x[, GEN z]} truncates the integer or real~\kbd{x}
! 256: (not the same as the integer part if \kbd{x} is non-integer and negative).
! 257:
! 258: \fun{GEN}{mpent[z]}{GEN x[, GEN z]} true integer part of the integer or
! 259: real~\kbd{x} (i.e.~the \kbd{floor} function).
! 260:
! 261: \subsec{Valuation and shift}
! 262:
! 263: \fun{long}{vals}{long s} 2-adic valuation of the long~\kbd{s}. Returns $-1$
! 264: if \kbd{s} is equal to 0, with no error.
! 265:
! 266: \fun{long}{vali}{GEN x} 2-adic valuation of the integer~\kbd{x}. Returns $-1$
! 267: if \kbd{s} is equal to 0, with no error.
! 268:
! 269: \fun{GEN}{mpshift[z]}{GEN x, long n[, GEN z]} shifts the real or
! 270: integer \kbd{x} by~\kbd{n}. If \kbd{n} is positive, this is a left shift,
! 271: i.e.~multiplication by $2^{\kbd{n}}$. If \kbd{n} is negative, it is a right
! 272: shift by~$-\kbd{n}$, which amounts to the truncation of the quotient of \kbd{x}
! 273: by~$2^{-\kbd{n}}$.
! 274:
! 275: \fun{GEN}{shifts}{long s, long n} converts the long \kbd{s} into a PARI
! 276: integer and shifts the value by~\kbd{n}.
! 277:
! 278: \fun{GEN}{shifti}{GEN x, long n} shifts the integer~\kbd{x} by~\kbd{n}.
! 279:
! 280: \fun{GEN}{shiftr}{GEN x, long n} shifts the real~\kbd{x} by~\kbd{n}.
! 281:
! 282: \subsec{Unary operations}
! 283:
! 284: \noindent
! 285: Let ``\op'' be some unary operation of type \kbd{GEN (*)(GEN)}. The names and
! 286: prototypes of the low-level functions corresponding to \op\ will be as follows.
! 287:
! 288: \funno{GEN}{mp\op}{GEN x} creates the result of \op\ applied to the integer
! 289: or real~\kbd{x}.
! 290:
! 291: \funno{GEN}{\op s}{long s} creates the result of \op\ applied to the
! 292: long~\kbd{s}.
! 293:
! 294: \funno{GEN}{\op i}{GEN x} creates the result of \op\ applied to the
! 295: integer~\kbd{x}.
! 296:
! 297: \funno{GEN}{\op r}{GEN x} creates the result of \op\ applied to the real~\kbd{x}.
! 298:
! 299: \funno{GEN}{mp\op z}{GEN x, GEN z} assigns the result of applying \op\ to the
! 300: integer or real~\kbd{x} into the integer or real \kbd{z}.
! 301:
! 302: \misctitle{Remark:} it has not been considered useful to include the
! 303: functions {\tt void \op sz(long,GEN)}, {\tt void \op iz(GEN,GEN)} and
! 304: {\tt void \op rz(GEN, GEN)}.
! 305: \smallskip
! 306:
! 307: \noindent The above prototype schemes apply to the following operators:
! 308:
! 309: \op=\key{neg}: negation ($-$\kbd{x}). The result is of the same type
! 310: as~\kbd{x}.
! 311:
! 312: \op=\key{abs}: absolute value ($|\kbd{x}|$). The result is of the same type
! 313: as~\kbd{x}.
! 314:
! 315: \noindent In addition, there exist the following special unary functions with
! 316: assignment:
! 317:
! 318: \fun{void}{mpinvz}{GEN x, GEN z} assigns the inverse of the integer or
! 319: real \kbd{x} into the real~\kbd{z}. The inverse is computed as a quotient
! 320: of real numbers, not as a Euclidean division.
! 321:
! 322: \fun{void}{mpinvsr}{long s, GEN z} assigns the inverse of the long \kbd{s}
! 323: into the real~\kbd{z}.
! 324:
! 325: \fun{void}{mpinvir}{GEN x, GEN z} assigns the inverse of the integer \kbd{x}
! 326: into the real~\kbd{z}.
! 327:
! 328: \fun{void}{mpinvrr}{GEN x, GEN z} assigns the inverse of the real \kbd{x} into
! 329: the real~\kbd{z}.
! 330:
! 331: \subsec{Comparison operators}
! 332:
! 333: \fun{long}{mpcmp}{GEN x, GEN y} compares the integer or real \kbd{x} to the
! 334: integer or real~\kbd{y}. The result is the sign of $\kbd{x}-\kbd{y}$.
! 335:
! 336: \fun{long}{cmpsi}{long s, GEN x} compares the long \kbd{s} to the
! 337: integer~\kbd{x}.
! 338:
! 339: \fun{long}{cmpsr}{long s, GEN x} compares the long \kbd{s} to the real~\kbd{x}.
! 340:
! 341: \fun{long}{cmpis}{GEN x, long s} compares the integer \kbd{x} to the
! 342: long~\kbd{s}.
! 343:
! 344: \fun{long}{cmpii}{GEN x, GEN y} compares the integer \kbd{x} to the
! 345: integer~\kbd{y}.
! 346:
! 347: \fun{long}{cmpir}{GEN x, GEN y} compares the integer \kbd{x} to the
! 348: real~\kbd{y}.
! 349:
! 350: \fun{long}{cmprs}{GEN x, long s} compares the real \kbd{x} to the
! 351: long~\kbd{s}.
! 352:
! 353: \fun{long}{cmpri}{GEN x, GEN y} compares the real \kbd{x} to the
! 354: integer~\kbd{y}.
! 355:
! 356: \fun{long}{cmprr}{GEN x, GEN y} compares the real \kbd{x} to the real~\kbd{y}.
! 357:
! 358: \subsec{Binary operations}
! 359:
! 360: \noindent
! 361: Let ``\op'' be some operation of type \kbd{GEN (*)(GEN,GEN)}. The names and
! 362: prototypes of the low-level functions corresponding to \op\ will be as follows.
! 363: In this section, the \kbd{z} argument in the \kbd{z}-functions must be of type
! 364: \typ{INT} or~\typ{REAL}.
! 365:
! 366: \funno{GEN}{mp\op[z]}{GEN x, GEN y[, GEN z]} applies \op\ to
! 367: the integer-or-reals \kbd{x} and~\kbd{y}.
! 368:
! 369: \funno{GEN}{\op ss[z]}{long s, long t[, GEN z]} applies \op\ to the longs
! 370: \kbd{s} and~\kbd{t}.
! 371:
! 372: \funno{GEN}{\op si[z]}{long s, GEN x[, GEN z]} applies \op\ to the long \kbd{s}
! 373: and the integer~\kbd{x}.
! 374:
! 375: \funno{GEN}{\op sr[z]}{long s, GEN x[, GEN z]} applies \op\ to the long \kbd{s}
! 376: and the real~\kbd{x}.
! 377:
! 378: \funno{GEN}{\op is[z]}{GEN x, long s[, GEN z]} applies \op\ to the
! 379: integer \kbd{x} and the long~\kbd{s}.
! 380:
! 381: \funno{GEN}{\op ii[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the
! 382: integers \kbd{x} and~\kbd{y}.
! 383:
! 384: \funno{GEN}{\op ir[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the
! 385: integer \kbd{x} and the real~\kbd{y}.
! 386:
! 387: \funno{GEN}{\op rs[z]}{GEN x, long s[, GEN z]} applies \op\ to the real \kbd{x}
! 388: and the long~\kbd{s}.
! 389:
! 390: \funno{GEN}{\op ri[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the real \kbd{x}
! 391: and the integer~\kbd{y}.
! 392:
! 393: \funno{GEN}{\op rr[z]}{GEN x, GEN y[, GEN z]} applies \op\ to the reals \kbd{x}
! 394: and~\kbd{y}.
! 395: \smallskip
! 396: \noindent Each of the above can be used with the following operators.
! 397:
! 398: \op=\key{add}: addition (\kbd{x + y}). The result is real unless both \kbd{x}
! 399: and \kbd{y} are integers (or longs).
! 400:
! 401: \op=\key{sub}: subtraction (\kbd{x - y}). The result is real unless both
! 402: \kbd{x} and \kbd{y} are integers (or longs).
! 403:
! 404: \op=\key{mul}: multiplication (\kbd{x * y}). The result is real unless both
! 405: \kbd{x} and \kbd{y} are integers (or longs), OR if \kbd{x} or \kbd{y} is the
! 406: integer or long zero.
! 407:
! 408: \op=\key{div}: division (\kbd{x / y}). In the case where \kbd{x} and \kbd{y}
! 409: are both integers or longs, the result is the Euclidean quotient, where the
! 410: remainder has the same sign as the dividend~\kbd{x}. If one of \kbd{x} or
! 411: \kbd{y} is real, the result is real unless \kbd{x} is the integer or long
! 412: zero. A division-by-zero error occurs if \kbd{y} is equal to zero.
! 413:
! 414: \op=\key{res}: remainder (``\kbd{x \% y}''). This operation is defined only
! 415: when \kbd{x} and \kbd{y} are longs or integers. The result is the Euclidean
! 416: remainder corresponding to \kbd{div},~i.e. its sign is that of the
! 417: dividend~\kbd{x}. The result is always an integer.
! 418:
! 419: \op=\key{mod}: remainder (\kbd{x \% y}). This operation is defined only when
! 420: \kbd{x} and \kbd{y} are longs or integers. The result is the true Euclidean
! 421: remainder, i.e.~non-negative and less than the absolute value of~\kbd{y}.
! 422:
! 423: \subsec{Division with remainder}: the following functions return two objects,
! 424: unless specifically asked for only one of them~--- a quotient and a remainder.
! 425: The remainder will be created on the stack, and a \kbd{GEN} pointer to this
! 426: object will be returned through the variable whose address is passed as the
! 427: \kbd{r} argument.
! 428:
! 429: \fun{GEN}{dvmdss}{long s, long t, GEN *r} creates the Euclidean
! 430: quotient and remainder of the longs \kbd{s} and~\kbd{t}. If \kbd{r} is not
! 431: \kbd{NULL} or \kbd{ONLY\_REM}, this puts the remainder into \kbd{*r},
! 432: and returns the quotient. If \kbd{r} is equal to \kbd{NULL}, only the
! 433: quotient is returned. If \kbd{r} is equal to \kbd{ONLY\_REM}, the remainder
! 434: is returned instead of the quotient. In the generic case, the remainder is
! 435: created after the quotient and can be disposed of individually with a
! 436: \kbd{cgiv(r)}. The remainder is always of the sign of the dividend~\kbd{s}.
! 437:
! 438: \fun{GEN}{dvmdsi}{long s, GEN x, GEN *r} creates the Euclidean
! 439: quotient and remainder of the long \kbd{s} by the integer~\kbd{x}.
! 440: Obeys the same conventions with respect to~\kbd{r}.
! 441:
! 442: \fun{GEN}{dvmdis}{GEN x, long s, GEN *r} create the Euclidean
! 443: quotient and remainder of the integer x by the long~s.
! 444:
! 445: \fun{GEN}{dvmdii}{GEN x, GEN y, GEN *r} returns the Euclidean quotient
! 446: of the integer \kbd{x} by the integer \kbd{y} and puts the remainder
! 447: into~\kbd{*r}. If \kbd{r} is equal to \kbd{NULL}, the remainder is not
! 448: created, and if \kbd{r} is equal to \kbd{ONLY\_REM}, only the remainder
! 449: is created and returned. In the generic case, the remainder is created
! 450: after the quotient and can be disposed of individually with a \kbd{cgiv(r)}.
! 451: The remainder is always of the sign of the dividend~\kbd{x}.
! 452:
! 453: \fun{GEN}{truedvmdii}{GEN x, GEN y, GEN *r}, as \kbd{dvmdii} but with a
! 454: non-negative remainder.
! 455:
! 456: \fun{void}{mpdvmdz}{GEN x, GEN y, GEN z, GEN *r} assigns the Euclidean
! 457: quotient of the integers \kbd{x} and \kbd{y} into the integer or real~\kbd{z},
! 458: putting the remainder into~\kbd{*r} (unless \kbd{r} is equal to \kbd{NULL} or
! 459: \kbd{ONLY\_REM} as above).
! 460:
! 461: \fun{void}{dvmdssz}{long s, long t, GEN z, GEN *r} assigns the Euclidean
! 462: quotient of the longs \kbd{s} and \kbd{t} into the integer or real~\kbd{z},
! 463: putting the remainder into~\kbd{*r} (unless \kbd{r} is equal to \kbd{NULL} or
! 464: \kbd{ONLY\_REM} as above).
! 465:
! 466: \fun{void}{dvmdsiz}{long s, GEN x, GEN z, GEN *r} assigns the Euclidean
! 467: quotient of the long \kbd{s} and the integer \kbd{x} into the integer or
! 468: real~\kbd{z}, putting the remainder into \kbd{*r} (unless \kbd{r} is equal
! 469: to \kbd{NULL} or \kbd{ONLY\_REM} as above).
! 470:
! 471: \fun{void}{dvmdisz}{GEN x, long s, GEN z, GEN *r} assigns the Euclidean
! 472: quotient of the integer \kbd{x} and the long \kbd{s} into the integer or
! 473: real~\kbd{z}, putting the remainder into~\kbd{*r} (unless \kbd{r} is equal
! 474: to \kbd{NULL} or \kbd{ONLY\_REM} as above).
! 475:
! 476: \fun{void}{dvmdiiz}{GEN x, GEN y, GEN z, GEN *r} assigns the Euclidean
! 477: quotient of the integers \kbd{x} and \kbd{y} into the integer or real~\kbd{z},
! 478: putting the address of the remainder into~\kbd{*r} (unless \kbd{r} is equal
! 479: to \kbd{NULL} or \kbd{ONLY\_REM} as above).
! 480:
! 481: \subsec{Miscellaneous functions}
! 482:
! 483: \fun{void}{addsii}{long s, GEN x, GEN z} assigns the sum of the long \kbd{s}
! 484: and the integer \kbd{x} into the integer~\kbd{z} (essentially identical to
! 485: \kbd{addsiz} except that \kbd{z} is specifically an integer).
! 486:
! 487: \fun{long}{divise}{GEN x, GEN y} if the integer \kbd{y} divides the
! 488: integer~\kbd{x}, returns 1 (true), otherwise returns 0 (false).
! 489:
! 490: \fun{long}{divisii}{GEN x, long s, GEN z} assigns the Euclidean quotient of
! 491: the integer \kbd{x} and the long \kbd{s} into the integer \kbd{z}, and returns
! 492: the remainder as a long.
! 493:
! 494: \fun{long}{mpdivis}{GEN x, GEN y, GEN z} if the integer \kbd{y} divides the
! 495: integer~\kbd{x}, assigns the quotient to the integer~\kbd{z} and returns
! 496: 1 (true), otherwise returns 0 (false).
! 497:
! 498: \fun{void}{mulsii}{long s, GEN x, GEN z} assigns the product of the long
! 499: \kbd{s} and the integer \kbd{x} into the integer~\kbd{z} (essentially
! 500: dentical to \kbd{mulsiz} except that \kbd{z} is specifically an integer).
! 501:
! 502: \section{Level 2 kernel (operations on general PARI objects)}
! 503:
! 504: \noindent The functions available to handle subunits are the following.
! 505:
! 506: \fun{GEN}{compo}{GEN x, long n} creates a copy of the \kbd{n}-th true
! 507: component (i.e.\ not counting the codewords) of the object~\kbd{x}.
! 508:
! 509: \fun{GEN}{truecoeff}{GEN x, long n} creates a copy of the coefficient of
! 510: degree~\kbd{n} of~\kbd{x} if \kbd{x} is a scalar, polynomial or power series,
! 511: and otherwise of the \kbd{n}-th component of~\kbd{x}.
! 512:
! 513: \noindent % borderline case -- looks better like this [GN]
! 514: The remaining two are macros, NOT functions (see \secref{se:typecast} for a
! 515: detailed explanation):
! 516:
! 517: \fun{long}{coeff}{GEN x, long i, long j} applied to a matrix \kbd{x} (type
! 518: \typ{MAT}), this gives the address of the coefficient at row \kbd{i} and
! 519: column~\kbd{j} of~\kbd{x}.
! 520:
! 521: \fun{long}{mael$n$}{GEN x, long $a_1$, ..., long $a_n$} stands for
! 522: \kbd{x[$a_1$][$a_2$]...[$a_n$]}, where $2\le n \le 5$, with all the
! 523: necessary typecasts.
! 524:
! 525: \subsec{Copying and conversion}
! 526:
! 527: \fun{GEN}{cgetp}{GEN x} creates space sufficient to hold the $p$-adic~\kbd{x},
! 528: and sets the prime $p$ and the $p$-adic precision to those of~\kbd{x}, but
! 529: does not copy (the $p$-adic unit or zero representative and the modulus
! 530: of)~\kbd{x}.
! 531:
! 532: \fun{GEN}{gcopy}{GEN x} creates a new copy of the object~\kbd{x} on the PARI
! 533: stack. For permanent subobjects, only the pointer is copied.
! 534:
! 535: \fun{GEN}{forcecopy}{GEN x} same as \key{copy} except that even permanent
! 536: subobjects are copied onto the stack.
! 537:
! 538: \fun{long}{taille}{GEN x} returns the total number of \B-bit words occupied
! 539: by the tree representing~\kbd{x}.
! 540:
! 541: \fun{GEN}{gclone}{GEN x} creates a new permanent copy of the object \kbd{x}
! 542: on the heap.
! 543:
! 544: \fun{GEN}{greffe}{GEN x, long l, int use\_stack} applied to a
! 545: polynomial~\kbd{x} (type \typ{POL}), creates a power series (type \typ{SER})
! 546: of length~\kbd{l} starting with~\kbd{x}, but without actually copying the
! 547: coefficients, just the pointers. If \kbd{use\_stack} is zero, this is created
! 548: through malloc, and must be freed after use. Intended for internal use only.
! 549:
! 550: \fun{double}{rtodbl}{GEN x} applied to a real~\kbd{x} (type \typ{REAL}),
! 551: converts \kbd{x} into a C double if possible.
! 552:
! 553: \fun{GEN}{dbltor}{double x} converts the C double \kbd{x} into a PARI real.
! 554:
! 555: \fun{double}{gtodouble}{GEN x} if \kbd{x} is a real number (but not
! 556: necessarily of type \typ{REAL}), converts \kbd{x} into a C double if possible.
! 557:
! 558: \fun{long}{gtolong}{GEN x} if \kbd{x} is an integer (not a C long,
! 559: but not necessarily of type \typ{INT}), converts \kbd{x} into a C long
! 560: if possible.
! 561:
! 562: \fun{GEN}{gtopoly}{GEN x, long v} converts or truncates the object~\kbd{x}
! 563: into a polynomial with main variable number~\kbd{v}. A common application
! 564: would be the conversion of coefficient vectors.
! 565:
! 566: \fun{GEN}{gtopolyrev}{GEN x, long v} converts or truncates the object~\kbd{x}
! 567: into a polynomial with main variable number~\kbd{v}, but vectors are converted
! 568: in reverse order.
! 569:
! 570: \fun{GEN}{gtoser}{GEN x, long v} converts the object~\kbd{x} into a power
! 571: series with main variable number~\kbd{v}.
! 572:
! 573: \fun{GEN}{gtovec}{GEN x} converts the object~\kbd{x} into a (row) vector.
! 574:
! 575: \fun{GEN}{co8}{GEN x, long l} applied to a quadratic number~\kbd{x}
! 576: (type \typ{QUAD}), converts \kbd{x} into a real or complex number
! 577: depending on the sign of the discriminant of~\kbd{x}, to precision
! 578: \hbox{\kbd{l} \B-bit} words.% absolutely forbid line brk at hyphen here [GN]
! 579:
! 580: \fun{GEN}{gcvtop}{GEN x, GEN p, long l} converts \kbd{x} into a \kbd{p}-adic
! 581: number of precision~\kbd{l}.
! 582:
! 583: \fun{GEN}{gmodulcp}{GEN x, GEN y} creates the object \kbd{\key{Mod}(x,y)}
! 584: on the PARI stack, where \kbd{x} and \kbd{y} are either both integers, and
! 585: the result is an integermod (type \typ{INTMOD}), or \kbd{x} is a scalar or
! 586: a polynomial and \kbd{y} a polynomial, and the result is a polymod
! 587: (type \typ{POLMOD}).
! 588:
! 589: \fun{GEN}{gmodulgs}{GEN x, long y} same as \key{gmodulcp} except \kbd{y} is a
! 590: \kbd{long}.
! 591:
! 592: \fun{GEN}{gmodulss}{long x, long y} same as \key{gmodulcp} except both \kbd{x}
! 593: and \kbd{y} are \kbd{long}s.
! 594:
! 595: \fun{GEN}{gmodulo}{GEN x, GEN y} same as \key{gmodulcp} except that the
! 596: modulus \kbd{y} is copied onto the heap and not onto the PARI stack.
! 597:
! 598: \fun{long}{gexpo}{GEN x} returns the binary exponent of \kbd{x} or the maximal
! 599: binary exponent of the coefficients of~\kbd{x}. Returns
! 600: \hbox{\kbd{-HIGHEXPOBIT}} if \kbd{x} has no components or is an exact zero.
! 601:
! 602: \fun{long}{gsigne}{GEN x} returns the sign of~\kbd{x} ($-1$, 0 or 1) when
! 603: \kbd{x} is an integer, real or (irreducible or reducible) fraction. Raises
! 604: an error for all other types.
! 605:
! 606: \fun{long}{gvar}{GEN x} returns the main variable of~\kbd{x}. If no component
! 607: of~\kbd{x} is a polynomial or power series, this returns \kbd{BIGINT}.
! 608:
! 609: \fun{int}{precision}{GEN x} If \kbd{x} is of type \typ{REAL}, returns the
! 610: precision of~\kbd{x} (the length of \kbd{x} in \B-bit words if \kbd{x} is
! 611: not zero, and a reasonable quantity obtained from the exponent of \kbd{x}
! 612: if \kbd{x} is numerically equal to zero). If \kbd{x} is of type \typ{COMPLEX},
! 613: returns the minimum of the precisions of the real and imaginary part.
! 614: Otherwise, returns~0 (which stands in fact for infinite precision).
! 615:
! 616: \fun{long}{sizedigit}{GEN x} returns 0 if \kbd{x} is exactly~0. Otherwise,
! 617: returns \kbd{\key{gexpo}(x)} multiplied by $\log_{10}(2)$. This gives a
! 618: crude estimate for the maximal number of decimal digits of the components
! 619: of~\kbd{x}.
! 620:
! 621: \subsec{Comparison operators and valuations}
! 622:
! 623: \fun{int}{gcmp0}{GEN x} returns 1 (true) if \kbd{x} is equal to~0, 0~(false)
! 624: otherwise.
! 625:
! 626: \fun{int}{isexactzero}{GEN x} returns 1 (true) if \kbd{x} is exactly equal
! 627: to~0, 0~(false) otherwise. Note that many PARI functions will return a
! 628: pointer to \key{gzero} when they are aware that the result they return is
! 629: an exact zero, so it is almost always faster to test for pointer equality
! 630: first, and call \key{isexactzero} (or \key{gcmp0}) only when the first
! 631: test fails.
! 632:
! 633: \fun{int}{gcmp1}{GEN x} returns 1 (true) if \kbd{x} is equal to~1, 0~(false)
! 634: otherwise.
! 635:
! 636: \fun{int}{gcmp\_1}{GEN x} returns 1 (true) if \kbd{x} is equal to~$-1$,
! 637: 0~(false) otherwise.
! 638:
! 639: \fun{long}{gcmp}{GEN x, GEN y} comparison of \kbd{x} with \kbd{y} (returns
! 640: the sign of $\kbd{x}-\kbd{y}$).
! 641:
! 642: \fun{long}{gcmpsg}{long s, GEN x} comparison of the long \kbd{s} with~\kbd{x}.
! 643:
! 644: \fun{long}{gcmpgs}{GEN x, long s} comparison of \kbd{x} with the long~\kbd{s}.
! 645:
! 646: \fun{long}{lexcmp}{GEN x, GEN y} comparison of \kbd{x} with \kbd{y} for the
! 647: lexicographic ordering.
! 648:
! 649: \fun{long}{gegal}{GEN x, GEN y} returns 1 (true) if \kbd{x} is equal
! 650: to~\kbd{y}, 0~otherwise.
! 651:
! 652: \fun{long}{gegalsg}{long s, GEN x} returns 1 (true) if the long \kbd{s} is
! 653: equal to~\kbd{x}, 0~otherwise.
! 654:
! 655: \fun{long}{gegalgs}{GEN x, long s} returns 1 (true) if \kbd{x} is equal to
! 656: the long~\kbd{s}, 0~otherwise.
! 657:
! 658: \fun{long}{iscomplex}{GEN x} returns 1 (true) if \kbd{x} is a complex number
! 659: (of component types embeddable into the reals) but is not itself real, 0~if
! 660: \kbd{x} is a real (not necessarily of type \typ{REAL}), or raises an error
! 661: if \kbd{x} is not embeddable into the complex numbers.
! 662:
! 663: \fun{long}{ismonome}{GEN x} returns 1 (true) if \kbd{x} is a non-zero monomial
! 664: in its main variable, 0~otherwise.
! 665:
! 666: \fun{long}{ggval}{GEN x, GEN p} returns the greatest exponent~$e$ such that
! 667: $\kbd{p}^e$ divides~\kbd{x}, when this makes sense.
! 668:
! 669: \fun{long}{gval}{GEN x, long v} returns the highest power of the variable
! 670: number \kbd{v} dividing the polynomial~\kbd{x}.
! 671:
! 672: \fun{int}{pvaluation}{GEN x, GEN p, GEN *r} applied to non-zero integers
! 673: \kbd{x} and~\kbd{p}, returns the highest exponent $e$ such that
! 674: $\kbd{p}^{e}$ divides~\kbd{x}, creates the quotient $\kbd{x}/\kbd{p}^{e}$
! 675: and returns its address in~\kbd{*r}.
! 676: In particular, if \kbd{p} is a prime, this returns the valuation at \kbd{p}
! 677: of~\kbd{x}, and \kbd{*r} will obtain the prime-to-\kbd{p} part of~\kbd{x}.
! 678:
! 679: \subsec{Assignment statements}
! 680:
! 681: \fun{void}{gaffsg}{long s, GEN x} assigns the long \kbd{s} into the
! 682: object~\kbd{x}.
! 683:
! 684: \fun{void}{gaffect}{GEN x, GEN y} assigns the object \kbd{x} into the
! 685: object~\kbd{y}.
! 686:
! 687: \subsec{Unary operators}
! 688:
! 689: \funno{GEN}{gneg[\key{z}]}{GEN x[, GEN z]} yields $-\kbd{x}$.
! 690:
! 691: \funno{GEN}{gabs[\key{z}]}{GEN x[, GEN z]} yields $|\kbd{x}|$.
! 692:
! 693: \fun{GEN}{gsqr}{GEN x} creates the square of~\kbd{x}.
! 694:
! 695: \fun{GEN}{ginv}{GEN x} creates the inverse of~\kbd{x}.
! 696:
! 697: \fun{GEN}{gfloor}{GEN x} creates the floor of~\kbd{x}, i.e.\ the (true)
! 698: integral part.
! 699:
! 700: \fun{GEN}{gfrac}{GEN x} creates the fractional part of~\kbd{x}, i.e.\ \kbd{x}
! 701: minus the floor of~\kbd{x}.
! 702:
! 703: \fun{GEN}{gceil}{GEN x} creates the ceiling of~\kbd{x}.
! 704:
! 705: \fun{GEN}{ground}{GEN x} rounds the components of \kbd{x} to the nearest
! 706: integers. Exact half-integers are rounded towards~$+\infty$.
! 707:
! 708: \fun{GEN}{grndtoi}{GEN x, long *e} same as \key{round}, but in addition puts
! 709: minus the number of significant binary bits left after rounding into~\kbd{*e}.
! 710: If \kbd{*e} is positive, all significant bits have been lost. This kind of
! 711: situation raises an error message in \key{ground} but not in \key{grndtoi}.
! 712:
! 713: \fun{GEN}{gtrunc}{GEN x} truncates~\kbd{x}. This is the (false) integer part
! 714: if \kbd{x} is an integer (i.e.~the unique integer closest to \kbd{x} among
! 715: those between 0 and~\kbd{x}). If \kbd{x} is a series, it will be truncated
! 716: to a polynomial; if \kbd{x} is a rational function, this takes the
! 717: polynomial part.
! 718:
! 719: \fun{GEN}{gcvtoi}{GEN x, long *e} same as \key{grndtoi} except that
! 720: rounding is replaced by truncation.
! 721:
! 722: \fun{GEN}{gred[z]}{GEN x[, GEN z]} reduces \kbd{x} to lowest terms if \kbd{x}
! 723: is a fraction or rational function (types \typ{FRAC}, \typ{FRACN},
! 724: \typ{RFRAC} and \typ{RFRACN}), otherwise creates a copy of~\kbd{x}.
! 725:
! 726: \fun{GEN}{content}{GEN x} creates the GCD of all the components of~\kbd{x}.
! 727:
! 728: \fun{GEN}{normalize}{GEN x} applied to an unnormalized power series~\kbd{x}
! 729: (i.e.~type \typ{SER} with all coefficients correctly set except that \kbd{x[2]}
! 730: might be zero), normalizes \kbd{x} correctly in place. Returns~\kbd{x}.
! 731: For internal use.
! 732:
! 733: \fun{GEN}{normalizepol}{GEN x} applied to an unnormalized polynomial~\kbd{x}
! 734: (i.e.~type \typ{POL} with all coefficients correctly set except that \kbd{x[2]}
! 735: might be zero), normalizes \kbd{x} correctly in place and returns~\kbd{x}.
! 736: For internal use.
! 737:
! 738: \subsec{Binary operators}
! 739:
! 740: \fun{GEN}{gmax[z]}{GEN x, GEN y[, GEN z]} yields the maximum of the objects
! 741: \kbd{x} and~\kbd{y} if they can be compared.
! 742:
! 743: \fun{GEN}{gmaxsg[z]}{long s, GEN x[, GEN z]} yields the maximum of the long
! 744: \kbd{s} and the object~\kbd{x}.
! 745:
! 746: \fun{GEN}{gmaxgs[z]}{GEN x, long s[, GEN z]} yields the maximum of the object
! 747: \kbd{x} and the long~\kbd{s}.
! 748:
! 749: \fun{GEN}{gmin[z]}{GEN x, GEN y[, GEN z]} yields the minimum of the objects
! 750: \kbd{x} and~\kbd{y} if they can be compared.
! 751:
! 752: \fun{GEN}{gminsg[z]}{long s, GEN x[, GEN z]} yields the minimum of the long
! 753: \kbd{s} and the object~\kbd{x}.
! 754:
! 755: \fun{GEN}{gmings[z]}{GEN x, long s[, GEN z]} yields the minimum of the object
! 756: \kbd{x} and the long~\kbd{s}.
! 757:
! 758: \fun{GEN}{gadd[z]}{GEN x, GEN y[, GEN z]} yields the sum of the objects \kbd{x}
! 759: and~\kbd{y}.
! 760:
! 761: \fun{GEN}{gaddsg[z]}{long s, GEN x[, GEN z]} yields the sum of the long \kbd{s}
! 762: and the object~\kbd{x}.
! 763:
! 764: \fun{GEN}{gaddgs[z]}{GEN x, long s[, GEN z]} yields the sum of the object
! 765: \kbd{x} and the long~\kbd{s}.
! 766:
! 767: \fun{GEN}{gsub[z]}{GEN x, GEN y[, GEN z]} yields the difference of the objects
! 768: \kbd{x} and~\kbd{y}.
! 769:
! 770: \fun{GEN}{gsubgs[z]}{GEN x, long s[, GEN z]} yields the difference of the
! 771: object \kbd{x} and the long~\kbd{s}.
! 772:
! 773: \fun{GEN}{gsubsg[z]}{long s, GEN x[, GEN z]} yields the difference of the
! 774: long \kbd{s} and the object~\kbd{x}.
! 775:
! 776: \fun{GEN}{gmul[z]}{GEN x, GEN y[, GEN z]} yields the product of the objects
! 777: \kbd{x} and~\kbd{y}.
! 778:
! 779: \fun{GEN}{gmulsg[z]}{long s, GEN x[, GEN z]} yields the product of the long
! 780: \kbd{s} with the object~\kbd{x}.
! 781:
! 782: \fun{GEN}{gmulgs[z]}{GEN x, long s[, GEN z]} yields the product of the object
! 783: \kbd{x} with the long~\kbd{s}.
! 784:
! 785: \fun{GEN}{gshift[z]}{GEN x, long n[, GEN z]} yields the result of shifting
! 786: (the components of) \kbd{x} left by \kbd{n} (if \kbd{n} is non-negative)
! 787: or right by $-\kbd{n}$ (if \kbd{n} is negative).
! 788: Applies only to integers, reals and vectors/matrices of such. For other
! 789: types, it is simply multiplication by~$2^{\kbd{n}}$.
! 790:
! 791: \fun{GEN}{gmul2n[z]}{GEN x, long n[, GEN z]} yields the product of \kbd{x}
! 792: and~$2^{\kbd{n}}$. This is different from \kbd{gshift} when \kbd{n} is negative
! 793: and \kbd{x} is of type \typ{INT}: \key{gshift} truncates, while \key{gmul2n}
! 794: creates a fraction if necessary.
! 795:
! 796: \fun{GEN}{gdiv[z]}{GEN x, GEN y[, GEN z]} yields the quotient of the objects
! 797: \kbd{x} and~\kbd{y}.
! 798:
! 799: \fun{GEN}{gdivgs[z]}{GEN x, long s[, GEN z]} yields the quotient of the object
! 800: \kbd{x} and the long~\kbd{s}.
! 801:
! 802: \fun{GEN}{gdivsg[z]}{long s, GEN x[, GEN z]} yields the quotient of the long
! 803: \kbd{s} and the object~\kbd{x}.
! 804:
! 805: \fun{GEN}{gdivent[z]}{GEN x, GEN y[, GEN z]} yields the true Euclidean
! 806: quotient of \kbd{x} and the integer or polynomial~\kbd{y}.
! 807:
! 808: \fun{GEN}{gdiventsg[z]}{long s, GEN x[, GEN z]} yields the true Euclidean
! 809: quotient of the long \kbd{s} by the integer~\kbd{x}.
! 810:
! 811: \fun{GEN}{gdiventgs[z]}{GEN x, long s[, GEN z]} yields the true Euclidean
! 812: quotient of the integer \kbd{x} by the long~\kbd{s}.
! 813:
! 814: \fun{GEN}{gdiventres}{GEN x, GEN y} creates a 2-component vertical
! 815: vector whose components are the true Euclidean quotient and remainder
! 816: of \kbd{x} and~\kbd{y}.
! 817:
! 818: \fun{GEN}{gdivmod}{GEN x, GEN y, GEN *r} If \kbd{r} is not equal to
! 819: \kbd{NULL} or \kbd{ONLY\_REM}, creates the (false) Euclidean quotient of
! 820: \kbd{x} and~\kbd{y}, and puts (the address of) the remainder into~\kbd{*r}.
! 821: If \kbd{r} is equal to \kbd{NULL}, do not create the remainder, and if
! 822: \kbd{r} is equal to \kbd{ONLY\_REM}, create and output only the remainder.
! 823: The remainder is created after the quotient and can be disposed of
! 824: individually with a \kbd{cgiv(r)}.
! 825:
! 826: \fun{GEN}{poldivres}{GEN x, GEN y, GEN *r} same as \key{gdivmod} but
! 827: specifically for polynomials \kbd{x} and~\kbd{y}.
! 828:
! 829: \fun{GEN}{gdeuc}{GEN x, GEN y} creates the Euclidean quotient of the
! 830: polynomials \kbd{x} and~\kbd{y}.
! 831:
! 832: \fun{GEN}{gdivround}{GEN x, GEN y} if \kbd{x} and \kbd{y} are integers,
! 833: returns the quotient $\kbd{x}/\kbd{y}$ of \kbd{x} and~\kbd{y}, rounded to
! 834: the nearest integer. If $\kbd{x}/\kbd{y}$ falls exactly halfway between
! 835: two consecutive integers, then it is rounded towards~$+\infty$ (as for
! 836: \key{round}). If \kbd{x} and \kbd{y} are not both integers, the result
! 837: is the same as that of \key{gdivent}.
! 838:
! 839: \fun{GEN}{gmod[z]}{GEN x, GEN y[, GEN z]} yields the true remainder of \kbd{x}
! 840: modulo the integer or polynomial~\kbd{y}.
! 841:
! 842: \fun{GEN}{gmodsg[z]}{long s, GEN x[, GEN z]} yields the true remainder of the
! 843: long \kbd{s} modulo the integer~\kbd{x}.
! 844:
! 845: \fun{GEN}{gmodgs[z]}{GEN x, long s[, GEN z]} yields the true remainder of the
! 846: integer \kbd{x} modulo the long~\kbd{s}.
! 847:
! 848: \fun{GEN}{gres}{GEN x, GEN y} creates the Euclidean remainder of the
! 849: polynomial \kbd{x} divided by the polynomial~\kbd{y}.
! 850:
! 851: \fun{GEN}{ginvmod}{GEN x, GEN y} creates the inverse of \kbd{x} modulo \kbd{y}
! 852: when it exists.
! 853:
! 854: \fun{GEN}{gpow}{GEN x, GEN y, long l} creates $\kbd{x}^{\kbd{y}}$. The
! 855: precision \kbd{l} is taken into account only if \kbd{y} is not an integer
! 856: and \kbd{x} is an exact object. If \kbd{y} is an integer, binary powering
! 857: is done. Otherwise, the result is $\exp(\kbd{y}*\log(\kbd{x}))$ computed
! 858: to precision~\kbd{l}.
! 859:
! 860: \fun{GEN}{ggcd}{GEN x, GEN y} creates the GCD of \kbd{x} and~\kbd{y}.
! 861:
! 862: \fun{GEN}{glcm}{GEN x, GEN y} creates the LCM of \kbd{x} and~\kbd{y}.
! 863:
! 864: \fun{GEN}{subres}{GEN x, GEN y} creates the resultant of the polynomials
! 865: \kbd{x} and~\kbd{y} computed using the subresultant algorithm.
! 866:
! 867: \fun{GEN}{gpowgs}{GEN x, long n} creates $\kbd{x}^{\kbd{n}}$ using
! 868: binary powering.
! 869:
! 870: \fun{GEN}{gsubst}{GEN x, long v, GEN y} substitutes the object \kbd{y}
! 871: into~\kbd{x} for the variable number~\kbd{v}.
! 872:
! 873: \fun{int}{gdivise}{GEN x, GEN y} returns 1 (true) if \kbd{y} divides~\kbd{x},
! 874: 0~otherwise.
! 875:
! 876: \fun{GEN}{gbezout}{GEN x,GEN y, GEN *u,GEN *v} creates the GCD of \kbd{x}
! 877: and~\kbd{y}, and puts (the adresses of) objects $u$ and~$v$ such that
! 878: $u\kbd{x}+v\kbd{y}=\gcd(\kbd{x},\kbd{y})$ into \kbd{*u} and~\kbd{*v}.
! 879: \vfill\eject
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>