16. Formatting Strings:
FMT Operator

---

Introduction

Format string according to the format pattern pattern.

{string FMT pattern}

Miva Script provides the FMT operator to format strings. For example, you may have a value of which you want to display only the first four characters:

<MvASSIGN name="tex" value="t56hkl0p">

<MvEVAL EXPR="{tex FMT '4.'}">

The FMT expression contains a value (the variable tex) and a pattern, the string '4.'. FMT tries to match the pattern to the characters in the value of tex, starting at the left most character. The pattern in this example is a very simple one, and simply matches the first four characters, no matter what they are. The result of the expression will be the characters 't56h'.

Formatting patterns can contain the following components:

• A modifier that matches and displays a character.
• A '!' , which reverses the meaning of the modifier that follows it
• A number that specifies how many times the character should be matched.
• Brackets ([ and ]) which group several patterns together
• '&nnn' ,which displays the character with ASCII code nnn

Unlike patterns in some other programming languages, the whole pattern does not have to match in order to for it to have an effect. Miva Script matches as much of the pattern as it can, displays the text that was matched, and discards the rest.

FMT Patterns and Modifiers

Modifier	Action
A	Match a letter and display it in uppercase
a	Match a letter and display it in lowercase
S	Match and display a special character (the percent symbol, for example)
#	Match and display a digit
P	Match and display a digit, and if no character is found, pad a "0."
.	Match and display any character
[pattern list]	Match and display any character that matches one of the patterns inside the brackets. This is useful for accepting upper- and lower- case alpha characters, normally treated distinctly.
[Aa]	Match and display any alphabetic character as is.

Any modifiers can be preceded by a number, which causes the modifier to try to match the specified number of characters. A special case is 0, which means "Match this pattern for as long as you can."

Here are some more examples:

{'HoTMetaL' FMT 'aAa'}

Displays hOt: the pattern matches three characters; the first and third displayed in lowercase; the second displayed in uppercase.

{'HoTMetaL' FMT '8a'}

Displays hotmetal: the pattern matches eight characters; displays them in lowercase.

{'HoTMetaL' FMT '0a'}

Displays hotmetal: unlike the previous pattern, displays the whole string in lowercase even if it has more than eight characters.

{'HoTM3taL' FMT '8a'}

Displays hotm: this pattern could match up to eight letters, but it has to stop after four characters because a number is present.

Examine the following patterns:

Expression	Displays
{'HoTM3taL' FMT '0A#'}	HOTM3
{'HoTM3taL' FMT '0a#0A'}	hotm3TAL
{'HoTM3taL' FMT '6.'}	HoTM3t
{'HoTM3taL' FMT '8[Aa]'}	HoTM

Any of the pattern modifiers may also be preceded by an exclamation point, to invert the meaning of the format. If the pattern contains a number, the '!' must come before the number.

Pattern	Function
!#	Match any non-digit
!A	Match any non-alpha.
!a	Same as '!A'
!.	Match and discard any character.

Here are some examples:

{'HoTM3taL' FMT '!0#'}

Displays HoTM: the pattern matches as many non-numeric characters as it can.

{'HoTM3taL' FMT '!0#!a'}

Displays HoTM3: the pattern matches as many non-numeric characters as it can, followed by a single non-letter.

{'HoTM3taL' FMT '3.!2.0.'}

Displays HoTtaL: the pattern matches 3 characters of any type; then matches and discards two characters of any type; then matches as many characters of any type as it can.

If you enclose two or more modifiers in square brackets, '[' and ']', the pattern thus created will match any character that any of the modifiers match. The most common example of this is '[aA]', which will match an uppercase or lowercase letter and display it unmodified. Here is another example:

{'HOTM3Tal' FMT '0[A#]'}

Displays HOTM3T.

In addition to displaying characters, a formatting pattern can also insert new characters. The expression &digits; with the ASCII code digits (where digits can be up to three characters). A frequent application of this is inserting currency symbols in numbers. For example:

{'15000' FMT '3#&36;2#'}

{'100' FMT '&163;0#'

Displays 150$00 and £100 respectively. (The ASCII code for '$' is 36 and the ASCII code for '£' is 163.)

The '&digits;' expression cannot insert a character at the end of a string. One technique for working around this is to temporarily add a character to the string. for example:

{('69' $ 'x') FMT '2.&36;'}

Displays 69$.

Numbers such as monetary amounts, telephone numbers, credit card numbers and dates are often displayed with separators in order to improve readability. For example, in the U.S. and in English Canada monetary amounts are usually displayed with a comma between every three digits. The FMT operator supports a notation for specifying such separators. Here is an example:

<MvEVAL EXPR="{'80550998' FMT '3+,0#'}">

Displays 80,550,998

The characters '3+,' in the pattern above cause FMT to insert the commas. In general, the notation n+c, where n is a number and c is a character means: "Insert character c every n characters, going from right to left."

Formatting U.S./English Canadian Monetary Values

Combining format patterns specifically for displaying numbers as dollars and cents according to the conventions used in the U.S. and in English Canada is easily accomplished using FMT.

Example Code:

<MvASSIGN NAME="usmoneyfmt" VALUE="&36;3+,0#.2P">

<MvASSIGN NAME="price" VALUE="569812.3">

<MvEVAL EXPR="{price FMT usmoneyfmt}">

Displays $569,812.30

The format expression above is interpreted as follows:

• The "&36;" says: "Prepend a "$" to the unformatted string."
• The "3+," says: "Insert a comma every three digits going from right to left, starting at the decimal."
• The "0#" says: "Any number of digits are allowed going from left to right." This is not affected by any characters inserted via the currently executing FMT pattern.
• The "." says: "Match any single character (including a period or decimal)." This is still reading left to right.
• The "2P" says; "Match a digit but put a "0" (zero) if there are no more digits to match." (P is a mnemonic for "Pad," and 2P is the same as PP)

If your site administrator has installed the format pattern usmoneyfmt into your system's site variables file, the pattern can be used as a variable in any Miva Script program.