feat: Implement <expr>$item() (#1652)

Author: etiennebacher

DESCRIPTION

@@ -53,7 +53,7 @@ VignetteBuilder:
 Config/Needs/dev: devtools, lifecycle, readr, glue, RcppTOML, smvr
 Config/Needs/lint: fs, lintr
 Config/Needs/website: etiennebacher/altdoc, future.apply
-Config/polars/lib-version: 1.6.0-rc.1
+Config/polars/lib-version: 1.7.0-rc.1
 Config/testthat/edition: 3
 Config/testthat/parallel: true
 Config/testthat/start-first: lazyframe-frame, *-s3-base, polars_options,

NEWS.md

@@ -2,6 +2,10 @@
 
 ## polars (development version)
 
+### New features
+
+- `<expr>$item()` to strictly extract a single value from an expression (#1652).
+
 ## polars 1.6.0
 
 This is an update that corresponds to Python Polars 1.35.2.

R/000-wrappers.R

@@ -2136,6 +2136,12 @@ class(`PlRDataTypeExpr`) <- c("PlRDataTypeExpr__bundle", "savvy_polars__sealed")
   }
 }
 
+`PlRExpr_item` <- function(self) {
+  function(`allow_empty`) {
+    .savvy_wrap_PlRExpr(.Call(savvy_PlRExpr_item__impl, `self`, `allow_empty`))
+  }
+}
+
 `PlRExpr_kurtosis` <- function(self) {
   function(`fisher`, `bias`) {
     .savvy_wrap_PlRExpr(.Call(savvy_PlRExpr_kurtosis__impl, `self`, `fisher`, `bias`))
@@ -3586,6 +3592,7 @@ class(`PlRDataTypeExpr`) <- c("PlRDataTypeExpr__bundle", "savvy_polars__sealed")
   e$`is_not_null` <- `PlRExpr_is_not_null`(ptr)
   e$`is_null` <- `PlRExpr_is_null`(ptr)
   e$`is_unique` <- `PlRExpr_is_unique`(ptr)
+  e$`item` <- `PlRExpr_item`(ptr)
   e$`kurtosis` <- `PlRExpr_kurtosis`(ptr)
   e$`last` <- `PlRExpr_last`(ptr)
   e$`len` <- `PlRExpr_len`(ptr)

R/expr-expr.R

@@ -4787,3 +4787,38 @@ expr__is_close <- function(other, ..., abs_tol = 0, rel_tol = 1e-09, nans_equal
     self$`_rexpr`$is_close(as_polars_expr(other)$`_rexpr`, abs_tol, rel_tol, nans_equal)
   })
 }
+
+#' Get the single value
+#'
+#' This raises an error if there is not exactly one value.
+#'
+#' @inheritParams rlang::args_dots_empty
+#' @param allow_empty Allow having no values to return `null`.
+#'
+#' @seealso [$get()][expr__get] to get a single value by index.
+#' @inherit as_polars_expr return
+#' @examples
+#' # This function may be useful to force ourselves to handle cases where we
+#' # expect a single value but there are several. For example, we might expect
+#' # `$mode()` to return a single value...
+#' df <- pl$DataFrame(x = c("a", "a", "c"))
+#' df$select(
+#'   mode = pl$col("x")$mode()$item()
+#' )
+#'
+#' # ... but this is not always the case:
+#' df <- pl$DataFrame(x = c("a", "b", "c"))
+#' tryCatch(
+#'   {
+#'     df$select(
+#'       mode = pl$col("x")$mode()$item()
+#'     )
+#'   },
+#'   error = function(e) print(e)
+#' )
+expr__item <- function(..., allow_empty = FALSE) {
+  wrap({
+    check_dots_empty0(...)
+    self$`_rexpr`$item(allow_empty)
+  })
+}

altdoc/mkdocs.yml

@@ -331,6 +331,7 @@ nav:
             - is_not_null: man/expr__is_not_null.md
             - is_null: man/expr__is_null.md
             - is_unique: man/expr__is_unique.md
+            - item: man/expr__item.md
             - kurtosis: man/expr__kurtosis.md
             - last: man/expr__last.md
             - le: man/expr__le.md

man/expr__item.Rd

@@ -1579,6 +1579,11 @@ SEXP savvy_PlRExpr_is_unique__impl(SEXP self__) {
     return handle_result(res);
 }
 
+SEXP savvy_PlRExpr_item__impl(SEXP self__, SEXP c_arg__allow_empty) {
+    SEXP res = savvy_PlRExpr_item__ffi(self__, c_arg__allow_empty);
+    return handle_result(res);
+}
+
 SEXP savvy_PlRExpr_kurtosis__impl(SEXP self__, SEXP c_arg__fisher, SEXP c_arg__bias) {
     SEXP res = savvy_PlRExpr_kurtosis__ffi(self__, c_arg__fisher, c_arg__bias);
     return handle_result(res);
@@ -3695,6 +3700,7 @@ static const R_CallMethodDef CallEntries[] = {
     {"savvy_PlRExpr_is_not_null__impl", (DL_FUNC) &savvy_PlRExpr_is_not_null__impl, 1},
     {"savvy_PlRExpr_is_null__impl", (DL_FUNC) &savvy_PlRExpr_is_null__impl, 1},
     {"savvy_PlRExpr_is_unique__impl", (DL_FUNC) &savvy_PlRExpr_is_unique__impl, 1},
+    {"savvy_PlRExpr_item__impl", (DL_FUNC) &savvy_PlRExpr_item__impl, 2},
     {"savvy_PlRExpr_kurtosis__impl", (DL_FUNC) &savvy_PlRExpr_kurtosis__impl, 3},
     {"savvy_PlRExpr_last__impl", (DL_FUNC) &savvy_PlRExpr_last__impl, 1},
     {"savvy_PlRExpr_len__impl", (DL_FUNC) &savvy_PlRExpr_len__impl, 1},

src/init.c

@@ -1,6 +1,6 @@
 [package]
 name = "r-polars"
-version = "1.6.0-rc.1"
+version = "1.7.0-rc.1"
 edition = "2024"
 rust-version = "1.89.0"
 publish = false

src/rust/Cargo.lock

@@ -321,6 +321,7 @@ SEXP savvy_PlRExpr_is_not_nan__ffi(SEXP self__);
 SEXP savvy_PlRExpr_is_not_null__ffi(SEXP self__);
 SEXP savvy_PlRExpr_is_null__ffi(SEXP self__);
 SEXP savvy_PlRExpr_is_unique__ffi(SEXP self__);
+SEXP savvy_PlRExpr_item__ffi(SEXP self__, SEXP c_arg__allow_empty);
 SEXP savvy_PlRExpr_kurtosis__ffi(SEXP self__, SEXP c_arg__fisher, SEXP c_arg__bias);
 SEXP savvy_PlRExpr_last__ffi(SEXP self__);
 SEXP savvy_PlRExpr_len__ffi(SEXP self__);