Library Functions -- $%FORMAT^STRING

Approved for inclusion in a future ANSI 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)

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"

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 to view or download the code for this function. Click here to view or download the code for all M[UMPS] Library Functions.

This document is © Ed de Moel, 1995-2005.
It is part of a book by Ed de Moel that is published under the title "M[UMPS] by Example" (ISBN 0-918118-42-5).
Printed copies of the book are no longer available.

This document describes the various library functions that are defined for the M[UMPS] programming language.

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

In this document, information is included that will appear in future standards.
The MDC cannot guarantee that these 'next' standards will indeed appear.