com.rubecula.jquantity
Class NumberPresentation

java.lang.Object
  extended bycom.rubecula.util.Presentation
      extended bycom.rubecula.jquantity.NumberPresentation
All Implemented Interfaces:
Auditable, java.lang.Cloneable, FuzzyPresentable, Identifiable, Mutable

public class NumberPresentation
extends Presentation
implements Mutable, FuzzyPresentable

Public class used primarily for the output of instances of Rational.

// TODO Needs ordering and ensure conformance to conventions.

Since:
V_0_1
Version:
$Revision: 1.27 $
Author:
Robin Hillyard

Field Summary
private  boolean _Constant
           
(package private) static java.lang.String _PresentableClass
          This string defines the class which will be used to parse NumberPresentations.
private  IntegerPresentation _PresentationFirst
          The First part of the string, usually the integer or the numerator.
private  java.lang.String _StringExponent
          The exponent part of the string, including the "E" character or whatever.
private  java.lang.String _StringFuzzy
          The offset of the Fuzzy part of the string.
private  java.lang.String _StringRadix
          The Radix as a string, including the "#" character (or empty).
private  java.lang.String _StringSecond
          The Second part of the string (including the integer-fraction delimiter - usuall a "." in English speaking countries, or a "," in Franco-German countries); or the "/" separator between numerator and denominator.
private static char $DecimalChar
          Class field: integer/fraction delimiter.
(package private) static java.lang.String $DelimiterExponent
          The character which can initiate the exponent.
private static java.lang.String $DelimiterFuzzy
          The list of characters which can precede (or constitute) fuzzy info.
(package private) static char $DelimiterRadix
          The character which can initiate the radix.
(package private) static char $DelimiterRatio
          The character which can initiate the radix.
(package private) static java.lang.String $Delimiters
          The character which are valid delimiters in a number string.
static Presentation $E
          Value of E as a String.
private static java.lang.String $Ellipsis
          The character(s) which represent the fact that there are repeating zeroes at this point. // TODO Check this explanation.
private static Range $Exp
           
private static Range $Fuzzy
           
static Presentation $Pi
          Value of Pi as a String.
private static Range $Radix
           
static java.lang.String $S_E
           
static java.lang.String $S_PI
           
private static Range $Separator
           
private static Range $Sign
          The following index values must always correspond to the positions in the $Delimiters string above.
private static int RADIX_DECIMAL
          The default radix: value = 10.
 
Fields inherited from class com.rubecula.util.Presentation
_Appearance, $empty, $Stars
 
Constructor Summary
private NumberPresentation()
          Null constructor.
  NumberPresentation(double value, boolean normalize)
          Secondary Constructor to create a NumberPresentation for a double value which is considered to be exact.
  NumberPresentation(double value, int halfPlaces, boolean normalize)
          Secondary Constructor to create a NumberPresentation for a double value.
  NumberPresentation(IntegerPresentation first, java.lang.String second, java.lang.String exponent, java.lang.String fuzz, java.lang.String radix)
          Primary Constructor to create a NumberPresentation from a set of explicit values.
  NumberPresentation(NumberPresentation source)
          Constructor to copy a NumberPresentation.
  NumberPresentation(java.lang.String string)
          Secondary Constructor to create a NumberPresentation for any number from a string.
  NumberPresentation(java.lang.String first, java.lang.String second)
          Secondary Constructor to create a NumberPresentation for an exact non-integer value from a string.
  NumberPresentation(java.lang.String first, java.lang.String second, java.lang.String fuzz)
          Primary Constructor to create a NumberPresentation from a set of explicit values.
 
Method Summary
 java.lang.String audit(java.lang.String label)
          Method to return a detailed string from an arithmetical object for debugging purposes.
 java.lang.Object clone()
          Creates and returns a copy of this object.
(package private)  double doubleValue()
           
 AttrMap getAttributes()
          Return the attributes with which this presentation was created, or at least the best guess.
static char GetDecimalChar()
          Method to get the current integer/fraction delimiter character (the decimal "point").
(package private)  java.lang.String getExponent()
           
(package private)  int getExponentAsInt()
           
(package private)  IntegerPresentation getFirst()
           
(package private)  java.math.BigDecimal getFirstAsBigDecimal()
          Return the integer part of this object as a BigDecimal.
(package private)  java.math.BigInteger getFirstAsBigInteger()
           
(package private)  java.lang.String getFirstNet()
           
(package private)  java.lang.String getFuzzy()
           
 int getFuzzyAsInt()
          Method to figure the precision of this presentation.
 int getFuzzyAsModel()
          Method to get the error model defined by the fuzzy characters.
(package private)  java.lang.String getFuzzyDigits()
           
 int getFuzzyDigitsAsInt()
           
 java.lang.String getIdentifier()
          Method to get the specific identifier for an object.
 java.lang.String getPresentableClass()
          Method to get the name of the corresponding Presentable class for this Presentation.
(package private)  java.lang.String getRadix()
           
(package private)  int getRadixAsInt()
           
(package private)  java.lang.String getSecond()
           
(package private)  java.math.BigDecimal getSecondAsBigDecimal()
          Get the fractional or divisor part of this presentation as a BigDecimal number.
(package private)  java.lang.String getSecondNet()
           
(package private)  java.lang.String getSecondwFuzz()
           
(package private)  boolean getSignAsBoolean()
           
(package private)  boolean isInfinite()
          Method to determine if this presentation represents an infinite number.
 boolean isMutable()
          This method indicates whether this particular instance is mutable.
(package private) static boolean isNumeric(java.lang.String s)
           
(package private)  boolean isRatio()
           
(package private)  long longValue()
          Return this in the form of a long.
static void main(java.lang.String[] args)
          Main method for testing this class.
 void makeFuzzy(int model, double boundAbs)
          Mutating instance method to set the fuzzy string according to given model and bounds.
(package private) static int MinOffset(int x, int y)
          return the minimum "offset" defined by the two offsets x and y.
(package private) static java.lang.String ModelAsString(int model)
          Class method to yield a presentable string for a Fuzzy model.
private  void moveDecimalPoint(int rightWardPlaces)
          Method to adjust the value of the number and, correspondingly, the value of the exponent.
 int normalize()
          MUTATING Method to adjust the value of the number and, correspondingly, the value of the exponent.
protected  int normalize(int before)
          MUTATING Method to adjust the value of the number and, correspondingly, the value of the exponent.
private  Range rangeDecimalPoint()
          Method to test if the decimal point can be moved.
 Mutable setConstant()
          This method sets this instance to be a constant, i.e. immutable.
static void SetDecimalChar(char decimalChar)
          Method to set the integer/fraction delimiter character (the decimal "point").
(package private)  void setExponent(int exponent)
           
(package private)  void setExponent(java.lang.String exponent)
           
(package private)  void setFirst(IntegerPresentation first)
          Method to set the value of first as an IntegerPresentation.
(package private)  void setFirst(java.lang.String first)
          Method to set the first string.
protected  void setFuzzy(int halfPlaces)
          Method to set the fuzzy part of this according to the number of halfplaces of decimals specified and the string given.
protected  void setFuzzy(int halfPlaces, java.lang.String fuzzy)
          Method to set the fuzzy part of this according to the number of halfplaces of decimals specified and the string given.
(package private)  void setFuzzy(java.lang.String fuzzy)
           
private  void setRadix(java.lang.String radix)
           
(package private)  void setSecond(java.lang.String second)
           
protected  void setValue(java.lang.String source)
          Instance method to set the value of a NumberPresentation from a String.
 java.lang.String toString(int width)
          Render this Presentation as a String within the width specified.
private static NumberPresentation valueOf(java.lang.String string)
           
 
Methods inherited from class com.rubecula.util.Presentation
audit, audit, parse, toString, updateAppearance
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

$S_E

public static final java.lang.String $S_E
See Also:
Constant Field Values

$S_PI

public static final java.lang.String $S_PI
See Also:
Constant Field Values

$Sign

private static final Range $Sign
The following index values must always correspond to the positions in the $Delimiters string above. Furthermore, because of the order of static initialization of classes, these definitions must precede their first usage.


$Separator

private static final Range $Separator

$Fuzzy

private static final Range $Fuzzy

$Radix

private static final Range $Radix

$Exp

private static final Range $Exp

$Delimiters

static final java.lang.String $Delimiters
The character which are valid delimiters in a number string.
Do not change the order of characters in this string.

See Also:
Constant Field Values

$DelimiterRadix

static final char $DelimiterRadix
The character which can initiate the radix.


$DelimiterRatio

static final char $DelimiterRatio
The character which can initiate the radix.


$DelimiterExponent

static final java.lang.String $DelimiterExponent
The character which can initiate the exponent.


$DelimiterFuzzy

private static final java.lang.String $DelimiterFuzzy
The list of characters which can precede (or constitute) fuzzy info.


$Ellipsis

private static final java.lang.String $Ellipsis
The character(s) which represent the fact that there are repeating zeroes at this point. // TODO Check this explanation.

See Also:
Constant Field Values

$E

public static final Presentation $E
Value of E as a String.


$Pi

public static final Presentation $Pi
Value of Pi as a String.


_PresentableClass

static java.lang.String _PresentableClass
This string defines the class which will be used to parse NumberPresentations.


_Constant

private boolean _Constant

RADIX_DECIMAL

private static int RADIX_DECIMAL
The default radix: value = 10.


$DecimalChar

private static char $DecimalChar
Class field: integer/fraction delimiter. Defaults to ".".


_PresentationFirst

private IntegerPresentation _PresentationFirst
The First part of the string, usually the integer or the numerator.


_StringSecond

private java.lang.String _StringSecond
The Second part of the string (including the integer-fraction delimiter - usuall a "." in English speaking countries, or a "," in Franco-German countries); or the "/" separator between numerator and denominator. Maybe empty.


_StringFuzzy

private java.lang.String _StringFuzzy
The offset of the Fuzzy part of the string.


_StringRadix

private java.lang.String _StringRadix
The Radix as a string, including the "#" character (or empty).


_StringExponent

private java.lang.String _StringExponent
The exponent part of the string, including the "E" character or whatever. May be empty.

Constructor Detail

NumberPresentation

public NumberPresentation(IntegerPresentation first,
                          java.lang.String second,
                          java.lang.String exponent,
                          java.lang.String fuzz,
                          java.lang.String radix)
                   throws PresentationException
Primary Constructor to create a NumberPresentation from a set of explicit values.

Parameters:
first - the integer presentation which will form the base of the new instance (i.e. the sign, integer part, radix and exponent).
second - EITHER: the fractional part, starting with the decimal character (usually ".") OR: the denominator, starting with "/".
exponent - a string representing the exponent, for example "E-2".
fuzz - the fuzzy information of the form "*", "*n", or "(nn)".
radix - a string representing the radix, for example #8.
Throws:
PresentationException - in case of parsing error.

NumberPresentation

public NumberPresentation(java.lang.String first,
                          java.lang.String second,
                          java.lang.String fuzz)
                   throws PresentationException
Primary Constructor to create a NumberPresentation from a set of explicit values.

Parameters:
first - the integer presentation which will form the base of the new instance (i.e. the sign, integer part, radix and exponent).
second - EITHER: the fractional part, starting with the decimal character (usually ".") OR: the denominator, starting with "/".
fuzz - the fuzzy information of the form "*", "*n", or "(nn)".
Throws:
PresentationException - in case of parsing error.

NumberPresentation

public NumberPresentation(java.lang.String first,
                          java.lang.String second)
                   throws PresentationException
Secondary Constructor to create a NumberPresentation for an exact non-integer value from a string.

Parameters:
first - the integer presentation which will form the base of the new instance (i.e. the sign, integer part, radix and exponent).
second - the denominator or fractional part (including the initial separator).
Throws:
PresentationException - in case of parsing error.

NumberPresentation

public NumberPresentation(java.lang.String string)
                   throws PresentationException
Secondary Constructor to create a NumberPresentation for any number from a string.

Parameters:
string - the presentation which defines the new instance.
Throws:
PresentationException - in case of parsing error.

NumberPresentation

public NumberPresentation(double value,
                          int halfPlaces,
                          boolean normalize)
                   throws PresentationException
Secondary Constructor to create a NumberPresentation for a double value.

Parameters:
value - the double whose value we wish to present.
halfPlaces - twice the number of significant figures to which the presentation should be rounded.
normalize - true if the presentation should be normalized.
Throws:
PresentationException - in case of parsing error. // TODO when the halfPlaces is set to a critical number, Gaussian model values are not presented correctly (problem may not be in this module).

NumberPresentation

public NumberPresentation(double value,
                          boolean normalize)
                   throws PresentationException
Secondary Constructor to create a NumberPresentation for a double value which is considered to be exact.

Parameters:
value - the double whose value we wish to present.
normalize - true if the presentation should be normalized.
Throws:
PresentationException - in case of parsing error.

NumberPresentation

public NumberPresentation(NumberPresentation source)
                   throws PresentationException
Constructor to copy a NumberPresentation.

Parameters:
source - the fuzzy presentation which is to be copied.
Throws:
PresentationException - in case of parsing error.

NumberPresentation

private NumberPresentation()
Null constructor.

Method Detail

valueOf

private static NumberPresentation valueOf(java.lang.String string)

main

public static void main(java.lang.String[] args)
Main method for testing this class.

Parameters:
args - String[] : the command line options.

SetDecimalChar

public static void SetDecimalChar(char decimalChar)
Method to set the integer/fraction delimiter character (the decimal "point"). By default, it is set to '.' but can be changed to, e.g. ',' for German usage.

Parameters:
decimalChar - the character to be used to separate integers from fractional parts of a string.

GetDecimalChar

public static char GetDecimalChar()
Method to get the current integer/fraction delimiter character (the decimal "point"). By default, it is set to '.' but can be changed to, e.g. ',' for German usage.

Returns:
x the character being used to separate integers from fractional parts of a string.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException
Creates and returns a copy of this object.

Returns:
a clone of this instance.
Throws:
PresentationException - : NumberPresentation not Cloneable (should be impossible)
java.lang.CloneNotSupportedException - if superclass cannot clone.
See Also:
Cloneable

makeFuzzy

public void makeFuzzy(int model,
                      double boundAbs)
               throws PresentationException
Mutating instance method to set the fuzzy string according to given model and bounds. Whatever fuzzy value was set before is replaced.

Parameters:
model - the error model required.
boundAbs - the absolute bounds required.
Throws:
PresentationException - invalid model.

setValue

protected final void setValue(java.lang.String source)
                       throws PresentationException
Instance method to set the value of a NumberPresentation from a String.
Note that although this method is an Instance method, it acts like a Class method: the original value of this is completely irrelevant (and therefore should ideally by undefined).

Parameters:
source - the string representing all aspects of this value. The format of the string is: [-+] [0-9]* [[.] [0-9]*] ['*'|'['[0-9]*']'] ['#'[0-9]*] ['E'[0-9]*]
Throws:
PresentationException

getFuzzyAsInt

public int getFuzzyAsInt()
Method to figure the precision of this presentation.

Specified by:
getFuzzyAsInt in interface FuzzyPresentable
Returns:
the precision in half-places of fractional digits.

getFuzzyDigitsAsInt

public int getFuzzyDigitsAsInt()
Specified by:
getFuzzyDigitsAsInt in interface FuzzyPresentable
Returns:
the digits that make up the fuzzy part (net of the delimiters) (may be empty string, but will not be null).

getFuzzyAsModel

public int getFuzzyAsModel()
Method to get the error model defined by the fuzzy characters. In the case that the fuzzy characters are the ellipsis, the invalid model value is returned.

Specified by:
getFuzzyAsModel in interface FuzzyPresentable
Returns:
the fuzzy model, defined in Fuzzy, e.g. Fuzzy.$DistUniform.

setFuzzy

protected final void setFuzzy(int halfPlaces,
                              java.lang.String fuzzy)
                       throws PresentationException
Method to set the fuzzy part of this according to the number of halfplaces of decimals specified and the string given.

Parameters:
halfPlaces - the precision desired in terms of half-places of decimals.
fuzzy - the characters defining the fuzzy data.
Throws:
PresentationException

setFuzzy

protected final void setFuzzy(int halfPlaces)
                       throws PresentationException
Method to set the fuzzy part of this according to the number of halfplaces of decimals specified and the string given.

Parameters:
halfPlaces - the precision desired in terms of half-places of decimals.
Throws:
PresentationException - in case of parsing error.

rangeDecimalPoint

private Range rangeDecimalPoint()
Method to test if the decimal point can be moved.

Returns:
the Range of values through which the decimal point may be moved. // TODO is this really dependent on the fuzzy model?

moveDecimalPoint

private void moveDecimalPoint(int rightWardPlaces)
                       throws PresentationException
Method to adjust the value of the number and, correspondingly, the value of the exponent. The effective value of this remins unchanged by this operation.

Parameters:
rightWardPlaces - the number of places the decimal point is to be moved toward the right.; a negative number denotes that the point be moved by abs(rightWardPlaces) to the left.
Throws:
PresentationException - in case of parsing error.

normalize

protected int normalize(int before)
                 throws PresentationException
MUTATING Method to adjust the value of the number and, correspondingly, the value of the exponent. After the operation, there will be exactly before non-zero digits before the decimal character. The effective value of this remins unchanged by this operation.

Parameters:
before - the number of non-zero digits required to precede the decimal point character.
Returns:
the increment actually effected, ie. the number of places to move right in order to revert to the preexisting state.
Throws:
PresentationException - if not possible to normalize.

normalize

public int normalize()
              throws PresentationException
MUTATING Method to adjust the value of the number and, correspondingly, the value of the exponent. After the operation, there will be exactly one non-zero digit before the decimal point. The effective value of this remins unchanged by this operation.

Returns:
the increment actually effected, ie. the number of places to move right in order to revert to the preexisting state.
Throws:
PresentationException - if not possible to normalize.

getSecond

final java.lang.String getSecond()
Returns:
the String representing the fraction. In some cases, this string will refer directly to a substring of the original string. Result may be empty, but not null.

getSecondwFuzz

final java.lang.String getSecondwFuzz()
Returns:
the String representing the fraction together with fuzz. In some cases, this string will refer directly to a substring of the original string. In other cases, specifically when the fuzzy string is of the form nnn*m, the result will be the fraction concatenated with the fuzzy digit, if any. Result may be empty, but not null.

getSecondNet

final java.lang.String getSecondNet()
Returns:
the String representing the fraction/divisor, without the separator or any fuzzy information. Result may be empty, but not null.

getFuzzy

final java.lang.String getFuzzy()
Returns:
the String representing the fuzzy part, derived directly from the original string (may be empty).

getPresentableClass

public java.lang.String getPresentableClass()
Method to get the name of the corresponding Presentable class for this Presentation.

Specified by:
getPresentableClass in class Presentation
Returns:
_PresentableClass.

audit

public java.lang.String audit(java.lang.String label)
Method to return a detailed string from an arithmetical object for debugging purposes.

Specified by:
audit in interface Auditable
Parameters:
label - String: the label to associate with the data
Returns:
the detailed string.

getAttributes

public AttrMap getAttributes()
                      throws PresentationException
Return the attributes with which this presentation was created, or at least the best guess.

Specified by:
getAttributes in class Presentation
Returns:
a map of attributes used to render this Presentation. Currently returns an empty map.
Throws:
PresentationException

isMutable

public boolean isMutable()
This method indicates whether this particular instance is mutable.

Specified by:
isMutable in interface Mutable
Returns:
true.

setConstant

public Mutable setConstant()
Description copied from interface: Mutable
This method sets this instance to be a constant, i.e. immutable. Future calls to the isMutable() method will yield false.

Specified by:
setConstant in interface Mutable
Returns:
as a convenience this method returns itself.

toString

public java.lang.String toString(int width)
                          throws PresentationException
Render this Presentation as a String within the width specified.

Specified by:
toString in class Presentation
Parameters:
width - the max. number of characters within which to output the presentation.
Returns:
a representation (rendering) of this Presentation.
Throws:
PresentationException - negative width.

doubleValue

final double doubleValue()
Returns:
the value of the presentation as a double.

getFuzzyDigits

final java.lang.String getFuzzyDigits()
Returns:
the digits that make up the fuzzy part (net of the delimiters) (may be empty string, but will not be null).

getSecondAsBigDecimal

final java.math.BigDecimal getSecondAsBigDecimal()
Get the fractional or divisor part of this presentation as a BigDecimal number.

Returns:
the BigDecimal corresponding to #getSecond().

getFirstAsBigDecimal

final java.math.BigDecimal getFirstAsBigDecimal()
Return the integer part of this object as a BigDecimal.

Returns:
the BigDecimal equivalent of the integer part of this.

setFirst

final void setFirst(IntegerPresentation first)
Method to set the value of first as an IntegerPresentation.

Parameters:
first - the IntegerPresentation to be used for the first part of this presentation.

setFirst

final void setFirst(java.lang.String first)
             throws PresentationException
Method to set the first string. Any leading zeroes (after the sign, if any) will be stripped off before storing in _StringFirst.

Parameters:
first - the String representing the first part, either the integer part or the numerator.
Throws:
PresentationException - in case of parsing error.

setSecond

final void setSecond(java.lang.String second)
              throws PresentationException
Parameters:
second - the String representing the fraction part or denominator, including the separator. May be empty.
Throws:
PresentationException

setFuzzy

final void setFuzzy(java.lang.String fuzzy)
Parameters:
fuzzy - the String representing the fuzzy part (may be empty).

setRadix

private void setRadix(java.lang.String radix)
Parameters:
radix - the String representing the radix part (may be empty).

setExponent

final void setExponent(java.lang.String exponent)
Parameters:
exponent - the String representing the exponent part (may be empty).

setExponent

final void setExponent(int exponent)
Parameters:
exponent - an integer representing the exponent part.

getFirst

final IntegerPresentation getFirst()
Returns:
the IntegerPresentation representing the integer part, derived directly from the original string.

getFirstNet

final java.lang.String getFirstNet()
Returns:
the String representing the integer part, without any sign.

getRadix

final java.lang.String getRadix()
Returns:
the String representing the radix, derived directly from the original string (may be empty).

getExponent

final java.lang.String getExponent()
Returns:
the String representing the sign, derived directly from the original string (may be empty).

getIdentifier

public java.lang.String getIdentifier()
Method to get the specific identifier for an object.

Specified by:
getIdentifier in interface Identifiable
Returns:
"<" value ">"

ModelAsString

static java.lang.String ModelAsString(int model)
Class method to yield a presentable string for a Fuzzy model.

Parameters:
model - the model value (Fuzzy.$DistUniform, etc.).
Returns:
a string which represents the model.

isInfinite

final boolean isInfinite()
Method to determine if this presentation represents an infinite number.

Returns:
true if this is infinite.

isRatio

final boolean isRatio()

getSignAsBoolean

final boolean getSignAsBoolean()
Returns:
true if getSign() is not "-".

getFirstAsBigInteger

final java.math.BigInteger getFirstAsBigInteger()

getRadixAsInt

final int getRadixAsInt()
Returns:
the String representing the radix, derived directly from the original string (may be empty).

getExponentAsInt

final int getExponentAsInt()
Returns:
exponent as a decimal integer.

longValue

final long longValue()
Return this in the form of a long.

Returns:
the long corresponding to this.

MinOffset

static int MinOffset(int x,
                     int y)
return the minimum "offset" defined by the two offsets x and y.

Parameters:
x - an offset into a string (or -1 for no argument).
y - an offset into a string (or -1 for no argument).
Returns:
x == -1 ? y : y == -1 ? x : Math.min(x,y);

isNumeric

static boolean isNumeric(java.lang.String s)