NAME

SYNOPSIS

  use Math::RPN;
  $value = rpn(expr...);
  @array = rpn(expr...);

expr... is one or more scalars or lists of scalars which contain RPN expressions. An RPN expression is a series of numbers and/or operators separated by commas. (commas are only required within scalars).

See EXAMPLES

EXAMPLES

    100,9,*,5,/,32,+    Convert 100 degrees C to 212 degrees F
                        (100*9/5+32)

    5,3,LT,100,500,IF   Yields 500
                        (5!<3=0,100,500,IF==500, the "else" clause)

  rpn(1, 2, '+')           is the same as 1+2   that returns 3
  rpn(1, 2, '+', 3, '*')   is the same as 1+2*3 that returns 9

DESCRIPTION

In the event of an error, an error message will be sent to STDERR, and rpn will return undef.

The expression can contain any combination of values and operators. Any token which is not an operator is assumed to be a value to be pushed onto the stack.

An explanation of Reverse Polish Notation is beyond the scope of this document, but it I will describe it briefly as a stack-based way of writing mathematical expressions. This has the advantage of eliminating the need for parenthesis and simplifying parsing for computers vs. normal algebraic notation at a slight cost in the ability of humans to easily comprehend the expressions.

This evaluator works by cycling through the expression from left to right. As each token is encountered, it is checked against the list of operators. If it matches, then a check is performed for stack underflow. If the stack has not underflowed, the operation is performed by removing the required number of operands from the top of the stack. The result is then pushed on to the stack. Operations for which order is significant (-,/,%,etc.) are processed such that the top item on the stack is treated as the right operand, and the next item down is treated as the left operand. Thus, "5,3,-" would yield 2, not -2. If the token does not match any of the known operators, the token is blindly pushed onto the stack. As a result, one can produce unexpected results. For example, the expression "5,3,grandma,+,*" would produce 15 because 5*(3+0) is how it would end up evaluated. That is, 5 would be pushed onto the stack, then 3, then "grandma". Next, + is evaluated, so 3+"grandma" is evaluated. Perl evaluates "grandma" to be numerically 0, so 3 is pushed back onto the stack. Next, the * multiplies the top two items of the stack [5][3], producing 15, which is pushed back onto the stack.

OPERATORS

Additionally, there are constructs like (condition ? result : otherwise) which indicate that if condition is true, result will be placed on the stack. If condition is false, otherwise will be placed on the stack. Thus, (a!=0 ? [b] : [c]) means that if a is not equal to 0, the [b] will be placed on the stack. If a is equal to 0, then [c] will be placed on the stack.

A glossary of other symbols is provided below for reference.

The following operators are supported in the RPN evaluator:

       Operator        Operation
       +,ADD           [a][b]->[a+b]
       ++,INCR         [a]->[a+1]
       -,SUB           [a][b]->[a-b]
       --,DECR         [a]->[a-1]
       *,MUL           [a][b]->[a*b]
       /,DIV           [a][b]->[a/b]
       %,MOD           [a][b]->[a%b]
       POW             [a][b]->[a^b]
       SQRT            [a]->[sqrt(a)]

       SIN             [a]->[sin(a)]
       COS             [a]->[cos(a)]
       TAN             [a]->[tan(a)]

       LOG             [a]->[log(a)]
       EXP             [a]->[e^a]

       ABS             [a]->[abs(a)]
       INT             [a]->[int(a)]

       &,AND           [a][b]->[a&b]
       |,OR            [a][b]->[a|b]
       !,NOT           [a]->(a==0 ? [1] : [0])
       XOR             [a][b]=>[a xor b] (exclusive or)
       ~               [a]->(a ^ -1) (Inverts all the bits in a)

       <,LT            [a][b]->(a<b ? [1] : [0])
       <=,LE           [a][b]->(a<=b ? [1] : [0])
       =,==,EQ         [a][b]->(a==b ? [1] : [0])
       >,GT            [a][b]->(a>b ? [1] : [0])
       >=,GE           [a][b]->(a>=b ? [1] : [0])
       !=,NE           [a][b]=>(a!=b ? [1] : [0])

       IF              [a][b][c]-> (a!=0 ? [b] : [c])

       DUP             [a]->[a][a]
       EXCH            [a][b]->[b][a]
       POP             [a][b]->[a]

       MIN             [a][b]->([a]<[b] ? [a] : [b])
       MAX             [a][b]->([a]>[b] ? [a] : [b])

       TIME            Pushes current time
                        (seconds since midnight UTC 1970)

       RAND            Pushes a random number 0<x<1 onto the stack.
       LRAND           [a]->[x=rand(0<x<a)]

Bitwise Boolean operations (&,|,!,~) are performed against the integerized (truncated) versions of the values on the stack. That is, [a][b]->[a&b] is performed internally as "push(@stack, (int(pop(@stack))&int(pop(@stack))))".

In addition, the IF operator supports special constructs for the "then" and "else" clauses on the stack. The construct allows an RPN expression to be enclosed in curly braces ({expr}), which will cause the entire expression to be pushed on to the stack unevaluated. If this expression is to be pushed onto the stack as a result of an IF, it is evaluated at that time. This allows more flexibility in IF statements and provides some performance benefits because any computations in the unused clause are not performed.

An example would look like so:

    1,{,5,3,+,10,*,},{,1,2,3,+,+,},IF

This example would result in the stack containing 80 at the end of the evaluation. First, the IF would be true because 1, so {,5,3,+,10,*,} would be evaluated and the result placed on the stack.

REFERENCE

    SYMBOL      CATEGORY        Meaning
      ^         (MATH)          Power of (x^y is X to the power of Y,
                                x^2 is X Squared, etc.)

WARNING: ^ is marked as poser here while in perl ** marks "power" and ^ is the bitwise xor. There might be some changes in this module later on to straigthen this out.

      %         (MATH)          Modulus, or Division Remainder

      &         (BOOLEAN)       Boolean Bitwise AND

      |         (BOOLEAN)       Boolean Bitwise OR

      !         (BOOLEAN)       Invert a boolean value
                                (true->false, false->true)

     sqrt       (MATH)          Square Root (sqrt(9) is 3)

     sin        (TRIG)          SINE of the given angle (in radians)

     cos        (TRIG)          COSINE of the given angle (in radians)

     tan        (TRIG)          TANGENT of the given angle (in radians)

     log        (MATH)          The logarithm of the given number. (such
                                that e^log(x) is x [e is an irrational
                                mathematical constant used for all sorts
                                of things])

     exp        (MATH)          The opposite of log. exp(x) returns e^x.
                                exp(log(x)) returns x.

     abs        (MATH)          The "absolute" value of the given number.
                                abs(-5) is 5.  abs(5) is 5.  Basically,
                                x=(x<0? x*-1 : x).

     int        (MATH)          Truncate the given number to its integer
                                portion, discarding any fractional part.
                                (This does not round, 4.9 would become 4)
                                If rounding is desired, n,.5,+,INT can
                                be used.

AUTHOR

MAINTAINER

COPYRIGHT

LICENSE

All distributions of this software must contain this copyright notice and license.