Versão: 20 R6

Collection

A classe Collection gerencia variáveis do tipo Collection.

Uma coleção se inicializa com:


New collection {( ...value : any )} : Collection cria uma nova coleção vazia ou pré-preenchida
New shared collection {( ...value : any )} : Collection cria uma nova coleção compartilhada vazia ou pré-preenchida

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


.at( index : Integer ) : any retorna o item na posição index, permitindo o uso de números inteiros positivos e negativos
.average( {propertyPath : Text } ) : Real retorna a média aritmética (média) dos valores definidos na instância de coleção
.clear() : Collection remove todos os elementos da instância da coleção e retorna uma coleção vazia
.combine( col2 : Collection {; index : Integer } ) : Collection insere col2 elementos no final ou na posição index especificada na instância da coleção e retorna a coleção editada
.concat( value : any { ;...valueN } ) : Collection retorna uma nova coleção contendo os elementos da coleção original com todos os elementos do parâmetro value adicionados ao final
.copy() : Collection .copy( option : Integer ) : Collection .copy( option : Integer ; groupWithCol : Collection ) : Collection .copy( option : Integer ; groupWithObj : Object ) : Collection retorna uma cópia profunda da instância da coleção
.count( { propertyPath : Text } ) : Real retorna o número de elementos não nulos na coleção
.countValues( value : any {; propertyPath : Text } ) : Real retorna o número de vezes que o valor é encontrado na coleção
.distinct( {options : Integer} ) : Collection .distinct( propertyPath : Text {; options : Integer } ) : Collection retorna uma coleção que contém apenas valores distintos (diferentes) da coleção original
.equal( collection2 : Collection {; option : Integer } ) : Boolean compara recursivamente os conteúdos da coleção e da coleção2 (comparação profunda)
.every( { startFrom : Integer ; } formula : 4D.Function { ;...param : any } ) : Boolean .every( { startFrom : Integer ; } methodName : Text { ;...param : any } ) : Boolean retorna true se todos os elementos da coleção passarem com sucesso em um teste implementado no objeto formula ou método methodName fornecido
.extract( propertyPath : Text { ; option : Integer } ) : Collection .extract( propertyPath : Text ; targetPath : Text { ;...propertyPathOrTargetPathN : Text } ) : Collection cria e retorna uma nova coleção contendo valores propertyPath extraídos da coleção original de objetos
.fill( value : any ) : Collection .fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection preenche a coleção com o value especificado, opcionalmente do índice startFrom até o índice end, e retorna a coleção resultante
.filter( formula : 4D.Function { ; ...param : any } ) : Collection .filter( methodName : Text { ; ...param : any } ) : Collection retorna uma nova coleção contendo todos os elementos da coleção original para os quais o resultado da formula ou do methodName é true
.find( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : any .find( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : any retorna o primeiro valor na coleção para o qual o formula ou o resultado do methodName, aplicado a cada elemento, seja true
.findIndex( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Integer .findIndex( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Integer retorna o índice, na coleção, do primeiro valor para o qual a formula ou o methodName, aplicado em cada elemento, retorna true
.first() : any retorna o primeiro elemento da coleção
.flat( { depth : Integer } ) : Collection cria uma nova coleção com todos os elementos da subcoleção concatenados recursivamente até a depth
.flatMap( formula : 4D.Function { ; ...param : any } ) : Collection .flatMap( methodName : Text { ; ...param : any } ) : Collection cria uma nova coleção com base no resultado da chamada da formula da função 4D ou do método methodName em cada elemento da coleção original e aplanada por uma profundidade de 1
.includes( toSearch : expression { ; startFrom : Integer } ) : Boolean retorna True se a expressão toSearch for encontrada entre os elementos da coleção, caso contrário False
.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer procura a expressão toSearch entre os elementos da coleção e retorna o índice da primeira ocorrência encontrada, ou -1 se não for encontrada
.indices( queryString : Text { ; ...value : any } ) : Collection retorna os índices, na coleção original, dos elementos da coleção de objetos que correspondem às condições de busca queryString
.insert( index : Integer ; element : any ) : Collection insere element na posição index especificada na instância da coleção e retorna a coleção editada
.join( delimiter : Text { ; option : Integer } ) : Text converte todos os elementos da coleção em strings e os concatena usando a string delimitadora especificada como separador
.last() : any retorna o último elemento da coleção
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer pesquisa a expressão toSearch entre os elementos da coleção e retorna o índice da última ocorrência
.length : Integer retorna o número de elementos na coleção
.new( { ...param : any } ) : 4D.Class cria e retorna um objeto `cs.className` que é uma nova instância da classe na qual ela é chamada
.max( { propertyPath : Text } ) : any retorna o elemento com o valor mais alto na coleção
.min( { propertyPath : Text } ) : any retorna o elemento com o menor valor na coleção
.multiSort() : Collection .multiSort( colsToSort : Collection ) : Collection .multiSort( formula : 4D.Function ; colsToSort : Collection ) : Collection permite que você execute uma classificação sincronizada em vários níveis em um conjunto de coleções
.orderBy( ) : Collection .orderBy( pathStrings : Text ) : Collection .orderBy( pathObjects : Collection ) : Collection .orderBy( ascOrDesc : Integer ) : Collection retorna uma nova coleção contendo todos os elementos da coleção na ordem especificada
.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection .orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection retorna uma nova coleção contendo todos os elementos da coleção na ordem definida por meio da função formula 4D ou do método methodName
.pop() : any remove o último elemento da coleção e o retorna como o resultado da função
.push( element : any { ;...elementN } ) : Collection acrescenta um ou mais elementos ao final da instância da coleção e retorna a coleção editada
.query( queryString : Text ) : Collection .query( queryString : Text ; ...value : any ) : Collection .query( queryString : Text ; querySettings : Object ) : Collection retorna todos os elementos de uma coleção de objetos que correspondem às condições de pesquisa
.reduce( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any aplica a chamada de retorno formula ou methodName em um acumulador e em cada elemento da coleção (da esquerda para a direita) para reduzi-lo a um único valor
.reduceRight( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any .reduceRight( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any aplica a chamada de retorno formula ou methodName em um acumulador e em cada elemento da coleção (da direita para a esquerda) para reduzi-lo a um único valor
.remove( index : Integer { ; howMany : Integer } ) : Collection
.resize( size : Integer { ; defaultValue : any } ) : Collection sets the collection length to the specified new size and returns the resized collection
.reverse( ) : Collection returns a deep copy of the collection with all its elements in reverse order
.shift() : any removes the first element of the collection and returns it as the function result
.slice( startFrom : Integer { ; end : Integer } ) : Collection retorna uma parte de uma coleção em uma nova coleção
.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean .some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean retorna true se pelo menos um elemento da coleção passar com êxito em um teste implementado no código formula ou methodName fornecido
.sort() : Collection .sort( formula : 4D.Function { ; ...extraParam : any } ) : Collection .sort( methodName : Text { ; ...extraParam : any } ) : Collection sorts the elements of the original collection and also returns the sorted collection
.sum( { propertyPath : Text } ) : Real returns the sum for all values in the collection instance
.unshift( value : any { ;...valueN : any } ) : Collection insere o(s) *valu(es) fornecido(s) no início da coleção

`New collection`

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	<-	Nova coleção

Descrição

O comando New collection cria uma nova coleção vazia ou pré-preenchida e retorna 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 índice do novo elemento estiver além do último elemento existente da coleção, a coleção será redimensionada automaticamente e todos os novos elementos intermediários receberão um valor nulo.

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 você passar um ponteiro, ele será mantido "como está"; ele será 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 valor 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ória

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 coleção compartilhada vazia ou pré-preenchida e retorna 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 obter mais informações sobre coleções compartilhadas, consulte a página Objetos e coleções compartilhadas.

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 value como 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 valor null.

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ória

Release	Mudanças
20	Adicionado

.at( index : Integer ) : any

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

Descrição

A função .at() retorna o item na posição index, permitindo o uso de números inteiros positivos e negativos.

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

A função retorna Indefinido se index estiver além dos limites da coleção.

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ória

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 (média) 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ória

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 da coleção e retorna uma coleção vazia.

Exemplo

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

.combine()

História

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 na posição index especificada na instância da coleção e retorna a coleçã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 da coleção.

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

Se index > o comprimento da coleção, o index inicial real será definido como o comprimento da coleção.
Se index < 0, ele será recalculado como index:=index+length (ele é considerado como o deslocamento do final da coleção).
Se o valor calculado for negativo, inicio toma o valor 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ória

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 valor for uma coleção, todos os elementos da coleção serão adicionados à coleção original
Resultados	Collection	<-	Nova coleção com valores adicionados à coleção original

Descrição

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

Se valor for uma coleção, todos os seus elementos serã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ória

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 partilhada
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() retorna uma cópia profunda da instância da coleção.Cópia profunda significa que os objetos ou coleções da coleção original são duplicados e não compartilham nenhuma referência com a coleção retornada.

Se for aprovado, o parâmetro option pode conter uma das seguintes constantes (ou ambos):

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. No entanto, você pode resolver os ponteiros ao copiar, passando a constante `ck resolve pointers`. Nesse caso, cada ponteiro presenta na coleção é avaliada quando copiar e seu valor de dereferencia é usado.
`ck shared`	Por padrão, `copy()` retorna uma coleção regular (não compartilhada), mesmo que o comando seja aplicado a uma coleção compartilhada. Passe a constante `ck shared` para criar uma coleção compartilhada. Nesse caso, você pode usar o parâmetro groupWith para associar a coleção compartilhada a outra coleção ou objeto (veja abaixo).

Os parâmetros groupWithCol ou groupWithObj permitem que você designe uma coleção ou um objeto ao qual a coleção resultante deve ser associada.

nota

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

Exemplo 1

Queremos copiar a $lastnames coleção regular (não compartilhada) para o $sharedObject objeto compartilhado. Para fazer isso, devemos criar uma cópia compartilhada 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. Portanto, devemos fazer uma cópia compartilhada de $sharedColl1 e designar $sharedColl2 como um grupo compartilhado 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 em Storage 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

Este 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ória

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() retorna o número de elementos não nulos na coleção.

Se a coleção contiver objetos, você poderá passar o parâmetro propertyPath. Nesse caso, somente os elementos que contêm o propertyPath sã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ória

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() retorna o número de vezes que o valor é encontrado na coleção.

Você pode passar em value:

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

Para que um elemento seja encontrado, o tipo de valor deve ser equivalente ao tipo do elemento; o método usa o operador de igualdade.

O parâmetro opcional propertyPath permite que você conte os valores dentro de uma coleção de objetos: passe em propertyPath o caminho da propriedade cujos valores você deseja 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ória

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

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

Parâmetro	Tipo		Descrição
propertyPath	Text	->	Rota do atributo cujos valores quer obter
options	Integer	->	`ck diacritical`, `ck count values`
Resultados	Collection	<-	Nova coleção com apenas valores distintos

Descrição

A função .distinct() retorna uma coleção que contém apenas valores distintos (diferentes) da coleção original.

A coleção retornada é ordenada automaticamente. Os valores null não são devolvidos.

Se a coleção contém objetos, você pode passar o parâmetro propertyPath para indicar a propriedade do objeto cujos valores distintos você quer obter.

No parâmetro opções, você pode passar uma ou uma combinação das seguintes constantes:

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 essa opção é passada, `.distinct()` retorna uma coleção de objetos contendo um par de atributos `{{"value":value; "count":count}`.

Exemplos

 var $c; $c2; $c3 : 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]
 $c3:=$c.distinct("size";ck count values) //$c3=[{value:1,count:2},{value:3,count:1}]

.equal()

História

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ítica ("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 recursivamente os conteúdos da coleção e da coleção2 (comparação profunda)e retorna verdadeiro se eles forem idênticos.

Notas

A função .equal() verifica apenas a igualdade de elementos do tipo string, booleano, número e nulo nas coleções. Ele não verifica a igualdade dos objetos nativos.
Elementos com valores null não são a mesma coisa que valores Undefined.

Como padrão, uma avaliação não-diacrítica é realizada. Se você quiser que a avaliação diferencie maiúsculas de minúsculas ou caracteres acentuados, passe a constante ck diacritical no parâmetro de opção.

tip

Uma comparação recursiva de coleções pode consumir muito tempo se a coleção for grande e profunda. Se quiser comparar apenas duas referências de coleção, você pode considerar o uso do operador de comparação = para referências de coleção.

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ória

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

.every( { startFrom : Integer ; } formula : 4D.Function { ;...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	any	->	Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultados	Parâmetros	<-	True se todos os elementos passarem o teste com sucesso

Descrição

A função .every() retorna true se todos os elementos da coleção passarem com sucesso em um teste implementado no objeto formula ou método methodName fornecido.

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

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

A callback é chamada com o(s) parâmetro(s) passados em param (opcional). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar true para cada elemento que cumpra o teste. Este método recebe um Object como primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser avaliado
em $2: param
em $N...: paramN...

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

(obrigatório se você usou um método) $1.result (Boolean): true se a avaliação do valor do elemento for bem-sucedida, false caso contrário.
$1.stop (Boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Em todos os casos, no momento em que a função .every() encontra o primeiro elemento da coleção avaliado como false, ela para de chamar o retorno de chamada e retorna false.

Por padrão, .every() testa toda a coleção. 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
var $f : 4D.Function

$f:=Formula($1.value>0)
$c:=New collection
$c.push(5;3;1;4;6;2)
$b:=$c.every($f) //retorna true
$c.push(-1)
$b:=$c.every($f) //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ória

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`: include null properties na coleção retornada (ignorado por padrão). Parâmetro ignorado se targetPath for passado.
Resultados	Collection	<-	Nova collection contendo valores extraídos

Descrição

A função .extract() cria e retorna uma nova coleção contendo valores propertyPath extraídos da coleção original de objetos.

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. Você pode passar a constante ck keep null no parâmetro option para incluir esses valores como elementos null na coleção retornada.
Se um ou mais parâmetros targetPath forem passados (correspondentes a um ou mais parâmetros propertyPath), .extract() preenche a nova coleção com as propriedades propertyPath e cada elemento da nova coleção é um objeto com as propriedades targetPath preenchidas com as propriedades correspondentes propertyPath. Os valores null são mantidos (o parâmetro option é ignorado com essa 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ória

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 .fill() preenche a coleção com o value especificado, opcionalmente do índice startFrom até o índice end, e retorna a coleção resultante.

Se o parâmetro startFrom for omitido, value é estabelecido para todos os elementos coleção (startFrom=0).
Se o parâmetro startFrom for passado e end for omitido, value é definido como os elementos da coleção a partir de startFrom até o último elemento da coleção (end=length).
Se tanto o parâmetro startFrom quanto end forem passados, value é definido como os elementos da coleção a partir de startFrom até o elemento end.

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

Se startFrom < 0, ele é recalculado como startFrom:=startFrom+length (é considerado como o deslocamento a partir do final da coleção). Se o valor calculado for negativo, startFrom toma o valor 0.
Se end < 0 , ele será recalculado como end:=end+length.
Se end < startFrom (valores passados ou calculados), o método não fará nada.

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ória

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

.filter( formula : 4D.Function { ; ...param : any } ) : Collection
.filter( 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	->	Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultados	Collection	<-	Nova coleção contendo elementos filtrados (cópia superficial)

Descrição

A função .filter() retorna uma nova coleção contendo todos os elementos da coleção original para os quais o resultado da formula ou do methodName é true. Esta função devolve uma shallow copy, 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:

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

A callback é chamada com o(s) parâmetro(s) passados em param (opcional) e um objeto no primeiro parâmetro ($1). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar true para cada elemento que cumpra a condição e assim, adicioná-lo à nova coleção.

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser avaliado
em $2: param
em $N...: paramN...

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

$1.result (boolean): true se o valor do elemento corresponder à condição de filtro e deve ser mantido, false caso contrário.
$1.stop (Boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

nota

Ao usar methodName como retorno de chamada e se o método não retornar nenhum valor, .filter() irá verificar a propriedade $1.result que você deve definir como true para cada elemento que satisfaz a condição.

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(Formula((Value type($1.value)=Is text) && (Length($1.value)<$2)); 6)
  //$colNew=["hello","world","tim","miami"]

Exemplo 2

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

 var $c;$c2;$c3 : Collection
 var $f : 4D.Function

 $f:=Formula(OB Get type($1;"value")=$2)
 $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($f;Is real) // $c2=[5,3,1,4,6,2]
 $c3:=$c.filter($f;Is object)
  // $c3=[{name:Cleveland,zc:35049},{name:Blountsville,zc:35031}]

.find()

História

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

.find( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : any
.find( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : any

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	->	Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultados	any	<-	Primeiro valor encontrado ou Undefined se não encontrado

Descrição

A função .find() retorna o primeiro valor na coleção para o qual o formula ou o resultado do methodName, aplicado a cada elemento, seja true.

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

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

A callback é chamada com o(s) parâmetro(s) passados em param (opcional). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar true para o primeiro elemento que cumpra a condição. Este método recebe um Object como primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser avaliado
em $2: param
em $N...: paramN...

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

(obrigatório se você usou um método) $1.result (Boolean): true se o valor do elemento corresponde à condição de pesquisa, false caso contrário.
$1.stop (Boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Por padrão, .find() pesquisa em toda a coleção. Opcionalmente pode passar em startFrom o índice do elemento a partir do qual vai começar a pesquisa.

Se startFrom >= o tamanho da coleção, -1 é retornado, 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 $col : Collection
$col:=New collection("hello";"world";4;"red horse";"tim";"san jose")
$value:=$col.find(Formula((Value type($1.value)=Is text) && (Length($1.value)<$2)); 5) //$value="tim"

Exemplo 2

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

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(Formula($1.value.name=$2); "Clanton")  //$c2={name:Clanton,zc:35046}

.findIndex()

História

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

.findIndex( { startFrom : Integer ; } formula : 4D.Function { ; ...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	->	Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultados	Integer	<-	Indice do primeiro valor encontrado ou -1 se não encontrado

Descrição

A função .findIndex() retorna o índice, na coleção, do primeiro valor para o qual a formula ou o methodName, aplicado em cada elemento, retorna true.

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

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
methodName, o nome de um método projeto (texto).

A callback é chamada com o(s) parâmetro(s) passados em param (opcional). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar true para o primeiro elemento que cumpra a condição. Este método recebe um Object como primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser avaliado
em $2: param
em $N...: paramN...

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

(obrigatório se você usou um método) $1.result (Boolean): true se o valor do elemento corresponde à condição de pesquisa, false caso contrário.
$1.stop (Boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

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

Se startFrom >= o tamanho da coleção, -1 é retornado, 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ória

Release	Mudanças
20	Adicionado

.first() : any

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

Descrição

A função .first() retorna o primeiro elemento da coleção.

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ória

Release	Mudanças
20	Adicionado

.flat( { depth : Integer } ) : Collection

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() cria uma nova coleção com todos os elementos da subcoleção concatenados recursivamente até a 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ória

Release	Mudanças
20	Adicionado

.flatMap( formula : 4D.Function { ; ...param : any } ) : Collection
.flatMap( 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	->	Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultados	Collection	<-	Collection of transformed values and flattened by a depth of 1

Descrição

A função .flatMap() cria uma nova coleção com base no resultado da chamada da formula da função 4D ou do método methodName em cada elemento da coleção original e aplanada por uma profundidade de 1. Opcionalmente, você pode passar parâmetros para formula ou methodName usando o(s) parâmetro(s) param.

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:

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

A callback é chamada com o(s) parâmetro(s) passados 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).

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser avaliado
em $2: param
em $N...: paramN...

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

(obrigatório se você usou um método) $1.result (qualquer tipo): novo valor transformado para adicionar à coleção resultante
$1.stop (Boolean, opcional): true para parar o callback do método. 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ória

Release	Mudanças
20	Adicionado

.includes( toSearch : expression { ; startFrom : Integer } ) : Boolean

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	<-	True se toSearch for encontrado na coleção

Descrição

A função .includes() retorna True se a expressão toSearch for encontrada entre os elementos da coleção, caso contrário 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 em startFrom.

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). Note que 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 $in : Boolean
 var $obj : Object
 $obj:=New object("value"; 10)
 $col:=New collection(1;2;"Henry";5;3;"Albert";6;4;"Alan";5;$obj)
 $in:=$col.includes(3) //True
 $in:=$col.includes(5;6) //True
 $in:=$col.includes("al@") //True
 $in:=$col.includes("Hello") //False
 $in:=$col.includes($obj)  //True
 $in:=$col.includes(New object("value"; 10)) //False

.indexOf()

História

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 .indexOf() procura a expressão toSearch entre os elementos da coleção e retorna o índice da primeira ocorrência encontrada, ou -1 se não for encontrada.

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 em startFrom.

Se startFrom >= o tamanho da coleção, -1 é retornado, 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ória

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 exatamente da mesma forma que a função .query(), mas retorna os índices, na coleção original, dos elementos da coleção de objetos que correspondem às condições de busca queryString, e não os próprios elementos. Indices são retornados em ordem ascendente.

O parâmetro queryString usa a seguinte sintaxe:

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

Para uma descrição detalhada dos parâmetros queryString e value, por favor consulte 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ória

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 .insert() insere element na posição index especificada na instância da coleção e retorna a coleção editada.

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

Se index > o comprimento da coleção, o index inicial real será definido como o comprimento 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ória

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 cadeias de caracteres nulas e vazias no resultado
Resultados	Text	<-	String contendo todos os elementos da coleção, separados por um delimitador

Descrição

A função .join() converte todos os elementos da coleção em strings e os concatena usando a string delimitadora especificada como separador. A função retorna a string resultante.

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

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ória

Release	Mudanças
20	Adicionado

.last() : any

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

Descrição

A função .last() retorna o último elemento da coleção.

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

Exemplo

var $col; $emptyCol : Collection
var $last : Variant
$col:=New collection(10; 20; 30; "hello"; 50)
$last:=$col.last() // 50

$emptyCol:=New collection() //empty
// $last:=$emptyCol[$emptyCol.length-1] //devolve um erro
$last:=$emptyCol.last() // devolve Undefined

.lastIndexOf()

História

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 retorna o índice da última ocorrência, ou -1 se ela não for encontrada.

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 ao elemento a ser encontrado (são aplicadas as mesmas regras do operador de igualdade).

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

Se startFrom >= o comprimento da coleção menos um (coll.length-1), toda a coleção será pesquisada (padrão).
Se startFrom < 0, ele é recalculado como startFrom:=startFrom+length (é considerado como o deslocamento a partir 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, será retornado -1, o que significa que a coleção não será 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ória

Release	Mudanças
v16 R5	Adicionado

.length : Integer

Descrição

A propriedade .length retorna o número de elementos na coleção.

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

Exemplo

 $col:=$c.query("dateHired &lt; :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ória

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

.map( formula : 4D.Function { ; ...param : any } ) : Collection
.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	->	Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultados	Collection	<-	Collection de valores transformados

Descrição

A função .map() cria uma nova coleção com base no resultado da chamada da função formula 4D ou do método methodName em cada elemento da coleção original. Opcionalmente, você pode passar parâmetros para formula ou methodName usando o(s) parâmetro(s) param. .map() sempre retorna uma coleção com o mesmo tamanho da coleção original, exceto se $1.stop tiver sido usado (veja abaixo).

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

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser avaliado
em $2: param
em $N...: paramN...

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

(obrigatório se você usou um método) $1.result (qualquer tipo): novo valor transformado para adicionar à coleção resultante
$1.stop (Boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Exemplo

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

.max()

História

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() retorna o elemento com o valor mais alto na coleção (o último elemento da coleção, como seria classificado em ordem crescente usando a função .sort()).

Se a coleção contiver diferentes tipos de valores, a função .max() retornará o valor máximo dentro do último tipo de elemento na ordem da lista de tipos (consulte a descrição de .sort()).

Se a coleção contiver objetos, passe o parâmetro propertyPath para indicar a propriedade do objeto cujo valor máximo você deseja obter.

Se a coleção estiver vazia, .max() retorna 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ória

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() retorna o elemento com o menor valor na coleção (o primeiro elemento da coleção, como seria classificado em ordem crescente usando a função .sort()).

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

Se a coleção contiver objetos, passe o parâmetro propertyPath para indicar a propriedade do objeto cujo valor mínimo você deseja 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"

.multiSort()

História

Release	Mudanças
20 R3	Adicionado

.multiSort() : Collection
.multiSort( colsToSort : Collection ) : Collection
.multiSort( formula : 4D.Function ; colsToSort : Collection ) : Collection

Parâmetro	Tipo		Descrição
formula	4D. Function	->	Objecto fórmula
colsToSort	Collection	->	Coleção de coleções e/ou objetos com propriedades {`collection`:colToSort;`order`:`ck ascending` ou `ck descending`}
Resultados	Collection	<-	Colecção original ordenada

Descrição

A função .multiSort() permite que você execute uma classificação sincronizada em vários níveis em um conjunto de coleções.

Se .multiSort() for chamada sem parâmetros, a função terá o mesmo efeito que a função .sort(): a coleção é classificada (somente valores escalares) em ordem crescente por padrão, de acordo com seu tipo. Se a coleção contiver valores de tipos diferentes, eles serão primeiro agrupados por tipo e, em seguida, classificados. 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

Classificação sincronizada de nível único

Para classificar várias coleções de forma síncrona, basta passar em colsToSort uma coleção de coleções a serem classificadas. Você pode passar um número ilimitado de coleções. A coleção original será classificada em ordem crescente e todas as coleções colsToSort serão classificadas de forma sincronizada.

nota

Todas as coleções colsToSort devem ter o mesmo número de elementos, caso contrário, será retornado um erro.

Se quiser classificar as coleções em outra ordem que não seja a ascendente, você deverá fornecer uma fórmula (Formula object que defina a ordem de classificaçã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. Você pode fornecer parâmetros adicionais à fórmula, se necessário.

A fórmula recebe os seguintes parâmetros:

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

Classificação sincronizada em vários níveis

A definição de uma classificação sincronizada em vários níveis exige que você passe um objeto contendo as propriedades {collection:colToSort;order:ck ascending ou ck descending} em vez da própria colToSort para cada coleção a ser usada como subnível.

Os níveis de classificação são determinados pela ordem em que as coleções são passadas no parâmetro colsToSort: a posição de um objeto collection/order na sintaxe determina seu nível de classificação.

nota

A função .multiSort() utiliza um algoritmo de classificação [estável] (https://en.wikipedia.org/wiki/Sorting_algorithm#Stability).

Exemplo 1

Uma simple classificação sincronizada de coleções com diferentes tipos de valores:

var $col;$col2;$col3 : Collection
$col:=["A"; "C"; "B"]
$col2:=[1; 2; 3]
$col3:=[["Jim"; "Philip"; "Maria"]; ["blue"; "green"]; ["11"; 22; "33"]]

$col.multiSort([$col2; $col3])
//$col=["A","B","C"]
//$col2=[1,3,2]
//$col3[0]=["Jim","Philip","Maria"]
//$col3[1]=["11",22,"33"]
//$col3[2]=["blue","green"]

Exemplo 2

Você deseja classificar três coleções sincronizadas: cidade, país e continente. Você deseja uma classificação ascendente da primeira e da terceira coleções e a sincronização da segunda coleção:

var $city : Collection
var $country : Collection
var $continent : Collection

$city:=["Paris"; "Lyon"; "Rabat"; "Eching"; "San Diego"]
$country:=["France"; "France"; "Morocco"; "Germany"; "US"]
$continent:=["Europe"; "Europe"; "Africa"; "Europe"; "America"]

$continent.multiSort([$country; {collection: $city; order: ck ascending}])
//$continent=["Africa","America","Europe","Europe","Europe"]
//$country=["Morocco","US","France","France","Germany"]
//$city=["Rabat","San Diego","Lyon","Paris","Eching"]

Exemplo 3

Você também pode sincronizar coleções de objetos.

var $name : Collection
var $address : Collection
$name:=[]
$name.push({firstname: "John"; lastname: "Smith"})
$name.push({firstname: "Alain"; lastname: "Martin"})
$name.push({firstname: "Jane"; lastname: "Doe"})
$name.push({firstname: "John"; lastname: "Doe"})
$address:=[]
$address.push({city: "Paris"; country: "France"})
$address.push({city: "Lyon"; country: "France"})
$address.push({city: "Eching"; country: "Germany"})
$address.push({city: "Berlin"; country: "Germany"})

$name.multiSort(Formula($1.value.firstname<$1.value2.firstname); [$address])
//"Alain Martin","Jane Doe","John Smith","John Doe"
//"Lyon France","Eching Germany","Paris France","Berlin Germany"

.orderBy()

História

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() retorna uma nova coleção contendo todos os elementos da coleção na ordem especificada.

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.

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). Você pode modificar essa ordem automática passando as constantes ck ascending ou ck descending no parâmetro ascOrDesc (veja 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 : Texto (fórmula). Sintaxe: propertyPath1 {desc or asc}, propertyPath2 {desc or asc},... (ordem padrão: asc). pathStrings contém uma fórmula feita de 1 a x caminhos de propriedade e, (opcionalmente), ordenar ordens, 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; $c3 : 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ória

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

.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection
.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 .orderByMethod() retorna uma nova coleção contendo todos os elementos da coleção na ordem definida por meio da função formula 4D ou do método methodName.

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

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

No retorno de chamada, passe algum código que compare dois valores e retorne true se o primeiro valor for menor que o segundo. Você pode fornecer parâmetros extraParam para a callback, se necessário.

A chamada de retorno recebe os seguintes parâmetros:

$1 (objeto), onde:
- $1.value (qualquer tipo): valor do primeiro elemento a ser comparado
- $1.value2 (qualquer tipo): valor do 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 (booleano): true se $1.value < $1.value2, false caso 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(Formula(Num($1.value)<Num($1.value2))) // $c3=["4","33","222","1111"]

Exemplo 2

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

 var $fruits; $c2 : Collection
 $fruits:=New collection("Orange";"Apple";"Grape";"pear";"Banana";"fig";"Blackberry";"Passion fruit")
 $c2:=$fruits.orderByMethod(Formula(Length(String($1.value))>Length(String($1.value2))))
  //$c2=[Passion fruit,Blackberry,Orange,Banana,Apple,Grape,pear,fig]

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]

O método sortCollection:

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

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

.pop()

História

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 último elemento da coleção e o retorna como o resultado da função.

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

Exemplo

O .pop(), usado em conjunto com .push(), pode ser usado para implementar um recurso de pilha do tipo primeiro a entrar, último a sair:

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

.push()

História

Release	Mudanças
v16 R6	Adicionado

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

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

Descrição

A função .push() acrescenta um ou mais elementos ao final da instância da coleção e retorna a coleção editada.

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ória

Release	Mudanças
20 R6	Consultas usando referências a objetos ou coleções
17 R5	Assistência de querySettings
v16 R6	Adicionado

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

Parâmetro	Tipo		Descrição
queryString	Text	->	Critérios de pesquisa
value	any	->	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() retorna todos os elementos de uma coleção de objetos que correspondem às condições de pesquisa definidas por queryString e (opcionalmente) value ou querySettings. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

Uma coleção vazia será retornada se a coleção na qual a consulta for executada não contiver o valor pesquisado.

parâmetro queryString

O parâmetro queryString usa a seguinte sintaxe:

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

onde:

propertyPath: caminho da propriedade em que você deseja executar a consulta. Os atributos se expressam como pares propriedade/ valor, onde propriedade é o nome do marcador de posição inserido para uma rota de atributo em queryString ou formula (":placeholder") e valor pode ser uma string ou uma coleção de strings. No caso de um caminho de atributo cujo tipo é Collection, a notação [] é usada para lidar todas as ocorrências (por exemplo children[].age).
comparator: símbolo que compara propertyPath e value. Os simbolos abaixo são compatíveis:

Comparação	Símbolos	Comentário
Igual a	=, ==	Retorna os dados coincidentes, admite o coringa (@), não diferencia entre maiúsculas e minúsculas nem diacríticas.
	===, IS	Retorna os dados coincidentes, considera @ como caractere padrão, não diferencia entre maiúsculas e minúsculas nem diacríticas
Diferente de	#, !=	Suporta o coringa (@). Equivalente a "Condição não aplicada em uma declaração" (ver abaixo).
	!==, IS NOT	Considera @ como um caractere normal
Não se aplica à condição de uma sentença	NOT	Parentesis são obrigatórios quando usar NOT antes de uma instrução que contenha vários operadores. Equivalente a "Not equal to" (veja abaixo).
Menor que	<
Maior que	>
Menor que ou igual a	<=
Maior ou igual a	> =
Incluído em	IN	Retorna dados iguais a ao menos um dos valores de uma coleção ou de um conjunto de valores, admite o coringa (@)

value: o valor a ser comparado com o valor atual da propriedade de cada elemento da coleção. Pode ser qualquer expressão de valor constante que corresponda à propriedade de tipo de dados do elemento ou um placeholder. Quando usar um valor constante, as regras abaixo devem ser respeitadas:
- A constante de tipo texto pode ser passada com ou sem aspas simples (ver Uso de aspas mais abaixo). Para pesquisar uma stirng dentro de uma string (uma pesquisa "contém") use o símbolo coringa (@) em valor para isolar a string a ser pesquisada como mostrado neste exemplo: "@Smith@". As palavras chaves abaixo são proibidas para constantes de texto: true, false.
- Valores constantes de tipo booleano: true ou false (diferencia maiúscula de minúscula).
- **Valores constantes de tipo numérico: os decimais se separam com um '.' (ponto).
- constantes de tipo date: formato "YYYY-MM-DD"
- null constante: usando a palavra-chave "null" irá encontrar as propriedades null e undefined.
- no caso de uma pesquisa com um comparador IN, valor deve ser uma coleção, ou valores que coincidam com o tipo da rota do atributo entre [ ] separados por vírgulas (para as strings, os caracteres " devem ser escapados com \).
logicalOperator: usado para participar de múltiplas condições na consulta (opcional). Pode usaar um dos operadores lógicos abaixo (ou o nome ou o símbolo podem ser usados):

Conjunção	Símbolos
AND	&, &&, and
OU	\|,\|\|, or

Usar aspas

Ao usar aspas dentro das consultas, você deve usar aspas simples ' ' dentro da consulta e aspas duplas " " para envolver toda a consulta, caso contrário, será retornado um erro. Por exemplo:

"employee.name = 'smith' AND employee.firstname = 'john'"

Usando parêntesis

Você pode usar parênteses na consulta para dar prioridade ao cálculo. Por exemplo, pode organizar uma pesquisa da seguinte maneira:

"(employee.age >= 30 OR employee.age <= 65) AND (employee.salary <= 10000 OR employee.status = 'Manager')"

Uso de placeholders

4D permite que você use espaços reservados para attributePath, formula e value argumentos dentro do parâmetro queryString . Um placeholder é um parâmetro que você insere em cadeias de consulta e que é substituído por outro valor quando a cadeia de consulta é avaliada. O valor dos placeholders é avaliado uma vez no início da consulta; ele não é avaliado para cada elemento.

Dois tipos de placeholders podem ser usados: placeholders indexados e placeholders nomeados.

Placeholders indexados: parâmetros são inseridos como :paramIndex (por exemplo, ":1", ":2"...) no queryString e seus respectivos valores são fornecidos pela sequência de parâmetro(s) value. É possível utilizar até 128 parâmetros value.

Exemplo:

$c:=$myCol.query(":1=:2";"city";"Chicago")

Named placeholders: os parâmetros são inseridos como :paramName (por exemplo, ":myparam") e seus valores são fornecidos nos objetos "attributes" e/ou "parameters" no parâmetro querySettings.

Exemplo:

$o.attributes:={att:"city"}
$o.parameters:={name:"Chicago")
$c:=$myCol.query(":att=:name";$o)

É possível misturar todos os tipos de argumentos em queryString. Uma queryString pode conter, para os parâmetros propertyPath e value:

valores diretos (sem placeholders),
placeholders indexados ou com nome.

O uso de placeholders em consultas é recomendado pelos seguintes motivos:

Evita a inserção de código malicioso: se user diretamente variáveis preenchidas com uma string de pesquisa, um usuário poderia modificar as condições de pesquisa entrando argumentos adicionais. Por exemplo, imagine uma string de pesquisa como:

 $vquery:="status = 'público' & nome = "+meunome //usuário entra em seu nome
 $result:=$col.query($vquery)

Essa consulta parece segura, pois os dados não públicos são filtrados. No entanto, se o usuário inserir na área myname algo como "smith OR status='private',* a string de consulta será modificada na etapa de interpretação e poderá retornar dados privados.

Ao usar placeholders, não é possível substituir as condições de segurança:

 $result:=$col.query("status='public' & name=:1";myname)

Neste caso, se o usuário digitar smith OR status='private' na área myname, isso não será interpretado na string de consulta, mas apenas passado como um valor. A busca por uma pessoa chamada "smith OR status='private'" simplesmente falhará.

Isso evita que você tenha que se preocupar com problemas de formatação ou caracteres, especialmente ao lidar com parâmetros propertyPath ou value que podem conter caracteres não alfanuméricos, como ".", "['...
Permite o uso de variáveis ou expressões nos argumentos de pesquisa. Exemplos:

$result:=$col.query("address.city = :1 & name =:2";$city;$myVar+"@")
$result2:=$col.query("company.name = :1";"John's Pizzas")

Pesquisa de valores null

Quando pesquisar por valores null não pode usar a sintaxe do marcador de posição porque o motor de consulta considera o valor null como um valor de comparação inesperado. Por exemplo, se executar esta pesquisa:

$vSingles:=$colPersons.query("spouse = :1";Null) // NÃO funcionará

Não obterá o resultado esperado porque o valor nulo será avaliado por 4D como um erro resultante da avaliação do parâmetro (por exemplo, um atributo vindo de outra consulta). Para este tipo de pesquisa, deve usar a sintaxe de pesquisa direta:

$vSingles:=$colPersons.query("spouse = null") //sintaxe correta

Referência de objeto ou de coleção como valor

Você pode consultar uma coleção usando uma referência de objeto ou uma referência de coleção como o parâmetro valor a ser comparado. A consulta corresponderá a objetos na coleção que se referem (apontam para) a mesma instância de objeto ou coleção.

Os seguintes comparadores são suportados:

Comparação	Símbolos
Igual a	=, ==
Diferente de	#, !=

Para criar uma consulta com um objeto ou uma referência de coleção, você deve usar a sintaxe do parâmetro querySettings. Exemplo com uma referência de objeto:

var $o1:={a: 1}
var $o2:={a: 1} //mesmo objeto mas outra referência
var $o3:=$o1 //mesmo objeto e referência

var $col; $colResult : Collection

$col:=[{o: $o1}; {o: $o2}; {o: $o3}]
$colResult:=$col.query("o = :v"; {parameters: {v: $o3}})
	//$colResult.length=2
	//$colResult[0].o=$o1 is true
	//$colResult[1].o=$o1 is true

Exemplo com uma referência de coleção:

$c1:=[1; 2; 3]
$c2:=[1; 2; 3] //mesma coleção, mas outra referência
$c3:=$c1 //mesma coleção e referência

$col:=[{c: $c1}; {c: $c2}; {c: $c3}]
$col2:=$col.query("c = :v"; {parameters: {v: $c3}})
	//$col2.length=2
	//$col2[0].c=$c1 é true
	//$col2[1].c=$c1 é true

Parâmetro querySettings

No parâmetro querySettings, você pode passar um objeto que contenha placeholders de consulta como objetos. As propriedades abaixo são compatíveis:

Propriedade

Tipo

Descrição

parameters

Object

Placeholders com nome para os valores usados na queryString. Os valores são expressos como pares de propriedade/valor, em que propriedade é o nome do espaço reservado inserido para um valor na queryString (":placeholder") e valor é o valor a ser comparado. Pode combinar marcadores de posição indexados (valores passados diretamente em parâmetros de valor) e valores de marcadores de posição com nome na mesma pesquisa.

attributes

Object

Placeholders nomeados para os caminhos de atributos usados na queryString. Os atributos são expressos como pares de propriedade/valor, em que propriedade é o nome do espaço reservado inserido para um caminho de atributo no queryString (":placeholder"), e o valor pode ser uma cadeia de caracteres ou uma coleção de cadeias de caracteres. Cada valor é um caminho que pode designar uma propriedade em um objeto da coleção

Tipo de propriedade	Descrição
String (cadeia de caracteres)	attributePath expresso usando a notação de ponto, por exemplo, "name" ou "user.address.zipCode"
Coleção de cadeias de caracteres	Cada cadeia de caracteres da coleção representa um nível de attributePath, por exemplo, ["name"] ou ["user", "address", "zipCode"]. Using a collection allows querying on attributes with names that are not compliant with dot notation, e.g. ["4Dv17.1","en/fr"]

You can mix indexed placeholders (values directly passed in value parameters) and named placeholder values in the same 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 for 01/10/2018

Exemplo 3

Pesquisas com datas:

$entitySelection:=ds.Employee.query("birthDate > :1";"1970-01-01")
$entitySelection:=ds.Employee.query("birthDate <= :1";Current date-10950)

info

More examples of queries can be found in the dataClass.query() page.

.reduce()

História

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

.reduce( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : 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 ser usado como primeiro argumento para a primeira chamada de formula ou 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() aplica a chamada de retorno formula ou methodName em um acumulador e em cada elemento da coleção (da esquerda para a direita) para reduzi-lo 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:

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

O retorno de chamada pega cada elemento da coleção e executa qualquer operação desejada para acumular o resultado em $1.accumulator, retornado em $1.value.

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:

em $1.value: valor do elemento a ser processado
em $2: param
em $N...: paramN...

A chamada de retorno recebe os seguintes parâmetros:

$1.accumulator: valor a ser modificado pela função sendo inicializado por initValue.
$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;$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(Formula(Flatten)) //$r=[0,1,2,3,4,5,6,7]

Com o seguinte método Flatten:

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

.reduceRight()

História

Release	Mudanças
20	Adicionado

.reduceRight( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any
.reduceRight( 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 ser usado como primeiro argumento para a primeira chamada de formula ou 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 chamada de retorno formula ou methodName em um acumulador e em cada elemento da coleção (da direita para a esquerda) para reduzi-lo 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:

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

O retorno de chamada pega cada elemento da coleção e executa qualquer operação desejada para acumular o resultado em $1.accumulator, retornado em $1.value.

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:

em $1.value: valor do elemento a ser processado
em $2: param
em $N...: paramN...

A chamada de retorno recebe os seguintes parâmetros:

$1.accumulator: valor a ser modificado pela função sendo inicializado por initValue.
$1.stop (boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Exemplo 1

var $c : Collection
$c:=New collection(5;3;5;1;3;4;4;6;2;2)
$r:=$c.reduceRight(Formula($1.accumulator*=$1.value); 1)  //retorna 86400

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.reduceRight(Formula(Flatten)) //$r=[6,7,4,5,2,3,0,1]

Com o seguinte método Flatten:

	//Método projeto Flatten 
 If($1.accumulator=Null)
    $1.accumulator:=New collection
 End if
 $1.accumulator.combine($1.value)

.remove()

História

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() remove um ou mais elemento(s) da posição índice especificada na coleção e retorna a coleção editada.

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

Se index < 0, ele será recalculado como index:=index+length (ele é considerado como o deslocamento do final da coleção).
Se o valor calculado for < 0, index será definido como 0.
Se o valor calculado > o comprimento da coleção, index é definido para o comprimento.

Em howMany, passe o número de elementos a serem removidos de index. 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ória

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

The .resize() function sets the collection length to the specified new size and returns the resized collection.

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

Por padrão, novos elementos são preenchidos com valores null. 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ória

Release	Mudanças
v16 R6	Adicionado

.reverse( ) : Collection

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

Descrição

The .reverse() function returns a deep copy of the collection with all its elements in reverse order. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

Exemplo

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

.shift()

História

Release	Mudanças
v16 R6	Adicionado

.shift() : any

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

Descrição

The .shift() function removes the first element of the collection and returns it as the function result.

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ória

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() retorna uma parte de uma coleção em uma nova coleção, selecionada do índice startFrom ao índice end (end não incluído). Esta função devolve uma cópia superficial da coleção. Na coleção original é uma coleção partilhada, a coleção retornada também é uma coleção partilhada.

A coleçã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 coleção devolvida contém todos os elementos desde startFrom até ao último elemento da coleção original.

Se startFrom < 0, ele é recalculado como startFrom:=startFrom+length (é considerado como o deslocamento a partir do final da coleção).
Se o valor calculado < 0, startFrom é definido como 0.
Se end < 0 , ele será recalculado como end:=end+length.
Se end < startFrom (valores passados ou calculados), o método não fará 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ória

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

.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean
.some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean

Parâmetro	Tipo		Descrição

Descrição

A função .some() retorna true se pelo menos um elemento da coleção passar com êxito em um teste implementado no código formula ou methodName fornecido.

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

formula (sintaxe recomendada), um objecto Formula que pode encapsular qualquer expressão executável, incluindo funções e métodos projecto;
ou methodName, o nome de um método projeto (texto).

A chamada de retorno recebe os seguintes parâmetros:

em $1.value: valor do elemento a ser processado
em $2: param
em $N...: paramN...

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

(obrigatório se você usou um método) $1.result (boolean): true se a avaliação do valor do elemento for bem-sucedida, false caso contrário.
$1.stop (boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

De qualquer forma, no momento em que a função .some() encontra o primeiro elemento da coleção retornando true, ela para de chamar o retorno de chamada e retorna true.

Por padrão, .some() testa toda a coleção. Opcionalmente pode passar o índice da coleção para a qual iniciar a pesquisa em startFrom.

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

You want to know if at least one collection value is >0.

 var $c : Collection
 var $b : Boolean
 $c:=New collection
 $c.push(-5;-3;-1;-4;-6;-2)
 $b:=$c.some(Formula($1.value>0)) // $b=false
 $c.push(1)
 $b:=$c.some(Formula($1.value>0)) // $b=true

 $c:=New collection
 $c.push(1;-5;-3;-1;-4;-6;-2)
 $b:=$c.some(Formula($1.value>0)) //$b=true
 $b:=$c.some(1;Formula($1.value>0)) //$b=false

.sort()

História

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

The .sort() function sorts the elements of the original collection and also returns the sorted collection .

If .sort() is called with no parameters, only scalar values (number, text, date, booleans) are sorted. Os elementos são classificados por defeito em ordem ascendente, de acordo com o seu tipo. 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

Se pretender ordenar os elementos da coleção por outra ordem ou ordenar qualquer tipo de elemento, deve fornecer em formula (objeto 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:
- $1.value (qualquer tipo): valor do primeiro elemento a ser comparado
- $1.value2 (qualquer tipo): valor do segundo elemento a ser comparado
$2...$N (qualquer tipo): parâmetros adicionais

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

$1.result (booleano): true se $1.value < $1.value2, false caso 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 $col; $col2; $col3 : Collection
$col:=New collection(33;4;66;1111;222)
$col2:=$col.sort() //ordenação numérica: [4,33,66,222,1111]
$col3:=$col.sort(Formula(String($1.value)<String($1.value2))) //ordenação alfabética: [1111,222,33,4,66]

.sum()

História

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

The .sum() function returns the sum for all values in the collection instance.

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 : Collection
 var $vSum : Real
 $col:=New collection(10;20;"Monday";True;2)
 $vSum:=$col.sum() //32

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ória

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(s) *valu(es) fornecido(s) no início da coleção e retorna 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​

New collection​

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

`New collection`

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