cox.jmatt.java.MathTools
Class Arithmetic

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

public class Arithmetic
extends java.lang.Object

This class provides methods for creating and manipulating numbers digit-wise. It also provides methods for identifying whole and fractional place values and a method to convert a long into words.

Arithmetic also contains several methods that, while not specifically arithmetic-related, are handy to have. These methods generate a (person's) name and can supply the properly-gendered pronouns for that name.

Decimal Arrays and Digit Arrays

Arithmetic allows digit-wise manipulation of numbers via the createNumber() method, decimal arrays, and digit arrays. A digit array is nothing more than an integer broken down into an array corresponding to its place values. Digit arrays should be read 'backwards;' element zero is ones, element 1 is tens, element 2 is hundreds, etc. The index of the array element equals the (positive) exponent of 10 in its place value. Each element of a digit array holds a single digit: 0 through 9. Most methods that deal with digit arrays enforce this by modding by ten as needed.

Decimal arrays work exactly as do digit arrays, but backward. The element index still represents an exponent, but in this case they are negative. Element 0 still represents ones, but in a decimal array this is the whole part of the number, so 'mod 10' is not applied to this place ONLY. Element 1 represents the tenths place, or 10^-1.

Use decimal and digit arrays to simplify rounding, addition-with-carry and subtraction-with-borrow problem creation.


Constructor Summary
Arithmetic()
          Constructor provided to generate instances for scripting apps.
 
Method Summary
static int coprime(int pLow, int pHigh, int pCoprime)
          Pick a number from a range that has no common factors with the given number greater than 1.
static java.lang.String createNumber(java.lang.String pFormat)
          Generate a number digit-wise per a special format String.
static java.lang.String daToString(int[] pDigits)
          This method turns a digit array into a String.
static java.lang.String fix(double pNumber, int pPlace, boolean pGroup)
          Sometimes a floating-point number needs to have its number of decimal places fixed.
static java.lang.String fromDecimalArray(int[] pDecArr)
          Convert a decimal array to a String.
static long fromDigitArray(int[] pAry)
          This method takes a digit (int[]) array and converts it to an integer type (long).
static int gcf(int pL, int pR)
          Calculate the Greatest Common Factor of the numbers given.
static java.lang.String[] getPerson()
          Pick a random name and gender-appropriate pronouns.
static java.lang.String getPlaceValue(int pIndex, boolean pSuffix)
          Convenience method for getPlaceValue(pIndex, pSuffix, true).
static java.lang.String getPlaceValue(int pIndex, boolean pSuffix, boolean pPlural)
          Retrieve a place value up to hundred quadrillion.
 Arithmetic_SCROB getSCROB()
          Return a SCROB instance of this class.
static int indivisible(int pLow, int pHigh, int pDivisor)
          Find a number not divisible by a given divisor from a range of candidates.
static int lcm(int pL, int pR)
          Find the Least Common Multiple of the given numbers.
static java.text.NumberFormat newNumberFormat()
          At times, a number needs formatting.
static double[] pad(double[] pAry, int pLength, double pPad)
          This method is identical to pad(int[], int, int) except that it works on double arrays.
static int[] pad(int[] pAry, int pLength, int pPad)
          This method takes an int[] array and extends it to the specified length, filling in any extra values with the padding constant.
static int[] round(int[] pData, int pPlace, boolean pDecArray)
          This method takes a decimal or digit array and rounds to the specified place.
static int[] splint(java.lang.String pData, boolean pDigitArray, boolean pDecimalArray)
          This method takes a space-separated String of numbers and converts them into an int[] array.
static int[] toDecimalArray(java.lang.String pDec)
          This method takes a number, a String with a decimal point somewhere, and converts it into an int[] array.
static int[] toDigitArray(int pNum)
          This method takes an int and turns it into an int array.
static java.lang.String toWords(long pVal)
          Convert a long into words.
static java.lang.String toWords(java.lang.String pNumber)
          Convert a String containing a number into words.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Arithmetic

public Arithmetic()
Constructor provided to generate instances for scripting apps.

Method Detail

getPlaceValue

public static java.lang.String getPlaceValue(int pIndex,
                                             boolean pSuffix,
                                             boolean pPlural)
Retrieve a place value up to hundred quadrillion. Outside that range the value '10^{pIndex} is returned. The place value is interpreted as a power of ten. If the index is negative it is a fractional place, if positive, whole. If desired, the proper suffix ('-s' or '-ths') can be appended to the place value.

Parameters:
pIndex - The exponent of the place value to be returned.
pSuffix - true to include the suffix, false otherwise.
pPlural - true to pluralize the suffix, false to leave it singular.
Returns:
The name of the place value associates with the given index.

getPlaceValue

public static java.lang.String getPlaceValue(int pIndex,
                                             boolean pSuffix)
Convenience method for getPlaceValue(pIndex, pSuffix, true).


toWords

public static java.lang.String toWords(long pVal)
Convert a long into words. Accurate to the extent of type long.


toWords

public static java.lang.String toWords(java.lang.String pNumber)

Convert a String containing a number into words. Decimal points are allowed here! If the String starts with a digit, the whole part will be stated even if it is zero. If the String starts with a decimal point, only the decimal part will be stated. If the number contains no decimal point there will be no fractional part stated. Any conversion errors are reported at Debug level and the return value is 'zero'. If pNumber contains more than one decimal point, the second point and everything afterward is ignored.

Parameters:
pNumber - The String containing the number to 'speak.' If null or blank, 'zero' is returned.
Returns:
The words representing the number given.

createNumber

public static java.lang.String createNumber(java.lang.String pFormat)

Generate a number digit-wise per a special format String. The position of a formatting character is the position in which that rule will be applied. The format characters are:

Characters other than the format characters are copied verbatim, thus allowing dollar amounts or decimals to be generated in-place. To include a format character, concatenate a String around it! If pFormat is null or empty it is returned unaltered.

Parameters:
pFormat - The String containing one or more formatting characters.
Returns:
A String containing the specified number.

toDigitArray

public static int[] toDigitArray(int pNum)
This method takes an int and turns it into an int array. Element zero is the digit in the ones place, element 1 is the tens, etc.

Parameters:
pNum - The int to split into a digit array.
Returns:
An int array consisting of pNum's digits, starting with the ones at element 0.

splint

public static int[] splint(java.lang.String pData,
                           boolean pDigitArray,
                           boolean pDecimalArray)

This method takes a space-separated String of numbers and converts them into an int[] array. If pDigitArray is true ALL numbers are modded down to single digits. If pDecimalArray is true the modding only occurs from element 1 up. If both are true, pDigitArray takes precedence. If an error occurs parsing one of the numbers it becomes zero. If pData is null or empty the zero array is returned. Parsing errors are reported at Debug level.

NOTE: If neither flag is set the String is split, parsed as int, and returned unaltered.

Parameters:
pData - A space-separated String of ints to break into an array.
pDigitArray - true to parse single digits only, false to leave them alone.
pDecimalArray - true to parse single digits starting at element 1.

fromDigitArray

public static long fromDigitArray(int[] pAry)
This method takes a digit (int[]) array and converts it to an integer type (long). All values are made positive and modded by 10 to ensure validity of the resulting number.

Parameters:
pAry - The digit array to convert. This is ENFORCED!
Returns:
The number made up by the digit array.

daToString

public static java.lang.String daToString(int[] pDigits)
This method turns a digit array into a String. No other formatting is applied.


fromDecimalArray

public static java.lang.String fromDecimalArray(int[] pDecArr)
Convert a decimal array to a String. The decimal point is inserted between elements 0 and 1. If the array is null or empty, '0.0' is returned. If it contains only one element, it is returned as a String. NOTE: Digits from position 1 up are modded by 10 to ensure that they are single digits.


toDecimalArray

public static int[] toDecimalArray(java.lang.String pDec)

This method takes a number, a String with a decimal point somewhere, and converts it into an int[] array. The index of each element indicates its fractional place value. Element 0 is the whole part, element 1 is tenths, element two is hundredths, etc. If the element does not contain a decimal part the entire thing is assigned to element zero.

If the conversion chokes on a position that digit becomes zero and the rest of the String is still parsed. If pDec is null or empty the zero array, '{0}', is returned. Parsing errors are reported at the DEBUG level. If the number contains more than one decimal point, whatever precedes the first (even nothing!) becomes the whole part and whatever lies between the first and second points becomes the decimal part.

Parameters:
pDec - A String containing a decimal point somewhere.
Returns:
A decimal array with the whole part in element 0 and moving up in index (down in place value) from there.

round

public static int[] round(int[] pData,
                          int pPlace,
                          boolean pDecArray)
This method takes a decimal or digit array and rounds to the specified place. If the specified rounding place is outside the array (or equal to its length), the array is returned unchanged. If the data array is null or length zero, the zero array is returned. If pData has only one element, it is returned. if pPlace is zero, decimal arrays are rounded to the nearest whole number and digit arrays are returned unaltered.

Parameters:
pData - The int[] array to be rounded.
pPlace - The place value to round to. If negative, it is made positive.
pDecArray - true for a decimal array, false for a digit array.
Returns:
The properly rounded and truncated array.

pad

public static int[] pad(int[] pAry,
                        int pLength,
                        int pPad)
This method takes an int[] array and extends it to the specified length, filling in any extra values with the padding constant. If the supplied array is equal to or longer than the one sent in no padding occurs. If pAry is null it is returned and no new array is created, otherwise the new array will be a copy.

Parameters:
pAry - The array to pad to the given length.
pLength - The minimum length of the returned array.
pPad - The pad value to use for any extended elements.

pad

public static double[] pad(double[] pAry,
                           int pLength,
                           double pPad)
This method is identical to pad(int[], int, int) except that it works on double arrays.

Parameters:
pAry - The double array to be padded.
pLength - The minimum length of the returned array.
pPad - The padding constant.

getPerson

public static java.lang.String[] getPerson()
Pick a random name and gender-appropriate pronouns. The String[] array returned has nine elements: [0] is the name, [1] is 'his/her,' [2] is 'him/her,' [3] is 'he/she,' and [4] is 'his/hers.' Elements [5] through [8] exactly mirror [1] through [4] but the words are capitalized.


newNumberFormat

public static java.text.NumberFormat newNumberFormat()
At times, a number needs formatting. This method returns a plain instance of java.text.NumberFormat for just such occasions. Its rounding mode is automatically set to HALF_UP.


fix

public static java.lang.String fix(double pNumber,
                                   int pPlace,
                                   boolean pGroup)
Sometimes a floating-point number needs to have its number of decimal places fixed. This method does that and returns the number as a String. If pPlace is less than zero the number is returned unaltered. If zero, zero places are fixed. Grouping may be used or not; pPlace must be zero or more or the number will not be formatted at all.

Parameters:
pNumber - The number to be rounded.
pPlace - The number of decimal places to allow.
pGroup - Flag passed to NumberFormat.setGroupingUsed().

gcf

public static int gcf(int pL,
                      int pR)
Calculate the Greatest Common Factor of the numbers given. If either is negative it is made positive before calculation. If either value is 0, 1 is returned.


lcm

public static int lcm(int pL,
                      int pR)
Find the Least Common Multiple of the given numbers. If either is negative it is made positive. If either is zero, zero is returned.


indivisible

public static int indivisible(int pLow,
                              int pHigh,
                              int pDivisor)
Find a number not divisible by a given divisor from a range of candidates. Returns 1 if none of the numbers are indivisible or if the divisor is 1, -1 or 0. If pHigh is less than or equal to pLow the method returns 1 immediately. If more than one indivisible value exists within the range, one is picked randomly. Regardless or the range values, zero will never be returned.

Parameters:
pLow - The low value from the candidate range. Included. Must be less than 'pHigh'.
pHigh - The high value from the candidate range. Excluded.
pDivisor - The number that does NOT divide the one selected.
Returns:
A number from [pLow, pHigh) that is NOT divisible by pDivisor or 1 if one cannot be found.

coprime

public static int coprime(int pLow,
                          int pHigh,
                          int pCoprime)
Pick a number from a range that has no common factors with the given number greater than 1. If no such value exists, if the low value is greater than or equal to the high value or if the given number is -1, 0 or 1, the method returns 1 immediately.

Parameters:
pLow - The low value from the candidate range. Included. Must be less than 'pHigh'.
pHigh - The high value from the candidate range. Excluded.
pCoprime - The number that has no common factors with the one selected.
Returns:
A number from [pLow, pHigh) that is relatively prime to pCoprime or 1 if one cannot be found.

getSCROB

public Arithmetic_SCROB getSCROB()
Return a SCROB instance of this class.