% This file was created automatically from function.msk.
% DO NOT EDIT!
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%W  function.msk           GAP documentation                Alexander Hulpke
%%
%H  @(#)$Id: function.msk,v 1.6.4.1 2005/05/05 09:15:47 gap Exp $
%%
%Y  Copyright 1999
%%
%%  This file describes functions for functions.
%%
\Chapter{Functions}

\index{functions}
The section~"Function" describes how to define a function. In this chapter
we describe functions that give information about functions, and various
utility functions used either when defining functions or calling functions.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Information about a function}

\>NameFunction( <func> ) F

returns the name of a function. For operations, this is the name used in
their declaration. For functions, this is the variable name they were
first assigned to. (For some internal functions, this might be a name
*different* from the name that is documented.)
If no such name exists, `"unknown"' is returned.

\beginexample
gap> NameFunction(SylowSubgroup);
"SylowSubgroup"
gap> Blubberflutsch:=x->x;;
gap> NameFunction(Blubberflutsch);
"Blubberflutsch"
gap> a:=Blubberflutsch;;
gap> NameFunction(a);
"Blubberflutsch"
gap> NameFunction(x->x);
"unknown"
gap> NameFunction(NameFunction);
"NAME_FUNC"
\endexample

\>NumberArgumentsFunction( <func> ) F

returns the number of arguments the function <func> accepts. For
functions that use `arg' to take a variable number of arguments, as well
as for operations, -1 is returned. For attributes, 1 is returned.

\beginexample
gap> NumberArgumentsFunction(function(a,b,c,d,e,f,g,h,i,j,k)return 1;end);
11
gap> NumberArgumentsFunction(Size);
1
gap> NumberArgumentsFunction(IsCollsCollsElms);
3
gap> NumberArgumentsFunction(Sum);
-1
\endexample

\>NamesLocalVariablesFunction( <func> ) F

returns a mutable list of strings;
the first entries are the names of the arguments of the function <func>,
in the same order as they were entered in the definition of <func>,
and the remaining ones are the local variables as given in the `local'
statement in <func>.
(The number of arguments can be computed with `NumberArgumentsFunction'.)


\beginexample
gap> NamesLocalVariablesFunction( function( a, b ) local c; return 1; end );
[ "a", "b", "c" ]
gap> NamesLocalVariablesFunction( function( arg ) local a; return 1; end );
[ "arg", "a" ]
gap> NamesLocalVariablesFunction( Size );
fail
\endexample


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Calling a function with a list argument that is interpreted as
several arguments}

\>CallFuncList( <func>, <args> ) F

returns the result, when calling function <func> with the arguments
given in the list <args>, i.e.~<args> is ``unwrapped'' so that <args> 
appears as several arguments to <func>.

\beginexample
gap> CallFuncList(\+, [6, 7]);
13
gap> #is equivalent to:
gap> \+(6, 7);
13
\endexample

A more useful application of `CallFuncList' is for a function <g> that is
called in the body of a function <f> with (a sublist of) the arguments of
<f>, where <f> has been defined  with  a  single  formal  argument  `arg'
(see~"function"); see the following code fragment.

\begintt
f := function ( arg )
       CallFuncList(g, arg);
       ...
     end;
\endtt

In the body of <f> the several arguments passed  to  <f>  become  a  list
`arg'. If <g> were called instead via `<g>( arg )' then <g> would  see  a
single list argument, so that <g> would, in general, have  to  ``unwrap''
the  passed  list.  The  following  (not  particularly  useful)   example
demonstrates both described possibilities for the call to <g>.

\beginexample
gap> PrintNumberFromDigits := function ( arg )
>     CallFuncList( Print, arg );
>     Print( "\n" );
>    end;
function( arg ) ... end
gap> PrintNumberFromDigits( 1, 9, 7, 3, 2 );
19732
gap> PrintDigits := function ( arg )
>     Print( arg );
>     Print( "\n" );
>    end;
function( arg ) ... end
gap> PrintDigits( 1, 9, 7, 3, 2 );
[ 1, 9, 7, 3, 2 ]
\endexample

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Functions that do nothing}

The following functions return fixed results (or just their own argument).
They can be useful in places when the syntax requires a function, but
actually no functionality is required. So `ReturnTrue' is often used as
family predicate in `InstallMethod'
(see~"prg:InstallMethod" in ``Programming in {\GAP}'').

\>ReturnTrue( ... ) F

This function takes any number of arguments, and always returns `true'.

\>ReturnFalse( ... ) F

This function takes any number of arguments, and always returns `false'.

\>ReturnFail( ... ) F

This function takes any number of arguments, and always returns `fail'.

\>IdFunc( <obj> ) F

returns <obj>.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\Section{Function Types}

Functions are {\GAP} objects and thus have categories and a family.

\>IsFunction( <obj> ) C

is the category of functions.

\>IsOperation( <obj> ) C

is the category of operations. Every operation is a function, but not
vice versa.

\>`FunctionsFamily' V

is the family of all functions.