cs-rep.qmd

---
depends_on:
- defs-required
- args-independence
---

# Case study: `rep()` {#sec-cs-rep}

```{r}
#| include = FALSE
source("common.R")
```

## What does `rep()` do?

`rep()` is an extremely useful base R function that repeats a vector `x` in various ways.
It has three details arguments: `times`, `each`, and `length.out`[^cs-rep-1] that interact in complicated ways.
Let's explore the basics first:

[^cs-rep-1]: Note that the function specification is `rep(x, ...)`, and `times`, `each`, and `length.out` do not appear explicitly.
    You have to read the documentation to discover these arguments.

```{r}
x <- c(1, 2, 4)

rep(x, times = 3)
rep(x, length.out = 10)
```

`times` and `length.out` replicate the vector in the same way, but `length.out` allows you to specify a non-integer number of replications.
If you specify both, `length.out` wins.

```{r}
rep(x, times = 3, length.out = 10)
```

The `each` argument repeats individual components of the vector rather than the whole vector:

```{r}
rep(x, each = 3)
```

And you can combine that with `times`:

```{r}
rep(x, each = 3, times = 2)
```

If you supply a vector to `times` it works a similar way to `each`, repeating each component the specified number of times:

```{r}
rep(x, times = x)
```

## What makes this function hard to understand?

-   There's a complicated dependency between `times`, `length.out`, and `each`.
    `times` and `length.out` both control the same underlying variable in different ways, and you can not set them simultaneously.
    `times` and `each` are mostly independent, but if you specify a vector for `times` you can't use each.

    ```{r}
    #| error = TRUE
    rep(1:3, times = c(2, 2, 2), each = 2)
    ```

-   I think using `times` with a vector is confusing because it switches from replicating the whole vector to replicating individual values of the vector, like `each` usually does.

    ```{r}
    rep(1:3, each = 2)
    rep(1:3, times = 2)
    rep(1:3, times = c(2, 2, 2))
    ```

I think these two problems have the same underlying cause: `rep()` is trying to do too much in a single function.
`rep()` is really exposing two different strategies (@sec-strategies-explicit): repeating each element of the vector vs. repeating the entire vector.
In this case, rather than exposing the two strategies via an argument, I think it makes sense to expose them each with a different function.

Why two separate functions?
It only makes sense to supply a vector of `times` when you're replicating the individual values.

## How might we improve the situation?

Two create two new functions, we need to first come up with names: I like `rep_each()` and `rep_full()`.
`rep_each()` was a fairly easy name to come up with.
`rep_full()` was a little harder and took a few iterations: I like that `full` has the same number of letters as `each`, which makes the two functions look like they belong together.
Another possibility would be `rep_every()` since each and every form a natural pair, but to me at least, repeating "every" element doesn't feel very different to repeating each element.

Next, we need to think about their arguments.
Both will have a single data argument: `x`, the vector to repeat.
`rep_each()` has an additional argument that specifies the number of times to replicate each element, which can either be a single number, or a vector the same length as `x`.
`rep_time()` has two mutually exclusive details arguments (@sec-mutually-exclusive), the number of times to repeat the whole vector, or the desired length of the output.

What should we call the arguments?
We've already captured the different replication strategies (each vs. full) in the function name, so I think the argument that specifies the number of times to replicate can be the same, and `times` seems reasonable.
For the second argument to `rep_full()`, I draw inspiration from `rep()` which uses `length.out`.
I think it's obvious that the argument controls the output, so `length` is adequate.

```{r}
rep_each <- function(x, times) {
  times <- vctrs::vec_recycle(times, length(x))
  rep(x, times = times)
}

rep_full <- function(x, times, length) {
  rlang::check_exclusive(times, length)
  
  if (!missing(length)) {
    rep(x, length.out = length)
  } else {
    rep(x, length.out = times * base::length(x))
  }
}
```

(Note the downside of using `length` as the argument name: we have to call [`base::length()`](#0) to avoid evaluating the missing `length` when times is supplied.
This is probably why `rep()` uses `length.out`.)

```{r}
x <- c(1, 2, 4)

rep_each(x, times = 2)
rep_full(x, times = 2)

rep_each(x, times = x)

rep_full(x, length = 5)
```

One downside of this approach is if you want to both replicate each component *and* the entire vector, you have to use two function calls, which is much more verbose than the `rep()` equivalent.
However, I don't think this is a terribly common use case, and so I think a longer call is more readable.

## Dealing with bad inputs

The implementations above work well for correct inputs, but will also work without error for a number of incorrect inputs:

```{r}
rep_full(1:3, 1:3)
```

Need to think about the types

```{r}
rep_each <- function(x, times) {
  times <- vctrs::vec_cast(times, integer())
  times <- vctrs::vec_recycle(times, vctrs::vec_size(x), x_arg = "times")
  
  rep.int(x, times)
}

rep_full <- function(x, times, length) {
  rlang::check_exclusive(times, length)
  
  if (!missing(length)) {
    rlang:::check_number_whole(length)
    rep(x, length.out = length)
  } else {
    rlang:::check_number_decimal(times)
    rep(x, length.out = times * base::length(x))
  }
}
```

```{r}
#| error = TRUE
rep_each(1:3, 1:2)
rep_each(1:3, "x")

rep_full(1:3, "x")
rep_full(1:3, c(1, 2))
```