Bind BWAPI.Lowest/Highest, update filter docs, and add tests

docs/source/api/BWAPI/classes/Game.rst

@@ -196,15 +196,15 @@ Game
       All units are checked. If center and radius are specified, then it will check all units that are within the radius of the position.
 
       :param function best: A function that takes two :class:`Unit` arguments and returns the best out of the two.
-      :param function pred: A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance.
+      :param function pred: A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`).
       :param BWAPI.Position center: (optional) The position to use in the search. If omitted, then the entire map is searched.
       :param int radius: (optional) The distance from ``center`` to search for units. If omitted, then the entire map is searched.
 
       :return: The desired unit that best matches the given criteria. Returns ``nil`` if a suitable unit was not found.
       :rtype: :class:`BWAPI.Unit`
 
       .. seealso::
-         :meth:`getClosestUnit`, :mod:`~BWAPI.Filter`
+         :meth:`getClosestUnit`, :mod:`~BWAPI.Filter`, :meth:`BWAPI.Lowest`, :meth:`BWAPI.Highest`
 
    .. method:: getBuildLocation(type, desiredPosition, [maxRange = 64], [creep = false]) -> TilePosition
 
@@ -232,21 +232,21 @@ Game
       Retrieves the closest unit to center that matches the criteria of the callback pred within an optional radius.
 
       :param BWAPI.Position center: The position to start searching for the closest unit.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
       :param int radius: (optional) The radius to search in. If omitted, the entire map will be searched.
 
       :return: The desired unit that is closest to center. Returns ``nil`` if a suitable unit was not found.
       :rtype: :class:`BWAPI.Unit`
 
       .. seealso::
-         :meth:`getBestUnit`, :class:`~BWAPI.UnitFilter`
+         :meth:`getBestUnit`, :mod:`~BWAPI.Filter`
 
    .. method:: getClosestUnitInRectangle(center, [pred = nil], [left = 0], [top = 0], [right = 999999], [bottom = 999999]) -> Unit
 
       Retrieves the closest unit to center that matches the criteria of the callback pred within an optional rectangle.
 
       :param BWAPI.Position center: The position to start searching for the closest unit.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
       :param int left: (optional) The left position of the rectangle. This value is 0 by default.
       :param int top: (optional) The top position of the rectangle. This value is 0 by default.
       :param int right: (optional) The right position of the rectangle. This value includes the entire map width by default.
@@ -256,7 +256,7 @@ Game
       :rtype: :class:`BWAPI.Unit`
 
       .. seealso::
-         :class:`~BWAPI.UnitFilter`
+         :mod:`~BWAPI.Filter`
 
    .. method:: getDamageFrom(fromType, toType, [fromPlayer = nil], [toPlayer = nil]) -> int
 
@@ -676,7 +676,7 @@ Game
       :param int x: The x coordinate of the center, in pixels.
       :param int y: The y coordinate of the center, in pixels.
       :param int radius: The radius from the center, in pixels, to include units.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` object consisting of all the units that have any part of them within the given radius from the center position.
       :rtype: :class:`BWAPI.Unitset`
@@ -687,7 +687,7 @@ Game
 
       :param BWAPI.Position center: The coordinate of the center.
       :param int radius: The radius from the center, in pixels, to include units.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` object consisting of all the units that have any part of them within the given radius from the center position.
       :rtype: :class:`BWAPI.Unitset`
@@ -700,7 +700,7 @@ Game
       :param int top: The Y coordinate of the top position of the bounding box, in pixels.
       :param int right: The X coordinate of the right position of the bounding box, in pixels.
       :param int bottom: The Y coordinate of the bottom position of the bounding box, in pixels.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` object consisting of all the units that have any part of them within the given rectangle bounds.
       :rtype: :class:`BWAPI.Unitset`
@@ -711,7 +711,7 @@ Game
 
       :param BWAPI.Position topLeft:
       :param BWAPI.Position bottomRight:
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` object consisting of all the units that have any part of them within the given rectangle bounds.
       :rtype: :class:`BWAPI.Unitset`
@@ -722,7 +722,7 @@ Game
 
       :param int tileX: The X position, in tiles.
       :param int tileY: The Y position, in tiles.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` object consisting of all the units that have any part of them on the given build tile.
       :rtype: :class:`BWAPI.Unitset`
@@ -732,7 +732,7 @@ Game
       This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
       :param BWAPI.TilePosition tile:
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` object consisting of all the units that have any part of them on the given build tile.
       :rtype: :class:`BWAPI.Unitset`

docs/source/api/BWAPI/classes/Region.rst

@@ -134,7 +134,7 @@ Region
 
       Also has the ability to filter the units before the creation of the :class:`~BWAPI.Unitset`.
 
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` containing all units in this region that have met the requirements of ``pred``.
       :rtype: :class:`BWAPI.Unitset`

docs/source/api/BWAPI/classes/Regionset.rst

@@ -42,7 +42,7 @@ Regionset
 
       Also has the ability to filter the units before the creation of the :class:`~BWAPI.Unitset`.
 
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` containing all units in this region that have met the requirements of ``pred``.
       :rtype: :class:`BWAPI.Unitset`

docs/source/api/BWAPI/classes/Unit.rst

@@ -868,7 +868,7 @@ Unit
       Takes into account this unit's dimensions. Can optionally specify a filter to include only specific units (such as only ground units, etc.)
 
       :param number radius: The radius, in pixels, to search for units.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
       :return: A :class:`Unitset` containing the set of units that match the given criteria.
       :rtype: :class:`Unitset`
 
@@ -902,7 +902,7 @@ Unit
       Obtains the set of units within weapon range of this unit.
 
       :param BWAPI.WeaponType weapon: The weapon type to use as a filter for distance and units that can be hit by it.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. If omitted, no additional filter is used.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). If omitted, no additional filter is used.
       :return: The set of units within weapon range of this unit.
       :rtype: :class:`Unitset`
 
@@ -913,7 +913,7 @@ Unit
 
       Retrieves the closest unit to this one.
 
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. If ``pred`` is omitted or ``nil``, then the closest unit owned by any player will be returned.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). If ``pred`` is omitted or ``nil``, then the closest unit owned by any player will be returned.
       :param number radius: (optional) The maximum radius to check for the closest unit. For performance reasons, a developer can limit the radius that is checked. If omitted, then the entire map is checked.
       :return: The closest unit that matches the predicate, or ``nil`` if no matching unit is found.
       :rtype: :class:`Unit`

docs/source/api/BWAPI/classes/Unitset.rst

@@ -535,7 +535,7 @@ Unitset
 
       Retrieves the closest unit relative to the value of :meth:`getPosition`.
 
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
       :param int radius: (optional) The maximum radius to check for the closest unit. For performance reasons, a developer can limit the radius that is checked. If omitted, then the entire map is checked.
 
       :return: The closest unit that matches the predicate, or ``nil`` if no matching unit is found.
@@ -591,7 +591,7 @@ Unitset
       Takes into account this unit's dimensions. Can optionally specify a filter to include only specific units (such as only ground units, etc.)
 
       :param int radius: The radius, in pixels, to search for units.
-      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise **or** a :class:`UnitFilter` instance. Defaults to ``nil``, which means no filter.
+      :param function pred: (optional) A predicate function that takes a :class:`Unit` and returns ``true`` for units that satisfy the intended filter and ``false`` otherwise (can be a :ref:`BWAPI.Filter unary filter <unary-filters>`). Defaults to ``nil``, which means no filter.
 
       :return: A :class:`~BWAPI.Unitset` containing the set of units that match the given criteria.
       :rtype: :class:`BWAPI.Unitset`

docs/source/api/BWAPI/data/Filter.rst

@@ -1,10 +1,14 @@
 .. currentmodule:: BWAPI
 
+.. _filters:
+
 Filter
 ======
 
 .. module:: BWAPI.Filter
 
+.. _unary-filters:
+
 Unary Filters
 -------------
 
@@ -355,6 +359,8 @@ These functions can be used as predicates for functions that take a unit predica
 
    Equivalent to ``unit:isVisible()``
 
+.. _comparison-filters:
+
 Comparison Filters
 ------------------
 

docs/source/api/BWAPI/index.rst

@@ -57,6 +57,28 @@ Functions
    :return: ``true`` if this is a DEBUG build, or ``false`` if this is a RELEASE build
    :rtype: boolean
 
+.. staticmethod:: Lowest(filter) -> bestFilter
+
+   Takes a :ref:`comparison filter <comparison-filters>` (or similar function) and converts it into a 'best' function intended for use with :meth:`Game.getBestUnit`.
+
+   :param function filter: A function that takes a :class:`~BWAPI.Unit` and returns a value that will be used for comparison. The returned value must be of a type that can be compared using the less than operator.
+   :return: A function that takes two :class:`~BWAPI.Unit` objects, and returns the object with the lowest value returned when passing it into ``filter``.
+   :rtype: function
+
+   .. seealso::
+      :ref:`The differences between the C++ and Lua implementations of BestFilter <differences-bestfilter>`, :meth:`Game.getBestUnit`
+
+.. staticmethod:: Highest(filter) -> bestFilter
+
+   Takes a :ref:`comparison filter <comparison-filters>` (or similar function) and converts it into a 'best' function intended for use with :meth:`Game.getBestUnit`.
+
+   :param function filter: A function that takes a :class:`~BWAPI.Unit` and returns a value that will be used for comparison. The returned value must be of a type that can be compared using the greater than operator.
+   :return: A function that takes two :class:`~BWAPI.Unit` objects, and returns the object with the highest value returned when passing it into ``filter``.
+   :rtype: function
+
+   .. seealso::
+      :ref:`The differences between the C++ and Lua implementations of BestFilter <differences-bestfilter>`, :meth:`Game.getBestUnit`
+
 Callbacks
 ---------
 

docs/source/api/differences.rst

@@ -199,7 +199,7 @@ All functions that take a UnitFilter parameter now expect a Lua function that ta
 
    :mod:`BWAPI.Filter` functions can be used by calling them with a :class:`Unit` as the parameter (e.g. ``BWAPI.Filter.CanAttack(unit)``)
 
-   These filters can also be combined by using the normal Lua boolean operators and wrapping/returning the result in a function. The function can then be passed as an argument to functions that would normally take a :class:`UnitFilter` in C++, like so:
+   These filters can also be combined by using the normal Lua boolean operators and wrapping/returning the result in a function. The function can then be passed as an argument to functions that would normally take a ``UnitFilter`` in C++, like so:
 
    .. code-block:: lua
 
@@ -213,7 +213,7 @@ All functions that take a UnitFilter parameter now expect a Lua function that ta
 BestFilter
 ----------
 
-All functions that take a BestUnitFilter parameter now expect a Lua function that takes two parameters: the current best unit, and the unit to compare to, and returns the best unit out of the two.
+All functions that take a ``BestUnitFilter`` parameter now expect a Lua function that takes two parameters: the current best unit, and the unit to compare to, and returns the best unit out of the two.
 
 .. code-block:: lua
    :caption: Example

src/bindings/Filters.cpp

@@ -20,6 +20,34 @@ namespace BWAPI_Lua
 
 	void bindFilters(sol::table module)
 	{
+		sol::state_view lua(module.lua_state());
+
+		sol::function Lowest = lua.do_string(R"(
+return function(filter)
+	return function(a, b)
+		if filter(b) < filter(a) then
+			return b
+		else
+			return a
+		end
+	end
+end
+		)");
+		module.set("Lowest", Lowest);
+
+		sol::function Highest = lua.do_string(R"(
+return function(filter)
+	return function(a, b)
+		if filter(b) > filter(a) then
+			return b
+		else
+			return a
+		end
+	end
+end
+		)");
+		module.set("Highest", Highest);
+
 		auto filter = module.create_named("Filter");
 		filter["IsTransport"] = unaryFilterAsFunction(Filter::IsTransport);
 		filter["CanProduce"] = unaryFilterAsFunction(Filter::CanProduce);