ENH: core: Add np.copyto, PyArray_MaskedMoveInto, PyArray_MaskedCopyInto

These functions expose masked copying routines, with and without
handling of overlapping data. Also deprecated the np.putmask and
PyArray_PutMask functions, because np.copyto supercedes their
functionality. This will need to be discussed on the list during
the pull request review.

doc/source/reference/c-api.array.rst

@@ -475,6 +475,10 @@ From other objects
     indicates that the array should be aligned in the sense that the
     strides are multiples of the element size.
 
+    In versions 1.6 and earlier of NumPy, the following flags
+    did not have the _ARRAY_ macro namespace in them. That form
+    of the constant names is deprecated in 1.7.
+
 .. cvar:: NPY_ARRAY_NOTSWAPPED
 
     Make sure the returned array has a data-type descriptor that is in
@@ -1210,6 +1214,10 @@ might not be writeable. It might be in Fortan-contiguous order. The
 array flags are used to indicate what can be said about data
 associated with an array.
 
+In versions 1.6 and earlier of NumPy, the following flags
+did not have the _ARRAY_ macro namespace in them. That form
+of the constant names is deprecated in 1.7.
+
 .. cvar:: NPY_ARRAY_C_CONTIGUOUS
 
     The data area is in C-style contiguous order (last index varies the

doc/source/reference/routines.array-manipulation.rst

@@ -3,6 +3,13 @@ Array manipulation routines
 
 .. currentmodule:: numpy
 
+Basic operations
+================
+.. autosummary::
+   :toctree: generated/
+
+    copyto
+
 Changing array shape
 ====================
 .. autosummary::

numpy/add_newdocs.py

@@ -3184,6 +3184,10 @@ def luf(lamdaexpr, *args, **kwargs):
         order.  If order is 'A' ('Any'), then the result has the same order
         as the input.
 
+    See also
+    --------
+    numpy.copyto
+
     Examples
     --------
     >>> x = np.array([[1,2,3],[4,5,6]], order='F')
@@ -3690,11 +3694,50 @@ def luf(lamdaexpr, *args, **kwargs):
 
     """))
 
+add_newdoc('numpy.core.multiarray', 'copyto',
+    """
+    copyto(dst, src, casting='same_kind', where=None)
+
+    Copies values from `src` into `dst`, broadcasting as necessary.
+    Raises a TypeError if the casting rule is violated, and if
+    `where` is provided, it selects which elements to copy.
+
+    .. versionadded:: 1.7.0
+
+    Parameters
+    ----------
+    dst : ndarray
+        The array into which values are copied.
+    src : array_like
+        The array from which values are copied.
+    casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional
+        Controls what kind of data casting may occur when copying.
+
+          * 'no' means the data types should not be cast at all.
+          * 'equiv' means only byte-order changes are allowed.
+          * 'safe' means only casts which can preserve values are allowed.
+          * 'same_kind' means only safe casts or casts within a kind,
+            like float64 to float32, are allowed.
+          * 'unsafe' means any data conversions may be done.
+    where : array_like of bool
+        A boolean array which is broadcasted to match the dimensions
+        of `dst`, and selects elements to copy from `src` to `dst`
+        wherever it contains the value True.
+
+    Returns
+    -------
+    out : ndarray
+        Returns the array `dst`.
+
+    """)
 
 add_newdoc('numpy.core.multiarray', 'putmask',
     """
     putmask(a, mask, values)
 
+    This function is deprecated as of NumPy 1.7. Use the function
+    ``np.copy(a, values, where=mask)`` to achieve this functionality.
+
     Changes elements of an array based on conditional and input values.
 
     Sets ``a.flat[n] = values[n]`` for each n where ``mask.flat[n]==True``.
@@ -3714,7 +3757,7 @@ def luf(lamdaexpr, *args, **kwargs):
 
     See Also
     --------
-    place, put, take
+    place, put, take, copyto
 
     Examples
     --------
@@ -5959,6 +6002,8 @@ def luf(lamdaexpr, *args, **kwargs):
     information defining business days for the business
     day-related functions.
 
+    .. versionadded:: 1.7.0
+
     Parameters
     ----------
     weekmask : str or array_like of bool, optional
@@ -6018,6 +6063,8 @@ def luf(lamdaexpr, *args, **kwargs):
     Calculates which of the given dates are valid business days, and
     which are not.
 
+    .. versionadded:: 1.7.0
+
     Parameters
     ----------
     dates : array_like of datetime64[D]
@@ -6070,6 +6117,8 @@ def luf(lamdaexpr, *args, **kwargs):
     the ``roll`` rule, then applies offsets to the given dates
     counted in business days.
 
+    .. versionadded:: 1.7.0
+
     Parameters
     ----------
     dates : array_like of datetime64[D]
@@ -6158,6 +6207,8 @@ def luf(lamdaexpr, *args, **kwargs):
     Counts the number of business days between `begindates` and
     `enddates`, not including the day of `enddates`.
 
+    .. versionadded:: 1.7.0
+
     Parameters
     ----------
     begindates : array_like of datetime64[D]

numpy/core/code_generators/numpy_api.py

@@ -256,7 +256,7 @@
     'PyArray_TimedeltaToTimedeltaStruct':   221,
     'PyArray_DatetimeStructToDatetime':     222,
     'PyArray_TimedeltaStructToTimedelta':   223,
-    # New Iterator API
+    # NDIter API
     'NpyIter_New':                          224,
     'NpyIter_MultiNew':                     225,
     'NpyIter_AdvancedNew':                  226,
@@ -315,6 +315,9 @@
     'PyArray_GetArrayParamsFromObject':     278,
     'PyArray_ConvertClipmodeSequence':      279,
     'PyArray_MatrixProduct2':               280,
+    # End 1.6 API
+    'PyArray_MaskedCopyInto':               281,
+    'PyArray_MaskedMoveInto':               282,
 }
 
 ufunc_types_api = {

numpy/core/numeric.py

@@ -1,7 +1,7 @@
 __all__ = ['newaxis', 'ndarray', 'flatiter', 'nditer', 'nested_iters', 'ufunc',
            'arange', 'array', 'zeros', 'count_nonzero', 'empty', 'broadcast',
            'dtype', 'fromstring', 'fromfile', 'frombuffer',
-           'int_asbuffer', 'where', 'argwhere',
+           'int_asbuffer', 'where', 'argwhere', 'copyto',
            'concatenate', 'fastCopyAndTranspose', 'lexsort', 'set_numeric_ops',
            'can_cast', 'promote_types', 'min_scalar_type', 'result_type',
            'asarray', 'asanyarray', 'ascontiguousarray', 'asfortranarray',
@@ -58,6 +58,7 @@ class ComplexWarning(RuntimeWarning):
 nested_iters = multiarray.nested_iters
 broadcast = multiarray.broadcast
 dtype = multiarray.dtype
+copyto = multiarray.copyto
 ufunc = type(sin)