# Funções de string
As funções de *string* são usadas para manipular dados de *string*. Estas são as funções de *string* que você pode usar com a linguagem Double Braces da Digibee:
## CAPITALIZE
Coloca o primeiro caractere de uma *string* em caixa alta. Outros caracteres não são afetados.
### Sintaxe
```
CAPITALIZE(value : string) -> string
```
* `value`: a *string* cuja primeira letra deve ser maiúscula.
Retorna: uma string que é uma versão de value com o primeiro caractere em caixa alta.
### Exemplo de uso
{{ CAPITALIZE("hello, world!") }}
O resultado esperado é:
```
"Hello, world!"
```
## CONCAT
Concatena qualquer número de *strings* em uma única *string*.
### Sintaxe
```
CONCAT(*values: string) -> string
```
* `values`: qualquer número de *strings* a serem concatenadas.
Retorna: a *string* concatenada.
### Exemplo de uso
```
{{ CONCAT("Hello", ", ", "world!") }}
```
O resultado esperado é:
```
"Hello, world!"
```
## CONCATWITHOUTTAB
Concatena duas ou mais strings e substitui cada caractere de tabulação (`\t`) por um único espaço ( ).
### Sintaxe
```
CONCATWITHOUTTAB([, , ..., ])
```
* `, , ..., `: uma ou mais expressões de texto.
* Os colchetes `[ ]` indicam que parâmetros adicionais são opcionais.
### Exemplo de uso
```
"oi": {{ CONCATWITHOUTTAB("Hello", "\tWorld")}}
```
**Resultado esperado**
```
{
"oi": "Hello World"
}
```
## CONTAINS
Verifica se uma *substring* está contida em uma determinada *string*.
### Sintaxe
```
CONTAINS(main_string: string, sub_string: string) -> boolean
```
* `main_string`: a *string* principal a ser pesquisada.
* `sub_string`: a *substring* a ser procurada.
Retorna: um valor booleano indicando se a substring foi encontrada ou não. Retorna `true` se a *substring* for encontrada na string principal e `false`, caso contrário.
### Exemplo de uso
```
{{ CONTAINS("Hello, world!", "world") }}
```
O resultado esperado é:
```
true
```
## DEFAULT
Retorna um valor padrão quando uma referência é feita a um valor nulo ou inexistente.
### Sintaxe
```
DEFAULT(value: string, defaultValue: string) -> string
```
* `value`: o valor a ser verificado quanto à nulidade ou inexistência.
* `defaultValue`: o valor padrão a ser retornado se value for nulo ou inexistente.
Retorna: `value`, se value não for nulo ou inexistente, ou `defaultValue`, se for.
### Exemplo de uso
Suponha que você esteja usando esta função no parâmetro JSON de um componente JSON Generator que recebe o seguinte *payload*:
```json
{
"nome": "João Silva",
"idade": null
}
```
Você pode usar a função DEFAULT para substituir o valor nulo por uma string "não disponível".
```
{
"nome": "João Silva",
"idade" : {{ DEFAULT(message.idade, "não disponível") }}
}
```
O resultado esperado é:
```json
{
"nome": "João Silva",
"idade": "não disponível"
}
```
Leia [este artigo](https://docs.digibee.com/documentation/connectors-and-triggers/pt-br/double-braces/how-to-reference-data-using-double-braces) para saber mais sobre como referenciar dados com Double Braces.
## ESCAPE
Codifique uma *string* usando sequências de escape.
### Sintaxe
```
ESCAPE(value: string, escapeType: string) -> string
```
* `value`: a *string* a ser codificada.
* `escapeType`: o tipo de sequência de escape a ser utilizada. As opções válidas são "JSON", "XML", "CSV" e "HTML". Caso não especificado, assume valor padrão "JSON".
Retorna: uma nova string na qual certos caracteres foram substituídos por sequências de escape.
### Exemplo de uso
```
{{ ESCAPE("Hello, world!
", "HTML") }}
```
O resultado esperado é:
```
"<h1>Hello, world!</h1>"
```
### **FUZZYMATCH**
Realiza uma comparação aproximada entre uma string de referência e uma lista de candidatos com base na similaridade entre elas.
#### **Sintaxe**
```
FUZZYMATCH(stringDeEntrada, limite, candidato1, candidato2, ...)
```
* **stringDeEntrada:** A string de referência para comparação. Se for nula, será tratada como uma string vazia e a execução não será interrompida.
* **limite (threshold):** Um número entre 0 e 1 que define a similaridade mínima (por exemplo, 0.8 para 80%). Valores fora deste intervalo resultarão em erro.
* **candidatos:** Uma ou mais strings candidatas para comparação. Pelo menos um candidato deve ser fornecido.
**Retorno:** Uma array (lista) de strings contendo os candidatos que possuem similaridade maior ou igual ao limite fornecido, ordenados por similaridade decrescente (o mais semelhante primeiro). Os valores retornados preservam sua formatação original (maiúsculas, minúsculas e acentos).
{% hint style="info" icon="marker" %}
Para o cálculo da pontuação (score), a função ignora maiúsculas/minúsculas (*case-insensitive*), remove diacríticos (acentos), substitui pontuação por espaços e aglutina espaços múltiplos.
{% endhint %}
#### **Exemplos de Uso**
**1. Correspondência com Normalização (Maiúsculas e Acentos)** Mesmo com diferenças de acentuação no candidato, a normalização permite a correspondência se o limite for atingido.
* **Expressão:** `{{ FUZZYMATCH("ACME CORPORATION", 0.9, "ÁCME CORPÔRATION") }}`
* **Resultado:** `["ÁCME CORPÔRATION"]`
**2. Múltiplos Candidatos com Ordenação** A função filtra aqueles que não atingem o nível mínimo e ordena os resultados pela pontuação de proximidade.
* **Expressão:** `{{ FUZZYMATCH("Acme Corp", 0.6, "Globex", "Acme Corporation", "Aacme Corp") }}`
* **Resultado:** `["Aacme Corp", "Acme Corporation"]`
**3. Limite Rígido (Sem Correspondência)** Se nenhum candidato atingir a similaridade mínima, uma array vazia é retornada.
* **Expressão:** `{{ FUZZYMATCH("Apple", 0.9, "Pineapple", "Banana") }}`
* **Resultado:** `[]`
**4. Tratamento de Erro de Parâmetros** A função requer pelo menos 3 parâmetros (entrada, limite e 1 candidato).
* **Expressão:** `{{ FUZZYMATCH("teste", 0.8) }}`
* **Resultado:** `Error: Wrong number of parameters. Expected at least 3 mandatory.`
## INDEXOF
Retorna o índice da primeira ocorrência de uma *substring* dentro de uma *string* determinada. Essa pesquisa diferencia maiúsculas de minúsculas e o índice começa em 0.
### Sintaxe
```
INDEXOF(main_string: string, sub_string: string, fromIndex: integer) -> int
```
* `main_string`: a *string* principal a ser pesquisada.
* `sub_string`: a *substring* a ser procurada.
* `fromIndex`: o índice a partir do qual a pesquisa deve começar. Caso não especificado, assume valor padrão 0.
Retorna: um *integer* indicando o índice da primeira ocorrência da *substring* na *string* principal. Se a *substring* não for encontrada, a função retorna -1.
### Exemplos de uso
```
{{ INDEXOF("Hello, world!", "world") }}
```
O resultado esperado é:
```
7
```
```
{{ INDEXOF("Hello, world!", "welcome") }}
```
O resultado esperado é:
```
-1
```
## JOIN
Concatena uma lista de *strings* em uma única *string* com um caractere separador especificado entre cada *string*.
### Sintaxe
```
JOIN(separator: string, *values: string) -> string
```
* `separator`: uma *string* representando o caractere separador a ser usado entre cada *string*.
* `values`: qualquer número de *strings* a serem concatenados.
Retorna: a *string* concatenada com o caractere separador especificado entre cada *string* no *input*.
### Exemplos de uso
```
{{ JOIN(" ", "Estas","palavras", "são", "separadas","por","espaços") }}
```
O resultado esperado é:
```
"Estas palavras são separadas por espaços"
```
```
{{ JOIN("-", "Estas","palavras", "são","separadas","por","hífens") }}
```
O resultado esperado é:
```
"Estas-palavras-são-separadas-por-hífens"
```
## LASTINDEXOF
Retorna o índice da última ocorrência de uma *substring* dentro de uma determinada *string*. Essa pesquisa diferencia maiúsculas de minúsculas e o índice começa em 0.
### Sintaxe
```
LASTINDEXOF(main_string: string, sub_string: string) -> int
```
* `main_string`: a *string* principal a ser pesquisada.
* `sub_string`: a *substring* a ser procurada.
* `fromIndex`: o índice a partir do qual a pesquisa deve começar. O padrão é 0.
Retorna: um *integer* indicando o índice da última ocorrência da *substring* na *string* principal. Se a *substring* não for encontrada, a função retornará -1.
### Exemplos de uso
```
{{ LASTINDEXOF("Hello, world!", "o") }}
```
O resultado esperado é:
```
8
```
```
{{ LASTINDEXOF("Hello, world!", "a") }}
```
Como a substring "a" não está contida na string "Hello, world!", o resultado esperado é:
```
-1
```
## LEFTPAD
Preenche o lado esquerdo de uma determinada *string* com um caractere especificado até um tamanho específico.
### Sintaxe
```
LEFTPAD(value: string, length: integer, character:string) -> string
```
* `value`: a *string* de entrada a ser preenchida.
* `length`: o comprimento da string desejada.
* `character`: o caractere que será usado para preencher o lado esquerdo da string de entrada. Por padrão, um espaço em branco.
Retorna: uma string preenchida do comprimento desejado com o caractere especificado preenchendo o lado esquerdo da string de entrada. Se o comprimento da *string* de entrada já for maior ou igual ao especificado, a *string* original será retornada.
### Exemplos de uso
```
{{ LEFTPAD("example", 10, "-")
```
O resultado esperado é:
```
"---example"
```
```
{{ LEFTPAD("hello", 5, "*")
```
Como "hello" já possui 5 caracteres, o resultado esperado é:
```
"hello"
```
## LOWERCASE
Converte todos os caracteres em minúsculos.
### Sintaxe
```
LOWERCASE(value: string) -> string
```
* `value`: a *string* de entrada a ser convertida em letras minúsculas.
Retorna: a *string* que é o equivalente em minúsculas da *string* de entrada.
### Exemplo de uso
```
{{ LOWERCASE("HELLO, WorLD!") }}
```
O resultado esperado é:
```
"Hello, world!"
```
## MATCHES
Verifica se uma *string* corresponde a uma expressão regular.
### Sintaxe
```
MATCHES(value: string, pattern: string) -> boolean
```
* `value`: uma *string* que deve ser comparada com a expressão regular fornecida.
* `pattern`: um padrão de expressão regular que deve ser usado para corresponder à *string* de entrada.
Retorna: true, se a *string* de entrada corresponder à expressão regular, false, caso contrário.
### Exemplo de uso
```
{{ MATCHES("123-456-7890", "\\d{3}-\\d{3}-\\d{4}") }}
```
O resultado esperado é:
```
true
```
## NORMALIZE
Transforma quaisquer caracteres especiais em caracteres não especiais.
### Sintaxe
```
NORMALIZE(value: string) -> string
```
* `value`: a string a ser normalizada.
Retorna: a string normalizada com caracteres especiais substituídos por suas contrapartes não especiais.
### Exemplo de uso
```
{{ NORMALIZE("São Paulo") }}
```
O resultado esperado é:
```
"Sao Paulo"
```
## RANDOMSTRINGS
Gera *strings* aleatórias dados um conjunto de caracteres e o comprimento da *string*.
### Sintaxe
```
RANDOMSTRINGS(charset: string, length: int) -> string
```
* `charset`: o conjunto de caracteres a ser usado. As opções são: `"ALPHANUMERIC"`, `"ALPHABETIC"` , `"ASCII"`, e `"NUMERIC"`.
* `length`: o comprimento da *string* de saída.
### Exemplo de uso
```
{{ RANDOMSTRINGS("ALPHANUMERIC",10) }}
```
O *output* varia porque é aleatório. Um *output* possível é:
```
"lUbCIs7T3G"
```
## REPLACE
Substitui todas as ocorrências de uma *substring* em uma *string* com base em uma determinada expressão regular.
### Sintaxe
```
REPLACE(value: string, pattern: string, replacement: string) -> string
```
* `value`: a *string* a ser pesquisada e alterada.
* `pattern`: um padrão de expressão regular que especifica a *substring* a ser pesquisada.
* `replacement`: uma *string* que substituirá todas as ocorrências do padrão correspondente na *string* de entrada.
### Exemplo de uso
```
{{ REPLACE("Hello, world!", "Hello", "Bonjour") }}
```
O resultado esperado é:
```
"Bonjour, world!"
```
## RIGHTPAD
Preenche o lado direito de uma determinada *string* com um caractere especificado até um comprimento específico.
### Sintaxe
```
RIGHTPAD(value: string, length: integer, character:string) -> string
```
* `value`: a *string* de entrada a ser preenchida.
* `length`: o comprimento da *string* desejada.
* `character`: o caractere que será usado para preencher o lado direito da *string* de entrada. Por padrão, um espaço em branco.
Retorna: uma *string* preenchida do comprimento desejado com o caractere especificado preenchendo o lado direito da *string* de entrada. Se o comprimento da *string* de entrada já for igual ou maior que o especificado, a *string* original será retornada.
### Exemplos de uso
```
{{ RIGHTPAD("example", 10, "-") }}
```
O resultado esperado é:
```
"example---"
```
```
{{ RIGHTPAD("hello", 5, "*") }}
```
Como "hello" já possui 5 caracteres, o resultado esperado é:
```
"hello"
```
## SPLIT
Divide uma string em um *array* de strings com base em um padrão de expressão regular especificado.
### Sintaxe
```
SPLIT(value: string, pattern: string) -> Array[string]
```
* `value`: a *string* a ser dividida.
* `pattern`: um padrão de expressão regular que especifica o ponto de divisão. A *string* será dividida em todas as ocorrências do padrão.
Retorna: um *array* de strings resultante da operação de divisão.
### Exemplo de uso
```
{{ SPLIT("Hello, world!", " ") }}
```
O resultado esperado é:
```
["Hello,", "world!"]
```
## STRINGMATCHES
Retorna um *array* de todas as expressões correspondentes em uma *string* que atendem a um determinado padrão de expressão regular.
### Sintaxe
```
STRINGMATCHES(value: string, pattern: string, patternFlag: string) -> Array[string]
```
* `value`: uma *string* para procurar correspondências.
* `pattern`: um padrão de expressão regular para corresponder à *string*.
* `patternFlag`: o comportamento do mecanismo de expressão regular. Isso pode ser usado para modificar o comportamento de correspondência da expressão regular. Se não for especificado, o mecanismo de expressão regular usará seu comportamento padrão. As opções são:
* `CANON_EQ`: ativa a correspondência de equivalência canônica de caracteres Unicode. Quando esse *pattern flag* é ativado, os caracteres que parecem idênticos são correspondidos, mesmo que tenham codepoints diferentes no Unicode.
* `CASE_INSENSITIVE`: desativa a diferenciação de maiúsculas e minúsculas.
* `COMMENTS`: permite comentários no padrão de expressão regular. Você pode adicionar comentários após uma hashtag #.
* `DOTALL`: ativa o modo "dotall", que permite que um ponto. corresponda ao caractere de nova linha\n.
* `LITERAL`: quando este sinalizador é especificado, a string de entrada que especifica o padrão é tratada como uma sequência de caracteres literais. Metacaracteres ou sequências de escape na sequência de entrada não terão nenhuma interpretação especial.
* `MULTILINE`: ativa a correspondência em várias linhas.
* `UNICODE_CASE`: permite correspondência sem distinção entre maiúsculas e minúsculas de caracteres Unicode, levando em consideração as *case folding rules* do Unicode.
* `UNICODE_CHARACTER_CLASS`: permite classes de caracteres Unicode no padrão de expressão regular.
* `UNIX_LINES`: altera o comportamento dos metacaracteres ^ e $ para coincidir com o início e o fim de uma linha, respectivamente, em vez do início e do fim da *string* de entrada.
Retorna: um *array* de todas as expressões correspondentes na *string* que satisfazem o padrão inserido.
### Exemplo de uso
```
{{ STRINGMATCHES("Hello, world!", "hello", "CASE_INSENSITIVE") }}
```
O resultado esperado é:
```
["Hello"]
```
## SUBSTRING
Extrai uma *substring* de uma determinada *string*.
### Sintaxe
```
SUBSTRING(value: string, start: int, end: int, throwIndexOutOfBoundError: boolean) -> string
```
* `value`: a *string* original da qual a *substring* deve ser extraída.
* `start`: o índice inicial da *substring*. O índice começa em 0.
* `end`: o índice final da *substring*. Se não for fornecido, a extração terminará no último caractere da *string* original.
* `throwIndexOutOfBoundError`: se `true`, um erro será gerado se os índices fornecidos estiverem fora do intervalo. Caso contrário, a string original será retornada. Assume valor `true` por padrão.
Retorna: a *substring* extraída da *string* original.
### Exemplo de uso
```
{{ SUBSTRING("Hello, world!", 0, 5) }}
```
O resultado esperado é:
```
"Hello"
```
### TOSTRING
Converte um objeto em sua representação de *string*.
### Sintaxe
```
TOSTRING(object: any) -> string
```
* `object`: o objeto a ser convertido em uma *string*. Pode ser de qualquer tipo.
### Exemplo de uso
```
{{ TOSTRING(123) }}
```
O resultado esperado é:
```
"123"
```
## TRIM
Remove espaços em branco no início e no final de uma string.
### Sintaxe
```
TRIM(value: string) -> string
```
* `value`: a *string* a ser aparada.
Retorna: uma string que é uma versão aparada de `value`.
### Exemplo de uso
```
{{ TRIM(" Hello, world! ") }}
```
O resultado esperado é:
```
"Hello, world!"
```
## UNESCAPE
Decodifica uma *string* que possui sequências de escape.
### Sintaxe
```
UNESCAPE(value: string, escapeType: string) -> string
```
* `value`: a *string* a ser decodificada.
* `escapeType`: o tipo de sequência de escape a ser utilizada. As opções válidas são `"JSON"`, `"XML"`, `"CSV"` e `"HTML"`. O padrão é `"JSON"`.
Retorna: uma nova *string* na qual certos caracteres foram substituídos por sequências de escape.
### Exemplo de uso
```
{{ UNESCAPE("<h1>Hello, world!</h1>", "HTML") }}
```
O resultado esperado é:
```
"Hello, world!
"
```
## UPPERCASE
Converte todos os caracteres em maiúsculas.
### Sintaxe
```
UPPERCASE(value: string) -> string
```
* `value`: a *string* de entrada cujos caracteres devem ser convertidos em letras maiúsculas.
Retorna: o equivalente maiúsculo da *string* de entrada.
### Exemplo de uso
```
{{ UPPERCASE("Hello, world!") }}
```
O resultado esperado é:
```
"HELLO, WORLD!"
```