What Happened to FormattedNumberStr

One of the Newton 2.x OS Q&As
Copyright © 1997 Newton, Inc. All Rights Reserved. Newton, Newton Technology, Newton Works, the Newton, Inc. logo, the Newton Technology logo, the Light Bulb logo and MessagePad are trademarks of Newton, Inc. and may be registered in the U.S.A. and other countries. Windows is a registered trademark of Microsoft Corp. All other trademarks and company names are the intellectual property of their respective owners.


For the most recent version of the Q&As on the World Wide Web, check the URL: http://www.newton-inc.com/dev/techinfo/qa/qa.htm
If you've copied this file locally, click here to go to the main Newton Q&A page.
This document was exported on 7/23/97.

What Happened to FormattedNumberStr (2/12/96)

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.