Package com.singularsys.jep

# Class Operator

java.lang.Object
com.singularsys.jep.Operator

All Implemented Interfaces:
  `Serializable`

Direct Known Subclasses:
  `OverloadedOperator`, `RangeOperator`, `TernaryOperator`, `TernaryOperator.RhsTernaryOperator`

public class Operator extends Object implements Serializable
An Operator with additional information about its commutativity etc.

Operators have a number of properties:

- A symbol or name of the operator "+".
- The number of arguments NO_ARGS 0, UNARY 1 (e.g. UMINUS -x), BINARY 2 (e.g. x+y), and NARY either 3 ( a>b ? a : b) or unspecified like a list [x,y,z,w].
- The binding of the operator, LEFT 1+2+3 -> (1+2)+3 or RIGHT 1=2=3 -> 1=(2=3).
- Whether the operator is ASSOCIATIVE or COMMUTATIVE.
- The precedence of the operators + has a higher precedence than *.
- For unary operators they can either be PREFIX like -x or SUFFIX like x%.
- Comparative operators can be REFLEXIVE, SYMMETRIC, TRANSITIVE or EQUIVALENCE which has all three properties.
- A reference to a PostfixtMathCommandI object which is used to evaluate an equation containing the operator.

Various is... and get... methods are provided to query the properties of the operator.

Author:
  Rich Morris Created on 19-Oct-2003
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `ASSOCIATIVE`
  Associative operators x*(y*z) == (x*y)*z .
  `static final int`
  `BINARY`
  Binary operators, such as x+y, x>y
  `static final int`
  `COMMUTATIVE`
  Commutative operators x*y = y*x.
  `static final int`
  `COMPOSITE`
  composite operators, like a-b which is a+(-b)
  `static final int`
  `EQUIVALENCE`
  Equivalence relations = reflexive, transitive and symmetric.
  `protected int`
  `flags`
  Flags for type of operator Access level changed to protected in version 3.5
  `protected int`
  `key`
  Key used to identify the operator in the operator table Access level changed to protected in version 3.5
  `static final int`
  `LEFT`
  Left binding like +: 1+2+3 -> (1+2)+3
  `protected final String`
  `name`
  A unique name defining the operator.
  `static final int`
  `NARY`
  Trinary ops such as ?
  `static final int`
  `NO_ARGS`
  No arguments to operator
  `static final int`
  `NOT_IN_PARSER`
  Non-standard operators, like array access.
  `protected PostfixMathCommandI`
  `pfmc`
  The PostfixMathCommandI for evaluating Access level changed to protected in version 3.5
  `protected int`
  `precedence`
  Precedence of operator, 0 is most tightly bound, so prec("*") < prec("+").
  `static final int`
  `PREFIX`
  prefix operators -x
  `protected String`
  `printSymbol`
  The symbol for the operator, used for printing.
  `static final int`
  `REFLEXIVE`
  Reflective relations x=x for all x.
  `static final int`
  `RIGHT`
  Right binding like =: 1=2=3 -> 1=(2=3)
  `static final int`
  `SELF_INVERSE`
  self inverse operators like -(-x) !
  `static final int`
  `SUFFIX`
  postfix operators x%
  `protected String`
  `symbol`
  The symbol for the operator, used for printing.
  `static final int`
  `SYMMETRIC`
  Symmetric relation x=y implies y=x.
  `static final int`
  `TERNARY`
  three argument operators like java's cond?
  `static final int`
  `TRANSITIVE`
  Transitive relations x=y and y=z implies x=z
  `static final int`
  `UNARY`
  Unary operators, such as -x !
  `static final int`
  `USE_BINDING_FOR_PRINT`
  For non-commutative operators printing can be determined by the left or right binding.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `Operator(String name, PostfixMathCommandI pfmc, int flags)`
  Construct a new operator with no precedence set.
  `Operator(String name, PostfixMathCommandI pfmc, int flags, int precedence)`
  Constructs a new operator with a given precedence.
  `Operator(String name, String symbol, PostfixMathCommandI pfmc, int flags)`
  Constructs a new operator, with a different name and symbol
  `Operator(String name, String symbol, PostfixMathCommandI pfmc, int flags, int precedence)`
  Constructs a new operator, with a different name and symbol and allows a given precedence to be set.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `addAltSymbol(String altSymbol)`
  Adds an alternate symbol which can be used at parse time.
  `Operator`
  `duplicate()`
  Return a copy of the operator with all fields identical.
  `List<String>`
  `getAltSymbols()`
  List of alternative symbols which can represent the same operator
  `Operator`
  `getBinaryInverseOp()`
  The composite or binaryInverse operator (e.g. subtract) associated with a root or unary inverse operator
  `final int`
  `getBinding()`
  Deprecated.
  Use `isLeftBinding()` and `isRightBinding()`.
  `final int`
  `getFlags()`
  The flags for this operator.
  `Operator`
  `getInverseOp()`
  The unary inverse operator associated with a root or composite operator.
  `int`
  `getKey()`
  Deprecated.
  Not used with new operator table
  `final String`
  `getName()`
  returns a unique name defining this operator.
  `final PostfixMathCommandI`
  `getPFMC()`
  Returns the PostfixMathCommandI used by this operator.
  `final int`
  `getPrecedence()`
  Get the precedence of the operator.
  `String`
  `getPrintSymbol()`
  The symbol used for printing.
  `Operator`
  `getRootOp()`
  The basic group operator associated with the inverse or composite operator.
  `final String`
  `getSymbol()`
  returns the symbol used by this operator.
  `final boolean`
  `isAssociative()`
  Is the operator associative?
  `final boolean`
  `isBinary()`
  Is the operator a binary operator, like `x+y`?
  `final boolean`
  `isCommutative()`
  Is the operator commutative, like `x+y = y+x`.
  `final boolean`
  `isComposite()`
  Is the operator composite operator like `a-b` which can be treated as `a+(-b)`.
  `boolean`
  `isDistributiveOver(Operator op)`
  Returns whether this operator is distributive over another operator.
  `final boolean`
  `isEquivalence()`
  Is the operator an equivalence relation, i.e. it is reflexive, symmetric and transitive.
  `final boolean`
  `isLeftBinding()`
  Is the operator left binding?
  `final boolean`
  `isNary()`
  Is the operator a n-ary operator?
  `final boolean`
  `isPrefix()`
  Is the operator a prefix operator like -x?
  `final boolean`
  `isReflexive()`
  Is the operator reflexive, like `a==a`?
  `final boolean`
  `isRightBinding()`
  Is the operator right binding?
  `final boolean`
  `isSelfInverse()`
  Is the operator self inverse like `-(-x)` or `!(!x)`?
  `final boolean`
  `isSuffix()`
  Is the operator a suffix operator like x%?
  `final boolean`
  `isSymmetric()`
  Is the operator symmetric, like `a!=b` implies `b!=a`?
  `final boolean`
  `isTernary()`
  Is the operator a ternary operator like a>b ?
  `final boolean`
  `isTransitive()`
  Is the operator transitive, like `a>b` and `b>c` implies `a>c`?
  `final boolean`
  `isUnary()`
  Is the operator a unary operator, like `-x`?
  `final boolean`
  `notInParser()`
  Non-standard operators, that require special parsing options.
  `final int`
  `numArgs()`
  Returns the number of arguments the operator takes.
  `void`
  `setBinaryInverseOp(Operator inv)`
  In a mathematical group with operator + and inverse uminus (-y) the binary inverse operator is the composition x + (-y) in other words subtraction -.
  `final void`
  `setDistributiveOver(Operator op)`
  Sets whether this operators this is distributive over another operator.
  `void`
  `setFlag(int flag, boolean val)`
  Set the value of a specific flag.
  `void`
  `setInverseOp(Operator inv)`
  For composite operators like a-b which can be considered as a+(-b) there is a root operator (+) and an inverse operator (UMinus).
  `void`
  `setKey(int key)`
  Deprecated.
  Not used with new operator table
  `final void`
  `setPFMC(PostfixMathCommandI pfmc)`
  Sets the PostfixMathCommandI used by this operator.
  `void`
  `setPrecedence(int i)`
  Set the precedence of the operator.
  `void`
  `setPrintSymbol(String printSymbol)`
  The symbol used for printing.
  `void`
  `setRootOp(Operator root)`
  For composite operators like a-b which can be considered as a+(-b) there is a root operator (+) and an inverse operator (UMinus).
  `final void`
  `setSymbol(String sym)`
  Sets the symbol used by the operator.
  `String`
  `toFullString()`
  returns a verbose representation of the operator and all its properties.
  `String`
  `toString()`
  `final boolean`
  `useBindingForPrint()`
  For non-commutative operators printing can be determined by the left or right binding.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### NO_ARGS

    public static final int NO_ARGS
    No arguments to operator
    See Also:
      - Constant Field Values

  - ### UNARY

    public static final int UNARY
    Unary operators, such as -x !x ~x
    See Also:
      - Constant Field Values

  - ### BINARY

    public static final int BINARY
    Binary operators, such as x+y, x>y
    See Also:
      - Constant Field Values

  - ### NARY

    public static final int NARY
    Trinary ops such as ?: and or higher like [x,y,z,w]
    See Also:
      - Constant Field Values

  - ### LEFT

    public static final int LEFT
    Left binding like +: 1+2+3 -> (1+2)+3
    See Also:
      - Constant Field Values

  - ### RIGHT

    public static final int RIGHT
    Right binding like =: 1=2=3 -> 1=(2=3)
    See Also:
      - Constant Field Values

  - ### ASSOCIATIVE

    public static final int ASSOCIATIVE
    Associative operators x*(y*z) == (x*y)*z .
    See Also:
      - Constant Field Values

  - ### COMMUTATIVE

    public static final int COMMUTATIVE
    Commutative operators x*y = y*x.
    See Also:
      - Constant Field Values

  - ### REFLEXIVE

    public static final int REFLEXIVE
    Reflective relations x=x for all x.
    See Also:
      - Constant Field Values

  - ### SYMMETRIC

    public static final int SYMMETRIC
    Symmetric relation x=y implies y=x.
    See Also:
      - Constant Field Values

  - ### TRANSITIVE

    public static final int TRANSITIVE
    Transitive relations x=y and y=z implies x=z
    See Also:
      - Constant Field Values

  - ### EQUIVALENCE

    public static final int EQUIVALENCE
    Equivalence relations = reflexive, transitive and symmetric.
    See Also:
      - Constant Field Values

  - ### PREFIX

    public static final int PREFIX
    prefix operators -x
    See Also:
      - Constant Field Values

  - ### SUFFIX

    public static final int SUFFIX
    postfix operators x%
    See Also:
      - Constant Field Values

  - ### SELF_INVERSE

    public static final int SELF_INVERSE
    self inverse operators like -(-x) !(!x)
    See Also:
      - Constant Field Values

  - ### COMPOSITE

    public static final int COMPOSITE
    composite operators, like a-b which is a+(-b)
    See Also:
      - Constant Field Values

  - ### USE_BINDING_FOR_PRINT

    public static final int USE_BINDING_FOR_PRINT
    For non-commutative operators printing can be determined by the left or right binding. For example (a-b)-c is printed as a-b-c (flag set). But a/b/c could be ambiguous so (a/b)/c is printed with brackets (flag not set).
    See Also:
      - Constant Field Values

  - ### NOT_IN_PARSER

    public static final int NOT_IN_PARSER
    Non-standard operators, like array access. These will typically require the PrintRulesI interface to print and require special parsing options.
    See Also:
      - Constant Field Values

  - ### TERNARY

    public static final int TERNARY
    three argument operators like java's cond?tval:fval
    See Also:
      - `TernaryOperator`
      - Constant Field Values

  - ### name

    protected final String name
    A unique name defining the operator. Access level changed to protected in version 3.5

  - ### symbol

    protected String symbol
    The symbol for the operator, used for printing. Access level changed to protected in version 3.5

  - ### printSymbol

    protected String printSymbol
    The symbol for the operator, used for printing. Access level changed to protected in version 3.5

  - ### pfmc

    protected PostfixMathCommandI pfmc
    The PostfixMathCommandI for evaluating Access level changed to protected in version 3.5

  - ### flags

    protected int flags
    Flags for type of operator Access level changed to protected in version 3.5

  - ### precedence

    protected int precedence
    Precedence of operator, 0 is most tightly bound, so prec("*") < prec("+"). Access level changed to protected in version 3.5

  - ### key

    protected int key
    Key used to identify the operator in the operator table Access level changed to protected in version 3.5

- ## Constructor Details

  - ### Operator

    public Operator(String name, PostfixMathCommandI pfmc, int flags)
    Construct a new operator with no precedence set.
    Parameters:
      `name` - printable name of the operator
      `pfmc` - postfix math command for the operator
      `flags` - set of flags defining the properties of the operator.
    Throws:
      `JepRuntimeException` - if the function is both a CallbackEvaluationI and a Unary/Binary/Nary/Nullary function

  - ### Operator

    public Operator(String name, PostfixMathCommandI pfmc, int flags, int precedence)
    Constructs a new operator with a given precedence.
    Parameters:
      `name` - printable name of the operator
      `pfmc` - postfix math command for the operator
      `flags` - set of flags defining the properties of the operator
      `precedence` - operator precedence to be set
    Throws:
      `JepRuntimeException` - if the function is both a CallbackEvaluationI and a Unary/Binary/Nary/Nullary function

  - ### Operator

    public Operator(String name, String symbol, PostfixMathCommandI pfmc, int flags)
    Constructs a new operator, with a different name and symbol
    Parameters:
      `name` - name of operator, must be unique, used when describing operator
      `symbol` - printable name of operator, used for printing equations
      `pfmc` - postfix math command for operator
      `flags` - set of flags defining the properties of the operator
    Throws:
      `JepRuntimeException` - if the function is both a CallbackEvaluationI and a Unary/Binary/Nary/Nullary function

  - ### Operator

    public Operator(String name, String symbol, PostfixMathCommandI pfmc, int flags, int precedence)
    Constructs a new operator, with a different name and symbol and allows a given precedence to be set.
    Parameters:
      `name` - name of operator, must be unique, used when describing operator
      `symbol` - printable name of operator, used for printing equations
      `pfmc` - postfix math command for operator
      `flags` - set of flags defining the properties of the operator.
      `precedence` - operator precedence to be set
    Throws:
      `JepRuntimeException` - if the function is both a CallbackEvaluationI and a Unary/Binary/Nary/Nullary function

- ## Method Details

  - ### getSymbol

    public final String getSymbol()
    returns the symbol used by this operator.
    Returns:
      The symbol

  - ### setSymbol

    public final void setSymbol(String sym)
    Sets the symbol used by the operator. Note `Jep.reinitializeComponents()` must be called after using this method.
    Parameters:
      `sym` - the new symbol to use.

  - ### getName

    public final String getName()
    returns a unique name defining this operator.
    Returns:
      the name

  - ### getPrintSymbol

    public String getPrintSymbol()
    The symbol used for printing. If null the symbol is used instead.
    Returns:
      the symbol used for printing or null if no special symbol is used

  - ### setPrintSymbol

    public void setPrintSymbol(String printSymbol)
    The symbol used for printing. If null the symbol is used instead.

  - ### getPFMC

    public final PostfixMathCommandI getPFMC()
    Returns the PostfixMathCommandI used by this operator.
    Returns:
      the PostfixMathCommandI

  - ### setPFMC

    public final void setPFMC(PostfixMathCommandI pfmc)
    Sets the PostfixMathCommandI used by this operator.
    Parameters:
      `pfmc` - the PostfixMathCommandI to use

  - ### getPrecedence

    public final int getPrecedence()
    Get the precedence of the operator. Lower values correspond to tighter binding, that is * gives a lower value than + and 1+2*3 is 1+(2*3).
    Returns:
      the precedence

  - ### setPrecedence

    public void setPrecedence(int i)
    Set the precedence of the operator. Lower values correspond to tighter binding, that is * gives a lower value than + and 1+2*3 is 1+(2*3).
    Parameters:
      `i` - the precedence

  - ### setDistributiveOver

    public final void setDistributiveOver(Operator op)
    Sets whether this operators this is distributive over another operator.
    Parameters:
      `op` - the other operator to check

  - ### isDistributiveOver

    public boolean isDistributiveOver(Operator op)
    Returns whether this operator is distributive over another operator.
    Parameters:
      `op` - the operator to check
    Returns:
      true if this operator is distributive over the given operator

  - ### setRootOp

    public void setRootOp(Operator root)
    For composite operators like a-b which can be considered as a+(-b) there is a root operator (+) and an inverse operator (UMinus). Typically, this is set for both the inverse and the composite
    Parameters:
      `root` - the root operator

  - ### setInverseOp

    public void setInverseOp(Operator inv)
    For composite operators like a-b which can be considered as a+(-b) there is a root operator (+) and an inverse operator (UMinus). Typically, set for the root and the composite operators.
    Parameters:
      `inv` - the unary inverse operator

  - ### setBinaryInverseOp

    public void setBinaryInverseOp(Operator inv)
    In a mathematical group with operator + and inverse uminus (-y) the binary inverse operator is the composition x + (-y) in other words subtraction -. Typically, set for the root and the inverse.
    Parameters:
      `inv` -

  - ### getRootOp

    public Operator getRootOp()
    The basic group operator associated with the inverse or composite operator.
    Returns:
      the root operator or null if this is the root operator or if none defined.

  - ### getInverseOp

    public Operator getInverseOp()
    The unary inverse operator associated with a root or composite operator.
    Returns:
      the inverse operator or null if this is the inverse operator or if none defined.

  - ### getBinaryInverseOp

    public Operator getBinaryInverseOp()
    The composite or binaryInverse operator (e.g. subtract) associated with a root or unary inverse operator
    Returns:
      the inverse operator or null if this is the inverse operator or if none defined.

  - ### getFlags

    public final int getFlags()
    The flags for this operator.
    Returns:
      the flags as a set of bits

  - ### getBinding

    @Deprecated public final int getBinding()
    Deprecated.
    Use `isLeftBinding()` and `isRightBinding()`.
    When parsing how is x+y+z interpreted. Can be `Operator.LEFT`: `x+y+z -> (x+y)+z` or `Operator.RIGHT`: `x=y=z -> x=(y=z)`.
    Returns:
      `Operator.LEFT` or `Operator.RIGHT`

  - ### isLeftBinding

    public final boolean isLeftBinding()
    Is the operator left binding? So `x+y+z -> (x+y)+z`.

  - ### isRightBinding

    public final boolean isRightBinding()
    Is the operator right binding? So `x=y=z -> x=(y=z)`.

  - ### isAssociative

    public final boolean isAssociative()
    Is the operator associative? So `x+(y+z) = (x+y)+z`.

  - ### isCommutative

    public final boolean isCommutative()
    Is the operator commutative, like `x+y = y+x`.

  - ### isBinary

    public final boolean isBinary()
    Is the operator a binary operator, like `x+y`?

  - ### isUnary

    public final boolean isUnary()
    Is the operator a unary operator, like `-x`?

  - ### isNary

    public final boolean isNary()
    Is the operator a n-ary operator? EG ternary operators like `a>b ? a : b` or has a variable number of arguments like a list `[a,b,c,d]`.

  - ### numArgs

    public final int numArgs()
    Returns the number of arguments the operator takes.
    Returns:
      0 for no arguments, 1 for unary, 2 for binary, 3 for ternary and n-ary operators.

  - ### isTransitive

    public final boolean isTransitive()
    Is the operator transitive, like `a>b` and `b>c` implies `a>c`?

  - ### isSymmetric

    public final boolean isSymmetric()
    Is the operator symmetric, like `a!=b` implies `b!=a`?

  - ### isReflexive

    public final boolean isReflexive()
    Is the operator reflexive, like `a==a`?

  - ### isEquivalence

    public final boolean isEquivalence()
    Is the operator an equivalence relation, i.e. it is reflexive, symmetric and transitive. For example the equality operator == is an equivalence relation.
    Returns:

  - ### isPrefix

    public final boolean isPrefix()
    Is the operator a prefix operator like -x?

  - ### isSuffix

    public final boolean isSuffix()
    Is the operator a suffix operator like x%?

  - ### isTernary

    public final boolean isTernary()
    Is the operator a ternary operator like a>b ? a : b?

  - ### isComposite

    public final boolean isComposite()
    Is the operator composite operator like `a-b` which can be treated as `a+(-b)`.

  - ### isSelfInverse

    public final boolean isSelfInverse()
    Is the operator self inverse like `-(-x)` or `!(!x)`?

  - ### useBindingForPrint

    public final boolean useBindingForPrint()
    For non-commutative operators printing can be determined by the left or right binding.
    Returns:

  - ### notInParser

    public final boolean notInParser()
    Non-standard operators, that require special parsing options. For example array access and array creation operators and the reciprocal operator.
    Returns:

  - ### setFlag

    public void setFlag(int flag, boolean val)
    Set the value of a specific flag. Use with care as can change the behaviour of the parser.
    Parameters:
      `flag` - flag to set
      `val` - value for that flag

  - ### toFullString

    public String toFullString()
    returns a verbose representation of the operator and all its properties. Symbols used to represent operator are enclosed in quotes.
    Returns:
      verbose string representation

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### getKey

    @Deprecated public int getKey()
    Deprecated.
    Not used with new operator table
    Get the key code used to identify the operator in the old `OperatorTable`.
    Returns:
      the key

  - ### setKey

    @Deprecated public void setKey(int key)
    Deprecated.
    Not used with new operator table
    Key code used to identify the operator in the old `OperatorTable`.
    Parameters:
      `key` - the key

  - ### getAltSymbols

    public List<String> getAltSymbols()
    List of alternative symbols which can represent the same operator
    Returns:
      either a list of strings or null if there are no such symbols

  - ### addAltSymbol

    public boolean addAltSymbol(String altSymbol)

    Adds an alternate symbol which can be used at parse time. The alternate symbol added will be recognised at parse time by configurable parser the normal symbol will be used in output.

    For example unicode U+002D the hyphen minus (-), U+2212 the unicode minus symbol (−), U+2013 then en-dash (–) may appear in some input to represent minus. Other possible alternative characters include U+2264 less-than or equals (≤), U+2264 greater-than or equals (≥), U+00D7 multiplication sign (×), U+00F7 division sign (÷), U+2044 fraction slash (⁄) and U+2215 division slash.

    Parameters:
      `altSymbol` - the symbol to add
    Returns:
      true if successfully added

  - ### duplicate

    public Operator duplicate()
    Return a copy of the operator with all fields identical.
    Returns:
      a copy of the operator
    Since:
      4.0