LSNumberFormat

Description

Formats a number using the locale convention. If mask is omitted, the number is formatted as an integer.

Syntax


LSNumberFormat(number [, mask ])

Parameters

Parameter

Description

number
The number to format

mask
LSNumberFormat mask characters apply, except that ($) dollar, (,) comma, and (.) dot are mapped to their locale-specific counterparts

Parameter	Description
number	The number to format
mask	LSNumberFormat mask characters apply, except that ($) dollar, (,) comma, and (.) dot are mapped to their locale-specific counterparts

LSNumberFormat Mask Characters

The following table lists the LSNumberFormat mask characters.

Character

Meaning

_ (underscore)
Optional digit placeholder.

9
Optional digit placeholder. Same as _, but shows decimal places more clearly.

.
Specifies the location of a mandatory decimal point.

0
Located to the left or right of a mandatory decimal point, to force padding with zeros.

( )
Places parentheses around the mask if the number is less than 0.

+
Places + in front of positive numbers, - (minus sign) in front of negative numbers.

-
Place " " (space) in front of positive, - (minus sign) in front of negative numbers.

,
Separates thousands with commas.

L,C
Specifies left-justify or center-justify a number within the width of the mask column. L or C must appear as the first character of the mask. By default, numbers are right-justified.

$
Places a dollar sign in front of the formatted number. $ must appear as the first character of the mask.

^
Separates left from right formatting.

Character	Meaning
_ (underscore)	Optional digit placeholder.
9	Optional digit placeholder. Same as _, but shows decimal places more clearly.
.	Specifies the location of a mandatory decimal point.
0	Located to the left or right of a mandatory decimal point, to force padding with zeros.
( )	Places parentheses around the mask if the number is less than 0.
+	Places + in front of positive numbers, - (minus sign) in front of negative numbers.
-	Place " " (space) in front of positive, - (minus sign) in front of negative numbers.
,	Separates thousands with commas.
L,C	Specifies left-justify or center-justify a number within the width of the mask column. L or C must appear as the first character of the mask. By default, numbers are right-justified.
$	Places a dollar sign in front of the formatted number. $ must appear as the first character of the mask.
^	Separates left from right formatting.

Note

If you do not specify a sign for the mask, positive and negative numbers do not align in columns. If you expect to display positive and negative numbers in your application, use a space or - (hyphen) to force a space in front of positive numbers and a minus sign in front of negative numbers.

Usage

The position of codes in format masks determines where they codes take effect. For example, if you place a dollar sign character 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.

In the examples below, the numbers under the masks and the formatted output are used to show the positions of characters.

Number

Mask

Result

4.37

$____.__

"$ 4.37"

4.37

_$___.__

" $4.37"

12345678

12345678

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

The positioning can also be used to show where to place a minus sign for negative numbers:

Number

Mask

Result

-4.37

-____.__

"- 4.37"

-4.37

_-___.__

" -4.37"

12345678

12345678

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

There are four positions for a code character: far left, near left, near right, and far right. The left and right positions are determined by the side of the decimal point the code character is shown on. 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.

Whether the code is placed in the far or near position is determined by the use of _ (underscore). Most code characters' effect is determined by the field they are located in. The following example shows how to use the field to determine exactly where to place 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) "

12345678

12345678

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

Example

<!--- This shows LSNumberFormat --->

<html>

<head>

<title>LSNumberFormat Example</title>

</head>



<body>

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

    <Hr noshade>

  </cfoutput>

</CFLOOP>



</body>

</html>

CFML Reference
ColdFusion Functions