Format Strings

A format string is a DataBasic string expression that modifies a value in some way. One common use of a format string is to present a number displayed on the screen in a particular way; for example, to specify the number of decimal places, that a currency symbol should be included, and so on...

This topic describes format strings that are used to format numbers and numeric strings. Conversion codes can also be used as format strings and can in some cases be applied to non-numeric strings.

Note

A format string can be used as a format mask in the INPUT@ statement.

Syntax

{{M}alignment}{precision{scaling}}{Z}{,}{creditIndicator}{$}{formatMask}

where:

M Specifies that scaling should be performed in the same way as in English. That is, if the scaling parameter is omitted, the precision parameter is also used as the scaling factor.

alignmentSpecifies the alignment required: L for left and R for right alignment (default: left aligned).

precisionA single digit (0-9) that specifies the decimal precision; that is, the number of digits to be output following the decimal point. The processor inserts trailing zeros or rounds if necessary (see the ROUND function). If precisionis omitted or 0 is specified, the processor does not output a decimal point.

Applies to numeric data only - precisionis ignored if the data is not numeric.

You can change the decimal point symbol by executing the SET-DEC command.

scaling A single digit that specifies the scaling. The value is descaled (divided) by the specified power of 10. For example, if scaling = 2, the value is divided by 100; if scaling = 3, the value is divided by 1000, and so on. If omitted, the value is not scaled unless the M alignment modifier is used, in which case precision is also used as the scaling factor.

Applies to numeric data only - scaling is ignored if the data is not numeric.

Note

The behaviour of precision and scaling can be modified with the FSCALE and NOUPSCALE compatibility options.

Z Suppress leading zeros. Note, however, that for values between 1 and -1 the output always includes a zero preceding the decimal point.

, Use thousands separators. If specified, thousands separators will be inserted every three digits to the left of the decimal point.

You can change the display separator symbol by executing the SET-THOUS command.

creditIndicatorSpecifies the credit indicator to be used. Appropriate credit characters will be appended to or enclose the value, as follows:

C Output the literal CR after negative values.

D Output the literal DB after positive values.

E Enclose negative values in angle brackets <>.

M Output negative values with a trailing minus sign.

N Suppress minus sign for negative values.

If you specify one of these indicators, positive values are output with a trailing space.

If none of these are specified, negative values are output with a leading minus sign.

$ Use the currency symbol. The processor prefixes the value with a floating currency symbol.

Note that on some keyboards, you may need to use £ instead of $. You can change the displayed currency symbol with the SET-MONEY command.

formatMask A format mask with the following format:

{&char}{(}mask{)}

where:

&charSpecifies a fill character to be used instead of blanks, asterisks or zeros. char can be any literal character.

mask The required format. This can be any combination of literal and fill characters. The formatted value overwrites the fill characters as necessary.

The following fill characters are available:

#{count} Blank.

*{count} Asterisk.

%{count} Zero.

where countspecifies the number of fill characters (default, 1).

Notes

  • At least one fill character must be included.

  • Only one of the above can be used as a fill character in a format mask. Once a fill character has been used, it can be repeated as required, but the other fill characters will be treated as literals.

If there is no opening parenthesis, a trailing close parenthesis is treated as part of the mask.

Parentheses

In addition to having their own flexible literal specification, English and DataBasic handle literals enclosed in parentheses, as specified by the SMA standard. Therefore, if a site converts from another system to Reality, existing format strings need not be changed.

Numeric Data

If precisionor precisionand scaling parameters are specified, DataBasic attempts to convert string data to a number. Numeric data is defined as containing:

If the data contains any other characters, it is treated as a string and the precisionand scaling parameters are ignored.

Note

Although real numbers (including decimal points) can be stored in Reality, it is recommended that you store numeric values as integers and scale them as required for display.

In addition to any formatting specified, the following are applied when displaying a string that has been converted to a number:

Case Sensitivity

If keyword case-insensitivity is selected, the format string parameters can be in any combination of upper or lower case. Otherwise, they must be in upper case.

Operation

To format a value, follow it with the required format string, separating the two with a space. For example:

1000 "R$,2#9"

The result can be displayed on the screen with the PRINT or CRT statement or assigned to a variable:

PRINT 1000 "R$,2#9"
V = 1000 "R$,2#9"

If required, the format string can be assigned to a variable. For example:

FS = "R$,2#9"
N = 1000
PRINT N FS

prints the following:

$1,000.00

Multiple Format Strings

Multiple format strings can be specified contiguously and operate from left to right. For example:

PRINT " TEST MENU " 'L*42' 'R*73'

This example centres a heading within a field of asterisks 73 characters wide. It first generates a left-aligned string comprising the text " TEST MENU " (11 characters) with 31 asterisks to the right of it (42 - 11 = 31). Note that the three spaces within the quotes count as three characters. This intermediate string is then printed right-aligned with 31 asterisks to the left (73 - 42 = 31). The display is of the form:

******************************* TEST MENU *******************************

Multiple Formatted Values

You can format more than one value in a PRINT statement. Simply separate the values with a colon (:) and format them individually. For example:

X = 2; Y = 1
PRINT X "L$######" : Y "L$%5"

This example prints the following:

$2       $1000

Note, however, if you use two variables, but only one format string, the formatting applies only to the variable just before the format string. For example:

AX=12
X=34567
PRINT AX,X "R4,*25"

This example prints the following:

12                **************34,567.0000

where the last number is formatted right aligned in a field of 25 asterisks. In addition, sixteen spaces are inserted for the tab (generated by the comma separating the variable names; for details, see PRINT Using Output Formatting).

Examples of Format Strings

In the following examples, b represents a blank space.

Print statement

Value of A

Actual Output

PRINT A "L#########"

2

2bbbbbbbb

PRINT A "R#########"

2

bbbbbbbb2

PRINT A "L******"

16

16****

PRINT A "R$,2#########"

10.2

bbb$10.20

PRINT A "R$,2#9"

1000

$1,000.00

PRINT A "R,2#########"

1000

b1,000.00

PRINT A "R2#9"

1000

bb1000.00

PRINT A "R%10"

4.3

00000004.3

PRINT A "R%%%%%"

56

00056

PRINT A "L,0#####"

2300.5

2,301

PRINT A+1 "R1#8"

7.9

bbbbb8.9

PRINT A*6 "2" "R%5"

1111

66.00

PRINT A "$2"

0.1234

$0.12

PRINT A "L$#######"

0.1234

$0.1234

PRINT A "L$#3"

0.1234

$0.

PRINT A "R$,#######"

0.1234

$0.1234

PRINT A "R$,#######"

1234

b$1,234

PRINT A "#####"

999

999bb

PRINT A "R4####"

10.3333

3333

PRINT A "R$,#10"

10000000

10,000,000

PRINT A "L,#9"

1234567

1,234,567

PRINT A "L$#####"

12.3456

$12.3

PRINT A "2#5"

.1277

0.13b

PRINT A "R2#10"

-0.559

bbbbb-0.56

PRINT A "L3"

1234.56789

1234.568

PRINT A "ML3"

1234.56789

1.235

PRINT A "L33"

1234.56789

1.235

PRINT A "32"

1234.56789

12.346

PRINT A "R22$(*8)"

1234

**$12.34

PRINT A "R22($*8)"

1234

$***12.34

PRINT A "L"

".555"

0.555

PRINT A "L"

"5."

5