Difference between revisions of "SHIP:Sail:bytesToString"

From Serious Documentation
Jump to: navigation, search
(→‎Parameters/Return Value)
(→‎Detailed Description)
Line 33: Line 33:
  
 
== Detailed Description ==
 
== Detailed Description ==
−
The <code>bytesToString()</code> function returns the character string representing the 8, 16, or 32-bit ASCII byte sequence held in the number specified.  
+
The {{SailFunc|bytesToString}}<code>()</code> 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 <code>0x53484950</code> is a big endian order representation of "SHIP".
 
For example, the 32-bit integer <code>0x53484950</code> is a big endian order representation of "SHIP".
  
 
The size of the source number is analyzed and used as the byte count to analyze. {{DataType|Integer}} properties are 4 bytes, {{DataType|Short}} properties are 2 bytes, and {{DataType|Byte}} properties are 2 bytes.  Constants are assumed to be the smallest representation size (1,2, or 4 bytes), so a constant of <code>0x80</code> is assumed to be 1 byte, a constant of <code>0x0123</code> is 2 bytes, and so forth. A constant written <code>0x00000023</code> is still assumed to be 1 byte, as is a constant <code>0xFFFFFFFF</code> since math in SHIP is signed and -1 can be written as simply <code>0xFF</code>.
 
The size of the source number is analyzed and used as the byte count to analyze. {{DataType|Integer}} properties are 4 bytes, {{DataType|Short}} properties are 2 bytes, and {{DataType|Byte}} properties are 2 bytes.  Constants are assumed to be the smallest representation size (1,2, or 4 bytes), so a constant of <code>0x80</code> is assumed to be 1 byte, a constant of <code>0x0123</code> is 2 bytes, and so forth. A constant written <code>0x00000023</code> is still assumed to be 1 byte, as is a constant <code>0xFFFFFFFF</code> since math in SHIP is signed and -1 can be written as simply <code>0xFF</code>.
−
 
  
 
== Examples ==
 
== Examples ==

Revision as of 05:19, 5 June 2015

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:

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

Retrieved from "https://techref.myserious.com/index.php?title=SHIP:Sail:bytesToString&oldid=4858"