package org.matheclipse.core.interfaces;
import java.util.Iterator;
import java.util.List;
import org.matheclipse.core.eval.exception.WrongArgumentType;
import org.matheclipse.core.expression.ASTRange;
import org.matheclipse.core.generic.interfaces.BiFunction;
import org.matheclipse.core.reflection.system.Apart;
import com.google.common.base.Function;
import com.google.common.base.Predicate;
//import org.matheclipse.generic.INestedList;
/**
*
*
* (I)nterface for the (A)bstract (S)yntax (T)ree of a given function.
*
*
*
* In MathEclipse, an abstract syntax tree (AST), is a tree representation of the abstract syntactic structure of the MathEclipse
* source code. Each node of the tree denotes a construct occurring in the source code. The syntax is 'abstract' in the sense that
* it does not represent every detail that appears in the real syntax. For instance, grouping parentheses are implicit in the tree
* structure, and a syntactic construct such as a Sin[x] expression will be denoted by an AST with 2 nodes. One node
* for the header Sin and one node for the argument x.
*
*
* Internally an AST is represented as a java.util.List which contains
*
* - the operator of a function (i.e. the "header"-symbol: Sin, Cos, Inverse, Plus, Times,...) at index
0
* and
* - the
n arguments of a function in the index 1 to n
*
*
* See Abstract syntax tree.
*/
public interface IAST extends IExpr, List, Cloneable {
/**
* NO_FLAG ACTIVATED
*/
public final int NO_FLAG = 0x0000;
/**
* The head or one of the arguments of the list or sublists contains a pattern object
*/
public final int CONTAINS_PATTERN = 0x0001;
/**
* The head or one of the arguments of the list or sublists contains a pattern object
*/
public final int CONTAINS_PATTERN_SEQUENCE = 0x0002;
/**
* One of the arguments of the list contains a pattern object which can be set to a default value.
*/
public final int CONTAINS_DEFAULT_PATTERN = 0x0004;
/**
* One of the arguments of the list or sublists contains a pattern object. Combination of
* CONTAINS_PATTERN, CONTAINS_PATTERN_SEQUENCE, CONTAINS_DEFAULT_PATTERN
*/
public final int CONTAINS_PATTERN_EXPR = 0x0007;
/**
* Negative flag mask for CONTAINS_DEFAULT_PATTERN
*/
public final int CONTAINS_NO_DEFAULT_PATTERN_MASK = 0xFFFB;
/**
* This expression represents a matrix
*/
public final int IS_MATRIX = 0x0020;
/**
* This expression represents a vector
*/
public final int IS_VECTOR = 0x0040;
/**
* This expression represents a matrix or vector if one of the following bits is set.
*/
public final int IS_MATRIX_OR_VECTOR = 0x0060;
/**
* This expression represents an already decomposed partial fraction
*
* @see Apart
*/
public final int IS_DECOMPOSED_PARTIAL_FRACTION = 0x0080;
/**
* This expression is an already flattened expression
*/
public final int IS_FLATTENED = 0x0100;
/**
* This expression is an already sorted expression
*/
public final int IS_SORTED = 0x0200;
/**
* This expression has already applied the Listable attribute to its argument expressions
*/
public final int IS_LISTABLE_THREADED = 0x0400;
/**
* This expression is an already flattened or sorted expression
*/
public final int IS_FLATTENED_OR_SORTED_MASK = 0x0300;
/**
* Get the evaluation flags for this list.
*
* @return
*/
public int getEvalFlags();
/**
* Returns the header. If the header itself is an ISymbol it will return the symbol object. If the header itself is an IAST it
* will recursively call headSymbol(). If the head is of type INumbers, the head will return one of these headers:
* "DoubleComplex", "Double", "Integer", "Fraction", "Complex". All other objects return null.
*/
public ISymbol topHead();
/**
* Are the given evaluation flags disabled for this list ?
*
* @return
*/
public boolean isEvalFlagOff(int i);
/**
* Are the given evaluation flags enabled for this list ?
*
* @return
*/
public boolean isEvalFlagOn(int i);
/**
* Set the evaluation flags for this list.
*
* @param i
*/
public void setEvalFlags(int i);
/**
* Add an evaluation flag to the existing ones.
*
* @param i
*/
public void addEvalFlags(int i);
/**
* Add an subAST with attribute OneIdentity for example Plus[] or Times[].
*
* @param subAST
* an ast with attribute OneIdentity.
* @return this ast after adding the subAST
*/
public IAST addOneIdentity(IAST subAST);
/**
* Get the argument at index 1, if the size() == 2 or the complete ast if the size() > 2 (useful for
* ASTs with attribute OneIdentity for example for Plus[] you can call
* getOneIdentity(F.C0) or for Times[]) you can call getOneIdentity(F.C1).
*
* @param defaultValue
* default value, if size() < 2.
* @return
*/
public IExpr getOneIdentity(IExpr defaultValue);
/**
* Appends all elements from offset startPosition to endPosition in the specified AST to the end of
* this AST.
*
* @param ast
* AST containing elements to be added to this AST
* @param startPosition
* the start position, inclusive.
* @param endPosition
* the ending position, exclusive.
* @return true if this AST changed as a result of the call
* @see #add(Object)
*/
public boolean addAll(List ast, int startPosition, int endPosition);
/**
* Appends all of the arguments (starting from offset 1) in the specified AST to the end of this AST.
*
* @param ast
* AST containing elements to be added to this AST
* @return true if this AST changed as a result of the call
* @see #add(Object)
*/
public boolean addAll(List ast);
/**
* Is this a list (i.e. with header == List)
*
* @return
*/
public boolean isList();
/**
* {@inheritDoc}
*/
public boolean isPlus();
/**
* {@inheritDoc}
*/
public boolean isPower();
/**
* {@inheritDoc}
*/
public boolean isTimes();
/**
* Returns an iterator over the elements in this list starting with offset 1.
*
* @return an iterator over this list values.
*/
public Iterator iterator();
/**
* Returns an iterator over the elements in this list starting with offset 0.
*
*
* @return an iterator over this list values.
*/
public Iterator iterator0();
/**
* Get the first argument (i.e. the second element of the underlying list structure) of the AST function (i.e.
* get(1) ).
*
* @return the first argument of the function represented by this AST.
* @see IExpr#head()
*/
public IExpr arg1();
/**
* Get the second argument (i.e. the third element of the underlying list structure) of the AST function (i.e.
* get(2) ).
*
* @return the second argument of the function represented by this AST.
* @see IExpr#head()
*/
public IExpr arg2();
/**
* Get the third argument (i.e. the fourth element of the underlying list structure) of the AST function (i.e.
* get(3) ).
*
* @return the third argument of the function represented by this AST.
* @see IExpr#head()
*/
public IExpr arg3();
/**
* Get the last element of the AST list (i.e. get(size()-1).
*
* @return the last argument of the function represented by this AST.
* @see IExpr#head()
*/
public IExpr last();
/**
* Apply the given head to this expression (i.e. create a list clone and replace the old head with the given one)
*
* @param head
* @return
*/
public IAST apply(IExpr head);
/**
* Apply the given head to this expression (i.e. create a sublist clone starting from index start and replacing the old head
* with the given one)
*
* @param head
* @return
*/
public IAST apply(IExpr head, int start);
/**
* Apply the given head to this expression (i.e. create a sublist clone from index start to end, and replacing the old head with
* the given one)
*
* @param head
* @return
*/
public IAST apply(IExpr head, int start, int end);
/**
* Maps the elements of this IAST with the unary functor. If the function returns null the original element is used
* (i.e. the functor didn't modified this AST).
*
*
*
* Example for mapping with Functors#replace1st(), where the first argument will be replaced by the current
* argument of this AST:
*
*
* plusAST.map(Functors.replace1st(F.D(F.Null, dAST.get(2))));
*
*
* @param functor
* a unary function
* @return
*/
public IAST map(final Function functor);
/**
* Maps the elements of this IAST with the unary functor. If the function returns null the original element of the
* result list is used.
*
* @param head
* the new head element of the result list
* @param functor
* a unary function
* @return
*/
public IAST map(final IExpr head, final Function functor);
/**
* Maps the elements of this IAST with the unary functor. If the function returns null the original element of the
* result list is used.
*
* @param clonedResultAST
* a list which is cloned from this list or greater or equal in size of this list.
* @param functor
* a unary function
* @return
*/
public IAST map(final IAST clonedResultAST, final Function functor);
/**
* Maps the elements of this IAST with the elements of the secondAST.
*
* @param functor
* a binary function
* @return the given resultAST.
* @throws IndexOutOfBoundsException
* if the secondAST size is lesser than this AST size
*/
public IAST map(IAST resultAST, IAST secondAST, BiFunction function);
/**
* Apply the predicate to each element in this AST and append the elements which satisfy the predicate to the
* filterAST.
*
* @param filterAST
* the elements which satisfy the predicate
* @param predicate
* the predicate which filters each element in the range
* @return the filterList
*/
public IAST filter(IAST filterAST, Predicate predicate);
/**
* Apply the predicate to each element in this AST and append the elements which satisfy the predicate to the
* filterAST, or otherwise append it to the restAST.
*
* @param filterAST
* the elements satisfy match the predicate
* @param restAST
* the elements which don't match the predicate
* @param predicate
* the predicate which filters each element in the range
* @return the filterList
*/
public IAST filter(IAST filterAST, IAST restAST, Predicate predicate);
/**
* Apply the predicate to each element in this AST and append the elements which satisfy the predicate to the
* 0th element of the result array, or otherwise append it to the 1st element of the result array.
*
* @param predicate
* the predicate which filters each element in the range
* @return the resulting ASTs in the 0-th and 1-st element of the array
*/
public IAST[] split(Predicate predicate);
/**
* Apply the function to each element in this AST and append the result elements for which the function returns
* non-null elements to the 0th element of the result array, or otherwise append it to the 1st element
* of the result array.
*
* @param function
* the function which filters each element in the range by returning a non-null result.
* @return the resulting ASTs in the 0-th and 1-st element of the array
*/
public IAST[] split(final Function function);
/**
* Set the head element of this list
*/
// public void setHeader(IExpr expr);
/**
* Returns a shallow copy of this IAST instance (the elements themselves are not copied).
*
* @return a clone of this IAST instance.
*/
public IAST clone();
/**
* Append an expression to this list.
*
* @return this after appending the given expression.
*/
public IAST append(IExpr expr);
/**
* Returns a shallow copy of this IAST instance (the elements themselves are not copied) and set the
* expr at the given position.
*
* @return a clone of this IAST instance.
*/
public IAST cloneSet(int position, IExpr expr);
/**
* Create a copy of this IAST, which only contains the head element of the list (i.e. the element with index 0).
*/
public IAST copyHead();
/**
* Create a copy of this IAST, which contains alls elements up to index (exclusive).
*/
public IAST copyUntil(int index);
/**
* Calculate a special hash value for pattern matching
*
* @return
*/
public int patternHashCode();
/**
* Prepend an expression to this list.
*
* @return this after prepending the given expression.
*/
public IAST prepend(IExpr expr);
/**
* Get the range of elements [1..ast.size()[. These range elements are the arguments of a function (represented as an AST).
*
* @return
*/
public ASTRange args();
/**
* Get the range of elements [0..ast.size()[ of the AST. This range elements are the head of the function prepended by the
* arguments of a function.
*
* @return
*/
public ASTRange range();
/**
* Get the range of elements [start..sizeOfAST[ of the AST
*
* @return
*/
public ASTRange range(int start);
/**
* Get the range of elements [start..end[ of the AST
*
* @return
*/
public ASTRange range(int start, int end);
/**
* Casts an IExpr at position index to an IInteger.
*
* @param index
* @return
* @throws WrongArgumentType
* if the cast is not possible
*/
public IInteger getInt(int index);
/**
* Casts an IExpr at position index to an INumber.
*
* @param index
* @return
* @throws WrongArgumentType
* if the cast is not possible
*/
public INumber getNumber(int index);
/**
* Casts an IExpr at position index to an IAST.
*
* @param index
* @return
* @throws WrongArgumentType
* if the cast is not possible
*/
public IAST getAST(int index);
/**
* Casts an IExpr which is a list at position index to an IAST.
*
* @param index
* @return
* @throws WrongArgumentType
*/
public IAST getList(int index);
}
Ads help maintain this website.