Button for 1977 Button for 1984 Button for 1990 Button for 1995 Button for MDC Button for notes Button for examples
☜

$%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"

Put the sign in a "floating" position:
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).
Click here for $%FORMAT^STRING sample code to view or download the code for this function.
Click here for AllFunctions to view or download the code for all M[UMPS] Library Functions.

Button for 1977 Button for 1984 Button for 1990 Button for 1995 Button for MDC Button for notes Button for examples

Copyright © Standard Documents; 1977-2024 MUMPS Development Committee;
Copyright © Examples: 1995-2024 Ed de Moel;
Copyright © Annotations: 2003-2008 Jacquard Systems Research
Copyright © Annotations: 2008-2024 Ed de Moel.

The information in this page is NOT authoritative and subject to be modified at any moment.
Please consult the appropriate (draft) language standard for an authoritative definition.

Some specifications are "approved for inclusion in a future standard". Note that the MUMPS Development Committee cannot guarantee that such future standards will indeed be published.

This page most recently updated on 15-Nov-2023, 13:16:10.

For comments, contact Ed de Moel (demoel@jacquardsystems.com)