IBM FileNet P8, Version 5.2.1            

Funções de Cadeia

Esta seção contém breves descrições das funções que se aplicam aos valores de sequência.

Tabela 1. Tabela de funções e seus propósitos
Função O que ela faz
convert Converte uma cadeia para outro tipo de dados ou converte outro tipo de dados para uma cadeia.
decode Converte uma expressão de cadeia codificada de volta à cadeia original.
encode Converte uma expressão de cadeia em uma cadeia de texto sem sentido.
hex Converte uma cadeia literal contendo códigos de caracteres hexadecimais em uma cadeia ASCII.
in_set Retorna o valor booleano true se uma sequência for composta inteiramente de caracteres de outra sequência.
is_number Retorna o valor booleano true se uma expressão de sequência for avaliada como um valor flutuante ou de número inteiro.
is_time Retorna o valor booleano true se uma expressão de sequência for avaliada como um valor de horário válido.
len Retorna o comprimento de um cadeia.

lower

upper

Muda os caracteres de uma cadeia para minúsculos ou maiúsculos.

ltrim

rtrim

trim

Excluir caracteres em branco ou caracteres especificados do início (ltrim), fim (rtrim) ou ambas as extremidades (trim) de um cadeia.
max Retorna o maior valor em uma lista de expressões de qualquer tipo de dados suportado.
min Retorna o menor valor de uma lista de expressões de qualquer tipo de dados suportado.
numbertostring Converte uma expressão flutuante ou de números inteiros em uma expressão de cadeia, utilizando uma máscara especificada.
repeat Cria uma cadeia repetindo outra cadeia um número especificado de vezes.
strins Insere uma cadeia em outra cadeia em um local especificado.
strloc Retorna a posição de início de uma subcadeia dentro de uma cadeia. Se a subcadeia não for localizada, a função retorna zero.
stringtotime Converte uma expressão de cadeia em uma expressão de tempo, utilizando uma máscara especificada.
substitute Dentro de uma cadeia, substitui uma subcadeia por outra.
substr Retorna uma subcadeia determinada uma posição de início e o comprimento.
timetostring Converte uma expressão de tempo em uma expressão de cadeia utilizando uma máscara especificada.
translate Substitui caracteres em um cadeia.
xmlencode Converte um campo XML em uma expressão de cadeia.
xmldecode Converte uma expressão de cadeia em XML.

hex

Esta função converte uma cadeia literal de códigos de caracteres hexadecimais em uma cadeia ASCII. A função hexadecimal pode expressar qualquer caractere, embora você geralmente a utiliza para caracteres que não possuem representações ASCII, como tabulações.

Cada dois dígitos hexadecimais representam um caractere na cadeia de resultados. Um número ímpar de caracteres hexa na cadeia literal resulta em um erro. Use a sintaxe a seguir:
hex (hex_codes)
em que hex_codes é uma cadeia literal contendo o código hexa para um caractere ou uma série de caracteres.
O exemplo a seguir retorna a cadeia abc porque 61, 62 e 63 são os códigos hexadecimais para esses caracteres.
hex ("616263")

translate

Esta função cria uma nova cadeia substituindo os caracteres em uma cadeia pelos caracteres que você especifica. A função translate é útil para caracteres de codificação.

Use a sintaxe a seguir:
translate (source_string, search_string,
replace_string)
em que:
Tabela 2. Parâmetros e Descrições da Função translate
Parâmetro Descrição
source_string A cadeia contendo os caracteres a serem substituídos.
search_string A cadeia de caracteres dentro de source_string a ser substituída. Deve ser do mesmo comprimento que replace_string.
replace_string A cadeia de caracteres de substituição. Deve ser do mesmo comprimento que search_string.

A procura e substituição ocorre em uma base por caractere. Se a sequência de procura for "abc" e a sequência de substituição for "def", a função converterá "a" em "d", "b" em "e" e "c" em "f" na sequência recém-criada.

Por exemplo, com os valores a seguir,
source_string contém "*123-#44-!999"
search_string contém "#*!-"
replace_string contém "XYZ&"
A função gera uma saída com as seguintes novas cadeias:
Y123&X44&Z999

Observe que o conteúdo da cadeia de origem, a cadeia de procura e a cadeia de substituição não mudam.

Dica: Para procurar por e substituir uma subsequência inteira em vez de caracteres individuais, utilize a função substitute.
O exemplo a seguir utiliza a função translate para converter uma cadeia do formato numérico Europeu para o formato numérico Americano.
translate (str, ".,", ",.")

lower, upper

Essas funções convertem todos os caracteres em uma cadeia para minúsculas ou maiúsculas, respectivamente. Use a sintaxe a seguir:
lower (string_exp)

upper (string_exp)
em que string_exp é a expressão de cadeia a ser convertida.

in_set

Esta função compara duas sequências, retornando um valor booleano true se cada caractere na primeira sequência estiver contido em algum lugar na segunda sequência. Se a primeira cadeia contiver no mínimo um caractere que também não esteja contido na segunda cadeia, a função retornará um valor false. Os caracteres não precisam aparecer na mesma ordem em ambas as cadeias. Além disso, a segunda cadeia pode conter caracteres adicionais.

Use a sintaxe a seguir:
in_set (subset_string,
superset_string)
em que:
Tabela 3. Parâmetros e Descrições da Função in_set
Parâmetro Descrição
subset_string A expressão de cadeia contendo apenas os caracteres de subconjunto.
superset_string A expressão de cadeia com a qual subset_string é comparada.
No exemplo a seguir,
in_set (name, "abcdefghijklmnopqrstuvwxyz")
a função retorna true se
name = "jim"
, mas false se
name = "Fido"
ou
name = "a.b"

len

Esta função calcula o comprimento real (não declarado) de uma expressão de cadeia. Ela dá o número total de caracteres, incluindo espaços, na expressão. Use a sintaxe a seguir:
len (string_expr)
em que string_expr é uma expressão de cadeia cujo comprimento deve ser calculado.
No exemplo a seguir, o comprimento retornado é 15. Observe que as aspas não são contadas como caracteres.
len ("Hamilton Burger")

repeat

Esta função cria uma cadeia pela repetição de uma determinada cadeia um número de vezes especificado. Use a sintaxe a seguir:
repeat (string_expr, repeat_num)
em que:
Tabela 4. Parâmetros e Descrições da Função repeat
Parâmetro Descrição
string_expr A expressão de cadeia a ser repetida.
repeat_num O número de vezes que string_exp deve ser repetida.
O exemplo a seguir gera a saída da cadeia abcdabcdabcdabcdabcd.
repeat ("abcd", 5)

strloc

Uma subcadeia é uma parte de uma cadeia de origem. Ela pode ser menor que ou igual ao comprimento da cadeia de origem. Por exemplo, Good, Morn, od Morni e Good Morni são todos subsequências de Good Morning.

Utilize a função strloc para localizar onde uma subcadeia particular ocorre em uma cadeia de origem. Esta função retorna a posição de caractere inicial da subcadeia na cadeia de origem.

Se a subcadeia puder ser localizada na cadeia de origem mais de uma vez, a função retornará a posição de início de sua primeira ocorrência. Se a subcadeia não for localizada ou se a subcadeia for maior que a cadeia de origem, a função retornará zero.

Use a sintaxe a seguir:
strloc
(source_string, sub_string)
em que:
Tabela 5. Parâmetros e Descrições da Função strloc
Parâmetro Descrição
source_string A cadeia na qual procurar pela subcadeia.
sub_string A cadeia a ser procurada.
Este exemplo retorna o valor 6 porque a subcadeia inicia na posição 6 da cadeia de origem.
strloc ("Good Morning", "Morning")

substr

Esta função extrai uma subcadeia de uma cadeia de origem, criando assim uma nova cadeia. Você especifica a cadeia de origem e a posição do caractere em que a extração inicia. Além disso, é possível fornecer opcionalmente o número de caracteres a ser extraído. Se você não fornecer esta informação, a extração para no final da cadeia de origem.

Use a sintaxe a seguir:
substr (source_string, start_pos {,
length})
em que:
Tabela 6. Parâmetros e Descrições da Função substr
Parâmetro Descrição
source_string A cadeia de origem.
start_pos A posição do caractere na qual a extração inicia.
length O número de caracteres a serem extraídos (por exemplo, o comprimento da cadeia extraída).
O exemplo a seguir retorna a sequênciaMorning. Observe que as aspas não contam como parte da cadeia.
substr ("Good Morning!", 6, 7)

Essa função também pode extrair sequências de comprimento zero (sequências sem nenhum caractere entre as aspas) em uma posição de mais um do que o comprimento de uma sequência. Esse uso é útil para algoritmos que possuem cadeias de comprimento zero como uma condição de extremidade. É possível extrair caracteres das posições 1 até o último caractere da cadeia +1. Assim, as posições 1 e o comprimento da cadeia +1 são condições de extremidade.

Ocorrem erros de tempo de execução se:

  • Sua posição inicial for menor que 1 ou maior que o comprimento da cadeia de origem + 1.
  • O comprimento especificado poderia produzir uma subcadeia que é mais longa que os caracteres restantes na cadeia de origem (ou seja, start_pos + comprimento > len (source_string) + 1).

strins

Esta função insere uma cadeia em outra cadeia, criando assim uma nova cadeia. Os valores da cadeia de origem e da cadeia de inserção não mudam. Use a sintaxe a seguir:
strins (source_string, insert_string, start_pos)
em que:
Tabela 7. Parâmetros e Descrições da Função strins
Parâmetro Descrição
source_string A cadeia que será combinada com insert_string para produzir uma nova cadeia.
insert_string A cadeia que será combinada com source_string para produzir uma nova cadeia.
start_pos

A posição na source_string na qual a inserção inicia. Os valores variam de 1 até o comprimento de source_string + 1.

Ocorre um erro de tempo de execução se você especificar um valor menor que 1 ou maior que source_string + 1.

No exemplo abaixo, considere que
insert_str = "Mr. Jones,"
e que
source_str = "Good morning, what a lovely day."
strins (source_str, insert_str, 15)
Com os valores especificados acima, a função retorna a seguinte cadeia:
Good morning, Mr. Jones, what a lovely day.

substitute

Esta função cria uma nova cadeia substituindo uma subcadeia por uma outra dentro de uma cadeia de origem especificada. Use a sintaxe a seguir:
substitute (source_string, unwanted_string,
replacement_string)
em que:
Tabela 8. Parâmetros e Descrições da Função substitute
Parâmetro Descrição
source_string A cadeia que contém unwanted_string.
unwanted_string Uma subsequência de source_string.
replacement_string A sequência que substituirá unwanted_string para criar uma nova sequência.
No exemplo a seguir, cada ocorrência de abc dentro de TestString é substituída por wxyz. A substituição ocorre da esquerda para direita.
substitute (TestString, "abc", "wxyz")
Se
TestString = "abcdabcd"
a função retorna a seguinte nova sequência:
wxyzdwxyzd
Observe que os conteúdos das sequências de origem, não desejada e de substituição não mudam.
Dica: Para procurar por e substituir caracteres individuais em vez de uma subcadeia, utilize a função translate.

ltrim, rtrim e trim

Essas funções criam uma nova cadeia copiando uma cadeia de origem existente e excluindo caracteres em branco ou caracteres especificados do início (ltrim), final (rtrim) ou de ambas as extremidades (trim) da nova cadeia. Em todos os casos, a cadeia de origem permanece inalterada.

Utilize a sintaxe a seguir para todas as três funções:
ltrim (string_expr{, trim_char}opt)

rtrim (string_expr{, trim_char}opt)

trim (string_expr{, trim_char}opt)
em que:
Tabela 9. Parâmetros e Descrições das Funções trim, ltrim e rtrim
Parâmetro Descrição
string_expr A expressão da cadeia de origem a ser copiada.
trim_char

Um parâmetro opcional que especifica os caracteres a serem excluídos da nova cadeia. Se você não especificar este parâmetro, os espaços em branco são excluídos.

Dependendo da função, a exclusão começa no início, no final ou em ambas as extremidades da nova cadeia e continua até que um caractere não especificado em trim_char (ou um caractere não em branco) seja encontrado.

O exemplo a seguir exclui todos os brancos à esquerda de LastName. No exemplo,
LastName = "Smith"
e a nova sequência retornada é
"Smith"
ltrim (LastName)
O exemplo abaixo exclui o caractere & do final da sequência denominada Status. Se
Status = "OpenXY&Z&&&&"
a nova sequência retornada será
"OpenXY&Z"
rtrim (Status, "&")
O exemplo a seguir exclui todos os dígitos à direita de AccountName.
rtrim (AccountName, "0123456789")

is_number

Esta função determina se a expressão de cadeia especificada avalia para um valor flutuante ou valor de número inteiro. A função is_number retorna o valor booleano true se a sequência inteira (não apenas uma subsequência) for avaliada como um valor flutuante ou de número inteiro e false em vez disso.

Use a sintaxe a seguir:
is_number (expr)
em que expr é uma expressão de cadeia.
Os três exemplos a seguir retornam true, false e false, respectivamente.
is_number ("123.4")

is_number ("no")

is_number ("abc63j")

is_time

Esta função determina se a expressão de cadeia especificada avalia para um valor de horário em um determinado formato. A função is_time retorna o valor booleano true se a sequência inteira (não apenas uma subsequência) for avaliada como um horário que é formatado conforme especificado; caso contrário, a função retorna um valor false.

Use a sintaxe a seguir:
is_time (str_expr, date_time_mask)
em que:
Tabela 10. Parâmetros e Descrições da Função is_time
Parâmetro Descrição
str_expr Uma expressão de cadeia.
date_time_mask Uma máscara de data/hora que especifica o formato que str_expr deve utilizar para que is_time retorne um valor true.
Nos exemplos a seguir, o primeiro exemplo retorna false e o segundo exemplo retorna true. Em ambos os exemplos, a função convert é utilizada para converter as expressões de cadeia para o tipo de dados de horário para que a função is_time possa ser avaliada.
is_time ("nov121995", "mm/dd/yyyy")

is_time ("11/12/1995", "mm/dd/yyyy")

timetostring

Esta função converte uma expressão de tempo em uma expressão de cadeia, utilizando o formato que você especifica. Use a sintaxe a seguir:
timetostring (time_expr, date_time_mask)
em que:
Tabela 11. Parâmetros e Descrições da Função timetostring
Parâmetro Descrição
time_expr Uma expressão de tipo horário.
date_time_mask Uma máscara de data/hora que determina o formato da saída da função timetostring.
O exemplo a seguir converte o horário do sistema em uma cadeia. A cadeia é formatada utilizando a máscara de data/hora especificada.
timetostring (systemtime(), "mm/dd/yyyy hh:tt:ss am")
No exemplo a seguir, se systemtime() for equivalente a 1 de julho de 1985 às 12h45min06s, a saída da cadeia será:
7/1/1985 12:45:06 pm

Consulte as informações sobre a função systemtime().

stringtotime

Esta função converte cadeias em horários, utilizando o formato que você especifica. Use a sintaxe a seguir:
stringtotime
(string_expr, date_time_mask)
em que:
Tabela 12. Parâmetros e Descrições da Função stringtotime
Parâmetro Descrição
string_expr Um expressão de cadeia de tipos.
date_time_mask Uma máscara de data/hora que especifica o formato de horário a ser utilizado para conversão.
No exemplo a seguir, HostTime é uma variável de cadeia.
stringtotime (HostTime, "mon. dd, yyyy hh:tt:ss am")
Se
HostTime = "Jul. 1, 1985 12:45:06 pm"
, a saída resultante será o valor de horário equivalente a 1 de julho de 1985 aos 6 segundos após 12h45.

encode, decode

Essas funções convertem cadeias em cadeias sem sentido para o propósito de distinção de conteúdos. Tanto encode quanto decode devem estar no mesmo fluxo de trabalho.

A função decode pode ser utilizada para converter uma expressão de cadeia contendo múltiplas cadeias codificadas.
encode
(string_expr)

decode (string_expr)
em que:
Tabela 13. Parâmetros e Descrições das Funções decode e encode
Parâmetro Descrição
string_expr Um expressão de cadeia de tipos. A cadeia não pode ser um literal.


Last updated: March 2016
bpfe012.htm

© Copyright IBM Corporation 2016.