From fc50dd81260d58f5ac52e7eb68d0cf15142b84fb Mon Sep 17 00:00:00 2001 From: Stanislav Malyshev Date: Wed, 6 Dec 2000 14:17:36 +0000 Subject: [PATCH] Add GMP module documentation git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@37162 c90b9560-bf6c-de11-be94-00142212c4b1 --- chapters.ent | 1 + functions/gmp.xml | 976 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 977 insertions(+) create mode 100644 functions/gmp.xml diff --git a/chapters.ent b/chapters.ent index 7a22288773..70d563140b 100644 --- a/chapters.ent +++ b/chapters.ent @@ -53,6 +53,7 @@ + diff --git a/functions/gmp.xml b/functions/gmp.xml new file mode 100644 index 0000000000..8026db0f99 --- /dev/null +++ b/functions/gmp.xml @@ -0,0 +1,976 @@ + + GMP functions + GMP + + + These functions allow you to work with arbitrary-length integers + using GNU MP library. In order to have these + functions available, you must compile PHP with + GMP + support by using the + option. + + + You can download the GMP library from &url.gmp;. + This site also has the GMP manual available. + + + You will need GMP version 2 or better to use these functions. Some + functions may require more recent version of the GMP library. + + + These functions have been added in PHP 4.0.4. + + + Most GMP functions accept GMP number arguments, defined as + resource below. However, most of these functions + will accept also numeric and string arguments, given it's possible + to convert the latter to number. Also, if there's faster function that + can operate on integer arguments, it would be used instead of + slower function when supplied arguments are integers. This is done + transparently, so the bootom line is that you can use integers in + every function that expects GMP number. See also + gmp_init function. + + + + + + gmp_init + Create GMP number + + + Description + + + resource gmp_init + mixed number + + + + Creates a GMP number from integer or string. String representation + can be decimal or hexadecimal. In the latter case, the string should + start with 0x. + + + + Creating GMP number + +<?php + $a = gmp_init(123456); + $b = gmp_init("0xFFFFDEBACDFEDF7200"); +?> + + + + + + It is not necessary to call this function if you want to use + integer or string in place of GMP number in GMP functions, like + gmp_add. Function arguments are automatically + converted to GMP numbers, if such conversion is possible and needed, + using the same rules as gmp_init. + + + + + + + + gmp_intval + Convert GMP number to integer + + + Description + + + int gmp_intval + resource gmpnumber + + + + This function allows to convert GMP number to integer. + + This function returns useful result only if the number actually + fits the PHP integer (i.e., signed long type). If you want just to + print the GMP number, use gmp_strval. + + + + + + + + + gmp_strval + Convert GMP number to string + + + Description + + + string gmp_strval + resource gmpnumber + int + base + + + + + Convert GMP number to string representation in base + base. The default base is 10. + Allowed values for the base are from 2 to 36. + + + + Converting GMP number to string + +<?php + $a = gmp_init("0x41682179fbf5"); + printf("Decimal: %s, 36-based: %s", gmp_strval($a), gmp_strval($a,36)); +?> + + + + + + + + + gmp_add + Add numbers + + + Description + + + resource gmp_add + resource a + resource b + + + + Add two GMP numbers. The result will be GMP number representing + the sum of the arguments. + + + + + + + gmp_sub + Subtract numbers + + + Description + + + resource gmp_sub + resource a + resource b + + + + Subtract b from a + and returns the result. + + + + + + + gmp_mul + Multiply numbers + + + Description + + + resource gmp_mul + resource a + resource b + + + + Multiplies a by b + and returns the result. + + + + + + + gmp_div_q + Divide numbers + + + Description + + + resource gmp_div_q + resource a + resource b + int + round + + + + + Divides a by b + and returns the integer result. The result rounding is defined by + the round, which can have the following + values: + + + + GMP_ROUND_ZERO: The result is truncated +towards 0. + + + + + GMP_ROUND_PLUSINF: The result is +rounded towards +infinity. + + + + + GMP_ROUND_MINUSINF: The result is +rounded towards -infinity. + + + + + + This function can also be called as gmp_div. + + + See also gmp_div_r, gmp_div_qr + + + + + + + gmp_div_r + Remainder of the division of numbers + + + Description + + + resource gmp_div_r + resource n + resource d + int + round + + + + + Calculates remainder of the integer division of + n by d. The remainder + has the sign of the n argument, if not zero. + + + See the gmp_div_q function for description + of the round argument. + + + See also gmp_div_q, gmp_div_qr + + + + + + + gmp_div_qr + Divide numbers and get quotient and remainder + + + Description + + + array gmp_div_qr + resource n + resource d + int + round + + + + + The function divides n by + d and returns array, with the first element being + [n/d] (the integer result of the + division) and the second being (n - [n/d] * d) + (the remainder of the division). + + + See the gmp_div_q function for description + of the round argument. + + + + Division of GMP numbers + +<?php + $a = gmp_init("0x41682179fbf5"); + $res = gmp_div_qr($a, "0xDEFE75"); + printf("Result is: q - %s, r - %s", gmp_strval($res[0]), gmp_strval($res[1])); +?> + + + + + See also gmp_div_q, gmp_div_r. + + + + + + + gmp_div + Divide numbers + + + Description + + + resource gmp_divexact + resource a + resource b + + + + This function is an alias to gmp_div_q. + + + + + + + gmp_mod + Modulo operation + + + Description + + + resource gmp_mod + resource n + resource d + + + + Calculates n modulo + d. The result is always non-negative, the + sign of d is ignored. + + + + + + + gmp_divexact + Exact division of numbers + + + Description + + + resource gmp_divexact + resource n + resource d + + + + Divides n by d, + using fast "exact division" algorithm. This function produces + correct results only when it is known in advance that + d divides n. + + + + + + + gmp_cmp + Compare numbers + + + Description + + + int gmp_cmp + resource a + resource b + + + + Returns positive value if a > b, zero if + a = b and negative value if a < b. + + + + + + + gmp_neg + Negate number + + + Description + + + resource gmp_neg + resource a + + + + Returns -a. + + + + + + + gmp_abs + Absolute value + + + Description + + + resource gmp_abs + resource a + + + + Returns absolute value of a. + + + + + + + gmp_sign + Sign of number + + + Description + + + int gmp_sign + resource a + + + + Return sign of a - 1 if + a is positive and -1 if it's negative. + + + + + + + gmp_fact + Factorial + + + Description + + + resource gmp_fact + int a + + + + Calculates factorial (a!) of a. + + + + + + + gmp_sqrt + Square root + + + Description + + + resource gmp_sqrt + resource a + + + + Calculates square root of a. + + + + + + + gmp_sqrtrm + Square root with remainder + + + Description + + + array gmp_sqrtrm + resource a + + + + Returns array where first element is the integer square root of + a (see also gmp_sqrt), and + the second is the remainder (i.e., the difference between + a and the first element squared). + + + + + + + gmp_perfect_square + Perfect square check + + + Description + + + bool gmp_perfect_square + resource a + + + + Returns true if a is a prefect square, + false otherwise. + + + See also: gmp_sqrt, + gmp_sqrtrm. + + + + + + + gmp_pow + Raise number into power + + + Description + + + resource gmp_pow + resource base + int exp + + + + Raise base into power + exp. The case of 0^0 yields + 1. exp cannot be negative. + + + + + + + gmp_powm + Raise number into power with modulo + + + Description + + + resource gmp_powm + resource base + resource exp + resource mod + + + + Calculate (base raised into power + exp) modulo mod. If + exp is negative, result is undefined. + + + + + + + gmp_prob_prime + Check if number is "probably prime" + + + Description + + + int gmp_prob_prime + resource a + int reps + + + + If this function returns 0, a is definitely + not prime. If it returns 1, then a is + "probably" prime. If it returns 2, then a is + surely prime. Reasonable values of reps + vary from 5 to 10 (default being 10); a higher value lowers the + probability for a non-prime to pass as a "probable" prime. + + + The function uses Miller-Rabin's probabilistic test. + + + + + + + gmp_gcd + Calculate GCD + + + Description + + + resource gmp_gcd + resource a + resource b + + + + Calculate greatest common divisor of a and + b. The result is always positive even if + either of or both input operands are negative. + + + + + + + gmp_gcdext + Calculate GCD and multipliers + + + Description + + + array gmp_gcdext + resource a + resource b + + + + Calculates g, s, and t, such that + a*s + b*t = g = gcd(a,b), where gcd is gretest + common divisor. Returns array with respective elements g, s and t. + + + + + + + gmp_invert + Inverse by modulo + + + Description + + + resource gmp_invert + resource a + resource b + + + + Computes the inverse of a modulo + b. Returns false if an inverse does not exist. + + + + + + + gmp_legendre + Legendre symbol + + + Description + + + int gmp_legendre + resource a + resource p + + + + Compute the + + Legendre symbol of a and + p. p should be odd + and must be positive. + + + + + + + gmp_jacobi + Jacobi symbol + + + Description + + + int gmp_jacobi + resource a + resource p + + + + Computes + + Jacobi symbol of a and + p. p should be odd + and must be positive. + + + + + + + gmp_random + Random number + + + Description + + + resource gmp_random + int limiter + + + + Generate a random number. The number will be up to + limiter words long. If + limiter is negative, negative numbers are generated. + + + + + + + gmp_and + Logical AND + + + Description + + + resource gmp_and + resource a + resource b + + + + Calculates logical AND of two GMP numbers. + + + + + + + gmp_or + Logical OR + + + Description + + + resource gmp_or + resource a + resource b + + + + Calculates logical inclusive OR of two GMP numbers. + + + + + + + gmp_xor + Logical XOR + + + Description + + + resource gmp_xor + resource a + resource b + + + + Calculates logical exclusive OR (XOR) of two GMP numbers. + + + + + + + gmp_setbit + Set bit + + + Description + + + resource gmp_setbit + resource &a + int index + bool set_clear + + + + Sets bit index in + a. set_clear defines + if the bit is set to 0 or 1. By default the bit is set to 1. + + + + + + + gmp_clrbit + Clear bit + + + Description + + + resource gmp_clrbit + resource &a + int index + + + + Clears (sets to 0) bit index in + a. + + + + + + + gmp_scan0 + Scan for 0 + + + Description + + + int gmp_scan0 + resource a + int start + + + + Scans a, starting with bit + start, towards more significant + bits, until the first clear bit is found. Returns the index of the + found bit. + + + + + + + gmp_scan1 + Scan for 1 + + + Description + + + int gmp_scan1 + resource a + int start + + + + Scans a, starting with bit + start, towards more significant + bits, until the first set bit is found. Returns the index of the + found bit. + + + + + + + gmp_popcount + Population count + + + Description + + + int gmp_popcount + resource a + + + + Return the population count of a. + + + + + + + gmp_hamdist + Hamming distance + + + Description + + + int gmp_hamdist + resource a + resource b + + + + Returns the hamming distance between a and + a. Both operands should be non-negative. + + + + + + + +