Function

A 4D.Function object contains a piece of code that can be executed from an object, either using the () operator, or using the apply() and call() functions. 4D proposes three kinds of Function objects:

• native functions, i.e. built-in functions from various 4D classes such as collection.sort() or file.copyTo().
• user functions, created in user classes using the Function keyword.
• formula functions, i.e. functions that can execute any 4D formula.

Formula objects

The Formula and Formula from string commands allow you to create 4D.Function objects to execute any 4D expression or code expressed as text.

Formula objects can be encapsulated in object properties:

 var $f : 4D.Function
 $f:=New object
 $f.message:=Formula(ALERT("Hello world"))

This property is an "object function", i.e. a function which is bound to its parent object. To execute a function stored in an object property, use the () operator after the property name, such as:

 $f.message() //displays "Hello world"

Syntax with brackets is also supported:

 $f["message"]() //displays "Hello world"

Note that, even if it does not have parameters (see below), an object function to be executed must be called with ( ) parenthesis. Calling only the object property will return a new reference to the formula (and will not execute it):

 $o:=$f.message //returns the formula object in $o

You can also execute a function using the apply() and call() functions:

 $f.message.apply() //displays "Hello world"

Passing parameters

You can pass parameters to your formulas using the sequential parameter syntax based upon $1, $2...$n. For example, you can write:

 var $f : Object
 $f:=New object
 $f.message:=Formula(ALERT("Hello "+$1))
 $f.message("John") //displays "Hello John"

Or using the .call() function:

 var $f : Object
 $f:=Formula($1+" "+$2)
 $text:=$f.call(Null;"Hello";"World") //returns "Hello World"
 $text:=$f.call(Null;"Welcome to";String(Year of(Current date))) //returns "Welcome to 2019" (for example)

Parameters to a single method

For more convenience, when the formula is made of a single project method, parameters can be omitted in the formula object initialization. They can just be passed when the formula is called. For example:

 var $f : 4D.Function

 $f:=Formula(myMethod)
  //Writing Formula(myMethod($1;$2)) is not necessary
 $text:=$f.call(Null;"Hello";"World") //returns "Hello World"
 $text:=$f.call() //returns "How are you?"

  //myMethod
 #DECLARE ($param1 : Text; $param2 : Text)->$return : Text
 If(Count parameters=2)
    $return:=$param1+" "+$param2
 Else
    $return:="How are you?"
 End if

Parameters are received within the method, in the order they are specified in the call.

Summary

.apply() : any .apply( thisObj : Object { ; formulaParams : Collection } ) : any executes the formula object to which it is applied and returns the resulting value
.call() : any .call( thisObj : Object { ; ...params : any } ) : any executes the formula object to which it is applied and returns the resulting value
.source : Text contains the source expression of the formula as text

.apply()

History

Release	Changes
17 R3	Added

.apply() : any
.apply( thisObj : Object { ; formulaParams : Collection } ) : any

Parameter	Type		Description
thisObj	Object	->	Object to be returned by the This command in the formula
formulaParams	Collection	->	Collection of values to be passed as $1...$n when formula is executed
Result	any	<-	Value from formula execution

Description

The .apply() function executes the formula object to which it is applied and returns the resulting value. The formula object can be created using the Formula or Formula from string commands.

In the thisObj parameter, you can pass a reference to the object to be used as This within the formula.

You can also pass a collection to be used as $1...$n parameters in the formula using the optional formulaParams parameter.

Note that .apply() is similar to .call() except that parameters are passed as a collection. This can be useful for passing calculated results.

Example 1

 var $f : 4D.Function
 $f:=Formula($1+$2+$3)

 $c:=New collection(10;20;30)
 $result:=$f.apply(Null;$c) // returns 60

Example 2

 var $calc : 4D.Function
 var $feta; $robot : Object
 $robot:=New object("name";"Robot";"price";543;"quantity";2)
 $feta:=New object("name";"Feta";"price";12.5;"quantity";5)

 $calc:=Formula(This.total:=This.price*This.quantity)

 $calc.apply($feta) // $feta={name:Feta,price:12.5,quantity:5,total:62.5}
 $calc.apply($robot) // $robot={name:Robot,price:543,quantity:2,total:1086}

.call()

History

Release	Changes
17 R3	Added

.call() : any
.call( thisObj : Object { ; ...params : any } ) : any

Parameter	Type		Description
thisObj	Object	->	Object to be returned by the This command in the formula
params	any	->	Value(s) to be passed as $1...$n when formula is executed
Result	any	<-	Value from formula execution

Description

The .call() function executes the formula object to which it is applied and returns the resulting value. The formula object can be created using the Formula or Formula from string commands.

In the thisObj parameter, you can pass a reference to the object to be used as This within the formula.

You can also pass values to be used as $1...$n parameters in the formula using the optional params parameter(s).

Note that .call() is similar to .apply() except that parameters are passed directly.

Example 1

 var $f : 4D.Function
 $f:=Formula(Uppercase($1))
 $result:=$f.call(Null;"hello") // returns "HELLO"

Example 2

 $o:=New object("value";50)
 $f:=Formula(This.value*2)
 $result:=$f.call($o) // returns 100

.source

History

Release	Changes
18 R2	Added

.source : Text

Description

The .source property contains the source expression of the formula as text.

This property is read-only.

Example

 var $of : 4D.Function
 var $tf : Text
 $of:=Formula(String(Current time;HH MM AM PM))
 $tf:=$of.source //"String(Current time;HH MM AM PM)"