From ded6d13e24be572c227617107622b643c20dd83f Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 05:54:27 +0000 Subject: [PATCH 01/15] test: add tests with timezones --- tests/testthat/test-as_polars.R | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/tests/testthat/test-as_polars.R b/tests/testthat/test-as_polars.R index 31288484c..e9f37ec5d 100644 --- a/tests/testthat/test-as_polars.R +++ b/tests/testthat/test-as_polars.R @@ -401,6 +401,20 @@ patrick::with_parameters_test_that("clock package class support", as.POSIXct(as.vector(pl_sys_time), tz = "Asia/Kolkata"), as.POSIXct(clock_sys_time, tz = "Asia/Kolkata") ) + + # Test on other time zone + withr::with_envvar( + new = c(TZ = "Europe/Paris"), + { + expect_equal(as.POSIXct(as.vector(pl_naive_time)), as.POSIXct(clock_naive_time)) + expect_equal(as.POSIXct(as.vector(pl_zoned_time_1)), as.POSIXct(clock_zoned_time_1)) + expect_equal(as.POSIXct(as.vector(pl_sys_time)), as.POSIXct(clock_sys_time, tz = "UTC")) + expect_equal( + as.POSIXct(as.vector(pl_sys_time), tz = "Asia/Kolkata"), + as.POSIXct(clock_sys_time, tz = "Asia/Kolkata") + ) + } + ) }, precision = c("nanosecond", "microsecond", "millisecond", "second", "minute", "hour", "day"), .test_name = precision From 7dab2d982166607c09e5919856acbde364c0d8c8 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 06:32:41 +0000 Subject: [PATCH 02/15] fix!: naive time -> POSIXct --- src/rust/src/conversion_s_to_r.rs | 35 ++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/src/rust/src/conversion_s_to_r.rs b/src/rust/src/conversion_s_to_r.rs index d99e482b9..848ef2264 100644 --- a/src/rust/src/conversion_s_to_r.rs +++ b/src/rust/src/conversion_s_to_r.rs @@ -1,8 +1,9 @@ -use crate::rdataframe::RPolarsDataFrame; +use crate::{rdataframe::RPolarsDataFrame, robj_to}; use extendr_api::prelude::*; use pl::PolarsError as pl_error; use polars::prelude::{self as pl}; use polars_core::datatypes::DataType; +use polars_lazy::{dsl::col, frame::IntoLazy}; //TODO throw a warning if i32 contains a lowerbound value which is the NA in R. pub fn pl_series_to_list( @@ -212,9 +213,31 @@ pub fn pl_series_to_list( pl::TimeUnit::Milliseconds => 1_000.0, }; - //resolve timezone - let tz = opt_tz.as_ref().map(|s| s.as_str()).unwrap_or(""); - s.cast(&Float64)? + let zoned_s: pl::Series = match opt_tz { + Some(_tz) => { + // zoned time + s.clone() + } + None => { + // naive time + let sys_tz_robj = R!("Sys.timezone()") + .map_err(|err| pl::PolarsError::ComputeError(err.to_string().into()))?; + let sys_tz = robj_to!(String, sys_tz_robj) + .map_err(|err| pl::PolarsError::ComputeError(err.to_string().into()))?; + let s_name = s.name(); + pl::DataFrame::new(vec![s.clone()])? + .lazy() + .select([col(s_name) + .dt() + .replace_time_zone(Some(sys_tz), pl::lit("raise"))]) + .collect()? + .column(s_name)? + .clone() + } + }; + + zoned_s + .cast(&Float64)? .f64() .map(|ca| { ca.into_iter() @@ -226,7 +249,9 @@ pub fn pl_series_to_list( robj.set_class(&["POSIXct", "POSIXt"]) .expect("internal error: class POSIXct label failed") }) - .map(|mut robj| robj.set_attrib("tzone", tz)) + .map(|mut robj| { + robj.set_attrib("tzone", opt_tz.as_ref().map(|s| s.as_str()).unwrap_or("")) + }) .expect("internal error: attr tzone failed") .map_err(|err| { pl_error::ComputeError( From dea8554631deea6f1e26f260117ae5b4b1a04529 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 07:53:22 +0000 Subject: [PATCH 03/15] fix!: POSIXct without tzone -> Polars datetime --- src/rust/src/conversion_r_to_s.rs | 43 ++++++++++++++++++++++++++++--- 1 file changed, 39 insertions(+), 4 deletions(-) diff --git a/src/rust/src/conversion_r_to_s.rs b/src/rust/src/conversion_r_to_s.rs index d5aeb31fe..39504308b 100644 --- a/src/rust/src/conversion_r_to_s.rs +++ b/src/rust/src/conversion_r_to_s.rs @@ -1,3 +1,4 @@ +use crate::robj_to; use crate::series::RPolarsSeries; use crate::utils::collect_hinted_result; use extendr_api::prelude::*; @@ -6,6 +7,8 @@ use extendr_api::prelude::*; use polars::prelude as pl; use polars::prelude::IntoSeries; use polars::prelude::NamedFrom; +use polars_lazy::dsl::col; +use polars_lazy::frame::IntoLazy; // Internal tree structure to contain Series of fully parsed nested Robject. // It is easier to resolve concatenated datatype after all elements have been parsed // because empty lists have no type in R, but the corrosponding polars type must be known before @@ -210,10 +213,42 @@ fn recursive_robjname2series_tree(x: &Robj, name: &str) -> pl::PolarsResult { + Ok(SeriesTree::Series( + (s * 1_000f64).cast(&pl::DataType::Int64)?.cast( + &pl::DataType::Datetime(pl::TimeUnit::Milliseconds, Some(tz)), + )?, + )) + } + // sys time + None => { + let sys_tz_robj = R!("Sys.timezone()") + .map_err(|err| pl::PolarsError::ComputeError(err.to_string().into()))?; + let sys_tz = robj_to!(String, sys_tz_robj) + .map_err(|err| pl::PolarsError::ComputeError(err.to_string().into()))?; + let s_name = s.name(); + let utc_s = (s.clone() * 1_000f64).cast(&pl::DataType::Int64)?.cast( + &pl::DataType::Datetime( + pl::TimeUnit::Milliseconds, + Some("UTC".to_string()), + ), + )?; + Ok(SeriesTree::Series( + pl::DataFrame::new(vec![utc_s.clone()])? + .lazy() + .select([col(s_name) + .dt() + .convert_time_zone(sys_tz) + .dt() + .replace_time_zone(None, pl::lit("raise"))]) + .collect()? + .column(s_name)? + .clone(), + )) + } + } } Ok(SeriesTree::Series(s)) if x.inherits("Date") => { Ok(SeriesTree::Series(s.cast(&pl::DataType::Date)?)) From fc27c433888bc9d3092ec7eae190028a94ca1883 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 09:11:03 +0000 Subject: [PATCH 04/15] test: rewrite tests for pl$date_range --- tests/testthat/test-expr_datetime.R | 43 ++++++++++++----------------- 1 file changed, 17 insertions(+), 26 deletions(-) diff --git a/tests/testthat/test-expr_datetime.R b/tests/testthat/test-expr_datetime.R index 6652b7a6e..13e2cf303 100644 --- a/tests/testthat/test-expr_datetime.R +++ b/tests/testthat/test-expr_datetime.R @@ -134,32 +134,23 @@ test_that("pl$date_range lazy ", { test_that("pl$date_range Date lazy/eager", { - r_vers = paste(unlist(R.version[c("major", "minor")]), collapse = ".") - if (r_vers >= "4.3.0") { - d1 = as.Date("2022-01-01") - s_d = pl$Series(d1, name = "Date") - s_dt = pl$Series(as.POSIXct(d1), name = "Date") # since R4.3 this becomes UTC timezone - df = pl$DataFrame(Date = d1)$to_series() - dr_e = pl$date_range(d1, d1 + 1, interval = "6h") - dr_l = pl$date_range(d1, d1 + 1, interval = "6h", eager = FALSE) - expect_identical(as.POSIXct(s_d$to_r()) |> "attr<-"("tzone", "UTC"), s_dt$to_r()) - expect_identical(d1, s_d$to_r()) - expect_identical(d1, df$to_r()) - expect_identical(s_dt$to_r(), dr_e$to_r()[1] |> "attr<-"("tzone", "UTC")) - expect_identical(s_dt$to_r(), dr_l$to_r()[1] |> "attr<-"("tzone", "UTC")) - } else { - d1 = as.Date("2022-01-01") - s_d = pl$Series(d1, name = "Date") - s_dt = pl$Series(as.POSIXct(d1), name = "Date") - df = pl$DataFrame(Date = d1)$to_series() - dr_e = pl$date_range(d1, d1 + 1, interval = "6h") - dr_l = pl$date_range(d1, d1 + 1, interval = "6h", eager = FALSE) - expect_identical(as.POSIXct(s_d$to_r()) |> "attr<-"("tzone", ""), s_dt$to_r()) - expect_identical(d1, s_d$to_r()) - expect_identical(d1, df$to_r()) - expect_identical(s_dt$to_r(), dr_e$to_r()[1]) - expect_identical(s_dt$to_r(), dr_l$to_r()[1]) - } + d_chr = "2022-01-01" + d_plus1_chr = "2022-01-02" + d_date = as.Date(d_chr) + s_d = pl$Series(d_date) + s_dt = pl$Series(as.POSIXct(d_chr)) + df = pl$DataFrame(Date = d_date)$to_series() + + dr_e = pl$date_range(d_date, d_date + 1, interval = "6h", eager = TRUE) + dr_l = pl$date_range(d_date, d_date + 1, interval = "6h", eager = FALSE) + + expect_identical(dr_e$to_r()[1], s_dt$to_r()) + expect_identical(rev(dr_e$to_r())[1], as.POSIXct(d_plus1_chr)) + expect_identical(dr_e$len(), 5) + + expect_identical(dr_l$to_r()[1], s_dt$to_r()) + expect_identical(rev(dr_l$to_r())[1], as.POSIXct(d_plus1_chr)) + expect_identical(dr_l$to_series()$len(), 5) }) From 3f5b821d24d6b9f2341e2803061b6c3fe568d83d Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 09:17:31 +0000 Subject: [PATCH 05/15] test: update the test case for the new behaver --- tests/testthat/test-expr_datetime.R | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/tests/testthat/test-expr_datetime.R b/tests/testthat/test-expr_datetime.R index 13e2cf303..b34d1aa21 100644 --- a/tests/testthat/test-expr_datetime.R +++ b/tests/testthat/test-expr_datetime.R @@ -12,7 +12,11 @@ test_that("pl$date_range", { ) expect_identical( pl$date_range(start = t1, end = t2, interval = "6h", time_zone = "GMT")$to_r(), - seq(t1, t2, by = as.difftime(6, units = "hours")) |> "attr<-"("tzone", "GMT") + seq( + as.POSIXct("2022-01-01", tz = "GMT"), + as.POSIXct("2022-01-02", tz = "GMT"), + by = as.difftime(6, units = "hours") + ) ) expect_identical( pl$date_range(start = t1, end = t2, interval = "3h", time_unit = "ms")$to_r(), From 5c4103c4c2cb8a25e94209f91a98513333606497 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 09:53:57 +0000 Subject: [PATCH 06/15] test: add more sys-time tests --- tests/testthat/test-datatype.R | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/tests/testthat/test-datatype.R b/tests/testthat/test-datatype.R index 44664cd92..dc544a7f7 100644 --- a/tests/testthat/test-datatype.R +++ b/tests/testthat/test-datatype.R @@ -38,6 +38,26 @@ test_that("POSIXct data conversion", { as.POSIXct("2022-01-01") ) + withr::with_envvar( + new = c(TZ = "America/New_York"), + { + non_exsitent_time_chr = "2020-03-08 02:00:00" + ambiguous_time_chr = "2020-11-01 01:00:00" + expect_identical( + pl$lit(as.POSIXct(non_exsitent_time_chr))$to_r(), + as.POSIXct(non_exsitent_time_chr) + ) + expect_error( + pl$lit(non_exsitent_time_chr)$str$strptime(pl$Datetime(), "%F %T")$to_r(), + "non-existent" + ) + expect_error( + pl$lit(ambiguous_time_chr)$str$strptime(pl$Datetime(), "%F %T")$to_r(), + "ambiguous" + ) + } + ) + expect_identical( pl$lit(as.POSIXct("2022-01-01", tz = "GMT"))$to_r(), as.POSIXct("2022-01-01", tz = "GMT") From 8b96bcbeaa8c6a0e495140c257054e093bcf6649 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 10:59:38 +0000 Subject: [PATCH 07/15] docs(news): update news --- NEWS.md | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) diff --git a/NEWS.md b/NEWS.md index 227efa524..c62a643b2 100644 --- a/NEWS.md +++ b/NEWS.md @@ -32,6 +32,77 @@ (either lexical or physical). This also means that calling `pl$Categorical` doesn't create a `DataType` anymore. All calls to `pl$Categorical` must be replaced by `pl$Categorical()` (#860). +- The conversion strategy between the POSIXct type without time zone attribute + and Polars datetime has been changed (#878). + `POSIXct` class vectors without a time zone attribute have UTC time internally + and is displayed based on the system's time zone. Previous versions of `polars` + only considered the internal value and interpreted it as UTC time, so the + time displayed as `POSIXct` and in Polars was different. + + ```r + # polars 0.14.1 + Sys.setenv(TZ = "Europe/Paris") + datetime = as.POSIXct("1900-01-01") + datetime + #> [1] "1900-01-01 PMT" + + s = polars::as_polars_series(datetime) + s + #> polars Series: shape: (1,) + #> Series: '' [datetime[ms]] + #> [ + #> 1899-12-31 23:50:39 + #> ] + + as.vector(s) + #> [1] "1900-01-01 PMT" + ``` + + Now the internal value is updated to match the displayed value. + + ```r + # polars 0.15.0 + Sys.setenv(TZ = "Europe/Paris") + datetime = as.POSIXct("1900-01-01") + datetime + #> [1] "1900-01-01 PMT" + + s = polars::as_polars_series(datetime) + s + #> polars Series: shape: (1,) + #> Series: '' [datetime[ms]] + #> [ + #> 1900-01-01 00:00:00 + #> ] + + as.vector(s) + #> [1] "1900-01-01 PMT" + ``` + + This update may cause errors when converting from Polars to `POSIXct` for non-existent + or ambiguous times. It is recommended to explicitly add a time zone before converting + from Polars to R. + + ```r + Sys.setenv(TZ = "America/New_York") + ambiguous_time = as.POSIXct("2020-11-01 01:00:00") + ambiguous_time + #> [1] "2020-11-01 01:00:00 EDT" + + pls = polars::as_polars_series(ambiguous_time) + pls + #> polars Series: shape: (1,) + #> Series: '' [datetime[ms]] + #> [ + #> 2020-11-01 01:00:00 + #> ] + + ## This will be error! + # pls |> as.vector() + + pls$dt$replace_time_zone("UTC") |> as.vector() + #> [1] "2020-11-01 01:00:00 UTC" + ``` ### New features From f6881aafc329670a5aa351b5f02512af64ab6617 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 13:34:16 +0000 Subject: [PATCH 08/15] test: add more tests --- tests/testthat/test-datatype.R | 44 ++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 13 deletions(-) diff --git a/tests/testthat/test-datatype.R b/tests/testthat/test-datatype.R index dc544a7f7..26d2d1c50 100644 --- a/tests/testthat/test-datatype.R +++ b/tests/testthat/test-datatype.R @@ -38,9 +38,31 @@ test_that("POSIXct data conversion", { as.POSIXct("2022-01-01") ) + expect_identical( + pl$lit("2022-01-01")$str$strptime(pl$Datetime(), "%F")$to_r(), + as.POSIXct("2022-01-01") + ) + # TODO: infer timezone from string, change the arugment name from `tz` + expect_true( + pl$Series("2022-01-01 UTC")$str$strptime(pl$Datetime(tz = "UTC"), "%F %Z")$eq( + pl$Series(as.POSIXct("2022-01-01", tz = "UTC")) + )$to_r() + ) + withr::with_envvar( new = c(TZ = "America/New_York"), { + expect_identical( + pl$lit("2022-01-01")$str$strptime(pl$Datetime(), "%F")$to_r(), + as.POSIXct("2022-01-01") + ) + # TODO: infer timezone from string, change the arugment name from `tz` + expect_true( + pl$Series("2022-01-01 UTC")$str$strptime(pl$Datetime(tz = "UTC"), "%F %Z")$eq( + pl$Series(as.POSIXct("2022-01-01", tz = "UTC")) + )$to_r() + ) + non_exsitent_time_chr = "2020-03-08 02:00:00" ambiguous_time_chr = "2020-11-01 01:00:00" expect_identical( @@ -68,21 +90,17 @@ test_that("POSIXct data conversion", { as.POSIXct("2022-01-01", tz = "HST") ) + # POSIXct is converted to datetime[ms], so sub-ms precision is lost expect_identical( - pl$lit(as.POSIXct("2022-01-01", tz = "GMT"))$to_r(), - as.POSIXct("2022-01-01", tz = "GMT") + pl$lit(as.POSIXct( + c( + "2020-01-01 13:45:48.343", + "2020-01-01 13:45:48.343999" + ), + tz = "UTC" + ))$to_r(), + as.POSIXct(c("2020-01-01 13:45:48.343", "2020-01-01 13:45:48.343"), tz = "UTC") ) - - - x = as.POSIXct( - c( - "2020-01-01 13:45:48.343", - "2020-01-01 13:45:48.343999" - ), - tz = "UTC" - ) - # POSIXct is converted to datetime[ms], so sub-ms precision is lost - expect_identical(pl$lit(x)$to_r(), as.POSIXct(c("2020-01-01 13:45:48.343", "2020-01-01 13:45:48.343"), tz = "UTC")) }) test_that("String and Utf8 are identical", { From da5d552fde29055f57d6eb034d41cee46b2f90d4 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 14:01:35 +0000 Subject: [PATCH 09/15] test: clean up some tests --- tests/testthat/test-expr_datetime.R | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/tests/testthat/test-expr_datetime.R b/tests/testthat/test-expr_datetime.R index 19afd7bd5..379d8e25b 100644 --- a/tests/testthat/test-expr_datetime.R +++ b/tests/testthat/test-expr_datetime.R @@ -112,32 +112,24 @@ test_that("dt$truncate", { }) -test_that("pl$date_range lazy ", { +test_that("pl$date_range", { t1 = ISOdate(2022, 1, 1, 0) t2 = ISOdate(2022, 1, 2, 0) - expect_identical( - pl$date_range(start = t1, end = t2, interval = "6h", time_zone = "GMT")$to_r(), - pl$date_range(start = t1, end = t2, interval = "6h", time_zone = "GMT")$to_r() - ) - - # check variations of lazy input gives same result df = pl$DataFrame( t1 = t1, t2 = t2 )$select( pl$date_range("t1", "t2", "6h")$alias("s1"), - pl$date_range("t1", "t2", "6h")$alias("s2"), - pl$date_range(pl$col("t1"), pl$col("t2"), "6h")$alias("s3"), - pl$date_range(t1, t2, "6h")$alias("s4") + pl$date_range(pl$col("t1"), pl$col("t2"), "6h")$alias("s2"), + pl$date_range(t1, t2, "6h")$alias("s3") ) l = df$to_list() expect_identical(l$s1, l$s2) expect_identical(l$s1, l$s3) - expect_identical(l$s1, l$s4) }) -test_that("pl$date_range Date lazy/eager", { +test_that("pl$date_range Date", { d_chr = "2022-01-01" d_plus1_chr = "2022-01-02" d_date = as.Date(d_chr) @@ -149,11 +141,7 @@ test_that("pl$date_range Date lazy/eager", { expect_identical(dr_e$to_r()[1], s_dt$to_r()) expect_identical(rev(dr_e$to_r())[1], as.POSIXct(d_plus1_chr)) - expect_identical(dr_e$len(), 5) - - expect_identical(dr_l$to_r()[1], s_dt$to_r()) - expect_identical(rev(dr_l$to_r())[1], as.POSIXct(d_plus1_chr)) - expect_identical(dr_l$to_series()$len(), 5) + expect_identical(dr_e$to_series()$len(), 5) }) From 7fbca2865bbb8cb80edde59effe0daa835783318 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 15:47:09 +0000 Subject: [PATCH 10/15] docs: add note about naive time v.s. POSIXct --- R/dataframe__frame.R | 19 ++++++++++++ R/expr__datetime.R | 53 ++++++++++++++++++++++++++------- R/lazyframe__lazy.R | 1 + R/s3_methods.R | 2 ++ R/series__series.R | 3 +- man/DataFrame_class.Rd | 20 +++++++++++++ man/DataFrame_to_data_frame.Rd | 20 +++++++++++++ man/DataFrame_to_list.Rd | 20 +++++++++++++ man/ExprDT_convert_time_zone.Rd | 53 ++++++++++++++++++++++++++------- man/LazyFrame_class.Rd | 20 +++++++++++++ man/S3_as.data.frame.Rd | 20 +++++++++++++ man/S3_as.vector.Rd | 20 +++++++++++++ man/Series_class.Rd | 20 +++++++++++++ man/Series_to_r.Rd | 20 +++++++++++++ 14 files changed, 270 insertions(+), 21 deletions(-) diff --git a/R/dataframe__frame.R b/R/dataframe__frame.R index b1380dfcc..7f5fddcec 100644 --- a/R/dataframe__frame.R +++ b/R/dataframe__frame.R @@ -60,6 +60,23 @@ #' #' `$width` returns the number of columns in the DataFrame. #' +#' @section Conversion to R data types considerations: +#' Polars objects, such as [the DataFrame class object][DataFrame_class] +#' can be converted to R objects via some way. For example, using the +#' [`as.data.frame()`][S3_as.data.frame] generic function. +#' When converting Polars objects to R objects, each type in the Polars object is +#' converted to an R type. +#' In some cases, an error may occur because the conversion is not appropriate. +#' In particular, there is a high possibility of an error when converting +#' a [Datetime][DataType_Datetime] type without a time zone. +#' A [Datetime][DataType_Datetime] type without a time zone in Polars is converted +#' to the [POSIXct] type in R, with taking into account the time zone in which +#' the R session is running (which can be checked with the [Sys.timezone()] +#' function). In this case, if ambiguous times are included, a conversion error +#' will occur. In such cases, change the session time zone using +#' [`Sys.setenv(TZ = "UTC")`][base::Sys.setenv] and then perform the conversion, or use the +#' [`$dt$replace_time_zone()`][ExprDT_replace_time_zone] method on the time type column to +#' explicitly specify the time zone before conversion. #' @details Check out the source code in #' [R/dataframe_frame.R](https://github.com/pola-rs/r-polars/blob/main/R/dataframe__frame.R) #' to see how public methods are derived from private methods. Check out @@ -885,6 +902,7 @@ DataFrame_group_by = function(..., maintain_order = polars_options()$maintain_or #' * `"string"` converts Int64 values to character. #' #' @return An R data.frame +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @keywords DataFrame #' @examples #' df = pl$DataFrame(iris[1:3, ]) @@ -917,6 +935,7 @@ DataFrame_to_data_frame = function(..., int64_conversion = polars_options()$int6 #' structure is not very typical or efficient in R. #' #' @return R list of vectors +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @keywords DataFrame #' @examples #' pl$DataFrame(iris)$to_list() diff --git a/R/expr__datetime.R b/R/expr__datetime.R index cda6dcb0f..2788594e8 100644 --- a/R/expr__datetime.R +++ b/R/expr__datetime.R @@ -652,19 +652,52 @@ ExprDT_cast_time_unit = function(tu = c("ns", "us", "ms")) { #' @aliases (Expr)$dt$convert_time_zone #' @examples #' df = pl$DataFrame( -#' date = pl$date_range( -#' start = as.Date("2001-3-1"), -#' end = as.Date("2001-5-1"), -#' interval = "1mo12m34s" -#' ) +#' london_timezone = pl$date_range( +#' as.POSIXct("2020-03-01", tz = "UTC"), +#' as.POSIXct("2020-07-01", tz = "UTC"), +#' "1mo", +#' time_zone = "UTC" +#' )$dt$convert_time_zone("Europe/London") #' ) +#' #' df$select( -#' pl$col("date"), -#' pl$col("date") -#' $dt$replace_time_zone("Europe/Amsterdam") -#' $dt$convert_time_zone("Europe/London") -#' $alias("London_with") +#' "london_timezone", +#' London_to_Amsterdam = pl$col( +#' "london_timezone" +#' )$dt$replace_time_zone("Europe/Amsterdam") +#' ) +#' +#' # You can use `ambiguous` to deal with ambiguous datetimes: +#' dates = c( +#' "2018-10-28 01:30", +#' "2018-10-28 02:00", +#' "2018-10-28 02:30", +#' "2018-10-28 02:00" +#' ) +#' +#' df = pl$DataFrame( +#' ts = pl$Series(dates)$str$strptime(pl$Datetime("us"), "%F %H:%M"), +#' ambiguous = c("earliest", "earliest", "latest", "latest") +#' ) +#' +#' df$with_columns( +#' ts_localized = pl$col("ts")$dt$replace_time_zone( +#' "Europe/Brussels", +#' ambiguous = pl$col("ambiguous") +#' ) #' ) +#' +#' # Polars Datetime type without a time zone will be converted to R +#' # with respect to the session time zone. If ambiguous times are present +#' # an error will be raised. It is recommended to add a time zone before +#' # converting to R. +#' s_without_tz = pl$Series(dates)$str$strptime(pl$Datetime("us"), "%F %H:%M") +#' s_without_tz +#' +#' s_with_tz = s_without_tz$dt$replace_time_zone("UTC") +#' s_with_tz +#' +#' as.vector(s_with_tz) ExprDT_convert_time_zone = function(tz) { check_tz_to_result(tz) |> map(\(valid_tz) .pr$Expr$dt_convert_time_zone(self, valid_tz)) |> diff --git a/R/lazyframe__lazy.R b/R/lazyframe__lazy.R index bbbae4ace..27308a874 100644 --- a/R/lazyframe__lazy.R +++ b/R/lazyframe__lazy.R @@ -46,6 +46,7 @@ #' #' `$width` returns the number of columns in the LazyFrame. #' +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @keywords LazyFrame #' @examples #' # see all exported methods diff --git a/R/s3_methods.R b/R/s3_methods.R index 8a2b8dd04..4cf78debe 100644 --- a/R/s3_methods.R +++ b/R/s3_methods.R @@ -255,6 +255,7 @@ dimnames.RPolarsLazyFrame = function(x) list(NULL, names(x)) #' @param x An object to convert to a [data.frame]. #' @param ... Additional arguments passed to methods. #' @inheritParams DataFrame_to_data_frame +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @seealso #' - [as_polars_df()] #' - [`$to_data_frame()`][DataFrame_to_data_frame] @@ -409,6 +410,7 @@ sum.RPolarsSeries = function(x, ...) x$sum() #' #' @param x A Polars Series #' @param mode Not used. +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @export #' @rdname S3_as.vector as.vector.RPolarsSeries = function(x, mode) x$to_vector() diff --git a/R/series__series.R b/R/series__series.R index 3c14f4845..8ff4ac4f6 100644 --- a/R/series__series.R +++ b/R/series__series.R @@ -88,6 +88,7 @@ #' #' `$struct` stores all struct related methods. #' +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @keywords Series #' #' @examples @@ -428,7 +429,7 @@ Series_compare = function(other, op) { #' @details #' Fun fact: Nested polars Series list must have same inner type, e.g. List(List(Int32)) #' Thus every leaf(non list type) will be placed on the same depth of the tree, and be the same type. -#' +#' @inheritSection DataFrame_class Conversion to R data types considerations #' @examples #' #' series_vec = pl$Series(letters[1:3]) diff --git a/man/DataFrame_class.Rd b/man/DataFrame_class.Rd index 2d54a867d..98bcbfb6c 100644 --- a/man/DataFrame_class.Rd +++ b/man/DataFrame_class.Rd @@ -84,6 +84,26 @@ the number of columns. } } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \examples{ # see all public exported method names (normally accessed via a class # instance with $) diff --git a/man/DataFrame_to_data_frame.Rd b/man/DataFrame_to_data_frame.Rd index 31aecb59f..77c040a7e 100644 --- a/man/DataFrame_to_data_frame.Rd +++ b/man/DataFrame_to_data_frame.Rd @@ -27,6 +27,26 @@ An R data.frame \description{ Return Polars DataFrame as R data.frame } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \examples{ df = pl$DataFrame(iris[1:3, ]) df$to_data_frame() diff --git a/man/DataFrame_to_list.Rd b/man/DataFrame_to_list.Rd index 3ae7b6ce9..c10df1ac4 100644 --- a/man/DataFrame_to_list.Rd +++ b/man/DataFrame_to_list.Rd @@ -37,6 +37,26 @@ before exporting to R. If \code{unnest_structs = FALSE}, then \code{struct} colu will be returned as nested lists, where each row is a list of values. Such a structure is not very typical or efficient in R. } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \examples{ pl$DataFrame(iris)$to_list() } diff --git a/man/ExprDT_convert_time_zone.Rd b/man/ExprDT_convert_time_zone.Rd index fc50cef48..27fae6770 100644 --- a/man/ExprDT_convert_time_zone.Rd +++ b/man/ExprDT_convert_time_zone.Rd @@ -22,18 +22,51 @@ corresponds to in R manually modifying the tzone attribute of POSIXt objects } \examples{ df = pl$DataFrame( - date = pl$date_range( - start = as.Date("2001-3-1"), - end = as.Date("2001-5-1"), - interval = "1mo12m34s" - ) + london_timezone = pl$date_range( + as.POSIXct("2020-03-01", tz = "UTC"), + as.POSIXct("2020-07-01", tz = "UTC"), + "1mo", + time_zone = "UTC" + )$dt$convert_time_zone("Europe/London") ) + df$select( - pl$col("date"), - pl$col("date") - $dt$replace_time_zone("Europe/Amsterdam") - $dt$convert_time_zone("Europe/London") - $alias("London_with") + "london_timezone", + London_to_Amsterdam = pl$col( + "london_timezone" + )$dt$replace_time_zone("Europe/Amsterdam") +) + +# You can use `ambiguous` to deal with ambiguous datetimes: +dates = c( + "2018-10-28 01:30", + "2018-10-28 02:00", + "2018-10-28 02:30", + "2018-10-28 02:00" +) + +df = pl$DataFrame( + ts = pl$Series(dates)$str$strptime(pl$Datetime("us"), "\%F \%H:\%M"), + ambiguous = c("earliest", "earliest", "latest", "latest") +) + +df$with_columns( + ts_localized = pl$col("ts")$dt$replace_time_zone( + "Europe/Brussels", + ambiguous = pl$col("ambiguous") + ) ) + +# Polars Datetime type without a time zone will be converted to R +# with respect to the session time zone. If ambiguous times are present +# an error will be raised. It is recommended to add a time zone before +# converting to R. +s_without_tz = pl$Series(dates)$str$strptime(pl$Datetime("us"), "\%F \%H:\%M") +s_without_tz + +s_with_tz = s_without_tz$dt$replace_time_zone("UTC") +s_with_tz + +as.vector(s_with_tz) } \keyword{ExprDT} diff --git a/man/LazyFrame_class.Rd b/man/LazyFrame_class.Rd index 308c27783..5fb45c476 100644 --- a/man/LazyFrame_class.Rd +++ b/man/LazyFrame_class.Rd @@ -54,6 +54,26 @@ SQL DBs and other data sources such parquet files simultaneously. } } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \examples{ # see all exported methods ls(.pr$env$RPolarsLazyFrame) diff --git a/man/S3_as.data.frame.Rd b/man/S3_as.data.frame.Rd index 450a9e1be..352c45811 100644 --- a/man/S3_as.data.frame.Rd +++ b/man/S3_as.data.frame.Rd @@ -78,6 +78,26 @@ into the resulting DataFrame. Useful in interactive mode to not lock R session.} \description{ Equivalent to \code{as_polars_df(x, ...)$to_data_frame(...)}. } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \seealso{ \itemize{ \item \code{\link[=as_polars_df]{as_polars_df()}} diff --git a/man/S3_as.vector.Rd b/man/S3_as.vector.Rd index 072c6250f..8172cbdee 100644 --- a/man/S3_as.vector.Rd +++ b/man/S3_as.vector.Rd @@ -14,3 +14,23 @@ \description{ Convert to a vector } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + diff --git a/man/Series_class.Rd b/man/Series_class.Rd index ecf0dcc16..509be5e9e 100644 --- a/man/Series_class.Rd +++ b/man/Series_class.Rd @@ -106,6 +106,26 @@ Some of these are stored in sub-namespaces. } } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \examples{ # make a Series s = pl$Series(c(1:3, 1L)) diff --git a/man/Series_to_r.Rd b/man/Series_to_r.Rd index 77628ca23..e3cceb9bb 100644 --- a/man/Series_to_r.Rd +++ b/man/Series_to_r.Rd @@ -40,6 +40,26 @@ return R list (implicit as.list) Fun fact: Nested polars Series list must have same inner type, e.g. List(List(Int32)) Thus every leaf(non list type) will be placed on the same depth of the tree, and be the same type. } +\section{Conversion to R data types considerations}{ + +Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} +can be converted to R objects via some way. For example, using the +\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +When converting Polars objects to R objects, each type in the Polars object is +converted to an R type. +In some cases, an error may occur because the conversion is not appropriate. +In particular, there is a high possibility of an error when converting +a \link[=DataType_Datetime]{Datetime} type without a time zone. +A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted +to the \link{POSIXct} type in R, with taking into account the time zone in which +the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} +function). In this case, if ambiguous times are included, a conversion error +will occur. In such cases, change the session time zone using +\code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +explicitly specify the time zone before conversion. +} + \examples{ series_vec = pl$Series(letters[1:3]) From d34fed20152ebaa6a8116d4037985465915bfe8a Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 16:03:37 +0000 Subject: [PATCH 11/15] docs: fix cross ref --- man/DataFrame_class.Rd | 2 +- man/DataFrame_to_data_frame.Rd | 2 +- man/DataFrame_to_list.Rd | 2 +- man/LazyFrame_class.Rd | 2 +- man/S3_as.data.frame.Rd | 2 +- man/S3_as.vector.Rd | 2 +- man/Series_class.Rd | 2 +- man/Series_to_r.Rd | 2 +- 8 files changed, 8 insertions(+), 8 deletions(-) diff --git a/man/DataFrame_class.Rd b/man/DataFrame_class.Rd index 98bcbfb6c..a63d14645 100644 --- a/man/DataFrame_class.Rd +++ b/man/DataFrame_class.Rd @@ -88,7 +88,7 @@ the number of columns. Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/DataFrame_to_data_frame.Rd b/man/DataFrame_to_data_frame.Rd index 77c040a7e..9e1d69b68 100644 --- a/man/DataFrame_to_data_frame.Rd +++ b/man/DataFrame_to_data_frame.Rd @@ -31,7 +31,7 @@ Return Polars DataFrame as R data.frame Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/DataFrame_to_list.Rd b/man/DataFrame_to_list.Rd index c10df1ac4..b0c2b61d8 100644 --- a/man/DataFrame_to_list.Rd +++ b/man/DataFrame_to_list.Rd @@ -41,7 +41,7 @@ structure is not very typical or efficient in R. Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/LazyFrame_class.Rd b/man/LazyFrame_class.Rd index 5fb45c476..77f509263 100644 --- a/man/LazyFrame_class.Rd +++ b/man/LazyFrame_class.Rd @@ -58,7 +58,7 @@ SQL DBs and other data sources such parquet files simultaneously. Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/S3_as.data.frame.Rd b/man/S3_as.data.frame.Rd index 352c45811..997cae6d4 100644 --- a/man/S3_as.data.frame.Rd +++ b/man/S3_as.data.frame.Rd @@ -82,7 +82,7 @@ Equivalent to \code{as_polars_df(x, ...)$to_data_frame(...)}. Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/S3_as.vector.Rd b/man/S3_as.vector.Rd index 8172cbdee..5f31914a5 100644 --- a/man/S3_as.vector.Rd +++ b/man/S3_as.vector.Rd @@ -18,7 +18,7 @@ Convert to a vector Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/Series_class.Rd b/man/Series_class.Rd index 509be5e9e..ed363e6d0 100644 --- a/man/Series_class.Rd +++ b/man/Series_class.Rd @@ -110,7 +110,7 @@ Some of these are stored in sub-namespaces. Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. diff --git a/man/Series_to_r.Rd b/man/Series_to_r.Rd index e3cceb9bb..458f3167a 100644 --- a/man/Series_to_r.Rd +++ b/man/Series_to_r.Rd @@ -44,7 +44,7 @@ Thus every leaf(non list type) will be placed on the same depth of the tree, and Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} can be converted to R objects via some way. For example, using the -\code{\link[=S3_as.data.frame]{as.data.frame()}} generic function. +\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. When converting Polars objects to R objects, each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. From 7eb1b887387264b11187201dff5704e54558e987 Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 16:12:45 +0000 Subject: [PATCH 12/15] docs: update from suggests --- R/dataframe__frame.R | 12 +++++------- man/DataFrame_class.Rd | 12 +++++------- man/DataFrame_to_data_frame.Rd | 12 +++++------- man/DataFrame_to_list.Rd | 12 +++++------- man/LazyFrame_class.Rd | 12 +++++------- man/S3_as.data.frame.Rd | 12 +++++------- man/S3_as.vector.Rd | 12 +++++------- man/Series_class.Rd | 12 +++++------- man/Series_to_r.Rd | 12 +++++------- 9 files changed, 45 insertions(+), 63 deletions(-) diff --git a/R/dataframe__frame.R b/R/dataframe__frame.R index 7f5fddcec..1813e4e2a 100644 --- a/R/dataframe__frame.R +++ b/R/dataframe__frame.R @@ -61,21 +61,19 @@ #' `$width` returns the number of columns in the DataFrame. #' #' @section Conversion to R data types considerations: -#' Polars objects, such as [the DataFrame class object][DataFrame_class] -#' can be converted to R objects via some way. For example, using the -#' [`as.data.frame()`][S3_as.data.frame] generic function. -#' When converting Polars objects to R objects, each type in the Polars object is -#' converted to an R type. +#' When converting Polars objects, such as [DataFrames][DataFrame_class] +#' to R objects, for example via the [`as.data.frame()`][as.data.frame.RPolarsDataFrame] generic function, +#' each type in the Polars object is converted to an R type. #' In some cases, an error may occur because the conversion is not appropriate. #' In particular, there is a high possibility of an error when converting #' a [Datetime][DataType_Datetime] type without a time zone. #' A [Datetime][DataType_Datetime] type without a time zone in Polars is converted -#' to the [POSIXct] type in R, with taking into account the time zone in which +#' to the [POSIXct] type in R, which takes into account the time zone in which #' the R session is running (which can be checked with the [Sys.timezone()] #' function). In this case, if ambiguous times are included, a conversion error #' will occur. In such cases, change the session time zone using #' [`Sys.setenv(TZ = "UTC")`][base::Sys.setenv] and then perform the conversion, or use the -#' [`$dt$replace_time_zone()`][ExprDT_replace_time_zone] method on the time type column to +#' [`$dt$replace_time_zone()`][ExprDT_replace_time_zone] method on the Datetime type column to #' explicitly specify the time zone before conversion. #' @details Check out the source code in #' [R/dataframe_frame.R](https://github.com/pola-rs/r-polars/blob/main/R/dataframe__frame.R) diff --git a/man/DataFrame_class.Rd b/man/DataFrame_class.Rd index a63d14645..82d491818 100644 --- a/man/DataFrame_class.Rd +++ b/man/DataFrame_class.Rd @@ -86,21 +86,19 @@ the number of columns. \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/DataFrame_to_data_frame.Rd b/man/DataFrame_to_data_frame.Rd index 9e1d69b68..1fd231e42 100644 --- a/man/DataFrame_to_data_frame.Rd +++ b/man/DataFrame_to_data_frame.Rd @@ -29,21 +29,19 @@ Return Polars DataFrame as R data.frame } \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/DataFrame_to_list.Rd b/man/DataFrame_to_list.Rd index b0c2b61d8..bcaacd7bd 100644 --- a/man/DataFrame_to_list.Rd +++ b/man/DataFrame_to_list.Rd @@ -39,21 +39,19 @@ structure is not very typical or efficient in R. } \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/LazyFrame_class.Rd b/man/LazyFrame_class.Rd index 77f509263..cefe70029 100644 --- a/man/LazyFrame_class.Rd +++ b/man/LazyFrame_class.Rd @@ -56,21 +56,19 @@ SQL DBs and other data sources such parquet files simultaneously. \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/S3_as.data.frame.Rd b/man/S3_as.data.frame.Rd index 997cae6d4..6f6ec493f 100644 --- a/man/S3_as.data.frame.Rd +++ b/man/S3_as.data.frame.Rd @@ -80,21 +80,19 @@ Equivalent to \code{as_polars_df(x, ...)$to_data_frame(...)}. } \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/S3_as.vector.Rd b/man/S3_as.vector.Rd index 5f31914a5..775e97ed1 100644 --- a/man/S3_as.vector.Rd +++ b/man/S3_as.vector.Rd @@ -16,21 +16,19 @@ Convert to a vector } \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/Series_class.Rd b/man/Series_class.Rd index ed363e6d0..e2a4d7e14 100644 --- a/man/Series_class.Rd +++ b/man/Series_class.Rd @@ -108,21 +108,19 @@ Some of these are stored in sub-namespaces. \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } diff --git a/man/Series_to_r.Rd b/man/Series_to_r.Rd index 458f3167a..7d6f8a0db 100644 --- a/man/Series_to_r.Rd +++ b/man/Series_to_r.Rd @@ -42,21 +42,19 @@ Thus every leaf(non list type) will be placed on the same depth of the tree, and } \section{Conversion to R data types considerations}{ -Polars objects, such as \link[=DataFrame_class]{the DataFrame class object} -can be converted to R objects via some way. For example, using the -\code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function. -When converting Polars objects to R objects, each type in the Polars object is -converted to an R type. +When converting Polars objects, such as \link[=DataFrame_class]{DataFrames} +to R objects, for example via the \code{\link[=as.data.frame.RPolarsDataFrame]{as.data.frame()}} generic function, +each type in the Polars object is converted to an R type. In some cases, an error may occur because the conversion is not appropriate. In particular, there is a high possibility of an error when converting a \link[=DataType_Datetime]{Datetime} type without a time zone. A \link[=DataType_Datetime]{Datetime} type without a time zone in Polars is converted -to the \link{POSIXct} type in R, with taking into account the time zone in which +to the \link{POSIXct} type in R, which takes into account the time zone in which the R session is running (which can be checked with the \code{\link[=Sys.timezone]{Sys.timezone()}} function). In this case, if ambiguous times are included, a conversion error will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the -\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the time type column to +\code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. } From 1ff24245f17112bd8f0684303c55aff9e4c7fc4a Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 16:30:53 +0000 Subject: [PATCH 13/15] docs: add non existent time example --- R/dataframe__frame.R | 23 +++++++++++++++++++++++ man/DataFrame_class.Rd | 24 ++++++++++++++++++++++++ man/DataFrame_to_data_frame.Rd | 24 ++++++++++++++++++++++++ man/DataFrame_to_list.Rd | 24 ++++++++++++++++++++++++ man/LazyFrame_class.Rd | 24 ++++++++++++++++++++++++ man/S3_as.data.frame.Rd | 24 ++++++++++++++++++++++++ man/S3_as.vector.Rd | 24 ++++++++++++++++++++++++ man/Series_class.Rd | 24 ++++++++++++++++++++++++ man/Series_to_r.Rd | 24 ++++++++++++++++++++++++ 9 files changed, 215 insertions(+) diff --git a/R/dataframe__frame.R b/R/dataframe__frame.R index 1813e4e2a..792a56ae5 100644 --- a/R/dataframe__frame.R +++ b/R/dataframe__frame.R @@ -75,6 +75,29 @@ #' [`Sys.setenv(TZ = "UTC")`][base::Sys.setenv] and then perform the conversion, or use the #' [`$dt$replace_time_zone()`][ExprDT_replace_time_zone] method on the Datetime type column to #' explicitly specify the time zone before conversion. +#' +#' ```{r} +#' non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "%F %T") +#' +#' withr::with_envvar( +#' new = c(TZ = "America/New_York"), +#' { +#' tryCatch( +#' # This causes an error due to the time zone (the `TZ` env var is affected). +#' as.vector(non_existent_time), +#' error = function(e) e +#' ) +#' } +#' ) +#' +#' withr::with_envvar( +#' new = c(TZ = "America/New_York"), +#' { +#' # This is safe. +#' as.vector(non_existent_time$dt$replace_time_zone("UTC")) +#' } +#' ) +#' ``` #' @details Check out the source code in #' [R/dataframe_frame.R](https://github.com/pola-rs/r-polars/blob/main/R/dataframe__frame.R) #' to see how public methods are derived from private methods. Check out diff --git a/man/DataFrame_class.Rd b/man/DataFrame_class.Rd index 82d491818..a4737f7c9 100644 --- a/man/DataFrame_class.Rd +++ b/man/DataFrame_class.Rd @@ -100,6 +100,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \examples{ diff --git a/man/DataFrame_to_data_frame.Rd b/man/DataFrame_to_data_frame.Rd index 1fd231e42..facafd19b 100644 --- a/man/DataFrame_to_data_frame.Rd +++ b/man/DataFrame_to_data_frame.Rd @@ -43,6 +43,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \examples{ diff --git a/man/DataFrame_to_list.Rd b/man/DataFrame_to_list.Rd index bcaacd7bd..e67f2ffc0 100644 --- a/man/DataFrame_to_list.Rd +++ b/man/DataFrame_to_list.Rd @@ -53,6 +53,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \examples{ diff --git a/man/LazyFrame_class.Rd b/man/LazyFrame_class.Rd index cefe70029..2a90f07fe 100644 --- a/man/LazyFrame_class.Rd +++ b/man/LazyFrame_class.Rd @@ -70,6 +70,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \examples{ diff --git a/man/S3_as.data.frame.Rd b/man/S3_as.data.frame.Rd index 6f6ec493f..3bfeb803a 100644 --- a/man/S3_as.data.frame.Rd +++ b/man/S3_as.data.frame.Rd @@ -94,6 +94,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \seealso{ diff --git a/man/S3_as.vector.Rd b/man/S3_as.vector.Rd index 775e97ed1..13bd634ec 100644 --- a/man/S3_as.vector.Rd +++ b/man/S3_as.vector.Rd @@ -30,5 +30,29 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } diff --git a/man/Series_class.Rd b/man/Series_class.Rd index e2a4d7e14..205d7c74d 100644 --- a/man/Series_class.Rd +++ b/man/Series_class.Rd @@ -122,6 +122,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \examples{ diff --git a/man/Series_to_r.Rd b/man/Series_to_r.Rd index 7d6f8a0db..e39fdb2f0 100644 --- a/man/Series_to_r.Rd +++ b/man/Series_to_r.Rd @@ -56,6 +56,30 @@ will occur. In such cases, change the session time zone using \code{\link[base:Sys.setenv]{Sys.setenv(TZ = "UTC")}} and then perform the conversion, or use the \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. + +\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + tryCatch( + # This causes an error due to the time zone (the `TZ` env var is affected). + as.vector(non_existent_time), + error = function(e) e + ) + \} +) +#> + +withr::with_envvar( + new = c(TZ = "America/New_York"), + \{ + # This is safe. + as.vector(non_existent_time$dt$replace_time_zone("UTC")) + \} +) +#> [1] "2020-03-08 02:00:00 UTC" +}\if{html}{\out{
}} } \examples{ From 618a39540ac3418e505e72a4c5005476f0fbb714 Mon Sep 17 00:00:00 2001 From: eitsupi <50911393+eitsupi@users.noreply.github.com> Date: Sun, 3 Mar 2024 01:42:41 +0900 Subject: [PATCH 14/15] Update R/dataframe__frame.R Co-authored-by: Etienne Bacher <52219252+etiennebacher@users.noreply.github.com> --- R/dataframe__frame.R | 2 ++ 1 file changed, 2 insertions(+) diff --git a/R/dataframe__frame.R b/R/dataframe__frame.R index 792a56ae5..d23cd07a9 100644 --- a/R/dataframe__frame.R +++ b/R/dataframe__frame.R @@ -77,6 +77,8 @@ #' explicitly specify the time zone before conversion. #' #' ```{r} +#' # Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +#' # so this particular date-time doesn't exist #' non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "%F %T") #' #' withr::with_envvar( From 5ad153fd66bee32fd9bd9c46476a0a448cf0b3ca Mon Sep 17 00:00:00 2001 From: eitsupi Date: Sat, 2 Mar 2024 16:44:41 +0000 Subject: [PATCH 15/15] docs: regen --- man/DataFrame_class.Rd | 4 +++- man/DataFrame_to_data_frame.Rd | 4 +++- man/DataFrame_to_list.Rd | 4 +++- man/LazyFrame_class.Rd | 4 +++- man/S3_as.data.frame.Rd | 4 +++- man/S3_as.vector.Rd | 4 +++- man/Series_class.Rd | 4 +++- man/Series_to_r.Rd | 4 +++- 8 files changed, 24 insertions(+), 8 deletions(-) diff --git a/man/DataFrame_class.Rd b/man/DataFrame_class.Rd index a4737f7c9..4cf0f36f2 100644 --- a/man/DataFrame_class.Rd +++ b/man/DataFrame_class.Rd @@ -101,7 +101,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/DataFrame_to_data_frame.Rd b/man/DataFrame_to_data_frame.Rd index facafd19b..02a789622 100644 --- a/man/DataFrame_to_data_frame.Rd +++ b/man/DataFrame_to_data_frame.Rd @@ -44,7 +44,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/DataFrame_to_list.Rd b/man/DataFrame_to_list.Rd index e67f2ffc0..86f1057f4 100644 --- a/man/DataFrame_to_list.Rd +++ b/man/DataFrame_to_list.Rd @@ -54,7 +54,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/LazyFrame_class.Rd b/man/LazyFrame_class.Rd index 2a90f07fe..936f079d9 100644 --- a/man/LazyFrame_class.Rd +++ b/man/LazyFrame_class.Rd @@ -71,7 +71,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/S3_as.data.frame.Rd b/man/S3_as.data.frame.Rd index 3bfeb803a..01ac0d1db 100644 --- a/man/S3_as.data.frame.Rd +++ b/man/S3_as.data.frame.Rd @@ -95,7 +95,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/S3_as.vector.Rd b/man/S3_as.vector.Rd index 13bd634ec..c21223f71 100644 --- a/man/S3_as.vector.Rd +++ b/man/S3_as.vector.Rd @@ -31,7 +31,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/Series_class.Rd b/man/Series_class.Rd index 205d7c74d..592459474 100644 --- a/man/Series_class.Rd +++ b/man/Series_class.Rd @@ -123,7 +123,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"), diff --git a/man/Series_to_r.Rd b/man/Series_to_r.Rd index e39fdb2f0..41b472bad 100644 --- a/man/Series_to_r.Rd +++ b/man/Series_to_r.Rd @@ -57,7 +57,9 @@ will occur. In such cases, change the session time zone using \code{\link[=ExprDT_replace_time_zone]{$dt$replace_time_zone()}} method on the Datetime type column to explicitly specify the time zone before conversion. -\if{html}{\out{
}}\preformatted{non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") +\if{html}{\out{
}}\preformatted{# Due to daylight savings, clocks were turned forward 1 hour on Sunday, March 8, 2020, 2:00:00 am +# so this particular date-time doesn't exist +non_existent_time = pl$Series("2020-03-08 02:00:00")$str$strptime(pl$Datetime(), "\%F \%T") withr::with_envvar( new = c(TZ = "America/New_York"),