cox.jmatt.java.MathTools
Class Percent

java.lang.Object
  extended by cox.jmatt.java.MathTools.Percent

public class Percent
extends java.lang.Object

The Percent class encapsulates all the machinery necessary to calculate simple percents. The methods in this class require terminology to use. In all cases involving percent problems the following three words are used consistently:

As stated previously, any time a percent rate is supplied it is assumed to be in integer form. There is no need to convert to decimal values as this is handled automatically! The methods in this class are static and ALL are convenience methods! While percent calculations are not hard to do, doing a lot of them at one time, especially when making up test questions, can be tedious and time-consuming. The Percent class is designed to ease this burden.

Two types of methods make up this class: quick-solve convenience methods and power-formatting methods. The latter solve for the (one) unknown quantity in a percent if given the other two. If any of the values is not valid it is returned as Double.NaN. The power-formatting methods take arguments of Object type Double to allow null for the unknown value. That is the value that will be calculated and then fed into a String template via ten pre-defined formatting characters. The result is broken into a Problem and Answer and returned as a Question.

The change methods (solveChange() and formatChange()) are used to calculate a percent change. The numeric values are ordered as given: the first value is the starting value and the second the ending value. The percent change is calculated from that and the sign determines whether it is a percent increase (positive) or percent decrease (negative). As with other methods the percent change is given as an integral percent and not a decimal. NOTE: The fix value of the percent change is separate from the other fix values!


Field Summary
static java.lang.String SIMPLE_CHANGE_QUESTION
          The simplest form of percent change question: 'What is the percent change from <0> to <1> @@ A(n) <3> percent <4>.'
static java.lang.String SIMPLE_QUESTION
          The simplest form of percent question: '<6> is <1><3> of <0>? @@ <2> is <1>% of <0>.'
 
Constructor Summary
Percent()
          Standard constructor, useful for scripting.
 
Method Summary
 java.lang.String convert_Rate(java.lang.Double pPercent, java.lang.Double pDecimal, int pFix)
          Instance rate converter.
static java.lang.String convertRate(java.lang.Double pPercent, java.lang.Double pDecimal, int pFix)
          This method is designed to convert between a (whole) percent and a decimal.
static Percent createPercent()
          Static factory method for creating new Percents.
 Question format_Change(java.lang.Number pFirst, java.lang.Number pSecond, java.lang.String pTemplate)
          Instance version of the short percent change formatting method.
 Question format_Change(java.lang.Number pFirst, java.lang.Number pSecond, java.lang.String pTemplate, int pFixFirst, int pFixSecond, int pFixChange, boolean pGroup)
          Instance version of the full percent change format() method.
static Question format(java.lang.Double pBase, java.lang.Double pRate, java.lang.Double pAmt, java.lang.String pTemplate)
          Format per the current 'fix' values.
static Question format(java.lang.Double pBase, java.lang.Double pRate, java.lang.Double pAmt, java.lang.String pTemplate, int pFixBase, int pFixRate, int pFixAmt, boolean pGroup)
          This is the power-method of the Percent class.
static Question formatChange(java.lang.Number pFirst, java.lang.Number pSecond, java.lang.String pTemplate)
          Percent change formatting method using internal fix values: Base for pFirst, Amount for pSecond and Rate for the percent change.
static Question formatChange(java.lang.Number pFirst, java.lang.Number pSecond, java.lang.String pTemplate, int pFixFirst, int pFixSecond, int pFixChange, boolean pGroup)
          Formatting method for percent change problems.
 Question formatPercent(java.lang.Double pBase, java.lang.Double pRate, java.lang.Double pAmt, java.lang.String pTemplate)
          Format per the current 'fix' values, instance version.
 Question formatPercent(java.lang.Double pBase, java.lang.Double pRate, java.lang.Double pAmt, java.lang.String pTemplate, int pFixBase, int pFixRate, int pFixAmt, boolean pGroup)
          Instance version of the full-power format() method.
 Percent newPercent()
          Instance method for a new Percent.
static void setFixValues(int pBase, int pRate, int pAmt, boolean pGroup)
          Set the default number of places to fix values for the Base, Rate and Amount.
 void setNewFixValues(int pBase, int pRate, int pAmt, boolean pGroup)
          Instance access to setFixValues().
 double solve_Amount(double pBase, double pRate)
          Instance version with modified name.
 double solve_Base(double pRate, double pAmount)
          Instance version with modified name.
 double solve_Change(double pFirst, double pSecond)
          Instance version of solveChange(double, double).
 double solve_Change(int pFirst, int pSecond)
          Instance version of solveChange(int, int).
 double solve_Rate(double pBase, double pAmount)
          Instance version with modified name.
static double solveAmount(double pBase, double pRate)
          Solve for the Amount, given the Base and the Rate.
static double solveBase(double pRate, double pAmount)
          Solve for the Base, given the Rate and the Amount.
static double solveChange(double pFirst, double pSecond)
          Calculate percent change on two doubles.
static double solveChange(int pFirst, int pSecond)
          Solve for the percent change, int version.
static double solveRate(double pBase, double pAmount)
          Solve for the Rate, given the Base and the Amount.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SIMPLE_QUESTION

public static final java.lang.String SIMPLE_QUESTION
The simplest form of percent question: '<6> is <1><3> of <0>? @@ <2> is <1>% of <0>.'

See Also:
Constant Field Values

SIMPLE_CHANGE_QUESTION

public static final java.lang.String SIMPLE_CHANGE_QUESTION
The simplest form of percent change question: 'What is the percent change from <0> to <1> @@ A(n) <3> percent <4>.'

See Also:
Constant Field Values
Constructor Detail

Percent

public Percent()
Standard constructor, useful for scripting.

Method Detail

createPercent

public static Percent createPercent()
Static factory method for creating new Percents.


newPercent

public Percent newPercent()
Instance method for a new Percent.


solveAmount

public static double solveAmount(double pBase,
                                 double pRate)
Solve for the Amount, given the Base and the Rate.


solveRate

public static double solveRate(double pBase,
                               double pAmount)
Solve for the Rate, given the Base and the Amount.


solveBase

public static double solveBase(double pRate,
                               double pAmount)
Solve for the Base, given the Rate and the Amount.


solveChange

public static double solveChange(int pFirst,
                                 int pSecond)
Solve for the percent change, int version. The calculation is (pSecond - pFirst) / pFirst, multiplied by 100. If something goes terribly wrong the return value is Double.NaN. The sign of the return value determines whether the change is a percent increase (positive) or percent decrease (negative).

Parameters:
pFirst - The starting number (the number that changes).
pSecond - The ending number (what pFirst changes into).
Returns:
The percent change or NaN if something terrible happens).

solveChange

public static double solveChange(double pFirst,
                                 double pSecond)
Calculate percent change on two doubles. Parameters and return values are per the int-argument method.


solve_Change

public double solve_Change(int pFirst,
                           int pSecond)
Instance version of solveChange(int, int).


solve_Change

public double solve_Change(double pFirst,
                           double pSecond)
Instance version of solveChange(double, double).


solve_Amount

public double solve_Amount(double pBase,
                           double pRate)
Instance version with modified name.


solve_Rate

public double solve_Rate(double pBase,
                         double pAmount)
Instance version with modified name.


solve_Base

public double solve_Base(double pRate,
                         double pAmount)
Instance version with modified name.


format

public static Question format(java.lang.Double pBase,
                              java.lang.Double pRate,
                              java.lang.Double pAmt,
                              java.lang.String pTemplate,
                              int pFixBase,
                              int pFixRate,
                              int pFixAmt,
                              boolean pGroup)

This is the power-method of the Percent class. It takes a Question.fillTemplate()-style formatting String, fills in information, and returns a Question. The basic format of the String is 'Problem @@ Answer' with the following tokens filled in to the data array:

The true power and flexibility of this method come from the parameters supplied. The three basic numeric quantities are all given as Double (Object version!) to allow one of them to be set to null. Whichever parameter is set to null is the parameter that will be solved! The data tokens for template replacement are listed above, and the resulting String is then broken down into Problem and Answer parts and returned as a Question.

NOTE: Exactly one of pBase, pRate, and pAmt must be null! Also, the template breaks on '@@' and this is not configurable. If pTemplate is null or empty SIMPLE_QUESTION is used. If either component of the Template is blank or there is no '@@' the Answer of the resulting Question will be 'Ans?'. If more than one required value is null, the returned Question is blank.

The formatting process allows the number of decimal places in each quantity to be specified. The fix values are explicitly supplied here: a value of -1 results in no place-fixing for that quantity.

Parameters:
pBase - The value of the Base, or null if it is unknown.
pRate - The value of the Rate, or null if it is unknown.
pAmt - The value of the Amount, or null if it is unknown.
pTemplate - The 'Problem @@ Answer' String template fed to Questionl.fillTemplate().
pFixBase - The number of decimal places allowed for the Base, or -1 to ignore.
pFixRate - The number of decimal places allowed for the Rate, or -1 to ignore.
pFixAmt - The number of decumal places allowed for the Rate, or -1 to ignore.
pGroup - Determine whether or not grouping is enabled for any 'fixed' numbers.
Returns:
A freshly-built Question with all necessary components filled in.

formatPercent

public Question formatPercent(java.lang.Double pBase,
                              java.lang.Double pRate,
                              java.lang.Double pAmt,
                              java.lang.String pTemplate,
                              int pFixBase,
                              int pFixRate,
                              int pFixAmt,
                              boolean pGroup)
Instance version of the full-power format() method.


format

public static Question format(java.lang.Double pBase,
                              java.lang.Double pRate,
                              java.lang.Double pAmt,
                              java.lang.String pTemplate)
Format per the current 'fix' values.


formatPercent

public Question formatPercent(java.lang.Double pBase,
                              java.lang.Double pRate,
                              java.lang.Double pAmt,
                              java.lang.String pTemplate)
Format per the current 'fix' values, instance version.


formatChange

public static Question formatChange(java.lang.Number pFirst,
                                    java.lang.Number pSecond,
                                    java.lang.String pTemplate,
                                    int pFixFirst,
                                    int pFixSecond,
                                    int pFixChange,
                                    boolean pGroup)

Formatting method for percent change problems. All parameters are specified. If anything goes wrong a Debug-level message is sent and the return value is a blank Question. The starting and ending numbers are cast as Number to allow use of the int-argument methods. This happens only if both numbers are of type Integer.

The Question is formed per the standard Percent.format() method: the answer token is hard-coded '@@' and the template is in Problem / Answer form. The replacement tokens available to this method are:

Parameters:
pFirst - The first (changing) value.
pSecond - The second (ending) value.
pTemplate - The template String to format into a Question. If null or blank, SIMPLE_CHANGE_QUESTION is used.
pFixFirst - The decimal places for pFirst.
pFixSecond - The decimal places to fix in pSecond or -1.
pFixChange - The number of decimal places to allow in the percent change, or -1 not to fix at all.
pGroup - Set whether or not to use grouping if fixing the numbers.
Returns:
A freshly-created Question based on the template sent in or a blank Question if something goes horribly wrong.

formatChange

public static Question formatChange(java.lang.Number pFirst,
                                    java.lang.Number pSecond,
                                    java.lang.String pTemplate)
Percent change formatting method using internal fix values: Base for pFirst, Amount for pSecond and Rate for the percent change.


format_Change

public Question format_Change(java.lang.Number pFirst,
                              java.lang.Number pSecond,
                              java.lang.String pTemplate,
                              int pFixFirst,
                              int pFixSecond,
                              int pFixChange,
                              boolean pGroup)
Instance version of the full percent change format() method.


format_Change

public Question format_Change(java.lang.Number pFirst,
                              java.lang.Number pSecond,
                              java.lang.String pTemplate)
Instance version of the short percent change formatting method.


setFixValues

public static void setFixValues(int pBase,
                                int pRate,
                                int pAmt,
                                boolean pGroup)
Set the default number of places to fix values for the Base, Rate and Amount. Once set these values are in effect until they are changed. Setting a value to -1 turns off fixing for that element.

Parameters:
pBase - Decimal places to fix in the Base.
pRate - Decimal places to fix in the Rate.
pAmt - Decimal places to fix in the Amount.
pGroup - Enable/disable grouping.

setNewFixValues

public void setNewFixValues(int pBase,
                            int pRate,
                            int pAmt,
                            boolean pGroup)
Instance access to setFixValues().


convertRate

public static java.lang.String convertRate(java.lang.Double pPercent,
                                           java.lang.Double pDecimal,
                                           int pFix)
This method is designed to convert between a (whole) percent and a decimal. The parameters are type Double to allow (exactly!) one to be null. If both are null the result is '0.0'. If both are defined pDecimal is converted to a percent.

Parameters:
pPercent - The percent value to convert to decimal.
pDecimal - The decimal value to convert to percent.
pFix - The number of decimal places to fix in the answer. Ignored if -1

convert_Rate

public java.lang.String convert_Rate(java.lang.Double pPercent,
                                     java.lang.Double pDecimal,
                                     int pFix)
Instance rate converter.