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

Defined in `awkward.operations.structure <https://github.com/scikit-hep/awkward-1.0/blob/80bbef0738a6b7928333d7c705ee1b359991de5b/src/awkward/operations/structure.py>`__ on `line 2665 <https://github.com/scikit-hep/awkward-1.0/blob/80bbef0738a6b7928333d7c705ee1b359991de5b/src/awkward/operations/structure.py#L2665>`__.

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


    :param array: Data containing nested lists to pad to a target length.
    :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.layout.Content` subclass.
    :type highlevel: bool
    :param behavior: Custom :py:obj:`ak.behavior` for the output array, if
                 high-level.
    :type behavior: None or dict

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

Consider the following doubly nested ``array``.

.. code-block:: python


    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.to_list(ak.pad_none(array, 5, axis=0))
    [[
      [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.to_list(ak.pad_none(array, 3, axis=1))
    [[
      [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.to_list(ak.pad_none(array, 2, axis=2))
    [[
      [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], ... [8.8, 9.9]]] type='3 * var * var * ?float64'>

and

.. code-block:: python


    >>> ak.pad_none(array, 2, axis=2, clip=True)
    <Array [[[1.1, 2.2], [None, ... [8.8, 9.9]]] 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.type(ak.pad_none(array, 2, axis=2))
    3 * var * var * ?float64
    >>> ak.type(ak.pad_none(array, 2, axis=2, clip=True))
    3 * var *   2 * ?float64

