Skip to content

Commit f7fa5c0

Browse files
fingolfinfingolfin
committed
WIP
1 parent 3cd9193 commit f7fa5c0

File tree

2 files changed

+195
-13
lines changed

2 files changed

+195
-13
lines changed

‎doc/ref/lists.xml‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1688,12 +1688,24 @@ with possibly slightly different meaning for lists and non-list collections.
16881688

16891689
The following functions are generalizations of
16901690
<Ref Func="List" Label="for a collection"/>,
1691-
<Ref Oper="Set"/>, <Ref Func="Sum"/>, and <Ref Func="Product"/>.
1691+
<Ref Oper="Set"/>,
1692+
<Ref Func="Sum"/>,
1693+
<Ref Func="Product"/>,
1694+
<Ref Func="ForAll"/>,
1695+
<Ref Func="ForAny"/>,
1696+
<Ref Func="Filtered"/>,
1697+
<Ref Func="Number"/>,
1698+
and <Ref Func="Perform"/>.
16921699

16931700
<#Include Label="ListX">
16941701
<#Include Label="SetX">
16951702
<#Include Label="SumX">
16961703
<#Include Label="ProductX">
1704+
<#Include Label="ForAllX">
1705+
<#Include Label="ForAnyX">
1706+
<#Include Label="FilteredX">
1707+
<#Include Label="NumberX">
1708+
<#Include Label="PerformX">
16971709

16981710
</Section>
16991711

‎lib/coll.gd‎

Lines changed: 182 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -2487,7 +2487,92 @@ DeclareOperation( "FoldLeftOp", [ IsListOrCollection, IsFunction, IsObject ] );
24872487
## <Func Name="FoldLeftX" Arg='gens, func, init[, abortValue]'/>
24882488
##
24892489
## <Description>
2490-
## TODO
2490+
## <Ref Func="FoldLeftX"/> is a generalization of <Ref Func="FoldLeft"/>
2491+
## which applies an accumulation function <A>func</A> to a bunch of
2492+
## inputs which are derived from <A>gens</A>.
2493+
## <P/>
2494+
## Specifically, let <C>n</A> denote the length of <A>gens</A>. Then
2495+
## each of the entries <A>gens</A><C>[1]</C>, <M>\ldots</M> <A>gens</A><C>[n]</C>
2496+
## must be one of the following:
2497+
## <List>
2498+
## <Mark>a list or collection</Mark>
2499+
## <Item>
2500+
## this introduces a new for-loop in the sequence of nested
2501+
## for-loops and if-statements;
2502+
## </Item>
2503+
## <Mark>a function returning a list or collection</Mark>
2504+
## <Item>
2505+
## this introduces a new for-loop in the sequence of nested
2506+
## for-loops and if-statements, where the loop-range depends on
2507+
## the values of the outer loop-variables; or
2508+
## </Item>
2509+
## <Mark>a function returning <K>true</K> or <K>false</K></Mark>
2510+
## <Item>
2511+
## this introduces a new if-statement in the sequence of nested
2512+
## for-loops and if-statements.
2513+
## </Item>
2514+
## </List>
2515+
## <P/>
2516+
## The argument <A>func</A> must be a binary function, whose first
2517+
## argument is an accumulator variable, and the second argument is
2518+
## the tuple of values of the loop-variables.
2519+
##
2520+
# TODO: continue editing after this point
2521+
# TODO: document initial as initial accumulator value
2522+
# TODO: document abortValue
2523+
# TODO: perhaps explain how to implement ListX via FoldLeftX as one of
2524+
# the examples?
2525+
#
2526+
##
2527+
## <P/>
2528+
## Thus <C>ListX( <A>list</A>, <A>func</A> )</C> is the same as
2529+
## <C>List( <A>list</A>, <A>func</A> )</C>,
2530+
## and <C>ListX( <A>list</A>, <A>func</A>, x -> x )</C> is the same as
2531+
## <C>Filtered( <A>list</A>, <A>func</A> )</C>.
2532+
## <P/>
2533+
## As a more elaborate example, assume <A>arg1</A> is a list or collection,
2534+
## <A>arg2</A> is a function returning <K>true</K> or <K>false</K>,
2535+
## <A>arg3</A> is a function returning a list or collection, and
2536+
## <A>arg4</A> is another function returning <K>true</K> or <K>false</K>,
2537+
## then
2538+
## <P/>
2539+
## <C><A>result</A> := ListX( <A>arg1</A>, <A>arg2</A>, <A>arg3</A>,
2540+
## <A>arg4</A>, <A>func</A> );</C>
2541+
## <P/>
2542+
## is equivalent to
2543+
## <P/>
2544+
## <Listing><![CDATA[
2545+
## result := [];
2546+
## for v1 in arg1 do
2547+
## if arg2( v1 ) then
2548+
## for v2 in arg3( v1 ) do
2549+
## if arg4( v1, v2 ) then
2550+
## Add( result, func( v1, v2 ) );
2551+
## fi;
2552+
## od;
2553+
## fi;
2554+
## od;
2555+
## ]]></Listing>
2556+
## <P/>
2557+
## The following example shows how <Ref Func="ListX"/> can be used to
2558+
## compute all pairs and all strictly sorted pairs of elements in a list.
2559+
## <P/>
2560+
## <Example><![CDATA[
2561+
## gap> l:= [ 1, 2, 3, 4 ];;
2562+
## gap> pair:= function( x, y ) return [ x, y ]; end;;
2563+
## gap> ListX( l, l, pair );
2564+
## [ [ 1, 1 ], [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 1 ], [ 2, 2 ],
2565+
## [ 2, 3 ], [ 2, 4 ], [ 3, 1 ], [ 3, 2 ], [ 3, 3 ], [ 3, 4 ],
2566+
## [ 4, 1 ], [ 4, 2 ], [ 4, 3 ], [ 4, 4 ] ]
2567+
## ]]></Example>
2568+
## <P/>
2569+
## In the following example, <Ref Oper="\&lt;"/> is the comparison
2570+
## operation:
2571+
## <P/>
2572+
## <Example><![CDATA[
2573+
## gap> ListX( l, l, \<, pair );
2574+
## [ [ 1, 2 ], [ 1, 3 ], [ 1, 4 ], [ 2, 3 ], [ 2, 4 ], [ 3, 4 ] ]
2575+
## ]]></Example>
24912576
## </Description>
24922577
## </ManSection>
24932578
## <#/GAPDoc>
@@ -2497,17 +2582,6 @@ DeclareOperation( "FoldLeftOp", [ IsListOrCollection, IsFunction, IsObject ] );
24972582
DeclareGlobalFunction( "FoldLeftX" );
24982583

24992584

2500-
#############################################################################
2501-
##
2502-
## TODO: document the following
2503-
##
2504-
DeclareGlobalFunction( "ForAllX" );
2505-
DeclareGlobalFunction( "ForAnyX" );
2506-
DeclareGlobalFunction( "FilteredX" );
2507-
DeclareGlobalFunction( "NumberX" );
2508-
DeclareGlobalFunction( "PerformX" );
2509-
2510-
25112585
#############################################################################
25122586
##
25132587
#F Sum( <list>[, <init>] ) . . . . . . . . . . sum of the elements of a list
@@ -2969,6 +3043,102 @@ DeclareGlobalFunction( "SumX" );
29693043
DeclareGlobalFunction( "ProductX" );
29703044

29713045

3046+
#############################################################################
3047+
##
3048+
#O ForAllX( <arg1>, <arg2>, ... <func> )
3049+
##
3050+
## <#GAPDoc Label="ForAllX">
3051+
## <ManSection>
3052+
## <Func Name="ForAllX" Arg='arg1, arg2, ... func'/>
3053+
##
3054+
## <Description>
3055+
## <Ref Func="ForAllX"/> returns <K>true</A> if all elements are
3056+
## <K>true</A> in the list obtained by calling <Ref Func="ListX"/> with the
3057+
## same arguments. Otherwise <K>false</A> is returned.
3058+
## </Description>
3059+
## </ManSection>
3060+
## <#/GAPDoc>
3061+
##
3062+
DeclareGlobalFunction( "ForAllX" );
3063+
3064+
3065+
#############################################################################
3066+
##
3067+
#O ForAnyX( <arg1>, <arg2>, ... <func> )
3068+
##
3069+
## <#GAPDoc Label="ForAnyX">
3070+
## <ManSection>
3071+
## <Func Name="ForAnyX" Arg='arg1, arg2, ... func'/>
3072+
##
3073+
## <Description>
3074+
## <Ref Func="ForAnyX"/> returns <K>true</A> if any element is
3075+
## <K>true</A> in the list obtained by calling <Ref Func="ListX"/> with the
3076+
## same arguments. Otherwise <K>false</A> is returned.
3077+
## </Description>
3078+
## </ManSection>
3079+
## <#/GAPDoc>
3080+
##
3081+
DeclareGlobalFunction( "ForAnyX" );
3082+
3083+
3084+
#############################################################################
3085+
##
3086+
#O FilteredX( <arg1>, <arg2>, ... <func> )
3087+
##
3088+
## <#GAPDoc Label="FilteredX">
3089+
## <ManSection>
3090+
## <Func Name="FilteredX" Arg='arg1, arg2, ... func'/>
3091+
##
3092+
## <Description>
3093+
## <Ref Func="FilteredX"/> returns the TODO of the elements in the list
3094+
## obtained by <Ref Func="ListX"/> when this is called with the same
3095+
## arguments.
3096+
## </Description>
3097+
## </ManSection>
3098+
## <#/GAPDoc>
3099+
##
3100+
## TODO: perhaps better to document this in terms of FoldLeftX
3101+
DeclareGlobalFunction( "FilteredX" );
3102+
3103+
3104+
#############################################################################
3105+
##
3106+
#O NumberX( <arg1>, <arg2>, ... <func> )
3107+
##
3108+
## <#GAPDoc Label="NumberX">
3109+
## <ManSection>
3110+
## <Func Name="NumberX" Arg='arg1, arg2, ... func'/>
3111+
##
3112+
## <Description>
3113+
## <Ref Func="NumberX"/> returns the TODO of the elements in the list
3114+
## obtained by <Ref Func="ListX"/> when this is called with the same
3115+
## arguments.
3116+
## </Description>
3117+
## </ManSection>
3118+
## <#/GAPDoc>
3119+
##
3120+
DeclareGlobalFunction( "NumberX" );
3121+
3122+
3123+
#############################################################################
3124+
##
3125+
#O PerformX( <arg1>, <arg2>, ... <func> )
3126+
##
3127+
## <#GAPDoc Label="PerformX">
3128+
## <ManSection>
3129+
## <Func Name="PerformX" Arg='arg1, arg2, ... func'/>
3130+
##
3131+
## <Description>
3132+
## <Ref Func="PerformX"/> works like <Ref Func="ListX"/> except that it
3133+
## returns nothing and ignores the return values of <A>func</A>.
3134+
## arguments.
3135+
## </Description>
3136+
## </ManSection>
3137+
## <#/GAPDoc>
3138+
##
3139+
DeclareGlobalFunction( "PerformX" );
3140+
3141+
29723142
#############################################################################
29733143
##
29743144
#O Perform( <list>, <func>)

0 commit comments

Comments
 (0)