Servizio ScriptForge.String (SF_String)

Contenuto

# Servizio ScriptForge.String

Il servizio String fornisce una raccolta di metodi per l'eleborazione delle stringhe. Questi metodi possono essere usati per:

- Convalidare il contenuto delle stringhe

- Formattare le stringhe rimuovendo spazi, giustificandole o adattando i loro contenuti

- Usare le espressioni regolari per cercare e sostituire parti delle stringhe

- Applicare algoritmi di hash alle stringhe, ecc.

## Definizioni

### Interruzioni di riga

Il servizio String riconosce i seguenti tipi di interruzione di riga:

Nome simbolico | Numero ASCII
--- | ---
Nuova riga Tabulatore verticale Ritorno a capo Nuova riga + Ritorno a capo Separatore file Separatore di gruppo Separatore di record Prossima riga Separatore di riga Separatore di paragrafo | 10 12 13 13 + 10 28 29 30 133 8232 8233

### Spazi vuoti

Il servizio String riconosce i seguenti tipi di spazi:

Nome simbolico | Numero ASCII
--- | ---
Spazio Tabulazione orizzontale A capo Tabulazione verticale Avanzamento di formulario Carattere di ritorno Prossima riga Spazio unificatore Separatore di riga Separatore di paragrafo | 32 9 10 11 12 13 133 160 8232 8233

### Sequenze di escape

Il seguente è un elenco delle sequenze di escape che potete usare nelle stringhe.

Sequenza di escape | Nome simbolico | Numero ASCII
--- | --- | ---
\n \r \t | A capo Carattere di ritorno Tabulazione orizzontale | 10 13 9

Per fare in modo che la sequenza di escape "\n" sia interpretata alla lettera come una stringa, usate semplicemente "\\n" invece di "\" & Chr(10).

### Caratteri non stampabili:

I caratteri che nel database dei caratteri Unicode sono definiti come “Altro” o “Separatore” sono considerati come caratteri non stampabili.

Anche i caratteri di controllo (codice ASCII <= 0x1F) sono considerati come non stampabili.

### Virgolette all'interno delle stringhe:

Per aggiungere delle virgolette all'interno delle stringhe usate \' (virgoletta) o \" (virgolette doppie). Per esempio:

- La stringa [str\'i\'nga] è interpretata come [str'i'nga]

- La stringa [str\"i\"nga] è interpretata come [str"i"nga]

## Invocazione del servizio

Prima di usare il servizio ScriptForge.String è necessario caricare la libreria ScriptForge usando:

##### In Basic

          GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Il caricamento della libreria creerà l'oggetto SF_String che può essere usato per chiamare i metodi del servizio String.

Il seguente frammento di codice mostra i tre modi per chiamare i metodi del servizio String (il metodo Capitalize viene usato come esempio):

        Dim s as String : s = "abc def"
        s = SF_String.Capitalize(s) ' Abc Def

        Dim s as String : s = "abc def"
        Dim svc : svc = SF_String
        s = svc.Capitalize(s) ' Abc Def

        Dim s as String : s = "abc def"
        Dim svc : svc = CreateScriptService("String")
        s = svc.Capitalize(s) ' Abc Def

##### In Python

Il frammento di codice seguente illustra come invocare i metodi del servizio String dagli script in Python. Il metodo IsIPv4 è usato come esempio.

        from scriptforge import CreateScriptService
        svc = CreateScriptService("String")
        ip_address = '192.168.0.14'
        svc.IsIPv4(ip_address) # True

## Proprietà

L'oggetto SF_String fornisce le seguenti proprietà per gli script in Basic:

Nome | Sola lettura | Descrizione
--- | --- | ---
sfCR | Sì | Carattere di ritorno: Chr(13)
sfCRLF | Sì | Carattere di ritorno + A capo: Chr(13) & Chr(10)
sfLF | Sì | A capo: Chr(10)
sfNEWLINE | Sì | Carattere di ritorno + A capo, che possono essere 1) Chr(13) e Chr(10) o 2) A capo: Chr(10) a seconda del sistema operativo.
sfTAB | Sì | Tabulazione orizzontale: Chr(9)

Potete usare le proprietà precedenti per identificare o inserire i corrispondenti caratteri all'interno delle stringhe. Per esempio, il carattere di A capo può essere sostituito da SF_String.sfLF.

Elenco dei metodi del servizio String
Capitalize Count EndsWith Escape ExpandTabs FilterNotPrintable FindRegex HashStr HtmlEncode IsADate IsAlpha IsAlphaNum IsAscii IsDigit IsEmail | IsFileName IsHexDigit IsIBAN IsIPv4 IsLike IsLower IsPrintable IsRegex IsSheetName IsTitle IsUpper IsUrl IsWhitespace JustifyCenter JustifyLeft | JustifyRight Quote ReplaceChar ReplaceRegex ReplaceStr Represent Reverse SplitLines SplitNotQuoted StartsWith TrimExt Unescape Unquote Wrap

Il primo argomento della maggior parte dei metodi è la stringa da prendere in considerazione. Questa viene sempre passata per riferimento e lasciata inalterata. Metodi come Capitalize, Escape, ecc., restituiscono una nuova stringa al termine dell'esecuzione.

Considerato che Python incorpora il supporto completo per le stringhe, la maggior parte dei metodi del servizio String è disponibile solamente per gli script in Basic. I metodi disponibili per Basic e Python sono: HashStr, IsADate, IsEmail, IsFileName, IsIBAN, IsIPv4, IsLike, IsSheetName, IsUrl, SplitNotQuoted e Wrap.

## Capitalize

Rende maiuscolo il primo carattere di ogni parola della stringa di partenza.

### Sintassi:

svc.Capitalize(inputstr: str): str

### Parametri:

inputstr: la stringa di cui rendere maiuscola l'iniziale.

### Esempio:

        Dim sName as String : sName = "john smith"
        Dim sCapitalizedName as String
        sCapitalizedName = SF_String.Capitalize(sName)
        MsgBox sCapitalizedName 'John Smith

## Count

Conta il numero di occorrenze di una sottostringa o di un'espressione regolare all'interno di una stringa.

### Sintassi:

svc.Count(inputstr: str, substring: str, [isregex: bool], [casesensitive: bool]): int

### Parametri:

inputstr: la stringa inserita da esaminare

substring: la sottostringa o l'espressione regolare da usare durante la ricerca

isregex: usate True se la sottostringa è un'espressione regolare (predefinito = False)

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

        'Conta le occorrenze della sottostringa "or" all'interno della stringa di partenza (restituisce 2)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)
        'Conta il numero di parole con solo lettere minuscole (restituisce 7)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)

Per saperne di più sulle espressioni regolari, fare riferimento alla documentazione di Python sulle Operazioni con le Espressioni regolari.

## EndsWith

Restituisce True se una stringa termina con la sottostringa indicata.

La funzione restituisce False se la stringa o la sottostringa hanno una lunghezza pari a = 0, o se la sottostringa è più lunga della stringa.

### Sintassi:

svc.EndsWith(inputstr: str, substring: str, [casesensitive: bool]): bool

### Parametri:

inputstr: la stringa da controllare.

substring: la sottostringa da cercare alla fine di inputstr.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

        'Restituisce True perchè il metodo è stato chiamato con il valore predefinito di CaseSensitive = False
        MsgBox SF_String.EndsWith("abcdefg", "EFG")
        'Restituisce False a causa del parametro CaseSensitive
        MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)

## Escape

Converte le interruzioni di riga e le tabulazioni contenute nella stringa di partenza nella loro equivalente sequenza di escape (\\, \n, \r, \t).

### Sintassi:

svc.Escape(inputstr: str): str

### Parametri:

inputstr: la stringa da convertire.

### Esempio:

        'Restituisce la stringa "abc\n\tdef\\n"
        MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")

## ExpandTabs

Sostituisce i caratteri di tabulazione Chr(9) con caratteri di spazio in modo da replicare il comportamento degli stop del tabulatore.

Se trova un'interruzione di riga, va a capo e il contatore dei caratteri viene azzerato.

### Sintassi:

svc.ExpandTabs(inputstr: str, [tabsize: int]): str

### Parametri:

inputstr: la stringa da espandere

tabsize: questo parametro viene usato per determinare gli stop del tabulatore usando la formula: TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (predefinito = 8)

### Esempio:

        Dim myText as String
        myText = "100" & SF_String.sfTAB & "200" & SF_String.sfTAB & "300" & SF_String.sfNEWLINE & _
                 "X"  & SF_String.sfTAB & "Y" & SF_String.sfTAB & "Z"
        MsgBox SF_String.ExpandTabs(myText)
        '100     200     300
        'X       Y       Z

## FilterNotPrintable

Sostituisce tutti i caratteri non stampabili della stringa inserita con il carattere indicato.

### Sintassi:

svc.FilterNotPrintable(inputstr: str, [replacedby: str]): str

### Parametri:

inputstr: la stringa in cui cercare

replacedby: zero, uno o più caratteri che sostituiranno tutti i caratteri non stampabili in inputstr (predefinito = "")

### Esempio:

        Dim LF : LF = Chr(10)
        Dim myText as String
        myText = "àén ΣlPµ" & LF & " Русский" & "\n"
        MsgBox SF_String.FilterNotPrintable(myText)
        ' "àén ΣlPµ Русский\n"

## FindRegex

Trova, all'interno di una stringa, una sottostringa conforme all'espressione regolare precisata.

### Sintassi:

svc.FindRegex(inputstr: str, regex: str, [start: int], [casesensitive: bool], [forward: bool]): str

### Parametri:

inputstr: la stringa in cui cercare

regex: l'espressione regolare

start: la posizione, all'interno della stringa, dalla quale inizierà la ricerca. Questo parametro viene passato come riferimento, perciò dopo l'esecuzione il valore di start punterà al primo carattere della sottostringa trovata. Se non viene trovata alcuna sottostringa corrispondente, start verrà impostato a 0.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

forward: determina la direzione della ricerca. Se True, la ricerca avviene in avanti. Se False la ricerca avviene all'indietro (predefinito = True)

Alla prima iterazione, se forward = True, start deve essere uguale a 1, mentre se forward = False, start deve essere uguale a Len(inputstr)

### Esempio:

        Dim lStart As Long : lStart = 1
        Dim result as String
        result = SF_String.FindRegex("abCcdefghHij", "C.*H", lStart, CaseSensitive := True)
        MsgBox lStart & ": " & result
        '3: CcdefghH

Nell'esempio sopra, il nuovo valore di lStart può essere usato per continuare a cercare la stessa stringa inserita, impostando il parametro Start a lStart + Len(result) all'iterazione successiva.

## HashStr

Le funzioni di hash sono usate in alcuni algoritmi crittografici, nelle firme digitali, nei codici di autenticazione dei messaggi, nel rilevamenti di manipolazioni, nelle "impronte digitali", nei checksum (controllo di integrità dei messaggi), nelle tabelle di hash, nella memorizzazione delle password e per molto altro ancora.

Il metodo HashStr restituisce il risultato di una funzione di hash, applicata alla stringa specificata, usando un algoritmo specifico, in formato stringa esadecimale con lettere minuscole.

Gli algoritmi di hash supportati sono: MD5, SHA1, SHA224, SHA256, SHA384 e SHA512.

### Sintassi:

svc.HashStr(inputstr: str, algorithm: str): str

### Parametri:

inputstr: la stringa di cui calcolare l'hash. Si presume che sia codificata in UTF-8. L'algoritmo di hash considererà la stringa come un flusso di byte.

algorithm: uno degli algoritmi supportati ed elencati in precedenza, passato in formato stringa.

### Esempio:

##### In Basic

        MsgBox SF_String.HashStr("œ∑¡™£¢∞§¶•ªº–≠œ∑´®†¥¨ˆøπ‘åß∂ƒ©˙∆˚¬", "MD5")
        ' c740ccc2e201df4b2e2b4aa086f35d8a

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        a_string = "œ∑¡™£¢∞§¶•ªº–≠œ∑´®†¥¨ˆøπ‘åß∂ƒ©˙∆˚¬"
        hash_value = svc.HashStr(a_string, "MD5")
        bas.MsgBox(hash_value)
        # c740ccc2e201df4b2e2b4aa086f35d8a

## HtmlEncode

Codifica la stringa inserita nei codici carattere HTML, sostituendo i caratteri speciali con il loro corrispondente &.

Per esempio, il carattere é sarà sostituito con &eacute; o con un codice numerico HTML equivalente.

### Sintassi:

svc.HtmlEncode(inputstr: str): str

### Parametri:

inputstr: la stringa da codificare

### Esempio:

        MsgBox SF_String.HtmlEncode("<a href=""https://a.b.com"">From α to ω</a>")
        ' "&lt;a href=&quot;https://a.b.com&quot;&gt;From &#945; to &#969;&lt;/a&gt;"

## IsADate

Restituisce True se la stringa inserita è una data valida secondo il formato data specificato.

### Sintassi:

svc.IsADate(inputstr: str, [dateformat: str]): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False

dateformat: il formato data, come stringa. Può essere uno tra "AAAA-MM-GG" (predefinito), "GG-MM-AAAA" o "MM-GG-AAAA"

Il trattino (-) può essere sostituito con un punto (.), una barra (/) o uno spazio.

Se il formato non è valido, il metodo restituisce False.

### Esempio:

##### In Basic

        MsgBox SF_String.IsADate("2020-12-31", "YYYY-MM-DD") ' True

Questo metodo controlla il formato della stringa inserita senza eseguire alcun controllo specifico in base al calendario. Perciò non controlla se la stringa inserita rispetta gli anni bisestili o i mesi da 30 o 31 giorni. Per questo consultate la funzione incorporata IsDate.

L'esempio sottostante mostra la differenza tra i metodi IsADate (ScriptForge) e la funzione (incorporata) IsDate.

        Dim myDate as String : myDate = "2020-02-30"
        MsgBox SF_String.IsADate(myDate, "YYYY-MM-DD") 'True
        MsgBox IsDate(myDate) ' False

##### In Python

        svc = CreateScriptService("String")
        s_date = "2020-12-31"
        result = svc.IsADate(s_date) # True

## IsAlpha

Restituisce True se tutti i caratteri della stringa sono alfabetici.

I caratteri alfabetici sono quei caratteri che nella documentazione Unicode Character Database sono definiti come Letter.

### Sintassi:

svc.IsAlpha(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsAlpha("àénΣlPµ") ' True
        MsgBox SF_String.IsAlpha("myVar3") ' False

## IsAlphaNum

Restituisce True se tutti i caratteri della stringa sono alfabetici, numerici o "_" (trattino basso). Il primo carattere non deve essere una cifra.

### Sintassi:

svc.IsAlphaNum(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsAlphaNum("_ABC_123456_abcàénΣlPµ") ' True
        MsgBox SF_String.IsAlphaNum("123ABC") ' False

## IsAscii

Restituisce True se tutti i caratteri della stringa sono caratteri ASCII.

### Sintassi:

svc.IsAscii(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsAscii("a%?,25") ' True
        MsgBox SF_String.IsAscii("abcàénΣlPµ") ' False

## IsDigit

Restituisce True se tutti i caratteri della stringa sono cifre.

### Sintassi:

svc.IsDigit(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsDigit("123456") ' True
        MsgBox SF_String.IsDigit("_12a") ' False

## IsEmail

Restituisce True se la stringa è un indirizzo di posta elettronica valido.

### Sintassi:

svc.IsEmail(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

##### In Basic

        MsgBox SF_String.IsEmail("first.last@something.org") ' True
        MsgBox SF_String.IsEmail("first.last@something.com.br") ' True
        MsgBox SF_String.IsEmail("first.last@something.123") ' False

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsEmail("first.last@something.org")) # True
        bas.MsgBox(svc.IsEmail("first.last@something.com.br")) # True
        bas.MsgBox(svc.IsEmail("first.last@something.123")) # False

## IsFileName

Restituisce True se la stringa è un nome di file valido per il sistema operativo specificato.

### Sintassi:

svc.IsFileName(inputstr: str, [osname: str]): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

osname: il nome del sistema operativo, in formato stringa. Può essere "WINDOWS", "LINUX", "MACOSX" o "SOLARIS".

Il valore predefinito è il sistema operativo corrente nel quale lo script viene eseguito.

### Esempio:

##### In Basic

        MsgBox SF_String.IsFileName("/home/user/Documents/a file name.odt", "LINUX") ' True
        MsgBox SF_String.IsFileName("C:\home\a file name.odt", "LINUX") ' False
        MsgBox SF_String.IsFileName("C:\home\a file name.odt", "WINDOWS") ' True

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsFileName("/home/user/Documents/a file name.odt", "LINUX")) # True
        bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "LINUX")) # False
        bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "WINDOWS")) # True

## IsHexDigit

Restituisce True se tutti i caratteri della stringa sono cifre esadecimali.

### Sintassi:

svc.IsHexDigit(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

Le cifre esadecimali possono avere il prefisso "0x" o "&H".

### Esempio:

        MsgBox SF_String.IsHexDigit("&H00FF") ' True
        MsgBox SF_String.IsHexDigit("08AAFF10") ' True
        MsgBox SF_String.IsHexDigit("0x18LA22") ' False

## IsIBAN

Restituisce True se la stringa è un IBAN (International Bank Account Number) valido. Il confronto non distingue tra minuscole e maiuscole.

### Sintassi:

svc.IsIBAN(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Tipo di ritorno:

True se la stringa contiene un codice IBAN valido.

### Esempio:

        ' Basic
        MsgBox SF_String.IsIBAN("BR15 0000 0000 0000 1093 2840 814 P2") ' True

        # Python
        result = svc.IsIBAN("BR15 0000 0000 0000 1093 2840 814 P2") # True

## IsIPv4

Restituisce True se la stringa è un indirizzo IP(v4) valido.

### Sintassi:

svc.IsIPv4(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

##### In Basic

        MsgBox SF_String.IsIPv4("192.168.1.50") ' True
        MsgBox SF_String.IsIPv4("192.168.50") ' False
        MsgBox SF_String.IsIPv4("255.255.255.256") ' False

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsIPv4("192.168.1.50")) # True
        bas.MsgBox(svc.IsIPv4("192.168.50")) # False
        bas.MsgBox(svc.IsIPv4("255.255.255.256")) # False

## IsLike

Restituisce True se l'intera stringa inserita corrisponde a un determinato schema contenente caratteri jolly.

### Sintassi:

svc.IsLike(inputstr: str, pattern: str, [casesensitive: bool]): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

pattern: lo schema in formato stringa. I caratteri jolly sono:

- "?" rappresenta un singolo carattere qualsiasi;

- "*" rappresenta zero, uno o più caratteri.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

##### In Basic

        MsgBox SF_String.IsLike("aAbB", "?A*") ' True
        MsgBox SF_String.IsLike("C:\a\b\c\f.odb", "?:*.*") ' True
        MsgBox SF_String.IsLike("name:host", "?*@?*") ' False
        MsgBox SF_String.IsLike("@host", "?*@?*") ' False

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsLike("aAbB", "?A*")) # True
        bas.MsgBox(svc.IsLike(r"C:\a\b\c\f.odb", "?:*.*")) # True
        bas.MsgBox(svc.IsLike("name:host", "?*@?*")) # False
        bas.MsgBox(svc.IsLike("@host", "?*@?*")) # False

## IsLower

Restituisce True se tutti i caratteri della stringa sono lettere minuscole. I caratteri non alfabetici vengono ignorati.

### Sintassi:

svc.IsLower(inputstr: str): bool

### Parametri:

InputStr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsLower("abc'(-xy4z") ' True
        MsgBox SF_String.IsLower("1234") ' True
        MsgBox SF_String.IsLower("abcDefg") ' False

## IsPrintable

Restituisce True se tutti i caratteri della stringa sono stampabili.

### Sintassi:

svc.IsPrintable(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsPrintable("àén ΣlPµ Русский") ' True
        MsgBox SF_String.IsPrintable("First line." & Chr(10) & "Second Line.") ' False

## IsRegex

Restituisce True se l'intera stringa inserita corrisponde all'espressione regolare specificata.

### Sintassi:

svc.IsRegex(inputstr: str, regex: str, [casesensitive: bool]): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

regex: l'espressione regolare. Se vuota, il metodo restituisce False.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

            MsgBox SF_String.IsRegex("aAbB", "[A-Za-z]+") ' True
            MsgBox SF_String.IsRegex("John;100", "[A-Za-z]+;[0-9]+") ' True
            MsgBox SF_String.IsRegex("John;100;150", "[A-Za-z]+;[0-9]+") ' False

## IsSheetName

Restituisce True se la stringa inserita è un nome valido di un foglio di Calc.

### Sintassi:

svc.IsSheetName(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

##### In Basic

        MsgBox SF_String.IsSheetName("1àbc + ""déf""") ' True
        MsgBox SF_String.IsSheetName("[MySheet]") ' False

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsSheetName("1àbc + ""déf""")) # True
        bas.MsgBox(svc.IsSheetName("[MySheet]")) # False

Il nome di un foglio non deve contenere i caratteri [ ] * ? : / \ o il carattere ' (apostrofo) come primo o ultimo carattere.

## IsTitle

Restituisce True se il primo carattere di ogni parola è maiuscolo e i restanti caratteri sono minuscoli.

### Sintassi:

svc.IsTitle(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsTitle("This Is The Title Of My Book") ' True
        MsgBox SF_String.IsTitle("This is the Title of my Book") ' False
        MsgBox SF_String.IsTitle("Result Number 100") ' True

## IsUpper

Restituisce True se tutti i caratteri della stringa sono maiuscoli. I caratteri non alfabetici vengono ignorati.

### Sintassi:

svc.IsUpper(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsUpper("ABC'(-XYZ") ' True
        MsgBox SF_String.IsUpper("A Title") ' False

## IsUrl

Restituisce True se la stringa è un indirizzo URL (Uniform Resource Locator) assoluto valido. Sono supportati solo i protocolli http, https e ftp.

### Sintassi:

svc.IsUrl(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

##### In Basic

        MsgBox SF_String.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff") ' True
        MsgBox SF_String.IsUrl("www.somesite.org") ' False

##### In Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff")) # True
        bas.MsgBox(svc.IsUrl("www.somesite.org")) # False

## IsWhitespace

Restituisce True se tutti i caratteri della stringa sono spazi bianchi

### Sintassi:

svc.IsWhitespace(inputstr: str): bool

### Parametri:

inputstr: la stringa da controllare. Se vuota, il metodo restituisce False.

### Esempio:

        MsgBox SF_String.IsWhitespace("    ") ' True
        MsgBox SF_String.IsWhitespace(" " & Chr(9) & Chr(10)) ' True
        MsgBox SF_String.IsWhitespace("") ' False

## JustifyCenter

Restituisce la stringa inserita giustificata al centro.

Gli spazi iniziali e finali vengono rimossi e i rimanenti caratteri vengono completati a sinistra e a destra fino a una lunghezza length totale specificata con il carattere definito in padding.

### Sintassi:

svc.JustifyCenter(inputstr: str, [length: int], [padding: str]): str

### Parametri:

inputstr: la stringa da allineare al centro. Se è vuota, il metodo restituisce una stringa vuota.

length: la lunghezza della stringa risultante (predefinito = la lunghezza della stringa inserita).

Se la lunghezza specificata è più corta della stringa inserita da allineare al centro, la stringa restituita è troncata.

padding: il singolo carattere da usare come riempimento (predefinito = lo spazio in codifica ASCII " ").

### Esempio:

        MsgBox SF_String.JustifyCenter("Title", Length := 11) ' "   Title   "
        MsgBox SF_String.JustifyCenter("    ABCDEF", Padding := "_") ' "__ABCDEF__"
        MsgBox SF_String.JustifyCenter("A Long Title", Length := 5) ' "ong T"

## JustifyLeft

Restituisce la stringa inserita allineata a sinistra.

Gli spazi iniziali vengono rimossi e i rimanenti caratteri vengono completati a destra fino a una lunghezza length totale specificata con il carattere definito in padding.

### Sintassi:

svc.JustifyLeft(inputstr: str, [length: int], [padding: str]): str

### Parametri:

inputstr: la stringa da allineare a sinistra. Se è vuota, il metodo restituisce una stringa vuota.

length: la lunghezza della stringa risultante (predefinito = la lunghezza della stringa inserita).

Se la lunghezza specificata è più corta della stringa inserita da allineare a sinistra, allora la stringa restituita è troncata.

padding: il singolo carattere da usare come riempimento (predefinito = lo spazio in codifica ASCII " ").

### Esempio:

        MsgBox SF_String.JustifyLeft("Title", Length := 10) ' "Title     "
        MsgBox SF_String.JustifyLeft("    ABCDEF", Padding := "_") ' "ABCDEF____"
        MsgBox SF_String.JustifyLeft("A Long Title", Length := 5) ' "A Lon"

## JustifyRight

Restituisce la stringa inserita allineata a destra.

Gli spazi iniziali vengono rimossi e i rimanenti caratteri vengono completati a sinistra fino a una lunghezza length totale specificata con il carattere definito in padding.

### Sintassi:

svc.JustifyRight(inputstr: str, [length: int], [padding: str]): str

### Parametri:

inputstr: la stringa da allineare a destra. Se è vuota, il metodo restituisce una stringa vuota.

length: la lunghezza della stringa risultante (predefinito = la lunghezza della stringa inserita).

Se la lunghezza specificata è più corta della stringa inserita da allineare a destra, allora la stringa restituita è troncata.

padding: il singolo carattere da usare come riempimento (predefinito = lo spazio in codifica ASCII " ").

### Esempio:

        MsgBox SF_String.JustifyRight("Title", Length := 10) ' "     Title"
        MsgBox SF_String.JustifyRight("  ABCDEF  ", Padding := "_") ' "____ABCDEF"
        MsgBox SF_String.JustifyRight("A Long Title", Length := 5) ' "Title"

## Quote

Restituisce la stringa inserita racchiusa tra virgolette singole o doppie. Le virgolette esistente rimangono invariate, comprese quelle iniziali e/o finali.

### Sintassi:

svc.Quote(inputstr: str, [quotechar: str]): str

### Parametri:

inputstr: la stringa da racchiudere tra virgolette.

quotechar: una tra la virgoletta singola (') o quella doppia (") (predefinita).

### Esempio:

        MsgBox SF_String.Quote("Text Value")
        ' "Text Value"
        MsgBox SF_String.Quote("Book Title: ""The Arabian Nights""", "'")
        ' 'Book Title: "The Arabian Nights"'

Questo metodo può essere utile per preparare un campo stringa al fine di memorizzarlo in un tipo di file come il CSV, che richiede che i valori di testo siano racchiusi tra virgolette singole o doppie.

## ReplaceChar

Sostituisce tutte le occorrenze del carattere specificato nel parametro Before con il corrispondente carattere specificato in After.

Se la lunghezza di Before è maggiore di quella di After, i caratteri residui in Before sono sostituiti con l'ultimo carattere di After.

### Sintassi:

svc.ReplaceChar(inputstr: str, before: str, after: str): str

### Parametri:

inputstr: la stringa inserita nella quale avranno luogo le sostituzioni.

before: una stringa contenente i caratteri da cercare nella stringa inserita per la loro sostituzione.

after: una stringa contenente i nuovi caratteri che sostituiranno quelli definiti in before.

### Esempio:

        ' Sostituisce i caratteri accentati
        MsgBox SF_String.ReplaceChar("Protégez votre vie privée", "àâãçèéêëîïôöûüýÿ", "aaaceeeeiioouuyy")
        ' "Protegez votre vie privee"
        MsgBox SF_String.ReplaceChar("Protégez votre vie privée", "àâãçèéêëîïôöûüýÿ", "")
        ' "Protgez votre vie prive"
        MsgBox SF_String.ReplaceChar("àâãçèéêëîïôöûüýÿ", "àâãçèéêëîïôöûüýÿ", "aaaceeeeiioouuyy")
        ' "aaaceeeeiioouuyy"

Il servizio SF_String fornisce delle costanti pubbliche utili per i set di caratteri latini, come mostrato nel seguente esempio:

        MsgBox SF_String.ReplaceChar("Protégez votre vie privée", SF_String.CHARSWITHACCENT, SF_String.CHARSWITHOUTACCENT)
        ' "Protegez votre vie privee"

## ReplaceRegex

Sostituisce tutte le occorrenze di un determinata espressione regolare con una nuova stringa.

### Sintassi:

svc.ReplaceRegex(inputstr: str, regex: str, newstr: str, [casesensitive: bool]): str

### Parametri:

inputstr: la stringa inserita nella quale avranno luogo le sostituzioni.

regex: l'espressione regolare

newstr: la stringa che sostituisce la precedente.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

        MsgBox SF_String.ReplaceRegex("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "[a-z]", "x", CaseSensitive := True)
        ' "Lxxxx xxxxx xxxxx xxx xxxx, xxxxxxxxxxx xxxxxxxxxx xxxx." (ogni lettera minuscola viene sostituita da una "x")
        MsgBox SF_String.ReplaceRegex("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", "x", CaseSensitive := False)
        ' "x x x x x, x x x." (ogni parola viene sostituita da una "x")

## ReplaceStr

Sostituisce in una stringa alcune o tutte le occorrenze presenti in una matrice di stringhe con quelle di una matrice di nuove stringhe.

### Sintassi:

svc.ReplaceStr(inputstr: str, oldstr: str, newstr: str, [occurrences: int], [casesensitive: bool]): str

### Parametri:

inputstr: la stringa inserita nella quale avranno luogo le sostituzioni.

oldstr: una singola stringa o una matrice di stringhe. Le stringhe di lunghezza pari a zero sono ignorate.

newstr: la stringa o la matrice di stringhe con cui effettuare le sostituzioni.

Se oldstr è una matrice, ogni occorrenza di uno degli elementi presenti in oldstr è sostituita da newstr.

Se oldstr e newstr sono matrici, le sostituzioni avvengono una per una fino al raggiungimento di UBound(newstr).

Se oldstr contiene più voci di newstr, gli elementi residui di oldstr vengono sostituiti dall'ultimo elemento di newstr.

occurrences: il numero massimo di sostituzioni. Il valore predefinito è 0, vale a dire che tutte le occorrenze saranno sostituite.

Quando oldstr è una matrice, il parametro occurrence è calcolato separatamente per ogni elemento della matrice.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

        MsgBox SF_String.ReplaceStr("100 xxx 200 yyy", Array("xxx", "yyy"), Array("(1)", "(2)"), CaseSensitive := False)
        ' "100 (1) 200 (2)"
        MsgBox SF_String.ReplaceStr("abCcdefghHij", Array("c", "h"), Array("Y", "Z"), CaseSensitive := False)
        ' "abYYdefgZZij"

## Represent

Restituisce una stringa con una rappresentazione leggibile dell'argomento, troncata alla lunghezza indicata. Questa è utile principalmente per finalità di debug e di tracciamento.

Se il parametro anyvalue è un oggetto, verrà inserito tra parentesi quadre "[" e "]".

Nelle stringhe, i segni di tabulazione e le interruzioni di riga sono sostituite da \t, \n o \r.

Se la lunghezza finale eccede il parametro maxlength, l'ultima parte della stringa viene sostituita da " ... (N)" dove N è la lunghezza totale della stringa originale prima del troncamento.

### Sintassi:

svc.Represent(anyvalue: any, [maxlength: int]): str

### Parametri:

anyvalue: il valore inserito che deve essere rappresentato. Può essere qualsiasi valore, come una stringa, una matrice, un oggetto di Basic, un oggetto UNO, ecc.

maxlength: la lunghezza massima della stringa risultante. Il valore predefinito è 0, vale a dire che non vi è alcun limite alla lunghezza della rappresentazione risultante.

### Esempio:

        MsgBox SF_String.Represent("this is a usual string") ' "this is a usual string"
        MsgBox SF_String.Represent("this is a usual string", 15) ' "this i ... (22)"
        MsgBox SF_String.Represent("this is a" & Chr(10) & " 2-lines string") ' "this is a\n 2-lines string"
        MsgBox SF_String.Represent(Empty) ' "[EMPTY]"
        MsgBox SF_String.Represent(Null) ' "[NULL]"
        MsgBox SF_String.Represent(Pi) ' "3.142"
        MsgBox SF_String.Represent(CreateUnoService("com.sun.star.util.PathSettings")) ' "[com.sun.star.comp.framework.PathSettings]"

Fate attenzione che la rappresentazione di tipi di dati come istanze di oggetti Matrice e dizionari ScriptForge.Dictionary comprendono sia il tipo di dati, sia i relativi valori:

        ' un esempio con una matrice incorporata di Basic
        MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
        ' "[ARRAY] (0:2) (1, 2, Text\there)"
        ' un esempio con una matrice di ScriptForge
        Dim aValues as Variant
        aValues = SF_Array.RangeInit(1, 5)
        MsgBox SF_String.Represent(aValues)
        ' "[ARRAY] (0:4) (1.0, 2.0, 3.0, 4.0, 5.0)"
        ' un esempio con un dizionario di ScriptForge
        Dim myDict As Variant : myDict = CreateScriptService("Dictionary")
        myDict.Add("A", 1) : myDict.Add("B", 2)
        MsgBox SF_String.Represent(myDict)
        ' "[Dictionary] ("A":1, "B":2)"

## Reverse

Restituisce la stringa inserita in ordine inverso.

Questo metodo è equivalente alla funzione StrReverse incorporata in Basic.

Per usare la funzione StrReverse, l'istruzione OpTion VBASupport 1 deve essere presente nel modulo.

### Sintassi:

svc.Reverse(inputstr: str): str

### Parametri:

inputstr: la stringa da invertire.

### Esempio:

        MsgBox SF_String.Reverse("abcdefghij") ' "jihgfedcba"

## SplitLines

Restituisce una matrice di stringhe, con indice a partire da zero, con le righe della stringa inserita. Ogni elemento della matrice è ottenuto spezzando la stringa inserita in corrispondenza dei caratteri di interruzione di riga.

### Sintassi:

svc.SplitLines(inputstr: str, [keepbreaks: int]): str[0..*]

### Parametri:

inputstr: la stringa da dividere.

keepbreaks: se impostato su True, le interruzioni di riga vengono mantenute nella matrice restituita (predefinito = False).

### Esempio:

        Dim a as Variant
        a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3")
        ' a = Array("Line1", "Line2", "Line3")
        a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3" & Chr(10))
        ' a = Array("Line1", "Line2", "Line3", "")
        a = SF_String.SplitLines("Line1" & Chr(10) & "Line2" & Chr(13) & "Line3" & Chr(10), KeepBreaks := True)
        ' a = Array("Line1\n", "Line2\r", "Line3\n", "")

## SplitNotQuoted

Divide una stringa in una matrice di elementi usando uno specifico delimitatore.

Se una sottostringa racchiusa tra virgolette contiene un delimitatore, questo viene ignorato. Ciò è utile quando si elaborano record tipo CSV che contengono stringhe tra virgolette.

### Sintassi:

svc.SplitNotQuoted(inputstr: str, [delimiter: str], [occurrences: int], [quotechar: str]): str[0..*]

### Parametri:

inputstr: la stringa da dividere.

delimiter: una stringa di uno o più caratteri che sarà usata come delimitatore. Il delimitatore predefinito è il carattere ASCII dello spazio " ".

occurrences: il numero massimo di sottostringhe da restituire. Il valore predefinito è 0, vale a dire che non c'è un limite al numero di stringhe da restituire.

quotechar: le virgolette singole (') o doppie (").

### Esempio:

##### In Basic

        arr1 = SF_String.SplitNotQuoted("abc def ghi")
        ' arr1 = Array("abc", "def", "ghi")
        arr2 = SF_String.SplitNotQuoted("abc,""def,ghi""", ",")
        ' arr2 = Array("abc", """def,ghi""")
        arr3 = SF_String.SplitNotQuoted("abc,""def\"",ghi""", ",")
         ' arr3 = Array("abc", """def\"",ghi""")
        arr4 = SF_String.SplitNotQuoted("abc,""def\"",ghi"""",", ",")
        ' arr4 = Array("abc", """def\"",ghi""", "")

##### In Python

        svc = CreateScriptService("String")
        arr1 = svc.SplitNotQuoted('abc def ghi')
        # arr1 = ('abc', 'def', 'ghi')
        arr2 = svc.SplitNotQuoted('abc,"def,ghi"', ",")
        # arr2 = ('abc', '"def,ghi"')
        arr3 = svc.SplitNotQuoted(r'abc,"def\",ghi"', ",")
        # arr3 = ('abc', '"def\\",ghi"')
        arr4 = svc.SplitNotQuoted(r'abc,"def\",ghi"",', ",")
        # arr4 = ('abc', '"def\\",ghi""', '')

Fate attenzione alle differenze tra Basic e Python nella rappresentazione delle stringhe. Per esempio, in Basic due caratteri "" all'interno di una stringa sono interpretati come un singolo carattere ". In Python, le stringhe racchiuse tra virgolette singole possono contenere il carattere " senza la necessità di raddoppiarlo.

## StartsWith

Restituisce True se i primi caratteri di una stringa sono identici alla sottostringa indicata.

Questo metodo restituisce False se una tra la stringa inserita o la sottostringa possiede una lunghezza pari a zero, oppure quando la sottostringa è più lunga della stringa inserita.

### Sintassi:

svc.StartsWith(inputstr: str, substring: str, [casesensitive: bool]): bool

### Parametri:

inputstr: la stringa da controllare.

substring: la sottostringa da cercare all'inizio di inputstr.

casesensitive: la ricerca può distinguere o no tra minuscole e maiuscole (predefinito = False).

### Esempio:

        MsgBox SF_String.StartsWith("abcdefg", "ABC") 'True
        MsgBox SF_String.StartsWith("abcdefg", "ABC", CaseSensitive := True) 'False

## TrimExt

Restituisce la stringa inserita senza gli spazi iniziali e finali.

### Sintassi:

svc.TrimExt(inputstr: str): str

### Parametri:

inputstr: la stringa da cui rimuovere gli spazi.

### Esempio:

        MsgBox SF_String.TrimExt(" Some text.  ") ' "Some text."
        MsgBox SF_String.TrimExt("   ABCDEF" & Chr(9) & Chr(10) & Chr(13) & " ") ' "ABCDEF"

## Unescape

Converte qualsiasi sequenza di escape (\\, \n, \r, \t) presente nella stringa inserita nel corrispondente carattere ASCII.

### Sintassi:

svc.Unescape(inputstr: str): str

### Parametri:

inputstr: la stringa da convertire.

### Esempio:

        MsgBox SF_String.Unescape("abc\n\tdef\\n")
        ' "abc" & Chr(10) & Chr(9) & "def\n"

## Unquote

Rimuove le virgolette singole o doppie che racchiudono la stringa inserita.

Questo è utile quando si elabora dei record tipo CSV che contengono stringhe tra virgolette.

### Sintassi:

svc.Unquote(inputstr: str, [quotechar: str]): str

### Parametri:

inputstr: la stringa da cui rimuovere le virgolette.

quotechar: le virgolette singole (') o doppie (") (predefinite).

### Esempio:

        Dim s as String
        ' s = "Testo di esempio" (senza virgolette)
        s = SF_String.Unquote("""Some text""")
        ' La stringa sottostante non è racchiusa tra virgolette, perciò rimane immutata
        ' s = "Testo di esempio" (immutato)
        s = SF_String.Unquote("Some text")
        ' Le virgolette all'interno della stringa non sono rimosse
        ' s = "Il ""vero"" significato" (immutato)
        s = SF_String.Unquote("The ""true"" meaning")

## Wrap

Converte la stringa inserita in una matrice di sottostringhe, in modo che ogni elemento della matrice abbia al massimo il numero di caratteri indicato.

In pratica, questo metodo restituisce una matrice, con indice a partire da zero, di righe di output, senza caratteri di a capo alla fine, fatta eccezione delle interruzioni di riga preesistenti.

Le tabulazioni vengono espanse usando la stessa procedura eseguita dal metodo ExpandTabs.

Le interruzioni di riga simboliche sono sostituite con i rispettivi caratteri ASCII equivalenti.

Se l'output reimpaginato non ha contenuto, la matrice restituita è vuota.

### Sintassi:

svc.Wrap(inputstr: str, [width: int], [tabsize: int]): str

### Parametri:

inputstr: la stringa da reimpaginare.

width: il numero massimo di caratteri per ciascuna riga (predefinito = 70).

tabsize: prima di reimpaginare il testo, i caratteri di tabulazione esistenti (TAB Chr(9)) vengono sostituiti con spazi. L'argomento tabsize definisce gli stop di tabulazione (TAB) nei punti TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (predefinito = 8).

### Esempio:

##### In Basic

        a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."
        b = SF_String.Wrap(a, 20)
        ' Array("Neque porro ", "quisquam est qui ", "dolorem ipsum quia ", "dolor sit amet, ", "consectetur, ", "adipisci velit...")

##### In Python

        a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."
        b = svc.Wrap(a, 20)
        # ('Neque porro ', 'quisquam est qui ', 'dolorem ipsum quia ', 'dolor sit amet, ', 'consectetur, ', 'adipisci velit...')

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic o negli script in Python.

Argomenti correlati

Servizio ScriptForge.Array

Funzione String