Merge branch 'master' into dev_delist

# Conflicts:
#	src/core/util.h

Author: tturocy

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+_Thanks for contributing to Gambit! Before you submitting or reviewing a pull request, check out our [guidelines for contributing](https://gambitproject.readthedocs.io/en/latest/developer.contributing.html)._
+
+_The person submitting the PR should ensure it has an informative title and update the headers below, before marking the PR as ready for review and assigning reviewers._
+
+### Issues closed by this PR
+
+_Add any issues that are being closed by this PR to the list. Use "Closes" or [another keyword](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue#linking-a-pull-request-to-an-issue-using-a-keyword) followed by the issue number._
+
+- Closes #ISSUE_NUMBER
+
+### Description of the changes in this PR
+
+_Update the description of the changes made in this PR. You can delete this section if the changes are already fully described in the linked issues._
+
+This PR ...
+
+### How to review this PR
+
+_The gambit repository contains source code and documentation for several different components. Explain how a reviewer should approach reviewing the specific changes made in this PR._
+
+_For example, you might include instructions like:_
+- _"Review code changes and ensure tests cover edge cases"_
+- _"Rebuild the GUI from this branch, then test features X, Y, Z work as expected"_
+- _"Click the link to the documentation page and sense check by reading"_

doc/developer.contributing.rst

@@ -37,8 +37,8 @@ version.
 
 1. To get started contributing code in the `Gambit GitHub repo <https://github.com/gambitproject/gambit>`__, do one of the following:
 
-- Core developers: request contributor access from one of the `team <https://www.gambit-project.org/team/>`__
-- External contributors: fork the repository on GitHub.
+   - Core developers: request contributor access from one of the `team <https://www.gambit-project.org/team/>`__
+   - External contributors: fork the repository on GitHub.
 
 2. Clone the repository to your local machine ::
 
@@ -63,9 +63,9 @@ version.
 
    Having `pre-commit` installed is recommended as it runs many of the same checks that are automatically conducted on any pull request.  Every time you commit, it will automatically fix some issues and highlight others for manual adjustment.
 
-5. Create a new branch for your changes ::
+5. Create a new branch for your changes. It's good practice to either give the branch a descriptive name or directly reference an issue number ::
 
-    git checkout -b feature/your-feature-name
+    git checkout -b feature/issue-number
 
 6. Make your changes. ::
 
@@ -78,11 +78,22 @@ version.
 
 7. Push your changes to your fork or branch ::
 
-    git push origin feature/your-feature-name
+    git push origin feature/issue-number
+
+8. Open a pull request on GitHub to the master branch of the upstream repository. Ensure your pull request:
+
+   - Has an informative title.
+   - Links to any relevant issues.
+   - Includes a clear description of the changes made.
+   - Explains how a reviewer can test the changes.
+
+   .. note::
+      It's good practice to open a draft pull request early in the development process to facilitate discussion and feedback, ensure there are no merge conflicts, and allow for continuous integration testing via GitHub Actions.
 
-8. Open a pull request on GitHub to the master branch of the upstream repository, describing your changes and linking to any relevant issues.
 9. Core developers will review your changes, provide feedback, and merge them into the master branch if they meet the project's standards.
 
+10. Once your pull request is merged, delete your branch on GitHub (a button should appear to do this automatically).
+
 Testing your changes
 --------------------
 

doc/index.rst

@@ -60,7 +60,6 @@ We recommended most new users install the PyGambit Python package and read the a
    :hidden:
    :maxdepth: 1
 
-   intro
    install
    pygambit
    tools

doc/intro.rst

@@ -30,6 +30,7 @@
 #include <algorithm>
 #include <numeric>
 #include <map>
+#include <optional>
 
 namespace Gambit {
 
@@ -102,8 +103,9 @@ template <class C> class EnumerateView {
 
 template <class C> auto enumerate(C &p_range) { return EnumerateView<C>(p_range); }
 
-/// @brief A container adaptor which skips over a given value when iterating
-template <typename Container, typename T> class exclude_value {
+/// @brief A container adaptor which returns only the elements matching the predicate
+///        This is intended to look forward to C++20-style ranges
+template <typename Container, typename Pred> class filter_if {
 public:
   using Iter = decltype(std::begin(std::declval<Container &>()));
 
@@ -115,10 +117,10 @@ template <typename Container, typename T> class exclude_value {
     using reference = typename std::iterator_traits<Iter>::reference;
     using pointer = typename std::iterator_traits<Iter>::pointer;
 
-    iterator(Iter current, Iter end, const T &value)
-      : m_current(current), m_end(end), m_value(value)
+    iterator(Iter current, Iter end, Pred pred)
+      : m_current(current), m_end(end), m_pred(std::move(pred))
     {
-      skip_if_value();
+      advance_next_valid();
     }
 
     value_type operator*() const { return *m_current; }
@@ -127,7 +129,7 @@ template <typename Container, typename T> class exclude_value {
     iterator &operator++()
     {
       ++m_current;
-      skip_if_value();
+      advance_next_valid();
       return *this;
     }
 
@@ -143,25 +145,22 @@ template <typename Container, typename T> class exclude_value {
       return a.m_current == b.m_current;
     }
 
-    friend bool operator!=(const iterator &a, const iterator &b)
-    {
-      return a.m_current != b.m_current;
-    }
+    friend bool operator!=(const iterator &a, const iterator &b) { return !(a == b); }
 
   private:
     Iter m_current, m_end;
-    T m_value;
+    Pred m_pred;
 
-    void skip_if_value()
+    void advance_next_valid()
     {
-      while (m_current != m_end && *m_current == m_value) {
+      while (m_current != m_end && !m_pred(*m_current)) {
         ++m_current;
       }
     }
   };
 
-  exclude_value(const Container &c, const T &value)
-    : m_begin(c.begin(), c.end(), value), m_end(c.end(), c.end(), value)
+  filter_if(const Container &c, Pred pred)
+    : m_begin(c.begin(), c.end(), pred), m_end(c.end(), c.end(), pred)
   {
   }
 
@@ -172,6 +171,60 @@ template <typename Container, typename T> class exclude_value {
   iterator m_begin, m_end;
 };
 
+template <typename Value, typename Range> class prepend_value {
+public:
+  using Iter = decltype(std::begin(std::declval<Range &>()));
+
+  class iterator {
+  public:
+    using iterator_category = std::forward_iterator_tag;
+    ;
+    using value_type = Value;
+    using difference_type = std::ptrdiff_t;
+    using reference = Value;
+    using pointer = Value;
+
+    iterator(std::optional<Value> first, Iter current, Iter end)
+      : m_first(std::move(first)), m_current(current), m_end(end)
+    {
+    }
+
+    reference operator*() const { return m_first ? *m_first : *m_current; }
+
+    iterator &operator++()
+    {
+      if (m_first) {
+        m_first.reset();
+      }
+      else {
+        ++m_current;
+      }
+      return *this;
+    }
+
+    bool operator==(const iterator &other) const
+    {
+      return m_first == other.m_first && m_current == other.m_current;
+    }
+
+    bool operator!=(const iterator &other) const { return !(*this == other); }
+
+  private:
+    std::optional<Value> m_first;
+    Iter m_current, m_end;
+  };
+
+  prepend_value(Value first, Range range) : m_first(first), m_range(std::move(range)) {}
+
+  iterator begin() const { return {m_first, std::begin(m_range), std::end(m_range)}; }
+
+  iterator end() const { return {std::nullopt, std::end(m_range), std::end(m_range)}; }
+
+private:
+  Value m_first;
+  Range m_range;
+};
+
 /// @brief Returns the maximum value of the function over the *non-empty* container
 template <class Container, class Func>
 auto maximize_function(const Container &p_container, const Func &p_function)