ScriptForge.String serviço

O serviço String disponibiliza um conjunto de métodos para o processamento de cadeias de caracteres. Estes métodos podem ser utilizados para:

• Validar o conteúdo das cadeias de caracteres

• Formatar cadeias de caracteres, recortando, alinhando ou quebrando o texto

• Utilizar expressões regulares para procurar e substituir subcadeias de caracteres

• Aplicar algoritmos de hash a cadeias de caracteres, etc.

Definições

Quebras de linha

O serviço String reconhece as seguintes quebras de linha:

Espaços em branco

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

Sequências de escape

Segue-se uma lista de sequências de escape que podem ser utilizadas em cadeias de caracteres.

Para que a sequência de escape «\n» seja interpretada como uma cadeia de caracteres propriamente dita, basta utilizar «\\n» em vez de "\" & Chr(10).

Caracteres não imprimíveis:

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

Os caracteres de controlo (código ASCII <= 0x1F) também são considerados não imprimíveis.

Aspas dentro de cadeias de caracteres:

Para inserir aspas nas cadeias de caracteres, utilize \' (aspas simples) ou \" (aspas duplas). Por exemplo:

• A cadeia de caracteres [str\'i\'ng] é interpretada como [str'i'ng]

• A cadeia de caracteres [str\"i\"ng] é interpretada como [str"i"ng]

Chamada de serviço

Antes de utilizar o serviço ScriptForge.String, é necessário carregar a biblioteca ScriptForge da seguinte forma:

      GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
  

Ao carregar a biblioteca, será criado o objeto SF_String, que pode ser utilizado para chamar os métodos do serviço String.

Os trechos de código seguintes mostram as três formas de chamar métodos do serviço String (o método Capitalize é utilizado como 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 fragmento de código abaixo ilustra como invocar métodos do serviço String em scripts Python. O método IsIPv4 é utilizado 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 disponibiliza as seguintes propriedades para scripts em Basic:

Pode utilizar as propriedades acima para identificar ou inserir os caracteres correspondentes dentro de cadeias de caracteres. Por exemplo, o avanço de linha pode ser substituído por SF_String.sfLF.

O primeiro argumento da maioria dos métodos é a cadeia de caracteres a ser considerada. É sempre passado por referência e permanece inalterado. Métodos como Capitalize, Escape, etc., devolvem uma nova cadeia de caracteres após a sua execução.

Como o Python dispõe de um suporte abrangente a cadeias de caracteres integrado, a maioria dos métodos do serviço String está disponível apenas para scripts 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

Coloca em maiúscula o primeiro carácter de cada palavra na cadeia de caracteres introduzida.

svc.Capitalize(inputstr: str): str

inputstr: A cadeia de caracteres a que se pretende aplicar 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 subcadeia ou de uma expressão regular numa cadeia de caracteres.

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

inputstr: A cadeia de caracteres de entrada a ser analisada

substring: A substring ou a expressão regular a utilizar durante a pesquisa

isregex: Utilize True se a subcadeia for uma expressão regular (Predefinição = False)

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefinição = False).

    'Conta o número de ocorrências da subcadeia «or» dentro da cadeia de caracteres 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 compostas apenas por letras minúsculas (retorna 7)
    MsgBox SF_String.Count("Lorem ipsum dolor sit amet, consectetur adipiscing elit.", "\b[a-z]+\b", IsRegex := True, CaseSensitive := True)
  

Para saber mais sobre expressões regulares, consulte a documentação do Python em Operações com expressões regulares.

EndsWith

Devolve True se uma cadeia terminar com uma subcadeia especificada.

A função devolve False quando a cadeia de caracteres ou a subcadeia têm um comprimento igual a 0 ou quando a subcadeia é mais longa do que a cadeia de caracteres.

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

inputstr: A cadeia de caracteres a testar.

substring: A substring a procurar no final de inputstr.

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefinição = False).

    «Devolve "True" porque o método foi chamado com o valor predefinido de CaseSensitive = False»
    MsgBox SF_String.EndsWith("abcdefg", "EFG")
    'Devolve «False» devido ao parâmetro «CaseSensitive»
    MsgBox SF_String.EndsWith("abcdefg", "EFG", CaseSensitive := True)
  

Escape

Converte as quebras de linha e as tabulações contidas na cadeia de caracteres de entrada nas respetivas sequências de escape equivalentes (\\, \n, \r, \t).

svc.Escape(inputstr: str): str

inputstr: A cadeia de caracteres a converter.

    'Devolve a cadeia de caracteres "abc\n\tdef\\n"
    MsgBox SF_String.Escape("abc" & Chr(10) & Chr(9) & "def\n")
  

ExpandTabs

Substitui os caracteres de tabulação Chr(9) por espaços, para reproduzir o comportamento dos pontos de tabulação.

Se for detetada uma quebra de linha, inicia-se uma nova linha e o contador de caracteres é reiniciado.

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

inputstr: A cadeia de caracteres a expandir

tabsize: Este parâmetro é utilizado para determinar os pontos de tabulação através da fórmula: TabSize + 1, 2 * TabSize + 1, ... N * TabSize + 1 (Predefiniçã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 cadeia de caracteres de entrada por um determinado caractere.

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

inputstr: A cadeia de caracteres a pesquisar

replacedby: Zero, um ou mais caracteres que substituirão todos os caracteres não imprimíveis em inputstr (Predefiniçã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 numa cadeia de caracteres uma subcadeia que corresponda a uma expressão regular especificada.

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

inputstr: A cadeia de caracteres a pesquisar

regex: A expressão regular

start: A posição na cadeia de caracteres onde a pesquisa terá início. Este parâmetro é passado por referência, pelo que, após a execução, o valor de start apontará para o primeiro carácter da subcadeia encontrada. Se não for encontrada nenhuma subcadeia correspondente, start será definido como 0.

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefinição = False).

para a frente: Determina a direção da pesquisa. Se for True, a pesquisa avança. Se for False, a pesquisa recua (Predefinição = True)

Na primeira iteração, se forward = True, então start deve ser igual a 1; por outro lado, se forward = False, então start deve 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 utilizado para continuar a pesquisar a mesma cadeia de caracteres de entrada, definindo o parâmetro Start como lStart + Len(result) na iteração seguinte.

HashStr

As funções hash são utilizadas em alguns algoritmos criptográficos, em assinaturas digitais, códigos de autenticação de mensagens, deteção de manipulação, impressões digitais, somas de verificação (verificação da integridade das mensagens), tabelas hash, armazenamento de palavras-passe e muito mais.

O método HashStr devolve o resultado da aplicação de uma função hash a uma determinada cadeia de caracteres, utilizando um algoritmo especificado, sob a forma de uma cadeia de caracteres composta por dígitos hexadecimais em minúsculas.

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

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

inputstr: A cadeia de caracteres a ser submetida ao algoritmo de hash. Presume-se que esteja codificada em UTF-8. O algoritmo de hash considerará a cadeia de caracteres como um fluxo de bytes.

algoritmo: Um dos algoritmos suportados acima referidos, passado como uma cadeia de caracteres.

    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 cadeia de caracteres de entrada nos códigos de caracteres HTML, substituindo os caracteres especiais pelas suas equivalências &.

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

svc.HtmlEncode(inputstr: str): str

inputstr: A cadeia de caracteres a codificar.

    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

Devolve True se a cadeia de caracteres introduzida for uma data válida de acordo com um formato de data especificado.

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

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False

dateformat: O formato da data, expresso como uma cadeia de caracteres. Pode ser «AAAA-MM-DD» (padrão), «DD-MM-AAAA» ou «MM-DD-AAAA»

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

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

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

Este método verifica o formato da cadeia de caracteres introduzida sem efetuar quaisquer verificações específicas do calendário. Por conseguinte, não verifica se a cadeia de caracteres introduzida inclui anos bissextos ou meses com 30 ou 31 dias. Para esse efeito, consulte a função incorporada IsDate.

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

    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

Devolve True se todos os caracteres da cadeia forem alfabéticos.

Os caracteres alfabéticos são aqueles definidos na Base de Dados de Caracteres Unicode como Letra.

svc.IsAlpha(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsAlphaNum

Devolve True se todos os caracteres da cadeia forem letras, algarismos ou «_» (traço inferior). O primeiro caractere não pode ser um algarismo.

svc.IsAlphaNum(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsAscii

Devolve True se todos os caracteres da cadeia forem caracteres ASCII.

svc.IsAscii(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsDigit

Devolve True se todos os caracteres da cadeia forem dígitos.

svc.IsDigit(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsEmail

Devolve True se a cadeia de caracteres for um endereço de e-mail válido.

svc.IsEmail(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve 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

Devolve True se a cadeia de caracteres for um nome de ficheiro válido num determinado sistema operativo.

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

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

osname: O nome do sistema operativo, sob a forma de uma cadeia de caracteres. Pode ser «WINDOWS», «LINUX», «MACOSX» ou «SOLARIS».

O valor predefinido é o sistema operativo atual no qual o script está a ser 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

Devolve True se todos os caracteres da cadeia forem dígitos hexadecimais.

svc.IsHexDigit(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

Os dígitos hexadecimais podem ser precedidos por «0x» ou «&H».

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

IsIBAN

Devolve True se a cadeia de caracteres for um Número Internacional de Conta Bancária (IBAN) válido. A comparação não distingue maiúsculas de minúsculas.

svc.IsIBAN(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

True se a cadeia de caracteres contiver 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

Devolve True se a cadeia de caracteres for um endereço IP (v4) válido.

svc.IsIPv4(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve 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

Devolve True se toda a cadeia de caracteres de entrada corresponder a um determinado padrão que contenha caracteres curinga.

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

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

padrão: O padrão na forma de uma cadeia de caracteres. Os caracteres curinga são:

• "?" representa qualquer carácter único;

• "*" representa zero, um ou vários caracteres.

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefiniçã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

Devolve True se todos os caracteres da cadeia de caracteres estiverem em minúsculas. Os caracteres não alfabéticos são ignorados.

svc.IsLower(inputstr: str): bool

InputStr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsPrintable

Devolve True se todos os caracteres da cadeia forem imprimíveis.

svc.IsPrintable(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsRegex

Devolve True se toda a cadeia de caracteres de entrada corresponder a uma determinada expressão regular.

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

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

regex: A expressão regular. Se estiver vazio, o método devolve False.

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefiniçã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

Devolve True se a cadeia de caracteres introduzida for um nome válido de folha do Calc.

svc.IsSheetName(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve 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
  

O nome de uma folha não pode conter os caracteres [ ] * ? : / \ nem o caractere ' (apóstrofo) como primeiro ou último caractere.

IsTitle

Devolve True se o primeiro carácter de cada palavra estiver em maiúscula e os restantes caracteres estiverem em minúscula.

svc.IsTitle(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve 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

Devolve True se todos os caracteres da cadeia de caracteres estiverem em maiúsculas. Os caracteres não alfabéticos são ignorados.

svc.IsUpper(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

IsUrl

Devolve True se a cadeia de caracteres for um endereço URL (Uniform Resource Locator) absoluto válido. Apenas os protocolos http, https e ftp são suportados.

svc.IsUrl(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve 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

Devolve True se todos os caracteres da cadeia forem espaços em branco

svc.IsWhitespace(inputstr: str): bool

inputstr: A cadeia de caracteres a verificar. Se estiver vazia, o método devolve False.

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

JustifyCenter

Devolve a cadeia de caracteres de entrada alinhada ao centro.

Os espaços em branco à esquerda e à direita são removidos e os caracteres restantes são preenchidos à esquerda e à direita até atingirem um comprimento total especificado com o caractere preenchimento.

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

inputstr: A cadeia de caracteres a ser justificada ao centro. Se estiver vazia, o método devolve uma cadeia de caracteres vazia.

comprimento: O comprimento da cadeia de caracteres resultante (por predefinição = o comprimento da cadeia de caracteres de entrada).

Se o comprimento especificado for inferior ao da cadeia de caracteres introduzida, alinhada ao centro, a cadeia de caracteres devolvida é truncada.

preenchimento: O carácter único a utilizar como preenchimento (por predefinição = o espaço 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

Devolve a cadeia de caracteres de entrada alinhada à esquerda.

Os espaços em branco à esquerda são removidos e os caracteres restantes são preenchidos à direita até atingirem um comprimento total especificado, utilizando o caractere preenchimento.

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

inputstr: A cadeia de caracteres a alinhar à esquerda. Se estiver vazia, o método devolve uma cadeia de caracteres vazia.

comprimento: O comprimento da cadeia de caracteres resultante (por predefinição = o comprimento da cadeia de caracteres de entrada).

Se o comprimento especificado for inferior ao da cadeia de caracteres de entrada alinhada à esquerda, a cadeia de caracteres devolvida é truncada.

preenchimento: O carácter único a utilizar como preenchimento (por predefinição = o espaço 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

Devolve a cadeia de caracteres de entrada alinhada à direita.

Os espaços em branco à esquerda são removidos e os caracteres restantes são preenchidos à esquerda até atingirem um comprimento total especificado, utilizando o caractere preenchimento.

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

inputstr: A cadeia de caracteres a alinhar à direita. Se estiver vazia, o método devolve uma cadeia de caracteres vazia.

comprimento: O comprimento da cadeia de caracteres resultante (por predefinição = o comprimento da cadeia de caracteres de entrada).

Se o comprimento especificado for inferior ao da cadeia de caracteres de entrada alinhada à direita, a cadeia de caracteres devolvida é truncada.

preenchimento: O carácter único a utilizar como preenchimento (por predefinição = o espaço 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

Devolve a cadeia de caracteres de entrada entre aspas simples ou duplas. As aspas existentes permanecem inalteradas, incluindo as aspas iniciais e/ou finais.

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

inputstr: A cadeia de caracteres a colocar entre aspas.

quotechar: As aspas simples (') ou duplas (") (por predefiniçã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 de cadeia de caracteres para ser guardado num ficheiro do tipo CSV, o que exige que os valores de texto sejam colocados entre aspas simples ou duplas.

ReplaceChar

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

Se o comprimento de Antes for superior ao comprimento de Depois, os caracteres restantes em Antes são substituídos pelo último carácter de Depois.

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

inputstr: A cadeia de caracteres de entrada na qual serão efetuadas as substituições.

antes: Uma cadeia de caracteres com os caracteres que serão procurados na cadeia de caracteres de entrada para substituição.

depois: Uma cadeia de caracteres com os novos caracteres que irão substituir os definidos em antes.

    ' Substitui os caracteres acentuados
    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 disponibiliza constantes públicas úteis para os conjuntos de caracteres latinos, conforme ilustrado no 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 determinada expressão regular por uma nova cadeia de caracteres.

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

inputstr: A cadeia de caracteres de entrada na qual serão efetuadas as substituições.

regex: A expressão regular.

newstr: A cadeia de caracteres a substituir.

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefiniçã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 letra minúscula é substituída 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, numa cadeia de caracteres, algumas ou todas as ocorrências de um conjunto de cadeias de caracteres por um conjunto de novas cadeias de caracteres.

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

inputstr: A cadeia de caracteres de entrada na qual serão efetuadas as substituições.

oldstr: Uma única cadeia de caracteres ou um tabular de cadeias de caracteres. As cadeias de caracteres com comprimento zero são ignoradas.

newstr: A cadeia de caracteres de substituição ou o conjunto de cadeias de caracteres de substituição.

Se oldstr for um tabular, cada ocorrência de qualquer um dos elementos de oldstr é substituída por newstr.

Se oldstr e newstr forem matrizes, as substituições ocorrem uma a uma até ao UBound(newstr).

Se oldstr tiver mais entradas do que newstr, os elementos restantes em oldstr são substituídos pelo último elemento de newstr.

ocorrências: O número máximo de substituições. O valor predefinido é 0, o que significa que todas as ocorrências serão substituídas.

Quando oldstr é uma matriz, o parâmetro occurrence é calculado separadamente para cada elemento da matriz.

distingue maiúsculas e minúsculas: A pesquisa pode distinguir ou não maiúsculas e minúsculas (predefiniçã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

Devolve uma cadeia de caracteres com uma representação legível do argumento, truncada num determinado comprimento. Isto é útil principalmente para fins de depuração ou registo.

Se o parâmetro anyvalue for um objeto, será colocado entre colchetes «[» e «]».

Nas cadeias de caracteres, as tabulações e as quebras de linha são substituídas por \t, \n ou \r.

Se o comprimento final exceder o parâmetro maxlength, a parte final da cadeia de caracteres é substituída por «... (N)», em que N é o comprimento total da cadeia de caracteres original antes do truncamento.

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

anyvalue: O valor de entrada a representar. Pode ser qualquer valor, como uma cadeia de caracteres, um array, um objeto Basic, um objeto UNO, etc.

maxlength: O comprimento máximo da cadeia de caracteres resultante. O valor predefinido é 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-se que a representação de tipos de dados, tais como matrizes e instâncias do objeto ScriptForge.Dictionary, inclui tanto o tipo de dados como os respetivos valores:

    ' Um exemplo com uma matriz incorporada do Basic
    MsgBox SF_String.Represent(Array(1, 2, "Text" & Chr(9) & "here"))
    ' "[ARRAY] (0:2) (1, 2, Text\there)"
    ' Um exemplo com um Array do 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 do 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

Devolve a cadeia de caracteres de entrada na ordem inversa.

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

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

svc.Reverse(inputstr: str): str

inputstr: A cadeia de caracteres a inverter.

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

SplitLines

Devolve uma matriz de cadeias de caracteres, com índice a partir de zero, contendo as linhas da cadeia de caracteres de entrada. Cada elemento da matriz é obtido através da divisão da cadeia de caracteres de entrada nos caracteres de nova linha.

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

inputstr: A cadeia de caracteres a dividir.

keepbreaks: Quando True, as quebras de linha são preservadas no array de saída (valor predefinido = 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 uma cadeia de caracteres num conjunto de elementos utilizando um delimitador especificado.

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

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

inputstr: The string to be split.

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

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

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

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

Beware of the differences between Basic and Python when representing strings. For example, in Basic two "" characters inside a string are interpreted as a single " character. In Python, strings enclosed with single quotes can contain " characters without having to double them.

StartsWith

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

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

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

inputstr: The string to be tested.

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

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

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

TrimExt

Returns the input string without its leading and trailing whitespaces.

svc.TrimExt(inputstr: str): str

inputstr: The string to trim.

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

Unescape

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

svc.Unescape(inputstr: str): str

inputstr: The string to be converted.

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

Unquote

Removes the single or double quotes enclosing the input string.

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

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

inputstr: The string to unquote.

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

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

Wrap

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

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

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

Symbolic line breaks are replaced by their equivalent ASCII characters.

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

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

inputstr: The string to wrap.

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

tabsize: Before wrapping the text, the existing TAB Chr(9) characters are replaced with spaces. The argument tabsize defines the TAB stops at TabSize + 1, 2 * TabSize + 1 , ... N * TabSize + 1 (Default = 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 Basic que tenham o caractere de sublinhado «_» como prefixo estão reservados para uso interno. Não se destinam a ser utilizados em macros do Basic ou em scripts Python.