up previous next
Define

define a function

Syntax
Define F(X_1,...,X_n) Help S:STRING; C EndDefine
F(X_1,...,X_n) := E
Define F(...) Help S:STRING; C EndDefine

where F is an identifier, C is a sequence of commands, the X_i's are
formal parameters and E is an expression.  The third form, which
literally includes the string ... is used for a variable number of
parameters.  The optional Help S, where S is a string, may be added
to provide help for the user.

Description
1. INTRODUCTION. This command adds the user-defined function F to the library. The function F can be called in the following way:
    F(E_1,...,E_n)
where the E_i's are expressions. The result of the evaluation of each expression E_i is assigned to the respective formal parameter X_i, and the command sequence C is executed. If, during the execution of C, a statement Return E is executed, then the result of the evaluation of E is the return-value of the function F. If no Return command is executed, or Return is executed without argument, then the return-value is Null.

Example
Define Square(X)
  Return X^2;
EndDefine;

Square(5);
25
------------------------------- 
2. SCOPE. Every variable defined or modified by the command sequence C is considered local to the function unless the variable is global or relative to a Var parameter. For the use of global variables, see Global Memory or the example below. See Var to learn about calling a function by reference, i.e. so that the function can change the value of an existing variable.

Example
Define Example_1(L)
  L := L + 5;
  Return L;
EndDefine;
L := 0;
Example_1(L);
5
-------------------------------
L;  -- L is unchanged despite the function call.
0
-------------------------------
Define Example_2(L)  -- Example using a global variable.
  MEMORY.X := L + 3;
EndDefine;
Example_2(10);
MEMORY.X;
13
------------------------------- 
3. VARIABLE NUMBER OF PARAMETERS. It is also possible to have a variable number of parameters using the syntax
    Define F(...) Help S:STRING; C EndDefine;
In this case the special variable ARGV will contain the list of the arguments passed to the function. (The statement, Help S; is optional.)

Example
Define Sum(...)
  If Len(ARGV) = 0 Then Return Null;  -- empty sum
  Else
    Sum := 0;
    Foreach N In ARGV Do Sum := Sum+N EndForeach;
  EndIf;
  Return Sum; 
EndDefine;
Sum(1,2,3,4,5);
15
-------------------------------
Sum();
Null
------------------------------- 
4. SHORTCUT. The form F(X_1,...,X_n) := E is discouraged and may be discontinued in later versions of CoCoA. If is shorthand for Define F(X_1,...X_n) Return E EndDefine;

Example
F(X) := X^2;
F(5);
25
------------------------------- 
5. HELP. Inside a user-defined function, one may add the command:
  Help S;
where S is a string. Then, when a user enters Help("F") where F is the identifier for the function, the string, S, is printed.

Example
Define Test(N)
  Help "Usage: Test(N:INT):INT";
  Return N;
EndDefine;
Help "Test";
Usage: Test(N:INT):INT
------------------------------- 
6. DEFINING RINGS INSIDE FUNCTIONS. For information on this topic, please see the section of the tutorial entitled, Rings Inside User-Defined Functions

See Also