SHIP:Sail:bytesToString

Function	Returns	Introduced	Description
bytesToString	String	v5.0.206	Builds a string from the ASCII bytes of an Integer, Short, or Byte until a 0x00 byte is encountered or the number of bytes of the size of the object are consumed. Optionally, non-printable characters can be replaced as-encountered. All byte orderings are supported.

See Also:

• Sail Home
• Sail Functions
• Sail String Functions
• charAt, codepointAt, codepointToString,subStr, subString, toString

Prototypes

String bytesToString(Float/Integer/Short/Byte number);

String bytesToString(Float/{DataType|Integer}}/Short/Byte number, ByteOrder byteOrder);

String bytesToString(Float/{DataType|Integer}}/Short/Byte number, ByteOrder byteOrder, Codepoint replacement );

Parameters/Return Value

Parameter	Data Type	Description
number	Float/Integer/Short/Byte	Number to convert. Floats are always trunc'd and passed as full 32-bit sized Integers. The size of the source type drives the maximum number of bytes to convert; constants are assumed to have the least number of representation bytes.
byteOrder	ByteOrder	Byte order to analyze the source number with (optional)
replacement	Codepoint	If a non-printable character (0x01-0x1F) is encountered, this UTF8 Codepoint is inserted into the string instead. 0x00 is permitted here and terminates the string upon encountering a non-printable byte. Any Unicode Codepoint is permitted.
Return	String	Character string

Detailed Description

The bytesToString() function returns the character string representing the 8, 16, or 32-bit ASCII byte sequence held in the number specified.

For example, the 32-bit integer 0x53484950 is a big endian order representation of "SHIP".

The size of the source number is analyzed and used as the byte count to analyze. Integer properties are 4 bytes, Short properties are 2 bytes, and Byte properties are 2 bytes. Constants are assumed to be the smallest representation size (1,2, or 4 bytes), so a constant of 0x80 is assumed to be 1 byte, a constant of 0x0123 is 2 bytes, and so forth. A constant written 0x00000023 is still assumed to be 1 byte, as is a constant 0xFFFFFFFF since math in SHIP is signed and -1 can be written as simply 0xFF.

Examples

Example	Result	Notes
bytesToString(0x53);	"S"
codepointToString(0x53484950);	"SHIP"
codepointToString(0x53484900);	"SHI"
codepointToString(0x53480050);	"SH"	Early terminated when 0x00 encountered in 3rd byte.
codepointToString(0x53484950,BYTEORDER.LITTLE_ENDIAN);	"PIHS"	All 4 bytes endian flipped.
codepointToString(0x53484950,BYTEORDER.BIG_ENDIAN,0x3F);	"SHIP"	All bytes are printable, so the replacement character 3F ('?') is unused.
codepointToString(0x53480350,BYTEORDER.BIG_ENDIAN,0x3F);	"SH?P"	The third byte, 0x03 is unprintable, so it is replaced with the replacement character 3F ('?').
codepointToString(0x53480350,BYTEORDER.BIG_ENDIAN,0x3F);	"SH╳P"	The third byte, 0x03 is unprintable, so it is replaced with the extended UTF8 replacement character 0x2573, the diagonal cross ('╳'). Note for this to be visible in your GUI this character must be present in your font.

References

• A handy 8-bit ASCII table
• A good codepoint table, courtesy of Sean M. Burke