Annotation of OpenXM_contrib/gmp/gmp.info-4, Revision 1.1.1.2
1.1.1.2 ! ohara 1: This is gmp.info, produced by makeinfo version 4.2 from gmp.texi.
1.1 maekawa 2:
1.1.1.2 ! ohara 3: This manual describes how to install and use the GNU multiple precision
! 4: arithmetic library, version 4.1.2.
! 5:
! 6: Copyright 1991, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
! 7: 2001, 2002 Free Software Foundation, Inc.
! 8:
! 9: Permission is granted to copy, distribute and/or modify this
! 10: document under the terms of the GNU Free Documentation License, Version
! 11: 1.1 or any later version published by the Free Software Foundation;
! 12: with no Invariant Sections, with the Front-Cover Texts being "A GNU
! 13: Manual", and with the Back-Cover Texts being "You have freedom to copy
! 14: and modify this GNU Manual, like GNU software". A copy of the license
! 15: is included in *Note GNU Free Documentation License::.
1.1 maekawa 16: INFO-DIR-SECTION GNU libraries
17: START-INFO-DIR-ENTRY
18: * gmp: (gmp). GNU Multiple Precision Arithmetic Library.
19: END-INFO-DIR-ENTRY
20:
1.1.1.2 ! ohara 21:
! 22: File: gmp.info, Node: Miscellaneous Float Functions, Prev: I/O of Floats, Up: Floating-point Functions
! 23:
! 24: Miscellaneous Functions
! 25: =======================
! 26:
! 27: - Function: void mpf_ceil (mpf_t ROP, mpf_t OP)
! 28: - Function: void mpf_floor (mpf_t ROP, mpf_t OP)
! 29: - Function: void mpf_trunc (mpf_t ROP, mpf_t OP)
! 30: Set ROP to OP rounded to an integer. `mpf_ceil' rounds to the
! 31: next higher integer, `mpf_floor' to the next lower, and `mpf_trunc'
! 32: to the integer towards zero.
1.1 maekawa 33:
1.1.1.2 ! ohara 34: - Function: int mpf_integer_p (mpf_t OP)
! 35: Return non-zero if OP is an integer.
1.1 maekawa 36:
1.1.1.2 ! ohara 37: - Function: int mpf_fits_ulong_p (mpf_t OP)
! 38: - Function: int mpf_fits_slong_p (mpf_t OP)
! 39: - Function: int mpf_fits_uint_p (mpf_t OP)
! 40: - Function: int mpf_fits_sint_p (mpf_t OP)
! 41: - Function: int mpf_fits_ushort_p (mpf_t OP)
! 42: - Function: int mpf_fits_sshort_p (mpf_t OP)
! 43: Return non-zero if OP would fit in the respective C data type, when
! 44: truncated to an integer.
1.1 maekawa 45:
1.1.1.2 ! ohara 46: - Function: void mpf_urandomb (mpf_t ROP, gmp_randstate_t STATE,
! 47: unsigned long int NBITS)
! 48: Generate a uniformly distributed random float in ROP, such that 0
! 49: <= ROP < 1, with NBITS significant bits in the mantissa.
1.1 maekawa 50:
1.1.1.2 ! ohara 51: The variable STATE must be initialized by calling one of the
! 52: `gmp_randinit' functions (*Note Random State Initialization::)
! 53: before invoking this function.
! 54:
! 55: - Function: void mpf_random2 (mpf_t ROP, mp_size_t MAX_SIZE, mp_exp_t
! 56: EXP)
! 57: Generate a random float of at most MAX_SIZE limbs, with long
! 58: strings of zeros and ones in the binary representation. The
! 59: exponent of the number is in the interval -EXP to EXP. This
! 60: function is useful for testing functions and algorithms, since
! 61: this kind of random numbers have proven to be more likely to
! 62: trigger corner-case bugs. Negative random numbers are generated
! 63: when MAX_SIZE is negative.
1.1 maekawa 64:
65:
1.1.1.2 ! ohara 66: File: gmp.info, Node: Low-level Functions, Next: Random Number Functions, Prev: Floating-point Functions, Up: Top
! 67:
! 68: Low-level Functions
! 69: *******************
! 70:
! 71: This chapter describes low-level GMP functions, used to implement the
! 72: high-level GMP functions, but also intended for time-critical user code.
! 73:
! 74: These functions start with the prefix `mpn_'.
! 75:
! 76: The `mpn' functions are designed to be as fast as possible, *not* to
! 77: provide a coherent calling interface. The different functions have
! 78: somewhat similar interfaces, but there are variations that make them
! 79: hard to use. These functions do as little as possible apart from the
! 80: real multiple precision computation, so that no time is spent on things
! 81: that not all callers need.
! 82:
! 83: A source operand is specified by a pointer to the least significant
! 84: limb and a limb count. A destination operand is specified by just a
! 85: pointer. It is the responsibility of the caller to ensure that the
! 86: destination has enough space for storing the result.
! 87:
! 88: With this way of specifying operands, it is possible to perform
! 89: computations on subranges of an argument, and store the result into a
! 90: subrange of a destination.
! 91:
! 92: A common requirement for all functions is that each source area
! 93: needs at least one limb. No size argument may be zero. Unless
! 94: otherwise stated, in-place operations are allowed where source and
! 95: destination are the same, but not where they only partly overlap.
! 96:
! 97: The `mpn' functions are the base for the implementation of the
! 98: `mpz_', `mpf_', and `mpq_' functions.
! 99:
! 100: This example adds the number beginning at S1P and the number
! 101: beginning at S2P and writes the sum at DESTP. All areas have N limbs.
! 102:
! 103: cy = mpn_add_n (destp, s1p, s2p, n)
! 104:
! 105: In the notation used here, a source operand is identified by the
! 106: pointer to the least significant limb, and the limb count in braces.
! 107: For example, {S1P, S1N}.
! 108:
! 109: - Function: mp_limb_t mpn_add_n (mp_limb_t *RP, const mp_limb_t *S1P,
! 110: const mp_limb_t *S2P, mp_size_t N)
! 111: Add {S1P, N} and {S2P, N}, and write the N least significant limbs
! 112: of the result to RP. Return carry, either 0 or 1.
! 113:
! 114: This is the lowest-level function for addition. It is the
! 115: preferred function for addition, since it is written in assembly
! 116: for most CPUs. For addition of a variable to itself (i.e., S1P
! 117: equals S2P, use `mpn_lshift' with a count of 1 for optimal speed.
! 118:
! 119: - Function: mp_limb_t mpn_add_1 (mp_limb_t *RP, const mp_limb_t *S1P,
! 120: mp_size_t N, mp_limb_t S2LIMB)
! 121: Add {S1P, N} and S2LIMB, and write the N least significant limbs
! 122: of the result to RP. Return carry, either 0 or 1.
! 123:
! 124: - Function: mp_limb_t mpn_add (mp_limb_t *RP, const mp_limb_t *S1P,
! 125: mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N)
! 126: Add {S1P, S1N} and {S2P, S2N}, and write the S1N least significant
! 127: limbs of the result to RP. Return carry, either 0 or 1.
! 128:
! 129: This function requires that S1N is greater than or equal to S2N.
! 130:
! 131: - Function: mp_limb_t mpn_sub_n (mp_limb_t *RP, const mp_limb_t *S1P,
! 132: const mp_limb_t *S2P, mp_size_t N)
! 133: Subtract {S2P, N} from {S1P, N}, and write the N least significant
! 134: limbs of the result to RP. Return borrow, either 0 or 1.
! 135:
! 136: This is the lowest-level function for subtraction. It is the
! 137: preferred function for subtraction, since it is written in
! 138: assembly for most CPUs.
! 139:
! 140: - Function: mp_limb_t mpn_sub_1 (mp_limb_t *RP, const mp_limb_t *S1P,
! 141: mp_size_t N, mp_limb_t S2LIMB)
! 142: Subtract S2LIMB from {S1P, N}, and write the N least significant
! 143: limbs of the result to RP. Return borrow, either 0 or 1.
! 144:
! 145: - Function: mp_limb_t mpn_sub (mp_limb_t *RP, const mp_limb_t *S1P,
! 146: mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N)
! 147: Subtract {S2P, S2N} from {S1P, S1N}, and write the S1N least
! 148: significant limbs of the result to RP. Return borrow, either 0 or
! 149: 1.
! 150:
! 151: This function requires that S1N is greater than or equal to S2N.
! 152:
! 153: - Function: void mpn_mul_n (mp_limb_t *RP, const mp_limb_t *S1P, const
! 154: mp_limb_t *S2P, mp_size_t N)
! 155: Multiply {S1P, N} and {S2P, N}, and write the 2*N-limb result to
! 156: RP.
! 157:
! 158: The destination has to have space for 2*N limbs, even if the
! 159: product's most significant limb is zero.
! 160:
! 161: - Function: mp_limb_t mpn_mul_1 (mp_limb_t *RP, const mp_limb_t *S1P,
! 162: mp_size_t N, mp_limb_t S2LIMB)
! 163: Multiply {S1P, N} by S2LIMB, and write the N least significant
! 164: limbs of the product to RP. Return the most significant limb of
! 165: the product. {S1P, N} and {RP, N} are allowed to overlap provided
! 166: RP <= S1P.
! 167:
! 168: This is a low-level function that is a building block for general
! 169: multiplication as well as other operations in GMP. It is written
! 170: in assembly for most CPUs.
! 171:
! 172: Don't call this function if S2LIMB is a power of 2; use
! 173: `mpn_lshift' with a count equal to the logarithm of S2LIMB
! 174: instead, for optimal speed.
! 175:
! 176: - Function: mp_limb_t mpn_addmul_1 (mp_limb_t *RP, const mp_limb_t
! 177: *S1P, mp_size_t N, mp_limb_t S2LIMB)
! 178: Multiply {S1P, N} and S2LIMB, and add the N least significant
! 179: limbs of the product to {RP, N} and write the result to RP.
! 180: Return the most significant limb of the product, plus carry-out
! 181: from the addition.
! 182:
! 183: This is a low-level function that is a building block for general
! 184: multiplication as well as other operations in GMP. It is written
! 185: in assembly for most CPUs.
! 186:
! 187: - Function: mp_limb_t mpn_submul_1 (mp_limb_t *RP, const mp_limb_t
! 188: *S1P, mp_size_t N, mp_limb_t S2LIMB)
! 189: Multiply {S1P, N} and S2LIMB, and subtract the N least significant
! 190: limbs of the product from {RP, N} and write the result to RP.
! 191: Return the most significant limb of the product, minus borrow-out
! 192: from the subtraction.
! 193:
! 194: This is a low-level function that is a building block for general
! 195: multiplication and division as well as other operations in GMP.
! 196: It is written in assembly for most CPUs.
! 197:
! 198: - Function: mp_limb_t mpn_mul (mp_limb_t *RP, const mp_limb_t *S1P,
! 199: mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N)
! 200: Multiply {S1P, S1N} and {S2P, S2N}, and write the result to RP.
! 201: Return the most significant limb of the result.
! 202:
! 203: The destination has to have space for S1N + S2N limbs, even if the
! 204: result might be one limb smaller.
! 205:
! 206: This function requires that S1N is greater than or equal to S2N.
! 207: The destination must be distinct from both input operands.
! 208:
! 209: - Function: void mpn_tdiv_qr (mp_limb_t *QP, mp_limb_t *RP, mp_size_t
! 210: QXN, const mp_limb_t *NP, mp_size_t NN, const mp_limb_t *DP,
! 211: mp_size_t DN)
! 212: Divide {NP, NN} by {DP, DN} and put the quotient at {QP, NN-DN+1}
! 213: and the remainder at {RP, DN}. The quotient is rounded towards 0.
! 214:
! 215: No overlap is permitted between arguments. NN must be greater
! 216: than or equal to DN. The most significant limb of DP must be
! 217: non-zero. The QXN operand must be zero.
! 218:
! 219: - Function: mp_limb_t mpn_divrem (mp_limb_t *R1P, mp_size_t QXN,
! 220: mp_limb_t *RS2P, mp_size_t RS2N, const mp_limb_t *S3P,
! 221: mp_size_t S3N)
! 222: [This function is obsolete. Please call `mpn_tdiv_qr' instead for
! 223: best performance.]
! 224:
! 225: Divide {RS2P, RS2N} by {S3P, S3N}, and write the quotient at R1P,
! 226: with the exception of the most significant limb, which is
! 227: returned. The remainder replaces the dividend at RS2P; it will be
! 228: S3N limbs long (i.e., as many limbs as the divisor).
! 229:
! 230: In addition to an integer quotient, QXN fraction limbs are
! 231: developed, and stored after the integral limbs. For most usages,
! 232: QXN will be zero.
! 233:
! 234: It is required that RS2N is greater than or equal to S3N. It is
! 235: required that the most significant bit of the divisor is set.
! 236:
! 237: If the quotient is not needed, pass RS2P + S3N as R1P. Aside from
! 238: that special case, no overlap between arguments is permitted.
! 239:
! 240: Return the most significant limb of the quotient, either 0 or 1.
! 241:
! 242: The area at R1P needs to be RS2N - S3N + QXN limbs large.
! 243:
! 244: - Function: mp_limb_t mpn_divrem_1 (mp_limb_t *R1P, mp_size_t QXN,
! 245: mp_limb_t *S2P, mp_size_t S2N, mp_limb_t S3LIMB)
! 246: - Macro: mp_limb_t mpn_divmod_1 (mp_limb_t *R1P, mp_limb_t *S2P,
! 247: mp_size_t S2N, mp_limb_t S3LIMB)
! 248: Divide {S2P, S2N} by S3LIMB, and write the quotient at R1P.
! 249: Return the remainder.
! 250:
! 251: The integer quotient is written to {R1P+QXN, S2N} and in addition
! 252: QXN fraction limbs are developed and written to {R1P, QXN}.
! 253: Either or both S2N and QXN can be zero. For most usages, QXN will
! 254: be zero.
! 255:
! 256: `mpn_divmod_1' exists for upward source compatibility and is
! 257: simply a macro calling `mpn_divrem_1' with a QXN of 0.
! 258:
! 259: The areas at R1P and S2P have to be identical or completely
! 260: separate, not partially overlapping.
! 261:
! 262: - Function: mp_limb_t mpn_divmod (mp_limb_t *R1P, mp_limb_t *RS2P,
! 263: mp_size_t RS2N, const mp_limb_t *S3P, mp_size_t S3N)
! 264: [This function is obsolete. Please call `mpn_tdiv_qr' instead for
! 265: best performance.]
! 266:
! 267: - Macro: mp_limb_t mpn_divexact_by3 (mp_limb_t *RP, mp_limb_t *SP,
! 268: mp_size_t N)
! 269: - Function: mp_limb_t mpn_divexact_by3c (mp_limb_t *RP, mp_limb_t *SP,
! 270: mp_size_t N, mp_limb_t CARRY)
! 271: Divide {SP, N} by 3, expecting it to divide exactly, and writing
! 272: the result to {RP, N}. If 3 divides exactly, the return value is
! 273: zero and the result is the quotient. If not, the return value is
! 274: non-zero and the result won't be anything useful.
! 275:
! 276: `mpn_divexact_by3c' takes an initial carry parameter, which can be
! 277: the return value from a previous call, so a large calculation can
! 278: be done piece by piece from low to high. `mpn_divexact_by3' is
! 279: simply a macro calling `mpn_divexact_by3c' with a 0 carry
! 280: parameter.
! 281:
! 282: These routines use a multiply-by-inverse and will be faster than
! 283: `mpn_divrem_1' on CPUs with fast multiplication but slow division.
! 284:
! 285: The source a, result q, size n, initial carry i, and return value
! 286: c satisfy c*b^n + a-i = 3*q, where b=2^mp_bits_per_limb. The
! 287: return c is always 0, 1 or 2, and the initial carry i must also be
! 288: 0, 1 or 2 (these are both borrows really). When c=0 clearly
! 289: q=(a-i)/3. When c!=0, the remainder (a-i) mod 3 is given by 3-c,
! 290: because b == 1 mod 3 (when `mp_bits_per_limb' is even, which is
! 291: always so currently).
! 292:
! 293: - Function: mp_limb_t mpn_mod_1 (mp_limb_t *S1P, mp_size_t S1N,
! 294: mp_limb_t S2LIMB)
! 295: Divide {S1P, S1N} by S2LIMB, and return the remainder. S1N can be
! 296: zero.
! 297:
! 298: - Function: mp_limb_t mpn_bdivmod (mp_limb_t *RP, mp_limb_t *S1P,
! 299: mp_size_t S1N, const mp_limb_t *S2P, mp_size_t S2N, unsigned
! 300: long int D)
! 301: This function puts the low floor(D/mp_bits_per_limb) limbs of Q =
! 302: {S1P, S1N}/{S2P, S2N} mod 2^D at RP, and returns the high D mod
! 303: `mp_bits_per_limb' bits of Q.
! 304:
! 305: {S1P, S1N} - Q * {S2P, S2N} mod 2^(S1N*mp_bits_per_limb) is placed
! 306: at S1P. Since the low floor(D/mp_bits_per_limb) limbs of this
! 307: difference are zero, it is possible to overwrite the low limbs at
! 308: S1P with this difference, provided RP <= S1P.
! 309:
! 310: This function requires that S1N * mp_bits_per_limb >= D, and that
! 311: {S2P, S2N} is odd.
! 312:
! 313: *This interface is preliminary. It might change incompatibly in
! 314: future revisions.*
! 315:
! 316: - Function: mp_limb_t mpn_lshift (mp_limb_t *RP, const mp_limb_t *SP,
! 317: mp_size_t N, unsigned int COUNT)
! 318: Shift {SP, N} left by COUNT bits, and write the result to {RP, N}.
! 319: The bits shifted out at the left are returned in the least
! 320: significant COUNT bits of the return value (the rest of the return
! 321: value is zero).
! 322:
! 323: COUNT must be in the range 1 to mp_bits_per_limb-1. The regions
! 324: {SP, N} and {RP, N} may overlap, provided RP >= SP.
! 325:
! 326: This function is written in assembly for most CPUs.
! 327:
! 328: - Function: mp_limb_t mpn_rshift (mp_limb_t *RP, const mp_limb_t *SP,
! 329: mp_size_t N, unsigned int COUNT)
! 330: Shift {SP, N} right by COUNT bits, and write the result to {RP,
! 331: N}. The bits shifted out at the right are returned in the most
! 332: significant COUNT bits of the return value (the rest of the return
! 333: value is zero).
! 334:
! 335: COUNT must be in the range 1 to mp_bits_per_limb-1. The regions
! 336: {SP, N} and {RP, N} may overlap, provided RP <= SP.
1.1 maekawa 337:
1.1.1.2 ! ohara 338: This function is written in assembly for most CPUs.
! 339:
! 340: - Function: int mpn_cmp (const mp_limb_t *S1P, const mp_limb_t *S2P,
! 341: mp_size_t N)
! 342: Compare {S1P, N} and {S2P, N} and return a positive value if S1 >
! 343: S2, 0 if they are equal, or a negative value if S1 < S2.
! 344:
! 345: - Function: mp_size_t mpn_gcd (mp_limb_t *RP, mp_limb_t *S1P,
! 346: mp_size_t S1N, mp_limb_t *S2P, mp_size_t S2N)
! 347: Set {RP, RETVAL} to the greatest common divisor of {S1P, S1N} and
! 348: {S2P, S2N}. The result can be up to S2N limbs, the return value
! 349: is the actual number produced. Both source operands are destroyed.
! 350:
! 351: {S1P, S1N} must have at least as many bits as {S2P, S2N}. {S2P,
! 352: S2N} must be odd. Both operands must have non-zero most
! 353: significant limbs. No overlap is permitted between {S1P, S1N} and
! 354: {S2P, S2N}.
! 355:
! 356: - Function: mp_limb_t mpn_gcd_1 (const mp_limb_t *S1P, mp_size_t S1N,
! 357: mp_limb_t S2LIMB)
! 358: Return the greatest common divisor of {S1P, S1N} and S2LIMB. Both
! 359: operands must be non-zero.
! 360:
! 361: - Function: mp_size_t mpn_gcdext (mp_limb_t *R1P, mp_limb_t *R2P,
! 362: mp_size_t *R2N, mp_limb_t *S1P, mp_size_t S1N, mp_limb_t
! 363: *S2P, mp_size_t S2N)
! 364: Calculate the greatest common divisor of {S1P, S1N} and {S2P,
! 365: S2N}. Store the gcd at {R1P, RETVAL} and the first cofactor at
! 366: {R2P, *R2N}, with *R2N negative if the cofactor is negative. R1P
! 367: and R2P should each have room for S1N+1 limbs, but the return
! 368: value and value stored through R2N indicate the actual number
! 369: produced.
! 370:
! 371: {S1P, S1N} >= {S2P, S2N} is required, and both must be non-zero.
! 372: The regions {S1P, S1N+1} and {S2P, S2N+1} are destroyed (i.e. the
! 373: operands plus an extra limb past the end of each).
! 374:
! 375: The cofactor R1 will satisfy R2*S1 + K*S2 = R1. The second
! 376: cofactor K is not calculated but can easily be obtained from (R1 -
! 377: R2*S1) / S2.
! 378:
! 379: - Function: mp_size_t mpn_sqrtrem (mp_limb_t *R1P, mp_limb_t *R2P,
! 380: const mp_limb_t *SP, mp_size_t N)
! 381: Compute the square root of {SP, N} and put the result at {R1P,
! 382: ceil(N/2)} and the remainder at {R2P, RETVAL}. R2P needs space
! 383: for N limbs, but the return value indicates how many are produced.
! 384:
! 385: The most significant limb of {SP, N} must be non-zero. The areas
! 386: {R1P, ceil(N/2)} and {SP, N} must be completely separate. The
! 387: areas {R2P, N} and {SP, N} must be either identical or completely
! 388: separate.
! 389:
! 390: If the remainder is not wanted then R2P can be `NULL', and in this
! 391: case the return value is zero or non-zero according to whether the
! 392: remainder would have been zero or non-zero.
! 393:
! 394: A return value of zero indicates a perfect square. See also
! 395: `mpz_perfect_square_p'.
! 396:
! 397: - Function: mp_size_t mpn_get_str (unsigned char *STR, int BASE,
! 398: mp_limb_t *S1P, mp_size_t S1N)
! 399: Convert {S1P, S1N} to a raw unsigned char array at STR in base
! 400: BASE, and return the number of characters produced. There may be
! 401: leading zeros in the string. The string is not in ASCII; to
! 402: convert it to printable format, add the ASCII codes for `0' or
! 403: `A', depending on the base and range. BASE can vary from 2 to 256.
! 404:
! 405: The most significant limb of the input {S1P, S1N} must be
! 406: non-zero. The input {S1P, S1N} is clobbered, except when BASE is
! 407: a power of 2, in which case it's unchanged.
! 408:
! 409: The area at STR has to have space for the largest possible number
! 410: represented by a S1N long limb array, plus one extra character.
! 411:
! 412: - Function: mp_size_t mpn_set_str (mp_limb_t *RP, const unsigned char
! 413: *STR, size_t STRSIZE, int BASE)
! 414: Convert bytes {STR,STRSIZE} in the given BASE to limbs at RP.
! 415:
! 416: STR[0] is the most significant byte and STR[STRSIZE-1] is the
! 417: least significant. Each byte should be a value in the range 0 to
! 418: BASE-1, not an ASCII character. BASE can vary from 2 to 256.
! 419:
! 420: The return value is the number of limbs written to RP. If the most
! 421: significant input byte is non-zero then the high limb at RP will be
! 422: non-zero, and only that exact number of limbs will be required
! 423: there.
! 424:
! 425: If the most significant input byte is zero then there may be high
! 426: zero limbs written to RP and included in the return value.
! 427:
! 428: STRSIZE must be at least 1, and no overlap is permitted between
! 429: {STR,STRSIZE} and the result at RP.
! 430:
! 431: - Function: unsigned long int mpn_scan0 (const mp_limb_t *S1P,
! 432: unsigned long int BIT)
! 433: Scan S1P from bit position BIT for the next clear bit.
! 434:
! 435: It is required that there be a clear bit within the area at S1P at
! 436: or beyond bit position BIT, so that the function has something to
! 437: return.
! 438:
! 439: - Function: unsigned long int mpn_scan1 (const mp_limb_t *S1P,
! 440: unsigned long int BIT)
! 441: Scan S1P from bit position BIT for the next set bit.
! 442:
! 443: It is required that there be a set bit within the area at S1P at or
! 444: beyond bit position BIT, so that the function has something to
! 445: return.
! 446:
! 447: - Function: void mpn_random (mp_limb_t *R1P, mp_size_t R1N)
! 448: - Function: void mpn_random2 (mp_limb_t *R1P, mp_size_t R1N)
! 449: Generate a random number of length R1N and store it at R1P. The
! 450: most significant limb is always non-zero. `mpn_random' generates
! 451: uniformly distributed limb data, `mpn_random2' generates long
! 452: strings of zeros and ones in the binary representation.
! 453:
! 454: `mpn_random2' is intended for testing the correctness of the `mpn'
! 455: routines.
! 456:
! 457: - Function: unsigned long int mpn_popcount (const mp_limb_t *S1P,
! 458: mp_size_t N)
! 459: Count the number of set bits in {S1P, N}.
! 460:
! 461: - Function: unsigned long int mpn_hamdist (const mp_limb_t *S1P, const
! 462: mp_limb_t *S2P, mp_size_t N)
! 463: Compute the hamming distance between {S1P, N} and {S2P, N}.
! 464:
! 465: - Function: int mpn_perfect_square_p (const mp_limb_t *S1P, mp_size_t
! 466: N)
! 467: Return non-zero iff {S1P, N} is a perfect square.
! 468:
! 469:
! 470: Nails
! 471: =====
! 472:
! 473: *Everything in this section is highly experimental and may disappear
! 474: or be subject to incompatible changes in a future version of GMP.*
! 475:
! 476: Nails are an experimental feature whereby a few bits are left unused
! 477: at the top of each `mp_limb_t'. This can significantly improve carry
! 478: handling on some processors.
! 479:
! 480: All the `mpn' functions accepting limb data will expect the nail
! 481: bits to be zero on entry, and will return data with the nails similarly
! 482: all zero. This applies both to limb vectors and to single limb
! 483: arguments.
! 484:
! 485: Nails can be enabled by configuring with `--enable-nails'. By
! 486: default the number of bits will be chosen according to what suits the
! 487: host processor, but a particular number can be selected with
! 488: `--enable-nails=N'.
! 489:
! 490: At the mpn level, a nail build is neither source nor binary
! 491: compatible with a non-nail build, strictly speaking. But programs
! 492: acting on limbs only through the mpn functions are likely to work
! 493: equally well with either build, and judicious use of the definitions
! 494: below should make any program compatible with either build, at the
! 495: source level.
! 496:
! 497: For the higher level routines, meaning `mpz' etc, a nail build
! 498: should be fully source and binary compatible with a non-nail build.
! 499:
! 500: - Macro: GMP_NAIL_BITS
! 501: - Macro: GMP_NUMB_BITS
! 502: - Macro: GMP_LIMB_BITS
! 503: `GMP_NAIL_BITS' is the number of nail bits, or 0 when nails are
! 504: not in use. `GMP_NUMB_BITS' is the number of data bits in a limb.
! 505: `GMP_LIMB_BITS' is the total number of bits in an `mp_limb_t'. In
! 506: all cases
! 507:
! 508: GMP_LIMB_BITS == GMP_NAIL_BITS + GMP_NUMB_BITS
! 509:
! 510: - Macro: GMP_NAIL_MASK
! 511: - Macro: GMP_NUMB_MASK
! 512: Bit masks for the nail and number parts of a limb.
! 513: `GMP_NAIL_MASK' is 0 when nails are not in use.
! 514:
! 515: `GMP_NAIL_MASK' is not often needed, since the nail part can be
! 516: obtained with `x >> GMP_NUMB_BITS', and that means one less large
! 517: constant, which can help various RISC chips.
! 518:
! 519: - Macro: GMP_NUMB_MAX
! 520: The maximum value that can be stored in the number part of a limb.
! 521: This is the same as `GMP_NUMB_MASK', but can be used for clarity
! 522: when doing comparisons rather than bit-wise operations.
! 523:
! 524: The term "nails" comes from finger or toe nails, which are at the
! 525: ends of a limb (arm or leg). "numb" is short for number, but is also
! 526: how the developers felt after trying for a long time to come up with
! 527: sensible names for these things.
! 528:
! 529: In the future (the distant future most likely) a non-zero nail might
! 530: be permitted, giving non-unique representations for numbers in a limb
! 531: vector. This would help vector processors since carries would only
! 532: ever need to propagate one or two limbs.
! 533:
! 534:
! 535: File: gmp.info, Node: Random Number Functions, Next: Formatted Output, Prev: Low-level Functions, Up: Top
! 536:
! 537: Random Number Functions
1.1 maekawa 538: ***********************
539:
1.1.1.2 ! ohara 540: Sequences of pseudo-random numbers in GMP are generated using a
! 541: variable of type `gmp_randstate_t', which holds an algorithm selection
! 542: and a current state. Such a variable must be initialized by a call to
! 543: one of the `gmp_randinit' functions, and can be seeded with one of the
! 544: `gmp_randseed' functions.
! 545:
! 546: The functions actually generating random numbers are described in
! 547: *Note Integer Random Numbers::, and *Note Miscellaneous Float
! 548: Functions::.
! 549:
! 550: The older style random number functions don't accept a
! 551: `gmp_randstate_t' parameter but instead share a global variable of that
! 552: type. They use a default algorithm and are currently not seeded
! 553: (though perhaps that will change in the future). The new functions
! 554: accepting a `gmp_randstate_t' are recommended for applications that
! 555: care about randomness.
! 556:
! 557: * Menu:
! 558:
! 559: * Random State Initialization::
! 560: * Random State Seeding::
! 561:
! 562:
! 563: File: gmp.info, Node: Random State Initialization, Next: Random State Seeding, Prev: Random Number Functions, Up: Random Number Functions
! 564:
! 565: Random State Initialization
! 566: ===========================
! 567:
! 568: - Function: void gmp_randinit_default (gmp_randstate_t STATE)
! 569: Initialize STATE with a default algorithm. This will be a
! 570: compromise between speed and randomness, and is recommended for
! 571: applications with no special requirements.
! 572:
! 573: - Function: void gmp_randinit_lc_2exp (gmp_randstate_t STATE, mpz_t A,
! 574: unsigned long C, unsigned long M2EXP)
! 575: Initialize STATE with a linear congruential algorithm X = (A*X +
! 576: C) mod 2^M2EXP.
! 577:
! 578: The low bits of X in this algorithm are not very random. The least
! 579: significant bit will have a period no more than 2, and the second
! 580: bit no more than 4, etc. For this reason only the high half of
! 581: each X is actually used.
! 582:
! 583: When a random number of more than M2EXP/2 bits is to be generated,
! 584: multiple iterations of the recurrence are used and the results
! 585: concatenated.
! 586:
! 587: - Function: int gmp_randinit_lc_2exp_size (gmp_randstate_t STATE,
! 588: unsigned long SIZE)
! 589: Initialize STATE for a linear congruential algorithm as per
! 590: `gmp_randinit_lc_2exp'. A, C and M2EXP are selected from a table,
! 591: chosen so that SIZE bits (or more) of each X will be used, ie.
! 592: M2EXP/2 >= SIZE.
! 593:
! 594: If successful the return value is non-zero. If SIZE is bigger
! 595: than the table data provides then the return value is zero. The
! 596: maximum SIZE currently supported is 128.
! 597:
! 598: - Function: void gmp_randinit (gmp_randstate_t STATE,
! 599: gmp_randalg_t ALG, ...)
! 600: *This function is obsolete.*
! 601:
! 602: Initialize STATE with an algorithm selected by ALG. The only
! 603: choice is `GMP_RAND_ALG_LC', which is `gmp_randinit_lc_2exp_size'.
! 604: A third parameter of type `unsigned long' is required, this is the
! 605: SIZE for that function. `GMP_RAND_ALG_DEFAULT' or 0 are the same
! 606: as `GMP_RAND_ALG_LC'.
! 607:
! 608: `gmp_randinit' sets bits in `gmp_errno' to indicate an error.
! 609: `GMP_ERROR_UNSUPPORTED_ARGUMENT' if ALG is unsupported, or
! 610: `GMP_ERROR_INVALID_ARGUMENT' if the SIZE parameter is too big.
! 611:
! 612: - Function: void gmp_randclear (gmp_randstate_t STATE)
! 613: Free all memory occupied by STATE.
! 614:
! 615:
! 616: File: gmp.info, Node: Random State Seeding, Prev: Random State Initialization, Up: Random Number Functions
! 617:
! 618: Random State Seeding
! 619: ====================
! 620:
! 621: - Function: void gmp_randseed (gmp_randstate_t STATE, mpz_t SEED)
! 622: - Function: void gmp_randseed_ui (gmp_randstate_t STATE,
! 623: unsigned long int SEED)
! 624: Set an initial seed value into STATE.
! 625:
! 626: The size of a seed determines how many different sequences of
! 627: random numbers that it's possible to generate. The "quality" of
! 628: the seed is the randomness of a given seed compared to the
! 629: previous seed used, and this affects the randomness of separate
! 630: number sequences. The method for choosing a seed is critical if
! 631: the generated numbers are to be used for important applications,
! 632: such as generating cryptographic keys.
! 633:
! 634: Traditionally the system time has been used to seed, but care
! 635: needs to be taken with this. If an application seeds often and
! 636: the resolution of the system clock is low, then the same sequence
! 637: of numbers might be repeated. Also, the system time is quite easy
! 638: to guess, so if unpredictability is required then it should
! 639: definitely not be the only source for the seed value. On some
! 640: systems there's a special device `/dev/random' which provides
! 641: random data better suited for use as a seed.
! 642:
! 643:
! 644: File: gmp.info, Node: Formatted Output, Next: Formatted Input, Prev: Random Number Functions, Up: Top
! 645:
! 646: Formatted Output
! 647: ****************
! 648:
1.1 maekawa 649: * Menu:
650:
1.1.1.2 ! ohara 651: * Formatted Output Strings::
! 652: * Formatted Output Functions::
! 653: * C++ Formatted Output::
! 654:
! 655:
! 656: File: gmp.info, Node: Formatted Output Strings, Next: Formatted Output Functions, Prev: Formatted Output, Up: Formatted Output
! 657:
! 658: Format Strings
! 659: ==============
! 660:
! 661: `gmp_printf' and friends accept format strings similar to the
! 662: standard C `printf' (*note Formatted Output: (libc)Formatted Output.).
! 663: A format specification is of the form
! 664:
! 665: % [flags] [width] [.[precision]] [type] conv
! 666:
! 667: GMP adds types `Z', `Q' and `F' for `mpz_t', `mpq_t' and `mpf_t'
! 668: respectively, and `N' for an `mp_limb_t' array. `Z', `Q' and `N'
! 669: behave like integers. `Q' will print a `/' and a denominator, if
! 670: needed. `F' behaves like a float. For example,
! 671:
! 672: mpz_t z;
! 673: gmp_printf ("%s is an mpz %Zd\n", "here", z);
! 674:
! 675: mpq_t q;
! 676: gmp_printf ("a hex rational: %#40Qx\n", q);
! 677:
! 678: mpf_t f;
! 679: int n;
! 680: gmp_printf ("fixed point mpf %.*Ff with %d digits\n", n, f, n);
! 681:
! 682: const mp_limb_t *ptr;
! 683: mp_size_t size;
! 684: gmp_printf ("limb array %Nx\n", ptr, size);
! 685:
! 686: For `N' the limbs are expected least significant first, as per the
! 687: `mpn' functions (*note Low-level Functions::). A negative size can be
! 688: given to print the value as a negative.
! 689:
! 690: All the standard C `printf' types behave the same as the C library
! 691: `printf', and can be freely intermixed with the GMP extensions. In the
! 692: current implementation the standard parts of the format string are
! 693: simply handed to `printf' and only the GMP extensions handled directly.
! 694:
! 695: The flags accepted are as follows. GLIBC style ' is only for the
! 696: standard C types (not the GMP types), and only if the C library
! 697: supports it.
! 698:
! 699: 0 pad with zeros (rather than spaces)
! 700: # show the base with `0x', `0X' or `0'
! 701: + always show a sign
! 702: (space) show a space or a `-' sign
! 703: ' group digits, GLIBC style (not GMP types)
! 704:
! 705: The optional width and precision can be given as a number within the
! 706: format string, or as a `*' to take an extra parameter of type `int', the
! 707: same as the standard `printf'.
! 708:
! 709: The standard types accepted are as follows. `h' and `l' are
! 710: portable, the rest will depend on the compiler (or include files) for
! 711: the type and the C library for the output.
! 712:
! 713: h short
! 714: hh char
! 715: j intmax_t or uintmax_t
! 716: l long or wchar_t
! 717: ll long long
! 718: L long double
! 719: q quad_t or u_quad_t
! 720: t ptrdiff_t
! 721: z size_t
! 722:
! 723: The GMP types are
! 724:
! 725: F mpf_t, float conversions
! 726: Q mpq_t, integer conversions
! 727: N mp_limb_t array, integer conversions
! 728: Z mpz_t, integer conversions
! 729:
! 730: The conversions accepted are as follows. `a' and `A' are always
! 731: supported for `mpf_t' but depend on the C library for standard C float
! 732: types. `m' and `p' depend on the C library.
! 733:
! 734: a A hex floats, C99 style
! 735: c character
! 736: d decimal integer
! 737: e E scientific format float
! 738: f fixed point float
! 739: i same as d
! 740: g G fixed or scientific float
! 741: m `strerror' string, GLIBC style
! 742: n store characters written so far
! 743: o octal integer
! 744: p pointer
! 745: s string
! 746: u unsigned integer
! 747: x X hex integer
! 748:
! 749: `o', `x' and `X' are unsigned for the standard C types, but for
! 750: types `Z', `Q' and `N' they are signed. `u' is not meaningful for `Z',
! 751: `Q' and `N'.
! 752:
! 753: `n' can be used with any type, even the GMP types.
! 754:
! 755: Other types or conversions that might be accepted by the C library
! 756: `printf' cannot be used through `gmp_printf', this includes for
! 757: instance extensions registered with GLIBC `register_printf_function'.
! 758: Also currently there's no support for POSIX `$' style numbered arguments
! 759: (perhaps this will be added in the future).
! 760:
! 761: The precision field has it's usual meaning for integer `Z' and float
! 762: `F' types, but is currently undefined for `Q' and should not be used
! 763: with that.
! 764:
! 765: `mpf_t' conversions only ever generate as many digits as can be
! 766: accurately represented by the operand, the same as `mpf_get_str' does.
! 767: Zeros will be used if necessary to pad to the requested precision. This
! 768: happens even for an `f' conversion of an `mpf_t' which is an integer,
! 769: for instance 2^1024 in an `mpf_t' of 128 bits precision will only
! 770: produce about 40 digits, then pad with zeros to the decimal point. An
! 771: empty precision field like `%.Fe' or `%.Ff' can be used to specifically
! 772: request just the significant digits.
! 773:
! 774: The decimal point character (or string) is taken from the current
! 775: locale settings on systems which provide `localeconv' (*note Locales
! 776: and Internationalization: (libc)Locales.). The C library will normally
! 777: do the same for standard float output.
! 778:
! 779: The format string is only interpreted as plain `char's, multibyte
! 780: characters are not recognised. Perhaps this will change in the future.
! 781:
! 782:
! 783: File: gmp.info, Node: Formatted Output Functions, Next: C++ Formatted Output, Prev: Formatted Output Strings, Up: Formatted Output
! 784:
! 785: Functions
! 786: =========
! 787:
! 788: Each of the following functions is similar to the corresponding C
! 789: library function. The basic `printf' forms take a variable argument
! 790: list. The `vprintf' forms take an argument pointer, see *Note Variadic
! 791: Functions: (libc)Variadic Functions, or `man 3 va_start'.
! 792:
! 793: It should be emphasised that if a format string is invalid, or the
! 794: arguments don't match what the format specifies, then the behaviour of
! 795: any of these functions will be unpredictable. GCC format string
! 796: checking is not available, since it doesn't recognise the GMP
! 797: extensions.
! 798:
! 799: The file based functions `gmp_printf' and `gmp_fprintf' will return
! 800: -1 to indicate a write error. All the functions can return -1 if the C
! 801: library `printf' variant in use returns -1, but this shouldn't normally
! 802: occur.
! 803:
! 804: - Function: int gmp_printf (const char *FMT, ...)
! 805: - Function: int gmp_vprintf (const char *FMT, va_list AP)
! 806: Print to the standard output `stdout'. Return the number of
! 807: characters written, or -1 if an error occurred.
! 808:
! 809: - Function: int gmp_fprintf (FILE *FP, const char *FMT, ...)
! 810: - Function: int gmp_vfprintf (FILE *FP, const char *FMT, va_list AP)
! 811: Print to the stream FP. Return the number of characters written,
! 812: or -1 if an error occurred.
! 813:
! 814: - Function: int gmp_sprintf (char *BUF, const char *FMT, ...)
! 815: - Function: int gmp_vsprintf (char *BUF, const char *FMT, va_list AP)
! 816: Form a null-terminated string in BUF. Return the number of
! 817: characters written, excluding the terminating null.
! 818:
! 819: No overlap is permitted between the space at BUF and the string
! 820: FMT.
! 821:
! 822: These functions are not recommended, since there's no protection
! 823: against exceeding the space available at BUF.
! 824:
! 825: - Function: int gmp_snprintf (char *BUF, size_t SIZE, const char *FMT,
! 826: ...)
! 827: - Function: int gmp_vsnprintf (char *BUF, size_t SIZE, const char
! 828: *FMT, va_list AP)
! 829: Form a null-terminated string in BUF. No more than SIZE bytes
! 830: will be written. To get the full output, SIZE must be enough for
! 831: the string and null-terminator.
! 832:
! 833: The return value is the total number of characters which ought to
! 834: have been produced, excluding the terminating null. If RETVAL >=
! 835: SIZE then the actual output has been truncated to the first SIZE-1
! 836: characters, and a null appended.
! 837:
! 838: No overlap is permitted between the region {BUF,SIZE} and the FMT
! 839: string.
! 840:
! 841: Notice the return value is in ISO C99 `snprintf' style. This is
! 842: so even if the C library `vsnprintf' is the older GLIBC 2.0.x
! 843: style.
! 844:
! 845: - Function: int gmp_asprintf (char **PP, const char *FMT, ...)
! 846: - Function: int gmp_vasprintf (char *PP, const char *FMT, va_list AP)
! 847: Form a null-terminated string in a block of memory obtained from
! 848: the current memory allocation function (*note Custom
! 849: Allocation::). The block will be the size of the string and
! 850: null-terminator. Put the address of the block in *PP. Return the
! 851: number of characters produced, excluding the null-terminator.
! 852:
! 853: Unlike the C library `asprintf', `gmp_asprintf' doesn't return -1
! 854: if there's no more memory available, it lets the current allocation
! 855: function handle that.
! 856:
! 857: - Function: int gmp_obstack_printf (struct obstack *OB, const char
! 858: *FMT, ...)
! 859: - Function: int gmp_obstack_vprintf (struct obstack *OB, const char
! 860: *FMT, va_list AP)
! 861: Append to the current obstack object, in the same style as
! 862: `obstack_printf'. Return the number of characters written. A
! 863: null-terminator is not written.
! 864:
! 865: FMT cannot be within the current obstack object, since the object
! 866: might move as it grows.
! 867:
! 868: These functions are available only when the C library provides the
! 869: obstack feature, which probably means only on GNU systems, see
! 870: *Note Obstacks: (libc)Obstacks.
! 871:
! 872:
! 873: File: gmp.info, Node: C++ Formatted Output, Prev: Formatted Output Functions, Up: Formatted Output
! 874:
! 875: C++ Formatted Output
! 876: ====================
! 877:
! 878: The following functions are provided in `libgmpxx', which is built
! 879: if C++ support is enabled (*note Build Options::). Prototypes are
! 880: available from `<gmp.h>'.
! 881:
! 882: - Function: ostream& operator<< (ostream& STREAM, mpz_t OP)
! 883: Print OP to STREAM, using its `ios' formatting settings.
! 884: `ios::width' is reset to 0 after output, the same as the standard
! 885: `ostream operator<<' routines do.
! 886:
! 887: In hex or octal, OP is printed as a signed number, the same as for
! 888: decimal. This is unlike the standard `operator<<' routines on
! 889: `int' etc, which instead give twos complement.
! 890:
! 891: - Function: ostream& operator<< (ostream& STREAM, mpq_t OP)
! 892: Print OP to STREAM, using its `ios' formatting settings.
! 893: `ios::width' is reset to 0 after output, the same as the standard
! 894: `ostream operator<<' routines do.
! 895:
! 896: Output will be a fraction like `5/9', or if the denominator is 1
! 897: then just a plain integer like `123'.
! 898:
! 899: In hex or octal, OP is printed as a signed value, the same as for
! 900: decimal. If `ios::showbase' is set then a base indicator is shown
! 901: on both the numerator and denominator (if the denominator is
! 902: required).
! 903:
! 904: - Function: ostream& operator<< (ostream& STREAM, mpf_t OP)
! 905: Print OP to STREAM, using its `ios' formatting settings.
! 906: `ios::width' is reset to 0 after output, the same as the standard
! 907: `ostream operator<<' routines do. The decimal point follows the
! 908: current locale, on systems providing `localeconv'.
! 909:
! 910: Hex and octal are supported, unlike the standard `operator<<' on
! 911: `double'. The mantissa will be in hex or octal, the exponent will
! 912: be in decimal. For hex the exponent delimiter is an `@'. This is
! 913: as per `mpf_out_str'.
! 914:
! 915: `ios::showbase' is supported, and will put a base on the mantissa,
! 916: for example hex `0x1.8' or `0x0.8', or octal `01.4' or `00.4'.
! 917: This last form is slightly strange, but at least differentiates
! 918: itself from decimal.
! 919:
! 920: These operators mean that GMP types can be printed in the usual C++
! 921: way, for example,
! 922:
! 923: mpz_t z;
! 924: int n;
! 925: ...
! 926: cout << "iteration " << n << " value " << z << "\n";
! 927:
! 928: But note that `ostream' output (and `istream' input, *note C++
! 929: Formatted Input::) is the only overloading available and using for
! 930: instance `+' with an `mpz_t' will have unpredictable results.
! 931:
! 932:
! 933: File: gmp.info, Node: Formatted Input, Next: C++ Class Interface, Prev: Formatted Output, Up: Top
! 934:
! 935: Formatted Input
! 936: ***************
! 937:
! 938: * Menu:
! 939:
! 940: * Formatted Input Strings::
! 941: * Formatted Input Functions::
! 942: * C++ Formatted Input::
! 943:
! 944:
! 945: File: gmp.info, Node: Formatted Input Strings, Next: Formatted Input Functions, Prev: Formatted Input, Up: Formatted Input
! 946:
! 947: Formatted Input Strings
! 948: =======================
! 949:
! 950: `gmp_scanf' and friends accept format strings similar to the
! 951: standard C `scanf' (*note Formatted Input: (libc)Formatted Input.). A
! 952: format specification is of the form
! 953:
! 954: % [flags] [width] [type] conv
! 955:
! 956: GMP adds types `Z', `Q' and `F' for `mpz_t', `mpq_t' and `mpf_t'
! 957: respectively. `Z' and `Q' behave like integers. `Q' will read a `/'
! 958: and a denominator, if present. `F' behaves like a float.
! 959:
! 960: GMP variables don't require an `&' when passed to `gmp_scanf', since
! 961: they're already "call-by-reference". For example,
! 962:
! 963: /* to read say "a(5) = 1234" */
! 964: int n;
! 965: mpz_t z;
! 966: gmp_scanf ("a(%d) = %Zd\n", &n, z);
! 967:
! 968: mpq_t q1, q2;
! 969: gmp_sscanf ("0377 + 0x10/0x11", "%Qi + %Qi", q1, q2);
! 970:
! 971: /* to read say "topleft (1.55,-2.66)" */
! 972: mpf_t x, y;
! 973: char buf[32];
! 974: gmp_scanf ("%31s (%Ff,%Ff)", buf, x, y);
! 975:
! 976: All the standard C `scanf' types behave the same as in the C library
! 977: `scanf', and can be freely intermixed with the GMP extensions. In the
! 978: current implementation the standard parts of the format string are
! 979: simply handed to `scanf' and only the GMP extensions handled directly.
! 980:
! 981: The flags accepted are as follows. `a' and `'' will depend on
! 982: support from the C library, and `'' cannot be used with GMP types.
! 983:
! 984: * read but don't store
! 985: a allocate a buffer (string conversions)
! 986: ' group digits, GLIBC style (not GMP types)
! 987:
! 988: The standard types accepted are as follows. `h' and `l' are
! 989: portable, the rest will depend on the compiler (or include files) for
! 990: the type and the C library for the input.
! 991:
! 992: h short
! 993: hh char
! 994: j intmax_t or uintmax_t
! 995: l long int, double or wchar_t
! 996: ll long long
! 997: L long double
! 998: q quad_t or u_quad_t
! 999: t ptrdiff_t
! 1000: z size_t
! 1001:
! 1002: The GMP types are
! 1003:
! 1004: F mpf_t, float conversions
! 1005: Q mpq_t, integer conversions
! 1006: Z mpz_t, integer conversions
! 1007:
! 1008: The conversions accepted are as follows. `p' and `[' will depend on
! 1009: support from the C library, the rest are standard.
! 1010:
! 1011: c character or characters
! 1012: d decimal integer
! 1013: e E f g G float
! 1014: i integer with base indicator
! 1015: n characters read so far
! 1016: o octal integer
! 1017: p pointer
! 1018: s string of non-whitespace characters
! 1019: u decimal integer
! 1020: x X hex integer
! 1021: [ string of characters in a set
! 1022:
! 1023: `e', `E', `f', `g' and `G' are identical, they all read either fixed
! 1024: point or scientific format, and either `e' or `E' for the exponent in
! 1025: scientific format.
! 1026:
! 1027: `x' and `X' are identical, both accept both upper and lower case
! 1028: hexadecimal.
! 1029:
! 1030: `o', `u', `x' and `X' all read positive or negative values. For the
! 1031: standard C types these are described as "unsigned" conversions, but
! 1032: that merely affects certain overflow handling, negatives are still
! 1033: allowed (see `strtoul', *Note Parsing of Integers: (libc)Parsing of
! 1034: Integers). For GMP types there are no overflows, and `d' and `u' are
! 1035: identical.
! 1036:
! 1037: `Q' type reads the numerator and (optional) denominator as given.
! 1038: If the value might not be in canonical form then `mpq_canonicalize'
! 1039: must be called before using it in any calculations (*note Rational
! 1040: Number Functions::).
! 1041:
! 1042: `Qi' will read a base specification separately for the numerator and
! 1043: denominator. For example `0x10/11' would be 16/11, whereas `0x10/0x11'
! 1044: would be 16/17.
! 1045:
! 1046: `n' can be used with any of the types above, even the GMP types.
! 1047: `*' to suppress assignment is allowed, though the field would then do
! 1048: nothing at all.
! 1049:
! 1050: Other conversions or types that might be accepted by the C library
! 1051: `scanf' cannot be used through `gmp_scanf'.
! 1052:
! 1053: Whitespace is read and discarded before a field, except for `c' and
! 1054: `[' conversions.
! 1055:
! 1056: For float conversions, the decimal point character (or string)
! 1057: expected is taken from the current locale settings on systems which
! 1058: provide `localeconv' (*note Locales and Internationalization:
! 1059: (libc)Locales.). The C library will normally do the same for standard
! 1060: float input.
! 1061:
! 1062: The format string is only interpreted as plain `char's, multibyte
! 1063: characters are not recognised. Perhaps this will change in the future.
! 1064:
! 1065:
! 1066: File: gmp.info, Node: Formatted Input Functions, Next: C++ Formatted Input, Prev: Formatted Input Strings, Up: Formatted Input
! 1067:
! 1068: Formatted Input Functions
! 1069: =========================
! 1070:
! 1071: Each of the following functions is similar to the corresponding C
! 1072: library function. The plain `scanf' forms take a variable argument
! 1073: list. The `vscanf' forms take an argument pointer, see *Note Variadic
! 1074: Functions: (libc)Variadic Functions, or `man 3 va_start'.
! 1075:
! 1076: It should be emphasised that if a format string is invalid, or the
! 1077: arguments don't match what the format specifies, then the behaviour of
! 1078: any of these functions will be unpredictable. GCC format string
! 1079: checking is not available, since it doesn't recognise the GMP
! 1080: extensions.
! 1081:
! 1082: No overlap is permitted between the FMT string and any of the results
! 1083: produced.
! 1084:
! 1085: - Function: int gmp_scanf (const char *FMT, ...)
! 1086: - Function: int gmp_vscanf (const char *FMT, va_list AP)
! 1087: Read from the standard input `stdin'.
! 1088:
! 1089: - Function: int gmp_fscanf (FILE *FP, const char *FMT, ...)
! 1090: - Function: int gmp_vfscanf (FILE *FP, const char *FMT, va_list AP)
! 1091: Read from the stream FP.
! 1092:
! 1093: - Function: int gmp_sscanf (const char *S, const char *FMT, ...)
! 1094: - Function: int gmp_vsscanf (const char *S, const char *FMT, va_list
! 1095: AP)
! 1096: Read from a null-terminated string S.
! 1097:
! 1098: The return value from each of these functions is the same as the
! 1099: standard C99 `scanf', namely the number of fields successfully parsed
! 1100: and stored. `%n' fields and fields read but suppressed by `*' don't
! 1101: count towards the return value.
! 1102:
! 1103: If end of file or file error, or end of string, is reached when a
! 1104: match is required, and when no previous non-suppressed fields have
! 1105: matched, then the return value is EOF instead of 0. A match is
! 1106: required for a literal character in the format string or a field other
! 1107: than `%n'. Whitespace in the format string is only an optional match
! 1108: and won't induce an EOF in this fashion. Leading whitespace read and
! 1109: discarded for a field doesn't count as a match.
! 1110:
! 1111:
! 1112: File: gmp.info, Node: C++ Formatted Input, Prev: Formatted Input Functions, Up: Formatted Input
! 1113:
! 1114: C++ Formatted Input
! 1115: ===================
! 1116:
! 1117: The following functions are provided in `libgmpxx', which is built
! 1118: only if C++ support is enabled (*note Build Options::). Prototypes are
! 1119: available from `<gmp.h>'.
! 1120:
! 1121: - Function: istream& operator>> (istream& STREAM, mpz_t ROP)
! 1122: Read ROP from STREAM, using its `ios' formatting settings.
! 1123:
! 1124: - Function: istream& operator>> (istream& STREAM, mpq_t ROP)
! 1125: Read ROP from STREAM, using its `ios' formatting settings.
! 1126:
! 1127: An integer like `123' will be read, or a fraction like `5/9'. If
! 1128: the fraction is not in canonical form then `mpq_canonicalize' must
! 1129: be called (*note Rational Number Functions::).
! 1130:
! 1131: - Function: istream& operator>> (istream& STREAM, mpf_t ROP)
! 1132: Read ROP from STREAM, using its `ios' formatting settings.
! 1133:
! 1134: Hex or octal floats are not supported, but might be in the future.
! 1135:
! 1136: These operators mean that GMP types can be read in the usual C++
! 1137: way, for example,
! 1138:
! 1139: mpz_t z;
! 1140: ...
! 1141: cin >> z;
! 1142:
! 1143: But note that `istream' input (and `ostream' output, *note C++
! 1144: Formatted Output::) is the only overloading available and using for
! 1145: instance `+' with an `mpz_t' will have unpredictable results.
! 1146:
! 1147:
! 1148: File: gmp.info, Node: C++ Class Interface, Next: BSD Compatible Functions, Prev: Formatted Input, Up: Top
! 1149:
! 1150: C++ Class Interface
! 1151: *******************
! 1152:
! 1153: This chapter describes the C++ class based interface to GMP.
! 1154:
! 1155: All GMP C language types and functions can be used in C++ programs,
! 1156: since `gmp.h' has `extern "C"' qualifiers, but the class interface
! 1157: offers overloaded functions and operators which may be more convenient.
! 1158:
! 1159: Due to the implementation of this interface, a reasonably recent C++
! 1160: compiler is required, one supporting namespaces, partial specialization
! 1161: of templates and member templates. For GCC this means version 2.91 or
! 1162: later.
! 1163:
! 1164: *Everything described in this chapter is to be considered preliminary
! 1165: and might be subject to incompatible changes if some unforeseen
! 1166: difficulty reveals itself.*
! 1167:
! 1168: * Menu:
1.1 maekawa 1169:
1.1.1.2 ! ohara 1170: * C++ Interface General::
! 1171: * C++ Interface Integers::
! 1172: * C++ Interface Rationals::
! 1173: * C++ Interface Floats::
! 1174: * C++ Interface MPFR::
! 1175: * C++ Interface Random Numbers::
! 1176: * C++ Interface Limitations::
1.1 maekawa 1177:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to gmp.info-4 CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [local] / OpenXM_contrib / gmp