Serviço ScriptForge.String

O serviço String fornece um conjunto de métodos para processamento de Strings. Tais métodos podem ser usados para:

• Validar os conteúdos das Strings.

• Formatar, aparar, justificar e inserir quebras automáticas em Strings

• Usar expressões regulares para buscar e substituir sub-strings.

• Aplicar algoritmos de hash em strings, etc.

Definições

Quebras de linha

O serviço String reconhece as quebras de linha a seguir:

Espaços em branco

O serviço String reconhece os seguintes espaços em branco:

Sequências de escape

Abaixo está uma lista de sequências de escape que podem ser usadas em Strings.

Para que a sequência "\n" seja interpretada como uma String, use "\\n" em vez de "\" & Chr(10).

Caracteres não imprimíveis

Caracteres definidos na Base de Dados de Caracteres Unicode como "Outros" ou "Separadores" são considerados caracteres não imprimíveis.

Caracteres de controle (ASCII code <= 0x1F) também são considerados como não imprimíveis.

Aspas dentro de Strings:

Para adicionar aspas em Strings use \' (aspas simples) ou \" (aspas duplas). Por exemplo:

• A String [str\'i\'ng] é interpretada como [str'i'ng]

• A String [str\"i\"ng] é interpretada como [str"i"ng]

Invocação do serviço

Antes de usar o serviço String a biblioteca ScriptForge precisa ser carregada usando:

      GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
  

Carregar a biblioteca criará o objeto SF_String que pode ser usado para chamar os métodos do serviço String.

Os trechos de código a seguir mostram três maneiras de chamar métodos do serviço String (o método Capitalize é usado como um exemplo):

    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
  

O exemplo abaixo ilustra como invocar métodos do serviço String em scripts Python. O método IsIPv4 é usado como exemplo.

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

Propriedades

O objeto SF_String fornece as seguintes propriedades para scripts Basic:

Você pode usar as propriedades acima para identificar ou inserir os caracteres correspondentes em Strings. Por exemplo, o Avanço de Linha pode ser substituído por SF_String.sfLF.

O primeiro argumento da maioria dos métodos é a String a ser considerada. Ela é sempre passada por referência e não é modificada. Métodos como Capitalize, Escape, etc retornam uma nova String após sua execução.

Como a linguagem Python possui amplo suporte a strings, a maioria dos métodos do serviço String estão disponíveis apenas para scripts escritos em Basic. Os métodos disponíveis para Basic e Python são: HashStr, IsADate, IsEmail, IsFileName, IsIBAN, IsIPv4, IsLike, IsSheetName, IsUrl, SplitNotQuoted e Wrap.

Capitalize

Converte para Maiúsculo o primeiro caractere de cada palavra na String de entrada.

svc.Capitalize(inputstr: str): str

inputstr: String a ser convertida para letras maiúsculas.

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

Count

Conta o número de ocorrências de uma sub-string or de uma expressão regular dentro de uma String.

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

inputstr: String de entrada a ser examinada

substring: Sub-string ou expressão regular a ser usada durante a busca

isregex: Use True se a sub-string é uma expressão regular (Padrão = False)

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

    'Conta as ocorrências da sub-string "or" dentro da String de entrada (retorna 2)
    MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "or", CaseSensitive := False)
    'Conta o número de palavras com apenas caracteres em caixa baixa (retorna 7)
    MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)
  

Para aprender mais sobre expressões regulares, consulte a documentação da linguagem Python na página Regular Expression Operations.

EndsWith

Retorna True se uma String termina com uma sub-string especificada.

A função retorna False quando a String ou a sub-string tiverem comprimento zero ou quando a sub-string for maior que a String de entrada.

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

inputstr: String a ser testada.

substring: A sub-string a ser buscada no final de inputstr.

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

    'Retorna True porque o método foi chamado com o valor padrão CaseSensitive = False
    MsgBox SF_String.EndsWith("abcdefg", "EFG")
    'Retorna False devido ao parâmetro CaseSensitive
    MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)
  

Escape

Converte quebras de linhas e tabulações contidas na String de entrada para seus correspondentes caracteres de escape (\\, \n, \r, \t).

svc.Escape(inputstr: str): str

inputstr: String a ser convertida.

    'Retorna a String "abc\n\tdef\\n"
    MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")
  

ExpandTabs

Substitui os caracteres Tab Chr(9) por caracteres de espaço para replicar o comportamento de paradas de tabulação.

Se uma quebra de linha é encontrada, uma nova linha é iniciada e o contador de caracteres é resetado.

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

inputstr: String a ser expandida.

tabsize: Este parâmetro é usado para determinar as paradas de tabulação usando a fórmula: TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Padrão = 8)

    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

Substitui todos os caracteres não imprimíveis na String de entrada por um dado caractere.

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

inputstr: String a ser pesquisada.

replacedby: Zero, um ou mais caracteres que substituirão todos os caracteres não imprimíveis em inputstr (Padrão = "")

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

FindRegex

Encontra em uma String uma sub-string que corresponde e uma dada expressão regular.

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

inputstr: String a ser pesquisada.

regex: Expressão regular.

start: Posição na string onde a busca será iniciada. Este parâmetro é passado por referência, logo, após a execução do método o valor de start apontará para o primeiro caractere da sub-string encontrada. Se nenhuma sub-string correspondente for encontrada, start terá o valor 0.

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

forward: Determina a direção da busca. Se True, a busca moverá para frente. Se False a busca ocorrerá para trás (Padrão = True)

Na primeira iteração, se forward = True, então start deveria ser igual a 1, ao passo que, se forward = False então start deveria ser igual a Len(inputstr)

    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
  

No exemplo acima, o novo valor de lStart pode ser usado para continuar a busca na mesma String de entrada ao definir o parâmetro Start para lStart + Len(result) na próxima iteração.

HashStr

Funções hash são usadas por alguns algoritmos criptográficos, em assinaturas digitais, códigos de autenticação de mensagens, detecção de fraudes, impressões digitais, verificação de integridade de mensagens, tabelas hash, armazenamento de senhas e muito mais.

O método HashStr retorna o resultado da função hash aplicada em uma dada String usando o algoritmo escolhido. O valor retornado é uma String com caracteres hexadecimais minúsculos.

Os algoritmos hash suportados são: MD5, SHA1, SHA224, SHA256, SHA384 e SHA512.

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

inputstr: String à qual a função hash será aplicada. Assume-se que a string usa a codificação UTF-8. O algoritmo hash considerará a string como um fluxo de bytes.

algorithm: Um dos algoritmos suportados e listados acima, passado como uma string.

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

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

HtmlEncode

Codifica a String de entrada em caracteres HTML, substituindo caracteres especiais pelos símbolos & correspondentes.

Por exemplo, o caractere é seria substituído por &eacute; ou um código numérico HTML equivalente.

svc.HtmlEncode(inputstr: str): str

inputstr: String a ser codificada.

    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

Retorna True se a String de entrada é uma data válida de acordo com o formato de dada especificado.

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

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

dateformat: Formato da data, como uma string. Pode ser um dos valores a seguir: "YYYY-MM-DD" (padrão), "DD-MM-YYYY" ou "MM-DD-YYYY"

O traço (-) pode ser substituído por um ponto (.), uma barra (/) ou um espaço em branco.

Se o formato for inválido, o método retorna False.

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

Este método verifica o formato da String de entrada sem fazer verificações específicas de calendário. Assim, o método não testa se a String de entrada é um ano bissexto ou se um determinado mês tem 30 ou 31 dias. Para isso, consulte a função interna Basic IsDate.

O exemplo abaixo mostra a diferença entre os métodos IsADate (ScriptForge) e o método interno IsDate.

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

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

IsAlpha

Retorna True se todos os caracteres em uma String são alfabéticos.

Caracteres alfabéticos são aqueles definidos na base Unicode Character Database como pertencentes ao grupo Letter.

svc.IsAlpha(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

IsAlphaNum

Retorna True se todos os caracteres na String são alfabéticos, dígitos ou "_" (underscore). O primeiro caractere não pode ser um dígito.

svc.IsAlphaNum(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

IsAscii

Retorna True se todos os caracteres na String são caracteres ASCII.

svc.IsAscii(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

IsDigit

Retorna True se todos os caracteres na String de entrada são dígitos.

svc.IsDigit(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

IsEmail

Retorna True se a String é um endereço de e-mail válido.

svc.IsEmail(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

    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
  

    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

Retorna True se a String é um nome válido de arquivo em um dado sistema operacional.

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

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

osname: Nome do sistema operacional, como uma String. Pode ser "WINDOWS", "LINUX", "MACOSX" ou "SOLARIS".

O valor padrão é o sistema operacional onde o script está sendo executado.

    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
  

    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

Retorna True se todos os caracteres na String são dígitos hexadecimais.

svc.IsHexDigit(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

Os dígitos hexadecimais podem ter os prefixos "0x" ou "&H".

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

IsIBAN

Retorna True se a string é um código IBAN (International Bank Account Number) válido (IBAN). A comparação não é sensível à caixa.

svc.IsIBAN(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

True se a string contém um número IBAN válido.

    ' 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

Retorna True se a String é um endereço IP(v4) válido.

svc.IsIPv4(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

    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
  

    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

Retorna True se a String de entrada inteira corresponde a um dado padrão contendo caracteres curinga.

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

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

pattern: String contendo o padrão. Os caracteres curinga podem ser:

• "?" representa qualquer caractere único

• "*" representa zero, um ou múltiplos caracteres

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

    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
  

    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

Retorna True se todos os caracteres na String estão em caixa baixa. Caracteres não alfabéticos são ignorados.

svc.IsLower(inputstr: str): bool

InputStr: String a ser verificada. Se estiver vazia o método retorna False

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

IsPrintable

Retorna True se todos os caracteres na String são imprimíveis.

svc.IsPrintable(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

IsRegex

Retorna True se a String de entrada inteira corresponde a uma dada expressão regular.

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

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

regex: Expressão regular a ser usada. Se for vazia, o método retorna False.

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

        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

Retorna True se a String de entrada é um nome válido para uma planilha Calc.

svc.IsSheetName(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

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

Nomes de planilhas Calc não podem conter os caracteres [ ] * ? : / \ ou o caractere ' (apóstrofe) na primeira ou última posição.

IsTitle

Retorna True se o primeiro caractere de todas as palavras estão em letras maiúsculas e todos os outros caracteres são minúsculos.

svc.IsTitle(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

    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

Retorna True se todos os caracteres na String estão em caixa alta. Caracteres não alfabéticos são ignorados.

svc.IsUpper(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

IsUrl

Retorna True se a String é um endereço URL (Uniform Resource Locator) válido. Apenas os protocolos http, https e ftp são suportados.

svc.IsUrl(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

    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

Retorna True se todos os caracteres na String são espaços em branco.

svc.IsWhitespace(inputstr: str): bool

inputstr: String a ser verificada. Se estiver vazia o método retorna False.

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

JustifyCenter

Retorna a String de entrada centralizada.

Os espaços em branco iniciais e finais são removidos e os caracteres restantes são completados à direta e à esquerda até uma quantidade total especificada no parâmetro length com o caractere padding.

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

inputstr: String a ser centralizada. Se estiver vazia o método retorna uma string vazia.

length: Comprimento da string resultante (Padrão = comprimento da string de entrada).

Se o comprimento especificado for menor que a String a ser centralizada, então a String resultante é truncada.

padding: Caractere único a ser usado como preenchimento (Padrão = espaço em branco ASCII " ").

    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

Retorna a String de entrada justificada à esquerda.

Os espaços em branco iniciais e finais são removidos e os caracteres restantes são completados à direta até uma quantidade total especificada no parâmetro length com o caractere padding.

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

inputstr: String a ser justificada à esquerda. Se estiver vazia o método retorna uma string vazia.

length: Comprimento da string resultante (Padrão = comprimento da string de entrada).

Se o comprimento especificado for menor que a String a ser justificada à esquerda, então a String resultante é truncada.

padding: Caractere único a ser usado como preenchimento (Padrão = espaço em branco ASCII " ").

    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

Retorna a String de entrada justificada à direita.

Os espaços em branco iniciais e finais são removidos e os caracteres restantes são completados à esquerda até uma quantidade total especificada no parâmetro length com o caractere padding.

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

inputstr: String a ser justificada à direita. Se estiver vazia o método retorna uma string vazia.

length: Comprimento da string resultante (Padrão = comprimento da string de entrada).

Se o comprimento especificado for menor que a String a ser justificada à direita, então a String resultante é truncada.

padding: Caractere único a ser usado como preenchimento (Padrão = espaço em branco ASCII " ").

    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

Retorna a String de entrada envolta em aspas duplas. Aspas existentes são deixadas como estão, incluindo aspas no início e fim da String.

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

inputstr: String a ser envolta em aspas.

quotechar: Pode ser tanto aspas simples (') como aspas duplas ("), que é o valor padrão.

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

Este método pode ser útil ao preparar um campo String para ser armazenado em arquivos CSV, os quais requerem que valores textuais sejam envoltos em aspas simples ou duplas.

ReplaceChar

Substitui todas as ocorrências dos caracteres especificados no parâmetro Before pelos caracteres correspondentes especificados no parâmetro After.

Se o comprimento de Before for maior que o comprimento de After, os caracteres residuais em Before serão substituídos pelo último caractere em After.

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

inputstr: String na qual as substituições ocorrerão.

before: String contendo os caracteres que serão buscados na string de entrada para serem substituídos.

after: String contendo os novos caracteres que substituirão aqueles definidos em before.

    ' Substitui caracteres com acento
    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"
  

O serviço SF_String fornece constantes públicas úteis para o conjunto de caracteres Latino, conforme mostra o exemplo abaixo:

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

ReplaceRegex

Substitui todas as ocorrências de uma dada expressão regular por uma nova String.

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

inputstr: String na qual as substituições ocorrerão.

regex: Expressão regular.

newstr: String que substituirá as correspondências.

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

    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." (cada caractere minúsculo é substituído por "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." (cada palavra é substituída por "x")
  

ReplaceStr

Substitui em uma String algumas ou todas as ocorrências de um Array de Strings for um Array com as novas Strings.

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

inputstr: String na qual as substituições ocorrerão.

oldstr: String única ou um array de strings. Strings de comprimento zero são ignoradas.

newstr: String ou array de strings que substituirão as correspondências.

Se oldstr for um array, então cada ocorrência de qualquer um dos itens em oldstr será substituída por newstr.

Se oldstr e newstr forem arrays, substituições ocorrerão uma a uma até o limite especificado em UBound(newstr).

Se oldstr tiver mais entradas que newstr, então os elementos residuais em oldstr serão substituídos pelo último elemento em newstr.

occurrences: Quantidade máxima de substituições. O valor padrão é 0, o que significa que todas as ocorrências serão substituídas.

Se oldstr for um array, o parâmetro occurrence é computado separadamente para cada item no array.

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

    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

Retorna uma String com uma representação legível do argumento, trucado até um determinado comprimento. Este método é especialmente útil para depuração de código ou para criar registros de log.

Se o parâmetro anyvalue for um objeto, ele será envolto em colchetes "[" e "]".

Em Strings, caracteres de tabulação e espaços são substituídos por \t, \n ou \r.

Se o comprimento final exceder maxlength, a parte final da string será substituída por " ... (N)" onde N é o comprimento total da string original antes de ser truncada.

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

anyvalue: Valor de entrada para o qual a string de representação será criada. Pode ser qualquer tipo de valor, tais como strings, arrays, objetos Basic, objetos UNO, etc.

maxlength: Comprimento máximo da string resultante. O valor padrão é 0, o que significa que não há limite para o comprimento da representação resultante.

    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 que a representação de tipos de dados como Arrays e objetos ScriptForge.Dictionary incluem tanto o tipo de dados como seus valores:

    ' Um exemplo com a função Basic Array
    MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
    ' "[ARRAY] (0:2) (1, 2, Text\there)"
    ' Um exemplo com um Array 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)"
    ' Um exemplo com um Dicionário 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

Retorna a String de entrada em ordem reversa.

Este método é equivalente à função Basic StrReverse.

Para usar a função StrReverse a instrução Option VBASupport 1 deve estar presente no módulo.

svc.Reverse(inputstr: str): str

inputstr: A String a ser invertida.

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

SplitLines

Retorna um Array de Strings indexado em zero com as linhas na String de entrada. Cada item no Array é obtido separando a String de entrada nos caracteres de quebra de linha.

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

inputstr: A String a ser dividida.

keepbreaks: Se True, quebras de linha são preservadas no array de saída (Padrão = False).

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

SplitNotQuoted

Divide a String em um Array de elementos usando um delimitador especificado.

Se uma sub-string entre aspas contiver um delimitador, ela será ignorada. Isto é especialmente útil ao processar registros de arquivos CSV contendo valores textuais entre aspas.

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

inputstr: A string a ser dividida.

delimiter: String com um ou mais caracteres que serão usados como delimitador. O delimitador padrão é o caractere ASCII " " correspondente ao espaço em branco.

occurrences: Número máximo de sub-strings a serem retornadas. O valor padrão é zero, indicando que não há limite para o número de strings retornadas.

quotechar: Pode ser tanto aspas simples (') como aspas duplas (").

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

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

Atente-se às diferenças entre as linguagens Basic e Python ao representar strings. Por exemplo, em Basic dois caracteres "" dentro de uma string são interpretados como um único caractere ". Em Python, strings entre aspas simples podem conter caracteres " sem ter que duplicá-los.

StartsWith

Retorna True se os primeiros caracteres de uma String são idênticos à sub-string especificada.

Este método retorna False se a String de entrada ou a sub-string tiverem comprimento zero ou quando a sub-string for maior que a String de entrada.

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

inputstr: String a ser testada.

substring: A sub-string a ser buscada no começo de inputstr.

casesensitive: A busca pode ser sensível à caixa ou não (Padrão = False).

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

TrimExt

Retorna a String de entrada sem os espaços em branco iniciais e finais.

svc.TrimExt(inputstr: str): str

inputstr: String a ser aparada.

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

Unescape

Converte as sequências de escape (\\, \n, \r, \t) na String de entrada em seus caracteres ASCII correspondentes.

svc.Unescape(inputstr: str): str

inputstr: String a ser convertida.

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

Unquote

Remove as aspas simples ou duplas em volta de uma String.

Isto é especialmente útil ao processar registros de arquivos CSV que contém Strings entre aspas.

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

inputstr: String que terá as aspas removidas.

quotechar: Pode ser tanto aspas simples (') como aspas duplas ("), que é o valor padrão.

    Dim s as String
    ' s = "Some text" (sem aspas em volta)
    s = SF_String.Unquote("""Some text""")
    ' A string abaixo não tem aspas em volta, então permanece inalterada
    ' s = "Some text" (sem modificação)
    s = SF_String.Unquote("Some text")
    ' Aspas dentro da String não são removidas
    ' s = "The ""true"" meaning" (sem modificação)
    s = SF_String.Unquote("The ""true"" meaning")
  

Wrap

Converte a String de entrada em um Array de sub-strings de forma que cada item no Array tem no máximo um dado número de caracteres.

Na prática, este método retorna um Array indexado em zero com as linhas de saída, sem caracteres de quebra de linha ao final, exceto quebras de linha preexistentes.

Caracteres de tabulação são expandidas com o mesmo procedimento executado pelo método ExpandTabs.

Quebras de linha simbólicas são substituídas por seus caracteres ASCII correspondentes.

Se a saída não tiver conteúdo, o Array retornado será vazio.

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

inputstr: String na qual serão inseridas quebras automáticas.

width: Número máximo de caracteres em cada linha (Padrão = 70).

tabsize: Antes de inserir as quebras automáticas, os caracteres TAB existentes Chr(9) são substituídos por espaços. O argumento tabsize define as paradas de tabulação nas posições TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Padrão = 8).

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

Todas as rotinas ou identificadores do ScriptForge em Basic que possuem o caractere "_" como prefixo são reservadas para uso interno. Elas não devem ser usadas em macros escritas em Basic ou em Python.