SHIP:Sail:toString

From Serious Documentation
Jump to: navigation, search
Function Returns Introduced Description
toString String v2.0 Converts an Integer or Float to a string. Options include leading 0 padding, radix, and precision.

See Also:


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/Float 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 zero or positive. (5.0.132+)
  • 0 (default) adds no prefix symbol for numbers >=0, negative numbers have a '-' sign.
  • 1 adds a '+' sign for positive numbers, space for 0, negative numbers have a '-' sign.
  • 2 adds a leading space to numbers >= 0 in order to have all numbers indent the same visually as negative numbers that have the '-' leading symbol always
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 non-negative numbers is to have no prefix (leading) symbol before the first digit.

Specifying the leadSymbolOption option alters the leading symbol treatment:

  • 0 (default) adds no prefix symbol for numbers >=0, negative numbers have a '-' sign.
  • 1 adds a '+' sign for positive numbers, space for 0, negative numbers have a '-' sign.
  • 2 adds a leading space to numbers >= 0 in order to have all numbers indent the same visually as negative numbers that have the '-' leading symbol always

The leadSymbolOption feature is only meaningful for radix 10; it is ignored for all other radices.

Examples

Example Result Notes
toString(50); " 50"
toString(50,0,10,1); "+50" leadSymbolOption 1 means use a + sign, not space
toString(50,0,10,2); "50" leadSymbolOption 2 means no leading character if +ve
toString(28-50); "-22"
toString(65,16); "41" decimal 65 is hex 0x41
"0x" + toString(65,0,16); "0x41" width is ignored
toString(65,4,16); "0041"
toString(12,0,2); "1100" width is ignored
toString(12,2,2); "1100" string is bigger than the requested width
toString(12,8,2); "00001100"
toString(65,1,10); " 65" string is bigger than the requested width
toString(65,0,37); " 65" the radix is invalid and defaults to 10
toString(65,-3,10); " 65" negative widths are ignored
toString(-6552,6,10); "-06552" 6 wide includes the "-" sign