From d53ac86e544d7347443fe0c49ae3abcad301fc17 Mon Sep 17 00:00:00 2001 From: eitsupi <50911393+eitsupi@users.noreply.github.com> Date: Sun, 23 Jul 2023 11:50:35 +0900 Subject: [PATCH] release: Release 0.7.0 (#308) Co-authored-by: sorhawell Co-authored-by: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com> Co-authored-by: etiennebacher --- .Rbuildignore | 3 + CRAN-SUBMISSION | 3 + DESCRIPTION | 15 +- LICENSE | 2 +- LICENSE.md | 2 +- NEWS.md | 11 +- R/Field.R | 8 +- R/after-wrappers.R | 108 +++++-- R/autocompletion.R | 10 +- R/csv.R | 47 ++- R/dataframe__frame.R | 61 ++-- R/datatype.R | 23 +- R/docs.R | 1 + R/error__rpolarserr.R | 2 + R/error_conversion.R | 18 +- R/expr__binary.R | 1 + R/expr__datetime.R | 33 +++ R/expr__expr.R | 17 +- R/expr__string.R | 12 +- R/functions__eager.R | 2 +- R/functions__lazy.R | 2 + R/functions__whenthen.R | 6 + R/groupby.R | 21 +- R/lazyframe__background.R | 2 + R/lazyframe__groupby.R | 2 +- R/lazyframe__lazy.R | 13 +- R/options.R | 11 + R/pkg-knitr.R | 1 + R/rust_result.R | 3 +- R/s3_methods.R | 4 +- R/series__series.R | 11 +- R/utils.R | 33 ++- R/zzz.R | 9 +- README.Rmd | 50 +++- README.md | 62 ++-- cran-comments.md | 63 ++++ docs/docs/about.md | 7 +- inst/misc/develop_polars.R | 278 ++++++++++++++++++ inst/misc/examples/example.R | 77 ----- inst/misc/filter_rcmdcheck.R | 46 +-- man/DataFrame_class.Rd | 16 +- man/DataFrame_print.Rd | 17 -- man/DataFrame_reverse.Rd | 2 +- man/DataFrame_select.Rd | 5 + man/DataFrame_slice.Rd | 2 +- man/DataFrame_sort.Rd | 4 +- man/DataFrame_to_data_frame.Rd | 6 +- man/DataType_new.Rd | 31 -- man/ExprBin_starts_with.Rd | 3 + man/ExprStr_replace.Rd | 4 +- man/ExprStr_replace_all.Rd | 4 +- man/ExprStr_slice.Rd | 4 +- man/Expr_class.Rd | 3 + man/Expr_print.Rd | 4 + man/GroupBy_class.Rd | 12 + man/LazyFrame_class.Rd | 9 +- man/LazyFrame_describe_plan.Rd | 3 + man/LazyFrame_sort.Rd | 2 +- man/LazyGroupBy_print.Rd | 3 + man/Series_class.Rd | 8 +- man/as.character.Series.Rd | 8 +- man/as.list.Expr.Rd | 3 + man/cash-.pl_polars_env.Rd | 15 - man/cash-.private_polars_env.Rd | 15 - man/cash-set-.DataFrame.Rd | 60 ---- man/check_tz_to_result.Rd | 31 -- man/clone_env_one_level_deep.Rd | 51 ---- man/construct_ProtoExprArray.Rd | 21 -- man/docs_translations.Rd | 3 + man/dot-DollarNames.DataFrame.Rd | 5 + man/dot-DollarNames.Expr.Rd | 5 + man/dot-DollarNames.GroupBy.Rd | 3 + man/dot-DollarNames.LazyFrame.Rd | 3 + man/dot-DollarNames.PolarsBackgroundHandle.Rd | 3 + man/dot-DollarNames.RField.Rd | 22 ++ man/dot-DollarNames.RPolarsErr.Rd | 3 + man/dot-DollarNames.Series.Rd | 3 + man/dot-DollarNames.VecDataFrame.Rd | 3 + man/dot-DollarNames.When.Rd | 3 + man/dot-DollarNames.WhenThen.Rd | 3 + man/dot-DollarNames.WhenThenThen.Rd | 3 + man/dot-DollarNames.method_environment.Rd | 22 ++ man/dot-DollarNames.polars_option_list.Rd | 20 ++ man/dot-pr.Rd | 17 +- man/extendr_method_to_pure_functions.Rd | 23 -- man/extra_auto_completion.Rd | 3 + man/get_method_usages.Rd | 26 -- man/is_DataFrame_data_input.Rd | 21 -- man/is_polars_dtype.Rd | 21 -- man/is_schema.Rd | 5 +- man/knit_print.DataFrame.Rd | 3 + man/macro_add_syntax_check_to.Rd | 32 -- man/macro_new_subnamespace.Rd | 63 ---- man/method_as_property.Rd | 20 -- man/move_env_elements.Rd | 21 -- man/pcase.Rd | 33 --- man/pl_dtypes.Rd | 9 +- man/pl_pl.Rd | 16 +- man/pl_std.Rd | 3 + man/pl_var.Rd | 3 + man/{object.Rd => polars_class_object.Rd} | 20 +- man/polars_runtime_flags.Rd | 3 + ...aren-close-paren.Rd => print.DataFrame.Rd} | 3 +- man/print_env.Rd | 7 +- man/pstop.Rd | 24 -- man/result.Rd | 40 --- man/scan_csv.Rd | 10 +- man/show_all_public_functions.Rd | 12 + man/show_all_public_methods.Rd | 15 + man/str_string.Rd | 23 -- man/unwrap.Rd | 39 --- man/unwrap_err.Rd | 21 -- man/wrap_elist_result.Rd | 28 -- man/wrap_proto_schema.Rd | 27 -- src/rust/Cargo.toml | 3 +- tests/testthat/_snaps/info.md | 2 +- tests/testthat/test-csv.R | 11 +- tests/testthat/test-info.R | 4 + tests/testthat/test-minipolars_options.R | 2 +- vignettes/polars.Rmd | 9 +- 120 files changed, 1075 insertions(+), 1077 deletions(-) create mode 100644 CRAN-SUBMISSION create mode 100644 cran-comments.md create mode 100644 inst/misc/develop_polars.R delete mode 100644 inst/misc/examples/example.R delete mode 100644 man/DataFrame_print.Rd delete mode 100644 man/DataType_new.Rd delete mode 100644 man/cash-.pl_polars_env.Rd delete mode 100644 man/cash-.private_polars_env.Rd delete mode 100644 man/cash-set-.DataFrame.Rd delete mode 100644 man/check_tz_to_result.Rd delete mode 100644 man/clone_env_one_level_deep.Rd delete mode 100644 man/construct_ProtoExprArray.Rd create mode 100644 man/dot-DollarNames.RField.Rd create mode 100644 man/dot-DollarNames.method_environment.Rd create mode 100644 man/dot-DollarNames.polars_option_list.Rd delete mode 100644 man/extendr_method_to_pure_functions.Rd delete mode 100644 man/get_method_usages.Rd delete mode 100644 man/is_DataFrame_data_input.Rd delete mode 100644 man/is_polars_dtype.Rd delete mode 100644 man/macro_add_syntax_check_to.Rd delete mode 100644 man/macro_new_subnamespace.Rd delete mode 100644 man/method_as_property.Rd delete mode 100644 man/move_env_elements.Rd delete mode 100644 man/pcase.Rd rename man/{object.Rd => polars_class_object.Rd} (69%) rename man/{print-open-paren-close-paren.Rd => print.DataFrame.Rd} (92%) delete mode 100644 man/pstop.Rd delete mode 100644 man/result.Rd create mode 100644 man/show_all_public_functions.Rd create mode 100644 man/show_all_public_methods.Rd delete mode 100644 man/str_string.Rd delete mode 100644 man/unwrap.Rd delete mode 100644 man/unwrap_err.Rd delete mode 100644 man/wrap_elist_result.Rd delete mode 100644 man/wrap_proto_schema.Rd diff --git a/.Rbuildignore b/.Rbuildignore index db08b64f1..e9c9ca835 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -16,3 +16,6 @@ ^\.venv$ ^Makefile$ ^src/\.cargo$ +^cran-comments\.md$ +^CRAN-SUBMISSION$ +^\.devcontainer$ diff --git a/CRAN-SUBMISSION b/CRAN-SUBMISSION new file mode 100644 index 000000000..d8938ad64 --- /dev/null +++ b/CRAN-SUBMISSION @@ -0,0 +1,3 @@ +Version: 0.7.0 +Date: 2023-07-15 22:14:51 UTC +SHA: 8c2aec5466018d0c51dde9b14c1e6503590e0332 diff --git a/DESCRIPTION b/DESCRIPTION index 40fb51bfe..b6ad6a132 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,14 +1,17 @@ Package: polars -Title: 'Polars' Ported to R -Version: 0.6.1.9000 +Title: Lightning-Fast 'DataFrame' Library +Version: 0.7.0 Depends: R (>= 4.1.0) Imports: utils, codetools Authors@R: c(person("Ritchie", "Vink", , "ritchie46@gmail.com", role = c("aut")), - person("Soren", "Welling", , "sorhawell@gmail.com", role = c("aut","cre"))) -Description: 'Polars' is a lightning fast Data Frame library written in Rust. - This package allows converting R data to 'Polars' data and vice versa, - and enabling fast data processing with 'Polars'. + person("Soren", "Welling", , "sorhawell@gmail.com", role = c("aut")), + person("Tatsuya", "Shima", , "ts1s1andn@gmail.com", role = c("aut", "cre")), + person("Etienne", "Bacher", , "etienne.bacher@protonmail.com", role = c("ctb"))) +Description: Lightning-fast 'DataFrame' library written in 'Rust'. Convert R data + to 'Polars' data and vice versa. Perform fast, lazy, larger-than-memory and + optimized data queries. 'Polars' is interoperable with the package 'arrow', + as both are based on the 'Apache Arrow' Columnar Format. License: MIT + file LICENSE Language: en-US Encoding: UTF-8 diff --git a/LICENSE b/LICENSE index 18ea475ed..e8918b696 100644 --- a/LICENSE +++ b/LICENSE @@ -1,2 +1,2 @@ YEAR: 2023 -COPYRIGHT HOLDER: rpolars authors +COPYRIGHT HOLDER: polars authors (polars the R package) diff --git a/LICENSE.md b/LICENSE.md index 5793a6c6b..d853d9124 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,6 +1,6 @@ # MIT License -Copyright (c) 2023 rpolars authors +Copyright (c) 2023 polars authors (polars the R package) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/NEWS.md b/NEWS.md index 9b0884066..ce65daaa7 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,4 +1,4 @@ -# polars (development version) +# polars 0.7.0 ## BREAKING CHANGES @@ -6,7 +6,6 @@ is for consistency with the upstream Polars (#291, #293). - Bump rust-polars from 2023-04-20 unreleased version to version 0.30.0 released in 2023-05-30 (#289). - Rename `concat_lst` to `concat_list`. - - Rename `$str$explode` to `$str$str_explode`. - Remove `tz_aware` and `utc` arguments from `str_parse`. - in `$date_range`'s the `lazy` argument is now `TRUE` by default. @@ -38,7 +37,11 @@ for demonstration purposes (#240). - `$glimpse()` is a fast `str()`-like view of a `DataFrame` (#277). - `$over()` now accepts a vector of column names (#287). - New method `$describe()` (#268). -- Cross joining is now possible with `how = "cross"` in `$join()` +- Cross joining is now possible with `how = "cross"` in `$join()` (#310). +- Add license info of all rust crates to `LICENSE.note` (#309). +- With CRAN 0.7.0 release candidate (#308). + - New author accredited, SHIMA Tatsuya (@eitsupi). + - DESCRIPTION revised. # polars 0.6.1 @@ -139,7 +142,7 @@ Release date: 2023-02-21. Full Changelog: [v0.4.3...v0.4.5](https://github.com/p - Customize **extendr** to better support cross Rust-R/R-Rust error handling - bump extendr_api by @sorhawell in #44 - Str even more by @sorhawell in #47 -- **rpolars** is now available for install from [rpolars.r-universe.dev](https://rpolars.r-universe.dev/rpolars#install) @eitsupi +- **rpolars** is now available for install from [rpolars.r-universe.dev](https://rpolars.r-universe.dev/polars#install) @eitsupi - advertise R-universe by @sorhawell in #39 - Includes reasonably easy pre-compiled installation for arm64-MacBooks - All string Expressions available diff --git a/R/Field.R b/R/Field.R index fada061cf..e14e0084f 100644 --- a/R/Field.R +++ b/R/Field.R @@ -32,12 +32,18 @@ pl$Field = function(name, datatype) { #' @examples #' print(pl$Field("foo", pl$List(pl$UInt64))) print.RField = function(x, ...) { - cat("") x$print() invisible(x) } + +#' @title auto complete $-access into a polars object +#' @description called by the interactive R session internally +#' @param x string name of an RField +#' @param pattern code-stump as string to auto-complete #' @export +#' @inherit .DollarNames.DataFrame return +#' @keywords internal .DollarNames.RField = function(x, pattern = "") { get_method_usages(RField, pattern = pattern) } diff --git a/R/after-wrappers.R b/R/after-wrappers.R index 01bce4687..fc4895e1e 100644 --- a/R/after-wrappers.R +++ b/R/after-wrappers.R @@ -1,8 +1,18 @@ +## after-wrappers.R +## THIS FILE IS SOURCED IMMEDIATELY AFTER extendr-wrappers.R . THIS FILE EXTENDS THE BEHAVIOUR +## OF EXTENDR-CLASS-SYSTEM WITH: +## 1. SEPARATE PRIVATE (.pr$) AND PUBLIC (pl$) METHODS/FUNCTIONS +## 2. ADD INTERNAL PROFILER, pl$set_polars_options(debug_polars = TRUE) +## 3. ADD build_debug_print TO DEBUG CLASS CONSTRUCTION DURING PACKAGE BUILDTIME (rarely used) +## 4. ADD BETTER METHOD LOOKUP ERR MSGS macro_add_syntax_check_to_class(), HELPS END USER +## 5. ADD OPTION TO FLAG A METHOD TO BEHAVE LIKE A PROPERTY method_as_property() + + # Build time options build_debug_print = FALSE #' extendr methods into pure functions -#' +#' @noRd #' @param env environment object output from extendr-wrappers.R classes #' @param class_name optional class string, only used for debug printing #' Default NULL, will infer class_name automatically @@ -31,6 +41,7 @@ extendr_method_to_pure_functions = function(env, class_name = NULL) { #' get private method from Class #' @details This method if polars_optenv$debug_polars == TRUE will print what methods are called +#' @noRd #' @export #' @keywords internal "$.private_polars_env" = function(self, name) { @@ -50,15 +61,21 @@ extendr_method_to_pure_functions = function(env, class_name = NULL) { #' @title polars-API: private calls to rust-polars #' @description `.pr` #' Original extendr bindings converted into pure functions +#' @details +#' .pr gives access to all private methods of package polars. Use at own discretion. +#' The polars package may introduce breaking changes to any private method in a patch with no +#' deprecation warning. Most private methods takes `self` as a first argument, the object the +#' method should be called upon. #' @aliases .pr #' @keywords internal api_private +#' @return not applicable #' @export #' @examples #' # .pr$DataFrame$print() is an external function where self is passed as arg -#' polars:::.pr$DataFrame$print(self = pl$DataFrame(iris)) -#' @keywords internal -#' @examples -#' polars:::print_env(.pr, ".pr the collection of private method calls to rust-polars") +#' .pr$DataFrame$print(self = pl$DataFrame(iris)) +#' +#' # show all content of .pr +#' .pr$print_env(.pr, ".pr the collection of private method calls to rust-polars") .pr = new.env(parent = emptyenv()) .pr$Series = extendr_method_to_pure_functions(Series) .pr$DataFrame = extendr_method_to_pure_functions(DataFrame) @@ -78,17 +95,24 @@ extendr_method_to_pure_functions = function(env, class_name = NULL) { .pr$RNullValues = extendr_method_to_pure_functions(RNullValues) .pr$RPolarsErr = extendr_method_to_pure_functions(RPolarsErr) -# TODO remove export +# add package environment to .pr, this can be used as replacement for :::, where cran does not +# allow that. Ok use : +# - internal documentation (noRd) to show case inner workings of code. +# - unit tests, which needs to verify an internal state. +.pr$env = getNamespace("polars") +.pr$print_env = print_env -## this macro must be defined now -#' @title add syntax verification to class + +##### ----- MACROS used at package build time + +#' @title add syntax verification to a class #' @include utils.R #' @param Class_name string name of env class #' @rdname macro_add_syntax_check_to -#' +#' @noRd #' @keywords internal #' @return dollarsign method with syntax verification #' @@ -139,6 +163,7 @@ if (build_debug_print) cat("\n") #' Give a class method property behavior #' @description Internal function, see use in source +#' @noRd #' @param f a function #' @param setter bool, if true a property method can be modified by user #' @keywords internal @@ -165,29 +190,61 @@ method_as_property = function(f, setter = FALSE) { #' @keywords api #' @details If someone do not particularly like the letter combination `pl`, they are free to #' bind the environment to another variable name as `simon_says = pl` or even do `attach(pl)` -#' +#' @return not applicable #' @export #' @examples #' # how to use polars via `pl` #' pl$col("colname")$sum() / pl$lit(42L) # expression ~ chain-method / literal-expression #' -#' # pl inventory -#' polars:::print_env(pl, "polars public functions") -#' -#' # all accessible classes and their public methods -#' polars:::print_env( -#' polars:::pl_pub_class_env, -#' "polars public class methods, access via object$method()" -#' ) +#' # show all public functions, RPolarsDataTypes, classes and methods +#' pl$show_all_public_functions() +#' pl$show_all_public_methods() pl = new.env(parent = emptyenv()) - class(pl) = c("pl_polars_env", "environment") +#' show all public functions / objects +#' @name show_all_public_functions +#' @description print any object(function, RPolarsDataType) available via `pl$`. +#' @return NULL +#' @keywords functions +#' @examples +#' pl$show_all_public_functions() +pl$show_all_public_functions = function() { + print_env(pl, "polars public functions via pl$...") +} + +#' show all public methods +#' @name show_all_public_methods +#' @description methods are listed by their Class +#' @param class_names character vector of polars class names to show, Default NULL is all. +#' @return NULL +#' @keywords functions +#' @examples +#' pl$show_all_public_methods() +pl$show_all_public_methods = function(class_names = NULL) { + + #subset classes to show + show_this_env = if(!is.null(class_names)) { + as.environment(mget(class_names, envir = pl_pub_class_env)) + } else { + pl_pub_class_env + } + + print_env( + show_this_env, + paste( + paste(class_names, collapse = ", "), + "class methods, access via object$method()" + ) + ) +} #' get public function from pl namespace/env #' @details This method if polars_optenv$debug_polars == TRUE will print what methods are called +#' @return an element from the public namespace `pl` polars. Likely a function or an RPolarsDataType #' @export +#' @noRd #' @keywords internal "$.pl_polars_env" = function(self, name) { # print called private class in debug mode @@ -218,9 +275,9 @@ pl_pub_class_env = as.environment(mget(pl_class_names, envir = pl_pub_env)) #' @title Any polars class object is made of this +#' @name polars_class_object #' @description One SEXP of Rtype: "externalptr" + a class attribute #' @keywords api_object -#' #' @details #' - `object$method()` calls are facilitated by a `$.ClassName`- s3method see 'R/after-wrappers.R' #' - Code completion is facilitated by `.DollarNames.ClassName`-s3method see e.g. 'R/dataframe__frame.R' @@ -228,8 +285,15 @@ pl_pub_class_env = as.environment(mget(pl_class_names, envir = pl_pub_env)) #' See function macro_add_syntax_check_to_class(). #' #' @importFrom utils .DollarNames +#' @return not applicable #' @examples -#' # all a polars object is made of: +#' # all a polars object is only made of: #' some_polars_object = pl$DataFrame(iris) #' str(some_polars_object) # External Pointer tagged with a class attribute. -object = "place_holder" +#' +#' # All state is stored on rust side. +#' +#' # The single exception from the rule is class "GroupBy", where objects also have +#' # two private attributes "groupby_input" and "maintain_order". +#' str(pl$DataFrame(iris)$groupby("Species")) +NULL diff --git a/R/autocompletion.R b/R/autocompletion.R index cf4d31360..dac896a66 100644 --- a/R/autocompletion.R +++ b/R/autocompletion.R @@ -1,7 +1,7 @@ #' Extra polars auto completion #' @param activate bool default TRUE, enable chained auto-completion #' @name extra_auto_completion -#' @return NULL +#' @return invisible NULL #' #' @details polars always supports auto completion via .DollarNames. #' However chained methods like x$a()$b()$? are not supported vi .DollarNames. @@ -32,12 +32,14 @@ pl$extra_auto_completion = function(activate = TRUE) { rc.options("custom.completer" = NULL) # function running base auto complete. # It will dump suggestion into mutable .CompletionEnv$comps - utils:::.completeToken() + .completeToken = utils::getFromNamespace(".completeToken", "utils") + .completeToken() rc.options("custom.completer" = f) # get line buffer - CE = utils:::.CompletionEnv + .CompletionEnv = utils::getFromNamespace(".CompletionEnv", "utils") + CE = .CompletionEnv lb = CE$linebuffer # skip custom completion if token completion already yielded suggestions. @@ -51,7 +53,7 @@ pl$extra_auto_completion = function(activate = TRUE) { last_char = substr(lb, nchar(lb), nchar(lb)) if (last_char == "$" && nchar(lb) > 1L) { x = eval(parse(text = substr(lb, 1, nchar(lb) - 1))) - if (inherits(x, c(polars:::pl_class_names, "method_environment"))) { + if (inherits(x, c(pl_class_names, "method_environment"))) { your_comps = .DollarNames(x) # append your suggestions to the vanilla suggestions/completions CE$comps = c(your_comps, CE$comps) diff --git a/R/csv.R b/R/csv.R index 52a11968e..4f26c74a1 100644 --- a/R/csv.R +++ b/R/csv.R @@ -1,8 +1,11 @@ #' new LazyFrame from csv -#' @description will scan the csv when collect(), not now +#' @description will scan the csv when collect(), not now. +#' read_csv is a shortcut for scan_csv$collect(). +#' @name scan_csv +#' @details Read a file from path into a polars lazy frame. Not yet supporting eol_char and with_column_names #' @keywords LazyFrame_new #' -#' @param path string, Path to a file +#' @param path string, Path to a file or URL #' @param sep Single char to use as delimiter in the file. #' @param has_header bool, indicate if the first row of dataset is a header or not. #' If set to False, column names will be autogenerated in the following format: @@ -45,11 +48,7 @@ #' @param parse_dates bool Try to automatically parse dates. If this does not succeed, the column remains of data type pl.Utf8. #' @param reuse_downloaded Boolean. If `TRUE`(default) and a URL was provided, #' cache the downloaded files in session for an easy reuse. -#' @return lazyframe -#' -#' -#' @details Read a file from path into a polars lazy frame. Not yet supporting eol_char and with_column_names -#' @name scan_csv +#' @return scan_csv returns a LazyFrame. read_csv returns a DataFrame. #' @examples #' my_file = tempfile() #' write.csv(iris, my_file) @@ -64,7 +63,7 @@ pl$scan_csv = function( skip_rows = 0, n_rows = NULL, cache = FALSE, - overwrite_dtype = NULL, # polars:::DataTypeVector$new()$print() + overwrite_dtype = NULL, low_memory = FALSE, comment_char = NULL, quote_char = '"', @@ -80,7 +79,7 @@ pl$scan_csv = function( args = as.list(environment()) args[["reuse_downloaded"]] = NULL - path <- check_is_link(path, reuse_downloaded = reuse_downloaded) + path = check_is_link(path, reuse_downloaded = reuse_downloaded) args[["path"]] = path.expand(path) # overwrite_dtype: convert named list of DataType's to DataTypeVector obj @@ -140,15 +139,33 @@ pl$scan_csv = function( unwrap(do.call(rlazy_csv_reader, args)) } -#' Read csv to DataFrame +#' Shortcut for pl$scan_csv()$collect() #' @rdname scan_csv -#' @param ... any argument passed to scan_csv #' @return DataFrame #' @name read_csv -#' @examples -#' df = pl$read_csv("https://j.mp/iriscsv") -pl$read_csv = function(...) { - pl$scan_csv(...)$collect() +pl$read_csv = function( + path, + sep = ",", + has_header = TRUE, + ignore_errors = FALSE, + skip_rows = 0, + n_rows = NULL, + cache = FALSE, + overwrite_dtype = NULL, + low_memory = FALSE, + comment_char = NULL, + quote_char = '"', + null_values = NULL, + infer_schema_length = 100, + skip_rows_after_header = 0, + encoding = "utf8", + row_count_name = NULL, + row_count_offset = 0, + parse_dates = FALSE, + reuse_downloaded = TRUE) { + mc = match.call() + mc[[1]] = quote(pl$scan_csv) + eval.parent(mc)$collect() } diff --git a/R/dataframe__frame.R b/R/dataframe__frame.R index 9b4e67dbd..ff128a14d 100644 --- a/R/dataframe__frame.R +++ b/R/dataframe__frame.R @@ -11,7 +11,7 @@ #' This class system in lack of a better name could be called "environment classes" #' and is the same class system extendr provides, except here there is #' both a public and private set of methods. For implementation reasons, the private methods are -#' external and must be called from polars:::.pr.$DataFrame$methodname(), also all private methods +#' external and must be called from `.pr$DataFrame$methodname()`, also all private methods #' must take any self as an argument, thus they are pure functions. Having the private methods #' as pure functions solved/simplified self-referential complications. #' @@ -22,22 +22,24 @@ #' prefixed `DataFrame_`. #' #' @keywords DataFrame +#' @return not applicable #' @examples -#' # see all exported methods -#' ls(polars:::DataFrame) +#' # see all public exported method names (normally accessed via a class instance with $) +#' ls(.pr$env$DataFrame) #' #' # see all private methods (not intended for regular use) -#' ls(polars:::.pr$DataFrame) +#' ls(.pr$DataFrame) #' #' #' # make an object #' df = pl$DataFrame(iris) #' +#' #' # use a public method/property #' df$shape #' df2 = df #' # use a private method, which has mutability -#' result = polars:::.pr$DataFrame$set_column_from_robj(df, 150:1, "some_ints") +#' result = .pr$DataFrame$set_column_from_robj(df, 150:1, "some_ints") #' #' # column exists in both dataframes-objects now, as they are just pointers to the same object #' # there are no public methods with mutability @@ -55,7 +57,7 @@ #' # method does not return any ok-value. #' #' # try unwrapping an error from polars due to unmatching column lengths -#' err_result = polars:::.pr$DataFrame$set_column_from_robj(df, 1:10000, "wrong_length") +#' err_result = .pr$DataFrame$set_column_from_robj(df, 1:10000, "wrong_length") #' tryCatch(unwrap(err_result, call = NULL), error = \(e) cat(as.character(e))) DataFrame @@ -67,7 +69,9 @@ DataFrame #' @description called by the interactive R session internally #' @param x DataFrame #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @return Doesn't return a value. This is used for autocompletion in RStudio. #' @keywords internal .DollarNames.DataFrame = function(x, pattern = "") { get_method_usages(DataFrame, pattern = pattern) @@ -78,7 +82,9 @@ DataFrame #' @description called by the interactive R session internally #' @param x VecDataFrame #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.VecDataFrame = function(x, pattern = "") { get_method_usages(VecDataFrame, pattern = pattern) @@ -261,8 +267,6 @@ pl$DataFrame = function(..., make_names_unique = TRUE, parallel = FALSE) { #' @param x DataFrame #' @param ... not used #' -#' @name print() -#' #' @return self #' @export #' @@ -273,8 +277,8 @@ print.DataFrame = function(x, ...) { } #' internal method print DataFrame -#' -#' +#' @noRd +#' @keywords internal #' @return self #' #' @examples pl$DataFrame(iris) @@ -286,15 +290,16 @@ DataFrame_print = function() { ## "Class methods" #' Validate data input for create Dataframe with pl$DataFrame -#' +#' @noRd #' @param x any R object to test if suitable as input to DataFrame -#' +#' @keywords internal #' @description The Dataframe constructors accepts data.frame inheritors or list of vectors and/or Series. #' #' @return bool #' -#' @examples polars:::is_DataFrame_data_input(iris) -#' polars:::is_DataFrame_data_input(list(1:5, pl$Series(1:5), letters[1:5])) +#' @examples +#' .pr$env$is_DataFrame_data_input(iris) +#' .pr$env$is_DataFrame_data_input(list(1:5, pl$Series(1:5), letters[1:5])) is_DataFrame_data_input = function(x) { inherits(x, "data.frame") || is.list(x) || @@ -307,8 +312,10 @@ is_DataFrame_data_input = function(x) { ## internal bookkeeping of methods which should behave as properties DataFrame.property_setters = new.env(parent = emptyenv()) + + #' generic setter method -#' +#' @noRd #' @param self DataFrame #' @param name name method/property to set #' @param value value to insert @@ -323,8 +330,8 @@ DataFrame.property_setters = new.env(parent = emptyenv()) #' @export #' @examples #' # For internal use -#' # is only activated for following methods of DataFrame -#' ls(polars:::DataFrame.property_setters) +#' # show what methods of DataFrame have active property setters +#' with(.pr$env, ls(DataFrame.property_setters)) #' #' # specific use case for one object property 'columns' (names) #' df = pl$DataFrame(iris) @@ -350,10 +357,9 @@ DataFrame.property_setters = new.env(parent = emptyenv()) #' #' # for stable code prefer e.g. df$columns = letters[5:1] #' -#' # to see inside code of a property use the [[]] syntax instead +#' # to verify inside code of a property, use the [[]] syntax instead. #' df[["columns"]] # to see property code, .pr is the internal polars api into rust polars -#' polars:::DataFrame.property_setters$columns # and even more obscure to see setter code -#' +#' DataFrame.property_setters$columns # and even more obscure to see setter code "$<-.DataFrame" = function(self, name, value) { name = sub("<-$", "", name) @@ -658,7 +664,7 @@ DataFrame_to_series = function(idx = 0) { #' @description sort a DataFrame by on or more Expr. #' #' @param by Column(s) to sort by. Column name strings, character vector of -#' column names, or Iterable Into (e.g. one Expr, or list mixed Expr and +#' column names, or Iterable `Into` (e.g. one Expr, or list mixed Expr and #' column name strings). #' @param ... more columns to sort by as above but provided one Expr per argument. #' @param descending Sort descending? Default = FALSE logical vector of length 1 or same length @@ -668,7 +674,7 @@ DataFrame_to_series = function(idx = 0) { #' be converted into an Expr e.g. `$sort(list(e1,e2,e3))`, #' or provide each Expr as an individual argument `$sort(e1,e2,e3)`ยด ... or both. #' -#' @return LazyFrame +#' @return DataFrame #' @keywords DataFrame #' @examples #' df = mtcars @@ -701,7 +707,9 @@ DataFrame_sort = function( #' (e.g `list(pl$col("a"))`). #' #' @aliases select +#' @return DataFrame #' @keywords DataFrame +#' @return DataFrame #' @examples #' pl$DataFrame(iris)$select( #' pl$col("Sepal.Length")$abs()$alias("abs_SL"), @@ -901,11 +909,11 @@ DataFrame_groupby = function(..., maintain_order = pl$options$default_maintain_o -#' return polars DataFrame as R data.frame +#' Return Polars DataFrame as R data.frame #' #' @param ... any args pased to as.data.frame() #' -#' @return data.frame +#' @return An R data.frame #' @keywords DataFrame #' @examples #' df = pl$DataFrame(iris[1:3, ]) @@ -925,6 +933,7 @@ DataFrame_to_data_frame = function(...) { } #' Alias for to_data_frame (backward compatibility) +#' @return An R data.frame #' @noRd DataFrame_as_data_frame = DataFrame_to_data_frame @@ -1136,7 +1145,7 @@ DataFrame_quantile = function(quantile, interpolation = "nearest") { #' @title Reverse #' @description Reverse the DataFrame. #' @keywords LazyFrame -#' @return LazyFrame +#' @return DataFrame #' @examples pl$DataFrame(mtcars)$reverse() DataFrame_reverse = function() { self$lazy()$reverse()$collect() @@ -1174,7 +1183,7 @@ DataFrame_fill_null = function(fill_value) { #' @title Slice #' @description Get a slice of this DataFrame. #' @keywords LazyFrame -#' @return LazyFrame +#' @return DataFrame #' @param offset integer #' @param length integer or NULL #' @examples diff --git a/R/datatype.R b/R/datatype.R index 4622c36cb..0dda37b59 100644 --- a/R/datatype.R +++ b/R/datatype.R @@ -3,11 +3,10 @@ #' @param x object to test if schema #' @return bool #' @format function +#' @keywords functions #' @examples -#' polars:::is_schema(pl$DataFrame(iris)$schema) #' pl$is_schema(pl$DataFrame(iris)$schema) -#' polars:::is_schema(list("alice", "bob")) -#' +#' pl$is_schema(list("alice", "bob")) is_schema = \(x) { is.list(x) && !is.null(names(x)) && !anyNA(names(x)) && do.call(all, lapply(x, inherits, "RPolarsDataType")) @@ -16,6 +15,7 @@ pl$is_schema = is_schema #' wrap proto schema +#' @noRd #' @name wrap_proto_schema #' @param x either schema, or incomplete schema where dataType can be NULL #' or schema is just char vec, implicitly the same as if all DataType are NULL, @@ -24,8 +24,8 @@ pl$is_schema = is_schema #' @format function #' @keywords internal #' @examples -#' polars:::wrap_proto_schema(c("alice", "bob")) -#' polars:::wrap_proto_schema(list("alice" = pl$Int64, "bob" = NULL)) +#' .pr$env$wrap_proto_schema(c("alice", "bob")) +#' .pr$env$wrap_proto_schema(list("alice" = pl$Int64, "bob" = NULL)) wrap_proto_schema = function(x) { pcase( is.list(x) && !is.null(names(x)), @@ -43,10 +43,11 @@ wrap_proto_schema = function(x) { -#' @title DataTypes polars types +#' @title DataTypes (RPolarsDataType) #' #' @name pl_dtypes #' @description `DataType` any polars type (ported so far) +#' @return not applicable #' @examples #' print(ls(pl$dtypes)) #' pl$dtypes$Float64 @@ -56,10 +57,6 @@ wrap_proto_schema = function(x) { #' #' pl$Struct(pl$Field("CityNames", pl$Utf8)) #' -#' # Some DataType use case, this user function fails because.... -#' \dontrun{ -#' pl$Series(1:4)$apply(\(x) letters[x]) -#' } #' # The function changes type from Integer(Int32)[Integers] to char(Utf8)[Strings] #' # specifying the output DataType: Utf8 solves the problem #' pl$Series(1:4)$apply(\(x) letters[x], datatype = pl$dtypes$Utf8) @@ -94,10 +91,11 @@ print.RPolarsDataType = function(x, ...) { #' check if x is a valid RPolarsDataType #' @name is_polars_dtype +#' @noRd #' @param x a candidate #' @keywords internal #' @return a list DataType with an inner DataType -#' @examples polars:::is_polars_dtype(pl$Int64) +#' @examples .pr$env$is_polars_dtype(pl$Int64) is_polars_dtype = function(x, include_unknown = FALSE) { inherits(x, "RPolarsDataType") && (x != pl$Unknown || include_unknown) } @@ -121,6 +119,7 @@ pl$same_outer_dt = function(lhs, rhs) { #' DataType_new (simple DataType's) +#' @noRd #' @description Create a new flag like DataType #' @param str name of DataType to create #' @keywords internal @@ -136,7 +135,7 @@ pl$same_outer_dt = function(lhs, rhs) { #' #' @return DataType #' @examples -#' polars:::DataType_new("Int64") +#' .pr$env$DataType_new("Int64") DataType_new = function(str) { .pr$DataType$new(str) } diff --git a/R/docs.R b/R/docs.R index cc6ef370d..1711ed958 100644 --- a/R/docs.R +++ b/R/docs.R @@ -3,6 +3,7 @@ #' @name docs_translations #' @aliases docs_translations #' @format info +#' @return Not applicable #' @description #' #' #Comments for how the R and python world translates into polars: diff --git a/R/error__rpolarserr.R b/R/error__rpolarserr.R index ad48664fb..24bd4d729 100644 --- a/R/error__rpolarserr.R +++ b/R/error__rpolarserr.R @@ -2,7 +2,9 @@ #' @description called by the interactive R session internally #' @param x RPolarsErr #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.RPolarsErr = function(x, pattern = "") { get_method_usages(RPolarsErr, pattern = pattern) diff --git a/R/error_conversion.R b/R/error_conversion.R index 598bb6a98..ee7bd383b 100644 --- a/R/error_conversion.R +++ b/R/error_conversion.R @@ -4,7 +4,7 @@ # a simpler unwrap without where_in and when_calling should be defined in rust_result.R #' rust-like unwrapping of result. Useful to keep error handling on the R side. -#' +#' @noRd #' @param result a list here either element ok or err is NULL, or both if ok is litteral NULL #' @param call context of error or string #' @param context a msg to prefix a raised error with @@ -13,8 +13,8 @@ #' @keywords internal #' @examples #' -#' # get unwrap without using ::: -#' unwrap = environment(polars::pl$all)$unwrap +#' # fetch internal unwrap-function +#' unwrap = .pr$env$unwrap #' #' structure(list(ok = "foo", err = NULL), class = "extendr_result") #' @@ -40,6 +40,7 @@ unwrap = function(result, context = NULL, call = sys.call(1L)) { } #' rust-like unwrap_err, internal use only +#' @noRd #' @details #' throwed error info is sparse because only for internal errors #' @keywords internal @@ -55,17 +56,18 @@ unwrap_err = function(result) { #' Capture any R error and return a rust-like Result +#' @noRd #' @param expr code to capture any error from and wrap as Result #' @param msg handy way to add a context msg #' @keywords internal #' @return Result #' @examples #' -#' # user internal functions without using ::: -#' result = environment(polars::pl$all)$result -#' unwrap_err = environment(polars::pl$all)$unwrap_err -#' unwrap = environment(polars::pl$all)$unwrap -#' Err = environment(polars::pl$all)$Err +#' # get user internal functions +#' result = .pr$env$result +#' unwrap_err = .pr$env$unwrap_err +#' unwrap = .pr$env$unwrap +#' Err = .pr$env$Err #' #' # capture regular R errors or RPolarsErr #' throw_simpleError = \() stop("Imma simple error") diff --git a/R/expr__binary.R b/R/expr__binary.R index 2d9dffd91..47192b56a 100644 --- a/R/expr__binary.R +++ b/R/expr__binary.R @@ -22,6 +22,7 @@ ExprBin_contains = function(lit) { #' @description Check if values starts with a binary substring. #' @keywords ExprBin #' @param sub Prefix substring. +#' @return Expr returing a Boolean ExprBin_starts_with = function(sub) { unwrap(.pr$Expr$bin_starts_with(self, sub)) } diff --git a/R/expr__datetime.R b/R/expr__datetime.R index 0385bc913..f70a69a3d 100644 --- a/R/expr__datetime.R +++ b/R/expr__datetime.R @@ -22,6 +22,7 @@ #' @return Date/Datetime expr #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$truncate #' @examples #' t1 = as.POSIXct("3040-01-01", tz = "GMT") @@ -74,6 +75,7 @@ ExprDT_truncate = function( #' @return Date/Datetime expr #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$round #' @examples #' t1 = as.POSIXct("3040-01-01", tz = "GMT") @@ -115,6 +117,7 @@ ExprDT_round = function(every, offset = NULL) { #' @return Date/Datetime expr #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$combine #' @examples #' # Using pl$PTime @@ -148,6 +151,7 @@ ExprDT_combine = function(tm, tu = "us") { #' @return Date/Datetime expr #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$strftime #' @examples #' pl$lit(as.POSIXct("2021-01-02 12:13:14", tz = "GMT"))$dt$strftime("this is the year: %Y")$to_r() @@ -166,6 +170,7 @@ ExprDT_strftime = function(fmt) { #' @return Expr of Year as Int32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$year #' @examples #' df = pl$DataFrame( @@ -197,6 +202,7 @@ ExprDT_year = function() { #' @return Expr of iso_year as Int32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$iso_year #' @examples #' df = pl$DataFrame( @@ -226,6 +232,7 @@ ExprDT_iso_year = function() { #' @return Expr of quarter as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$quarter #' @examples #' df = pl$DataFrame( @@ -254,6 +261,7 @@ ExprDT_quarter = function() { #' @return Expr of month as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dtmonth #' @examples #' df = pl$DataFrame( @@ -283,6 +291,7 @@ ExprDT_month = function() { #' @return Expr of week as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$week #' @examples #' df = pl$DataFrame( @@ -310,6 +319,7 @@ ExprDT_week = function() { #' @return Expr of weekday as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$weekday #' @examples #' df = pl$DataFrame( @@ -339,6 +349,7 @@ ExprDT_weekday = function() { #' @return Expr of day as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$day #' @examples #' df = pl$DataFrame( @@ -367,6 +378,7 @@ ExprDT_day = function() { #' @return Expr of ordinal_day as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$ordinal_day #' @examples #' df = pl$DataFrame( @@ -395,6 +407,7 @@ ExprDT_ordinal_day = function() { #' @return Expr of hour as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$hour #' @examples #' df = pl$DataFrame( @@ -422,6 +435,7 @@ ExprDT_hour = function() { #' @return Expr of minute as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$minute #' @examples #' df = pl$DataFrame( @@ -451,6 +465,7 @@ ExprDT_minute = function() { #' @return Expr of second as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$second #' @examples #' pl$DataFrame(date = pl$date_range( @@ -480,6 +495,7 @@ ExprDT_second = function(fractional = FALSE) { #' @return Expr of millisecond as Int64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$millisecond #' @examples #' pl$DataFrame(date = pl$date_range( @@ -504,6 +520,7 @@ ExprDT_millisecond = function() { #' @return Expr of microsecond as Int64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$microsecond #' @examples #' pl$DataFrame( @@ -535,6 +552,7 @@ ExprDT_microsecond = function() { #' @return Expr of second as Int64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$nanosecond #' @examples #' pl$DataFrame(date = pl$date_range( @@ -563,6 +581,7 @@ ExprDT_nanosecond = function() { #' @return Expr of epoch as UInt32 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$epoch #' @examples #' pl$date_range(as.Date("2022-1-1"), lazy = TRUE)$dt$epoch("ns")$lit_to_s() @@ -596,6 +615,7 @@ ExprDT_epoch = function(tu = c("us", "ns", "ms", "s", "d")) { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$timestamp #' @examples #' df = pl$DataFrame( @@ -627,6 +647,7 @@ ExprDT_timestamp = function(tu = c("ns", "us", "ms")) { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$with_time_unit #' @examples #' df = pl$DataFrame( @@ -659,6 +680,7 @@ ExprDT_with_time_unit = function(tu = c("ns", "us", "ms")) { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$cast_time_unit #' @examples #' df = pl$DataFrame( @@ -689,6 +711,7 @@ ExprDT_cast_time_unit = function(tu = c("ns", "us", "ms")) { #' @keywords ExprDT #' @details corresponds to in R manually modifying the tzone attribute of POSIXt objects #' @format function +#' @usage NULL #' @aliases (Expr)$dt$convert_time_zone #' @examples #' df = pl$DataFrame( @@ -731,6 +754,7 @@ ExprDT_convert_time_zone = function(tz) { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$replace_time_zone #' @examples #' df_1 = pl$DataFrame(x = as.POSIXct("2009-08-07 00:00:01", tz = "America/New_York")) @@ -773,6 +797,7 @@ ExprDT_replace_time_zone = function(tz, use_earliest = NULL) { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$tz_localize #' @examples #' df = pl$DataFrame( @@ -819,6 +844,7 @@ ExprDT_tz_localize = function(tz) { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$days #' @examples #' df = pl$DataFrame( @@ -843,6 +869,7 @@ ExprDT_days = function() { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$hours #' @examples #' df = pl$DataFrame( @@ -867,6 +894,7 @@ ExprDT_hours = function() { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$minutes #' @examples #' df = pl$DataFrame( @@ -892,6 +920,7 @@ ExprDT_minutes = function() { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$seconds #' @examples #' df = pl$DataFrame(date = pl$date_range( @@ -914,6 +943,7 @@ ExprDT_seconds = function() { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$milliseconds #' @examples #' df = pl$DataFrame(date = pl$date_range( @@ -936,6 +966,7 @@ ExprDT_milliseconds = function() { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$microseconds #' @examples #' df = pl$DataFrame(date = pl$date_range( @@ -958,6 +989,7 @@ ExprDT_microseconds = function() { #' @return Expr of i64 #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$nanoseconds #' @examples #' df = pl$DataFrame(date = pl$date_range( @@ -1005,6 +1037,7 @@ ExprDT_nanoseconds = function() { #' @return Date/Datetime expr #' @keywords ExprDT #' @format function +#' @usage NULL #' @aliases (Expr)$dt$offset_by #' @examples #' df = pl$DataFrame( diff --git a/R/expr__expr.R b/R/expr__expr.R index 7a3a7410a..c41f906b6 100644 --- a/R/expr__expr.R +++ b/R/expr__expr.R @@ -1,6 +1,7 @@ #' @title Polars Expressions #' #' @name Expr_class +#' @return not applicable #' @description Expressions are all the functions and methods that are applicable #' to a Polars DataFrame. They can be split into the following categories (following #' the [Py-Polars classification](https://pola-rs.github.io/polars/py-polars/html/reference/expressions/)): @@ -39,6 +40,9 @@ print.Expr = function(x, ...) { #' internal method print Expr #' @name Expr_print #' @keywords Expr +#' @examples +#' pl$col("some_column")$sum()$over("some_other_column")$print() +#' @return invisible self #' @examples pl$DataFrame(iris) Expr_print = function() { .pr$Expr$print(self) @@ -49,6 +53,7 @@ Expr_print = function() { #' @description called by the interactive R session internally #' @param x Expr #' @param pattern code-stump as string to auto-complete +#' @inherit .DollarNames.DataFrame return #' @export #' @keywords internal .DollarNames.Expr = function(x, pattern = "") { @@ -59,6 +64,7 @@ Expr_print = function() { #' @description wraps an Expr in a list #' @param x Expr #' @param ... not used +#' @return One Expr wrapped in a list #' @export #' @keywords Expr as.list.Expr = function(x, ...) { @@ -121,17 +127,18 @@ wrap_e_result = function(e, str_to_lit = TRUE, argname = NULL) { } #' internal wrap_elist_result +#' @noRd #' @description make sure all elements of a list is wrapped as Expr #' DEPRECATED: prefer robj_to!(VecPlExpr) on rust side #' Capture any conversion error in the result -#' @param elist a list Expr or any R object Into (passable to pl$lit) +#' @param elist a list Expr or any R object `Into` (passable to pl$lit) #' @details #' Used internally to ensure an object is a list of expression #' The output is wrapped in a result, which can contain an ok or #' err value. #' @keywords internal #' @return Expr -#' @examples polars:::wrap_elist_result(list(pl$lit(42), 42, 1:3)) +#' @examples .pr$env$wrap_elist_result(list(pl$lit(42), 42, 1:3)) wrap_elist_result = function(elist, str_to_lit = TRUE) { element_i = 0L result( @@ -563,7 +570,7 @@ Expr_is_not_null = "use_extendr_wrapper" # TODO move this function in to rust with input list of args # TODO deprecate context feature #' construct proto Expr array from args -#' +#' @noRd #' @param ... any Expr or string #' #' @@ -571,7 +578,7 @@ Expr_is_not_null = "use_extendr_wrapper" #' #' @return ProtoExprArray object #' -#' @examples polars:::construct_ProtoExprArray(pl$col("Species"), "Sepal.Width") +#' @examples .pr$env$construct_ProtoExprArray(pl$col("Species"), "Sepal.Width") construct_ProtoExprArray = function(...) { pra = ProtoExprArray$new() args = list2(...) @@ -3826,7 +3833,7 @@ prepare_alpha = function( #' average of `[` \eqn{x_0}, None, \eqn{x_2}`]` are #' \eqn{1-\alpha} and \eqn{1} if `adjust=TRUE`, #' and \eqn{1-\alpha} and \eqn{\alpha} if `adjust=FALSE`. -#' @return Expr +#' @return Expr #' @aliases ewm_mean #' @format NULL #' @keywords Expr diff --git a/R/expr__string.R b/R/expr__string.R index a03d69c6b..d7b4acb3a 100644 --- a/R/expr__string.R +++ b/R/expr__string.R @@ -633,8 +633,8 @@ ExprStr_splitn = function(by, n) { #' @description #' Replace first matching regex/literal substring with a new string value. #' @keywords ExprStr -#' @param pattern Into, regex pattern -#' @param value Into replacement +#' @param pattern `Into`, regex pattern +#' @param value `Into` replacement #' @param literal bool, Treat pattern as a literal string. #' #' @return Expr of Utf8 Series @@ -659,8 +659,8 @@ ExprStr_replace = function(pattern, value, literal = FALSE) { #' @description #' Replace all matching regex/literal substrings with a new string value. #' @keywords ExprStr -#' @param pattern Into, regex pattern -#' @param value Into replacement +#' @param pattern `Into`, regex pattern +#' @param value `Into` replacement #' @param literal bool, treat pattern as a literal string. #' #' @return Expr of Utf8 Series @@ -684,8 +684,8 @@ ExprStr_replace_all = function(pattern, value, literal = FALSE) { #' @description #' Create subslices of the string values of a Utf8 Series. #' @keywords ExprStr -#' @param pattern Into, regex pattern -#' @param value Into replacement +#' @param pattern `Into`, regex pattern +#' @param value `Into` replacement #' @param literal bool, treat pattern as a literal string. #' #' @return Expr: Series of dtype Utf8. diff --git a/R/functions__eager.R b/R/functions__eager.R index b0e88479d..7c7e2c5ae 100644 --- a/R/functions__eager.R +++ b/R/functions__eager.R @@ -165,7 +165,7 @@ pl$date_range = function( high = time_to_value_unit_tz(high, time_unit, time_zone) # eager date_range, create in ms precision and cast to desired precision - dt_series = unwrap(polars:::r_date_range( + dt_series = unwrap(r_date_range( start = convert_time_unit(low, "ms"), stop = convert_time_unit(high, "ms"), every = interval, diff --git a/R/functions__lazy.R b/R/functions__lazy.R index 1bb8d7759..c8014078b 100644 --- a/R/functions__lazy.R +++ b/R/functions__lazy.R @@ -675,6 +675,7 @@ pl$coalesce = function(...) { #' Standard deviation #' @description syntactic sugar for starting a expression with std #' @param ddof integer Delta Degrees of Freedom: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1. +#' @return Expr or Series matching type of input column #' @name pl_std pl$std = function(column, ddof = 1) { if (inherits(column, "Series") || inherits(column, "Expr")) { @@ -693,6 +694,7 @@ pl$std = function(column, ddof = 1) { #' Variance #' @description syntactic sugar for starting a expression with var #' @param ddof integer Delta Degrees of Freedom: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1. +#' @return Expr or Series matching type of input column #' @name pl_var pl$var = function(column, ddof = 1) { if (inherits(column, "Series") || inherits(column, "Expr")) { diff --git a/R/functions__whenthen.R b/R/functions__whenthen.R index 17f202b6b..e4148bc87 100644 --- a/R/functions__whenthen.R +++ b/R/functions__whenthen.R @@ -130,7 +130,9 @@ print.WhenThenThen = function(x, ...) { #' @description called by the interactive R session internally #' @param x When #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.When = function(x, pattern = "") { paste0(ls(When, pattern = pattern), "()") @@ -140,7 +142,9 @@ print.WhenThenThen = function(x, ...) { #' @description called by the interactive R session internally #' @param x WhenThen #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.WhenThen = function(x, pattern = "") { paste0(ls(WhenThen, pattern = pattern), "()") @@ -150,7 +154,9 @@ print.WhenThenThen = function(x, ...) { #' @description called by the interactive R session internally #' @param x WhenThenThen #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.WhenThenThen = function(x, pattern = "") { paste0(ls(WhenThenThen, pattern = pattern), "()") diff --git a/R/groupby.R b/R/groupby.R index b3e3fb18e..889b12e8f 100644 --- a/R/groupby.R +++ b/R/groupby.R @@ -1,15 +1,17 @@ #' @title Operations on Polars grouped DataFrame +#' @return not applicable +#' @details The GroupBy class in R, is just another interface on top of the DataFrame(R wrapper class) in +#' rust polars. Groupby does not use the rust api for groupby+agg because the groupby-struct is a +#' reference to a DataFrame and that reference will share lifetime with its parent DataFrame. There +#' is no way to expose lifetime limited objects via extendr currently (might be quirky anyhow with R +#' GC). Instead the inputs for the groupby are just stored on R side, until also agg is called. +#' Which will end up in a self-owned DataFrame object and all is fine. groupby aggs are performed +#' via the rust polars LazyGroupBy methods, see DataFrame.groupby_agg method. #' #' @name GroupBy_class NULL -# The GroupBy class in R, is just another interface on top of the DataFrame(R wrapper class) in rust polars. -# Groupby does not use the rust api for groupby+agg because the groupby-struct is a reference to a DataFrame -# and that reference will share lifetime with its parent DataFrame. There is no way to expose lifetime -# limited objects via extendr currently (might be quirky anyhow with R GC). Instead the inputs for the groupby -# are just stored on R side, until also agg is called. Which will end up in a self-owned DataFrame object and -# all is fine. -# groupby aggs are performed via the rust polars LazyGroupBy methods, see DataFrame.groupby_agg method. + GroupBy = new.env(parent = emptyenv()) @@ -27,7 +29,9 @@ GroupBy = new.env(parent = emptyenv()) #' @description called by the interactive R session internally #' @param x GroupBy #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.GroupBy = function(x, pattern = "") { paste0(ls(GroupBy, pattern = pattern), "()") @@ -35,6 +39,8 @@ GroupBy = new.env(parent = emptyenv()) #' The internal GroupBy constructor +#' @keywords internal +#' @return The input as grouped DataFrame #' @noRd construct_groupby = function(df, groupby_input, maintain_order) { if (!inherits(df, "DataFrame")) stopf("internal error: construct_group called not on DataFrame") @@ -293,5 +299,6 @@ GroupBy_to_data_frame = function(...) { # TODO REMOVE_AT_BREAKING_CHANGE #' Alias to GroupBy_to_data_frame (backward compatibility) +#' @return R data.frame #' @noRd GroupBy_as_data_frame = GroupBy_to_data_frame diff --git a/R/lazyframe__background.R b/R/lazyframe__background.R index ac75aacf9..036b2c525 100644 --- a/R/lazyframe__background.R +++ b/R/lazyframe__background.R @@ -2,7 +2,9 @@ #' @description called by the interactive R session internally #' @param x LazyFrame #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.PolarsBackgroundHandle = function(x, pattern = "") { paste0(ls(PolarsBackgroundHandle, pattern = pattern), "()") diff --git a/R/lazyframe__groupby.R b/R/lazyframe__groupby.R index f68560e5f..3f2a74363 100644 --- a/R/lazyframe__groupby.R +++ b/R/lazyframe__groupby.R @@ -74,7 +74,7 @@ LazyGroupBy_tail = function(n = 1L) { #' @title LazyGroupBy_print #' @description #' prints opaque groupby, not much to show -#' @return NULL +#' @return invisible self LazyGroupBy_print = function() { .pr$LazyGroupBy$print(self) invisible(self) diff --git a/R/lazyframe__lazy.R b/R/lazyframe__lazy.R index e82f8466b..b877aac8b 100644 --- a/R/lazyframe__lazy.R +++ b/R/lazyframe__lazy.R @@ -14,7 +14,7 @@ #' "environment classes" and is the same class system extendr provides, except #' here there is both a public and private set of methods. For implementation #' reasons, the private methods are external and must be called from -#' `polars:::.pr.$LazyFrame$methodname()`. Also, all private methods must take +#' `.pr$LazyFrame$methodname()`. Also, all private methods must take #' any self as an argument, thus they are pure functions. Having the private methods #' as pure functions solved/simplified self-referential complications. #' @@ -33,14 +33,14 @@ #' pure external functions in after-wrappers.R. In zzz.R (named zzz to be last #' file sourced) the extendr-methods are removed and replaced by any function #' prefixed `LazyFrame_`. -#' +#' @return not applicable #' @keywords LazyFrame #' @examples #' # see all exported methods -#' ls(polars:::LazyFrame) +#' ls(.pr$env$LazyFrame) #' #' # see all private methods (not intended for regular use) -#' ls(polars:::.pr$LazyFrame) +#' ls(.pr$LazyFrame) #' #' #' ## Practical example ## @@ -103,7 +103,9 @@ LazyFrame #' @description called by the interactive R session internally #' @param x LazyFrame #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.LazyFrame = function(x, pattern = "") { paste0(ls(LazyFrame, pattern = pattern), "()") @@ -183,6 +185,7 @@ LazyFrame_print = "use_extendr_wrapper" #' that both plans are identical if `polars` doesn't find any way to optimize the #' query. #' @keywords LazyFrame +#' @return invisible NULL #' @examples #' my_file = tempfile() #' write.csv(iris, my_file) @@ -613,7 +616,7 @@ LazyFrame_join = function( #' @description sort a LazyFrame by on or more Expr #' #' @param by Column(s) to sort by. Column name strings, character vector of -#' column names, or Iterable Into (e.g. one Expr, or list mixed Expr and +#' column names, or Iterable `Into` (e.g. one Expr, or list mixed Expr and #' column name strings). #' @param ... more columns to sort by as above but provided one Expr per argument. #' @param descending Sort descending? Default = FALSE logical vector of length 1 or same length diff --git a/R/options.R b/R/options.R index 5184557e1..4f0814e07 100644 --- a/R/options.R +++ b/R/options.R @@ -158,7 +158,16 @@ pl$options = lapply(names(polars_optenv), \(name) { }) names(pl$options) = names(polars_optenv) class(pl$options) = c("polars_option_list", "list") + + +#' @title auto complete $-access into a polars object +#' @description called by the interactive R session internally +#' @param x string name of an option +#' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return +#' @keywords internal .DollarNames.polars_option_list = function(x, pattern = "") { with(x, ls(pattern = pattern)) } @@ -167,6 +176,7 @@ class(pl$options) = c("polars_option_list", "list") print("pl$options (polars_options, list-like with value validation):") print(pl$get_polars_options()) } + #' #' @export #' `as.list.polars_option_list` = function(x, ...) { #' pl$get_polars_options() @@ -279,6 +289,7 @@ pl$get_polars_opt_requirements = function() { #' internal keeping of state at runtime #' @name polars_runtime_flags #' @keywords internal +#' @return not applicable #' @description This environment is used internally for the package to remember #' what has been going on. Currently only used to throw one-time warnings() runtime_state = new.env(parent = emptyenv()) diff --git a/R/pkg-knitr.R b/R/pkg-knitr.R index ebdf34ce8..4799ad450 100644 --- a/R/pkg-knitr.R +++ b/R/pkg-knitr.R @@ -13,6 +13,7 @@ #' @name knit_print.DataFrame #' @param x a polars DataFrame to knit_print #' @param ... additional arguments, not used +#' @return invisible x or NULL #' @keywords DataFrame #' @export knit_print.DataFrame = function(x, ...) { diff --git a/R/rust_result.R b/R/rust_result.R index a640fe53e..6ee4ace4b 100644 --- a/R/rust_result.R +++ b/R/rust_result.R @@ -111,6 +111,7 @@ unwrap_or = function(x, or) { #' pstop +#' @noRd #' @description DEPRECATED USE stopf instead #' @param err error msg string #' @param call calling context @@ -119,7 +120,7 @@ unwrap_or = function(x, or) { #' @return throws an error #' #' @examples -#' f = function() polars:::pstop("this aint right!!") +#' f = function() .pr$env$pstop("this aint right!!") #' tryCatch(f(), error = \(e) as.character(e)) pstop = function(err, call = sys.call(1L)) { unwrap(list(ok = NULL, err = err), call = call) diff --git a/R/s3_methods.R b/R/s3_methods.R index b83eb1816..56cb8e830 100644 --- a/R/s3_methods.R +++ b/R/s3_methods.R @@ -196,10 +196,10 @@ as.vector.Series = function(x, mode) x$to_vector() #' as.character for polars Series #' @param x Series -#' @param str_length an integer. If specified, #' @param ... Additional arguments are ignored. +#' @param str_length an integer. If specified, #' utf8 or categorical type Series will be formatted to a string of this length. -#' @param ... Additional characters are ignored. +#' @return character vector #' @examples #' s = pl$Series(c("foo", "barbaz")) #' as.character(s) diff --git a/R/series__series.R b/R/series__series.R index d185a1260..5ad35b284 100644 --- a/R/series__series.R +++ b/R/series__series.R @@ -9,7 +9,7 @@ #' Most methods return another `Series`-class instance or similar which allows for method chaining. #' This class system in lack of a better name could be called "environment classes" and is the same class #' system extendr provides, except here there is both a public and private set of methods. For implementation -#' reasons, the private methods are external and must be called from polars:::.pr.$Series$methodname(), also +#' reasons, the private methods are external and must be called from `.pr$Series$methodname()`, also #' all private methods must take any self as an argument, thus they are pure functions. Having the private methods #' as pure functions solved/simplified self-referential complications. #' @@ -20,12 +20,10 @@ #' #' @keywords Series #' @examples -#' # see all exported methods -#' ls(polars:::Series) +#' pl$show_all_public_methods("Series") #' #' # see all private methods (not intended for regular use) -#' ls(polars:::.pr$Series) -#' +#' ls(.pr$Series) #' #' # make an object #' s = pl$Series(1:3) @@ -83,7 +81,9 @@ Series_print = function() { #' @description called by the interactive R session internally #' @param x Series #' @param pattern code-stump as string to auto-complete +#' @return char vec #' @export +#' @inherit .DollarNames.DataFrame return #' @keywords internal .DollarNames.Series = function(x, pattern = "") { get_method_usages(Series, pattern = pattern) @@ -365,6 +365,7 @@ Series_to_vector = \() { } #' Alias to Series_to_vector (backward compatibility) +#' @return R vector #' @noRd Series_to_r_vector = Series_to_vector diff --git a/R/utils.R b/R/utils.R index 76e1a222a..6a80e031c 100644 --- a/R/utils.R +++ b/R/utils.R @@ -83,6 +83,8 @@ verify_method_call = function(Class_env, Method_name, call = sys.call(1L), class #' list2 - one day like rlang #' list2 placeholder for future rust-impl #' @noRd +#' @keywords internal +#' @return An R list #' @details rlang has this wonderful list2 implemented in c/c++, that is agnostic about trailing #' commas in ... params. One day r-polars will have a list2-impl written in rust, which also allows #' trailing commas. @@ -111,7 +113,7 @@ unpack_list = function(...) { } #' Simple SQL CASE WHEN implementation for R -#' +#' @noRd #' @description Inspired by data.table::fcase + dplyr::case_when. #' Used instead of base::switch internally. #' @@ -125,7 +127,7 @@ unpack_list = function(...) { #' @keywords internal #' @examples #' n = 7 -#' polars:::pcase( +#' .pr$env$pcase( #' n < 5, "nope", #' n > 6, "yeah", #' or_else = stopf("failed to have a case for n=%s", n) @@ -144,13 +146,13 @@ pcase = function(..., or_else = NULL) { #' Move environment elements from one env to another -#' +#' @noRd #' @param from_env env from #' @param element_names names of elements to move, if named names, then name of name is to_env name #' @param remove bool, actually remove element in from_env #' @param to_env env to #' @keywords internal -#' @return NULL +#' @return invisble NULL #' move_env_elements = function(from_env, to_env, element_names, remove = TRUE) { names_from = element_names @@ -216,6 +218,7 @@ l_to_vdf = function(l) { #' @param env an R environment. #' @return shallow clone of R environment #' @keywords internal +#' @noRd #' @examples #' #' fruit_env = new.env(parent = emptyenv()) @@ -226,7 +229,7 @@ l_to_vdf = function(l) { #' env_1$fruit_env = fruit_env #' #' env_naive_copy = env_1 -#' env_shallow_clone = polars:::clone_env_one_level_deep(env_1) +#' env_shallow_clone = .pr$env$clone_env_one_level_deep(env_1) #' #' # modifying env_! #' env_1$minerals = new.env(parent = emptyenv()) @@ -333,7 +336,9 @@ construct_DataTypeVector = function(l) { #' @details used internally for auto completion in .DollarNames methods #' @return method usages #' @keywords internal -#' @examples polars:::get_method_usages(polars:::DataFrame, pattern = "col") +#' @noRd +#' @examples +#' .pr$env$get_method_usages(.pr$env$DataFrame, pattern = "col") get_method_usages = function(env, pattern = "") { found_names = ls(env, pattern = pattern) objects = mget(found_names, envir = env) @@ -363,8 +368,9 @@ get_method_usages = function(env, pattern = "") { suggestions } -#' print recursively an environment, used in some documentation +#' Print recursively an environment, used in some documentation #' @keywords internal +#' @return Print recursively an environment to the console #' @param api env #' @param name name of env #' @param max_depth numeric/int max levels to recursive iterate through @@ -382,6 +388,7 @@ print_env = function(api, name, max_depth = 10) { } for (name in ls(value)) { + if (name == "env") next() show_api(get(name, envir = as.environment(value)), name) } cat("\n") @@ -473,10 +480,11 @@ restruct_list = function(l) { #' to solve some tricky self-referential problem. If possible to deprecate a macro in a clean way #' , go ahead. #' @keywords internal +#' @noRd #' @examples #' #' # macro_new_subnamespace() is not exported, export for this toy example -#' # macro_new_subnamespace = polars:::macro_new_subnamespace +#' # macro_new_subnamespace = .pr$env$macro_new_subnamespace #' #' ## define some new methods prefixed 'MyClass_' #' # MyClass_add2 = function() self + 2 @@ -488,7 +496,7 @@ restruct_list = function(l) { #' # here adding sub-namespace as a expr-class property/method during session-time, #' # which only is for this demo. #' # instead sourced method like Expr_arr() at package build time instead -#' # env = polars:::Expr #get env of the Expr Class +#' # env = .pr$env$Expr #get env of the Expr Class #' # env$my_sub_ns = method_as_property(function() { #add a property/method #' # my_class_sub_ns(self) #' # }) @@ -542,9 +550,9 @@ macro_new_subnamespace = function(class_pattern, subclass_env = NULL, remove_f = #' @param collapse word to glue possible multilines with #' @keywords internal #' @return string -#' +#' @noRd #' @examples -#' polars:::str_string(list(a = 42, c(1, 2, 3, NA))) +#' str_string(list(a = 42, c(1, 2, 3, NA))) str_string = function(x, collapse = " ") { paste(capture.output(str(x)), collapse = collapse) } @@ -574,8 +582,9 @@ convert_to_fewer_types = function(x) { #' @return a result object, with either a valid string or an Err #' @keywords internal #' +#' @noRd #' @examples -#' check_tz_to_result = polars:::check_tz_to_result # expose internal +#' check_tz_to_result = .pr$env$check_tz_to_result # expose internal #' # return Ok #' check_tz_to_result("GMT") #' check_tz_to_result(NULL) diff --git a/R/zzz.R b/R/zzz.R index 750651c44..9fc99dcb0 100644 --- a/R/zzz.R +++ b/R/zzz.R @@ -5,7 +5,7 @@ if (build_debug_print) { print(paste( "Modifying extendr bindings,", - "originals converted to pure functions and saved to polars:::.pr" + "originals converted to pure functions and saved to .pr" )) } @@ -66,7 +66,13 @@ replace_private_with_pub_methods(WhenThenThen, "^WhenThenThen_") # any sub-namespace inherits 'method_environment' # This s3 method performs auto-completion +#' @title auto complete $-access into a polars object +#' @description called by the interactive R session internally +#' @param x string, name of method in method_environment (sub-namespace) +#' @param pattern code-stump as string to auto-complete #' @export +#' @inherit .DollarNames.DataFrame return +#' @keywords internal .DollarNames.method_environment = function(x, pattern = "") { # I ponder why R chose to let attributes of environments be mutable also?! # temp store full class and upcast to plain environment @@ -106,7 +112,6 @@ move_env_elements(Expr, pl, c("lit"), remove = FALSE) pl$mem_address = mem_address - # tell testthat data.table is suggested .datatable.aware = TRUE diff --git a/README.Rmd b/README.Rmd index b264100a7..2b0489f7d 100644 --- a/README.Rmd +++ b/README.Rmd @@ -40,18 +40,29 @@ Ritchie Vink ([@ritchie46](https://github.com/ritchie46)). This R port is maintained by Sรธren Welling ([@sorhawell](https://github.com/sorhawell)) and [contributors](https://github.com/pola-rs/r-polars/graphs/contributors). -Consider joining our [Discord](https://discord.gg/4UfP5cfBE7) (subchannel) for +Consider joining our [Discord](https://discord.com/invite/4UfP5cfBE7) (subchannel) for additional help and discussion. ## Install -The package is not yet available on CRAN. But we provide convenient installation -options for a variety of operating systems: +The package can be installed from CRAN, R-universe, or GitHub. + +Some platforms can install pre-compiled binaries, and others will need to build from source. + +### CRAN + +CRAN provides pre-compiled binaries for Windows (x86_64) and macOS. + +Binary packages on CRAN are compiled by stable Rust, with nightly features disabled. + +```r +install.packages("polars") +``` ### R-universe [R-universe](https://rpolars.r-universe.dev/polars#install) provides -pre-compiled **polars** binaries for Windows (x86_64), MacOS (x86_64) and Ubuntu 22.04 (x86_64) +pre-compiled **polars** binaries for Windows (x86_64), macOS (x86_64) and Ubuntu 22.04 (x86_64) with source builds for other platforms. Binary packages on R-universe are compiled by stable Rust, with nightly features disabled. @@ -70,12 +81,13 @@ excellent R-universe support. ### GitHub releases -We also provide pre-compiled binaries for various operating systems, as well as -source installs, on our +We also provide pre-compiled binaries for various operating systems on our [GitHub releases](https://github.com/pola-rs/r-polars/releases) page. You can download and install these files manually, or install directly from R. Simply match the URL for your operating system and the desired release. For example, to -install the latest release of **polars** on Linux (x86_64) one would use: +install the latest release of **polars** on one can use: + +#### Linux (x86_64) ```r install.packages( @@ -84,10 +96,22 @@ install.packages( ) ``` -Similarly for Windows -([URL](https://github.com/pola-rs/r-polars/releases/latest/download/polars.zip)) -and MacOS (x86_64, -[URL](https://github.com/pola-rs/r-polars/releases/latest/download/polars__x86_64-apple-darwin20.tgz)). +#### Windows +```r +install.packages( + "https://github.com/pola-rs/r-polars/releases/latest/download/polars.zip", + repos = NULL +) +``` + +#### macOS(x86_64) +```r +install.packages( + "https://github.com/pola-rs/r-polars/releases/latest/download/polars__x86_64-apple-darwin20.tgz", + repos = NULL +) +``` + Just remember to invoke the `repos = NULL` argument if you are installing these binary builds directly from within R. @@ -188,13 +212,13 @@ to install the Rust toolchain: ``` - Windows: Make sure the latest version of [Rtools](https://cran.r-project.org/bin/windows/Rtools/) is installed and on your PATH. -* MacOS: Make sure [`Xcode`](https://developer.apple.com/support/xcode/) is installed. +* macOS: Make sure [`Xcode`](https://developer.apple.com/support/xcode/) is installed. * Install [CMake](https://cmake.org/) and add it to your PATH. ### Implementing new features Here are the steps required for an example contribution, where we are implementing the -[cosine expression](https://rpolars.github.io/reference/Expr_cos.html): +[cosine expression](https://rpolars.github.io/reference/Expr_cos/): * Look up the [polars.Expr.cos method in py-polars documentation](https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.cos.html). * Press the `[source]` button to see the [Python implementation](https://github.com/pola-rs/polars/blob/d23bbd2f14f1cd7ae2e27e1954a2dc4276501eef/py-polars/polars/expr/expr.py#L5892-L5914) diff --git a/README.md b/README.md index 32f7095fc..09d36ac55 100644 --- a/README.md +++ b/README.md @@ -31,18 +31,31 @@ The primary developer of the upstream Polars project is Ritchie Vink ([@ritchie46](https://github.com/ritchie46)). This R port is maintained by Sรธren Welling ([@sorhawell](https://github.com/sorhawell)) and [contributors](https://github.com/pola-rs/r-polars/graphs/contributors). -Consider joining our [Discord](https://discord.gg/4UfP5cfBE7) +Consider joining our [Discord](https://discord.com/invite/4UfP5cfBE7) (subchannel) for additional help and discussion. ## Install -The package is not yet available on CRAN. But we provide convenient -installation options for a variety of operating systems: +The package can be installed from CRAN, R-universe, or GitHub. + +Some platforms can install pre-compiled binaries, and others will need +to build from source. + +### CRAN + +CRAN provides pre-compiled binaries for Windows (x86_64) and macOS. + +Binary packages on CRAN are compiled by stable Rust, with nightly +features disabled. + +``` r +install.packages("polars") +``` ### R-universe [R-universe](https://rpolars.r-universe.dev/polars#install) provides -pre-compiled **polars** binaries for Windows (x86_64), MacOS (x86_64) +pre-compiled **polars** binaries for Windows (x86_64), macOS (x86_64) and Ubuntu 22.04 (x86_64) with source builds for other platforms. Binary packages on R-universe are compiled by stable Rust, with nightly @@ -62,13 +75,14 @@ the excellent R-universe support. ### GitHub releases -We also provide pre-compiled binaries for various operating systems, as -well as source installs, on our [GitHub -releases](https://github.com/pola-rs/r-polars/releases) page. You can -download and install these files manually, or install directly from R. -Simply match the URL for your operating system and the desired release. -For example, to install the latest release of **polars** on Linux -(x86_64) one would use: +We also provide pre-compiled binaries for various operating systems on +our [GitHub releases](https://github.com/pola-rs/r-polars/releases) +page. You can download and install these files manually, or install +directly from R. Simply match the URL for your operating system and the +desired release. For example, to install the latest release of +**polars** on one can use: + +#### Linux (x86_64) ``` r install.packages( @@ -77,10 +91,24 @@ install.packages( ) ``` -Similarly for Windows -([URL](https://github.com/pola-rs/r-polars/releases/latest/download/polars.zip)) -and MacOS (x86_64, -[URL](https://github.com/pola-rs/r-polars/releases/latest/download/polars__x86_64-apple-darwin20.tgz)). +#### Windows + +``` r +install.packages( + "https://github.com/pola-rs/r-polars/releases/latest/download/polars.zip", + repos = NULL +) +``` + +#### macOS(x86_64) + +``` r +install.packages( + "https://github.com/pola-rs/r-polars/releases/latest/download/polars__x86_64-apple-darwin20.tgz", + repos = NULL +) +``` + Just remember to invoke the `repos = NULL` argument if you are installing these binary builds directly from within R. @@ -226,7 +254,7 @@ you will to install the Rust toolchain: [Rtools](https://cran.r-project.org/bin/windows/Rtools/) is installed and on your PATH. -- MacOS: Make sure [`Xcode`](https://developer.apple.com/support/xcode/) +- macOS: Make sure [`Xcode`](https://developer.apple.com/support/xcode/) is installed. - Install [CMake](https://cmake.org/) and add it to your PATH. @@ -235,7 +263,7 @@ you will to install the Rust toolchain: Here are the steps required for an example contribution, where we are implementing the [cosine -expression](https://rpolars.github.io/reference/Expr_cos.html): +expression](https://rpolars.github.io/reference/Expr_cos/): - Look up the [polars.Expr.cos method in py-polars documentation](https://pola-rs.github.io/polars/py-polars/html/reference/expressions/api/polars.Expr.cos.html). diff --git a/cran-comments.md b/cran-comments.md new file mode 100644 index 000000000..0940a5364 --- /dev/null +++ b/cran-comments.md @@ -0,0 +1,63 @@ +## Test environments + +- local: x86_64-pc-linux-gnu +- GitHub Actions + - { os: macos-latest, r: "release" } + - { os: windows-latest, r: "devel" } + - { os: windows-latest, r: "release" } + - { os: ubuntu-latest, r: "devel" } + - { os: ubuntu-latest, r: "release" } + - { os: ubuntu-latest, r: "oldrel-1" } + +## R CMD check results + +- There were no ERRORs or WARNINGs. +- There was 2 NOTEs. + - New submission + - installed size is 140.8Mb + +## Resubmission + +This is a resubmission. Thank your for the comments, below are our answers: + +> Please add \value to .Rd files regarding exported methods and explain +the functions results in the documentation. Please write about the +structure of the output (class) and also what the output means. + +We have added \value where it was missing. + +> You have examples for unexported functions. Please either omit these +examples or export these functions. + +Most polars unexported functions (427 closures with a `self`) are actually the +public methods called through `object$method()`. They should NOT be exported as +plain functions. Public methods should be documented though. + +The vast number of methods makes it unfeasible to bundle all methods in a single +doc page per class, like common practice for another class-system as R6. Imagine +a .Rd params section with +500 parameters? Many param-names will collide. Then a +details section with +100 out-of-context sections. Then +100 different return +values. Then +400 mixed use examples. It would be completely unreadable and +unsearchable. The number of methods are only expected to increase further in +future versions. + +Besides methods, upstream Polars also has a number of functions/objects that +collide with `base`, `utils`, `stats`, and many popular packages. Polars strives +to be a cross-language syntax (Rust, Python, R, NodeJS). It is not possible to +rename functions to avoid namespace collisions locally in R. Package functions +(and other objects types) are in all languages bundled in a namespace `pl` to +not clutter user search()-namespace and to remove the risk of conflicts. + +> In your LICENSE file you state "rpolars authors" to be the +copyrightholders. Do you mean yourself? In that case please write "polar +authors" instead. Otherwise please add the copyrightholders to the +Authors@R field in your description. + +We have changed to 'polars authors' in LICENCE to: + +YEAR: 2023 +COPYRIGHT HOLDER: polars authors (polars the R package) + +We add also (polars the R package) to not claim authorship or copyright to e.g. +rust-polars or py-polars. Ritchie Vink is the first author to all r-polars, +py-polars and rust-polars. No organization is 'cph'. diff --git a/docs/docs/about.md b/docs/docs/about.md index fe97bbf00..7452c55e3 100644 --- a/docs/docs/about.md +++ b/docs/docs/about.md @@ -8,14 +8,17 @@ maintained by Sรธren Welling Development occurs on Github: https://github.com/pola-rs/r-polars -Consider joining our [Discord](https://discord.gg/4UfP5cfBE7) +Consider joining our [Discord](https://discord.com/invite/4UfP5cfBE7) (subchannel) for additional help and discussion. +**'Polars'** is a query engine/syntax for multiple languages. The R specific implementation +can be referred to as **r-polars** and is derived from **rust-polars**. + The **polars** package for R is published under the MIT license. ## MIT License -Copyright (c) 2023 rpolars authors +Copyright (c) 2023 polars authors (polars the R package) Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/inst/misc/develop_polars.R b/inst/misc/develop_polars.R new file mode 100644 index 000000000..ba0079626 --- /dev/null +++ b/inst/misc/develop_polars.R @@ -0,0 +1,278 @@ +#' load polars with environment variables and packages +#' +#' @param ALL_FEATURES bool, to compile with e.g. simd, only for nightly toolchain +#' @param NOT_CRAN bool, do not delete compiled target objects. Next compilation much faster. +#' @param RPOLARS_CARGO_CLEAN_DEPS bool, do clean up cargo cache. Slows down next compilation +#' @param ... other environment args to add +#' @details in general Makevars check if bool-like envvars are not 'true'. +#' +#' @return no return +#' +#' @examples load_polars(ALL_FEATURES = '', SOME_OTHER_ENVVAR = 'true') +load_polars = function( + RPOLARS_ALL_FEATURES = 'true', + NOT_CRAN = 'true', + RPOLARS_CARGO_CLEAN_DEPS = 'false', + ..., + .packages = c("arrow","nanoarrow") +) { + + # bundle all envvars + args = c( + list( + RPOLARS_ALL_FEATURES = RPOLARS_ALL_FEATURES, + NOT_CRAN = NOT_CRAN, + RPOLARS_CARGO_CLEAN_DEPS = RPOLARS_CARGO_CLEAN_DEPS + ), + list(...), + .packages = list(.packages) + ) + + do.call(with_polars, c(list(rextendr::document), args)) + +} + + +#' load polars with environment variables and packages +#' +#' @param ALL_FEATURES bool, to compile with e.g. simd, only for nightly toolchain +#' @param NOT_CRAN bool, do not delete compiled target objects. Next compilation much faster. +#' @param RPOLARS_CARGO_CLEAN_DEPS bool, do clean up cargo cache. Slows down next compilation +#' @param ... other environment args to add +#' @details in general Makevars check if bool-like envvars are not 'true'. +#' +#' @return no return +#' +#' @examples load_polars(ALL_FEATURES = '', SOME_OTHER_ENVVAR = 'true') +build_polars = function( + RPOLARS_ALL_FEATURES = 'true', + NOT_CRAN = 'true', + RPOLARS_CARGO_CLEAN_DEPS = 'false', + ..., + .packages = c("arrow","nanoarrow") +) { + + # bundle all envvars + args = c( + list( + RPOLARS_ALL_FEATURES = RPOLARS_ALL_FEATURES, + NOT_CRAN = NOT_CRAN, + RPOLARS_CARGO_CLEAN_DEPS = RPOLARS_CARGO_CLEAN_DEPS + ), + list(...), + .packages = list(.packages) + ) + + do.call(with_polars, c(list(\() system("cd ..; R CMD INSTALL --preclean --no-multiarch --with-keep.source r-polars")), args)) + +} + +#' check polars with environment variables, filter errors, symlink precompiled target +#' +#' @param RPOLARS_RUST_SOURCE where check can find precomiled target, set to '' if not use, +#' DEFAULT is `paste0(getwd(),"/src/rust")`. +#' @param ALL_FEATURES bool, to compile with e.g. simd, only for nightly toolchain +#' @param NOT_CRAN bool, do not delete compiled target objects. Next compilation much faster. +#' @param RPOLARS_CARGO_CLEAN_DEPS bool, do clean up cargo cache. Slows down next compilation +#' @param ... other environment args to add +#' @details in general Makevars check if bool-like envvars are not 'true'. +#' +#' @return no return +#' +#' @examples load_polars(ALL_FEATURES = '', SOME_OTHER_ENVVAR = 'true') +check_polars = function( + RPOLARS_RUST_SOURCE = paste0(getwd(),"/src/rust"), + RPOLARS_ALL_FEATURES = 'true', + NOT_CRAN = 'true', + RPOLARS_CARGO_CLEAN_DEPS = 'false', + FILTER_CHECK_NO_FILTER = 'false', + ..., + check_dir = "./check/", + .packages = character() +) { + + # bundle all envvars + envvars = c( + list( + RPOLARS_RUST_SOURCE = RPOLARS_RUST_SOURCE, + RPOLARS_ALL_FEATURES = RPOLARS_ALL_FEATURES, + NOT_CRAN = NOT_CRAN, + RPOLARS_CARGO_CLEAN_DEPS = RPOLARS_CARGO_CLEAN_DEPS + ), + list(...) + ) + not_cran = identical(NOT_CRAN,'true') + cat("check in not_cran mode:", not_cran ,"\n") + with_polars( + \() { + devtools::check( + env_vars = envvars, check_dir = check_dir, + vignettes = FALSE, cran = !not_cran + ) + rextendr::document() # restore nanoarrow.Rd + }, + RPOLARS_ALL_FEATURES = RPOLARS_ALL_FEATURES, + NOT_CRAN = NOT_CRAN, + RPOLARS_CARGO_CLEAN_DEPS = RPOLARS_CARGO_CLEAN_DEPS, + RPOLARS_RUST_SOURCE = RPOLARS_RUST_SOURCE, + ... + ) + + on.exit({unlink("check",recursive = TRUE)}) + source("./inst/misc/filter_rcmdcheck.R") + print("check polars is done") +} + +#' submit polars with environment variables, filter errors, symlink precompiled target +#' +#' @param RPOLARS_RUST_SOURCE where check can find precomiled target, set to '' if not use, +#' DEFAULT is `paste0(getwd(),"/src/rust")`. +#' @param ALL_FEATURES bool, to compile with e.g. simd, only for nightly toolchain +#' @param NOT_CRAN bool, do not delete compiled target objects. Next compilation much faster. +#' @param RPOLARS_CARGO_CLEAN_DEPS bool, do clean up cargo cache. Slows down next compilation +#' @param ... other environment args to add +#' @details in general Makevars check if bool-like envvars are not 'true'. +#' +#' @return no return +#' +#' @examples load_polars(ALL_FEATURES = '', SOME_OTHER_ENVVAR = 'true') +submit_polars = function( + RPOLARS_RUST_SOURCE = paste0(getwd(),"/src/rust"), + RPOLARS_ALL_FEATURES = 'false', + NOT_CRAN = 'true', + RPOLARS_CARGO_CLEAN_DEPS = 'false', + ..., + temp_dir = tempdir(check = TRUE), + .packages = character(), + unlink_temp = TRUE +) { + + # bundle all envvars + envvars = c( + list( + RPOLARS_RUST_SOURCE = RPOLARS_RUST_SOURCE, + RPOLARS_ALL_FEATURES = RPOLARS_ALL_FEATURES, + NOT_CRAN = NOT_CRAN, + RPOLARS_CARGO_CLEAN_DEPS = RPOLARS_CARGO_CLEAN_DEPS + ), + list(...) + ) + not_cran = identical(NOT_CRAN,'true') + cat("in not_cran mode:", not_cran ,"\n") + with_polars( + \() { + temp_dir = paste0(temp_dir,"/polars_submission") + unlink(temp_dir, recursive = TRUE, force = TRUE) + dir.create(temp_dir) + #copy repo except target folders + all_files = list.files(path = ".", full.names = TRUE, recursive = TRUE) + non_target_files = setdiff(all_files, grep("^\\./src/rust/target", all_files , value = TRUE)) + non_target_dirs = gregexpr("/",non_target_files) |> + lapply(tail,1) |> + substr(x=non_target_files,start=1) |> + unique() |> + (\(x){ x[order(nchar(x))][-1]})() + for(i in paste0(temp_dir,"/", non_target_dirs)) dir.create(i) + res = file.copy(non_target_files, paste0(temp_dir,"/", non_target_files)) + if(!all(res)) warning("copy incomplete") + + oldwd = getwd() + setwd(temp_dir) + on.exit({ + setwd(oldwd) + if(unlink_temp) unlink(temp_dir,recursive = TRUE) + }) + devtools::submit_cran() + }, + RPOLARS_ALL_FEATURES = RPOLARS_ALL_FEATURES, + NOT_CRAN = NOT_CRAN, + RPOLARS_CARGO_CLEAN_DEPS = RPOLARS_CARGO_CLEAN_DEPS, + RPOLARS_RUST_SOURCE = RPOLARS_RUST_SOURCE, + ... + ) + +} + +with_polars = function( + f, + ..., + .packages = character() +) { + # bundle all envvars + envvar = list(...) + stopifnot(all(sapply(names(envvar),nchar))) + + + # write envvar to environment, store old + old_tmp = list() + for(i in seq_along(envvar)) { + key = names(envvar)[i] + old_val = Sys.getenv(key) + old_tmp[[key]] = old_val + do.call(Sys.setenv, envvar[key]) + } + + # add packages to search path + if(length(.packages)) { + not_in_search = .packages[!paste0("package:",.packages) %in% search()] + for(i in not_in_search) { + if(!require(i, character.only = TRUE)) warning(paste("did not preload package:", i)) + } + } else { + not_in_search = character() + } + + #plan to restore old envvar and search() + on.exit({ + # restore args + do.call(Sys.setenv, old_tmp) + + # restore search + for(i in not_in_search) { + message(paste("detaching ", i)) + detach(paste0("package:",i),character.only = TRUE) + } + }) + + # build + + out = f() + + invisible(out) +} + + +#' find compiled *.Rd files for missing return value +#' +#' @return char vec +#' +#' @examples +#' find_missing_return() +find_missing_return = function() { + + has_value = function(x) { + found = character() + + has_value_recursive = function(x,lvl=0) { + for(i in x) { + if(is.list(i)) has_value_recursive(i, lvl = lvl+1) + if(identical("\\value",attr(i, "Rd_tag"))) { + found <<- c(found, substr(paste(unlist(i),collapse=" | "),1,25)) + } + } + } + has_value_recursive(x) + found + } + + all_doc_values = list.files("./man/", full.names = TRUE) |> + sapply(\(x) { + tools::parse_Rd(x) |> + unclass() |> + has_value() + }) + + names(all_doc_values[sapply(all_doc_values,length)<1]) + +} + diff --git a/inst/misc/examples/example.R b/inst/misc/examples/example.R deleted file mode 100644 index d9b763178..000000000 --- a/inst/misc/examples/example.R +++ /dev/null @@ -1,77 +0,0 @@ -library(magrittr) -pf = pl$DataFrame(iris) - - -#check cloning -pf2 = pl$DataFrame(pf) # constructor is also identity function -pf3 = pf$clone(deep=TRUE) -pf4 = pf$clone(deep=FALSE) - - -isTRUE(all.equal(pf,pf2)) -isTRUE(all.equal(pf,pf3)) -isTRUE(all.equal(pf,pf4)) -isFALSE(identical(pf3,pf4)) - -pl$mem_address(pf$.__enclos_env__$private$pf) == - pl$mem_address(pf2$.__enclos_env__$private$pf) - -pl$mem_address(pf$.__enclos_env__$private$pf) != - pl$mem_address(pf3$.__enclos_env__$private$pf) - -pl$mem_address(pf$.__enclos_env__$private$pf) == - pl$mem_address(pf4$.__enclos_env__$private$pf) - - - -values = list ( - newname = pl$Series(c(1,2,3,4,5),name = "b"), #overwrite name b with newname - pl$Series((1:5) * 5,"a"), - pl$Series(letters[1:5],"b"), - c(5,4,3,2,1), #unnamed vector - named_vector = c(15,14,13,12,11) ,#named provide - c(5,4,3,2,0) -) - -pl$DataFrame(values) - - - - - -#build an expression -pl$col("Sepal.Width")$sum()$over("Species")$alias("miah") -pl$col("Sepal.Width")$sum()$over(c("Species", "Petal.Width"))$alias("miah") - -#make selection with expressions or strings, convert back to data.frame -pf$select( - pl$col("Sepal.Width")$sum()$over("Species")$alias("sw_sum_over_species"), - pl$col("Sepal.Length")$sum()$over("Species")$alias("sl_sum_over_species"), - "Petal.Width" -)$to_data_frame() |> head() - - -#datatypes -pl$dtypes - - -##read a csv file -polars:::new_csv_r( - path = "a path", - sep = ",", - has_header = TRUE, - ignore_errors = FALSE, - skip_rows = 0, - n_rows = NULL, - cache = FALSE, - polars:::DataType_vector$new() -) - - - - - - - - - diff --git a/inst/misc/filter_rcmdcheck.R b/inst/misc/filter_rcmdcheck.R index 6c81a29b1..a894af177 100644 --- a/inst/misc/filter_rcmdcheck.R +++ b/inst/misc/filter_rcmdcheck.R @@ -12,52 +12,24 @@ print(getwd()) #define ignore rules for notes, warnings and errors ignore_rules = list( notes = list( - #if note contains this phrase then skip it by returning TRUE. #yes polars is huge way above 10Mb nothing to do about that ignore_lib_size = function(msg) { isTRUE(grepl("checking installed package size ... NOTE",msg)) - }, - - #check warnings/notes appear since main polars commit from and after - #" feat(rust, python): The 1 billion row sort (#6156) " - # 1a51f9e55196f69fb59e44d497de4f0e6685640d - # don't know how to fix it for now, just ignore unit tests passes just fine - ignore_macos_dll_error = function(msg) { - isTRUE(Sys.info()["sysname"]=="Darwin") && - isTRUE(grepl("_IOBSDNameMatching",msg)) - }, - - ignore_windows_linker_error = function(msg) { - #isTRUE(grepl("windows",tolower(R.version$os))[1]) && - isTRUE(grepl("drectve at end of def file",msg)) } - ), + warnings = list(), + errors = list() +) - warnings = list( - #see above both warnings and a note - ignore_windows_linker_error = function(msg) { - #isTRUE(grepl("windows",tolower(R.version$os))[1]) && - isTRUE(grepl("drectve at end of def file",msg)) - }, - - ignore_macos_dll_error = function(msg) { - isTRUE(grepl("darwin",R.version$os)[1]) && - isTRUE(grepl("_IOBSDNameMatching",msg)) - }, - ignore_lengths_ns_collision = function(msg) { - isTRUE( - grepl("Functions or methods with usage in documentation object 'ExprStr_lengths'", - msg) - ) - } - ), +#drop any filter if FILTER_CHECK_NO_FILTER = true +if (Sys.getenv("FILTER_CHECK_NO_FILTER") == "true") { + ignore_rules$notes = list() + ignore_rules$warnings = list() + ignore_rules$errors = list() +} - errors = list( - ) -) #helper function #iterate a msg_set, as notes, warnings, errors and drop those where an ignore rule returns TRUE diff --git a/man/DataFrame_class.Rd b/man/DataFrame_class.Rd index b391f8e9f..7a2fd3a36 100644 --- a/man/DataFrame_class.Rd +++ b/man/DataFrame_class.Rd @@ -3,6 +3,9 @@ \name{DataFrame_class} \alias{DataFrame_class} \title{Inner workings of the DataFrame-class} +\value{ +not applicable +} \description{ The \code{DataFrame}-class is simply two environments of respectively the public and private methods/function calls to the polars rust side. The instantiated @@ -14,7 +17,7 @@ another \code{DataFrame}-class instance or similar which allows for method chain This class system in lack of a better name could be called "environment classes" and is the same class system extendr provides, except here there is both a public and private set of methods. For implementation reasons, the private methods are -external and must be called from polars:::.pr.$DataFrame$methodname(), also all private methods +external and must be called from \code{.pr$DataFrame$methodname()}, also all private methods must take any self as an argument, thus they are pure functions. Having the private methods as pure functions solved/simplified self-referential complications. } @@ -26,21 +29,22 @@ zzz to be last file sourced) the extendr-methods are removed and replaced by any prefixed \code{DataFrame_}. } \examples{ -# see all exported methods -ls(polars:::DataFrame) +# see all public exported method names (normally accessed via a class instance with $) +ls(.pr$env$DataFrame) # see all private methods (not intended for regular use) -ls(polars:::.pr$DataFrame) +ls(.pr$DataFrame) # make an object df = pl$DataFrame(iris) + # use a public method/property df$shape df2 = df # use a private method, which has mutability -result = polars:::.pr$DataFrame$set_column_from_robj(df, 150:1, "some_ints") +result = .pr$DataFrame$set_column_from_robj(df, 150:1, "some_ints") # column exists in both dataframes-objects now, as they are just pointers to the same object # there are no public methods with mutability @@ -58,7 +62,7 @@ df2$columns # method does not return any ok-value. # try unwrapping an error from polars due to unmatching column lengths -err_result = polars:::.pr$DataFrame$set_column_from_robj(df, 1:10000, "wrong_length") +err_result = .pr$DataFrame$set_column_from_robj(df, 1:10000, "wrong_length") tryCatch(unwrap(err_result, call = NULL), error = \(e) cat(as.character(e))) } \keyword{DataFrame} diff --git a/man/DataFrame_print.Rd b/man/DataFrame_print.Rd deleted file mode 100644 index 1a4235cfc..000000000 --- a/man/DataFrame_print.Rd +++ /dev/null @@ -1,17 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dataframe__frame.R -\name{DataFrame_print} -\alias{DataFrame_print} -\title{internal method print DataFrame} -\usage{ -DataFrame_print() -} -\value{ -self -} -\description{ -internal method print DataFrame -} -\examples{ -pl$DataFrame(iris) -} diff --git a/man/DataFrame_reverse.Rd b/man/DataFrame_reverse.Rd index 94c644a69..b4e8a7277 100644 --- a/man/DataFrame_reverse.Rd +++ b/man/DataFrame_reverse.Rd @@ -7,7 +7,7 @@ DataFrame_reverse() } \value{ -LazyFrame +DataFrame } \description{ Reverse the DataFrame. diff --git a/man/DataFrame_select.Rd b/man/DataFrame_select.Rd index e40b9b85c..4e7a90848 100644 --- a/man/DataFrame_select.Rd +++ b/man/DataFrame_select.Rd @@ -12,6 +12,11 @@ DataFrame_select(...) column names (e.g \code{"a"}), or list containing expressions or column names (e.g \code{list(pl$col("a"))}).} } +\value{ +DataFrame + +DataFrame +} \description{ Related to dplyr \code{mutate()}. However, it discards unmentioned columns (like \code{.()} in \code{data.table}). diff --git a/man/DataFrame_slice.Rd b/man/DataFrame_slice.Rd index e38c9d5b2..44cdd44a1 100644 --- a/man/DataFrame_slice.Rd +++ b/man/DataFrame_slice.Rd @@ -12,7 +12,7 @@ DataFrame_slice(offset, length = NULL) \item{length}{integer or NULL} } \value{ -LazyFrame +DataFrame } \description{ Get a slice of this DataFrame. diff --git a/man/DataFrame_sort.Rd b/man/DataFrame_sort.Rd index abe21402a..ff32256e8 100644 --- a/man/DataFrame_sort.Rd +++ b/man/DataFrame_sort.Rd @@ -8,7 +8,7 @@ DataFrame_sort(by, ..., descending = FALSE, nulls_last = FALSE) } \arguments{ \item{by}{Column(s) to sort by. Column name strings, character vector of -column names, or Iterable Into\if{html}{\out{}} (e.g. one Expr, or list mixed Expr and +column names, or Iterable \verb{Into} (e.g. one Expr, or list mixed Expr and column name strings).} \item{...}{more columns to sort by as above but provided one Expr per argument.} @@ -19,7 +19,7 @@ as number of Expr's from above by + ....} \item{nulls_last}{Bool default FALSE, place all nulls_last?} } \value{ -LazyFrame +DataFrame } \description{ sort a DataFrame by on or more Expr. diff --git a/man/DataFrame_to_data_frame.Rd b/man/DataFrame_to_data_frame.Rd index e6c0de433..f779fe4df 100644 --- a/man/DataFrame_to_data_frame.Rd +++ b/man/DataFrame_to_data_frame.Rd @@ -3,7 +3,7 @@ \name{DataFrame_to_data_frame} \alias{DataFrame_to_data_frame} \alias{as.data.frame.DataFrame} -\title{return polars DataFrame as R data.frame} +\title{Return Polars DataFrame as R data.frame} \usage{ DataFrame_to_data_frame(...) @@ -15,12 +15,12 @@ DataFrame_to_data_frame(...) \item{x}{DataFrame} } \value{ -data.frame +An R data.frame data.frame } \description{ -return polars DataFrame as R data.frame +Return Polars DataFrame as R data.frame } \examples{ df = pl$DataFrame(iris[1:3, ]) diff --git a/man/DataType_new.Rd b/man/DataType_new.Rd deleted file mode 100644 index 481ae4dee..000000000 --- a/man/DataType_new.Rd +++ /dev/null @@ -1,31 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/datatype.R -\name{DataType_new} -\alias{DataType_new} -\title{DataType_new (simple DataType's)} -\usage{ -DataType_new(str) -} -\arguments{ -\item{str}{name of DataType to create} -} -\value{ -DataType -} -\description{ -Create a new flag like DataType -} -\details{ -This function is mainly used in \code{zzz.R} \code{.onLoad} to instantiate singletons of all -flag-like DataType. - -Non-flag like DataType called composite DataTypes also carries extra information -e.g. Datetime a timeunit and a TimeZone, or List which recursively carries another DataType -inside. Composite DataTypes use DataType constructors. - -Any DataType can be found in pl$dtypes -} -\examples{ -polars:::DataType_new("Int64") -} -\keyword{internal} diff --git a/man/ExprBin_starts_with.Rd b/man/ExprBin_starts_with.Rd index 9554032ab..77d2d682d 100644 --- a/man/ExprBin_starts_with.Rd +++ b/man/ExprBin_starts_with.Rd @@ -7,6 +7,9 @@ \arguments{ \item{sub}{Prefix substring.} } +\value{ +Expr returing a Boolean +} \description{ Check if values starts with a binary substring. } diff --git a/man/ExprStr_replace.Rd b/man/ExprStr_replace.Rd index 5a4897aff..31311da8f 100644 --- a/man/ExprStr_replace.Rd +++ b/man/ExprStr_replace.Rd @@ -5,9 +5,9 @@ \alias{expr_str_replace} \title{replace} \arguments{ -\item{pattern}{Into\if{html}{\out{}}, regex pattern} +\item{pattern}{\verb{Into}, regex pattern} -\item{value}{Into\if{html}{\out{}} replacement} +\item{value}{\verb{Into} replacement} \item{literal}{bool, Treat pattern as a literal string.} } diff --git a/man/ExprStr_replace_all.Rd b/man/ExprStr_replace_all.Rd index 8cef793fd..a5f9351ec 100644 --- a/man/ExprStr_replace_all.Rd +++ b/man/ExprStr_replace_all.Rd @@ -5,9 +5,9 @@ \alias{expr_str_replace_all} \title{replace_all} \arguments{ -\item{pattern}{Into\if{html}{\out{}}, regex pattern} +\item{pattern}{\verb{Into}, regex pattern} -\item{value}{Into\if{html}{\out{}} replacement} +\item{value}{\verb{Into} replacement} \item{literal}{bool, treat pattern as a literal string.} } diff --git a/man/ExprStr_slice.Rd b/man/ExprStr_slice.Rd index 881a0f09f..86aa24565 100644 --- a/man/ExprStr_slice.Rd +++ b/man/ExprStr_slice.Rd @@ -5,9 +5,9 @@ \alias{expr_str_slice} \title{slice} \arguments{ -\item{pattern}{Into\if{html}{\out{}}, regex pattern} +\item{pattern}{\verb{Into}, regex pattern} -\item{value}{Into\if{html}{\out{}} replacement} +\item{value}{\verb{Into} replacement} \item{literal}{bool, treat pattern as a literal string.} } diff --git a/man/Expr_class.Rd b/man/Expr_class.Rd index 08d3452bf..10cf38d74 100644 --- a/man/Expr_class.Rd +++ b/man/Expr_class.Rd @@ -3,6 +3,9 @@ \name{Expr_class} \alias{Expr_class} \title{Polars Expressions} +\value{ +not applicable +} \description{ Expressions are all the functions and methods that are applicable to a Polars DataFrame. They can be split into the following categories (following diff --git a/man/Expr_print.Rd b/man/Expr_print.Rd index 8e8ce7ad5..1309daefa 100644 --- a/man/Expr_print.Rd +++ b/man/Expr_print.Rd @@ -6,10 +6,14 @@ \usage{ Expr_print() } +\value{ +invisible self +} \description{ internal method print Expr } \examples{ +pl$col("some_column")$sum()$over("some_other_column")$print() pl$DataFrame(iris) } \keyword{Expr} diff --git a/man/GroupBy_class.Rd b/man/GroupBy_class.Rd index b7a90acd5..119cd3cf0 100644 --- a/man/GroupBy_class.Rd +++ b/man/GroupBy_class.Rd @@ -3,6 +3,18 @@ \name{GroupBy_class} \alias{GroupBy_class} \title{Operations on Polars grouped DataFrame} +\value{ +not applicable +} \description{ Operations on Polars grouped DataFrame } +\details{ +The GroupBy class in R, is just another interface on top of the DataFrame(R wrapper class) in +rust polars. Groupby does not use the rust api for groupby+agg because the groupby-struct is a +reference to a DataFrame and that reference will share lifetime with its parent DataFrame. There +is no way to expose lifetime limited objects via extendr currently (might be quirky anyhow with R +GC). Instead the inputs for the groupby are just stored on R side, until also agg is called. +Which will end up in a self-owned DataFrame object and all is fine. groupby aggs are performed +via the rust polars LazyGroupBy methods, see DataFrame.groupby_agg method. +} diff --git a/man/LazyFrame_class.Rd b/man/LazyFrame_class.Rd index 2b8bcc41a..1d1893976 100644 --- a/man/LazyFrame_class.Rd +++ b/man/LazyFrame_class.Rd @@ -3,6 +3,9 @@ \name{LazyFrame_class} \alias{LazyFrame_class} \title{Inner workings of the LazyFrame-class} +\value{ +not applicable +} \description{ The \code{LazyFrame}-class is simply two environments of respectively the public and private methods/function calls to the polars rust side. The @@ -17,7 +20,7 @@ for method chaining. This class system in lack of a better name could be called "environment classes" and is the same class system extendr provides, except here there is both a public and private set of methods. For implementation reasons, the private methods are external and must be called from -\code{polars:::.pr.$LazyFrame$methodname()}. Also, all private methods must take +\code{.pr$LazyFrame$methodname()}. Also, all private methods must take any self as an argument, thus they are pure functions. Having the private methods as pure functions solved/simplified self-referential complications. @@ -40,10 +43,10 @@ prefixed \code{LazyFrame_}. } \examples{ # see all exported methods -ls(polars:::LazyFrame) +ls(.pr$env$LazyFrame) # see all private methods (not intended for regular use) -ls(polars:::.pr$LazyFrame) +ls(.pr$LazyFrame) ## Practical example ## diff --git a/man/LazyFrame_describe_plan.Rd b/man/LazyFrame_describe_plan.Rd index 693c11d93..a02e8718f 100644 --- a/man/LazyFrame_describe_plan.Rd +++ b/man/LazyFrame_describe_plan.Rd @@ -13,6 +13,9 @@ LazyFrame_describe_optimized_plan() LazyFrame_describe_plan } +\value{ +invisible NULL +} \description{ \verb{$describe_plan()} shows our query in the format that \code{polars} understands. \verb{$describe_optimized_plan()} shows the optimized query plan that diff --git a/man/LazyFrame_sort.Rd b/man/LazyFrame_sort.Rd index 3df50f2a5..34f494bd4 100644 --- a/man/LazyFrame_sort.Rd +++ b/man/LazyFrame_sort.Rd @@ -8,7 +8,7 @@ LazyFrame_sort(by, ..., descending = FALSE, nulls_last = FALSE) } \arguments{ \item{by}{Column(s) to sort by. Column name strings, character vector of -column names, or Iterable Into\if{html}{\out{}} (e.g. one Expr, or list mixed Expr and +column names, or Iterable \verb{Into} (e.g. one Expr, or list mixed Expr and column name strings).} \item{...}{more columns to sort by as above but provided one Expr per argument.} diff --git a/man/LazyGroupBy_print.Rd b/man/LazyGroupBy_print.Rd index acfab3b9d..7a28f59fe 100644 --- a/man/LazyGroupBy_print.Rd +++ b/man/LazyGroupBy_print.Rd @@ -6,6 +6,9 @@ \usage{ LazyGroupBy_print() } +\value{ +invisible self +} \description{ prints opaque groupby, not much to show } diff --git a/man/Series_class.Rd b/man/Series_class.Rd index 05c3d78e8..54c09eb3f 100644 --- a/man/Series_class.Rd +++ b/man/Series_class.Rd @@ -12,7 +12,7 @@ rust side. The S3 method \code{.DollarNames.Series} exposes all public \verb{$fo Most methods return another \code{Series}-class instance or similar which allows for method chaining. This class system in lack of a better name could be called "environment classes" and is the same class system extendr provides, except here there is both a public and private set of methods. For implementation -reasons, the private methods are external and must be called from polars:::.pr.$Series$methodname(), also +reasons, the private methods are external and must be called from \code{.pr$Series$methodname()}, also all private methods must take any self as an argument, thus they are pure functions. Having the private methods as pure functions solved/simplified self-referential complications. } @@ -23,12 +23,10 @@ into pure external functions in after-wrappers.R. In zzz.R (named zzz to be last are removed and replaced by any function prefixed \code{Series_}. } \examples{ -# see all exported methods -ls(polars:::Series) +pl$show_all_public_methods("Series") # see all private methods (not intended for regular use) -ls(polars:::.pr$Series) - +ls(.pr$Series) # make an object s = pl$Series(1:3) diff --git a/man/as.character.Series.Rd b/man/as.character.Series.Rd index 51b592d25..a49ecb050 100644 --- a/man/as.character.Series.Rd +++ b/man/as.character.Series.Rd @@ -9,9 +9,13 @@ \arguments{ \item{x}{Series} -\item{...}{Additional characters are ignored.} +\item{...}{Additional arguments are ignored.} -\item{str_length}{an integer. If specified,} +\item{str_length}{an integer. If specified, +utf8 or categorical type Series will be formatted to a string of this length.} +} +\value{ +character vector } \description{ as.character for polars Series diff --git a/man/as.list.Expr.Rd b/man/as.list.Expr.Rd index d9b8cb22f..36817f51e 100644 --- a/man/as.list.Expr.Rd +++ b/man/as.list.Expr.Rd @@ -11,6 +11,9 @@ \item{...}{not used} } +\value{ +One Expr wrapped in a list +} \description{ wraps an Expr in a list } diff --git a/man/cash-.pl_polars_env.Rd b/man/cash-.pl_polars_env.Rd deleted file mode 100644 index b2f7b498a..000000000 --- a/man/cash-.pl_polars_env.Rd +++ /dev/null @@ -1,15 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/after-wrappers.R -\name{$.pl_polars_env} -\alias{$.pl_polars_env} -\title{get public function from pl namespace/env} -\usage{ -\method{$}{pl_polars_env}(self, name) -} -\description{ -get public function from pl namespace/env -} -\details{ -This method if polars_optenv$debug_polars == TRUE will print what methods are called -} -\keyword{internal} diff --git a/man/cash-.private_polars_env.Rd b/man/cash-.private_polars_env.Rd deleted file mode 100644 index 3d118952c..000000000 --- a/man/cash-.private_polars_env.Rd +++ /dev/null @@ -1,15 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/after-wrappers.R -\name{$.private_polars_env} -\alias{$.private_polars_env} -\title{get private method from Class} -\usage{ -\method{$}{private_polars_env}(self, name) -} -\description{ -get private method from Class -} -\details{ -This method if polars_optenv$debug_polars == TRUE will print what methods are called -} -\keyword{internal} diff --git a/man/cash-set-.DataFrame.Rd b/man/cash-set-.DataFrame.Rd deleted file mode 100644 index 47227e61f..000000000 --- a/man/cash-set-.DataFrame.Rd +++ /dev/null @@ -1,60 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dataframe__frame.R -\name{$<-.DataFrame} -\alias{$<-.DataFrame} -\title{generic setter method} -\usage{ -\method{$}{DataFrame}(self, name) <- value -} -\arguments{ -\item{self}{DataFrame} - -\item{name}{name method/property to set} - -\item{value}{value to insert} -} -\value{ -value -} -\description{ -set value of properties of DataFrames -} -\details{ -settable polars object properties may appear to be R objects, but they are not. -See \verb{[[method_name]]} example -} -\examples{ -# For internal use -# is only activated for following methods of DataFrame -ls(polars:::DataFrame.property_setters) - -# specific use case for one object property 'columns' (names) -df = pl$DataFrame(iris) - -# get values -df$columns - -# set + get values -df$columns = letters[1:5] #<- is fine too -df$columns - -# Rstudio is not using the standard R code completion tool -# and it will backtick any special characters. It is possible -# to completely customize the R / Rstudio code completion except -# it will trigger Rstudio to backtick any completion! Also R does -# not support package isolated customization. - - -# Concrete example if tabbing on 'df$' the raw R suggestion is df$columns<- -# however Rstudio backticks it into df$`columns<-` -# to make life simple, this is valid polars syntax also, and can be used in fast scripting -df$`columns<-` = letters[5:1] - -# for stable code prefer e.g. df$columns = letters[5:1] - -# to see inside code of a property use the [[]] syntax instead -df[["columns"]] # to see property code, .pr is the internal polars api into rust polars -polars:::DataFrame.property_setters$columns # and even more obscure to see setter code - -} -\keyword{DataFrame} diff --git a/man/check_tz_to_result.Rd b/man/check_tz_to_result.Rd deleted file mode 100644 index a0f63bf85..000000000 --- a/man/check_tz_to_result.Rd +++ /dev/null @@ -1,31 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{check_tz_to_result} -\alias{check_tz_to_result} -\title{Verify correct time zone} -\usage{ -check_tz_to_result(tz, allow_null = TRUE) -} -\arguments{ -\item{tz}{time zone string or NULL} - -\item{allow_null}{bool, if TRUE accept NULL} -} -\value{ -a result object, with either a valid string or an Err -} -\description{ -Verify correct time zone -} -\examples{ -check_tz_to_result = polars:::check_tz_to_result # expose internal -# return Ok -check_tz_to_result("GMT") -check_tz_to_result(NULL) - -# return Err -check_tz_to_result("Alice") -check_tz_to_result(42) -check_tz_to_result(NULL, allow_null = FALSE) -} -\keyword{internal} diff --git a/man/clone_env_one_level_deep.Rd b/man/clone_env_one_level_deep.Rd deleted file mode 100644 index 4483dad0f..000000000 --- a/man/clone_env_one_level_deep.Rd +++ /dev/null @@ -1,51 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{clone_env_one_level_deep} -\alias{clone_env_one_level_deep} -\title{Clone env on level deep.} -\usage{ -clone_env_one_level_deep(env) -} -\arguments{ -\item{env}{an R environment.} -} -\value{ -shallow clone of R environment -} -\description{ -Clone env on level deep. -} -\details{ -Sometimes used in polars to produce different hashmaps(environments) containing -some of the same, but not all elements. - -environments are used for collections of methods and types. This function can be used to make -a parallel collection pointing to some of the same types. Simply copying an environment, does -apparently not spawn a new hashmap, and therefore the collections stay identical. -} -\examples{ - -fruit_env = new.env(parent = emptyenv()) -fruit_env$banana = TRUE -fruit_env$apple = FALSE - -env_1 = new.env(parent = emptyenv()) -env_1$fruit_env = fruit_env - -env_naive_copy = env_1 -env_shallow_clone = polars:::clone_env_one_level_deep(env_1) - -# modifying env_! -env_1$minerals = new.env(parent = emptyenv()) -env_1$fruit_env$apple = 42L - -# naive copy is fully identical to env_1, so copying it not much useful -ls(env_naive_copy) -# shallow copy env does not have minerals -ls(env_shallow_clone) - -# however shallow clone does subscribe to changes to fruits as they were there -# at time of cloning -env_shallow_clone$fruit_env$apple -} -\keyword{internal} diff --git a/man/construct_ProtoExprArray.Rd b/man/construct_ProtoExprArray.Rd deleted file mode 100644 index 7b9930d7e..000000000 --- a/man/construct_ProtoExprArray.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/expr__expr.R -\name{construct_ProtoExprArray} -\alias{construct_ProtoExprArray} -\title{construct proto Expr array from args} -\usage{ -construct_ProtoExprArray(...) -} -\arguments{ -\item{...}{any Expr or string} -} -\value{ -ProtoExprArray object -} -\description{ -construct proto Expr array from args -} -\examples{ -polars:::construct_ProtoExprArray(pl$col("Species"), "Sepal.Width") -} -\keyword{internal} diff --git a/man/docs_translations.Rd b/man/docs_translations.Rd index 32ce7ecf5..e7e63f38f 100644 --- a/man/docs_translations.Rd +++ b/man/docs_translations.Rd @@ -6,6 +6,9 @@ \format{ info } +\value{ +Not applicable +} \description{ #Comments for how the R and python world translates into polars: diff --git a/man/dot-DollarNames.DataFrame.Rd b/man/dot-DollarNames.DataFrame.Rd index 8392719ac..72edb94a6 100644 --- a/man/dot-DollarNames.DataFrame.Rd +++ b/man/dot-DollarNames.DataFrame.Rd @@ -11,6 +11,11 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec + +Doesn't return a value. This is used for autocompletion in RStudio. +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.Expr.Rd b/man/dot-DollarNames.Expr.Rd index e7efe5502..69be42422 100644 --- a/man/dot-DollarNames.Expr.Rd +++ b/man/dot-DollarNames.Expr.Rd @@ -11,6 +11,11 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec + +Doesn't return a value. This is used for autocompletion in RStudio. +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.GroupBy.Rd b/man/dot-DollarNames.GroupBy.Rd index 152a5a168..a2437f684 100644 --- a/man/dot-DollarNames.GroupBy.Rd +++ b/man/dot-DollarNames.GroupBy.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.LazyFrame.Rd b/man/dot-DollarNames.LazyFrame.Rd index 70e36ce9c..ff551cfb1 100644 --- a/man/dot-DollarNames.LazyFrame.Rd +++ b/man/dot-DollarNames.LazyFrame.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.PolarsBackgroundHandle.Rd b/man/dot-DollarNames.PolarsBackgroundHandle.Rd index e8f0550e5..3c2cb91d9 100644 --- a/man/dot-DollarNames.PolarsBackgroundHandle.Rd +++ b/man/dot-DollarNames.PolarsBackgroundHandle.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.RField.Rd b/man/dot-DollarNames.RField.Rd new file mode 100644 index 000000000..26534ec14 --- /dev/null +++ b/man/dot-DollarNames.RField.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/Field.R +\name{.DollarNames.RField} +\alias{.DollarNames.RField} +\title{auto complete $-access into a polars object} +\usage{ +\method{.DollarNames}{RField}(x, pattern = "") +} +\arguments{ +\item{x}{string name of an RField} + +\item{pattern}{code-stump as string to auto-complete} +} +\value{ +char vec + +Doesn't return a value. This is used for autocompletion in RStudio. +} +\description{ +called by the interactive R session internally +} +\keyword{internal} diff --git a/man/dot-DollarNames.RPolarsErr.Rd b/man/dot-DollarNames.RPolarsErr.Rd index 33a04ca49..853687c6a 100644 --- a/man/dot-DollarNames.RPolarsErr.Rd +++ b/man/dot-DollarNames.RPolarsErr.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.Series.Rd b/man/dot-DollarNames.Series.Rd index 9a0083837..90b93a498 100644 --- a/man/dot-DollarNames.Series.Rd +++ b/man/dot-DollarNames.Series.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.VecDataFrame.Rd b/man/dot-DollarNames.VecDataFrame.Rd index 37177d181..b23482d77 100644 --- a/man/dot-DollarNames.VecDataFrame.Rd +++ b/man/dot-DollarNames.VecDataFrame.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.When.Rd b/man/dot-DollarNames.When.Rd index 9ffd048f0..c74583722 100644 --- a/man/dot-DollarNames.When.Rd +++ b/man/dot-DollarNames.When.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.WhenThen.Rd b/man/dot-DollarNames.WhenThen.Rd index 2c9111763..15fe32a61 100644 --- a/man/dot-DollarNames.WhenThen.Rd +++ b/man/dot-DollarNames.WhenThen.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.WhenThenThen.Rd b/man/dot-DollarNames.WhenThenThen.Rd index ad772f87b..ca8d42339 100644 --- a/man/dot-DollarNames.WhenThenThen.Rd +++ b/man/dot-DollarNames.WhenThenThen.Rd @@ -11,6 +11,9 @@ \item{pattern}{code-stump as string to auto-complete} } +\value{ +char vec +} \description{ called by the interactive R session internally } diff --git a/man/dot-DollarNames.method_environment.Rd b/man/dot-DollarNames.method_environment.Rd new file mode 100644 index 000000000..9e0a4a59a --- /dev/null +++ b/man/dot-DollarNames.method_environment.Rd @@ -0,0 +1,22 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/zzz.R +\name{.DollarNames.method_environment} +\alias{.DollarNames.method_environment} +\title{auto complete $-access into a polars object} +\usage{ +\method{.DollarNames}{method_environment}(x, pattern = "") +} +\arguments{ +\item{x}{string, name of method in method_environment (sub-namespace)} + +\item{pattern}{code-stump as string to auto-complete} +} +\value{ +char vec + +Doesn't return a value. This is used for autocompletion in RStudio. +} +\description{ +called by the interactive R session internally +} +\keyword{internal} diff --git a/man/dot-DollarNames.polars_option_list.Rd b/man/dot-DollarNames.polars_option_list.Rd new file mode 100644 index 000000000..2143c8257 --- /dev/null +++ b/man/dot-DollarNames.polars_option_list.Rd @@ -0,0 +1,20 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/options.R +\name{.DollarNames.polars_option_list} +\alias{.DollarNames.polars_option_list} +\title{auto complete $-access into a polars object} +\usage{ +\method{.DollarNames}{polars_option_list}(x, pattern = "") +} +\arguments{ +\item{x}{string name of an option} + +\item{pattern}{code-stump as string to auto-complete} +} +\value{ +char vec +} +\description{ +called by the interactive R session internally +} +\keyword{internal} diff --git a/man/dot-pr.Rd b/man/dot-pr.Rd index 9881308e8..8bab5a836 100644 --- a/man/dot-pr.Rd +++ b/man/dot-pr.Rd @@ -5,19 +5,30 @@ \alias{.pr} \title{polars-API: private calls to rust-polars} \format{ -An object of class \code{environment} of length 17. +An object of class \code{environment} of length 19. } \usage{ .pr } +\value{ +not applicable +} \description{ \code{.pr} Original extendr bindings converted into pure functions } +\details{ +.pr gives access to all private methods of package polars. Use at own discretion. +The polars package may introduce breaking changes to any private method in a patch with no +deprecation warning. Most private methods takes \code{self} as a first argument, the object the +method should be called upon. +} \examples{ # .pr$DataFrame$print() is an external function where self is passed as arg -polars:::.pr$DataFrame$print(self = pl$DataFrame(iris)) -polars:::print_env(.pr, ".pr the collection of private method calls to rust-polars") +.pr$DataFrame$print(self = pl$DataFrame(iris)) + +# show all content of .pr +.pr$print_env(.pr, ".pr the collection of private method calls to rust-polars") } \keyword{api_private} \keyword{internal} diff --git a/man/extendr_method_to_pure_functions.Rd b/man/extendr_method_to_pure_functions.Rd deleted file mode 100644 index 4a3c89885..000000000 --- a/man/extendr_method_to_pure_functions.Rd +++ /dev/null @@ -1,23 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/after-wrappers.R -\name{extendr_method_to_pure_functions} -\alias{extendr_method_to_pure_functions} -\title{extendr methods into pure functions} -\usage{ -extendr_method_to_pure_functions(env, class_name = NULL) -} -\arguments{ -\item{env}{environment object output from extendr-wrappers.R classes} - -\item{class_name}{optional class string, only used for debug printing -Default NULL, will infer class_name automatically} -} -\value{ -env of pure function calls to rust -} -\description{ -self is a global of extendr wrapper methods -this function copies the function into a new environment and -modify formals to have a self argument -} -\keyword{internal} diff --git a/man/extra_auto_completion.Rd b/man/extra_auto_completion.Rd index 128818891..e101ddc9b 100644 --- a/man/extra_auto_completion.Rd +++ b/man/extra_auto_completion.Rd @@ -6,6 +6,9 @@ \arguments{ \item{activate}{bool default TRUE, enable chained auto-completion} } +\value{ +invisible NULL +} \description{ Extra polars auto completion } diff --git a/man/get_method_usages.Rd b/man/get_method_usages.Rd deleted file mode 100644 index 923e10492..000000000 --- a/man/get_method_usages.Rd +++ /dev/null @@ -1,26 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{get_method_usages} -\alias{get_method_usages} -\title{Generate autocompletion suggestions for object} -\usage{ -get_method_usages(env, pattern = "") -} -\arguments{ -\item{env}{environment to extract usages from} - -\item{pattern}{string passed to ls(pattern) to subset methods by pattern} -} -\value{ -method usages -} -\description{ -Generate autocompletion suggestions for object -} -\details{ -used internally for auto completion in .DollarNames methods -} -\examples{ -polars:::get_method_usages(polars:::DataFrame, pattern = "col") -} -\keyword{internal} diff --git a/man/is_DataFrame_data_input.Rd b/man/is_DataFrame_data_input.Rd deleted file mode 100644 index 74dbdf31d..000000000 --- a/man/is_DataFrame_data_input.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/dataframe__frame.R -\name{is_DataFrame_data_input} -\alias{is_DataFrame_data_input} -\title{Validate data input for create Dataframe with pl$DataFrame} -\usage{ -is_DataFrame_data_input(x) -} -\arguments{ -\item{x}{any R object to test if suitable as input to DataFrame} -} -\value{ -bool -} -\description{ -The Dataframe constructors accepts data.frame inheritors or list of vectors and/or Series. -} -\examples{ -polars:::is_DataFrame_data_input(iris) -polars:::is_DataFrame_data_input(list(1:5, pl$Series(1:5), letters[1:5])) -} diff --git a/man/is_polars_dtype.Rd b/man/is_polars_dtype.Rd deleted file mode 100644 index 3d2e440e5..000000000 --- a/man/is_polars_dtype.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/datatype.R -\name{is_polars_dtype} -\alias{is_polars_dtype} -\title{check if x is a valid RPolarsDataType} -\usage{ -is_polars_dtype(x, include_unknown = FALSE) -} -\arguments{ -\item{x}{a candidate} -} -\value{ -a list DataType with an inner DataType -} -\description{ -check if x is a valid RPolarsDataType -} -\examples{ -polars:::is_polars_dtype(pl$Int64) -} -\keyword{internal} diff --git a/man/is_schema.Rd b/man/is_schema.Rd index 4ece08658..80335ac8d 100644 --- a/man/is_schema.Rd +++ b/man/is_schema.Rd @@ -19,8 +19,7 @@ bool check if schema } \examples{ -polars:::is_schema(pl$DataFrame(iris)$schema) pl$is_schema(pl$DataFrame(iris)$schema) -polars:::is_schema(list("alice", "bob")) - +pl$is_schema(list("alice", "bob")) } +\keyword{functions} diff --git a/man/knit_print.DataFrame.Rd b/man/knit_print.DataFrame.Rd index 51220d3a0..e40b335cb 100644 --- a/man/knit_print.DataFrame.Rd +++ b/man/knit_print.DataFrame.Rd @@ -11,6 +11,9 @@ knit_print.DataFrame(x, ...) \item{...}{additional arguments, not used} } +\value{ +invisible x or NULL +} \description{ Mimics python-polars' NotebookFormatter for HTML outputs. diff --git a/man/macro_add_syntax_check_to.Rd b/man/macro_add_syntax_check_to.Rd deleted file mode 100644 index 2ec917a7c..000000000 --- a/man/macro_add_syntax_check_to.Rd +++ /dev/null @@ -1,32 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/after-wrappers.R -\name{macro_add_syntax_check_to_class} -\alias{macro_add_syntax_check_to_class} -\title{add syntax verification to class} -\usage{ -macro_add_syntax_check_to_class(Class_name) -} -\arguments{ -\item{Class_name}{string name of env class} -} -\value{ -dollarsign method with syntax verification -} -\description{ -add syntax verification to class -} -\details{ -this function overrides dollarclass method of a extendr env_class -to run first verify_method_call() to check for syntax error and return -more user friendly error if issues - -All R functions coined 'macro'-functions use eval(parse()) but only at package build time -to solve some tricky self-referential problem. If possible to deprecate a macro in a clean way -, go ahead. - -see zzz.R for usage examples -} -\seealso{ -verify_method_call -} -\keyword{internal} diff --git a/man/macro_new_subnamespace.Rd b/man/macro_new_subnamespace.Rd deleted file mode 100644 index 1ce0f7139..000000000 --- a/man/macro_new_subnamespace.Rd +++ /dev/null @@ -1,63 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{macro_new_subnamespace} -\alias{macro_new_subnamespace} -\title{Macro - New subnamespace} -\usage{ -macro_new_subnamespace(class_pattern, subclass_env = NULL, remove_f = TRUE) -} -\arguments{ -\item{class_pattern}{regex to select functions} - -\item{subclass_env}{optional subclass of} - -\item{remove_f}{drop sourced functions from package ns after bundling into sub ns} -} -\value{ -A function which returns a subclass environment of bundled class functions. -} -\description{ -Bundle class methods into an environment (subname space) -} -\details{ -This function is used to emulate py-polars subnamespace-methods -All R functions coined 'macro_'-functions use eval(parse()) but only at package build time -to solve some tricky self-referential problem. If possible to deprecate a macro in a clean way -, go ahead. -} -\examples{ - -# macro_new_subnamespace() is not exported, export for this toy example -# macro_new_subnamespace = polars:::macro_new_subnamespace - -## define some new methods prefixed 'MyClass_' -# MyClass_add2 = function() self + 2 -# MyClass_mul2 = function() self * 2 - -## grab any sourced function prefixed 'MyClass_' -# my_class_sub_ns = macro_new_subnamespace("^MyClass_", "myclass_sub_ns") - -# here adding sub-namespace as a expr-class property/method during session-time, -# which only is for this demo. -# instead sourced method like Expr_arr() at package build time instead -# env = polars:::Expr #get env of the Expr Class -# env$my_sub_ns = method_as_property(function() { #add a property/method -# my_class_sub_ns(self) -# }) -# rm(env) #optional clean up - -# add user defined S3 method the subclass 'myclass_sub_ns' -# print.myclass_sub_ns = function(x, ...) { #add ... even if not used -# print("hello world, I'm myclass_sub_ns") -# print("methods in sub namespace are:") -# print(ls(x)) -# } - -# test -# e = pl$lit(1:5) #make an Expr -# print(e$my_sub_ns) #inspect -# e$my_sub_ns$add2() #use the sub namespace -# e$my_sub_ns$mul2() - -} -\keyword{internal} diff --git a/man/method_as_property.Rd b/man/method_as_property.Rd deleted file mode 100644 index a229b9141..000000000 --- a/man/method_as_property.Rd +++ /dev/null @@ -1,20 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/after-wrappers.R -\name{method_as_property} -\alias{method_as_property} -\title{Give a class method property behavior} -\usage{ -method_as_property(f, setter = FALSE) -} -\arguments{ -\item{f}{a function} - -\item{setter}{bool, if true a property method can be modified by user} -} -\value{ -function subclassed into c("property","function") or c("setter","property","function") -} -\description{ -Internal function, see use in source -} -\keyword{internal} diff --git a/man/move_env_elements.Rd b/man/move_env_elements.Rd deleted file mode 100644 index e78d77b02..000000000 --- a/man/move_env_elements.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{move_env_elements} -\alias{move_env_elements} -\title{Move environment elements from one env to another} -\usage{ -move_env_elements(from_env, to_env, element_names, remove = TRUE) -} -\arguments{ -\item{from_env}{env from} - -\item{to_env}{env to} - -\item{element_names}{names of elements to move, if named names, then name of name is to_env name} - -\item{remove}{bool, actually remove element in from_env} -} -\description{ -Move environment elements from one env to another -} -\keyword{internal} diff --git a/man/pcase.Rd b/man/pcase.Rd deleted file mode 100644 index e389845f3..000000000 --- a/man/pcase.Rd +++ /dev/null @@ -1,33 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{pcase} -\alias{pcase} -\title{Simple SQL CASE WHEN implementation for R} -\usage{ -pcase(..., or_else = NULL) -} -\arguments{ -\item{...}{odd arguments are bool statements, a next even argument is returned -if prior bool statement is the first true} - -\item{or_else}{return this if no bool statements were true} -} -\value{ -any return given first true bool statement otherwise value of or_else -} -\description{ -Inspired by data.table::fcase + dplyr::case_when. -Used instead of base::switch internally. -} -\details{ -Lifecycle: perhaps replace with something written in rust to speed up a bit -} -\examples{ -n = 7 -polars:::pcase( - n < 5, "nope", - n > 6, "yeah", - or_else = stopf("failed to have a case for n=\%s", n) -) -} -\keyword{internal} diff --git a/man/pl_dtypes.Rd b/man/pl_dtypes.Rd index 20705b11c..43282a69f 100644 --- a/man/pl_dtypes.Rd +++ b/man/pl_dtypes.Rd @@ -2,7 +2,10 @@ % Please edit documentation in R/datatype.R \name{pl_dtypes} \alias{pl_dtypes} -\title{DataTypes polars types} +\title{DataTypes (RPolarsDataType)} +\value{ +not applicable +} \description{ \code{DataType} any polars type (ported so far) } @@ -15,10 +18,6 @@ pl$List(pl$List(pl$UInt64)) pl$Struct(pl$Field("CityNames", pl$Utf8)) -# Some DataType use case, this user function fails because.... -\dontrun{ -pl$Series(1:4)$apply(\(x) letters[x]) -} # The function changes type from Integer(Int32)[Integers] to char(Utf8)[Strings] # specifying the output DataType: Utf8 solves the problem pl$Series(1:4)$apply(\(x) letters[x], datatype = pl$dtypes$Utf8) diff --git a/man/pl_pl.Rd b/man/pl_pl.Rd index 58ad1fe56..6830bf224 100644 --- a/man/pl_pl.Rd +++ b/man/pl_pl.Rd @@ -6,11 +6,14 @@ \alias{pl} \title{The complete polars public API.} \format{ -An object of class \code{pl_polars_env} (inherits from \code{environment}) of length 71. +An object of class \code{pl_polars_env} (inherits from \code{environment}) of length 73. } \usage{ pl } +\value{ +not applicable +} \description{ \code{pl}-object is a environment of all public functions and class constructors. Public functions are not exported as a normal package as it would be huge namespace @@ -27,13 +30,8 @@ bind the environment to another variable name as \code{simon_says = pl} or even # how to use polars via `pl` pl$col("colname")$sum() / pl$lit(42L) # expression ~ chain-method / literal-expression -# pl inventory -polars:::print_env(pl, "polars public functions") - -# all accessible classes and their public methods -polars:::print_env( - polars:::pl_pub_class_env, - "polars public class methods, access via object$method()" -) +# show all public functions, RPolarsDataTypes, classes and methods +pl$show_all_public_functions() +pl$show_all_public_methods() } \keyword{api} diff --git a/man/pl_std.Rd b/man/pl_std.Rd index b9832ccf4..e0e9afaf9 100644 --- a/man/pl_std.Rd +++ b/man/pl_std.Rd @@ -6,6 +6,9 @@ \arguments{ \item{ddof}{integer Delta Degrees of Freedom: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1.} } +\value{ +Expr or Series matching type of input column +} \description{ syntactic sugar for starting a expression with std } diff --git a/man/pl_var.Rd b/man/pl_var.Rd index 1431abf23..c2165f154 100644 --- a/man/pl_var.Rd +++ b/man/pl_var.Rd @@ -6,6 +6,9 @@ \arguments{ \item{ddof}{integer Delta Degrees of Freedom: the divisor used in the calculation is N - ddof, where N represents the number of elements. By default ddof is 1.} } +\value{ +Expr or Series matching type of input column +} \description{ syntactic sugar for starting a expression with var } diff --git a/man/object.Rd b/man/polars_class_object.Rd similarity index 69% rename from man/object.Rd rename to man/polars_class_object.Rd index 2fdd18b62..dbdeabf39 100644 --- a/man/object.Rd +++ b/man/polars_class_object.Rd @@ -1,14 +1,10 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/after-wrappers.R -\docType{data} -\name{object} -\alias{object} +\name{polars_class_object} +\alias{polars_class_object} \title{Any polars class object is made of this} -\format{ -An object of class \code{character} of length 1. -} -\usage{ -object +\value{ +not applicable } \description{ One SEXP of Rtype: "externalptr" + a class attribute @@ -22,8 +18,14 @@ See function macro_add_syntax_check_to_class(). } } \examples{ -# all a polars object is made of: +# all a polars object is only made of: some_polars_object = pl$DataFrame(iris) str(some_polars_object) # External Pointer tagged with a class attribute. + +# All state is stored on rust side. + +# The single exception from the rule is class "GroupBy", where objects also have +# two private attributes "groupby_input" and "maintain_order". +str(pl$DataFrame(iris)$groupby("Species")) } \keyword{api_object} diff --git a/man/polars_runtime_flags.Rd b/man/polars_runtime_flags.Rd index 00c6e411c..8fd5f84db 100644 --- a/man/polars_runtime_flags.Rd +++ b/man/polars_runtime_flags.Rd @@ -11,6 +11,9 @@ An object of class \code{environment} of length 0. \usage{ runtime_state } +\value{ +not applicable +} \description{ This environment is used internally for the package to remember what has been going on. Currently only used to throw one-time warnings() diff --git a/man/print-open-paren-close-paren.Rd b/man/print.DataFrame.Rd similarity index 92% rename from man/print-open-paren-close-paren.Rd rename to man/print.DataFrame.Rd index 7941f44b3..530082500 100644 --- a/man/print-open-paren-close-paren.Rd +++ b/man/print.DataFrame.Rd @@ -1,7 +1,6 @@ % Generated by roxygen2: do not edit by hand % Please edit documentation in R/dataframe__frame.R -\name{print()} -\alias{print()} +\name{print.DataFrame} \alias{print.DataFrame} \title{s3 method print DataFrame} \usage{ diff --git a/man/print_env.Rd b/man/print_env.Rd index d7385217a..fbc0da103 100644 --- a/man/print_env.Rd +++ b/man/print_env.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/utils.R \name{print_env} \alias{print_env} -\title{print recursively an environment, used in some documentation} +\title{Print recursively an environment, used in some documentation} \usage{ print_env(api, name, max_depth = 10) } @@ -13,7 +13,10 @@ print_env(api, name, max_depth = 10) \item{max_depth}{numeric/int max levels to recursive iterate through} } +\value{ +Print recursively an environment to the console +} \description{ -print recursively an environment, used in some documentation +Print recursively an environment, used in some documentation } \keyword{internal} diff --git a/man/pstop.Rd b/man/pstop.Rd deleted file mode 100644 index 7473cee47..000000000 --- a/man/pstop.Rd +++ /dev/null @@ -1,24 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/rust_result.R -\name{pstop} -\alias{pstop} -\title{pstop} -\usage{ -pstop(err, call = sys.call(1L)) -} -\arguments{ -\item{err}{error msg string} - -\item{call}{calling context} -} -\value{ -throws an error -} -\description{ -DEPRECATED USE stopf instead -} -\examples{ -f = function() polars:::pstop("this aint right!!") -tryCatch(f(), error = \(e) as.character(e)) -} -\keyword{internal} diff --git a/man/result.Rd b/man/result.Rd deleted file mode 100644 index 44361ef0d..000000000 --- a/man/result.Rd +++ /dev/null @@ -1,40 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/error_conversion.R -\name{result} -\alias{result} -\title{Capture any R error and return a rust-like Result} -\usage{ -result(expr, msg = NULL) -} -\arguments{ -\item{expr}{code to capture any error from and wrap as Result} - -\item{msg}{handy way to add a context msg} -} -\value{ -Result -} -\description{ -Capture any R error and return a rust-like Result -} -\examples{ - -# user internal functions without using ::: -result = environment(polars::pl$all)$result -unwrap_err = environment(polars::pl$all)$unwrap_err -unwrap = environment(polars::pl$all)$unwrap -Err = environment(polars::pl$all)$Err - -# capture regular R errors or RPolarsErr -throw_simpleError = \() stop("Imma simple error") -result(throw_simpleError()) - -throw_RPolarsErr = \() unwrap( - Err(.pr$RPolarsErr$new()$bad_robj(42)$mistyped("String")$when("doing something")) -) -res_RPolarsErr = result(throw_RPolarsErr()) -str(res_RPolarsErr) -RPolarsErr = unwrap_err(res_RPolarsErr) -RPolarsErr$contexts() -} -\keyword{internal} diff --git a/man/scan_csv.Rd b/man/scan_csv.Rd index c4793df22..0a02d10d9 100644 --- a/man/scan_csv.Rd +++ b/man/scan_csv.Rd @@ -5,7 +5,7 @@ \alias{read_csv} \title{new LazyFrame from csv} \arguments{ -\item{path}{string, Path to a file} +\item{path}{string, Path to a file or URL} \item{sep}{Single char to use as delimiter in the file.} @@ -64,16 +64,15 @@ table scan will be done (slow).} \item{reuse_downloaded}{Boolean. If \code{TRUE}(default) and a URL was provided, cache the downloaded files in session for an easy reuse.} - -\item{...}{any argument passed to scan_csv} } \value{ -lazyframe +scan_csv returns a LazyFrame. read_csv returns a DataFrame. DataFrame } \description{ -will scan the csv when collect(), not now +will scan the csv when collect(), not now. +read_csv is a shortcut for scan_csv$collect(). } \details{ Read a file from path into a polars lazy frame. Not yet supporting eol_char and with_column_names @@ -84,6 +83,5 @@ write.csv(iris, my_file) lazy_frame = pl$scan_csv(path = my_file) lazy_frame$collect() unlink(my_file) -df = pl$read_csv("https://j.mp/iriscsv") } \keyword{LazyFrame_new} diff --git a/man/show_all_public_functions.Rd b/man/show_all_public_functions.Rd new file mode 100644 index 000000000..2938cd93d --- /dev/null +++ b/man/show_all_public_functions.Rd @@ -0,0 +1,12 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/after-wrappers.R +\name{show_all_public_functions} +\alias{show_all_public_functions} +\title{show all public functions / objects} +\description{ +print any object(function, RPolarsDataType) available via \verb{pl$}. +} +\examples{ +pl$show_all_public_functions() +} +\keyword{functions} diff --git a/man/show_all_public_methods.Rd b/man/show_all_public_methods.Rd new file mode 100644 index 000000000..83d4a7145 --- /dev/null +++ b/man/show_all_public_methods.Rd @@ -0,0 +1,15 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/after-wrappers.R +\name{show_all_public_methods} +\alias{show_all_public_methods} +\title{show all public methods} +\arguments{ +\item{class_names}{character vector of polars class names to show, Default NULL is all.} +} +\description{ +methods are listed by their Class +} +\examples{ +pl$show_all_public_methods() +} +\keyword{functions} diff --git a/man/str_string.Rd b/man/str_string.Rd deleted file mode 100644 index 7cfe6b2a9..000000000 --- a/man/str_string.Rd +++ /dev/null @@ -1,23 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/utils.R -\name{str_string} -\alias{str_string} -\title{Simple viewer of an R object based on str()} -\usage{ -str_string(x, collapse = " ") -} -\arguments{ -\item{x}{object to view.} - -\item{collapse}{word to glue possible multilines with} -} -\value{ -string -} -\description{ -Simple viewer of an R object based on str() -} -\examples{ -polars:::str_string(list(a = 42, c(1, 2, 3, NA))) -} -\keyword{internal} diff --git a/man/unwrap.Rd b/man/unwrap.Rd deleted file mode 100644 index 35869bd23..000000000 --- a/man/unwrap.Rd +++ /dev/null @@ -1,39 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/error_conversion.R -\name{unwrap} -\alias{unwrap} -\title{rust-like unwrapping of result. Useful to keep error handling on the R side.} -\usage{ -unwrap(result, context = NULL, call = sys.call(1L)) -} -\arguments{ -\item{result}{a list here either element ok or err is NULL, or both if ok is litteral NULL} - -\item{context}{a msg to prefix a raised error with} - -\item{call}{context of error or string} -} -\value{ -the ok-element of list , or a error will be thrown -} -\description{ -rust-like unwrapping of result. Useful to keep error handling on the R side. -} -\examples{ - -# get unwrap without using ::: -unwrap = environment(polars::pl$all)$unwrap - -structure(list(ok = "foo", err = NULL), class = "extendr_result") - -tryCatch( - unwrap( - structure( - list(ok = NULL, err = "something happen on the rust side"), - class = "extendr_result" - ) - ), - error = function(err) as.character(err) -) -} -\keyword{internal} diff --git a/man/unwrap_err.Rd b/man/unwrap_err.Rd deleted file mode 100644 index 2a1b50e7f..000000000 --- a/man/unwrap_err.Rd +++ /dev/null @@ -1,21 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/error_conversion.R -\name{unwrap_err} -\alias{unwrap_err} -\title{rust-like unwrap_err, internal use only} -\usage{ -unwrap_err(result) -} -\arguments{ -\item{result}{a Result, see rust_result.R#'} -} -\value{ -some error type -} -\description{ -rust-like unwrap_err, internal use only -} -\details{ -throwed error info is sparse because only for internal errors -} -\keyword{internal} diff --git a/man/wrap_elist_result.Rd b/man/wrap_elist_result.Rd deleted file mode 100644 index 9b94bb113..000000000 --- a/man/wrap_elist_result.Rd +++ /dev/null @@ -1,28 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/expr__expr.R -\name{wrap_elist_result} -\alias{wrap_elist_result} -\title{internal wrap_elist_result} -\usage{ -wrap_elist_result(elist, str_to_lit = TRUE) -} -\arguments{ -\item{elist}{a list Expr or any R object Into\if{html}{\out{}} (passable to pl$lit)} -} -\value{ -Expr -} -\description{ -make sure all elements of a list is wrapped as Expr -DEPRECATED: prefer robj_to!(VecPlExpr) on rust side -Capture any conversion error in the result -} -\details{ -Used internally to ensure an object is a list of expression -The output is wrapped in a result, which can contain an ok or -err value. -} -\examples{ -polars:::wrap_elist_result(list(pl$lit(42), 42, 1:3)) -} -\keyword{internal} diff --git a/man/wrap_proto_schema.Rd b/man/wrap_proto_schema.Rd deleted file mode 100644 index 75384fb73..000000000 --- a/man/wrap_proto_schema.Rd +++ /dev/null @@ -1,27 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/datatype.R -\name{wrap_proto_schema} -\alias{wrap_proto_schema} -\title{wrap proto schema} -\format{ -function -} -\usage{ -wrap_proto_schema(x) -} -\arguments{ -\item{x}{either schema, or incomplete schema where dataType can be NULL -or schema is just char vec, implicitly the same as if all DataType are NULL, -mean undefined.} -} -\value{ -bool -} -\description{ -wrap proto schema -} -\examples{ -polars:::wrap_proto_schema(c("alice", "bob")) -polars:::wrap_proto_schema(list("alice" = pl$Int64, "bob" = NULL)) -} -\keyword{internal} diff --git a/src/rust/Cargo.toml b/src/rust/Cargo.toml index cd74236ba..85e6b81e9 100644 --- a/src/rust/Cargo.toml +++ b/src/rust/Cargo.toml @@ -20,9 +20,10 @@ mimalloc = { version = "0.1.34", default-features = false } jemallocator = { version = "0.5.0", features = ["disable_initial_exec_tls"] } -# use opt-level = 1 for argminmax package unless profile is profile.release-optimized for to support Rust < 1.66 +# use opt-level = 1 for argminmax package unless profile is profile.release-optimized to support Rust < 1.66 [profile.release-optimized] inherits = "release" + [profile.release.package.argminmax] opt-level = 1 [profile.release-optimized.package.argminmax] diff --git a/tests/testthat/_snaps/info.md b/tests/testthat/_snaps/info.md index b5bb6b6b3..e2dade0e6 100644 --- a/tests/testthat/_snaps/info.md +++ b/tests/testthat/_snaps/info.md @@ -3,7 +3,7 @@ Code info Output - R Polars package version: 0.6.1.9000 + R Polars package version: 999.999.999 Features: simd FALSE diff --git a/tests/testthat/test-csv.R b/tests/testthat/test-csv.R index 2f5115b7d..5fa7a0e76 100644 --- a/tests/testthat/test-csv.R +++ b/tests/testthat/test-csv.R @@ -2,19 +2,22 @@ test_that("csv read iris", { tmpf = tempfile() write.csv(iris, tmpf, row.names = FALSE) lf = pl$scan_csv(tmpf) - - df = lf$collect() + df = pl$read_csv(tmpf) iris_char = iris iris_char$Species = as.character(iris$Species) - testthat::expect_equal( + expect_equal( + lf$collect()$to_data_frame(), + iris_char + ) + expect_equal( df$to_data_frame(), iris_char ) # named dtype changed to categorical - testthat::expect_equal( + expect_equal( pl$scan_csv(tmpf, overwrite_dtype = list(Species = pl$Categorical))$collect()$to_data_frame(), iris ) diff --git a/tests/testthat/test-info.R b/tests/testthat/test-info.R index 81ffb196a..7450c34df 100644 --- a/tests/testthat/test-info.R +++ b/tests/testthat/test-info.R @@ -8,6 +8,10 @@ patrick::with_parameters_test_that("polars_info() features are logical", test_that("print pl$polars_info()", { info <- pl$polars_info() + + # Ensure static version for snapshot test + info$version <- package_version("999.999.999") + # Ensure all features are FALSE for snapshot test for (feature in names(info$features)) { info$features[[feature]] <- FALSE diff --git a/tests/testthat/test-minipolars_options.R b/tests/testthat/test-minipolars_options.R index 389b589cd..b0f01b46c 100644 --- a/tests/testthat/test-minipolars_options.R +++ b/tests/testthat/test-minipolars_options.R @@ -1,6 +1,6 @@ test_that("get options", { opts = pl$get_polars_options() - expect_equal(opts, as.list(polars:::polars_optenv)) + expect_equal(opts, as.list(.pr$env$polars_optenv)) }) diff --git a/vignettes/polars.Rmd b/vignettes/polars.Rmd index f95f720b5..db8d1bf01 100644 --- a/vignettes/polars.Rmd +++ b/vignettes/polars.Rmd @@ -220,7 +220,7 @@ dat$groupby("cyl")$mean() We can now start chaining together various methods (expressions) to manipulate it in different ways. For example, we can subset the data by rows -([`filter()`](https://rpolars.github.io/reference/filter-open-paren-close-paren/)) +([`filter()`](https://rpolars.github.io/reference/DataFrame_filter/)) and also columns ([`select()`](https://rpolars.github.io/reference/DataFrame_select/)): @@ -368,7 +368,7 @@ flights$join( ``` More information on the **polars** joining method can be found in the -[reference manual](https://rpolars.github.io/reference/DataFrame_join). +[reference manual](https://rpolars.github.io/reference/DataFrame_join/). The package supports many other data manipulation operations, which we won't cover here. Hopefully, you will already have a sense of the key syntax features. @@ -379,13 +379,12 @@ We now turn to another core idea of the Polars ecosystem: _lazy execution_. While the "eager" execution engine of **polars** works perfectly well---as evidenced by all of the previous examples---to get the most out of the package you need to go _lazy_. -[Lazy execution](https://pola-rs.github.io/polars-book/user-guide/lazy-api/) -enables several benefits, but the most important is that it improves +Lazy execution enables several benefits, but the most important is that it improves performance. Delaying execution until the last possible moment allows Polars to apply automatic optimization to every query. Let's take a quick look. To create a so-called -"[LazyFrame](https://rpolars.github.io/reference/LazyFrame_class)" from an +"[LazyFrame](https://rpolars.github.io/reference/LazyFrame_class/)" from an existing object in memory, we can invoke the `lazy()` constructor. ```{r}