[]
DEMOS DOCS API PRICING
FREE TRIAL
(Showing Draft Content)

FormulaSyntaxTree

Class FormulaSyntaxTree

java.lang.Object
com.grapecity.documents.excel.expressions.FormulaSyntaxTree
All Implemented Interfaces:
Cloneable
public class FormulaSyntaxTree extends Object implements Cloneable
Represents a formula as a syntax tree.

This class is the entry point for the formula expression API. A FormulaSyntaxTree can be created as an empty tree and then populated by assigning a root SyntaxNode, or it can be created from formula text by using Parse(String). After the tree is built, you can inspect its structure with getRoot() or convert it back to formula text with toString().


 String formula = "LET(AppUpTime,NOW()-DATE(2020,4,17)+366, YEAR(AppUpTime)-1900-1 & \" years\")";
 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse(formula);
 FunctionNode find = new FunctionNode("NOW");
 FunctionNode replacement = new FunctionNode("DATE");
 replacement.getChildren().add(new NumberNode(2021));
 replacement.getChildren().add(new NumberNode(2));
 replacement.getChildren().add(new NumberNode(14));

 java.util.Stack<SyntaxNode> nodes = new java.util.Stack<SyntaxNode>();
 nodes.push(syntaxTree.getRoot());
 while (!nodes.isEmpty()) {
     java.util.List<SyntaxNode> children = nodes.pop().getChildren();
     for (int i = 0; i < children.size(); i++) {
         SyntaxNode child = children.get(i);
         if (child.equals(find)) {
             children.set(i, replacement);
         } else {
             nodes.push(child);
         }
     }
 }
 String formulaText = syntaxTree.toString();

  • Constructor Details

    • FormulaSyntaxTree

      public FormulaSyntaxTree()

  • Method Details

    • getRoot

      public final SyntaxNode getRoot()
      Gets the root element of the syntax tree for this formula. 
      
 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse("SUM(A1:A3)+B1");
 SyntaxNode root = syntaxTree.getRoot();
 String formulaText = root.toString();
      Returns:
      The root SyntaxNode of the formula syntax tree.

    • setRoot

      public final void setRoot(SyntaxNode value)
      Sets the root node of the formula syntax tree.

      Use this method to replace the current formula expression with a different SyntaxNode. Passing null clears the current root node.

      
 String formula = "SUM(A1:A3)+B1";
 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse(formula);
 SyntaxNode root = SyntaxNode.Parse("A1*A2");
 syntaxTree.setRoot(root);
      Parameters:
      value - The root SyntaxNode to assign to the syntax tree, or null to clear the current root node.

    • Parse

      public static FormulaSyntaxTree Parse(String text)
      Creates a new FormulaSyntaxTree from a formula string.

      The specified text should contain only the formula expression. It should not start with = and should not be surrounded with {= }}. If text is null or empty, this method returns an empty FormulaSyntaxTree.

      Use Parse(String,ParseContext) when the formula needs parsing options such as base row, base column, or R1C1 reference style.

      
 String formula = "SUM(A1:A3)+B1";
 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse(formula);
 SyntaxNode root = syntaxTree.getRoot();
      Parameters:
      text - The formula text to parse. This value can be null or empty.
      Returns:
      A FormulaSyntaxTree populated from the specified formula text, or an empty FormulaSyntaxTree if text is null or empty.

    • Parse

      public static FormulaSyntaxTree Parse(String text, ParseContext context)
      Parses formula text into a FormulaSyntaxTree by using the specified ParseContext.

      Use the parse context to control how references in the formula text are interpreted, including the zero-based base row, zero-based base column, and whether the formula uses R1C1 reference style.

      If text is null or empty, this method returns an empty FormulaSyntaxTree whose root node is null.

      
 ParseContext context = new ParseContext();
 context.setBaseRow(1);
 context.setBaseColumn(4);
 context.setIsR1C1(true);

 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse("R1C:R3C[1]", context);
 SyntaxNode root = syntaxTree.getRoot();
      Parameters:
      text - The formula text to parse. If text is null or empty, an empty FormulaSyntaxTree is returned.
      context - The parse context that specifies the base row, base column, and reference style used to interpret the formula text.
      Returns:
      A FormulaSyntaxTree created from the specified formula text. Returns an empty FormulaSyntaxTree if text is null or empty.

    • toString

      public String toString()
      Returns the formula text represented by this syntax tree.

      This method returns the same result as calling toString(UnParseContext) with the default unparse context. If this syntax tree has no root node, an empty string is returned.

      
 String formula = "SUM(A1:A3)+B1";
 FormulaSyntaxTree syntaxTree = FormulaSyntaxTree.Parse(formula);
 String formulaText = syntaxTree.toString();
      Overrides:
      toString in class Object
      Returns:
      A String containing the formula text, or an empty string if this syntax tree has no root node.

    • toString

      public final String toString(UnParseContext context)
      Returns the formula text represented by this syntax tree, optionally using the specified unparse context.

      Use UnParseContext to control how references are converted when the formula text is generated, such as the base row, base column, and reference style.

      
 ParseContext parseContext = new ParseContext();
 parseContext.setIsR1C1(true);
 FormulaSyntaxTree tree = FormulaSyntaxTree.Parse("R1C:R2C[1]", parseContext);
 UnParseContext unparseContext = new UnParseContext();
 unparseContext.setBaseRow(0);
 unparseContext.setBaseColumn(2);
 String formulaText = tree.toString(unparseContext);
      Parameters:
      context - The context that specifies how the syntax tree is converted to formula text, or null to omit conversion options.
      Returns:
      The formula text generated from this syntax tree. Returns an empty string if this syntax tree has no root node.

    • clone

      public final FormulaSyntaxTree clone()
      Creates a copy of the FormulaSyntaxTree instance.
      Overrides:
      clone in class Object
      Returns:
      A copy of the FormulaSyntaxTree instance.

    • equals

      public boolean equals(Object obj)
      Indicates whether this formula syntax tree is equal to the specified object.

      Two FormulaSyntaxTree instances are considered equal when the specified object is also a FormulaSyntaxTree and their root syntax nodes are equal. This method returns false if obj is null or is not a FormulaSyntaxTree.

      Overrides:
      equals in class Object
      Parameters:
      obj - The object to compare with this formula syntax tree. May be null.
      Returns:
      true if obj is a FormulaSyntaxTree with an equal root syntax node; otherwise, false.

    • hashCode

      public int hashCode()
      Returns the hash code for this FormulaSyntaxTree instance.

      This method is not intended to provide a content-based hash code for the syntax tree. Because the tree is mutable, the returned value is based on the runtime type rather than the current formula structure.

      Overrides:
      hashCode in class Object
      Returns:
      The hash code of the current FormulaSyntaxTree type.