mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) NNNNAAAAMMMMEEEE mpexpr - Evaluate an expression with multiple precision math SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ppppaaaacccckkkkaaaaggggeeee rrrreeeeqqqquuuuiiiirrrreeee MMMMppppeeeexxxxpppprrrr mmmmppppeeeexxxxpppprrrr _a_r_g ?_a_r_g _a_r_g ...? mmmmppppffffoooorrrrmmmmaaaatttt _f_o_r_m_a_t_S_t_r_i_n_g ?_a_r_g _a_r_g ...? gggglllloooobbbbaaaallll mmmmpppp____pppprrrreeeecccciiiissssiiiioooonnnn DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN Mpexpr is based on Tcl's native _e_x_p_r command, and shares many similarities with _e_x_p_r. Mpexpr performs all of its calculations using an arbitrary precision math package. Mpexpr concatenates _a_r_g's (adding separator spaces between them), evaluates the result as a Tcl expression, and returns the value. The operators permitted in Tcl expressions are a subset of the operators permitted in C expressions, and they have the same meaning and precedence as the corresponding C operators. Expressions almost always yield numeric results (integer or floating-point values). For example, the expression mmmmppppeeeexxxxpppprrrr 8888....2222 ++++ 6666 evaluates to 14.2. Tcl expressions differ from C expres- sions in the way that operands are specified. Also, Tcl expressions support non-numeric operands and string com- parisons. OOOOPPPPEEEERRRRAAAANNNNDDDDSSSS A Tcl expression consists of a combination of operands, operators, and parentheses. White space may be used between the operands and operators and parentheses; it is ignored by the expression processor. Where possible, operands are interpreted as integer values. Integer values may be speci- fied in decimal (the normal case), in octal (if the first character of the operand is 0000), or in hexadecimal (if the first two characters of the operand are 0000xxxx). If an operand does not have one of the integer formats given above, then it is treated as a floating-point number if that is possi- ble. Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler (except that the ``f'', ``F'', ``l'', and ``L'' suffixes will not be per- mitted in most installations). For example, all of the fol- lowing are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If no numeric interpretation is possible, then an operand is left as a string (and only a limited set of operators may be applied to it). Tcl Last change: 8 January 1998 1 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) Operands may be specified in any of the following ways: [1] As an numeric value, either integer or floating-point. [2] As a Tcl variable, using standard $$$$ notation. The variable's value will be used as the operand. [3] As a string enclosed in double-quotes. The expression parser will perform backslash, variable, and command substitutions on the information between the quotes, and use the resulting value as the operand [4] As a string enclosed in braces. The characters between the open brace and matching close brace will be used as the operand without any substitutions. [5] As a Tcl command enclosed in brackets. The command will be executed and its result will be used as the operand. [6] As a mathematical function whose arguments have any of the above forms for operands, such as ``ssssiiiinnnn(((($$$$xxxx))))''. See below for a list of defined functions. Where substitutions occur above (e.g. inside quoted strings), they are performed by the expression processor. However, an additional layer of substitution may already have been performed by the command parser before the expres- sion processor was called. As discussed below, it is usu- ally best to enclose expressions in braces to prevent the command parser from performing substitutions on the con- tents. For some examples of simple expressions, suppose the vari- able aaaa has the value 3 and the variable bbbb has the value 6. Then the command on the left side of each of the lines below will produce the value on the following line: mmmmppppeeeexxxxpppprrrr 3333....1111 ++++ $$$$aaaa 6.1 mmmmppppeeeexxxxpppprrrr 2222 ++++ """"$$$$aaaa....$$$$bbbb"""" 5.6 mmmmppppeeeexxxxpppprrrr 4444****[[[[lllllllleeeennnnggggtttthhhh """"6666 2222""""]]]] 8 mmmmppppeeeexxxxpppprrrr {{{{{{{{wwwwoooorrrrdddd oooonnnneeee}}}} <<<< """"wwwwoooorrrrdddd $$$$aaaa""""}}}} 0 Tcl Last change: 8 January 1998 2 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) OOOOPPPPEEEERRRRAAAATTTTOOOORRRRSSSS The valid operators are listed below, grouped in decreasing order of precedence: ---- ++++ ~~~~ !!!! Unary minus, unary plus, bit-wise NOT, logical NOT. None of these operands may be applied to string operands, and bit- wise NOT may be applied only to integers. **** //// %%%% Multiply, divide, remainder. None of these operands may be applied to string operands, and remainder may be applied only to integers. The remainder will always have the same sign as the divisor and an absolute value smaller than the divisor. ++++ ---- Add and subtract. Valid for any numeric operands. <<<<<<<< >>>>>>>> Left and right shift. Valid for integer operands only. Integers in mpexpr are not limited to a machine word and do not use two's complement format. Therefore shifting will not include a sign bit. <<<< >>>> <<<<==== >>>>==== Boolean less, greater, less than or equal, and greater than or equal. Each operator produces 1 if the condition is true, 0 otherwise. These operators may be applied to strings as well as numeric operands, in which case string com- parison is used. ======== !!!!==== Boolean equal and not equal. Each operator produces a zero/one result. Valid for all operand types. &&&& Bit-wise AND. Valid for integer operands only. ^^^^ Bit-wise exclusive OR. Valid for integer operands only. |||| Bit-wise OR. Valid for integer operands only. &&&&&&&& Logical AND. Produces a 1 result if both operands are non-zero, 0 otherwise. Valid for numeric operands only (integers or floating-point). Tcl Last change: 8 January 1998 3 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) |||||||| Logical OR. Produces a 0 result if both operands are zero, 1 otherwise. Valid for numeric operands only (integers or floating-point). _x????_y::::_z If-then-else, as in C. If _x evaluates to non-zero, then the result is the value of _y. Otherwise the result is the value of _z. The _x operand must have a numeric value. See the C manual for more details on the results produced by each operator. All of the binary operators group left-to- right within the same precedence level. For example, the command mmmmppppeeeexxxxpppprrrr 4444****2222 <<<< 7777 returns 0. The &&&&&&&&, ||||||||, and ????:::: operators have ``lazy evaluation'', just as in C, which means that operands are not evaluated if they are not needed to determine the outcome. For example, in the command mmmmppppeeeexxxxpppprrrr {{{{$$$$vvvv ???? [[[[aaaa]]]] :::: [[[[bbbb]]]]}}}} only one of [[[[aaaa]]]] or [[[[bbbb]]]] will actually be evaluated, depending on the value of $$$$vvvv. Note, however, that this is only true if the entire expression is enclosed in braces; otherwise the Tcl parser will evaluate both [[[[aaaa]]]] and [[[[bbbb]]]] before invok- ing the eeeexxxxpppprrrr command. MMMMAAAATTTTHHHH FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS Mpexpr supports the following mathematical functions in expressions. _x and _y are integer or floating point values; _i, _j and _c are integer values; Math functions compatible with _e_x_p_r: aaaaccccoooossss((((_x)))) Arc cosine of _x. aaaassssiiiinnnn((((_x)))) Arc sine of _x. aaaattttaaaannnn((((_x)))) Arc tangent of _x. aaaattttaaaannnn2222((((_x,_y)))) Arc tangent of _x / _y. cccceeeeiiiillll((((_x)))) Least integral value greater than or equal to _x. Tcl Last change: 8 January 1998 4 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) ccccoooossss((((_x)))) Cosine of _x. ccccoooosssshhhh((((_x)))) Hyperbolic cosine of _x. eeeexxxxpppp((((_x)))) Exponential function e ** _x. fffflllloooooooorrrr((((_x)))) Greatest integral value less than or equal to _x. ffffmmmmoooodddd((((_x,_y)))) Remainder of _x divided by _y. hhhhyyyyppppooootttt((((_x,_y)))) Euclidean distance of sqrt( _x * _x + _y * _y). lllloooogggg((((_x)))) Natural logarithm of _x. lllloooogggg11110000((((_x)))) Base-10 logarithm of _x. ppppoooowwww((((_x,_y)))) _x raised to the _y power. ssssiiiinnnn((((_x)))) Sine of _x. ssssiiiinnnnhhhh((((_x)))) Hyperbolic sine of _x. ssssqqqqrrrrtttt((((_x)))) Square root of _x. ttttaaaannnn((((_x)))) Tangent of _x. ttttaaaannnnhhhh((((_x)))) Hyperbolic tangent of _x. aaaabbbbssss((((_x)))) Returns the absolute value of _x. _x may be either integer or floating-point, and the result is returned in the same form. ddddoooouuuubbbblllleeee((((_x)))) If _x is a floating value, returns _x, other- wise converts _x to floating and returns the converted value. iiiinnnntttt((((_x)))) If _x is an integer value, returns _x, other- wise converts _x to integer by truncation and returns the converted value. rrrroooouuuunnnndddd((((_x)))) If _x is an integer value, returns _x, other- wise converts _x to integer by rounding and returns the converted value. Additional _m_p_e_x_p_r functions: rrrrooooooootttt((((_x,_y)))) The _y_t_h root of _x. ffffrrrreeeemmmm((((_x,_y)))) Remove all occurance of factor_y from number _x. Tcl Last change: 8 January 1998 5 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) mmmmiiiinnnnvvvv((((_x,_y)))) Inverse of _x modulo _y. ggggccccdddd((((_x,_y)))) Greatest common divisor of _x and _y. llllccccmmmm((((_x,_y)))) Least common multiple of _x and _y. mmmmaaaaxxxx((((_x,_y)))) Maximum of _x and _y. mmmmiiiinnnn((((_x,_y)))) Minimum of _x and _y. ppppiiii(((()))) Value of pi. ffffiiiibbbb((((_i)))) Fibonacci number of integer _i. ffffaaaacccctttt((((_i)))) Factorial of integer _i. ppppffffaaaacccctttt((((_i)))) Product of prime numbers up to integer _i. llllffffaaaaccccttttoooorrrr((((_i,_c)))) Lowest prime factor of integer _i, trying count _c times. iiiirrrrooooooootttt((((_i,_j)))) Integer root _j of integer _i. ggggccccddddrrrreeeemmmm((((_i,_j)))) Relatively prime of greatest common divisior of _i divided by _j. ppppeeeerrrrmmmm((((_i,_j)))) Permutations of _i taking _j at a time: _i ! / ( _i - _j ) !. ccccoooommmmbbbb((((_i,_j)))) Combinations of _i taking _j at a time: _i ! / ( _j ! * ( _i - _j ) ! ) . pppprrrriiiimmmmeeee((((_i,_c)))) Return 0 if _i is not prime, return 1 if _i probably is prime. Test for primality count _c times. The chance of a non-prime passing this test is less than (1/4)^count. For example, a count of 100 fails for only 1 in 10^60 numbers. rrrreeeellllpppprrrriiiimmmmeeee((((_i,_j)))) Return 1 if _i and _j are relatively prime to each other, 0 otherwise. TTTTYYYYPPPPEEEESSSS,,,, OOOOVVVVEEEERRRRFFFFLLLLOOOOWWWW,,,, AAAANNNNDDDD PPPPRRRREEEECCCCIIIISSSSIIIIOOOONNNN Computations are performed using arbitrary fixed and float- ing point values. Native machine values (_i_n_t, _l_o_n_g, _I_E_E_E _7_5_4 _f_l_o_a_t_i_n_g _p_o_i_n_t, _e_t_c. ) and instructions are not used. Conversion among internal representations for integer, floating-point, and string operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example, Tcl Last change: 8 January 1998 6 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) mmmmppppeeeexxxxpppprrrr 5555 //// 4444 returns 1, while mmmmppppeeeexxxxpppprrrr 5555 //// 4444....0000 mmmmppppeeeexxxxpppprrrr 5555 //// (((( [[[[ssssttttrrrriiiinnnngggg lllleeeennnnggggtttthhhh """"aaaabbbbccccdddd""""]]]] ++++ 0000....0000 )))) both return 1.25. Floating-point values are always returned with a ``.'' or an ``e'' so that they will not look like integer values. For example, mmmmppppeeeexxxxpppprrrr 22220000....0000////5555....0000 returns ``4.0'', not ``4''. The global variable mmmmpppp____pppprrrreeeecccciiiissssiiiioooonnnn determines the number of significant digits that are retained during evaluation. If mmmmpppp____pppprrrreeeecccciiiissssiiiioooonnnn is unset then 17 digits of precision are used. The maximum value of mmmmpppp____pppprrrreeeecccciiiissssiiiioooonnnn is 10000. Note that larger values for mmmmpppp____pppprrrreeeecccciiiissssiiiioooonnnn will require increas- ingly longer execution times. Setting mmmmpppp____pppprrrreeeecccciiiissssiiiioooonnnn to an illegal value will generate an error. SSSSTTTTRRRRIIIINNNNGGGG OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNNSSSS String values may be used as operands of the comparison operators, although the expression evaluator tries to do comparisons as integer or floating-point when it can. If one of the operands of a comparison is a string and the other has a numeric value, the numeric operand is converted back to a string using the C _s_p_r_i_n_t_f format specifier %%%%dddd for integers and %%%%gggg for floating-point values. For example, the commands mmmmppppeeeexxxxpppprrrr {{{{""""0000xxxx00003333"""" >>>> """"2222""""}}}} mmmmppppeeeexxxxpppprrrr {{{{""""0000yyyy"""" <<<< """"0000xxxx11112222""""}}}} both return 1. The first comparison is done using integer comparison, and the second is done using string comparison after the second operand is converted to the string ``18''. Because of Tcl's tendency to treat values as numbers when- ever possible, it isn't generally a good idea to use opera- tors like ======== when you really want string comparison and the values of the operands could be arbitrary; it's better in these cases to use the ssssttttrrrriiiinnnngggg ccccoooommmmppppaaaarrrreeee command instead. mmmmppppffffoooorrrrmmmmaaaatttt formats a string in the style of Tcl's native _f_o_r_- _m_a_t command. Mpformat will interpret numeric arguments as arbitrary precision numbers. Mpformat performs limited % substitution on the output string. The following may be specified: %%%% [[[[----]]]] [[[[wwwwiiiiddddtttthhhh[[[[....pppprrrreeeecccciiiissssiiiioooonnnn]]]]]]]] ffffoooorrrrmmmmaaaattttCCCChhhhaaaarrrr Tcl Last change: 8 January 1998 7 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) ---- Specifies left justification; right justification is the default. wwwwiiiiddddtttthhhh....pppprrrreeeecccciiiissssiiiioooonnnn Specifies optional width and precision. Default preci- sion is 8. Width and/or precision may be specified as ****, in which the next argument will be used for the width or precision value. FFFFoooorrrrmmmmaaaatttt cccchhhhaaaarrrraaaacccctttteeeerrrr aaaannnndddd rrrreeeessssuuuulllltttt dddd Format next argument as integer, truncating after the decimal point. ffff Format next argument in decimal floating point. eeee Format next argument in scientific notation. rrrr, RRRR Format next argument as rational fraction x / y. NNNN Format next argument as numerator only of rational fraction x / y. DDDD Format next argument as denominator only of rational fraction x / y. oooo Format next argument in octal format, with leading '0'; floating point argument formatted as octal rational fraction x / y. xxxx Format next argument in hexadecimal format, with lead- ing '0x'; floating point formatted argument as hexade- cimal rational fraction x / y. bbbb Format next argument in binary format, with leading '0b'; floating point argument formatted as binary rational fraction x / y. ssss Format next argument as string. cccc Format next argument as single character value. %%%% Format single literal %. OOOOtttthhhheeeerrrr cccchhhhaaaarrrraaaacccctttteeeerrrrssss iiiinnnn ffffoooorrrrmmmmaaaatttt ssssttttrrrriiiinnnngggg Format ASCII newline. 7 Format ASCII carriage return. Format ASCII tab. Tcl Last change: 8 January 1998 8 mpexpr(TCL) Misc. Reference Manual Pages mpexpr(TCL) Format ASCII form feed. Format ASCII vertical tab. Format ASCII backspace. NNNNOOOOTTTTEEEESSSS Mpexpr is based on Tcl 7.6 'tclExpr.c' and David Bell's 'Calc' program. This man page is largely borrowed from Tcl 7.6 as well, as is the mpexpr test suite. See the files README and INSTALL for additional information. Tcl 7.6 is Copyright (c) 1987-1994 The Regents of the University of California and Copyright (c) 1994 Sun Microsystems, Inc. Calc is Copyright (c) 1994 David I. Bell. AAAAUUUUTTTTHHHHOOOORRRR Tom Poindexter, tpoindex@nyx.net, Talus Technologies, Inc., Highlands Ranch, CO. http://www.nyx.net/~tpoindex Version 1.0 released November, 1998. Copyright 1998 Tom Poindexter. See the file 'LICENSE.TERMS' for additional copyright and licensing terms. Tcl Last change: 8 January 1998 9