README.Rmd

---
output: github_document
---

<!-- README.md is generated from README.Rmd. Please edit that file -->

```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
```

# b64 <img src="man/figures/logo.svg" align="right" height="139" alt="" />

<!-- badges: start -->
[![R-CMD-check](https://github.com/extendr/b64/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/extendr/b64/actions/workflows/R-CMD-check.yaml)
<!-- badges: end -->

The goal of b64 is to provide a very fast, lightweight, and vectorized base64 encoder and decoder. 

## Installation

You can install the development version of b64 like so:

```r
pak::pak("extendr/b64")
```

## Example

Encode to base64 using `encode()`.

```{r example}
library(b64)

hello <- encode("Hello, from extendr")
hello
```

Decode using `decode()`

```{r}
decoded <- decode(hello)
decoded
```

We can convert the decoded base64 to characters and see how it worked.

```{r}
rawToChar(decoded[[1]])
```


### Vectorized 

Both `encode()` and `decode()` are vectorized. 

```{r}
lorem <- unlist(lorem::ipsum(5, 1,  5))
lorem

encoded <- encode(lorem)
encoded
```

We can decode all of these using `decode()` as well. This will always return a `blob` object.

```{r}
decode(encoded)
```


## Encoding and decoding files

`b64` shines when encoding and decoding files. `encode_file()` and `decode_file()` both work by reading a file as a stream making it far faster than the alternative. 

```{r message = FALSE, warn = FALSE}
tmp <- tempfile() 
fp <- "https://github.com/datablist/sample-csv-files/raw/main/files/leads/leads-100000.csv"

download.file(fp, tmp)

bench::mark(
  b64 = encode_file(tmp),
  base64enc = base64enc::base64encode(tmp)
)
```

While the encoding is very impressive, better yet is the decoding performance. 

```{r}
# create a temp file
tmp2 <- tempfile()

# encode it and write to tmep file
encode_file(tmp) |>
  charToRaw() |>
  writeBin(tmp2)

bench::mark(
  b64 = decode_file(tmp2),
  base64enc = base64enc::base64decode(file(tmp2))
)
```

## Alternative engines 

Out of the box, `b64` provides a number of pre-configured engines that can be used. The function `engine()` allows you to choose one of these different engines For example, `engine("url_safe")` provides a standard engine that uses a url-safe alphabet with padding.


```{r}
url_engine <- engine("url_safe")
url_safe_encoded <- encode("\xfa\xec U", url_engine)
url_safe_encoded
```

If we try to decode this using the standard engine, we will encounter an error. 

```{r error=TRUE}
decode(url_safe_encoded)
```

We can use our new engine to decode it.

```{r}
decode(url_safe_encoded, url_engine)
```

### Custom Engines

We can create custom engines with `new_engine()`. This allows us to provide our on alphabet and configuration. 

We can use one of the many predefined alphabets or create one our selves with `new_alphabet()`. We can also specify our engine config using `new_config()` which lets us choose whether or not to pad and how to handle decoding. 

```{r}
my_eng <- new_engine(
  alphabet("crypt"),
  new_config(TRUE, TRUE, "none")
)
```

This engine can be used to encode or decode text. 

```{r}
txt <- "lorem ipsum sit dolor amet"

encode(txt, my_eng)
```

Compare this to the standard encoder: 

```{r}
encode(txt)
```