16. Formatting Strings:
FMT Operator
Introduction
Format string according to the format pattern 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
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."
- {'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:
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.
- {'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.
- <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.