collection.find( )

Home

4D v19.8

collection.find( )


collection.find ( {startFrom ;} methodName {; param {; param2 ; ... ; paramN}} ) -> Function result

Parameter	Type	Description
startFrom	Longint	Index to start the search at
methodName	Text	Name of the function to call for the find
param	Expression	Parameter(s) to pass to methodName
Function result		First value found, or Undefined if not found

Description

The collection.find( ) method returns the first value in the collection for which methodName, applied on each element, returns true.

Note: This method does not modify the original collection.

By default, collection.find( ) searches in the whole collection. Optionally, you can pass in startFrom the index of element from which to start the search.

If startFrom >= the collection's length, -1 is returned, which means the collection is not searched.
If startFrom < 0, it is considered as the offset from the end of the collection (startFrom:=startFrom+length).
Note: Even if startFrom is negative, the collection is still searched from left to right.
If startFrom = 0, the whole collection is searched (default).

In methodName, pass the name of the method to use to evaluate collection elements, along with its parameter(s) in param (optional). methodName can perform any test, with or without the parameter(s). This method receives an Object parameter in $1 and must set $1.result to true for the first element fulfilling the condition.

methodName receives the following parameters:

in $1.value: element value to be evaluated
in $2: param
in $N...: param2...paramN

methodName sets the following parameter(s):

$1.result (boolean): true if the element value matches the search condition.
$1.stop (boolean, optional): true to stop the method callback. The returned value is the last calculated.

Example 1

You want to get the first element with a length smaller than 5:

 C_COLLECTION($col)

 $col:=New collection("hello";"world";4;"red horse";"tim";"san jose")

 $value:=$col.find("LengthLessThan";5) //$value="tim"

The code for LengthLessThan method is:

 C_OBJECT($1)

 C_LONGINT($2)

 If(Value type($1.value)=Is text)

    $1.result:=(Length($1.value))<$2

 End if

Example 2

You want to find a city name within a collection:

 C_COLLECTION($c)

 $c:=New collection

 $c.push(New object("name";"Cleveland";"zc";35049))

 $c.push(New object("name";"Blountsville";"zc";35031))

 $c.push(New object("name";"Adger";"zc";35006))

 $c.push(New object("name";"Clanton";"zc";35046))

 $c.push(New object("name";"Clanton";"zc";35045))

 $c2:=$c.find("FindCity";"Clanton") //$c2={name:Clanton,zc:35046}

The code for the FindCity method is:

 C_OBJECT($1)

 C_TEXT($2)

 $1.result:=$1.value.name=$2 //name is a property name of objects in the collection