a
    yn„fp  ã                   @  sn   d dl mZ d dlZd dlmZ d dlmZmZ d dl	m
Z
 dZe
 ¡ Zeƒ dddddœd	d
„ƒZdd„ ZdS )é    )ÚannotationsN)Úhigh_level_function)ÚHighLevelContextÚensure_same_backend)ÚNumpyMetadata)ÚmaskT)Ú
valid_whenÚ	highlevelÚbehaviorÚattrsc                c  s   | |fV  t | |||||ƒS )aŽ  
    Args:
        array: Array-like data (anything #ak.to_layout recognizes).
        mask (array of booleans): The mask that overlays elements in the
            `array` with None. Must have the same length as `array`.
        valid_when (bool): If True, True values in `mask` are considered
            valid (passed from `array` to the output); if False, False
            values in `mask` are considered valid.
        highlevel (bool): If True, return an #ak.Array; otherwise, return
            a low-level #ak.contents.Content subclass.
        behavior (None or dict): Custom #ak.behavior for the output array, if
            high-level.
        attrs (None or dict): Custom attributes for the output array, if
            high-level.

    Returns an array for which

        output[i] = array[i] if mask[i] == valid_when else None

    Unlike filtering data with #ak.Array.__getitem__, this `output` has the
    same length as the original `array` and can therefore be used in
    calculations with it, such as
    [universal functions](https://docs.scipy.org/doc/numpy/reference/ufuncs.html).

    For example, with

        >>> array = ak.Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

    with a boolean selection of `good` elements like

        >>> good = (array % 2 == 1)
        >>> good
        <Array [False, True, False, True, ..., True, False, True] type='10 * bool'>

    could be used to filter the original `array` (or another with the same
    length).

        >>> array[good]
        <Array [1, 3, 5, 7, 9] type='5 * int64'>

    However, this eliminates information about which elements were dropped and
    where they were. If we instead use #ak.mask,

        >>> ak.mask(array, good)
        <Array [None, 1, None, 3, None, 5, None, 7, None, 9] type='10 * ?int64'>

    this information and the length of the array is preserved, and it can be
    used in further calculations with the original `array` (or another with
    the same length).

        >>> ak.mask(array, good) + array
        <Array [None, 2, None, 6, None, 10, None, 14, None, 18] type='10 * ?int64'>

    In particular, successive filters can be applied to the same array.

    Even if the `array` and/or the `mask` is nested,

        >>> array = ak.Array([[[0, 1, 2], [], [3, 4], [5]], [[6, 7, 8], [9]]])
        >>> good = (array % 2 == 1)
        >>> good
        <Array [[[False, True, False], ..., [True]], ...] type='2 * var * var * bool'>

    it can still be used with #ak.mask because the `array` and `mask`
    parameters are broadcasted.

        >>> ak.mask(array, good)
        <Array [[[None, 1, None], [], ..., [5]], ...] type='2 * var * var * ?int64'>

    See #ak.broadcast_arrays for details about broadcasting and the generalized
    set of broadcasting rules.

    Another syntax for

        ak.mask(array, array_of_booleans)

    is

        array.mask[array_of_booleans]

    (which is 5 characters away from simply filtering the `array`).
    )Ú_impl)Úarrayr   r   r	   r
   r   © r   ú]/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/awkward/operations/ak_mask.pyr      s    T
r   c           
        sš   ‡ fdd„}t ||d��2}t|j| ddd�|j|ddd�ƒ}W d   ƒ n1 sP0    Y  tjj||ddd�}	t|	tƒr„t|	ƒd	ksˆJ ‚|j	|	d
 |d�S )Nc                   sr   | \}}|j rj|j |j¡}t|jjttj	fƒs@t
d|j›�ƒ‚tj | tj¡¡}tjjj||ˆ d�fS d S d S )Nz!mask must have boolean type, not ©r   )Zis_numpyZnplikeZasarrayÚdataÚ
issubclassZdtypeÚtypeÚboolÚnpZbool_Ú
ValueErrorÚakÚindexZIndex8ÚviewZint8ÚcontentsZByteMaskedArrayZ
simplified)ÚinputsÚbackendÚkwargsZlayoutarrayZ
layoutmaskÚmZbytemaskr   r   r   Úactionj   s    ÿÿz_impl.<locals>.action)r
   r   FÚerror)Zallow_recordZprimitive_policyT)Znumpy_to_regularZright_broadcasté   r   )r	   )
r   r   Úunwrapr   Z_broadcastingZbroadcast_and_applyÚ
isinstanceÚtupleÚlenÚwrap)
r   r   r   r	   r
   r   r   ÚctxZlayoutsÚoutr   r   r   r   i   s    þ"ÿr   )Ú
__future__r   Zawkwardr   Zawkward._dispatchr   Zawkward._layoutr   r   Zawkward._nplikes.numpy_liker   Ú__all__Úinstancer   r   r   r   r   r   r   Ú<module>   s   Y