ArciMath BigDecimal v2.05
now with BigDecimalFormat

be.arci.text
Class BigDecimalFormat

java.lang.Object
  |
  +--java.text.Format
        |
        +--be.arci.text.BigDecimalFormat
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable

public class BigDecimalFormat
extends java.text.Format
implements java.lang.Cloneable, java.io.Serializable

BigDecimalFormat is an implementation of java.text.Format that parses and formats (large) decimal numbers. Many new options and features of BigDecimalFormat make it much more advanced than the standard java.text.DecimalFormat (we use the unqualified class name DecimalFormat further on). Therefor we decided to let BigDecimalFormat format not only ArciMath BigDecimal numbers, but also all Java's primitive numeric types, Java's standard large number classes java.math.BigInteger and java.math.BigDecimal, and all Number objects having a decimal String representation, like com.ibm.math.BigDecimal and com.tce.math.TBigDecimal.

BigDecimalFormat's parsing is very lenient, to accept common user input styles as well as output from BigDecimalFormat's own format methods.

BigDecimalFormat uses intermediate ArciMath BigDecimal objects for all arithmetic, rounding, and toString() representation.

Contents

  1. Overflow protection
  2. Number notations and localization
  3. Exponential Notation
  4. Rounding
  5. Multiples of a smallest module
  6. Padding and alignment
  7. FieldPosition alignment
  8. Parsing
  9. Patterns
    1. Properties not set from a pattern
    2. Shorthand syntax
    3. Full Pattern grammar
    4. Examples

For access to member descriptions use the navigation bar on top.

  1. Overflow protection
  2. Unlike DecimalFormat, BigDecimalFormat will never truncate most-significand digits or the exponent of a formatted number; it gives you the choice to either extend the formatted number beyond the desired pattern width, or to throw an FormatOverflowException instead.

    Also, BigDecimalFormat uses the ArciMath BigDecimal class for all arithmetic, which offers a very strong protection against overflow both by the range of numbers that can be represented as ArciMath BigDecimal objects, and by ArciMath's performant but safe algorithms, throwing an ArithmeticException on overflow.

    -- back to contents --

  3. Number notations and localization
  4. BigDecimalFormat supports different flavors of number notations, including integers (123), percentages (12%) and per milles (124;), currency amounts ($123), fixed-point numbers (123.4), scientific (1.2345E+5), engineering (123.45E+3) and other forms of exponential notation. All of these flavors can be easily localized and adapted to your specific needs, both by applying measure-made patterns, and by using the API to modify settings that follow from the standard patterns. The symbols used for currency, thousands, decimal point, exponential notation etc. may be set to arbitrary values via the java.text.DecimalFormatSymbols object, taking care that no ambiguity results.

    BigDecimalFormat outputs decimal digits starting with the DecimalFormatSymbols- defined localized zero digit; as an example the decimal digit 5 is output as (char)(decimalFormatSymbols.getZeroDigit() + 5). During parsing BigDecimalFormat recognizes all Unicode characters that represent decimal digits, as defined by Character.digit(), as well as the ten consecutive characters starting with the localized zero digit defined in the DecimalFormatSymbols object. Thus BigDecimalFormat makes it possible to parse and format numbers in any locale where the decimal digits ocupy 10 consecutive places in de Unicode character table, offering support for Western (ISO-LATIN-1), Arabic-Indic, Extended Arabic-Indic, Devanagari, Bengali, Gurmukhi, Gujarati, Oriya, Telugu, Kannada, Malayalam, Thai, Lao, Tibetan and Fullwidth digits.

    For localization BigDecimalFormat builds on DecimalFormat, rather than directly parsing the localization rules in the java.text.resources.LocaleElements_xx_XX group of classfiles, because the latter are undocumented and indeed differ in different JDK versions.

    The default BigDecimalFormat() constructor starts from a default DecimalFormat object. The BigDecimalFormat(DecimalFormat) constructor accepts the localized DecimalFormat objects typically delivered by calls to java.text.NumberFormat's getNumberInstance, getCurrencyInstance, getPercentInstance and getScientificInstance methods. (Currently, upto JDK13, all of these methods in NumberFormat are hardcoded to return a DecimalFormat object, even though it is documented that for some locales NumberFormat might return another type). DecimalFormat patterns should all be compatible with BigDecimalFormat, though the reverse is certainly not true.

    -- back to contents --

  5. Exponential Notation
  6. In a class that formats ArciMath BigDecimal numbers, there is an obvious need for exponential notation. In exponential notation numbers are expressed as the product of a base number with a power of ten. For example, 1234 can be expressed as 1.234 * 10^3. For e.g. scientific notation, a common form of exponential notation, the base number is in the range 1.0 <= x < 10.0. In engineering notation, another form of exponential notation, the base number is in the range 1.0 <= x < 1000.0, and the power of 10 is a multiple of 3. In BigDecimalFormat, numbers in exponential notation may contain grouping separators in the integer field (in DecimalFormat they may not).

    The usual symbol for indicating the exponent is "E", but the user can set any other String to be used as exponent symbol (this should be a feature of DecimalFormatSymbols, but it isn't, and because DecimalFormatSymbols is final we made it a feature of BigDecimalFormat itself).

    Negative exponents are formatted using the localized minus sign, not the prefix and suffix from the negative subpattern. This allows notations such as "(1.17E+5)" for the value -117,000. For positive exponents the user can specify to show a plus sign following the exponent symbol or not.

    -- back to contents --

  7. Rounding
  8. On formatting BigDecimalFormat rounds formatted numbers to the specified maximum number of decimal places, according to a specified rounding mode. Rounding is done after an eventual multiplier is applied. The class MathContext defines the rounding modes that are accepted.

    With exponent increments, formatting rounds the number to the sum of the actual integer digits that will be shown and the maximum number of decimal places (in DecimalFormat the number of formatted digits is fixed at 1 + the number of decimal places, making that some digits may get shifted from the decimal places into the integer field to make the exponent a multiple of it's increment). For example the pattern "000.0000E+03" sets a fixed length engineering format with 3 integer digits and 4 decimal places, and an exponent value of 2 digits.

    -- back to contents --

  9. Multiples of a smallest module
  10. BigDecimalFormat supports limiting a formatted number to multiples of a specific smallest module. Examples for this are the smallest coin for a currency (e.g. 25 centimes in pre-Euro Belgium), or the smallest subdivision of sliding callipers, often 1/20 mm or 0.05mm. The smallest module can also be used to round a formatted number to a position within the integer field, commonly used to express a sum of money in e.g. thousands or millions. The rounding mode set for the BigDecimalFormat is used for formatting a number in multiples of the smallest module. If the smallest module is 0.25, the number 12.30 will be rounded to 12.25 or 12.50, depending on the rounding mode of BigDecimalFormat.

    -- back to contents --

  11. Padding and alignment
  12. For proper alignment of formatted numbers BigDecimalFormat supports replacing non-significant zero digits with a padding character of choice, or padding any number to a fixed width. The former kind of padding can only be specified through the API method setZeroPaddingChar(). The latter kind may be specified either through the API or through the pattern syntax. Alignment is made easier if you keep positive and negative prefix and positive and negative suffixes the same length.

    -- back to contents --

  13. FieldPosition alignment
  14. If the padding alone is not sufficient for proper alignment (e.g. when using proportional fonts), or if you need to further customize the format result, you can use the FieldPosition argument to the format() methods with one of the many xxx_FIELD constants of BigDecimalFormat. After formatting, the FieldPosition object will contain the beginning and ending positions of the indicated field in the formatted number. If the desired field is not present in the formatted number, FieldPosition's begin and end position will be equal, and indicate the position where that field would have been. For example, with FieldPosition fp = new FieldPosition(BigDecimalFormat.EXPONENT_SIGN_FIELD); and a formatted number "1.23E4", where there is no exponent sign shown, fp.getBeginIndex() and fp.getEndIndex() both return 5, because the proper place for the exponent sign would have been at offset 5 (between the 'E' and the '4').

    For example, you can use FieldPosition to align numbers on the decimal point in two ways:

    1. If you are using a monospaced font with spacing for alignment, you can pass the FieldPosition in your format call, with field = INTEGER_FIELD. On output, getEndIndex will be set to the offset between the last character of the integer and the decimal. Add (desiredSpaceCount - getEndIndex) spaces at the front of the string.
    2. If you are using proportional fonts, instead of padding with spaces, measure the width of the string in pixels from the start to getEndIndex. Then move the pen by (desiredPixelWidth - widthToAlignmentPoint) before drawing the text.
    3. If you are using a well-defined proportional font, you can also try out the Unicode set of full-width characters ('\uFF01'-'\uFF5E') to format the number as if in monospaced font.

    Note: JDK1.1 We cannot set the FieldPosition indexes in the JDK1.1.x version, due to a bug in java.text.FieldPosition (package private access to the relevant methods). However, we have noticed that the Java 2 version of BigDecimalFormat, that does set the FieldPosition indexes, works fine on Sun's JDK1.1.x virtual machines; apparently these virtual machines check for method accessibility at compile time only, not at runtime. As the FieldPosition treatment is the only difference between the JDK1.1 and Java2 versions of BigDecimalFormat, you could use the Java2 version on these virtual machines.

    -- back to contents --

  15. Parsing
  16. BigDecimalFormat's default parsing is very lenient. BigDecimalFormat accepts common user input styles as well as output from BigDecimalFormat's own format methods. However, this lenience may be overridden by requiring strict parsing adherence to the different parts in a BigDecimal pattern. If BigDecimalFormat.parse(String, ParsePosition) fails to parse a String, it returns null and leaves the parse position unchanged. The convenience method BigDecimalFormat.parse(String) indicates parse failure by throwing a ParseException.

    Here are the rules for lenient parsing; see the description of strict parsing for possible areas of strict parsing:

    1. A number String must contain at least one digit.
    2. If parse integer only is set, parsing stops at the decimal separator, if any. Decimal places, exponent or suffix that are present in the input but that come after a decimal separator are ignored. ParsePosition index is set at that decimal separator.
    3. Leading spaces and padding characters are skipped upto the prefix, if any. The prefix must match either the positive prefix or the negative prefix to be recognized. The prefix is recognized even if it was specified to contain a digit.
    4. If both positive and negative prefix can be matched, the one found at the smallest offset determines the sign; else if both occur at the same offset, the longest match determines the sign; else they are equal, and the sign is left undetermined.
    5. Next, again spaces and padding characters are skipped. If no sign was determined from a prefix, these may contain a leading explicit sign (the localized plus or minus sign, or the '-' or '+' character), determining the sign of the number.
    6. Next leading zero padding characters are skipped, upto the first digit or a leading decimal separator.
    7. Next, digits and decimal and grouping separators are matched to form a decimal base number.
    8. The grouping seperators may be the commonly used characters '.' and ',' or the genuine grouping separator; all grouping separators must be the same character. No grouping separator can occur after a decimal separator. If grouping separators are used in the number String, these serve as check against omitting digits in typing; therefor grouping separator positions must always match the grouping size setting.
    9. A decimal separator may be the commonly used characters '.' and ',' or the genuine decimal or monetary decimal separator (regardless of the currency format setting). Only one decimal separator can occur.
    10. The ambiguity when only one separator character occurs, and it is the '.' or the ',' character, is resolved as such.
      The separator character is interpreted as a decimal separator if it is
      • the genuine decimal separator, or,
      • the genuine monetary decimal separator if it is a currency format, or
      • neither of both genuine decimal separators, but also not the genuine grouping separator and the grouping is not the proper grouping size setting
      Else the separator character is interpreted as a grouping separator.
    11. Next, if the BigDecimalFormat has exponential notation, an exponent may follow. The exponent symbol might be either the genuine exponent symbol or the commonly used characters 'E' and 'e'. The exponent symbol may be preceded by zero padding characters followed by spaces and padding characters. The exponent symbol may be also followed by an explicit sign, determining the sign of the exponent value. Note that the exponent sign is determined from the presence of the characters '+' and '-' or of the plus-sign and minus-sign set for the BigDecimalFormat, not as in DecimalFormat from the repetition around the exponent value of the negative or positive prefix and suffix that determine the sign of the number as a whole.
    12. Next if an exponent symbol is found, spaces are skipped.
    13. Next if an exponent symbol is found, zero padding characters are skipped.
    14. Next if an exponent symbol is found, digits are matched to form the exponent value. If the sign of the exponent value was not yet determined, these digits may be preceeded by an explicit sign, determining the sign of the exponent value (else the sign of the exponent value is positive).
    15. Next a suffix may follow. The suffix may be preceded by zero padding characters followed by spaces and padding characters. The suffix must match either the positive suffix or the negative suffix to be recognized.
    16. If both positive and negative suffix can be matched, the first one determines the sign; else if both occur at the same offset, the longest match determines the sign; else they are equal, and the sign is left undetermined. If a sign was determined from the prefix as well, both should match. If a sign can be determined from the prefix, it may not have been determined from a leading explicit sign, even if that is the same sign as determined from the suffix.
    17. If no sign was determined from a prefix, suffix or explicit sign, then the sign is determined from the absence of prefix and suffix. If the prefix is absent and the positive prefix of BigDecimalFormat is not empty and not equal to the negative prefix, it's absence is interpreted as a negative sign. If the prefix is absent and the negative prefix of BigDecimalFormat is not empty and not equal to the positive prefix, it's absence is interpreted as a positive sign. The same is done with the suffixes. If in this way no unambiguous sign can be determined, parsing fails.
    18. After the suffix, or if no suffix is found, spaces or padding characters are skipped, only if the padding position is after the suffix, upto the explicit or implicit padding width, and the ParsePosition index is set.
    19. If the BigDecimalFormat has a multiplier set (e.g. 100 for percents or 1000 for per milles), the parsed number is divided by this multiplier, regardless of wether a percent or per mille token appears in the input prefix or suffix.

    -- back to contents --

  17. Patterns
  18. A BigDecimalFormat comprises a pattern and a set of symbols. The symbols are stored in a DecimalFormatSymbols object. The pattern may be set directly using applyPattern() and applyLocalizedPattern(), or indirectly using the API methods. When using the default BigDecimalFormat() or the BigDecimalFormat(DecimalFormat) constructors, the pattern and symbols are read from the (default) DecimalFormat object.

    Contains:

    1. Properties not set from a pattern
    2. Shorthand pattern syntax
    3. Full Pattern grammar
    4. Examples

      -- back to contents --

    1. Properties not set from a pattern
    2. The following properties can only be set through the API, not through a pattern:

      -- back to contents --

    3. Shorthand pattern syntax
    4. -- back to contents --

    5. Full Pattern grammar


    6. Notation
      + repeat ('1 or more instances of')
      * repeat optional ('0 or more instances of')
      { } optional ('0 or 1 instances of')
      [ X | Y | ... | Z ] choose ('1 of the choices X to Z')
      ( ) group ('treat enclosed grammar specification as 1 symbol')
      X..Y range ('any of X up to Y, inclusive')
      S - T exclude ('symbols in S, except those in T')


      Symbols
      The non-localized symbols are used with applyPattern() and toPattern(). The corresponding localized symbols are used with applyLocalizedPattern(), toLocalizedPattern(), format() and parse(). They can be get/set through the DecimalFormatSymbols object or (for the exponent symbol) through the BigDecimalFormat object itself.

      currencySign := '¤'
      '¤' is Unicode character '\u00A4'
      decimalSep := [ '.' | localizedDecimalSeparator ]
      digitPlace := [ '#' | localizedDigit ]
      exponentSymbol:= [ "E" | localizedExponentSymbol ]
      groupingSep := [ ',' | localizedGroupingSeparator ]
      padEscape := '^'
      patternSep := [ ';' | localizedPatternSeparator ]
      percent := [ '%' | localizedPercent ]
      perMille := [ '‰' | localizedPerMill ]
      '‰' is Unicode character '\u2030'
      plusSign := [ '+' | localizedPlusSign ]
      quote := '\''
      The single quote character
      zeroDigit := [ '0' | localizedZeroDigit ]
      nonZeroDigit := (zeroDigit + 1..9)
      This is an arithmetic sum!
      digit := [ zeroDigit | nonZeroDigit ]
      char := [ ( '\u0000'..'\uFFFD' - quote ) | ( quote quote ) ]
      expandedChar := [ percent |
      perMille |
      currencySign |
      ( currencySign currencySign ) ]
      specialChar := [ currencySign |
      decimalSep |
      digit |
      digitPlace |
      groupingSep |
      padEscape |
      patternSep |
      percent |
      perMille ]
      unquotedChar := [ ( char - specialChar ) | expandedChar ]
      quotedChars := quote char+ quote


      Grammar
      pattern := posPattern { patternSep negPattern }
      posPattern := subPattern
      negPattern := subPattern
      subPattern := [ ( { paddedPrefix } number { suffix } ) |
      ( { prefix } paddedNumber { suffix } ) |
      ( { prefix } number { paddedSuffix } ) ]
      paddedPrefix := paddedAffix
      paddedSuffix := paddedAffix
      paddedAffix := [ ( padSpec affix ) | ( affix padSpec ) ]
      prefix := affix
      suffix := affix
      affix := [ unquotedChar | quotedChars ]+
      padSpec := padEscape padChar
      padChar := char
      paddedNumber := fixedPoint { padSpec } exponent
      number := fixedPoint exponent
      fixedPoint := [ integer |
      ( integer decimalSep ) |
      ( { integer } decimalSep mantissa ) ]
      integer := [ minIntDigits+ |
      ( maxIntDigits+ minIntDigits* ) ]
      minIntDigits := { groupingSep } digit+
      maxIntDigits := { groupingSep } digitPlace+
      mantissa := [ minDecPlaces |
      ( { minDecPlaces } maxDecPlaces ) ]
      minDecPlaces := digit+
      maxDecPlaces := digitPlace+
      exponent := exponentSymbol { plusSign } exponentValue
      exponentValue := [ minExpDigits |
      ( { minExpDigits } maxExpDigits ) ]
      minExpDigits := digit+
      maxExpDigits := digitPlace+


      -- back to contents --

    7. Examples
    8. All examples here use the default roundingMode, retainZeroTail false, a groupingSeparator of ',' and a decimalSeparator of '.'

      General examples
      "^*#,###,##0.00;(#)"
      formats the number -4321.3 as "BEF(****4,321.30)" if the international currency symbol for the locale is "BEF".
      "00.0%"
      formats the number -0.1237 as "-12.4%"

      Examples of smallest modules
      "#,##0.25"
      formats the number 234.56 as "234.50" (smallest module 0.25)
      "#,##02.50"
      formats the number 456.78 as "457.50" (smallest module 2.50)
      "#,##1,000"
      formats the number 1234567 as "1,235,000" (smallest module 1000)

      Examples of exponential notation
      "0.####E0"
      formats the number 12345 as "1.2345E4"
      "0.####E0"
      formats the number 0.12345 as "1.2345E-1"
      "0.####E0"
      formats the number 1.2345 as "1.2345E0"
      "0.####E+0"
      formats the number 12345 as "1.2345E+4"
      "0.####E+0"
      formats the number 0.12345 as "1.2345E-1"
      "0.####E+0"
      formats the number 1.2345 as "1.2345E+0"
      "0.####E#"
      formats the number 1.2345 as "1.2345"
      "0.####E+#"
      formats the number 1.2345 as "1.2345"
      "0.0000E+0"
      formats the number 1.23 as "1.2300E+0"
      "0.0000E+0"
      formats the number 1.23 as "1.23__E+0" if the zero padding character is '_'
      " 0.####^_E+0;-#"
      formats the number 1.23 as " 1.23__E+0" (padding character '_')
      "000.####E+0"
      formats the number 12345 as "123.45E+2"
      "000.####E+3"
      formats the number 12345 as "012.345E+3"
      "##0.####E+3"
      formats the number 12345 as "12.345E+3"
      "##0.####E+0"
      formats the number 12345 as "12.345E+3"

-- back to contents --

See Also:
"java.text.Format", "java.text.NumberFormat", "java.text.DecimalFormat", "java.text.DecimalFormatSymbols", BigDecimal, MathContext, Serialized Form

Field Summary
static int BASE_NUMBER_FIELD
          Field constant that can be used to construct a FieldPosition object.
static char CURRENCY_SIGN
          The CURRENCY_SIGN is the standard Unicode symbol for currency.
static int DECIMAL_FRACTION_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int DECIMAL_SEPARATOR_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int EXPONENT_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int EXPONENT_SIGN_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int EXPONENT_SYMBOL_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int EXPONENT_VALUE_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int INTEGER_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int NUMBER_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int PAD_AFTER_PREFIX
          Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters after the prefix.
static int PAD_AFTER_SUFFIX
          Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters after the suffix.
static int PAD_BEFORE_EXPONENT
          Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters before the exponent.
static int PAD_BEFORE_PREFIX
          Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters before the prefix.
static int PAD_BEFORE_SUFFIX
          Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters before the suffix.
static int PADDING_FIELD
          Field constant that can be used to construct a FieldPosition object.
static int PARSE_LENIENT
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), specifying lenient parsing of number Strings.
static int PARSE_MATCH_AFFIXES
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness().
static int PARSE_MATCH_EXPONENT_SYMBOL
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), allowing only the exponent symbol set for the BigDecimalFormat as exponent symbol in a number String.
static int PARSE_MATCH_GROUPING
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring digit grouping if the grouping size set for the BigDecimalFormat is not zero.
static int PARSE_MATCH_PADDING_CHAR
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), accepting only the padding character set for the BigDecimalFormat as padding in a number String.
static int PARSE_MATCH_PADDING_POS
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring any padding in a number String to occur at the padding position set for the BigDecimalFormat.
static int PARSE_MATCH_PADDING_WIDTH
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), to enforce a correct number of padding characters.
static int PARSE_MATCH_PREFIX
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring a match with either the positive or the negative prefix when parsing a number String.
static int PARSE_MATCH_SEPARATOR_CHARS
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), allowing only the grouping separator and the decimal (or monetary decimal for currency formats) separator characters set for the BigDecimalFormat's java.text.DecimalFormatSymbols as separator characters in a number String.
static int PARSE_MATCH_SIGN_CHARS
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), allowing only the plus sign and minus sign set for the BigDecimalFormat or it's java.text.DecimalFormatSymbols as sign character in a number String.
static int PARSE_MATCH_SUFFIX
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring a match with either the positive or the negative suffix when parsing a number String.
static int PARSE_STRICT
          Parsing strictness constant for getParsingStrictness() and setParsingStrictness().
static char PER_MILLE_SIGN
          The PER_MILLE_SIGN is the standard Unicode symbol for per mille.
static char PERCENT_SIGN
          The PERCENT_SIGN is the standard Unicode symbol for percent.
static int PREFIX_FIELD
          Field constant that can be used to construct a FieldPosition object.
static char QUOTE
          The single quote character to embed special characters in pattern affixes
static int SUFFIX_FIELD
          Field constant that can be used to construct a FieldPosition object.
 
Constructor Summary
BigDecimalFormat()
          Create a BigDecimalFormat using the default pattern and symbols for the default locale.
BigDecimalFormat(java.text.DecimalFormat dfmt)
          Convenience method to construct a localized BigDecimalFormat, based on e.g. one of the standard DecimalFormat's for a given locale, obtained using the factory methods on NumberFormat such as getInstance or getCurrencyInstance.
BigDecimalFormat(java.lang.String sPattern)
          Create a BigDecimalFormat from the given pattern and the symbols for the default locale.
BigDecimalFormat(java.lang.String sPattern, java.text.DecimalFormatSymbols dfsSymbols)
          Create a BigDecimalFormat from the given pattern and symbols.
BigDecimalFormat(java.lang.String sPattern, java.util.Locale locale)
          Create a BigDecimalFormat from the given pattern and the symbols for the given locale.
 
Method Summary
 void applyLocalizedPattern(java.lang.String sLocalizedPattern)
          Apply the given localized pattern to this BigDecimalFormat object.
 void applyPattern(java.lang.String sPattern)
          Apply the given pattern to this BigDecimalFormat object.
 java.lang.Object clone()
          Standard override; no change in semantics.
 boolean equals(java.lang.Object obj)
          Overrides equals
 java.lang.String format(java.math.BigDecimal bdNumber)
          Convenience method which formats a java.math.BigDecimal value to a String according to the pattern represented by this BigDecimalFormat.
 java.lang.String format(BigDecimal bdNumber)
          Convenience method which formats an ArciMath BigDecimal value to a String according to the pattern represented by this BigDecimalFormat.
 java.lang.StringBuffer format(java.math.BigDecimal bdNumber, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Format a java.math.BigDecimal number.
 java.lang.StringBuffer format(BigDecimal bdNumber, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Format an ArciMath BigDecimal number.
 java.lang.String format(java.math.BigInteger biNumber)
          Convenience method which formats a BigInteger value to a String according to the pattern represented by this BigDecimalFormat.
 java.lang.StringBuffer format(java.math.BigInteger biNumber, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Format a BigInteger number.
 java.lang.String format(double dNumber)
          Convenience method which formats the decimal String representation of a double value to a String according to the pattern represented by this BigDecimalFormat.
 java.lang.StringBuffer format(double dNumber, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Formats a double value, with proper rendering of NaN and Infinite values.
 java.lang.String format(long lNumber)
          Convenience method which formats a long value to a String according to the pattern represented by this BigDecimalFormat.
 java.lang.StringBuffer format(long lNumber, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Format a long value.
 java.lang.String format(java.lang.Number number)
          Convenience method which formats the toString() representation of a Number value to a String according to the pattern represented by this BigDecimalFormat.
 java.lang.StringBuffer format(java.lang.Number number, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Format a Number.
 java.lang.StringBuffer format(java.lang.Object oNumber, java.lang.StringBuffer sbToAppendTo, java.text.FieldPosition fPos)
          Formats an object to produce a string.
 boolean getCurrencyFormat()
          true if this object represents a currency format.
 java.text.DecimalFormatSymbols getDecimalFormatSymbols()
          Returns a clone of the decimal format symbols used by this BigDecimalFormat; changes to the returned object thus have no influence on the BigDecimalFormat.
 boolean getDecimalSeparatorAlwaysShown()
          Returns wether the decimal separator is shown with integer numbers.
 boolean getExponentialNotation()
          Return whether or not exponential notation is used.
 int getExponentIncrement()
          Return the exponent increment used with exponential notation.
 boolean getExponentSignAlwaysShown()
          Return whether the exponent sign is always shown.
 java.lang.String getExponentSymbol()
          Get the symbol indicating the exponent in exponential notation and localized patterns.
 int getGroupingSize()
          Return the grouping size.
 int getMaximumDecimalPlaces()
          Returns the maximum number of digits to format in the decimal fraction of a number; this value has no effect on parsing.
 int getMaximumExponentDigits()
          Return the maximum number of digits to format in the exponent value of a number with exponential notation; this value has no effect on parsing.
 int getMaximumIntegerDigits()
          Returns the maximum number of digits to format in the integer portion of a number; this value has no effect on parsing.
 int getMinimumDecimalPlaces()
          Returns the minimum number of digits to format in the decimal fraction of a number; this value has no effect on parsing.
 int getMinimumExponentDigits()
          Return the minimum number of digits required in the exponent value of a number with exponential notation.
 int getMinimumIntegerDigits()
          Returns the minimum number of digits required in the integer portion of a number.
 int getMultiplier()
          Get the multiplier for use in percent, permill, etc.
 java.lang.String getNegativePrefix()
          Get the negative prefix.
 java.lang.String getNegativeSuffix()
          Get the negative suffix.
 char getPaddingChar()
          Get the character used to pad a formatted number to the padding width.
 int getPaddingPosition()
          Get the position at which to pad a formatted number that is shorter than the padding width.
 int getPaddingWidth()
          Get the width to which the output of format() is to be padded.
 boolean getParseIntegerOnly()
          Returns true if this format will parse numbers as integers only.
 int getParsingStrictness()
          Returns the parsing strictness for this BigDecimalFormat.
 char getPlusSign()
          Get the symbol indicating the localized plus sign.
 java.lang.String getPositivePrefix()
          Get the positive prefix.
 java.lang.String getPositiveSuffix()
          Get the positive suffix.
 boolean getRetainZeroTail()
          Returns whether trailing zero digits in a number will be formatted as significand.
 int getRoundingMode()
          Get the rounding mode used in rounding numbers to the maximum decimal places and to multiples of the smallest module, and in dividing parsed numbers by the multiplier property.
 boolean getSignalOverflow()
          Return whether or not overflow is signalled during formatting.
 BigDecimal getSmallestModule()
          Get the smallest modules to which this BigDecimalFormat rounds formatted numbers.
 int getZeroPaddingChar()
          Get the character used to replace non-significant zeroes.
 int hashCode()
          Overrides hashCode
 BigDecimal parse(java.lang.String sNumber)
          Convenience method to parse a number from a String.
 BigDecimal parse(java.lang.String sNumber, java.text.ParsePosition ppStatus)
          Returns an ArciMath BigDecimal number parsed from the String argument.
 java.lang.Object parseObject(java.lang.String sNumber, java.text.ParsePosition ppStatus)
          Parses a String to produce an ArciMath BigDecimal object.
 void setCurrencyFormat(boolean swCurrencyFormat)
          Set to true if this object has to represent a currency format.
 void setDecimalFormatSymbols(java.text.DecimalFormatSymbols dfsSymbols)
          Sets the decimal format symbols to a clone of the argument; later changes to the argument thus have no influence on the BigDecimalFormat.
 void setDecimalSeparatorAlwaysShown(boolean swDecimalSeparatorAlwaysShown)
          Sets wether the decimal separator is to be shown with integer numbers.
 void setExponentialNotation(boolean swExponentialNotation)
          Set whether or not exponentional notation is used.
 void setExponentIncrement(int iExponentIncrement)
          Sets the exponent increment used with exponential notation.
 void setExponentSignAlwaysShown(boolean swExponentSignAlwaysShown)
          Set whether the exponent sign is always shown.
 void setExponentSymbol(java.lang.String sExponentSymbol)
          Set the symbol indicating the exponent in exponential notation and localized patterns.
 void setGroupingSize(int iGroupingSize)
          Set the grouping size.
 void setMaximumDecimalPlaces(int iMaximumDecimalPlaces)
          Sets the maximum number of digits to format in the decimal fraction of a number; this value has no effect on parsing. maximumDecimalPlaces must be >= minimumDecimalPlaces.
 void setMaximumExponentDigits(int iMaximumExponentDigits)
          Set the maximum number of digits to format in the exponent value of a number with exponential notation; this value has no effect on parsing.
 void setMaximumIntegerDigits(int iMaximumIntegerDigits)
          Sets the maximum number of digits to format in the integer portion of a number; this value has no effect on parsing. maximumIntegerDigits must be >= minimumIntegerDigits.
 void setMinimumDecimalPlaces(int iMinimumDecimalPlaces)
          Sets the minimum number of digits to format in the decimal fraction of a number; this value has no effect on parsing. minimumDecimalPlaces must be <= maximumDecimalPlaces.
 void setMinimumExponentDigits(int iMinimumExponentDigits)
          Set the minimum number of digits required in the exponent value of a number with exponential notation.
 void setMinimumIntegerDigits(int iMinimumIntegerDigits)
          Sets the minimum number of digits to format in the integer portion of a number; this value has no effect on parsing. minimumIntegerDigits must be <= maximumIntegerDigits.
 void setMultiplier(int iMultiplier)
          Set the multiplier for use in percent, permill, etc.
 void setNegativePrefix(java.lang.String sNegativePrefix)
          Set the negative prefix.
 void setNegativeSuffix(java.lang.String sNegativeSuffix)
          Set the negative suffix.
 void setPaddingChar(char cPaddingChar)
          Set the character used to pad a formatted number to the padding width.
 void setPaddingPosition(int iPaddingPosition)
          Set the position at which to pad a formatted number that is shorter than the padding width.
 void setPaddingWidth(int iPaddingWidth)
          Set the width to which the output of format() is to be padded.
 void setParseIntegerOnly(boolean swParseIntegerOnly)
          Deprecated. This method is retained for compatibility with DecimalFormat only; we advise to obtain an integer number from the fully parsed ArciMath BigDecimal result, e.g. by the operation bdResult.setScale(0, roundingMode)
 void setParsingStrictness(int iParsingStrictness)
          Sets the parsing strictness for this BigDecimalFormat.
 void setPlusSign(char cPlusSign)
          Set the symbol indicating the localized plus sign.
 void setPositivePrefix(java.lang.String sPositivePrefix)
          Set the positive prefix.
 void setPositiveSuffix(java.lang.String sPositiveSuffix)
          Set the positive suffix.
 void setRetainZeroTail(boolean swRetainZeroTail)
          Set whether trailing zero digits in a number will be formatted as significand.
 void setRoundingMode(int iRoundingMode)
          Get the rounding mode used in rounding numbers to the maximum decimal places and to multiples of the smallest module, and in dividing parsed numbers by the multiplier property.
 void setSignalOverflow(boolean swSignalOverflow)
          Set whether or not overflow is signalled on formatting.
 void setSmallestModule(BigDecimal bdSmallestModule)
          Set the smallest modules to which this BigDecimalFormat rounds formatted numbers.
 void setZeroPaddingChar(int iZeroPaddingChar)
          Set the character used to replace non-significant zeroes.
 
Methods inherited from class java.text.Format
format, parseObject
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

QUOTE

public static final char QUOTE
The single quote character to embed special characters in pattern affixes

PERCENT_SIGN

public static final char PERCENT_SIGN
The PERCENT_SIGN is the standard Unicode symbol for percent. It is used in patterns. If the PERCENT_SIGN is seen in a pattern, then a multiplier of 100 is applied. The PERCENT_SIGN can be localized through the DecimalFormatSymbols.
See Also:
setMultiplier(int), setDecimalFormatSymbols(java.text.DecimalFormatSymbols)

PER_MILLE_SIGN

public static final char PER_MILLE_SIGN
The PER_MILLE_SIGN is the standard Unicode symbol for per mille. It is used in patterns. If the PER_MILLE_SIGN is seen in a pattern, then a multiplier of 1000 is applied. The PER_MILLE_SIGN can be localized through the DecimalFormatSymbols.
See Also:
setMultiplier(int), setDecimalFormatSymbols(java.text.DecimalFormatSymbols)

CURRENCY_SIGN

public static final char CURRENCY_SIGN
The CURRENCY_SIGN is the standard Unicode symbol for currency. It is used in patterns and substitued with either the currency symbol, or if it is doubled, with the international currency symbol. If the CURRENCY_SIGN is seen in a pattern, then the decimal separator is replaced with the monetary decimal separator.

The CURRENCY_SIGN is not localized.


PREFIX_FIELD

public static final int PREFIX_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the prefix field of a formatted number should be returned.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

INTEGER_FIELD

public static final int INTEGER_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the integer field of a formatted number should be returned (including zero padding characters).

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

DECIMAL_SEPARATOR_FIELD

public static final int DECIMAL_SEPARATOR_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the decimal separator of a formatted number should be returned.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

DECIMAL_FRACTION_FIELD

public static final int DECIMAL_FRACTION_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the decimal fraction of a formatted number should be returned (including zero padding characters).

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

BASE_NUMBER_FIELD

public static final int BASE_NUMBER_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the combined basenumber fields (integer + decimal separator + decimal places) of a formatted number should be returned (excluding the sign of the basenumber, which is in the affixes).

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

EXPONENT_SYMBOL_FIELD

public static final int EXPONENT_SYMBOL_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the exponent symbol of a formatted number should be returned.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

EXPONENT_SIGN_FIELD

public static final int EXPONENT_SIGN_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the exponent sign of a formatted number should be returned.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

EXPONENT_VALUE_FIELD

public static final int EXPONENT_VALUE_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the exponent value of a formatted number should be returned (including zero padding characters).

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

EXPONENT_FIELD

public static final int EXPONENT_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the combined exponent fields (symbol + sign + value) of a formatted number should be returned.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

NUMBER_FIELD

public static final int NUMBER_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the combined number fields (basenumber + exponent + padding if before exponent) of a formatted number should be returned (excluding the sign of the number, which is in the affixes).

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

SUFFIX_FIELD

public static final int SUFFIX_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the suffix field of a formatted number should be returned.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

PADDING_FIELD

public static final int PADDING_FIELD
Field constant that can be used to construct a FieldPosition object. Signifies that the position of the padding added to a formatted number should be returned, be it before or after the prefix, before the exponent, or before or after the suffix.

Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")

See Also:
"java.text.FieldPosition"

PAD_BEFORE_PREFIX

public static final int PAD_BEFORE_PREFIX
Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters before the prefix.
See Also:
setPaddingPosition(int), getPaddingPosition(), PAD_AFTER_PREFIX, PAD_BEFORE_EXPONENT, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

PAD_AFTER_PREFIX

public static final int PAD_AFTER_PREFIX
Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters after the prefix.
See Also:
setPaddingPosition(int), getPaddingPosition(), PAD_BEFORE_PREFIX, PAD_BEFORE_EXPONENT, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

PAD_BEFORE_EXPONENT

public static final int PAD_BEFORE_EXPONENT
Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters before the exponent.
See Also:
setPaddingPosition(int), getPaddingPosition(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_AFTER_SUFFIX

PAD_BEFORE_SUFFIX

public static final int PAD_BEFORE_SUFFIX
Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters before the suffix.
See Also:
setPaddingPosition(int), getPaddingPosition(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_EXPONENT, PAD_AFTER_SUFFIX

PAD_AFTER_SUFFIX

public static final int PAD_AFTER_SUFFIX
Constant for getPaddingPosition() and setPaddingPosition(), specifying to insert padding characters after the suffix.
See Also:
setPaddingPosition(int), getPaddingPosition(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_EXPONENT, PAD_BEFORE_SUFFIX

PARSE_LENIENT

public static final int PARSE_LENIENT
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), specifying lenient parsing of number Strings. This is the default parsing strictness of BigDecimalFormat.
See Also:
setParsingStrictness(int), getParsingStrictness(), PARSE_STRICT

PARSE_MATCH_PREFIX

public static final int PARSE_MATCH_PREFIX
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring a match with either the positive or the negative prefix when parsing a number String. If not set, the prefix is optional.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants, except with PARSE_MATCH_SIGN_CHARS.

See Also:
getPositivePrefix(), getNegativePrefix(), setParsingStrictness(int), getParsingStrictness(), PARSE_MATCH_SUFFIX, PARSE_MATCH_AFFIXES

PARSE_MATCH_SUFFIX

public static final int PARSE_MATCH_SUFFIX
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring a match with either the positive or the negative suffix when parsing a number String. If not set, the suffix is optional.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
getPositiveSuffix(), getNegativeSuffix(), setParsingStrictness(int), getParsingStrictness(), PARSE_MATCH_PREFIX, PARSE_MATCH_AFFIXES

PARSE_MATCH_AFFIXES

public static final int PARSE_MATCH_AFFIXES
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(). Combination of PARSE_MATCH_PREFIX and PARSE_MATCH_SUFFIX.

See Also:
setParsingStrictness(int), getParsingStrictness(), PARSE_MATCH_PREFIX, PARSE_MATCH_SUFFIX

PARSE_MATCH_PADDING_CHAR

public static final int PARSE_MATCH_PADDING_CHAR
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), accepting only the padding character set for the BigDecimalFormat as padding in a number String. If not set, the space (' ') character can also serve as padding character.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
setParsingStrictness(int), getParsingStrictness(), getPaddingChar(), PARSE_MATCH_PADDING_POS, PARSE_MATCH_PADDING_WIDTH

PARSE_MATCH_PADDING_POS

public static final int PARSE_MATCH_PADDING_POS
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring any padding in a number String to occur at the padding position set for the BigDecimalFormat. If not set, padding can occur at any of the places represented by the PAD_xxx constants, and, in addition, space padding characters are accepted either between the exponent symbol and the sign of an exponent or between the sign and the value of an exponent, unless when such is not allowed as a consequence of the PARSE_MATCH_PADDING_CHAR setting.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
setParsingStrictness(int), getParsingStrictness(), getPaddingChar(), PARSE_MATCH_PADDING_CHAR, PARSE_MATCH_PADDING_WIDTH

PARSE_MATCH_PADDING_WIDTH

public static final int PARSE_MATCH_PADDING_WIDTH
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), to enforce a correct number of padding characters. Stated otherwise, this parsing strictness constant requires a number String to match the padding width set for the BigDecimalFormat; a number String can only exceed that padding width if no padding is used (i.e. numbers that are too long but do not contain padding will be accepted). If not set, the number of padding characters is not enforced in BigDecimalFormat.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
setParsingStrictness(int), getParsingStrictness(), getPaddingChar(), PARSE_MATCH_PADDING_CHAR, PARSE_MATCH_PADDING_POS

PARSE_MATCH_SIGN_CHARS

public static final int PARSE_MATCH_SIGN_CHARS
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), allowing only the plus sign and minus sign set for the BigDecimalFormat or it's java.text.DecimalFormatSymbols as sign character in a number String. If not set, the '+' and '-' characters too are allowed as sign character in a number String. Note that if either or both the prefix or the suffix of the number String allow to determine the sign, no sign character at all is accepted.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants, except with PARSE_MATCH_PREFIX.

See Also:
getPlusSign(), "java.text.DecimalFormatSymbols.getMinusSign()", setParsingStrictness(int), getParsingStrictness()

PARSE_MATCH_SEPARATOR_CHARS

public static final int PARSE_MATCH_SEPARATOR_CHARS
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), allowing only the grouping separator and the decimal (or monetary decimal for currency formats) separator characters set for the BigDecimalFormat's java.text.DecimalFormatSymbols as separator characters in a number String. If not set, both the characters '.' and ',' are also accepted as grouping or decimal separator, if that does not cause ambiguity.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
"java.text.DecimalFormatSymbols.getGroupingSeparator()", "java.text.DecimalFormatSymbols.getDecimalSeparator()", "java.text.DecimalFormatSymbols.getMonetaryDecimalSeparator() (Java 2)", getCurrencyFormat(), setParsingStrictness(int), getParsingStrictness(), PARSE_MATCH_GROUPING

PARSE_MATCH_EXPONENT_SYMBOL

public static final int PARSE_MATCH_EXPONENT_SYMBOL
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), allowing only the exponent symbol set for the BigDecimalFormat as exponent symbol in a number String. If not set, the characters 'e' and 'E' are also accepted as exponent symbol in a number String.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
getExponentSymbol(), setParsingStrictness(int), getParsingStrictness()

PARSE_MATCH_GROUPING

public static final int PARSE_MATCH_GROUPING
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(), requiring digit grouping if the grouping size set for the BigDecimalFormat is not zero. If not set, grouping separators may be omitted in a number String to be parsed. But even if not set, if grouping separators are used in a number String, they are always required to match the grouping size set for the BigDecimalFormat, as a common measure to intercept typing errors.

This constant can be combined ('|' operator) with other PARSE_MATCH_xxx constants.

See Also:
getGroupingSize(), setParsingStrictness(int), getParsingStrictness(), PARSE_MATCH_SEPARATOR_CHARS

PARSE_STRICT

public static final int PARSE_STRICT
Parsing strictness constant for getParsingStrictness() and setParsingStrictness(). Sets strict parsing close to DecimalFormat policy (but with stricter grouping size checking). Note that even with this setting, numbers that are longer than expressed in the format pattern, or that contain a decimal part if such is not in the pattern and parseIntegerOnly is not set, will still be parsed completely (as it is also done in DecimalFormat).

Combination of PARSE_MATCH_AFFIXES, PARSE_MATCH_PADDING_CHAR, PARSE_MATCH_PADDING_POS, PARSE_MATCH_PADDING_WIDTH, PARSE_MATCH_SIGN_CHARS, PARSE_MATCH_SEPARATOR_CHARS, PARSE_MATCH_EXPONENT_SYMBOL, and PARSE_MATCH_GROUPING.

See Also:
setParsingStrictness(int), getParsingStrictness(), PARSE_LENIENT, PARSE_MATCH_AFFIXES, PARSE_MATCH_SIGN_CHARS, PARSE_MATCH_PADDING_CHAR, PARSE_MATCH_PADDING_POS, PARSE_MATCH_PADDING_WIDTH, PARSE_MATCH_SEPARATOR_CHARS, PARSE_MATCH_GROUPING, PARSE_MATCH_EXPONENT_SYMBOL
Constructor Detail

BigDecimalFormat

public BigDecimalFormat()
Create a BigDecimalFormat using the default pattern and symbols for the default locale. Equivalent to BigDecimalFormat(new DecimalFormat()). This is a convenient way to obtain a BigDecimalFormat when internationalization is not the main concern.

NOTE: See setRoundingMode for a comment on the rounding mode used.

See Also:
setRoundingMode(int), BigDecimalFormat(DecimalFormat dfmt)

BigDecimalFormat

public BigDecimalFormat(java.text.DecimalFormat dfmt)
Convenience method to construct a localized BigDecimalFormat, based on e.g. one of the standard DecimalFormat's for a given locale, obtained using the factory methods on NumberFormat such as getInstance or getCurrencyInstance. The BigDecimalFormat uses the DecimalFormat's pattern, as returned by toPattern, it's DecimalFormatSymbols property, and it's isParseIntegerOnly property.

NOTE: See setRoundingMode for a comment on the rounding mode used.

See Also:
setRoundingMode(int), "java.text.DecimalFormat", "java.text.DecimalFormatSymbols", "java.text.NumberFormat#getInstance", "java.text.NumberFormat#getNumberInstance", "java.text.NumberFormat#getCurrencyInstance", "java.text.NumberFormat#getPercentInstance"

BigDecimalFormat

public BigDecimalFormat(java.lang.String sPattern)
Create a BigDecimalFormat from the given pattern and the symbols for the default locale. This is a convenient way to obtain a BigDecimalFormat when internationalization is not the main concern.

Parameters:
sPattern - A non-localized pattern string.
Throws:
java.lang.IllegalArgumentException - if the given pattern is invalid.

BigDecimalFormat

public BigDecimalFormat(java.lang.String sPattern,
                        java.util.Locale locale)
Create a BigDecimalFormat from the given pattern and the symbols for the given locale.

Parameters:
sPattern - A non-localized pattern string.
locale - the Locale to construct the for
Throws:
java.lang.IllegalArgumentException - if the given pattern is invalid.

BigDecimalFormat

public BigDecimalFormat(java.lang.String sPattern,
                        java.text.DecimalFormatSymbols dfsSymbols)
Create a BigDecimalFormat from the given pattern and symbols. Use this constructor when you need to completely customize the behavior of the format.

Parameters:
sPattern - a non-localized pattern string
dfsSymbols - the set of symbols to be used. A clone of this object is used by the constructed BigDecimalFormat, so any later changes to dfsSymbols have no effect on the constructed BigDecimalFormat.
Throws:
java.lang.IllegalArgumentException - if the given pattern is invalid
Method Detail

equals

public boolean equals(java.lang.Object obj)
Overrides equals
Overrides:
equals in class java.lang.Object

hashCode

public int hashCode()
Overrides hashCode
Overrides:
hashCode in class java.lang.Object

clone

public java.lang.Object clone()
Standard override; no change in semantics.
Overrides:
clone in class java.text.Format

format

public java.lang.StringBuffer format(java.lang.Object oNumber,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Formats an object to produce a string. This general routines allow polymorphic parsing and formatting for objects such as the MessageFormat. This method converts all java.lang.Number objects to ArciMath BigDecimal objects before formatting, as follows:
Overrides:
format in class java.text.Format
Parameters:
oNumber - The Number object to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
java.lang.IllegalArgumentException - when the oNumber argument is not a Number, or cannot be converted into an ArciMath BigDecimal object.
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
BigDecimal.BigDecimal(String), format(BigDecimal bd, StringBuffer sbToAppendTo, FieldPosition fPos), "java.text."

parseObject

public java.lang.Object parseObject(java.lang.String sNumber,
                                    java.text.ParsePosition ppStatus)
Parses a String to produce an ArciMath BigDecimal object.

This java.text.Format subclass supplies specific parse methods that return ArciMath BigDecimal objects (since methods can't overload on return types, these are named parse), and to which parseObject delegates.

Note:
The contract for java.text.Format.parseObject() is to discard leading whitespace. However both java.text.NumberFormat.parseObject() and DecimalFormat.parse() break that contract and do not accept leading whitespace. Even though we are a direct subclass of java.text.Format, we choose to follow the behaviour of DecimalFormat, for which BigDecimalFormat claims to be a replacement. In the default lenient parsing mode however we do accept leading space characters and leading padding characters.

Overrides:
parseObject in class java.text.Format
Parameters:
sNumber - String containing the number to parse, starting at th index of ppStatus
ppStatus - Input-Output parameter. Before calling, set ppStatus.index to the offset you want to start parsing at in sNumber. After return, ppStatus.index is the end of the text you parsed; if an error occurs, this index is unchanged.
Returns:
Object ArciMath BigDecimal object parsed from sNumber. In case of an error, returns null.
See Also:
parse(String sNumber, ParsePosition ppStatus), PARSE_LENIENT, "java.text.ParsePosition"

format

public java.lang.String format(double dNumber)
Convenience method which formats the decimal String representation of a double value to a String according to the pattern represented by this BigDecimalFormat.
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(double dNumber, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.String format(long lNumber)
Convenience method which formats a long value to a String according to the pattern represented by this BigDecimalFormat.
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(long lNumber, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.String format(java.math.BigInteger biNumber)
Convenience method which formats a BigInteger value to a String according to the pattern represented by this BigDecimalFormat.
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(java.math.BigInteger biNumber, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.String format(java.math.BigDecimal bdNumber)
Convenience method which formats a java.math.BigDecimal value to a String according to the pattern represented by this BigDecimalFormat.
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(java.math.BigDecimal bdNumber, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.String format(java.lang.Number number)
Convenience method which formats the toString() representation of a Number value to a String according to the pattern represented by this BigDecimalFormat.
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(Number number, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public final java.lang.String format(BigDecimal bdNumber)
Convenience method which formats an ArciMath BigDecimal value to a String according to the pattern represented by this BigDecimalFormat.
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(BigDecimal bdNumber, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.StringBuffer format(double dNumber,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Formats a double value, with proper rendering of NaN and Infinite values. BigDecimalFormat makes no distinction between negative and positive zero values.

Special Cases

NaN is typically formatted as the single character String \uFFFD. This String is determined by the DecimalFormatSymbols object. The empty String replaces any positive and negative prefix or suffix in the formatted output, because NaN has no sign. The NaN symbol String is regarded as the first and only part of the NUMBER_FIELD, which is neither in the BASE_NUMBER_FIELD nor in the EXPONENT_FIELD.

Infinity is typically formatted as the single character String \u221E, with the positive or negative prefixes and suffixes applied. This String is determined by the DecimalFormatSymbols object. The Infinity symbol String is regarded as the first and only part of the NUMBER_FIELD, which is neither in the BASE_NUMBER_FIELD nor in the EXPONENT_FIELD.

Parameters:
dNumber - The double value to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(BigDecimal bd, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.StringBuffer format(long lNumber,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Format a long value.

Parameters:
lNumber - The long value to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(BigDecimal bd, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.StringBuffer format(java.math.BigInteger biNumber,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Format a BigInteger number.

Parameters:
biNumber - The BigInteger value to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(BigDecimal bd, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.StringBuffer format(java.math.BigDecimal bdNumber,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Format a java.math.BigDecimal number.

Parameters:
bdNumber - The java.math.BigDecimal value to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(BigDecimal bd, StringBuffer sbToAppendTo, FieldPosition fPos)

format

public java.lang.StringBuffer format(java.lang.Number number,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Format a Number.

Parameters:
number - The Number object to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
java.lang.IllegalArgumentException - if the toString() representation of the number is not a decimal representation that is understood by ArciMath BigDecimal.
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(BigDecimal bd, StringBuffer sbToAppendTo, FieldPosition fPos), BigDecimal.BigDecimal(String)

format

public java.lang.StringBuffer format(BigDecimal bdNumber,
                                     java.lang.StringBuffer sbToAppendTo,
                                     java.text.FieldPosition fPos)
Format an ArciMath BigDecimal number. This is the workhorse to which all other format() method signatures delegate to (except for double NaN and infinity values).

Parameters:
bdNumber - The ArciMath BigDecimal value to format.
sbToAppendTo - where the text is to be appended
fPos - an alignment field, if desired, or null; on output the offsets of the alignment field are filled in. The field property of fPos must be one of the predefined xxx_FIELD constants of BigDecimalFormat.
Note: In the JDK1.1 version the FieldPosition indexes are not set (see "FieldPosition alignment")
Returns:
the value passed in as sbToAppendTo (this allows chaining, as with StringBuffer.append())
Throws:
FormatOverflowException - if signalOverflow is set and the formatted number, after truncation to maximum decimal places, does not fit into maximum integer digits and maximum exponent digits.
See Also:
format(Object oNumber, StringBuffer sbToAppendTo, FieldPosition fPos)

parse

public BigDecimal parse(java.lang.String sNumber)
                 throws java.text.ParseException
Convenience method to parse a number from a String.
Throws:
java.text.ParseException - if the specified string is invalid.
See Also:
parse(String sNumber, ParsePosition ppStatus), parseObject(String sNumber, ParsePosition ppStatus)

parse

public BigDecimal parse(java.lang.String sNumber,
                        java.text.ParsePosition ppStatus)
Returns an ArciMath BigDecimal number parsed from the String argument.

When parsing, leading whitespace is discarded (with successful parse), while trailing whitespace is left as is.

Example: Parsing " 12 xy" for a number, with ppStatus.getIndex() == 0 on entry, will parse the number 12, with ppStatus.getIndex() == 3 on exit (just before the second space). Parsing a second time will return null,since "xy" is not a number, and leave ppStatus.getIndex() at 3.

If ParseIntegerOnly is set, parsing will stop at a decimal point, thus not seeing any sign indicated by a suffix or any exponent. Does not throw an exception; if no object can be parsed, the return value is null and the index of ppStatus is unchanged.

Parameters:
sNumber - String containing the number to parse, starting at th index of ppStatus
ppStatus - Input-Output parameter. Before calling, use ppStatus.setIndex to set the offset you want to start parsing at in sNumber. After return, ppStatus.getIndex gives the end of the text you parsed; if an error occurs, this index is unchanged. In the Java 2 version, ppStatus.getErrorIndex can be checked for the position that caused the parsing error.
Returns:
ArciMath BigDecimal object parsed from sNumber. In case of an error, returns null.
See Also:
setParseIntegerOnly(boolean), parseObject(String sNumber, ParsePosition ppStatus), "java.text.ParsePosition"

applyPattern

public void applyPattern(java.lang.String sPattern)
Apply the given pattern to this BigDecimalFormat object. A pattern is a short-hand specification for the various formatting properties. The full pattern syntax is descriped in the class description. The properties set through a pattern can also be changed individually through the various API setXXX methods. The special characters and symbols to be used in the sPattern argument are the non-localized ones. On formatting, however, BigDecimalFormat always uses the localized characters and symbols, as defined in the property and the ExponentSymbol property.

Parameters:
sPattern - a formatting pattern complying with the pattern syntax for BigDecimalFormat
See Also:
applyLocalizedPattern(java.lang.String), getDecimalFormatSymbols(), getExponentSymbol(), BigDecimalFormat

applyLocalizedPattern

public void applyLocalizedPattern(java.lang.String sLocalizedPattern)
Apply the given localized pattern to this BigDecimalFormat object. A pattern is a short-hand specification for the various formatting properties. The full pattern syntax is descriped in the class description. The properties set through a pattern can also be changed individually through the various API setXXX methods. The special characters and symbols to be used in the sPattern argument are the localized ones, as defined in the property and the ExponentSymbol property.

Parameters:
sPattern - a formatting pattern complying with the pattern syntax for BigDecimalFormat
See Also:
applyLocalizedPattern(java.lang.String), getDecimalFormatSymbols(), getExponentSymbol(), BigDecimalFormat

getDecimalFormatSymbols

public java.text.DecimalFormatSymbols getDecimalFormatSymbols()
Returns a clone of the decimal format symbols used by this BigDecimalFormat; changes to the returned object thus have no influence on the BigDecimalFormat.
Returns:
clone of the used
See Also:
setDecimalFormatSymbols(java.text.DecimalFormatSymbols), "java.text.DecimalFormatSymbols"

setDecimalFormatSymbols

public void setDecimalFormatSymbols(java.text.DecimalFormatSymbols dfsSymbols)
Sets the decimal format symbols to a clone of the argument; later changes to the argument thus have no influence on the BigDecimalFormat.
Parameters:
dfsSymbols - desired
See Also:
getDecimalFormatSymbols(), "java.text.DecimalFormatSymbols"

getExponentSymbol

public java.lang.String getExponentSymbol()
Get the symbol indicating the exponent in exponential notation and localized patterns. The default value is "E".

setExponentSymbol

public void setExponentSymbol(java.lang.String sExponentSymbol)
Set the symbol indicating the exponent in exponential notation and localized patterns. This should have been a property of . common values are "E", " E", "e", "G" or " *10\^" and similar.

getPlusSign

public char getPlusSign()
Get the symbol indicating the localized plus sign. The default value is '+'.

setPlusSign

public void setPlusSign(char cPlusSign)
Set the symbol indicating the localized plus sign. This should have been a property of .

getSignalOverflow

public boolean getSignalOverflow()
Return whether or not overflow is signalled during formatting. The default value is false.
Returns:
true if this object signals formatting overflow through an FormatOverflowException
See Also:
setSignalOverflow(boolean)

setSignalOverflow

public void setSignalOverflow(boolean swSignalOverflow)
Set whether or not overflow is signalled on formatting. If true, an FormatOverflowException is thrown when a formatted number does not fit into the specified maximum integer digits and maximum exponent digits. If overflow is not signalled, formatted number Strings which overflow the maximum integer digits or maximum exponent digits can be extended beyond the expected format length; BigDecimalFormat never truncates exponent values or most-signicant digits. For fitting a number within the maximum decimal places setting, appropriate rounding is applied regardless of the signal overflow setting.

This property can only be set by this method; it can not be set, nor will it be changed, by applying a pattern.

A common use of SignalOverflow would be to switch to exponential notation if a number is too long for fixed point notation, as in this example:

 BigDecimalFormat bdfFixedPoint = new BigDecimalFormat("##,##0.####");//these patterns have
 BigDecimalFormat bdfScientific = new BigDecimalFormat("0.####E+###");//equal maximum length
 String s;
 try {
  s = bdfFixedPoint.format(myNumber);
 }
 catch (FormatOverflowException e) {
  s = bdfScientific.format(myNumber);
 }
 

See Also:
getSignalOverflow()

getPositivePrefix

public java.lang.String getPositivePrefix()
Get the positive prefix. The default value is set from the pattern.

Examples: +123, $123, sFr123


setPositivePrefix

public void setPositivePrefix(java.lang.String sPositivePrefix)
Set the positive prefix.

Parameters:
sPositivePrefix - the new prefix to use for positive numbers. Special characters like the currency sign '', the percent sign '%' and the per mille sign '' are not interpreted nor expanded, as if sPositivePrefix was put between quotes in a pattern.

getPositiveSuffix

public java.lang.String getPositiveSuffix()
Get the positive suffix. The default value is set from the pattern.

setPositiveSuffix

public void setPositiveSuffix(java.lang.String sPositiveSuffix)
Set the positive suffix.

Parameters:
sPositiveSuffix - the new prefix to use for positive numbers. Special characters like the currency sign '', the percent sign '%' and the per mille sign '' are not interpreted nor expanded, as if sPositiveSuffix was put between quotes in a pattern.

getNegativePrefix

public java.lang.String getNegativePrefix()
Get the negative prefix. The default value is set from the pattern.

setNegativePrefix

public void setNegativePrefix(java.lang.String sNegativePrefix)
Set the negative prefix.

Parameters:
sNegativePrefix - the new prefix to use for positive numbers. Special characters like the currency sign '', the percent sign '%' and the per mille sign '' are not interpreted nor expanded, as if sNegativePrefix was put between quotes in a pattern.

getNegativeSuffix

public java.lang.String getNegativeSuffix()
Get the negative suffix. The default value is set from the pattern.

setNegativeSuffix

public void setNegativeSuffix(java.lang.String sNegativeSuffix)
Set the negative suffix.

Parameters:
sNegativeSuffix - the new prefix to use for positive numbers. Special characters like the currency sign '', the percent sign '%' and the per mille sign '' are not interpreted nor expanded, as if sNegativeSuffix was put between quotes in a pattern.

getCurrencyFormat

public boolean getCurrencyFormat()
true if this object represents a currency format. This determines whether the monetary decimal separator is used instead of the normal one. The default value is true if the pattern contains an unquoted currency sign '' (Unicode value '\00A4'), else false.

setCurrencyFormat

public void setCurrencyFormat(boolean swCurrencyFormat)
Set to true if this object has to represent a currency format. This determines whether the monetary decimal separator is used instead of the normal one.

getMultiplier

public int getMultiplier()
Get the multiplier for use in percent, permill, etc. The default value is 100 if the pattern contains an unquoted percent sign, 1000 if it contains an unquoted per mille sign, and else 1.

See Also:
setMultiplier(int)

setMultiplier

public void setMultiplier(int iMultiplier)
Set the multiplier for use in percent, permill, etc.

Examples: with multiplier 100, 1.23 is formatted as if it where 123, and "123" is parsed as 1.23

Parameters:
iMultiplier - the multiplier to use.
Throws:
java.lang.IllegalArgumentException - if iMultiplier <= 0
See Also:
getMultiplier()

getGroupingSize

public int getGroupingSize()
Return the grouping size. The default value is set from the pattern.

Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "1,234,567.89", the grouping size is 3. A value of 0 means that there are no grouping separators (replacing the 'grouping used' setting of DecimalFormat).

See Also:
setGroupingSize(int), "java.text.DecimalFormat#getGroupingSeparator"

setGroupingSize

public void setGroupingSize(int iGroupingSize)
Set the grouping size. Grouping size is the number of digits between grouping separators in the integer portion of a number. For example, in the number "1,234,567.89", the grouping size is 3. A value of 0 means that there are no grouping separators (replacing the 'grouping used' setting of DecimalFormat).
Throws:
java.lang.IllegalArgumentException - if iGroupingSize < 0
See Also:
getGroupingSize(), "java.text.DecimalFormat#setGroupingSeparator"

getMaximumIntegerDigits

public int getMaximumIntegerDigits()
Returns the maximum number of digits to format in the integer portion of a number; this value has no effect on parsing. The default value is set from the pattern.
See Also:
setMaximumIntegerDigits(int), getMinimumIntegerDigits(), getSignalOverflow()

setMaximumIntegerDigits

public void setMaximumIntegerDigits(int iMaximumIntegerDigits)
Sets the maximum number of digits to format in the integer portion of a number; this value has no effect on parsing. maximumIntegerDigits must be >= minimumIntegerDigits. If the new value for maximumIntegerDigits is less than the current value of minimumIntegerDigits, then minimumIntegerDigits will also be set to the new value.

With exponential notation the maximum number of integer digits, if present and not equal to the minumum number of integer digits, specifies the exponent increment. The decimal point is shifted within the formatted number so as to keep the exponent a multiple of the set maximum number of integer digits. The most common use of exponent increments is to generate engineering notation, in which the exponent is a multiple of three.

Parameters:
iMaximumIntegerDigits - the maximum number of integer digits to be shown.
Throws:
java.lang.IllegalArgumentException - if iMaximumIntegerDigits < 0
See Also:
getMaximumIntegerDigits(), setMinimumIntegerDigits(int), setSignalOverflow(boolean)

getMinimumIntegerDigits

public int getMinimumIntegerDigits()
Returns the minimum number of digits required in the integer portion of a number. The default value is set from the pattern.

A number with insufficient integer digits will be padded with leading zero padding characters to satisfy the minimum integer digits setting.

See Also:
setMinimumIntegerDigits(int), getZeroPaddingChar(), getMaximumIntegerDigits()

setMinimumIntegerDigits

public void setMinimumIntegerDigits(int iMinimumIntegerDigits)
Sets the minimum number of digits to format in the integer portion of a number; this value has no effect on parsing. minimumIntegerDigits must be <= maximumIntegerDigits. If the new value for minimumIntegerDigits exceeds the current value of maximumIntegerDigits, then maximumIntegerDigits will also be set to the new value.

For exponential notation with exponent increments (see setExponentIncrement(int) and setMaximumIntegerDigits(int)) the minimum integer digits setting is disregarded while adjusting the exponent value. A number with insufficient integer digits will be padded with leading zero padding characters to satisfy the minimum integer digits setting.

Parameters:
iMinimumIntegerDigits - the minimum number of integer digits to be shown.
Throws:
java.lang.IllegalArgumentException - if iMinimumIntegerDigits < 0
See Also:
getMinimumIntegerDigits(), setZeroPaddingChar(int), setMaximumIntegerDigits(int)

getDecimalSeparatorAlwaysShown

public boolean getDecimalSeparatorAlwaysShown()
Returns wether the decimal separator is shown with integer numbers. The default value is true if the pattern contains a decimal separator and no decimal places specification, else false. The decimal separator will always appear before decimal places.

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345


setDecimalSeparatorAlwaysShown

public void setDecimalSeparatorAlwaysShown(boolean swDecimalSeparatorAlwaysShown)
Sets wether the decimal separator is to be shown with integer numbers. The decimal separator will always appear before decimal places.

Example: Decimal ON: 12345 -> 12345.; OFF: 12345 -> 12345


getParseIntegerOnly

public boolean getParseIntegerOnly()
Returns true if this format will parse numbers as integers only. The default value is false.

For example if '.' is the decimal separator and ParseIntegerOnly is true, the string "1234.56" would be parsed as the integer value 1234 and parsing would stop at the '.' character. Of course, the exact format accepted by the parse operation is locale dependant.

See Also:
setParseIntegerOnly(boolean)

setParseIntegerOnly

public void setParseIntegerOnly(boolean swParseIntegerOnly)
Deprecated. This method is retained for compatibility with DecimalFormat only; we advise to obtain an integer number from the fully parsed ArciMath BigDecimal result, e.g. by the operation bdResult.setScale(0, roundingMode)

Sets whether or not numbers should be parsed as integers only. If set to true, any suffix after a decimal point or any exponent will not be parsed, so

This property can only be set by this method; it can not be set, nor will it be changed, by applying a pattern.

Parameters:
swParseIntegerOnly - true if only the integer part of a number should be parsed, else false. If true, parsing will stop at the decimal point, and that position will be indicated as index of the ParsePosition argument to parse().
See Also:
getParseIntegerOnly()

getMaximumDecimalPlaces

public int getMaximumDecimalPlaces()
Returns the maximum number of digits to format in the decimal fraction of a number; this value has no effect on parsing. The default value is set from the pattern. Trailing zero digits in a number will be formatted as significant zero only if the BigDecimalFormat retains zero tails, and else as non-significant zero.
See Also:
setMaximumDecimalPlaces(int), getRetainZeroTail(), getRoundingMode()

setMaximumDecimalPlaces

public void setMaximumDecimalPlaces(int iMaximumDecimalPlaces)
Sets the maximum number of digits to format in the decimal fraction of a number; this value has no effect on parsing. maximumDecimalPlaces must be >= minimumDecimalPlaces. If the new value for maximumDecimalPlaces is less than the current value of minimumDecimalPlaces, then minimumDecimalPlaces will also be set to the new value.

Parameters:
iMaximumDecimalPlaces - the maximum number of decimal places to be shown.
Throws:
java.lang.IllegalArgumentException - if iMaximumDecimalPlaces < 0
See Also:
getMaximumDecimalPlaces(), setRetainZeroTail(boolean), setRoundingMode(int)

getMinimumDecimalPlaces

public int getMinimumDecimalPlaces()
Returns the minimum number of digits to format in the decimal fraction of a number; this value has no effect on parsing. The default value is set from the pattern.

A number with insufficient decimal places will be padded with trailing zero padding characters to satisfy the minimum decimal places setting.

See Also:
setMinimumDecimalPlaces(int), getZeroPaddingChar()

setMinimumDecimalPlaces

public void setMinimumDecimalPlaces(int iMinimumDecimalPlaces)
Sets the minimum number of digits to format in the decimal fraction of a number; this value has no effect on parsing. minimumDecimalPlaces must be <= maximumDecimalPlaces. If the new value for minimumDecimalPlaces exceeds the current value of maximumDecimalPlaces, then maximumIntegerDigits will also be set to the new value. A number with insufficient decimal places will be padded with trailing zero padding characters to satisfy the minimum decimal places setting
Parameters:
iMinimumDecimalPlaces - the minimum number of decimal places to be shown.
Throws:
java.lang.IllegalArgumentException - if iMinimumDecimalPlaces < 0
See Also:
getMinimumDecimalPlaces(), setZeroPaddingChar(int)

getRetainZeroTail

public boolean getRetainZeroTail()
Returns whether trailing zero digits in a number will be formatted as significand. If true, a pattern like "0.###" will format a number new be.arci.math.BigDecimal("1.20") as "1.20", if false as "1.2". Default value is false.

In ArciMath BigDecimal, trailing zeroes in a number are significand. In standard arithmetic trailing zeros of an operation's result are preserved, which best simulates the notation you would use when performing the operation by hand on a piece of paper, except for the division and power operators were indeed this 'natural concept of precision' makes no sense (this is in contrast to binary floating point operations and most electronic calculators, which lose the information about trailing zeros in the fractional part of results). This preservation of trailing zeros is desirable for most calculations (including financial calculations). So, for example:

 "1.20" + "1"  = "2.20"
 "1.20" - "1"  = "0.20"
 "1.20" * "1"  = "1.20"
 "1.20" / "1"  = "1.20"
 "1.20" / "2"  = "0.60"
 "1.20" / "10" = "0.12"
See Also:
setRetainZeroTail(boolean), getMaximumDecimalPlaces()

setRetainZeroTail

public void setRetainZeroTail(boolean swRetainZeroTail)
Set whether trailing zero digits in a number will be formatted as significand. This property cannot be set from a pattern.
Parameters:
swRetainZeroTail - if true, a pattern like "0.###" will format a number new be.arci.math.BigDecimal("1.20") as "1.20", if false as "1.2".
See Also:
getRetainZeroTail(), setMaximumDecimalPlaces(int)

getSmallestModule

public BigDecimal getSmallestModule()
Get the smallest modules to which this BigDecimalFormat rounds formatted numbers. The default value is null if the pattern contains no smallest module specification.
Returns:
A positive smallest module, or null if rounding to smallest modules is not in effect.
See Also:
setSmallestModule(be.arci.math.BigDecimal), getRoundingMode()

setSmallestModule

public void setSmallestModule(BigDecimal bdSmallestModule)
Set the smallest modules to which this BigDecimalFormat rounds formatted numbers.
Parameters:
bdSmallestModule - A positive non-zero smallest module, or null to disable rounding to smallest modules.
Throws:
java.lang.IllegalArgumentException - if bdSmallestModule is negative or zero.
See Also:
getSmallestModule(), setRoundingMode(int)

getRoundingMode

public int getRoundingMode()
Get the rounding mode used in rounding numbers to the maximum decimal places and to multiples of the smallest module, and in dividing parsed numbers by the multiplier property. Default value is MathContext.ROUND_HALF_UP.

Returns:
A rounding mode, one of the predefined MathContext.ROUND_xxx constants.
See Also:
setRoundingMode(int), getSmallestModule(), getMaximumDecimalPlaces(), MathContext

setRoundingMode

public void setRoundingMode(int iRoundingMode)
Get the rounding mode used in rounding numbers to the maximum decimal places and to multiples of the smallest module, and in dividing parsed numbers by the multiplier property.

NOTE: Although not documented, DecimalFormat uses the equivalent of MathContext.ROUND_HALF_EVEN for rounding to the maximum number of decimal places, and no rounding (truncation) in other places. By default BigDecimalFormat uses MathContext.ROUND_HALF_UP in calculations.

Parameters:
iRoundingMode - A rounding mode, one of the predefined MathContext.ROUND_xxx constants.
Throws:
java.lang.IllegalArgumentException - if iRoundingMode is unrecognized.
See Also:
getRoundingMode(), setSmallestModule(be.arci.math.BigDecimal), setMaximumDecimalPlaces(int), MathContext

getExponentialNotation

public boolean getExponentialNotation()
Return whether or not exponential notation is used. The default value is true if the pattern contains an exponent specification, else false.
Returns:
true if this object formats and parses exponentional notation
See Also:
setExponentialNotation(boolean), getMaximumExponentDigits(), getMinimumExponentDigits(), getExponentSymbol(), getExponentSignAlwaysShown()

setExponentialNotation

public void setExponentialNotation(boolean swExponentialNotation)
Set whether or not exponentional notation is used.
Parameters:
swExponentialNotation - true if this object formats and parses exponentional notation
See Also:
getExponentialNotation(), setMaximumExponentDigits(int), setMinimumExponentDigits(int), setExponentSymbol(java.lang.String), setExponentSignAlwaysShown(boolean)

getMaximumExponentDigits

public int getMaximumExponentDigits()
Return the maximum number of digits to format in the exponent value of a number with exponential notation; this value has no effect on parsing. The default value is set from the pattern.
Returns:
the maximum exponent digits that will be shown
See Also:
setMaximumExponentDigits(int), getExponentialNotation(), getExponentSignAlwaysShown(), getSignalOverflow()

setMaximumExponentDigits

public void setMaximumExponentDigits(int iMaximumExponentDigits)
Set the maximum number of digits to format in the exponent value of a number with exponential notation; this value has no effect on parsing. If the new value for maximumExponentDigits is less than the current value of minimumExponentDigits, then minimumExponentDigits will also be set to the new value.
Parameters:
iMaximumExponentDigits - the maximum number of exponent digits to be shown.
Throws:
java.lang.IllegalArgumentException - if iMaximumExponentDigits < 0
See Also:
getMaximumExponentDigits(), setExponentialNotation(boolean), setExponentSignAlwaysShown(boolean), setSignalOverflow(boolean)

getMinimumExponentDigits

public int getMinimumExponentDigits()
Return the minimum number of digits required in the exponent value of a number with exponential notation. The default value is set from the pattern.

If this setting is 0, no exponent (exponent symbol + sign + value) will be shown if the exponent value is zero.

Returns:
the minimum number of exponent digits that will be shown
See Also:
setMinimumExponentDigits(int), getExponentialNotation(), getExponentSignAlwaysShown(), getZeroPaddingChar()

setMinimumExponentDigits

public void setMinimumExponentDigits(int iMinimumExponentDigits)
Set the minimum number of digits required in the exponent value of a number with exponential notation. If this setting is 0, no exponent (exponent symbol + sign + value) will be shown if the exponent value is zero. If the new value for minimumExponentDigits is more than the current value of maximumExponentDigits, then maximumExponentDigits will also be set to the new value.
Parameters:
iMinimumExponentDigits - the minimum number of exponent digits that will be shown
Throws:
java.lang.IllegalArgumentException - if iMinimumExponentDigits < 0
See Also:
getMinimumExponentDigits(), setExponentialNotation(boolean), setExponentSignAlwaysShown(boolean), setZeroPaddingChar(int)

getExponentIncrement

public int getExponentIncrement()
Return the exponent increment used with exponential notation. If the pattern specifies no explicit exponent increment, the exponent increment is deduced from the maximum and minimum integer digits.

Returns:
the exponent increment used with exponential notation; if this value is 0, no exponent increment is used
See Also:
setExponentIncrement(int), getExponentialNotation(), setMaximumIntegerDigits(int)

setExponentIncrement

public void setExponentIncrement(int iExponentIncrement)
Sets the exponent increment used with exponential notation.
Parameters:
iExponentIncrement - The exponent increment. If this value is 0, the exponent increment is deduced from maximum and minimum integer digits, as in DecimalFormat: the exponent increment is then taken 0 if maximum integer digits equals minimum integer digits, and else it is the value of maximum integer digits itself.
Throws:
java.lang.IllegalArgumentException - if iExponentIncrement < 0
See Also:
getExponentIncrement(), setExponentialNotation(boolean), setMaximumIntegerDigits(int)

getExponentSignAlwaysShown

public boolean getExponentSignAlwaysShown()
Return whether the exponent sign is always shown. The default value is set to true if the pattern has a plus sign the exponent, and else false.
Returns:
true if the exponent is always prefixed with either the localized minus sign or the localized plus sign, false if only negative exponents are prefixed with the localized minus sign. The default value is true if the pattern specifies no exponential notation (this has no effect untill exponential notation is set in use).
See Also:
setExponentSignAlwaysShown(boolean), getPlusSign(), getExponentialNotation()

setExponentSignAlwaysShown

public void setExponentSignAlwaysShown(boolean swExponentSignAlwaysShown)
Set whether the exponent sign is always shown. This has no effect unless exponential notation is in use.
Parameters:
swExponentSignAlwaysShown - true if the exponent is always prefixed with either the localized minus sign or the localized plus sign, false if only negative exponents are prefixed with the localized minus sign.
See Also:
getExponentSignAlwaysShown(), setPlusSign(char), setExponentialNotation(boolean)

getZeroPaddingChar

public int getZeroPaddingChar()
Get the character used to replace non-significant zeroes. The default value is -1, meaning that non-significant zeroes are retained by format output.

Are replaced by the zero padding character as non-significant zeroes: leading zeroes in the integer part and the grouping separators enclosed by them, trailing zeroes in the decimal fraction, and leading zeroes in the exponent part, all upto the requested minimum integer digits, minimum decimal places and minimum exponent digits respectively.

Returns:
the character that replaces non-significant zeroes, or -1 if non-significant zeroes are retained by format output.
See Also:
setZeroPaddingChar(int), getMinimumIntegerDigits(), getMinimumDecimalPlaces(), getMinimumExponentDigits()

setZeroPaddingChar

public void setZeroPaddingChar(int iZeroPaddingChar)
Set the character used to replace non-significant zeroes.

Are replaced by the zero padding character as non-significant zeroes: leading zeroes in the integer part and the grouping separators enclosed by them, trailing zeroes in the decimal fraction, and leading zeroes in the exponent part, all upto the requested minimum integer digits, minimum decimal places and minimum exponent digits respectively.

This property can only be set by this method; it can not be set, nor will it be changed, by applying a pattern.

Parameters:
iZeroPaddingChar - the character used to replace non-significant zeroes, or -1 if non-significant zeroes should be retained by format output.
Throws:
java.lang.IllegalArgumentException - if iZeroPaddingChar is not -1 nor a character value
See Also:
getZeroPaddingChar(), setMinimumIntegerDigits(int), setMinimumDecimalPlaces(int), setMinimumExponentDigits(int)

getPaddingChar

public char getPaddingChar()
Get the character used to pad a formatted number to the padding width. The default value is ' ' if the pattern contains no padding specifier.
Returns:
the padding character
See Also:
setPaddingChar(char), getPaddingWidth(), getPaddingPosition()

setPaddingChar

public void setPaddingChar(char cPaddingChar)
Set the character used to pad a formatted number to the padding width.
Parameters:
cPaddingChar - the padding character
See Also:
getPaddingChar(), setPaddingWidth(int), setPaddingPosition(int)

getPaddingWidth

public int getPaddingWidth()
Get the width to which the output of format() is to be padded. The default value is zero, or, if a pattern with a padding specifier is applied, the maximum formatted number width compatible with the settings of this BigDecimalFormat (this value is returned as negative).
Returns:
the padding width, which is zero if padding is disabled. A negative return value signifies that the padding width is the maximum formatted number width compatible with the settings of this BigDecimalFormat; the actual padding width used is the absolute value of the return value.
See Also:
setPaddingWidth(int), getPaddingChar(), getPaddingPosition(), getSignalOverflow()

setPaddingWidth

public void setPaddingWidth(int iPaddingWidth)
Set the width to which the output of format() is to be padded. The value 0 means that no padding is done, the value -1 signifies that the padding width is the maximum formatted number width compatible with the settings of this BigDecimalFormat.
Parameters:
iPaddingWidth - the width to which to pad the formatted numbers with padding characters. Use the value 0 to disable padding. Use the value -1 to let this BigDecimalFormat object calculate the padding width as the maximum formatted number width compatible with it's settings.
Throws:
java.lang.IllegalArgumentException - if iPaddingWidth < -1.
See Also:
getPaddingWidth(), setPaddingChar(char), setPaddingPosition(int), setSignalOverflow(boolean)

getPaddingPosition

public int getPaddingPosition()
Get the position at which to pad a formatted number that is shorter than the padding width. The default value is PAD_BEFORE_PREFIX if the pattern contains no padding specifier.
Returns:
the padding position, one of the predefined PAD_xxx constants.
See Also:
setPaddingPosition(int), getPaddingWidth(), getPaddingChar(), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_EXPONENT, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

setPaddingPosition

public void setPaddingPosition(int iPaddingPosition)
Set the position at which to pad a formatted number that is shorter than the padding width.
Parameters:
iPaddingPosition - the padding position, one of the predefined PAD_xxx constants.
Throws:
java.lang.IllegalArgumentException - if the padding position is unrecognized
See Also:
getPaddingPosition(), setPaddingWidth(int), setPaddingChar(char), PAD_BEFORE_PREFIX, PAD_AFTER_PREFIX, PAD_BEFORE_EXPONENT, PAD_BEFORE_SUFFIX, PAD_AFTER_SUFFIX

getParsingStrictness

public int getParsingStrictness()
Returns the parsing strictness for this BigDecimalFormat. The default strictness is PARSE_LENIENT

See Also:
Parsing rules, setParsingStrictness(int), PARSE_LENIENT, PARSE_MATCH_PREFIX, PARSE_MATCH_SUFFIX, PARSE_MATCH_AFFIXES, PARSE_MATCH_SIGN_CHARS, PARSE_MATCH_PADDING_CHAR, PARSE_MATCH_PADDING_POS, PARSE_MATCH_PADDING_WIDTH, PARSE_MATCH_SEPARATOR_CHARS, PARSE_MATCH_EXPONENT_SYMBOL, PARSE_MATCH_GROUPING, PARSE_STRICT

setParsingStrictness

public void setParsingStrictness(int iParsingStrictness)
Sets the parsing strictness for this BigDecimalFormat. The default strictness is PARSE_LENIENT

Parameters:
iParsingStrictness - a combination ('|' operator) of PARSE_xxx constants.
See Also:
Parsing rules, getParsingStrictness(), PARSE_LENIENT, PARSE_MATCH_PREFIX, PARSE_MATCH_SUFFIX, PARSE_MATCH_AFFIXES, PARSE_MATCH_SIGN_CHARS, PARSE_MATCH_PADDING_CHAR, PARSE_MATCH_PADDING_POS, PARSE_MATCH_PADDING_WIDTH, PARSE_MATCH_SEPARATOR_CHARS, PARSE_MATCH_EXPONENT_SYMBOL, PARSE_MATCH_GROUPING, PARSE_STRICT

ArciMath BigDecimal v2.05
now with BigDecimalFormat