Versão: 20

Collection

A classe Collection gerencia variáveis de tipo Collection.

Uma coleção se inicializa com:


New collection {( ...value : any )} : Collection cria uma nova colecção vazia ou pré-carregada
New shared collection {( ...value : any )} : Collection cria uma nova colecção partilhada vazia ou pré-carregada

Exemplo

 var $colVar : Collection //criação de uma variável 4D de tipo coleção
 $colVar:=New collection //initialização da coleção e atribuição à variável 4D

Resumo


O código para o método LengthLessThan é: devolve o item na posição índice, permitindo números inteiros positivos e negativos
.average( {propertyPath : Text } ) : Real retorna a média aritmética dos valores definidos na instância de coleção
.clear() : Collection remove todos os elementos da instância de recolha e devolve uma coleção vazia
.combine( col2 : Collection {; index : Integer } ) : Collection insere col2 elementos no final ou no índice especificado posição na instância de coleção e devolve a colecção editada
.concat( value : any { ;...valueN } ) : Collection devolve uma nova colecção contendo os elementos da colecção original com todos os elementos do parâmetro value adicionado ao final
.copy() : Collection .copy( option : Integer ) : Collection .copy( option : Integer ; groupWithCol : Collection ) : Collection .copy( option : Integer ; groupWithObj : Object ) : Collection devolve uma cópia profunda da instância da coleção
.count( { propertyPath : Text } ) : Real devolve o número de elementos não-nulos na colecção
.countValues( value : any {; propertyPath : Text } ) : Real devolve o número de vezes que o valor é encontrado na colecção
.distinct( {option : Integer} ) : Collection .distinct( propertyPath : Text {; option : Integer } ) : Collection devolve uma colecção contendo apenas valores distintos (diferentes) da colecção original
.equal( collection2 : Collection {; option : Integer } ) : Boolean compara a collection com a collection2
.every( methodName : Text { ;...param : any } ) : Boolean .every( startFrom : Integer ; methodName : Text { ;...param : any } ) : Boolean returns true if all elements in the collection successfully passed a test implemented in the provided formula object or methodName method
.extract( propertyPath : Text { ; option : Integer } ) : Collection .extract( propertyPath : Text ; targetPath : Text { ;...propertyPathOrTargetPathN : Text } ) : Collection cria e devolve uma nova colecção contendo propertyPath valores extraídos da colecção original de objectos
.fill( value : any ) : Collection .fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection insere elementos no índice posição na instância de coleção e devolve a coleção editada
.find( methodName : Text { ; ...param : any } ) : any .find( startFrom : Integer ; methodName : Text { ; ...param : any } ) : any devolve uma nova coleção contendo todos os elementos da coleção original para a qual a fórmula ou methodName resultado for true
Com o método TypeLookUp: pesquisa a expressão toSearch entre os elementos da colecção e devolve o índice da primeira ocorrência encontrada, ou -1 se não foi encontrada
.findIndex( methodName : Text { ; ...param : any } ) : Integer .findIndex( startFrom : Integer ; methodName : Text { ; ...param : any } ) : Integer preenche a coleção com o valor especificado *, opcionalmente de startFrom* index to end index, e devolve a coleção resultante
Com o método Flatten: sorts the elements of the original collection
O código para NumAscending é: creates a new collection with all sub-collection elements concatenated into it recursively up to the specified depth
.map( methodName : Text { ; ...param : any } ) : Collection cria uma nova colecção com base no resultado da chamada da function 4D formula ou do método methodName em cada elemento da colecção original e achatada com uma profundidade de 1
O código para TypeLookUp é: devolve True se a expressão toSearch for encontrada entre os elementos da colecção; caso contrário, devolve False
.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer The `.findIndex()` function
.indices( queryString : Text { ; ...value : any } ) : Collection devolve índices, na coleção original, de elementos da coleção de objectos que correspondem à queryString condições de pesquisa
.insert( index : Integer ; element : any ) : Collection define o comprimento da coleção para o novo tamanho especificado e devolve a coleção redimensionada
.join( delimiter : Text { ; option : Integer } ) : Text inserts the given value(s) at the beginning of the collection
O código para WordLength é: devolve o último elemento da colecção
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer pesquisa a expressão toSearch entre os elementos da coleção e devolve o índice da última ocorrência
.length : Integer devolve o número de elementos da colecção
Aqui está o método sortCollection: cria uma nova colecção com base no resultado da chamada da fórmula ** 4D function ou methodName method em cada elemento da colecção original
.max( { propertyPath : Text } ) : any devolve o elemento com o maior valor na colecção
.min( { propertyPath : Text } ) : any devolve o elemento com o menor valor da colecção
.orderBy( ) : Collection .orderBy( pathStrings : Text ) : Collection .orderBy( pathObjects : Collection ) : Collection .orderBy( ascOrDesc : Integer ) : Collection devolve uma nova colecção contendo todos os elementos da colecção na ordem especificada
.orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection devolve uma nova coleção contendo todos os elementos da coleção na ordem definida através da função 4D formula ou método methodName
.pop() : any remove o primeiro elemento da coleção e devolve-o como resultado da função
.push( element : any { ;...elementN } ) : Collection The `.indexOf()` function
.query( queryString : Text ; ...value : any ) : Collection .query( queryString : Text ; querySettings : Object ) : Collection devolve todos os elementos de uma coleção de objectos que correspondem às condições de pesquisa
.reduce( methodName : Text ) : any .reduce( methodName : Text ; initValue : any { ; ...param : expression } ) : any The `.reduce()` function
O código para o método FindCity é: aplica a formula ou methodName callback a um acumulador e a cada elemento da colecção (da direita para a esquerda) para o reduzir a um único valor
.remove( index : Integer { ; howMany : Integer } ) : Collection insere elementos no índice posição na instância de coleção e devolve a coleção editada
.resize( size : Integer { ; defaultValue : any } ) : Collection define o comprimento da coleção para o novo tamanho especificado e devolve a coleção redimensionada
.reverse( ): Collection devolve uma cópia profunda da colecção com todos os seus elementos em ordem inversa
.shift() : any remove o primeiro elemento da colecção e devolve-o como resultado da função
.slice( startFrom : Integer { ; end : Integer } ) : Collection devolve uma parte de uma colecção para uma nova colecção
.some( methodName : Text { ; ...param : any } ) : Boolean .some( startFrom : Integer ; methodName : Text { ; ...param : any } ) : Boolean anexa um ou mais elementos(s) ao final da instância de recolha e devolve a coleção editada
.sort() : Collection .sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection .sort( methodName : Text { ; ...extraParam : any } ) : Collection remove o primeiro elemento da colecção e devolve-o como resultado da função
.sum( { propertyPath : Text } ) : Real devolve a soma para todos os valores na instância da coleção
.unshift( value : any { ;...valueN : any } ) : Collection insere o valor dado no início da coleção

`Nova coleção`

New collection {( ...value : any )} : Collection

Parâmetro	Tipo		Descrição
value	Number, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer	->	Valor(es) de collection
Resultados	Collection	<-	A nova coleção

Descrição

O comando New collection cria uma nova colecção vazia ou pré-carregada e devolve a sua referência.

Se não passar nenhum parâmetro, New collection cria uma coleção vazia e retorna sua referência.

Precisa atribuir a referência devolvida à uma variável 4D de tipo Collection.

Opcionalmente pode pré-preencher a nova coleção passando um ou mais parâmetros value.

Pode também adicionar ou modificar elementos subsequentemente através de assignação. Por exemplo:

 myCol[10]:="My new element"

Se o novo índice de elemento estiver além do último elemento existente da coleção, a coelção é redimensionada automaticamente e todos os elementos intermediários são atribuídos ao valor null.

Pode passar qualquer número de valores de qualquer tipo compatível (número, texto, data, imagem, ponteiro, objeto, coleção....). Diferente de arrays, coleções podem misturar dados de tipos diferentes.

Pode prestar atenção aos problemas de conversão abaixo:

Se passar um ponteiro, é mantido "tal qual": é avaliado usando o comando JSON Stringify
Datas são armazenadas no formato "aaaa-mm-dd" ou strings com o formato "AAAA-MM-DDTHH:mm:ss.SSSZ", de acordo com a configuração atual "dates inside objects"/datas dentro de objetos. Quando converter datas 4D em texto antes de armazená-las em uma coleção, como padrão o programa considera a zona horária local. Pode modificar esse comportamento usando o seletor Dates inside objects do comando SET DATABASE PARAMETER.
Se passar a hora, é armazenada como um número de milissegundos (Real).

Exemplo 1

Se quiser criar uma nova coleção vazia e atribuí-la à uma variável coleção 4D:

 var $myCol : Collection
 $myCol:=New collection
  //$myCol=[]

Exemplo 2

Se quiser criar uma coleção pré-prenchida:

 var $filledColl : Collection
 $filledColl:=New collection(33;"mike";"november";->myPtr;Current date)
  //$filledColl=[33,"mike","november","->myPtr","2017-03-28T22:00:00.000Z"]

Exemplo 3

Pode criar uma nova coleção e adicionar um novo elemento:

 var $coll : Collection
 $coll:=New collection("a";"b";"c")
  //$coll=["a","b","c"]
 $coll[9]:="z" //adicionar um 10º elemento com o valor "z"
 $vcolSize:=$coll.length //10
  //$coll=["a","b","c",null,null,null,null,null,null,"z"]

`New shared collection`

Histórico

Release	Mudanças
v16 R6	Adicionado

New shared collection {( ...value : any )} : Collection

Parâmetro	Tipo		Descrição
value	Number, Text, Date, Time, Boolean, Shared object, Shared collection	->	Valores da collection compartida
Resultados	Collection	<-	A nova coleção compartilhada

Descrição

O comando New shared collection cria uma nova colecção partilhada vazia ou pré-carregada e devolve a sua referência.

A adição de um elemento a esta coleção utilizando o operador de atribuição deve ser rodeada pela estrutura Use... End use , caso contrário é gerado um erro (isto não é necessário ao adicionar elementos utilizando funções como push() ou map() porque estes ativam automaticamente uma estrutura interna Use... End use). A leitura de um elemento sem um Use... End use estrutura é, no entanto, possível.

info

Para saber mais sobre coleções partilhadas, veja a página Shared objects and collections.

Se não quiser passar parâmetros, New shared collection cria uma coleção vazia partilhada e retorna sua referência.

Precisa atribuir a referência devolvida à uma variável 4D de tipo Collection.

Opcionalmente pode preencher automaticamente a nova coleção partilhada passando um ou vários valorescomo parâmetros. Também pode adicionar ou modificar elementos através de atribuição de notação de objetos (ver exemplo).

Se o novo índice elemento for além do último elemento existente da coleção partilhada, a coleção é automaticamente redimensionada e todos os novos elementos intermediários são atribuídos um valornull.

Pode passar qualquer número de valores dos tipos compatíveis abaixo:

número (real, longint....). Valores numéricos são sempre armazenados como reais.
text
boolean
date
hora (armazenada como número de milissegundos - real)
null
objeto compartido
coleção compartilhada

nota

Diferente de coleções padrão (não partilhadas), coleções partilhadas não são compatíveis com imagens, ponteiros e objetos ou coleção que não forem partilhadas.

Exemplo

 $mySharedCol:=New shared collection("alpha";"omega")
 Use($mySharedCol)
    $mySharedCol[1]:="beta"
 End use

.at()

Histórico

Release	Mudanças
20	Adicionado

O código para o método LengthLessThan é:

Parâmetro	Tipo		Descrição
index	Integer	->	Índice de elemento a devolver
Resultados	any	<-	O elemento nesse índice

Descrição

A função .some() devolve o item na posição índice, permitindo números inteiros positivos e negativos.

Os números inteiros negativos contam para trás a partir do último item da colecção.

Se end < 0 , é recalculado como sendo end:=end+length.

Exemplo

var $col : Collection
$col:=New collection(10; 20; 30; 40; 50)
$element:=$col.at(0) // 10
$element:=$col.at(1) // 20
$element:=$col.at(-1) // 50
$element:=$col.at(-2) // 40
$element:=$col.at(10) // undefined

.average()

Histórico

Release	Mudanças
v16 R6	Adicionado

.average( {propertyPath : Text } ) : Real

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota de propriedade objeto a ser usado para cálculos
Resultados	Real, Undefined	<-	Média aritmética dos valores coleção

Descrição

A função .average() retorna a média aritmética dos valores definidos na instância de coleção.

Apenas elementos numéricos são considerados para cálculos (outros tipos são ignorados).

Se a coleção contiver objetos, passe o parâmetro propertyPath para indicar a propriedade objeto para levar em consideração.

.average() retorna undefined se:

a coleção estiver vazia,
a coleção não contiver elementos numéricos,
propertyPath não for encontrada na collection.

Exemplo 1

 var $col : Collection
 $col:=New collection(10;20;"Monday";True;6)
 $vAvg:=$col.average() //12

Exemplo 2

 var $col : Collection
 $col:=New collection
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Gross";"salary";10500))
 $vAvg:=$col.average("salary") //23500

.clear()

Histórico

Release	Mudanças
v16 R6	Adicionado

.clear() : Collection

Parâmetro	Tipo		Descrição
Resultados	Collection	<-	Collection original com todos os elementos removidos

Descrição

A função .clear() remove todos os elementos da instância de recolha e devolve uma coleção vazia.

Exemplo

var $col : Collection
$col:=New collection(1;2;5)
$col.clear()
$vSize:=$col.length //$vSize=0

.combine()

Histórico

Release	Mudanças
v16 R6	Adicionado

.combine( col2 : Collection {; index : Integer } ) : Collection

Parâmetro	Tipo		Descrição
col2	Collection	->	Collection a combinar
index	Integer	->	Posição para a qual inserir elementos para combinar em coleção (padrão = length +1)
Resultados	Collection	<-	Collection original contendo elementos combinados

Descrição

A função .combine() insere col2 elementos no final ou no índice especificado posição na instância de coleção e devolve a colecção editada. Ao contrário da função .insert(), .combine() adiciona cada valor de col2 na coleção original, e não como um único elemento de coleção.

Como padrão, elementos col2 são adicionados ao final da collection original. Pode passar em index a posição onde quiser que os elmentos col2 sejam inseridos na coleção.

Se index > o tamanho da coleção, o início real de index será estabelecido para o tamanho da coleção.
Se index < 0, será recalculado como index:=index+length (é considerado como o offset do final da coleção).
Se o valor calculado for negativo, index será estabelecido como 0.

Exemplo

var $c; $fruits : Collection
$c:=New collection(1;2;3;4;5;6)
$fruits:=New collection("Orange";"Banana";"Apple";"Grape")
$c.combine($fruits;3) //[1,2,3,"Orange","Banana","Apple","Grape",4,5,6]

.concat()

Histórico

Release	Mudanças
v16 R6	Adicionado

.concat( value : any { ;...valueN } ) : Collection

Parâmetro	Tipo		Descrição
value	Number, Text, Object, Collection, Date, Time, Boolean, Picture	->	Valores a concatenar. Se value for uma coleção, todos os elementos da coleção são adicionados para a coleção original
Resultados	Collection	<-	Nova coleção com valores adicionados à coleção original

Descrição

A função .concat() devolve uma nova colecção contendo os elementos da colecção original com todos os elementos do parâmetro value adicionado ao final.

Se value for uma coleção, todos os elementos são adicionados como novos elementos no final da coleção original. Se value não for a coleção, será adicionado ao novo elemento.

Exemplo

var $c : Collection
$c:=New collection(1;2;3;4;5)
$fruits:=New collection("Orange";"Banana";"Apple";"Grape")
$fruits.push(New object("Intruder";"Tomato"))
$c2:=$c.concat($fruits) //[1,2,3,4,5,"Orange","Banana","Apple","Grape",{"Intruder":"Tomato"}]
$c2:=$c.concat(6;7;8) //[1,2,3,4,5,6,7,8]

.copy()

Histórico

Release	Mudanças
18 R3	Nova opção ck shared. Novos parâmetros groupWith
v16 R6	Adicionado

.copy() : Collection
.copy( option : Integer ) : Collection
.copy( option : Integer ; groupWithCol : Collection ) : Collection
.copy( option : Integer ; groupWithObj : Object ) : Collection

Parâmetro	Tipo		Descrição
option	Integer	->	`ck resolve pointers`: resolve ponteiros antes de copiar, `ck shared`: retorna uma coleção partilihada
groupWithCol	Collection	->	Coleção partilhada a ser agrupada com a coleção resultante
groupWithObj	Object	->	Objeto partilhado a ser agrupado com a coleção resultante
Resultados	Collection	<-	Cópia profunda da collection original

Descrição

A função .copy() devolve uma cópia profunda da instância da coleção.Deep copy significa que os objectos ou colecções dentro da colecção original são duplicados e não partilham qualquer referência com a colecção devolvida.

Se passado, o parâmetro option pode conter uma das constantes abaixo (ou ambas):

option	Descrição
`ck resolve pointers`	Se a collection original contém valores tipo ponteiro, por padrão a cópia também contém os ponteiros. Entretanto pode resolver ponteiros quando copiar por passando os `ck resolve pointers`. Nesse caso, cada ponteiro presenta na coleção é avaliada quando copiar e seu valor de dereferencia é usado.
`ck shared`	Como padrão, `copy()` retorna uma colleciton regular (não partilhado), mesmo se o comando for aplicado para a collection shared. Passe a constante `ck shared` para criar uma collection shared. Nesse caso, pode usar o parâmetro groupWith para associar a collection partilhada com outra collection ou objeto (ver abaixo).

Os parâmetros groupWithCol ou groupWithObj permite determinar uma collection ou um objeto com o qual a coleção resultante deveria ser associada.

nota

Os objectos de datastore, dataclass, e entity não são copiáveis. Se .copy() for chamado com eles, Null valores são devolvidos.

Exemplo 1

Se quiser copiar a collection comum (não partilhada) $lastnames no objeto partilhado $sharedObject. Para fazer isso, precisa criar uma cópia partilhada da coleção ($sharedLastnames).

var $sharedObject : Object
var $lastnames;$sharedLastnames : Collection
var $text : Text

$sharedObject:=New shared object

$text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")
$lastnames:=JSON Parse($text) //$lastnames is a regular collection

$sharedLastnames:=$lastnames.copy(ck shared) //$sharedLastnames is a shared collection

//Now we can put $sharedLastnames into $sharedObject Use($sharedObject)
    $sharedObject.lastnames:=$sharedLastnames End use

Exemplo 2

Se quisermos combinar $sharedColl1 e $sharedColl2. Já que pertencem a grupos partilhados diferentes, uma combinação diferente resultaria em um erro. Por isso precisa fazer uma cópia partilhada de $sharedColl1 e designar $sharedColl2 commo um grupo partilhado para a cópia.

var $sharedColl1;$sharedColl2;$copyColl : Collection

$sharedColl1:=New shared collection(New shared object("lastname";"Smith"))
$sharedColl2:=New shared collection(New shared object("lastname";"Brown"))

//$copyColl belongs to the same shared group as $sharedColl2
 $copyColl:=$sharedColl1.copy(ck shared;$sharedColl2)
 Use($sharedColl2)
    $sharedColl2.combine($copyColl)
 End use

Exemplo 3

Se tiver uma collection comum ($lastnames) e se quisermos colocar emStorage da aplicação. Para fazer isso, precisamos criar antes uma cópia partilhada ($sharedLastnames).

var $lastnames;$sharedLastnames : Collection
var $text : Text

$text:=Document to text(Get 4D folder(Current resources folder)+"lastnames.txt")
$lastnames:=JSON Parse($text) //$lastnames is a regular collection

$sharedLastnames:=$lastnames.copy(ck shared) // shared copy Use(Storage)
    Storage.lastnames:=$sharedLastnames End use

Exemplo

Esse exemplo ilustra o uso da opção ck resolve pointers:

 var $col : Collection
 var $p : Pointer
 $p:=->$what

 $col:=New collection
 $col.push(New object("alpha";"Hello";"num";1))
 $col.push(New object("beta";"You";"what";$p))

 $col2:=$col.copy()
 $col2[1].beta:="World!"
 ALERT($col[0].alpha+" "+$col2[1].beta) //exibe "Hello World!"

 $what:="You!"
 $col3:=$col2.copy(ck resolve pointers)
 ALERT($col3[0].alpha+" "+$col3[1].what) //exibe "Hello You!"

.count()

Histórico

Release	Mudanças
v16 R6	Adicionado

.count( { propertyPath : Text } ) : Real

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota de propriedade objeto a ser usado para cálculos
Resultados	Real	<-	Número de elementos na coleção

Descrição

A função .count() devolve o número de elementos não-nulos na colecção.

Se a coleção conter objetos, pode passar o parâmetro propertyPath. Nesse caso, só elementos que conterem propertyPath serão levados em consideração.

Exemplo

 var $col : Collection
 var $count1;$count2 : Real
 $col:=New collection(20;30;Null;40)
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Gross";"salary";10500))
 $col.push(New object("lastName";"Henry";"salary";12000))
 $count1:=$col.count() //$count1=7
 $count2:=$col.count("name") //$count2=3

.countValues()

Histórico

Release	Mudanças
v16 R6	Adicionado

.countValues( value : any {; propertyPath : Text } ) : Real

Parâmetro	Tipo		Descrição
value	Text, Number, Boolean, Date, Object, Collection	->	Valor a contar
propertyPath	Text	->	Rota de propriedade objeto a ser usado para cálculos
Resultados	Real	<-	Número de ocorrências do valor

Descrição

A função .countValues() devolve o número de vezes que o valor é encontrado na colecção.

Pode passar em value:

um valor escalar (texto, número, booleano, data),
um objeto ou uma referência de coleção.

Para um elemento ser encontrado, o tipo de value deve ser equivalente ao tipo de elemento, o método usa o operador equality.

O parâmetro opcional propertyPath permite contar valores dentro de uma coleção de objetos: passe em propertyPath a rota da propriedade cujos valores quer contar.

Exemplo 1

 var $col : Collection
 var $vCount : Integer
 $col:=New collection(1;2;5;5;5;3;6;4)
 $vCount:=$col.countValues(5) // $vCount=3

Exemplo 2

 var $col : Collection
 var $vCount : Integer
 $col:=New collection
 $col.push(New object("name";"Smith";"age";5))
 $col.push(New object("name";"Wesson";"age";2))
 $col.push(New object("name";"Jones";"age";3))
 $col.push(New object("name";"Henry";"age";4))
 $col.push(New object("name";"Gross";"age";5))
 $vCount:=$col.countValues(5;"age") //$vCount=2

Exemplo 3

 var $numbers; $letters : Collection
 var $vCount : Integer

 $letters:=New collection("a";"b";"c")
 $numbers:=New collection(1;2;$letters;3;4;5)

 $vCount:=$numbers.countValues($letters) //$vCount=1

.distinct()

Histórico

Release	Mudanças
20	Suporte de `ck count values`
v16 R6	Adicionado

.distinct( {option : Integer} ) : Collection
.distinct( propertyPath : Text {; option : Integer } ) : Collection

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota do atributo cujos valores quer obter
options	Integer	->	`ck diacritical`: avaliação diacríticos ("A" # "a" por exemplo)
Resultados	Collection	<-	Nova coleção com apenas valores distintos

Descrição

A função .distinct() devolve uma colecção contendo apenas valores distintos (diferentes) da colecção original.

A coleção retornada é ordenada automaticamente. Valores Null não são retornados.

Se a coleção conter objetos, pode passar o parâmetro propertyPath para indicar a propriedade objeto cujos valores diferentes você quer obter.

pathString (Text) : Este parâmetro contém uma fórmula feita de rotas de atributo 1 a x (e opcionalmente) ordenação separado por vírgulas A sintaxe é:

Parâmetros	Valor	Comentário
`ck diacritical`	8	A avaliação é sensível a maiúsculas e minúsculas e diferencia os caracteres acentuados. Como padrão, uma avaliação não-diacrítica é realizada.
`ck count values`	32	Devolve a contagem de elementos para cada valor distinto. Quando esta opção é passada, `.distinct()` devolve uma colecção de objectos que contém um par de atributos `{"value":value; "count":count}`.

Exemplos

 var $c; $c2 : Collection
 $c:=New collection
 $c.push("a";"b";"c";"A";"B";"c";"b";"b")
 $c.push(New object("size";1))
 $c.push(New object("size";3))
 $c.push(New object("size";1))
 $c2:=$c.distinct() //$c2=["a","b","c",{"size":1},{"size":3},{"size":1}]
 $c2:=$c.distinct(ck diacritical) //$c2=["a","A","b","B","c",{"size":1},{"size":3},{"size":1}]
 $c2:=$c.distinct("size") //$c2=[1,3]

.equal()

Histórico

Release	Mudanças
v16 R6	Adicionado

.equal( collection2 : Collection {; option : Integer } ) : Boolean

Parâmetro	Tipo		Descrição
collection2	Collection	->	Coleção a comparar
option	Integer	->	`ck diacritical`: avaliação diacríticos ("A" # "a" por exemplo)
Resultados	Parâmetros	<-	True se as coleções forem idênticas, senão false

Descrição

A função .equal() compara a collection com a collection2 e retorna true se forem idênticos (deep comparison).

Notas

The .equal() function only checks equality for string, boolean, number, and null type elements in the collections. Ele não verifica a igualdade dos objetos nativos.
Elements with null values are not equal to Undefined elements.

Como padrão, uma avaliação não-diacrítica é realizada. Se quiser que a avaliação diferencie maiúsculas de minúsculas e caracteres acentuados, passe a constanteck diacritical no parâmetro option.

Exemplo

 var $c; $c2 : Collection
 var $b : Boolean

 $c:=New collection(New object("a";1;"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"orange");2;3;4)
 $b:=$c.equal($c2) // false

 $c:=New collection(New object("1";"a";"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"orange");2;3)
 $b:=$c.equal($c2) // false

 $c:=New collection(New object("a";1;"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"ORange");2;3)
 $b:=$c.equal($c2) // true

 $c:=New collection(New object("a";1;"b";"orange");2;3)
 $c2:=New collection(New object("a";1;"b";"ORange");2;3)
 $b:=$c.equal($c2;ck diacritical) //false

.every()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.every( methodName : Text { ;...param : any } ) : Boolean
.every( startFrom : Integer ; methodName : Text { ;...param : any } ) : Boolean

Parâmetro	Tipo		Descrição
startFrom	Integer	->	Índice para início do teste em
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	Mixed	->	methodName recebe os parâmetros abaixo:
Resultados	Parâmetros	<-	True se todos os elementos passarem o teste com sucesso

Descrição

A função .every() returns true if all elements in the collection successfully passed a test implemented in the provided formula object or methodName method.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

Em methodName, passe o nome do método para usar para avliar elementos collection, junto com os parâmetros em param (opcional). methodName pode realizar qualquer teste, com ou sem os parâmetros. Este método recebe um Object como primeiro parâmetro ($1) e deve estabelecer $1.result para true para o primeiro elemento que cumprir a condição.

A chamada de retorno recebe os seguintes parâmetros:

$1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
methodName recebe os parâmetros abaixo:
$N...: param2...paramN

Pode definir o(s) seguinte(s) parâmetro(s):

#DECLARE ($toEval : Object ; $param : Integer) //$1; $2 If(Value type($toEval.value)=$param) $toEval.result:=True End if
$1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Em todos os casos, no ponto quanod a função .every() encontra o primeiro elemento de coleção retornando false em $1.result, ele para de chamar methodName e retorna false.

Como padrão, .every() testa a coleção completa. Opcionalmente, pode passar em startFrom o índice do elemento a partir do qual se inicia o teste.

Se startFrom >= tamanho da coleção, é retornado false, o que significa que a coleção não é testada.
Se startFrom < 0, é considerada como offset do final da coleção( startFrom:=startFrom+length).
Se startFrom = 0, a coleção inteira é pesquisada (padrão).

Exemplo 1

var $c : Collection  
var $b : Boolean
$c:=New collection
$c.push(5;3;1;4;6;2)
$b:=$c.every("NumberGreaterThan0") //retorna true
$c.push(-1)
$b:=$c.every("NumberGreaterThan0") //retorna false

Exemplo 2

Esse exemplo testa que todos os elementos da coleção sejam do tipo real:

var $c : Collection
var $b : Boolean
$c:=New collection
$c.push(5;3;1;4;6;2)
$b:=$c.every("TypeLookUp";Is real) //$b=true
$c:=$c.push(New object("name";"Cleveland";"zc";35049))
$c:=$c.push(New object("name";"Blountsville";"zc";35031))
$b:=$c.every("TypeLookUp";Is real) //$b=false

.extract()

Histórico

Release	Mudanças
v16 R6	Adicionado

.extract( propertyPath : Text { ; option : Integer } ) : Collection
.extract( propertyPath : Text ; targetPath : Text { ;...propertyPathOrTargetPathN : Text } ) : Collection

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota de propriedade de objeto cujos valores serão extraídos para nova coleção
targetpath	Text	->	Rota de propriedade alvo ou nome propriedade
option	Integer	->	`ck keep null`: inclui propriedades null na coleção retornada (ignorado como padrão). Parâmetro ignorado se for passado targetPath.
Resultados	Collection	<-	Nova collection contendo valores extraídos

Descrição

A função .extract() cria e devolve uma nova colecção contendo propertyPath valores extraídos da colecção original de objectos.

Os conteúdos da coleção retornada depende do parâmetro targetPath:

Se o parâmetro targetPath for omitido, .extract() preenche a nova coleção com os valores propertyPath da coleção original.

Como padrão, elementos para os quais propertyPath for null ou undefined são ignorados na coleção resultante. Pode passar a constante ck keep null no parâmetro option para incluir esses valores como elementos null na coleção retornada.
If one or more targetPath parameter(s) are passed (corresponding to one or more propertyPath parameter(s)), .extract() populates the new collection with the propertyPath properties and each element of the new collection is an object with targetPath properties filled with the matching propertyPath properties. Se mantém os valores null (o parámetro option se ignora) com esta sintaxe.

Exemplo 1

var $c : Collection
$c:=New collection
$c.push(New object("name";"Cleveland"))
$c.push(New object("zip";5321))
$c.push(New object("name";"Blountsville"))
$c.push(42)
$c2:=$c.extract("name") // $c2=[Cleveland,Blountsville]
$c2:=$c.extract("name";ck keep null) //$c2=[Cleveland,null,Blountsville,null]

Exemplo 2

var $c : Collection
$c:=New collection
$c.push(New object("zc";35060))
$c.push(New object("name";Null;"zc";35049))
$c.push(New object("name";"Cleveland";"zc";35049))
$c.push(New object("name";"Blountsville";"zc";35031))
$c.push(New object("name";"Adger";"zc";35006))
$c.push(New object("name";"Clanton";"zc";35046))
$c.push(New object("name";"Clanton";"zc";35045))
$c2:=$c.extract("name";"City") //$c2=[{City:null},{City:Cleveland},{City:Blountsville},{City:Adger},{City:Clanton},{City:Clanton}]
$c2:=$c.extract("name";"City";"zc";"Zip") //$c2=[{Zip:35060},{City:null,Zip:35049},{City:Cleveland,Zip:35049},{City:Blountsville,Zip:35031},{City:Adger,Zip:35006},{City:Clanton,Zip:35046},{City:Clanton,Zip:35045}]

.fill()

Histórico

Release	Mudanças
v16 R6	Adicionado

.fill( value : any ) : Collection
.fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection

Parâmetro	Tipo		Descrição
value	number, Text, Collection, Object, Date, Boolean	->	Valores preenchido
startFrom	Integer	->	Início do índice (incluído)
end	Integer	->	Final do índice (não incluído)
Resultados	collection	<-	Coleção original com valores preenchidos

Descrição

A função .insert() insere elementos no índice posição na instância de coleção e devolve a coleção editada.

Se o parâmetro startFrom for omitido, value é estabelecido para todos os elementos coleção (startFrom=0).
Se end < 0 , é recalculado como sendo end:=end+length.
Se end < startFrom (valores passados ou calculados), o método não faz nada.

Em caso de inconsistências, as regras abaixos são seguidas:

Se index < 0, será recalculado como startFrom:=startFrom+length (é considerado como o offset do final da coleção). Se o valor calculado for negativo, startFrom toma o valor 0.
em $2: param
Se tanto startFrom quanto end forem passados, value é estabelecido para elementos coleção começando em startFrom ao elemento end.

Exemplo

 var $c : Collection
 $c:=New collection(1;2;3;"Lemon";Null;"";4;5)
 $c.fill("2") // $c:=[2,2,2,2,2,2,2,2]
 $c.fill("Hello";5) // $c=[2,2,2,2,2,Hello,Hello,Hello]
 $c.fill(0;1;5) // $c=[2,0,0,0,0,Hello,Hello,Hello]
 $c.fill("world";1;-5) //-5+8=3 -> $c=[2,"world","world",0,0,Hello,Hello,Hello]

.filter()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.find( methodName : Text { ; ...param : any } ) : any
.find( startFrom : Integer ; methodName : Text { ; ...param : any } ) : any

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	any	->	methodName recebe os parâmetros abaixo:
Resultados	Collection	<-	Nova coleção contendo elementos filtrados (cópia superficial)

Descrição

A função .map() devolve uma nova coleção contendo todos os elementos da coleção original para a qual a *fórmula * ou methodName resultado for true. Esta função devolve uma cópia superficial, o que significa que os objectos ou colecções de ambas as colecções partilham a mesma referência. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

Pode determinar a chamada de retorno a ser executada para filtrar os elementos de recolha utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

A chamada de retorno é chamada com o(s) parâmetro(s) passado(s) em param (opcional) e um objecto no primeiro parâmetro ($1). Em methodName, passe o nome do método para usar para avliar elementos collection, junto com os parâmetros em param (opcional).

A chamada de retorno recebe os seguintes parâmetros:

$1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
methodName recebe os parâmetros abaixo:
$N...: param2...paramN

Pode definir o(s) seguinte(s) parâmetro(s):

$1.result (boolean): true se o valor elemento corresponder à condição de pesquisa.
$1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

nota

O código para o método LengthLessThan é:

Exemplo 1

Se quiser obter a coleção de elementos textos cujo tamanho for menor que 6:

var $col;$colNew : Collection
 $col:=New collection("hello";"world";"red horse";66;"tim";"san jose";"miami")
 $colNew:=$col.filter("LengthLessThan";6)
  //$colNew=["hello","world","tim","miami"]

Exemplo 2

Se quiser filtrar elementos de acordo com seu tipo de valor:

 var $c : Collection
 var $c2 : Object
 $c:=New collection
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))
 $c.push(New object("name";"Adger";"zc";35006))
 $c.push(New object("name";"Clanton";"zc";35046))
 $c.push(New object("name";"Clanton";"zc";35045))
 $c2:=$c.find("FindCity";"Clanton") //$c2={name:Clanton,zc:35046}

.find()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

Com o método TypeLookUp:

Parâmetro	Tipo		Descrição
startFrom	Integer	->	Índice onde inicia a pesquisa
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	any	->	methodName recebe os parâmetros abaixo:
Resultados	any	<-	Primeiro valor encontrado ou Undefined se não encontrado

Descrição

A função .indexOf() pesquisa a expressão toSearch entre os elementos da colecção e devolve o índice da primeira ocorrência encontrada, ou -1 se não foi encontrada.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

Em methodName, passe o nome do método para usar para avliar elementos collection, junto com os parâmetros em param (opcional). A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). Este método recebe um Object como primeiro parâmetro ($1) e deve estabelecer $1.result para true para o primeiro elemento que cumprir a condição.

A chamada de retorno recebe os seguintes parâmetros:

$1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
methodName recebe os parâmetros abaixo:
$N...: param2...paramN

Pode definir o(s) seguinte(s) parâmetro(s):

$1.result (boolean): true se o valor elemento corresponder à condição de pesquisa.
$1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Como padrão, .findIndex() testa a coleção completa. Opcionalmente pode passar em startFrom o índice do elemento a partir do qual vai começar a pesquisa.

Se startFrom >= tamanho da coleção, é retornado false, o que significa que a coleção não é pesquisada.
Se startFrom < 0, é considerada como offset do final da coleção (startFrom:=startFrom+length). Nota: Mesmo se startFrom for negativo, a coleção ainda é pesquisada da esquerda para direita.
Se startFrom = 0, a coleção inteira é pesquisada (padrão).

Exemplo 1

Se quiser obter o primeiro elemento com um tamanho menor que 5:

var $1 : Object
 var $2 : Integer
 If(Value type($1.value)=Is text)
    $1.result:=(Length($1.value))<$2
 End if

Exemplo 2

Se quiser encontrar o nome da cidade dentro da coleção:

var $c;$c2;$c3 : Collection
 $c:=New collection(5;3;1;4;6;2)
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))
 $c2:=$c.filter("TypeLookUp";Is real) // $c2=[5,3,1,4,6,2]
 $c3:=$c.filter("TypeLookUp";Is object)
  // $c3=[{name:Cleveland,zc:35049},{name:Blountsville,zc:35031}]

.findIndex()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.findIndex( methodName : Text { ; ...param : any } ) : Integer
.findIndex( startFrom : Integer ; methodName : Text { ; ...param : any } ) : Integer

Parâmetro	Tipo		Descrição
startFrom	Integer	->	Índice onde inicia a pesquisa
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	any	->	methodName recebe os parâmetros abaixo:
Resultados	Integer	<-	Indice do primeiro valor encontrado ou -1 se não encontrado

Descrição

A função .fill() preenche a coleção com o valor especificado **, opcionalmente de startFrom index to end index, e devolve a coleção resultante.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
Parâmetros a passar para methodName

A chamada de retorno recebe os seguintes parâmetros:

$1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
methodName recebe os parâmetros abaixo:
$N...: param2...paramN

Pode definir o(s) seguinte(s) parâmetro(s):

$1.result (boolean): true se o valor elemento corresponder à condição de pesquisa.
$1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Como padrão, .every() testa a coleção completa. Opcionalmente pode passar em startFrom o índice do elemento a partir do qual vai começar a pesquisa.

Se startFrom >= tamanho da coleção, é retornado false, o que significa que a coleção não é pesquisada.
Se startFrom < 0, é considerada como offset do final da coleção (startFrom:=startFrom+length). Nota: Mesmo se startFrom for negativo, a coleção ainda é pesquisada da esquerda para direita.
Se startFrom = 0, a coleção inteira é pesquisada (padrão).

Exemplo

Se quiser encontrar a posição do primeiro nome de cidade dentro da coleção:

var $c : Collection
 var $val2;$val3 : Integer
 $c:=New collection
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))
 $c.push(New object("name";"Adger";"zc";35006))
 $c.push(New object("name";"Clanton";"zc";35046))
 $c.push(New object("name";"Clanton";"zc";35045))
 $val2:=$c.findIndex("FindCity";"Clanton") // $val2=3
 $val3:=$c.findIndex($val2+1;"FindCity";"Clanton") //$val3=4

.first()

Histórico

Release	Mudanças
20	Adicionado

Com o método Flatten:

Parâmetro	Tipo		Descrição
Resultados	any	<-	Primeiro elemento de colecção

Descrição

A função .first() sorts the elements of the original collection.

Nome da função a chamar para filtrar a coleção

Exemplo

var $col : Collection
 $col:=New collection("hello";"world";4;"red horse";"tim";"san jose")
 $value:=$col.find("LengthLessThan";5) //$value="tim"

.flat()

Histórico

Release	Mudanças
20	Adicionado

O código para NumAscending é:

Parâmetro	Tipo		Descrição
depth	Integer	->	A profundidade a que uma estrutura de colecção aninhada deve ser aplanada. O padrão=1
Resultados	Collection	<-	Colecção achatada

Descrição

A função .flat() creates a new collection with all sub-collection elements concatenated into it recursively up to the specified depth.

Por defeito, se o parâmetro depth for omitido, apenas o primeiro nível da estrutura de colecção aninhada será aplanado.

Exemplo

$col:=New collection(1; 2; New collection(3; 4))
$col.flat()
// [1, 2, 3, 4]

$col:=New collection(1; 2; New collection(3; 4; New collection(5; 6)))
$col.flat()
// [1, 2, 3, 4, [5, 6]]

$col:=New collection(1; 2; New collection(3; 4; New collection(5; 6)))
$col.flat(2)
// [1, 2, 3, 4, 5, 6]

$col:=New collection(1; 2; New collection(3; 4; 5; 6; New collection(7; 8; New collection(9; 10))))
$col.flat(MAXLONG)
// [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

.flatMap()

Histórico

Release	Mudanças
20	Adicionado

.map( methodName : Text { ; ...param : any } ) : Collection

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	any	->	methodName recebe os parâmetros abaixo:
Resultados	Collection	<-	Collection of transformed values and flattened by a depth of 1

Descrição

A função .flatMap() cria uma nova colecção com base no resultado da chamada da function 4D formula ou do método methodName em cada elemento da colecção original e achatada com uma profundidade de 1. methodName pode realizar qualquer teste, com ou sem os parâmetros. In methodName, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in param (optional).

Esta função é idêntica a uma chamada map() seguida de uma chamada flat() de profundidade 1.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

A chamada de retorno recebe os seguintes parâmetros:

$1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
methodName recebe os parâmetros abaixo:
$N...: param2...paramN

Pode definir o(s) seguinte(s) parâmetro(s):

$1.result (qualquer tipo): novo valor transformado para adicionar à coleção resultante
$1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Exemplo 1

C_OBJECT($1)
 C_LONGINT($2)
 If(OB Get type($1;"value")=$2)


    $1.result:=True
 End if

Exemplo 2

var $col; $result : Collection
$col:=New collection("Hello how"; ""; "are you ?")

$result:=$col.map(Formula(Split string($1.value; " ")))
// [["Hello", "how"], [], ["are", "you", "?"]]

$result:=$col.flatMap(Formula(Split string($1.value; " ")))
// ["Hello", "how", "are", "you", "?"]

Exemplo 3

Pretende-se calcular a percentagem de cada valor da colecção em relação ao total:

var $c; $c2 : Collection
 $c:=New collection(1;4;9;10;20)
 $c2:=$c.map("Percentage";$c.sum())
  //$c2=[2.27,9.09,20.45,22.73,45.45]

.includes()

Histórico

Release	Mudanças
20	Adicionado

O código para TypeLookUp é:

Parâmetro	Tipo		Descrição
toSearch	expressão	->	Expressão a pesquisar na coleção
startFrom	Integer	->	Índice onde inicia a pesquisa
Resultados	Parâmetros	<-	O código para TypeLookUp é:

Descrição

A função .includes() devolve True se a expressão toSearch for encontrada entre os elementos da colecção; caso contrário, devolve False.

Em toSearch, passe a expressão para encontrar na coleção. Pode passar:

um valor escalar (texto, número, booleano, data),
$1.result:=$1.value>0
um objeto ou uma referência de coleção.

toSearch deve corresponder exatamente com o elemento a encontrar (as mesmas regras que para o operador de igualdade do tipo dados é aplicado).

Opcionalmente pode passar o índice da coleção para a qual iniciar a pesquisa emstartFrom.

Se startFrom >= tamanho da coleção, é retornado false, o que significa que a coleção não é pesquisada.
Se startFrom < 0, é considerada como offset do final da coleção (startFrom:=startFrom+length). Aviso: Lembre que elementos coleção são numerados a partir de 0.
Se startFrom = 0, a coleção inteira é pesquisada (padrão).

Exemplo

 var $c : Collection
 $c:=New collection
 $c.push(New object("name";"Smith";"dateHired";!22-05-2002!;"age";45))
 $c.push(New object("name";"Wesson";"dateHired";!30-11-2017!))
 $c.push(New object("name";"Winch";"dateHired";!16-05-2018!;"age";36))

 $c.push(New object("name";"Sterling";"dateHired";!10-5-1999!;"age";Null))
 $c.push(New object("name";"Mark";"dateHired";!01-01-2002!))

.indexOf()

Histórico

Release	Mudanças
v16 R6	Adicionado

.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer

Parâmetro	Tipo		Descrição
toSearch	expressão	->	Expressão a pesquisar na coleção
startFrom	Integer	->	Índice onde inicia a pesquisa
Resultados	Integer	<-	Índice da primeira ocorrência de toSearch na coleção, -1 se não encontrado

Descrição

A função .find() The .findIndex() function.

Em toSearch, passe a expressão para encontrar na coleção. Pode passar:

um valor escalar (texto, número, booleano, data),
$1.result:=$1.value>0
um objeto ou uma referência de coleção.

toSearch deve corresponder exatamente com o elemento a encontrar (as mesmas regras que para o operador de igualdade do tipo dados é aplicado).

Opcionalmente pode passar o índice da coleção para a qual iniciar a pesquisa emstartFrom.

Se startFrom >= tamanho da coleção, é retornado false, o que significa que a coleção não é pesquisada.
Se startFrom < 0, é considerada como offset do final da coleção (startFrom:=startFrom+length). Nota: Mesmo se startFrom for negativo, a coleção ainda é pesquisada da esquerda para direita.
Se startFrom = 0, a coleção inteira é pesquisada (padrão).

Exemplo

 var $col : Collection
 var $i : Integer
 $col:=New collection(1;2;"Henry";5;3;"Albert";6;4;"Alan";5)
 $i:=$col.indexOf(3) //$i=4
 $i:=$col.indexOf(5;5) //$i=9
 $i:=$col.indexOf("al@") //$i=5
 $i:=$col.indexOf("Hello") //$i=-1

.indices()

Histórico

Release	Mudanças
v16 R6	Adicionado

.indices( queryString : Text { ; ...value : any } ) : Collection

Parâmetro	Tipo		Descrição
queryString	Text	->	Critérios de pesquisa
value	any	->	Valores a comparar quando usar placeholders (valores temporários)
Resultados	Collection	<-	Índices elemento correspondendo a queryString na coleção

Descrição

A função .indices() funciona exactamente da mesma forma que a função .query() mas devolve índices, na coleção original, de elementos da coleção de objectos que correspondem à queryString condições de pesquisae não os elementos em si. Indices são retornados em ordem ascendente.

O parâmetro queryString usa a sintaxe abaixo:

valor de comparação propertyPath {valor de comparação logicalOperator propertyPath}

Para uma descrição detalhada dos parâmetros queryString e value, veja a função dataClass.query().

Exemplo

 var $c; $icol : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))

 $c.push(New object("name";"Adger";"zc";35006))
 $c.push(New object("name";"Clanton";"zc";35046))
 $c.push(New object("name";"Clanton";"zc";35045))
 $icol:=$c.indices("name = :1";"Cleveland") // $icol=[0]
 $icol:=$c.indices("zc > 35040") // $icol=[0,3,4]

.insert()

Histórico

Release	Mudanças
v16 R6	Adicionado

.insert( index : Integer ; element : any ) : Collection

Parâmetro	Tipo		Descrição
index	Integer	->	Onde inserir os elementos
element	any	->	Elemento a inserir na coleção
Resultados	Collection	<-	Collection original contendo elementos inseridos

Descrição

A função .resize() define o comprimento da coleção para o novo tamanho especificado e devolve a coleção redimensionada.

In index, passe a posição onde quiser que o elemento seja inserido na coleção.

Se index > o tamanho da coleção, o índice de início é estabelecido como o tamanho da coleção.
Se index < 0, será recalculado como index:=index+length (é considerado como o offset do final da coleção).
Se o valor calculado for negativo, index será estabelecido como 0.

Qualquer tipo de elemento aceito por uma coleção pode ser inserido, mesmo outra coleção.

Exemplo

 var $col : Collection
 $col:=New collection("a";"b";"c";"d") //$col=["a","b","c","d"]
 $col.insert(2;"X") //$col=["a","b","X","c","d"]
 $col.insert(-2;"Y") //$col=["a","b","X","Y","c","d"]
 $col.insert(-10;"Hi") //$col=["Hi","a","b","X","Y","c","d"]

.join()

Histórico

Release	Mudanças
v16 R6	Adicionado

.join( delimiter : Text { ; option : Integer } ) : Text

Parâmetro	Tipo		Descrição
delimiter	Text	->	Separador a usar entre os elementos
option	Integer	->	`ck ignore null or empty`: ignora strings vazias ou nulls no resultado
Resultados	Text	<-	String contendo todos os elementos da coleção, separados por um delimitador

Descrição

The .unshift() function inserts the given value(s) at the beginning of the collectionand returns the modified collection.

Como padrão, elementos null ou vazios da coleção são retornados na string resultante. Passe a constante ck ignore null or empty na opção option parâmetro se quiser removê-las da string resultado.

Exemplo

 var $c : Collection
 var $t1;$t2 : Text
 $c:=New collection(1;2;3;"Paris";Null;"";4;5)
 $t1:=$c.join("|") //1|2|3|Paris|null||4|5
 $t2:=$c.join("|";ck ignore null or empty) //1|2|3|Paris|4|5

.last()

Histórico

Release	Mudanças
20	Adicionado

O código para WordLength é:

Parâmetro	Tipo		Descrição
Resultados	any	<-	Último elemento da coleção

Descrição

A função .last() devolve o último elemento da colecção.

Nome da função a chamar para filtrar a coleção

Exemplo

var $col : Collection
 var $pos1;$pos2;$pos3;$pos4;$pos5 : Integer
 $col:=Split string("a,b,c,d,e,f,g,h,i,j,e,k,e";",") //$col.length=13
 $pos1:=$col.lastIndexOf("e") //devolve 12
 $pos2:=$col.lastIndexOf("e";6) //devolve 4
 $pos3:=$col.lastIndexOf("e";15) //devolve 12
 $pos4:=$col.lastIndexOf("e";-2) //devolve 10
 $pos5:=$col.lastIndexOf("x") //devolve -1

.lastIndexOf()

Histórico

Release	Mudanças
v16 R6	Adicionado

.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer

Parâmetro	Tipo		Descrição
toSearch	expressão	->	O elemento que é pesquisado dentro da coleção
startFrom	Integer	->	Índice onde inicia a pesquisa
Resultados	Integer	<-	Índice da última ocorrência de toSearch na coleção, -1 se não encontrado

Descrição

A função .lastIndexOf() pesquisa a expressão toSearch entre os elementos da coleção e devolve o índice da última ocorrênciaou -1 se não foi encontrado.

Em toSearch, passe a expressão para encontrar na coleção. Pode passar:

um valor escalar (texto, número, booleano, data),
$1.result:=$1.value>0
um objeto ou uma referência de coleção.

toSearch deve corresponder exactamente ao elemento a procurar (são aplicadas as mesmas regras que para o operador de igualdade).

Opcionalmente pode passar o índice da coleção para a qual iniciar a pesquisa reversa em startFrom.

Se startFrom >= o tamanho da coleção menos um (coll.length-1), a coleção inteira é pesquisada (padrão).
Se index < 0, será recalculado como startFrom:=startFrom+length (é considerado como o offset do final da coleção). Se o valor calculado for negativo, -1 é retornado (a coleção não é pesquisada). Nota: Mesmo se startFrom for negativo, a coleção ainda é pesquisada da direita para esquerda.
Se startFrom = 0, é retornado -1, o que significa que a coleção não é pesquisada.

Exemplo

 var $col : Collection //$col.length inicializa em 0
 $col:=New collection("one";"two";"three") //$col.length atualizado a  3
 $col[4]:="five" //$col.length atualizado a 5
 $vSize:=$col.remove(0;3).length //$vSize=2

.length

Histórico

Release	Mudanças
v16 R5	Adicionado

.length : Integer

Descrição

A propriedade .length devolve o número de elementos da colecção.

A propriedade .length é iniciada quando a coleção for criada. Adicionar ou remover elementos atualiza o tamanho, se necessário. Essa propriedade é read-only /apenas leitura (não pode usá-la para estabelecer o tamanho da coleção).

Exemplo

 $col:=$c.query("dateHired < :1";(Current date-90))
  //$col=[{name:Smith...},{name:Sterling...},{name:Mark...}] if today is 01/10/2018 se hoje for 01/10/2018

.map()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

Aqui está o método sortCollection:

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	any	->	methodName recebe os parâmetros abaixo:
Resultados	Collection	<-	Collection de valores transformados

Descrição

A função .some() cria uma nova colecção com base no resultado da chamada da fórmula ** 4D function ou methodName method em cada elemento da colecção original. methodName pode realizar qualquer teste, com ou sem os parâmetros. In methodName, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in param (optional). .map() always returns a collection with the same size as the original collection, except if $1.stop was used (see below).

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

A chamada de retorno recebe os seguintes parâmetros:

$1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
methodName recebe os parâmetros abaixo:
$N...: param2...paramN

Pode definir o(s) seguinte(s) parâmetro(s):

$1.result (qualquer tipo): novo valor transformado para adicionar à coleção resultante
$1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Exemplo

var $1 : Object
 var $2 : Real
 $1.result:=Round(($1.value/$2)*100;2)

.max()

Histórico

Release	Mudanças
v16 R6	Adicionado

.max( { propertyPath : Text } ) : any

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota de propriedade objeto a ser usado para avaliação
Resultados	Boolean, Text, Number, Collection, Object, Date	<-	Valor máximo na coleção

Descrição

A função .max() devolve o elemento com o maior valor na colecção (o último elemento da colecção como seria classificado em ordem ascendente utilizando a função .sort()``).

shared collection(*) > Diferente de coleções padrão (não partilhadas), coleções partilhadas não são compatíveis com imagens, ponteiros, objetos ou coleções que não são compartilhadas.

Se a coleção conter objetos, pode passar o parâmetro propertyPath para indicar a propriedade objeto cujos valores máximos você quer obter.

Se a coleção estiver vazia, .max() devolve Undefined.

Exemplo

 var $col : Collection
 $col:=New collection(200;150;55)
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Alabama";"salary";10500))
 $max:=$col.max() //{name:Alabama,salary:10500}
 $maxSal:=$col.max("salary") //50000
 $maxName:=$col.max("name") //"Wesson"

.min()

Histórico

Release	Mudanças
v16 R6	Adicionado

.min( { propertyPath : Text } ) : any

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota de propriedade objeto a ser usado para avaliação
Resultados	Boolean, Text, Number, Collection, Object, Date	<-	Valor mínimo na coleção

Descrição

A função .min() devolve o elemento com o menor valor da colecção (o primeiro elemento da colecção como seria classificado em ordem ascendente utilizando a função .sort()``).

Se a coleção conter diferentes tipos de valores, a função .min() devolverá o valor mínimo dentro do primeiro tipo de elemento na ordem da lista de tipos (ver a descrição de .sort()).

Se a coleção conter objetos, pode passar o parâmetro propertyPath para indicar a propriedade objeto cujos valores mínimos você quer obter.

Se a coleção estiver vazia, .min() devolve Undefined.

Exemplo

 var $col : Collection
 $col:=New collection(200;150;55)
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Alabama";"salary";10500))
 $min:=$col.min() //55
 $minSal:=$col.min("salary") //10000
 $minName:=$col.min("name") //"Alabama"

.orderBy()

Histórico

Release	Mudanças
v16 R6	Adicionado

.orderBy( ) : Collection
.orderBy( pathStrings : Text ) : Collection
.orderBy( pathObjects : Collection ) : Collection
.orderBy( ascOrDesc : Integer ) : Collection

Parâmetro	Tipo		Descrição
pathStrings	Text	->	Caminho(s) de propriedade(s) no(s) qual(is) encomendar a coleção
pathObjects	Collection	->	Coleção de objetos criterio
ascOrDesc	Integer	->	`ck ascending` ou `ck descending` (valores escalares)
Resultados	Collection	<-	Cópia ordenada da coleção (cópia superficial)

Descrição

A função .orderBy() devolve uma nova colecção contendo todos os elementos da colecção na ordem especificada.

Esta função devolve uma cópia superficial, o que significa que os objetos ou coleções de ambas coleções compartem a mesma referência. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

If you pass no parameter, the function orders scalar values in the collection in ascending order (other element types such as objects or collections are returned with an internal order). Pode modificar esta ordem automático passando as constantes ck ascending ou ck descending no parâmetro ascOrDesc (ver abaixo).

Também pode passar um parâmetro de critérios para definir como devem ordenar-se os elementos da coleção. Três sintaxes são compatíveis com esse parâmetro:

pathStrings : Text (fórmula). Sintaxe: propertyPath1 {desc or asc}, propertyPath2 {desc or asc},... (ordem predefinida: asc). pathStrings contém uma fórmula composta de 1 a x rotas de propriedades e (opcionalmente) ordens de classificação, separados por vírgulas. A ordem na qual as propriedades são passadas determina a prioridade de ordenação dos elementos da coleção Como padrão as propriedades são ordenadas de forma ascendente. Como padrão as propriedades são ordenadas de forma ascendente. Pode definir a ordem de clasificação de uma propriedade na string de critérios, separado da rota da propriedade por um só espaço: passe "asc" para ordenar em ordem ascendente ou "desc" em ordem descendente.
pathObjects : Collection. Pode adicionar tantos objetos na coleção pathObjects como seja necessário. Como padrão, as propriedades se classificam em ordem ascendente ("descending" é false). Cada elemento da coleção contém um objeto estruturado da seguinte maneira:

{
    "propertyPath": string,
    "descending": boolean
}

ascOrDesc: Integer. Se passar uma das seguintes constantes do tema Objects and collections:

Parâmetros Tipo Valor Comentário
ck ascending Integer 0 Os elementos são ordenados de forma ascendente (por padrão)
ck descending Integer 1 Os elementos são ordenados de forma descendente

Essa sintaxe ordena apenas os valores escalares da coleção (outros tipos de elementos como objetos ou coleções são retornados sem ordenar).

Se a coleção conter elementos de tipos diferentes, são primeiro agrupados por tipo e ordenados depois. Se attributePath levar a uma propriedade de objeto que conter valores de diferentes tipos, primeiro se agrupam por tipo e se ordenam depois.

null
booleans
strings
números
objetos
collections
datas

Exemplo 1

Ordenar uma coleção de números em ordem ascendente e descendente:

 var $c; $c2; $3 : Collection
 $c:=New collection
 For($vCounter;1;10)
    $c.push(Random)
 End for
 $c2:=$c.orderBy(ck ascending)
 $c3:=$c.orderBy(ck descending)

Exemplo 2

Ordenar uma coleção de objetos a partir de uma fórmula de texto com nomes de propriedades:

 var $c; $c2 : Collection
 $c:=New collection
 For($vCounter;1;10)
    $c.push(New object("id";$vCounter;"value";Random))
 End for
 $c2:=$c.orderBy("value desc")
 $c2:=$c.orderBy("value desc, id")
 $c2:=$c.orderBy("value desc, id asc")

Ordenar uma coleção de objetos com uma rota de propriedades:

 var $c; $c2 : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))
 $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))

 $c2:=$c.orderBy("phones.p1 asc")

Exemplo 3

Ordenar uma coleção de objetos utilizando uma coleção de objetos critério:

 var $crit; $c; $c2 : COllection
 $crit:=New collection
 $c:=New collection
 For($vCounter;1;10)
    $c.push(New object("id";$vCounter;"value";Random))
 End for
 $crit.push(New object("propertyPath";"value";"descending";True))
 $crit.push(New object("propertyPath";"id";"descending";False))
 $c2:=$c.orderBy($crit)

Ordenar com uma rota de propriedade:

 var $crit; $c; $c2 : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"phones";New object("p1";"01";"p2";"02")))
 $c.push(New object("name";"Blountsville";"phones";New object("p1";"00";"p2";"03")))
 $crit:=New collection(New object("propertyPath";"phones.p2";"descending";True))
 $c2:=$c.orderBy($crit)

.orderByMethod()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
extraParam	any	->	Parâmetro(s) a transmitir
Resultados	Collection	<-	Cópia ordenada da coleção (cópia superficial)

Descrição

A função .orderBy() devolve uma nova coleção contendo todos os elementos da coleção na ordem definida através da função 4D formula ou método methodName.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

Em methodName, passe um método de comparação que compare dois valores e devolva true em $1.result se o primeiro valor for menor que o segundo. Pode fornecer parâmetros adicionais a methodName se for necessário.

A chamada de retorno recebe os seguintes parâmetros:

$1 (objeto), onde:
- em $1.value (qualquer tipo): primeiro elemento a ser comparado
- em $1.value2 (qualquer tipo): segundo elemento a ser comparado
- $2...$N (qualquer tipo): parâmetros adicionais

Se utilizou um método, este deve definir o seguinte parâmetro:

$1.result (boolean): true se $1.value < $1.value2, false do contrário

Exemplo 1

Se quiser ordenar a coleção de strings em ordem numérica ao invés de ordem alfabética:

 var $c; $c2; $c3 : Collection
 $c:=New collection
 $c.push("33";"4";"1111";"222")
 $c2:=$c.orderBy() //$c2=["1111","222","33","4"], alphabetical order
 $c3:=$c.orderByMethod("NumAscending") // $c3=["4","33","222","1111"]

Exemplo 2

Se quiser ordenar a coleção de strings de acordo com seu tamanho:

 $1.result:=Length(String($1.value))>Length(String($1.value2))

Exemplo 3

Se quiser ordenar a coleção por código de caractere ou alfabeticamente:

var $fruits; $c2 : Collection
 $fruits:=New collection("Orange";"Apple";"Grape";"pear";"Banana";"fig";"Blackberry";"Passion fruit")
 $c2:=$fruits.orderByMethod("WordLength")
  //$c2=[Passion fruit,Blackberry,Orange,Banana,Apple,Grape,pear,fig]

Com o método Multiply:

var$1Object
var$2Integer // sort option

$1.result:=(Compare strings($1.value;$1.value2;$2)<0)

.pop()

Histórico

Release	Mudanças
v16 R6	Adicionado

.pop() : any

Parâmetro	Tipo		Descrição
Resultados	any	<-	Último elemento da coleção

Descrição

A função .pop() remove o primeiro elemento da coleção e devolve-o como resultado da função.

Quando for aplicado a uma coleção vazia, .pop() devolve undefined.

Exemplo

.pop(), utilizado junto com .push(), pode ser utilizado para implementar uma funcionalidade primeira entrada, última saída de tratamento de dados empilhados:

 var $stack : Collection
 $stack:=New collection //$stack=[]
 $stack.push(1;2) //$stack=[1,2]
 $stack.pop() //$stack=[1]  Returns 2
 $stack.push(New collection(4;5)) //$stack=[[1,[4,5]]
 $stack.pop() //$stack=[1]  Returns [4,5]
 $stack.pop() //$stack=[]  Returns 1

.push()

Histórico

Release	Mudanças
v16 R6	Adicionado

.push( element : any { ;...elementN } ) : Collection

Parâmetro	Tipo		Descrição
element	Mixed	->	Elementos a adicionar à coleção
Resultados	Collection	<-	Collection original contendo elementos inseridos

Descrição

A função .find() The .indexOf() function.

Exemplo 1

 var $col : Collection
 $col:=New collection(1;2) //$col=[1,2]
 $col.push(3) //$col=[1,2,3]
 $col.push(6;New object("firstname";"John";"lastname";"Smith"))
  //$col=[1,2,3,6,{firstname:John,lastname:Smith}

Exemplo 2

Você deseja ordenar a coleção resultante:

 var $col; $sortedCol : Collection
 $col:=New collection(5;3;9) //$col=[5,3,9]
 $sortedCol:=$col.push(7;50).sort()
  //$col=[5,3,9,7,50]
  //$sortedCol=[3,5,7,9,50]

.query()

Histórico

Release	Mudanças
17 R5	Assistência de querySettings
v16 R6	Adicionado

.query( queryString : Text ; ...value : any ) : Collection
.query( queryString : Text ; querySettings : Object ) : Collection

Parâmetro	Tipo		Descrição
queryString	Text	->	Critérios de pesquisa
value	Mixed	->	Valores a comparar quando usar placeholders (valores temporários)
querySettings	Object	->	Opções de pesquisa: parâmetros, atributos
Resultados	Collection	<-	Elementos que correspondem com queryString na coleção

Descrição

A função .query() devolve todos os elementos de uma coleção de objectos que correspondem às condições de pesquisa defined by queryString and (optionally) value or querySettings. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

O parâmetro queryString usa a sintaxe abaixo:

valor de comparação propertyPath {valor de comparação logicalOperator propertyPath}

Para obter informação detalhada sobre como construir uma consulta utilizando os parâmetros queryString, value e querySettings, consulte a descrição da função dataClass.query().

Exemplo 1

 var $c; $c2; $c3 : Collection
 $c:=New collection
 $c.push(New object("name";"Cleveland";"zc";35049))
 $c.push(New object("name";"Blountsville";"zc";35031))
 $c.push(New object("name";"Adger";"zc";35006))
 $c.push(New object("name";"Clanton";"zc";35046))
 $c.push(New object("name";"Clanton";"zc";35045))
 $c2:=$c.query("name = :1";"Cleveland") //$c2=[{name:Cleveland,zc:35049}]
 $c3:=$c.query("zc > 35040") //$c3=[{name:Cleveland,zc:35049},{name:Clanton,zc:35046},{name:Clanton,zc:35045}]

Exemplo 2

 var $c : Collection
 $c:=New collection
 $c.push(New object("name";"Smith";"dateHired";!22-05-2002!;"age";45))
 $c.push(New object("name";"Wesson";"dateHired";!30-11-2017!))
 $c.push(New object("name";"Winch";"dateHired";!16-05-2018!;"age";36))

 $c.push(New object("name";"Sterling";"dateHired";!10-5-1999!;"age";Null))
 $c.push(New object("name";"Mark";"dateHired";!01-01-2002!))

Este exemplo devolve as pessoas cujo nome contém "in":

 $col:=$c.query("name = :1";"@in@")
  //$col=[{name:Winch...},{name:Sterling...}]

Este exemplo devolve as pessoas cujo nome não começa por uma string de uma variável (introduzida pelo usuário, por exemplo):

 $col:=$c.query("name # :1";$aString+"@")
  //if $astring="W"
  //$col=[{name:Smith...},{name:Sterling...},{name:Mark...}]

Este exemplo devolve as pessoas cuja idade não se conhece (propriedade definida como null ou indefinida):

 $col:=$c.query("age=null") //não são permitidos placeholders ou marcadores de posição com "null"
  //$col=[{name:Wesson...},{name:Sterling...},{name:Mark...}]

Este exemplo devolve as pessoas contratadas há mais de 90 dias:

 $col:=$c.query("dateHired < :1";(Current date-90))
  //$col=[{name:Smith...},{name:Sterling...},{name:Mark...}] se hoje é 01/10/2018

Exemplo 3

Mais exemplos de pesquisas podem ser encontrados na página dataClass.query().

.reduce()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.reduce( methodName : Text ) : any
.reduce( methodName : Text ; initValue : any { ; ...param : expression } ) : any

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
initValue	Text, Number, Object, Collection, Date, Boolean	->	Valor a utilizar como primeiro argumento da primeira chamada de methodName
param	expressão	->	Parâmetro(s) a transmitir
Resultados	Text, Number, Object, Collection, Date, Boolean	<-	Resultado do valor do acumulador

Descrição

A função .reduce() The .reduce() function.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

var $1 : Object var $2 : Text $1.result:=$1.value.name=$2

Pode passar o valor para inicializar o acumulador em initValue. Se omitido, $1.accumulator> começa com Undefined.

A chamada de retorno recebe os seguintes parâmetros:

With the following NumberGreaterThan0 method:
em $2: param
methodName estabelece os parâmetros abaixo:

A chamada de retorno recebe os seguintes parâmetros:

$1.result:=$1.value>0
$1.stop (boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Exemplo 1

C_COLLECTION($c)
 $c:=New collection(5;3;5;1;3;4;4;6;2;2)
 $r:=$c.reduce("Multiply";1) //returns 86400

Exemplo 2

Este exemplo permite reduzir vários elementos da coleção a um só:

 var $c : Collection
 $c:=New collection
 $c.push(New object("name";"Smith";"dateHired";!22-05-2002!;"age";45))
 $c.push(New object("name";"Wesson";"dateHired";!30-11-2017!))
 $c.push(New object("name";"Winch";"dateHired";!16-05-2018!;"age";36))

 $c.push(New object("name";"Sterling";"dateHired";!10-5-1999!;"age";Null))
 $c.push(New object("name";"Mark";"dateHired";!01-01-2002!))

methodName estabelece os parâmetros abaixo:

 If($1.accumulator=Null)
    $1.accumulator:=New collection
 End if
 $1.accumulator.combine($1.value)

.reduceRight()

Histórico

Release	Mudanças
20	Adicionado

O código para o método FindCity é:

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
initValue	Text, Number, Object, Collection, Date, Boolean	->	Valor a utilizar como primeiro argumento da primeira chamada de methodName
param	expressão	->	Parâmetro(s) a transmitir
Resultados	Text, Number, Object, Collection, Date, Boolean	<-	Resultado do valor do acumulador

Descrição

A função .reduceRight() aplica a *formula * ou methodName callback a um acumulador e a cada elemento da colecção (da direita para a esquerda) para o reduzir a um único valor.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

var $1 : Object var $2 : Text $1.result:=$1.value.name=$2

Pode passar o valor para inicializar o acumulador em initValue. Se omitido, $1.accumulator> começa com Undefined.

A chamada de retorno recebe os seguintes parâmetros:

With the following NumberGreaterThan0 method:
em $2: param
methodName estabelece os parâmetros abaixo:

A chamada de retorno recebe os seguintes parâmetros:

$1.result:=$1.value>0
$1.stop (boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Exemplo 1

//numberOrder project method
 var $1 : Object
 $1.result:=String($1.value)<String($1.value2)

Exemplo 2

Este exemplo permite reduzir vários elementos da coleção a um só:

 var $c;$r : Collection
 $c:=New collection
 $c.push(New collection(0;1))
 $c.push(New collection(2;3))
 $c.push(New collection(4;5))
 $c.push(New collection(6;7))
 $r:=$c.reduce("Flatten") //$r=[0,1,2,3,4,5,6,7]

methodName estabelece os parâmetros abaixo:

    If(Value type($1.value)=Is real)
    $1.accumulator:=$1.accumulator*$1.value
 End if

.remove()

Histórico

Release	Mudanças
v16 R6	Adicionado

.remove( index : Integer { ; howMany : Integer } ) : Collection

Parâmetro	Tipo		Descrição
index	Integer	->	Elemento no qual que se inicia a eliminação
howMany	Integer	->	Número de elementos a eliminar, ou 1 elemento se omitir
Resultados	Collection	<-	Modified collection without removed element(s)

Descrição

A função .remove() insere elementos no índice posição na instância de coleção e devolve a coleção editada.

Em index, passe a posição onde deseja que o elemento seja retirado da colecção.

Se index < 0, será recalculado como index:=index+length (é considerado como o offset do final da coleção).
Se o valor calculado < 0, index será estabelecido como 0.
Se o valor calculado > o comprimento da colecção, índice é definido para o comprimento.

Em howMany, passe o número de elementos a remover do índice **. Se howMany não for especificado, então um elemento é removido.

Se tentar remover um elemento de uma coleção vazia, o método não faz nada (não é gerado qualquer erro).

Exemplo

 var $col : Collection
 $col:=New collection("a";"b";"c";"d";"e";"f";"g";"h")
 $col.remove(3) // $col=["a","b","c","e","f","g","h"]
 $col.remove(3;2) // $col=["a","b","c","g","h"]
 $col.remove(-8;1) // $col=["b","c","g","h"]
 $col.remove(-3;1) // $col=["b","g","h"]

.resize()

Histórico

Release	Mudanças
v16 R6	Adicionado

.resize( size : Integer { ; defaultValue : any } ) : Collection

Parâmetro	Tipo		Descrição
size	Integer	->	Nova dimensão da colecção
defaultValue	Number, Text, Object, Collection, Date, Boolean	->	Valor padrão para preencher novos elementos
Resultados	Collection	<-	Colecção original redimensionada

Descrição

A função .resize() define o comprimento da coleção para o novo tamanho especificado e devolve a coleção redimensionada.

Se tamanho < comprimento da colecção, os elementos excedentes são removidos da colecção.
Se tamanho > comprimento da colecção, o comprimento da colecção é aumentado à medida.

Por padrão, são preenchidos novos elementos null valores. Pode especificar o valor para preencher os elementos adicionados usando o parâmetro defaultValue .

Exemplo

 var $c : Collection
 $c:=New collection
 $c.resize(10) // $c=[null,null,null,null,null,null,null,null,null,null]

 $c:=New collection
 $c.resize(10;0) // $c=[0,0,0,0,0,0,0,0,0,0]

 $c:=New collection(1;2;3;4;5)
 $c.resize(10;New object("name";"X")) //$c=[1,2,3,4,5,{name:X},{name:X},{name:X},{name:X},{name:X}]

 $c:=New collection(1;2;3;4;5)
 $c.resize(2) //$c=[1,2]

.reverse()

Histórico

Release	Mudanças
v16 R6	Adicionado

.reverse( ): Collection

Parâmetro	Tipo		Descrição
Resultados	Collection	<-	Cópia invertida da colecção

Descrição

A função .reverse() devolve uma cópia profunda da colecção com todos os seus elementos em ordem inversa. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

Exemplo

 C_OBJECT($1)
 C_LONGINT($2)
 If(Value type($1.value)=Is text)
    $1.result:=(Length($1.value))<$2
 End if

.shift()

Histórico

Release	Mudanças
v16 R6	Adicionado

.shift() : any

Parâmetro	Tipo		Descrição
Resultados	any	<-	Primeiro elemento de colecção

Descrição

A função .shift() remove o primeiro elemento da colecção e devolve-o como resultado da função.

Se a colecção estiver vazia, este método não faz nada.

Exemplo

 var $c : Collection
 var $val : Variant
 $c:=New collection(1;2;4;5;6;7;8)
 $val:=$c.shift()
  // $val=1
  // $c=[2,4,5,6,7,8]

.slice()

Histórico

Release	Mudanças
v16 R6	Adicionado

.slice( startFrom : Integer { ; end : Integer } ) : Collection

Parâmetro	Tipo		Descrição
startFrom	Integer	->	Início do índice (incluído)
end	Integer	->	Final do índice (não incluído)
Resultados	Collection	<-	Nova colecção contendo elementos cortados (cópia superficial)

Descrição

A função .slice() devolve uma parte de uma colecção para uma nova colecção, selected from startFrom index to end index (end not included). Esta função devolve uma cópia superficial da colecção. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

A colecção devolvida contém o elemento especificado por startFrom e todos os elementos subsequentes até, mas não incluindo, o elemento especificado por end. Se apenas for especificado o parâmetro startFrom , a colecção devolvida contém todos os elementos desde startFrom até ao último elemento da colecção original.

Se index < 0, será recalculado como startFrom:=startFrom+length (é considerado como o offset do final da coleção).
Se o valor calculado < 0, index será estabelecido como 0.
em $2: param
Se end < startFrom (valores passados ou calculados), o método não faz nada.

Exemplo

 var $c; $nc : Collection
 $c:=New collection(1;2;3;4;5)
 $nc:=$c.slice(0;3) //$nc=[1,2,3]
 $nc:=$c.slice(3) //$nc=[4,5]
 $nc:=$c.slice(1;-1) //$nc=[2,3,4]
 $nc:=$c.slice(-3;-2) //$nc=[3]

.some()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.some( methodName : Text { ; ...param : any } ) : Boolean
.some( startFrom : Integer ; methodName : Text { ; ...param : any } ) : Boolean

Parâmetro	Tipo		Descrição
startFrom	Integer	->	Índice para início do teste em
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
param	Mixed	->	Parâmetro(s) a transmitir
Resultados	Parâmetros	<-	True se todos os elementos passarem o teste com sucesso

Descrição

A função .push() anexa um ou mais elementos(s) ao final da instância de recolha e devolve a coleção editada.

Designa-se a chamada de retorno a ser executada para avaliar os elementos da colecção utilizando qualquer um dos dois:

fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
methodName estabelece os parâmetros abaixo:

A chamada de retorno recebe os seguintes parâmetros:

With the following NumberGreaterThan0 method:
em $2: param
methodName estabelece os parâmetros abaixo:

Pode definir o(s) seguinte(s) parâmetro(s):

$1.result (boolean): true if the element value evaluation is successful, false otherwise.
$1.stop (boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

In any case, at the point where .some() function encounters the first collection element returning true in $1.result, it stops calling methodName and returns true.

Como padrão, .some() testa toda a colecção. Opcionalmente pode passar o índice da coleção para a qual iniciar a pesquisa emstartFrom.

Se startFrom >= tamanho da coleção, é retornado false, o que significa que a coleção não é testada.
Se startFrom < 0, é considerado como a compensação a partir do final da recolha.
Se startFrom = 0, a coleção inteira é pesquisada (padrão).

Exemplo

Quer saber se pelo menos um valor de colecção é >0.

 var $c : Collection
 var $b : Boolean
 $c:=New collection
 $c.push(-5;-3;-1;-4;-6;-2)
 $b:=$c.some("NumberGreaterThan0") // returns false
 $c.push(1)
 $b:=$c.some("NumberGreaterThan0") // returns true

 $c:=New collection
 $c.push(1;-5;-3;-1;-4;-6;-2)
 $b:=$c.some("NumberGreaterThan0") //$b=true
 $b:=$c.some(1;"NumberGreaterThan0") //$b=false

.sort()

Histórico

Release	Mudanças
19 R6	Compatibilidade de fórmula
v16 R6	Adicionado

.sort() : Collection
.sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection
.sort( methodName : Text { ; ...extraParam : any } ) : Collection

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
methodName	Text	->	Nome da função a qual se chama para processar os elementos da coleção
extraParam	any	->	Parâmetros para o método
Resultados	Collection	<-	Colecção original ordenada

Descrição

A função .shift() remove o primeiro elemento da colecção e devolve-o como resultado da função .

Se .sort() for chamado sem parâmetros, apenas valores escalares (número, texto, data, booleanos) são ordenados. Os elementos são classificados por defeito em ordem ascendente, de acordo com o seu tipo. If the collection contains scalar values of different types, they are first grouped by type and sorted afterwards. Se attributePath levar a uma propriedade de objeto que conter valores de diferentes tipos, primeiro se agrupam por tipo e se ordenam depois.

null
booleans
strings
números
objetos
collections
datas

Se pretender ordenar os elementos da coleção por outra ordem ou ordenar qualquer tipo de elemento, deve fornecer em formula (object Formula) ou methodName (Text) uma chamada de retorno que defina a ordem de ordenação. O valor de retorno deve ser um booleano que indica a ordem relativa dos dois elementos: True se $1.value for menor que $1.value2, False se $1.value for maior que $1.value2. Pode fornecer parâmetros adicionais a methodName se for necessário.

A chamada de retorno recebe os seguintes parâmetros:

$1 (objeto), onde:
- em $1.value (qualquer tipo): primeiro elemento a ser comparado
- em $1.value2 (qualquer tipo): segundo elemento a ser comparado
$2...$N (qualquer tipo): parâmetros adicionais

Se utilizou um método, deve definir o seguinte parâmetro:

$1.result (boolean): True if $1.value < $1.value2, False do contrário.

Exemplo 1

 var $col; $col2 : Collection
 $col:=New collection("Tom";5;"Mary";3;"Henry";1;"Jane";4;"Artie";6;"Chip";2)
 $col2:=$col.sort() // $col2=["Artie","Chip","Henry","Jane","Mary","Tom",1,2,3,4,5,6]
  // $col=["Artie","Chip","Henry","Jane","Mary","Tom",1,2,3,4,5,6]

Exemplo 2

 var $col; $col2 : Collection
 $col:=New collection(10;20)
 $col2:=$col.push(5;3;1;4;6;2).sort() //$col2=[1,2,3,4,5,6,10,20]

Exemplo 3

var $strings1; $strings2 : Collection
$strings1:=New collection("Alpha";"Charlie";"alpha";"bravo";"Bravo";"charlie")

//using the character code:
$strings2:=$strings1.orderByMethod("sortCollection";sk character codes)
// result : ["Alpha","Bravo","Charlie","alpha","bravo","charlie"]

//using the language:
$strings2:=$strings1.orderByMethod("sortCollection";sk strict)
// result : ["alpha","Alpha","bravo","Bravo","charlie","Charlie"]

.sum()

Histórico

Release	Mudanças
v16 R6	Adicionado

.sum( { propertyPath : Text } ) : Real

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota de propriedade objeto a ser usado para cálculos
Resultados	Real	<-	Soma dos valores da colecção

Descrição

A função .sum() devolve a soma para todos os valores na instância da coleção.

Apenas elementos numéricos são considerados para cálculos (outros tipos são ignorados).

Se a coleção contiver objetos, passe o parâmetro propertyPath para indicar a propriedade objeto para levar em consideração.

.sum() retorna 0 se:

a coleção estiver vazia,
a coleção não contiver elementos numéricos,
propertyPath não for encontrada na collection.

Exemplo 1

 var $col; $col2; $col3 : Collection
 $col:=New collection(33;4;66;1111;222)
 $col2:=$col.sort() //numerical sort: [4,33,66,222,1111]
 $col3:=$col.sort("numberOrder") //alphabetical sort: [1111,222,33,4,66]

Exemplo 2

 var $col : Collection
 var $vSum : Real
 $col:=New collection
 $col.push(New object("name";"Smith";"salary";10000))
 $col.push(New object("name";"Wesson";"salary";50000))
 $col.push(New object("name";"Gross";"salary";10500,5))
 $vSum:=$col.sum("salary") //$vSum=70500,5

.unshift()

Histórico

Release	Mudanças
v16 R6	Adicionado

.unshift( value : any { ;...valueN : any } ) : Collection

Parâmetro	Tipo		Descrição
value	Text, Number, Object, Collection, Date	->	Valor(es) a inserir no início da colecção
Resultados	Real	<-	Colecção contendo elemento(s) adicionado(s)

| | | |

Descrição

A função .unshift() insere o valor dado no início da coleção e devolve a coleção modificada.

Se vários valores forem passados, são inseridos todos ao mesmo tempo, o que significa que aparecem na colecção resultante na mesma ordem que na lista de argumentos.

Exemplo

 var $c : Collection
 $c:=New collection(1;2)
 $c.unshift(4) // $c=[4,1,2]
 $c.unshift(5) //$c=[5,4,1,2]
 $c.unshift(6;7) // $c=[6,7,5,4,1,2]

Parâmetros	Tipo	Valor	Comentário
ck ascending	Integer	0	Os elementos são ordenados de forma ascendente (por padrão)
ck descending	Integer	1	Os elementos são ordenados de forma descendente

Exemplo​

Resumo​

Nova coleção​

Descrição​

Exemplo 1​

Exemplo 2​

Exemplo 3​

New shared collection​

Descrição​

Exemplo​

.at()​

Descrição​

Exemplo​

.average()​

Descrição​

Exemplo 1​

Exemplo 2​

.clear()​

Descrição​

Exemplo​

.combine()​

Descrição​

Exemplo​

.concat()​

Descrição​

Exemplo​

.copy()​

Descrição​

Exemplo 1​

Exemplo 2​

Exemplo 3​

Exemplo​

.count()​

Descrição​

Exemplo​

.countValues()​

Descrição​

Exemplo 1​

Exemplo 2​

Exemplo 3​

.distinct()​

Descrição​

Exemplos​

.equal()​

Descrição​

Exemplo​

.every()​

Descrição​

Exemplo 1​

Exemplo 2​

.extract()​

Descrição​

Exemplo 1​

Exemplo 2​

.fill()​

Descrição​

Exemplo​

.filter()​

Descrição​

Exemplo 1​

Exemplo 2​

.find()​

Descrição​

Exemplo 1​

Exemplo 2​

.findIndex()​

Descrição​

Exemplo​

.first()​

Descrição​

Exemplo​

.flat()​

Descrição​

Exemplo​

.flatMap()​

Descrição​

Exemplo 1​

Exemplo 2​

Exemplo 3​

.includes()​

Exemplo

Resumo

`Nova coleção`

Descrição

Exemplo 1

Exemplo 2

Exemplo 3

`New shared collection`

Descrição

Exemplo

.at()

Descrição

Exemplo

.average()

Descrição

Exemplo 1

Exemplo 2

.clear()

Descrição

Exemplo

.combine()

Descrição

Exemplo

.concat()

Descrição

Exemplo

.copy()

Descrição

Exemplo 1

Exemplo 2

Exemplo 3

Exemplo

.count()

Descrição

Exemplo

.countValues()

Descrição

Exemplo 1

Exemplo 2

Exemplo 3

.distinct()

Descrição

Exemplos

.equal()

Descrição

Exemplo

.every()

Descrição

Exemplo 1

Exemplo 2

.extract()

Descrição

Exemplo 1

Exemplo 2

.fill()

Descrição

Exemplo

.filter()

Descrição

Exemplo 1

Exemplo 2

.find()

Descrição

Exemplo 1

Exemplo 2

.findIndex()

Descrição

Exemplo

.first()

Descrição

Exemplo

.flat()

Descrição

Exemplo

.flatMap()

Descrição

Exemplo 1

Exemplo 2

Exemplo 3

.includes()