CloseMutableBasis now returns something

Up to now, `CloseMutableBasis` had no return value.
Now it returns `true` if the basis was extended and `false` otherwise.

This saves work in situations where one builds a basis by
adding vectors, and where one wants to know which ones really
extended the current basis.

lib/algrep.gi

@@ -568,8 +568,7 @@ InstallMethod( CloseMutableBasis,
     [ IsMutableBasis and IsMutable and
       IsMutableBasisViaUnderlyingMutableBasisRep, IsVector ], 0,
     function( MB, v )
-
-       CloseMutableBasis( MB!.underlyingMutableBasis, ExtRepOfObj( v ) );
+    return CloseMutableBasis( MB!.underlyingMutableBasis, ExtRepOfObj( v ) );
 
 end );
 

lib/basismut.gd

@@ -218,24 +218,33 @@ DeclareOperation( "ImmutableBasis", [ IsMutableBasis, IsFreeLeftModule ] );
 ##
 ##  <Description>
 ##  For a mutable basis <A>MB</A> over the coefficient ring <M>R</M>, say,
-##  and a vector <A>v</A>, <C>CloseMutableBasis</C> changes <A>MB</A> such that afterwards
-##  it describes the <M>R</M>-span of the former basis vectors together with <A>v</A>.
+##  and a vector <A>v</A>, <Ref Oper="CloseMutableBasis"/> changes <A>MB</A>
+##  such that afterwards it describes the <M>R</M>-span of the former
+##  basis vectors together with <A>v</A>.
 ##  <P/>
 ##  <E>Note</E> that if <A>v</A> enlarges the dimension then this does in general <E>not</E>
 ##  mean that <A>v</A> is simply added to the basis vectors of <A>MB</A>.
 ##  Usually a linear combination of <A>v</A> and the other basis vectors is added,
 ##  and also the old basis vectors may be modified, for example in order to
-##  keep the list of basis vectors echelonized (see&nbsp;<Ref Prop="IsSemiEchelonized"/>).
+##  keep the list of basis vectors echelonized
+##  (see&nbsp;<Ref Prop="IsSemiEchelonized"/>).
+##  <P/>
+##  <Ref Oper="CloseMutableBasis"/> returns <K>false</K> if <A>v</A> was
+##  already in the <M>R</M>-span described by <A>MB</A>,
+##  and <K>true</K> if <A>MB</A> got extended.
 ##  <Example><![CDATA[
 ##  gap> MB:= MutableBasis( Rationals, [ [ 1, 1, 3 ], [ 2, 2, 1 ] ] );
 ##  <mutable basis over Rationals, 2 vectors>
 ##  gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
 ##  false
 ##  gap> CloseMutableBasis( MB, [ 1, 0, 0 ] );
+##  true
 ##  gap> MB;
 ##  <mutable basis over Rationals, 3 vectors>
 ##  gap> IsContainedInSpan( MB, [ 1, 0, 0 ] );
 ##  true
+##  gap> CloseMutableBasis( MB, [ 1, 0, 0 ] );
+##  false
 ##  ]]></Example>
 ##  </Description>
 ##  </ManSection>

lib/basismut.gi

@@ -206,6 +206,10 @@ InstallMethod( CloseMutableBasis,
       V:= LeftModuleByGenerators( LeftActingDomain( V ), vectors );
       UseBasis( V, vectors );
       MB!.immutableBasis := Basis( V );
+      return true;
+    else
+      # The basis was not extended.
+      return false;
     fi;
     end );
 
@@ -406,7 +410,7 @@ InstallMethod( CloseMutableBasis,
     function( MB, v )
     local R, M;
     if IsBound( MB!.niceMutableBasis ) then
-      CloseMutableBasis( MB!.niceMutableBasis,
+      return CloseMutableBasis( MB!.niceMutableBasis,
                          NiceVector( MB!.leftModule, v ) );
     elif v <> MB!.zero then
 
@@ -419,6 +423,7 @@ InstallMethod( CloseMutableBasis,
       MB!.leftModule:= M;
       MB!.niceMutableBasis:= MutableBasis( R,
                                        [ NiceVector( M, v ) ] );
+      return true;
 
     fi;
     end );

lib/vspcmat.gi

@@ -1045,6 +1045,7 @@ InstallMethod( CloseMutableBasis,
       ResetFilterObj( MB, IsMutableBasisOfGaussianMatrixSpaceRep );
 
       MB!.immutableBasis:= Basis( V );
+      return true;
 
     else
 
@@ -1077,10 +1078,12 @@ InstallMethod( CloseMutableBasis,
           od;
           Add( basisvectors, v );
           heads[i][j]:= Length( basisvectors );
-          break;
+          return true;
         fi;
       od;
 
+      # The basis was not extended.
+      return false;
     fi;
     end );
 

lib/vspcrow.gi

@@ -1560,6 +1560,7 @@ InstallMethod( CloseMutableBasis,
       ResetFilterObj( MB, IsMutableBasisOfGaussianRowSpaceRep );
 
       MB!.immutableBasis:= Basis( V );
+      return true;
 
     else
 
@@ -1568,7 +1569,7 @@ InstallMethod( CloseMutableBasis,
       ncols:= Length( v );
       heads:= MB!.heads;
 
-      if ncols <> Length( MB!.heads ) then
+      if ncols <> Length( heads ) then
         Error( "<v> must have same length as `MB!.heads'" );
       fi;
 
@@ -1588,6 +1589,10 @@ InstallMethod( CloseMutableBasis,
         MultVector( v, Inverse( v[j] ) );
         Add( basisvectors, v );
         heads[j]:= Length( basisvectors );
+        return true;
+      else
+        # The basis was not extended.
+        return false;
       fi;
 
     fi;

tst/testinstall/vspchom.tst

@@ -404,7 +404,10 @@ gap> IsSubset( hom, triv );
 true
 gap> mb:= MutableBasis( f, [], zero );
 <mutable basis over GF(3), 0 vectors>
+gap> CloseMutableBasis( mb, zero );
+false
 gap> CloseMutableBasis( mb, map6 );
+true
 gap> ImmutableBasis( mb );
 Basis( <vector space of dimension 1 over GF(3)>, ... )
 

tst/testinstall/vspcmali.tst

@@ -365,6 +365,7 @@ gap> mb:= MutableBasis( Rationals,
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 true
 gap> CloseMutableBasis( mb, LieObject( [ [ E(4), 0 ], [ 0, 0 ] ] ) );
+true
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 false
 gap> Print( BasisVectors( mb ), "\n" );
@@ -376,8 +377,11 @@ gap> mb:= MutableBasis( Rationals,
 >            LieObject( [ [ 1, 1 ], [ 1, 1 ] ] ) ] );
 <mutable basis over Rationals, 2 vectors>
 gap> CloseMutableBasis( mb, LieObject( [ [ 1, 2 ], [ 3, 4 ] ] ) );
+true
 gap> CloseMutableBasis( mb, LieObject( [ [ 1, 2 ], [ 3, 5 ] ] ) );
+true
 gap> CloseMutableBasis( mb, LieObject( [ [ 0, 0 ], [ 0, 7 ] ] ) );
+false
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 true
 gap> bv:= BasisVectors( mb );;
@@ -392,8 +396,11 @@ gap> mb:= MutableBasis( Rationals, [],
 >             LieObject( [ [ 0, 0 ], [ 0, 0 ] ] ) );
 <mutable basis over Rationals, 0 vectors>
 gap> CloseMutableBasis( mb, LieObject( [ [ 1, 2 ], [ 3, 4 ] ] ) );
+true
 gap> CloseMutableBasis( mb, LieObject( [ [ 1, 2 ], [ 3, 5 ] ] ) );
+true
 gap> CloseMutableBasis( mb, LieObject( [ [ 0, 0 ], [ 0, 7 ] ] ) );
+false
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 true
 gap> BasisVectors( mb );

tst/testinstall/vspcmat.tst

@@ -322,6 +322,7 @@ gap> mb:= MutableBasis( Rationals,
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 true
 gap> CloseMutableBasis( mb, [ [ E(4), 0 ], [ 0, 0 ] ] );
+true
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 false
 gap> BasisVectors( mb );
@@ -332,8 +333,11 @@ gap> mb:= MutableBasis( Rationals,
 >            [ [ 1, 1 ], [ 1, 1 ] ] ] );
 <mutable basis over Rationals, 2 vectors>
 gap> CloseMutableBasis( mb, [ [ 1, 2 ], [ 3, 4 ] ] );
+true
 gap> CloseMutableBasis( mb, [ [ 1, 2 ], [ 3, 5 ] ] );
+true
 gap> CloseMutableBasis( mb, [ [ 0, 0 ], [ 0, 7 ] ] );
+false
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 true
 gap> bv:= BasisVectors( mb );;
@@ -347,8 +351,11 @@ SemiEchelonBasis( <vector space of dimension 4 over Rationals>,
 gap> mb:= MutableBasis( Rationals, [], [ [ 0, 0 ], [ 0, 0 ] ] );
 <mutable basis over Rationals, 0 vectors>
 gap> CloseMutableBasis( mb, [ [ 1, 2 ], [ 3, 4 ] ] );
+true
 gap> CloseMutableBasis( mb, [ [ 1, 2 ], [ 3, 5 ] ] );
+true
 gap> CloseMutableBasis( mb, [ [ 0, 0 ], [ 0, 7 ] ] );
+false
 gap> IsMutableBasisOfGaussianMatrixSpaceRep( mb );
 true
 gap> BasisVectors( mb );
@@ -359,7 +366,22 @@ SemiEchelonBasis( <vector space of dimension 2 over Rationals>,
 gap> mb:= MutableBasis( Rationals, [], [ [ 0, 0 ], [ 0, 0 ] ] );
 <mutable basis over Rationals, 0 vectors>
 gap> CloseMutableBasis( mb, [ [ 1, 0 ], [ 0, 1 ] ] );
+true
 gap> CloseMutableBasis( mb, [ [ 0, 1 ], [ 1, 0 ] ] );   
+true
 gap> IsContainedInSpan( mb, [ [ 1, 1 ], [ 1, 1 ] ] );
 true
+
+#############################################################################
+##
+##  8. Methods for mutable bases of non-Gaussian matrix spaces
+##
+gap> mb:= MutableBasis( Rationals, [ [ [ E(4) ] ] ] );
+<mutable basis over Rationals, 1 vectors>
+gap> CloseMutableBasis( mb, [ [ E(3) ] ] );
+true
+gap> CloseMutableBasis( mb, [ [ E(3)+E(4) ] ] );
+false
+
+##
 gap> STOP_TEST( "vspcmat.tst", 1);

tst/testinstall/vspcrow.tst

@@ -290,6 +290,7 @@ gap> mb:= MutableBasis( Rationals,
 gap> IsMutableBasisOfGaussianRowSpaceRep( mb );
 true
 gap> CloseMutableBasis( mb, [ E(4), 0, 0, 0 ] );
+true
 gap> IsMutableBasisOfGaussianRowSpaceRep( mb );
 false
 gap> BasisVectors( mb );
@@ -298,8 +299,11 @@ gap> mb:= MutableBasis( Rationals,
 >          [ [ 1, 1, 1, 1 ], [ 0, 1, 1, 1 ], [ 1, 1, 1, 1 ] ] );
 <mutable basis over Rationals, 2 vectors>
 gap> CloseMutableBasis( mb, [ 1, 2, 3, 4 ] );
+true
 gap> CloseMutableBasis( mb, [ 1, 2, 3, 5 ] );
+true
 gap> CloseMutableBasis( mb, [ 0, 0, 0, 7 ] );
+false
 gap> IsMutableBasisOfGaussianRowSpaceRep( mb );
 true
 gap> BasisVectors( mb );
@@ -310,8 +314,11 @@ SemiEchelonBasis( <vector space of dimension 4 over Rationals>,
 gap> mb:= MutableBasis( Rationals, [], [ 0, 0, 0, 0 ] );
 <mutable basis over Rationals, 0 vectors>
 gap> CloseMutableBasis( mb, [ 1, 2, 3, 4 ] );
+true
 gap> CloseMutableBasis( mb, [ 1, 2, 3, 5 ] );
+true
 gap> CloseMutableBasis( mb, [ 0, 0, 0, 7 ] );
+false
 gap> IsMutableBasisOfGaussianRowSpaceRep( mb );
 true
 gap> BasisVectors( mb );
@@ -320,9 +327,20 @@ gap> ImmutableBasis( mb );
 SemiEchelonBasis( <vector space of dimension 2 over Rationals>, 
 [ [ 1, 2, 3, 4 ], [ 0, 0, 0, 1 ] ] )
 
+############################################################################
+##
+##  8. Methods for mutable bases of non-Gaussian row spaces
+##
+gap> mb:= MutableBasis( Rationals, [ [ E(4) ] ] );
+<mutable basis over Rationals, 1 vectors>
+gap> CloseMutableBasis( mb, [ E(3) ] );
+true
+gap> CloseMutableBasis( mb, [ E(3)+E(4) ] );
+false
+
 #############################################################################
 ##
-##  8. Enumerations
+##  9. Enumerations
 ##
 gap> erg:= [];;  i:= 0;;
 gap> dims:= [ 1,4,27,28,29,31,32,33,63,64,65,92,127,128,129,384 ];;
@@ -338,7 +356,7 @@ gap> erg;
 
 #############################################################################
 ##
-##  9. Arithmetic
+##  10. Arithmetic
 ##
 gap> A := [ [ Z(2^2)^2, 0*Z(2), Z(2^2), 0*Z(2), 0*Z(2), 0*Z(2) ], 
 >   [ Z(2^2)^2, 0*Z(2), Z(2^2)^2, Z(2)^0, Z(2^2)^2, Z(2)^0 ],