--- title: "Testo e collezioni" description: "Funzioni per testo e collezioni negli script TapHome: LENGTH, GETAT, SETAT, APPEND, INSERT, REMOVEAT, COPY, INDEXOF, REPLACE, SPLIT, COMPARE e BYTECOLLECTION, UINT16COLLECTION, BOOLCOLLECTION." url: "https://taphome.com/it/docs/script/text-string-and-byte-array/" language: it lastmod: 2026-11-06 generator: hugo ai: topics: ["string-functions","byte-array","collections","scripting-language"] questions: ["Come si ottiene la lunghezza di una stringa in uno script TapHome?","Come si divide una stringa in base a un separatore in TapHome?","Come si sostituisce del testo all'interno di una stringa in TapHome?","Come si crea una collezione di byte da valori esadecimali?","Come si trova l'indice di un elemento in una stringa o in una collezione?","APPEND crea una nuova collezione o modifica quella originale?","Come si confrontano due stringhe in uno script TapHome?"] --- # Testo e collezioni Funzioni degli script TapHome per stringhe, collezioni e array di byte — LENGTH, GETAT, SETAT, APPEND, INSERT, REMOVEAT, COPY, INDEXOF, REPLACE, SPLIT, COMPARE, BYTECOLLECTION, UINT16COLLECTION, BOOLCOLLECTION. Ultimo aggiornamento: 2026-11-06 Queste funzioni accettano come primo argomento una stringa o una collezione e lavorano con i caratteri o gli elementi tramite un indice che parte da zero. - Una **collezione** viene modificata **sul posto** da `APPEND`, `INSERT`, `REMOVEAT`, `SETAT` e `REPLACE`, che restituiscono la stessa collezione. Per una **stringa** restituiscono una nuova stringa. - Un **blob**, come `RECEIVEDMSG.PAYLOAD`, è accettato solo da `LENGTH`, `GETAT`, `COPY` e `INDEXOF`. - Un primo argomento `Null` interrompe lo script con *Parameter 1 is null*, tranne in `LENGTH` (0), `INDEXOF` (-1) e `SPLIT` (una collezione vuota); `COMPARE` segnala *COMPARE arguments 1 and 2 must be strings*. `ENCODE` e `DECODE` (XML, Base64) sono nella pagina [Conversioni tra tipi di dati](https://taphome.com/it/docs/script/data-type-conversions/), `EQUALS` nella pagina [Logica e diagnostica](https://taphome.com/it/docs/script/logic-and-diagnostics/#equals). I tipi di collezione sono descritti in [Tipi di dati](https://taphome.com/it/docs/script/data-types/). ## LENGTH `LENGTH` restituisce il numero di caratteri di una stringa, di elementi di una collezione o di byte di un blob; per un numero restituisce la dimensione del suo tipo in byte e per `Null` 0. ```taphome # caratteri in una stringa LENGTH("Hello World"); # Result: 11 # lunghezza di un numero LENGTH(40); # Result: 8 (a decimal literal is a double) # byte in una collezione di byte LENGTH(BYTECOLLECTION("010203")); # Result: 3 ``` ## GETAT `GETAT` restituisce l'elemento in una posizione: un `char` di una stringa, un elemento di una collezione o un byte di un blob. ```text GETAT(value, index) ``` **Valore restituito** — per una stringa un `char`, non una stringa di una lettera; confrontalo con un letterale di carattere come `'l'`. ```taphome GETAT("Hello", 2); # Result: 'l' (Char) GETAT({1, 2, 4}, 2); # Result: 4 ``` ## SETAT `SETAT` sostituisce l'elemento in una posizione; una collezione viene modificata sul posto, per una stringa il carattere nella posizione viene sostituito dal testo di `newValue`. ```text SETAT(value, index, newValue) ``` ```taphome # sostituisce un carattere SETAT("Hello", 1, "a"); # Result: "Hallo" # sostituisce un carattere con un testo più lungo SETAT("Hello", 4, "o World"); # Result: "Hello World" # una collezione da modificare VAR c := {1, 2, 4}; # sostituisce un elemento sul posto SETAT(c, 2, 3); # Result: {1, 2, 3}, and c is now {1, 2, 3} ``` ## APPEND `APPEND` aggiunge un valore alla fine di una stringa o di una collezione; una collezione viene modificata sul posto e restituita, non copiata. ```text APPEND(value, what) ``` **Note** — L'aggiunta di una collezione con lo stesso tipo di elemento aggiunge tutti i suoi elementi. Un singolo valore viene aggiunto come un elemento. Una collezione con un altro tipo di elemento è un errore (*Cannot append 'UInt8' collection to 'Double' collection*). ```taphome # una collezione da estendere VAR c := {1, 2}; # aggiunge un elemento sul posto APPEND(c, 3); # Result: {1, 2, 3}, and c is now {1, 2, 3} # aggiunge più elementi sul posto APPEND(c, {4, 5}); # Result: {1, 2, 3, 4, 5} # accoda testo a una stringa APPEND("abc", "def"); # Result: "abcdef" ``` ## INSERT `INSERT` inserisce un valore in una posizione: una sottostringa in una stringa, oppure un elemento in una collezione, sul posto. ```text INSERT(value, index, what) ``` ```taphome # inserisce una sottostringa INSERT("Hello", 5, " World"); # Result: "Hello World" # inserisce un carattere INSERT("Hello", 1, "i"); # Result: "Hiello" # inserisce un elemento in una collezione INSERT({1, 2, 4}, 2, 3); # Result: {1, 2, 3, 4} ``` ## REMOVEAT `REMOVEAT` rimuove `count` caratteri o elementi, 1 per impostazione predefinita, a partire da una posizione. ```text REMOVEAT(value, index) REMOVEAT(value, index, count) ``` ```taphome # rimuove un carattere REMOVEAT("Hello", 1); # Result: "Hllo" # rimuove 2 caratteri dall'indice 3 REMOVEAT("Hello", 3, 2); # Result: "Hel" # rimuove 2 elementi da una collezione REMOVEAT({1, 2, 3, 4}, 2, 2); # Result: {1, 2} ``` ## COPY `COPY` restituisce una nuova stringa, collezione o blob con `length` elementi a partire da `from`; senza `length` copia fino alla fine, senza `from` l'intero valore. ```text COPY(value) COPY(value, from) COPY(value, from, length) ``` ```taphome # copia dall'indice 2 alla fine COPY("Hello World", 2); # Result: "llo World" # copia 4 caratteri dall'indice 2 COPY("Hello World", 2, 4); # Result: "llo " # copia 1 byte da un blob COPY(BYTECOLLECTION("01020304"), 2, 1); # Result: {0x03} ``` **Errori** — *Parameter 1 must be a non-empty string* quando si copia da una stringa vuota. ## INDEXOF `INDEXOF` restituisce la posizione della prima occorrenza di un valore in una stringa, in una collezione o in un blob, oppure `-1` se non viene trovato. ```text INDEXOF(value, what) ``` ```taphome # posizione di una sottostringa INDEXOF("Hello World", "Wor"); # Result: 6 # se non trovato dà -1 INDEXOF("Hello World", "or12"); # Result: -1 # posizione di un elemento in un blob INDEXOF(BYTECOLLECTION("ab cd ee ff 01 02"), 2); # Result: 5 ``` **Errori** — *Parameter 2 must be a non-empty string* quando in una stringa si cerca una stringa vuota. ## REPLACE `REPLACE` sostituisce ogni occorrenza di un valore: da una stringa si ottiene una nuova stringa, in una collezione gli elementi corrispondenti vengono sostituiti sul posto. ```text REPLACE(value, what, replacement) ``` ```taphome # rimuove ogni l REPLACE("Hello", "l", ""); # Result: "Heo" # sostituisce una sottostringa REPLACE("Hello", "lo", "22"); # Result: "Hel22" # sostituisce un elemento in un blob REPLACE(BYTECOLLECTION("050607"), 5, 9); # Result: {0x09, 0x06, 0x07} ``` **Errori** — *Empty string to replace* quando `what` è una stringa vuota. ## SPLIT `SPLIT` divide una stringa a ogni separatore e restituisce una `collection`; le parti vuote vengono mantenute. ```text SPLIT(string, separator) ``` **Parametri** — `separator` è un `char`, una stringa, una `collection` o una `collection`. ```taphome # divide a ogni separatore SPLIT("1;2;3;4", ";"); # Result: {"1", "2", "3", "4"} # separatore più lungo di un carattere SPLIT("1;2;3.4", "2;"); # Result: {"1;", "3.4"} # più separatori insieme SPLIT("1;2;3.4", {"2", "3."}); # Result: {"1;", ";", "4"} ``` ## COMPARE `COMPARE` confronta due stringhe e restituisce un numero negativo quando la prima viene prima della seconda nell'ordinamento, 0 quando sono uguali e un numero positivo quando viene dopo; considera solo il segno, non la grandezza. ```text COMPARE(string1, string2) COMPARE(string1, string2, CompareOptions) ``` **Note** — Senza opzioni un'unità di controllo restituisce la differenza dei codici di carattere dei primi caratteri diversi, quindi le lettere maiuscole vengono prima delle minuscole. Con `CompareOptions` (`IgnoreCase`, `IgnoreNonSpace`, `IgnoreSymbols`, `IgnoreKanaType`, `IgnoreWidth`, `OrdinalIgnoreCase`, `StringSort`, `Ordinal`, `None`) le stringhe vengono confrontate secondo le regole linguistiche della cultura invariante, uguali su ogni unità di controllo, adattate da quelle opzioni. ```taphome # stringhe uguali danno 0 COMPARE("abc", "abc"); # Result: 0 # maiuscole diverse danno un numero positivo COMPARE("abc", "ABC"); # Result: 32 # la prima stringa viene prima della seconda COMPARE("a", "c"); # Result: -2 # ignorare le maiuscole dà 0 COMPARE("abc", "ABC", CompareOptions.IgnoreCase); # Result: 0 ``` **Errori** — *COMPARE arguments 1 and 2 must be strings*. ## BYTECOLLECTION `BYTECOLLECTION` crea una `collection`, da una stringa di cifre esadecimali oppure riempita con un dato numero di byte a zero (1 – 2048). ```text BYTECOLLECTION(hexString) BYTECOLLECTION(count) ``` **Note** — I caratteri della stringa che non sono cifre esadecimali vengono ignorati, quindi spazi, virgole e trattini possono separare i byte; il numero di cifre rimanenti deve essere pari. ```taphome # byte da testo esadecimale BYTECOLLECTION("00 0A FF"); # Result: {0x00, 0x0A, 0xFF} # testo esadecimale con separatori misti BYTECOLLECTION("aa, be1-1,fe"); # Result: {0xAA, 0xBE, 0x11, 0xFE} # un numero dà tanti byte a zero BYTECOLLECTION(6); # Result: 6 zero bytes ``` **Errori** — *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` crea una `collection` di 1 – 2048 zeri, di solito riempita con `PACKVALUE` e scritta nei registri Modbus con `MODBUSWBLOCK`. ```taphome collection regs := UINT16COLLECTION(4); PACKVALUE(regs, 0, BigEndianFloat, 21.5); PACKVALUE(regs, 2, Uint16, 100); MODBUSWBLOCK(H, 200, regs); ``` **Disponibile** — TapHome Next 2026.1.39016+. **Vedi anche** — [Dati binari](https://taphome.com/it/docs/script/binary-data/), [Funzioni Modbus](https://taphome.com/it/docs/script/modbus/). ## BOOLCOLLECTION `BOOLCOLLECTION` crea una `collection` di 1 – 2048 valori `FALSE`, di solito per scrivere coil Modbus con `MODBUSWBLOCK`. ```taphome collection coils := BOOLCOLLECTION(8); SETAT(coils, 0, TRUE); MODBUSWBLOCK(C, 0, coils); ``` **Disponibile** — TapHome Next 2026.1.39016+.