"Fossies" - the Fresh Open Source Software Archive 
As a special service "Fossies" has tried to format the requested text file into HTML format (style:
standard) with prefixed line numbers.
Alternatively you can here
view or
download the uninterpreted source code file.
1
2 ##############
3 ### list.g ###
4 ##############
5
6 #############################################################################
7 ##
8 #F List( <obj> ) . . . . . . . . . . . . . . . . . . . . . convert to a list
9 ##
10 InstallMethod(
11 rec(
12 kind:="FUNCTION",
13 name:="List",
14 sin:=[[list,"l"],[func,"f"]],
15 sou:=[],
16 short:=
17 "Apply `f' to every member of `l' and return the list of return values.",
18 ex:=["l:=[1,2,3,4];\n"+
19 "List(l,i->3*i);",
20 "l:=[1,2,3,4];\n"+
21 "List(l,IsEven);"],
22 see:=[]), _Apply_list_func);
23 InstallMethod(
24 rec(
25 kind:="FUNCTION",
26 name:="List",
27 sin:=[[func,"f"],[list,"l"]],
28 sou:=[],
29 short:=
30 "Apply `f' to every member of `l' and return the list of return values.",
31 ex:=["l:=[1,2,3,4];\n"+
32 "List(i->3*i,l);",
33 "l:=[1,2,3,4];\n"+
34 "List(IsEven,l);"],
35 see:=[]), _Apply_func_list);
36 #InstallMethod(
37 # rec(
38 # kind:="FUNCTION",
39 # name:="List",
40 # sin:=[[any,"l"]],
41 # sou:=[[list]],
42 # short:=
43 # "Return the list constructed by the elements of `l'.\n"+
44 # "Note: Use this construction to obtain a list from various "+
45 # "types like seq, tup and the like.",
46 # ex:=["List([1,2,3,4]);"],
47 # see:=[]), _List_any);
48
49 InstallMethod(
50 rec(
51 kind:="FUNCTION",
52 name:="Size",
53 sin:=[[string,"s"]],
54 sou:=[[elt-ord^rat]],
55 short:="Count the number of characters in `s'.",
56 ex:=["Number(\"How many characters do I have?\");"],
57 see:=[]), _Size_list);
58 InstallMethod(
59 rec(
60 kind:="FUNCTION",
61 name:="Size",
62 sin:=[[list,"l"]],
63 sou:=[[elt-ord^rat]],
64 short:="Count the number of list elements `l'.",
65 ex:=["Size([1,2,4,3]);"],
66 see:=[]), _Size_list);
67
68
69 #############################################################################
70 ##
71 #F Apply_( <list>, <func> ) . apply a function to list entries destructively
72 ##
73 InstallMethod(
74 rec(
75 kind:="FUNCTION",
76 name:="Apply_",
77 sin:=[[list,"l"],[func,"f"]],
78 sou:=[],
79 short:=
80 "Apply 'f' to every member of `l' and replace the entry by "+
81 "the corresponding return value.\n"+
82 "Note: The previous contents of `l' will be lost.",
83 ex:=["l:=[1,2,3,4];\n"+
84 "Apply_(l,i->3*i); l;",
85 "l:=[1,2,3,4];\n"+
86 "Apply_(l,IsEven); l;"],
87 see:=[]), _Apply__list_func);
88 InstallMethod(
89 rec(
90 kind:="FUNCTION",
91 name:="Apply_",
92 sin:=[[func,"f"],[list,"l"]],
93 sou:=[],
94 short:=
95 "Apply 'f' to every member of `l' and replace the entry by "+
96 "the corresponding return value.\n"+
97 "Note: The previous contents of `l' will be lost.",
98 ex:=["l:=[1,2,3,4];\n"+
99 "Apply_(i->3*i,l); l;",
100 "l:=[1,2,3,4];\n"+
101 "Apply_(IsEven,l); l;"],
102 see:=[]), _Apply__func_list);
103 InstallMethod(
104 rec(
105 kind:="FUNCTION",
106 name:="Apply",
107 sin:=[[list,"l"],[func,"f"]],
108 sou:=[[list,"r"]],
109 short:=
110 "Return the list where every member 'b' of 'l' is replaced by 'f' applied to 'b'.",
111 ex:=["l:=[1,2,3,4];\n"+
112 "Apply(l,i->3*i); l;",
113 "l:=[1,2,3,4];\n"+
114 "Apply(l,IsEven); l;"],
115 see:=[]), _Apply_list_func);
116 InstallMethod(
117 rec(
118 kind:="FUNCTION",
119 name:="Apply",
120 sin:=[[func,"f"],[list,"A"]],
121 sou:=[[list,"r"]],
122 short:=
123 "Apply 'f' to every member of `A' and replace the entry by "+
124 "the corresponding return value.\n"+
125 "Note: The previous contents of `l' will be lost.",
126 ex:=["l:=[1,2,3,4];\n"+
127 "Apply(i->3*i,l); l;",
128 "l:=[1,2,3,4];\n"+
129 "Apply(IsEven,l); l;"],
130 see:=[]), _Apply_func_list);
131
132 InstallMethod(
133 rec(
134 kind:="FUNCTION",
135 name:="Apply",
136 sin:=[[func,"f"],[alist,"A"]],
137 sou:=[[alist,"r"]],
138 short:=
139 "Apply `f' to every member of `A' and return the alist of return values.",
140 ex:=["l:=Alist([3,1],[6,2],[9,3],[12,4]);\n"+
141 "Apply(i->3*i,l);",
142 "l:=[1,2,3,4];\n"+
143 "Apply(IsEven,l);"],
144 see:=[]), _Apply_func_alist);
145 InstallMethod(
146 rec(
147 kind:="FUNCTION",
148 name:="Apply",
149 sin:=[[alist,"l"],[func,"f"]],
150 sou:=[[alist,"r"]],
151 short:=
152 "Apply `f' to every member of `l' and return the alist of return values.",
153 ex:=["l:=Alist([3,1],[6,2],[9,3],[12,4]);\n"+
154 "Apply(l,i->3*i);",
155 "l:=[1,2,3,4];\n"+
156 "Apply(l,IsEven);"],
157 see:=[]), _Apply_alist_func);
158 InstallMethod(
159 rec(
160 kind:="FUNCTION",
161 name:="Apply_",
162 sin:=[[alist,"A"],[func,"f"]],
163 sou:=[],
164 short:=
165 "Apply 'f' to every member of `A' and replace the entry by "+
166 "the corresponding return value.\n"+
167 "Note: The previous contents of `A' will be lost.",
168 ex:=["l:=[1,2,3,4];\n"+
169 "Apply_(l,i->3*i); l;",
170 "l:=[1,2,3,4];\n"+
171 "Apply_(l,IsEven); l;"],
172 see:=[]), _Apply__list_func);
173 InstallMethod(
174 rec(
175 kind:="FUNCTION",
176 name:="Apply_",
177 sin:=[[func,"f"],[alist,"A"]],
178 sou:=[],
179 short:=
180 "Apply 'f' to every member of `A' and replace the entry by "+
181 "the corresponding return value.\n"+
182 "Note: The previous contents of `l' will be lost.",
183 ex:=["l:=[1,2,3,4];\n"+
184 "Apply_(i->3*i,l); l;",
185 "l:=[1,2,3,4];\n"+
186 "Apply_(IsEven,l); l;"],
187 see:=[]), _Apply__func_list);
188 ##List:=Copy(Apply);
189
190
191 #############################################################################
192 ##
193 #F GetEntry( <record>, <string> )
194 #F GetEntry( <list>, <elt-ord^rat> )
195 ##
196 InstallMethod(
197 rec(
198 kind:="FUNCTION",
199 name:="GetEntry",
200 sin:=[[record,"r"],[string,"f"]],
201 opt:=[__FAILUREDOC],
202 sou:=[[any]],
203 short:="Returns the element of `r' in the field `f' if it exists and "+
204 "fails otherwise.",
205 ex:=["A:=rec(ac:=1,ad:=INFTY);\n"+
206 "GetEntry(A,\"ad\");\n"+
207 "GetEntry(A,\"ab\");"],
208 see:=[]), _GetEntry_rec_string,
209 rec(DefaultValues:=__FAILUREREC));
210 InstallMethod(
211 rec(
212 kind:="FUNCTION",
213 name:="GetEntry",
214 sin:=[[list,"l"],[elt-ord^rat,"pos"]],
215 opt:=[__FAILUREDOC],
216 sou:=[[any]],
217 short:="Returns the element of `l' at position `pos' if it exists and "+
218 "fails otherwise.",
219 ex:=["A:=[2,3,5,7,11,13,17,19];\n"+
220 "GetEntry(A,2);\n"+
221 "GetEntry(A,44);"],
222 see:=[]), _GetEntry_list_eor,
223 rec(DefaultValues:=__FAILUREREC));
224
225
226
227 #############################################################################
228 ##
229 #F Position( <alist>, <elt-ord^rat> )
230 #F Position( <dry>, <elt-ord^rat> )
231 ##
232 InstallMethod(
233 rec(
234 kind:= "FUNCTION",
235 name:= "Position",
236 sin := [[list,"L"],[any,"a"]],
237 opt := [[elt-ord^rat,"Start",
238 "Determines the position where the search is started.",rec(Default:=1)],
239 __FAILUREDOC],
240 sou := [[elt-ord^rat]],
241 short := "Return the position of the first occurence of `a' in `L' "+
242 "if `a in L' is true, and FAILURE otherwise.",
243 ex := ["L:=[1,,3,4];\n"+
244 "Position(L,3); Position(L,1,rec(Start:=2)); Position(L,\"foo\");"],
245 see := []), _Position_list_any,
246 rec(DefaultValues:=__FAILUREREC));
247 InstallMethod(
248 rec(
249 kind:= "FUNCTION",
250 name:= "Position",
251 sin := [[string,"S"],[char,"c"]],
252 opt := [[elt-ord^rat,"Start",
253 "Determines the position where the search is started.",rec(Default:=1)],
254 __FAILUREDOC],
255 sou := [[elt-ord^rat]],
256 short := "Return the position of the first occurence of `c' in `S' "+
257 "if c is a character in the string `S', and FAILURE otherwise.",
258 ex := ["S:=\"foobar\";\n"+
259 "Position(S,'o'); Position(S,'f',rec(Start:=2)); Position(S,\"foo\");"],
260 see := []), _Position_list_any,
261 rec(DefaultValues:=__FAILUREREC));
262 InstallMethod(
263 rec(
264 kind:="FUNCTION",
265 name:="Position",
266 sin:=[[dry,"D"],[any,"a"]],
267 opt:=[[elt-ord^rat,"Start",
268 "Determines the position where the search is started.",rec(Default:=1)],
269 __FAILUREDOC],
270 sou:=[[elt-ord^rat]],
271 short := "Return the position of the occurence of `a' in `D' "+
272 "if `a in D' is true, and FAILURE otherwise.",
273 ex := ["D:=Dry([1,12,4,3]);\n"+
274 "Position(D,12); Position(D,1,rec(Start:=2)); Position(D,\"foo\");"],
275 see := []), DryPosition,
276 rec(DefaultValues:=__FAILUREREC));
277 InstallMethod(
278 rec(
279 kind:="FUNCTION",
280 name:="Position",
281 sin:=[[alist,"A"],[any,"a"]],
282 opt:=[[elt-ord^rat,"Start",
283 "Determines the position where the search is started.",rec(Default:=1)],
284 __FAILUREDOC],
285 sou:=[[elt-ord^rat]],
286 short := "Return the position of the occurence of `a' in `A' "+
287 "if `a in A' is true, and FAILURE otherwise.",
288 ex := ["A:=Alist([1,12],[3,4]);\n"+
289 "Position(A,3); Position(A,1,rec(Start:=2)); Position(A,\"foo\");"],
290 see := []), _Position_alist_any,
291 rec(DefaultValues:=__FAILUREREC));
292
293
294
295
296 #############################################################################
297 ##
298 #F Mapconcat(<func>, <list>, <sep>) . . . . . . . . concatentation of lists
299 #F Mapconcat(<func>, <list>) . . . . . . . . . . . . concatentation of lists
300 ##
301 InstallMethod(
302 rec(
303 kind:="FUNCTION",
304 name:="Mapconcat",
305 sin:=[[func,"f"],[list,"l"],[string,"sep"]],
306 sou:=[[string,"s"]],
307 short:="Apply `f' to every member of `l' to obtain a string. "+
308 "Then concatenate all these strings intermixed with `sep' and "+
309 "return the result.",
310 ex:=["Stringify:=function(arg) return SPrint(arg[1]); end;\n"+
311 "Mapconcat(Stringify,[E,1,\"test\"],\", \");"],
312 see:=[DocGenHashByString("Mapconcat(func,list)")]), _Mapconcat_func_list_string);
313 InstallMethod(
314 rec(
315 kind:="FUNCTION",
316 name:="Mapconcat",
317 sin:=[[func,"f"],[list,"l"]],
318 sou:=[[string,"s"]],
319 short:="Apply `f' to every member of `l' to obtain a string. "+
320 "Then concatenate all these strings intermixed with a space and "+
321 "return the result.",
322 ex:=["Stringify:=function(arg) return SPrint(arg[1]); end;\n"+
323 "Mapconcat(Stringify,[E,1,\"test\"]);"],
324 see:=[DocGenHashByString("Mapconcat(func,list,string)")]), _Mapconcat_func_list);
325
326
327
328 #############################################################################
329 ##
330 #F Filtered( <list>, <func> ) . . . . extract elements that have a property
331 ##
332 InstallMethod(
333 rec(
334 kind:="FUNCTION",
335 name:="Filtered",
336 sin:=[[func,"pred"],[list,"l"]],
337 sou:=[[list,"filt"]],
338 short:="Gather elements from `l' which suffice the predicate function `pred'.\n"+
339 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
340 ex:=["Filtered(IsPrime,[1..100]);"],
341 see:=[]), _Filtered_func_list);
342 InstallMethod(
343 rec(
344 kind:="FUNCTION",
345 name:="Filtered",
346 sin:=[[list,"l"],[func,"pred"]],
347 sou:=[[list,"filt"]],
348 short:="Gather elements from `l' which suffice the predicate function `pred'.\n"+
349 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
350 ex:=["Filtered([1..100],IsPrime);"],
351 see:=[]), _Filtered_list_func);
352
353
354 #############################################################################
355 ##
356 #F Butfirst( <list> ) (a.k.a. Rest)
357 ##
358 InstallDocumentation(
359 rec(
360 kind:="FUNCTION",
361 name:="Butfirst",
362 sin:=[[list,"l"]],
363 sou:=[[list,"r"]],
364 short:="Return the list `l' without its first element.",
365 see:=[DocHash("Butfirst_(list)")]));
366 InstallDocumentation(
367 rec(
368 kind:="FUNCTION",
369 name:="Butfirst_",
370 sin:=[[list,"l"]],
371 sou:=[[list,"r"]],
372 short:="Remove the first element from the list `l'.\n"+
373 "Note: `l' is modified by side-effect.",
374 see:=[DocHash("Butfirst(list)")]));
375
376 #############################################################################
377 ##
378 #F First( <list> )
379 ##
380 InstallMethod(
381 rec(
382 kind:="FUNCTION",
383 name:="First",
384 sin:=[[list,"l"]],
385 sou:=[[any,"f"]],
386 short:="Return the first element of the list `l'.",
387 see:=[DocHash("Last(list)")]), First);
388
389 #############################################################################
390 ##
391 #F Butlast( <list> )
392 ##
393 InstallDocumentation(
394 rec(
395 kind:="FUNCTION",
396 name:="Butlast",
397 sin:=[[list,"l"]],
398 sou:=[[list,"r"]],
399 short:="Return the list `l' without its last element.",
400 see:=[DocHash("Butlast_(list)")]));
401 InstallDocumentation(
402 rec(
403 kind:="FUNCTION",
404 name:="Butlast_",
405 sin:=[[list,"l"]],
406 sou:=[[list,"r"]],
407 short:="Remove the last element from the list `l'.\n"+
408 "Note: `l' is modified by side-effect.",
409 see:=[DocHash("Butlast(list)")]));
410
411 #############################################################################
412 ##
413 #F Last( <list> )
414 ##
415 InstallMethod(
416 rec(
417 kind:="FUNCTION",
418 name:="Last",
419 sin:=[[list,"l"]],
420 sou:=[[any,"r"]],
421 short:="Return the last element of the list `l'.",
422 see:=[DocHash("First(list)")]), Last);
423
424
425 #############################################################################
426 ##
427 ##
428 InstallDocumentation(
429 rec(
430 kind:="FUNCTION",
431 name:="Mapc",
432 sin:=[[func,"f"],[list,"l"]],
433 sou:=[],
434 short:="Apply 'f' on each element of 'l' _without_ modifying 'l'."));
435
436 #############################################################################
437 ##
438 #F RunHookWithArg( <list>, <any> ) . . . . . . . .
439 ##
440 InstallDocumentation(
441 rec(
442 kind:="FUNCTION",
443 name:="RunHookWithArg",
444 sin:=[[list,"hook"],[any,"arg"]],
445 sou:=[],
446 short:="Run each function of the list `hook' with `arg' as argument.\n"+
447 "This is unlike Mapc which takes _one_ function which acts on a list "+
448 "of arguments.",
449 ex:=["RunHookWithArg([i->i*2, i->i*3, i->i*4],2);"]));
450
451
452 #############################################################################
453 ##
454 #F Concatenation( <list>, <list> ) . . . . . . . . . concatentation of lists
455 ##
456 InstallDocumentation(
457 rec(
458 kind:="FUNCTION",
459 name:="Concatenation",
460 sin:=[[list,"l1"],[list,"l2"]],
461 sou:=[[list,"l"]],
462 short:="Concatenate the lists `l1' and `l2' and return the result.",
463 ex:=["Concatenation([1,2],[3,4]);"],
464 see:=[]));
465
466 #############################################################################
467 ##
468 #F Flat( <list> ) . . . . . . . list of elements of a nested list structure
469 ##
470 InstallDocumentation(
471 rec(
472 kind:="FUNCTION",
473 name:="Flat",
474 sin:=[[list,"l"]],
475 sou:=[[list,"f"]],
476 short:="Flatten `l' by recursing into a nested list structure and "+
477 "fetching all atomary (i.e. non-lists) elements and return the "+
478 "result.",
479 ex:=["l:=[[1],[2,3,4]];\n"+
480 "Flat(l);"],
481 see:=[]));
482
483 #############################################################################
484 ##
485 #F Reversed( <list> ) . . . . . . . . . . . reverse the elements in a list
486 ##
487 InstallDocumentation(
488 rec(
489 kind:="FUNCTION",
490 name:="Reversed",
491 sin:=[[list,"l"]],
492 sou:=[[list,"r"]],
493 short:="Reverse `l' and return the result.",
494 ex:=["l:=[1,2,3,4];\n"+
495 "Reversed(l);"],
496 see:=[]));
497
498
499 #############################################################################
500 ##
501 #F Filter( <func> ) . . . . . . . . . extract elements that have a property
502 ##
503 InstallDocumentation(
504 rec(
505 kind:="FUNCTION",
506 name:="Filter",
507 sin:=[[func,"pred"]],
508 sou:=[[func,"filt"]],
509 short:="Construct a functional `filt(<list> l) -> <list>' "+
510 "which gathers elements from `l' which suffice the predicate "+
511 "function `pred' which has to have out-signature `-> elt-alg^boo'.",
512 ex:=["f:=Filter(IsPrime);\n"+
513 "f([1..100]);\n"],
514 see:=[]));
515
516
517 #############################################################################
518 ##
519 #F Number( <list> [, <func>] ) . . . . . count elements that have a property
520 ##
521 InstallMethod(
522 rec(
523 kind:="FUNCTION",
524 name:="Number",
525 sin:=[[list,"l"],[func,"pred"]],
526 sou:=[[elt-ord^rat]],
527 short:="Return the number of elements from `l' which suffice the "+
528 "predicate function `pred'.\n"+
529 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
530 ex:=["Number([1..100],IsPrime);"],
531 see:=[]), _Number_list_func);
532 InstallMethod(
533 rec(
534 kind:="FUNCTION",
535 name:="Number",
536 sin:=[[func,"pred"],[list,"l"]],
537 sou:=[[elt-ord^rat]],
538 short:="Return the number of elements from `l' which suffice the "+
539 "predicate function `pred'.\n"+
540 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
541 ex:=["Number(IsPrime,[1..100]);"],
542 see:=[]), _Number_func_list);
543 InstallMethod(
544 rec(
545 kind:="FUNCTION",
546 name:="Number",
547 sin:=[[list,"l"]],
548 sou:=[[elt-ord^rat]],
549 short:="Count the number of elements in `l'.",
550 ex:=["Number([101,102,103]);",
551 "Number([1,2,3,,,,,,4]);"],
552 see:=[]), _Number_list);
553 InstallMethod(
554 rec(
555 kind:="FUNCTION",
556 name:="Number",
557 sin:=[[func,"pred"]],
558 sou:=[[func,"ctr"]],
559 short:="Construct a functional `ctr(<list> l) -> elt-ord^rat' "+
560 "which returns the number of elements from `l' which suffice "+
561 "the predicate function `pred'.\n"+
562 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
563 ex:=["f:=Number(IsPrime);\n"+
564 "f([1..100]);"],
565 see:=[]), _Number_func);
566
567 InstallMethod(
568 rec(
569 kind:="FUNCTION",
570 name:="Number",
571 sin:=[[string,"s"],[func,"pred"]],
572 sou:=[[elt-ord^rat]],
573 short:="Return the number of characters from `s' which suffice the "+
574 "predicate function `pred'.\n"+
575 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
576 ex:=["Number(\"some really random text\",i->i in \"aeiou\");"],
577 see:=[]), _Number_list_func);
578 InstallMethod(
579 rec(
580 kind:="FUNCTION",
581 name:="Number",
582 sin:=[[func,"pred"],[string,"s"]],
583 sou:=[[elt-ord^rat]],
584 short:="Return the number of characters from `s' which suffice the "+
585 "predicate function `pred'.\n"+
586 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
587 ex:=["Number(i->not i in \"aeiou\",\"hm, this is a demonstration text\");"],
588 see:=[]), _Number_func_list);
589 InstallMethod(
590 rec(
591 kind:="FUNCTION",
592 name:="Number",
593 sin:=[[string,"s"]],
594 sou:=[[elt-ord^rat]],
595 short:="Count the number of characters in `s'.",
596 ex:=["Number(\"How many characters do I have?\");"],
597 see:=[]), _Size_list);
598
599 InstallMethod(
600 rec(
601 kind:="FUNCTION",
602 name:="Number",
603 sin:=[[seq(),"s"],[func,"pred"]],
604 sou:=[[elt-ord^rat]],
605 short:="Return the number of elements from `s' which suffice the "+
606 "predicate function `pred'.\n"+
607 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
608 ex:=["Number(Sequence([1..100]),IsPrime);"],
609 see:=[]), _Number_list_func);
610 InstallMethod(
611 rec(
612 kind:="FUNCTION",
613 name:="Number",
614 sin:=[[func,"pred"],[seq(),"s"]],
615 sou:=[[elt-ord^rat]],
616 short:="Return the number of elements from `s' which suffice the "+
617 "predicate function `pred'.\n"+
618 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
619 ex:=["Number(IsPrime,Sequence([1..100]));"],
620 see:=[]), _Number_func_list);
621 InstallMethod(
622 rec(
623 kind:="FUNCTION",
624 name:="Number",
625 sin:=[[seq(),"s"]],
626 sou:=[[elt-ord^rat]],
627 short:="Count the number of elements in `s'.",
628 ex:=["Number(Sequence([101,102,103]));"],
629 see:=[]), _Number_list);
630
631
632
633 #############################################################################
634 ##
635 #F ForAll( <list>, <func> ) . . test a property for all elements of a list
636 ##
637 InstallMethod(
638 rec(
639 kind:="FUNCTION",
640 name:="ForAll",
641 sin:=[[list,"l"],[func,"pred"]],
642 sou:=[[elt-alg^boo]],
643 short:="Return true iff every member of `l' suffices the predicate "+
644 "function `pred'.\n"+
645 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
646 ex:=["ForAll([1..100],IsPrime);",
647 "ForAll([2,4,6,8,100],IsEven);"],
648 see:=[]), _ForAll_list_func);
649 InstallMethod(
650 rec(
651 kind:="FUNCTION",
652 name:="ForAll",
653 sin:=[[func,"pred"],[list,"l"]],
654 sou:=[[elt-alg^boo]],
655 short:="Return true iff every member of `l' suffices the predicate "+
656 "function `pred'.\n"+
657 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
658 ex:=["ForAll(IsPrime,[1..100]);",
659 "ForAll(IsEven,[2,4,6,8,100]);"],
660 see:=[]), _ForAll_func_list);
661 InstallMethod(
662 rec(
663 kind:="FUNCTION",
664 name:="ForAll",
665 sin:=[[func,"pred"]],
666 sou:=[[func,"fa"]],
667 short:="Construct a functional `fa(<list> l) -> elt-alg^boo' "+
668 "which returns true iff every member of `l' suffices the predicate "+
669 "function `pred'.\n"+
670 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
671 ex:=["l:=[Random(10),Random(10)];\n"+
672 "f:=ForAll(IsEven);\n"+
673 "l; f(l);"],
674 see:=[]), _ForAll_func);
675
676 InstallMethod(
677 rec(
678 kind:="FUNCTION",
679 name:="ForAll",
680 sin:=[[seq(),"s"],[func,"pred"]],
681 sou:=[[elt-alg^boo]],
682 short:="Return true iff every element of `s' suffices the predicate "+
683 "function `pred'.\n"+
684 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
685 ex:=["ForAll(Sequence([1..100]),IsPrime);",
686 "ForAll(Sequence([2,4,6,8,100]),IsEven);"],
687 see:=[DocHash("ForAll(list,func)")]), _ForAll_list_func);
688 InstallMethod(
689 rec(
690 kind:="FUNCTION",
691 name:="ForAll",
692 sin:=[[func,"pred"],[seq(),"s"]],
693 sou:=[[elt-alg^boo]],
694 short:="Return true iff every element of `s' suffices the predicate "+
695 "function `pred'.\n"+
696 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
697 ex:=["ForAll(IsPrime,Sequence([1..100]));",
698 "ForAll(IsEven,Sequence([2,4,6,8,100]));"],
699 see:=[DocHash("ForAll(func,list)")]), _ForAll_func_list);
700
701
702 #############################################################################
703 ##
704 #F ForAny( <list>, <func> ) . . . test a property for any element of a list
705 ##
706 InstallMethod(
707 rec(
708 kind:="FUNCTION",
709 name:="ForAny",
710 sin:=[[list,"l"],[func,"pred"]],
711 sou:=[[elt-alg^boo]],
712 short:="Return true iff every member of `l' suffices the predicate "+
713 "function `pred'.\n"+
714 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
715 ex:=["ForAny([1..100],IsPrime);",
716 "ForAny([2,4,6,8,100],IsEven);"],
717 see:=[]), _ForAny_list_func);
718 InstallMethod(
719 rec(
720 kind:="FUNCTION",
721 name:="ForAny",
722 sin:=[[func,"pred"],[list,"l"]],
723 sou:=[[elt-alg^boo]],
724 short:="Return true iff every member of `l' suffices the predicate "+
725 "function `pred'.\n"+
726 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
727 ex:=["ForAny(IsPrime,[1..100]);",
728 "ForAny(IsOdd,[2,4,6,8,100]);"],
729 see:=[]), _ForAny_func_list);
730 InstallMethod(
731 rec(
732 kind:="FUNCTION",
733 name:="ForAny",
734 sin:=[[func,"pred"]],
735 sou:=[[func,"fa"]],
736 short:="Construct a functional `fa(<list> l) -> elt-alg^boo' "+
737 "which returns true iff every member of `l' suffices the predicate "+
738 "function `pred'.\n"+
739 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
740 ex:=["l:=[Random(1000)..1000+Random(1000)];\n"+
741 "f:=ForAny(IsPrime);\n"+
742 "l; f(l);"],
743 see:=[]), _ForAny_func);
744
745 InstallMethod(
746 rec(
747 kind:="FUNCTION",
748 name:="ForAny",
749 sin:=[[seq(),"s"],[func,"pred"]],
750 sou:=[[elt-alg^boo]],
751 short:="Return true iff every element of `s' suffices the predicate "+
752 "function `pred'.\n"+
753 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
754 ex:=["ForAny(Sequence([1..100]),IsPrime);",
755 "ForAny(Sequence([2,4,6,8,100]),IsEven);"],
756 see:=[DocHash("ForAny(list,func)")]), _ForAny_list_func);
757 InstallMethod(
758 rec(
759 kind:="FUNCTION",
760 name:="ForAny",
761 sin:=[[func,"pred"],[seq(),"s"]],
762 sou:=[[elt-alg^boo]],
763 short:="Return true iff every element of `s' suffices the predicate "+
764 "function `pred'.\n"+
765 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
766 ex:=["ForAny(IsPrime,Sequence([1..100]));",
767 "ForAny(IsOdd,Sequence([2,4,6,8,100]));"],
768 see:=[DocHash("ForAny(func,list)")]), _ForAny_func_list);
769
770
771 #############################################################################
772 ##
773 #F First( <list>, <func> ) . . find first element in a list with a property
774 ##
775 InstallMethod(
776 rec(
777 kind:="FUNCTION",
778 name:="First",
779 sin:=[[list,"l"],[func,"pred"]],
780 opt:=[__FAILUREDOC],
781 sou:=[[any]],
782 short:="Find the first element which suffices the predicate function `pred' "+
783 "and return it.\n"+
784 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
785 ex:=["First([1..100],IsPrime);",
786 "First([2,4,6,8,12,50,100],i->i mod 5=0);"],
787 see:=[DocHash("Last(list,func)")]), _First_list_func,
788 rec(DefaultValues:=__FAILUREREC));
789 InstallMethod(
790 rec(
791 kind:="FUNCTION",
792 name:="First",
793 sin:=[[func,"pred"],[list,"l"]],
794 opt:=[__FAILUREDOC],
795 sou:=[[any]],
796 short:="Find the first element which suffices the predicate function `pred' "+
797 "and return it.\n"+
798 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
799 ex:=["First(IsPrime,[1..100]);",
800 "First(IsOdd,[2,4,6,8,100]);"],
801 see:=[DocHash("Last(func,list)")]), _First_func_list,
802 rec(DefaultValues:=__FAILUREREC));
803 InstallMethod(
804 rec(
805 kind:="FUNCTION",
806 name:="First",
807 sin:=[[func,"pred"]],
808 opt:=[__FAILUREDOC],
809 sou:=[[func,"fir"]],
810 short:="Construct a functional `fir(<list> l) -> any' "+
811 "which finds and returns the first element which suffices the predicate "+
812 "function `pred' and returns it.\n"+
813 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
814 ex:=["l:=[Random(1000)..1000+Random(1000)];\n"+
815 "f:=First(i->i mod 17=0);\n"+
816 "l; f(l);"],
817 see:=[DocHash("Last(func)")]), _First_func,
818 rec(DefaultValues:=__FAILUREREC));
819
820 InstallMethod(
821 rec(
822 kind:="FUNCTION",
823 name:="First",
824 sin:=[[string,"s"],[func,"pred"]],
825 opt:=[__FAILUREDOC],
826 sou:=[[char]],
827 short:="Find the first character which suffices the predicate function `pred' "+
828 "and return it.\n"+
829 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
830 ex:=["First(\"abcdefzyx\",i->(i='d' or i='z'));"],
831 see:=[DocHash("Last(string,func)")]), _First_list_func,
832 rec(DefaultValues:=__FAILUREREC));
833 InstallMethod(
834 rec(
835 kind:="FUNCTION",
836 name:="First",
837 sin:=[[func,"pred"],[string,"s"]],
838 opt:=[__FAILUREDOC],
839 sou:=[[char]],
840 short:="Find the first character which suffices the predicate function `pred' "+
841 "and return it.\n"+
842 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
843 ex:=["First(i->(i='d' or i='z'),\"abcdefzyx\");"],
844 see:=[DocHash("Last(func,string)")]), _First_func_list,
845 rec(DefaultValues:=__FAILUREREC));
846
847 InstallMethod(
848 rec(
849 kind:="FUNCTION",
850 name:="First",
851 sin:=[[seq(),"s"],[func,"pred"]],
852 opt:=[__FAILUREDOC],
853 sou:=[[any]],
854 short:="Find the first element which suffices the predicate function `pred' "+
855 "and return it.\n"+
856 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
857 ex:=["First(Sequence([1..100]),IsPrime);",
858 "First(Sequence([2,4,6,8,12,50,100]),i->i mod 5=0);"],
859 see:=[DocHash("Last(seq(),func)")]), _First_list_func,
860 rec(DefaultValues:=__FAILUREREC));
861 InstallMethod(
862 rec(
863 kind:="FUNCTION",
864 name:="First",
865 sin:=[[func,"pred"],[seq(),"s"]],
866 opt:=[__FAILUREDOC],
867 sou:=[[any]],
868 short:="Find the first element which suffices the predicate function `pred' "+
869 "and return it.\n"+
870 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
871 ex:=["First(IsPrime,Sequence([1..100]));",
872 "First(IsOdd,Sequence([2,4,6,8,100]));"],
873 see:=[DocHash("Last(func,list)")]), _First_func_list,
874 rec(DefaultValues:=__FAILUREREC));
875
876
877 #############################################################################
878 ##
879 #F Last( <list>, <func> ) . . . find last element in a list with a property
880 ##
881 InstallMethod(
882 rec(
883 kind:="FUNCTION",
884 name:="Last",
885 sin:=[[list,"l"],[func,"pred"]],
886 opt:=[__FAILUREDOC],
887 sou:=[[any]],
888 short:="Find the last element which suffices the predicate function `pred' "+
889 "and return it.\n"+
890 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
891 ex:=["Last([1..100],IsPrime);",
892 "Last([2,4,6,8,12,50,100],i->i mod 3=0);"],
893 see:=[DocHash("First(list,func)")]), _Last_list_func,
894 rec(DefaultValues:=__FAILUREREC));
895 InstallMethod(
896 rec(
897 kind:="FUNCTION",
898 name:="Last",
899 sin:=[[func,"pred"],[list,"l"]],
900 opt:=[__FAILUREDOC],
901 sou:=[[any]],
902 short:="Find the last element which suffices the predicate function `pred' "+
903 "and return it.\n"+
904 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
905 ex:=["Last(IsPrime,[1..100]);",
906 "Last(IsOdd,[2,4,6,8,100]);"],
907 see:=[DocHash("First(func,list)")]), _Last_func_list,
908 rec(DefaultValues:=__FAILUREREC));
909 InstallMethod(
910 rec(
911 kind:="FUNCTION",
912 name:="Last",
913 sin:=[[func,"pred"]],
914 opt:=[__FAILUREDOC],
915 sou:=[[func,"las"]],
916 short:="Construct a functional `las(<list> l) -> any' "+
917 "which finds and returns the last element which suffices the predicate "+
918 "function `pred' and returns it.\n"+
919 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
920 ex:=["l:=[Random(1000)..1000+Random(1000)];\n"+
921 "f:=Last(i->i mod 17=0);\n"+
922 "l; f(l);"],
923 see:=[DocHash("First(func)")]), _Last_func,
924 rec(DefaultValues:=__FAILUREREC));
925
926 InstallMethod(
927 rec(
928 kind:="FUNCTION",
929 name:="Last",
930 sin:=[[string,"s"],[func,"pred"]],
931 opt:=[__FAILUREDOC],
932 sou:=[[char]],
933 short:="Find the last character which suffices the predicate function `pred' "+
934 "and return it.\n"+
935 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
936 ex:=["Last(\"test\",i->i<'s');"],
937 see:=[DocHash("First(string,func)")]), _Last_list_func,
938 rec(DefaultValues:=__FAILUREREC));
939 InstallMethod(
940 rec(
941 kind:="FUNCTION",
942 name:="Last",
943 sin:=[[func,"pred"],[string,"s"]],
944 opt:=[__FAILUREDOC],
945 sou:=[[char]],
946 short:="Find the last character which suffices the predicate function `pred' "+
947 "and return it.\n"+
948 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
949 ex:=["Last(i->i>'f',\"this is a demo.\");"],
950 see:=[DocHash("First(func,string)")]), _Last_func_list,
951 rec(DefaultValues:=__FAILUREREC));
952
953 InstallMethod(
954 rec(
955 kind:="FUNCTION",
956 name:="Last",
957 sin:=[[seq(),"s"],[func,"pred"]],
958 opt:=[__FAILUREDOC],
959 sou:=[[any]],
960 short:="Find the last element which suffices the predicate function `pred' "+
961 "and return it.\n"+
962 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
963 ex:=["Last(Sequence([1..100]),IsPrime);",
964 "Last(Sequence([2,4,6,8,12,50,100]),i->i mod 3=0);"],
965 see:=[DocHash("First(seq(),func)")]), _Last_list_func,
966 rec(DefaultValues:=__FAILUREREC));
967 InstallMethod(
968 rec(
969 kind:="FUNCTION",
970 name:="Last",
971 sin:=[[func,"pred"],[seq(),"s"]],
972 opt:=[__FAILUREDOC],
973 sou:=[[any]],
974 short:="Find the last element which suffices the predicate function `pred' "+
975 "and return it.\n"+
976 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
977 ex:=["Last(IsPrime,Sequence([1..100]));",
978 "Last(IsOdd,Sequence([2,4,6,8,100]));"],
979 see:=[DocHash("First(func,seq())")]), _Last_func_list,
980 rec(DefaultValues:=__FAILUREREC));
981
982
983 #############################################################################
984 ##
985 #F PositionProperty( <list>, <func> ) position of an element with a property
986 ##
987 InstallMethod(
988 rec(
989 kind:="FUNCTION",
990 name:="PositionProperty",
991 sin:=[[list,"l"],[func,"pred"]],
992 opt:=[__FAILUREDOC],
993 sou:=[[elt-ord^rat]],
994 short:="Return the position of the first element of `l' which suffices "+
995 "the predicate function `pred'.\n"+
996 "Return FAILURE if no such element exists in `l'.\n"+
997 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
998 ex:=["PositionProperty([50..100],IsPrime);",
999 "PositionProperty([2,4,6,8,12,50,100],i->i mod 5=0);"],
1000 see:=[]), _PositionProperty_list_func);
1001 InstallMethod(
1002 rec(
1003 kind:="FUNCTION",
1004 name:="PositionProperty",
1005 sin:=[[func,"pred"],[list,"l"]],
1006 opt:=[__FAILUREDOC],
1007 sou:=[[elt-ord^rat]],
1008 short:="Return the position of the first element of `l' which suffices "+
1009 "the predicate function `pred'.\n"+
1010 "Return FAILURE if no such element exists in `l'.\n"+
1011 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
1012 ex:=["PositionProperty(IsPrime,[1..100]);",
1013 "PositionProperty(IsOdd,[2,4,6,8,100]);"],
1014 see:=[]), _PositionProperty_func_list);
1015 InstallMethod(
1016 rec(
1017 kind:="FUNCTION",
1018 name:="PositionProperty",
1019 sin:=[[func,"pred"]],
1020 opt:=[__FAILUREDOC],
1021 sou:=[[func,"pos"]],
1022 short:="Construct a functional `pos(<list> l) -> elt-ord^rat' "+
1023 "which returns the position of the first element of `l' which suffices "+
1024 "the predicate function `pred'.\n"+
1025 "Return FAILURE if no such element exists in `l'.\n"+
1026 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
1027 ex:=["l:=[Random(1000)..1000+Random(1000)];;\n"+
1028 "f:=PositionProperty(i->i mod 17=0);;\n"+
1029 "l; f(l);"],
1030 see:=[]), _PositionProperty_func);
1031
1032 InstallMethod(
1033 rec(
1034 kind:="FUNCTION",
1035 name:="PositionProperty",
1036 sin:=[[string,"s"],[func,"pred"]],
1037 opt:=[__FAILUREDOC],
1038 sou:=[[elt-ord^rat]],
1039 short:="Return the position of the first character of `s' which suffices "+
1040 "the predicate function `pred'.\n"+
1041 "Return FAILURE if no such character exists in `s'.\n"+
1042 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
1043 ex:=["PositionProperty(\"some random text\",i->i in \"uvwxyz\");"],
1044 see:=[]), _PositionProperty_list_func);
1045 InstallMethod(
1046 rec(
1047 kind:="FUNCTION",
1048 name:="PositionProperty",
1049 sin:=[[func,"pred"],[string,"s"]],
1050 opt:=[__FAILUREDOC],
1051 sou:=[[elt-ord^rat]],
1052 short:="Return the position of the first character of `s' which suffices "+
1053 "the predicate function `pred'.\n"+
1054 "Return FAILURE if no such character exists in `s'.\n"+
1055 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
1056 ex:=["PositionProperty(i->i in \"aeiou\",\"some random text\");"],
1057 see:=[]), _PositionProperty_func_list);
1058
1059 InstallMethod(
1060 rec(
1061 kind:="FUNCTION",
1062 name:="PositionProperty",
1063 sin:=[[seq(),"s"],[func,"pred"]],
1064 opt:=[__FAILUREDOC],
1065 sou:=[[elt-ord^rat]],
1066 short:="Return the position of the first element of `s' which suffices "+
1067 "the predicate function `pred'.\n"+
1068 "Return FAILURE if no such element exists in `s'.\n"+
1069 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
1070 ex:=["PositionProperty(Sequence([50..100]),IsPrime);",
1071 "PositionProperty(Sequence([2,4,6,8,12,50,100]),i->i mod 5=0);"],
1072 see:=[DocHash("PositionProperty(list,func)")]), _PositionProperty_list_func);
1073 InstallMethod(
1074 rec(
1075 kind:="FUNCTION",
1076 name:="PositionProperty",
1077 sin:=[[func,"pred"],[seq(),"s"]],
1078 opt:=[__FAILUREDOC],
1079 sou:=[[elt-ord^rat]],
1080 short:="Return the position of the first element of `s' which suffices "+
1081 "the predicate function `pred'.\n"+
1082 "Return FAILURE if no such element exists in `s'.\n"+
1083 "Note: Apparently `pred' must have `-> elt-alg^boo' out-signature.",
1084 ex:=["PositionProperty(IsPrime,Sequence([1..100]));",
1085 "PositionProperty(IsOdd,Sequence([2,4,6,8,100]));"],
1086 see:=[DocHash("PositionProperty(func,list)")]), _PositionProperty_func_list);
1087
1088
1089
1090 #############################################################################
1091 ##
1092 #F Collected( <list> ) . . . . .
1093 ##
1094 InstallDocumentation(
1095 rec(
1096 kind:="FUNCTION",
1097 name:="Collected",
1098 sin:=[[list,"l"]],
1099 sou:=[[list,"coll"]],
1100 short:="Document me!",
1101 ex:=["Collected([1,2,3,3,2,5,4,3,2,1,4,4,3]);"],
1102 see:=[]));
1103
1104
1105 #############################################################################
1106 ##
1107 #F Equivalenceclasses( <list>, <function> ) . calculate equivalence classes
1108 #C Completely obscure function, do not use me!
1109 ##
1110 ## returns
1111 ##
1112 ## rec(
1113 ## classes := <list>,
1114 ## indices := <list>
1115 ## )
1116 ##
1117 #InstallDocumentation(
1118 # rec(
1119 # kind:="FUNCTION",
1120 # name:="Equivalenceclasses",
1121 # sin:=[[list,"l"],[func,"equi"]],
1122 # sou:=[[record]],
1123 # short:="Document me!",
1124 # ex:=["f:=function(i,j) return i-j=2 or j-i=2; end;\n"+
1125 # "Equivalenceclasses([1..100],f); WTF?"],
1126 # see:=[]));
1127
1128
1129 #############################################################################
1130 ##
1131 #F Cartesian( <list>, <list>.. ) . . . . . . . . cartesian product of lists
1132 ##
1133 InstallDocumentation(
1134 rec(
1135 kind:="FUNCTION",
1136 name:="Cartesian",
1137 sin:=[[list,"l1"],[list,"l2"]],
1138 sou:=[[list,"l1xl2"]],
1139 short:="Return list obtained by the cartesian product of `l1' and `l2'.",
1140 ex:=["Cartesian([1,2,3,4],[1,I]);"],
1141 see:=[]));
1142
1143
1144 #############################################################################
1145 ##
1146 #F Sort( <list> ) . . . . . . . . . . . . . . . . . . . . . . . sort a list
1147 ##
1148 ## Sort() uses Shell's diminishing increment sort, which extends bubblesort.
1149 ## The bubble sort works by running through the list again and again,
1150 ## each time exchanging pairs of adjacent elements which are out of order.
1151 ## Thus large elements "bubble" to the top, hence the name of the method.
1152 ## However elements need many moves to come close to their final position.
1153 ## In shellsort the first passes do not compare element j with its neighbor
1154 ## but with the element j+h, where h is larger than one. Thus elements that
1155 ## aren't at their final position make large moves towards the destination.
1156 ## This increment h is diminished, until during the last pass it is one.
1157 ## A good sequence of incremements is given by Knuth: (3^k-1)/2,... 13,4,1.
1158 ## For this sequence shellsort uses on average approximatly N^1.25 moves.
1159 ##
1160 ## Shellsort is the method of choice to sort lists for various reasons:
1161 ## Shellsort is quite easy to get right, much easier than, say, quicksort.
1162 ## It runs as fast as quicksort for lists with less than ~5000 elements.
1163 ## It handles both almost sorted and reverse sorted lists very good.
1164 ## It works well in the presence of duplicate elements in the list.
1165 ## Says Sedgewick: "In short, if you have a sorting problem, use the above
1166 ## program, then determine whether the extra effort required to replace it
1167 ## with a sophisticated method will be worthwile."
1168 ##
1169 ## Donald Knuth, The Art of Computer Programming, Vol.3, AddWes 1973, 84-95
1170 ## Donald Shell, CACM 2, July 1959, 30-32
1171 ## Robert Sedgewick, Algorithms 2nd ed., AddWes 1988, 107-123
1172 ##
1173 InstallDocumentation(
1174 rec(
1175 kind:="FUNCTION",
1176 name:="Sort",
1177 sin:=[[list,"l"]],
1178 sou:=[],
1179 short:="Sort `l'.",
1180 ex:=["A:=[1,14,3,7,2,1];\n"+
1181 "Sort(A); A;"],
1182 see:=[]));
1183
1184
1185 #############################################################################
1186 ##
1187 #F SortParallel(<list>,<list2>) . . . . . . . . sort two lists in parallel
1188 ##
1189 InstallDocumentation(
1190 rec(
1191 kind:="FUNCTION",
1192 name:="SortParallel",
1193 sin:=[[list,"l1"],[list,"l2"]],
1194 sou:=[],
1195 short:="Document me!",
1196 ex:=[],
1197 see:=[]));
1198
1199
1200 #############################################################################
1201 ##
1202 #F Permuted( <list>, <perm> ) . . . apply permutation <perm> to list <list>
1203 ##
1204 InstallDocumentation(
1205 rec(
1206 kind:="FUNCTION",
1207 name:="Permuted",
1208 sin:=[[list,"l"],[elt-grp^per,"perm"]],
1209 sou:=[],
1210 short:="Document me!",
1211 ex:=[],
1212 see:=[]));
1213
1214
1215
1216 #############################################################################
1217 ##
1218 #F PositionSorted( <list>, <elm> ) . . . . find an element in a sorted list
1219 ##
1220 ## 'PositionSorted' uses a binary search instead of the linear search used
1221 ## 'Position'. This takes log to base 2 of 'Size( <list> )' comparisons.
1222 ## The list <list> must be sorted however for 'PositionSorted' to work.
1223 ##
1224 ## Jon Bentley, Programming Pearls, AddWes 1986, 85-88
1225 ##
1226 InstallDocumentation(
1227 rec(
1228 kind:="FUNCTION",
1229 name:="PositionSorted",
1230 sin:=[[list,"l"],[any,"elm"]],
1231 sou:=[[elt-ord^rat]],
1232 short:="Returns the position of `elm' in the sorted list `l'.",
1233 ex:=["A:=[2,3,5,7,11,13,17,19];\n"+
1234 "PositionSorted(A,11);"],
1235 see:=[]));
1236
1237
1238
1239 #############################################################################
1240 ##
1241 #F Product( <list> ) . . . . . . . . . . . product of the elements in a list
1242 ##
1243 ## 'Product( <list> )' \\
1244 ## 'Product( <list>, <func> )'
1245 ##
1246 ## When used in the first way 'Product' returns the product of the elements
1247 ## of the list <list>. When used in the second way 'Product' applies the
1248 ## function <func>, which must be a function taking one argument, and
1249 ## returns the product of the results. In either case if <list> is empty
1250 ## 'Product' returns 1.
1251 ##
1252 InstallMethod(
1253 rec(
1254 kind:="FUNCTION",
1255 name:="Product",
1256 sin:=[[list,"l"]],
1257 sou:=[[any]],
1258 short:="Return the product of the elements of `l'.\n"+
1259 "Note: `l' may consist of elements of different types. "+
1260 "Generally `Product' works on everything `*' can operate on.",
1261 ex:=["Product([2,3,5,7]);",
1262 "Product([2,\"1,2 \",2]);"],
1263 see:=[]), _Product_list);
1264 InstallMethod(
1265 rec(
1266 kind:="FUNCTION",
1267 name:="Product",
1268 sin:=[[seq(),"s"]],
1269 sou:=[[any]],
1270 short:="Return the product of the elements of `s'.",
1271 ex:=["Product(Sequence([2,3,5,7]));"],
1272 see:=[DocHash("Product(list)")]), _Product_list);
1273 InstallMethod(
1274 rec(
1275 kind:="FUNCTION",
1276 name:="Product",
1277 sin:=[[tup(),"t"]],
1278 sou:=[[any]],
1279 short:="Return the product of the elements of `t'.",
1280 ex:=["Product(Tuple([2,3,5,7]));",
1281 "Product(Tuple([2,\"a,b \",5]));"],
1282 see:=[DocHash("Product(list)")]), _Product_list);
1283 InstallMethod(
1284 rec(
1285 kind:="FUNCTION",
1286 name:="Product",
1287 sin:=[[list,"l"],[func,"f"]],
1288 sou:=[[any]],
1289 short:="Document me!",
1290 ex:=[],
1291 see:=[]), _Product_list_func);
1292 InstallMethod(
1293 rec(
1294 kind:="FUNCTION",
1295 name:="Product",
1296 sin:=[[func,"l"],[list,"l"]],
1297 sou:=[[any]],
1298 short:="Document me!",
1299 ex:=[],
1300 see:=[]), _Product_func_list);
1301 InstallMethod(
1302 rec(
1303 kind:="FUNCTION",
1304 name:="Product",
1305 sin:=[[func,"l"]],
1306 sou:=[[any]],
1307 short:="Document me!",
1308 ex:=[],
1309 see:=[]), _Product_func);
1310
1311
1312 #############################################################################
1313 ##
1314 #F Sum( <list> ) . . . . . . . . . . . . . . . sum of the elements of a list
1315 ##
1316 InstallMethod(
1317 rec(
1318 kind:="FUNCTION",
1319 name:="Sum",
1320 sin:=[[list,"l"]],
1321 sou:=[[any]],
1322 short:="Return the sum of the elements of `l'.\n"+
1323 "Note: `l' may consist of elements of different types. "+
1324 "Generally `Sum' works on everything `+' can operate on.",
1325 ex:=["Sum([1..100]);",
1326 "Sum([\"a\",\"b\",\"c\"]);"],
1327 see:=[]), _Sum_list);
1328 InstallMethod(
1329 rec(
1330 kind:="FUNCTION",
1331 name:="Sum",
1332 sin:=[[seq(),"s"]],
1333 sou:=[[any]],
1334 short:="Return the sum of the elements of `s'.",
1335 ex:=["Sum(Sequence([1..100]));",
1336 "Sum(Sequence([\"a\",\"b\",\"c\"]));"],
1337 see:=[]), _Sum_list);
1338 InstallMethod(
1339 rec(
1340 kind:="FUNCTION",
1341 name:="Sum",
1342 sin:=[[tup(),"t"]],
1343 sou:=[[any]],
1344 short:="Return the sum of the elements of `t'.",
1345 ex:=["Sum(Tuple([1..100]));",
1346 "Sum(Tuple([\"a\",\"b\",\"c\"]));"],
1347 see:=[]), _Sum_list);
1348 InstallMethod(
1349 rec(
1350 kind:="FUNCTION",
1351 name:="Sum",
1352 sin:=[[list,"l"],[func,"f"]],
1353 sou:=[[any]],
1354 short:="Document me!",
1355 ex:=[],
1356 see:=[]), _Sum_list_func);
1357 InstallMethod(
1358 rec(
1359 kind:="FUNCTION",
1360 name:="Sum",
1361 sin:=[[func,"f"],[list,"l"]],
1362 sou:=[[any]],
1363 short:="Document me!",
1364 ex:=[],
1365 see:=[]), _Sum_func_list);
1366 InstallMethod(
1367 rec(
1368 kind:="FUNCTION",
1369 name:="Sum",
1370 sin:=[[func,"f"]],
1371 sou:=[[any]],
1372 short:="Document me!",
1373 ex:=[],
1374 see:=[]), _Sum_func);
1375
1376
1377 #############################################################################
1378 ##
1379 #F Iterated( <list>, <func> ) . . . . . . . iterate a function over a list
1380 ##
1381 InstallDocumentation(
1382 rec(
1383 kind:="FUNCTION",
1384 name:="Iterated",
1385 sin:=[[list,"l"],[func,"f"]],
1386 sou:=[[any]],
1387 short:="Document me!",
1388 ex:=[],
1389 see:=[]));
1390
1391
1392 #############################################################################
1393 ##
1394 #F Maximum( <obj>, <obj>... ) . . . . . . . . . . . . . maximum of integers
1395 ##
1396 InstallDocumentation(
1397 rec(
1398 kind:="FUNCTION",
1399 name:="Maximum",
1400 sin:=[[set,"s"]],
1401 sou:=[[any]],
1402 short:="Determine and return the maximal element of `s'.\n"+
1403 "Note: `s' may also be a list (nonetheless `Set(s)' must exist).",
1404 ex:=["Maximum([3,-3,5]);",
1405 "Maximum(['a','b']);"],
1406 see:=[]));
1407 InstallDocumentation(
1408 rec(
1409 kind:="FUNCTION",
1410 name:="Maximum",
1411 sin:=[[seq(),"l"]],
1412 sou:=[[any]],
1413 short:="Determine and return the maximal element of `s'.",
1414 ex:=["Maximum(Sequence([3,-3,5]));",
1415 "Maximum(Sequence(['a','b']));"],
1416 see:=[]));
1417 InstallDocumentation(
1418 rec(
1419 kind:="FUNCTION",
1420 name:="Maximum",
1421 sin:=[[tup(),"l"]],
1422 sou:=[[any]],
1423 short:="Determine and return the maximal element in `t'.",
1424 ex:=["Maximum(Tuple([3,-3,5]));",
1425 "Maximum(Tuple(['a','b']));"],
1426 see:=[]));
1427
1428
1429 #############################################################################
1430 ##
1431 #F Minimum( <obj>, <obj>... ) . . . . . . . . . . . . . minimum of integers
1432 ##
1433 InstallDocumentation(
1434 rec(
1435 kind:="FUNCTION",
1436 name:="Minimum",
1437 sin:=[[set,"s"]],
1438 sou:=[[any]],
1439 short:="Determine and return the minimal element of `s'.\n"+
1440 "Note: `s' may also be a list (nonetheless `Set(s)' must exist).",
1441 ex:=["Minimum([3,-3,5]);",
1442 "Minimum(['a','b']);"],
1443 see:=[]));
1444 InstallDocumentation(
1445 rec(
1446 kind:="FUNCTION",
1447 name:="Minimum",
1448 sin:=[[seq(),"l"]],
1449 sou:=[[any]],
1450 short:="Determine and return the minimal element of `s'.",
1451 ex:=["Minimum(Sequence([3,-3,5]));",
1452 "Minimum(Sequence(['a','b']));"],
1453 see:=[]));
1454 InstallDocumentation(
1455 rec(
1456 kind:="FUNCTION",
1457 name:="Minimum",
1458 sin:=[[tup(),"l"]],
1459 sou:=[[any]],
1460 short:="Determine and return the minimal element in `t'.",
1461 ex:=["Minimum(Tuple([3,-3,5]));",
1462 "Minimum(Tuple(['a','b']));"],
1463 see:=[]));
1464
1465
1466 #############################################################################
1467 ##
1468 #F Remove( <list> )
1469 #F Remove( <seq> )
1470 ##
1471 InstallMethod(
1472 rec(
1473 kind:= "FUNCTION",
1474 name:= "Remove",
1475 sin := [[list,"L"],[elt-ord^rat,"pos"]],
1476 opt := [__FAILUREDOC],
1477 sou := [[list]],
1478 short := "Return the list derived from removing the element at position "+
1479 "`pos' from `L'.\n"+
1480 "Note: `pos' must not exceed the scope of `L'.\n"+
1481 "Note: This function returns the list created by the removal but does "+
1482 "not affect `L'.",
1483 ex := ["L:=[1,,3,4];\n"+
1484 "Remove(L,3); L;"],
1485 see := [DocHash("Remove_(list,elt-ord^rat)")]
1486 ), _Remove_list_eor);
1487 InstallMethod(
1488 rec(
1489 kind:= "FUNCTION",
1490 name:= "Remove_",
1491 sin := [[list,"L"],[elt-ord^rat,"pos"]],
1492 opt := [__FAILUREDOC,
1493 __SUCCESSDOC],
1494 sou := [],
1495 short := "Remove the element at position `pos' in the list `L'.\n"+
1496 "Note: `pos' must not exceed the scope of `L'.\n"+
1497 "Note: This function works by side effect and returns VOID.",
1498 ex := ["L:=[1,,3,4];\n"+
1499 "Remove_(L,3); L;"],
1500 see := [DocHash("Remove(list,elt-ord^rat)")]
1501 ), _Remove__list_eor);
1502 InstallMethod(
1503 rec(
1504 kind:="FUNCTION",
1505 name:="Remove",
1506 sin:=[[seq(),"S"],[elt-ord^rat,"pos"]],
1507 sou:=[[seq()]],
1508 short := "Return the sequence derived from removing the element at position "+
1509 "`pos' from `S'.\n"+
1510 "Note: `pos' must not exceed the scope of `S'.\n"+
1511 "Note: This function returns the sequence created by the removal but does "+
1512 "not affect `S'."), _Remove_list_eor);
1513 InstallMethod(
1514 rec(
1515 kind:="FUNCTION",
1516 name:="Remove_",
1517 sin:=[[seq(),"S"],[elt-ord^rat,"pos"]],
1518 sou:=[[]],
1519 short := "Remove the element at position `pos' in the sequence `S'.\n"+
1520 "Note: `pos' must not exceed the scope of `S'.\n"+
1521 "Note: This function works by side effect and returns VOID."), _Remove__list_eor);
1522
1523
1524 #############################################################################
1525 ##
1526 #F Add( <list> )
1527 #F Add( <seq> )
1528 #F Add( <tup> )
1529 ##
1530 InstallMethod(
1531 rec(
1532 kind:= "FUNCTION",
1533 name:= "Add_",
1534 sin := [[list,"L"],[any,"a"]],
1535 sou := [],
1536 short := "Add `a' to `L' by assigning `a' at the next position beyond the "+
1537 "scope of `L'.\n"+
1538 "Note: This function works by side effect and returns VOID.",
1539 ex := ["L:=[1,,3,4];\nAdd_(L,5); L;"],
1540 see := [DocHash("Add(list,any)"),
1541 DocHash("Append(list,list)")]), _Add__list_any);
1542 InstallMethod(
1543 rec(
1544 kind:= "FUNCTION",
1545 name:= "Add",
1546 sin := [[list,"L"],[any,"a"]],
1547 sou := [[list]],
1548 short := "Add `a' to `L' by assigning `a' at the next position beyond the "+
1549 "scope of `L'.\n"+
1550 "Note: This function returns the list created by the addition but does "+
1551 "not affect `L'.",
1552 ex := ["L:=[1,,3,4];\nAdd(L,5); L;"],
1553 see := [DocHash("Add_(list,any)"),
1554 DocHash("Append_(list,list)")]), _Add_list_any);
1555
1556 InstallMethod(
1557 rec(
1558 kind:="FUNCTION",
1559 name:="Add",
1560 sin:=[[seq(),"Q"],[any,"x"]],
1561 sou:=[[seq()]],
1562 short:="The sequence built by appending x to the sequence Q.",
1563 ex:=["L:=Sequence([1,2,3,4]);\nAdd(L,5); L;"],
1564 see:=[DocHash("Add(list,any)"),
1565 DocHash("Append(seq(),seq())")]), _Add_list_any);
1566 InstallMethod(
1567 rec(
1568 kind:="FUNCTION",
1569 name:="Add_",
1570 sin:=[[seq(),"Q"],[any,"x"]],
1571 sou:=[[seq()]],
1572 short:="Modify `Q' by appending x to the sequence Q.",
1573 ex:=["L:=Sequence([1,2,3,4]);\nAdd_(L,5); L;"],
1574 see:=[DocHash("Add_(list,any)"),
1575 DocHash("Append_(seq(),seq())")]), _Add__list_any);
1576
1577 InstallMethod(
1578 rec(
1579 kind:="FUNCTION",
1580 name:="Add",
1581 sin:=[[string,"S"],[char,"c"]],
1582 sou:=[[string]],
1583 short:="The string built by appending `c' to the string `S'.\n"+
1584 "Note: This is roughly equivalent to `S+c'.",
1585 ex:=["S:=\"abcdef\";\nAdd(S,'z'); S;"],
1586 see:=[DocHash("Add(list,any)"),
1587 DocHash("Append(string,string)")]), _Add_list_any);
1588 InstallMethod(
1589 rec(
1590 kind:="FUNCTION",
1591 name:="Add_",
1592 sin:=[[string,"S"],[char,"c"]],
1593 sou:=[[string]],
1594 short:="Modify `S' by appending `c' to the string `S'.",
1595 ex:=["S:=\"abcdef\";\nAdd_(S,'z'); S;"],
1596 see:=[DocHash("Add_(list,any)"),
1597 DocHash("Append_(string,string)")]), _Add__list_any);
1598
1599
1600
1601 ###################
1602 ### set.c/dry.c ###
1603 ###################
1604
1605 #############################################################################
1606 ##
1607 #F Union( <dry> )
1608 #F Union( <set> )
1609 ##
1610 InstallMethod(
1611 rec(
1612 kind:="FUNCTION",
1613 name:="Union",
1614 sin:=[[dry,"D1"],[list,"D2"]],
1615 sou:=[[dry]],
1616 short:="Return the dry derived by the union of `D1' and `D2'.\n"+
1617 "The union is the dry of those elements that are elements of either dry. "+
1618 "So `"+~.name+"' adds (see DryAdd) all elements to `D1' that are in `D2'. "+
1619 "`D2' may be a list that is not a proper dry, in which case `Dry' is "+
1620 "silently applied to it.",
1621 ex:=[],
1622 see:=[]), DryUnion);
1623 InstallMethod(
1624 rec(
1625 kind:="FUNCTION",
1626 name:="Union",
1627 sin:=[[set,"S1"],[list,"S2"]],
1628 sou:=[[set]],
1629 short:="Return the set derived by the union of `S1' and `S2'.\n"+
1630 "The union is the dry of those elements that are elements of either dry. "+
1631 "So `"+~.name+"' adds (see SetAdd) all elements to `S1' that are in `S2'. "+
1632 "`S2' may be a list that is not a proper set, in which case `Set' is "+
1633 "silently applied to it.",
1634 ex:=[],
1635 see:=[]), SetUnion);
1636 InstallMethod(
1637 rec(
1638 kind:="FUNCTION",
1639 name:="Union_",
1640 sin:=[[dry,"D1"],[list,"D2"]],
1641 sou:=[],
1642 short:="Change `D1' so that it becomes the union of `D1' and `D2'.\n"+
1643 "The union is the dry of those elements that are elements of either dry. "+
1644 "So `"+~.name+"' adds (see DryAdd) all elements to `D1' that are in `D2'. "+
1645 "`D2' may be a list that is not a proper dry, in which case `Dry' is "+
1646 "silently applied to it.",
1647 ex:=[],
1648 see:=[]), DryUnion_);
1649 InstallMethod(
1650 rec(
1651 kind:="FUNCTION",
1652 name:="Union_",
1653 sin:=[[set,"S1"],[list,"S2"]],
1654 sou:=[],
1655 short:="Change `S1' so that it becomes the union of `S1' and `S2'.\n"+
1656 "The union is the dry of those elements that are elements of either dry. "+
1657 "So `"+~.name+"' adds (see SetAdd) all elements to `S1' that are in `S2'. "+
1658 "`S2' may be a list that is not a proper set, in which case `Set' is "+
1659 "silently applied to it.",
1660 ex:=[],
1661 see:=[]), SetUnion_);
1662
1663 #############################################################################
1664 ##
1665 #F Intersection( <dry> )
1666 #F Intersection( <set> )
1667 ##
1668 InstallMethod(
1669 rec(
1670 kind := "FUNCTION",
1671 name := "Intersection",
1672 sin := [[dry,"D1"],[list,"D2"]],
1673 sou := [[dry]],
1674 short := "Return the dry derived by the intersection of the dries `D1' "+
1675 "and `D2'.\n"+
1676 "The intersection is the dry of those elements that are elements in "+
1677 "both dries. So `"+~.name+"' removes (see `DryRemove') all elements "+
1678 "from `D1' that are not in `D2'.\n"+
1679 "Note: `D2' may be a list that is not a proper dry, in which case `Dry' "+
1680 "is silently applied to it."
1681 ), DryIntersection);
1682 InstallMethod(
1683 rec(
1684 kind := "FUNCTION",
1685 name := "Intersection",
1686 sin := [[set,"S1"],[list,"S2"]],
1687 sou := [[set]],
1688 short := "Return the set derived by the intersection of the sets `S1' "+
1689 "and `S2'.\n"+
1690 "The intersection is the set of those elements that are elements in "+
1691 "both sets. So `"+~.name+"' removes (see `SetRemove') all elements "+
1692 "from `S1' that are not in `S2'.\n"+
1693 "`S2' may be a list that is not a proper set, in which case `Set' "+
1694 "is silently applied to it."
1695 ), SetIntersection);
1696 InstallMethod(
1697 rec(
1698 kind := "FUNCTION",
1699 name := "Intersection_",
1700 sin := [[dry,"D1"],[list,"D2"]],
1701 sou := [],
1702 short := "Change `D1' so that it becomes the intersection of `D1' and `D2'.\n"+
1703 "The intersection is the dry of those elements that are elements in "+
1704 "both dries. So `"+~.name+"' removes (see `DryRemove_') all elements "+
1705 "from `D1' which are not in `D2'.\n"+
1706 "Note: `D2' may be a list that is not a proper dry, in which case `Dry' "+
1707 "is silently applied to it."
1708 ), DryIntersection_);
1709 InstallMethod(
1710 rec(
1711 kind := "FUNCTION",
1712 name := "Intersection_",
1713 sin := [[set,"S1"],[list,"S2"]],
1714 sou := [],
1715 short := "Change `S1' so that it becomes the intersection of `S1' "+
1716 "and `S2'.\n"+
1717 "The intersection is the set of those elements that are elements in "+
1718 "both sets. So `SetIntersection_' removes (see `SetRemove_') all elements "+
1719 "from `S1' that are not in `S2'.\n"+
1720 "`S2' may be a list that is not a proper set, in which case `Set' "+
1721 "is silently applied to it."
1722 ), SetIntersection_);
1723
1724
1725 #############################################################################
1726 ##
1727 #F Difference( <dry> )
1728 #F Difference( <set> )
1729 ##
1730 InstallMethod(
1731 rec(
1732 kind := "FUNCTION",
1733 name := "Difference",
1734 sin := [[dry,"D1"],[list,"D2"]],
1735 sou := [[dry]],
1736 short := "Return the dry derived by the difference of the dries `D1' "+
1737 "and `D2'.\n"+
1738 "The difference is the dry of the elements that are in `D1' but not "+
1739 "in `D2'. So `"+~.name+"' removes (see `DryRemove') all elements from "+
1740 "`D1' that are in `D2'.\n"+
1741 "Note: `D2' may be a list that is not a proper dry, in which case `Dry' "+
1742 "is silently applied to it."
1743 ), DryDifference);
1744 InstallMethod(
1745 rec(
1746 kind := "FUNCTION",
1747 name := "Difference",
1748 sin := [[set,"S1"],[list,"S2"]],
1749 sou := [[set]],
1750 short := "Return the set derived by the difference of the sets `S1' "+
1751 "and `S2'.\n"+
1752 "The difference is the set of the elements that are in `S1' but not "+
1753 "in `S2'. So `"+~.name+"' removes (see `SetRemove') all elements from "+
1754 "`S1' that are in `S2'.\n"+
1755 "Note: `S2' may be a list that is not a proper set, in which case `Set' "+
1756 "is silently applied to it."
1757 ), SetDifference);
1758 InstallMethod(
1759 rec(
1760 kind := "FUNCTION",
1761 name := "Difference_",
1762 sin := [[dry,"D1"],[list,"D2"]],
1763 sou := [],
1764 short := "Change `D1' so that it becomes the difference of `D1' and `D2'.\n"+
1765 "The difference is the dry of the elements that are in `D1' but not "+
1766 "in `D2'. So `"+~.name+"' removes (see `DryRemove_') all elements from "+
1767 "`D1' that are in `D2'.\n"+
1768 "Note: `D2' may be a list that is not a proper dry, in which case `Dry' "+
1769 "is silently applied to it."
1770 ), DryDifference_);
1771 InstallMethod(
1772 rec(
1773 kind := "FUNCTION",
1774 name := "Difference_",
1775 sin := [[set,"S1"],[list,"S2"]],
1776 sou := [],
1777 short := "Change `S1' so that it becomes the difference of `S1' and `S2'.\n"+
1778 "The difference is the set of the elements that are in `S1' but not "+
1779 "in `S2'. So `"+~.name+"' removes (see `SetRemove_') all elements from "+
1780 "`S1' that are in `S2'.\n"+
1781 "Note: `S2' may be a list that is not a proper set, in which case `Set' "+
1782 "is silently applied to it."
1783 ), SetDifference_);
1784
1785
1786
1787
1788
1789 ###############
1790 ### alist.g ###
1791 ###############
1792
1793
1794 #############################################################################
1795 ##
1796 #F AlistKeys( <alist> )
1797 ##
1798 InstallDocumentation(
1799 rec(
1800 kind:="FUNCTION",
1801 name:="AlistKeys",
1802 sin:=[[alist,"A"]],
1803 opt:=[__FAILUREDOC],
1804 sou:=[[list,"keyl"]],
1805 short:="Return a list of keys of the alist `A'.",
1806 ex:=["A:=Alist([\"foo\",\"someval1\"],[\"bar\",\"someval2\"]);\n"+
1807 "AlistKeys(A);"],
1808 see:=[DocHash("AlistValues(alist)")]));
1809
1810 #############################################################################
1811 ##
1812 #F AlistValues( <alist> )
1813 ##
1814 InstallDocumentation(
1815 rec(
1816 kind:="FUNCTION",
1817 name:="AlistValues",
1818 sin:=[[alist,"A"]],
1819 opt:=[__FAILUREDOC],
1820 sou:=[[list,"vall"]],
1821 short:="Return a list of values of the alist `A'.",
1822 ex:=["A:=Alist([\"foo\",\"someval1\"],[\"bar\",\"someval2\"]);\n"+
1823 "AlistValues(A);"],
1824 see:=[DocHash("AlistKeys(alist)")]));
1825
1826 #############################################################################
1827 ##
1828 #F Assoc( alist, any )
1829 #F Image( alist, any )
1830 ##
1831 InstallDocumentation(
1832 rec(
1833 kind:="FUNCTION",
1834 name:="Assoc",
1835 sin:=[[alist,"A"],[any,"key"]],
1836 opt:=[__FAILUREDOC],
1837 sou:=[[any,"val"]],
1838 short:="Return the value associated with `key' in the alist `A'.",
1839 ex:=["A:=Alist([\"foo\",\"someval1\"],[\"bar\",\"someval2\"]);\n"+
1840 "Assoc(A,\"bar\"); Assoc(A,25);"],
1841 see:=[]));
1842 ## there are complications with our internal Image fun
1843 #InstallMethod(
1844 # rec(
1845 # kind:="FUNCTION",
1846 # name:="Image",
1847 # sin:=[[alist,"A"],[any,"key"]],
1848 # opt:=[__FAILUREDOC],
1849 # sou:=[[any,"val"]],
1850 # short:="Return the value associated with `key' in the alist `A'.",
1851 # ex:=["A:=Alist([\"foo\",\"someval1\"],[\"bar\",\"someval2\"]);\n"+
1852 # "Image(A,\"bar\"); Image(A,25);"],
1853 # see:=[]), Assoc);
1854
1855 #############################################################################
1856 ##
1857 #F Rassoc( alist, any )
1858 #F Preimages( alist, any )
1859 ##
1860 InstallDocumentation(
1861 rec(
1862 kind:="FUNCTION",
1863 name:="Rassoc",
1864 sin:=[[alist,"A"],[any,"val"]],
1865 opt:=[__FAILUREDOC],
1866 sou:=[[any,"key"]],
1867 short:="Return a list of keys whose associations are `val' in the alist `A'.",
1868 ex:=["A:=Alist([\"foo\",\"someval1\"],[\"bar\",\"someval2\"]);\n"+
1869 "Rassoc(A,\"someval1\"); Rassoc(A,25);"],
1870 see:=[]));
1871 InstallMethod(
1872 rec(
1873 kind:="FUNCTION",
1874 name:="Preimages",
1875 sin:=[[alist,"A"],[any,"val"]],
1876 opt:=[__FAILUREDOC],
1877 sou:=[[any,"key"]],
1878 short:="Return a list of keys whose associations are `val' in the alist `A'.",
1879 ex:=["A:=Alist([\"foo\",\"someval1\"],[\"bar\",\"someval2\"]);\n"+
1880 "Preimages(A,\"someval1\"); Preimages(A,25);"],
1881 see:=[]), Rassoc);
1882
1883
1884 #############################################################################
1885 ##
1886 #F AddAssoc( alist, any, any )
1887 #F AddAssoc( alist, list(any,any) )
1888 #F AddAssoc_( alist, any, any )
1889 #F AddAssoc_( alist, list(any,any) )
1890 ##
1891 InstallMethod(
1892 rec(
1893 kind:="FUNCTION",
1894 name:="AddAssoc",
1895 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
1896 opt:=[__FAILUREDOC,
1897 __SUCCESSDOC],
1898 sou:=[[alist]],
1899 short:=
1900 "Associate `key' with `val' in alist `A' if `key' was not already present "+
1901 "and return the alist derived from this association or FAILURE in case `key' "+
1902 "already had an association in `A'.\n"+
1903 "Note: This does not affect `A'.",
1904 ex:=["A:=Alist();\n"+
1905 "AddAssoc(A,1,\"foo\");"],
1906 see:=[DocHash("AddAssoc_(alist,any,any)")]), _AddAssoc_alist_any_any);
1907 InstallMethod(
1908 rec(
1909 kind:="FUNCTION",
1910 name:="Add",
1911 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
1912 opt:=[__FAILUREDOC,
1913 __SUCCESSDOC],
1914 sou:=[[alist]],
1915 short:=
1916 "Associate `key' with `val' in alist `A' if `key' was not already present "+
1917 "and return the alist derived from this association or FAILURE in case `key' "+
1918 "already had an association in `A'.\n"+
1919 "Note: This does not affect `A'.",
1920 ex:=["A:=Alist();\n"+
1921 "Add(A,1,\"foo\");"],
1922 see:=[DocHash("Add(alist,any,any)")]), _AddAssoc_alist_any_any, rec(WrapFormerFuns:=FALSE));
1923 InstallMethod(
1924 rec(
1925 kind:="FUNCTION",
1926 name:="AddAssoc_",
1927 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
1928 opt:=[__FAILUREDOC,
1929 __SUCCESSDOC],
1930 sou:=[],
1931 short:=
1932 "Associate `key' with `val' in alist `A' if `key' was not already present "+
1933 "and return FAILURE on failure.\n"+
1934 "Note: `A' is modified by side-effect.",
1935 ex:=["A:=Alist();\n"+
1936 "AddAssoc_(A,1,\"foo\"); A;"],
1937 see:=[DocHash("AddAssoc(alist,any,any)")]), _AddAssoc__alist_any_any);
1938 InstallMethod(
1939 rec(
1940 kind:="FUNCTION",
1941 name:="Add_",
1942 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
1943 opt:=[__FAILUREDOC,
1944 __SUCCESSDOC],
1945 sou:=[],
1946 short:=
1947 "Associate `key' with `val' in alist `A' if `key' was not already present "+
1948 "and return FAILURE on failure.\n"+
1949 "Note: `A' is modified by side-effect.",
1950 ex:=["A:=Alist();\n"+
1951 "Add_(A,1,\"foo\"); A;"],
1952 see:=[DocHash("Add(alist,any,any)")]), _AddAssoc__alist_any_any, rec(WrapFormerFuns:=FALSE));
1953 InstallMethod(
1954 rec(
1955 kind:="FUNCTION",
1956 name:="AddAssoc",
1957 sin:=[[alist,"A"],[list,"keyval"]],
1958 opt:=[__FAILUREDOC,
1959 __SUCCESSDOC],
1960 sou:=[[alist]],
1961 short:=
1962 "Associate `key' (taken as first element of `keyval') with `val' (taken "+
1963 "as the rest of `keyval') in alist `A' if `key' was not already present "+
1964 "and return the alist derived from this association or FAILURE in case `key' "+
1965 "already had an association in `A'.\n"+
1966 "Note: This does not affect `A'.",
1967 ex:=["A:=Alist();\n"+
1968 "AddAssoc(A,[2,\"bar\",\"and_baz\"]);"],
1969 see:=[DocHash("AddAssoc_(alist,list)")]), _AddAssoc_alist_list);
1970 InstallMethod(
1971 rec(
1972 kind:="FUNCTION",
1973 name:="AddAssoc_",
1974 sin:=[[alist,"A"],[list,"keyval"]],
1975 opt:=[__FAILUREDOC,
1976 __SUCCESSDOC],
1977 sou:=[],
1978 short:=
1979 "Associate `key' (taken as first element of `keyval') with `val' (taken "+
1980 "as the rest of `keyval') in alist `A' if `key' was not already present "+
1981 "and return FAILURE in case of failure.\n"+
1982 "Note: `A' is modified by side-effect.",
1983 ex:=["A:=Alist();\n"+
1984 "AddAssoc_(A,[2,\"bar\",\"and_baz\"]); A;"],
1985 see:=[DocHash("AddAssoc(alist,list)")]), _AddAssoc__alist_list);
1986
1987
1988 #############################################################################
1989 ##
1990 #F PutAssoc( <alist>, <any>, <any> )
1991 ##
1992 InstallMethod(
1993 rec(
1994 kind:="FUNCTION",
1995 name:="PutAssoc",
1996 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
1997 opt:=[__FAILUREDOC,
1998 __SUCCESSDOC],
1999 sou:=[[alist]],
2000 short:=
2001 "Associate `key' with `val' in alist `A' and return the alist derived "+
2002 "from this association.\n"+
2003 "Note: This does not affect `A'.",
2004 ex:=["A:=Alist();\n"+
2005 "PutAssoc(A,1,\"foo\");"],
2006 see:=[DocHash("PutAssoc_(alist,any,any)")]), _PutAssoc_alist_any_any);
2007 InstallMethod(
2008 rec(
2009 kind:="FUNCTION",
2010 name:="Put",
2011 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
2012 opt:=[__FAILUREDOC,
2013 __SUCCESSDOC],
2014 sou:=[[alist]],
2015 short:=
2016 "Associate `key' with `val' in alist `A' and return the alist derived "+
2017 "from this association.\n"+
2018 "Note: This does not affect `A'.",
2019 ex:=["A:=Alist();\n"+
2020 "Put(A,1,\"foo\");"],
2021 see:=[DocHash("Put_(alist,any,any)")]), _PutAssoc_alist_any_any);
2022 InstallMethod(
2023 rec(
2024 kind:="FUNCTION",
2025 name:="PutAssoc_",
2026 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
2027 opt:=[__FAILUREDOC,
2028 __SUCCESSDOC],
2029 sou:=[],
2030 short:=
2031 "Associate `key' with `val' in alist `A' and return FAILURE on failure.\n"+
2032 "Note: `A' is modified by side-effect.",
2033 ex:=["A:=Alist();\n"+
2034 "PutAssoc_(A,1,\"foo\"); A;"],
2035 see:=[DocHash("PutAssoc(alist,any,any)")]), _PutAssoc__alist_any_any);
2036 InstallMethod(
2037 rec(
2038 kind:="FUNCTION",
2039 name:="Put_",
2040 sin:=[[alist,"A"],[any,"key"],[any,"val"]],
2041 opt:=[__FAILUREDOC,
2042 __SUCCESSDOC],
2043 sou:=[],
2044 short:=
2045 "Associate `key' with `val' in alist `A' and return FAILURE on failure.\n"+
2046 "Note: `A' is modified by side-effect.",
2047 ex:=["A:=Alist();\n"+
2048 "Put_(A,1,\"foo\"); A;"],
2049 see:=[DocHash("Put(alist,any,any)")]), _PutAssoc__alist_any_any);
2050 InstallMethod(
2051 rec(
2052 kind:="FUNCTION",
2053 name:="PutAssoc",
2054 sin:=[[alist,"A"],[list,"keyval"]],
2055 opt:=[__FAILUREDOC,
2056 __SUCCESSDOC],
2057 sou:=[[alist]],
2058 short:=
2059 "Associate `key' (taken as first element of `keyval') with `val' (taken "+
2060 "as second element of `keyval') in alist `A' and return the alist derived "+
2061 "from this association.\n"+
2062 "Note: This does not affect `A'.",
2063 ex:=["A:=Alist();\n"+
2064 "PutAssoc_(A,[2,\"bar\"]);"],
2065 see:=[DocHash("PutAssoc(alist,list)")]), _PutAssoc_alist_list);
2066 InstallMethod(
2067 rec(
2068 kind:="FUNCTION",
2069 name:="PutAssoc_",
2070 sin:=[[alist,"A"],[list,"keyval"]],
2071 opt:=[__FAILUREDOC,
2072 __SUCCESSDOC],
2073 sou:=[],
2074 short:=
2075 "Associate `key' (taken as first element of `keyval') with `val' (taken "+
2076 "as second element of `keyval') in alist `A' and return FAILURE on failure.\n"+
2077 "Note: `A' is modified by side-effect.",
2078 ex:=["A:=Alist();\n"+
2079 "PutAssoc_(A,[2,\"bar\"]); A;"],
2080 see:=[DocHash("PutAssoc(alist,list)")]), _PutAssoc__alist_list);
2081
2082
2083 #############################################################################
2084 ##
2085 #F RemAssoc( alist, any )
2086 #F RemAssoc_( alist, any )
2087 #F RemImage( alist, any )
2088 #F RemImage_( alist, any )
2089 ##
2090 InstallDocumentation(
2091 rec(
2092 kind:="FUNCTION",
2093 name:="RemAssoc",
2094 sin:=[[alist,"A"],[any,"key"]],
2095 opt:=[__FAILUREDOC,
2096 __SUCCESSDOC],
2097 sou:=[[alist]],
2098 short:=
2099 "Remove `key' and its association in alist `A' and return the alist derived "+
2100 "from this removal.\n"+
2101 "Note: This does not affect `A'.",
2102 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"]);\n"+
2103 "RemAssoc(A,1);"],
2104 see:=[DocHash("RemAssoc_(alist,any)")]));
2105 InstallMethod(
2106 rec(
2107 kind:="FUNCTION",
2108 name:="Remove",
2109 sin:=[[alist,"A"],[any,"key"]],
2110 opt:=[__FAILUREDOC,
2111 __SUCCESSDOC],
2112 sou:=[[alist]],
2113 short:=
2114 "Remove `key' and its association in alist `A' and return the alist derived "+
2115 "from this removal.\n"+
2116 "Note: This does not affect `A'.",
2117 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"]);\n"+
2118 "RemAssoc(A,1);"],
2119 see:=[DocHash("Remove_(alist,any)")]), RemAssoc, rec(WrapFormerFuns:=FALSE));
2120 InstallDocumentation(
2121 rec(
2122 kind:="FUNCTION",
2123 name:="RemAssoc_",
2124 sin:=[[alist,"A"],[any,"key"]],
2125 opt:=[__FAILUREDOC,
2126 __SUCCESSDOC],
2127 sou:=[],
2128 short:=
2129 "Remove `key' and its association in alist `A' and return FAILURE on failure "+
2130 "or SUCCESS on success.\n"+
2131 "Note: `A' is modified by side-effect.",
2132 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"]);\n"+
2133 "RemAssoc_(A,1); A;"],
2134 see:=[DocHash("RemAssoc(alist,any)")]));
2135 InstallMethod(
2136 rec(
2137 kind:="FUNCTION",
2138 name:="Remove_",
2139 sin:=[[alist,"A"],[any,"key"]],
2140 opt:=[__FAILUREDOC,
2141 __SUCCESSDOC],
2142 sou:=[],
2143 short:=
2144 "Remove `key' and its association in alist `A' and return FAILURE on failure "+
2145 "or SUCCESS on success.\n"+
2146 "Note: `A' is modified by side-effect.",
2147 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"]);\n"+
2148 "RemAssoc_(A,1); A;"],
2149 see:=[DocHash("Remove(alist,any)")]), RemAssoc_, rec(WrapFormerFuns:=FALSE));
2150
2151
2152 #############################################################################
2153 ##
2154 #F Alist( )
2155 #F Alist( nof(list(any, any)) )
2156 ##
2157 ## documentation see lib/init-methods.g
2158 InstallDocumentation(
2159 rec(
2160 kind:="FUNCTION",
2161 name:="Alist",
2162 sin:=[[]],
2163 sou:=[[alist,"A"]],
2164 short:=
2165 "Create and return an empty association list `A'.",
2166 ex:=["A:=Alist();"],
2167 see:=[DocHash("Alist(nof(list))")]));
2168 InstallDocumentation(
2169 rec(
2170 kind:="FUNCTION",
2171 name:="Alist",
2172 sin:=[[nof(list)]],
2173 sou:=[[alist,"A"]],
2174 short:=
2175 "Create and return an association list `A' along with some content.\n"+
2176 "The arguments are two-cell lists. The alist is built by taking the "+
2177 "first element of a list as key and the second element as associated "+
2178 "value.",
2179 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"]);"],
2180 see:=[DocHash("Alist()")]));
2181
2182
2183 #############################################################################
2184 ##
2185 #F Function( <alist> )
2186 ##
2187 InstallMethod(
2188 rec(
2189 kind:="FUNCTION",
2190 name:="Function",
2191 sin:=[[alist,"A"]],
2192 sou:=[[func]],
2193 short:=
2194 "Create a function (not a map!) whose `domain' is the keylist of `A' and "+
2195 "whose `co-domain' is the valuelist of `A' and return this function.",
2196 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"],[3,\"foobar\"]);\n"+
2197 "AF:=Function(A);\n"+
2198 "AF(1); AF(2); AF(3); AF(4);"],
2199 see:=[]), _Function_alist);
2200
2201
2202 #############################################################################
2203 ##
2204 #F Function( <alist> )
2205 ##
2206 InstallMethod(
2207 rec(
2208 kind:="FUNCTION",
2209 name:="MapAlist",
2210 sin:=[[func,"f"],[alist,"A"]],
2211 sou:=[[]],
2212 short:=
2213 "Apply `f' to all entries in alist `A' and return SUCCESS.\n"+
2214 "`f' is expected to take two arguments, the first one is bound "+
2215 "to the key of an alist element, the second one is bound to its "+
2216 "association.",
2217 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"],[3,\"foobar\"]);\n"+
2218 "f:=function(key,val)\n"+
2219 "Print(\"key is \",key,\", val is \",val,\"\\n\");\n"+
2220 "end;\n"+
2221 "MapAlist(f,A);"],
2222 see:=[DocHash("Apply(func,alist)")]), _MapAlist_func_alist);
2223 InstallMethod(
2224 rec(
2225 kind:="FUNCTION",
2226 name:="MapAlist",
2227 sin:=[[alist,"A"],[func,"f"]],
2228 sou:=[[]],
2229 short:=
2230 "Apply `f' to all entries in alist `A' and return SUCCESS.\n"+
2231 "`f' is expected to take two arguments, the first one is bound "+
2232 "to the key of an alist element, the second one is bound to its "+
2233 "association.",
2234 ex:=["A:=Alist([1,\"foo\"],[2,\"bar\"],[3,\"foobar\"]);\n"+
2235 "f:=function(key,val)\n"+
2236 "Print(\"key is \",key,\", val is \",val,\"\\n\");\n"+
2237 "end;\n"+
2238 "MapAlist(A,f);"],
2239 see:=[DocHash("Apply(func,alist)")]), _MapAlist_alist_func);
2240
2241
2242
2243
2244 ##############
2245 ### term.g ###
2246 ##############
2247
2248 #############################################################################
2249 ##
2250 #F PrintString(<nof(string)> [, optarg])
2251 ##
2252 InstallDocumentation(
2253 rec(
2254 kind:= "FUNCTION",
2255 name:= "PrintString",
2256 sin := [[nof(string),"S"]],
2257 opt := [[elt-ord^rat,"Start",
2258 "Offset to indicate how many columns have already been printed "+
2259 "in the current line",rec(Default:="GetCurrentColumn()")]],
2260 sou := [[]],
2261 short := "Print a string with respect to the current term's columns and lines "+
2262 "definition.",
2263 ex := [],
2264 see := []
2265 ));
2266
2267
2268
2269
2270
2271 #####################
2272 ### doc.g/docui.g ###
2273 #####################
2274
2275
2276 #############################################################################
2277 ##
2278 #F DocGenHashByString( <string> )
2279 ##
2280 InstallDocumentation(
2281 rec(
2282 kind := "FUNCTION",
2283 name := "DocGenHashByString",
2284 sin := [[string,"docsig"]],
2285 sou := [[string,"dochash"]],
2286 short := "Return the hash value a record with signature `docsig' would "+
2287 "have if added to the global documentation dry.\n"+
2288 "You may want to use this when using the InstallDocumentation or "+
2289 "MergeDocumentation macros in order to refer to other functions without "+
2290 "looking up the hash value.",
2291 ex:=["DocGenHashByString(\"DocGenHashByString(string)\");"],
2292 see:=[DocGenHashByString("DocGenHashByRecord(record)")]));
2293
2294 #############################################################################
2295 ##
2296 #F DocGenHashByRecord( <record> )
2297 ##
2298 InstallDocumentation(
2299 rec(
2300 kind := "FUNCTION",
2301 name := "DocGenHashByRecord",
2302 sin := [[record,"docrec"]],
2303 sou := [[string,"dochash"]],
2304 short := "Return the hash value a record `docrec' would have if added "+
2305 "to the global documentation dry.\n"+
2306 "You may want to use this when using the InstallDocumentation or "+
2307 "MergeDocumentation macros in order to refer to other functions without "+
2308 "looking up the hash value.\n"+
2309 "Note: In general there is no need to provide the whole record as "+
2310 "argument, instead sufficient are the rec fields which are used to "+
2311 "compute the hash sum. Currently these are `kind' and `name' and in "+
2312 "some cases (OPERATION and FUNCTION) `sin' is also mandatory.",
2313 ex:=["DocGenHashByRecord(rec(kind:=\"FUNCTION\","+
2314 "name:=\"DocGenHashByRecord\","+
2315 "sin:=[[record]]));"],
2316 see:=[DocGenHashByString("DocGenHashByString(string)")]));
2317
2318 #############################################################################
2319 ##
2320 #F CheckDocumentation( <record> )
2321 ##
2322 InstallDocumentation(
2323 rec(
2324 kind := "FUNCTION",
2325 name := "CheckDocumentation",
2326 sin := [[record,"r"]],
2327 sou := [],
2328 short := "Return true iff documentation in record 'r' tends to be correct."));
2329 #############################################################################
2330 ##
2331 #F BlowUpDocumentation( <record> )
2332 ##
2333 InstallDocumentation(
2334 rec(
2335 kind := "FUNCTION",
2336 name := "BlowUpDocumentation",
2337 sin := [[record,"r"]],
2338 sou := [],
2339 short := "Blow up documentation in record 'r' by adding useful fields."));
2340
2341
2342 #############################################################################
2343 ##
2344 #F InstallDocumentation( <record> )
2345 ##
2346 InstallDocumentation(
2347 rec(
2348 kind := "FUNCTION",
2349 name := "InstallDocumentation",
2350 sin := [[record,"r"]],
2351 opt := [__FAILUREDOC,
2352 [elt-alg^boo,"ForceAdd","Default: FALSE, indicate you want to add "+
2353 "or replace existing documentation."]],
2354 sou := [[elt-alg^boo,"success"]],
2355 short := "Add documentation given by `r' to global documentation hash table.\n"+
2356 "The documentation in `r' is blown up and checked. Then it is tried to be "+
2357 "added with a dry operation (DryReplaceOrAdd) and thus overwrites existing "+
2358 "documentation iff the hash value computed by `r' is already in the global "+
2359 "dry, and is appended otherwise.",
2360 see := [DocGenHashByRecord(rec(kind:="FUNCTION",
2361 name:="BlowUpDocumentation",
2362 sin:=[[record]])),
2363 DocGenHashByRecord(rec(kind:="FUNCTION",
2364 name:="CheckDocumentation",
2365 sin:=[[record]]))]));
2366 #############################################################################
2367 ##
2368 #F MergeDocumentation( <record> )
2369 ##
2370 InstallDocumentation(
2371 rec(
2372 kind := "FUNCTION",
2373 name := "MergeDocumentation",
2374 sin := [[record,"r"]],
2375 opt := [__FAILUREDOC,
2376 [any,"Success","Default: TRUE, indicate what to return in case of success"],
2377 [any,"Add","Default: FALSE, add `r' to documentation dry in either case"]],
2378 sou := [],
2379 short := "Merge documentation given (even partially) by `r' to global "+
2380 "documentation hash table.\n"));
2381
2382 #############################################################################
2383 ##
2384 #F DocHash(<string>)
2385 ##
2386 InstallDocumentation(
2387 rec(
2388 kind := "FUNCTION",
2389 name := "DocHash",
2390 sin := [[string,"s"]],
2391 sou := [[string,"hash"]],
2392 short := "Return the hash value used to identify a function specified by 's'. "+
2393 "The string 's' must be of the form \"functionname(typearg1,typearg2,...)\" or "+
2394 "\"type\" or \"keyword\".",
2395 ex := ["x_s := DocHash(\"GCD(elt-ord^rat,elt-ord^rat)\"););",
2396 "x_s := DocHash(\"record\");",
2397 "x_s := DocHash(\"operations\");"]));
2398
2399 #############################################################################
2400 ##
2401 #F Help(<string>)
2402 ##
2403 InstallDocumentation(
2404 rec(
2405 kind := "FUNCTION",
2406 name := "DocHash",
2407 sin := [[string,"s"]],
2408 sou := [],
2409 short := "'Help(\"helpquery\")' is called when '?helpquery' is entered at the "+
2410 "prompt.",
2411 ex := ["Help(\"documentation\");"]));
2412
2413
2414 ##############
2415 ### init.g ###
2416 ##############
2417
2418 #############################################################################
2419 ##
2420 #F CheckArgs( <list>, <list>, <list> )
2421 ##
2422 InstallDocumentation(
2423 rec(
2424 kind:="FUNCTION",
2425 name :="CheckArgs",
2426 sin :=[[list,"arglist"],[list,"argnames"],[list,"defaults"]],
2427 sou :=[[record]],
2428 short:="Traverse through `arglist' and bind arguments to argument names in "+
2429 "`argnames'. If some arguments are not provided bind them to values from "+
2430 "`defaults'. Return the resulting record.",
2431 see :=[DocGenHashByString("HasOptarg(list)"),
2432 DocGenHashByString("ExtractOptarg(list)")]));
2433 #############################################################################
2434 ##
2435 #F HasOptarg( <list> )
2436 ##
2437 InstallDocumentation(
2438 rec(
2439 kind := "KEYWORD",
2440 name := "Optional Arguments",
2441 short :=
2442 "Many KASH3 functions take optional arguments. These are passed to a function "+
2443 "by passing a record as a last argument to the function. ",
2444 see :=[DocGenHashByString("ExtractOptarg(list)"),
2445 DocGenHashByString("HasOptarg(list)"),
2446 DocGenHashByString("CheckArgs(list,list,list)")]));
2447
2448 InstallDocumentation(
2449 rec(
2450 kind:="FUNCTION",
2451 name :="HasOptarg",
2452 sin :=[[list,"arglist"]],
2453 sou :=[[elt-alg^boo]],
2454 short:="Return TRUE iff arglist's last argument is an optional argument "+
2455 "record.",
2456 see :=[DocGenHashByString("ExtractOptarg(list)"),
2457 DocGenHashByString("CheckArgs(list,list,list)")]));
2458 #############################################################################
2459 ##
2460 #F ExtractOptarg( <string> )
2461 ##
2462 InstallDocumentation(
2463 rec(
2464 kind:="FUNCTION",
2465 name :="ExtractOptarg",
2466 sin :=[[list,"arglist"]],
2467 sou :=[[record]],
2468 short:="Return arglist's last argument if it is an optional argument, "+
2469 "FAILURE otherwise otherwise.",
2470 see :=[DocGenHashByString("ExtractOptarg_(list)"),
2471 DocGenHashByString("HasOptarg(list)"),
2472 DocGenHashByString("CheckArgs(list,list,list)")]));
2473 #############################################################################
2474 ##
2475 #F ExtractOptarg_( <string> )
2476 ##
2477 InstallDocumentation(
2478 rec(
2479 kind:="FUNCTION",
2480 name :="ExtractOptarg_",
2481 sin :=[[list,"arglist"]],
2482 sou :=[[record]],
2483 short:="Return and remove arglist's last argument if it is an optional "+
2484 "argument, FAILURE otherwise.\n "+
2485 "Note: This is the destructive version of ExtractOptarg.",
2486 see :=[DocGenHashByString("ExtractOptarg(list)"),
2487 DocGenHashByString("HasOptarg(list)"),
2488 DocGenHashByString("CheckArgs(list,list,list)")]));
2489 #############################################################################
2490 ##
2491 #F Optarg( <list>, <list>, <list> )
2492 ##
2493 InstallDocumentation(
2494 rec(
2495 kind:="FUNCTION",
2496 name :="Optarg",
2497 sin :=[[list,"arglist"],[list,"optarg_names"],[list,"defaults"]],
2498 sou :=[[record]],
2499 short:="Process optional arguments. Extract optional arguments record from 'arglist'."+
2500 "Set missing entries (from 'optarg_names') to default values from "+
2501 "'defaults'.",
2502 see :=[DocGenHashByString("ExtractOptarg(list)"),
2503 DocGenHashByString("HasOptarg(list)"),
2504 DocGenHashByString("CheckArgs(list,list,list)")]));
2505 #############################################################################
2506 ##
2507 #F Read( <string> )
2508 ##
2509 InstallDocumentation(
2510 rec(
2511 kind:="FUNCTION",
2512 name :="Read",
2513 sin :=[[string,"filename"]],
2514 sou :=[],
2515 short:="Read a file 'filename' containing KASH commands.",
2516 long :="The file 'filename' must both existing and readable."+
2517 "KASH looks first in the given path, then in the current directory "+
2518 "and finally in $LIBNAME../src.",
2519 see :=[DocGenHashByString("ReadLib(string)")]));
2520 #############################################################################
2521 ##
2522 #F ReadLib( <string> )
2523 ##
2524 InstallDocumentation(
2525 rec(
2526 kind:="FUNCTION",
2527 name :="ReadLib",
2528 sin :=[[string,"lib"]],
2529 sou :=[],
2530 short:="Same as `Read', but here the file should be in the KASH lib "+
2531 "directory and it must have the extension .g .",
2532 see :=[DocGenHashByString("Read(string)")]));
2533
2534 #############################################################################
2535 ##
2536 #K arg
2537 ##
2538 InstallDocumentation(
2539 rec(
2540 kind:="KEYWORD",
2541 name :="arg",
2542 syntax := "function(arg) ... end;",
2543 short := "Collapse arbitrary many arguments to a list of arguments and "+
2544 "pass it to arg.",
2545 long := "When used as (only) argument in a function's declaration this so "+
2546 "defined function accepts any number of arguments. "+
2547 "Arguments passed to the function at call-time are gathered into a "+
2548 "list whose value becomes `arg' in the function body.\n"+
2549 "Note: This will not work on abbreviated function declarations, like "+
2550 "`arg->arg[1];'.\n"+
2551 "Note: Also, the function keyword will not collect rests of arguments "+
2552 "into the arg argument, that is `function(some, arg) return TRUE; end;' "+
2553 "is a valid function which takes exactly two arguments, `arg' has no "+
2554 "no special meaning here (yet).",
2555 ex := ["x_f := function(arg) return arg; end;\n"+
2556 "x_f(1,2.3,\"hi mom\",[12,3]);\n"+
2557 "x_f(6);"]));
2558