## \$%FORMAT^STRING

### M[UMPS] by Example

Approved for inclusion in a future M[UMPS] language standard.

This function formats a numeric value to match certain local preferences for the representation of numbers. The function allows for various separators, currency symbols, leading and trailing markers, et cetera.

The examples below all work with the same test value
Set B="100000.05"

Set up the formatting preferences:
Set X="FM=Z:CS=""\$"":DC=""."":SL="","":FS=""*"""
Set Z="cnsnnnsnnndnn"

FM is the local variable that specifies the format mask
CS is the currency string
DC is the decimal character
SL is left separator character
FS is the fill string

In the "mask string", the meaning of the letters is:
c = currency symbol
d = decimal separator (may occur only once in mask)
f = floating symbol
l = left justified numeric
m = money (right justified)
n = numeric
s = separator
x = spacer
- = display sign only if negative
+ = display sign always
( and ) = display negative numbers within parentheses
space = insert space for the spaces in the mask

Reference Value \$%FORMAT^STRING(B,X) "\$**100,000.05"

Change the fill character:
Set Z="+nsnnnsnnndnn",X=X_":FS=""0"""

Reference Value \$%FORMAT^STRING(B,X) "+00100,000.05"

Make the currency symbol a multi-character string:
Set Z="ccnsnnnsnnndnn"
Set X=X_":FS="" "":CS=""DM"":SL=""."":DC="","""

Reference Value \$%FORMAT^STRING(B,X) "DM  100.000,05"

Show the currency as a trailing string:
Set Z="nsnnnsnnn ccc",X=X_":CS=""ATS"""

Reference Value \$%FORMAT^STRING(B,X) "  100.000 ATS"

Note that for every format property, the last one (right-most) prevails:
Write \$Piece(X,":",1,7)
FM=Z:CS="\$":DC=".":SL=",":FS="*":FS="0":FS=" "
Write \$Piece(X,":",8,99)
CS="DM":SL=".":DC=",":CS="ATS"

Some local preferences use the currency symbol as the decimal separator:
Set X="FM=Z:DC=""\$"":SL="" "":FS="" """
Set Z="nsnnnsnnndnn"

Reference Value \$%FORMAT^STRING(B,X) "  100 000\$05"

Set X="FM=Z:DC=""."":SL="","":FS="" """
Set Z="cfsfffsffndnn"

Reference Value \$%FORMAT^STRING(-B,X) "\$  –100,000.05"

Apply a different fill character
Set T=X_":FS=""\$"""

Reference Value \$%FORMAT^STRING(B,T) "\$\$\$100,000.05"

Use parentheses to indicate negative value:
Set Z="(nnsnnnsnnndnn)",Y=X_":FS=""&"""

Reference Value \$%FORMAT^STRING(-B,Y) "(&&&100,000.05)"

Allow the parentheses to "float":
Set Z="(ffsfffsffndnn)"

Reference Value \$%FORMAT^STRING(-B,X) "   (100,000.05)"

Braces do not appear for positive values:
Set Z="(nnsnnnsnnndnn)",Y=X_":FS=""&"""

Reference Value \$%FORMAT^STRING(B,Y) " &&&100,000.05 "

Insert a separator character at specific places:
Set Z="nnsnnsnnsn",Y=X_":SL=""-"""

Reference Value \$%FORMAT^STRING(1234567,Y) "12–34–56–7"

Use multiple separators:
Set Z="nns nns",Y=X_":SL=""""""'"""

Reference Value \$%FORMAT^STRING(1210,Y) "12' 10""

Use different separators to the left and to the right of the decimal separator:
Set Z="nnnnsnnnnsnnnnsnnnndnnnnsnnnnsnnnn"
Set Y=X_":SL=""!@#"":SR=""%^"":DC="","""
Set VAL=345678901234.56789

Reference Value \$%FORMAT^STRING(VAL,Y) "     3456@7890!1234,5678%9000^000"

Right and left justification:
Set L="llsllsllsl",R="nnsnnsnnsn"
Set ^\$Job(\$Job,"FORMAT","SL")="-"

Reference Value \$%FORMAT^STRING(4567,"FM=R") "    4–56–7" \$%FORMAT^STRING(4567,"FM=L") "45–67     "

The MDC has approved code to approximate the return value of this function. Implementors are encouraged to provide more accurate and efficient code).