Difference between revisions of "SHIP:Sail:bytesToString"

Revision as of 10:16, 5 June 2015

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

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 most common use of this function is when receiving Modbus or other communications variables from a remote system that are encoding strings or character sequences. For example, the remote end may pass Short variables with 2-letter codes describing the state of a machine; say 0x444F or "DO" for Door Open. You may want to display these codes in your GUI, and so converting them to a String is desirable. One option in this example is

String = codepointToString((x>>8)&0x0FF) + codepointToString(x&0x0FF);

But this technique gets cumbersome with Integer variables. Further, what if the encoding in the number has non-printable characters you wish to replace, and/or you may encounter a string-ending 0x00 byte in the sequence? The method above does not handle these cases.

The bytesToString() function makes parsing these objects much simpler.

Size of Source Object

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. Floats are always trunc'd and passed as full 32-bit sized Integers. 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.

Byte Ordering

Often the bytes in the number object are not in the same order. Often communications Integer values come in big Endian, but other times you may have all sorts of needs for the 4 different byte orderings of a 32-bit value (or 2 for a 16-bit value).

The optional parameter allows you to manipulate the byte ordering that the object is processed in. The ByteOrder value is similar to that supported in linkset nodes to convert incoming data, and a typical value might be BYTEORDER.SWAP8 to swap pairs of 8-bit values in a 16- or 32-bit number.

Examples

References

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