Merge pull request #2598 from oddbookworm/clamp_zero_vector

Allow for clamping the zero vector when possible

Author: MyreMylar

docs/reST/ref/math.rst

@@ -471,7 +471,7 @@ Multiple coordinates can be set using slices or swizzling
       | :sg:`clamp_magnitude(min_length, max_length, /) -> Vector2`
 
       **Experimental:** feature still in development available for testing and feedback. It may change.
-      `Please leave clamp_magnitude feedback with authors <https://github.com/pygame/pygame/pull/2990>`_
+      `Please leave clamp_magnitude feedback with authors <https://github.com/pygame-community/pygame-ce>`_
 
       Returns a new copy of a vector with the magnitude clamped between 
       ``max_length`` and ``min_length``. If only one argument is passed, it is 
@@ -482,6 +482,12 @@ Multiple coordinates can be set using slices or swizzling
 
       .. versionadded:: 2.1.3
 
+      .. versionchanged:: 2.4.0 It is now possible to use ``clamp_magnitude`` on a zero-vector as long as ``min_length``
+         is unspecified or 0.
+      
+      .. note::
+         Before pygame-ce 2.4.0, attempting to clamp a zero vector would always raise a ``ValueError``
+
       .. ## Vector2.clamp_magnitude ##
    
 
@@ -499,6 +505,12 @@ Multiple coordinates can be set using slices or swizzling
 
       .. versionadded:: 2.1.3
 
+      .. versionchanged:: 2.4.0 It is now possible to use ``clamp_magnitude`` on a zero-vector as long as ``min_length``
+         is unspecified or 0.
+      
+      .. note::
+         Before pygame-ce 2.4.0, attempting to clamp a zero vector would always raise a ``ValueError``
+
       .. ## Vector2.clamp_magnitude_ip ##
 
 
@@ -1118,6 +1130,12 @@ Multiple coordinates can be set using slices or swizzling
 
       .. versionadded:: 2.1.3
 
+      .. versionchanged:: 2.4.0 It is now possible to use ``clamp_magnitude`` on a zero-vector as long as ``min_length``
+         is unspecified or 0.
+      
+      .. note::
+         Before pygame-ce 2.4.0, attempting to clamp a zero vector would always raise a ``ValueError``
+
       .. ## Vector3.clamp_magnitude ##
    
 
@@ -1135,6 +1153,12 @@ Multiple coordinates can be set using slices or swizzling
 
       .. versionadded:: 2.1.3
 
+      .. versionchanged:: 2.4.0 It is now possible to use ``clamp_magnitude`` on a zero-vector as long as ``min_length``
+         is unspecified or 0.
+      
+      .. note::
+         Before pygame-ce 2.4.0, attempting to clamp a zero vector would always raise a ``ValueError``
+
       .. ## Vector3.clamp_magnitude_ip ##
 
    .. method:: update

src_c/math.c

@@ -928,9 +928,10 @@ vector_clamp_magnitude_ip(pgVector *self, PyObject *const *args,
 
     /* Get magnitude of Vector */
     old_length_sq = _scalar_product(self->coords, self->coords, self->dim);
-    if (old_length_sq == 0) {
+    if (old_length_sq == 0 && min_length > 0) {
         return RAISE(PyExc_ValueError,
-                     "Cannot clamp a vector with zero length");
+                     "Cannot clamp a vector with zero length with a "
+                     "min_length greater than 0");
     }
 
     /* Notes for other contributors reading this code:

test/math_test.py

@@ -1173,6 +1173,11 @@ def test_clamp_mag_v2_no_change(self):
                 self.assertEqual(v1, v2)
                 self.assertEqual(v1, Vector2(1, 2))
 
+        v2 = Vector2()
+        self.assertEqual(v2.clamp_magnitude(1), Vector2())
+        v2.clamp_magnitude_ip(2)
+        self.assertEqual(v2.magnitude(), 0)
+
     def test_clamp_mag_v2_edge_cases(self):
         v1 = Vector2(1, 2)
         v2 = v1.clamp_magnitude(6, 6)
@@ -1206,10 +1211,10 @@ def test_clamp_mag_v2_errors(self):
                 self.assertRaises(ValueError, v1.clamp_magnitude, *invalid_args)
                 self.assertRaises(ValueError, v1.clamp_magnitude_ip, *invalid_args)
 
-        # 0 vector
+        # 0 vector with a min_length > 0
         v2 = Vector2()
-        self.assertRaises(ValueError, v2.clamp_magnitude, 3)
-        self.assertRaises(ValueError, v2.clamp_magnitude_ip, 4)
+        self.assertRaises(ValueError, v2.clamp_magnitude, 1, 2)
+        self.assertRaises(ValueError, v2.clamp_magnitude_ip, 2, 3)
 
     def test_subclassing_v2(self):
         """Check if Vector2 is subclassable"""
@@ -2828,6 +2833,11 @@ def test_clamp_mag_v3_no_change(self):
                 self.assertEqual(v1, v2)
                 self.assertEqual(v1, Vector3(1, 2, 3))
 
+            v2 = Vector3()
+            self.assertEqual(v2.clamp_magnitude(1), Vector3())
+            v2.clamp_magnitude_ip(2)
+            self.assertEqual(v2.magnitude(), 0)
+
     def test_clamp_mag_v3_edge_cases(self):
         v1 = Vector3(1, 2, 1)
         v2 = v1.clamp_magnitude(6, 6)
@@ -2863,8 +2873,8 @@ def test_clamp_mag_v3_errors(self):
 
         # 0 vector
         v2 = Vector3()
-        self.assertRaises(ValueError, v2.clamp_magnitude, 3)
-        self.assertRaises(ValueError, v2.clamp_magnitude_ip, 4)
+        self.assertRaises(ValueError, v2.clamp_magnitude, 1, 2)
+        self.assertRaises(ValueError, v2.clamp_magnitude_ip, 2, 3)
 
     def test_subclassing_v3(self):
         """Check if Vector3 is subclassable"""