19. Tech Note: The FormattedNumberStr Function   -- March 4, 1996
-------------------------------------------------------------
[Note: This information was originally posted to 
comp.sys.newton.programmer.

Q:      The Newton 1.x documentation and OS included a sprintf-like
function for formatting numbers called FormattedNumberStr.  The Newton
Programmer's Guide 2.0 First Edition (beta) says this function is no
longer supported.  How do I format my numbers?

A:      You may continue to use FormattedNumberStr.  Here is the
FormattedNumberStrAPI that is supported.  FormattedNumberStr should be
considered to have undefined results if passed arguments other than
those specified here.

FormattedNumberStr(number, formatString)
Returns a formatted string representation of a real number. 
number          A real number.
formatString    A string specifying how the number should be formatted.
This function works similar to the C function sprintf. The formatString
specifies how the real number should be formatted; that is, whether to
use decimal or exponential notation and how many places to include
after the decimal point. It accepts the following format specifiers:
        %f      Use decimal notation (such as "123,456.789000").
        %e      Use exponential notation (such as "1.234568e+05").
        %E      Use exponential notation (such as "1.234568E+05").
        
You can also specify a period followed by a number after the % symbol
to indicate how many places to show following the decimal point. 
("%.3f" yields "123,456.789" for example.)
Note: FormattedNumberStr uses the current values of
GetLocale().numberFormat to get the separator and decimal characters
and settings.  The example strings above are for the US English locale.

Known Problems

Other specifiers
Do not use other formatStrings.  Previous releases of the documentation
listed %g and %G as supported specifiers.  The behavior of these
specifiers has changed with the Newton 2.0 OS.  Given the similarities
to the sprintf function, it may occur to you to try other sprintf
formatting characters.   Specifiers other than above have an undefined
result and should be considered undocumented and unsupported.

Large numbers
FormattedNumberStr does not work properly for numbers larger than
1.0e24.  If the number is very large the function can cause the Newton
device to hang.

Small numbers or long numbers
If more than 15 characters of output would be generated, for example
because you are using %f with large number or a large number of digits
following the decimal, FormattedNumberStr has undefined results, and
can cause the Newton device to hang.

Rounding
FormattedNumberStr does not guarantee which direction it will round. 
In the Newton 2.0 OS, it rounds half cases down rather than up or to an
even digit.  If you need a precisely rounded number you should use the
math functions Ceiling, Floor, NearbyInt, or Round with suitable math.

Trailing decimals
In early releases of the Newton 1.0 OS, there was a bug in
FormattedNumberStr that caused a trailing decimal character to be added
when zero decimal positions was specified.  That is,
FormattedNumberStr(3.0, "%.0f") resulted in  "3." not "3".  To properly
test for and remove this unwanted extra character you must be sure to
use the character specified in the Locale settings and not assume the
decimal character will be a period.

_________________________________________________________________
Bob Ebert, Newton Developer Technical Support, Apple Computer Inc
MS 305-2A, 5 Infinite Loop, Cupertino, CA  95014   (408) 974-1945
Internet: ebert© newton.apple.com  ALink: EBERT  Fax: 408-862-1277
Disclaimer: I've been wrong before, and I'll be wrong again...