eX version 0.4b User's Manual                         File eXMan15.txt
(C) Copyright 1995, 1996 William E. Wilgus III.   All rights reserved.


Operators

All operators are quasi-local to the plane and level in which they
appear.  They have equal precedence and eXpression evaluation is 
usually left to right, the exception being multiple operators
employing a single term or expression as their right-hand operand, as
illustrated by  

                         / + 5

The order of performance of such multiple operators is right to
left---i.e.,  in the above example, the addition is performed before
the division.  
 
All binary operations are performed using the appropriate current
accumulator(s) as the operation's left-hand operand(s) and the
value(s) provided to it as its right-hand term(s).  The result(s) of
the operation is (are) placed in the appropriate plane, level 
accumulator(s).  As numeric values are always returned as
double-precision floating point, data type cast operations are not
required to perform operations on what might otherwise appear to be
mixed numeric type operations.  
 
With the exception of the unary operator -, negation, and the logical 
operator not, operations may be restricted to perform only the data 
class operation indicated by an optional suffix.  The numeric suffix
is 

                         #

and the string suffix is 

                         $


`No Operation' Operator


nop
     `No operation' operator.  It prevents the operation preceding it
     from taking place with the eev(s) that are provided to the nop,
     in effect postponing the preceding operation until a subsequent
     value is provided.  It is otherwise inert. 



Arithmetic Operators
 
+    Addition
     If a numeric eev is available, performs numeric addition.  If a
     string eev is available performs string concatenation.  If both
     eev classes are available, does both operations.

+#   Numeric addition.
     If a numeric eev is available, performs numeric addition.  No
     other operation is performed.

+$   String concatenation.
     If a string eev is available, performs string concatenation.  If
     a numeric eev is available and a string eev is not, 
     concatenates the rounded to integer numeric eev modulo 256 
     character.  Does not perform both operations.

-    Subtraction.
     If a numeric eev is available, performs numeric subtraction.  If
     a string eev is available performs string from string 
     subtraction.  If both eev classes are available, does both
     operations.
 
     String from string subtraction is the removal of the last
     occurance of the right-hand operand from the left-hand operand,
     if any.

            "subtraction" - "ion"   yields   "subtract"
            "subtraction" - "ed"    yields   "subtraction"
            "subtraction" - "tr"    yields   "subaction"

-#   Numeric subtraction.
     If a numeric eev is available, performs numeric subtraction.  No
     other operation is performed.

-$   String subtraction.
     If a string eev is available performs string from string 
     subtraction.  If a numeric eev is available and a string eev is
     not, performs numeric from string subtraction.  Does not perform
     both operations.  
 
     Numeric from string subtraction is the removal of the last  
     right-hand operand number of characters from the left-hand
     operand string (or as many as exist).

          "subtraction" -$ 3      yields    "subtract"
          "subtraction" -$ 100    yields    ""

-    Negation (if no whitespace follows, or, if a dollar sign follows,
     the dollar sign is the data type specifier for a string  
     variable.)

     If a numeric eev is provided, performs numeric negation.  If a
     string eev is provided, performs string negation.  If both eev
     classes are provided, performs both operations.  
 
     String negation is a byte-wise 2's compliment.

*    Multiplication.
     If a numeric eev is available, performs numeric multiplication. 
     If a string eev is available, performs string by string 
     multiplication.  If both eev classes are available, does both
     operations.   
 
     String by string multiplication is the multiplication of each
     character in the left-hand operand by the right-hand operand.  
     By definition, if either operand is null, the result is the null
     string (""). 

               "ab" * "xy"    yields   "axybxy"

*#   Numeric multiplication.
     If a numeric eev is available, numeric multiplication occurs.  
     No other operation is performed.

*$   String multiplication.
     If a string eev is available, performs string by string 
     multiplication.  If a numeric eev is available and a string eev
     is not, performs string by numeric multiplication.  It does not
     perform both operations.  
 
     String by numeric multiplication is the right-hand operand
     replications of the left-hand operand.  The right-hand operand
     may be or include a fractional part.  By definition, both the
     multiplication of the null string ("") by any number, and the
     multiplication of any string by 0.0 yields the null string.  

          "Times" *$ 3     yields   "TimesTimesTimes"
          "Times" *$ 1.5   yields   "TimesTim"
          "Times" *$ 0.5   yields   "Tim"
          "" *$ 3          yields   ""
          "Times" *$ 0     yields   ""

/    Division
     If a numeric eev is available, performs numeric by numeric
     division.  If a string eev is available, performs string by
     string division.  If both eev classes are available, performs
     both operations.  
 
     String by string division is the removal of all occurances of the
     right-hand operand from the left-hand operand, if any.  By
     definition, division of the null string by any string yields the
     null string and division of any string by the null string ("") 
     yields the dividend.

               "axybxy" / "xy"   yields   "ab"
               "ab" / "xy"       yields   "ab"
               "ab" / ""         yields   "ab"
               "" / "xy"         yields   ""

/#   Numeric division
     If a numeric eev is available, performs numeric by numeric
     division.  No other operation is performed.

/$   String division
     If a string eev is available, string by string division.  If a
     numeric eev is available and a string eev is not, performs string
     by numeric division.  Does not perform both operations.
 
     String by numeric division divides the length of the dividend  
     (string) by the divisor (numeric), and retains only the rounded
     to integer quotient left characters of the dividend.  The divisor
     may, of course, either be or include a fractional part.  By
     definition, the division of any string by 0 yields that string 
     (dividend), and division with a divisor of less than unity (1.0)
     is equivalent to multiplication by the reciprocal of the divisor.

          "123456789" /$ 2.25   yields   "1234"
          "123456789" /$ 2      yields   "12345"
          "123456789" /$ 0      yields   "123456789"
          "123456789" /$ 0.5    yields   "123456789123456789"

\    Integer result division
     If a numeric eev is available, performs numeric by numeric
     integer result division.  If a string eev is available, performs
     string by string integer result division.  If both classes of eev
     are available, performs both operations.  
 
     String by string integer result division follows the simple rule
     that if a character in the dividend is followed by the character
     sequence that is the divisor, that character is retained and the
     divisor that follows it is discarded.  If a character in the
     dividend is not followed by the chracter sequence that represents
     the divisor, the character is discarded.  The operation is
     performed iteratively by character from left to right (but
     possibly should be performed right to left).

     By definition, if the divisor (right-hand operand) is the null
     string (""), the operation yields the dividend; if the dividend
     is the null string, the operation yields the null string.

               "100100" \ "0"     yields   "11"
               "1000100" \ "0"    yields   "101"
               "111" \ "0"        yields   ""
               "111" \ ""         yields   ""
               "" \ "0"           yields   ""

\#   Numeric integer result division
     If a numeric eev is available, performs numeric by numeric 
     integer result division.  No other operation is performed.

\$   String integer result division.
     If a string eev is available, performs string by string integer 
     result division.  If a numeric eev is available and a string eev
     is not, performs string by numeric integer result division.  Does
     not perform both operations.  
 
     String by numeric integer result division yields the left n  
     characters of the dividend, where n is the integer result
     division of the length of the string operand (dividend) by the  
     numeric operand (divisor).  By definition, a divisor of 0 yields
     the dividend string,  and a divisor of less than unity (< 1.0) is
     equivalent to the multiplication of the dividend string by the
     integer result division of the expansion of the reciprocal of the
     divisor.

          "123456789" \$ 2     yields   "1234"
          "123456789" \$ 0.5   yields   "123456789123456789"
          "123456789" \$ 0     yields   "123456789"

^    Exponentiation
     If a numeric eev is available, performs numeric by numeric 
     exponentiation.  If a string eev is available, performs string by
     string exponentiation.  If both eev classes are present, performs
     both operations.  
 
     String by string factoring is the multiplication of each 
     character in the left-hand operand by each character in the
     right-hand operand.  By definition, if either operand is the null
     string (""), the left-hand operand is the result. 

     "ab" ^ "xy"   yields   "axaybxby"
     "ab" ^ ""     yields   "ab"
     "" ^ "xy"     yields   ""

^#   Numeric exponentiation
     If a numeric eev is available, performs numeric by numeric 
     exponentiation.  No other operation is performed.

^$   String exponentiation
     If a string eev is available, performs string by string 
     exponentiation.  If a numeric eev is available and a string eev
     is not, performs string by numeric exponentiation.  Does not
     perform both operations.  
 
     String by numeric exponentiation yields a string containing the
     length of the string raised to the numeric power copies  of the
     string value.  By definition, if the left-hand operand is the
     null string (""), the result is the null string.

                    "a" ^$ 0   yields   "a"
                    "a" ^$ 1   yields   "aa"
                    "a" ^$ 2   yields   "aaaa"
                    "a" ^$ 3   yields   "aaaaaaaa"
                    "" ^$ 3    yields   ""

mod  Modulo
     If a numeric eev is available, performs numeric by numeric
     modulo.  If a string eev is available, performs string by string
     modulo.  Does not perform both operations.
 
     String by string modulo is the removal of all occurances of the
     divisor and the character that precedes it in the dividend from
     the dividend.  By definition, if the left-hand operand is the
     null string (""), the null string is the result; if the modulus
     is the null string, the left-hand operand is the result.

                    "axbxc" mod "x"   yields   "c"
                    "axbx" mod "x"    yields   ""
                    "axbx" mod ""     yields   "axbx"
                    "" mod "x"        yields   ""

mod#  Numeric modulo
     If a numeric eev is available, performs numeric by numeric
     modulo.  No other operation is performed.

mod$  String modulo.
     If a string eev is available, performs string by string modulo.  
     If a numeric eev is available and a string eev is not, performs
     string by numeric modulo.  Does not perform both operations.
 
     String by numeric modulo yields the right n characters of the
     dividend, where n is equivalent to 

                    len(dividend$) mod divisor#.

                    "12345678" mod$ 3   yields   "78"
                    "12345678" mod$ 4   yields   ""

  
Relational Operators
 
Relational operators set the numeric accumulator for the plane and
level that the operator appears in to true (-1) or false (0).  If both
a string and numeric test is performed by a single operator, both
relations must be true for the result to be true.  A string by numeric
relational operation is defined as the comparison of the length of the
left-hand operand (string) with the rounded to integer right-hand
operand.  

<    Less than
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  If a string eev is available, performs a string by
     string comparison.  If both eev classes are available, performs
     both comparisons.

<#   Numeric less than
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  No other operation is performed.

<$   String less than
     If a string eev is available, performs a string by string 
     comparison.  If a numeric eev is available and a string eev is
     not, performs a string by numeric comparison.  Does not perform
     both operations.  
 
<>   Not equal
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  If a string eev is available, performs a string by
     string comparison.  If both eev classes are available, performs
     both comparisons.

<>#  Numeric not equal
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  No other operation is performed.

<>$  String not equal
     If a string eev is available, performs a string by string 
     comparison.  If a numeric eev is available and a string eev is
     not, performs a string by numeric comparison.  Does not perform
     both comparisons.  

<=   Less than or equal
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  If a string eev is available, performs a string by
     string comparison.  If both eev classes are available, performs
     both comparisons.

<=#  Numeric less than or equal
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  No other operation is performed.

<=$  String less than or equal
     If a string eev is available, performs a string by string 
     comparison.  If a numeric eev is available and a string eev is
     not, performs a string by numeric comparison.  Does not perform
     both comparisons.  

=    Equality
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  If a string eev is available, performs a string by
     string comparison.  If both eev classes are available, performs
     both comparisons. 

=#   Numeric equality
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  No other operation is performed.

=$   String equality
     If a string eev is available, performs a string by string 
     comparison.  If a numeric eev is available and a string eev is
     not, performs a string by numeric comparison.  Does not perform
     both comparisons.

>    Greater than
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  If a string eev is available, performs a string by
     string comparison.  If both eev classes are available, performs
     both comparisons.

>#   Numeric greater than
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  No other operation is performed.

>$   String greater than
     If a string eev is available, performs a string by string 
     comparison.  If a numeric eev is available and a string eev is
     not, performs a string by numeric comparison.  Does not perform
     both of comparisons.  

>=   Greater than or equal
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  If a string eev is available, performs a string by
     string comparison.  If both eev classes are available, performs
     both comparisons.

>=#  Numeric greater than or equal
     If a numeric eev is available, performs a numeric by numeric 
     comparison.  No other operation is performed.

>=$  String greater than or equal
     If a string eev is available, performs a string by string 
     comparison.  If a numeric eev is available and a string eev is
     not, performs a string by numeric comparison.  Does not perform
     both comparisons.

 

Logical Operators
 
See also the hermaphrodite functions even and odd, which act like
logical operators within a test.


                  Bits  |   Bit Value Returned
              --------------------------------------
                        |       X   X   X   X   X
                        |  NOT AND OR  XOR EQV IMP
                X   Y   |   Y   Y   Y   Y   Y   Y
              --------------------------------------
                1   1   |   0   1   1   0   1   1
                1   0   |   1   0   1   1   0   0
                0   1   |   0   0   1   1   0   1
                0   0   |   1   0   0   0   1   1

                  Logical Operation Truth Table


                              Note
    In this implementation of eX, logical operator operands are
    temporarily converted to integers to perform the operation. 
    Therefore, operands must be in the range 

             -2,147,483,648 to +2,147,483,647



eX permits logical operations upon strings, and one of the uses of
binary logical operators is in conditional tests.  In order to extend
that use to logical string operations, the following inventiveness was
necessary.  
 
If a binary string logical operation, whether string by string or
string by numeric, is performed within and at the plane and level of a
conditional test structure, the numeric accumulator is set to reflect 
the results of that operation:  

  0 indicates that the result is a string whose bytes (or characters)
    are all ASCII code zero (0).
 -1 indicates that the result is a string whose bytes (or characters)
    were not all ASCII code zero (0), and if a numeric (by numeric)
    operation was also performed, its result was not zero (0).

If a logical operator is not within and at the plane and level of a 
conditional test structure, a string logical operation does not affect
the numeric accumulator. 

A string by string logical operation is the character-wise, bit-wise
logical operation of the left-hand operand with right-hand operand.  
(The unary operation not is performed in the same manner.)  With the
exception of the logical operators or and xor, the length of the
left-hand operand is un-altered.  However, if the length of the
right-hand operand is greater than the length of the left-hand operand
in a logical or or xor operation, the length of the left-hand operand
is increased to match that of the right-hand operand by padding the
left-hand operand with ASCII code 0's. 

A string by numeric logical operation is the character-wise, bit-wise
logical operation of the left-hand operand with the numeric value
produced by the right-hand operand, which must be in the range 
0--255.  The length of the left-hand operand remains un-altered with
all operations. 


&
and  and
     If a numeric eev is available, performs a numeric by numeric
     logical and.  If a string eev is available, performs a string by
     string logical and.  If both eev classes are available, performs
     both operations.

&#
and# Numeric and
     If a numeric eev is available, performs a numeric by numeric
     logical and.  No other operation is performed.

&$
and$ String and
     If a string eev is available, performs a string by string logical
     and.  If a numeric eev is available and a string eev is not, 
     performs a string by numeric logical and.  It does not perform
     both operations.

eqv  Equivalence
     If a numeric eev is available, performs a numeric by numeric
     logical equivalence.  If a string eev is available, performs a
     string by string logical equivalence (which does not alter the
     length of the left-hand operand).  If both eev classes are
     available, performs both operations.

eqv# Numeric equivalence
     If a numeric eev is available, performs a numeric by numeric
     logical equivalence.  No other operation is performed.

eqv$ String Equivalence
     If a string eev is available, performs a string by string logical
     equivalence.  If a numeric eev is available and a string eev is
     not, performs a string by numeric logical equivalence.  It does
     not both operations.

imp  Implication
     If a numeric eev is available, performs a numeric by numeric
     logical implication.  If a string eev is available, performs a
     string by string logical implication.  If both eev classes are
     available, performs both operations.

imp# Numeric implication
     If a numeric eev is available, performs a numeric by numeric
     logical implication.  No other operation is performed.

imp$ String Implication
     If a string eev is available, performs a string by string logical
     implication.  If a numeric eev is available and a string eev is
     not, performs a string by numeric logical implication.  It does
     not perform both operations.

not  not
     If a numeric eev is available, performs a numeric logical not.
     If a string eev is available, performs a string logical not.
     If both eev classes are available, performs both operations.

not# Numeric not
     If a numeric eev is available, performs a numeric logical not.
     No other operation is performed.

not$ String not
     If a string eev is available, performs a string logical not.  No
     other operation is performed.

or   or
     If a numeric eev is available, performs a numeric by numeric
     logical or.  If a string eev is available, performs a string by
     string logical or which, if the right-hand operator is longer
     than the left, necessarily will alter the length of the left-hand
     operand to match that of the right-hand operand.  If both eev
     classes are available, performs both operations.

or#  Numeric or
     If a numeric eev is available, performs a numeric by numeric
     logical or.  No other operation is performed.

or$  String or
     If a string eev is available, performs a string by string logical
     logical or.  If a numeric eev is available and a string eev is
     not, performs a string by numeric logical or.  It does not
     perform both operations.

xor  exclusive or
     If a numeric eev is available, performs a numeric by numeric
     logical xor.  If a string eev is available, performs a string by
     string logical xor which, if the right-hand operator is longer
     than the left, necessarily will alter the length of the left-hand
     operand to match that of the right-hand operand.  If both eev
     classes are available, performs both operations.

xor# Numeric exclusive or
     If a numeric eev is available, performs a numeric by numeric
     logical xor.  No other operation is performed.

xor$ String exclusive or
     If a string eev is available, performs a string by string logical
     xor.  If a numeric eev is available and a string eev is not, 
     performs a string by numeric logical xor.  It does not perform
     both operations.



Radix Operators
 
Radix operators transform their (right-hand) operand from the number
base specified by their radix designator to base 10 numbers. 
Whitespace may not exist between the radix operator (&) and its  
designator, but it may exist between the radix designator and its
value term: 

                     &b<< >>eev$

Literal values may be given as an un-delimited literal if no whitespace
exists between the radix designator and the literal, otherwise the literal
must be delimited.

                    &hFF
                    &h "ff"

Although shown below in lower case, the radix designator may be given 
in either alphabetic case.

&b   Binary radix
     The radix value must be a string literal or within a string
     variable.

&k   Kilo (1,024^10)
     The radix value provided to the operator must be a base 10 value.
     It accepts negative numbers and fractional parts.  Note that this
     may `disappear' or be changed in future versions of eX.

&o   Octal radix
     The radix value must be a string literal or within a string
     variable.

&h   Hexadecimal radix
     The radix value must be a string literal or within a string
     variable.  It is currently limited to &hFFFF.

