Polars raw list

Description

Create an "rpolars_raw_list", which is an R list where all elements must be an R raw or NULL.

Usage

pl$raw_list(...)

# S3 method for class 'rpolars_raw_list'
x[index]

# S3 method for class 'rpolars_raw_list'
as.list(x, ...)

Arguments

`…`	Elements
`x`	A `rpolars_raw_list` object created with `pl$raw_list()`
`index`	Elements to select

Details

In R, raw can contain a binary sequence of bytes, and the length is the number of bytes. In polars a Series of DataType Binary is more like a vector of vectors of bytes where missing values are allowed, similar to how NAs can be present in vectors.

To ensure correct round-trip conversion, r-polars uses an R list where any elements must be raw or NULL (encoded as missing), and the S3 class is c(“rpolars_raw_list”,“list”).

Value

An R list where any elements must be raw, and the S3 class is c(“rpolars_raw_list”,“list”).

Examples

library(polars)

# create a rpolars_raw_list
raw_list = pl$raw_list(raw(1), raw(3), charToRaw("alice"), NULL)

# pass it to Series or lit
pl$Series(values = raw_list)

#> polars Series: shape: (4,)
#> Series: '' [binary]
#> [
#>  b"\x00"
#>  b"\x00\x00\x00"
#>  b"alice"
#>  null
#> ]

pl$lit(raw_list)

#> polars Expr: Series

# convert polars bianry Series to rpolars_raw_list
pl$Series(values = raw_list)$to_r()

#> [[1]]
#> [1] 00
#> 
#> [[2]]
#> [1] 00 00 00
#> 
#> [[3]]
#> [1] 61 6c 69 63 65
#> 
#> [[4]]
#> NULL
#> 
#> attr(,"class")
#> [1] "rpolars_raw_list" "list"

# NB: a plain list of raws yield a polars Series of DateType [list[Binary]]
# which is not the same
pl$Series(values = list(raw(1), raw(2)))

#> polars Series: shape: (2,)
#> Series: '' [list[binary]]
#> [
#>  [b"\x00"]
#>  [b"\x00\x00"]
#> ]

# to regular list, use as.list or unclass
as.list(raw_list)

#> [[1]]
#> [1] 00
#> 
#> [[2]]
#> [1] 00 00 00
#> 
#> [[3]]
#> [1] 61 6c 69 63 65
#> 
#> [[4]]
#> NULL

# subsetting preserves class
pl$raw_list(NULL, raw(2), raw(3))[1:2]

#> [[1]]
#> NULL
#> 
#> [[2]]
#> [1] 00 00
#> 
#> attr(,"class")
#> [1] "rpolars_raw_list" "list"

# to regular list, use as.list or unclass
pl$raw_list(NULL, raw(2), raw(3)) |> as.list()

#> [[1]]
#> NULL
#> 
#> [[2]]
#> [1] 00 00
#> 
#> [[3]]
#> [1] 00 00 00