From 51528e25ddf03e2975b6bd313f1b0e3112195ee3 Mon Sep 17 00:00:00 2001 From: Max Horn Date: Wed, 21 Apr 2021 17:09:04 +0200 Subject: [PATCH] docs: mention FirstOp, LastOp, ForAllOp, etc. ... in the documentation entries for their non-Op counterparts First, Last, ForAll, etc. and explain that custom methods need to be installed there. Also explain uniformly that this is to avoid the method selection overhead penalty for plain list inputs. --- lib/coll.gd | 142 +++++++++++++++------------------------------------- lib/list.gd | 86 +++++++++++-------------------- 2 files changed, 67 insertions(+), 161 deletions(-) diff --git a/lib/coll.gd b/lib/coll.gd index b390515c0c..9945323020 100644 --- a/lib/coll.gd +++ b/lib/coll.gd @@ -2051,6 +2051,10 @@ DeclareAttribute( "UnderlyingCollection", IsListOrCollection ); ## same as (see also ## ). ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation ListOp. +## ListOp +##

## List( [1,2,3], i -> i^2 ); ## [ 1, 4, 9 ] @@ -2084,6 +2088,10 @@ DeclareAttribute( "UnderlyingCollection", IsListOrCollection ); ## ## ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation ListOp. +## ListOp +##

## l:= List( Group( (1,2,3) ) ); ## [ (), (1,3,2), (1,2,3) ] @@ -2098,8 +2106,8 @@ DeclareAttribute( "UnderlyingCollection", IsListOrCollection ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "List" ); - DeclareOperation( "ListOp", [ IsListOrCollection ] ); DeclareOperation( "ListOp", [ IsListOrCollection, IsFunction ] ); @@ -2453,6 +2461,10 @@ DeclareGlobalFunction( "Elements" ); ## This is useful for example if the first argument is empty and a different ## zero than 0 is desired, in which case init is returned. ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation SumOp. +## SumOp +##

## Sum( [ 2, 3, 5, 7, 11, 13, 17, 19 ] ); ## 77 @@ -2467,28 +2479,8 @@ DeclareGlobalFunction( "Elements" ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "Sum" ); - - -############################################################################# -## -#O SumOp( ) -#O SumOp( , ) -#O SumOp( , ) -#O SumOp( , , ) -## -## -## -## -## -## -## -## -## SumOp is the operation called by Sum -## if C is not an internal list. -## -## -## DeclareOperation( "SumOp", [ IsListOrCollection ] ); @@ -2531,6 +2523,10 @@ DeclareOperation( "SumOp", [ IsListOrCollection ] ); ## This is useful for example if the first argument is empty and a different ## identity than 1 is desired, in which case init is returned. ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation ProductOp. +## ProductOp +##

## Product( [ 2, 3, 5, 7, 11, 13, 17, 19 ] ); ## 9699690 @@ -2545,28 +2541,8 @@ DeclareOperation( "SumOp", [ IsListOrCollection ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "Product" ); - - -############################################################################# -## -#O ProductOp( ) -#O ProductOp( , ) -#O ProductOp( , ) -#O ProductOp( , , ) -## -## -## -## -## -## -## -## -## ProductOp is the operation called by Product -## if C is not an internal list. -## -## -## DeclareOperation( "ProductOp", [ IsListOrCollection ] ); @@ -2604,6 +2580,10 @@ DeclareOperation( "ProductOp", [ IsListOrCollection ] ); ## (see ) can be used to extract ## elements of a list according to indices given in another list. ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation FilteredOp. +## FilteredOp +##

## Filtered( [1..20], IsPrime ); ## [ 2, 3, 5, 7, 11, 13, 17, 19 ] @@ -2619,22 +2599,8 @@ DeclareOperation( "ProductOp", [ IsListOrCollection ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "Filtered" ); - - -############################################################################# -## -#O FilteredOp( , ) -## -## -## -## -## -## FilteredOp is the operation called by Filtered -## if C is not an internal list. -## -## -## DeclareOperation( "FilteredOp", [ IsListOrCollection, IsFunction ] ); @@ -2671,6 +2637,10 @@ DeclareOperation( "FilteredOp", [ IsListOrCollection, IsFunction ] ); ## allows you to extract the elements of a list ## that have a certain property. ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation NumberOp. +## NumberOp +##

## Number( [ 2, 3, 5, 7 ] ); ## 4 @@ -2690,22 +2660,8 @@ DeclareOperation( "FilteredOp", [ IsListOrCollection, IsFunction ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "Number" ); - - -############################################################################# -## -#O NumberOp( , ) -## -## -## -## -## -## NumberOp is the operation called by Number -## if C is not an internal list. -## -## -## DeclareOperation( "NumberOp", [ IsListOrCollection, IsFunction ] ); @@ -2722,6 +2678,10 @@ DeclareOperation( "NumberOp", [ IsListOrCollection, IsFunction ] ); ## tests whether the unary function func returns true ## for all elements in the list or collection listorcoll. ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation ForAllOp. +## ForAllOp +##

## ForAll( [1..20], IsPrime ); ## false @@ -2736,22 +2696,8 @@ DeclareOperation( "NumberOp", [ IsListOrCollection, IsFunction ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "ForAll" ); - - -############################################################################# -## -#O ForAllOp( , ) -## -## -## -## -## -## ForAllOp is the operation called by ForAll -## if C is not an internal list. -## -## -## DeclareOperation( "ForAllOp", [ IsListOrCollection, IsFunction ] ); @@ -2768,6 +2714,10 @@ DeclareOperation( "ForAllOp", [ IsListOrCollection, IsFunction ] ); ## tests whether the unary function func returns true ## for at least one element in the list or collection listorcoll. ##

+## Developers who wish to adapt this for custom list or collection types need to +## install suitable methods for the operation ForAnyOp. +## ForAnyOp +##

## ForAny( [1..20], IsPrime ); ## true @@ -2784,22 +2734,8 @@ DeclareOperation( "ForAllOp", [ IsListOrCollection, IsFunction ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "ForAny" ); - - -############################################################################# -## -#O ForAnyOp( , ) -## -## -## -## -## -## ForAnyOp is the operation called by ForAny -## if C is not an internal list. -## -## -## DeclareOperation( "ForAnyOp", [ IsListOrCollection, IsFunction ] ); diff --git a/lib/list.gd b/lib/list.gd index 53bfc86ea8..d2d2a67677 100644 --- a/lib/list.gd +++ b/lib/list.gd @@ -688,12 +688,15 @@ DeclareOperation( "Position", [ IsList, IsObject, IS_INT ] ); ## <#GAPDoc Label="Positions"> ## ## -## ## ## ## returns the set of positions of all occurrences of obj in ## list. ##

+## Developers who wish to adapt this for custom list types need to +## install suitable methods for the operation PositionsOp. +## PositionsOp +##

## Positions([1,2,1,2,3,2,2],2); ## [ 2, 4, 6, 7 ] @@ -704,6 +707,7 @@ DeclareOperation( "Position", [ IsList, IsObject, IS_INT ] ); ## ## <#/GAPDoc> ## +## We catch plain lists by a function to avoid method selection: DeclareGlobalFunction( "Positions" ); DeclareOperation( "PositionsOp", [ IsList, IsObject ] ); @@ -786,7 +790,6 @@ DeclareOperation( "PositionNthOccurrence", [ IsList, IsObject, IS_INT ] ); ## ## ## -## PositionSortedOp ## Called with two arguments, returns ## the position of the element elm in the sorted list list. ##

@@ -816,8 +819,9 @@ DeclareOperation( "PositionNthOccurrence", [ IsList, IsObject, IS_INT ] ); ## for testing whether a list is sorted, ## see  and . ##

-## Specialized functions for certain kinds of lists must be installed -## as methods for the operation PositionSortedOp. +## Developers who wish to adapt this for custom list types need to +## install suitable methods for the operation PositionSortedOp. +## PositionSortedOp ##

## PositionSorted( [1,4,5,5,6,7], 0 ); @@ -839,10 +843,6 @@ DeclareOperation( "PositionNthOccurrence", [ IsList, IsObject, IS_INT ] ); DeclareGlobalFunction( "PositionSorted" ); DeclareOperation( "PositionSortedOp", [ IsList, IsObject ] ); DeclareOperation( "PositionSortedOp", [ IsList, IsObject, IsFunction ] ); -#T originally was -#T DeclareOperation( "PositionSorted", [ IsHomogeneousList, IsObject ] ); -#T note the problem with inhomogeneous lists that may be sorted -#T (although they cannot store this and claim that they are not sorted) ############################################################################# @@ -854,7 +854,6 @@ DeclareOperation( "PositionSortedOp", [ IsList, IsObject, IsFunction ] ); ## ## ## -## PositionSortedByOp ## This function returns the same value that would be returned by ## PositionSorted(List(list, func), val), but computes it in ## a more efficient way. @@ -879,8 +878,9 @@ DeclareOperation( "PositionSortedOp", [ IsList, IsObject, IsFunction ] ); ## uses binary search. ## Each func(list[i]) is computed at most once. ##

-## Specialized functions for certain kinds of lists must be installed -## as methods for the operation PositionSortedByOp. +## Developers who wish to adapt this for custom list types need to +## install suitable methods for the operation PositionSortedByOp. +## PositionSortedByOp ##

## PositionSortedBy( [ "", "ab", ], -1, Length ); @@ -898,6 +898,7 @@ DeclareOperation( "PositionSortedOp", [ IsList, IsObject, IsFunction ] ); ## ## <#/GAPDoc> ## +## We catch plain lists by a function to avoid method selection: DeclareGlobalFunction( "PositionSortedBy" ); DeclareOperation("PositionSortedByOp", [ IsList, IsObject, IsFunction ]); @@ -1549,6 +1550,10 @@ DeclareOperation( "Flat", [ IsList ] ); ## which can also be formulated in terms of the {} operator ## (see ). ##

+## Developers who wish to adapt this for custom list types need to +## install suitable methods for the operation ReversedOp. +## ReversedOp +##

## Reversed( [ 1, 4, 9, 5, 6, 7 ] ); ## [ 7, 6, 5, 9, 4, 1 ] @@ -1557,26 +1562,11 @@ DeclareOperation( "Flat", [ IsList ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "Reversed" ); - - -############################################################################# -## -#O ReversedOp( ) . . . . . . . . . . reverse the elements in a list -## -## -## -## -## -## is the operation called by -## if list is not an internal list. -## (Note that it would not make sense to turn this into an attribute -## because the result shall be mutable.) -## -## -## DeclareOperation( "ReversedOp", [ IsDenseList ] ); + ############################################################################# ## #F Shuffle( ) . . . . . . . . . . . . . . . permute entries randomly @@ -2110,6 +2100,10 @@ DeclareGlobalFunction( "IteratorList" ); ## position of the first element in a list that satisfies a certain ## property. ##

+## Developers who wish to adapt this for custom list types need to +## install suitable methods for the operation FirstOp. +## FirstOp +##

## First( [10^7..10^8], IsPrime ); ## 10000019 @@ -2125,22 +2119,8 @@ DeclareGlobalFunction( "IteratorList" ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "First" ); - - -############################################################################# -## -#O FirstOp( [, ] ) -## -## -## -## -## -## is the operation called by -## if list is not an internally represented list. -## -## -## DeclareOperation( "FirstOp", [ IsListOrCollection ] ); DeclareOperation( "FirstOp", [ IsListOrCollection, IsFunction ] ); @@ -2163,6 +2143,10 @@ DeclareOperation( "FirstOp", [ IsListOrCollection, IsFunction ] ); ## If func returns false for all elements of list ## then returns fail. ##

+## Developers who wish to adapt this for custom list types need to +## install suitable methods for the operation LastOp. +## LastOp +##

## Last( [10^7..10^8], IsPrime ); ## 99999989 @@ -2178,22 +2162,8 @@ DeclareOperation( "FirstOp", [ IsListOrCollection, IsFunction ] ); ## ## <#/GAPDoc> ## +## We catch internal lists by a function to avoid method selection: DeclareGlobalFunction( "Last" ); - - -############################################################################# -## -#O LastOp( [, ] ) -## -## -## -## -## -## is the operation called by -## if list is not an internally represented list. -## -## -## DeclareOperation( "LastOp", [ IsListOrCollection ] ); DeclareOperation( "LastOp", [ IsListOrCollection, IsFunction ] );