Data types
Data types of the TapHome script language: numbers, text, structured and enum types, collections, the .Type property, type promotion in arithmetic, and how Null and NaN behave.
Last updated:
The TapHome script language has scalar types such as numbers and text, structured types, enum types and collections, and this page lists all of them. It also explains how the .Type property returns the type of a value, how arithmetic chooses the type of a result and how Null and NaN behave. All you need is a script, because the type names listed here are used in typed declarations. With them you declare typed variables and avoid surprises such as integer division, where 5 / 2 gives 2.
Scalar types
Every value in a script carries a concrete type. The type names below are used in typed declarations (see Local variables), and the .Type property returns them.
| Type | Values | Notes |
|---|---|---|
bool | TRUE, FALSE | Any non-zero number converts to TRUE, zero to FALSE. |
int8, uint8, int16, uint16, int, uint, int64, uint64 | Whole numbers of 8, 16, 32 and 64 bits | int and uint are the 32-bit types. uint8 is the byte of byte collections. |
float, double | Floating point numbers | Number literals and most arithmetic give a double. |
char | One character, 'A' | Takes part in arithmetic as its character code. |
string | Text, "abc" | + with a string on either side joins text. |
Structured types
Structured types hold several values, available as properties:
| Type | Holds | Properties |
|---|---|---|
datetime | Date and time with a kind (Local, Utc, Unspecified) | See Date and time |
timespan | Time interval | Days, Hours, Minutes, Seconds, Milliseconds, TotalDays, TotalHours, TotalMinutes, TotalSeconds, TotalMilliseconds (read-only) |
httprequest | Prepared HTTP request from HTTPREQUEST | Path, Method, Body, Headers (read and write) |
httpresponse | Answer of SENDHTTPREQUEST | Content, Headers, IsSuccess, StatusCode, ReasonPhrase (read-only) |
receivedmessage | Incoming message RECEIVEDMSG of a listener script | Protocol, Payload, Length, Topic, ContentType, PayloadFormat, ClientId, Expiry, Dup (read-only) |
blob | Raw bytes, for example RECEIVEDMSG.PAYLOAD | Length (read-only) |
rgbcolor, hsvcolor | Colours, see Colours | Red, Green, Blue and Hue, Saturation, Value (read and write) |
groupvalue | Value of a device group | Calculated, Values (read-only) |
currentvalueinfo, historyvalues | Parts of a Value info variable | See Value info |
Enum types
An enum type is a fixed set of named values that some functions take as a parameter:
| Type | Values | Used by |
|---|---|---|
ModbusRegisterType | C, H, D, A | Modbus functions |
ModbusDataType | Int16, Uint16, Int32, UInt32, Float, Bool, String, Int64, UInt64, Double and their byte-order variants, see Modbus data types | Modbus functions, PACKVALUE, UNPACKVALUE |
LinearType | DEFAULT, BOUNDS, STRICT, INFINITE | LINEAR |
DateTimeKind | Local, Utc, Unspecified | NOW, DATETIME |
DayOfWeek | Monday … Sunday | datetime properties |
CompareOptions | None, IgnoreCase, IgnoreNonSpace, IgnoreSymbols, IgnoreKanaType, IgnoreWidth, OrdinalIgnoreCase, StringSort, Ordinal | COMPARE |
An enum value is written bare (Utc) or with its type (DateTimeKind.Utc). Enum types also work as declaration keywords:
DateTimeKind kind := Utc;
VAR t := NOW(kind);Collections
collection<T> is a list of values of one element type T.
# create typed collections
collection<uint16> registers := UINT16COLLECTION(4);
collection<string> names := {"a", "b", "c"};
collection<uint8> data := BYTECOLLECTION("0A0B0C");
# number of elements
LENGTH(names);
# Result: 3- The element type comes from the declaration, otherwise from the first element that is not
Null.{Null}alone fails withUnable to determine collection type. - Nested collections are not supported:
Collection<Collection<>> is not supported. - Collections are reference values.
APPEND,INSERT,REMOVEAT,SETATandREPLACEchange the collection in place and return the same collection. BYTECOLLECTION,UINT16COLLECTIONandBOOLCOLLECTIONcreate at most 2048 elements; each form reports a larger count with its own message (see Run-time errors).LENGTH(c)orc.Lengthreturns the number of elements.
Available — typed collections: Core 2022.2 or newer; UINT16COLLECTION and BOOLCOLLECTION: TapHome Next 2026.1.39016+.
The .Type property
Every value has the read-only property .Type, which returns the name of its type as text. For an enum value it is the enum type, for example "DateTimeKind".
# type of a number
VAR x := 5.5;
x.Type;
# Result: "Double"
# type of a collection
VAR c := BYTECOLLECTION("0A0B");
c.Type;
# Result: "Collection<UInt8>"Properties can be read only from a named variable. AVG('a', 'c').Type fails with Unexpected character '.'; store the value in a variable first.
Type conversion rules
In arithmetic the first rule that matches the two operands decides the type of the result:
- Either operand is
double(or a group value):double. - Either operand is
float:float. - Either operand is
int64:int64. - Either operand is
uint64:uint64. - Either operand is
uint:uintwhen the other one is unsigned too, otherwiseint64. - Otherwise (smaller integers,
bool,char):int.
Division of two integers truncates. A number literal is a double, so dividing by it does not:
# two integers
int a := 5;
int b := 2;
# integer division cuts the fraction
a / b;
# Result: 2
# a number literal is a double
a / 2;
# Result: 2.5- Bitwise operators work on integers; a
doubleoperand is converted toint64first. +with a string on either side joins text:"T=" + 21.5is"T=21.5".datetime+ number adds milliseconds,datetime+timespanadds the interval, andtimespan±timespanworks as expected.- Dividing by zero stops the script with
Division by zero. Guard the divisor withIF. - Assigning to a typed variable converts the value to its type, see Local variables.
Null and NaN
NaN is a number whose value is unknown, for example a sensor that was not read yet or a device in error. Null means there is no value at all: a deleted device, or a function that found nothing.
- Comparing with the literal
NaN(x = NaN,x < NaN) is rejected when the script is parsed:Comparison with NaN is always false. Use the IsNaN method to check for NaN value.UseISNAN. <,>,<=and>=with aNulloperand giveFALSE.Null = Null,Null <= NullandNull >= NullareTRUE,Null = 5isFALSE.&,|and^with aNulloperand giveNull;<<and>>giveNullfor aNullvalue on the left, while aNullshift count stops the script withCannot cast DataType.Null to number.- Arithmetic and logic with
Null(Null + 5,!Null) stops the script withOperator '+' not defined for 'Null' and 'Double'. Check the value withISNULLfirst. - A
Nullcondition ofIFcounts asFALSE. MIN,MAX,AVGandORDERskipNullandNaN; the…STRICTvariants pass them on.EQUALS(NaN, NaN)isTRUE.
IF(ISNULL(value) OR ISNAN(value), 0, value);
# Result: the value, or 0 when it is missing or unknown