LSNumberFormat

Description

Formats a number in a locale-specific format.

Return value

A formatted number.

If no mask is specified, it returns the number formatted as an integer
If no mask is specified, truncates the decimal part; for example, it truncates 34.57 to 35
If the specified mask cannot correctly mask a number, it returns the number unchanged
If the parameter value is "" (an empty string), it returns 0.

Syntax

LSNumberFormat(number [, mask ])

History

New in ColdFusion MX: If the specified mask format cannot correctly mask a number, this function returns the number unchanged. (In earlier releases, it truncated the number or threw an error.) (If no mask is specified, ColdFusion MX truncates the decimal part as ColdFusion 5 does. For example, it truncates 1234.567 to 1235.)

New in ColdFusion MX: This function might return different formatting than in earlier releases. This function uses Java standard locale formatting rules on all platforms.

Parameters

Parameter Description

number
Number to format

mask
LSNumberFormat mask characters apply, except: dollar sign, comma, and dot are mapped to their locale-specific equivalents.

Parameter	Description
number	Number to format
mask	LSNumberFormat mask characters apply, except: dollar sign, comma, and dot are mapped to their locale-specific equivalents.

The following table lists the LSNumberFormat mask characters.

Character Meaning

_
(Underscore.) Digit placeholder.

9
Digit placeholder. (Shows decimal places more clearly than _ .)

.
Location of a mandatory decimal point (or locale-appropriate symbol).

0
Located to the left or right of a mandatory decimal point. Pads with zeros.

( )
If number is less than zero, puts parentheses around the mask.

+
Puts plus sign before positive number; minus sign before negative number.

-
Puts space before positive number; minus sign before negative number.

,
Separates every third decimal place with a comma (or locale-appropriate symbol).

L,C
Left-justifies or center-justifies number within width of mask column. First character of mask must be L or C. Default: right-justified.

$
Puts a dollar sign (or locale-appropriate symbol) before formatted number. First character of mask must be the dollar sign ($).

^
Separates left and right formatting.

Character	Meaning
_	(Underscore.) Digit placeholder.
9	Digit placeholder. (Shows decimal places more clearly than _ .)
.	Location of a mandatory decimal point (or locale-appropriate symbol).
0	Located to the left or right of a mandatory decimal point. Pads with zeros.
( )	If number is less than zero, puts parentheses around the mask.
+	Puts plus sign before positive number; minus sign before negative number.
-	Puts space before positive number; minus sign before negative number.
,	Separates every third decimal place with a comma (or locale-appropriate symbol).
L,C	Left-justifies or center-justifies number within width of mask column. First character of mask must be L or C. Default: right-justified.
$	Puts a dollar sign (or locale-appropriate symbol) before formatted number. First character of mask must be the dollar sign ($).
^	Separates left and right formatting.

Note: If you do not specify a sign for the mask, positive and negative numbers do not align in columns. To put a plus sign or space before positive numbers and a minus sign before negative numbers, use the plus or hyphen mask character, respectively.

Usage

This function uses Java standard locale formatting rules on all platforms.

The position of symbols in format masks determines where the codes take effect. For example, if you put a dollar sign at the far left of a format mask, ColdFusion displays a dollar sign at the left edge of the formatted number. If you separate the dollar sign on the left edge of the format mask by at least one underscore, ColdFusion displays the dollar sign just to the left of the digits in the formatted number.

These examples show how symbols determine formats:

Number Mask Result

4.37

$____.__

"$ 4.37"

4.37

_$___.__

" $4.37"

Number	Mask	Result
4.37	$____.__	"$ 4.37"
4.37	_$___.__	" $4.37"

The positioning can also show where to put a minus sign for negative numbers:

Number Mask Result

-4.37

-____.__

"- 4.37"

-4.37

_-___.__

" -4.37"

Number	Mask	Result
-4.37	-____.__	"- 4.37"
-4.37	_-___.__	" -4.37"

The positions for a symbol are: far left, near left, near right, and far right. The left and right positions are determined by the side of the decimal point on which the code character is shown. For formats that do not have a fixed number of decimal places, you can use a caret (^) to separate the left fields from the right.

An underscore determines whether the code is placed in the far or near position. Most code characters' effect is determined by the field in which they are located. This example shows how to specify where to put parentheses to display negative numbers:

Number Mask Result

3.21

C(__^__)

"( 3.21 )"

3.21

C__(^__)

" (3.21 )"

3.21

C(__^)__

"( 3.21) "

3.21

C__(^)__

" (3.21) "

Number	Mask	Result
3.21	C(__^__)	"( 3.21 )"
3.21	C__(^__)	" (3.21 )"
3.21	C(__^)__	"( 3.21) "
3.21	C__(^)__	" (3.21) "

To set the default display format of date, time, number, and currency values, use the SetLocale function.

When converting from string to double, to prevent rounding errors, this function adds a rounding factor of 1.5543122344752E-014 to the converted number. For example, without adding the rounding factor, converting the string value 1.275 to double with two digits of precision results in a value of 1.27499999999999999, which would be rounded up to 1.27. By adding the rounding factor, the conversion correctly results in a value of 1.28.

If you round off a double, such as 1.99499999999999999999999999999, where the last decimal is 10E-14, the rounding factor can cause an incorrect result.

Example

<h3>LSNumberFormat Example</h3>
<p>LSNumberFormat returns a number value using the locale convention. 
<!--- loop through a list of locales and show number values --->
<cfloop LIST = "#Server.Coldfusion.SupportedLocales#"
index = "locale" delimiters = ",">
  <cfset oldlocale = SetLocale(locale)>
  <cfoutput><p><b><i>#locale#</i></b><br>
    #LSNumberFormat(-1234.5678, "_________")#<br>
    #LSNumberFormat(-1234.5678, "_________.___")#<br>
    #LSNumberFormat(1234.5678, "_________")#<br>
    #LSNumberFormat(1234.5678, "_________.___")#<br>    
    #LSNumberFormat(1234.5678, "$_(_________.___)")#<br>    
    #LSNumberFormat(-1234.5678, "$_(_________.___)")#<br>    
    #LSNumberFormat(1234.5678, "+_________.___")#<br>    
    #LSNumberFormat(1234.5678, "-_________.___")#<br>    
  </cfoutput>
</cfloop>