---
title: "Getting Started with rapidxlsx"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Getting Started with rapidxlsx}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>"
)
```

The `rapidxlsx` package provides high-throughput serialization of R data frames to Microsoft Excel (`.xlsx`) workbooks. It utilizes a multi-threaded Rust engine with zero-copy SEXP vector ingestion and parallel Deflate block compression (`Z_SYNC_FLUSH`).

## Basic Usage

The primary function is `write_xlsx()`. It takes a `data.frame` and an output file path:

```{r setup}
library(rapidxlsx)

df <- data.frame(
  id = 101:105,
  name = c("Alice", "Bob", "Charlie", "David", "Eva"),
  score = c(95.5, 88.0, 92.3, 76.4, 89.1),
  active = c(TRUE, FALSE, TRUE, TRUE, FALSE),
  group = factor(c("A", "B", "A", "C", "B")),
  stringsAsFactors = FALSE
)

tmp <- tempfile(fileext = ".xlsx")
write_xlsx(df, tmp, sheet_name = "Participants")
```

The function returns the path invisibly, enabling standard R piping (`|>` or `%>%`):

```{r piping}
out_path <- df |>
  subset(active == TRUE) |>
  write_xlsx(tempfile(fileext = ".xlsx"), sheet_name = "ActiveUsers")

file.exists(out_path)
```

## Missing Values

Missing values (`NA`, `NA_real_`, `NA_integer_`, `NA_character_`) are mapped to empty OpenXML cells:

```{r na-handling}
data_with_na <- data.frame(
  x = c(1.0, NA, 3.5),
  y = c("valid", "text", NA),
  stringsAsFactors = FALSE
)

tmp_na <- tempfile(fileext = ".xlsx")
write_xlsx(data_with_na, tmp_na)
```

## Compression Level

The `compression_level` argument accepts integers from 1 to 9 (default `1L`):

* `1L`: Fastest compression throughput (recommended for large datasets exceeding 100,000 rows).
* `6L` or `9L`: Higher compression ratio at the expense of CPU time.

```{r compression}
tmp_comp <- tempfile(fileext = ".xlsx")
write_xlsx(df, tmp_comp, compression_level = 6L)
```

## Clean Up

```{r cleanup, include=FALSE}
unlink(tmp)
unlink(out_path)
unlink(tmp_na)
unlink(tmp_comp)
```