cox.jmatt.java.MathTools
Class MFraction

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

public final class MFraction
extends java.lang.Object

This class encapsulates the behavior and manipulation of fractions. It provides static and instance methods to create, add, subtract, multiply, divide, raise, and reduce fractions. It also provides a rich capability to format these fractions many ways. The createMFraction() method can take a fraction in a commonly-typed format, e.g. '-2 4/9', and create an MFraction from it. From there it can be easily manipulated.

Once created, an MFraction is immutable. The only things that change it are methods that do not change the value of the underlying fraction. The raise() and reduce() methods, for instance, multiply or divide both the numerator and denominator by the same (non-zero!) quantity. This may change the appearance of the fraction but it does not change the fraction itself.

Internally the fraction is maintained as a sign multiplier, a numerator, and a denominator. There are methods to test whether the fraction is proper or improper, and methods to produce the numbers needed to format as mixed numbers or improper fractions. MFraction's versatile format() methods allow access to all of these values, raw or 'cooked.'


Field Summary
static java.lang.String DEFAULT_FRACTION_BAR
          Default fraction bar symbol: a single slash ('/').
static java.lang.String FORMAT_DEBUG
          Dump ALL replacement tokens.
static java.lang.String FORMAT_LATEX
          LaTeX fraction, (signed) numerator over denominator.
static java.lang.String FORMAT_LATEX_MIXED
          LaTeX mixed fraction.
static java.lang.String FORMAT_LATEX_TYPICAL
          Typical LaTeX format.
static java.lang.String FORMAT_MATHML
          MathML presentation standard 'mfrac' tag with just the numerator() and denominator() present.
static java.lang.String FORMAT_MATHML_MIXED
          MathML mixed number with explicit whole part and fractional numerator.
static java.lang.String FORMAT_MATHML_TYPICAL
          Typical format for MathML.
static java.lang.String FORMAT_OO_MIXED
          OpenOffice fraction, per STANDARD_MIXED.
static java.lang.String FORMAT_OO_STANDARD
          OpenOffice fraction format, per STANDARD with (plain) numerator and denominator.
static java.lang.String FORMAT_OO_TYPICAL
          Typical format for OpenOffice.
static java.lang.String FORMAT_STANDARD
          Standard (default) format for a fraction: <0>/<1>.
static java.lang.String FORMAT_STANDARD_MIXED
          Standard mixed format: <4> <5>/<1>.
static java.lang.String FORMAT_TYPICAL
          Typical format: mixed if improper, single number if whole or unit, proper if proper.
 
Constructor Summary
MFraction()
          Zero-argument constructor.
MFraction(int pNumerator, int pDenominator)
          Standard constructor: numerator and denominator specified.
MFraction(int pWhole, int pNumerator, int pDenominator)
          Mixed-number constructor: whole part, numerator and denominator.
MFraction(MFraction pMFraction)
          Copy constructor.
MFraction(java.lang.String pFraction)
          Constructor for a String containing a single-line-formatted fraction or mixed number.
 
Method Summary
 int absNumerator()
          Return the unsigned (absolute) value of the numerator.
 MFraction add(MFraction pFrac)
          Add this MFraction to another.
 int compareTo(MFraction pMFrac)
          Compare this MFraction to another.
static MFraction createDyadic(int pDen)
          Create a random MFraction whose denominator is 2pDen and whose numerator is an odd number between 1 and one less than the denominator.
static MFraction createIrreducible(int pWhole, int pLow, int pHigh, int pDenom)
          Create a fraction that cannot be reduced.
static MFraction createMFraction(int pWhole, int pNum, int pDen)
          Create a MFraction given the whole part, numerator and denominator as type int.
static MFraction createMFraction(java.lang.String pFraction)
          Parse a typically-formatted String into an MFraction.
 int denominator()
          Get the fraction's denominator.
 MFraction divide(MFraction pFrac)
          Divide this fraction by another MFraction.
 boolean equals(MFraction pMFrac)
          Test for equality between this MFraction and another.
 java.lang.String format_MFraction(MFraction pFraction, java.lang.String pFormat)
          Instance version of formatMFraction().
 java.lang.String format()
          Format this per its current furmat.
 java.lang.String format(java.lang.String pFormat)
          Format this MFraction per the supplied format.
static java.lang.String formatMFraction(MFraction pFraction, java.lang.String pFormat)
          Format an MFraction according to the specified format string.
 java.lang.String getBar()
          Return the current bar value, just in case it's needed.
 boolean isImproper()
          Return true if the numerator is (strictly!) greater than the denominator.
 boolean isProper()
          Return true if the numerator is (strictly) less than the denominator.
 boolean isUnit()
          Return true if the numerator equals the denominator.
 boolean isWhole()
          Return true if the numerator is evenly divisible by the denominator.
 int mixedNumerator()
          Return the NUMERATOR of the fractional part of this fraction expressed as a mixed number.
 MFraction multiply(MFraction pFrac)
          Multiply this MFraction by another.
 MFraction newDyadic(int pDen)
          Instance version of createDyadic().
 MFraction newIrreducible(int pWhole, int pLow, int pHigh, int pDenom)
          Instance shadow for an irreducible fraction.
 MFraction newMFraction(int pWhole, int pNum, int pDen)
          Instance version of createMFraction(int, int, int).
 MFraction newMFraction(java.lang.String pFraction)
          Instance version of createMFraction().
 MFraction normalize()
          This method takes care of the MFraction's signs.
 int numerator()
          Get the fraction's numerator.
 MFraction raise(int pNum)
          Multiply the numerator and denominator by the same constant.
 MFraction reciprocal()
          Create and return the reciprocal of this fraction if it exists.
 MFraction reduce()
          Reduce completely.
 MFraction reduce(int pNum)
          Reduce the fraction by pNum.
 java.lang.String sCompareTo(MFraction pRHFrac)
          Compare per compareTo() but returns '<,' '=' or '>' instead of a number.
 void setBar(java.lang.String pBar)
          Set the fraction bar String for this instance.
static void setDefaultBar(java.lang.String pBar)
          Set the String used for the default fraction bar.
static void setDefaultFormat(java.lang.String pFormat)
          Set the default format for all MFractions created after this is set.
 MFraction setFormat(java.lang.String pFormat)
          Set the format for this MFraction.
 void setNewDefaultBar(java.lang.String pBar)
          Instance default bar set method.
 void setNewDefaultFormat(java.lang.String pFormat)
          Instance alias for setDefaultFormat().
 int signum()
          Return 1 if the fraction is positive, 0 if it is zero, and -1 if it is negative.
 MFraction subtract(MFraction pFrac)
          Subtract another fraction from this one.
 double toDouble()
          Return the double value of this MFraction.
 java.lang.String toString()
          Return a constructor-like representation of this MFraction.
 java.lang.String toXML(java.lang.String pID)
          Return a simple XML format for this MFraction.
 int wholePart()
          Return the whole part of the fraction expressed as a mixed number.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

DEFAULT_FRACTION_BAR

public static final java.lang.String DEFAULT_FRACTION_BAR
Default fraction bar symbol: a single slash ('/').

See Also:
Constant Field Values

FORMAT_STANDARD

public static final java.lang.String FORMAT_STANDARD
Standard (default) format for a fraction: <0>/<1>.

See Also:
Constant Field Values

FORMAT_STANDARD_MIXED

public static final java.lang.String FORMAT_STANDARD_MIXED
Standard mixed format: <4> <5>/<1>.

See Also:
Constant Field Values

FORMAT_TYPICAL

public static final java.lang.String FORMAT_TYPICAL
Typical format: mixed if improper, single number if whole or unit, proper if proper. The bar used is the one currently set.

See Also:
Constant Field Values

FORMAT_OO_STANDARD

public static final java.lang.String FORMAT_OO_STANDARD
OpenOffice fraction format, per STANDARD with (plain) numerator and denominator.

See Also:
Constant Field Values

FORMAT_OO_MIXED

public static final java.lang.String FORMAT_OO_MIXED
OpenOffice fraction, per STANDARD_MIXED.

See Also:
Constant Field Values

FORMAT_OO_TYPICAL

public static final java.lang.String FORMAT_OO_TYPICAL
Typical format for OpenOffice. CRITICAL NOTE: For this format to work the 'bar' value must be set to 'over'.

See Also:
Constant Field Values

FORMAT_MATHML

public static final java.lang.String FORMAT_MATHML
MathML presentation standard 'mfrac' tag with just the numerator() and denominator() present.

See Also:
Constant Field Values

FORMAT_MATHML_MIXED

public static final java.lang.String FORMAT_MATHML_MIXED
MathML mixed number with explicit whole part and fractional numerator. (Uses mrow and mfrac.)

See Also:
Constant Field Values

FORMAT_MATHML_TYPICAL

public static final java.lang.String FORMAT_MATHML_TYPICAL
Typical format for MathML. No requirements for the 'bar' value.

See Also:
Constant Field Values

FORMAT_LATEX

public static final java.lang.String FORMAT_LATEX
LaTeX fraction, (signed) numerator over denominator.

See Also:
Constant Field Values

FORMAT_LATEX_MIXED

public static final java.lang.String FORMAT_LATEX_MIXED
LaTeX mixed fraction. Implicit whole part, mixed numerator over denominator.

See Also:
Constant Field Values

FORMAT_LATEX_TYPICAL

public static final java.lang.String FORMAT_LATEX_TYPICAL
Typical LaTeX format. No bar requirements.

See Also:
Constant Field Values

FORMAT_DEBUG

public static final java.lang.String FORMAT_DEBUG
Dump ALL replacement tokens. Not intended for production use.

See Also:
Constant Field Values
Constructor Detail

MFraction

public MFraction()
Zero-argument constructor. Gives the zero fraction: 0/1.


MFraction

public MFraction(int pNumerator,
                 int pDenominator)
Standard constructor: numerator and denominator specified. If the denominator is zero, an ArithmeticException is thrown.

Parameters:
pNumerator - The numerator of the fraction.
pDenominator - The denominator of the fraction.
Throws:
java.lang.ArithmeticException - if the denominator is zero. NOT ALLOWED!

MFraction

public MFraction(int pWhole,
                 int pNumerator,
                 int pDenominator)
Mixed-number constructor: whole part, numerator and denominator. Can throw an ArithmeticException on a zero denominator!

Parameters:
pWhole - The whole part of the mixed number.
pNumerator - The numerator of the fractional part.
pDenominator - The denominator of the fractional part.
Throws:
java.lang.ArithmeticException - if the denominator is zero.

MFraction

public MFraction(java.lang.String pFraction)
Constructor for a String containing a single-line-formatted fraction or mixed number. See MFraction.createMFraction() for details. If the denominator is zero an ArithmeticException is thrown but if the String is invalid the zero fraction is returned.

Throws:
java.lang.ArithmeticException - if the denominator is zero.

MFraction

public MFraction(MFraction pMFraction)
Copy constructor.

Throws:
java.lang.NullPointerException - if pMFraction is null.
Method Detail

createMFraction

public static final MFraction createMFraction(java.lang.String pFraction)

Parse a typically-formatted String into an MFraction. A typically-formatted String is a string containing the typical typewriter or keyboard formats of fractionnal notation: '4/9' or '3 1/5'. Because of the way this method parses a String, the space delimiter will work in both places. For instance, '3 1/5' could also be 3 1 5'. Slashes also work in both places.

If an error occurs during parsing it is reported at Error level and the zero fraciton is returned. That is, this method guarantees a valid MFraction, just not necessarily the one in the String.

Parameters:
pFraction - A String consisting of a single-line representation of a fraction, e.g. '3/8 or -12 5/7'.
Returns:
A valid MFraction. Either the one specified, or, if an error occurs, the fraction '0/1'.

newMFraction

public MFraction newMFraction(java.lang.String pFraction)
Instance version of createMFraction().


createMFraction

public static MFraction createMFraction(int pWhole,
                                        int pNum,
                                        int pDen)
Create a MFraction given the whole part, numerator and denominator as type int. Any errors are reported at Error level and the return is '0/1'.

Parameters:
pWhole - The whole part of the fraction. May be zero.
pNum - The numerator of the fraction. May be zero.
pDen - The denominator of the fraction. MUST NOT BE ZERO!!!

newMFraction

public MFraction newMFraction(int pWhole,
                              int pNum,
                              int pDen)
Instance version of createMFraction(int, int, int).


createDyadic

public static MFraction createDyadic(int pDen)
Create a random MFraction whose denominator is 2pDen and whose numerator is an odd number between 1 and one less than the denominator. If 'pDen' is zero the zero fraction is returned. If it is '1' the fraction is '1/2'. If 'pDen' is negative the zero fraction is returned.

Parameters:
pDen - The power of two for the denominator.

newDyadic

public MFraction newDyadic(int pDen)
Instance version of createDyadic().


createIrreducible

public static MFraction createIrreducible(int pWhole,
                                          int pLow,
                                          int pHigh,
                                          int pDenom)
Create a fraction that cannot be reduced. This uses the Arithmetic.coprime() method to generate the numerator so all range and return rules apply. Note: the range/divisor parameters here are in the same order as the 'coprime()' method.

Parameters:
pWhole - The whole part of the fraction.
pDenom - The denominator of the fraction.
pLow - The low value for the numerator range, inclusive.
pHigh - The high value for the numerator range, exclusive.

newIrreducible

public MFraction newIrreducible(int pWhole,
                                int pLow,
                                int pHigh,
                                int pDenom)
Instance shadow for an irreducible fraction.


formatMFraction

public static java.lang.String formatMFraction(MFraction pFraction,
                                               java.lang.String pFormat)
Format an MFraction according to the specified format string. It is a Question.fillTemplate() String with the following tokens supplied to the data array:

If something goes horribly wrong the String '0/1' is returned.


format_MFraction

public java.lang.String format_MFraction(MFraction pFraction,
                                         java.lang.String pFormat)
Instance version of formatMFraction().


setDefaultFormat

public static void setDefaultFormat(java.lang.String pFormat)
Set the default format for all MFractions created after this is set. If pFormat is null or blank, FORMAT_STANDARD is set.


setNewDefaultFormat

public void setNewDefaultFormat(java.lang.String pFormat)
Instance alias for setDefaultFormat().


setFormat

public MFraction setFormat(java.lang.String pFormat)
Set the format for this MFraction. If pFormat is null or empty it is set to the current default format. Returns a reference to this to allow method chaining.


setDefaultBar

public static void setDefaultBar(java.lang.String pBar)
Set the String used for the default fraction bar. If null or blank DEFAULT_FRACTION_BAR is set.


setNewDefaultBar

public void setNewDefaultBar(java.lang.String pBar)
Instance default bar set method.


setBar

public void setBar(java.lang.String pBar)
Set the fraction bar String for this instance. If 'pBar' is null or blank the current default is set.


getBar

public java.lang.String getBar()
Return the current bar value, just in case it's needed.


format

public java.lang.String format(java.lang.String pFormat)
Format this MFraction per the supplied format. If it is blank or null the currently-set format is used.


format

public java.lang.String format()
Format this per its current furmat.


normalize

public MFraction normalize()
This method takes care of the MFraction's signs. Ordinarily, if the fraction is negative the numerator should receive the sign. This method makes sure that happens. Most methods that might alter things call this one automatically, but it never hurts to do it manually, too. A reference to this MFraction is returned.


signum

public int signum()
Return 1 if the fraction is positive, 0 if it is zero, and -1 if it is negative.


numerator

public int numerator()
Get the fraction's numerator. If the fraction is negative, this value is negative.


denominator

public int denominator()
Get the fraction's denominator.


isImproper

public boolean isImproper()
Return true if the numerator is (strictly!) greater than the denominator.


isWhole

public boolean isWhole()
Return true if the numerator is evenly divisible by the denominator.


isUnit

public boolean isUnit()
Return true if the numerator equals the denominator.


isProper

public boolean isProper()
Return true if the numerator is (strictly) less than the denominator.


wholePart

public int wholePart()
Return the whole part of the fraction expressed as a mixed number. If it is nonzero the whole part will have the sign.


mixedNumerator

public int mixedNumerator()
Return the NUMERATOR of the fractional part of this fraction expressed as a mixed number. If the fraction is proper this is the same as numerator(), i.e. it does have the sign. If the fraction is improper it returns the integer remainder of (unsigned) numerator / denominator.


absNumerator

public int absNumerator()
Return the unsigned (absolute) value of the numerator. Regardless of the fraction's sign, this value is guaranteed non-negative.


toDouble

public double toDouble()
Return the double value of this MFraction.


toString

public java.lang.String toString()
Return a constructor-like representation of this MFraction.

Overrides:
toString in class java.lang.Object

equals

public boolean equals(MFraction pMFrac)
Test for equality between this MFraction and another. This is the proper equality test: A/B = C/D iff AD = BC.

Throws:
java.lang.NullPointerException - if pMFrac is null.

compareTo

public int compareTo(MFraction pMFrac)
Compare this MFraction to another. The result is -1 if this fraction is less, 0 if they are equal, and 1 if this is greater.

Throws:
java.lang.NullPointerException - if pMFrac is null.

sCompareTo

public java.lang.String sCompareTo(MFraction pRHFrac)
Compare per compareTo() but returns '<,' '=' or '>' instead of a number. If pRHFrac is null the return is '*ERROR*.'


add

public MFraction add(MFraction pFrac)
Add this MFraction to another. Neither fraction is changed, a new one is created. If pFrac is null, this fraction is returned.


subtract

public MFraction subtract(MFraction pFrac)
Subtract another fraction from this one. Neither fraction is changed, a new one is created. If pFrac is null a reference to this is returned.


multiply

public MFraction multiply(MFraction pFrac)
Multiply this MFraction by another. Neither is changed, a new one is created. If pFrac is null, this fraction is returned.


divide

public MFraction divide(MFraction pFrac)
Divide this fraction by another MFraction. A new MFraction is creaed. If pFrac is null a reference to this is returned. If pFrac is zero an ArithmeticException is thrown.

Throws:
java.lang.ArithmeticException - if pFrac is zero.

reciprocal

public MFraction reciprocal()
Create and return the reciprocal of this fraction if it exists. If the (current) numerator is zero an ArithmeticException is thrown.

Throws:
java.lang.ArithmeticException - if the reciprocal would have a zero denominator.

raise

public MFraction raise(int pNum)
Multiply the numerator and denominator by the same constant. If pNum is zero, this is returned. If pNum is not zero, a new fraction is created.


reduce

public MFraction reduce(int pNum)
Reduce the fraction by pNum. If pNum is zero or does not evenly divide both the numerator and denominator, this is returned. Otherwise, a new MFraction is created.


reduce

public MFraction reduce()
Reduce completely. The numerator and denominator are divided by their GCF.


toXML

public java.lang.String toXML(java.lang.String pID)
Return a simple XML format for this MFraction. It consists of an empty MFraction tag with the attributes 'numerator=' and 'denominator='. If pID is not null or empty it becomes an 'id=' attribute.

Parameters:
pID - The id attribute on the resulting tag. If null or empty no 'id' attribute is set.