Export the Series as an R vector

Description

Export the Series as an R vector.

Usage

<series>$_to_r_vector(
  ...,
  uint8 = c("integer", "raw"),
  int64 = c("double", "character", "integer", "integer64"),
  date = c("Date", "IDate"),
  time = c("hms", "ITime"),
  struct = c("dataframe", "tibble"),
  decimal = c("double", "character"),
  as_clock_class = FALSE,
  ambiguous = c("raise", "earliest", "latest", "null"),
  non_existent = c("raise", "null")
)

Arguments

… These dots are for future extensions and must be empty.

uint8

Determine how to convert Polars’ UInt8 type values to R type. One of the followings:

“integer” (default): Convert to the R’s integer type.
“raw”: Convert to the R’s raw type. If the value is null, export as 00.

int64

Determine how to convert Polars’ Int64, UInt32, or UInt64 type values to R type. One of the followings:

“double” (default): Convert to the R’s double type. Accuracy may be degraded.
“character”: Convert to the R’s character type.
“integer”: Convert to the R’s integer type. If the value is out of the range of R’s integer type, export as NA_integer\_.
“integer64”: Convert to the bit64::integer64 class. The bit64 package must be installed. If the value is out of the range of bit64::integer64, export as bit64::NA_integer64\_.

date

Determine how to convert Polars’ Date type values to R class. One of the followings:

“Date” (default): Convert to the R’s Date class.
“IDate”: Convert to the data.table::IDate class.

time

Determine how to convert Polars’ Time type values to R class. One of the followings:

“hms” (default): Convert to the hms::hms class. If the hms package is not installed, a warning will be shown.
“ITime”: Convert to the data.table::ITime class. The data.table package must be installed.

struct

Determine how to convert Polars’ Struct type values to R class. One of the followings:

“dataframe” (default): Convert to the R’s data.frame class.
“tibble”: Convert to the tibble class. If the tibble package is not installed, a warning will be shown.

decimal

Determine how to convert Polars’ Decimal type values to R type. One of the followings:

“double” (default): Convert to the R’s double type.
“character”: Convert to the R’s character type.

as_clock_class

A logical value indicating whether to export datetimes and duration as the clock package’s classes.

FALSE (default): Duration values are exported as difftime and datetime values are exported as POSIXct. Accuracy may be degraded.
TRUE: Duration values are exported as clock_duration, datetime without timezone values are exported as clock_naive_time, and datetime with timezone values are exported as clock_zoned_time. For this case, the clock package must be installed. Accuracy will be maintained.

ambiguous

Determine how to deal with ambiguous datetimes. Only applicable when as_clock_class is set to FALSE and datetime without timezone values are exported as POSIXct. Character vector or expression containing the followings:

“raise” (default): Throw an error
“earliest”: Use the earliest datetime
“latest”: Use the latest datetime
“null”: Return a NA value

non_existent

Determine how to deal with non-existent datetimes. Only applicable when as_clock_class is set to FALSE and datetime without timezone values are exported as POSIXct. One of the followings:

“raise” (default): Throw an error
“null”: Return a NA value

Details

The class/type of the exported object depends on the data type of the Series as follows:

Boolean: logical.
UInt8: integer or raw, depending on the uint8 argument.
UInt16, Int8, Int16, Int32: integer.
Int64, UInt32, UInt64: double, character, integer, or bit64::integer64, depending on the int64 argument.
Float32, Float64: double.
Decimal: double.
String: character.
Categorical: factor.
Date: Date or data.table::IDate, depending on the date argument.
Time: hms::hms or data.table::ITime, depending on the time argument.
Datetime (without timezone): POSIXct or clock_naive_time, depending on the as_clock_class argument.
Datetime (with timezone): POSIXct or clock_zoned_time, depending on the as_clock_class argument.
Duration: difftime or clock_duration, depending on the as_clock_class argument.
Binary: blob::blob.
Null: vctrs::unspecified.
List, Array: vctrs::list_of.
Struct: data.frame or tibble, depending on the struct argument.

Value

A vector

Examples

library("polars")

# Struct values handling
series_struct <- as_polars_series(
  data.frame(
    a = 1:2,
    b = I(list(data.frame(c = "foo"), data.frame(c = "bar")))
  )
)
series_struct

#> shape: (2,)
#> Series: '' [struct[2]]
#> [
#>  {1,[{"foo"}]}
#>  {2,[{"bar"}]}
#> ]

# Export Struct as normal R data frame
series_struct$to_r_vector()

#>   a   b
#> 1 1 foo
#> 2 2 bar

# Export Struct as tibble data frame
series_struct$to_r_vector(struct = "tibble")

#> # A tibble: 2 × 2
#>       a                  b
#>   <int> <list<tibble[,1]>>
#> 1     1            [1 × 1]
#> 2     2            [1 × 1]

# UInt8 values handling
series_uint8 <- as_polars_series(c(NA, 0, 255))$cast(pl$UInt8)
series_uint8

#> shape: (3,)
#> Series: '' [u8]
#> [
#>  null
#>  0
#>  255
#> ]

# Export UInt8 as integer
series_uint8$to_r_vector(uint8 = "integer")

#> [1]  NA   0 255

# Export UInt8 as raw (`null` is exported as `00`)
series_uint8$to_r_vector(uint8 = "raw")

#> [1] 00 00 ff

# Other Integer values handlings
series_uint64 <- as_polars_series(
  c(NA, "0", "4294967295", "18446744073709551615")
)$cast(pl$UInt64)
series_uint64

#> shape: (4,)
#> Series: '' [u64]
#> [
#>  null
#>  0
#>  4294967295
#>  18446744073709551615
#> ]

# Export UInt64 as double
series_uint64$to_r_vector(int64 = "double")

#> [1]           NA 0.000000e+00 4.294967e+09 1.844674e+19

# Export UInt64 as character
series_uint64$to_r_vector(int64 = "character")

#> [1] NA                     "0"                    "4294967295"          
#> [4] "18446744073709551615"

# Export UInt64 as integer (overflow occurs)
series_uint64$to_r_vector(int64 = "integer")

#> [1] NA  0 NA NA

# Export UInt64 as bit64::integer64 (overflow occurs)
if (requireNamespace("bit64", quietly = TRUE)) {
  series_uint64$to_r_vector(int64 = "integer64")
}

#> integer64
#> [1] <NA>       0          4294967295 <NA>

# Duration values handling
series_duration <- as_polars_series(
  c(NA, -1000000000, -10, -1, 1000000000)
)$cast(pl$Duration("ns"))
series_duration

#> shape: (5,)
#> Series: '' [duration[ns]]
#> [
#>  null
#>  -1s
#>  -10ns
#>  -1ns
#>  1s
#> ]

# Export Duration as difftime
series_duration$to_r_vector(as_clock_class = FALSE)

#> Time differences in secs
#> [1]     NA -1e+00 -1e-08 -1e-09  1e+00

# Export Duration as clock_duration
if (requireNamespace("clock", quietly = TRUE)) {
  series_duration$to_r_vector(as_clock_class = TRUE)
}

#> <duration<nanosecond>[5]>
#> [1] NA          -1000000000 -10         -1          1000000000

# Datetime values handling
series_datetime <- as_polars_series(
  as.POSIXct(
    c(NA, "1920-01-01 00:00:00", "1970-01-01 00:00:00", "2020-01-01 00:00:00"),
    tz = "UTC"
  )
)$cast(pl$Datetime("ns", "UTC"))
series_datetime

#> shape: (4,)
#> Series: '' [datetime[ns, UTC]]
#> [
#>  null
#>  1920-01-01 00:00:00 UTC
#>  1970-01-01 00:00:00 UTC
#>  2020-01-01 00:00:00 UTC
#> ]

# Export zoned datetime as POSIXct
series_datetime$to_r_vector(as_clock_class = FALSE)

#> [1] NA               "1920-01-01 UTC" "1970-01-01 UTC" "2020-01-01 UTC"

# Export zoned datetime as clock_zoned_time
if (requireNamespace("clock", quietly = TRUE)) {
  series_datetime$to_r_vector(as_clock_class = TRUE)
}

#> <zoned_time<nanosecond><UTC>[4]>
#> [1] NA                                    "1920-01-01T00:00:00.000000000+00:00"
#> [3] "1970-01-01T00:00:00.000000000+00:00" "2020-01-01T00:00:00.000000000+00:00"