ak.copy
-------

.. py:module: ak.copy

Defined in `awkward.operations.ak_copy <https://github.com/scikit-hep/awkward/blob/36da52cfa8846355c390beb6555eac1d31c27c26/src/awkward/operations/ak_copy.py>`__ on `line 18 <https://github.com/scikit-hep/awkward/blob/36da52cfa8846355c390beb6555eac1d31c27c26/src/awkward/operations/ak_copy.py#L18>`__.

.. py:function:: ak.copy(array)


    :param array: Array-like data (anything :py:obj:`ak.to_layout` recognizes).

Returns a deep copy of the array (no memory shared with original).

This is identical to ``np.copy`` and ``copy.deepcopy``.

It's only useful to explicitly copy an array if you're going to change it
in-place. This doesn't come up often because Awkward Arrays are immutable.
That is to say, the Awkward Array library doesn't have any operations that
change an array in-place, but the data in the array might be owned by another
library that can change it in-place.

For example, if the array comes from NumPy:

.. code-block:: python


    >>> underlying_array = np.array([1.1, 2.2, 3.3, 4.4, 5.5])
    >>> wrapper = ak.Array(underlying_array)
    >>> duplicate = ak.copy(wrapper)
    >>> underlying_array[2] = 123
    >>> underlying_array
    array([  1.1,   2.2, 123. ,   4.4,   5.5])
    >>> wrapper
    <Array [1.1, 2.2, 123, 4.4, 5.5] type='5 * float64'>
    >>> duplicate
    <Array [1.1, 2.2, 3.3, 4.4, 5.5] type='5 * float64'>

There is an exception to this rule: you can add fields to records in an
:py:obj:`ak.Array` in-place. However, this changes the :py:obj:`ak.Array` wrapper without
affecting the underlying layout data (it *replaces* its layout), so a
shallow copy will do:

.. code-block:: python


    >>> import copy
    >>> original = ak.Array([{"x": 1}, {"x": 2}, {"x": 3}])
    >>> shallow_copy = copy.copy(original)
    >>> shallow_copy["y"] = original.x**2
    >>> shallow_copy
    <Array [{x: 1, y: 1}, {...}, {x: 3, y: 9}] type='3 * {x: int64, y: int64}'>
    >>> original
    <Array [{x: 1}, {x: 2}, {x: 3}] type='3 * {x: int64}'>

This is key to Awkward Array's efficiency (memory and speed): operations that
only change part of a structure reuse pieces from the original ("structural
sharing"). Changing data in-place would result in many surprising long-distance
changes, so we don't support it. However, an :py:obj:`ak.Array`'s data might come from
a mutable third-party library, so this function allows you to make a true copy.