Package com.singularsys.jep.walkers

# Class SubstitutionVisitor

java.lang.Object
com.singularsys.jep.walkers.GenericDoNothingVisitor<Void>
com.singularsys.jep.walkers.SubstitutionVisitor

All Implemented Interfaces:
  `GenericVisitor<Node,Void,ParseException>`, `JepComponent`, `Serializable`

public class SubstitutionVisitor extends GenericDoNothingVisitor<Void>
Allows substitution of variable with values or expressions. For example

     Jep jep = new Jep();
     SubstitutionVisitor sv = new SubstitutionVisitor(jep);
     Node node = jep.parse("x^2+x");
     Node sub = jep.parse("sin(y)");
     Node res = sv.substitute(node,"x",sub);

Will give the expression "(sin(y))^2+sin(y)".

Various different types of substitution are available.

Substitute a variable by a value.
  `substitute(Node, String, Object)`
Substitute a variable by an expression
  `substitute(Node, String, Node)`
Substitute a set of variables by a set of values
  `substitute(Node, String[], Object[])`
Substitute a set of variables by a set of expressions
  `substitute(Node, String[], String[])`
Substitute using an expression of the form `x=z+3`
  `substitute(Node, Node)`
Substitute using a set of expressions of the form `x=z+3`
  `substitute(Node, Node[])`

The methods which do multiple substitutions at the same time do not apply substitutions to the expressions which have been substituted. Hence if we try to use two substitutions `x=y+2`, `y=z+3` the result of substituting into `x^2+y^2` will be `(y+2)^2+(z+3)^2` and not `(z+3+2)^2+(z+1)^2`. This prevents possible infinite recursion. To completely substitute a set of expressions a loop could be used.

     Node base = jep.parse("x^2+y^2");
     Node sub1 = jep.parse("x=y+2");
     Node sub2 = jep.parse("y=z+3");
     Node subs[] = new Node[] {sub1,sub2};
     for(Node sub:subs) {
        base = sv.substitute(base, sub);
     }

Note that the order of substitution matters.

Author:
  Rich Morris Created on 16-Nov-2003
See Also:
  - Serialized Form

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `protected Operator`
  `assign`
  `protected final DeepCopyVisitor`
  `dcv`

  ### Fields inherited from class com.singularsys.jep.walkers.GenericDoNothingVisitor

  `ft, nf, ot`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `SubstitutionVisitor()`
  Constructor to uses as a JepComponent.
  `SubstitutionVisitor(Jep j)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `init(Jep j)`
  Initialize the component.
  `Node`
  `substitute(Node orig, Node sub)`
  Substitutes into `orig` the equation given by sub
  `Node`
  `substitute(Node orig, Node[] subs)`
  Substitute a set of equations into the original.
  `Node`
  `substitute(Node orig, String[] names, Node[] replacements)`
  Substitutes all occurrences of a set of variables var with a set of replacements.
  `Node`
  `substitute(Node orig, String[] names, Object[] values)`
  Substitute all occurrences of variables with matching name with corresponding values.
  `Node`
  `substitute(Node orig, String[] oldNames, String[] newNames)`
  Renames a set of variables with a new set of names.
  `Node`
  `substitute(Node orig, String name, Node replacement)`
  Substitutes all occurrences of variable `var` with `replacement`.
  `Node`
  `substitute(Node orig, String name, Object value)`
  Substitute a single variable with a given value.
  `Node`
  `visit(ASTVarNode node, Void data)`
  Visit a variable node

  ### Methods inherited from class com.singularsys.jep.walkers.GenericDoNothingVisitor

  `childrenHaveChanged, copyChildrenIfNeeded, copyChildrenIfNeeded, getLightWeightInstance, makeException, visit, visit, visit`

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

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

  ### Methods inherited from interface com.singularsys.jep.GenericVisitor

  `makeException, visit, visitChildren`

- ## Field Details

  - ### assign

    protected Operator assign

  - ### dcv

    protected final DeepCopyVisitor dcv

- ## Constructor Details

  - ### SubstitutionVisitor

    public SubstitutionVisitor(Jep j)

  - ### SubstitutionVisitor

    public SubstitutionVisitor()
    Constructor to uses as a JepComponent. `init(Jep)` method must be called to set the jep instance.
    Since:
      3.4.0

- ## Method Details

  - ### init

    public void init(Jep j)
    Description copied from interface: `JepComponent`
    Initialize the component. This method is called whenever a component is added to Jep. Hence, it allows components to keep track of the other components they may rely on.
    Specified by:
      `init` in interface `JepComponent`
    Overrides:
      `init` in class `GenericDoNothingVisitor<Void>`
    Parameters:
      `j` - the current Jep instance

  - ### substitute

    public Node substitute(Node orig, String name, Node replacement) throws ParseException
    Substitutes all occurrences of variable `var` with `replacement`. Does not do a DeepCopy.
    Parameters:
      `orig` - the expression we wish to perform the substitution on
      `name` - the name of the variable
      `replacement` - the expression `var` is substituted for
    Returns:
      the tree with variable replace (does not do a DeepCopy)
    Throws:
      `ParseException`

  - ### substitute

    public Node substitute(Node orig, Node sub) throws ParseException
    Substitutes into `orig` the equation given by sub
    Parameters:
      `orig` - the equation to substitute into
      `sub` - and equation of the form `x=....`
    Returns:
      a copy of `orig` after substitution
    Throws:
      `ParseException` - if sub is of the wrong form

  - ### substitute

    public Node substitute(Node orig, Node[] subs) throws ParseException
    Substitute a set of equations into the original. For example

                Node base = jep.parse("x^2+y^2");
                Node sub1 = jep.parse("x=y+2");
                Node sub2 = jep.parse("y=z+3");
                Node res = sv.substitute(base, new Node[] {sub1,sub2});

    Node this method does not do two levels of substitution, so the result here is `(y+2)^2+(z+3)^2`.
    Parameters:
      `orig` - the expression to substitute into
      `subs` - a set of equations of the form `x=...`
    Returns:
      a copy of `orig` after substitution
    Throws:
      `ParseException`

  - ### substitute

    public Node substitute(Node orig, String[] names, Node[] replacements) throws ParseException
    Substitutes all occurrences of a set of variables var with a set of replacements. Does not do a DeepCopy. For example

        	Node base = jep.parse("x^2+y^2");
        	Node sub1 = jep.parse("y+2");
        	Node sub2 = jep.parse("z+3");
        	Node res = sv.substitute(base, new String[]{"x","y"},new Node[] {sub1,sub2});

    Node this method does not do two levels of substitution, so the result here is `(y+2)^2+(z+3)^2`.
    Parameters:
      `orig` - the expression we wish to perform the substitution on
      `names` - the names of the variable
      `replacements` - the expression var is substituted for
    Returns:
      the tree with variable replace (does not do a DeepCopy)
    Throws:
      `ParseException`

  - ### substitute

    public Node substitute(Node orig, String[] names, Object[] values) throws ParseException
    Substitute all occurrences of variables with matching name with corresponding values. For example

        substitute(node, new String[]{"x","y"}, new Double[]{3.0,2.0});

    Parameters:
      `orig` - the equation to substitute into
      `names` - set of variable names
      `values` - set of values
    Returns:
      node with the substitution performed
    Throws:
      `ParseException`

  - ### substitute

    public Node substitute(Node orig, String name, Object value) throws ParseException
    Substitute a single variable with a given value. For example `substitute(node, "x", 3.0);`
    Parameters:
      `orig` - equation to perform substitution on
      `name` - variable name
      `value` - value to use
    Returns:
      node with the substitution performed
    Throws:
      `ParseException`
    Since:
      3.4.0

  - ### substitute

    public Node substitute(Node orig, String[] oldNames, String[] newNames) throws ParseException
    Renames a set of variables with a new set of names.
    Parameters:
      `orig` - equation to perform substitution on
      `oldNames` - the old variable name
      `newNames` - the new variable names
    Returns:
      node with the substitution performed
    Throws:
      `ParseException`

  - ### visit

    public Node visit(ASTVarNode node, Void data) throws ParseException
    Description copied from interface: `GenericVisitor`
    Visit a variable node
    Specified by:
      `visit` in interface `GenericVisitor<Node,Void,ParseException>`
    Overrides:
      `visit` in class `GenericDoNothingVisitor<Void>`
    Parameters:
      `node` - current node
      `data` - context data
    Returns:
      the result of visiting the node
    Throws:
      `ParseException`