=================================================================== RCS file: /home/cvs/OpenXM_contrib/gmp/Attic/gmp.info-4,v retrieving revision 1.1.1.1 retrieving revision 1.1.1.2 diff -u -p -r1.1.1.1 -r1.1.1.2 --- OpenXM_contrib/gmp/Attic/gmp.info-4 2000/09/09 14:12:19 1.1.1.1 +++ OpenXM_contrib/gmp/Attic/gmp.info-4 2003/08/25 16:06:02 1.1.1.2 @@ -1,310 +1,1177 @@ -This is gmp.info, produced by makeinfo version 4.0 from gmp.texi. +This is gmp.info, produced by makeinfo version 4.2 from gmp.texi. +This manual describes how to install and use the GNU multiple precision +arithmetic library, version 4.1.2. + + Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, +2001, 2002 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this +document under the terms of the GNU Free Documentation License, Version +1.1 or any later version published by the Free Software Foundation; +with no Invariant Sections, with the Front-Cover Texts being "A GNU +Manual", and with the Back-Cover Texts being "You have freedom to copy +and modify this GNU Manual, like GNU software". A copy of the license +is included in *Note GNU Free Documentation License::. INFO-DIR-SECTION GNU libraries START-INFO-DIR-ENTRY * gmp: (gmp). GNU Multiple Precision Arithmetic Library. END-INFO-DIR-ENTRY - This file documents GNU MP, a library for arbitrary-precision -arithmetic. + +File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions - Copyright (C) 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000 -Free Software Foundation, Inc. +Miscellaneous Functions +======================= - Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. + - Function: void mpf_ceil (mpf_t ROP, mpf_t OP) + - Function: void mpf_floor (mpf_t ROP, mpf_t OP) + - Function: void mpf_trunc (mpf_t ROP, mpf_t OP) + Set ROP to OP rounded to an integer. `mpf_ceil' rounds to the + next higher integer, `mpf_floor' to the next lower, and `mpf_trunc' + to the integer towards zero. - Permission is granted to copy and distribute modified versions of -this manual under the conditions for verbatim copying, provided that -the entire resulting derived work is distributed under the terms of a -permission notice identical to this one. + - Function: int mpf_integer_p (mpf_t OP) + Return non-zero if OP is an integer. - Permission is granted to copy and distribute translations of this -manual into another language, under the above conditions for modified -versions, except that this permission notice may be stated in a -translation approved by the Foundation. + - Function: int mpf_fits_ulong_p (mpf_t OP) + - Function: int mpf_fits_slong_p (mpf_t OP) + - Function: int mpf_fits_uint_p (mpf_t OP) + - Function: int mpf_fits_sint_p (mpf_t OP) + - Function: int mpf_fits_ushort_p (mpf_t OP) + - Function: int mpf_fits_sshort_p (mpf_t OP) + Return non-zero if OP would fit in the respective C data type, when + truncated to an integer. + - Function: void mpf_urandomb (mpf_t ROP, gmp_randstate_t STATE, + unsigned long int NBITS) + Generate a uniformly distributed random float in ROP, such that 0 + <= ROP < 1, with NBITS significant bits in the mantissa. + + The variable STATE must be initialized by calling one of the + `gmp_randinit' functions (*Note Random State Initialization::) + before invoking this function. + + - Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t + EXP) + Generate a random float of at most MAX_SIZE limbs, with long + strings of zeros and ones in the binary representation. The + exponent of the number is in the interval -EXP to EXP. This + function is useful for testing functions and algorithms, since + this kind of random numbers have proven to be more likely to + trigger corner-case bugs. Negative random numbers are generated + when MAX_SIZE is negative. +  -File: gmp.info, Node: Function Index, Prev: Concept Index, Up: Top +File: gmp.info, Node: Low-level Functions, Next: Random Number Functions, Prev: Floating-point Functions, Up: Top -Function and Type Index +Low-level Functions +******************* + + This chapter describes low-level GMP functions, used to implement the +high-level GMP functions, but also intended for time-critical user code. + + These functions start with the prefix `mpn_'. + + The `mpn' functions are designed to be as fast as possible, *not* to +provide a coherent calling interface. The different functions have +somewhat similar interfaces, but there are variations that make them +hard to use. These functions do as little as possible apart from the +real multiple precision computation, so that no time is spent on things +that not all callers need. + + A source operand is specified by a pointer to the least significant +limb and a limb count. A destination operand is specified by just a +pointer. It is the responsibility of the caller to ensure that the +destination has enough space for storing the result. + + With this way of specifying operands, it is possible to perform +computations on subranges of an argument, and store the result into a +subrange of a destination. + + A common requirement for all functions is that each source area +needs at least one limb. No size argument may be zero. Unless +otherwise stated, in-place operations are allowed where source and +destination are the same, but not where they only partly overlap. + + The `mpn' functions are the base for the implementation of the +`mpz_', `mpf_', and `mpq_' functions. + + This example adds the number beginning at S1P and the number +beginning at S2P and writes the sum at DESTP. All areas have N limbs. + + cy = mpn_add_n (destp, s1p, s2p, n) + +In the notation used here, a source operand is identified by the +pointer to the least significant limb, and the limb count in braces. +For example, {S1P, S1N}. + + - Function: mp_limb_t mpn_add_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Add {S1P, N} and {S2P, N}, and write the N least significant limbs + of the result to RP. Return carry, either 0 or 1. + + This is the lowest-level function for addition. It is the + preferred function for addition, since it is written in assembly + for most CPUs. For addition of a variable to itself (i.e., S1P + equals S2P, use `mpn_lshift' with a count of 1 for optimal speed. + + - Function: mp_limb_t mpn_add_1 (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N, mp_limb_t S2LIMB) + Add {S1P, N} and S2LIMB, and write the N least significant limbs + of the result to RP. Return carry, either 0 or 1. + + - Function: mp_limb_t mpn_add (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) + Add {S1P, S1N} and {S2P, S2N}, and write the S1N least significant + limbs of the result to RP. Return carry, either 0 or 1. + + This function requires that S1N is greater than or equal to S2N. + + - Function: mp_limb_t mpn_sub_n (mp_limb_t *RP, const mp_limb_t *S1P, + const mp_limb_t *S2P, mp_size_t N) + Subtract {S2P, N} from {S1P, N}, and write the N least significant + limbs of the result to RP. Return borrow, either 0 or 1. + + This is the lowest-level function for subtraction. It is the + preferred function for subtraction, since it is written in + assembly for most CPUs. + + - Function: mp_limb_t mpn_sub_1 (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N, mp_limb_t S2LIMB) + Subtract S2LIMB from {S1P, N}, and write the N least significant + limbs of the result to RP. Return borrow, either 0 or 1. + + - Function: mp_limb_t mpn_sub (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) + Subtract {S2P, S2N} from {S1P, S1N}, and write the S1N least + significant limbs of the result to RP. Return borrow, either 0 or + 1. + + This function requires that S1N is greater than or equal to S2N. + + - Function: void mpn_mul_n (mp_limb_t *RP, const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Multiply {S1P, N} and {S2P, N}, and write the 2*N-limb result to + RP. + + The destination has to have space for 2*N limbs, even if the + product's most significant limb is zero. + + - Function: mp_limb_t mpn_mul_1 (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t N, mp_limb_t S2LIMB) + Multiply {S1P, N} by S2LIMB, and write the N least significant + limbs of the product to RP. Return the most significant limb of + the product. {S1P, N} and {RP, N} are allowed to overlap provided + RP <= S1P. + + This is a low-level function that is a building block for general + multiplication as well as other operations in GMP. It is written + in assembly for most CPUs. + + Don't call this function if S2LIMB is a power of 2; use + `mpn_lshift' with a count equal to the logarithm of S2LIMB + instead, for optimal speed. + + - Function: mp_limb_t mpn_addmul_1 (mp_limb_t *RP, const mp_limb_t + *S1P, mp_size_t N, mp_limb_t S2LIMB) + Multiply {S1P, N} and S2LIMB, and add the N least significant + limbs of the product to {RP, N} and write the result to RP. + Return the most significant limb of the product, plus carry-out + from the addition. + + This is a low-level function that is a building block for general + multiplication as well as other operations in GMP. It is written + in assembly for most CPUs. + + - Function: mp_limb_t mpn_submul_1 (mp_limb_t *RP, const mp_limb_t + *S1P, mp_size_t N, mp_limb_t S2LIMB) + Multiply {S1P, N} and S2LIMB, and subtract the N least significant + limbs of the product from {RP, N} and write the result to RP. + Return the most significant limb of the product, minus borrow-out + from the subtraction. + + This is a low-level function that is a building block for general + multiplication and division as well as other operations in GMP. + It is written in assembly for most CPUs. + + - Function: mp_limb_t mpn_mul (mp_limb_t *RP, const mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N) + Multiply {S1P, S1N} and {S2P, S2N}, and write the result to RP. + Return the most significant limb of the result. + + The destination has to have space for S1N + S2N limbs, even if the + result might be one limb smaller. + + This function requires that S1N is greater than or equal to S2N. + The destination must be distinct from both input operands. + + - Function: void mpn_tdiv_qr (mp_limb_t *QP, mp_limb_t *RP, mp_size_t + QXN, const mp_limb_t *NP, mp_size_t NN, const mp_limb_t *DP, + mp_size_t DN) + Divide {NP, NN} by {DP, DN} and put the quotient at {QP, NN-DN+1} + and the remainder at {RP, DN}. The quotient is rounded towards 0. + + No overlap is permitted between arguments. NN must be greater + than or equal to DN. The most significant limb of DP must be + non-zero. The QXN operand must be zero. + + - Function: mp_limb_t mpn_divrem (mp_limb_t *R1P, mp_size_t QXN, + mp_limb_t *RS2P, mp_size_t RS2N, const mp_limb_t *S3P, + mp_size_t S3N) + [This function is obsolete. Please call `mpn_tdiv_qr' instead for + best performance.] + + Divide {RS2P, RS2N} by {S3P, S3N}, and write the quotient at R1P, + with the exception of the most significant limb, which is + returned. The remainder replaces the dividend at RS2P; it will be + S3N limbs long (i.e., as many limbs as the divisor). + + In addition to an integer quotient, QXN fraction limbs are + developed, and stored after the integral limbs. For most usages, + QXN will be zero. + + It is required that RS2N is greater than or equal to S3N. It is + required that the most significant bit of the divisor is set. + + If the quotient is not needed, pass RS2P + S3N as R1P. Aside from + that special case, no overlap between arguments is permitted. + + Return the most significant limb of the quotient, either 0 or 1. + + The area at R1P needs to be RS2N - S3N + QXN limbs large. + + - Function: mp_limb_t mpn_divrem_1 (mp_limb_t *R1P, mp_size_t QXN, + mp_limb_t *S2P, mp_size_t S2N, mp_limb_t S3LIMB) + - Macro: mp_limb_t mpn_divmod_1 (mp_limb_t *R1P, mp_limb_t *S2P, + mp_size_t S2N, mp_limb_t S3LIMB) + Divide {S2P, S2N} by S3LIMB, and write the quotient at R1P. + Return the remainder. + + The integer quotient is written to {R1P+QXN, S2N} and in addition + QXN fraction limbs are developed and written to {R1P, QXN}. + Either or both S2N and QXN can be zero. For most usages, QXN will + be zero. + + `mpn_divmod_1' exists for upward source compatibility and is + simply a macro calling `mpn_divrem_1' with a QXN of 0. + + The areas at R1P and S2P have to be identical or completely + separate, not partially overlapping. + + - Function: mp_limb_t mpn_divmod (mp_limb_t *R1P, mp_limb_t *RS2P, + mp_size_t RS2N, const mp_limb_t *S3P, mp_size_t S3N) + [This function is obsolete. Please call `mpn_tdiv_qr' instead for + best performance.] + + - Macro: mp_limb_t mpn_divexact_by3 (mp_limb_t *RP, mp_limb_t *SP, + mp_size_t N) + - Function: mp_limb_t mpn_divexact_by3c (mp_limb_t *RP, mp_limb_t *SP, + mp_size_t N, mp_limb_t CARRY) + Divide {SP, N} by 3, expecting it to divide exactly, and writing + the result to {RP, N}. If 3 divides exactly, the return value is + zero and the result is the quotient. If not, the return value is + non-zero and the result won't be anything useful. + + `mpn_divexact_by3c' takes an initial carry parameter, which can be + the return value from a previous call, so a large calculation can + be done piece by piece from low to high. `mpn_divexact_by3' is + simply a macro calling `mpn_divexact_by3c' with a 0 carry + parameter. + + These routines use a multiply-by-inverse and will be faster than + `mpn_divrem_1' on CPUs with fast multiplication but slow division. + + The source a, result q, size n, initial carry i, and return value + c satisfy c*b^n + a-i = 3*q, where b=2^mp_bits_per_limb. The + return c is always 0, 1 or 2, and the initial carry i must also be + 0, 1 or 2 (these are both borrows really). When c=0 clearly + q=(a-i)/3. When c!=0, the remainder (a-i) mod 3 is given by 3-c, + because b == 1 mod 3 (when `mp_bits_per_limb' is even, which is + always so currently). + + - Function: mp_limb_t mpn_mod_1 (mp_limb_t *S1P, mp_size_t S1N, + mp_limb_t S2LIMB) + Divide {S1P, S1N} by S2LIMB, and return the remainder. S1N can be + zero. + + - Function: mp_limb_t mpn_bdivmod (mp_limb_t *RP, mp_limb_t *S1P, + mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N, unsigned + long int D) + This function puts the low floor(D/mp_bits_per_limb) limbs of Q = + {S1P, S1N}/{S2P, S2N} mod 2^D at RP, and returns the high D mod + `mp_bits_per_limb' bits of Q. + + {S1P, S1N} - Q * {S2P, S2N} mod 2^(S1N*mp_bits_per_limb) is placed + at S1P. Since the low floor(D/mp_bits_per_limb) limbs of this + difference are zero, it is possible to overwrite the low limbs at + S1P with this difference, provided RP <= S1P. + + This function requires that S1N * mp_bits_per_limb >= D, and that + {S2P, S2N} is odd. + + *This interface is preliminary. It might change incompatibly in + future revisions.* + + - Function: mp_limb_t mpn_lshift (mp_limb_t *RP, const mp_limb_t *SP, + mp_size_t N, unsigned int COUNT) + Shift {SP, N} left by COUNT bits, and write the result to {RP, N}. + The bits shifted out at the left are returned in the least + significant COUNT bits of the return value (the rest of the return + value is zero). + + COUNT must be in the range 1 to mp_bits_per_limb-1. The regions + {SP, N} and {RP, N} may overlap, provided RP >= SP. + + This function is written in assembly for most CPUs. + + - Function: mp_limb_t mpn_rshift (mp_limb_t *RP, const mp_limb_t *SP, + mp_size_t N, unsigned int COUNT) + Shift {SP, N} right by COUNT bits, and write the result to {RP, + N}. The bits shifted out at the right are returned in the most + significant COUNT bits of the return value (the rest of the return + value is zero). + + COUNT must be in the range 1 to mp_bits_per_limb-1. The regions + {SP, N} and {RP, N} may overlap, provided RP <= SP. + + This function is written in assembly for most CPUs. + + - Function: int mpn_cmp (const mp_limb_t *S1P, const mp_limb_t *S2P, + mp_size_t N) + Compare {S1P, N} and {S2P, N} and return a positive value if S1 > + S2, 0 if they are equal, or a negative value if S1 < S2. + + - Function: mp_size_t mpn_gcd (mp_limb_t *RP, mp_limb_t *S1P, + mp_size_t S1N, mp_limb_t *S2P, mp_size_t S2N) + Set {RP, RETVAL} to the greatest common divisor of {S1P, S1N} and + {S2P, S2N}. The result can be up to S2N limbs, the return value + is the actual number produced. Both source operands are destroyed. + + {S1P, S1N} must have at least as many bits as {S2P, S2N}. {S2P, + S2N} must be odd. Both operands must have non-zero most + significant limbs. No overlap is permitted between {S1P, S1N} and + {S2P, S2N}. + + - Function: mp_limb_t mpn_gcd_1 (const mp_limb_t *S1P, mp_size_t S1N, + mp_limb_t S2LIMB) + Return the greatest common divisor of {S1P, S1N} and S2LIMB. Both + operands must be non-zero. + + - Function: mp_size_t mpn_gcdext (mp_limb_t *R1P, mp_limb_t *R2P, + mp_size_t *R2N, mp_limb_t *S1P, mp_size_t S1N, mp_limb_t + *S2P, mp_size_t S2N) + Calculate the greatest common divisor of {S1P, S1N} and {S2P, + S2N}. Store the gcd at {R1P, RETVAL} and the first cofactor at + {R2P, *R2N}, with *R2N negative if the cofactor is negative. R1P + and R2P should each have room for S1N+1 limbs, but the return + value and value stored through R2N indicate the actual number + produced. + + {S1P, S1N} >= {S2P, S2N} is required, and both must be non-zero. + The regions {S1P, S1N+1} and {S2P, S2N+1} are destroyed (i.e. the + operands plus an extra limb past the end of each). + + The cofactor R1 will satisfy R2*S1 + K*S2 = R1. The second + cofactor K is not calculated but can easily be obtained from (R1 - + R2*S1) / S2. + + - Function: mp_size_t mpn_sqrtrem (mp_limb_t *R1P, mp_limb_t *R2P, + const mp_limb_t *SP, mp_size_t N) + Compute the square root of {SP, N} and put the result at {R1P, + ceil(N/2)} and the remainder at {R2P, RETVAL}. R2P needs space + for N limbs, but the return value indicates how many are produced. + + The most significant limb of {SP, N} must be non-zero. The areas + {R1P, ceil(N/2)} and {SP, N} must be completely separate. The + areas {R2P, N} and {SP, N} must be either identical or completely + separate. + + If the remainder is not wanted then R2P can be `NULL', and in this + case the return value is zero or non-zero according to whether the + remainder would have been zero or non-zero. + + A return value of zero indicates a perfect square. See also + `mpz_perfect_square_p'. + + - Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE, + mp_limb_t *S1P, mp_size_t S1N) + Convert {S1P, S1N} to a raw unsigned char array at STR in base + BASE, and return the number of characters produced. There may be + leading zeros in the string. The string is not in ASCII; to + convert it to printable format, add the ASCII codes for `0' or + `A', depending on the base and range. BASE can vary from 2 to 256. + + The most significant limb of the input {S1P, S1N} must be + non-zero. The input {S1P, S1N} is clobbered, except when BASE is + a power of 2, in which case it's unchanged. + + The area at STR has to have space for the largest possible number + represented by a S1N long limb array, plus one extra character. + + - Function: mp_size_t mpn_set_str (mp_limb_t *RP, const unsigned char + *STR, size_t STRSIZE, int BASE) + Convert bytes {STR,STRSIZE} in the given BASE to limbs at RP. + + STR[0] is the most significant byte and STR[STRSIZE-1] is the + least significant. Each byte should be a value in the range 0 to + BASE-1, not an ASCII character. BASE can vary from 2 to 256. + + The return value is the number of limbs written to RP. If the most + significant input byte is non-zero then the high limb at RP will be + non-zero, and only that exact number of limbs will be required + there. + + If the most significant input byte is zero then there may be high + zero limbs written to RP and included in the return value. + + STRSIZE must be at least 1, and no overlap is permitted between + {STR,STRSIZE} and the result at RP. + + - Function: unsigned long int mpn_scan0 (const mp_limb_t *S1P, + unsigned long int BIT) + Scan S1P from bit position BIT for the next clear bit. + + It is required that there be a clear bit within the area at S1P at + or beyond bit position BIT, so that the function has something to + return. + + - Function: unsigned long int mpn_scan1 (const mp_limb_t *S1P, + unsigned long int BIT) + Scan S1P from bit position BIT for the next set bit. + + It is required that there be a set bit within the area at S1P at or + beyond bit position BIT, so that the function has something to + return. + + - Function: void mpn_random (mp_limb_t *R1P, mp_size_t R1N) + - Function: void mpn_random2 (mp_limb_t *R1P, mp_size_t R1N) + Generate a random number of length R1N and store it at R1P. The + most significant limb is always non-zero. `mpn_random' generates + uniformly distributed limb data, `mpn_random2' generates long + strings of zeros and ones in the binary representation. + + `mpn_random2' is intended for testing the correctness of the `mpn' + routines. + + - Function: unsigned long int mpn_popcount (const mp_limb_t *S1P, + mp_size_t N) + Count the number of set bits in {S1P, N}. + + - Function: unsigned long int mpn_hamdist (const mp_limb_t *S1P, const + mp_limb_t *S2P, mp_size_t N) + Compute the hamming distance between {S1P, N} and {S2P, N}. + + - Function: int mpn_perfect_square_p (const mp_limb_t *S1P, mp_size_t + N) + Return non-zero iff {S1P, N} is a perfect square. + + +Nails +===== + + *Everything in this section is highly experimental and may disappear +or be subject to incompatible changes in a future version of GMP.* + + Nails are an experimental feature whereby a few bits are left unused +at the top of each `mp_limb_t'. This can significantly improve carry +handling on some processors. + + All the `mpn' functions accepting limb data will expect the nail +bits to be zero on entry, and will return data with the nails similarly +all zero. This applies both to limb vectors and to single limb +arguments. + + Nails can be enabled by configuring with `--enable-nails'. By +default the number of bits will be chosen according to what suits the +host processor, but a particular number can be selected with +`--enable-nails=N'. + + At the mpn level, a nail build is neither source nor binary +compatible with a non-nail build, strictly speaking. But programs +acting on limbs only through the mpn functions are likely to work +equally well with either build, and judicious use of the definitions +below should make any program compatible with either build, at the +source level. + + For the higher level routines, meaning `mpz' etc, a nail build +should be fully source and binary compatible with a non-nail build. + + - Macro: GMP_NAIL_BITS + - Macro: GMP_NUMB_BITS + - Macro: GMP_LIMB_BITS + `GMP_NAIL_BITS' is the number of nail bits, or 0 when nails are + not in use. `GMP_NUMB_BITS' is the number of data bits in a limb. + `GMP_LIMB_BITS' is the total number of bits in an `mp_limb_t'. In + all cases + + GMP_LIMB_BITS == GMP_NAIL_BITS + GMP_NUMB_BITS + + - Macro: GMP_NAIL_MASK + - Macro: GMP_NUMB_MASK + Bit masks for the nail and number parts of a limb. + `GMP_NAIL_MASK' is 0 when nails are not in use. + + `GMP_NAIL_MASK' is not often needed, since the nail part can be + obtained with `x >> GMP_NUMB_BITS', and that means one less large + constant, which can help various RISC chips. + + - Macro: GMP_NUMB_MAX + The maximum value that can be stored in the number part of a limb. + This is the same as `GMP_NUMB_MASK', but can be used for clarity + when doing comparisons rather than bit-wise operations. + + The term "nails" comes from finger or toe nails, which are at the +ends of a limb (arm or leg). "numb" is short for number, but is also +how the developers felt after trying for a long time to come up with +sensible names for these things. + + In the future (the distant future most likely) a non-zero nail might +be permitted, giving non-unique representations for numbers in a limb +vector. This would help vector processors since carries would only +ever need to propagate one or two limbs. + + +File: gmp.info, Node: Random Number Functions, Next: Formatted Output, Prev: Low-level Functions, Up: Top + +Random Number Functions *********************** + Sequences of pseudo-random numbers in GMP are generated using a +variable of type `gmp_randstate_t', which holds an algorithm selection +and a current state. Such a variable must be initialized by a call to +one of the `gmp_randinit' functions, and can be seeded with one of the +`gmp_randseed' functions. + + The functions actually generating random numbers are described in +*Note Integer Random Numbers::, and *Note Miscellaneous Float +Functions::. + + The older style random number functions don't accept a +`gmp_randstate_t' parameter but instead share a global variable of that +type. They use a default algorithm and are currently not seeded +(though perhaps that will change in the future). The new functions +accepting a `gmp_randstate_t' are recommended for applications that +care about randomness. + * Menu: -* __GNU_MP_VERSION: Useful Macros and Constants. -* __GNU_MP_VERSION_MINOR: Useful Macros and Constants. -* __GNU_MP_VERSION_PATCHLEVEL: Useful Macros and Constants. -* _mpz_realloc: Initializing Integers. -* allocate_function: Custom Allocation. -* deallocate_function: Custom Allocation. -* gcd: BSD Compatible Functions. -* gmp_randclear: Random State Initialization. -* gmp_randinit: Random State Initialization. -* gmp_randinit_lc_2exp: Random State Initialization. -* gmp_randseed: Random State Initialization. -* gmp_randseed_ui: Random State Initialization. -* itom: BSD Compatible Functions. -* madd: BSD Compatible Functions. -* mcmp: BSD Compatible Functions. -* mdiv: BSD Compatible Functions. -* mfree: BSD Compatible Functions. -* min: BSD Compatible Functions. -* mout: BSD Compatible Functions. -* move: BSD Compatible Functions. -* mp_limb_t: Nomenclature and Types. -* mp_set_memory_functions: Custom Allocation. -* mpf_abs: Float Arithmetic. -* mpf_add: Float Arithmetic. -* mpf_add_ui: Float Arithmetic. -* mpf_ceil: Miscellaneous Float Functions. -* mpf_clear: Initializing Floats. -* mpf_cmp: Float Comparison. -* mpf_cmp_si: Float Comparison. -* mpf_cmp_ui: Float Comparison. -* mpf_div: Float Arithmetic. -* mpf_div_2exp: Float Arithmetic. -* mpf_div_ui: Float Arithmetic. -* mpf_eq: Float Comparison. -* mpf_floor: Miscellaneous Float Functions. -* mpf_get_d: Converting Floats. -* mpf_get_prec: Initializing Floats. -* mpf_get_str: Converting Floats. -* mpf_init: Initializing Floats. -* mpf_init2: Initializing Floats. -* mpf_init_set: Simultaneous Float Init & Assign. -* mpf_init_set_d: Simultaneous Float Init & Assign. -* mpf_init_set_si: Simultaneous Float Init & Assign. -* mpf_init_set_str: Simultaneous Float Init & Assign. -* mpf_init_set_ui: Simultaneous Float Init & Assign. -* mpf_inp_str: I/O of Floats. -* mpf_mul: Float Arithmetic. -* mpf_mul_2exp: Float Arithmetic. -* mpf_mul_ui: Float Arithmetic. -* mpf_neg: Float Arithmetic. -* mpf_out_str: I/O of Floats. -* mpf_pow_ui: Float Arithmetic. -* mpf_random2: Miscellaneous Float Functions. -* mpf_reldiff: Float Comparison. -* mpf_set: Assigning Floats. -* mpf_set_d: Assigning Floats. -* mpf_set_default_prec: Initializing Floats. -* mpf_set_prec: Initializing Floats. -* mpf_set_prec_raw: Initializing Floats. -* mpf_set_q: Assigning Floats. -* mpf_set_si: Assigning Floats. -* mpf_set_str: Assigning Floats. -* mpf_set_ui: Assigning Floats. -* mpf_set_z: Assigning Floats. -* mpf_sgn: Float Comparison. -* mpf_sqrt: Float Arithmetic. -* mpf_sqrt_ui: Float Arithmetic. -* mpf_sub: Float Arithmetic. -* mpf_sub_ui: Float Arithmetic. -* mpf_swap: Assigning Floats. -* mpf_t: Nomenclature and Types. -* mpf_trunc: Miscellaneous Float Functions. -* mpf_ui_div: Float Arithmetic. -* mpf_ui_sub: Float Arithmetic. -* mpf_urandomb: Miscellaneous Float Functions. -* mpn_add: Low-level Functions. -* mpn_add_1: Low-level Functions. -* mpn_add_n: Low-level Functions. -* mpn_addmul_1: Low-level Functions. -* mpn_bdivmod: Low-level Functions. -* mpn_cmp: Low-level Functions. -* mpn_divexact_by3: Low-level Functions. -* mpn_divexact_by3c: Low-level Functions. -* mpn_divmod: Low-level Functions. -* mpn_divmod_1: Low-level Functions. -* mpn_divrem: Low-level Functions. -* mpn_divrem_1: Low-level Functions. -* mpn_gcd: Low-level Functions. -* mpn_gcd_1: Low-level Functions. -* mpn_gcdext: Low-level Functions. -* mpn_get_str: Low-level Functions. -* mpn_hamdist: Low-level Functions. -* mpn_lshift: Low-level Functions. -* mpn_mod_1: Low-level Functions. -* mpn_mul: Low-level Functions. -* mpn_mul_1: Low-level Functions. -* mpn_mul_n: Low-level Functions. -* mpn_perfect_square_p: Low-level Functions. -* mpn_popcount: Low-level Functions. -* mpn_preinv_mod_1: Low-level Functions. -* mpn_random: Low-level Functions. -* mpn_random2: Low-level Functions. -* mpn_rshift: Low-level Functions. -* mpn_scan0: Low-level Functions. -* mpn_scan1: Low-level Functions. -* mpn_set_str: Low-level Functions. -* mpn_sqrtrem: Low-level Functions. -* mpn_sub: Low-level Functions. -* mpn_sub_1: Low-level Functions. -* mpn_sub_n: Low-level Functions. -* mpn_submul_1: Low-level Functions. -* mpn_tdiv_qr: Low-level Functions. -* mpq_add: Rational Arithmetic. -* mpq_canonicalize: Rational Number Functions. -* mpq_clear: Initializing Rationals. -* mpq_cmp: Comparing Rationals. -* mpq_cmp_ui: Comparing Rationals. -* mpq_denref: Applying Integer Functions. -* mpq_div: Rational Arithmetic. -* mpq_equal: Comparing Rationals. -* mpq_get_d: Miscellaneous Rational Functions. -* mpq_get_den: Miscellaneous Rational Functions. -* mpq_get_num: Miscellaneous Rational Functions. -* mpq_init: Initializing Rationals. -* mpq_inv: Rational Arithmetic. -* mpq_mul: Rational Arithmetic. -* mpq_neg: Rational Arithmetic. -* mpq_numref: Applying Integer Functions. -* mpq_out_str: I/O of Rationals. -* mpq_set: Initializing Rationals. -* mpq_set_d: Miscellaneous Rational Functions. -* mpq_set_den: Miscellaneous Rational Functions. -* mpq_set_num: Miscellaneous Rational Functions. -* mpq_set_si: Initializing Rationals. -* mpq_set_ui: Initializing Rationals. -* mpq_set_z: Initializing Rationals. -* mpq_sgn: Comparing Rationals. -* mpq_sub: Rational Arithmetic. -* mpq_swap: Initializing Rationals. -* mpq_t: Nomenclature and Types. -* mpz_abs: Integer Arithmetic. -* mpz_add: Integer Arithmetic. -* mpz_add_ui: Integer Arithmetic. -* mpz_addmul_ui: Integer Arithmetic. -* mpz_and: Integer Logic and Bit Fiddling. -* mpz_array_init: Initializing Integers. -* mpz_bin_ui: Number Theoretic Functions. -* mpz_bin_uiui: Number Theoretic Functions. -* mpz_cdiv_q: Integer Division. -* mpz_cdiv_q_ui: Integer Division. -* mpz_cdiv_qr: Integer Division. -* mpz_cdiv_qr_ui: Integer Division. -* mpz_cdiv_r: Integer Division. -* mpz_cdiv_r_ui: Integer Division. -* mpz_cdiv_ui: Integer Division. -* mpz_clear: Initializing Integers. -* mpz_clrbit: Integer Logic and Bit Fiddling. -* mpz_cmp: Integer Comparisons. -* mpz_cmp_si: Integer Comparisons. -* mpz_cmp_ui: Integer Comparisons. -* mpz_cmpabs: Integer Comparisons. -* mpz_cmpabs_ui: Integer Comparisons. -* mpz_com: Integer Logic and Bit Fiddling. -* mpz_divexact: Integer Division. -* mpz_even_p: Miscellaneous Integer Functions. -* mpz_fac_ui: Number Theoretic Functions. -* mpz_fdiv_q: Integer Division. -* mpz_fdiv_q_2exp: Integer Division. -* mpz_fdiv_q_ui: Integer Division. -* mpz_fdiv_qr: Integer Division. -* mpz_fdiv_qr_ui: Integer Division. -* mpz_fdiv_r: Integer Division. -* mpz_fdiv_r_2exp: Integer Division. -* mpz_fdiv_r_ui: Integer Division. -* mpz_fdiv_ui: Integer Division. -* mpz_fib_ui: Number Theoretic Functions. -* mpz_fits_sint_p: Miscellaneous Integer Functions. -* mpz_fits_slong_p: Miscellaneous Integer Functions. -* mpz_fits_sshort_p: Miscellaneous Integer Functions. -* mpz_fits_uint_p: Miscellaneous Integer Functions. -* mpz_fits_ulong_p: Miscellaneous Integer Functions. -* mpz_fits_ushort_p: Miscellaneous Integer Functions. -* mpz_gcd: Number Theoretic Functions. -* mpz_gcd_ui: Number Theoretic Functions. -* mpz_gcdext: Number Theoretic Functions. -* mpz_get_d: Converting Integers. -* mpz_get_si: Converting Integers. -* mpz_get_str: Converting Integers. -* mpz_get_ui: Converting Integers. -* mpz_getlimbn: Converting Integers. -* mpz_hamdist: Integer Logic and Bit Fiddling. -* mpz_init: Initializing Integers. -* mpz_init_set: Simultaneous Integer Init & Assign. -* mpz_init_set_d: Simultaneous Integer Init & Assign. -* mpz_init_set_si: Simultaneous Integer Init & Assign. -* mpz_init_set_str: Simultaneous Integer Init & Assign. -* mpz_init_set_ui: Simultaneous Integer Init & Assign. -* mpz_inp_raw: I/O of Integers. -* mpz_inp_str: I/O of Integers. -* mpz_invert: Number Theoretic Functions. -* mpz_ior: Integer Logic and Bit Fiddling. -* mpz_jacobi: Number Theoretic Functions. -* mpz_kronecker_si: Number Theoretic Functions. -* mpz_kronecker_ui: Number Theoretic Functions. -* mpz_lcm: Number Theoretic Functions. -* mpz_legendre: Number Theoretic Functions. -* mpz_mod: Integer Division. -* mpz_mod_ui: Integer Division. -* mpz_mul: Integer Arithmetic. -* mpz_mul_2exp: Integer Arithmetic. -* mpz_mul_si: Integer Arithmetic. -* mpz_mul_ui: Integer Arithmetic. -* mpz_neg: Integer Arithmetic. -* mpz_nextprime: Number Theoretic Functions. -* mpz_odd_p: Miscellaneous Integer Functions. -* mpz_out_raw: I/O of Integers. -* mpz_out_str: I/O of Integers. -* mpz_perfect_power_p: Integer Roots. -* mpz_perfect_square_p: Integer Roots. -* mpz_popcount: Integer Logic and Bit Fiddling. -* mpz_pow_ui: Integer Exponentiation. -* mpz_powm: Integer Exponentiation. -* mpz_powm_ui: Integer Exponentiation. -* mpz_probab_prime_p: Number Theoretic Functions. -* mpz_random: Integer Random Numbers. -* mpz_random2: Integer Random Numbers. -* mpz_remove: Number Theoretic Functions. -* mpz_root: Integer Roots. -* mpz_rrandomb: Integer Random Numbers. -* mpz_scan0: Integer Logic and Bit Fiddling. -* mpz_scan1: Integer Logic and Bit Fiddling. -* mpz_set: Assigning Integers. -* mpz_set_d: Assigning Integers. -* mpz_set_f: Assigning Integers. -* mpz_set_q: Assigning Integers. -* mpz_set_si: Assigning Integers. -* mpz_set_str: Assigning Integers. -* mpz_set_ui: Assigning Integers. -* mpz_setbit: Integer Logic and Bit Fiddling. -* mpz_sgn: Integer Comparisons. -* mpz_si_kronecker: Number Theoretic Functions. -* mpz_size: Miscellaneous Integer Functions. -* mpz_sizeinbase: Miscellaneous Integer Functions. -* mpz_sqrt: Integer Roots. -* mpz_sqrtrem: Integer Roots. -* mpz_sub: Integer Arithmetic. -* mpz_sub_ui: Integer Arithmetic. -* mpz_swap: Assigning Integers. -* mpz_t: Nomenclature and Types. -* mpz_tdiv_q: Integer Division. -* mpz_tdiv_q_2exp: Integer Division. -* mpz_tdiv_q_ui: Integer Division. -* mpz_tdiv_qr: Integer Division. -* mpz_tdiv_qr_ui: Integer Division. -* mpz_tdiv_r: Integer Division. -* mpz_tdiv_r_2exp: Integer Division. -* mpz_tdiv_r_ui: Integer Division. -* mpz_tdiv_ui: Integer Division. -* mpz_tstbit: Integer Logic and Bit Fiddling. -* mpz_ui_kronecker: Number Theoretic Functions. -* mpz_ui_pow_ui: Integer Exponentiation. -* mpz_urandomb: Integer Random Numbers. -* mpz_urandomm: Integer Random Numbers. -* mpz_xor: Integer Logic and Bit Fiddling. -* msqrt: BSD Compatible Functions. -* msub: BSD Compatible Functions. -* mtox: BSD Compatible Functions. -* mult: BSD Compatible Functions. -* pow: BSD Compatible Functions. -* reallocate_function: Custom Allocation. -* rpow: BSD Compatible Functions. -* sdiv: BSD Compatible Functions. -* xtom: BSD Compatible Functions. +* Random State Initialization:: +* Random State Seeding:: + +File: gmp.info, Node: Random State Initialization, Next: Random State Seeding, Prev: Random Number Functions, Up: Random Number Functions + +Random State Initialization +=========================== + + - Function: void gmp_randinit_default (gmp_randstate_t STATE) + Initialize STATE with a default algorithm. This will be a + compromise between speed and randomness, and is recommended for + applications with no special requirements. + + - Function: void gmp_randinit_lc_2exp (gmp_randstate_t STATE, mpz_t A, + unsigned long C, unsigned long M2EXP) + Initialize STATE with a linear congruential algorithm X = (A*X + + C) mod 2^M2EXP. + + The low bits of X in this algorithm are not very random. The least + significant bit will have a period no more than 2, and the second + bit no more than 4, etc. For this reason only the high half of + each X is actually used. + + When a random number of more than M2EXP/2 bits is to be generated, + multiple iterations of the recurrence are used and the results + concatenated. + + - Function: int gmp_randinit_lc_2exp_size (gmp_randstate_t STATE, + unsigned long SIZE) + Initialize STATE for a linear congruential algorithm as per + `gmp_randinit_lc_2exp'. A, C and M2EXP are selected from a table, + chosen so that SIZE bits (or more) of each X will be used, ie. + M2EXP/2 >= SIZE. + + If successful the return value is non-zero. If SIZE is bigger + than the table data provides then the return value is zero. The + maximum SIZE currently supported is 128. + + - Function: void gmp_randinit (gmp_randstate_t STATE, + gmp_randalg_t ALG, ...) + *This function is obsolete.* + + Initialize STATE with an algorithm selected by ALG. The only + choice is `GMP_RAND_ALG_LC', which is `gmp_randinit_lc_2exp_size'. + A third parameter of type `unsigned long' is required, this is the + SIZE for that function. `GMP_RAND_ALG_DEFAULT' or 0 are the same + as `GMP_RAND_ALG_LC'. + + `gmp_randinit' sets bits in `gmp_errno' to indicate an error. + `GMP_ERROR_UNSUPPORTED_ARGUMENT' if ALG is unsupported, or + `GMP_ERROR_INVALID_ARGUMENT' if the SIZE parameter is too big. + + - Function: void gmp_randclear (gmp_randstate_t STATE) + Free all memory occupied by STATE. + + +File: gmp.info, Node: Random State Seeding, Prev: Random State Initialization, Up: Random Number Functions + +Random State Seeding +==================== + + - Function: void gmp_randseed (gmp_randstate_t STATE, mpz_t SEED) + - Function: void gmp_randseed_ui (gmp_randstate_t STATE, + unsigned long int SEED) + Set an initial seed value into STATE. + + The size of a seed determines how many different sequences of + random numbers that it's possible to generate. The "quality" of + the seed is the randomness of a given seed compared to the + previous seed used, and this affects the randomness of separate + number sequences. The method for choosing a seed is critical if + the generated numbers are to be used for important applications, + such as generating cryptographic keys. + + Traditionally the system time has been used to seed, but care + needs to be taken with this. If an application seeds often and + the resolution of the system clock is low, then the same sequence + of numbers might be repeated. Also, the system time is quite easy + to guess, so if unpredictability is required then it should + definitely not be the only source for the seed value. On some + systems there's a special device `/dev/random' which provides + random data better suited for use as a seed. + + +File: gmp.info, Node: Formatted Output, Next: Formatted Input, Prev: Random Number Functions, Up: Top + +Formatted Output +**************** + +* Menu: + +* Formatted Output Strings:: +* Formatted Output Functions:: +* C++ Formatted Output:: + + +File: gmp.info, Node: Formatted Output Strings, Next: Formatted Output Functions, Prev: Formatted Output, Up: Formatted Output + +Format Strings +============== + + `gmp_printf' and friends accept format strings similar to the +standard C `printf' (*note Formatted Output: (libc)Formatted Output.). +A format specification is of the form + + % [flags] [width] [.[precision]] [type] conv + + GMP adds types `Z', `Q' and `F' for `mpz_t', `mpq_t' and `mpf_t' +respectively, and `N' for an `mp_limb_t' array. `Z', `Q' and `N' +behave like integers. `Q' will print a `/' and a denominator, if +needed. `F' behaves like a float. For example, + + mpz_t z; + gmp_printf ("%s is an mpz %Zd\n", "here", z); + + mpq_t q; + gmp_printf ("a hex rational: %#40Qx\n", q); + + mpf_t f; + int n; + gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n); + + const mp_limb_t *ptr; + mp_size_t size; + gmp_printf ("limb array %Nx\n", ptr, size); + + For `N' the limbs are expected least significant first, as per the +`mpn' functions (*note Low-level Functions::). A negative size can be +given to print the value as a negative. + + All the standard C `printf' types behave the same as the C library +`printf', and can be freely intermixed with the GMP extensions. In the +current implementation the standard parts of the format string are +simply handed to `printf' and only the GMP extensions handled directly. + + The flags accepted are as follows. GLIBC style ' is only for the +standard C types (not the GMP types), and only if the C library +supports it. + + 0 pad with zeros (rather than spaces) + # show the base with `0x', `0X' or `0' + + always show a sign + (space) show a space or a `-' sign + ' group digits, GLIBC style (not GMP types) + + The optional width and precision can be given as a number within the +format string, or as a `*' to take an extra parameter of type `int', the +same as the standard `printf'. + + The standard types accepted are as follows. `h' and `l' are +portable, the rest will depend on the compiler (or include files) for +the type and the C library for the output. + + h short + hh char + j intmax_t or uintmax_t + l long or wchar_t + ll long long + L long double + q quad_t or u_quad_t + t ptrdiff_t + z size_t + +The GMP types are + + F mpf_t, float conversions + Q mpq_t, integer conversions + N mp_limb_t array, integer conversions + Z mpz_t, integer conversions + + The conversions accepted are as follows. `a' and `A' are always +supported for `mpf_t' but depend on the C library for standard C float +types. `m' and `p' depend on the C library. + + a A hex floats, C99 style + c character + d decimal integer + e E scientific format float + f fixed point float + i same as d + g G fixed or scientific float + m `strerror' string, GLIBC style + n store characters written so far + o octal integer + p pointer + s string + u unsigned integer + x X hex integer + + `o', `x' and `X' are unsigned for the standard C types, but for +types `Z', `Q' and `N' they are signed. `u' is not meaningful for `Z', +`Q' and `N'. + + `n' can be used with any type, even the GMP types. + + Other types or conversions that might be accepted by the C library +`printf' cannot be used through `gmp_printf', this includes for +instance extensions registered with GLIBC `register_printf_function'. +Also currently there's no support for POSIX `$' style numbered arguments +(perhaps this will be added in the future). + + The precision field has it's usual meaning for integer `Z' and float +`F' types, but is currently undefined for `Q' and should not be used +with that. + + `mpf_t' conversions only ever generate as many digits as can be +accurately represented by the operand, the same as `mpf_get_str' does. +Zeros will be used if necessary to pad to the requested precision. This +happens even for an `f' conversion of an `mpf_t' which is an integer, +for instance 2^1024 in an `mpf_t' of 128 bits precision will only +produce about 40 digits, then pad with zeros to the decimal point. An +empty precision field like `%.Fe' or `%.Ff' can be used to specifically +request just the significant digits. + + The decimal point character (or string) is taken from the current +locale settings on systems which provide `localeconv' (*note Locales +and Internationalization: (libc)Locales.). The C library will normally +do the same for standard float output. + + The format string is only interpreted as plain `char's, multibyte +characters are not recognised. Perhaps this will change in the future. + + +File: gmp.info, Node: Formatted Output Functions, Next: C++ Formatted Output, Prev: Formatted Output Strings, Up: Formatted Output + +Functions +========= + + Each of the following functions is similar to the corresponding C +library function. The basic `printf' forms take a variable argument +list. The `vprintf' forms take an argument pointer, see *Note Variadic +Functions: (libc)Variadic Functions, or `man 3 va_start'. + + It should be emphasised that if a format string is invalid, or the +arguments don't match what the format specifies, then the behaviour of +any of these functions will be unpredictable. GCC format string +checking is not available, since it doesn't recognise the GMP +extensions. + + The file based functions `gmp_printf' and `gmp_fprintf' will return +-1 to indicate a write error. All the functions can return -1 if the C +library `printf' variant in use returns -1, but this shouldn't normally +occur. + + - Function: int gmp_printf (const char *FMT, ...) + - Function: int gmp_vprintf (const char *FMT, va_list AP) + Print to the standard output `stdout'. Return the number of + characters written, or -1 if an error occurred. + + - Function: int gmp_fprintf (FILE *FP, const char *FMT, ...) + - Function: int gmp_vfprintf (FILE *FP, const char *FMT, va_list AP) + Print to the stream FP. Return the number of characters written, + or -1 if an error occurred. + + - Function: int gmp_sprintf (char *BUF, const char *FMT, ...) + - Function: int gmp_vsprintf (char *BUF, const char *FMT, va_list AP) + Form a null-terminated string in BUF. Return the number of + characters written, excluding the terminating null. + + No overlap is permitted between the space at BUF and the string + FMT. + + These functions are not recommended, since there's no protection + against exceeding the space available at BUF. + + - Function: int gmp_snprintf (char *BUF, size_t SIZE, const char *FMT, + ...) + - Function: int gmp_vsnprintf (char *BUF, size_t SIZE, const char + *FMT, va_list AP) + Form a null-terminated string in BUF. No more than SIZE bytes + will be written. To get the full output, SIZE must be enough for + the string and null-terminator. + + The return value is the total number of characters which ought to + have been produced, excluding the terminating null. If RETVAL >= + SIZE then the actual output has been truncated to the first SIZE-1 + characters, and a null appended. + + No overlap is permitted between the region {BUF,SIZE} and the FMT + string. + + Notice the return value is in ISO C99 `snprintf' style. This is + so even if the C library `vsnprintf' is the older GLIBC 2.0.x + style. + + - Function: int gmp_asprintf (char **PP, const char *FMT, ...) + - Function: int gmp_vasprintf (char *PP, const char *FMT, va_list AP) + Form a null-terminated string in a block of memory obtained from + the current memory allocation function (*note Custom + Allocation::). The block will be the size of the string and + null-terminator. Put the address of the block in *PP. Return the + number of characters produced, excluding the null-terminator. + + Unlike the C library `asprintf', `gmp_asprintf' doesn't return -1 + if there's no more memory available, it lets the current allocation + function handle that. + + - Function: int gmp_obstack_printf (struct obstack *OB, const char + *FMT, ...) + - Function: int gmp_obstack_vprintf (struct obstack *OB, const char + *FMT, va_list AP) + Append to the current obstack object, in the same style as + `obstack_printf'. Return the number of characters written. A + null-terminator is not written. + + FMT cannot be within the current obstack object, since the object + might move as it grows. + + These functions are available only when the C library provides the + obstack feature, which probably means only on GNU systems, see + *Note Obstacks: (libc)Obstacks. + + +File: gmp.info, Node: C++ Formatted Output, Prev: Formatted Output Functions, Up: Formatted Output + +C++ Formatted Output +==================== + + The following functions are provided in `libgmpxx', which is built +if C++ support is enabled (*note Build Options::). Prototypes are +available from `'. + + - Function: ostream& operator<< (ostream& STREAM, mpz_t OP) + Print OP to STREAM, using its `ios' formatting settings. + `ios::width' is reset to 0 after output, the same as the standard + `ostream operator<<' routines do. + + In hex or octal, OP is printed as a signed number, the same as for + decimal. This is unlike the standard `operator<<' routines on + `int' etc, which instead give twos complement. + + - Function: ostream& operator<< (ostream& STREAM, mpq_t OP) + Print OP to STREAM, using its `ios' formatting settings. + `ios::width' is reset to 0 after output, the same as the standard + `ostream operator<<' routines do. + + Output will be a fraction like `5/9', or if the denominator is 1 + then just a plain integer like `123'. + + In hex or octal, OP is printed as a signed value, the same as for + decimal. If `ios::showbase' is set then a base indicator is shown + on both the numerator and denominator (if the denominator is + required). + + - Function: ostream& operator<< (ostream& STREAM, mpf_t OP) + Print OP to STREAM, using its `ios' formatting settings. + `ios::width' is reset to 0 after output, the same as the standard + `ostream operator<<' routines do. The decimal point follows the + current locale, on systems providing `localeconv'. + + Hex and octal are supported, unlike the standard `operator<<' on + `double'. The mantissa will be in hex or octal, the exponent will + be in decimal. For hex the exponent delimiter is an `@'. This is + as per `mpf_out_str'. + + `ios::showbase' is supported, and will put a base on the mantissa, + for example hex `0x1.8' or `0x0.8', or octal `01.4' or `00.4'. + This last form is slightly strange, but at least differentiates + itself from decimal. + + These operators mean that GMP types can be printed in the usual C++ +way, for example, + + mpz_t z; + int n; + ... + cout << "iteration " << n << " value " << z << "\n"; + + But note that `ostream' output (and `istream' input, *note C++ +Formatted Input::) is the only overloading available and using for +instance `+' with an `mpz_t' will have unpredictable results. + + +File: gmp.info, Node: Formatted Input, Next: C++ Class Interface, Prev: Formatted Output, Up: Top + +Formatted Input +*************** + +* Menu: + +* Formatted Input Strings:: +* Formatted Input Functions:: +* C++ Formatted Input:: + + +File: gmp.info, Node: Formatted Input Strings, Next: Formatted Input Functions, Prev: Formatted Input, Up: Formatted Input + +Formatted Input Strings +======================= + + `gmp_scanf' and friends accept format strings similar to the +standard C `scanf' (*note Formatted Input: (libc)Formatted Input.). A +format specification is of the form + + % [flags] [width] [type] conv + + GMP adds types `Z', `Q' and `F' for `mpz_t', `mpq_t' and `mpf_t' +respectively. `Z' and `Q' behave like integers. `Q' will read a `/' +and a denominator, if present. `F' behaves like a float. + + GMP variables don't require an `&' when passed to `gmp_scanf', since +they're already "call-by-reference". For example, + + /* to read say "a(5) = 1234" */ + int n; + mpz_t z; + gmp_scanf ("a(%d) = %Zd\n", &n, z); + + mpq_t q1, q2; + gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2); + + /* to read say "topleft (1.55,-2.66)" */ + mpf_t x, y; + char buf[32]; + gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y); + + All the standard C `scanf' types behave the same as in the C library +`scanf', and can be freely intermixed with the GMP extensions. In the +current implementation the standard parts of the format string are +simply handed to `scanf' and only the GMP extensions handled directly. + + The flags accepted are as follows. `a' and `'' will depend on +support from the C library, and `'' cannot be used with GMP types. + + * read but don't store + a allocate a buffer (string conversions) + ' group digits, GLIBC style (not GMP types) + + The standard types accepted are as follows. `h' and `l' are +portable, the rest will depend on the compiler (or include files) for +the type and the C library for the input. + + h short + hh char + j intmax_t or uintmax_t + l long int, double or wchar_t + ll long long + L long double + q quad_t or u_quad_t + t ptrdiff_t + z size_t + +The GMP types are + + F mpf_t, float conversions + Q mpq_t, integer conversions + Z mpz_t, integer conversions + + The conversions accepted are as follows. `p' and `[' will depend on +support from the C library, the rest are standard. + + c character or characters + d decimal integer + e E f g G float + i integer with base indicator + n characters read so far + o octal integer + p pointer + s string of non-whitespace characters + u decimal integer + x X hex integer + [ string of characters in a set + + `e', `E', `f', `g' and `G' are identical, they all read either fixed +point or scientific format, and either `e' or `E' for the exponent in +scientific format. + + `x' and `X' are identical, both accept both upper and lower case +hexadecimal. + + `o', `u', `x' and `X' all read positive or negative values. For the +standard C types these are described as "unsigned" conversions, but +that merely affects certain overflow handling, negatives are still +allowed (see `strtoul', *Note Parsing of Integers: (libc)Parsing of +Integers). For GMP types there are no overflows, and `d' and `u' are +identical. + + `Q' type reads the numerator and (optional) denominator as given. +If the value might not be in canonical form then `mpq_canonicalize' +must be called before using it in any calculations (*note Rational +Number Functions::). + + `Qi' will read a base specification separately for the numerator and +denominator. For example `0x10/11' would be 16/11, whereas `0x10/0x11' +would be 16/17. + + `n' can be used with any of the types above, even the GMP types. +`*' to suppress assignment is allowed, though the field would then do +nothing at all. + + Other conversions or types that might be accepted by the C library +`scanf' cannot be used through `gmp_scanf'. + + Whitespace is read and discarded before a field, except for `c' and +`[' conversions. + + For float conversions, the decimal point character (or string) +expected is taken from the current locale settings on systems which +provide `localeconv' (*note Locales and Internationalization: +(libc)Locales.). The C library will normally do the same for standard +float input. + + The format string is only interpreted as plain `char's, multibyte +characters are not recognised. Perhaps this will change in the future. + + +File: gmp.info, Node: Formatted Input Functions, Next: C++ Formatted Input, Prev: Formatted Input Strings, Up: Formatted Input + +Formatted Input Functions +========================= + + Each of the following functions is similar to the corresponding C +library function. The plain `scanf' forms take a variable argument +list. The `vscanf' forms take an argument pointer, see *Note Variadic +Functions: (libc)Variadic Functions, or `man 3 va_start'. + + It should be emphasised that if a format string is invalid, or the +arguments don't match what the format specifies, then the behaviour of +any of these functions will be unpredictable. GCC format string +checking is not available, since it doesn't recognise the GMP +extensions. + + No overlap is permitted between the FMT string and any of the results +produced. + + - Function: int gmp_scanf (const char *FMT, ...) + - Function: int gmp_vscanf (const char *FMT, va_list AP) + Read from the standard input `stdin'. + + - Function: int gmp_fscanf (FILE *FP, const char *FMT, ...) + - Function: int gmp_vfscanf (FILE *FP, const char *FMT, va_list AP) + Read from the stream FP. + + - Function: int gmp_sscanf (const char *S, const char *FMT, ...) + - Function: int gmp_vsscanf (const char *S, const char *FMT, va_list + AP) + Read from a null-terminated string S. + + The return value from each of these functions is the same as the +standard C99 `scanf', namely the number of fields successfully parsed +and stored. `%n' fields and fields read but suppressed by `*' don't +count towards the return value. + + If end of file or file error, or end of string, is reached when a +match is required, and when no previous non-suppressed fields have +matched, then the return value is EOF instead of 0. A match is +required for a literal character in the format string or a field other +than `%n'. Whitespace in the format string is only an optional match +and won't induce an EOF in this fashion. Leading whitespace read and +discarded for a field doesn't count as a match. + + +File: gmp.info, Node: C++ Formatted Input, Prev: Formatted Input Functions, Up: Formatted Input + +C++ Formatted Input +=================== + + The following functions are provided in `libgmpxx', which is built +only if C++ support is enabled (*note Build Options::). Prototypes are +available from `'. + + - Function: istream& operator>> (istream& STREAM, mpz_t ROP) + Read ROP from STREAM, using its `ios' formatting settings. + + - Function: istream& operator>> (istream& STREAM, mpq_t ROP) + Read ROP from STREAM, using its `ios' formatting settings. + + An integer like `123' will be read, or a fraction like `5/9'. If + the fraction is not in canonical form then `mpq_canonicalize' must + be called (*note Rational Number Functions::). + + - Function: istream& operator>> (istream& STREAM, mpf_t ROP) + Read ROP from STREAM, using its `ios' formatting settings. + + Hex or octal floats are not supported, but might be in the future. + + These operators mean that GMP types can be read in the usual C++ +way, for example, + + mpz_t z; + ... + cin >> z; + + But note that `istream' input (and `ostream' output, *note C++ +Formatted Output::) is the only overloading available and using for +instance `+' with an `mpz_t' will have unpredictable results. + + +File: gmp.info, Node: C++ Class Interface, Next: BSD Compatible Functions, Prev: Formatted Input, Up: Top + +C++ Class Interface +******************* + + This chapter describes the C++ class based interface to GMP. + + All GMP C language types and functions can be used in C++ programs, +since `gmp.h' has `extern "C"' qualifiers, but the class interface +offers overloaded functions and operators which may be more convenient. + + Due to the implementation of this interface, a reasonably recent C++ +compiler is required, one supporting namespaces, partial specialization +of templates and member templates. For GCC this means version 2.91 or +later. + + *Everything described in this chapter is to be considered preliminary +and might be subject to incompatible changes if some unforeseen +difficulty reveals itself.* + +* Menu: + +* C++ Interface General:: +* C++ Interface Integers:: +* C++ Interface Rationals:: +* C++ Interface Floats:: +* C++ Interface MPFR:: +* C++ Interface Random Numbers:: +* C++ Interface Limitations::