format Function

               format(value, picture)

The format function provides editting functions on values. It takes two arguments. The first is the value to be editted - value. If the second argument is omitted, format simply converts value to string. The second argument is a edit string describing the editting desired - picture. There are two types of pictures - string and numeric.

String Picture

A string picture is used to edit a string value. The value argument is converted to a string and editted using the picture argument.

The picture string is scanned and each character - x or X, is is replaced by a character from the value string. Any other characters in the picture string are left unchanged. The value string is extended with spaces as needed.

Examples:

  Expression                               Result
  format('abc', 'x x x')                   'a b c'
  format('8005551212', '(XXX) XXX-XXXX')   '(800) 555-1212'
  format('xyz', '*x*x*x*x*')               '*x*y*z* *'

Numeric Picture

A numeric picture is used to edit a numeric value. The value argument is converted to numeric and editted using the picture argument.

A numeric picture string is scanned and each character - 9, is replaced by digit from the numeric value. Normally, other characters in the picture are left unchanged. If a decimal character (.) is found in the picture string, the digits of the numeric value are arranged around it, otherwise only the integral portion of the numeric value is used. The numeric value is extended on the left and right of the decimal character with zeros as needed.

Examples:

  Expression                               Result
  format(12.34, '999.9')                   '012.3'
  format(12.34, '99.999')                  '12.340'
  format(12.34, '9,999')                   '0,012'
  format(.1234, '.9999')                   '.1234'
  format(12.34, '9.9999')                  '?.????'

Note: As shown in the last example, signficance overflow is indicated by question mark characters.

Zero Suppression

For zero suppression to the left of the decimal place, the 0 character is used. If the corresponding digit from the numeric value is zero and previous digits were zero, it is replaced by a space. Additionally, any trailing characters up to the next 0, 9 or decimal character are replaced by spaces.

Examples:

  Expression                               Result
  format(12.34, '000.9')                   ' 12.3'
  format(12.34, '0,999')                   '  012'
  format(.1234, '0,000.9999')              '     .1234'
  format(.1234, '0,009.9999')              '    0.1234'
  format(10196, '09/09/09')                ' 1/ 1/96'

Trailing Sign

The sign of a numeric value is not shown unless a sign character is used in the picture string. Signs may be trailing, leading or floating. A trailing sign is indicated by plus (+) or minus (-) character immediately following the last 0, 9 or decimal character.

The minus (-) character is not replaced when the numeric value is negative and is replaced by a space when the numeric value is zero or postive. The plus (+) character is not replaced when the numeric value is zero or postive and is replaced by a minus (-) character when the numeric value is negative. Examples:

  Expression                               Result
  format(12.34, '0,000.99-')               '   12.34 '
  format(-12.34, '0,000.99-')              '   12.34-'
  format(12.34, '0,000.99+')               '   12.34+'
  format(-12.34, '0,000.99+')              '   12.34-'

Leading Sign

A leading sign is indicated by a single plus (+) or minus (-) character before numeric digits. The replacement is the same as with a trailing sign.

Parentheses may also be a leading sign. If a leading left parenthesis - (, is found, it is replaced by a space when the numeric value is zero or positive. When the leading left parenthesis is used, a trailing right parenthesis - ), is also replaced by a space when the numeric value is not negative.

Examples:

  Expression                               Result
  format(12.34, '-0,000.99')               '    12.34'
  format(-12.34, '-0,000.99')              '-   12.34'
  format(12.34, '+0,000.99')               '+   12.34'
  format(-12.34, '+0,000.99')              '-   12.34'
  format(12.34, '(0,000.99)')              '    12.34 '
  format(-12.34, '(0,000.99)')             '(   12.34)'

Floating Sign

The sign characters - minus (-), plus (+) and left parenthesis can also 'float' over zero suppressed digits and characters. A floating sign is indicated by two successive sign characters. Starting with the repeated sign character, subsequent sign characters operate like the zero suppession character - 0, replacing the sign character and intervening characters with spaces for leading zero digits.

The leftmost non-zero suppressed digit or the decimal place is preceded by the appropriate sign character. Sign floating is terminated by a 0, 9 or decimal character.

Examples:

  Expression                               Result
  format(12.34, '--,---.99')               '    12.34'
  format(-12.34, '--,---.99')              '   -12.34'
  format(12.34, '++,+++.99')               '   +12.34'
  format(-12.34, '++,+++.99')              '   -12.34'
  format(12.34, '((,(((.99)')              '    12.34 '
  format(-12.34, '((,(((.99)')             '   (12.34)'

Floating Currency Symbol

Special symbol characters used for currency - $, * and #, may also be floated. A floating currency symbol is indicated by two successive currency symbols. The symbol over zero suppressed characters in the same manner as a floating sign. The exception is * which replaces zero suppressed characters with a '*' rather than a space.

Examples:

  Expression                               Result
  format(12.34, '$$,$$$.99')               '   $12.34'
  format(12.34, '**,***.99')               '****12.34'
  format(12.34, '##,###.99')               '   #12.34'

Combined Floating Currency Symbol and Sign

If a floating sign is preceded by a single currency symbol, the currency symbol is floated to the left of the sign character.

Examples:

  Expression                               Result
  format(12.34, '$--,---.99')              '    $12.34'
  format(-12.34, '$--,---.99')             '   $-12.34'
  format(12.34, '*++,+++.99')              '****+12.34'
  format(-12.34, '*++,+++.99')             '****-12.34'
  format(12.34, '#((,(((.99)')             '    #12.34 '
  format(-12.34, '#((,(((.99)')            '   #(12.34)'

Distinguishing a String Picture from a Numeric Picture

A numeric picture is determined by scanning the picture string. If a 0, 9, floating sign or floating currency symbol is found before an x or X, the picture is a numeric picture, otherwise it is a string picture.