ENH: Add shape to *_like() array creation (#13046)

* ENH: Added shape argument to *_like() array creation functions

* ENH: C backend adjustments for shape argument on *_like()

* TST: Added test for shape argument in *_like() functions

* ENH: Added PyArray_NewLikeArrayWithShape()

This change maintains backwards compatibility, rather than passing new
arguments to PyArray_NewLikeArray().

* BUG: Fix for PyArray_NewLikeArrayWithShape strides and ndim == 0

Arrays created with new shapes should not take into consideration the original
array's stride, and ndim == 0 should not be a case to ignore a new shape, as
the caller may request a 0d array.

* REL: Updates for C-API, version 1.17.x

* Add comments to cversions.txt (new PyArray_NewLikeArrayWithShape function)
* Increment C_API_VERSION to 1.17 in setup_common.py

* Revert "REL: Updates for C-API, version 1.17.x"

This reverts commit 807f512ebeb7797ad374d845e41015948afcc708.

* Revert exposing PyArray_NewLikeArrayWithShape on C-API

* DOC: fix versionadded for *_like() shape argument

* STY: add missing spaces in array initializers

* ENH: empty_like raises ValueError

This occurs when shape is defined and number of dimensions match but
order is 'K'.

* TST: test for exception of *_like() functions

* DOC: release note for shape argument in *_like() functions

* DOC: fix *_like() documentation on raises

* BUG: *_like() raises for non-C/F-layout arrays

* TST: change *_like() shapes to prevent NPY_RELAXED_STRIDE_DEBUG=1 failure

* Move empty_like() exception to C implementation

* Update *_like() ValueError documentation

* Rearrange stride computation for *_like() if new shape and order='K'

* Change handling of order= for *_like()

- If order='K' try to keep, otherwise, order='C' is implied
- Do not raise ValueError anymore

* Fix *_like() tests

1 files changed, 27 insertions, 9 deletions

diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py
index 34705efc7..4b59d730d 100644
--- a/numpy/core/numeric.py
+++ b/numpy/core/numeric.py
@@ -90,12 +90,12 @@ class ComplexWarning(RuntimeWarning):
     pass
 
 
-def _zeros_like_dispatcher(a, dtype=None, order=None, subok=None):
+def _zeros_like_dispatcher(a, dtype=None, order=None, subok=None, shape=None):
     return (a,)
 
 
 @array_function_dispatch(_zeros_like_dispatcher)
-def zeros_like(a, dtype=None, order='K', subok=True):
+def zeros_like(a, dtype=None, order='K', subok=True, shape=None):
     """
     Return an array of zeros with the same shape and type as a given array.
 
@@ -119,6 +119,12 @@ def zeros_like(a, dtype=None, order='K', subok=True):
         If True, then the newly created array will use the sub-class
         type of 'a', otherwise it will be a base-class array. Defaults
         to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+
+        .. versionadded:: 1.17.0
 
     Returns
     -------
@@ -150,7 +156,7 @@ def zeros_like(a, dtype=None, order='K', subok=True):
     array([0.,  0.,  0.])
 
     """
-    res = empty_like(a, dtype=dtype, order=order, subok=subok)
+    res = empty_like(a, dtype=dtype, order=order, subok=subok, shape=shape)
     # needed instead of a 0 to get same result as zeros for for string dtypes
     z = zeros(1, dtype=res.dtype)
     multiarray.copyto(res, z, casting='unsafe')
@@ -210,12 +216,12 @@ def ones(shape, dtype=None, order='C'):
     return a
 
 
-def _ones_like_dispatcher(a, dtype=None, order=None, subok=None):
+def _ones_like_dispatcher(a, dtype=None, order=None, subok=None, shape=None):
     return (a,)
 
 
 @array_function_dispatch(_ones_like_dispatcher)
-def ones_like(a, dtype=None, order='K', subok=True):
+def ones_like(a, dtype=None, order='K', subok=True, shape=None):
     """
     Return an array of ones with the same shape and type as a given array.
 
@@ -239,6 +245,12 @@ def ones_like(a, dtype=None, order='K', subok=True):
         If True, then the newly created array will use the sub-class
         type of 'a', otherwise it will be a base-class array. Defaults
         to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+
+        .. versionadded:: 1.17.0
 
     Returns
     -------
@@ -270,7 +282,7 @@ def ones_like(a, dtype=None, order='K', subok=True):
     array([1.,  1.,  1.])
 
     """
-    res = empty_like(a, dtype=dtype, order=order, subok=subok)
+    res = empty_like(a, dtype=dtype, order=order, subok=subok, shape=shape)
     multiarray.copyto(res, 1, casting='unsafe')
     return res
 
@@ -322,12 +334,12 @@ def full(shape, fill_value, dtype=None, order='C'):
     return a
 
 
-def _full_like_dispatcher(a, fill_value, dtype=None, order=None, subok=None):
+def _full_like_dispatcher(a, fill_value, dtype=None, order=None, subok=None, shape=None):
     return (a,)
 
 
 @array_function_dispatch(_full_like_dispatcher)
-def full_like(a, fill_value, dtype=None, order='K', subok=True):
+def full_like(a, fill_value, dtype=None, order='K', subok=True, shape=None):
     """
     Return a full array with the same shape and type as a given array.
 
@@ -349,6 +361,12 @@ def full_like(a, fill_value, dtype=None, order='K', subok=True):
         If True, then the newly created array will use the sub-class
         type of 'a', otherwise it will be a base-class array. Defaults
         to True.
+    shape : int or sequence of ints, optional.
+        Overrides the shape of the result. If order='K' and the number of
+        dimensions is unchanged, will try to keep order, otherwise,
+        order='C' is implied.
+
+        .. versionadded:: 1.17.0
 
     Returns
     -------
@@ -379,7 +397,7 @@ def full_like(a, fill_value, dtype=None, order='K', subok=True):
     array([0.1,  0.1,  0.1,  0.1,  0.1,  0.1])
 
     """
-    res = empty_like(a, dtype=dtype, order=order, subok=subok)
+    res = empty_like(a, dtype=dtype, order=order, subok=subok, shape=shape)
     multiarray.copyto(res, fill_value, casting='unsafe')
     return res