NumberToText



Release:

4.6  •  5.0  •  5.1  •  5.2

NumberToText(x, format, digits, showZeroes, separators, currency, dateFormat, fullPrecision,getFrom)

Converts a number (or date-time number) to text with explicit control over the number format settings. The parameters are similar to those found on the Number Format Dialog.

If «x» is a non-numeric value (text, Null, Handles, References, etc.), it returns the value of «x» without modification.

Prior to the introduction of this function, you would need to concatenate text to the number, e.g., "" & x, during which the number format for the current object controls how the resulting number is formatted (see coercing numbers to text). This remains a perfectly good way to coerce numbers to text, but NumberToText provides additional flexibility.

Parameters

«format»
The type of format used for numbers (but not date or date/time values). It can be one of the following values (or just the first letter):
"Suffix" (e.g., 39.63K)
"Exponential" (e.g., 3.963e+004)
"General" (e.g., 39632.55)
"Fixed Point" (e.g., 39632.55)
"Integer" (e.g., 39633)
"Percent" (e.g., 3963254.89%)
"Date" (e.g., 4-Jul-2012) -- forces numbers to display as dates
"Boolean" (e.g., True)
"Hexadecimal" (e.g., 0x9ad1)
"Binary" (e.g., 0b1001101011010001)
«digits»
The number of significant digits for Suffix and Exponential formats, or the number of digits to the right of the decimal point for Fixed Point and Percent formats.
«showZeroes»
Boolean specifying whether to show trailing zeroes so that all numbers have the same number of decimal digits, even if they are zero.
«separators»
Boolean (0 or 1) controls whether to show separators. In the US, these are commas between each group of three digits (e.g., 39,632.55).
«currency»
Specifies the currency symbol to display, or the symbol and its placement relative to the digits and sign. It recognizes these templates, where $ can be replaced by any currency symbol:
"$-#"
"$#-"
"-$#"
"-#$"
"#$-"
"#-$"
"(#$)"
"($#)"
"regional"
«dateFormat»
The template used to display dates, times, or date-time numbers. It substitutes these patterns, and anything else is printed literally.
"SHORT", "ABBREV", "LONG", "TIME", "DATETIME": regional-specific standard formats.
y, yy, yyyy: The year. y = two digits, no leading zero. yy = two digits. yyyy = four digits.
M, MM: The month number, without or with leading zero.
MMM, MMMM: The month name, abbreviated or full ("Jan" or "January")
d, dd: The day number, without or with leading zero.
w: The weekday number
www, wwww: The weekday name, abbreviated or full ("Wed", or "Wednesday")
q: The quarter (1 thru 4)
h, hh: The numeric hour from 1 thru 12, without or with leading zero.
tt: AM or PM
H, HH: The numeric hour from 0 thru 23, without or with leading zero.
m, mm: The numeric number of minutes, from 0 to 59, without or with leading zero.
s, ss: The whole number portion of seconds, from 0 to 59, without or with leading zero.
.ssssss: The fractional seconds (up to 6 digits)
' literal text ': The literal text is shown. If you want the ' character to show, then you must double it.
«fullPrecision»
A boolean value. When set to true, the number is displayed at full precision even if this requires exceeding the number of digits specified in «digits».
«getFrom»
(New to Analytica 5.2)
A handle to an object whose stored number format should be used. If other parameters are specified, it starts with this and then the other parameters override these.

Examples

NumberToText(-1234567.89012, "Fixed Point", 1) → "-1234567.9"
NumberToText(-1234567.89012, digits: 6) → "-1.23456M"
NumberToText(0.8, "Percent", 4, showZeroes: true) → "80.0000%"
NumberToText(-594321.342, "Fixed Point", separators: true, currency: "-# USD") → "-594,321.34 USD"
NumberToText(-594321.342, "Fixed Point", separators: true, currency: "(€#)") → "(€594,321.34)"
NumberToText(594321.342 "Fixed Point", separators: true, currency: "(€#)") → "€594,321.34"
NumberToText(594321.342, "Fixed Point", separators: true, currency: "$-#") → "$594,321.34"
NumberToText(594321.342, "Suffix", 3, currency: "£") → "£594K"
NumberToText(4-Jul-2012 13:52:03, dateFormat: "www, MMMM dd, "yy 'at' hh:mm tt") → "Wed, July 04, '12 at 01:52 PM"
NumberToText(594321.342, getFrom: Handle( SomeOtherVariable ))

History

NumberToText was introduced in Analytica 4.5.

See Also

Comments


You are not allowed to post comments.