ak.contents.ListArray
---------------------

.. py:module: ak.contents.ListArray

Defined in `awkward.contents.listarray <https://github.com/scikit-hep/awkward/blob/b4f9627fd984b284e79a322a20833cc40c1eb089/src/awkward/contents/listarray.py>`__ on `line 54 <https://github.com/scikit-hep/awkward/blob/b4f9627fd984b284e79a322a20833cc40c1eb089/src/awkward/contents/listarray.py#L54>`__.

.. py:class:: ak.contents.ListArray(self, starts, stops, content, *, parameters=None)

ListArray generalizes :py:obj:`ak.contents.ListOffsetArray` by not
requiring its ``content`` to be in increasing order and by allowing it to
have unreachable elements between lists. Instead of a single ``offsets`` buffer,
ListArray has

* ``starts``: The starting index of each list.
* ``stops``: The stopping index of each list.

:py:obj:`ak.contents.ListOffsetArray` ``offsets`` may be related to ``starts`` and
``stops`` by

.. code-block:: python


    starts = offsets[:-1]
    stops = offsets[1:]

ListArrays are a common by-product of structure manipulation: as a result of
some operation, we might want to view slices or permutations of the ``content``
without copying it to make a contiguous version of it. For that reason,
ListArrays are more useful in a data-manipulation library like Awkward Array
than in a data-representation library like Apache Arrow.

Like :py:obj:`ak.contents.ListOffsetArray` and :py:obj:`ak.contents.RegularArray`, a ListArray can
represent strings if its ``__array__`` parameter is ``"string"`` (UTF-8 assumed) or
``"bytestring"`` (no encoding assumed) and it contains an :py:obj:`ak.contents.NumpyArray`
of ``dtype=np.uint8`` whose ``__array__`` parameter is ``"char"`` (UTF-8 assumed) or
``"byte"`` (no encoding assumed).

There is no equivalent of ListArray in Apache Arrow.

To illustrate how the constructor arguments are interpreted, the following is a
simplified implementation of ``__init__``, ``__len__``, and ``__getitem__``:

.. code-block:: python


    class ListArray(Content):
        def __init__(self, starts, stops, content):
            assert isinstance(starts, (Index32, IndexU32, Index64))
            assert isinstance(stops, type(starts))
            assert isinstance(content, Content)
            assert len(stops) >= len(starts)  # usually equal
            for i in range(len(starts)):
                start = starts[i]
                stop = stops[i]
                if start != stop:
                    assert start < stop  # i.e. start <= stop
                    assert start >= 0
                    assert stop <= len(content)
            self.starts = starts
            self.stops = stops
            self.content = content

        def __len__(self):
            return len(self.starts)

        def __getitem__(self, where):
            if isinstance(where, int):
                if where < 0:
                    where += len(self)
                assert 0 <= where < len(self)
                return self.content[self.starts[where] : self.stops[where]]

            elif isinstance(where, slice) and where.step is None:
                starts = self.starts[where.start : where.stop]
                stops = self.stops[where.start : where.stop]
                return ListArray(starts, stops, self.content)

            elif isinstance(where, str):
                return ListArray(self.starts, self.stops, self.content[where])

            else:
                raise AssertionError(where)



.. _ak-contents-listarray-starts:

.. py:attribute:: ak.contents.ListArray.starts



.. _ak-contents-listarray-stops:

.. py:attribute:: ak.contents.ListArray.stops



.. _ak-contents-listarray-copy:

.. py:method:: ak.contents.ListArray.copy(self, starts=UNSET, stops=UNSET, content=UNSET, *, parameters=UNSET)



.. _ak-contents-listarray-__copy__:

.. py:method:: ak.contents.ListArray.__copy__(self)



.. _ak-contents-listarray-__deepcopy__:

.. py:method:: ak.contents.ListArray.__deepcopy__(self, memo)



.. _ak-contents-listarray-simplified:

.. py:method:: ak.contents.ListArray.simplified(cls, starts, stops, content, *, parameters=None)



.. _ak-contents-listarray-_form_with_key:

.. py:method:: ak.contents.ListArray._form_with_key(self, getkey)



.. _ak-contents-listarray-_form_with_key_path:

.. py:method:: ak.contents.ListArray._form_with_key_path(self, path)



.. _ak-contents-listarray-_to_buffers:

.. py:method:: ak.contents.ListArray._to_buffers(self, form, getkey, container, backend, byteorder)



.. _ak-contents-listarray-_to_typetracer:

.. py:method:: ak.contents.ListArray._to_typetracer(self, forget_length)



.. _ak-contents-listarray-_touch_data:

.. py:method:: ak.contents.ListArray._touch_data(self, recursive)



.. _ak-contents-listarray-_touch_shape:

.. py:method:: ak.contents.ListArray._touch_shape(self, recursive)



.. _ak-contents-listarray-length:

.. py:attribute:: ak.contents.ListArray.length



.. _ak-contents-listarray-__repr__:

.. py:method:: ak.contents.ListArray.__repr__(self)



.. _ak-contents-listarray-_repr:

.. py:method:: ak.contents.ListArray._repr(self, indent, pre, post)



.. _ak-contents-listarray-to_listoffsetarray64:

.. py:method:: ak.contents.ListArray.to_ListOffsetArray64(self, start_at_zero=False)



.. _ak-contents-listarray-to_regulararray:

.. py:method:: ak.contents.ListArray.to_RegularArray(self)



.. _ak-contents-listarray-_getitem_nothing:

.. py:method:: ak.contents.ListArray._getitem_nothing(self)



.. _ak-contents-listarray-_is_getitem_at_placeholder:

.. py:method:: ak.contents.ListArray._is_getitem_at_placeholder(self)



.. _ak-contents-listarray-_is_getitem_at_virtual:

.. py:method:: ak.contents.ListArray._is_getitem_at_virtual(self)



.. _ak-contents-listarray-_getitem_at:

.. py:method:: ak.contents.ListArray._getitem_at(self, where)



.. _ak-contents-listarray-_getitem_range:

.. py:method:: ak.contents.ListArray._getitem_range(self, start, stop)



.. _ak-contents-listarray-_getitem_field:

.. py:method:: ak.contents.ListArray._getitem_field(self, where, only_fields=())



.. _ak-contents-listarray-_getitem_fields:

.. py:method:: ak.contents.ListArray._getitem_fields(self, where, only_fields=())



.. _ak-contents-listarray-_carry:

.. py:method:: ak.contents.ListArray._carry(self, carry, allow_lazy)



.. _ak-contents-listarray-_compact_offsets64:

.. py:method:: ak.contents.ListArray._compact_offsets64(self, start_at_zero)



.. _ak-contents-listarray-_broadcast_tooffsets64:

.. py:method:: ak.contents.ListArray._broadcast_tooffsets64(self, offsets)



.. _ak-contents-listarray-_getitem_next_jagged:

.. py:method:: ak.contents.ListArray._getitem_next_jagged(self, slicestarts, slicestops, slicecontent, tail)



.. _ak-contents-listarray-_getitem_next:

.. py:method:: ak.contents.ListArray._getitem_next(self, head, tail, advanced)



.. _ak-contents-listarray-_offsets_and_flattened:

.. py:method:: ak.contents.ListArray._offsets_and_flattened(self, axis, depth)



.. _ak-contents-listarray-_mergeable_next:

.. py:method:: ak.contents.ListArray._mergeable_next(self, other, mergebool)



.. _ak-contents-listarray-_mergemany:

.. py:method:: ak.contents.ListArray._mergemany(self, others)



.. _ak-contents-listarray-_fill_none:

.. py:method:: ak.contents.ListArray._fill_none(self, value)



.. _ak-contents-listarray-_local_index:

.. py:method:: ak.contents.ListArray._local_index(self, axis, depth)



.. _ak-contents-listarray-_numbers_to_type:

.. py:method:: ak.contents.ListArray._numbers_to_type(self, name, including_unknown)



.. _ak-contents-listarray-_is_unique:

.. py:method:: ak.contents.ListArray._is_unique(self, negaxis, starts, parents, outlength)



.. _ak-contents-listarray-_unique:

.. py:method:: ak.contents.ListArray._unique(self, negaxis, starts, parents, outlength)



.. _ak-contents-listarray-_argsort_next:

.. py:method:: ak.contents.ListArray._argsort_next(self, negaxis, starts, shifts, parents, outlength, ascending, stable)



.. _ak-contents-listarray-_sort_next:

.. py:method:: ak.contents.ListArray._sort_next(self, negaxis, starts, parents, outlength, ascending, stable)



.. _ak-contents-listarray-_combinations:

.. py:method:: ak.contents.ListArray._combinations(self, n, replacement, recordlookup, parameters, axis, depth)



.. _ak-contents-listarray-_reduce_next:

.. py:method:: ak.contents.ListArray._reduce_next(self, reducer, negaxis, starts, shifts, parents, outlength, mask, keepdims, behavior)



.. _ak-contents-listarray-_validity_error:

.. py:method:: ak.contents.ListArray._validity_error(self, path)



.. _ak-contents-listarray-_nbytes_part:

.. py:method:: ak.contents.ListArray._nbytes_part(self)



.. _ak-contents-listarray-_pad_none:

.. py:method:: ak.contents.ListArray._pad_none(self, target, axis, depth, clip)



.. _ak-contents-listarray-_to_arrow:

.. py:method:: ak.contents.ListArray._to_arrow(self, pyarrow, mask_node, validbytes, length, options)



.. _ak-contents-listarray-_to_cudf:

.. py:method:: ak.contents.ListArray._to_cudf(self, cudf, mask, length)



.. _ak-contents-listarray-_to_backend_array:

.. py:method:: ak.contents.ListArray._to_backend_array(self, allow_missing, backend)



.. _ak-contents-listarray-_remove_structure:

.. py:method:: ak.contents.ListArray._remove_structure(self, backend, options)



.. _ak-contents-listarray-_drop_none:

.. py:method:: ak.contents.ListArray._drop_none(self)



.. _ak-contents-listarray-_rebuild_without_nones:

.. py:method:: ak.contents.ListArray._rebuild_without_nones(self, none_indexes, new_content)



.. _ak-contents-listarray-_recursively_apply:

.. py:method:: ak.contents.ListArray._recursively_apply(self, action, depth, depth_context, lateral_context, options)



.. _ak-contents-listarray-to_packed:

.. py:method:: ak.contents.ListArray.to_packed(self, recursive=True)



.. _ak-contents-listarray-_to_list:

.. py:method:: ak.contents.ListArray._to_list(self, behavior, json_conversions)



.. _ak-contents-listarray-_to_backend:

.. py:method:: ak.contents.ListArray._to_backend(self, backend)



.. _ak-contents-listarray-_materialize:

.. py:method:: ak.contents.ListArray._materialize(self)



.. _ak-contents-listarray-_is_all_materialized:

.. py:attribute:: ak.contents.ListArray._is_all_materialized



.. _ak-contents-listarray-_is_any_materialized:

.. py:attribute:: ak.contents.ListArray._is_any_materialized



.. _ak-contents-listarray-_is_equal_to:

.. py:method:: ak.contents.ListArray._is_equal_to(self, other, index_dtype, numpyarray, all_parameters)