ENHANCE: `onlyone'' option for ContainedConjugates`

lib/grplatt.gd

@@ -449,21 +449,29 @@ DeclareGlobalFunction("LowLayerSubgroups");
 
 #############################################################################
 ##
-#O ContainedConjugates(<G>,<A>,<B>)
+#O ContainedConjugates(<G>,<A>,<B>[,<onlyone>])
 ##
 ## <#GAPDoc Label="ContainedConjugates">
 ## <ManSection>
-## <Oper Name="ContainedConjugates" Arg='G, A, B'/>
+## <Oper Name="ContainedConjugates" Arg='G, A, B [,onlyone]'/>
 ##
 ## <Description>
 ## For <M>A,B \leq G</M> this operation returns representatives of the <A>A</A>
 ## conjugacy classes of subgroups that are conjugate to <A>B</A> under <A>G</A>.
 ## The function returns a list of pairs of subgroup and conjugating element.
+## If the optional fourth argument <A>onlyone</A> is given as <A>true</A>,
+## then only one pair (or <A>fail</A> if none exists) is returned.
 ## <Example><![CDATA[
 ## gap> g:=SymmetricGroup(8);;
-## gap> a:=TransitiveGroup(8,47);;b:=TransitiveGroup(8,7);;
+## gap> a:=TransitiveGroup(8,47);;b:=TransitiveGroup(8,9);;
 ## gap> ContainedConjugates(g,a,b);
-## [ [ Group([ (1,4,2,5,3,6,8,7), (1,3)(2,8) ]), (2,4,5,3)(7,8) ] ]
+## [ [ Group([ (1,8)(2,3)(4,5)(6,7), (1,3)(2,8)(4,6)(5,7), (1,5)(2,6)(3,7)(4,8),
+ (4,5)(6,7) ]), () ],
+## [ Group([ (1,8)(2,3)(4,5)(6,7), (1,5)(2,6)(3,7)(4,8), (1,3)(2,8)(4,6)(5,7),
+ (2,3)(6,7) ]), (2,4)(3,5) ] ]
+## gap> ContainedConjugates(g,a,b,true);
+## [ Group([ (1,8)(2,3)(4,5)(6,7), (1,3)(2,8)(4,6)(5,7), (1,5)(2,6)(3,7)(4,8),
+ (4,5)(6,7) ]), () ]
 ## ]]></Example>
 ## </Description>
 ## </ManSection>

lib/grplatt.gi

@@ -3187,21 +3187,22 @@ local act,offset,G,lim,cond,dosub,all,m,i,j,new,old;
  return all;
 end);
 
-#############################################################################
-##
-#F ContainedConjugates( <G>, <A>, <B> )
-##
-InstallMethod(ContainedConjugates,"finite groups",IsFamFamFam,[IsGroup,IsGroup,IsGroup],0,
-function(G,A,B)
-local l,N,dc,gens,i;
+DoContainedConjugates:=function(arg)
+local G,A,B,onlyone,l,N,dc,gens,i;
+ G:=arg[1];
+ A:=arg[2];
+ B:=arg[3];
+ if Length(arg)>3 then onlyone:=arg[4]; else onlyone:=false;fi;
+
  if not IsFinite(G) and IsFinite(A) and IsFinite(B) then
  TryNextMethod();
  fi;
  if not IsSubset(G,A) and IsSubset(G,B) then
  Error("A and B must be subgroups of G");
  fi;
  if Size(A) mod Size(B)<>0 then
- return []; # cannot be contained by order
+ # cannot be contained by order
+ if onlyone then return fail;else return [];fi;
  fi;
 
  l:=[];
@@ -3211,15 +3212,30 @@ local l,N,dc,gens,i;
  gens:=SmallGeneratingSet(B);
  for i in dc do
  if ForAll(gens,x->x^i[1] in A) then
+ if onlyone then return [B^i[1],i[1]];fi;
  Add(l,[B^i[1],i[1]]);
  fi;
  od;
+ if onlyone then return fail;fi;
+ return l;
+ elif onlyone then
+ l:=DoConjugateInto(G,A,B,true);
+ if l<>fail then l:=[B^l,l];fi;
  return l;
  else
  l:=DoConjugateInto(G,A,B,false);
  return List(l,x->[B^x,x]);
  fi;
-end);
+end;
+
+#############################################################################
+##
+#F ContainedConjugates( <G>, <A>, <B> )
+##
+InstallMethod(ContainedConjugates,"finite groups",IsFamFamFam,
+ [IsGroup,IsGroup,IsGroup],0,DoContainedConjugates);
+InstallOtherMethod(ContainedConjugates,"onlyone",IsFamFamFamX,
+ [IsGroup,IsGroup,IsGroup,IsBool],0,DoContainedConjugates);
 
 #############################################################################
 ##