hirondelle.formula
Class Formula

Object
  hirondelle.formula.Formula

public final class Formula
extends Object

Evaluate a mathematical formula.

If any variables are present in the formula, then they must all be assigned a value before the formula can be successfully evaluated.

If any custom functions are present in the formula, then they must all be defined before the formula can be successfully evaluated.

Constructor Summary

Formula(String aFormula)
Constructor for the simplest case.

Formula(String aFormula, Map<String,Decimal> aVariableValues)
Constructor for a formula containing variables.

Formula(String aFormula, Map<String,Decimal> aVariableValues, Map<String,Function> aCustomFunctions)
Full constructor, taking all possible parameters.

Method Summary

Decimal	getAnswer() Evaluate the formula, and return the answer as a number.
Map<String,Function>	getCustomFunctions() Return the Map of custom functions passed to the constructor, if any.
static Map<String,Function>	getDefaultFunctions() Return all built-in functions, in a mutable Map, whose key is the name of the function as it appears in a formula.
String	getFormula() Return the text of the formula passed to the constructor.
List<String>	getFunctionNames() Return the names of all functions appearing in the formula, if any.
List<String>	getUnknownFunctionNames() Return the names of all functions appearing in the formula which aren't recognized, if any.
List<String>	getUnpopulatedVariableNames() Return the names of all variables appearing in the formula which aren't populated, if any.
List<String>	getVariableNames() Return the names of all variables appearing in the formula, if any.
Map<String,Decimal>	getVariableValues() Return the Map of variable values passed to the constructor, if any.
boolean	hasUnknownFunctionNames() Return true only if the formula has at least one unknown function name.
boolean	hasUnpopulatedVariables() Return true only if the formula has at least one variable which has not been populated.
boolean	hasVariables() Return true only if the formula has at least one variable.

Methods inherited from class Object

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

Constructor Detail

Formula

public Formula(String aFormula)

Constructor for the simplest case.

As in the full constructor, but using an empty Map for the variables, and the default built-in functions. This constructor can only be used when there are no variables in the formula.

Formula

public Formula(String aFormula,
               Map<String,Decimal> aVariableValues)

Constructor for a formula containing variables. As in the full constructor, but using default built-in functions.

Formula

public Formula(String aFormula,
               Map<String,Decimal> aVariableValues,
               Map<String,Function> aCustomFunctions)

Full constructor, taking all possible parameters.

Parameters:

aFormula - the text of the formula; must have content; if the formula contains references to variables, then values for all of those variables must be supplied in aVariableValues

aVariableValues - maps all variable names to their corresponding values; possibly empty.

aCustomFunctions - maps all possible function names to their corresponding implementations of the Function interface. Typically, callers will build this parameter by starting with getDefaultFunctions(), and altering its return value.

Method Detail

getDefaultFunctions

public static Map<String,Function> getDefaultFunctions()

Return all built-in functions, in a mutable Map, whose key is the name of the function as it appears in a formula.

The caller can alter the returned Map, and then pass the new Map to a constructor of this class. This allows you to add to the built-in functions, and even customize/replace the built-in functions themselves. In general, you may take the return value and :

• add your own custom functions
• substitute a different name for a built-in function (especially useful for multilingual applications)
• substitute a different implementation for a built-in function (not usually necessary, but the option exists)

getFormula

public String getFormula()

Return the text of the formula passed to the constructor.

getVariableValues

public Map<String,Decimal> getVariableValues()

Return the Map of variable values passed to the constructor, if any. Maps variable name to a Decimal value. May return an empty Map.

getCustomFunctions

public Map<String,Function> getCustomFunctions()

Return the Map of custom functions passed to the constructor, if any. Maps function name to a Function object. May return an empty Map.

hasVariables

public boolean hasVariables()

Return true only if the formula has at least one variable.

hasUnpopulatedVariables

public boolean hasUnpopulatedVariables()

Return true only if the formula has at least one variable which has not been populated.

getVariableNames

public List<String> getVariableNames()

Return the names of all variables appearing in the formula, if any.

getUnpopulatedVariableNames

public List<String> getUnpopulatedVariableNames()

Return the names of all variables appearing in the formula which aren't populated, if any. Variables are populated by passing a Map to the constructor.

getFunctionNames

public List<String> getFunctionNames()

Return the names of all functions appearing in the formula, if any.

hasUnknownFunctionNames

public boolean hasUnknownFunctionNames()

Return true only if the formula has at least one unknown function name. Any custom functions must be passed to the constructor.

getUnknownFunctionNames

public List<String> getUnknownFunctionNames()

Return the names of all functions appearing in the formula which aren't recognized, if any.

getAnswer

public Decimal getAnswer()
                  throws MalformedFormulaException

Evaluate the formula, and return the answer as a number. Resolves variable names into corresponding values, using a Map passed to the constructor.

Throws:

UnpopulatedVariableException - if there are one or more variables in the formula that are not in the Map of variable values passed to the constructor.

UnknownFunctionException - if there are one or more function names in the formula that are not in the Map of functions passed to the constructor.

MalformedFormulaException