type.lib
Class Fraction

java.lang.Object
  extended by type.lib.Fraction
All Implemented Interfaces:
java.io.Serializable, java.lang.Comparable<Fraction>
Direct Known Subclasses:
MixedNumber

public class Fraction
extends java.lang.Object
implements java.io.Serializable, java.lang.Comparable<Fraction>

This class encapsulates a fraction. It maintains the fraction's state (numerator and denominator) and provides functionality for manipulating fractions. The class ensures that the denominators of all its instances are non-negative at all times by transferring any negative denominator sign to the numerator. Furthermore, the fraction is kept in reduced form at all times, i.e. with no common divisor greater than 1. A Fraction instance can have a zero denominator either upon creation or after an operation. Such an instance is treated like any other (it can, for example, participate in the operations supported by the class without leading to exceptions) except for two differences:

  1. When invoked on such an instance, the toString method returns the literal NaF, which stands for "Not a Fraction".
  2. All such instances are considered equal (regardless of their numerator values) and greater than any non-zero denominator fraction. This affects the contracts of compareTo and equals.
For pedagogical reasons, certain attributes were made public to demonstrate the negative consequences of violating design guidelines. These anomalies are noted where applicable (see also the FractionNS class).

Version:
7.1 - Summer 2011
Author:
H. Roumani, roumani@cse.yorku.ca
See Also:
Serialized Form

Field Summary
static boolean isQuoted
          A flag that determines if the return of the toProperString() method is surrounded by quotes or not.
protected static java.util.Random rng
          The random number generator used by the getRandom() method.
 char separator
          A character that separates the numerator denominator pair in the return of the toString() method.
 
Constructor Summary
Fraction()
          Construct a default fraction with numerator equal to 0, denominator equal to 1, and separator equal to '/'.
Fraction(Fraction fraction)
          Construct a copy of the passed Fraction.
Fraction(long numerator, long denominator)
          Construct a fraction with the passed numerator and denominator and a '/' separator.
Fraction(long numerator, long denominator, char separator)
          Construct a fraction with the passed numerator, denominator, and separator.
 
Method Summary
 void add(Fraction other)
          Add the passed fraction to the fraction on which it was called.
 Fraction cloneMe()
          Copy the state of this object.
 int compareTo(Fraction other)
          Compare this object with the specified object for order.
 void divide(Fraction other)
          Divide the fraction on which the method was called by the passed fraction.
 boolean equals(java.lang.Object other)
          Determine if this fraction is the same as the passed one.
 long getDenominator()
          An accessor to the denominator of this fraction.
 long getNumerator()
          An accessor to the numerator of this fraction.
static Fraction getRandom()
          Create a random fraction.
 char getSeparator()
          An accessor to the separator of this fraction.
 int hashCode()
          Compute a hash code for this Fraction.
 void multiply(Fraction other)
          Multiply the fraction on which the method was called by the passed fraction.
 void pow(int exponent)
          Raise the fraction on which the method was called to the passed exponent.
 boolean resembles(Fraction other)
          Determine if this fraction resembles the passed one.
 void setDenominator(long denominator)
          A mutator for the denominator of this fraction.
 void setFraction(Fraction other)
          A mutator for this fraction.
 void setFraction(long numerator, long denominator)
          A mutator for this fraction.
 void setNumerator(long numerator)
          A mutator of the numerator of this fraction.
static void setSeed(long seed)
          Change the seed of the random sequence returned by getRandom().
 boolean setSeparator(char newSeparator)
          A mutator of the separator of this fraction.
 void subtract(Fraction other)
          Subtract the passed fraction from the fraction on which it was called.
 java.lang.String toProperString()
          Return this fraction as a proper fraction.
 java.lang.String toString()
          Return a string representation of this fraction.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

separator

public char separator
A character that separates the numerator denominator pair in the return of the toString() method. The default value is '/'.

(Bad design--should have been kept private. Access would have still been possible via the existing public accessor and mutator.)


isQuoted

public static boolean isQuoted
A flag that determines if the return of the toProperString() method is surrounded by quotes or not. The default value is true.

(Bad design--should have been kept private. Access would have still been possible via a public static accessor, e.g. isQuoted() and a public static mutator, e.g. setIsQuoted(boolean).)


rng

protected static java.util.Random rng
The random number generator used by the getRandom() method.

Constructor Detail

Fraction

public Fraction()
Construct a default fraction with numerator equal to 0, denominator equal to 1, and separator equal to '/'. The rational value of the constructed fraction is, thus, zero.


Fraction

public Fraction(long numerator,
                long denominator)
Construct a fraction with the passed numerator and denominator and a '/' separator. If the passed denominator is negative, the sign of the numerator is reversed in order to keep the denominator positive.

Parameters:
numerator - the numerator of the fraction to construct.
denominator - the denominator of the fraction to construct.

Fraction

public Fraction(Fraction fraction)
Construct a copy of the passed Fraction.

Parameters:
fraction - the Fraction to copy.
Throws:
java.lang.RuntimeException - if fraction = null

Fraction

public Fraction(long numerator,
                long denominator,
                char separator)
Construct a fraction with the passed numerator, denominator, and separator. If the passed denominator is negative, the sign of the numerator is reversed in order to keep the denominator positive, and if the passed separator is a letter or a digit, it is replaced with '/'.

Parameters:
numerator - the numerator of the fraction to construct.
denominator - the denominator of the fraction to construct.
separator - the separator of the fraction to construct.
Method Detail

add

public void add(Fraction other)
Add the passed fraction to the fraction on which it was called. This method is, in effect, a mutator because it changes the state of the encapsulated object.

Parameters:
other - the fraction to add to this fraction.

subtract

public void subtract(Fraction other)
Subtract the passed fraction from the fraction on which it was called. This method is, in effect, a mutator because it changes the state of the encapsulated object.

Parameters:
other - the fraction to subtract from this fraction.

multiply

public void multiply(Fraction other)
Multiply the fraction on which the method was called by the passed fraction. This method is, in effect, a mutator because it changes the state of the encapsulated object.

Parameters:
other - the fraction to multiply this fraction by

divide

public void divide(Fraction other)
Divide the fraction on which the method was called by the passed fraction. This method is, in effect, a mutator because it changes the state of the encapsulated object.

Parameters:
other - the fraction to divide this fraction by

pow

public void pow(int exponent)
Raise the fraction on which the method was called to the passed exponent. This method is, in effect, a mutator because it changes the state of the encapsulated object.

Parameters:
exponent - the exponent to raise this fraction to (must be non-negative).
Throws:
java.lang.RuntimeException - if the exponent is negative.

setNumerator

public void setNumerator(long numerator)
A mutator of the numerator of this fraction.

Parameters:
numerator - the new numerator.

getNumerator

public long getNumerator()
An accessor to the numerator of this fraction.

Returns:
the numerator of this fraction.

setDenominator

public void setDenominator(long denominator)
A mutator for the denominator of this fraction.

Parameters:
denominator - the new denominator.

getDenominator

public long getDenominator()
An accessor to the denominator of this fraction.

Returns:
the denominator of this fraction.

setFraction

public void setFraction(long numerator,
                        long denominator)
A mutator for this fraction.

Parameters:
numerator - the new numerator of the fraction.
denominator - the new denominator of the fraction.

setFraction

public void setFraction(Fraction other)
A mutator for this fraction.

Parameters:
other - the fraction whose numerator and denominator will become those of this fraction.

setSeparator

public boolean setSeparator(char newSeparator)
A mutator of the separator of this fraction. The separator must not be a letter or a digit.

Parameters:
newSeparator - the new separator.
Returns:
true if the change was made (i.e. if the passed parameter is neither a letter nor a digit), and return false otherwise.

getSeparator

public char getSeparator()
An accessor to the separator of this fraction.

Returns:
the separator of this fraction.

toString

public java.lang.String toString()
Return a string representation of this fraction. Note that the literal "NaF" (Not A Fraction) is returned if the denominator is zero to indicate that this is not a valid fraction.

Overrides:
toString in class java.lang.Object
Returns:
the numerator and denominator of this fraction separated by separator.

toProperString

public java.lang.String toProperString()
Return this fraction as a proper fraction. Note that the literal "NaF" (Not A Fraction) is returned if the denominator is zero to indicate that this is not a valid fraction.

Returns:
a string representation of of this fraction in the form:
w n/d
where w is a whole number and n < d. The n/d part and the space that precedes it are not present if the numerator of this fraction is divisible by its denominator. The return is surrounded by double quotes if isQuoted is true.

equals

public boolean equals(java.lang.Object other)
Determine if this fraction is the same as the passed one. Two fractions are considered equal if they have the same numerator and denominator (in reduced form).

Overrides:
equals in class java.lang.Object
Parameters:
other - a reference to the object to test equality with.
Returns:
true if other is not null and points to a fraction that is equal to this one. The return is false otherwise. Note that all zero-denominator fractions are considered equal.

hashCode

public int hashCode()
Compute a hash code for this Fraction.

Overrides:
hashCode in class java.lang.Object
Returns:
a hash code value for this object.

resembles

public boolean resembles(Fraction other)
Determine if this fraction resembles the passed one. Two fractions are said to resemble each other if they have a common denominator.

Parameters:
other - a reference to the object to test resemblance with.
Returns:
true if other is not null and does resemble this object. The return is false otherwise.

getRandom

public static Fraction getRandom()
Create a random fraction. The numerators and denominators of the created fractions are uniformly distributed in [0,1000) but no zero-denominator fraction is generated.

This method was added for pedagogical reasons.

Returns:
a randomly chosen fraction.

setSeed

public static void setSeed(long seed)
Change the seed of the random sequence returned by getRandom(). This method is meant to be used by a test harness so that the same sequence can be generated for the app being tested and its oracle.

Parameters:
seed - the initial seed for random number generator.

cloneMe

public Fraction cloneMe()
Copy the state of this object.

Returns:
a reference to a new Fraction object having exactly the same state as this one.

compareTo

public int compareTo(Fraction other)
Compare this object with the specified object for order. Return a negative integer, zero, or a positive integer if this object is less than, equal to, or greater than the specified object.

Specified by:
compareTo in interface java.lang.Comparable<Fraction>
Parameters:
other - the Object to compare to.
Returns:
-1 if this fraction is less than the passed one, +1 if it is greater, and 0 if they are equal. Note that all zero-denominator fractions are considered equal and greater than any other fraction.


Java by Abstraction: A Client-View Approach