////
Licensed to the Apache Software Foundation (ASF) under one
or more contributor license agreements.  See the NOTICE file
distributed with this work for additional information
regarding copyright ownership.  The ASF licenses this file
to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance
with the License.  You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing,
software distributed under the License is distributed on an
"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
KIND, either express or implied.  See the License for the
specific language governing permissions and limitations
under the License.
////


== formatNumber



=== Purpose


Formats a number using the patterns defined by the {javase}java.base/java/text/DecimalFormat.html[DecimalFormat] class. Also supports attributes used in the JSTL `formatNumber` tag.


=== Examples


[source,xml]
----
<g:formatNumber number="${myNumber}" format="\\$###,##0" />
----

Example of formatting an EUR currency amount:
[source,xml]
----
<g:formatNumber number="${myCurrencyAmount}" type="currency" currencyCode="EUR" />
----

Example of formatting a USD currency amount:
[source,xml]
----
<g:formatNumber number="${myCurrencyAmount}" type="currency" currencyCode="USD" />
----

For USD, the currency symbol will be based on the locale of the request. For the "en_US" locale, the result is "$123.45" and for "fi_FI" locale, the formatting is "123,45 USD". The formatting rules come from the {javase}java.base/java/util/Currency.html[Currency] class.

Example of left padding a number with zeros:
[source,xml]
----
<g:formatNumber number="${myNumber}" type="number" minIntegerDigits="9" />
----

Example of formatting a number showing 2 fraction digits:
[source,xml]
----
<g:formatNumber number="${myNumber}" type="number" maxFractionDigits="2" />
----

Example of formatting a number showing 2 fraction digits, rounding with RoundingMode.HALF_DOWN:
[source,xml]
----
<g:formatNumber number="${myNumber}" type="number"
                maxFractionDigits="2" roundingMode="HALF_DOWN" />
----


=== Description


Attributes

* `number` (required) - The number object to format
* `format` (optional) - The formatting pattern to use for the number, see {javase}java.base/java/text/DecimalFormat.html[DecimalFormat]
* `formatName` (optional) - Look up `format` from the default MessageSource / ResourceBundle (i18n/*.properties file) with this key. Look up `format` from the default MessageSource / ResourceBundle (i18n/*.properties file) with this key. If `format` and `formatName` are empty, `format` is looked up with '`default.number.format`' key. If the key is missing, '0' formatting pattern is used.
* `type` (optional) - The type of formatter to use: 'number', 'currency' or 'percent' . `format` or `formatName` aren't used when `type` is specified.
* `locale` (optional) - Override the locale of the request , String or {javase}java.base/java/util/Locale.html[Locale] value
* `groupingUsed` (optional) - Set whether grouping will be used in this format.
* `minIntegerDigits` (optional) - Sets the minimum number of digits allowed in the integer portion of a number.
* `maxIntegerDigits` (optional) - Sets the maximum number of digits allowed in the integer portion of a number.
* `minFractionDigits` (optional) - Sets the minimum number of digits allowed in the fraction portion of a number.
* `maxFractionDigits` (optional) - Sets the maximum number of digits allowed in the fraction portion of a number.
* `currencyCode` (optional) - The standard currency code ('EUR', 'USD', etc.), uses formatting settings for the currency. type='currency' attribute is recommended.
* `currencySymbol` (optional) - Force the currency symbol to some symbol, recommended way is to use `currencyCode` attribute instead (takes symbol information from {javase}java.base/java/util/Currency.html[Currency])
* `roundingMode` (optional) - Sets the {javase}java.base/java/math/RoundingMode.html[RoundingMode] used in this DecimalFormat. Usual values: `HALF_UP`, `HALF_DOWN`. If roundingMode is `UNNECESSARY` and an `ArithemeticException` occurs, the original number formatted with default number formatting will be returned.


