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:

Definições

Quebras de linha

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

Nome simbólico

Número ASCII

Avanço de linha
Tabulação vertical
Retorno de carro
Avanço de linha + Retorno de carro
Separador de arquivo
Separador de grupo
Separador de registro
Próxima linha
Separador de linha
Separador de parágrafo

10
12
13
10 + 13
28
29
30
133
8232
8233


Espaços em branco

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

Nome simbólico

Número ASCII

Espaço
Tabulação horizontal
Avanço de linha
Tabulação vertical
Avanço de formulário
Retorno de carro
Próxima linha
Espaço sem quebra
Separador de linha
Separador de parágrafo

32
9
10
11
12
13
133
160
8232
8233


Sequências de escape

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

Sequência de Escape

Nome simbólico

Número ASCII

\n
\r
\t

Avanço de linha
Retorno de carro
Tabulação horizontal

10
13
9


tip

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 (código ASCII <= 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:

Invocação do serviço

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


      GlobalScope.BasicLibraries.LoadLibrary("ScriptForge")
  

O trecho de código a seguir mostra três maneiras de chamar métodos no serviço String (o método ExpandTabs é usado como um exemplo):


        SF_String.ExpandTabs(...)
    

        Dim s : s = SF_String
        s.ExpandTabs(...)
    

        Dim s : s = CreateScriptService("String")
        s.ExpandTabs(...)
    

Propriedades

O objeto SF_String fornece as seguintes propriedades:

Nome

Somente leitura

Descrição

sfCR

Sim

Retorno de carro: Chr(13)

sfCRLF

Sim

Retorno de carro + Avanço de linha: Chr(13) & Chr(10)

sfLF

Sim

Avanço de linha: Chr(10)

sfNEWLINE

Sim

Retorno de carro + Avanço de linha, que pode ser
1) Chr(13) & Chr(10) ou
2) Linefeed: Chr(10)
dependendo do sistema operacional.

sfTAB

Sim

Tabulação horizontal: Chr(9)


tip

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.


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


note

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.


Capitalize

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

Sintaxe:


       SF_String.Capitalize(InputStr As String) As String
     

Parâmetros:

InputStr: A String a ser capitalizada.

Exemplo:


       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.

Sintaxe:


        SF_String.Count(InputStr As String, Substring As String[, IsRegex As Boolean][, CaseSensitive As Boolean]) As Long
      

Parâmetros:

InputStr: String de entrada a ser examinada

Substring: Sub-string ou expressão regular a ser usada na busca

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

CaseSensitive: Padrão = False

Exemplo:


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

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.

Sintaxe:


       SF_String.EndsWith(InputStr As String, Substring As String[, CaseSensitive As Boolean]) As Boolean
     

Parâmetros:

InputStr: String a ser testada.

Substring: A sub-string a ser buscada no final de InputStr.

CaseSensitive: A comparação pode ser sensível à caixa ou não (Padrão = False).

Exemplo:


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

Sintaxe:


          SF_String.Escape(InputStr As String) As String
      

Parâmetros:

InputStr: String a ser convertida.

Exemplo:


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

Sintaxe:


        SF_String.ExpandTabs(InputStr As String[, TabSize As Integer]) As String
      

Parâmetros:

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)

Exemplo:


        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.

Sintaxe:


        SF_String.FilterNotPrintable(InputStr As String[, ReplacedBy As String]) As String
      

Parâmetros:

InputStr: String a ser considerada.

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

Exemplo:


        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.

Sintaxe:


        SF_String.FindRegex(InputStr As String, Regex As String[, Start As Long[, CaseSensitive As Boolean[, Forward As Boolean]]]) As String
      

Parâmetros:

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: 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)

Exemplo:


        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
      
tip

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.

Sintaxe:


          SF_String.HashStr(InputStr As String, Algorithm As String) As String
      

Parâmetros:

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 hash suportados e listados acima, passados como uma String.

Exemplo:


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

Sintaxe:


        SF_String.HtmlEncode(InputStr) As String
      

Parâmetros:

InputStr: String a ser codificada.

Exemplo:


        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.

Sintaxe:


        SF_String.IsADate(InputStr As String[, DateFormat As String]) As Boolean
      

Parâmetros:

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.

Exemplo:


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

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
  

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.

Sintaxe:


        SF_String.IsAlpha(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsAlphaNum(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsAscii(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsDigit(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsEmail(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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
      

IsFileName

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

Sintaxe:


        SF_String.IsFileName(InputStr As String[, OSName As String]) As Boolean
      

Parâmetros:

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.

Exemplo:


        MsgBox SF_String.IsFileName("~/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
      

IsHexDigit

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

Sintaxe:


        SF_String.IsHexDigit(InputStr As String) As Boolean
      

Parâmetros:

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

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

Exemplo:


        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.

note

Este método está disponível a partir do LibreOffice 7.2 em diante.


Sintaxe:


        SF_String.IsIBAN(InputStr As String) As Boolean
      

Parâmetros:

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

Valor de retorno:

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

Exemplo:


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

IsIPv4

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

Sintaxe:


        SF_String.IsIPv4(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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
      

IsLike

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

Sintaxe:


        SF_String.IsLike(InputStr As String, Pattern As String[, CaseSensitive As Boolean) As Boolean
      

Parâmetros:

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

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

CaseSensitive: Padrão = False.

Exemplo:


        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
      

IsLower

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

Sintaxe:


        SF_String.IsLower(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsPrintable(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsRegex(InputStr As String, Regex As String[, CaseSensitive As Boolean) As Boolean
      

Parâmetros:

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: Padrão = False.

Exemplo:


        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.

Sintaxe:


          SF_String.IsSheetName(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


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

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.

Sintaxe:


        SF_String.IsTitle(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsUpper(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.IsUrl(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


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

IsWhitespace

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

Sintaxe:


        SF_String.IsWhitespace(InputStr As String) As Boolean
      

Parâmetros:

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

Exemplo:


        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.

Sintaxe:


        SF_String.JustifyCenter(InputStr As String[, Length As Long[, Padding As String]]) As String
      

Parâmetros:

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

Exemplo:


        MsgBox SF_String.JustifyCenter("Title", Length := 11) ' "   Title   "
        MsgBox SF_String.JustifyCenter("    ABCDE", 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.

Sintaxe:


        SF_String.JustifyLeft(InputStr As String[, Length As Long[, Padding As String]]) As String
      

Parâmetros:

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

Exemplo:


        MsgBox SF_String.JustifyLeft("Title", Length := 10) ' "Title     "
        MsgBox SF_String.JustifyLeft("    ABCDE", 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.

Sintaxe:


        SF_String.JustifyRight(InputStr As String[, Length As Long[, Padding As String]]) As String
      

Parâmetros:

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

Exemplo:


        MsgBox SF_String.JustifyRight("Title", Length := 10) ' "     Title"
        MsgBox SF_String.JustifyRight("  ABCDE  ", 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.

Sintaxe:


        SF_String.Quote(InputStr As String, [QuoteChar As String]) As String
      

Parâmetros:

InputStr: String a ser envolta em aspas.

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

Exemplo:


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

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.

Sintaxe:


        SF_String.ReplaceChar(InputStr As String, Before As String, After As String) As String
      

Parâmetros:

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.

Exemplo:


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

Sintaxe:


        SF_String.ReplaceRegex(InputStr As String, Regex As String, NewStr As String[, CaseSensitive As Boolean]) As String
      

Parâmetros:

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

Regex: Expressão regular.

NewStr: String que substituirá as correspondências.

CaseSensitive: Padrão = False.

Exemplo:


          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.

Sintaxe:


        SF_String.ReplaceStr(InputStr As String, OldStr As Variant, NewStr As Variant[, Occurrences As Long[, CaseSensitive As Boolean]]) As String
      

Parâmetros:

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: Padrão = False.

Exemplo:


        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.

Sintaxe:


        SF_String.Represent(AnyValue As Variant[, MaxLength As Long]) As String
      

Parâmetros:

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.

Exemplo:


        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, porém com desempenho melhor.

note

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


Sintaxe:


        SF_String.Reverse(InputStr As String) As String
      

Parâmetros:

InputStr: A String a ser invertida.

Exemplo:


        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.

Sintaxe:


        SF_String.SplitLines(InputStr As String[, KeepBreaks As Long]) As Variant
      

Parâmetros:

InputStr: A String a ser dividida.

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

Exemplo:


        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.

Sintaxe:


        SF_String.SplitNotQuoted(InputStr As String[, Delimiter As String], [Occurrences As Long], [QuoteChar As String]) As Variant
      

Parâmetros:

InputStr: A String a ser dividida.

Delimiter: String com um ou mais caracteres que serão usados como delimitador. O delimitador padrão é o 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 (").

Exemplo:


        a = SF_String.SplitNotQuoted("abc def ghi")
        ' a = Array("abc", "def", "ghi")
        a = SF_String.SplitNotQuoted("abc,""def,ghi""", ",")
        ' a = Array("abc", """def,ghi""")
        a = SF_String.SplitNotQuoted("abc,""def\"",ghi""", ",")
         ' a = Array("abc", """def\"",ghi""")
        a = SF_String.SplitNotQuoted("abc,""def\"",ghi"""",", ",")
        ' a = Array("abc", """def\"",ghi""", "")
      

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.

Sintaxe:


        SF_String.StartsWith(InputStr As String, Substring As String[, CaseSensitive As Boolean]) As Boolean
      

Parâmetros:

InputStr: String a ser testada.

Substring: A sub-string a ser buscada no começo de InputStr.

CaseSensitive: Padrão = False.

Exemplo:


        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.

Sintaxe:


        SF_String.TrimExt(InputStr As String) As String
      

Parâmetros:

InputStr : String a ser aparada.

Exemplo:


        MsgBox SF_String.TrimExt(" Some text.  ") ' "Some text."
        MsgBox SF_String.TrimExt("   ABCDE" & 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.

Sintaxe:


        SF_String.Unescape(InputStr As String) As String
      

Parâmetros:

InputStr: String a ser convertida.

Exemplo:


        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.

Sintaxe:


        SF_String.Unquote(InputStr As String, [QuoteChar As String]) As String
      

Parâmetros:

InputStr : String que terá as aspas removidas.

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

Exemplo:


        Dim s as String
        s = SF_String.Unquote("""Some text""") ' s = "Some text" (Sem as aspas no início e fim)
        ' The string below does not have enclosing quotes, so it remains unchanged
        s = SF_String.Unquote("Some text") ' s = "Some text" (sem modificação)
        ' Aspas dentro da String não são removidas
        s = SF_String.Unquote("The ""true"" meaning") ' s = "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.

Sintaxe:


          SF_String.Wrap(InputStr As String, [Width As Long], [TabSize As Integer]) As String
      

Parâmetros:

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. TabSize define as paradas de tabulação nas posições TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Padrão = 8).

Exemplo:


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

Todas as rotinas básicas ou identificadores do ScriptForge que possuem o caractere "_" como prefixo são reservados apenas para uso interno. Elas não devem ser usadas em macros Basic.


♥ Doe para nosso projeto! ♥