Text and collections

These functions take a string or a collection as the first argument and work with characters or elements by a zero-based index.

• A collection is changed in place by APPEND, INSERT, REMOVEAT, SETAT and REPLACE, which return the same collection. For a string they return a new string.
• A blob, such as RECEIVEDMSG.PAYLOAD, is accepted only by LENGTH, GETAT, COPY and INDEXOF.
• A Null first argument stops the script with Parameter 1 is null, except in LENGTH (0), INDEXOF (-1) and SPLIT (an empty collection); COMPARE reports COMPARE arguments 1 and 2 must be strings.

ENCODE and DECODE (XML, Base64) are on Data type conversions, EQUALS on Logic and diagnostics. Collection types are described in Data types.

LENGTH#

LENGTH returns the number of characters of a string, elements of a collection or bytes of a blob; for a number it returns the size of its type in bytes, and for Null 0.

LENGTH("Hello World");
# Result: 11
LENGTH(40);
# Result: 8 (a decimal literal is a double)
LENGTH(BYTECOLLECTION("010203"));
# Result: 3

GETAT#

GETAT returns the element at an index: a char of a string, an element of a collection or a byte of a blob.

1

GETAT(value, index)

Returns — for a string a char, not a one-letter string; compare it with a char literal such as 'l'.

GETAT("Hello", 2);
# Result: 'l' (Char)
GETAT({1, 2, 4}, 2);
# Result: 4

SETAT#

SETAT replaces the element at an index; a collection is changed in place, for a string the character at the index is replaced by the text of newValue.

1

SETAT(value, index, newValue)

SETAT("Hello", 1, "a");
# Result: "Hallo"
SETAT("Hello", 4, "o World");
# Result: "Hello World"
VAR c := {1, 2, 4};
SETAT(c, 2, 3);
# Result: {1, 2, 3}, and c is now {1, 2, 3}

APPEND#

APPEND adds a value to the end of a string or a collection; a collection is changed in place and returned, not copied.

1

APPEND(value, what)

Remarks — Appending a collection with the same element type adds all its elements. A single value is added as one element. A collection of another element type is an error (Cannot append ‘UInt8’ collection to ‘Double’ collection).

VAR c := {1, 2};
APPEND(c, 3);
# Result: {1, 2, 3}, and c is now {1, 2, 3}
APPEND(c, {4, 5});
# Result: {1, 2, 3, 4, 5}
APPEND("abc", "def");
# Result: "abcdef"

INSERT#

INSERT inserts a value at an index: a substring into a string, or an element into a collection in place.

1

INSERT(value, index, what)

INSERT("Hello", 5, " World");
# Result: "Hello World"
INSERT("Hello", 1, "i");
# Result: "Hiello"
INSERT({1, 2, 4}, 2, 3);
# Result: {1, 2, 3, 4}

REMOVEAT#

REMOVEAT removes count characters or elements, 1 by default, starting at an index.

1
2

REMOVEAT(value, index)
REMOVEAT(value, index, count)

REMOVEAT("Hello", 1);
# Result: "Hllo"
REMOVEAT("Hello", 3, 2);
# Result: "Hel"
REMOVEAT({1, 2, 3, 4}, 2, 2);
# Result: {1, 2}

COPY#

COPY returns a new string, collection or blob with length items starting at from; without length it copies to the end, without from the whole value.

1
2
3

COPY(value)
COPY(value, from)
COPY(value, from, length)

COPY("Hello World", 2);
# Result: "llo World"
COPY("Hello World", 2, 4);
# Result: "llo "
COPY(BYTECOLLECTION("01020304"), 2, 1);
# Result: {0x03}

Errors — Parameter 1 must be a non-empty string when copying from an empty string.

INDEXOF#

INDEXOF returns the position of the first occurrence of a value in a string, a collection or a blob, or -1 when it is not found.

1

INDEXOF(value, what)

INDEXOF("Hello World", "Wor");
# Result: 6
INDEXOF("Hello World", "or12");
# Result: -1
INDEXOF(BYTECOLLECTION("ab cd ee ff 01 02"), 2);
# Result: 5

Errors — Parameter 2 must be a non-empty string when searching a string for an empty string.

REPLACE#

REPLACE replaces every occurrence of a value: a string gives a new string, a collection has its matching elements replaced in place.

1

REPLACE(value, what, replacement)

REPLACE("Hello", "l", "");
# Result: "Heo"
REPLACE("Hello", "lo", "22");
# Result: "Hel22"
REPLACE(BYTECOLLECTION("050607"), 5, 9);
# Result: {0x09, 0x06, 0x07}

Errors — Empty string to replace when what is an empty string.

SPLIT#

SPLIT splits a string at every separator and returns a collection<string>; empty parts are kept.

1

SPLIT(string, separator)

Parameters — separator is a char, a string, a collection<char> or a collection<string>.

SPLIT("1;2;3;4", ";");
# Result: {"1", "2", "3", "4"}
SPLIT("1;2;3.4", "2;");
# Result: {"1;", "3.4"}
SPLIT("1;2;3.4", {"2", "3."});
# Result: {"1;", ";", "4"}

COMPARE#

COMPARE compares two strings and returns a negative number when the first sorts before the second, 0 when they are equal and a positive number when it sorts after; rely on the sign only, not on the size.

1
2

COMPARE(string1, string2)
COMPARE(string1, string2, CompareOptions)

Remarks — Without options a control unit returns the difference of the character codes of the first differing characters, so uppercase letters sort before lowercase ones. With CompareOptions (IgnoreCase, IgnoreNonSpace, IgnoreSymbols, IgnoreKanaType, IgnoreWidth, OrdinalIgnoreCase, StringSort, Ordinal, None) the strings are compared by the linguistic rules of the invariant culture, the same on every control unit, adjusted by those options.

COMPARE("abc", "abc");
# Result: 0
COMPARE("abc", "ABC");
# Result: 32
COMPARE("a", "c");
# Result: -2
COMPARE("abc", "ABC", CompareOptions.IgnoreCase);
# Result: 0

Errors — COMPARE arguments 1 and 2 must be strings.

BYTECOLLECTION#

BYTECOLLECTION creates a collection<uint8>, either from a string of hexadecimal digits or filled with a given number of zero bytes (1 – 2048).

1
2

BYTECOLLECTION(hexString)
BYTECOLLECTION(count)

Remarks — Characters of the string that are not hexadecimal digits are ignored, so spaces, commas and dashes can separate the bytes; the number of remaining digits must be even.

BYTECOLLECTION("00 0A FF");
# Result: {0x00, 0x0A, 0xFF}
BYTECOLLECTION("aa, be1-1,fe");
# Result: {0xAA, 0xBE, 0x11, 0xFE}
BYTECOLLECTION(6);
# Result: 6 zero bytes

Errors — Parameter must be a non-empty string; Length must be a multiple of 2; Maximum array length is 2048; Invalid array length. Must be greater than 0 and less than or equal 2048.

UINT16COLLECTION#

UINT16COLLECTION creates a collection<uint16> of 1 – 2048 zeros, typically filled with PACKVALUE and written to Modbus registers with MODBUSWBLOCK.

collection<uint16> regs := UINT16COLLECTION(4);
PACKVALUE(regs, 0, BigEndianFloat, 21.5);
PACKVALUE(regs, 2, Uint16, 100);
MODBUSWBLOCK(H, 200, regs);

Available — Core 2026.1, build 39001 and later.

See also — Binary data, Modbus functions.

BOOLCOLLECTION#

BOOLCOLLECTION creates a collection<bool> of 1 – 2048 FALSE values, typically for writing Modbus coils with MODBUSWBLOCK.

collection<bool> coils := BOOLCOLLECTION(8);
SETAT(coils, 0, TRUE);
MODBUSWBLOCK(C, 0, coils);

Available — Core 2026.1, build 39001 and later.