previous  next
Define
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.
Summary
define a function
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.) 

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
-------------------------------

NOTE: The use of the following shorthand is discouraged and may be
discontinued in later versions of CoCoA.
4. SHORTCUT.  The form 'F(X_1,...,X_n) := E' 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: