Spis treści

# Usługa ScriptForge.String

Usługa String udostępnia zbiór metod przetwarzania ciągów. Metody te można wykorzystać do:

- Sprawdzania zawartości ciągów

- Formatowania ciągów znaków, przycinając, justując lub zawijając ich zawartość

- Używania wyrażeń regularnych, aby wyszukiwać i zamieniać podciągi

- Stosowania algorytmu mieszającego na ciągach znaków itp.

## Definicje

### Podziały wierszy

Usługa String rozpoznaje następujące podziały wierszy:

Nazwa symboliczna | Numer ASCII
--- | ---
Przesunięcie wiersza Tabulator pionowy Powrót karetki Powrót karetki + przesunięcie wiersza Separator pliku Separator grupy Separator rekordów Następny wiersz Separator wiersza Separator akapitu | 10 12 13 13 + 10 28 29 30 133 8232 8233

### Białe znaki

Usługa String rozpoznaje następujące białe znaki:

Nazwa symboliczna | Numer ASCII
--- | ---
Spacja Tabulator poziomy Przesunięcie wiersza Tabulator pionowy Wysunięcie formularza Powrót karetki Następny wiersz Spacja nierozdzielająca Separator wiersza Separator akapitu | 32 9 10 11 12 13 133 160 8232 8233

### Sekwencje ucieczki

Poniżej znajduje się lista sekwencji ucieczki, które można zastosować w ciągach znaków.

Sekwencja ucieczki | Nazwa symboliczna | Numer ASCII
--- | --- | ---
\n \r \t | Przesunięcie wiersza Powrót karetki Tabulator poziomy | 10 13 9

Aby sekwencja ucieczki "\n" była interpretowana jako rzeczywisty ciąg znaków, po prostu użyj "\\n" zamiast "\" & Chr(10).

### Znaki niedrukowalne:

Znaki zdefiniowane w bazie danych znaków Unicode jako „Inne” lub „Separator” są uważane za znaki niedrukowalne.

Znaki sterujące (kod ASCII <= 0x1F) są również uważane za niedrukowalne.

### Cudzysłowy wewnątrz ciągów:

Aby dodać cudzysłowy w łańcuchach, użyj \' (pojedynczy cudzysłów) lub \" (podwójny cudzysłów). Na przykład:

- Ciąg [str\'i\'ng] jest interpretowany jako [str'i'ng]

- Ciąg [str\"i\"ng] jest interpretowany jako [str"i"ng]

## Wywoływanie usługi

Przed użyciem usługi ScriptForge.String należy załadować bibliotekę ScriptForge za pomocą:

##### W języku Basic

          GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Załadowanie biblioteki spowoduje utworzenie obiektu SF_String, którego można użyć do wywołania metod w usłudze String.

Poniższe fragmenty kodu przedstawiają trzy sposoby wywoływania metod z usługi String (jako przykład użyto metody 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

##### W języku Python

Poniższy fragment kodu ilustruje sposób wywoływania metod z usługi String w skryptach Pythona. Jako przykład użyto metody IsIPv4.

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

## Właściwości

Obiekt SF_String udostępnia następujące właściwości skryptów Basic:

Nazwa | Tylko do odczytu | Opis
--- | --- | ---
sfCR | Tak | Powrót karetki: Chr(13)
sfCRLF | Tak | Powrót karetki + przesunięcie wiersza: Chr(13) & Chr(10)
sfLF | Tak | Przesunięcie wiersza: Chr(10)
sfNEWLINE | Tak | Powrót karetki + wysunięcie wiersza, który może wynosić 1) Chr(13) & Chr(10) lub 2) Wysunięcie wiersza: Chr(10) w zależności od systemu operacyjnego.
sfTAB | Tak | Tabulator poziomy: Chr(9)

Możesz użyć powyższych właściwości, aby zidentyfikować lub wstawić odpowiednie znaki wewnątrz ciągów. Na przykład przesunięcie wiersza można zastąpić przez SF_String.sfLF.

Lista metod w usłudze 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

Pierwszym argumentem większości metod jest ciąg znaków, który należy wziąć pod uwagę. Jest on zawsze przekazywany przez odniesienie i pozostawiany bez zmian. Metody takie jak Capitalize, Escape itp. po wykonaniu zwracają nowy ciąg.

Ponieważ Python ma kompleksową wbudowaną obsługę ciągów znaków, większość metod usługi String jest dostępna tylko dla skryptów Basic. Metody dostępne dla języka Basic i Python to: HashStr, IsADate, IsEmail, IsFileName, IsIBAN, IsIPv4, IsLike, IsSheetName, IsUrl, SplitNotQuoted i Wrap.

## Capitalize

Zamienia na wielką literę pierwszy znak każdego słowa w ciągu wejściowym.

### Składnia:

svc.Capitalize(inputstr: str): str

### Parametry:

inputstr: ciąg, który ma być pisany wielką literą.

### Przykład:

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

## Count

Zlicza liczbę wystąpień podciągu lub wyrażenia regularnego w ciągu.

### Składnia:

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

### Parametry:

inputstr: ciąg wejściowy, który ma zostać sprawdzony

substring: podciąg lub wyrażenie regularne, które ma być użyte podczas wyszukiwania

isregex: użyj True, jeśli podciąg jest wyrażeniem regularnym (domyślnie = False)

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

        ' Zlicza wystąpienia podciągu "or" w ciągu wejściowym (zwraca 2)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)
        ' Zlicza słowa zawierające tylko małe litery (zwraca 7)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)

Aby dowiedzieć się więcej o wyrażeniach regularnych, zapoznaj się z dokumentacją Pythona dotyczącą Regular Expression Operations.

## EndsWith

Zwraca True, jeśli ciąg kończy się określonym podciągiem.

Funkcja zwraca False, gdy ciąg lub podciąg ma długość = 0 lub gdy podciąg jest dłuższy niż ciąg.

### Składnia:

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

### Parametry:

inputstr: ciąg do przetestowania.

substring: podciąg do przeszukania na końcu inputstr.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

        ' Zwraca True, ponieważ metoda została wywołana z domyślną wartością CaseSensitive = False
        MsgBox SF_String.EndsWith("abcdefg", "EFG")
        ' Zwraca wartość False ze względu na parametr CaseSensitive
        MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)

## Escape

Konwertuje podziały wierszy i tabulatory zawarte w ciągu wejściowym na ich równoważną sekwencję ucieczki (\\, \n, \r, \t).

### Składnia:

svc.Escape(inputstr: str): str

### Parametry:

inputstr: ciąg do przekonwertowania.

### Przykład:

        ' Zwraca ciąg "abc\n\tdef\\n"
        MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")

## ExpandTabs

Zastępuje znaki tabulacji Chr(9) spacjami, aby odtworzyć zachowanie tabulatorów.

Jeśli zostanie znaleziony podział wiersza, rozpoczynany jest nowy wiersz, a licznik znaków jest resetowany.

### Składnia:

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

### Parametry:

inputstr: ciąg, który ma zostać rozwinięty

tabsize: ten parametr służy do określenia tabulatorów za pomocą wzoru: TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (domyślnie = 8)

### Przykład:

        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

Zastępuje wszystkie niedrukowalne znaki w ciągu wejściowym danym znakiem.

### Składnia:

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

### Parametry:

inputstr: ciąg, który ma zostać przeszukany

replacedby: zero, jeden lub więcej znaków, które zastąpią wszystkie niedrukowalne znaki w inputstr (domyślnie = "")

### Przykład:

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

## FindRegex

Znajduje w ciągu podciąg pasujący do danego wyrażenia regularnego.

### Składnia:

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

### Parametry:

inputstr: ciąg, który ma zostać przeszukany

regex: wyrażenie regularne

start: pozycja w ciągu, od której rozpocznie się wyszukiwanie. Parametr ten przekazywany jest przez odwołanie, zatem po wykonaniu wartość start będzie wskazywała pierwszy znak znalezionego podciągu. Jeśli nie zostanie znaleziony pasujący podciąg, start zostanie ustawione na 0.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

forward: określa kierunek poszukiwań. Jeśli True, wyszukiwanie będzie kontynuowane. Jeśli False wyszukiwanie zostanie cofnięte (domyślnie = True)

W pierwszej iteracji, jeśli forward = True, to start powinno być równe 1, natomiast jeśli forward = False to start powinno być równe Len(inputstr)

### Przykład:

        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

W powyższym przykładzie nowej wartości lStart można użyć do dalszego wyszukiwania tego samego ciągu wejściowego, ustawiając parametr Start na lStart + Len(result) w następnej iteracji.

## HashStr

Funkcje skrótu są wykorzystywane w niektórych algorytmach kryptograficznych, w podpisach cyfrowych, kodach uwierzytelniających wiadomości, wykrywaniu manipulacji, odciskach palców, sumach kontrolnych (sprawdzanie integralności wiadomości), tabelach skrótów, przechowywaniu haseł i wielu innych.

Metoda HashStr zwraca wynik funkcji skrótu zastosowanej do danego ciągu i przy użyciu określonego algorytmu pod postacią ciągu małych cyfr szesnastkowych.

Obsługiwane algorytmy mieszające to: MD5, SHA1, SHA224, SHA256, SHA384 i SHA512.

### Składnia:

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

### Parametry:

inputstr: ciąg znaków do zaszyfrowania. Zakłada się, że jest zakodowany w UTF-8. Algorytm mieszający potraktuje ciąg jako strumień bajtów.

algorithm: jeden z obsługiwanych algorytmów wymienionych powyżej, przekazywany jako ciąg znaków.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

## HtmlEncode

Koduje ciąg wejściowy w kodach znaków HTML, zastępując znaki specjalne ich odpowiednikami &.

Na przykład znak é zostanie zastąpiony przez &eacute; lub równoważny numeryczny kod HTML.

### Składnia:

svc.HtmlEncode(inputstr: str): str

### Parametry:

inputstr: ciąg do zakodowania.

### Przykład:

        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

Zwraca wartość True, jeśli ciąg wejściowy jest prawidłową datą zgodnie z określonym formatem daty.

### Składnia:

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

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False

dateformat: format daty jako ciąg. Może to być "YYYY-MM-DD" (domyślnie), "DD-MM-YYYY" lub "MM-DD-YYYY"

Dywiz (-) można zastąpić kropką (.), ukośnikiem (/) lub spacją.

Jeśli format jest nieprawidłowy, metoda zwraca False.

### Przykład:

##### W języku Basic

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

Ta metoda sprawdza format ciągu wejściowego bez przeprowadzania kontroli specyficznych dla kalendarza. Dlatego nie testuje ciągu wejściowego dla lat lub miesięcy przestępnych mających 30 lub 31 dni. W tym celu skorzystaj z wbudowanej funkcji IsDate.

Poniższy przykład pokazuje różnicę pomiędzy metodami IsADate (ScriptForge) a funkcją IsDate (wbudowaną).

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

##### W języku Python

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

## IsAlpha

Zwraca True, jeśli wszystkie znaki w ciągu są alfabetyczne.

Znaki alfabetyczne to znaki zdefiniowane w Unicode Character Database jako Letter.

### Składnia:

svc.IsAlpha(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsAlphaNum

Zwraca wartość True, jeśli wszystkie znaki w ciągu są literami, cyframi lub "_" (podkreśleniem). Pierwszy znak nie może być cyfrą.

### Składnia:

svc.IsAlphaNum(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsAscii

Zwraca True, jeśli wszystkie znaki w ciągu są znakami ASCII.

### Składnia:

svc.IsAscii(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsDigit

Zwraca wartość True, jeśli wszystkie znaki w ciągu są cyframi.

### Składnia:

svc.IsDigit(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsEmail

Zwraca wartość True, jeśli ciąg znaków jest prawidłowym adresem e-mail.

### Składnia:

svc.IsEmail(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

##### W języku 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

##### W języku 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

Zwraca True, jeśli ciąg znaków jest prawidłową nazwą pliku w danym systemie operacyjnym.

### Składnia:

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

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

osname: nazwa systemu operacyjnego jako ciąg. Może to być "WINDOWS", "LINUX", "MACOSX" lub "SOLARIS".

Wartość domyślna to bieżący system operacyjny, w którym działa skrypt.

### Przykład:

##### W języku 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

##### W języku 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

Zwraca True, jeśli wszystkie znaki w ciągu są cyframi szesnastkowymi.

### Składnia:

svc.IsHexDigit(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

Cyfry szesnastkowe mogą być poprzedzone "0x" lub "&H".

### Przykład:

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

## IsIBAN

Zwraca wartość True, jeśli ciąg znaków jest prawidłowym międzynarodowym numerem konta bankowego (IBAN). W porównaniu nie jest rozróżniana wielkość liter.

### Składnia:

svc.IsIBAN(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Zwracana wartość:

True, jeśli ciąg zawiera prawidłowy numer IBAN.

### Przykład:

        ' 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

Zwraca wartość True, jeśli ciąg znaków jest prawidłowym adresem IP(v4).

### Składnia:

svc.IsIPv4(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

##### W języku 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

##### W języku 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

Zwraca wartość True, jeśli cały ciąg wejściowy pasuje do danego wzorca zawierającego symbole wieloznaczne.

### Składnia:

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

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

pattern: wzór jako ciąg. Symbole wieloznaczne to:

- "?" reprezentuje dowolny pojedynczy znak;

- "*" reprezentuje zero, jeden lub wiele znaków.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

##### W języku 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

##### W języku 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

Zwraca True, jeśli wszystkie znaki w ciągu są małymi literami. Znaki inne niż alfabetyczne są ignorowane.

### Składnia:

svc.IsLower(inputstr: str): bool

### Parametry:

InputStr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsPrintable

Zwraca True, jeśli wszystkie znaki w ciągu nadają się do wydrukowania.

### Składnia:

svc.IsPrintable(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsRegex

Zwraca wartość True, jeśli cały ciąg wejściowy pasuje do danego wyrażenia regularnego.

### Składnia:

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

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

regex: wyrażenie regularne. Jeśli jest pusty, metoda zwraca False.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

            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

Zwraca True, jeśli ciąg wejściowy jest prawidłową nazwą arkusza Calc.

### Składnia:

svc.IsSheetName(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

##### W języku Basic

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

##### W języku Python

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

Nazwa arkusza nie może zawierać znaków [ ] * ? : / \ lub znak ' (apostrof) jako pierwszy lub ostatni znak.

## IsTitle

Zwraca True, jeśli pierwszy znak każdego słowa jest pisany wielkimi literami, a pozostałe znaki małymi literami.

### Składnia:

svc.IsTitle(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

        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

Zwraca True, jeśli wszystkie znaki w ciągu są wielkimi literami. Znaki inne niż alfabetyczne są ignorowane.

### Składnia:

svc.IsUpper(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## IsUrl

Zwraca wartość True, jeśli ciąg znaków jest prawidłowym bezwzględnym adresem URL (Uniform Resource Locator). Obsługiwane są tylko protokoły http, https i ftp.

### Składnia:

svc.IsUrl(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

##### W języku Basic

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

##### W języku 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

Zwraca wartość True, jeśli wszystkie znaki w ciągu znaków są spacjami.

### Składnia:

svc.IsWhitespace(inputstr: str): bool

### Parametry:

inputstr: ciąg do sprawdzenia. Jeśli jest pusty, metoda zwraca False.

### Przykład:

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

## JustifyCenter

Zwraca ciąg wejściowy wyrównany do środka.

Początkowe i końcowe puste znaki są usuwane z ciągu, a pozostałe znaki są dopełniane w lewo i w prawo za pomocą znaków padding, tak aby ciąg miał całkowitą długość length.

### Składnia:

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

### Parametry:

inputstr: ciąg znaków, który ma być wyrównany do środka. Jeśli jest pusty, metoda zwraca pusty ciąg.

length: długość wynikowego ciągu (domyślnie = długość ciągu wejściowego).

Jeśli określona długość jest krótsza niż ciąg wejściowy wyrównany do środka, zwrócony ciąg zostanie obcięty.

padding: pojedynczy znak używany jako dopełnienie (domyślnie = spacja ASCII " ").

### Przykład:

        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

Zwraca ciąg wejściowy wyrównany do lewej.

Początkowe i końcowe puste znaki są usuwane z ciągu, a pozostałe znaki są dopełniane w prawo znakami padding, tak aby ciąg miał całkowitą długość length.

### Składnia:

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

### Parametry:

inputstr: ciąg znaków, który ma być wyrównany do lewej strony. Jeśli jest pusty, metoda zwraca pusty ciąg.

length: długość wynikowego ciągu (domyślnie = długość ciągu wejściowego).

Jeśli określona długość jest krótsza niż ciąg wejściowy wyrównany do lewej, zwrócony ciąg zostanie obcięty.

padding: pojedynczy znak używany jako uzupełnienie (domyślnie = spacja ASCII " ").

### Przykład:

        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

Zwraca ciąg wejściowy wyrównany do prawej.

Początkowe i końcowe puste znaki są usuwane z ciągu, a pozostałe znaki są dopełniane w lewo znakami padding, dzięki czemu ciąg ma całkowitą długość length.

### Składnia:

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

### Parametry:

inputstr: ciąg znaków, który ma być wyrównany do prawej strony. Jeśli jest pusty, metoda zwraca pusty ciąg.

length: długość wynikowego ciągu (domyślnie = długość ciągu wejściowego).

Jeśli określona długość jest krótsza niż ciąg wejściowy wyrównany do prawej strony, zwrócony ciąg zostanie obcięty.

padding: pojedynczy znak używany jako uzupełnienie (domyślnie = spacja ASCII " ").

### Przykład:

        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

Zwraca ciąg wejściowy ujęty w pojedynczy lub podwójny cudzysłów. Istniejące cudzysłowy pozostają niezmienione, łącznie z cudzysłowami wiodącymi i/lub końcowymi.

### Składnia:

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

### Parametry:

inputstr: ciąg znaków, który należy ująć w cudzysłów.

quotechar: pojedynczy (') lub podwójny (") cudzysłów (domyślny).

### Przykład:

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

Ta metoda może być przydatna podczas przygotowywania pola tekstowego do zapisania w pliku typu CSV, który wymaga, aby wartości tekstowe były ujęte w pojedyncze lub podwójne cudzysłowy.

## ReplaceChar

Zastępuje wszystkie wystąpienia znaków określonych w parametrze Before odpowiednimi znakami określonymi w parametrze After.

Jeśli długość Before jest większa niż długość After, pozostałe znaki w Before są zastępowane przez ostatni znak w After.

### Składnia:

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

### Parametry:

inputstr: ciąg wejściowy, w którym nastąpi zamiana.

before: ciąg zawierający znaki, które będą wyszukiwane w ciągu wejściowym w celu zamiany.

after: ciąg znaków zawierający nowe znaki, które zastąpią te zdefiniowane w before.

### Przykład:

        ' Zastępuje znaki akcentowane
        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"

Usługa SF_String udostępnia przydatne stałe publiczne dla zestawów znaków łacińskich, jak pokazano w poniższym przykładzie:

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

## ReplaceRegex

Zastępuje wszystkie wystąpienia danego wyrażenia regularnego nowym ciągiem znaków.

### Składnia:

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

### Parametry:

inputstr: ciąg wejściowy, w którym nastąpi zamiana.

regex: wyrażenie regularne.

newstr: ciąg zastępujący.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

        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żda mała litera zostaje zastąpiona przez "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żde słowo zostaje zastąpione przez "x")

## ReplaceStr

Zastępuje w ciągu niektóre lub wszystkie wystąpienia tablicy ciągów tablicą nowych ciągów.

### Składnia:

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

### Parametry:

inputstr: ciąg wejściowy, w którym nastąpi zamiana.

oldstr: pojedynczy ciąg lub tablica ciągów. Ciągi o zerowej długości są ignorowane.

newstr: ciąg zastępujący lub tablica ciągów zastępujących.

Jeśli oldstr jest tablicą, każde wystąpienie dowolnego elementu w oldstr jest zastępowane przez newstr.

Jeśli oldstr i newstr są tablicami, zamiany następują jedna po drugiej, aż do UBound(newstr).

Jeśli oldstr ma więcej wpisów niż newstr, to pozostałe elementy w oldstr są zastępowane ostatnim elementem w newstr.

occurrences: maksymalna liczba zamian. Wartość domyślna to 0, co oznacza, że wszystkie wystąpienia zostaną zastąpione.

Gdy oldstr jest tablicą, parametr occurrence jest obliczany oddzielnie dla każdego elementu tablicy.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

        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

Zwraca ciąg znaków z czytelną reprezentacją argumentu, obcięty o podaną długość. Jest to przydatne głównie do celów debugowania lub rejestrowania.

Jeśli parametr anyvalue jest obiektem, zostanie on ujęty w nawiasy kwadratowe "[" i "]".

W ciągach znaków tabulatory i podziały wierszy są zastępowane przez \t, \n lub \r.

Jeśli ostateczna długość przekracza parametr maxlength, druga część ciągu jest zastępowana przez " ... (N)", gdzie N jest całkowitą długością oryginalnego ciągu przed obcięciem.

### Składnia:

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

### Parametry:

anyvalue: wartość wejściowa, która ma być reprezentowana. Może to być dowolna wartość, taka jak ciąg znaków, tablica, obiekt Basic, obiekt UNO itp.

maxlength: maksymalna długość wynikowego ciągu. Wartość domyślna to 0, co oznacza, że nie ma ograniczeń co do długości wynikowej reprezentacji.

### Przykład:

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

Reprezentacje typów danych, takie jak tablice lub obiekty ScriptForge.Dictionary, zawierają zarówno typy danych, jak i wartości:

        ' Przykład z wbudowaną tablicą Basic
        MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
        ' "[ARRAY] (0:2) (1, 2, Text\there)"
        ' Przykład z tablicą 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)"
        ' Przykład ze słownikiem 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

Zwraca ciąg wejściowy w odwrotnej kolejności.

Ta metoda odpowiada wbudowanej w Basic funkcji StrReverse.

Aby skorzystać z funkcji StrReverse, w module musi znajdować się komenda Option VBASupport 1.

### Składnia:

svc.Reverse(inputstr: str): str

### Parametry:

inputstr: ciąg, który ma zostać odwrócony.

### Przykład:

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

## SplitLines

Zwraca tablicę ciągów liczoną od zera zawierającą wiersze w ciągu wejściowym. Każdy element tablicy uzyskuje się poprzez podzielenie ciągu wejściowego na znaki nowego wiersza.

### Składnia:

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

### Parametry:

inputstr: ciąg, który ma zostać podzielony.

keepbreaks: jeśli True, w tablicy wyjściowej zachowywane są podziały wierszy (domyślnie = False).

### Przykład:

        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

Dzieli ciąg na tablicę elementów przy użyciu określonego ogranicznika.

Jeśli cytowany podciąg zawiera ogranicznik, jest on ignorowany. Jest to przydatne podczas analizowania rekordów w formacie CSV zawierających ciągi znaków w cudzysłowie.

### Składnia:

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

### Parametry:

inputstr: ciąg, który ma zostać podzielony.

separator: ciąg jednego lub większej liczby znaków, który będzie używany jako ogranicznik. Domyślnym ogranicznikiem jest znak spacji ASCII " ".

occurrences: maksymalna liczba podciągów do zwrócenia. Wartość domyślna to 0, co oznacza, że nie ma ograniczenia liczby zwracanych ciągów.

quotechar: pojedynczy (') lub podwójny (") cudzysłów.

### Przykład:

##### W języku 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""", "")

##### W języku 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""', '')

Podczas reprezentowania ciągów uważaj na różnice między Basic i Pythonem. Na przykład w języku Basic dwa znaki "" w ciągu znaków są interpretowane jako pojedynczy znak ". W Pythonie ciągi ujęte w pojedyncze cudzysłowy mogą zawierać znaki " bez konieczności ich podwajania.

## StartsWith

Zwraca True, jeśli pierwsze znaki ciągu są identyczne z danym podciągiem.

Ta metoda zwraca False, jeśli ciąg wejściowy lub podciąg ma długość = 0 lub gdy podciąg jest dłuższy niż ciąg wejściowy.

### Składnia:

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

### Parametry:

inputstr: ciąg do przetestowania.

substring: podciąg do przeszukania na początku inputstr.

casesensitive: podczas wyszukiwania może być uwzględniana wielkość liter lub nie (domyślnie = False).

### Przykład:

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

## TrimExt

Zwraca ciąg wejściowy bez początkowych i końcowych białych znaków.

### Składnia:

svc.TrimExt(inputstr: str): str

### Parametry:

inputstr: ciąg do przycięcia.

### Przykład:

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

## Unescape

Konwertuje dowolną sekwencję ucieczki (\\, \n, \r, \t) w ciągu wejściowym na odpowiadający jej znak ASCII.

### Składnia:

svc.Unescape(inputstr: str): str

### Parametry:

inputstr: ciąg do przekonwertowania.

### Przykład:

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

## Unquote

Usuwa pojedyncze lub podwójne cudzysłowy otaczające ciąg wejściowy.

Jest to przydatne podczas analizowania rekordów w formacie CSV zawierających ciągi znaków w cudzysłowie.

### Składnia:

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

### Parametry:

inputstr: ciąg, z którego mają zostać usunięte cudzysłowy.

quotechar: pojedynczy (') lub podwójny (") cudzysłów (domyślny).

### Przykład:

        Dim s as String
        ' s = "Some text" (bez cudzysłowów zamykających)
        s = SF_String.Unquote("""Some text""")
        ' Poniższy ciąg nie zawiera cudzysłowów, więc pozostaje niezmieniony
        ' s = "Some text" (niezmieniony)
        s = SF_String.Unquote("Some text")
        ' Cudzysłowy wewnątrz ciągu nie są usuwane
        ' s = "The ""true"" meaning" (niezmieniony)
        s = SF_String.Unquote("The ""true"" meaning")

## Wrap

Konwertuje ciąg wejściowy na tablicę podciągów, tak aby każdy element tablicy miał co najwyżej określoną liczbę znaków.

W praktyce ta metoda zwraca tablicę wierszy wyjściowych liczoną od zera, bez znaków nowego wiersza na końcu, z wyjątkiem istniejących wcześniej podziałów wierszy.

Tabulatory są zastępowane spacjami, tak jak w przypadku metody ExpandTabs.

Symboliczne podziały wierszy są zastępowane odpowiadającymi im znakami ASCII.

Jeśli zawinięte dane wyjściowe nie zawierają treści, zwrócona tablica jest pusta.

### Składnia:

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

### Parametry:

inputstr: ciąg do zawinięcia.

width: maksymalna liczba znaków w każdym wierszu (domyślnie = 70).

tabsize: przed zawinięciem tekstu istniejące znaki tabulacji Chr(9) są zastępowane spacjami. Argument tabsize definiuje pozycje tabulatora przy TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (domyślnie = 8).

### Przykład:

##### W języku 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...")

##### W języku 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...')

Wszystkie podstawowe procedury lub identyfikatory ScriptForge poprzedzone znakiem podkreślenia „_” są zarezerwowane do użytku wewnętrznego. Nie należy ich używać w makrach Basic ani skryptach Pythona.

Tematy pokrewne

Usługa ScriptForge.Array

Funkcja String