  
  [1X5 [33X[0;0YFunctions[133X[101X
  
  [33X[0;0YThe  section [14X4.23[114X  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.[133X
  
  
  [1X5.1 [33X[0;0YInformation about a function[133X[101X
  
  [1X5.1-1 NameFunction[101X
  
  [29X[2XNameFunction[102X( [3Xfunc[103X ) [32X function
  
  [33X[0;0Yreturns  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 [13Xdifferent[113X
  from  the  name  that  is  documented.)  If  no such name exists, the string
  [10X"unknown"[110X is returned.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XNameFunction(SylowSubgroup);[127X[104X
    [4X[28X"SylowSubgroup"[128X[104X
    [4X[25Xgap>[125X [27XBlubberflutsch:=x->x;;[127X[104X
    [4X[25Xgap>[125X [27XNameFunction(Blubberflutsch);[127X[104X
    [4X[28X"Blubberflutsch"[128X[104X
    [4X[25Xgap>[125X [27Xa:=Blubberflutsch;;[127X[104X
    [4X[25Xgap>[125X [27XNameFunction(a);[127X[104X
    [4X[28X"Blubberflutsch"[128X[104X
    [4X[25Xgap>[125X [27XNameFunction(x->x);[127X[104X
    [4X[28X"unknown"[128X[104X
    [4X[25Xgap>[125X [27XNameFunction(NameFunction);[127X[104X
    [4X[28X"NameFunction"[128X[104X
  [4X[32X[104X
  
  [1X5.1-2 NumberArgumentsFunction[101X
  
  [29X[2XNumberArgumentsFunction[102X( [3Xfunc[103X ) [32X function
  
  [33X[0;0Yreturns  the  number  of arguments the function [3Xfunc[103X accepts. -1 is returned
  for  all  operations.  For  functions that use [10X...[110X or [10Xarg[110X to take a variable
  number  of  arguments,  the  number returned is -1 times the total number of
  parameters. For attributes, 1 is returned.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XNumberArgumentsFunction(function(a,b,c,d,e,f,g,h,i,j,k)return 1;end);[127X[104X
    [4X[28X11[128X[104X
    [4X[25Xgap>[125X [27XNumberArgumentsFunction(Size);[127X[104X
    [4X[28X1[128X[104X
    [4X[25Xgap>[125X [27XNumberArgumentsFunction(IsCollsCollsElms);[127X[104X
    [4X[28X3[128X[104X
    [4X[25Xgap>[125X [27XNumberArgumentsFunction(Sum);[127X[104X
    [4X[28X-1[128X[104X
    [4X[25Xgap>[125X [27XNumberArgumentsFunction(function(a, x...) return 1; end);[127X[104X
    [4X[28X-2[128X[104X
  [4X[32X[104X
  
  [1X5.1-3 NamesLocalVariablesFunction[101X
  
  [29X[2XNamesLocalVariablesFunction[102X( [3Xfunc[103X ) [32X function
  
  [33X[0;0Yreturns  a  mutable  list of strings; the first entries are the names of the
  arguments  of  the  function [3Xfunc[103X, in the same order as they were entered in
  the  definition  of  [3Xfunc[103X, and the remaining ones are the local variables as
  given  in  the  [9Xlocal[109X  statement  in  [3Xfunc[103X.  (The number of arguments can be
  computed with [2XNumberArgumentsFunction[102X ([14X5.1-2[114X).)[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XNamesLocalVariablesFunction(function( a, b ) local c; return 1; end);[127X[104X
    [4X[28X[ "a", "b", "c" ][128X[104X
    [4X[25Xgap>[125X [27XNamesLocalVariablesFunction(function( arg ) local a; return 1; end);[127X[104X
    [4X[28X[ "arg", "a" ][128X[104X
    [4X[25Xgap>[125X [27XNamesLocalVariablesFunction( Size );[127X[104X
    [4X[28Xfail[128X[104X
  [4X[32X[104X
  
  [1X5.1-4 FilenameFunc[101X
  
  [29X[2XFilenameFunc[102X( [3Xfunc[103X ) [32X function
  
  [33X[0;0YFor  a  function [3Xfunc[103X, [2XFilenameFunc[102X returns either [9Xfail[109X or the absolute path
  of  the  file from which [3Xfunc[103X has been read. The return value [9Xfail[109X occurs if
  [3Xfunc[103X  is  a  compiled function or an operation. For functions that have been
  entered interactively, the string [10X"*stdin*"[110X is returned, see Section [14X9.5[114X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XFilenameFunc( LEN_LIST );  # a kernel function[127X[104X
    [4X[28Xfail[128X[104X
    [4X[25Xgap>[125X [27XFilenameFunc( Size );      # an operation[127X[104X
    [4X[28Xfail[128X[104X
    [4X[25Xgap>[125X [27XFilenameFunc( x -> x^2 );  # an interactively entered function[127X[104X
    [4X[28X"*stdin*"[128X[104X
    [4X[25Xgap>[125X [27Xmeth:= ApplicableMethod( Size, [ Group( () ) ] );;[127X[104X
    [4X[25Xgap>[125X [27XFilenameFunc( meth );[127X[104X
    [4X[28X"... some path .../grpperm.gi"[128X[104X
  [4X[32X[104X
  
  [1X5.1-5 StartlineFunc[101X
  
  [29X[2XStartlineFunc[102X( [3Xfunc[103X ) [32X function
  [29X[2XEndlineFunc[102X( [3Xfunc[103X ) [32X function
  
  [33X[0;0YLet  [3Xfunc[103X  be a function. If [2XFilenameFunc[102X ([14X5.1-4[114X) returns [9Xfail[109X for [3Xfunc[103X then
  also  [2XStartlineFunc[102X returns [9Xfail[109X. If [2XFilenameFunc[102X ([14X5.1-4[114X) returns a filename
  for  [3Xfunc[103X  then [2XStartlineFunc[102X returns the line number in this file where the
  definition of [3Xfunc[103X starts.[133X
  
  [33X[0;0Y[2XEndlineFunc[102X behaves similarly and returns the line number in this file where
  the definition of [3Xfunc[103X ends.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xmeth:= ApplicableMethod( Size, [ Group( () ) ] );;[127X[104X
    [4X[25Xgap>[125X [27XFilenameFunc( meth );[127X[104X
    [4X[28X"... some path ... gap4r5/lib/grpperm.gi"[128X[104X
    [4X[25Xgap>[125X [27XStartlineFunc( meth );[127X[104X
    [4X[28X487[128X[104X
    [4X[25Xgap>[125X [27XEndlineFunc( meth );[127X[104X
    [4X[28X487[128X[104X
  [4X[32X[104X
  
  [1X5.1-6 PageSource[101X
  
  [29X[2XPageSource[102X( [3Xfunc[103X ) [32X function
  
  [33X[0;0YThis  shows  the  file  containing the source code of the function or method
  [3Xfunc[103X  in  a  pager (see [2XPager[102X ([14X2.4-1[114X)). The display starts at a line shortly
  before the code of [3Xfunc[103X.[133X
  
  [33X[0;0YThis function works if [10XFilenameFunc([3Xfunc[103X[10X)[110X returns the name of a proper file.
  In  that  case this filename and the position of the function definition are
  also  printed.  Otherwise  the  function  indicates  that  the source is not
  available  (for  example this happens for functions which are implemented in
  the [5XGAP[105X C-kernel).[133X
  
  [33X[0;0YUsage examples:[133X
  [33X[0;0Y[10Xmet := ApplicableMethod(\^, [(1,2),2743527]); PageSource(met);[110X[133X
  [33X[0;0Y[10XPageSource(Combinations);[110X[133X
  [33X[0;0Y[10Xct:=CharacterTable(Group((1,2,3))); [110X[133X
  [33X[0;0Y[10Xmet := ApplicableMethod(Size,[ct]); PageSource(met); [110X[133X
  
  
  [1X5.2  [33X[0;0YCalling  a function with a list argument that is interpreted as several[101X
  [1Xarguments[133X[101X
  
  [1X5.2-1 CallFuncList[101X
  
  [29X[2XCallFuncList[102X( [3Xfunc[103X, [3Xargs[103X ) [32X operation
  
  [33X[0;0Yreturns  the  result, when calling function [3Xfunc[103X with the arguments given in
  the  list  [3Xargs[103X,  i.e. [3Xargs[103X  is  [21Xunwrapped[121X  so  that [3Xargs[103X appears as several
  arguments to [3Xfunc[103X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XCallFuncList(\+, [6, 7]);[127X[104X
    [4X[28X13[128X[104X
    [4X[25Xgap>[125X [27X#is equivalent to:[127X[104X
    [4X[25Xgap>[125X [27X\+(6, 7);[127X[104X
    [4X[28X13[128X[104X
  [4X[32X[104X
  
  [33X[0;0YA more useful application of [2XCallFuncList[102X is for a function [10Xg[110X that is called
  in  the body of a function [10Xf[110X with (a sublist of) the arguments of [10Xf[110X, where [10Xf[110X
  has  been  defined  with  a single formal argument [10Xarg[110X (see [14X4.23[114X), as in the
  following code fragment.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[28Xf := function ( arg )[128X[104X
    [4X[28X       CallFuncList(g, arg);[128X[104X
    [4X[28X       ...[128X[104X
    [4X[28X     end;[128X[104X
  [4X[32X[104X
  
  [33X[0;0YIn  the  body of [10Xf[110X the several arguments passed to [10Xf[110X become a list [10Xarg[110X. If [10Xg[110X
  were called instead via [10Xg( arg )[110X then [10Xg[110X would see a single list argument, so
  that [10Xg[110X would, in general, have to [21Xunwrap[121X the passed list. The following (not
  particularly  useful)  example demonstrates both described possibilities for
  the call to [10Xg[110X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XPrintNumberFromDigits := function ( arg )[127X[104X
    [4X[25X>[125X [27X    CallFuncList( Print, arg );[127X[104X
    [4X[25X>[125X [27X    Print( "\n" );[127X[104X
    [4X[25X>[125X [27X   end;[127X[104X
    [4X[28Xfunction( arg... ) ... end[128X[104X
    [4X[25Xgap>[125X [27XPrintNumberFromDigits( 1, 9, 7, 3, 2 );[127X[104X
    [4X[28X19732[128X[104X
    [4X[25Xgap>[125X [27XPrintDigits := function ( arg )[127X[104X
    [4X[25X>[125X [27X    Print( arg );[127X[104X
    [4X[25X>[125X [27X    Print( "\n" );[127X[104X
    [4X[25X>[125X [27X   end;[127X[104X
    [4X[28Xfunction( arg... ) ... end[128X[104X
    [4X[25Xgap>[125X [27XPrintDigits( 1, 9, 7, 3, 2 );[127X[104X
    [4X[28X[ 1, 9, 7, 3, 2 ][128X[104X
  [4X[32X[104X
  
  
  [1X5.3 [33X[0;0YCalling a function with a time limit[133X[101X
  
  [1X5.3-1 CallWithTimeout[101X
  
  [29X[2XCallWithTimeout[102X( [3Xtimeout[103X, [3Xfunc[103X, [3X.....[103X ) [32X function
  [29X[2XCallWithTimeoutList[102X( [3Xtimeout[103X, [3Xfunc[103X, [3Xarglist[103X ) [32X function
  
  [33X[0;0Y[10XCallWithTimeout[110X  and  [10XCallWithTimeoutList[110X  support calling a function with a
  limit on the CPU time it can consume.[133X
  
  [33X[0;0YThis  functionality may not be available on all systems and you should check
  [2XGAPInfo.TimeoutsSupported[102X ([14X5.3-2[114X) before using this functionality.[133X
  
  [33X[0;0Y[10XCallWithTimeout[110X is variadic. Its third and subsequent arguments, if any, are
  the  arguments passed to [3Xfunc[103X. [10XCallWithTimeoutList[110X in contrast takes exactly
  three  arguments, of which the third is a list (possibly empty) or arguments
  to pass to [3Xfunc[103X.[133X
  
  [33X[0;0YIf  the  call  completes  within  the allotted time and returns a value, the
  result of [10XCallWithTimeout[List][110X is a length 1 list containing that value.[133X
  
  [33X[0;0YIf  the  call  completes  within the allotted time and returns no value, the
  result of [10XCallWithTimeout[List][110X is an empty list.[133X
  
  [33X[0;0YIf   the   call  does  not  complete  within  the  timeout,  the  result  of
  [10XCallWithTimeout[List][110X  is [9Xfail[109X. In this case, just as if you had [10Xquit[110X from a
  break loop, there is some risk that internal data structures in [5XGAP[105X may have
  been left in an inconsistent state, and you should proceed with caution.[133X
  
  [33X[0;0YThe  timer  is suspended during execution of a break loop and abandoned when
  you quit from a break loop.[133X
  
  [33X[0;0YTimeouts    may    not   be   nested.   That   is,   during   execution   of
  [10XCallWithTimeout([3Xtimeout[103X[10X,[3Xfunc[103X[10X,...)[110X, [3Xfunc[103X (or functions it calls) may not call
  [10XCallWithTimeout[110X or [10XCallWithTimeoutList[110X. This restriction may be lifted on at
  least   some   systems   in   future   releases.  It  is  permitted  to  use
  [10XCallWithTimeout[110X  or  [10XCallWithTimeoutList[110X from within a break loop, even if a
  suspended  timeout  exists,  although  there  is  limit on the depth of such
  nesting.[133X
  
  [33X[0;0YThe  limit  [3Xtimeout[103X  is  specified  as  a  record.  At present the following
  components  are recognised [10Xnanoseconds[110X, [10Xmicroseconds[110X, [10Xmilliseconds[110X, [10Xseconds[110X,
  [10Xminutes[110X,  [10Xhours[110X,  [10Xdays[110X  and  [10Xweeks[110X. Any of these components which is present
  should  be  bound  to  a  positive  integer, rational or float and the times
  represented  are  totalled  to  give  the  actual timeout. As a shorthand, a
  single  positive  integers  may  be  supplied,  and  is taken as a number of
  microseconds.  Further  components  are  permitted and ignored, to allow for
  future functionality.[133X
  
  [33X[0;0YThe  precision  of  the  timeouts  is  not guaranteed, and there is a system
  dependent  upper limit on the timeout which is typically about 8 years on 32
  bit  systems  and  about 30 billion years on 64 bit systems. Timeouts longer
  than this will be reduced to this limit. On Windows systems, timing is based
  on  elapsed time, not CPU time because the necessary POSIX CPU timing API is
  not supported.[133X
  
  [1X5.3-2 GAPInfo.TimeoutsSupported[101X
  
  [29X[2XGAPInfo.TimeoutsSupported[102X[32X global variable
  
  [33X[0;0Ytests whether this installation of [5XGAP[105X supports the timeout functionality of
  [2XCallWithTimeout[102X ([14X5.3-1[114X) and related functions.[133X
  
  
  [1X5.4 [33X[0;0YFunctions that do nothing[133X[101X
  
  [33X[0;0YThe  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 [2XReturnTrue[102X ([14X5.4-1[114X) is often used
  as family predicate in [2XInstallMethod[102X ([14X78.2-1[114X).[133X
  
  [1X5.4-1 ReturnTrue[101X
  
  [29X[2XReturnTrue[102X( [3X...[103X ) [32X function
  
  [33X[0;0YThis function takes any number of arguments, and always returns [9Xtrue[109X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xf:=ReturnTrue;  [127X[104X
    [4X[28Xfunction( arg... ) ... end[128X[104X
    [4X[25Xgap>[125X [27Xf();  [127X[104X
    [4X[28Xtrue[128X[104X
    [4X[25Xgap>[125X [27Xf(42);[127X[104X
    [4X[28Xtrue[128X[104X
  [4X[32X[104X
  
  [1X5.4-2 ReturnFalse[101X
  
  [29X[2XReturnFalse[102X( [3X...[103X ) [32X function
  
  [33X[0;0YThis function takes any number of arguments, and always returns [9Xfalse[109X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xf:=ReturnFalse;  [127X[104X
    [4X[28Xfunction( arg... ) ... end[128X[104X
    [4X[25Xgap>[125X [27Xf();  [127X[104X
    [4X[28Xfalse[128X[104X
    [4X[25Xgap>[125X [27Xf("any_string");[127X[104X
    [4X[28Xfalse[128X[104X
  [4X[32X[104X
  
  [1X5.4-3 ReturnFail[101X
  
  [29X[2XReturnFail[102X( [3X...[103X ) [32X function
  
  [33X[0;0YThis function takes any number of arguments, and always returns [9Xfail[109X.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xoops:=ReturnFail;  [127X[104X
    [4X[28Xfunction( arg... ) ... end[128X[104X
    [4X[25Xgap>[125X [27Xoops();  [127X[104X
    [4X[28Xfail[128X[104X
    [4X[25Xgap>[125X [27Xoops(-42);  [127X[104X
    [4X[28Xfail[128X[104X
  [4X[32X[104X
  
  [1X5.4-4 ReturnNothing[101X
  
  [29X[2XReturnNothing[102X( [3X...[103X ) [32X function
  
  [33X[0;0YThis function takes any number of arguments, and always returns nothing.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xn:=ReturnNothing;[127X[104X
    [4X[28Xfunction( object... ) ... end[128X[104X
    [4X[25Xgap>[125X [27Xn();[127X[104X
    [4X[25Xgap>[125X [27Xn(-42);[127X[104X
  [4X[32X[104X
  
  [1X5.4-5 ReturnFirst[101X
  
  [29X[2XReturnFirst[102X( [3X...[103X ) [32X function
  
  [33X[0;0YThis  function  takes  one  or  more arguments, and always returns the first
  argument.  [2XIdFunc[102X  ([14X5.4-6[114X)  behaves  similarly,  but  only  accepts a single
  argument.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xf:=ReturnFirst;[127X[104X
    [4X[28Xfunction( object... ) ... end[128X[104X
    [4X[25Xgap>[125X [27Xf(1);[127X[104X
    [4X[28X1[128X[104X
    [4X[25Xgap>[125X [27Xf(2,3,4);[127X[104X
    [4X[28X2[128X[104X
    [4X[25Xgap>[125X [27Xf();[127X[104X
    [4X[28XError, RETURN_FIRST requires one or more arguments[128X[104X
  [4X[32X[104X
  
  [1X5.4-6 IdFunc[101X
  
  [29X[2XIdFunc[102X( [3Xobj[103X ) [32X function
  
  [33X[0;0Yreturns  [3Xobj[103X.  [2XReturnFirst[102X  ([14X5.4-5[114X)  is  similar,  but  accepts  one or more
  arguments, returning only the first.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27Xid:=IdFunc;  [127X[104X
    [4X[28Xfunction( object ) ... end[128X[104X
    [4X[25Xgap>[125X [27Xid(42);  [127X[104X
    [4X[28X42[128X[104X
    [4X[25Xgap>[125X [27Xf:=id(SymmetricGroup(3));                 [127X[104X
    [4X[28XSym( [ 1 .. 3 ] )[128X[104X
    [4X[25Xgap>[125X [27Xs:=One(AutomorphismGroup(SymmetricGroup(3)));[127X[104X
    [4X[28XIdentityMapping( Sym( [ 1 .. 3 ] ) )[128X[104X
    [4X[25Xgap>[125X [27Xf=s;[127X[104X
    [4X[28Xfalse[128X[104X
  [4X[32X[104X
  
  
  [1X5.5 [33X[0;0YFunction Types[133X[101X
  
  [33X[0;0YFunctions are [5XGAP[105X objects and thus have categories and a family.[133X
  
  [1X5.5-1 IsFunction[101X
  
  [29X[2XIsFunction[102X( [3Xobj[103X ) [32X Category
  
  [33X[0;0Yis the category of functions.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XIsFunction(x->x^2);[127X[104X
    [4X[28Xtrue[128X[104X
    [4X[25Xgap>[125X [27XIsFunction(Factorial);[127X[104X
    [4X[28Xtrue[128X[104X
    [4X[25Xgap>[125X [27Xf:=One(AutomorphismGroup(SymmetricGroup(3)));[127X[104X
    [4X[28XIdentityMapping( Sym( [ 1 .. 3 ] ) )[128X[104X
    [4X[25Xgap>[125X [27XIsFunction(f);         [127X[104X
    [4X[28Xfalse[128X[104X
  [4X[32X[104X
  
  [1X5.5-2 IsOperation[101X
  
  [29X[2XIsOperation[102X( [3Xobj[103X ) [32X Category
  
  [33X[0;0Yis  the  category of operations. Every operation is a function, but not vice
  versa.[133X
  
  [4X[32X  Example  [32X[104X
    [4X[25Xgap>[125X [27XMinimalPolynomial;  [127X[104X
    [4X[28X<Operation "MinimalPolynomial">[128X[104X
    [4X[25Xgap>[125X [27XIsOperation(MinimalPolynomial);[127X[104X
    [4X[28Xtrue[128X[104X
    [4X[25Xgap>[125X [27XIsFunction(MinimalPolynomial);         [127X[104X
    [4X[28Xtrue[128X[104X
    [4X[25Xgap>[125X [27XFactorial;[127X[104X
    [4X[28Xfunction( n ) ... end[128X[104X
    [4X[25Xgap>[125X [27XIsOperation(Factorial);[127X[104X
    [4X[28Xfalse[128X[104X
  [4X[32X[104X
  
  [1X5.5-3 FunctionsFamily[101X
  
  [29X[2XFunctionsFamily[102X[32X global variable
  
  [33X[0;0Yis the family of all functions.[133X
  
  
  [1X5.6 [33X[0;0YNaming Conventions[133X[101X
  
  [33X[0;0YThe  way  functions  are  named  in [5XGAP[105X might help to memorize or even guess
  names of library functions.[133X
  
  [33X[0;0YIf  a  variable name consists of several words then the first letter of each
  word is capitalized.[133X
  
  [33X[0;0YIf  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 [2XAppend[102X
  ([14X21.4-5[114X)  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 [2XConcatenation[102X ([14X21.20-1[114X) returns the concatenation
  of the lists given as arguments.[133X
  
  [33X[0;0YIf  the  name  of  a  function contains the word [21X[10XOf[110X[121X then the return value is
  thought of as information deduced from the arguments. Usually such functions
  are  attributes  (see [14X13.5[114X).  Examples are [2XGeneratorsOfGroup[102X ([14X39.2-4[114X), which
  returns  a  list  of  generators  for  the  group  entered  as  argument, or
  [2XDiagonalOfMat[102X ([14X24.12-1[114X).[133X
  
  [33X[0;0YFor  the  setter and tester functions of an attribute [10XAttr[110X the names [10XSetAttr[110X
  resp. [10XHasAttr[110X are available (see [14X13.5[114X).[133X
  
  [33X[0;0YIf  the  name  of  a  function contains the word [21X[10XBy[110X[121X 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
  [2XNaturalHomomorphismByNormalSubgroup[102X   ([14X39.18-1[114X).   Other   examples   of  [21X[10XBy[110X[121X
  functions       are       [2XGroupHomomorphismByImages[102X       ([14X40.1-1[114X)       and
  [2XLaurentPolynomialByCoefficients[102X ([14X66.13-1[114X).[133X
  
  [33X[0;0YOften   such  functions  construct  an  algebraic  structure  given  by  its
  generators  (for  example, [2XRingByGenerators[102X ([14X56.1-4[114X)). In some cases, [21X[10XBy[110X[121X may
  be  replaced  by  [21X[10XWith[110X[121X (like e.g. [2XGroupWithGenerators[102X ([14X39.2-3[114X)) or even both
  versions  of the name may be used. The difference between [10XStructByGenerators[110X
  and   [10XStructWithGenerators[110X   is   that   the   latter  guarantees  that  the
  [10XGeneratorsOfStruct[110X  value  of  the  result  is  equal  to  the  given set of
  generators (see [14X31.3[114X).[133X
  
  [33X[0;0YIf  the name of a function has the form [21X[10XAsSomething[110X[121X then the return value is
  an  object  (usually  a  collection  which has the same family of elements),
  which may, for example:[133X
  
  [30X    [33X[0;6Yknow  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 [2XAsGroup[102X ([14X39.2-5[114X));[133X
  
  [30X    [33X[0;6Ydiscard  its  additional  structure (e.g. [2XAsList[102X ([14X30.3-8[114X) applied to a
        group will return a list of its elements);[133X
  
  [30X    [33X[0;6Ycontain  all  elements of the original object without duplicates (like
        e.g.  [2XAsSet[102X  ([14X30.3-10[114X) does if its argument is a list of elements from
        the same family);[133X
  
  [30X    [33X[0;6Yremain  unchanged (like e.g. [2XAsSemigroup[102X ([14X51.1-6[114X) does if its argument
        is a group).[133X
  
  [33X[0;0YIf [10XSomething[110X and the argument of [10XAsSomething[110X are domains, some further rules
  apply as explained in [14XTutorial: Changing the Structure[114X.[133X
  
  [33X[0;0YIf  the  name of a function [10Xfun1[110X ends with [21X[10XNC[110X[121X then there is another function
  [10Xfun2[110X  with  the  same  name  except that the [10XNC[110X is missing. [10XNC[110X stands for [21Xno
  check[121X.  When  [10Xfun2[110X is called then it checks whether its arguments are valid,
  and if so then it calls [10Xfun1[110X. The functions [2XSubgroupNC[102X ([14X39.3-1[114X) and [2XSubgroup[102X
  ([14X39.3-1[114X) are a typical example.[133X
  
  [33X[0;0YThe  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; [2XSubgroup[102X ([14X39.3-1[114X) would
  check this, and [2XSubgroupNC[102X ([14X39.3-1[114X) omits the check.[133X
  
  [33X[0;0YNeedless  to  say,  all  these rules are not followed slavishly, for example
  there   is   one   operation   [2XZero[102X  ([14X31.10-3[114X)  instead  of  two  operations
  [10XZeroOfElement[110X and [10XZeroOfAdditiveGroup[110X.[133X
  
