[Numpy-svn] r5153 - in trunk/numpy/core: . tests

[numpy-svn at scipy.org]

Author: rkern
Date: 2008-05-09 19:18:03 -0500 (Fri, 09 May 2008)
New Revision: 5153

Modified:
   trunk/numpy/core/fromnumeric.py
   trunk/numpy/core/tests/test_numeric.py
Log:
Add the out= argument to the clip() function to bring it in line with the .clip() method.

Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py	2008-05-09 17:17:12 UTC (rev 5152)
+++ trunk/numpy/core/fromnumeric.py	2008-05-10 00:18:03 UTC (rev 5153)
@@ -889,30 +889,45 @@
     return compress(condition, axis, out)
 
 
-def clip(a, a_min, a_max):
+def clip(a, a_min, a_max, out=None):
     """Return an array whose values are limited to [a_min, a_max].
 
     Parameters
     ----------
     a : {array_like}
         Array containing elements to clip.
-    a_min
+    a_min :
         Minimum value
-    a_max
+    a_max :
         Maximum value
+    out : array, optional
+        The results will be placed in this array. It may be the input array for
+        inplace clipping.
 
     Returns
     -------
     clipped_array : {array}
         A new array whose elements are same as for a, but values
         < a_min are replaced with a_min, and > a_max with a_max.
-    
+
+    Examples
+    --------
+    >>> a = np.arange(10)
+    >>> np.clip(a, 1, 8)
+    array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8])
+    >>> a
+    array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
+    >>> np.clip(a, 3, 6, out=a)
+    array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
+    >>> a
+    array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
+
     """
     try:
         clip = a.clip
     except AttributeError:
-        return _wrapit(a, 'clip', a_min, a_max)
-    return clip(a_min, a_max)
+        return _wrapit(a, 'clip', a_min, a_max, out)
+    return clip(a_min, a_max, out)
 
 
 def sum(a, axis=None, dtype=None, out=None):

Modified: trunk/numpy/core/tests/test_numeric.py
===================================================================
--- trunk/numpy/core/tests/test_numeric.py	2008-05-09 17:17:12 UTC (rev 5152)
+++ trunk/numpy/core/tests/test_numeric.py	2008-05-10 00:18:03 UTC (rev 5153)
@@ -668,6 +668,19 @@
         self.clip(a, m, M, ac)
         assert_array_strict_equal(a, ac)
 
+    def test_clip_func_takes_out(self):
+        """ Ensure that the clip() function takes an out= argument.
+        """
+        a = self._generate_data(self.nr, self.nc)
+        ac = a.copy()
+        m = -0.5
+        M = 0.6
+        a2 = clip(a, m, M, out=a)
+        self.clip(a, m, M, ac)
+        assert_array_strict_equal(a2, ac)
+        self.assert_(a2 is a)
+
+
 class test_allclose_inf(ParametricTestCase):
     rtol = 1e-5
     atol = 1e-8