Difference between revisions of "SHIP:Sail:toString"

Revision as of 07:34, 16 February 2015

See Also:

• Sail Home
• Sail Functions
• Sail String Functions
• length, subStr, subStringtoLowerCase, toUpperCase

Prototype

String toString(Integer number[, Integer width[, Integer radix[, leadSymbolOption ]]]);

String toString(Float number[, Integer precision[, Integer width[, leadSymbolOption]]]);

Parameters/Return Value

Parameter	Data Type	Description
number	Integer	The number (or any expression returning number) to convert
width	Integer	The desired minimum width (prior to any '.') of the number, including any "-" sign; leading '0's are added to ensure this minimum width. Default is 1.
radix	Integer	For Integer values, the radix of the string from 2 through 36; 10 (default) is decimal, 16 is hex, 2 is binary, etc.
precision	Integer	The number of digits shown after the decimal place for Float values; if not specified, defaults to 0 and the '.' is not shown.
leadSymbolOption	Byte	Negative numbers are always prefixed with '-'. This option controls what leading symbol (if any) is used when the number is positive. (5.0.132+) 0 (default) adds a leading space in order to have +ve and -ve numbers indent the same visually 1 adds a '+' sign 2 adds no prefix symbol.
Return	String	resultant string

Detailed Description

The toString function returns the string equivalent of a number. Optional radix and width parameters allow conversion into a different base (for instance, base 16 hexadecimal) and left padding to a specific width.

Supported radices are anything from 2 to 36. Radices beyond 16 (i.e. hex) continue to use the ASCII alphabet ('G', 'H', ..., 'Z') for a total of 36 possible characters. Using a non-supported radix reverts to the default radix of base 10.

The width of the resulting string is optionally specified by the width parameter. Zero or a negative value for width is invalid and ignored. This enables function calls such as toString(33,0,16) which means convert the number 33 to a hex string ("21") without regard to the resulting width of the string.

If the resulting string is larger than the requested width, the requested width parameter will be ignored.

Positive Numbers

Positive numbers are left-padded with "0" to reach the desired width. In the absence of a valid width specifier, positive numbers never start with a "0" unless the value is 0.

Negative Numbers

Negative numbers are treated differently in base 10 vs. other radices. In base 10, a negative number is prefixed by the minus ("-") sign. In other radices, the string is sign extended with the character (radix-1), for example the "F" character in hexadecimal.

In absence of a valid width specifier, non-decimal negative numbers are expressed as if they were full 32-bit signed values. For example, toString(-1,0,16) returns "FFFFFFFF", the full 32-bit sign extended representation.

Width Parameter and Negative Numbers

Strings are left-padded to fill the width (if valid and requested).

In decimal (base 10), negative numbers begin with the "-" sign in the first character, followed by some number of 0s followed by the number. For example, toString(-5,5,10) results in "-0005". The minus sign is counted in the character count within the desired width. If the resulting string cannot fit within the width requested, the width parameter will be ignored. For example, toString(-1234,3,10) results in "-1234" (ignoring the desired width of 3).

In other radices, the result does not start with the "-" sign, but rather the string is left-sign-extended by the (radix-1) character (e.g. "F" in base 16, "1" in binary/base 2, etc.).

If the resulting string requires more characters than the requested width, the minimum number of characters will be returned required to accurately represent the number, which will larger than the requested width. For example, toString(-35426,4,16) is hex "F759E". This cannot fit within a 4 character width, because "759E" is a positive number. The leading "F" must be present. Therefore "F759E" will be returned which is larger than the 4 character width requested. However toString(-35426,6,16) will return the "FF759E", which is correct.

Positive Numbers and the leadSymbolOption Option

The default behavior for positive numbers is to prefix the number with a space character in order to have negative and positive numbers of the same order of magnitude occupied the same field width -- an often useful feature in output fields.

Specifying the leadSymbolOption option with a value enables other lead symbol treatment for positive numbers:

Examples