Caché MultiValue Basic Reference
FMT
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

Formats a value for display.
Synopsis
FMT(string,format)
Arguments
string An expression that resolves to a string or number to be formatted for display.
format An expression that resolves to a string consisting of positional letter and number codes specifying the display format for string.
Description
The FMT function returns the string value formatted as specified by format. This formatting may include padding or rounding/truncating of string. The most common use for FMT is to provide a uniform display format for decimal numbers.
The format string has the following format:
wfRnm
w Optional — The overall width of the display field, specified as a positive integer. Used to impose a uniform width (number of characters) on string. Different operations are performed if w is larger or smaller than the length of string, as described below.
f Optional — A fill character, specified as a single character. (Certain fill characters, as described below, must be specified as a quoted string.) You must specify w to use f. If you specify w, but do not specify f, it defaults to the space character.
R Optional — The letter “R” or “L” specifying right or left justification. This letter code is not case sensitive. If you do not specify a letter code, FMT defaults to left justification. (The letters “T” and “U” are synonyms for “L”).
n Optional — A positive integer in the range 0 through 9 that specifies the number of fractional digits to the right of the decimal place. If you specify n, it must either be the only code in format, or it must be preceded by the letter “R” or “L”. If you do not specify n, FMT defaults to number of fractional digits in string. Zero-padding and rounding are applied as needed.
m Optional — A positive integer in the range 0 through 9 that specifies the repositioning of the decimal point. Both n and m must be specified. The number 4 specifies do not reposition the decimal point (the default). Integers higher than 4 move the decimal point to the left; integers lower than 4 move the decimal point to the right. Zero-padding and rounding are applied as needed.
There are two basic uses of format:
Formatting Numbers
For fractional numbers, the most basic format is "Rn", where “R” is either the letter “R” specifying right justification or the letter “L” specifying left justification, and n is the number of digits to the right of the decimal point to display. If string is an integer or has fewer fractional digits than n, zero padding is added. If string has more digits than n, the number is rounded to the specified number of fractional digits. If n is zero, the number is rounded to an integer and the decimal point is removed. If string is less than 1, specifying n supplies a zero (0) to the left of the decimal point. If string contains any character other than a number, the decimal point character, or a plus or minus sign, FMT does no zero padding or rounding.
A more complex example of format is "10#R5", where “10” is the overall width of the display field elements, “#” is the fill character to use to fill out a display field element. Because “R” indicates right justification, these fill characters will appear to the left of the string value. The n value of 5 indicates that the string value is to have 5 digits to the right of the decimal place. When an n value is present, FMT only formats a number; a non-numeric string is returned unchanged.
If string is 0, FMT applies numeric formatting; it returns the value zero with n fractional digits and m shifting of the decimal point. If string is the null string (""), FMT numeric formatting returns the null string. This null string behavior is emulation-dependent: Caché, jBASE, and UniData emulations treat a null string as null. The other MultiValue emulations treat a null string as zero, and apply numeric formatting.
Formatting Strings
For strings, the most basic format is "wf", where “w” is an integer specifying width and f is a literal fill character (for example "9^"). You can use w (width) and f (fill) formatting to make a display field a standard width. By default, the justification is “L” (left); you can, of course, specify “R” for right justification.
The w (width) value may be larger than, equal to, or smaller than the number of characters (including the decimal point) of string. If string is a fractional number, w is applied after FMT adjusts the number of fractional digits (by rounding or zero padding).
The fill character is optional; if omitted, filling is done with blank spaces. The fill character cannot be the same as the format string delimiter character. If the fill character is a number, the backslash (\), or the letters “L”, “R”, “T”, or “U” it must be enclosed in string delimiter quotes that are different than the format string. For example: "10'0'R2". You cannot use the backslash as a string delimiter for the fill character.
Implicit Formatting
The same formatting codes can be used with the CRT, PRINT, or DISPLAY commands. This is known as implicit formatting, because the FMT function is not specified. For example:
PRINT 1.2 "R4"           ;! Returns 1.2000
Which is exactly equivalent to:
PRINT FMT(1.2,"R4")      ;! Returns 1.2000
The formatting codes apply only to the argument that they immediately precede. For example, the following two statements are functionally identical:
CRT "Over":"There" "R#20"
CRT "Over":FMT("There","R#20")
Implicit formatting is just one of the ways that these commands can interpret a second argument. Many of the OCONV function conversion codes can also be used with implicit (or explicit) formatting. For example, date conversion:
  PRINT OCONV(14100,"D");   ! "08 AUG 2006"
  PRINT 14100 "D";          ! "08 AUG 2006"
  PRINT FMT(14100,"D");     ! "08 AUG 2006"
Because the letter codes “R” and “L” are used as formatting (FMT) codes, the corresponding OCONV conversion codes cannot be used for implicit formatting.
An expression can be used to specify an implicit formatting string, with the following limitation: a Caché global variable cannot be used for implicit formatting. This is because the caret (^) that Caché uses to indicate a global is often interpreted in these contexts as the exponentiation operator. A Caché global can be used for explicit formatting in the FMT function.
Examples
The following examples use “Rn” formatting to format a numeric values so that it displays 4 decimal digits. Note that both zero padding and rounding are performed as needed:
PRINT FMT(1.2,"R4");      ! Returns 1.2000
PRINT FMT(1.77777,"R4");  ! Returns 1.7778
PRINT FMT(.4,"R4");       ! Returns 0.4000
PRINT FMT(0,"R4");        ! Returns 0.0000
See Also