USING()

Description

USING() formats a numeric expression to match the supplied template string. The result is returned as a string.

Syntax

1. using("templateString", numericExpression)

   (e.g. a literal string of # characters such as "####.##")

2. using(templateString$, numericExpression)

   (e.g. a string variable such as colPlaces$="####.##")

Hints

The templateString only allows the "#" character to represent a number's position, and the "." (period) for the location of the decimal point. No other formatting characters are allowed in the template.

If you need thousand separators, look at Custom USING function (thousand separators)

It looks like numeric expression internally converted to Double data type before formatting. This way:

• you will get garbage beyond 17th significant digit
• you can get Float Overflow Exception if your number exceeds Double range (approximately +/- 1e307)

templateString might be string literal (string in double quotes), string variable or string expression.

Depending on templateString and numericExpression, following can happen:

• If there are more decimal digits (after decimal point) in the number than places in the template, the function will truncate the digits to match the template.
• If there are less decimal digits (after decimal point) in the number than places in the template, the function will pad number from the right with 0's.
• If there are more digits before decimal point in the number than places in the template, the function will NOT truncate the digits but prepends it with %.
• If there are less digits before decimal point in the number than places in the template, the function will pad number from the left with spaces.

print using("###.#",123.456)
'->123.5
print using("###.###",123.4)
'->123.400
print using("#.###",123.456)
'->%123.456
print using("#####.###",123.456)
'->  123.456

USING() might round the output.

USING() is very useful when listing columns of numbers where the number of digits after the decimal point may differ from one number to the next, or to right-justify numbers when displayed in columnar format in the mainwin, as when separating data with commas in the print statement.

Example

' Examples of template strings
'    "###.##"
'    template$ = "#####.###"

' Format a number while assigning to a variable
    num = 12345.6713
    newNum$ = using("#####.##", num)
    print "Here's the new number "; newNum$

' USING() in a direct print statement
    print using("#####.##", 123.4)

' Showing 'rounding' with USING()
    print using("##.##", 12.3456)    ' Produces 12.35

' Neatly formatting a column of numbers
    numList$ = "123.45 34.567 1124.78 19.9"
    numItems = 4

    for i = 1 to numItems
        num = val(word$(numList$, i))
        print "Item "; i; ":"; using("#####.##", num)
    next i

' Right-justify columnar output in the mainwin
    num = 1000.00
    print "Heading 1","Heading 2","Heading 3"
    print "-------------|-------------|-------------|"
    for i = 1 to 3
        for t = 1 to 3
            print using("#########.##",num),
        next t
        print
    next i

    end

Useful Procedures

JB can input numbers in scientific format, like 1.23e4.

However, there is no build-in way to force number output in this form.

Below is a function that does just that, with required number of digits after decimal separator.

print usingS$(123.456,2)    '->1.23e+2
print usingS$(123.456e6,2)  '->1.23e+8

'scientific USING function.
'(keep in mind that there are no more then 16 digits stored in real number (Double data type)).
function usingS$(n,prec)
  if n = 0 then usingS$="0e+0":exit function
  fmt$ = "#"+left$(".",prec>0)+left$("#################",prec)   'fmt of mantissa
  s$=left$("-",n<0)
  n=abs(n)
  log10=log(n)/log(10)
  e=int(log10)-(log10<0)    'QB like INT. Makes mantissa for negative exponents start from digit (not 0 as JB do)
  p=10^e
  if left$(using(fmt$,n/p),1)="%" then p=p*10:e = e+1
  usingS$=s$+using(fmt$,n/p) +"e"+left$("+",e>0) +str$(e)   'Excel always shows "+" for exponent
End function

See also Custom USING function (thousand separators)