Skip to main content
Version: v19 R8 BETA

Collection

A classe Collection gerencia variáveis de tipo Collection.

Uma coleção se inicializa com:

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

Exemplo

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

Resumo

.average( {propertyPath : Text } ) : Real    retorna a média aritmética dos valores definidos na instância de coleção
.clear() : Collection    remove todos os elementos da instância de recolha e devolve uma coleção vazia
.combine( col2 : Collection {; index : Integer } ) : Collection    insere col2 elementos no final ou no índice especificado posição na instância de coleção e devolve a colecção editada
.concat( value : any { ;...valueN } ) : Collection    devolve uma nova colecção contendo os elementos da colecção original com todos os elementos do parâmetro value adicionado ao final
.copy() : Collection
.copy( option : Integer ) : Collection
.copy( option : Integer ; groupWithCol : Collection ) : Collection
.copy( option : Integer ; groupWithObj : Object ) : Collection
     devolve uma cópia profunda da instância da coleção
.count( { propertyPath : Text } ) : Real    devolve o número de elementos não-nulos na colecção
.countValues( value : any {; propertyPath : Text } ) : Real    devolve o número de vezes que o valor é encontrado na colecção
.distinct( {option : Integer} ) : Collection
.distinct( propertyPath : Text {; option : Integer } ) : Collection
    devolve uma colecção contendo apenas valores distintos (diferentes) da colecção original
.equal( collection2 : Collection {; option : Integer } ) : Boolean    compara a collection com a collection2
.every( { 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 passaram com sucesso num teste implementado na fórmula fornecida object ou methodName name
.extract( propertyPath : Text { ; option : Integer } ) : Collection
.extract( propertyPath : Text ; targetPath : Text { ;...propertyPathN : Text ;... targetPathN : Text } ) : Collection
    cria e devolve uma nova colecção contendo propertyPath valores extraídos da colecção original de objectos
.fill( value : any ) : Collection
.fill( value : any ; startFrom : Integer { ; end : Integer } ) : Collection
    preenche a coleção com o valor especificado *, opcionalmente de startFrom index to end* index, e devolve a coleção resultante
.filter( formula : 4D. Function { ; ...param : any } ) : Collection
.filter( methodName : Text { ; ...param : any } ) : Collection
    devolve uma nova coleção contendo todos os elementos da coleção original para a qual a fórmula ou methodName resultado for true
.find( { startFrom : Integer ; } formula : 4D. Function { ; ...param : any } ) : any
.find( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : any
    retorna o primeiro valor da coleção cujo resultado fórmula ou methodName, aplicado em cada elemento, retorna true
.findIndex( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Integer
.findIndex( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Integer
    devolve o índice, na coleção, do primeiro valor para o qual fórmula ou methodName, aplicado sobre cada elemento, devolve true
.indexOf( toSearch : expression { ; startFrom : Integer } ) : Integer     pesquisa a expressão toSearch entre os elementos da colecção e devolve o índice da primeira ocorrência encontrada, ou -1 se não foi encontrada
.indices( queryString : Text { ; ...value : any } ) : Collection     devolve índices, na coleção original, de elementos da coleção de objectos que correspondem à queryString condições de pesquisa
.insert( index : Integer ; element : any ) : Collection      insere elementos no índice posição na instância de coleção e devolve a coleção editada
.join( delimiter : Text { ; option : Integer } ) : Text     inserts the given value(s) at the beginning of the collection
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer     pesquisa a expressão toSearch entre os elementos da coleção e devolve o índice da última ocorrência
.length : Integer    devolve o número de elementos da colecção
.map( formula : 4D. Function { ; ...param : any } ) : Collection
.map( methodName : Text { ; ...param : any } ) : Collection
    cria uma nova coleção com base no resultado da chamada da fórmula 4D ou método methodName sobre cada elemento da coleção original
.max( { propertyPath : Text } ) : any     devolve o elemento com o maior valor na colecção
.min( { propertyPath : Text } ) : any     devolve o elemento com o menor valor da colecção
.orderBy( ) : Collection
.orderBy( pathStrings : Text ) : Collection
.orderBy( pathObjects : Collection ) : Collection
.orderBy( ascOrDesc : Integer ) : Collection
    devolve uma nova colecção contendo todos os elementos da colecção na ordem especificada
.orderByMethod( formula : 4D. Function { ; ...extraParam : expression } ) : Collection
.orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection
    devolve uma nova coleção contendo todos os elementos da coleção na ordem definida através da fórmula 4D função ou métodoNome método
.pop() : any     remove o primeiro elemento da coleção e devolve-o como resultado da função
.push( element : any { ;...elementN } ) : Collection     anexa um ou mais elementos(s) ao final da instância de recolha e devolve a coleção editada
.query( queryString : Text ; ...value : any ) : Collection
.query( queryString : Text ; querySettings : Object ) : Collection
    devolve todos os elementos de uma coleção de objectos que correspondem às condições de pesquisa
.reduce( formula : 4D. Function { ; initValue : any { ; ...param : expression }} ) : any
.reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any
    aplica a fórmula ou methodName contra um acumulador e cada elemento da coleção (da esquerda para a direita) para o reduzir a um único valor
.remove( index : Integer { ; howMany : Integer } ) : Collection     insere elementos no índice posição na instância de coleção e devolve a coleção editada
.resize( size : Integer { ; defaultValue : any } ) : Collection     define o comprimento da coleção para o novo tamanho especificado e devolve a coleção redimensionada
.reverse( ): Collection     devolve uma cópia profunda da colecção com todos os seus elementos em ordem inversa
.shift() : any    remove o primeiro elemento da colecção e devolve-o como resultado da função
.slice( startFrom : Integer { ; end : Integer } ) : Collection    devolve uma parte de uma colecção para uma nova colecção
.some( { startFrom : Integer ; } formula : 4D. Function { ; ...param : any } ) : Boolean
.some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean
    retorna true se todos os elementos da coleção passaram com sucesso num teste implementado na fórmula fornecida object ou methodName name
.sort( formula : 4D. Function { ; ...extraParam : any } ) : Collection
.sort( methodName : Text { ; ...extraParam : any } ) : Collection
    ordena os elementos da coleção original e também devolve a coleção ordenada
.sum( { propertyPath : Text } ) : Real    devolve a soma para todos os valores na instância da coleção
.unshift( value : any { ;...valueN : any } ) : Collection    insere o valor dado no início da coleção

Nova colecção

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

ParâmetrosTipoDescrição
valueNumber, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer->Valor(es) de collection
ResultadosCollection<-New collection

Descrição

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

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

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

Lembre que declaraçõesvar : Collection ou C_COLLECTION declaram uma variável do tipo Collection mas não cria qualquer coleção.

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

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

 myCol[10]:="My new element"

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

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

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

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

Exemplo 1

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

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

Exemplo 2

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

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

Exemplo 3

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

 var $coll : Collection
$coll:=New collection("a";"b";"c")
//$coll=["a","b","c"]
$coll[9]:="z" //add a 10th element with value "z"
$vcolSize:=$coll.length //10
//$coll=["a","b","c",null,null,null,null,null,null,"z"]

New shared collection

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
valueNumber, Text, Date, Time, Boolean, Shared object, Shared collection->Valores da collection compartida
ResultadosCollection<-New shared collection

Descrição

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

A adição de um elemento a esta colecção deve ser rodeada pela estrutura de utilização Use...End , caso contrário é gerado um erro. Ler um elemento sem a estrutura é entretanto possível.

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

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

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

Lembre que declaraçõesvar : Collection ou C_COLLECTION declaram uma variável do tipo Collection mas não cria qualquer coleção.

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

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

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

  • número (real, longint....). Valores numéricos são sempre armazenados como reais.
  • text
  • boolean
  • date
  • hora (armazenada como número de milissegundos - real)
  • null
  • objeto compartido(*)
  • shared collection(*) > Diferente de coleções padrão (não partilhadas), coleções partilhadas não são compatíveis com imagens, ponteiros, objetos ou coleções que não são compartilhadas.
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.

(*)Quando um objeto partilhado ou coleção forem adicionadas a uma coleção partilhada, partilham o mesmo locking identifier. Para saber mais sobre esse ponto, veja 4D Doc Center.

Exemplo

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

.average()

Histórico
VersãoMudanças
v16 R6Adicionado

.average( {propertyPath : Text } ) : Real

ParâmetrosTipoDescrição
propertyPathText->Rota de propriedade objeto a ser usado para cálculos
ResultadosReal, Undefined<-Média aritmética dos valores coleção

Descrição

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

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

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

.average() retorna undefined se:

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

Exemplo 1

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

Exemplo 2

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

.clear()

Histórico
VersãoMudanças
v16 R6Adicionado

.clear() : Collection

ParâmetrosTipoDescrição
ResultadosCollection<-Collection original com todos os elementos removidos

Descrição

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

Essa função modifica a coleção original.

Exemplo

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

.combine()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
col2Collection->Collection a combinar
indexInteger->Posição para a qual inserir elementos para combinar em coleção (padrão = length +1)
ResultadosCollection<-Collection original contendo elementos combinados

Descrição

A função .combine() insere col2 elementos no final ou no índice especificado posição na instância de coleção e devolve a colecção editada. .

Essa função modifica a coleção original.

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

Aviso: Lembre que elementos coleção são numerados a partir de 0.

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

Exemplo

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

.concat()

Histórico
VersãoMudanças
v16 R6Adicionado

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

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

Descrição

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

Essa função não modifica a coleção original.

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

Exemplo

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

.copy()

Histórico
VersãoMudanças
v18 R3Nova opção ck shared. Novos parâmetros groupWith
v16 R6Adicionado

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

ParâmetrosTipoDescrição
optionInteger->ck resolve pointers: resolve ponteiros antes de copiar,
ck shared: retorna uma coleção partilihada
groupWithColCollection->Coleção partilhada a ser agrupada com a coleção resultante
groupWithObjObjeto->Objeto partilhado a ser agrupado com a coleção resultante
ResultadosCollection<-Cópia profunda da collection original

Descrição

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

Essa função não modifica a coleção original.

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

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

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

Exemplo 1

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

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

$sharedObject:=New shared object

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

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

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

Exemplo 2

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

var $sharedColl1;$sharedColl2;$copyColl : Collection

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

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

Exemplo 3

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

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

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

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

Exemplo 4

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

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

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

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

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

.count()

Histórico
VersãoMudanças
v16 R6Adicionado

.count( { propertyPath : Text } ) : Real

ParâmetrosTipoDescrição
propertyPathText->Rota de propriedade objeto a ser usado para cálculos
ResultadosReal<-Número de elementos na coleção

Descrição

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

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

Exemplo

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

.countValues()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
valueText, Number, Boolean, Date, Object, Collection->Valor a contar
propertyPathText->Rota de propriedade objeto a ser usado para cálculos
ResultadosReal<-Número de ocorrências do valor

Descrição

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

Pode passar em value:

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

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

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

Essa função não modifica a coleção original.

Exemplo 1

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

Exemplo 2

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

Exemplo 3

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

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

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

.distinct()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
optionInteger->ck diacritical: avaliação diacríticos ("A" # "a" por exemplo)
propertyPathText->Rota do atributo cujos valores quer obter
ResultadosCollection<-Nova coleção com apenas valores distintos

Descrição

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

Essa função não modifica a coleção original.

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

Como padrão, uma avaliação não-diacrítica é realizada. Se quiser que a avaliação diferencie minúsculas de maiúsculas ou que diferencie letras acentuadas, passe a constante ck diacritical no parâmetrooption.

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

Exemplo

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

.equal()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
collection2Collection->Coleção a comparar
optionInteger->ck diacritical: avaliação diacríticos ("A" # "a" por exemplo)
ResultadosBooleano<-True se as coleções forem idênticas, senão false

Descrição

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

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

Elementos com valores Null não são a mesma coisa que valores Undefined.

Exemplo

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

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

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

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

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

.every()

Histórico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetrosTipoDescrição
startFromInteger->Índice para início do teste em
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
paramMixed->Parâmetro(s) a passar para formula ou methodName
ResultadosBooleano<-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 passaram com sucesso num teste implementado na fórmula fornecida object ou methodName name.

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

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

A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar verdadeiro para cada elemento que cumpra o teste. Recebe um objecto no primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

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

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

  • (obrigatório se você usou um método) $1.result (Booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
  • $1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Em todos os casos, no ponto em que a função .every() encontra o primeiro elemento de recolha avaliado para false, deixa de chamar a chamada de retorno e devolve false.

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

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

Exemplo 1

var $c : Collection
$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!))

Exemplo 2

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

var $c : Collection
var $b : Boolean
var $f : 4D. Function

$f:=Formula(Value type($1.value)=$2
$c:=New collection
$c.push(5;3;1;4;6;2)
$b:=$c.every($f;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($f;Is real) //$b=false

.extract()

Histórico

|Versão|Alterações|

|---|---| |v16 R6|Added|

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

ParâmetrosTipoDescrição
propertyPathText->Rota de propriedade de objeto cujos valores serão extraídos para nova coleção
targetpathText->Rota de propriedade alvo ou nome propriedade
optionInteger->ck keep null: inclui propriedades null na coleção retornada (ignorado como padrão). Parâmetro ignorado se for passado targetPath.
ResultadosCollection<-Nova collection contendo valores extraídos

Descrição

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

Essa função não modifica a coleção original.

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

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

    Como padrão, elementos para os quais propertyPath for null ou undefined são ignorados na coleção resultante. Pode passar a constante ck keep null no parâmetro option para incluir esses valores como elementos null na coleção retornada.

  • Se um ou mais parâmetros targetPath forem passados,, .extract() preenche a nova coelção com as propriedades propertyPath e cada elemento da nova coleção é um objeto com as propriedades targetPath preenchidas com as propriedades correspondentes propertyPath. Se mantém os valores null (o parámetro option se ignora) com esta sintaxe.

Exemplo 1

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

Exemplo 2

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

.fill()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
valuenumber, Text, Collection, Object, Date, Boolean->Valores preenchido
startFromInteger->Início do índice (incluído)
endInteger->Final do índice (não incluído)
Resultadoscollection<-Coleção original com valores preenchidos

Descrição

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

Essa função modifica a coleção original.

  • 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 o parâmetroend for omitido, value é estabelecido para elementos de coleção começando com startFrom até o elemento final da coleção (end=length).
  • Se tanto startFrom quanto end forem passados, value é estabelecido para elementos coleção começando em startFrom ao elemento end.

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

  • Se index < 0, será recalculado como startFrom:=startFrom+length (é considerado como o offset do final da coleção). Se o valor calculado for negativo, startFrom toma o valor 0.
  • Se end < 0 , é recalculado como sendo end:=end+length.
  • Se end < startFrom (valores passados ou calculados), o método não faz 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órico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

.filter( formula : 4D. Function { ; ...param : any } ) : Collection
.filter( methodName : Text { ; ...param : any } ) : Collection

ParâmetrosTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
paramany->Parâmetro(s) a passar para formula ou methodName
ResultadosCollection<-Nova coleção contendo elementos filtrados (cópia superficial)

Descrição

A função .filter() devolve uma nova coleção contendo todos os elementos da coleção original para a qual a fórmula ou methodName resultado for true. Summary --> devolve todos os elementos de uma coleção de objetos que coincidem com as condiciones 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.

Essa função não modifica a coleção original.

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

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

A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar verdadeiro para cada elemento que preencha a condição e, portanto, para empurrar para a nova colecção. Recebe um objecto no primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

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

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

  • (obrigatório se tiver utilizado um método) $1.resultado (Booleano): verdadeiro se o valor do elemento corresponder à condição do filtro e tiver de ser mantido, falso caso contrário.
  • $1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

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órico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetrosTipoDescrição
startFromInteger->Índice onde inicia a pesquisa
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
paramany->Parâmetro(s) a passar para formula ou methodName
Resultadosany<-Primeiro valor encontrado ou Undefined se não encontrado

Descrição

A função .find() retorna o primeiro valor da coleção cujo resultado fórmula ou methodName, aplicado em cada elemento, retorna true.

Essa função não modifica a coleção original.

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

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

A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). The callback is called with the parameter(s) passed in param (optional). Recebe um objecto no primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

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

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

  • (obrigatório se tiver utilizado um método) $1.resultado (Booleano): verdadeiro se o valor do elemento corresponder à condição de pesquisa, falso caso contrário.
  • $1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

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

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

Exemplo 1

Se quiser obter o primeiro elemento texto 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órico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetrosTipoDescrição
startFromInteger->Índice onde inicia a pesquisa
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
paramany->Parâmetro(s) a passar para formula ou methodName
ResultadosInteger<-Indice do primeiro valor encontrado ou -1 se não encontrado

Descrição

A função .find() devolve o índice, na coleção, do primeiro valor para o qual fórmula ou methodName, aplicado sobre cada elemento, devolve true.

Essa função não modifica a coleção original.

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

  • fórmula (sintaxe recomendada), um Objecto de fórmula que pode encapsular qualquer expressão executável, incluindo funções e métodos de projecto;
  • methodName, o nome de um método projecto (texto).

A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). The callback is called with the parameter(s) passed in param (optional). Recebe um objecto no primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

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

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

  • (obrigatório se tiver utilizado um método) $1.resultado (Booleano): verdadeiro se o valor do elemento corresponder à condição de pesquisa, falso caso contrário.
  • $1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

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

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

Exemplo

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

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

.indexOf()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
toSearchexpressão->Expressão a pesquisar na coleção
startFromInteger->Índice onde inicia a pesquisa
ResultadosInteger<-Índice da primeira ocorrência de toSearch na coleção, -1 se não encontrado

Descrição

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

Essa função não modifica a coleção original.

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

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

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

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

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

Exemplo

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

.indices()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
queryStringText->Critérios de pesquisa
valueany->Valores a comparar quando usar placeholders (valores temporários)
ResultadosCollection<-Índices elemento correspondendo a queryString na coleção

Descrição

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

Essa função não modifica a coleção original.

O parâmetro queryString usa a sintaxe abaixo:

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

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

Exemplo

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

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

.insert()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
indexInteger->Onde inserir os elementos
elementany->Elemento a inserir na coleção
ResultadosCollection<-Collection original contendo elementos inseridos

Descrição

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

Essa função modifica a coleção original.

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

Aviso: Lembre que elementos coleção são numerados a partir de 0.

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

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

Exemplo

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

.join()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
delimiterText->Separador a usar entre os elementos
optionInteger->ck ignore null or empty: ignora strings vazias ou nulls no resultado
ResultadosText<-String contendo todos os elementos da coleção, separados por um delimitador

Descrição

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

Essa função não modifica a coleção original.

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

Exemplo

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

.lastIndexOf()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
toSearchexpressão->O elemento que é pesquisado dentro da coleção
startFromInteger->Índice onde inicia a pesquisa
ResultadosInteger<-Índice da última ocorrência de toSearch na coleção, -1 se não encontrado

Descrição

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

Essa função não modifica a coleção original.

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

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

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

Se startFrom = 0, a coleção inteira é pesquisada (padrão).

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

Exemplo

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

.length

Histórico
VersãoMudanças
v16 R5Adicionado

.length : Integer

Descrição

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

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

Exemplo

 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

.map()

Histórico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

.map( formula : 4D. Function { ; ...param : any } ) : Collection
.map( methodName : Text { ; ...param : any } ) : Collection

ParâmetrosTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
paramany->Parâmetro(s) a passar para formula ou methodName
ResultadosCollection<-Collection de valores transformados

Descrição

A função .map() cria uma nova coleção com base no resultado da chamada da fórmula 4D ou método methodName sobre cada elemento da coleção original. Optionally, you can pass parameters to formula or methodName using the param parameter(s). .map() always returns a collection with the same size as the original collection, except if $1.stop was used (see below).

Essa função não modifica a coleção original.

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

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

A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). The callback is called with the parameter(s) passed in param (optional). Recebe um objecto no primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

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

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

  • (obrigatório se tiver utilizado um método) $1.resultado (qualquer tipo): novo valor transformado a acrescentar à coleção resultante
  • $1.stop (Booleano, opcional): true para parar o método callback. O valor retornado é o último calculado.

Exemplo

var $c; $c2 : Collection
$c:=New collection(1; 4; 9; 10; 20)
$c2:=$c.map(Formula(Round(($1.value/$2)*100; 2)); $c.sum())
//$c2=[2.27,9.09,20.45,22.73,45.45]

.max()

Histórico
VersãoMudanças
v16 R6Adicionado

.max( { propertyPath : Text } ) : any

ParâmetrosTipoDescrição
propertyPathText->Rota de propriedade objeto a ser usado para avaliação
ResultadosBoolean, Text, Number, Collection, Object, Date<-Valor máximo na coleção

Descrição

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

Essa função não modifica a coleção original.

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

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

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

Exemplo

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

.min()

Histórico
VersãoMudanças
v16 R6Adicionado

.min( { propertyPath : Text } ) : any

ParâmetrosTipoDescrição
propertyPathText->Rota de propriedade objeto a ser usado para avaliação
ResultadosBoolean, Text, Number, Collection, Object, Date<-Valor mínimo na coleção

Descrição

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

Essa função não modifica a coleção original.

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

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

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

Exemplo

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

.orderBy()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
pathStringsText->Caminho(s) de propriedade(s) no(s) qual(is) encomendar a coleção
pathObjectsCollection->Coleção de objetos criterio
ascOrDescInteger->ck ascending ou ck descending (valores escalares)
ResultadosCollection<-Cópia ordenada da coleção (cópia superficial)

Descrição

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

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

Essa função não modifica a coleção original.

Se não passar nenhum parâmetro, a função ordena os valores escalares da coleção em ordem ascendente (outros tipos de elementos, como objetos ou coleções, se devolvem desordenados). Pode modificar esta ordem automático passando as constantes ck ascending ou ck descending no parâmetro ascOrDesc (ver abaixo).

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

  • pathStrings : Text (fórmula). Syntax: propertyPath1 {desc or asc}, propertyPath2 {desc or asc},... (default order: asc). pathStrings contém uma fórmula composta de 1 a x rotas de propriedades e (opcionalmente) ordens de classificação, separados por vírgulas. A ordem na qual as propriedades são passadas determina a prioridade de ordenação dos elementos da coleção Como padrão as propriedades são ordenadas de forma ascendente. 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:

    ConstanteTipoValueComentário
    ck ascendingLongint0Os elementos são ordenados de forma ascendente (por padrão)
    ck descendingLongint1Os 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.

  1. null
  2. booleans
  3. strings
  4. números
  5. objetos
  6. collections
  7. datas

Exemplo 1

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

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

Exemplo 2

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

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

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

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

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

Exemplo 3

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

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

Ordenar com uma rota de propriedade:

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

.orderByMethod()

Histórico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

.orderByMethod( formula : 4D. Function { ; ...extraParam : expression } ) : Collection
.orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection

ParâmetrosTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
extraParamany->Parâmetro(s) a passar
ResultadosCollection<-Cópia ordenada da coleção (cópia superficial)

Descrição

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

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

Essa função não modifica a coleção original.

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

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

Na chamada de retorno, passe algum código que compare dois valores e devolva true se o primeiro valor for inferior ao segundo valor. Pode fornecer extraParam parâmetros para o retorno da chamada, se necessário.

A chamada de retorno recebe os seguintes parâmetros:

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

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

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

Exemplo 1

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

 var $c; $c2; $c3 : Collection
$c:=New collection
$c.push("33";"4";"1111";"222")
$c2:=$c.orderBy() //$c2=["1111","222","33","4"], alphabetical order
$c3:=$c.orderByMethod(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 $strings1; $strings2 : Collection
$strings1:=New collection("Alpha";"Charlie";"alpha";"bravo";"Bravo";"charlie")

//usar o código de caractere:
$strings2:=$strings1.orderByMethod(Function(sortCollection);sk character codes)
// result : ["Alpha","Bravo","Charlie","alpha","bravo","charlie"]

//usar a linguagem:
$strings2:=$string1s.orderByMethod(Function(sortCollection);sk strict)
// result : ["alpha","Alpha","bravo","Bravo","charlie","Charlie"]

Aqui está o método sortCollection:

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

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

.pop()

Histórico
VersãoMudanças
v16 R6Adicionado

.pop() : any

ParâmetrosTipoDescrição
Resultadosany<-Último elemento da coleção

Descrição

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

Essa função modifica a coleção original.

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

Exemplo

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

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

.push()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
elementMixed->Elementos a adicionar à coleção
ResultadosCollection<-Collection original contendo elementos inseridos

Descrição

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

Essa função modifica a coleção original.

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

Se quiser ordenar a coleção resultante:

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

.query()

Histórico
VersãoMudanças
v17 R5Assistência de querySettings
v16 R6Adicionado

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

ParâmetrosTipoDescrição
queryStringText->Critérios de pesquisa
valueMixed->Valores a comparar quando usar placeholders (valores temporários)
querySettingsObjeto->Opções de pesquisa: parâmetros, atributos
ResultadosCollection<-Elementos que correspondem com queryString na coleção

Descrição

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

Essa função não modifica a coleção original.

O parâmetro queryString usa a sintaxe abaixo:

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

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

As fórmulas não tem compatibilidade com a função collection.query(), nem com o parâmetro queryString nem como parâmetro do objeto fórmula.

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...}] if today is 01/10/2018 se hoje for 01/10/2018

Exemplo 3

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

.reduce()

Histórico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

.reduce( formula : 4D. Function { ; initValue : any { ; ...param : expression }} ) : any
.reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any

ParâmetrosTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
initValueText, Number, Object, Collection, Date, Boolean->Valor a utilizar como primeiro argumento da primeira chamada de formula ou methodName
paramexpressão->Parâmetro(s) a passar
ResultadosText, Number, Object, Collection, Date, Boolean<-Resultado do valor do acumulador

Descrição

A função .reduce() aplica a fórmula ou methodName contra um acumulador e cada elemento da coleção (da esquerda para a direita) para o reduzir a um único valor.

Essa função não modifica a coleção original.

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

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

A chamada de retorno leva cada elemento de colecção e realiza qualquer operação desejada para acumular o resultado em $1.acumulador, que é devolvido em $1.valor.

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 elemento a ser processado
  • in $2: param
  • em $N...: paramN...

A chamada de retorno recebe os seguintes parâmetros):

  • $1.accumulator: valor que vai ser modificado pela função e que é 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.reduce(Formula($1.accumulator:=$1.accumulator*$1.value); 1) //devolve 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 método Flatten:

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

.remove()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
indexInteger->Elemento no qual que se inicia a eliminação
howManyInteger->Número de elementos a eliminar, ou 1 elemento se omitir
ResultadosCollection<-Colección original sem elementos eliminados

Descrição

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

Essa função modifica a coleção original.

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

Aviso: Lembre que elementos coleção são numerados a partir de 0. If startFrom < 0, it is considered as the offset from the end of the collection (startFrom:=startFrom+length).

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

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

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

Exemplo

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

.resize()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
sizeInteger->Nova dimensão da colecção
defaultValueNumber, Text, Object, Collection, Date, Boolean->Valor padrão para preencher novos elementos
ResultadosCollection<-Colecção original redimensionada

Descrição

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

Essa função modifica a coleção original.

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

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

Exemplo

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

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

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

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

.reverse()

Histórico
VersãoMudanças
v16 R6Adicionado

.reverse( ): Collection

ParâmetrosTipoDescrição
ResultadosCollection<-Cópia invertida da colecção

Descrição

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

Essa função não modifica a coleção original.

Exemplo

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

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

.shift()

Histórico
VersãoMudanças
v16 R6Adicionado

.shift() : any

ParâmetrosTipoDescrição
Resultadosany<-Primeiro elemento de colecção

Descrição

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

Essa função modifica a coleção original.

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

Exemplo

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

.slice()

Histórico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
startFromInteger->Início do índice (incluído)
endInteger->Final do índice (não incluído)
ResultadosCollection<-Nova colecção contendo elementos cortados (cópia superficial)

Descrição

A função .slice() devolve uma parte de uma colecção para uma nova colecção, selected from startFrom index to end index (end not included). Summary --> devolve todos os elementos de uma coleção de objetos que coincidem com as condiciones 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.

Essa função não modifica a coleção original.

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

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

Exemplo

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

.some()

Histórico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetrosTipoDescrição
startFromInteger->Índice para início do teste em
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
paramMixed->Parâmetro(s) a passar
ResultadosBooleano<-True se todos os elementos passarem o teste com sucesso

Descrição

A função .some() retorna true se todos os elementos da coleção passaram com sucesso num teste implementado na fórmula fornecida object ou methodName name.

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

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

A chamada de retorno é chamada com o(s) parâmetro(s) aprovado(s) em param (opcional). A chamada de retorno pode realizar qualquer teste, com ou sem o(s) parâmetro(s) e deve retornar verdadeiro para cada elemento que cumpra o teste. Recebe um objecto no primeiro parâmetro ($1).

A chamada de retorno recebe os seguintes parâmetros:

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

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

  • (obrigatório se você usou um método) $1.result (booleano): true se a avaliação do elemento valor tiver sucesso, senão seráfalse.
  • $1.stop (boolean, opcional): true para parar o callback do método. O valor retornado é o último calculado.

Em todos os casos, no ponto em que a função .some() encontra o primeiro elemento de recolha avaliado para false, deixa de chamar a chamada de retorno e devolve true.

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

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

Exemplo

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

 var $c : Collection
var $b : Boolean
$c:=New collection
$c.push(-5;-3;-1;-4;-6;-2)
$b:=$c.some(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órico
VersãoMudanças
v19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetrosTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome de um método
extraParamany->Parâmetros para o método
ResultadosCollection<-Colecção original ordenada

Descrição

A função .sort() ordena os elementos da coleção original e também devolve a coleção ordenada .

Essa função modifica a coleção original.

Se .sort() for chamado sem parâmetros, apenas valores escalares (número, texto, data, booleanos) são ordenados. Os elementos são classificados por defeito em ordem ascendente, de acordo com o seu tipo.

Se quiser ordenar os elementos da colecção noutra ordem ou ordenar qualquer tipo de elemento, deve fornecer em fórmula (Formula object) ou methodName (Text) uma chamada de comparação que compara dois valores e retorna true se o primeiro valor for inferior ao segundo valor. Pode fornecer parâmetros adicionais para a chamada de retorno, se necessário.

A chamada de retorno recebe os seguintes parâmetros:

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

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

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

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.

  1. null
  2. booleans
  3. strings
  4. números
  5. objetos
  6. collections
  7. datas

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() //numerical sort: [4,33,66,222,1111]
$col3:=$col.sort(Formula(String($1.value)<String($1.value2))) //ordem alfabética: [1111,222,33,4,66]

.sum()

Histórico
VersãoMudanças
v16 R6Adicionado

.sum( { propertyPath : Text } ) : Real

ParâmetrosTipoDescrição
propertyPathText->Rota de propriedade objeto a ser usado para cálculos
ResultadosReal<-Soma dos valores da colecção

Descrição

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

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

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

.sum() retorna 0 se:

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

Exemplo 1

 var $col : 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órico
VersãoMudanças
v16 R6Adicionado

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

ParâmetrosTipoDescrição
valueText, Number, Object, Collection, Date, Boolean->Valor(es) a inserir no início da colecção
ResultadosReal<-Colecção contendo elemento(s) adicionado(s)

Descrição

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

Essa função modifica a coleção original.

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]