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%"
)

# remotes::install_github("GuangchuangYu/badger")
library(badger)
library(incase)

parties <- sample(
  c("D", "R", "G", "L", "I", NA),
  20,
  replace = TRUE,
  c(0.25, 0.25, 0.075, 0.075, 0.25, 0.1)
)
```

# incase <img src="man/figures/logo.png?raw=TRUE" align="right" height="138" />

<!-- badges: start -->
`r badge_cran_release(color = "brightgreen")`
`r badge_runiverse()`
`r badge_lifecycle("stable")`
`r badge_license(color = "blueviolet")`
`r badge_github_actions(action = "R-CMD-check")`
`r badge_codecov(branch = "main")`
<!-- badges: end -->

**incase** provides a more pipe-friendly alternative to [**dplyr**](https://github.com/tidyverse/dplyr)'s [`case_when()`](https://dplyr.tidyverse.org/reference/case_when.html) and [`if_else()`](https://dplyr.tidyverse.org/reference/if_else.html).

## Installation

You can install the released version of **incase** from [CRAN](https://cran.r-project.org/package=incase) with:

``` {r eval = FALSE}
install.packages("incase")
```

or the development version from [GitHub](https://github.com/rossellhayes/incase) with:

``` {r eval = FALSE}
# install.packages("pak")
pak::pkg_install("rossellhayes/incase")
```

## Usage

### Pipe-friendly conditionals

**incase**'s `in_case()` and `if_case()` accept a vector as their first input, allowing you to take full advantage of [**magrittr**](https://github.com/tidyverse/magrittr)'s `.`

```{r}
1:20 %>%
  in_case(
    . %% 15 == 0 ~ "fizz buzz",
    . %%  3 == 0 ~ "fizz",
    . %%  5 == 0 ~ "buzz",
    TRUE         ~ .
  )

1:20 %>% if_case(. %% 3 == 0, "fizz", .)
```

### Automatic type conversion

**incase** functions automatically coerce types.
This is especially useful when dealing with integers or `NA`s.

```{r error=TRUE}
x <- -1:5

# Replace -1 with NA
dplyr::case_when(x == -1 ~ NA, TRUE ~ x)
dplyr::case_when(x == -1 ~ NA_integer_, TRUE ~ x)
in_case(x == -1 ~ NA, TRUE ~ x)

# Replace -1 with 0
dplyr::case_when(x == -1 ~ 0, TRUE ~ x)
dplyr::case_when(x == -1 ~ 0L, TRUE ~ x)
in_case(x == -1 ~ 0, TRUE ~ x)
```

With **incase**, you no longer have to worry about specifying the type of your `NA`s or adding `L` to your integers.

### Easy default values

`in_case()` adds `preserve` and `default` arguments as a more intuitive alternative to `TRUE ~ ...`.*

```{r}
1:20 %>%
  in_case(
    . %% 15 == 0 ~ "fizz buzz",
    . %%  3 == 0 ~ "fizz",
    . %%  5 == 0 ~ "buzz"
  )

1:20 %>%
  in_case(
    . %% 15 == 0 ~ "fizz buzz",
    . %%  3 == 0 ~ "fizz",
    . %%  5 == 0 ~ "buzz",
    preserve     = TRUE
  )

1:20 %>%
  in_case(
    . %% 15 == 0 ~ "fizz buzz",
    . %%  3 == 0 ~ "fizz",
    . %%  5 == 0 ~ "buzz",
    default      = "pass"
  )
```

### Simplified interface for recoding

`switch_case()` works as a convenient shorthand for `in_case()` when recoding discrete values.

```{r}
parties

parties %>%
  switch_case(
    "D"         ~ "Democrat",
    "R"         ~ "Republican",
    c("G", "L") ~ "Other",
    c("I", NA)  ~ "Independent"
  )
```

`grep_case()` allows you to recode values with pattern matching.

```{r}
countries <- c(
  "France", "Ostdeutschland", "Westdeutschland", "Nederland",
  "België (Vlaanderen)", "Belgique (Wallonie)", "Luxembourg", "Italia"
)

grep_case(
  countries,
  "Deutschland" ~ "Germany",
  "Belg"        ~ "Belgium",
  "Nederland"   ~ "Netherlands",
  "Italia"      ~ "Italy",
  preserve      = TRUE,
  ignore.case   = TRUE
)
```

#### Easily recode to (ordered) factor

When you need an ordered factor, the `*_fct()` family of functions lets you save a step by using the order of your cases as the order of your factor levels.
Use `ordered = TRUE` to create an ordered factor and `ordered = FALSE` to make a regular-old factor.

```{r}
data <- runif(10, 0, 10)
data

data %>% 
  in_case_fct(
    . < 3   ~ "Low",
    . < 7   ~ "Medium",
    default = "High",
    ordered = TRUE
  )

parties %>%
  switch_case_fct(
    "D"         ~ "Democrat",
    "R"         ~ "Republican",
    c("G", "L") ~ "Other",
    c("I", NA)  ~ "Independent"
  )
```

---

Hex sticker fonts are [Source Sans by Adobe](https://github.com/adobe-fonts/source-sans) and [Hasklig by Ian Tuomi](https://github.com/i-tu/Hasklig).

Please note that **incase** is released with a [Contributor Code of Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html).
By contributing to this project, you agree to abide by its terms.

\* Intuitiveness may vary from person to person.