---
title: "Data type conversions"
description: "TapHome script conversions: format numbers and dates with TOSTRING, parse numbers with TODOUBLE, text to bytes with TOBYTES, Base64 and XML with ENCODE."
url: "https://taphome.com/en/docs/script/data-type-conversions/"
language: en
lastmod: 2026-11-06
generator: hugo
ai:
  topics: ["data-conversion","type-conversion","number-formatting","encoding","scripting-language"]
  questions: ["How do I convert a string to a number in TapHome script?","How to format a number as a string in TapHome?","How do I format a number with two decimal places?","How do I print a number as hexadecimal?","How do I format a date as text in a TapHome script?","How do I convert a string to a byte array?","How do I encode text as Base64 in a TapHome script?","How do I escape special characters for XML?","Where are TOBCD, FROMBCD, RGBTOHSV and HSVTORGB documented?"]
---

# Data type conversions

TapHome script conversion functions — TOSTRING with number and date format strings, TODOUBLE, TOBYTES, and ENCODE / DECODE for XML escaping and Base64.

Last updated: 2026-11-06

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](https://taphome.com/en/docs/script/bit-operations/) and colour conversion (`HSVTORGB`, `RGBTOHSV`) on [Colours](https://taphome.com/en/docs/script/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.

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

| Input | Result |
|---|---|
| string | Unchanged. |
| number | Without a format, the plain number with a decimal point (`21.5`). With a format, see [Format strings](https://taphome.com/en/docs/script/data-type-conversions/#format-strings). |
| `datetime` | Without a format `yyyy/MM/dd hh:mm:ss.fff` (12-hour clock, no AM or PM); with a format the given pattern. |
| `collection<uint8>`, blob | The bytes decoded as text. The second argument is the encoding name, `iso-8859-1` by default, for example `"utf-8"`. |
| other collection | Error *Cannot cast collection of 'X' to string*. |

**Example**

```taphome
# hexadecimal text, upper case
TOSTRING(192, "X");
# Result: "C0"
TOSTRING(192, "X4");
# Result: "00C0"
# fixed number of decimals
TOSTRING(123.34, "F4");
# Result: "123.3400"
TOSTRING(123.34, "F0");
# Result: "123"
# bytes decoded as text
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](https://taphome.com/en/docs/script/listener-scripts/#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.

| Format | Input | Output |
|---|---|---|
| `"F2"` | `231.4721` | `"231.47"` — fixed number of decimals |
| `"F0"` | `21.5` | `"22"` — rounded to a whole number |
| `"0.0"` | `7` | `"7.0"` — custom pattern |
| `"00"` | `7` | `"07"` — leading zeros |
| `"X"`, `"X4"` | `255` | `"FF"`, `"00FF"` — hexadecimal, upper case |
| `"yyyy-MM-dd"` | `datetime` | `"2026-01-15"` |
| `"HH:mm"` | `datetime` | `"08:30"` — 24-hour clock |
| `"dd.MM.yyyy HH:mm:ss"` | `datetime` | `"15.01.2026 08:30:00"` |

**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**

```taphome
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.

```text
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**

```taphome
# text with a decimal point to a number
TODOUBLE("232");
# Result: 232
TODOUBLE("-192.332");
# Result: -192.332
# not a number gives NaN
TODOUBLE("some text");
# Result: NaN
# decimal comma replaced by a point first
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.

```text
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](https://taphome.com/en/docs/script/packet-parser/#senddata) or for [UNPACKVALUE](https://taphome.com/en/docs/script/binary-data/#unpackvalue).

**Example**

```taphome
# text to bytes, iso-8859-1 by default
VAR bytes := TOBYTES("Hello");
LENGTH(bytes);
# Result: 5
# another encoding named explicitly
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).

```text
ENCODE(text, coding)
```

**Remarks**

- `"xml"` replaces `&`, `'`, `"`, `>` and `<` with `&amp;`, `&apos;`, `&quot;`, `&gt;` and `&lt;`.
- Empty text returns an empty string. The coding name is not case sensitive.
- `"base64"` needs Core 2022.2 or newer.
- `"base64"` encodes the UTF-8 bytes of text. For binary data, such as encrypted bytes, use [TOBASE64](https://taphome.com/en/docs/script/byte-encodings/#tobase64).

**Example**

```taphome
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**

```taphome
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"`).

```text
DECODE(text, coding)
```

**Example**

```taphome
# Base64 to UTF-8 text
DECODE("dXNlcjpwYXNz", "base64");
# Result: "user:pass"
# XML entity back to a character
DECODE("a &lt; b", "xml");
# Result: "a < b"
# decode a Base64 value from JSON
DECODE(PARSEJSON(json, "payload"), "base64");
```

**Remarks** — `"base64"` returns UTF-8 text, so bytes above `0x7F` do not survive it. Decode binary data, such as encrypted bytes, with [FROMBASE64](https://taphome.com/en/docs/script/byte-encodings/#tobase64).

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

**See also** — [ENCODE](https://taphome.com/en/docs/script/data-type-conversions/#encode), [PARSEJSON](https://taphome.com/en/docs/script/parsing-functions/#parsejson).