Obsah

# Služba ScriptForge.String

Služba String nabízí sadu metod na zpracování řetězců. Pomocí těchto metod je možné:

- Validovat obsah řetězců.

- Formátovat řetězce ořezáváním, zarovnáním nebo zalamováním jejich obsahu.

- Používat regulární výrazy pro vyhledávání a nahrazování podřetězců.

- Používat na řetězce hashovací algoritmy atd.

## Definice

### Zalomení řádku

Služba String rozpoznává následující zalomení řádku:

Název symbolu | Číslo ASCII
--- | ---
Line feed Vertikální tabulátor Carriage return Line feed + Carriage return Oddělovač souborů Oddělovač skupin Oddělovač záznamů Další řádek Oddělovač řádků Oddělovač odstavců | 10 12 13 13 + 10 28 29 30 133 8232 8233

### Prázdné znaky

Služba String rozpoznává následující prázdné znaky:

Název symbolu | Číslo ASCII
--- | ---
Mezera horizontální tabulátor line feed vertikální tabulátor form feed carriage return další řádek nezlomitelná mezera oddělovač řádků oddělovač odstavců | 32 9 10 11 12 13 133 160 8232 8233

### Escape sekvence

Následuje seznam escape sekvencí, které lze v řetězcích použít.

Escape sekvence | Název symbolu | Číslo ASCII
--- | --- | ---
\n \r \t | line feed carriage return horizontální tabulátor | 10 13 9

Chcete-li, aby se escape sekvence "\n" interpretovala jako skutečný řetězec, jednoduše použijte "\\n" místo "\" & Chr(10).

### Netisknutelné znaky:

Za netisknutelné se považují znaky definované v databázi znaků Unicode (Unicode Character Database) jako „Other“ nebo „Separator“.

Za netisknutelné se považují také řídicí znaky (kód ASCII <= 0x1F).

### Uvozovky v řetězcích:

Uvozovky přidáte do řetězců pomocí \' (jednoduchá uvozovka) nebo \" (dvojitá uvozovka). Například:

- Řetězec [str\'i\'ng] je interpretován jako [str'i'ng]

- Řetězec [str\"i\"ng] je interpretován jako [str"i"ng]

## Volání služby

Před používáním služby ScriptForge.String je nutné načíst knihovnu ScriptForge pomocí:

##### V Basicu

          GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Načtení knihovny vytvoří objekt SF_String, který lze používat pro volání metod služby String.

Následující části kódu ukazují různé způsoby volání metod služby String (jako příklad je uvedena metoda Capitalize):

        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

##### V Pythonu

Níže uvedená část kódu ukazuje, jak volat metody služby String ze skriptů Pythonu. Jako příklad je použita metoda IsIPv4.

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

## Vlastnosti

Objekt SF_String poskytuje skriptům Basicu následující vlastnosti:

Název | Pouze pro čtení | Popis
--- | --- | ---
sfCR | ano | carriage return: Chr(13)
sfCRLF | ano | carriage return + line feed: Chr(13) & Chr(10)
sfLF | ano | line feed: Chr(10)
sfNEWLINE | ano | carriage return + line feed, což může být podle operačního systému: 1) Chr(13) & Chr(10) nebo 2) Linefeed: Chr(10)
sfTAB | ano | horizontální tabulátor: Chr(9)

Výše uvedené vlastnosti může použít pro identifikaci nebo vkládání odpovídajících znaků do řetězců. Například line feed lze nahradit vlastností SF_String.sfLF.

Seznam metod služby 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

Prvním argumentem je u většiny metod zpracovávaný řetězec. Vždy se předává odkazem, a zůstává tedy nezměněn. Metody jako Capitalize či Escape vrací po provedení nový řetězec.

Protože v Pythonu je již obsáhlá podpora pro řetězce vestavěná, většina metod služby String je k dispozici pouze pro skripty Basicu. Metodami dostupnými v Basicu i Pythonu jsou: HashStr, IsADate, IsEmail, IsFileName, IsIBAN, IsIPv4, IsLike, IsSheetName, IsUrl, SplitNotQuoted a Wrap.

## Capitalize

Změní první písmeno každého slova vstupního řetězce na velké.

### Syntaxe:

svc.Capitalize(inputstr: str): str

### Parametry:

inputstr: Řetězec, u nějž se mají první písmena změnit.

### Příklad:

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

## Count

Zjistí pro řetězec počet výskytů podřetězce nebo regulárního výrazu.

### Syntaxe:

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

### Parametry:

inputstr: Vstupní řetězec, pro nějž se má počet zjistit.

substring: Podřetězec nebo regulární výraz použitý pro vyhledávání.

isregex: Použijte True, pokud je podřetězec regulárním výrazem (výchozí = False)

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

        ' Spočítá výskytu podřetězce "or" ve vstupním řetězci (vrátí 2)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)
        ' Spočítá slova psaná pouze malými písmeny (vrátí 7)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)

Podrobnosti o regulárních výrazem naleznete v dokumentaci Pythonu na stránce Regular Expression Operations.

## EndsWith

Vrátí True, pokud řetězec končí zadaným podřetězcem.

Funkce vrátí False také tehdy, má-li řetězec nebo podřetězec délku 0 nebo je-li podřetězec delší než řetězec.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má ověřit.

substring: Podřetězec, který se má vyhledat na konci řetězce inputstr.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

        ' Vrátí True, protože metoda byla zavolána s výchozím parametrem casesensitive = False
        MsgBox SF_String.EndsWith("abcdefg", "EFG")
        ' Vzhledem k parametru casesensitive vrátí False
        MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)

## Escape

Převede konce řádků a tabulátor ze vstupního řetězce na odpovídající escape sekvence (\\, \n, \r, \t).

### Syntaxe:

svc.Escape(inputstr: str): str

### Parametry:

inputstr: Řetězec, který se má převést.

### Příklad:

        ' Vrátí řetězec "abc\n\tdef\\n"
        MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")

## ExpandTabs

Nahradí znaky tabulátoru Chr(9) znaky mezery tak, aby byl napodoben krok tabulátoru.

Při zalomení řádku se začne vytvářet nový řádek a vynuluje se čítač znaků.

### Syntaxe:

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

### Parametry:

inputstr: Vstupní řetězec, který se má upravit.

tabsize: Tento parametr odpovídající kroku tabulátoru se použije pro určení umístění textu, a to podle vzorců: tabsize + 1, 2 * tabsize + 1 , ... N * tabsize + 1 (výchozí = 8)

### Příklad:

        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

Nahradí všechny netisknutelné znaky vstupního řetězce zadaným znakem.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má prohledat.

replacedby: Žádný, jeden či více znaků, které nahradí každý netisknutelný znak v řetězci inputstr (výchozí = "").

### Příklad:

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

## FindRegex

Najde v řetězci podřetězec odpovídající zadanému regulárnímu výrazu.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má prohledat.

regex: Regulární výraz.

start: Pozice v řetězci, od níž vyhledávání začne. Tento parametr se předává odkazem, po provedení metody tedy bude hodnota start odkazovat na první znak nalezeného řetězce. Nebude-li nalezen žádný, hodnota start bude 0.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

forward: Určuje směr vyhledávání. V případě True vyhledávání postupuje směrem dopředu, v opačném případě směrem zpět (výchozí = True).

Po první iteraci vyhledávání by měla být v případě forward = True hodnota start rovna 1, zatímco v případě forward = False by se tato hodnota měla rovnat Len(inputstr).

### Příklad:

        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

Ve výše uvedeném příkladu je možné využít novou hodnotu lStart k tomu, aby vyhledávání pokračovalo. K tomu je nutné natavit pro další iteraci parametr start na hodnotu lStart + Len(result).

## HashStr

Hashovací funkce se používají u některých kryptografických algoritmů, elektronických podpisů, autentizačních kódů, detekování podvodů, otisků (fingerprints), kontrolních součtů (kontrolách integrity zpráv), hashovacích tabulek, ukládání hesel apod.

Metoda HashStr vrátí výsledek hashovací funkce použité s daným algoritmem na zadaný řetězec. Návratovou hodnotou je řetězec složený z malých šestnáctkových číslic.

Podporovanými hashovacími algoritmy jsou: MD5, SHA1, SHA224, SHA256, SHA384 a SHA512.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který má být zahashován. Předpokládá se, že je v kódování UTF-8. V hashovacím algoritmu bude řetězec považován za posloupnost bajtů.

algorithm: Některý z výše uvedených podporovaných algoritmů, zadaný jako řetězec.

### Příklad:

##### V Basicu

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

##### V Pythonu

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

## HtmlEncode

Zakóduje vstupní řetězec na HTML kódy znaků tím, že nahradí speciální znaky jim odpovídajícími řetězci, které začínají znakem &.

Například znak é bude nahrazen řetězcem &eacute; nebo odpovídajícím číselným HTML kódem.

### Syntaxe:

svc.HtmlEncode(inputstr: str): str

### Parametry:

inputstr: Řetězec, který se má zakódovat.

### Příklad:

        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

Vrátí True, pokud vstupní řetězec představuje pro určený formát platné datum.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má ověřit. Je-li prázdný, metoda vrátí False.

dateformat: Formát data jako řetězec. Je možné zvolit "YYYY-MM-DD" (výchozí), "DD-MM-YYYY" nebo "MM-DD-YYYY".

Spojovník (-) lze nahradit tečkou (.), lomítkem (/) nebo mezerou.

V případě neplatného formátu metoda vrátí False.

### Příklad:

##### V Basicu

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

Tato metoda kontroluje pouze formát vstupního řetězce, nekontroluje, zda odpovídá datu kalendáře. Neověřuje tedy vstupní řetězec vzhledem k přestupným rokům či tomu, zda má měsíc 30 nebo 31 dní. Pro takovou kontrolu je určena vestavěná funkce IsDate.

Níže uvedený příklad ukazuje rozdíl mezi metodou IsADate (ScriptForge) a funkcí IsDate (vestavěná).

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

##### V Pythonu

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

## IsAlpha

Vrátí True, jsou-li všechny znaky řetězce písmeny abecedy.

Znaky abecedy jsou ty znaky, které jsou v databázi znaků Unicode (Unicode Character Database) definovány jako Letter.

### Syntaxe:

svc.IsAlpha(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsAlphaNum

Vrátí True, jestliže jsou všechny znaky řetězce písmena abeceda, číslice nebo "_" (podtržítka). První znak nesmí být číslice.

### Syntaxe:

svc.IsAlphaNum(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsAscii

Vrátí True, jsou-li všechny znaky řetězce znaky ASCII.

### Syntaxe:

svc.IsAscii(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsDigit

Vrátí True, jsou-li všechny znaky řetězce číslicemi.

### Syntaxe:

svc.IsDigit(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsEmail

Vrátí True, jestliže řetězec představuje platnou e-mailovou adresu.

### Syntaxe:

svc.IsEmail(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

##### V Basicu

        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

##### V Pythonu

        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

Vrátí True, jestliže řetězec představuje v zadaném operačním systému platný název souboru.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

osname: Název operačního systému jako řetězec. Může se jednat o hodnoty "WINDOWS", "LINUX", "MACOSX" a "SOLARIS".

Výchozí hodnotou je operační systém, na kterém je skript spuštěn.

### Příklad:

##### V Basicu

        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

##### V Pythonu

        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

Vrátí True, jsou-li všechny znaky řetězce šestnáctkovými číslicemi.

### Syntaxe:

svc.IsHexDigit(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

Šestnáctkové číslice mohou být uvozeny znaky "0x" nebo "&H".

### Příklad:

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

## IsIBAN

Vrátí True, jestliže řetězec představuje platné Mezinárodní číslo bankovního účtu (International Bank Account Number, IBAN). Při porovnávání se nerozlišuje velikost písmen.

### Syntaxe:

svc.IsIBAN(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Návratová hodnota:

True, pokud řetězec obsahuje platné číslo IBAN.

### Příklad:

        ' 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

Vrátí True, jestliže řetězec představuje platnou IP adresu (v4).

### Syntaxe:

svc.IsIPv4(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

##### V Basicu

        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

##### V Pythonu

        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

Vrátí True, jestliže celý vstupní řetězec odpovídá zadanému vzorku obsahujícímu zástupné znaky.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

pattern: Vzorek jako řetězec. Zástupnými znaky jsou:

- "?" představuje libovolný jediný znak;

- "*" představuje žádný, jeden či více znaků.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

##### V Basicu

        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

##### V Pythonu

        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

Vrátí True, jsou-li všechny znaky vstupního řetězce malými písmeny. Znaky, které nejsou písmeny abecedy, se ignorují.

### Syntaxe:

svc.IsLower(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsPrintable

Vrátí True, jsou-li všechny znaky řetězce tisknutelné.

### Syntaxe:

svc.IsPrintable(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsRegex

Vrátí True, jestliže celý vstupní řetězec odpovídá zadanému regulárnímu výrazu.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

regex: Regulární výraz. Je-li prázdný, metoda vrátí False.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

            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

Vrátí True, jestliže vstupní řetězec představuje platný název listu Calcu.

### Syntaxe:

svc.IsSheetName(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

##### V Basicu

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

##### V Pythonu

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

Název listu nemůže obsahovat znaky [ ] * ? : / \ nebo znak ' (apostrof) na první nebo poslední pozici.

## IsTitle

Vrátí True, je-li první znak každého slova velké písmeno a ostatní znaky jsou malá písmena.

### Syntaxe:

svc.IsTitle(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

        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

Vrátí True, jsou-li všechny znaky vstupního řetězce velkými písmeny. Znaky, které nejsou písmeny abecedy, se ignorují.

### Syntaxe:

svc.IsUpper(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## IsUrl

Vrátí True, je-li řetězec platnou absolutní adresou URL (Uniform Resource Locator). Podporovány jsou pouze protokoly http, https a ftp.

### Syntaxe:

svc.IsUrl(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

##### V Basicu

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

##### V Pythonu

        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

Vrátí True, jsou-li všechny znaky řetězce prázdnými znaky.

### Syntaxe:

svc.IsWhitespace(inputstr: str): bool

### Parametry:

inputstr: Řetězec, který se má zkontrolovat. Je-li prázdný, metoda vrátí False.

### Příklad:

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

## JustifyCenter

Vrátí vstupní řetězec zarovnaný na střed.

Z řetězce se odstraní úvodní a koncové prázdné znaky a ke zbylým znakům se doleva a doprava doplní znaky padding tak, aby měl řetězec celkovou délku length.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zarovnat na střed. Je-li prázdný, metoda vrátí prázdný řetězec.

length: Délka výsledného řetězce (výchozí = délka vstupního řetězce).

Pokud je zadaná délka menší než na střed zarovnaný vstupní řetězec, vrácený řetězec bude oříznut.

padding: Jediný znak použitý pro doplnění (výchozí = znak mezery ASCII " ").

### Příklad:

        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

Vrátí vstupní řetězec zarovnaný vlevo.

Z řetězce se odstraní úvodní a koncové prázdné znaky a ke zbylým znakům se doprava doplní znaky padding tak, aby měl řetězec celkovou délku length.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zarovnat vlevo. Je-li prázdný, metoda vrátí prázdný řetězec.

length: Délka výsledného řetězce (výchozí = délka vstupního řetězce).

Pokud je zadaná délka menší než vlevo zarovnaný vstupní řetězec, vrácený řetězec bude oříznut.

padding: Jediný znak použitý pro doplnění (výchozí = znak mezery ASCII " ").

### Příklad:

        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

Vrátí vstupní řetězec zarovnaný vpravo.

Z řetězce se odstraní úvodní a koncové prázdné znaky a ke zbylým znakům se doleva doplní znaky padding tak, aby měl řetězec celkovou délku length.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zarovnat vpravo. Je-li prázdný, metoda vrátí prázdný řetězec.

length: Délka výsledného řetězce (výchozí = délka vstupního řetězce).

Pokud je zadaná délka menší než vpravo zarovnaný vstupní řetězec, vrácený řetězec bude oříznut.

padding: Jediný znak použitý pro doplnění (výchozí = znak mezery ASCII " ").

### Příklad:

        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

Vrátí vstupní řetězec uzavřený do jednoduchých či dvojitých uvozovek. Existující uvozovky nejsou dotčeny, a to včetně úvodních a koncových uvozovek.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má uzavřít do uvozovek.

quotechar: Jednoduchá ('), nebo dvojitá (") uvozovka (výchozí).

### Příklad:

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

Tato metoda může být užitečná při přípravě pole řetězců pro uložení do souboru typu CSV, který vyžaduje, aby textové hodnoty byly uzavřeny v jednoduchých nebo dvojitých uvozovkách.

## ReplaceChar

Nahradí všechny výskyty znaků uvedených v parametru before odpovídajícími znaky z parametru after.

Jestliže je řetězec before delší než after, zbývající znaky z before se nahradí posledním znakem z after.

### Syntaxe:

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

### Parametry:

inputstr: Vstupní řetězec, ve kterém se má nahrazení provést.

before: Řetězec se znaky, které budou ve vstupním řetězci vyhledány a nahrazeny.

after: Řetězec s novými znaky, které nahradí ty, které jsou uvedeny v řetězci before.

### Příklad:

        ' Nahradí znaky s diakritikou
        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"

Služba SF_String poskytuje přístup k užitečným konstantám pro skupiny znaků latinky, jak je ukázáno v příkladu níže:

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

## ReplaceRegex

Nahradí všechny výskyty zadaného regulárního výrazu novým řetězcem.

### Syntaxe:

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

### Parametry:

inputstr: Vstupní řetězec, ve kterém se má nahrazení provést.

regex: Regulární výraz.

newstr: Nahrazující řetězec.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

        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." (každé malé písmeno je nahrazeno znakem "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." (každé slovo je nahrazeno znakem "x")

## ReplaceStr

Nahradí v řetězci některé nebo všechny výskyty prvků z pole řetězců prvky z jiného pole řetězců.

### Syntaxe:

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

### Parametry:

inputstr: Vstupní řetězec, ve kterém se má nahrazení provést.

oldstr: Jediný řetězec nebo pole řetězců. Řetězce s nulovou délkou se ignorují.

newstr: Nahrazující řetězec nebo pole nahrazujících řetězců.

Je-li argument oldstr pole, každý výskyt jakékoliv jeho položky se nahradí argumentem newstr.

Je-li oldstr i newstr pole, nahrazovat se budou odpovídající položky až do indexu UBound(newstr).

Pokud má oldstr více položek než newstr, přebývající prvky v oldstr budou nahrazeny posledním prvkem newstr.

occurrences: Maximální počet nahrazení. Výchozí hodnotou je 0, což znamená, že se nahradí všechny výskyty.

Je-li parametr oldstr pole, parametr occurrence se uplatní zvlášť pro každou položku tohoto pole.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

        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

Vrátí řetězec s čitelnou reprezentací argumentu oříznutou na zadanou délku. Ta je využitelná zejména pro účely ladění a záznamu.

Pokud je parametr anyvalue objekt, bude uzavřen do hranatých závorek "[" a "]".

Tabulátory a zalomení řádku jsou v řetězcích nahrazeny sekvencemi \t a \n či \r.

Jestliže je délka výsledného řetězce větší než parametr maxlength, přesahující část řetězce se nahradí řetězcem " ... (N)", kde N je celková délka původního řetězce před zkrácením.

### Syntaxe:

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

### Parametry:

anyvalue: Vstupní hodnota, jejíž reprezentace se má připravit. Může se jednat o libovolnou hodnotu, například řetězec, pole, objekt Basicu, objekt UNO atd.

maxlength: Maximální délka výsledného řetězce. Výchozí hodnotou je 0, což znamená, že délka výsledné reprezentace není nijak omezena.

### Příklad:

        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]"

Reprezentace datových typů jako pole či objekt ScriptForge.Dictionary obsahují jak datový typ, tak hodnoty:

        ' Příklad s vestavěným polem Basicu
        MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
        ' "[ARRAY] (0:2) (1, 2, Text\there)"
        ' Příklad s polem knihovny 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)"
        ' Příklad s objektem Dictionary knihovny 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

Vrátí vstupní řetězec v obráceném pořadí.

Tato metoda odpovídá vestavěné funkci Basicu StrReverse.

Pro použití funkce StrReverse je nutné, aby se v modulu nacházel příkaz Option VBASupport 1.

### Syntaxe:

svc.Reverse(inputstr: str): str

### Parametry:

inputstr: Řetězec, který se má obrátit.

### Příklad:

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

## SplitLines

Vrátí pole řetězců začínající od 0 s řádky vstupního řetězce. Položky pole jsou získány rozdělením vstupního řetězce v místech se znaky konce řádku.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má rozdělit.

keepbreaks: Je-li True, ve výstupním poli se zachovají konce řádků (výchozí = False).

### Příklad:

        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

Rozdělí řetězec na pole prvků pomocí zadaného oddělovače.

Pokud se oddělovač nachází v podřetězci v uvozovkách, ignoruje se. To je užitečné při zpracování záznamů ve tvaru jako v souboru CSV, které obsahují řetězce v uvozovkách.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má rozdělit.

delimiter: Řetězec jednoho či více znaků, které se použijí jako oddělovač. Výchozím oddělovačem je znak mezery ASCII " ".

occurrences: Maximální počet vrácených podřetězců. Výchozí hodnotou je 0, což znamená, že počet vrácených řetězců není omezen.

quotechar: Jednoduchá ('), nebo dvojitá (") uvozovka.

### Příklad:

##### V Basicu

        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""", "")

##### V Pythonu

        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""', '')

Při reprezentaci řetězců mějte na paměti rozdíly mezi jazyky Basic a Python. V Basicu jsou například dva znaky "" uvnitř řetězce interpretovány jako jediný znak ". V Pythonu však mohou řetězce uzavřené v jednoduchých závorkách obsahovat znaky " bez nutnosti je zdvojovat.

## StartsWith

Vrátí True, pokud se první znaky řetězce shodují se zadaným podřetězcem.

Metoda vrátí False, má-li řetězec nebo podřetězec délku 0 nebo je-li podřetězec delší než vstupní řetězec.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má ověřit.

substring: Podřetězec, který se má vyhledat na začátku řetězce inputstr.

casesensitive: Zda se u vyhledávání rozlišuje velikost písmen (výchozí = False).

### Příklad:

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

## TrimExt

Vrátí vstupní řetězec bez úvodních a koncových prázdných znaků.

### Syntaxe:

svc.TrimExt(inputstr: str): str

### Parametry:

inputstr: Řetězec, který se má oříznout.

### Příklad:

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

## Unescape

Převede escape sekvence (\\, \n, \r, \t) ve vstupním řetězci na jim odpovídající znaky ASCII.

### Syntaxe:

svc.Unescape(inputstr: str): str

### Parametry:

inputstr: Řetězec, který se má převést.

### Příklad:

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

## Unquote

Odstraní jednoduché nebo dvojité uvozovky uzavírající vstupní řetězec.

To je užitečné při zpracování záznamů ve tvaru jako v souboru CSV, které obsahují řetězce v uvozovkách.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, ze kterého se mají uvozovky odstranit.

quotechar: Jednoduchá ('), nebo dvojitá (") uvozovka (výchozí).

### Příklad:

        Dim s as String
        ' s = "Some text" (bez uzavírajících uvozovek)
        s = SF_String.Unquote("""Some text""")
        ' Řetězec níže uzavírající závorky nemá, proto se nezmění
        ' s = "Some text" (nezměněno)
        s = SF_String.Unquote("Some text")
        ' Uvozovky uvnitř řetězce se neodstraní
        ' s = "The ""true"" meaning" (nezměněno)
        s = SF_String.Unquote("The ""true"" meaning")

## Wrap

Převede vstupní řetězec na pole podřetězců takovým způsobem, aby měla každá položka pole nejvýše zadaný počet znaků.

Metoda vrátí pole výstupních řádků začínající od 0, a to bez znaků nových řádků na konci (s výjimkou zalomení řádku, které v řetězci již existují).

Tabulátory jsou nahrazeny mezerami stejně jako při použití metody ExpandTabs.

Symbolická zalomení řádku jsou nahrazena odpovídajícími znaky ASCII.

Jestliže nemá připravený výstup žádný obsah, vrátí se prázdné pole.

### Syntaxe:

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

### Parametry:

inputstr: Řetězec, který se má zpracovat.

width: Maximální počet znaků každého řádku (výchozí = 70).

tabsize: Před rozdělením textu se stávající znaky tabulátoru Chr(9) nahradí mezerami. Argument tabsize určuje krok tabulátoru, text bude umístěn na pozicích tabsize + 1, 2 * tabsize + 1 , ... N * tabsize + 1 (výchozí = 8).

### Příklad:

##### V Basicu

        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...")

##### V Pythonu

        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...')

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.

Související témata

Služba ScriptForge.Array

Funkce String