Implement generic link of face

engine/maths/CMakeLists.txt

@@ -1,6 +1,7 @@
 # maths 
 
 ADD_SUBDIRECTORY("spec")
+ADD_SUBDIRECTORY("detail")
 
 # Files to compile
 SET ( FILES

engine/maths/detail/CMakeLists.txt

@@ -0,0 +1,8 @@
+# maths/detail
+
+if (${REGINA_INSTALL_DEV})
+  INSTALL( FILES
+    permContractFront.h
+    DESTINATION "${INCLUDEDIR}/maths/detail" COMPONENT Development)
+endif (${REGINA_INSTALL_DEV})
+

engine/maths/detail/permContractFront.h

@@ -0,0 +1,157 @@
+
+/**************************************************************************
+ *                                                                        *
+ *  Regina - A Normal Surface Theory Calculator                           *
+ *  Computational Engine                                                  *
+ *                                                                        *
+ *  Copyright (c) 1999-2023, Ben Burton                                   *
+ *  For further details contact Ben Burton (bab@debian.org).              *
+ *                                                                        *
+ *  This program is free software; you can redistribute it and/or         *
+ *  modify it under the terms of the GNU General Public License as        *
+ *  published by the Free Software Foundation; either version 2 of the    *
+ *  License, or (at your option) any later version.                       *
+ *                                                                        *
+ *  As an exception, when this program is distributed through (i) the     *
+ *  App Store by Apple Inc.; (ii) the Mac App Store by Apple Inc.; or     *
+ *  (iii) Google Play by Google Inc., then that store may impose any      *
+ *  digital rights management, device limits and/or redistribution        *
+ *  restrictions that are required by its terms of service.               *
+ *                                                                        *
+ *  This program is distributed in the hope that it will be useful, but   *
+ *  WITHOUT ANY WARRANTY; without even the implied warranty of            *
+ *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU     *
+ *  General Public License for more details.                              *
+ *                                                                        *
+ *  You should have received a copy of the GNU General Public             *
+ *  License along with this program; if not, write to the Free            *
+ *  Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,       *
+ *  MA 02110-1301, USA.                                                   *
+ *                                                                        *
+ **************************************************************************/
+
+#ifndef __REGINA_PERM_CONTRACT_FRONT_H
+#ifndef __DOXYGEN
+#define __REGINA_PERM_CONTRACT_FRONT_H
+#endif
+
+/*! \file maths/detail/permContractFront.h
+ *  \brief Implements Perm<n>::contractFront.
+ */
+
+namespace regina {
+
+namespace detail {
+
+/**
+ * A helper template to implement Perm<n>::contractFront(Perm<k>).
+ */
+template<int n,
+         int k,
+         PermCodeType nPermCodeType = Perm<n>::codeType,
+         PermCodeType kPermCodeType = Perm<k>::codeType>
+struct PermContractFront;
+
+/*
+ * Generic implementation using the Perm<n>(p[0], ..., p[n-1])
+ * contructor which is only available when Perm<n> encoding
+ * is PERM_CODE_INDEX.
+ */
+template<int n, int k, PermCodeType kPermCodeType>
+struct PermContractFront<n, k, PERM_CODE_INDEX, kPermCodeType>
+{
+    static_assert(n < k);
+
+    Perm<n> operator() (Perm<k> p) {
+        return helper(p, std::make_integer_sequence<int, n>());
+    }
+
+private:
+    template<int ...i>
+    Perm<n> helper(Perm<k> p, std::integer_sequence<int, i...>)
+    {
+        constexpr int s = k - n;
+        return Perm<n>(p[s + i] - s...);
+    }
+};
+
+/*
+ * Generic implementation where Perm<n> is constructed using the
+ * bit-coded images, so internal encoding must be PERM_CODE_IMAGES.
+ */
+template<int n, int k, PermCodeType kPermCodeType>
+struct PermContractFront<n, k, PERM_CODE_IMAGES, kPermCodeType>
+{
+    static_assert(n < k);
+
+    Perm<n> operator() (Perm<k> p) {
+        constexpr int s = k - n;
+
+        using Code = typename Perm<n>::Code;
+
+        Code c = 0;
+        for (int i = 0, bits = 0; i < n; ++i, bits += Perm<n>::imageBits)
+            c |= static_cast<Code>(p[s + i] - s) << bits;
+
+        return Perm<n>::fromPermCode(c);
+    }
+};
+
+template<int k>
+struct PermContractFront<k, k + 1, PERM_CODE_INDEX, PERM_CODE_INDEX>
+{
+    Perm<k> operator() (Perm<k + 1> p) {
+        using Code = typename Perm<k>::Code2;
+        return Perm<k>::fromPermCode2(static_cast<Code>(p.permCode2()));
+    }
+};
+
+template<int k, PermCodeType kPermCodeType>
+struct PermContractFront<2, k, PERM_CODE_INDEX, kPermCodeType>
+{
+    static_assert(2 < k);
+
+    Perm<2> operator() (Perm<k> p) {
+        using Code = typename Perm<2>::Code;
+        return Perm<2>::fromPermCode(static_cast<Code>(
+                                         p[k-1] == k - 1 ? 0 : 1));
+    }
+};
+
+template<>
+struct PermContractFront<2, 3, PERM_CODE_INDEX, PERM_CODE_INDEX>
+{
+    Perm<2> operator() (Perm<3> p) {
+        using Code = typename Perm<2>::Code;
+        return Perm<2>::fromPermCode(static_cast<Code>(
+                                         p.permCode() == 0 ? 0 : 1));
+    }
+};
+
+template<>
+struct PermContractFront<2, 4, PERM_CODE_INDEX, PERM_CODE_INDEX>
+{
+    Perm<2> operator() (Perm<4> p) {
+        const Perm<4>::Code2 c = p.permCode2();
+        return Perm<2>::fromPermCode(static_cast<Perm<2>::Code>(
+                                         c == 1 || c == 6 ? 1 : 0));
+    }
+};
+
+template<>
+struct PermContractFront<2, 5, PERM_CODE_INDEX, PERM_CODE_INDEX>
+{
+    Perm<2> operator() (Perm<5> p) {
+        const Perm<5>::Code2 c = p.permCode2();
+        return Perm<2>::fromPermCode(
+            static_cast<Perm<2>::Code>(
+                c == 1 || c == 6 || c == 24 || c == 31 || c == 49 || c == 54
+                ? 1 : 0));
+    }
+};
+
+}
+
+}
+
+#endif

engine/maths/perm.h

@@ -1273,6 +1273,32 @@ class Perm {
         template <int k>
         static constexpr Perm contract(Perm<k> p);
 
+        /**
+         * Restricts a <i>k</i>-element permutation to an <i>n</i>-element
+         * permutation, where \a k > \a n.
+         *
+         * This is similar to Perm<n>::contract but is considering the last
+         * <i>n</i> elements of the <i>k</i>-element permutation rather than
+         * the first and ignores the "unused" images
+         * \a p[0], ...,\a p[<i>k</i> - \a n - 1].
+         *
+         * The resulting permutation maps 0,...,<i>n</i>-1 to
+         * \a p[<i>k</i> - \a n] + \a n - <i>k</i>, ...,
+         * \a p[<i>k</i> - 1] + \a n - <i>k</i>.
+         *
+         * \pre The given permutation maps <i>k</i> - \a n, ..., <i>k</i> - 1
+         * to <i>k</i> - \a n, ..., <i>k</i> - 1 in some order.
+         *
+         * \tparam k the number of elements for the input permutation;
+         * this must be strictly greater than \a n.
+         *
+         * \param p a permutation on \a k elements.
+         * \return the same permutation restricted to a permutation on
+         * the last \a n elements.
+         */
+        template <int k>
+        static constexpr Perm contractFront(Perm<k> p);
+
         /**
          * Is this permutation minimal in its conjugacy class?
          *
@@ -2261,6 +2287,7 @@ constexpr Perm<n> Perm<n>::contract(Perm<k> p) {
 
     return Perm<n>(c);
 }
+
 #endif // __DOXYGEN
 
 template <int n>
@@ -2560,6 +2587,8 @@ inline PermClass<n> PermClass<n>::operator ++(int) {
 #include "maths/spec/perm5.h"
 #include "maths/spec/perm7.h"
 
+#include "maths/detail/permContractFront.h"
+
 // Explicitly declare the non-specialised classes as extern.  Otherwise the
 // linker on Windows (and *only* Windows) fails to unify their static data
 // members between the DLL and the executable (even though they are correctly
@@ -2579,10 +2608,25 @@ extern template class regina::Perm<16>;
 
 namespace regina {
 
+template <int n>
+template <int k>
+constexpr Perm<n> Perm<n>::contractFront(Perm<k> p) {
+    static_assert(
+        k > n,
+        "Given permutation needs to have more elements then permutation "
+        "we contract to.");
+    return detail::PermContractFront<n, k>()(p);
+}
+
 // What follows are implementations that use these specialised classes.
 // We hide them from doxygen since specialisations can confuse it.
 #ifndef __DOXYGEN
 
+template <int k>
+inline constexpr Perm<2> Perm<2>::contractFront(Perm<k> p) {
+    return detail::PermContractFront<2, k>()(p);
+}
+
 template <int k>
 inline constexpr Perm<2> Perm<2>::contract(Perm<k> p) {
     static_assert(k >= 8, "The generic implementation of Perm<2>::contract<k> "
@@ -2635,6 +2679,11 @@ inline constexpr Perm<3> Perm<3>::contract(Perm<k> p) {
     return Perm<3>(p[0], p[1], p[2]);
 }
 
+template <int k>
+inline constexpr Perm<3> Perm<3>::contractFront(Perm<k> p) {
+    return detail::PermContractFront<3, k>()(p);
+}
+
 template <>
 inline constexpr Perm<3> Perm<3>::contract(Perm<4> p) {
     // Code map: 0,3,8,7,12,15 -> 0,1,2,3,4,5.
@@ -2666,6 +2715,11 @@ inline constexpr Perm<4> Perm<4>::contract(Perm<k> p) {
     return Perm<4>(p[0], p[1], p[2], p[3]);
 }
 
+template <int k>
+inline constexpr Perm<4> Perm<4>::contractFront(Perm<k> p) {
+    return detail::PermContractFront<4, k>()(p);
+}
+
 inline void Perm<4>::clear(unsigned from) {
     if (from <= 1)
         code_ = 0;
@@ -2697,6 +2751,11 @@ constexpr Perm<5> Perm<5>::contract(Perm<k> p) {
     return Perm<5>(p[0], p[1], p[2], p[3], p[4]);
 }
 
+template <int k>
+inline constexpr Perm<5> Perm<5>::contractFront(Perm<k> p) {
+    return detail::PermContractFront<5, k>()(p);
+}
+
 inline void Perm<5>::clear(unsigned from) {
     if (from <= 1)
         code2_ = 0;
@@ -2747,6 +2806,11 @@ constexpr Perm<6> Perm<6>::contract(Perm<k> p) {
     return Perm<6>(p[0], p[1], p[2], p[3], p[4], p[5]);
 }
 
+template <int k>
+inline constexpr Perm<6> Perm<6>::contractFront(Perm<k> p) {
+    return detail::PermContractFront<6, k>()(p);
+}
+
 inline void Perm<6>::clear(unsigned from) {
     switch (from) {
         case 0:
@@ -2800,6 +2864,11 @@ constexpr Perm<7> Perm<7>::contract(Perm<k> p) {
     return Perm<7>(p[0], p[1], p[2], p[3], p[4], p[5], p[6]);
 }
 
+template <int k>
+inline constexpr Perm<7> Perm<7>::contractFront(Perm<k> p) {
+    return detail::PermContractFront<7, k>()(p);
+}
+
 inline void Perm<7>::clear(unsigned from) {
     switch (from) {
         case 0: