Difference between revisions of "SHIP:Sail:toString"

Revision as of 07:19, 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 {{v5}]]]);

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	The radix of the string (10 is decimal, 16 is hex, 2 is binary, etc.); only applies to Integer
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.
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 2,10, and 16. Using a non-supported radix reverts to 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. The maximum width specifiable is 256.

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.

Examples