Difference between revisions of "SHIP:Sail:bytesToString"

From Serious Documentation
Jump to: navigation, search
(→‎Prototype)
Line 10: Line 10:
 
== Prototype ==
 
== Prototype ==
 
<code>{{DataType|String}} {{SailFunc|bytesToString}}({{DataType|Integer}}/{{DataType|Short}}/{{DataType|Byte}});</code>
 
<code>{{DataType|String}} {{SailFunc|bytesToString}}({{DataType|Integer}}/{{DataType|Short}}/{{DataType|Byte}});</code>
−
<code>{{DataType|String}} {{SailFunc|bytesToString}}({{DataType|Integer}}/{{DataType|Short}}/{{DataType|Byte}}, {{DataType|Byte}} byteOrder);</code><code>{{DataType|String}} {{SailFunc|bytesToString}}({{DataType|Integer}}/{{DataType|Short}}/{{DataType|Byte}}, {{DataType|Byte}} byteOrder, {{DataType|codePoint}} replacement );</code>
+
 
 +
<code>{{DataType|String}} {{SailFunc|bytesToString}}({{DataType|Integer}}/{{DataType|Short}}/{{DataType|Byte}}, {{DataType|Byte}} byteOrder);</code>
 +
 
 +
<code>{{DataType|String}} {{SailFunc|bytesToString}}({{DataType|Integer}}/{{DataType|Short}}/{{DataType|Byte}}, {{DataType|Byte}} byteOrder, {{DataType|codePoint}} replacement );</code>
 
=== Parameters/Return Value ===
 
=== Parameters/Return Value ===
 
{| class="wikitable" style="margin: 1em 1em;"  
 
{| class="wikitable" style="margin: 1em 1em;"  

Revision as of 05:12, 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:

Prototype

String bytesToString(Integer/Short/Byte);

String bytesToString(Integer/Short/Byte, Byte byteOrder);

String bytesToString(Integer/Short/Byte, Byte byteOrder, codePoint replacement );

Parameters/Return Value

Parameter Data Type Description
number Integer/Short/Byte Number to convert
byteOrder ByteOrder Byte order to analyze the source number with (optional)
replacement CodePoint If a non-printable character (0x01-0x1F) is encountered, this UTF8 Codepointis 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=4842"