ak.pad_none
-----------

.. py:module: ak.pad_none

Defined in `awkward.operations.ak_pad_none <https://github.com/scikit-hep/awkward/blob/e9dd2694cf5c6ccb1717358fe926816d8ecbfb9c/src/awkward/operations/ak_pad_none.py>`__ on `line 17 <https://github.com/scikit-hep/awkward/blob/e9dd2694cf5c6ccb1717358fe926816d8ecbfb9c/src/awkward/operations/ak_pad_none.py#L17>`__.

.. py:function:: ak.pad_none(array, target, axis=1, *, clip=False, highlevel=True, behavior=None, attrs=None)


    :param array: Array-like data (anything :py:obj:`ak.to_layout` recognizes).
    :param target: The intended length of the lists. If ``clip=True``,
               the output lists will have exactly this length; otherwise,
               they will have *at least* this length.
    :type target: int
    :param axis: The dimension at which this operation is applied. The
             outermost dimension is ``0``, followed by ``1``, etc., and negative
             values count backward from the innermost: ``-1`` is the innermost
             dimension, ``-2`` is the next level up, etc.
    :type axis: int
    :param clip: If True, the output lists will have regular lengths
             (:py:obj:`ak.types.RegularType`) of exactly ``target``; otherwise the
             output lists will have in-principle variable lengths
             (:py:obj:`ak.types.ListType`) of at least ``target``.
    :type clip: bool
    :param highlevel: If True, return an :py:obj:`ak.Array`; otherwise, return
                  a low-level :py:obj:`ak.contents.Content` subclass.
    :type highlevel: bool
    :param behavior: Custom :py:obj:`ak.behavior` for the output array, if
                 high-level.
    :type behavior: None or dict
    :param attrs: Custom attributes for the output array, if
              high-level.
    :type attrs: None or dict

Increase the lengths of lists to a target length by adding None values.

Consider the following

.. code-block:: python


    >>> array = ak.Array([[[1.1, 2.2, 3.3],
    ...                    [],
    ...                    [4.4, 5.5],
    ...                    [6.6]],
    ...                   [],
    ...                   [[7.7],
    ...                    [8.8, 9.9]
    ...                   ]])

At ``axis=0``, this operation pads the whole array, adding None at the
outermost level:

.. code-block:: python


    >>> ak.pad_none(array, 5, axis=0).show()
    [[[1.1, 2.2, 3.3], [], [4.4, 5.5], [6.6]],
     [],
     [[7.7], [8.8, 9.9]],
     None,
     None]

At ``axis=1``, this operation pads the first nested level:

.. code-block:: python


    >>> ak.pad_none(array, 3, axis=1).show()
    [[[1.1, 2.2, 3.3], [], [4.4, 5.5], [6.6]],
     [None, None, None],
     [[7.7], [8.8, 9.9], None]]

And so on for higher values of ``axis``:

.. code-block:: python


    >>> ak.pad_none(array, 2, axis=2).show()
    [[[1.1, 2.2, 3.3], [None, None], [4.4, 5.5], [6.6, None]],
     [],
     [[7.7, None], [8.8, 9.9]]]

Note that the ``clip`` parameter not only determines whether the lengths are
at least ``target`` or exactly ``target``, it also determines the type of the
output:

* ``clip=True`` returns regular lists (:py:obj:`ak.types.RegularType`), and
* ``clip=False`` returns in-principle variable lengths
  (:py:obj:`ak.types.ListType`).

The in-principle variable-length lists might, in fact, all have the same
length, but the type difference is significant, for instance in
broadcasting rules (see :py:obj:`ak.broadcast_arrays`).

The difference between

.. code-block:: python


    >>> ak.pad_none(array, 2, axis=2)
    <Array [[[1.1, 2.2, 3.3], ..., [...]], ...] type='3 * var * var * ?float64'>

and

.. code-block:: python


    >>> ak.pad_none(array, 2, axis=2, clip=True)
    <Array [[[1.1, 2.2], ..., [6.6, None]], ...] type='3 * var * 2 * ?float64'>

is not just in the length of ``[1.1, 2.2, 3.3]`` vs ``[1.1, 2.2]``, but also
in the distinction between the following types.

.. code-block:: python


    >>> ak.pad_none(array, 2, axis=2).type.show()
    3 * var * var * ?float64
    >>> ak.pad_none(array, 2, axis=2, clip=True).type.show()
    3 * var *   2 * ?float64