Data type conversions

Conversion functions turn values into text and back: numbers and dates into formatted text, text into numbers and bytes, and text into Base64 or XML-safe form. BCD conversion (TOBCD, FROMBCD) is on Bit operations and colour conversion (HSVTORGB, RGBTOHSV) on Colours.

TOSTRING#

TOSTRING converts any value to text — numbers and dates with an optional .NET format string, byte collections and blobs with a text encoding.

1
2
3

TOSTRING(value)
TOSTRING(value, format)
TOSTRING(bytes, encoding)

Example

TOSTRING(192, "X");
# Result: "C0"
TOSTRING(192, "X4");
# Result: "00C0"
TOSTRING(123.34, "F4");
# Result: "123.3400"
TOSTRING(123.34, "F0");
# Result: "123"
TOSTRING(BYTECOLLECTION("48656c6c6f"));
# Result: "Hello"
TOSTRING(BYTECOLLECTION("48656c6c6f"), "iso-8859-1");
# Result: "Hello"

In a listener script, TOSTRING(RECEIVEDMSG.PAYLOAD, "utf-8") reads the received message as text — see RECEIVEDMSG.

Format strings#

TOSTRING formats numbers and dates with .NET format strings and always uses a decimal point, whatever the language settings of the control unit.

Remarks

• A format that contains an upper-case X first converts the value to a 32-bit whole number, then prints it in hexadecimal.
• In date formats HH is the 24-hour clock and hh the 12-hour clock; MM is the month and mm the minute.

Example — timestamp for a log or an HTTP request

VAR now := NOW();
"Updated " + TOSTRING(now, "dd.MM.yyyy HH:mm");

TODOUBLE#

TODOUBLE reads a number from text that uses a decimal point and returns NaN when the text is not a number.

1

TODOUBLE(text)

Returns — double. NaN when the text cannot be read; 0 for Null.

Remarks — The text is always read with a decimal point. A comma counts as a thousands separator, so "1,5" gives 15. Replace the comma first when the source uses a decimal comma.

Example

TODOUBLE("232");
# Result: 232
TODOUBLE("-192.332");
# Result: -192.332
TODOUBLE("some text");
# Result: NaN
TODOUBLE(REPLACE("21,5", ",", "."));
# Result: 21.5

TOBYTES#

TOBYTES encodes text into a byte collection (collection<uint8>), using iso-8859-1 unless another encoding is named.

1
2

TOBYTES(text)
TOBYTES(text, encoding)

Remarks — Older documentation called this function TOBYTEARRAY; that name does not exist in the language. Use TOBYTES to prepare data for SENDDATA or for UNPACKVALUE.

Example

VAR bytes := TOBYTES("Hello");
LENGTH(bytes);
# Result: 5
VAR euro := TOBYTES("€", "utf-8");
LENGTH(euro);
# Result: 3

Errors — TOBYTES - argument 1 must be a string (the text is Null); TOBYTES - unknown encoding.

ENCODE#

ENCODE escapes text for XML ("xml") or encodes it as Base64 ("base64", from the UTF-8 bytes of the text).

1

ENCODE(text, coding)

Remarks

• "xml" replaces &, ', ", > and < with &, ', ", > and <.
• Empty text returns an empty string. The coding name is not case sensitive.
• "base64" needs Core 2022.2 or newer.

Example

ENCODE("a<b & c>d", "xml");
# Result: "a&lt;b &amp; c&gt;d"
ENCODE("user:pass", "base64");
# Result: "dXNlcjpwYXNz"

Example — HTTP Basic authorization header

VAR auth := "Authorization: Basic " + ENCODE("user:pass", "base64");
VAR response := SENDHTTPREQUEST("/status", "GET", "", auth);

Errors — ENCODE Unknown encoding. Valid values are ‘xml’, ‘base64’.

DECODE#

DECODE reverses ENCODE: it turns XML entities back into characters ("xml") or decodes Base64 into UTF-8 text ("base64").

1

DECODE(text, coding)

Example

DECODE("dXNlcjpwYXNz", "base64");
# Result: "user:pass"
DECODE("a < b", "xml");
# Result: "a < b"
DECODE(PARSEJSON(json, "payload"), "base64");

Errors — The provided text does not have the base64 format.; DECODE Unknown encoding. Valid values are ‘xml’, ‘base64’.

See also — ENCODE, PARSEJSON.