Add FoldLeft, FoldLeftX; and ForAllX, ForAnyX, FilteredX, NumberX, PerformX to complement ListX, SetX, SumX, ProductX

doc/ref/lists.xml

@@ -1688,12 +1688,26 @@ with possibly slightly different meaning for lists and non-list collections.
 
 The following functions are generalizations of
 <Ref Func="List" Label="for a collection"/>,
-<Ref Oper="Set"/>, <Ref Func="Sum"/>, and <Ref Func="Product"/>.
-
+<Ref Oper="Set"/>,
+<Ref Func="Sum"/>,
+<Ref Func="Product"/>,
+<Ref Func="ForAll"/>,
+<Ref Func="ForAny"/>,
+<Ref Func="Filtered"/>,
+<Ref Func="Number"/>,
+and <Ref Func="Perform"/>.
+
+<#Include Label="FoldLeft">
+<#Include Label="FoldLeftX">
 <#Include Label="ListX">
 <#Include Label="SetX">
 <#Include Label="SumX">
 <#Include Label="ProductX">
+<#Include Label="ForAllX">
+<#Include Label="ForAnyX">
+<#Include Label="FilteredX">
+<#Include Label="NumberX">
+<#Include Label="PerformX">
 
 </Section>
 
@@ -1890,4 +1904,3 @@ such as before objectifying, or calling some kernel functions.
 <!-- %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% -->
 <!-- %% -->
 <!-- %E -->
-

lib/coll.gd

@@ -2478,6 +2478,120 @@ DeclareOperation( "AsSSortedListNonstored", [IsListOrCollection] );
 DeclareGlobalFunction( "Elements" );
 
 
+#############################################################################
+##
+#O  FoldLeft( <C>, <func>[, <init>] )
+##
+##  <#GAPDoc Label="FoldLeft">
+##  <ManSection>
+##  <Oper Name="FoldLeft" Arg='C, func[, init]'/>
+##
+##  <Description>
+##  <Ref Oper="FoldLeft"/> applies the binary function <A>func</A>
+##  left-associatively to the elements of the list or collection <A>C</A>.
+##  <P/>
+##  If no initial accumulator <A>init</A> is given, the first element of
+##  <A>C</A> is used as the initial accumulator and the remaining elements
+##  are combined with it from left to right. In that case <A>C</A> must not
+##  be empty.
+##  <P/>
+##  If <A>init</A> is given, the accumulator is initialized with
+##  <A>init</A>. Then an empty list or collection is allowed, and
+##  <A>init</A> is returned unchanged in that case.
+##  <P/>
+##  If <A>C</A> is a list with holes, these holes are ignored, just as when
+##  iterating over the list with a <C>for</C>-loop.
+##  <P/>
+##  This operation can be used to express reductions similar to
+##  <Ref Func="Sum"/> or <Ref Func="Product"/>, but it is more general
+##  because the accumulator is updated by an arbitrary binary function.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> FoldLeft( [ 1 .. 10 ], \+ );
+##  55
+##  gap> FoldLeft( [ 1 .. 4 ], \*, 2 );
+##  48
+##  gap> FoldLeft( [ 1,, 3 ], function( a, b ) return a + b; end );
+##  4
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareOperation( "FoldLeft", [ IsListOrCollection, IsFunction ] );
+DeclareOperation( "FoldLeft", [ IsListOrCollection, IsFunction, IsObject ] );
+
+
+#############################################################################
+##
+#O  FoldLeftX( <gens>, <func>, <init>[, <abortValue>] )
+##
+##  <#GAPDoc Label="FoldLeftX">
+##  <ManSection>
+##  <Func Name="FoldLeftX" Arg='gens, func, init[, abortValue]'/>
+##
+##  <Description>
+##  <Ref Func="FoldLeftX"/> is a generalization of <Ref Func="FoldLeft"/>
+##  which applies an accumulation function <A>func</A> to a bunch of
+##  inputs which are derived from <A>gens</A>.
+##  <P/>
+##  The argument <A>gens</A> must be a plain list whose entries describe a
+##  sequence of nested loops and filters. Specifically, let <C>n</C> denote
+##  the length of <A>gens</A>. Then each of the entries
+##  <A>gens</A><C>[1]</C>, <M>\ldots</M> <A>gens</A><C>[n]</C>
+##  must be one of the following:
+##  <List>
+##  <Mark>a list or collection</Mark>
+##  <Item>
+##      this introduces a new for-loop in the sequence of nested
+##      for-loops and if-statements;
+##  </Item>
+##  <Mark>a function returning a list or collection</Mark>
+##  <Item>
+##      this introduces a new for-loop in the sequence of nested
+##      for-loops and if-statements, where the loop-range depends on
+##      the values of the outer loop-variables; or
+##  </Item>
+##  <Mark>a function returning <K>true</K> or <K>false</K></Mark>
+##  <Item>
+##      this introduces a new if-statement in the sequence of nested
+##      for-loops and if-statements.
+##  </Item>
+##  </List>
+##  <P/>
+##  The argument <A>func</A> must be a binary function, whose first
+##  argument is an accumulator variable, and the second argument is
+##  the tuple of values of the loop-variables.
+##  <P/>
+##  The accumulator is initialized with <A>init</A>. For every tuple that is
+##  produced by the loops and filters described by <A>gens</A>,
+##  <A>func</A> is called with the current accumulator and that tuple.
+##  Its return value becomes the new accumulator.
+##  <P/>
+##  If the optional argument <A>abortValue</A> is given, iteration stops as
+##  soon as the accumulator becomes identical to <A>abortValue</A>.
+##  This is useful for short-circuiting computations such as
+##  <Ref Func="ForAllX"/> and <Ref Func="ForAnyX"/>.
+##  <P/>
+##  <Example><![CDATA[
+##  gap> FoldLeftX( [ [ 1 .. 3 ], i -> [ 1 .. i ],
+##  >                function( i, j ) return i <> j; end ],
+##  >              function( acc, x ) return acc + 1; end, 0 );
+##  3
+##  gap> FoldLeftX( [ [ 1 .. 3 ], [ 1 .. 3 ], \< ],
+##  >              function( acc, x )
+##  >                Add( acc, ShallowCopy( x ) );
+##  >                return acc;
+##  >              end, [] );
+##  [ [ 1, 2 ], [ 1, 3 ], [ 2, 3 ] ]
+##  ]]></Example>
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "FoldLeftX" );
+
+
 #############################################################################
 ##
 #F  Sum( <list>[, <init>] ) . . . . . . . . . . sum of the elements of a list
@@ -2939,6 +3053,116 @@ DeclareGlobalFunction( "SumX" );
 DeclareGlobalFunction( "ProductX" );
 
 
+#############################################################################
+##
+#O  ForAllX( <arg1>, <arg2>, ... <func> )
+##
+##  <#GAPDoc Label="ForAllX">
+##  <ManSection>
+##  <Func Name="ForAllX" Arg='arg1, arg2, ... func'/>
+##
+##  <Description>
+##  <Ref Func="ForAllX"/> returns <K>true</K> if all elements are
+##  <K>true</K> in the list obtained by calling <Ref Func="ListX"/> with the
+##  same arguments. Otherwise <K>false</K> is returned.
+##  As with <Ref Func="ForAll"/>, the last argument must return either
+##  <K>true</K> or <K>false</K>, and evaluation stops as soon as the result
+##  is known.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "ForAllX" );
+
+
+#############################################################################
+##
+#O  ForAnyX( <arg1>, <arg2>, ... <func> )
+##
+##  <#GAPDoc Label="ForAnyX">
+##  <ManSection>
+##  <Func Name="ForAnyX" Arg='arg1, arg2, ... func'/>
+##
+##  <Description>
+##  <Ref Func="ForAnyX"/> returns <K>true</K> if any element is
+##  <K>true</K> in the list obtained by calling <Ref Func="ListX"/> with the
+##  same arguments. Otherwise <K>false</K> is returned.
+##  As with <Ref Func="ForAny"/>, the last argument must return either
+##  <K>true</K> or <K>false</K>, and evaluation stops as soon as the result
+##  is known.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "ForAnyX" );
+
+
+#############################################################################
+##
+#O  FilteredX( <arg1>, <arg2>, ... <func> )
+##
+##  <#GAPDoc Label="FilteredX">
+##  <ManSection>
+##  <Func Name="FilteredX" Arg='arg1, arg2, ... func'/>
+##
+##  <Description>
+##  <Ref Func="FilteredX"/> returns the tuples of loop-variable values for
+##  which the last argument returns <K>true</K>.
+##  In other words, it keeps precisely those tuples that would pass the
+##  filters when calling <Ref Func="ListX"/> with the same generators.
+##  <P/>
+##  Even with only one generator, the result consists of singleton tuples.
+##  Thus <C>FilteredX( [ 1 .. 4 ], IsEvenInt )</C> returns
+##  <C>[ [ 2 ], [ 4 ] ]</C>, not <C>[ 2, 4 ]</C>.
+##  Use <Ref Func="Filtered"/> if you want to filter the elements of a single
+##  list or collection directly.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "FilteredX" );
+
+
+#############################################################################
+##
+#O  NumberX( <arg1>, <arg2>, ... <func> )
+##
+##  <#GAPDoc Label="NumberX">
+##  <ManSection>
+##  <Func Name="NumberX" Arg='arg1, arg2, ... func'/>
+##
+##  <Description>
+##  <Ref Func="NumberX"/> returns the number of tuples selected by the last
+##  argument, using the same generators as <Ref Func="ListX"/>.
+##  Equivalently, it counts the entries of the result that
+##  <Ref Func="FilteredX"/> would return with the same arguments.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "NumberX" );
+
+
+#############################################################################
+##
+#O  PerformX( <arg1>, <arg2>, ... <func> )
+##
+##  <#GAPDoc Label="PerformX">
+##  <ManSection>
+##  <Func Name="PerformX" Arg='arg1, arg2, ... func'/>
+##
+##  <Description>
+##  <Ref Func="PerformX"/> works like <Ref Func="ListX"/> except that it
+##  returns nothing and ignores the return values of <A>func</A>.
+##  It is useful for iterating through the tuples described by the generators
+##  purely for their side effects.
+##  </Description>
+##  </ManSection>
+##  <#/GAPDoc>
+##
+DeclareGlobalFunction( "PerformX" );
+
+
 #############################################################################
 ##
 #O  Perform( <list>, <func>)