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