The second argument of the display function, called the format string, is optional. It contains formatting codes, plus leading or trailing text, that tells the function how to display the first argument. Display function format strings are similar to those in the C programming language.
display(@pi,"Result = %-15.31E\n")
The fundamental parts of the format string are the following:
- Double quote characters ("). Like a string literal, the format string starts and ends with double-quote characters.
- The characters % and l. The format string needs to contain a conversion specification for the expression specified in the first argument. This conversion specification consists of the % character, representing the string in the first argument, followed by a lowercase l (reflecting the fact that DPL stores all numeric data as double precision numbers (l = long)).
- A display specification character, consisting of either an uppercase or lowercase e, a lowercase f, or an uppercase or lowercase g at the end of the conversion specification. The characters e, E, f, g, and G determine how the function displays the number produced by its first argument. If the character is e or E, the function displays a floating point number with an exponent. (The case of the e in the format string determines whether the exponent is displayed as an uppercase or a lowercase e.) If the last character is f, the function displays a floating point number without an exponent. If the last character is g or G, the function displays an integer or a floating point number with or without an exponent, depending on which requires the fewest number of characters.
- Optional formatting information, like the new line character \n, or specifications of field width. To start a new line after a display, type \n at any point in the argument where you would like a new line. If the format string does not include a new line character, the output will be held in memory until another display statement with a new line specification is executed. This is useful for concatenating output lines.
- To specify a field width for the display of the number represented by the expression, insert a decimal constant, called the field width, after the % sign. If the field width is preceded by a minus sign, the function left-justifies the number in the field. If you use a format string but do not specify the field width, DPL uses a field just wide enough to display the number. If you do not supply a format string, DPL uses one equivalent to "%M.Nlg". You set N, the number of File | Options | Outputs, in the Main window options. DPL makes M equal to N + 8.
- An optional precision specification. The precision specification determines the number of significant digits that the function will display. To specify the precision, insert a decimal constant preceded by a period between the % sign and the lowercase l. If you are including a field width constant in the format string, insert the precision constant after the field width constant. It must be preceded by a period. If the conversion specification ends with E, e, or f, the precision equals the number of digits displayed after the decimal point. Numbers displayed with the E and e conversion specifications include one more digit to the left of the decimal point. If the conversion specification ends with G or g, the precision equals the number of significant digits displayed, including the ones to the left of the decimal point. If you use a format string but do not specify the precision, DPL uses a default precision of 6. The display function rounds a number to the specified precision before displaying it. The maximum displayable precision is 16 digits.
- Leading or trailing text, if desired. Any text between the first " character and the conversion specification is displayed immediately before the function's first argument, whereas any text between the conversion specification and the second " character is displayed immediately after the first argument.
Consider the following expression:
display(@pi, "%lg\n")
This expression displays the number represented by @pi, just as the previously introduced unformatted expression. The g in the format string indicates that the number should be displayed with or without an exponent, depending on which is shortest, using the default precision. The example displayed @pi with six significant digits, including the digit to the left of the decimal point (3.14159) because the default precision is 6 and the conversion specification ended with a lowercase g.
Consider a program that defines the following string:
string FMT = "%10.21f\n";
The following function uses a string instead of a string literal for the format string:
display(@pi, FMT)
It specifies a field width of 10 and a precision of 2. The f in the format string causes the function to display the number without an exponent, even if the number is very large or small. The result is the following line:
3.14
Only three digits of @pi are displayed here. The first digit is preceded by six blanks because only four characters are needed to display the number, and the field width is 10. The number is right justified in the field because the conversion specification does not include a minus sign.
The format string in the next example includes text before the conversion specification and a field width of 15. The conversion specification ends with an uppercase E instead of g and includes no precision. This means that the function will display @pi with an exponent and six digits after the decimal point (the default).
display(@pi, "Result = %151E\n")
This expression displays the following line:
Result = 3.141593E+000
There are two spaces between the equals sign and the first digit of the number because the field width is 15, and 13 characters are needed to display the number with its exponent. If the number were negative, one of the spaces would be replaced by a leading minus sign. Because the conversion specification ends with an uppercase E, the function uses that character to display the exponent.
The format string in the next example includes text after the conversion specification, a field width of 8, a precision of 3, and a minus sign preceding the field width indicating that the number should be left-justified in the field.
display(@pi, "%-8.31f(Total)\n")
This produces the following line:
3.142 (Total)
There are 3 spaces between the number and the text because the field width is 8 and only 5 characters are needed to display the number.
If the first argument of the display function is an expression, the function returns a number equal to the result of that expression. You can use this number in an expression that contains the display function. This gives you a way to display a number in the middle of an analysis and then continue the analysis using that number. It is especially useful for debugging a DPL program. For example, the following expression displays a warning message if a number that depends on two values, GNP and IdleCapacityRate, is negative or 0.
value x = GNP * (1 - 2 * IdleCapacityRate); . . @if(x <= 0, display (x,"Warning: Adjusted GNP = %lg\n"),x)
The expression equals x whether or not that number is negative. When it is negative, the function @if() returns its second argument which contains the display function. The display function produces the warning and returns the value of x.
Versions: DPL Professional, DPL Enterprise, DPL Portfolio