Tartalom

# ScriptForge.String service

The String service provides a collection of methods for string processing. These methods can be used to:

- Validate the contents of strings

- Format strings by trimming, justifying or wrapping their contents

- Use regular expressions to search and replace substrings

- Apply hash algorithms on strings, etc.

## Meghatározások

### Sortörések

The String service recognizes the following line breaks:

Szimbolikus név | ASCII-kód
--- | ---
Line feed Vertical tab Carriage return Carriage return + Line feed File separator Group separator Record separator Next line Line separator Paragraph separator | 10 12 13 13 + 10 28 29 30 133 8232 8233

### Üres karakterek

The String service recognizes the following whitespaces:

Szimbolikus név | ASCII-kód
--- | ---
Space Horizontal tab Line feed Vertical tab Form feed Carriage return Next line No-break space Line separator Paragraph separator | 32 9 10 11 12 13 133 160 8232 8233

### Escape sorozatok

Below is a list of escape sequences that can be used in strings.

Escape sorozat | Szimbolikus név | ASCII-kód
--- | --- | ---
\n \r \t | Line feed Carriage return Horizontal tab | 10 13 9

To have the escape sequence "\n" interpreted as an actual string, simply use "\\n" instead of "\" & Chr(10).

### Nem nyomtatható karakterek:

Characters defined in the Unicode Character Database as “Other” or “Separator” are considered as non-printable characters.

Control characters (ASCII code <= 0x1F) are also considered as non-printable.

### Quotes inside strings:

To add quotes in strings use \' (single quote) or \" (double quote). For example:

- The string [str\'i\'ng] is interpreted as [str'i'ng]

- The string [str\"i\"ng] is interpreted as [str"i"ng]

## A szolgáltatás igénybevétele

Before using the ScriptForge.String service the ScriptForge library needs to be loaded using:

##### A Basic nyelvben

          GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

Loading the library will create the SF_String object that can be used to call the methods in the String service.

The following code snippets show the three ways to call methods from the String service (the Capitalize method is used as an example):

        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

##### A Python nyelvben

The code snippet below illustrates how to invoke methods from the String service in Python scripts. The IsIPv4 method is used as an example.

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

## Tulajdonságok

The SF_String object provides the following properties for Basic scripts:

Név | Írásvédett | Leírás
--- | --- | ---
sfCR | Igen | Carriage return: Chr(13)
sfCRLF | Igen | Carriage return + Linefeed: Chr(13) & Chr(10)
sfLF | Igen | Linefeed: Chr(10)
sfNEWLINE | Igen | Carriage return + Linefeed, which can be 1) Chr(13) & Chr(10) or 2) Linefeed: Chr(10) depending on the operating system.
sfTAB | Igen | Horizontal tabulation: Chr(9)

You can use the properties above to identify or insert the corresponding characters inside strings. For example, the Linefeed can be replaced by SF_String.sfLF.

List of Methods in the String Service

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

A legtöbb metódus első argumentuma a figyelembe veendő karakterlánc. Ezt mindig hivatkozással adjuk át, és változatlanul hagyjuk. Az olyan metódusok, mint a Capitalize, Escape, stb. a végrehajtásuk után egy új karakterláncot adnak vissza.

Mivel a Python átfogó beépített karakterlánc-támogatással rendelkezik, a String szolgáltatás legtöbb metódusa csak Basic parancsfájlok számára érhető el. A Basic és Python számára elérhető metódusok a következők: HashStr, IsADate, IsEmail, IsFileName, IsIBAN, IsIPv4, IsLike, IsSheetName, IsUrl, SplitNotQuoted és Wrap.

## Capitalize

Capitalizes the first character from each word in the input string.

### Szintaxis:

svc.Capitalize(inputstr: str): str

### Paraméterek:

inputstr: The string to be capitalized.

### Példa:

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

## Count

Counts the number of occurrences of a substring or a regular expression within a string.

### Szintaxis:

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

### Paraméterek:

inputstr: The input string to be examined

substring: The substring or the regular expression to be used during search

isregex: Use True if the substring is a regular expression (Default = False)

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

        'Counts the occurrences of the substring "or" inside the input string (returns 2)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)
        'Counts the number of words with only lowercase letters (returns 7)
        MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)

To learn more about regular expressions, refer to the Python's documentation on Regular Expression Operations.

## EndsWith

Returns True if a string ends with a specified substring.

The function returns False when either the string or the substring have a length = 0 or when the substring is longer than the string.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be tested.

substring: The substring to be searched at the end of inputstr.

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

        'Returns True because the method was called with the default CaseSensitive = False
        MsgBox SF_String.EndsWith("abcdefg", "EFG")
        'Returns False due to the CaseSensitive parameter
        MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)

## Escape

Converts linebreaks and tabs contained in the input string to their equivalent escaped sequence (\\, \n, \r, \t).

### Szintaxis:

svc.Escape(inputstr: str): str

### Paraméterek:

inputstr: The string to be converted.

### Példa:

        'Returns the string "abc\n\tdef\\n"
        MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")

## ExpandTabs

Replaces Tab characters Chr(9) by space characters to replicate the behavior of tab stops.

If a line break is found, a new line is started and the character counter is reset.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be expanded

tabsize: This parameter is used to determine the Tab stops using the formula: TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Default = 8)

### Példa:

        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

Replaces all non-printable characters in the input string by a given character.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be searched

replacedby: Zero, one or more characters that will replace all non-printable characters in inputstr (Default = "")

### Példa:

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

## FindRegex

Finds in a string a substring matching a given regular expression.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be searched

regex: The regular expression

start: A karakterlánc azon pozíciója, ahol a keresés kezdődik. Ez a paraméter hivatkozással kerül átadásra, így a végrehajtás után a start értéke a talált részlánc első karakterére mutat. Ha nem találunk megfelelő részláncot, a start értéke 0 lesz.

casesensitive: The search can be case sensitive or not (Default = False).

forward: Determines the direction of the search. If True, search moves forward. If False search moves backwards (Default = True)

At the first iteration, if forward = True, then start should be equal to 1, whereas if forward = False then start should be equal to Len(inputstr)

### Példa:

        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

A fenti példában az lStart új értéke felhasználható ugyanazon bemeneti karakterlánc további keresésére, ha a Start paramétert a következő iterációnál lStart + Len(result) értékre állítjuk.

## HashStr

Hash functions are used inside some cryptographic algorithms, in digital signatures, message authentication codes, manipulation detection, fingerprints, checksums (message integrity check), hash tables, password storage and much more.

The HashStr method returns the result of a hash function applied on a given string and using a specified algorithm, as a string of lowercase hexadecimal digits.

The hash algorithms supported are: MD5, SHA1, SHA224, SHA256, SHA384 and SHA512.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to hash. It is presumed to be encoded in UTF-8. The hashing algorithm will consider the string as a stream of bytes.

algorithm: One of the supported algorithms listed above, passed as a string.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

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

## HtmlEncode

Encodes the input string into the HTML character codes, replacing special characters by their & counterparts.

For example, the character é would be replaced by &eacute; or an equivalent numerical HTML code.

### Szintaxis:

svc.HtmlEncode(inputstr: str): str

### Paraméterek:

inputstr: The string to encode.

### Példa:

        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

Returns True if the input string is a valid date according to a specified date format.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False

dateformat: The date format, as a string. It can be either "YYYY-MM-DD" (default), "DD-MM-YYYY" or "MM-DD-YYYY"

The dash (-) may be replaced by a dot (.), a slash (/) or a space.

If the format is invalid, the method returns False.

### Példa:

##### A Basic nyelvben

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

Ez a módszer a bemeneti karakterlánc formátumát ellenőrzi, anélkül, hogy bármilyen naptár-specifikus ellenőrzést végezne. Ezért nem vizsgálja a bemeneti karakterláncot szökőévekre vagy 30 vagy 31 napos hónapokra. Ehhez lásd a IsDate beépített függvényt.

The example below shows the difference between the methods IsADate (ScriptForge) and the IsDate (built-in) function.

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

##### A Python nyelvben

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

## IsAlpha

Returns True if all characters in the string are alphabetic.

Alphabetic characters are those characters defined in the Unicode Character Database as Letter.

### Szintaxis:

svc.IsAlpha(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsAlphaNum

Returns True if all characters in the string are alphabetic, digits or "_" (underscore). The first character must not be a digit.

### Szintaxis:

svc.IsAlphaNum(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsAscii

Returns True if all characters in the string are ASCII characters.

### Szintaxis:

svc.IsAscii(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsDigit

Returns True if all characters in the string are digits.

### Szintaxis:

svc.IsDigit(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsEmail

Returns True if the string is a valid email address.

### Szintaxis:

svc.IsEmail(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

##### A Basic nyelvben

        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

##### A Python nyelvben

        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

Returns True if the string is a valid filename in a given operating system.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

osname: The operating system name, as a string. It can be "WINDOWS", "LINUX", "MACOSX" or "SOLARIS".

The default value is the current operating system on which the script is running.

### Példa:

##### A Basic nyelvben

        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

##### A Python nyelvben

        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

Returns True if all characters in the string are hexadecimal digits.

### Szintaxis:

svc.IsHexDigit(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

The hexadecimal digits may be prefixed with "0x" or "&H".

### Példa:

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

## IsIBAN

Returns True if the string is a valid International Bank Account Number (IBAN). The comparison is not case-sensitive.

### Szintaxis:

svc.IsIBAN(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Visszatérési érték:

True if the string contains a valid IBAN number.

### Példa:

        ' 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

Returns True if the string is a valid IP(v4) address.

### Szintaxis:

svc.IsIPv4(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

##### A Basic nyelvben

        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

##### A Python nyelvben

        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

Returns True if the whole input string matches a given pattern containing wildcards.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

pattern: The pattern as a string. Wildcards are:

- "?" represents any single character;

- "*" represents zero, one, or multiple characters.

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

##### A Basic nyelvben

        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

##### A Python nyelvben

        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

Returns True if all characters in the string are in lowercase. Non-alphabetic characters are ignored.

### Szintaxis:

svc.IsLower(inputstr: str): bool

### Paraméterek:

InputStr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsPrintable

Returns True if all characters in the string are printable.

### Szintaxis:

svc.IsPrintable(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsRegex

Returns True if the whole input string matches a given regular expression.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

regex: The regular expression. If empty, the method returns False.

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

            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

Returns True if the input string is a valid Calc sheet name.

### Szintaxis:

svc.IsSheetName(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

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

A sheet name must not contain the characters [ ] * ? : / \ or the character ' (apostrophe) as first or last character.

## IsTitle

Returns True if the first character of every word is in uppercase and the other characters are in lowercase.

### Szintaxis:

svc.IsTitle(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

        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

Returns True if all characters in the string are in uppercase. Non alphabetic characters are ignored.

### Szintaxis:

svc.IsUpper(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## IsUrl

Returns True if the string is a valid absolute URL (Uniform Resource Locator) address. Only the http, https and ftp protocols are supported.

### Szintaxis:

svc.IsUrl(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

        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

Returns True if all characters in the string are whitespaces

### Szintaxis:

svc.IsWhitespace(inputstr: str): bool

### Paraméterek:

inputstr: The string to be checked. If empty, the method returns False.

### Példa:

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

## JustifyCenter

Returns the input string center-justified.

The leading and trailing white spaces are stripped and the remaining characters are completed left and right up to a specified total length with the character padding.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be center-justified. If empty, the method returns an empty string.

length: The length of the resulting string (default = the length of the input string).

If the specified length is shorter than the center-justified input string, then the returned string is truncated.

padding: The single character to be used as padding (default = the ASCII space " ").

### Példa:

        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

Returns the input string left-justified.

The leading white spaces are stripped and the remaining characters are completed to the right up to a specified total length with the character padding.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be left-justified. If empty, the method returns an empty string.

length: The length of the resulting string (default = the length of the input string).

If the specified length is shorter than the left-justified input string, then the returned string is truncated.

padding: The single character to be used as padding (default = the ASCII space " ").

### Példa:

        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

Returns the input string right-justified.

The leading white spaces are stripped and the remaining characters are completed to the left up to a specified total length with the character padding.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be right-justified. If empty, the method returns an empty string.

length: The length of the resulting string (default = the length of the input string).

If the specified length is shorter than the right-justified input string, then the returned string is truncated.

padding: The single character to be used as padding (default = the ASCII space " ").

### Példa:

        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

Returns the input string enclosed in single or double quotes. Existing quotes are left unchanged, including leading and/or trailing quotes.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to quote.

quotechar: Either the single (') or double (") quote (default).

### Példa:

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

This method can be useful while preparing a string field to be stored in a csv-like file, which requires that text values be enclosed with single or double quotes.

## ReplaceChar

Replaces all occurrences of the characters specified in the Before parameter by the corresponding characters specified in After.

If the length of Before is greater than the length of After, the residual characters in Before are replaced by the last character in After.

### Szintaxis:

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

### Paraméterek:

inputstr: The input string on which replacements will occur.

before: A string with the characters that will be searched in the input string for replacement.

after: A string with the new characters that will replace those defined in before.

### Példa:

        ' Replaces accented characters
        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"

The SF_String service provides useful public constants for the Latin character sets, as shown in the example below:

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

## ReplaceRegex

Replaces all occurrences of a given regular expression by a new string.

### Szintaxis:

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

### Paraméterek:

inputstr: The input string on which replacements will occur.

regex: The regular expression.

newstr: The replacing string.

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

        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." (each lowercase letter is replaced by "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." (each word is replaced by "x")

## ReplaceStr

Replaces in a string some or all occurrences of an array of strings by an array of new strings.

### Szintaxis:

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

### Paraméterek:

inputstr: The input string on which replacements will occur.

oldstr: A single string or an array of strings. Zero-length strings are ignored.

newstr: The replacing string or the array of replacing strings.

If oldstr is an array, each occurrence of any of the items in oldstr is replaced by newstr.

If oldstr and newstr are arrays, replacements occur one by one up to the UBound(newstr).

If oldstr has more entries than newstr, then the residual elements in oldstr are replaced by the last element in newstr.

occurrences: The maximum number of replacements. The default value is 0, meaning that all occurrences will be replaced.

When oldstr is an array, the occurrence parameter is computed separately for each item in the array.

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

        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

Returns a string with a readable representation of the argument, truncated at a given length. This is useful mainly for debugging or logging purposes.

If the anyvalue parameter is an object, it will be enclosed with square brackets "[" and "]".

In strings, tabs and line breaks are replaced by \t, \n or \r.

Ha a végső hossz meghaladja a maxlength paramétert, a karakterlánc utolsó része helyébe " ... (N)" lép, ahol N az eredeti karakterlánc teljes hossza a csonkítás előtt.

### Szintaxis:

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

### Paraméterek:

anyvalue: The input value to be represented. It can be any value, such as a string, an array, a Basic object, a UNO object, etc.

maxlength: The maximum length of the resulting string. The default value is 0, meaning there is no limit to the length of the resulting representation.

### Példa:

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

Note that the representation of data types such as Arrays and ScriptForge.Dictionary object instances include both the data type and their values:

        ' An example with a Basic built-in Array
        MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
        ' "[ARRAY] (0:2) (1, 2, Text\there)"
        ' An example with a ScriptForge Array
        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)"
        ' An example with a ScriptForge Dictionary
        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

Returns the input string in reversed order.

This method is equivalent to the built-in StrReverse Basic function.

To use the StrReverse function, the statement Option VBASupport 1 must be present in the module.

### Szintaxis:

svc.Reverse(inputstr: str): str

### Paraméterek:

inputstr: The string to be reversed.

### Példa:

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

## SplitLines

Returns a zero-based array of strings with the lines in the input string. Each item in the array is obtained by splitting the input string at newline characters.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be split.

keepbreaks: When True, line breaks are preserved in the output array (default = False).

### Példa:

        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

Splits a string into an array of elements using a specified delimiter.

If a quoted substring contains a delimiter, it is ignored. This is useful when parsing CSV-like records that contain quoted strings.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be split.

delimiter: A string of one or more characters that will be used as delimiter. The default delimiter is the ASCII space " " character.

occurrences: The maximum number of substrings to return. The default value is 0, meaning that there is no limit to the number of returned strings.

quotechar: Either the single (') or double (") quote.

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

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

Figyeljünk a Basic és a Python közötti különbségekre a karakterláncok ábrázolásánál. Például a Basicben két "" karaktert egy karakterláncban egyetlen " karakterként értelmezünk. A Pythonban az egyszerű idézőjelekkel körülvett karakterláncok tartalmazhatnak " karaktereket anélkül, hogy azokat meg kellene duplázni.

## StartsWith

Returns True if the first characters of a string are identical to a given substring.

This method returns False if either the input string or the substring have a length = 0 or when the substring is longer than the input string.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to be tested.

substring: The substring to be searched at the start of inputstr.

casesensitive: The search can be case sensitive or not (Default = False).

### Példa:

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

## TrimExt

Returns the input string without its leading and trailing whitespaces.

### Szintaxis:

svc.TrimExt(inputstr: str): str

### Paraméterek:

inputstr: The string to trim.

### Példa:

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

## Unescape

Converts any escaped sequence (\\, \n, \r, \t) in the input string to their corresponding ASCII character.

### Szintaxis:

svc.Unescape(inputstr: str): str

### Paraméterek:

inputstr: The string to be converted.

### Példa:

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

## Unquote

Removes the single or double quotes enclosing the input string.

This is useful when parsing CSV-like records that contain quoted strings.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to unquote.

quotechar: Either the single (') or double (") quote (default).

### Példa:

        Dim s as String
        ' s = "Some text" (without enclosing quotes)
        s = SF_String.Unquote("""Some text""")
        ' The string below does not have enclosing quotes, so it remains unchanged
        ' s = "Some text" (unchanged)
        s = SF_String.Unquote("Some text")
        ' Quotes inside the string are not removed
        ' s = "The ""true"" meaning" (unchanged)
        s = SF_String.Unquote("The ""true"" meaning")

## Wrap

Converts the input string into an array of substrings so that each item in the array has at most a given number of characters.

In practice, this method returns a zero-based array of output lines, without newlines at the end, except for the pre-existing line-breaks.

Tabs are expanded using the same procedure performed by the ExpandTabs method.

Symbolic line breaks are replaced by their equivalent ASCII characters.

If the wrapped output has no content, the returned array is empty.

### Szintaxis:

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

### Paraméterek:

inputstr: The string to wrap.

width: The maximum number of characters in each line (Default = 70).

tabsize: A szöveg körbefuttatása előtt a meglévő TAB Chr(9) karakterek szóközökre cserélődnek. A tabsize argumentum meghatározza a TAB-megállókat: TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (alapértelmezett = 8).

### Példa:

##### A Basic nyelvben

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

##### A Python nyelvben

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.

Kapcsolódó témakörök

ScriptForge.Array service

String Function