Saltar para o conteúdo principal
Versão: 20 R6 BETA

Collection

A classe Collection gerencia variáveis do tipo [Collection] (Concepts/dt_collection.md).

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
returns a new collection containing the elements of the original collection with all elements of the value parameter added to the end
.copy() : Collection
.copy( option : Integer ) : Collection
.copy( option : Integer ; groupWithCol : Collection ) : Collection
.copy( option : Integer ; groupWithObj : Object ) : Collection

returns a deep copy of the collection instance
.count( { propertyPath : Text } ) : Real
returns the number of non-null elements in the collection
.countValues( value : any {; propertyPath : Text } ) : Real
returns the number of times value is found in the collection
.distinct( {options : Integer} ) : Collection
.distinct( propertyPath : Text {; options : Integer } ) : Collection

returns a collection containing only distinct (different) values from the original collection
.equal( collection2 : Collection {; option : Integer } ) : Boolean
recursively compares the contents of the collection and collection2 (deep comparison)
.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
.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
converts all elements of the collection to strings and concatenates them using the specified delimiter string as separator
.last() : any
returns the last element of the collection
.lastIndexOf( toSearch : expression { ; startFrom : Integer } ) : Integer
searches the toSearch expression among collection elements and returns the index of the last occurrence
.length : Integer
returns the number of elements in the collection
.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
returns the element with the highest value in the collection
.min( { propertyPath : Text } ) : any
returns the element with the smallest value in the collection
.multiSort() : Collection
.multiSort( colsToSort : Collection ) : Collection
.multiSort( formula : 4D.Function ; colsToSort : Collection ) : Collection

enables you to carry out a multi-level synchronized sort on a set of collections
.orderBy( ) : Collection
.orderBy( pathStrings : Text ) : Collection
.orderBy( pathObjects : Collection ) : Collection
.orderBy( ascOrDesc : Integer ) : Collection

returns a new collection containing all elements of the collection in the specified order
.orderByMethod( formula : 4D.Function { ; ...extraParam : expression } ) : Collection
.orderByMethod( methodName : Text { ; ...extraParam : expression } ) : Collection

returns a new collection containing all elements of the collection in the order defined through the formula 4D function or methodName method
.pop() : any
removes the last element from the collection and returns it as the function result
.push( element : any { ;...elementN } ) : Collection
appends one or more element(s) to the end of the collection instance and returns the edited collection
.query( queryString : Text ) : Collection
.query( queryString : Text ; ...value : any ) : Collection
.query( queryString : Text ; querySettings : Object ) : Collection

returns all elements of a collection of objects that match the search conditions
.reduce( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any
.reduce( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any

applies the formula or methodName callback against an accumulator and each element in the collection (from left to right) to reduce it to a single value
.reduceRight( formula : 4D.Function { ; initValue : any { ; ...param : expression }} ) : any
.reduceRight( methodName : Text { ; initValue : any { ; ...param : expression }} ) : any

applies the formula or methodName callback against an accumulator and each element in the collection (from right to left) to reduce it to a single value
.remove( index : Integer { ; howMany : Integer } ) : Collection
removes one or more element(s) from the specified index position in the collection and returns the edited 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
returns a portion of a collection into a new collection
.some( { startFrom : Integer ; } formula : 4D.Function { ; ...param : any } ) : Boolean
.some( { startFrom : Integer ; } methodName : Text { ; ...param : any } ) : Boolean

returns true if at least one element in the collection successfully passed a test implemented in the provided formula or methodName code
.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
inserts the given value(s) at the beginning of the collection

New collection

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

ParâmetroTipoDescrição
valueNumber, Text, Date, Time, Boolean, Object, Collection, Picture, Pointer->Valor(es) de collection
ResultadosCollection<-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.

Lembre-se de que as instruções var : Collection ou C_COLLECTION declaram uma variável do tipo Collection, mas não criam nenhuma 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 í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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescrição
valueNumber, Text, Date, Time, Boolean, Shared object, Shared collection->Valores da collection compartida
ResultadosCollection<-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.

Lembre-se de que as instruções var : Collection ou C_COLLECTION declaram uma variável do tipo Collection, mas não criam nenhuma coleção.

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
ReleaseMudanças
20Adicionado

.at( index : Integer ) : any

ParâmetroTipoDescrição
indexInteger->Índice de elemento a devolver
Resultadosany<-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.

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

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
ReleaseMudanças
v16 R6Adicionado

.average( {propertyPath : Text } ) : Real

ParâmetroTipoDescriçã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 (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
ReleaseMudanças
v16 R6Adicionado

.clear() : Collection

ParâmetroTipoDescrição
ResultadosCollection<-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.

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ória
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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 na posição index especificada na instância da coleção e retorna a coleção editada. Unlike the .insert() function, .combine() adds each value of col2 in the original collection, and not as a single collection element.

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

By default, col2 elements are added at the end of the orginal collection. You can pass in index the position where you want the col2 elements to be inserted in the collection.

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

  • If index > the length of the collection, the actual starting index will be set to the length of the collection.
  • If index < 0, it is recalculated as index:=index+length (it is considered as the offset from the end of the collection).
  • If the calculated value is negative, index is set to 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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescrição
valueNumber, Text, Object, Collection, Date, Time, Boolean, Picture->Valores a concatenar. If value is a collection, all collection elements are added to the original collection
ResultadosCollection<-Nova coleção com valores adicionados à coleção original

Descrição

The .concat() function returns a new collection containing the elements of the original collection with all elements of the value parameter added to the end.

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

If value is a collection, all its elements are added as new elements at the end of the original collection. 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
ReleaseMudanças
18 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âmetroTipoDescrição
optionInteger->ck resolve pointers: resolve ponteiros antes de copiar,
ck shared: retorna uma coleção partilhada
groupWithColCollection->Coleção partilhada a ser agrupada com a coleção resultante
groupWithObjObject->Objeto partilhado a ser agrupado com a coleção resultante
ResultadosCollection<-Cópia profunda da collection original

Descrição

The .copy() function returns a deep copy of the collection instance.Deep copy means that objects or collections within the original collection are duplicated and do not share any reference with the returned collection.

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

If passed, the option parameter can contain one of the following constants (or both):

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. However, you can resolve pointers when copying by passing the ck resolve pointers constant. Nesse caso, cada ponteiro presenta na coleção é avaliada quando copiar e seu valor de dereferencia é usado.
ck sharedBy default, copy() returns a regular (not shared) collection, even if the command is applied to a shared collection. Passe a constante ck shared para criar uma coleção compartilhada. In this case, you can use the groupWith parameter to associate the shared collection with another collection or object (see below).

The groupWithCol or groupWithObj parameters allow you to designate a collection or an object with which the resulting collection should be associated.

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

We want to copy the $lastnames regular (non shared) collection into the $sharedObject shared object. To do this, we must create a shared copy of the collection ($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

We want to combine $sharedColl1 and $sharedColl2. Já que pertencem a grupos partilhados diferentes, uma combinação diferente resultaria em um erro. Therefore, we must make a shared copy of $sharedColl1 and designate $sharedColl2 as a shared group for the copy.

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. To do this, we must create a shared copy beforehand ($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
ReleaseMudanças
v16 R6Adicionado

.count( { propertyPath : Text } ) : Real

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

Descrição

The .count() function returns the number of non-null elements in the collection.

If the collection contains objects, you can pass the propertyPath parameter. In this case, only elements that contain the propertyPath are taken into account.

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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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

The .countValues() function returns the number of times value is found in the collection.

Você pode passar em value:

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

For an element to be found, the type of value must be equivalent to the type of the element; the method uses the equality operator.

The optional propertyPath parameter allows you to count values inside a collection of objects: pass in propertyPath the path of the property whose values you want to count.

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ória
ReleaseMudanças
20Suporte do ck count values
v16 R6Adicionado

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

ParâmetroTipoDescrição
propertyPathText->Rota do atributo cujos valores quer obter
optionsInteger->ck diacritical, ck count values
ResultadosCollection<-Nova coleção com apenas valores distintos

Descrição

The .distinct() function returns a collection containing only distinct (different) values from the original collection.

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

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

If the collection contains objects, you can pass the propertyPath parameter to indicate the object property whose distinct values you want to get.

In the options parameter, you can pass one or a combination of the following constants:

ParâmetrosValorComentário
ck diacritical8A 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 values32Devolve a contagem de elementos para cada valor distinto. When this option is passed, .distinct() returns a collection of objects containing a pair of {"value":*value*;"count":*count*} attributes.

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
ReleaseMudanças
v16 R6Adicionado

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

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

Descrição

The .equal() function recursively compares the contents of the collection and collection2 (deep comparison)and returns true if they are identical.

Notas
  • The .equal() function only checks equality for string, boolean, number, and null type elements in the collections. Ele não verifica a igualdade dos objetos nativos.
  • 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. If you want the evaluation to be case sensitive or to differentiate accented characters, pass the ck diacritical constant in the option parameter.

tip

A recursive comparison of collections can be time-consuming if the collection is large and deep. If you only want to compare two collection references, you may consider using the = comparison operator for collection references.

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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
startFromInteger->Índice para início do teste em
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
paramany->Parâmetro(s) a ser(em) passado(s) para formula ou methodName
ResultadosParâ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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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: include null properties na coleção retornada (ignorado por padrão). Parâmetro ignorado se targetPath for passado.
ResultadosCollection<-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.

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. 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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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 value especificado, opcionalmente do índice startFrom até o índice end, e retorna 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 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.
  • If end < startFrom (passed or calculated values), the method does nothing.

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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
paramany->Parâmetro(s) a ser(em) passado(s) para formula ou methodName
ResultadosCollection<-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.

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:

  • 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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
startFromInteger->Índice onde inicia a pesquisa
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
paramany->Parâmetro(s) a ser(em) passado(s) para formula ou methodName
Resultadosany<-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.

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:

  • 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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
startFromInteger->Índice onde inicia a pesquisa
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
paramany->Parâmetro(s) a ser(em) passado(s) para formula ou methodName
ResultadosInteger<-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.

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:

  • 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
ReleaseMudanças
20Adicionado

.first() : any

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

Descrição

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

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

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
ReleaseMudanças
20Adicionado

.flat( { depth : Integer } ) : Collection

ParâmetroTipoDescrição
depthInteger->A profundidade a que uma estrutura de colecção aninhada deve ser aplanada. O padrão=1
ResultadosCollection<-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.

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

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
ReleaseMudanças
20Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
paramany->Parâmetro(s) a ser(em) passado(s) para formula ou methodName
ResultadosCollection<-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.

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:

  • 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
ReleaseMudanças
20Adicionado

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

ParâmetroTipoDescrição
toSearchexpressão->Expressão a pesquisar na coleção
startFromInteger->Índice onde inicia a pesquisa
ResultadosParâ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.

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),
  • $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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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() 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.

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),
  • $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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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 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.

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

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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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 element na posição index especificada na instância da coleção e retorna 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 de coleção são numerados a partir de 0.

  • If index > the length of the collection, actual starting index will be set to the length of the collection.
  • If index <0, it is recalculated as index:=index+length (it is considered as the offset from the end of the collection).
  • 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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescrição
delimiterText->Separador a usar entre os elementos
optionInteger->ck ignore null or empty: ignore null and empty strings in the result
ResultadosText<-String contendo todos os elementos da coleção, separados por um delimitador

Descrição

The .join() function converts all elements of the collection to strings and concatenates them using the specified delimiter string as separator.The function returns the resulting string.

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. Pass the ck ignore null or empty constant in the option parameter if you want to remove them from the resulting string.

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
ReleaseMudanças
20Adicionado

.last() : any

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

Descrição

The .last() function returns the last element of the collection.

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

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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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

The .lastIndexOf() function searches the toSearch expression among collection elements and returns the index of the last occurrence, or -1 if it was not found.

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),
  • $1.result:=$1.value>0
  • um objeto ou uma referência de coleção.

toSearch must match exactly the element to find (the same rules as for the equality operator are applied).

Optionally, you can pass the index of collection from which to start a reverse search in startFrom.

  • If startFrom >= the collection's length minus one (coll.length-1), the whole collection is searched (default).
  • 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.
  • If startFrom = 0, -1 is returned, which means the collection is not searched.

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
ReleaseMudanças
v16 R5Adicionado

.length : Integer

Descrição

The .length property returns the number of elements in the collection.

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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
paramany->Parâmetro(s) a ser(em) passado(s) para formula ou methodName
ResultadosCollection<-Collection de valores transformados

Descrição

The .map() function creates a new collection based upon the result of the call of the formula 4D function or methodName method on each element of the original collection. Opcionalmente, você pode passar parâmetros para formula ou methodName usando o(s) parâmetro(s) param. .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:

  • 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

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

.max()

História
ReleaseMudanças
v16 R6Adicionado

.max( { propertyPath : Text } ) : any

ParâmetroTipoDescriçã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

The .max() function returns the element with the highest value in the collection (the last element of the collection as it would be sorted in ascending order using the .sort() function).

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

If the collection contains different types of values, the .max() function will return the maximum value within the last element type in the type list order (see .sort() description).

If the collection contains objects, pass the propertyPath parameter to indicate the object property whose maximum value you want to get.

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
ReleaseMudanças
v16 R6Adicionado

.min( { propertyPath : Text } ) : any

ParâmetroTipoDescriçã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

The .min() function returns the element with the smallest value in the collection (the first element of the collection as it would be sorted in ascending order using the .sort() function).

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

If the collection contains different types of values, the .min() function will return the minimum value within the first element type in the type list order (see .sort() description).

If the collection contains objects, pass the propertyPath parameter to indicate the object property whose minimum value you want to get.

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
ReleaseMudanças
20 R3Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
colsToSortCollection->Collection of collections and/or objects with {collection:colToSort;order:ck ascending or ck descending} properties
ResultadosCollection<-Colecção original ordenada

Descrição

The .multiSort() function enables you to carry out a multi-level synchronized sort on a set of collections.

This function modifies the original collection as well as all collections used in colsToSort parameter.

If .multiSort() is called with no parameters, the function has the same effect as the .sort() function: the collection is sorted (only scalar values) in ascending order by default, according to their type. 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.

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

Classificação sincronizada de nível único

To sort several collections synchronously, just pass in colsToSort a collection of collections to sort. Você pode passar um número ilimitado de coleções. The original collection will be sorted in ascending order and all colsToSort collections will be sorted in a synchronized manner.

nota

All colsToSort collections must have the same number of elements, otherwise an error is returned.

If you want to sort the collections in some other order than ascending, you must supply a formula (Formula object that defines the sort order. The return value should be a boolean that indicates the relative order of the two elements: True if $1.value is less than $1.value2, False if $1.value is greater than $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 (any type): first element value to be compared
    • $1.value2 (any type): second element value to be compared
  • $2...$N (qualquer tipo): parâmetros adicionais

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

Defining a multi-level synchronized sort requires that you pass an object containing {collection:colToSort;order:ck ascending or ck descending} properties instead of the colToSort itself for every collection to use as sub-level.

The sort levels are determined by the order in which the collections are passed in the colsToSort parameter: the position of a collection/order object in the syntax determines its sort level.

nota

The .multiSort() function uses a stable sort algorithm.

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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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

The .orderBy() function returns a new collection containing all elements of the collection in the specified order.

This function returns a shallow copy, which means that objects or collections in both collections share the same reference. 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.

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). You can modify this automatic order by passing the ck ascending or ck descending constants in the ascOrDesc parameter (see below).

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 contains a formula made of 1 to x property paths and (optionally) sort orders, separated by commas. 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. You can add as many objects in the pathObjects collection as necessary. 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âmetrosTipoValorComentá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; $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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
extraParamany->Parâmetro(s) a transmitir
ResultadosCollection<-Cópia ordenada da coleção (cópia superficial)

Descrição

The .orderByMethod() function returns a new collection containing all elements of the collection in the order defined through the formula 4D function or methodName method.

This function returns a shallow copy, which means that objects or collections in both collections share the same reference. 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:

  • 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 (any type): first element value to be compared
    • $1.value2 (any type): second element value to be compared
    • $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
ReleaseMudanças
v16 R6Adicionado

.pop() : any

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

Descrição

The .pop() function removes the last element from the collection and returns it as the function result.

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

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

Exemplo

.pop(), used in conjunction with .push(), can be used to implement a first-in, last-out stack feature:

 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
ReleaseMudanças
v16 R6Adicionado

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

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

Descrição

The .push() function appends one or more element(s) to the end of the collection instance and returns the edited collection.

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

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
ReleaseMudanças
20 R6Support of queries using object or collection references
17 R5Assistência de querySettings
v16 R6Adicionado

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

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

Descrição

The .query() function returns all elements of a collection of objects that match the search conditions 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.

An empty collection is returned if the collection in which the query is executed does not contain the searched value.

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

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çãoSímbolosComentário
Igual a=, ==Retorna os dados coincidentes, admite o coringa (@), não diferencia entre maiúsculas e minúsculas nem diacríticas.
===, ISRetorna 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 NOTConsidera @ como um caractere normal
Não se aplica à condição de uma sentençaNOTParentesis 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 emINRetorna 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çãoSí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'"

Aspas siples (') não são permitidas nos valores pesquisados, já que quebrariam a string de pesquisa. Por exemplo, "comp.name = 'John's pizza' " gerará um erro. Se precisar pesquisar valores com aspas simples, pode considerar o uso de placeholders (ver abaixo).

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 allows you to use placeholders for propertyPath and value arguments within the queryString parameter. 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: parameters are inserted as :paramName (for example ":myparam") and their values are provided in the "attributes" and/or "parameters" objects in the querySettings parameter.

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:

  1. 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á.

  1. It prevents having to worry about formatting or character issues, especially when handling propertyPath or value parameters that might contain non-alphanumeric characters such as ".", "['...

  2. 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")

O uso de uma referência de coleção ou referência de objeto no parâmetro value não é compatível com essa sintaxe. Você deve usar o parâmetro [querySettings] (#querysettings-parameter).

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

You can query a collection using an object reference or a collection reference as the value parameter to compare. 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çãoSímbolos
Igual a=, ==
Diferente de#, !=

To build a query with an object or a collection reference, you must use the querySettings parameter syntax. Exemplo com uma referência de objeto:

var $o1:={a: 1}
var $o2:={a: 1} //same object but another reference
var $o3:=$o1 //same object and reference

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

In the querySettings parameter, you can pass an object containing query placeholders as objects. As propriedades abaixo são compatíveis:

PropriedadeTipoDescrição
parametersObjectPlaceholders com nome para os valores usados na queryString. Values are expressed as property / value pairs, where property is the placeholder name inserted for a value in the queryString (":placeholder") and value is the value to compare. 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.
attributesObjectPlaceholders nomeados para os caminhos de atributos usados na queryString. Attributes are expressed as property / value pairs, where property is the placeholder name inserted for an attribute path in the queryString (":placeholder"), and value can be a string or a collection of strings. Each value is a path that can designate a property in an object of the collection
TypeDescription
StringattributePath expressed using the dot notation, e.g. "name" or "user.address.zipCode"
Collection of stringsEach string of the collection represents a level of attributePath, e.g. ["name"] or ["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.

Using this parameter is mandatory if you want to query a collection using a collection reference or object reference.

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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
initValueText, Number, Object, Collection, Date, Boolean->Value to use as the first argument to the first call of formula or methodName
paramexpressão->Parâmetro(s) a transmitir
ResultadosText, Number, Object, Collection, Date, Boolean<-Resultado do valor do acumulador

Descrição

The .reduce() function applies the formula or methodName callback against an accumulator and each element in the collection (from left to right) to reduce it to a single value.

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:

  • 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).

The callback takes each collection element and performs any desired operation to accumulate the result into $1.accumulator, which is returned in $1.value.

Pode passar o valor para inicializar o acumulador em initValue. If omitted, $1.accumulator starts with 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: value to be modified by the function and which is initialized by 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
ReleaseMudanças
20Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
initValueText, Number, Object, Collection, Date, Boolean->Value to use as the first argument to the first call of formula or methodName
paramexpressão->Parâmetro(s) a transmitir
ResultadosText, Number, Object, Collection, Date, Boolean<-Resultado do valor do acumulador

Descrição

The .reduceRight() function applies the formula or methodName callback against an accumulator and each element in the collection (from right to left) to reduce it to a single value.

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:

  • 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).

The callback takes each collection element and performs any desired operation to accumulate the result into $1.accumulator, which is returned in $1.value.

Pode passar o valor para inicializar o acumulador em initValue. If omitted, $1.accumulator starts with 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: value to be modified by the function and which is initialized by 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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescrição
indexInteger->Elemento no qual que se inicia a eliminação
howManyInteger->Número de elementos a eliminar, ou 1 elemento se omitir
ResultadosCollection<-Modified collection without removed element(s)

Descrição

The .remove() function removes one or more element(s) from the specified index position in the collection and returns the edited collection.

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 de coleção são numerados a partir de 0. If index is greater than the length of the collection, actual starting index will be set to the length of the collection.

  • If index < 0, it is recalculated as index:=index+length (it is considered as the offset from the end of the collection).
  • Se o valor calculado for < 0, index será definido como 0.
  • If the calculated value > the length of the collection, index is set to the length.

Em howMany, passe o número de elementos a serem removidos de index. If howMany is not specified, then one element is removed.

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
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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

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

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

  • If size < collection length, exceeding elements are removed from the collection.
  • Se size > comprimento da coleção, o comprimento da coleção é aumentado à medida.

Por padrão, novos elementos são preenchidos com valores null. You can specify the value to fill in added elements using the defaultValue parameter.

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
ReleaseMudanças
v16 R6Adicionado

.reverse( ) : Collection

ParâmetroTipoDescrição
ResultadosCollection<-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.

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

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
ReleaseMudanças
v16 R6Adicionado

.shift() : any

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

Descrição

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

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ória
ReleaseMudanças
v16 R6Adicionado

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

ParâmetroTipoDescriçã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

The .slice() function returns a portion of a collection into a new collection, selected from startFrom index to end index (end not included). This function returns a shallow copy of the collection. 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.

The returned collection contains the element specified by startFrom and all subsequent elements up to, but not including, the element specified by end. If only the startFrom parameter is specified, the returned collection contains all elements from startFrom to the last element of the original collection.

  • Se startFrom < 0, ele é recalculado como startFrom:=startFrom+length (é considerado como o deslocamento a partir do final da coleção).
  • If the calculated value < 0, startFrom is set to 0.
  • Se end < 0 , ele será recalculado como end:=end+length.
  • If end < startFrom (passed or calculated values), the method does nothing.

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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição

|startFrom |Integer |->|Index to start the test at| |formula|4D.Function|->|Formula object| |methodName|Text|->|Name of a method| |param |any |->|Parameter(s) to pass| |Result|Boolean|<-|True if at least one element successfully passed the test|

Descrição

The .some() function returns true if at least one element in the collection successfully passed a test implemented in the provided formula or methodName code.

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

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

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

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. Optionally, you can pass the index of an element from which to start the test in startFrom.

  • Se startFrom >= tamanho da coleção, é retornado False, o que significa que a coleção não é testada.

  • If startFrom < 0, it is considered as the offset from the end of the collection.

  • 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
ReleaseMudanças
19 R6Compatibilidade de fórmula
v16 R6Adicionado

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

ParâmetroTipoDescrição
formula4D. Function->Objecto fórmula
methodNameText->Nome da função a qual se chama para processar os elementos da coleção
extraParamany->Parâmetros para o método
ResultadosCollection<-Colecção original ordenada

Descrição

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

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

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.

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

If you want to sort the collection elements in some other order or sort any type of element, you must supply in formula (Formula object) or methodName (Text) a callback that defines the sort order. The return value should be a boolean that indicates the relative order of the two elements: True if $1.value is less than $1.value2, False if $1.value is greater than $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 (any type): first element value to be compared
    • $1.value2 (any type): second element value to be compared
  • $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
ReleaseMudanças
v16 R6Adicionado

.sum( { propertyPath : Text } ) : Real

ParâmetroTipoDescrição
propertyPathText->Rota de propriedade objeto a ser usado para cálculos
ResultadosReal<-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
ReleaseMudanças
v16 R6Adicionado

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

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

Descrição

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

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]