diff --git a/polars/lazy/expr/list.ts b/polars/lazy/expr/list.ts index fc4486d7..39af8931 100644 --- a/polars/lazy/expr/list.ts +++ b/polars/lazy/expr/list.ts @@ -8,7 +8,6 @@ import { concatList } from "../functions"; * List functions for Lazy dataframes */ export interface ExprList extends ListFunctions {} -// export interface ListNamespace extends ListFunctions {} export const ExprListFunctions = (_expr: any): ExprList => { const wrap = (method, ...args: any[]): Expr => { @@ -43,17 +42,21 @@ export const ExprListFunctions = (_expr: any): ExprList => { return concatList(otherList); }, - contains(item) { - return wrap("listContains", exprToLitOrExpr(item)._expr, false); + contains(item, nullsEqual?: boolean) { + return wrap( + "listContains", + exprToLitOrExpr(item)._expr, + nullsEqual ?? true, + ); }, diff(n = 1, nullBehavior = "ignore") { return wrap("listDiff", n, nullBehavior); }, - get(index: number | Expr) { + get(index: number | Expr, nullOnOob?: boolean) { if (Expr.isExpr(index)) { - return wrap("listGet", index._expr, true); + return wrap("listGet", index._expr, nullOnOob ?? true); } - return wrap("listGet", pli.lit(index), true); + return wrap("listGet", pli.lit(index), nullOnOob ?? true); }, head(n = 5) { return this.slice(0, n); diff --git a/polars/series/list.ts b/polars/series/list.ts index 998841a9..4ed30f0b 100644 --- a/polars/series/list.ts +++ b/polars/series/list.ts @@ -2,8 +2,6 @@ import { col } from "../lazy/functions"; import type { ListFunctions } from "../shared_traits"; import { _Series, type Series } from "."; -// export type ListNamespace = ListFunctions; - /** * List functions for Series */ diff --git a/polars/shared_traits.ts b/polars/shared_traits.ts index 264359f0..ced2e804 100644 --- a/polars/shared_traits.ts +++ b/polars/shared_traits.ts @@ -511,7 +511,37 @@ export interface Bincode { * Functions that can be applied to dtype List */ export interface ListFunctions { + /** + * Retrieve the index of the minimal value in every sublist. + * @returns Expression of data type :class:`UInt32` or :class:`UInt64` + * @example + * -------- + * ``` + * const s0 = pl.Series("a", [[1, 2], [2, 1]]); + * s0.lst.argMax(); + * Series: 'a' [u32] + * [ + * 0 + * 1 + * ] + * ``` + */ argMin(): T; + /** + * Retrieve the index of the maximum value in every sublist. + * @returns Expression of data type :class:`UInt32` or :class:`UInt64` + * @example + * -------- + * ``` + * const s0 = pl.Series("a", [[1, 2], [2, 1]]); + * s0.lst.argMax(); + * Series: 'a' [u32] + * [ + * 1 + * 0 + * ] + * ``` + */ argMax(): T; /** * Concat the arrays in a Series dtype List in linear time. @@ -541,6 +571,7 @@ export interface ListFunctions { /** * Check if sublists contain the given item. * @param item Item that will be checked for membership + * @param nullBehavior - bool, default True If True, treat null as a distinct value. Null values will not propagate. * @example * -------- * ``` @@ -561,7 +592,7 @@ export interface ListFunctions { * ``` * @category List */ - contains(item: any): T; + contains(item: any, nullBehavior?: boolean): T; /** * Calculate the n-th discrete difference of every sublist. * @param n number of slots to shift @@ -582,22 +613,30 @@ export interface ListFunctions { diff(n?: number, nullBehavior?: "ignore" | "drop"): T; /** * Get the value by index in the sublists. - * So index `0` would return the first item of every sublist - * and index `-1` would return the last item of every sublist - * if an index is out of bounds, it will return a `null`. + * @param index - Index to return per sublist + * @param nullOnOob - Behavior if an index is out of bounds: + * True -> set as null + * False -> raise an error + * @example + * ------- + * ``` + * const s0 = pl.Series("a", [[1, 2], [2, 1]]); + * s0.lst.get(0); + * Series: 'a' [f64] + [ + 1.0 + 2.0 + ] + * ``` * @category List */ - get(index: number | Expr): T; + get(index: number | Expr, nullOnOob?: boolean): T; /** * Run any polars expression against the lists' elements * Parameters * ---------- * @param expr * Expression to run. Note that you can select an element with `pl.first()`, or `pl.col()` - * @param parallel - * Run all expression parallel. Don't activate this blindly. - * Parallelism is worth it if there is enough work to do per thread. - * This likely should not be use in the groupby context, because we already parallel execution per group * @example * >df = pl.DataFrame({"a": [1, 8, 3], "b": [4, 5, 2]}) * >df.withColumn( @@ -617,7 +656,7 @@ export interface ListFunctions { * └─────┴─────┴────────────┘ * @category List */ - eval(expr: Expr, parallel?: boolean): T; + eval(expr: Expr): T; /** * Get the first value of the sublists. * @category List @@ -797,7 +836,7 @@ export interface DateFunctions { */ second(): T; /** - * Format Date/datetime with a formatting rule: See [chrono strftime/strptime](https://docs.rs/chrono/0.4.19/chrono/format/strftime/index.html). + * Format Date/datetime with a formatting rule: See [chrono strftime/strptime](https://docs.rs/chrono/0.4.41/chrono/format/strftime/index.html). */ strftime(fmt: string): T; /** Return timestamp in ms as Int64 type. */