5 Functions
  
  The  section 4.11  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.
  
  
  5.1 Information about a function
  
  5.1-1 NameFunction
  
  NameFunction( func )  attribute
  
  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, the string
  "unknown" is returned.
  
    Example  
    gap> NameFunction(SylowSubgroup);
    "SylowSubgroup"
    gap> Blubberflutsch:=x->x;;
    gap> HasNameFunction(Blubberflutsch);
    true
    gap> NameFunction(Blubberflutsch);
    "Blubberflutsch"
    gap> a:=Blubberflutsch;;
    gap> NameFunction(a);
    "Blubberflutsch"
    gap> SetNameFunction(a, "f");
    gap> NameFunction(a);
    "f"
    gap> HasNameFunction(x->x);
    false
    gap> NameFunction(x->x);
    "unknown"
  
  
  5.1-2 NumberArgumentsFunction
  
  NumberArgumentsFunction( func )  operation
  
  returns  the  number  of arguments the function func accepts. -1 is returned
  for  all  operations.  For  functions that use ... or arg to take a variable
  number  of  arguments,  the  number returned is -1 times the total number of
  parameters. For attributes, 1 is returned.
  
    Example  
    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
    gap> NumberArgumentsFunction(function(a, x...) return 1; end);
    -2
  
  
  5.1-3 NamesLocalVariablesFunction
  
  NamesLocalVariablesFunction( func )  operation
  
  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 (5.1-2).)
  
    Example  
    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
  
  
  5.1-4 FilenameFunc
  
  FilenameFunc( func )  function
  
  For  a  function func, FilenameFunc returns either fail or the absolute path
  of  the  file from which func has been read. The return value fail occurs if
  func  is  a  compiled function or an operation. For functions that have been
  entered interactively, the string "*stdin*" is returned, see Section 9.5.
  
    Example  
    gap> FilenameFunc( LEN_LIST );  # a kernel function
    fail
    gap> FilenameFunc( Size );      # an operation
    fail
    gap> FilenameFunc( x -> x^2 );  # an interactively entered function
    "*stdin*"
    gap> meth:= ApplicableMethod( Size, [ Group( () ) ] );;
    gap> FilenameFunc( meth );
    "... some path .../grpperm.gi"
  
  
  5.1-5 StartlineFunc
  
  StartlineFunc( func )  function
  EndlineFunc( func )  function
  
  Let  func  be a function. If FilenameFunc (5.1-4) returns fail for func then
  also  StartlineFunc returns fail. If FilenameFunc (5.1-4) returns a filename
  for  func  then StartlineFunc returns the line number in this file where the
  definition of func starts.
  
  EndlineFunc behaves similarly and returns the line number in this file where
  the definition of func ends.
  
    Example  
    gap> meth:= ApplicableMethod( Size, [ Group( () ) ] );;
    gap> FilenameFunc( meth );
    "... some path ... /lib/grpperm.gi"
    gap> StartlineFunc( meth );
    487
    gap> EndlineFunc( meth );
    487
  
  
  5.1-6 LocationFunc
  
  LocationFunc( func )  function
  
  Let func be a function. Returns a string describing the location of func, or
  fail  if the information cannot be found. This uses the information provided
  by FilenameFunc (5.1-4) and StartlineFunc (5.1-5)
  
    Example  
    gap> LocationFunc( Intersection );
    "... some path ... gap/lib/coll.gi:2467"
    # String is an attribute, so no information is stored
    gap> LocationFunc( String );
    fail
  
  
  5.1-7 PageSource
  
  PageSource( func[, nr] )  function
  
  This  shows  the  file  containing the source code of the function or method
  func  in  a  pager (see Pager (2.4-1)). The display starts at a line shortly
  before the code of func.
  
  For operations func the function shows the source code of the declaration of
  func.  Operations  can  have  several  declarations, use the optional second
  argument to specify which one should be shown (in the order the declarations
  were read); the default is to show the first.
  
  For kernel functions the function tries to show the C source code.
  
  If GAP cannot find a file containing the source code this will be indicated.
  
  Usage examples:
  met := ApplicableMethod(\^, [(1,2),2743527]); PageSource(met);
  PageSource(Combinations);
  PageSource(SORT_LIST); 
  PageSource(Size, 2);
  ct := CharacterTable(Group((1,2,3))); 
  met := ApplicableMethod(Size,[ct]); PageSource(met); 
  
  
  5.2  Calling  a function with a list argument that is interpreted as several
  arguments
  
  5.2-1 CallFuncList
  
  CallFuncList( func, args )  operation
  CallFuncListWrap( func, args )  operation
  
  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.
  
    Example  
    gap> CallFuncList(\+, [6, 7]);
    13
    gap> #is equivalent to:
    gap> \+(6, 7);
    13
  
  
  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 4.11), as in the
  following code fragment.
  
    Example  
    f := function ( arg )
           CallFuncList(g, arg);
           ...
         end;
  
  
  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.
  
    Example  
    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 ]
  
  
  CallFuncListWrap  differs  only  in that the result is a list. This returned
  list is empty if the called function returned no value, else it contains the
  returned  value  as  its single member. This allows wrapping functions which
  may, or may not return a value.
  
    Example  
    gap> CallFuncListWrap( x -> x, [1] );
    [ 1 ]
    gap> CallFuncListWrap( function(x) end, [1] );
    [ ]
  
  
  
  5.3 Wrapping a function, so the values produced are cached
  
  5.3-1 MemoizePosIntFunction
  
  MemoizePosIntFunction( function[, options] )  function
  
  MemoizePosIntFunction returns a function which behaves the same as function,
  except it caches the results for any inputs that are positive integers. Thus
  if  the  new function is called multiple times with the same input, then any
  call  after  the  first will return the cached value, instead of recomputing
  it. By default, the cache can be flushed by calling FlushCaches (79.10-4).
  
  The returned function will by default only accept positive integers.
  
  This function does not promise to never call function more than once for any
  input  --  values  may  be  removed  if  the  cache  gets  too  large, or if
  FlushCaches (79.10-4) is called, or if multiple threads try to calculate the
  same value simultaneously.
  
  The  optional  second  argument  is  a  record  which  provides  a number of
  configuration options. The following options are supported.
  
  defaults (default an empty list)
        Used  to  initalise the cache, both initially and after each flush. If
        defaults[i]  is bound, then this is used as default vale for the input
        i.
  
  flush (default true)
        If  this  is true, the cache is emptied whenever FlushCaches (79.10-4)
        is called; if false, then the cache cannot be flushed.
  
  errorHandler (defaults to Error (6.6-1))
        A  function to be called when an input which is not a positive integer
        is  passed  to  the  cache. The function can either raise an error, or
        else  return  a  value  which is then returned by the cache. Note that
        such a value does not get cached itself.
  
    Example  
    gap> f := MemoizePosIntFunction(
    >           function(i) Print("Check: ",i,"\n"); return i*i; end,
    >           rec(defaults := [,,50], errorHandler := x -> "Bad") );;
    gap> f(2);
    Check: 2
    4
    gap> f(2);
    4
    gap> f(3);
    50
    gap> f(-3);
    "Bad"
    gap> FlushCaches();
    gap> f(2);
    Check: 2
    4
    gap> f(3);
    50
  
  
  
  5.4 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 (5.4-1) is often used
  as family predicate in InstallMethod (78.3-1).
  
  5.4-1 ReturnTrue
  
  ReturnTrue( ... )  function
  
  This function takes any number of arguments, and always returns true.
  
    Example  
    gap> f:=ReturnTrue;  
    function( arg... ) ... end
    gap> f();  
    true
    gap> f(42);
    true
  
  
  5.4-2 ReturnFalse
  
  ReturnFalse( ... )  function
  
  This function takes any number of arguments, and always returns false.
  
    Example  
    gap> f:=ReturnFalse;  
    function( arg... ) ... end
    gap> f();  
    false
    gap> f("any_string");
    false
  
  
  5.4-3 ReturnFail
  
  ReturnFail( ... )  function
  
  This function takes any number of arguments, and always returns fail.
  
    Example  
    gap> oops:=ReturnFail;  
    function( arg... ) ... end
    gap> oops();  
    fail
    gap> oops(-42);  
    fail
  
  
  5.4-4 ReturnNothing
  
  ReturnNothing( ... )  function
  
  This function takes any number of arguments, and always returns nothing.
  
    Example  
    gap> n:=ReturnNothing;
    function( object... ) ... end
    gap> n();
    gap> n(-42);
  
  
  5.4-5 ReturnFirst
  
  ReturnFirst( ... )  function
  
  This  function  takes  one  or  more arguments, and always returns the first
  argument.  IdFunc  (5.4-6)  behaves  similarly,  but  only  accepts a single
  argument.
  
    Example  
    gap> f:=ReturnFirst;
    function( first, rest... ) ... end
    gap> f(1);
    1
    gap> f(2,3,4);
    2
    gap> f();
    Error, Function: number of arguments must be at least 1 (not 0)
  
  
  5.4-6 IdFunc
  
  IdFunc( obj )  function
  
  returns  obj.  ReturnFirst  (5.4-5)  is  similar,  but  accepts  one or more
  arguments, returning only the first.
  
    Example  
    gap> id:=IdFunc;  
    function( object ) ... end
    gap> id(42);  
    42
    gap> f:=id(SymmetricGroup(3));                 
    Sym( [ 1 .. 3 ] )
    gap> s:=One(AutomorphismGroup(SymmetricGroup(3)));
    IdentityMapping( Sym( [ 1 .. 3 ] ) )
    gap> f=s;
    false
  
  
  
  5.5 Function Types
  
  Functions are GAP objects and thus have categories and a family.
  
  5.5-1 IsFunction
  
  IsFunction( obj )  Category
  
  is the category of functions.
  
    Example  
    gap> IsFunction(x->x^2);
    true
    gap> IsFunction(Factorial);
    true
    gap> f:=One(AutomorphismGroup(SymmetricGroup(3)));
    IdentityMapping( Sym( [ 1 .. 3 ] ) )
    gap> IsFunction(f);         
    false
  
  
  5.5-2 FunctionsFamily
  
  FunctionsFamily  family
  
  is the family of all functions.
  
  
  5.6 Naming Conventions
  
  The  way  functions  are  named  in GAP might help to memorize or even guess
  names of library functions.
  
  If  a  variable name consists of several words then the first letter of each
  word is capitalized.
  
  If  the first part of the name of a function is a verb then the function may
  modify  its  argument(s)  but  does  not return anything, for example Append
  (21.4-5)  appends  the  list  given  as second argument to the list given as
  first  argument.  Otherwise  the function returns an object without changing
  the arguments, for example Concatenation (21.20-1) returns the concatenation
  of the lists given as arguments.
  
  If  the  name  of  a  function contains the word Of then the return value is
  thought of as information deduced from the arguments. Usually such functions
  are  attributes  (see 13.5).  Examples are GeneratorsOfGroup (39.2-4), which
  returns  a  list  of  generators  for  the  group  entered  as  argument, or
  DiagonalOfMat (24.12-1).
  
  For  the  setter and tester functions of an attribute Attr the names SetAttr
  resp. HasAttr are available (see 13.5).
  
  If  the  name  of  a  function contains the word By then the return value is
  thought  of as built in a certain way from the parts given as arguments. For
  example,  creating  a  group  as a factor group of a given group by a normal
  subgroup      can     be     done     by     taking     the     image     of
  NaturalHomomorphismByNormalSubgroup   (39.18-1).   Other   examples   of  By
  functions       are       GroupHomomorphismByImages       (40.1-1)       and
  LaurentPolynomialByCoefficients (66.13-1).
  
  Often   such  functions  construct  an  algebraic  structure  given  by  its
  generators  (for  example, RingByGenerators (56.1-4)). In some cases, By may
  be  replaced  by  With (like e.g. GroupWithGenerators (39.2-3)) or even both
  versions  of the name may be used. The difference between StructByGenerators
  and   StructWithGenerators   is   that   the   latter  guarantees  that  the
  GeneratorsOfStruct  value  of  the  result  is  equal  to  the  given set of
  generators (see 31.3).
  
  If  the name of a function has the form AsSomething then the return value is
  an  object  (usually  a  collection  which has the same family of elements),
  which may, for example:
  
      know  more  about  its  own structure (and so support more operations)
        than  its  input (e.g. if the elements of the collection form a group,
        then this group can be constructed using AsGroup (39.2-5));
  
      discard  its  additional  structure (e.g. AsList (30.3-8) applied to a
        group will return a list of its elements);
  
      contain  all  elements of the original object without duplicates (like
        e.g.  AsSet  (30.3-10) does if its argument is a list of elements from
        the same family);
  
      remain  unchanged (like e.g. AsSemigroup (51.1-6) does if its argument
        is a group).
  
  If Something and the argument of AsSomething are domains, some further rules
  apply as explained in Tutorial: Changing the Structure.
  
  If  the  name of a function fun1 ends with NC then there is another function
  fun2  with  the  same  name  except that the NC is missing. NC stands for no
  check.  When  fun2 is called then it checks whether its arguments are valid,
  and if so then it calls fun1. The functions SubgroupNC (39.3-1) and Subgroup
  (39.3-1) are a typical example.
  
  The  idea  is that the possibly time consuming check of the arguments can be
  omitted  if  one  is  sure  that  they  are  unnecessary. For example, if an
  algorithm  produces generators of the derived subgroup of a group then it is
  guaranteed  that  they  lie  in  the original group; Subgroup (39.3-1) would
  check this, and SubgroupNC (39.3-1) omits the check.
  
  Needless  to  say,  all  these rules are not followed slavishly, for example
  there   is   one   operation   Zero  (31.10-3)  instead  of  two  operations
  ZeroOfElement and ZeroOfAdditiveGroup.
  
  
  5.7 Code annotations (pragmas)
  
  GAP  supports  the  use  of  code  annotations (pragmas) in functions, i.e.,
  adding  comments to functions that are stored in the function object itself,
  unlike regular comments. Pragmas are single-line comments, starting with #%:
  
    Example  
    gap> function()
    >       #% This is a pragma
    >       #  This is not a pragma
    >       return;
    > end;;
    gap> Display( last );
    function (  )
        #% This is a pragma
        return;
    end
  
  
  Pragmas  can  be  used  to  mark  parts  of  functions  that should later be
  manipulated using 4.16.
  
  Please  note that heavy use of pragmas in functions slows down the execution
  of your function in the same way as adding empty ; statements to your code.
  
    Example  
    gap> a := function( )
    >       local i;
    >       for i in [ 1 .. 1000000 ] do
    >               i := i + 1;
    >       od;
    > end;
    function(  ) ... end
    gap> a();
    gap> time;
    14
    gap> b := function( )
    >       local i;
    >       for i in [ 1 .. 1000000 ] do
    >               i := i + 1;
    >               #% pragma
    >               #% pragma
    >               #% pragma
    >               #% pragma
    >               #% pragma
    >       od;
    > end;
    function(  ) ... end
    gap> b();
    gap> time;
    25