Working with Data Types

Data types form the foundation of Coldwave Script. Unlike in many high-level languages, they directly influence safety and predictability: integers saturate instead of overflowing, floating-point values follow IEEE rules, time types support precise control logic, and type conversions are strictly defined. Understanding these rules helps avoid surprises and enables deterministic programming.

Integers (signed/unsigned, promotion, overflow)

INT = 16-bit (−32768 … +32767), UINT = 16-bit (0 … 65535), use DINT/LINT for larger signed values, UDINT/ULINT for larger unsigned values.

Special behavior: saturating arithmetic — overflow clamps to the maximum, underflow clamps to minimum (signed) or 0 (unsigned).

PROGRAM  
    DIM a AS INT = 32760  
    DIM b AS INT = 100  
    PRINT a + b ' Output: 32767 (saturated, no overflow)  
END PROGRAM

Promotion rules: Within the same type family, operands are promoted to the wider type. For example, INT + DINT promotes to DINT.

Coldwave Script enforces strict type families:

Family	Types
Signed integer	SINT, INT, DINT, LINT
Unsigned integer	USINT, UINT, UDINT, ULINT
Bitword	BYTE, WORD, DWORD, LWORD
Real	REAL, LREAL

Arithmetic across families (e.g. INT + REAL, DINT + UDINT, or DWORD + INT) is a compile error. Use explicit conversion functions like TO_REAL(), TO_DINT(), etc.

PROGRAM
    DIM i AS INT = 7
    DIM r AS REAL = 2.0
    ' PRINT i + r        ' ERROR: cross-family
    PRINT TO_REAL(i) + r  ' OK: 9.0
END PROGRAM

Exception: Literal constants (e.g. 42, 3.14) are coerced to the target type automatically. DIM x AS REAL = 42 works because the literal 42 is coerced to REAL at compile time.

Floating Point (REAL/LREAL)

REAL = 32-bit, LREAL = 64-bit. IEEE 754 compliant. Suitable for physical values with decimals.

PROGRAM  
    PRINT 7 / 2 ' Output: 3 (INT division)  
    PRINT TO_REAL(7) / 2 ' Output: 3.5 (REAL division)  
END PROGRAM

Tip: If fractional results are required, convert first using TO_REAL.

BOOL & Comparisons

BOOL only supports TRUE and FALSE. Comparisons return BOOL. Operators: AND, OR, XOR, NOT.

PROGRAM  
    DIM ok AS BOOL  
    ok = (5 < 7)  
    PRINT ok ' Output: TRUE  
END PROGRAM

TIME / DATE

TIME is stored in milliseconds. Syntax: T#500ms, T#2s, T#1h.

DATE, TOD, DT examples: DATE#2025-01-01, TOD#12:00:00, DT#2025-01-01-12:00:00.

PROGRAM  
    PRINT TO_TIME(1000) ' Output: T#1000ms  
    PRINT ADD_TIME(T#500ms, T#200ms) ' Output: T#700ms  
END PROGRAM

TIME is often used together with blocks like TON.

Type Conversions

All TO_* functions are safety-oriented. Non-representable values are clamped instead of wrapping.

PROGRAM  
    PRINT TO_UINT(-5) ' Output: 0  
    PRINT TO_INT(3.9) ' Output: 3  
    PRINT TO_REAL(42) ' Output: 42.0  
END PROGRAM

Generic Type Classes (ANY_*)

In addition to concrete data types like DINT or LREAL, Coldwave Script supports generic type classes inspired by IEC 61131-3. These are not data types you can use for variables — they are constraints that you place on function and block parameters to indicate which family of types is accepted.

Type Class	Accepts
ANY_NUM	All numeric types: SINT, INT, DINT, LINT, USINT, UINT, UDINT, ULINT, REAL, LREAL
ANY_REAL	Floating-point types: REAL, LREAL
ANY_INT	All integer types (signed and unsigned)
ANY_BIT	Bit-oriented types: BOOL, BYTE, WORD, DWORD, LWORD
ANY_STRING	String types: STRING, WSTRING
ANY_DATE	Date/time types: TIME, DATE, TOD, DT

Key rules:

• Generic type classes can only be used in FUNCTION, SUB, and BLOCK parameter declarations and return types. They cannot be used with DIM or CONST — variables always need a concrete type.
• When a function is called, the compiler checks that each argument belongs to the declared type class. Passing a BOOL to an ANY_NUM parameter is a compile-time error.
• When the return type is generic (e.g. AS ANY_NUM), the actual return type is determined automatically from the argument types using type promotion.

' OK — DINT is in ANY_NUM
PRINT MyFunc(42)

' OK — LREAL is in ANY_NUM
PRINT MyFunc(3.14)

' ERROR — BOOL is not in ANY_NUM
PRINT MyFunc(TRUE)

Arrays

Arrays are the only composite data type in Coldwave Script. They are fixed‑length, statically‑sized containers of scalar values and follow IEC 61131‑3 conventions (DIM, 1‑based indices) — but with the size constraints and trap semantics of the Coldwave VM.

Declaration

DIM a AS INT[3] = {10, 20, 30}   ' list initialiser
DIM b AS INT[4] = 0              ' broadcast initialiser (all slots = 0)
DIM c AS REAL[2] = 0.0           ' broadcast, REAL

• The length N inside [ … ] must be a compile‑time positive integer constant in the range 1 … ARRAY_MAX_LEN (see Resource Limits).
• Every array must carry an initialiser. A list initialiser { … } must have exactly N entries; a scalar expression after = is a broadcast and assigns the same value to every slot.
• The element type is any scalar type (BOOL, SINT, INT, DINT, LINT and their unsigned variants, bitword types, REAL, LREAL, TIME, DATE, TOD, DT). STRING and WSTRING are not allowed as element types.

Access

Array elements are read and written with the subscript operator [ … ]. Indices are 1‑based — a[1] is the first element, a[N] is the last, and a[0] is always out of bounds.

PROGRAM
    DIM a AS INT[3] = {10, 20, 30}
    DIM i AS INT
    FOR i = 1 TO 3
        PRINT a[i]              ' prints 10, 20, 30
    NEXT
    a[1] = 100                  ' element assignment
    PRINT a[1]                  ' prints 100
END PROGRAM

Index checks (static vs. runtime)

Out‑of‑bounds access is diagnosed as early as possible:

Condition	Diagnostic	When
Constant index outside 1..N	SCRIPT_ERR_ARRAY_OOB_CONST	compile
FOR‑counter‑bounded index whose range provably escapes 1..N (including shifted forms like a[i + k])	SCRIPT_ERR_ARRAY_OOB_CONST	compile
Any other non‑constant index outside 1..N	VM_E_OOB_ARRAY trap	runtime

The compile‑time checker recognises index expressions of the form i, i + k, i - k or k - i where i is the counter of an enclosing FOR loop with literal TO bounds and k is an integer constant. If the resulting range lies outside 1..N, the program is rejected before it ever runs.

Limitations (V1)

• No multi‑dimensional arrays.
• No whole‑array assignment, slicing, or array‑valued expressions.
• No STRING / WSTRING elements.
• No ARRAY OF T alias syntax; use AS T[N].

Summary

• Integers saturate; unsigned clamps to 0.
• Promotion raises operands to the wider type.
• REAL/LREAL for fractional values; INT division truncates.
• BOOL from comparisons and logical operators.
• TIME/DATE/DT enable time-based logic.
• TO_* conversion functions are safe and deterministic.
• Arrays are the only composite type — fixed length, 1‑based indices, compile‑ and runtime‑checked bounds.