Difference between revisions of "SHIP:Sail:toString"

Revision as of 15:42, 8 July 2014

See Also:

• SHIP Sail Home
• SHIP Sail Function Home
• codepointToString(), length(), toString()

toString

Converts an Integer or Float to a string. Options include leading 0 padding, radix, and precision.

Prototype

Integer toString(Integer number);

Integer toString(Integer number, Integer width);

Integer toString(Integer number, Integer width, Integer radix);

Float toString(Float number);

Float toString(Float number, Integer precision);

Float toString(Float number, Integer precision, Integer width);

Parameters/Return Value

Detailed Description

The toString(number) 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