readme

a very popular packet of cryptography tools,it encloses the most common used algorithm and protocols

Copyright 2001 Free Software Foundation, Inc.

This file is part of the GNU MP Library.

The GNU MP Library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as published by
the Free Software Foundation; either version 2.1 of the License, or (at your
option) any later version.

The GNU MP Library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public
License for more details.

You should have received a copy of the GNU Lesser General Public License
along with the GNU MP Library; see the file COPYING.LIB.  If not, write to
the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
02111-1307, USA.






                    GMP EXPRESSION EVALUATION
                    -------------------------



THIS CODE IS PRELIMINARY AND MAY BE SUBJECT TO INCOMPATIBLE CHANGES IN
FUTURE VERSIONS OF GMP.



The files in this directory implement a simple scheme of string based
expression parsing and evaluation, supporting mpz, mpq, mpf and mpfr.

This will be slower than direct GMP library calls, but may be convenient in
various circumstances, such as while prototyping, or for letting a user
enter values in symbolic form.  "2**5723-7" for example is a lot easier to
enter or maintain than the equivalent written out in decimal.



BUILDING

Nothing in this directory is a normal part of libgmp, and nothing is built
or installed, but various Makefile rules are available to compile
everything.

All the functions are available through a little library (there's no shared
library since upward binary compatibility is not guaranteed).

	make libexpr.a

In a program, prototypes are available using

	#include "expr.h"

run-expr.c is a sample program doing evaluations from the command line.

	make run-expr
	./run-expr '1+2*3'

t-expr.c is self-test program, it prints nothing if successful.

	make t-expr
	./t-expr

The expr*.c sources don't depend on gmp-impl.h and can be compiled with just
a standard installed GMP.  This isn't true of t-expr though, since it uses
some of the internal tests/libtests.la.



OPTIONAL MPFR

The mpfr support in libexpr.a is built if GMP is configured with
--enable-mpfr.  Programs must include mpfr.h before expr.h to get the extra
prototypes,

	 #include "mpfr.h"
	 #include "expr.h"

If the expr sources are being compiled outside a GMP build tree, then change
HAVE_MPFR in expr-impl.h if necessary to indicate whether mpfr is available.
exprfr.c and exprfra.c are the C files providing mpfr support.




SIMPLE USAGE

int mpz_expr (mpz_t res, int base, const char *e, ...);
int mpq_expr (mpq_t res, int base, const char *e, ...);
int mpf_expr (mpf_t res, int base, const char *e, ...);
int mpfr_expr (mpfr_t res, int base, const char *e, ...);

These functions evaluate simple arithmetic expressions.  For example,

	mpz_expr (result, 0, "123+456", NULL);

Numbers are parsed by mpz_expr and mpq_expr the same as mpz_set_str with the
given base.  mpf_expr and mpfr_expr follow mpf_set_str and mpfr_set_str
respectively, but supporting an "0x" prefix for hex when base==0.

	mpz_expr (result, 0, "0xAAAA * 0x5555", NULL);

White space, as indicated by <ctype.h> isspace(), is ignored except for the
purpose of separating tokens.

Variables can be included in expressions by putting them in the varargs list
after the string.  "a", "b", "c" etc in the expression string designate
those values.  For example,

        mpq_t  foo, bar;
        ...
	mpq_expr (q, 10, "2/3 + 1/a + b/2", foo, bar, NULL);

Here "a" will be the value from foo and "b" from bar.  Up to 26 variables
can be included this way.  The NULL must be present to indicate the end of
the list.

Variables can also be written "$a", "$b" etc.  This is necessary when using
bases greater than 10 since plain "a", "b" etc will otherwise be interpreted
as numbers.  For example,

        mpf_t  quux;
        mpf_expr (f, 16, "F00F@-6 * $a", quux, NULL);

All the standard C operators are available, with the usual precedences, plus
"**" for exponentiation at the highest precedence (and right associative).

        Operators      Precedence
         **              220
         ~ ! - (unary)   210
         * / %           200
         + -             190
         << >>           180
         <= < >= >       170
         == !=           160
         &               150
         ^               140
         |               130
         &&              120
         ||              110
         ? :             100/101

Currently only mpz_expr has the bitwise ~ % & ^ and | operators.  The
precedence numbers are of interest in the advanced usage described below.

Various functions are available too.  For example,

        mpz_expr (res, 10, "gcd(123,456,789) * abs(a)", var, NULL);

The following is the full set of functions,

        mpz_expr
            abs bin clrbit cmp cmpabs congruent_p divisible_p even_p fib fac
            gcd hamdist invert jacobi kronecker lcm lucnum max min nextprime
            odd_p perfect_power_p perfect_square_p popcount powm
            probab_prime_p root scan0 scan1 setbit sgn sqrt

        mpq_expr
            abs, cmp, den, max, min, num, sgn

        mpf_expr
            abs, ceil, cmp, eq, floor, integer_p, max, min, reldiff, sgn,
            sqrt, trunc

        mpfr_expr
            abs, agm, ceil, cmp, cos, eq, exp, floor, inf_p, log, max, min,
            nan_p, number_p, reldiff, sgn, sin, sqrt, trunc

In addition mpfr_expr has constants "log2" and "pi".  For example,

	mpfr_expr (res, 0, "2 * pi - log2", NULL);

All these are the same as the GMP library functions, except that min and max
don't exist in the library.  Note also that min, max, gcd and lcm take any
number of arguments, not just two.


mpf_expr and mpfr_expr do all calculations to the precision of the
destination variable.  mpfr_expr rounds using GMP_RNDZ (but this can be
changed at build time in expr-impl.h).


Expression parsing can succeed or fail.  The return value indicates this,
and will be one of the following

	MPEXPR_RESULT_OK
	MPEXPR_RESULT_BAD_VARIABLE
	MPEXPR_RESULT_BAD_TABLE
	MPEXPR_RESULT_PARSE_ERROR
	MPEXPR_RESULT_NOT_UI

BAD_VARIABLE is when a variable is referenced that hasn't been provided.
For example if "c" is used when only two parameters have been passed.
BAD_TABLE is applicable to the advanced usage described below.

PARSE_ERROR is a general syntax error, returned for any mal-formed input
string.

NOT_UI is returned when an attempt is made to use an operand that's bigger
than an "unsigned long" with a function that's restricted to that range.
For example "fib" is mpz_fib_ui and only accepts an "unsigned long".




ADVANCED USAGE

int mpz_expr_a (const struct mpexpr_operator_t *table,
                mpz_ptr res, int base, const char *e, size_t elen,
                mpz_srcptr var[26])
int mpq_expr_a (const struct mpexpr_operator_t *table,
                mpq_ptr res, int base, const char *e, size_t elen,
                mpq_srcptr var[26])
int mpf_expr_a (const struct mpexpr_operator_t *table,
                mpf_ptr res, int base, unsigned long prec,
                const char *e, size_t elen,
                mpf_srcptr var[26])
int mpfr_expr_a (const struct mpexpr_operator_t *table,
                 mpfr_ptr res, int base, unsigned long prec,
                 const char *e, size_t elen,
                 mpfr_srcptr var[26])

These functions are an advanced interface to expression parsing.

The string is taken as pointer and length.  This makes it possible to parse
an expression in the middle of somewhere without copying and null
terminating it.

Variables are an array of 26 pointers to the appropriate operands, or NULL
for variables that are not available.  Any combination of variables can be
given, for example just "x" and "y" (var[23] and var[24]) could be set.

Operators and functions are specified with a table.  This makes it possible
to provide additional operators or functions, or to completely change the
syntax.  The standard tables used by the simple functions above are
available as

	const struct mpexpr_operator_t * const mpz_expr_standard_table;
	const struct mpexpr_operator_t * const mpq_expr_standard_table;
	const struct mpexpr_operator_t * const mpf_expr_standard_table;
	const struct mpexpr_operator_t * const mpfr_expr_standard_table;

struct mpexpr_operator_t is the following

	struct mpexpr_operator_t {
	  const char    *name;
	  mpexpr_fun_t  fun;
	  int           type;
	  int           precedence;
	};

        typedef void (*mpexpr_fun_t) (void);

As an example, the standard mpz_expr table entry for multiplication is as
follows.  See the source code for the full set of standard entries.

	{ "*", (mpexpr_fun_t) mpz_mul, MPEXPR_TYPE_BINARY, 200 },