Package org.mariuszgromada.math.mxparser

Class Argument

  • All Implemented Interfaces:
    java.io.Serializable
    Direct Known Subclasses:
    RecursiveArgument
    public class Argument
extends PrimitiveElement
implements java.io.Serializable
    Argument class enables to declare the argument (variable) which can be used in further processing (in expressions, functions and dependent / recursive arguments).

    For example:
    • 'x' - argument in expression 'sin(x)'
    • 'x' and 'y' - arguments in expression 'sin(x)+cos(y)'.
    • 'x=2*t' - dependent argument (dependent from 't') in expression 'cos(x)'

    Using Argument class you can define two argument types:

    • free argument - when value of argument 'x' is directly given by a number (for example 'x=5')
    • dependent argument - when value of argument 'x' is given by expression (for example: 'x=2*a+b' - argument 'x' depends from argument/constant 'a' and argument/constant 'b' or any other possible option like function, etc...)

    When creating an argument you should avoid names reserved as parser keywords, in general words known in mathematical language as function names, operators (for example: sin, cos, +, -, etc...). Please be informed that after associating the argument with the expression, function or dependent/recursive argument its name will be recognized by the parser as reserved key word. It means that it could not be the same as any other key word known by the parser for this particular expression. Parser is case-sensitive.

    Version:
    6.1.0
    See Also:
    RecursiveArgument, Expression, Function, Constant, Serialized Form

    • Constructor Summary

      Constructors 
      Constructor Description
      Argument​(boolean isRecursive, java.lang.String argumentDefinitionString, PrimitiveElement... elements)
      Package level constructor used by RecursiveArgument class
      Argument​(java.lang.String argumentDefinitionString, boolean forceDependent, PrimitiveElement... elements)
      Default constructor - creates argument based on the argument definition string.
      Argument​(java.lang.String argumentName, double argumentValue)
      Constructor - creates free argument.
      Argument​(java.lang.String argumentName, java.lang.String argumentExpressionString, PrimitiveElement... elements)
      Constructor - creates dependent argument(with hidden argument expression).
      Argument​(java.lang.String argumentName, ArgumentExtension argumentExtension)
      Constructor for argument definition based on your own source code - this is via implementation of ArgumentExtension interface.
      Argument​(java.lang.String argumentDefinitionString, PrimitiveElement... elements)
      Default constructor - creates argument based on the argument definition string.
      Argument​(Argument argumentToClone, boolean isThreadSafeClone, CloneCache cloneCache)  

    • Field Detail

      • serialVersionUID

        private static final long serialVersionUID

      • NO_SYNTAX_ERRORS

        public static final boolean NO_SYNTAX_ERRORS
        Status of the syntax - no syntax error
        See Also:
        Constant Field Values

      • SYNTAX_ERROR

        public static final boolean SYNTAX_ERROR
        Status of the syntax - syntax error or syntax status unknown
        See Also:
        Constant Field Values

      • SYNTAX_ERROR_OR_STATUS_UNKNOWN

        @Deprecated
public static final boolean SYNTAX_ERROR_OR_STATUS_UNKNOWN
        Deprecated.
        Planned to be removed, use SYNTAX_ERROR instead
        Status of the syntax - syntax error or syntax status unknown
        See Also:
        Constant Field Values

      • SYNTAX_STATUS_UNKNOWN

        private static final boolean SYNTAX_STATUS_UNKNOWN
        See Also:
        Constant Field Values

      • ARGUMENT_INITIAL_VALUE

        public static final double ARGUMENT_INITIAL_VALUE
        Double.NaN as initial value of the argument.
        See Also:
        Constant Field Values

      • NOT_FOUND

        public static final int NOT_FOUND
        When argument was not found
        See Also:
        Constant Field Values

      • FREE_ARGUMENT

        public static final int FREE_ARGUMENT
        Type indicator for free argument.
        See Also:
        Constant Field Values

      • DEPENDENT_ARGUMENT

        public static final int DEPENDENT_ARGUMENT
        Type indicator for dependent argument.
        See Also:
        Constant Field Values

      • RECURSIVE_ARGUMENT

        public static final int RECURSIVE_ARGUMENT
        Type indicator for recursive argument.
        See Also:
        Constant Field Values

      • TYPE_ID

        public static final int TYPE_ID
        Argument type id for the definition of keywords known by the parser.
        See Also:
        Constant Field Values

      • TYPE_DESC

        public static java.lang.String TYPE_DESC

      • description

        private java.lang.String description
        Description of the argument.

      • argumentExpression

        Expression argumentExpression
        Argument expression for dependent and recursive arguments.

      • argumentName

        private java.lang.String argumentName
        Argument name (x, y, arg1, my_argument, etc...)

      • syntaxStatusDefinition

        protected boolean syntaxStatusDefinition
        Syntax status registered on argument definition: - constructor, set name, ...

      • errorMessageDefinition

        private java.lang.String errorMessageDefinition
        Error Message registered on argument definition: - constructor, set name, ...

      • argumentType

        int argumentType
        Argument type (free, dependent)

      • argumentValue

        double argumentValue
        Argument value (for free arguments).

      • recursionCallsCounter

        private int recursionCallsCounter
        Internal counter to avoid infinite loops while calculating expression defined in the way showed by below examples Argument x = new Argument("x = 2*x"); x.addDefinitions(x);

      • computingTime

        double computingTime
        Keeps computing time

      • MAX_RECURSION_CALLS

        static int MAX_RECURSION_CALLS

    • Constructor Detail

      • Argument

        public Argument​(java.lang.String argumentDefinitionString,
                PrimitiveElement... elements)
        Default constructor - creates argument based on the argument definition string.
        Parameters:
        argumentDefinitionString - Argument definition string, i.e.:
        • 'x' - only argument name
        • 'x=5' - argument name and argument value
        • 'x=2*5' - argument name and argument value given as simple expression
        • 'x=2*y' - argument name and argument expression (dependent argument 'x' on argument 'y')
        elements - Optional parameters (comma separated) such as Arguments, Constants, Functions

      • Argument

        public Argument​(java.lang.String argumentDefinitionString,
                boolean forceDependent,
                PrimitiveElement... elements)
        Default constructor - creates argument based on the argument definition string.
        Parameters:
        argumentDefinitionString - Argument definition string, i.e.:
        • 'x' - only argument name
        • 'x=5' - argument name and argument value
        • 'x=2*5' - argument name and argument value given as simple expression
        • 'x=2*y' - argument name and argument expression (dependent argument 'x' on argument 'y')
        forceDependent - If true parser will try to create dependent argument
        elements - Optional parameters (comma separated) such as Arguments, Constants, Functions

      • Argument

        Argument​(boolean isRecursive,
         java.lang.String argumentDefinitionString,
         PrimitiveElement... elements)
        Package level constructor used by RecursiveArgument class
        Parameters:
        isRecursive -
        argumentDefinitionString -
        elements -
        See Also:
        RecursiveArgument

      • Argument

        public Argument​(java.lang.String argumentName,
                double argumentValue)
        Constructor - creates free argument.
        Parameters:
        argumentName - the argument name
        argumentValue - the argument value

      • Argument

        public Argument​(java.lang.String argumentName,
                ArgumentExtension argumentExtension)
        Constructor for argument definition based on your own source code - this is via implementation of ArgumentExtension interface.
        Parameters:
        argumentName - Argument name
        argumentExtension - Your own source code

      • Argument

        public Argument​(java.lang.String argumentName,
                java.lang.String argumentExpressionString,
                PrimitiveElement... elements)
        Constructor - creates dependent argument(with hidden argument expression).
        Parameters:
        argumentName - the argument name
        argumentExpressionString - the argument expression string
        elements - Optional parameters (comma separated) such as Arguments, Constants, Functions
        See Also:
        Expression, PrimitiveElement

      • Argument

        Argument​(Argument argumentToClone,
         boolean isThreadSafeClone,
         CloneCache cloneCache)

    • Method Detail

      • refreshMaxAllowedRecursionDepth

        static void refreshMaxAllowedRecursionDepth()

      • buildErrorMessageInvalidArgumentName

        private static java.lang.String buildErrorMessageInvalidArgumentName​(java.lang.String argumentName)

      • buildErrorMessageInvalidArgumentDefinition

        private static java.lang.String buildErrorMessageInvalidArgumentDefinition​(java.lang.String argumentDefinitionString,
                                                                           java.lang.String argumentDefinitionExamples)

      • buildErrorMessageInvalidArgumentDefinition

        private static java.lang.String buildErrorMessageInvalidArgumentDefinition​(java.lang.String argumentDefinitionString)

      • registerNoSyntaxErrorInDefinition

        private void registerNoSyntaxErrorInDefinition()

      • registerSyntaxErrorInDefinition

        private void registerSyntaxErrorInDefinition​(java.lang.String errorMessage)

      • analyzeArgumentDefinitionString

        private void analyzeArgumentDefinitionString​(boolean isRecursive,
                                             boolean forceDependent,
                                             java.lang.String argumentDefinitionString,
                                             PrimitiveElement... elements)
        Argument definition in one string logic
        Parameters:
        isRecursive -
        forceDependent -
        argumentDefinitionString -
        elements -

      • setDescription

        public void setDescription​(java.lang.String description)
        Sets argument description.
        Parameters:
        description - the argument description.

      • getDescription

        public java.lang.String getDescription()
        Gets argument description.
        Returns:
        The argument description string.

      • setVerboseMode

        public void setVerboseMode()
        Enables argument verbose mode

      • setSilentMode

        public void setSilentMode()
        Disables argument verbose mode (sets default silent mode)

      • getVerboseMode

        public boolean getVerboseMode()
        Returns verbose mode status
        Returns:
        true if verbose mode is on, otherwise returns false.

      • getRecursiveMode

        public boolean getRecursiveMode()
        Gets recursive mode status
        Returns:
        true if recursive mode is enabled (RecursiveArgument), otherwise returns false
        See Also:
        RecursiveArgument

      • getComputingTime

        public double getComputingTime()
        Gets computing time
        Returns:
        Computing time in seconds.

      • setArgumentName

        public void setArgumentName​(java.lang.String argumentName)
        Sets (modifies) argument name. Each expression / function / dependent argument associated with this argument will be marked as modified (requires new syntax checking).
        Parameters:
        argumentName - the argument name

      • setArgumentExpressionString

        public void setArgumentExpressionString​(java.lang.String argumentExpressionString)
        Sets argument expression string. Each expression / function / dependent argument associated with this argument will be marked as modified (requires new syntax checking). If BODY_EXTENDED argument then BODY_RUNTIME is set.
        Parameters:
        argumentExpressionString - the argument expression string
        See Also:
        Expression

      • getArgumentName

        public java.lang.String getArgumentName()
        Gets argument name
        Returns:
        the argument name as string

      • getArgumentExpressionString

        public java.lang.String getArgumentExpressionString()
        Gets argument expression string
        Returns:
        the argument expression string

      • getArgumentType

        public int getArgumentType()
        Gets argument type
        Returns:
        Argument type: Argument.FREE_ARGUMENT, Argument.DEPENDENT_ARGUMENT, Argument.RECURSIVE_ARGUMENT

      • setArgumentValue

        public void setArgumentValue​(double argumentValue)
        Sets argument value, if DEPENDENT_ARGUMENT then argument type is set to FREE_ARGUMENT. If BODY_EXTENDED argument the BODY_RUNTIME argument is set.
        Parameters:
        argumentValue - the value of argument

      • checkSyntax

        public boolean checkSyntax()
        Checks argument syntax
        Returns:
        syntax status: Argument.NO_SYNTAX_ERRORS, Argument.SYNTAX_ERROR

      • getErrorMessage

        public java.lang.String getErrorMessage()
        Returns error message after checking the syntax
        Returns:
        Error message as string.

      • getArgumentValue

        public double getArgumentValue()
        Gets argument value.
        Returns:
        direct argument value for free argument, otherwise returns calculated argument value based on the argument expression.

      • getArgumentValue

        public double getArgumentValue​(CalcStepsRegister calcStepsRegister)
        Gets argument value and registers all the calculation steps
        Parameters:
        calcStepsRegister - A collection to store list of calculation steps, steps registered as strings.
        Returns:
        direct argument value for free argument, otherwise returns calculated argument value based on the argument expression.

      • addDefinitions

        public void addDefinitions​(PrimitiveElement... elements)
        Adds user defined elements (such as: Arguments, Constants, Functions) to the argument expressions.
        Parameters:
        elements - Elements list (variadic - comma separated) of types: Argument, Constant, Function
        See Also:
        PrimitiveElement

      • removeDefinitions

        public void removeDefinitions​(PrimitiveElement... elements)
        Removes user defined elements (such as: Arguments, Constants, Functions) from the argument expressions.
        Parameters:
        elements - Elements list (variadic - comma separated) of types: Argument, Constant, Function
        See Also:
        PrimitiveElement

      • addArguments

        public void addArguments​(Argument... arguments)
        Adds arguments (variadic) to the argument expression definition.
        Parameters:
        arguments - the arguments list (comma separated list)
        See Also:
        Argument, RecursiveArgument

      • defineArguments

        public void defineArguments​(java.lang.String... argumentsNames)
        Enables to define the arguments (associated with the argument expression) based on the given arguments names.
        Parameters:
        argumentsNames - the arguments names (variadic) comma separated list
        See Also:
        Argument, RecursiveArgument

      • defineArgument

        public void defineArgument​(java.lang.String argumentName,
                           double argumentValue)
        Enables to define the argument (associated with the argument expression) based on the argument name and the argument value.
        Parameters:
        argumentName - the argument name
        argumentValue - the argument value
        See Also:
        Argument, RecursiveArgument

      • getArgumentIndex

        public int getArgumentIndex​(java.lang.String argumentName)
        Gets argument index from the argument expression.
        Parameters:
        argumentName - the argument name
        Returns:
        The argument index if the argument name was found, otherwise returns Argument.NOT_FOUND
        See Also:
        Argument, RecursiveArgument

      • getArgument

        public Argument getArgument​(java.lang.String argumentName)
        Gets argument from the argument expression.
        Parameters:
        argumentName - the argument name
        Returns:
        The argument if the argument name was found, otherwise returns null.
        See Also:
        Argument, RecursiveArgument

      • getArgument

        public Argument getArgument​(int argumentIndex)
        Gets argument from the argument expression.
        Parameters:
        argumentIndex - the argument index
        Returns:
        Argument if the argument index is between 0 and the last available argument index (getArgumentsNumber()-1), otherwise returns null.
        See Also:
        Argument, RecursiveArgument

      • getArgumentsNumber

        public int getArgumentsNumber()
        Gets number of arguments associated with the argument expression.
        Returns:
        The number of arguments (int >= 0)
        See Also:
        Argument, RecursiveArgument

      • removeArguments

        public void removeArguments​(java.lang.String... argumentsNames)
        Removes first occurrences of the arguments associated with the argument expression.
        Parameters:
        argumentsNames - the arguments names (variadic parameters) comma separated list
        See Also:
        Argument, RecursiveArgument

      • removeArguments

        public void removeArguments​(Argument... arguments)
        Removes first occurrences of the arguments associated with the argument expression.
        Parameters:
        arguments - the arguments (variadic parameters) comma separated list
        See Also:
        Argument, RecursiveArgument

      • removeAllArguments

        public void removeAllArguments()
        Removes all arguments associated with the argument expression.
        See Also:
        Argument, RecursiveArgument

      • addConstants

        public void addConstants​(Constant... constants)
        Adds constants (variadic parameters) to the argument expression definition.
        Parameters:
        constants - the constants (comma separated list)
        See Also:
        Constant

      • addConstants

        public void addConstants​(java.util.List<Constant> constantsList)
        Adds constants to the argument expression definition.
        Parameters:
        constantsList - the list of constants
        See Also:
        Constant

      • defineConstant

        public void defineConstant​(java.lang.String constantName,
                           double constantValue)
        Enables to define the constant (associated with the argument expression) based on the constant name and constant value.
        Parameters:
        constantName - the constant name
        constantValue - the constant value
        See Also:
        Constant

      • getConstantIndex

        public int getConstantIndex​(java.lang.String constantName)
        Gets constant index associated with the argument expression.
        Parameters:
        constantName - the constant name
        Returns:
        Constant index if constant name was found, otherwise return Constant.NOT_FOUND.
        See Also:
        Constant

      • getConstant

        public Constant getConstant​(java.lang.String constantName)
        Gets constant associated with the argument expression.
        Parameters:
        constantName - the constant name
        Returns:
        Constant if constant name was found, otherwise return null.
        See Also:
        Constant

      • getConstant

        public Constant getConstant​(int constantIndex)
        Gets constant associated with the argument expression.
        Parameters:
        constantIndex - the constant index
        Returns:
        Constant if the constantIndex is between 0 and the last available constant index (getConstantsNumber() - 1), otherwise it returns null.
        See Also:
        Constant

      • getConstantsNumber

        public int getConstantsNumber()
        Gets number of constants associated with the argument expression.
        Returns:
        number of constants (int >= 0)
        See Also:
        Constant

      • removeConstants

        public void removeConstants​(java.lang.String... constantsNames)
        Removes first occurrences of the constants associated with the argument expression.
        Parameters:
        constantsNames - the constants names (variadic parameters) comma separated list
        See Also:
        Constant

      • removeConstants

        public void removeConstants​(Constant... constants)
        Removes first occurrences of the constants associated with the argument expression
        Parameters:
        constants - the constants (variadic parameters) comma separated list
        See Also:
        Constant

      • removeAllConstants

        public void removeAllConstants()
        Removes all constants associated with the argument expression
        See Also:
        Constant

      • addFunctions

        public void addFunctions​(Function... functions)
        Adds functions (variadic parameters) to the argument expression definition.
        Parameters:
        functions - the functions (variadic parameters) comma separated list
        See Also:
        Function

      • defineFunction

        public void defineFunction​(java.lang.String functionName,
                           java.lang.String functionExpressionString,
                           java.lang.String... argumentsNames)
        Enables to define the function (associated with the argument expression) based on the function name, function expression string and arguments names (variadic parameters).
        Parameters:
        functionName - the function name
        functionExpressionString - the expression string
        argumentsNames - the function arguments names (variadic parameters) comma separated list
        See Also:
        Function

      • getFunctionIndex

        public int getFunctionIndex​(java.lang.String functionName)
        Gets index of function associated with the argument expression.
        Parameters:
        functionName - the function name
        Returns:
        Function index if function name was found, otherwise returns Function.NOT_FOUND
        See Also:
        Function

      • getFunction

        public Function getFunction​(java.lang.String functionName)
        Gets function associated with the argument expression.
        Parameters:
        functionName - the function name
        Returns:
        Function if function name was found, otherwise returns null.
        See Also:
        Function

      • getFunction

        public Function getFunction​(int functionIndex)
        Gets function associated with the argument expression.
        Parameters:
        functionIndex - the function index
        Returns:
        Function if function index is between 0 and the last available function index (getFunctionsNumber()-1), otherwise returns null.
        See Also:
        Function

      • getFunctionsNumber

        public int getFunctionsNumber()
        Gets number of functions associated with the argument expression.
        Returns:
        number of functions (int >= 0)
        See Also:
        Function

      • removeFunctions

        public void removeFunctions​(java.lang.String... functionsNames)
        Removes first occurrences of the functions associated with the argument expression.
        Parameters:
        functionsNames - the functions names (variadic parameters) comma separated list
        See Also:
        Function

      • removeFunctions

        public void removeFunctions​(Function... functions)
        Removes first occurrences of the functions associated with the argument expression.
        Parameters:
        functions - the functions (variadic parameters) comma separated list.
        See Also:
        Function

      • removeAllFunctions

        public void removeAllFunctions()
        Removes all functions associated with the argument expression.
        See Also:
        Function

      • addRelatedExpression

        void addRelatedExpression​(Expression expression)
        Adds related expression to the argumentExpression
        Parameters:
        expression - the related expression
        See Also:
        Expression

      • removeRelatedExpression

        void removeRelatedExpression​(Expression expression)
        Adds related expression form the argumentExpression
        Parameters:
        expression - related expression
        See Also:
        Expression

      • setExpressionModifiedFlags

        void setExpressionModifiedFlags()
        Sets expression was modified flag to all related expressions to the argumentExpression.
        See Also:
        Expression

      • clone

        public Argument clone()
        Creates cloned object of this argument.
        Overrides:
        clone in class java.lang.Object
        Returns:
        clone of the argument.

      • cloneForThreadSafeInternal

        Argument cloneForThreadSafeInternal​(CloneCache cloneCache)

      • cloneForThreadSafeInternal

        Argument cloneForThreadSafeInternal​(Expression relatedExpressionThatInitiatedClone,
                                    CloneCache cloneCache)

      • cloneForThreadSafe

        public Argument cloneForThreadSafe()
        Creates a completely independent 1-1 clone that can be safely used by a separate thread. If the cloned element contains references to other elements (e.g. arguments, functions, constants), then they will also be cloned and the newly created element will contain references to the corresponding clones. Important - the API allows you to extract all these clones.
        Returns:
        Cloned object.