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.

Overflow protection

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 --

Number notations and localization

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 --

Exponential Notation

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 --

Rounding

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 --

Multiples of a smallest module

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 --

Padding and alignment

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 --

FieldPosition alignment

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 --

Parsing

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 --

Patterns

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 --

Properties not set from a pattern

The following properties can only be set through the API, not through a pattern:
• decimalFormatSymbols: these are the symbols used in localized patterns, in format() and in parse()
• exponentSymbol: logically belongs to DecimalFormatSymbols
• parseIntegerOnly: is deprecated, affects parsing only
• parsingStrictness: affects parsing only, sets the degree to which a parsed number String should complie with different parts of a BigDecimalFormat pattern.
• plusSign: logically belongs to DecimalFormatSymbols
• retainZeroTail: is in a strict sense a property of ArciMath BigDecimal, which you can choose to respect in BigDecimalFormat.
• rounding mode: sets the rounding mode used in calculations for truncating formatted numbers and for applying multiplier and smallestModule
• signalOverflow: sets strict interpretation of pattern maxima
• smallestModule: can only be set through a pattern as a fixed point number, not if exponential notation is needed to specify the smallestModule
• zeroPaddingChar: we already had mixed feelings about the padding escape, so we decided not to introduce another notation for the zeroPaddingChar

-- back to contents --

Shorthand pattern syntax

• Pattern format

                      decimal separator
                             |
                     integer | decimal exponent
                    /       \|/      \  /   \
   (optional prefix)#,###,#00.0000####E+000##(optional suffix)
                        / \ /          ^
            last grouping grouping     optional, to always
                separator size         show the exponent sign
   

• '0's count minimum digits, and '0's + '#'s count maximum digits. Note that these values do not affect parsing, they serve for formatting only.
• Through the API a zero padding character can be set to replace non-significant zeroes at minimum ('0') digit positions.
• A pattern can contain an optional negative subpattern, separated from the base pattern by ';'. The negative subpattern sets only the prefix and suffix for use with negative numbers. The rest of the negative subpattern has no influence on formatting and parsing, but should constitute a valid number pattern to separate the negative prefix from the negative suffix. If there is no explicit negative subpattern, or if the specified negative prefix and suffix are identical to the positive prefix and suffix, the localized minus sign, typically '-', is prefixed to the positive prefix to form a distinct negative prefix. That is, "pre 0.00 suf" and "pre 0.00 suf;pre 0.00 suf" are equivalent to "pre 0.00 suf;-pre 0.00 suf".
  
• A single padding specifier can occur, either right before or right after prefix or suffix, or right before the exponent symbol 'E'. The padding specifier consists of the padding escape character '^', followed the padding character to use. The padding character can be any character, but should not cause ambiguity. Formatted numbers will be padded at the position of the padding specifier upto the 'natural' padding width, based on the pattern's maximum digit settings of each kind and the longest of positive and negative affixes.
• Any but the last grouping separator is ignored. The last grouping separator, if any, sets the grouping size (the number of digits to be grouped by inserting grouping separators). The parse() methods accept number Strings without grouping separators; number Strings with grouping separators must match the specified grouping size.
• If a decimal separator and no decimal digits are specified, decimal separator is set true.
• if no exponent is specified, format and parse will use fixed point notation only.
• if an exponent is specified with a maximum and no minimum exponent digits (i.e. only '#' pattern symbols), then format will only output an exponent if the exponent value is not 0.
• Non-zero instead of '0' digits in the integer and decimal fraction part of a pattern set the 'smallest module', e.g. the smallest coin in a currency, to which formatted numbers will be rounded. In an exponential format, only a fixed point smallest module can be specified through the pattern (an exponent of 10 for the smallest modules cannot be specified through the pattern, but can be specified through the API).
• Non-zero instead of '0' digits in the exponent part of a pattern set the 'exponent increment'; the decimal point in formatted numbers will be shifted to make the displayed exponent a multiple of the exponent increment. The most common use of this is to generate the above mentioned engineering notation, in which the exponent is incremented in steps of 3, by shifting 1 to 3 digits into the integer field.
• If the pattern contains an exponent specifier that does not specify an exponent increment, the exponent increment will be set to the maximum number of integer digits, if different than the minimum number of integer digits, for compatibility with DecimalFormat patterns. This in fact is the only use for a maximum integer digits setting with exponential notation, for otherwise exponent adjustments are made to fix the number of formatted integer digits to the minimum integer digits setting.
• a positive prefix or suffix pattern containing '%' or '‰' (Unicode '\2030') sets percent or permille notation: formatted numbers are multiplied by 100 or 1000, and parsed numbers are divided by the same.
• a positive prefix or suffix pattern containing '¤' (Unicode '\00A4') or '¤¤' sets currency notation: the monetary decimal separator is used instead of the plain decimal separator, and '¤' is replaced by the currency symbol, '¤¤' by the international currency symbol for the locale.
• Special characters in prefix and suffix can be enclosed in single quotes to avoid misinterpretation.
• A single quote in prefix, suffix or padding specifier that has to appear as such, needs to be repeated twice.

-- back to contents --

Full Pattern grammar



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+





• The negPattern must be a valid subPattern, but all elements except prefix and suffix are ignored.
• If no explicit negPattern is given, or if both it's prefix and suffix equal those of posPattern, the String concatenation "-" + posPattern is taken as implicit negPattern.
• Maximum integer digits is set from (maxIntDigits + minIntDigits)
  Maximum decimal places is set from (maxDecPlaces + minDecPlaces)
  Maximum exponent digits is set from (maxExpDigits + minExpDigits)
  Note that these values do not affect parsing, they serve for formatting only.
• All groupingSep in an integer part except the last one are ignored.
• The first nonZeroDigit in the fixedPoint part starts the specification of the smallest modulus.
• The first nonZeroDigit in the exponentValue part starts the explicit specification of the exponent increment.
• A maxIntDigits setting with a pattern for exponential notation implicitely sets the exponent increment in absence of an explicit one.
• The plusSign in exponent makes format() to always print the sign of the exponent value; else only the sign for negative exponent values is printed.
• On formatting non-significant zero digits are omitted at digitPlace positions.
• On formatting non-significant zero digits are replaced by the zero padding character, if set, at zeroDigit positions.
• Patterns with only maxIntDigits and/or maxDecPlaces, and no minIntDigits nor minDecPlaces, format 0 number values with printing at least 1 zero digit.
• If exponentValue has only maxExpDigits and no minExpDigits, the exponent symbol and sign are omitted if the exponent value is zero.
• An unquoted percent in the positive subpattern sets percent notation, with a multiplier of 100.
• An unquoted perMille in the positive subpattern sets per mille notation, with a multiplier of 1000.
• An unquoted currencySign in the positive subpattern sets national currency notation, where the decimal separator is replaced by the monetary decimal separator and the currencySign is expanded into the localized national currency symbol. currencySign symbols in a negPattern are expanded, but do not set the currency notation status.
• An unquoted ( currencySign currencySign ) symbol in the positive subpattern sets international currency notation, where the decimal separator is replaced by the monetary decimal separator and the ( currencySign currencySign ) symbol is expanded into the international currency symbol. ( currencySign currencySign) symbols in a negPattern are expanded, but do not set the currency notation status.
• The exponentSymbol can appear unquoted in affix, unless when a suffix has to start with what can be parsed as a valid exponent specification.
• The above grammar is not complete: in affix unquoted specialChar is accepted if it does not cause ambiguity (e.g. a digit can be specified unquoted in a suffix if it cannot be considered as part of a number or paddedNumber, but not in a prefix, for there it would start the number or paddedNumber part).
• NEW
  As a workaround for a bug in JDK1.1.x's method java.text.DecimalFormat.toPattern(), which is used in constructing a BigDecimalFormat from a DecimalFormat, we consider an unquoted decimalSep in a prefix as part of the prefix, unless when immediately followed by a digit or digitPlace.

-- back to contents --

Examples

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:

• The java.lang wrapper classes for primitive numeric integer types by their longValue()
• The java.lang wrapper classes for primitive numeric floating point types by the decimal String representation of their doubleValue()
• the java.math.BigInteger and java.math.BigDecimal types by direct conversion to ArciMath BigDecimal.
• Other java.lang.Number subclasses by their toString() representation, if that is accepted by the ArciMath BigDecimal(String) constructor. For example IBM's BigDecimal implementation (com.ibm.math.BigDecimal) can be formatted this way.

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

• The sign of the number String should be in the prefix
• This setting should not be used with exponential notation

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