---
title: "Adverbs"
author: "Colin Fay"
date: "`r Sys.Date()`"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Adverbs}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

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

## Adverbs

Adverbs take a function and return a modified function.

### `silently()` 

`silently()` transforms a function so that when you call this new function, it returns nothing unless there is an error or a warning (contrary to `attempt` that returns the result). In a sense, the new function stay silent unless error or warning.

```{r eval = TRUE}
silent_log <- silently(log)
silent_log(1)
silent_log("a")
# Error in .f(...) : non-numeric argument to mathematical function
```

With `silently()`, the result is never returned.

```{r}
silent_matrix <- silently(matrix)
silent_matrix(1:3, 2)
# Warning message:
# In .f(...) :
#  data length [3] is not a sub-multiple or multiple of the number of rows [2]
```


### `surely()` 

`surely()` transforms a function so that when you call this new function, it calls `attempt()` - i.e. in the code below, calling `sure_log(1)` is the same as calling `attempt(log(1))`. In a sense, you're sure this new function will always work.

```{r}
sure_log <- surely(log)
sure_log(1)
# [1] 0
sure_log("a")
# Error: non-numeric argument to mathematical function
```

### `with_message()` and `with_warning()`

These two functions take a function, and add a warning or a message to it.

```{r eval = TRUE}
as_num_msg <- with_message(as.numeric, msg = "We're performing a numeric conversion")
as_num_warn <- with_warning(as.numeric, msg = "We're performing a numeric conversion")
as_num_msg("1")
as_num_warn("1")
```

### `without_message()`, `without_warning()`, and `discretly()`

These three functions do the opposite, as they remove warnings and messages: 

```{r}
matrix(1:3, ncol = 2)
no_warning_matrix <- without_warning(matrix)
no_warning_matrix(1:3, ncol = 2)
```