Struct MapChunked 

pub struct MapChunked { /* private fields */ }

A Map backed by a List(Struct {key, value}) Series.

Storage safety contract

Every MapChunked must satisfy:

1. The storage dtype is the DataType::map_storage_dtype of a Map dtype that passes DataType::ensure_valid_map_dtype.
2. Child arrays are valid over their entire extent, including outside the list offsets: categorical codes in range for every non-null slot, no Object.
3. Entries and keys are non-null within the offset window of every non-null row of every chunk.

Map values are nullable. Everything a live row does not own – entries under null rows or outside the offsets – is unconstrained, as for any ListChunked. Flat accessors mask those entries and Arrow export drops them; repairs never clear entry or key validity, which would expose arbitrary payloads.

Canonical semantics

Validated ingestion (Self::try_from_storage, List(Struct) -> Map, from_any_values, Parquet) deduplicates keys within each row. Whole-row operations and value-only replacements preserve uniqueness; key-changing operations re-establish it. Arrow, IPC and FFI imports trust the producer and may contain duplicates. Uniqueness is never a safety requirement; callers that need it must canonicalize first.

Equality is entry-order-sensitive on the storage.

Implementations

impl MapChunked

pub unsafe fn from_storage_unchecked( dtype: DataType, storage: Series, ) -> MapChunked

Safety

storage must satisfy the MapChunked storage safety contract for dtype.

pub fn try_from_storage( dtype: DataType, storage: Series, ) -> Result<MapChunked, PolarsError>

Validate map storage and canonicalize duplicate keys.

Rejects null entries or keys that a live row owns. Duplicate keys keep their first position and last value.

pub fn name(&self) -> &PlSmallStr

pub fn rename(&mut self, name: PlSmallStr)

pub fn field(&self) -> Field

pub fn dtype(&self) -> &DataType

pub fn key_dtype(&self) -> &DataType

pub fn value_dtype(&self) -> &DataType

pub fn storage(&self) -> &Series

The raw List(Struct {key, value}) storage, including entries that no live row owns.

Entries and keys are non-null within the offset windows of live rows. Null rows and slicing can hide arbitrary entries, as they can for any ListChunked; Self::live_storage empties the null rows.

pub fn len(&self) -> usize

pub fn is_empty(&self) -> bool

pub fn any_value_iter(&self) -> impl PolarsIterator

One freshly-allocated AnyValue::Map per row.

pub fn get_any_value(&self, i: usize) -> Result<AnyValue<'_>, PolarsError>

pub unsafe fn get_any_value_unchecked(&self, i: usize) -> AnyValue<'_>

Safety

i must be in bounds.

pub fn keys(&self) -> Series

Keys of all entries in live rows, flattened in row order.

pub fn values(&self) -> Series

Values of all entries in live rows, flattened in row order.

pub fn live_row_lengths(&self) -> impl Iterator<Item = usize>

Entries each row contributes to Self::keys and Self::values, in row order.

A null row contributes none, whatever its offset window retains. Reads the offsets in place, so pairing this with a flat accessor never materializes the other field.

pub fn key_lists(&self) -> ChunkedArray<ListType>

One list of keys per row: List(key_dtype).

Preserves rows, validity and entry order; null rows have empty windows.

pub fn value_lists(&self) -> ChunkedArray<ListType>

One list of values per row: List(value_dtype).

Preserves rows, validity and entry order; null rows have empty windows.

pub fn with_values(&self, values: &Series) -> Result<MapChunked, PolarsError>

Replace live entry values.

Requires one value per live entry, in Self::values order, and a valid Map value dtype. This also applies to list-valued entries.

Preserves row count, validity, live keys and entry order. Drops entries that no live row owns and may rebase offsets.

pub fn entries(&self) -> Series

All entries in live rows, flattened in row order.

Excludes entries retained by null rows or sliced away.

pub fn live_storage(&self) -> Cow<'_, ChunkedArray<ListType>>

Storage with empty windows for null rows.

Preserves row count, validity and live entries. Borrows if no compaction is needed. Mutating the returned Cow affects only its owned copy.

pub fn cast_with_options( &self, dtype: &DataType, options: CastOptions, ) -> Result<Series, PolarsError>

Trait Implementations

impl Clone for MapChunked

fn clone(&self) -> MapChunked

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl IntoSeries for MapChunked

fn into_series(self) -> Series

fn is_series() -> bool