eu.simuline.util

Class RealRepresentation

java.lang.Object

eu.simuline.util.RealRepresentation

Direct Known Subclasses:

RealRepresentation.BigDecimalRep, RealRepresentation.DoubleRep

public class RealRepresentation
extends Object

Describes the representation of a real value, which may be either a double, resp. a Double-value or a BigDecimal for use in tables. At a rudimentary stage, RealRepresentation wraps the number whereas RealRepresentation.Desc describes how to format it, e.g. where to add blanks.

Also asInteger() provides some support for formatting integers. These are the two supported levels of precision. It is characterized by the mantissa() and the exponent. The mantissa in turn splits into the integer and the fractional part. The essential point is that these three parts are properly aligned and filled up with 0's and blanks by need.

The splitting between integer, fraction and exponent is as specified for Double.toString(double). The difference between the two levels of precision is made as transparent as possible. Transparence is given up in (at least) the following cases:

• unlike BigDecimals doubles (influenced by the standard IEEE 754), distinguish between +0 and -0.
• for doubles by specification of the string representation,

   "There must be at least one digit to represent the fractional part, 
   and beyond that as many, but only as many, 
   more digits as are needed to uniquely distinguish the argument value 
   from adjacent values of type double. 
   That is, suppose that x is the exact mathematical value 
   represented by the decimal representation produced by this method 
   for a finite nonzero argument d. 
   Then d must be the double value nearest to x; 
   or if two double values are equally close to x, 
   then d must be one of them 
   and the least significant bit of the significand of d must be 0. "
   

  This does not make sense for BigDecimals because there is no nearest BigDecimal: The BigDecimals are "almost" dense in the real numbers. Instead we neglect any trailing zeros. In later versions, this should be different.

Also infinite double's and NaN are not supported. This is because they have no splitting into integer, fractional part and exponent. They do not make sense for BigDecimals and so this would make transparency more difficult. Note that denormalization of double's does not affect their string representation such that this is completely as forforBigDecimals for which automatic denormalization does not make sense (although can be forced by the user).

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
private static class	RealRepresentation.BigDecimalRep Describes the representation of a BigDecimal-value.
static interface	RealRepresentation.Cutter A Cutter is used to shorten numbers.
static class	RealRepresentation.Desc Describes the way the real number represented by RealRepresentation is displayed as a string.
private static class	RealRepresentation.DoubleRep Describes the representation of a double, resp. a Double-value.
private static class	RealRepresentation.Number2SignUnsigned Container for number splitted into sign and unsigned.

Field Summary

Fields

Modifier and Type	Field and Description
static RealRepresentation.Cutter	ALIGN_CUT_OFF_LEFT Describe the action to be taken if a sequence of symbols, e.g. digits are longer as needed.
static RealRepresentation.Cutter	ALIGN_CUT_OFF_RIGHT Describe the action to be taken if a sequence of symbols, e.g. digits are longer as needed.
static RealRepresentation.Cutter	ALIGN_EXCEPTION Describe the action to be taken if a sequence of symbols, e.g. digits are longer as needed.
static RealRepresentation.Cutter	ALIGN_LEAVE_UNCHANGED Describe the action to be taken if a sequence of symbols, e.g. digits are longer as desired.
static String	EXP_CHAR A string containing the character signifying an exponent.
protected String	exponent The exponent of the double value represented.
private static Map<Character,String>	FILL_STRINGS The keys are Characters (intended for either " " or "0") and the associated values are strings consisting of a number of characters given by the key.
protected String	fraction The fractional part of the mantissa of the double value represented.
protected String	integer The integer part of the mantissa of the double value represented.
private static String	noPointS Substitutes the place for the point in case the real number represented has no fractional part.
private static String	POINT_S A string constant containing the decimal point.
protected String	sign The sign of the double value represented.
private static String	SIGN_MINUS A character constant containing +.
private static String	SIGN_PLUS A character constant containing +.
private String	signOfExp
private String	unsignedExp

Constructor Summary

Constructors

Constructor and Description
RealRepresentation()

Method Summary

Modifier and Type	Method and Description
static String	alignLeft(String str, int len, char filler, RealRepresentation.Cutter cutter) Returns a String which is by attaching the minimal number of fillers to the right hand side of str such that the length of the result is at least int.
static String	alignRight(String str, int len, char filler, RealRepresentation.Cutter cutter) Returns a String which is by attaching the minimal number of fillers to the left hand side of str such that the length of the result is at least int.
void	asInteger() Converts this representation such that there is neither a fraction nor an exponent.
static void	compensatePoint(boolean compensate) Sets noPointS according to the parameter: true means that noPointS is attached with " "; otherwise it is "".
static RealRepresentation	create(double val, boolean precision) Converts the given double number to a RealRepresentation with the given precision.
static RealRepresentation	create(Number val) Converts the given number to a RealRepresentation with the natural precision.
static RealRepresentation	create(Number val, boolean precision) Converts the given high precision representation of a real number to a RealRepresentation preserving full precision if so specified.
static RealRepresentation	create(String val, boolean precision) Converts the given string representation of a real number to a RealRepresentation with the given precision.
String	exponent()
static String	fill(char chr0, int len) Returns a String consisting of len copies of the character c.
String	fraction()
private String	getExpWithE()
boolean	hasBlankFraction()
boolean	hasExponent()
boolean	hasFraction()
boolean	hasInteger()
protected void	initSignExp()
String	integer()
String	mantissa()
String	sign()
BigDecimal	this2BigDecimal() Returns a BigDecimal represented.
double	this2double() Returns a double represented.
Double	this2Double() Returns a Double represented.
String	toString() Returns a String representation of this real number.
String	toString(RealRepresentation.Desc desc)
String	toStringDecomp() Returns a string showing the decomposition of the underlying real number into sign, mantissa and exponent.
String	trimExponent(int numDigits, char blankOrNull, boolean strict) Trims the exponent part to length numDigits if possible.
String	trimFraction(int numDigits, char blankOrNull, RealRepresentation.Cutter cutter) Trims the fractional part to length numDigits if possible.
String	trimInteger(int numDigits, char blankOrNull, boolean strict) Trims the integer part to length numDigits if possible.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

ALIGN_CUT_OFF_LEFT

public static final RealRepresentation.Cutter ALIGN_CUT_OFF_LEFT

Describe the action to be taken if a sequence of symbols, e.g. digits are longer as needed.

See Also:

alignLeft(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter), alignRight(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter)

ALIGN_CUT_OFF_RIGHT

public static final RealRepresentation.Cutter ALIGN_CUT_OFF_RIGHT

Describe the action to be taken if a sequence of symbols, e.g. digits are longer as needed.

See Also:

alignLeft(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter), alignRight(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter)

ALIGN_EXCEPTION

public static final RealRepresentation.Cutter ALIGN_EXCEPTION

Describe the action to be taken if a sequence of symbols, e.g. digits are longer as needed.

See Also:

alignLeft(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter), alignRight(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter), trimExponent(int, char, boolean)

ALIGN_LEAVE_UNCHANGED

public static final RealRepresentation.Cutter ALIGN_LEAVE_UNCHANGED

Describe the action to be taken if a sequence of symbols, e.g. digits are longer as desired.

See Also:

alignLeft(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter), alignRight(java.lang.String, int, char, eu.simuline.util.RealRepresentation.Cutter), trimExponent(int, char, boolean)

FILL_STRINGS

private static final Map<Character,String> FILL_STRINGS

The keys are Characters (intended for either " " or "0") and the associated values are strings consisting of a number of characters given by the key.

See Also:

fill(char, int)

EXP_CHAR

public static final String EXP_CHAR

A string containing the character signifying an exponent. This is e but could also be E.

See Also:

Constant Field Values

noPointS

private static String noPointS

Substitutes the place for the point in case the real number represented has no fractional part. This is either " " or "". The default value is " ".

See Also:

compensatePoint(boolean)

POINT_S

private static final String POINT_S

A string constant containing the decimal point.

See Also:

Constant Field Values

SIGN_PLUS

private static final String SIGN_PLUS

A character constant containing +.

See Also:

Constant Field Values

SIGN_MINUS

private static final String SIGN_MINUS

A character constant containing +.

See Also:

Constant Field Values

sign

protected String sign

The sign of the double value represented. This may be either + or -. Note that the standard IEEE 754 distinguishes -0 from +0 and so do we in the subclass RealRepresentation.DoubleRep.

integer

protected String integer

The integer part of the mantissa of the double value represented.

fraction

protected String fraction

The fractional part of the mantissa of the double value represented. This may never be empty but it may be 0.

exponent

protected String exponent

The exponent of the double value represented.

signOfExp

private String signOfExp

unsignedExp

private String unsignedExp

Constructor Detail

RealRepresentation

public RealRepresentation()

Method Detail

compensatePoint

public static void compensatePoint(boolean compensate)

Sets noPointS according to the parameter: true means that noPointS is attached with " "; otherwise it is "".

Parameters:

compensate - a boolean deciding whether to compensate a decimal point in case the real number represented has no fractional part.

initSignExp

protected final void initSignExp()

create

public static RealRepresentation create(String val,
                                        boolean precision)

Converts the given string representation of a real number to a RealRepresentation with the given precision.

Parameters:

val - a String representation of a real number.

precision - a boolean which offers choice between full precision (true) and double precision (false).

Returns:

a RealRepresentation of the real value given by the string representation val with the precision determined by precision.

Throws:

NumberFormatException - if val is not the string representation of a double or if it is NaN or represents an infinite value.

create

public static RealRepresentation create(Number val,
                                        boolean precision)

Converts the given high precision representation of a real number to a RealRepresentation preserving full precision if so specified.

Parameters:

val - a Number value which is either a BigDecimal or a Double.

precision - specifies whether to preserve full precision. If set to false only double precision is used.

Returns:

a RealRepresentation of the real value given by val preserving full precision is specified so.

Throws:

ClassCastException - if val is neither a BigDecimal nor a Double.

create

public static RealRepresentation create(double val,
                                        boolean precision)

Converts the given double number to a RealRepresentation with the given precision.

Parameters:

val - a double value.

precision - a boolean which offers choice between full precision (true which is obsolete****) and double precision (false).

Returns:

a RealRepresentation of the given double with the precision determined by precision.

Throws:

NumberFormatException - if val is either NaN or infinite.

create

public static RealRepresentation create(Number val)

Converts the given number to a RealRepresentation with the natural precision.

Parameters:

val - a Number value which is either a BigDecimal or a Double.

Returns:

a RealRepresentation of the given number with the natural precision: create((BigDecimal)val, true) or create((Double )val, true).

Throws:

ClassCastException - if val is neither a BigDecimal nor a Double.

fill

public static String fill(char chr0,
                          int len)

Returns a String consisting of len copies of the character c.

Parameters:

chr0 - a char.

len - the number of repetitions of c needed. This should be a non-negative integer.

Returns:

a String consisting of len characters c.

alignLeft

public static String alignLeft(String str,
                               int len,
                               char filler,
                               RealRepresentation.Cutter cutter)

Returns a String which is by attaching the minimal number of fillers to the right hand side of str such that the length of the result is at least int. For strict == true even equality is assured.

Parameters:

str - the String to be aligned.

len - an int value which determines the length of the result string:

filler - a char value.

cutter - takes effect if str.length > len:

• for ALIGN_CUT_OFF_RIGHT superfluous digits are cut off,
• { for ALIGN_EXCEPTION superfluous digits cause an exception,
• for ALIGN_LEAVE_UNCHANGED superfluous digits are left unchanged,

Returns:

• for str.length()≤len copies of fillers are attached to the right hand side of str such that the length of the result is least int.
• for str.length()>len
  • str is returned as is provided cutter == ALIGN_LEAVE_UNCHANGED
  • For cutter == ALIGN_EXCEPTION there is no return value: an exception is thrown and finally
  • for cutter == ALIGN_CUT_OFF_RIGHT the overhead is silently cut off.

Throws:

IllegalArgumentException - for cutter == ALIGN_EXCEPTION if str.length() exceeds len.

alignRight

public static String alignRight(String str,
                                int len,
                                char filler,
                                RealRepresentation.Cutter cutter)

Returns a String which is by attaching the minimal number of fillers to the left hand side of str such that the length of the result is at least int. For strict == true even equality is assured.

Parameters:

str - the String to be aligned.

len - an int value which determines the length of the result string:

filler - a char value.

cutter - takes effect if str.length > len: { {

• for ALIGN_CUT_OFF_LEFT superfluous digits are cut off,
• for ALIGN_EXCEPTION superfluous digits cause an exception,
• for ALIGN_LEAVE_UNCHANGED superfluous digits are left unchanged,

Returns:

• for str.length()≤len copies of fillers are attached to the right hand side of str such that the length of the result is least int.
• for str.length()>len
  • str is returned as is provided cutter == ALIGN_LEAVE_UNCHANGED
  • For cutter == ALIGN_EXCEPTION there is no return value: an exception is thrown and finally
  • for cutter == ALIGN_CUT_OFF_LEFT the overhead is silently cut off.

Throws:

IllegalArgumentException - for cutter == ALIGN_EXCEPTION if str.length() exceeds len.

trimInteger

public final String trimInteger(int numDigits,
                                char blankOrNull,
                                boolean strict)

Trims the integer part to length numDigits if possible. If this leads to a prolongation of the integer part, it is filled up with characters blankOrNull from the left hand side. If the integer part is already longer than specified, the action taken relies on the parameter strict. Caution: ***** this does not work very well for numDigits = 0. Caution: **** not ok with signs. Caution: **** what to do if ".4" is needed?

Parameters:

numDigits - a non-negative int value signifying the length of the integer part.

blankOrNull - a char with which the integer part is filled up by need from the left hand side to reach length numDigits. Useful settings are probably blank and '0' only.

strict - a boolean signifying whether an attempt to cut off parts of the integer will result in an exception; otherwise it is just ignored.

Returns:

the new integer part as a String.

Throws:

IllegalArgumentException - for strict( == true) if the length of the integer part exceeds numDigits.

trimExponent

public final String trimExponent(int numDigits,
                                 char blankOrNull,
                                 boolean strict)

Trims the exponent part to length numDigits if possible. If this leads to a prolongation of the exponent part, it is filled up with characters blankOrNull from the left hand side. If the exponent part is already longer than specified, the action taken relies on the parameter strict. Caution: ***** this does not work very well for numDigits = 0. Caution: **** not ok with signs. Caution: **** not ok if there are no exponents at all.

Parameters:

numDigits - a non-negative int value signifying the length of the exponent part.

blankOrNull - a char with which the exponent part is filled up by need from the left hand side to reach length numDigits. Useful settings are probably blank and '0' only.

strict - a boolean signifying whether an attempt to cut off parts of the exponent will result in an exception; otherwise it is just ignored.

Returns:

the new exponent as a String.

Throws:

IllegalArgumentException - for strict( == true) if the length of the exponent part exceeds numDigits.

trimFraction

public final String trimFraction(int numDigits,
                                 char blankOrNull,
                                 RealRepresentation.Cutter cutter)

Trims the fractional part to length numDigits if possible. If this leads to a prolongation of the fractional part, it is filled up with characters blankOrNull. If the fractional part is already longer than specified, the action taken relies on the code cutter. Caution: ***** this does not work very well for numDigits = 0. Caution: **** this method simply cuts off digits without rounding.

Parameters:

numDigits - a non-negative int value signifying the length of the fractional part.

blankOrNull - a char with which the fractional part is filled up by need to reach length numDigits. Useful settings are probably '0' and blank only.

cutter - an int code which is relevant only, if the current fractional part is longer than specified by numDigits.

Returns:

the new trimmed fractional part as a String.

Throws:

IllegalArgumentException - for cutter == ALIGN_EXCEPTION if the length of the fractional part exceeds numDigits.

asInteger

public final void asInteger()

Converts this representation such that there is neither a fraction nor an exponent. Of course in general thereby the current format is lost.

Throws:

NumberFormatException - if this representation cannot be written as an integer.

hasBlankFraction

public final boolean hasBlankFraction()

hasFraction

public final boolean hasFraction()

hasInteger

public final boolean hasInteger()

hasExponent

public final boolean hasExponent()

sign

public final String sign()

exponent

public final String exponent()

mantissa

public final String mantissa()

integer

public final String integer()

fraction

public final String fraction()

this2Double

public final Double this2Double()

Returns a Double represented.

Returns:

a Double d satisfying create(d, false).this2Double().compareTo(d) == 0.

this2double

public final double this2double()

Returns a double represented.

Returns:

a double d satisfying create(d, false).this2double() == d.

this2BigDecimal

public final BigDecimal this2BigDecimal()

Returns a BigDecimal represented.

Returns:

a BigDecimal d satisfying create(d, true).this2BigDecimal().compareTo(d) == 0.

getExpWithE

private String getExpWithE()

toString

public final String toString()

Returns a String representation of this real number. Formatting is determined by previous invocations of the methods trimInteger(int, char, boolean), trimFraction(int, char, eu.simuline.util.RealRepresentation.Cutter) and trimExponent(int, char, boolean).

Overrides:

toString in class Object

Returns:

a String reflecting this representation of a real number. In front of the sign (which may be empty), between the sign and the integer part, between the fractional part and the exponent or the end of the string and also between the *****

See Also:

toStringDecomp()

toString

public final String toString(RealRepresentation.Desc desc)

toStringDecomp

public final String toStringDecomp()

Returns a string showing the decomposition of the underlying real number into sign, mantissa and exponent.

Returns:

a String value

See Also:

toString()