Package eu.simuline.util

Class RealRepresentation

  • Direct Known Subclasses:
    RealRepresentation.BigDecimalRep, RealRepresentation.DoubleRep
    public class RealRepresentation
extends java.lang.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).

    • Field Summary

      Fields 
      Modifier and Type Field 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 java.lang.String EXP_CHAR
      A string containing the character signifying an exponent.
      protected java.lang.String exponent
      The exponent of the double value represented.
      private static java.util.Map<java.lang.Character,​java.lang.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 java.lang.String fraction
      The fractional part of the mantissa of the double value represented.
      protected java.lang.String integer
      The integer part of the mantissa of the double value represented.
      private static java.lang.String noPointS
      Substitutes the place for the point in case the real number represented has no fractional part.
      private static java.lang.String POINT_S
      A string constant containing the decimal point.
      protected java.lang.String sign
      The sign of the double value represented.
      private static java.lang.String SIGN_MINUS
      A character constant containing +.
      private static java.lang.String SIGN_PLUS
      A character constant containing +.
      private java.lang.String signOfExp  
      private java.lang.String unsignedExp  

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static java.lang.String alignLeft​(java.lang.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 java.lang.String alignRight​(java.lang.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​(java.lang.Number val)
      Converts the given number to a RealRepresentation with the natural precision.
      static RealRepresentation create​(java.lang.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​(java.lang.String val, boolean precision)
      Converts the given string representation of a real number to a RealRepresentation with the given precision.
      java.lang.String exponent()  
      static java.lang.String fill​(char chr0, int len)
      Returns a String consisting of len copies of the character c.
      java.lang.String fraction()  
      private java.lang.String getExpWithE()  
      boolean hasBlankFraction()  
      boolean hasExponent()  
      boolean hasFraction()  
      boolean hasInteger()  
      protected void initSignExp()  
      java.lang.String integer()  
      java.lang.String mantissa()  
      java.lang.String sign()  
      java.math.BigDecimal this2BigDecimal()
      Returns a BigDecimal represented.
      double this2double()
      Returns a double represented.
      java.lang.Double this2Double()
      Returns a Double represented.
      java.lang.String toString()
      Returns a String representation of this real number.
      java.lang.String toString​(RealRepresentation.Desc desc)  
      java.lang.String toStringDecomp()
      Returns a string showing the decomposition of the underlying real number into sign, mantissa and exponent.
      java.lang.String trimExponent​(int numDigits, char blankOrNull, boolean strict)
      Trims the exponent part to length numDigits if possible.
      java.lang.String trimFraction​(int numDigits, char blankOrNull, RealRepresentation.Cutter cutter)
      Trims the fractional part to length numDigits if possible.
      java.lang.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

    • 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​(java.lang.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:
        java.lang.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​(java.lang.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:
        java.lang.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:
        java.lang.NumberFormatException - if val is either NaN or infinite.

      • create

        public static RealRepresentation create​(java.lang.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:
        java.lang.ClassCastException - if val is neither a BigDecimal nor a Double.

      • fill

        public static java.lang.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 java.lang.String alignLeft​(java.lang.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:
        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
        Throws:
        java.lang.IllegalArgumentException - for cutter == ALIGN_EXCEPTION if str.length() exceeds len.

      • alignRight

        public static java.lang.String alignRight​(java.lang.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: { {
        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
        Throws:
        java.lang.IllegalArgumentException - for cutter == ALIGN_EXCEPTION if str.length() exceeds len.

      • trimInteger

        public final java.lang.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:
        java.lang.IllegalArgumentException - for strict( == true) if the length of the integer part exceeds numDigits.

      • trimExponent

        public final java.lang.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:
        java.lang.IllegalArgumentException - for strict( == true) if the length of the exponent part exceeds numDigits.

      • trimFraction

        public final java.lang.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:
        java.lang.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:
        java.lang.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 java.lang.String sign()

      • exponent

        public final java.lang.String exponent()

      • mantissa

        public final java.lang.String mantissa()

      • integer

        public final java.lang.String integer()

      • fraction

        public final java.lang.String fraction()

      • getExpWithE

        private java.lang.String getExpWithE()

      • toStringDecomp

        public final java.lang.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()