BigDecimal.Format Method

[Android.Runtime.Register("format", "(II)Ljava/lang/String;", "GetFormat_IIHandler", ApiSince=24)]
public virtual string? Format (int before, int after);

[<Android.Runtime.Register("format", "(II)Ljava/lang/String;", "GetFormat_IIHandler", ApiSince=24)>]
abstract member Format : int * int -> string
override this.Format : int * int -> string

Parameters

Returns

A String representing this BigDecimal, laid out according to the specified parameters

Attributes

RegisterAttribute

Remarks

Returns the String representation of this BigDecimal, modified by layout parameters.

This method is provided as a primitive for use by more sophisticated classes, such as DecimalFormat , that can apply locale-sensitive editing of the result. The level of formatting that it provides is a necessary part of the BigDecimal class as it is sensitive to and must follow the calculation and rounding rules for BigDecimal arithmetic. However, if the function is provided elsewhere, it may be removed from this class.

The parameters, for both forms of the format method are all of type int. A value of -1 for any parameter indicates that the default action or value for that parameter should be used.

The parameters, before and after, specify the number of characters to be used for the integer part and decimal part of the result respectively. Exponential notation is not used. If either parameter is -1 (which indicates the default action), the number of characters used will be exactly as many as are needed for that part.

before must be a positive number; if it is larger than is needed to contain the integer part, that part is padded on the left with blanks to the requested length. If before is not large enough to contain the integer part of the number (including the sign, for negative numbers) an exception is thrown.

after must be a non-negative number; if it is not the same size as the decimal part of the number, the number will be rounded (or extended with zeros) to fit. Specifying 0 for after will cause the number to be rounded to an integer (that is, it will have no decimal part or decimal point). The rounding method will be the default, MathContext.ROUND_HALF_UP.

Other rounding methods, and the use of exponential notation, can be selected by using #format(int,int,int,int,int,int). Using the two-parameter form of the method has exactly the same effect as using the six-parameter form with the final four parameters all being -1.

Java documentation for android.icu.math.BigDecimal.format(int, int).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.

[Android.Runtime.Register("format", "(IIIIII)Ljava/lang/String;", "GetFormat_IIIIIIHandler", ApiSince=24)]
public virtual string? Format (int before, int after, int explaces, int exdigits, int exformint, Android.Icu.Math.RoundOptions exround);

[<Android.Runtime.Register("format", "(IIIIII)Ljava/lang/String;", "GetFormat_IIIIIIHandler", ApiSince=24)>]
abstract member Format : int * int * int * int * int * Android.Icu.Math.RoundOptions -> string
override this.Format : int * int * int * int * int * Android.Icu.Math.RoundOptions -> string

Parameters

Returns

A String representing this BigDecimal, laid out according to the specified parameters

Attributes

RegisterAttribute

Remarks

Returns the String representation of this BigDecimal, modified by layout parameters and allowing exponential notation.

This method is provided as a primitive for use by more sophisticated classes, such as DecimalFormat , that can apply locale-sensitive editing of the result. The level of formatting that it provides is a necessary part of the BigDecimal class as it is sensitive to and must follow the calculation and rounding rules for BigDecimal arithmetic. However, if the function is provided elsewhere, it may be removed from this class.

The parameters are all of type int. A value of -1 for any parameter indicates that the default action or value for that parameter should be used.

The first two parameters (before and after) specify the number of characters to be used for the integer part and decimal part of the result respectively, as defined for #format(int,int). If either of these is -1 (which indicates the default action), the number of characters used will be exactly as many as are needed for that part.

The remaining parameters control the use of exponential notation and rounding. Three (explaces, exdigits, and exform) control the exponent part of the result. As before, the default action for any of these parameters may be selected by using the value -1.

explaces must be a positive number; it sets the number of places (digits after the sign of the exponent) to be used for any exponent part, the default (when explaces is -1) being to use as many as are needed. If explaces is not -1, space is always reserved for an exponent; if one is not needed (for example, if the exponent will be 0) then explaces+2 blanks are appended to the result. (This preserves vertical alignment of similarly formatted numbers in a monospace font.) If explaces is not -1 and is not large enough to contain the exponent, an exception is thrown.

exdigits sets the trigger point for use of exponential notation. If, before any rounding, the number of places needed before the decimal point exceeds exdigits, or if the absolute value of the result is less than 0.000001, then exponential form will be used, provided that exdigits was specified. When exdigits is -1, exponential notation will never be used. If 0 is specified for exdigits, exponential notation is always used unless the exponent would be 0.

exform sets the form for exponential notation (if needed). It may be either MathContext#SCIENTIFIC or MathContext#ENGINEERING. If the latter, engineering, form is requested, up to three digits (plus sign, if negative) may be needed for the integer part of the result (before ). Otherwise, only one digit (plus sign, if negative) is needed.

Finally, the sixth argument, exround, selects the rounding algorithm to be used, and must be one of the values indicated by a public constant in the MathContext class whose name starts with ROUND_ . The default (ROUND_HALF_UP) may also be selected by using the value -1, as before.

The special value MathContext.ROUND_UNNECESSARY may be used to detect whether non-zero digits are discarded -- if exround has this value than if non-zero digits would be discarded (rounded) during formatting then an ArithmeticException is thrown.

Java documentation for android.icu.math.BigDecimal.format(int, int, int, int, int, int).

Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.