USING$ function

Purpose:

USING$ returns a string converted from a number using a specified format.

Syntax:

RetStr = USING$(FormatStr AS STRING, Number)

Return Value:

  • Data type: STRING
    RetStr The formatted Number.

Parameters:

  • Data type: STRING
    FormatStr String containing formatting template. A U.S. dollar symbol or percent sign can be appended to the formatting template as show below in Example 2.
  • Data type: Scalar
    Number Numeric expression to be formatted and converted to a string.

Remarks:

If the format string contains a "^" character, USING$ will return a scientific notation version of its numeric argument and any other characters contained in the format string will be ignored. Although USING$ will accept an LDOUBLE, that parameter is always cast, internally, to a DOUBLE before being returned as a scientific notation string.

Example 1:

PRINT USING$("^", ATN(1) * 4)
PRINT USING$("^", 12345678.12345678)

Result:

3.141592653589793E+00
1.234567812345678E+07

Example 2:

PRINT USING$("###.##$", 33.5)
PRINT USING$("###.##%", 99.99)

Result:

$33.50
99.99%

Example 3:

DIM A$

A$ = USING$("###.#",-1.123456789)                 : PRINT A$
A$ = USING$("###.##",1.123456789)                 : PRINT A$
A$ = USING$("###.###",1.123456789)                : PRINT A$
A$ = USING$("###.####",1.123456789)               : PRINT A$
A$ = USING$("###.######",1.123456789)             : PRINT A$
A$ = USING$("###.#######",1.123456789)            : PRINT A$
A$ = USING$("###.########",1.123456789)           : PRINT A$
A$ = USING$("###.#########",1.123456789)          : PRINT A$
A$ = USING$("###.##########",1.123456789)         : PRINT A$
A$ = USING$(" ###.#",1.123456789)                 : PRINT A$
A$ = USING$("  ###.##",1.123456789)               : PRINT A$
A$ = USING$("   ###.###",1.123456789)             : PRINT A$
A$ = USING$("    ###.####",1.123456789)           : PRINT A$
A$ = USING$("     ###.######",1.123456789)        : PRINT A$
A$ = USING$("      ###.#######",1.123456789)      : PRINT A$
A$ = USING$("       ###.########",1.123456789)    : PRINT A$
A$ = USING$("        ###.#########",1.123456789)  : PRINT A$
A$ = USING$("         ###.#########",1.123456789) : PRINT A$

Result:

-1.1
 1.12
 1.123
 1.1235
 1.123457
 1.1234568
 1.12345679
 1.123456789
 1.1234567890
  1.1
   1.12
    1.123
     1.1235
      1.123457
       1.1234568
        1.12345679
         1.123456789
          1.123456789

Example 4:

Zeros can be used inside the format string to LEFT pad the resulting string with zeros. Commonly useful for formatting time and date strings but not limited to those.

PRINT USING$("###.##", PI)        ' Normal, no LEFT padding occurs 
PRINT USING$("  #.####", PI)      ' Explicit LEFT padding (spaces) 
PRINT USING$("000.000000", PI)    ' Pad 2 zeros on LEFT side of PI 
PRINT USING$("0000.########", PI) ' Pad 3 zeros on LEFT side of PI

Result:

3.14
  3.1416
003.141593
0003.14159265

BCX Console Sample Programs using the USING$ function.


FORMAT$ function

Purpose:

The BCX FORMAT$ function provides basic number formatting capabilities similar to the VB and PowerBasic FORMAT$ function. It takes a numeric value and a mask string and produces a formatted output string.

Syntax:

RetStr = FORMAT$(Number [, FormatStr AS STRING])

Return Value:

  • Data type: STRING
    RetStr The formatted Number.

Parameters:

  • Data type: Scalar
    Number Numeric expression to be formatted and converted to a string.
  • Data type: STRING
    FormatStr [OPTIONAL] String containing formatting template.
    👉 If the FormatStr mask is empty, the function uses "%.6Lg" format with trailing zeros removed.

Core Features:

  1. Basic Number Formatting

    • Decimal Point: Use . to specify decimal placement 
      PRINT FORMAT$(123.45, "000.00")     ' → "123.45"
    • One argument option -- displays at most 6 digits (rounded) to the right of the decimal. 
      PRINT FORMAT$(9.123456789)          ' → "9.123457"
      👉 If the FormatStr mask is empty, the function uses "%.6Lg" format with trailing zeros removed.
    • Zero Padding: Use 0 to force display of digits with leading/trailing zeros. 
      PRINT FORMAT$(5.1, "000.00")        ' → "005.10"
    • Optional Digits: Use # to display digits only if significant 
      PRINT FORMAT$(123.45, "###.##")     ' → "123.45"
PRINT FORMAT$(5.1, "###.##")        ' → "5.1"

  2. Sign Formatting

    • Space for Positive: Use + at start to show space for positive numbers, minus for negative. 
      PRINT FORMAT$(123.45, " +0.00")     ' → " 123.45"
PRINT FORMAT$(-123.45, " +0.00")    ' → "-123.45"
PRINT FORMAT$(123.45, "+0.00")      ' → "+123.45"
    • Always Show Sign: Use + to always show + or - sign

  3. Thousand Separators

    • Comma Separator: Include , in mask to add thousand separators. 
      PRINT FORMAT$(1234567.89, "#,##0.00")    ' → "1,234,567.89"
PRINT FORMAT$(1234, "#,##0")             ' → "1,234"

  4. Percentage Formatting

    • Percent Symbol: Include % to multiply by 100 and add percent sign. 
      PRINT FORMAT$(0.1234, "0.00%")      ' → "12.34%"
PRINT FORMAT$(0.05, "#.#%")         ' → "5%"

  5. Scientific Notation

    • Exponential Format: Use E+, E-, e+, or e- for scientific notation. 
      PRINT FORMAT$(1234.5, "0.00E+00")   ' → "1.23E+03"
PRINT FORMAT$(0.00123, "0.00e-00")  ' → "1.23e-03"

  6. Fill Characters

    • Custom Fill: Use * followed by a character for custom padding. 
      PRINT FORMAT$(123, "*0000")         ' → "0123"
PRINT FORMAT$(123, "* 000")         ' → " 123"

  7. Leading Spaces

    • Space Padding: Leading spaces in mask create leading spaces in output. 
      PRINT FORMAT$(123.456, "    0.00") ' → "  123.46"
PRINT FORMAT$(123.45,  "(+0.00)")  ' → "(123.45)"
PRINT FORMAT$(-123.45, "(+0.00)")  ' → "(-123.45)"

Remarks:

PRINT FORMAT$ uses LDOUBLE internally for maximum precision. Output is limited to 256 characters.

Example:

PRINT FORMAT$(9.123456789)               ' →   "9.123457"
PRINT FORMAT$(PI, "0.000000000000000")   ' →   "3.141592653589793"
PRINT FORMAT$(123.45, "000.00")          ' →   "123.45"
PRINT FORMAT$(5.1, "000.00")             ' →   "005.10"
PRINT FORMAT$(123.45, "###.##")          ' →   "123.45"
PRINT FORMAT$(5.1, "###.00")             ' →   "5.10"
PRINT FORMAT$(123.45, "(+0.00)")         ' →   "(123.45)"
PRINT FORMAT$(-123.45, "(+0.00)")        ' →   "(-123.45)"
PRINT FORMAT$(123.45, " +0.00")          ' →   " 123.45"
PRINT FORMAT$(-123.45, " +0.00")         ' →   "-123.45"
PRINT FORMAT$(123.45, "+0.00")           ' →   "+123.45"
PRINT FORMAT$(1234567.89, "#,##0.00")    ' →   "1,234,567.89"
PRINT FORMAT$(1234, "#,##0")             ' →   "1,234"
PRINT FORMAT$(1234.5, "0.00E+00")        ' →   "1.23E+03"
PRINT FORMAT$(-0.00123, "0.00e-00")      ' →   "-1.23e-03"
PRINT FORMAT$(123, "0000")               ' →   "0123"
PRINT FORMAT$(123, " 000")               ' →   " 123"
PRINT FORMAT$(12, "0000")                ' →   "0012"
PRINT FORMAT$(-123, "*0000")             ' →   "-123"
PRINT FORMAT$(1234, "*0000")             ' →   "1234"
PRINT FORMAT$(5.1, "000.00")             ' →   "005.10"
PRINT FORMAT$(5.1, "###.##")             ' →   "5.1"
PRINT FORMAT$(123.789, "000")            ' →   "124"
PRINT FORMAT$(1234567.89, "#,##0.00")    ' →   "1,234,567.89"
PRINT FORMAT$(1234, "#,##0")             ' →   "1,234"
PRINT FORMAT$(0.1234, "0.00%")           ' →   "12.34%"
PRINT FORMAT$(1.5, "#.#%")               ' →   "150%"
PRINT FORMAT$(0.0001, "0.0000")          ' →   "0.0001"
PRINT FORMAT$(999999999.99, "#,##0.00")  ' →   "999,999,999.99"