Serviço ScriptForge.String (SF_String)

Sumário

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

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 13 + 10 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

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:

##### Em Basic

          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

##### Em Python

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:

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)

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.

Lista de Métodos no Serviço String
Capitalize Count EndsWith Escape ExpandTabs FilterNotPrintable FindRegex HashStr HtmlEncode IsADate IsAlpha IsAlphaNum IsAscii IsDigit IsEmail | IsFileName IsHexDigit IsIBAN IsIPv4 IsLike IsLower IsPrintable IsRegex IsSheetName IsTitle IsUpper IsUrl IsWhitespace JustifyCenter JustifyLeft | JustifyRight Quote ReplaceChar ReplaceRegex ReplaceStr Represent Reverse SplitLines SplitNotQuoted StartsWith TrimExt Unescape Unquote Wrap

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.

### Sintaxe:

svc.Capitalize(inputstr: str): str

### Parâmetros:

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

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

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

### Parâmetros:

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

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

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:

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

### Parâmetros:

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

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

svc.Escape(inputstr: str): str

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

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

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

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

### Parâmetros:

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

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

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

### Parâmetros:

inputstr: String a ser pesquisada

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

### 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

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:

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

### 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 suportados e listados acima, passado como uma string.

### Exemplo:

##### Em Basic

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

##### Em Python

        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.

### Sintaxe:

svc.HtmlEncode(inputstr: str): str

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

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

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

##### Em Basic

        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

##### Em Python

        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.

### Sintaxe:

svc.IsAlpha(inputstr: str): bool

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

svc.IsAlphaNum(inputstr: str): bool

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

svc.IsAscii(inputstr: str): bool

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

svc.IsDigit(inputstr: str): bool

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

svc.IsEmail(inputstr: str): bool

### Parâmetros:

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

### Exemplo:

##### Em Basic

        MsgBox SF_String.IsEmail("first.last@something.org") ' True
        MsgBox SF_String.IsEmail("first.last@something.com.br") ' True
        MsgBox SF_String.IsEmail("first.last@something.123") ' False

##### Em Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsEmail("first.last@something.org")) # True
        bas.MsgBox(svc.IsEmail("first.last@something.com.br")) # True
        bas.MsgBox(svc.IsEmail("first.last@something.123")) # False

## IsFileName

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

### Sintaxe:

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

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

##### Em Basic

        MsgBox SF_String.IsFileName("/home/user/Documents/a file name.odt", "LINUX") ' True
        MsgBox SF_String.IsFileName("C:\home\a file name.odt", "LINUX") ' False
        MsgBox SF_String.IsFileName("C:\home\a file name.odt", "WINDOWS") ' True

##### Em Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsFileName("/home/user/Documents/a file name.odt", "LINUX")) # True
        bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "LINUX")) # False
        bas.MsgBox(svc.IsFileName(r"C:\home\a file name.odt", "WINDOWS")) # True

## IsHexDigit

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

### Sintaxe:

svc.IsHexDigit(inputstr: str): bool

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

### Sintaxe:

svc.IsIBAN(inputstr: str): bool

### Parâmetros:

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

### Tipo de retorno:

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

### Exemplo:

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

### Sintaxe:

svc.IsIPv4(inputstr: str): bool

### Parâmetros:

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

### Exemplo:

##### Em Basic

        MsgBox SF_String.IsIPv4("192.168.1.50") ' True
        MsgBox SF_String.IsIPv4("192.168.50") ' False
        MsgBox SF_String.IsIPv4("255.255.255.256") ' False

##### Em Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsIPv4("192.168.1.50")) # True
        bas.MsgBox(svc.IsIPv4("192.168.50")) # False
        bas.MsgBox(svc.IsIPv4("255.255.255.256")) # False

## IsLike

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

### Sintaxe:

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

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

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

### Exemplo:

##### Em Basic

        MsgBox SF_String.IsLike("aAbB", "?A*") ' True
        MsgBox SF_String.IsLike("C:\a\b\c\f.odb", "?:*.*") ' True
        MsgBox SF_String.IsLike("name:host", "?*@?*") ' False
        MsgBox SF_String.IsLike("@host", "?*@?*") ' False

##### Em Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsLike("aAbB", "?A*")) # True
        bas.MsgBox(svc.IsLike(r"C:\a\b\c\f.odb", "?:*.*")) # True
        bas.MsgBox(svc.IsLike("name:host", "?*@?*")) # False
        bas.MsgBox(svc.IsLike("@host", "?*@?*")) # False

## IsLower

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

### Sintaxe:

svc.IsLower(inputstr: str): bool

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

svc.IsPrintable(inputstr: str): bool

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

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

### 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: A busca pode ser sensível à caixa ou não (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:

svc.IsSheetName(inputstr: str): bool

### Parâmetros:

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

### Exemplo:

##### Em Basic

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

##### Em Python

        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.

### Sintaxe:

svc.IsTitle(inputstr: str): bool

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

svc.IsUpper(inputstr: str): bool

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

svc.IsUrl(inputstr: str): bool

### Parâmetros:

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

### Exemplo:

##### Em Basic

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

##### Em Python

        svc = CreateScriptService("String")
        bas = CreateScriptService("Basic")
        bas.MsgBox(svc.IsUrl("http://foo.bar/?q=Test%20URL-encoded%20stuff")) # True
        bas.MsgBox(svc.IsUrl("www.somesite.org")) # False

## IsWhitespace

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

### Sintaxe:

svc.IsWhitespace(inputstr: str): bool

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

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

### 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("    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.

### Sintaxe:

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

### 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("    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.

### Sintaxe:

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

### 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("  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.

### Sintaxe:

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

### 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"'

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:

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

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

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

### Parâmetros:

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

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

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

### 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: A busca pode ser sensível à caixa ou não (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:

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

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

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

### Sintaxe:

svc.Reverse(inputstr: str): str

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

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

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

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

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

### Exemplo:

##### Em Basic

        arr1 = SF_String.SplitNotQuoted("abc def ghi")
        ' arr1 = Array("abc", "def", "ghi")
        arr2 = SF_String.SplitNotQuoted("abc,""def,ghi""", ",")
        ' arr2 = Array("abc", """def,ghi""")
        arr3 = SF_String.SplitNotQuoted("abc,""def\"",ghi""", ",")
         ' arr3 = Array("abc", """def\"",ghi""")
        arr4 = SF_String.SplitNotQuoted("abc,""def\"",ghi"""",", ",")
        ' arr4 = Array("abc", """def\"",ghi""", "")

##### Em Python

        svc = CreateScriptService("String")
        arr1 = svc.SplitNotQuoted('abc def ghi')
        # arr1 = ('abc', 'def', 'ghi')
        arr2 = svc.SplitNotQuoted('abc,"def,ghi"', ",")
        # arr2 = ('abc', '"def,ghi"')
        arr3 = svc.SplitNotQuoted(r'abc,"def\",ghi"', ",")
        # arr3 = ('abc', '"def\\",ghi"')
        arr4 = svc.SplitNotQuoted(r'abc,"def\",ghi"",', ",")
        # arr4 = ('abc', '"def\\",ghi""', '')

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.

### Sintaxe:

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

### Parâmetros:

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

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

svc.TrimExt(inputstr: str): str

### Parâmetros:

inputstr: String a ser aparada.

### Exemplo:

        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.

### Sintaxe:

svc.Unescape(inputstr: str): str

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

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

### 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 = "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.

### Sintaxe:

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

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

### Exemplo:

##### Em Basic

        a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."
        b = SF_String.Wrap(a, 20)
        ' Array("Neque porro ", "quisquam est qui ", "dolorem ipsum quia ", "dolor sit amet, ", "consectetur, ", "adipisci velit...")

##### Em Python

        a = "Neque porro quisquam est qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit..."
        b = svc.Wrap(a, 20)
        # ('Neque porro ', 'quisquam est qui ', 'dolorem ipsum quia ', 'dolor sit amet, ', 'consectetur, ', 'adipisci velit...')

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.

Tópicos relacionados

Serviço ScriptForge.Array

Função String

♥ Doe para nosso projeto! ♥