# Invariants for subsetting and subassignment

This vignette defines invariants for subsetting and subset-assignment for tibbles, and illustrates where their behaviour differs from data frames. The goal is to define a small set of invariants that consistently define how behaviors interact. Some behaviors are defined using functions of the vctrs package, e.g. `vec_slice()`, `vec_recycle()` and `vec_as_index()`. Refer to their documentation for more details about the invariants that they follow.

The subsetting and subassignment operators for data frames and tibbles are particularly tricky, because they support both row and column indexes, both of which are optionally missing. We resolve this by first defining column access with `[[` and `$`, then column-wise subsetting with `[`, then row-wise subsetting, then the composition of both.

## Conventions

In this article, all behaviors are demonstrated using one example data frame and its tibble equivalent:

    library(vctrs)
    #>
    #> Attaching package: 'vctrs'
    #> The following object is masked from 'package:dplyr':
    #>
    #>     data_frame
    #> The following object is masked from 'package:tibble':
    #>
    #>     data_frame
    library(tibble)
    new_df <- function() {
      df <- data.frame(n = c(1L, NA, 3L, NA))
      df$c <- letters[5:8]
      df$li <- list(9, 10:11, 12:14, "text")
      df
    }
    new_tbl <- function() {
      as_tibble(new_df())
    }

Results of the same code for data frames and tibbles are presented side by side:

    new_df()
    #>    n c         li
    #> 1  1 e          9
    #> 2 NA f     10, 11
    #> 3  3 g 12, 13, 14
    #> 4 NA h       text
    new_tbl()
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2    NA f     <int [2]>
    #> 3     3 g     <int [3]>
    #> 4    NA h     <chr [1]>

If the results are identical (after converting to a data frame if necessary), only the tibble result is shown.

Subsetting operations are read-only. The same objects are reused in all examples:

    df <- new_df()
    tbl <- new_tbl()

Where needed, we also show examples with hierarchical columns containing a data frame or a matrix:

    new_tbl2 <- function() {
      tibble(
        tb = tbl,
        m = diag(4)
      )
    }
    new_df2 <- function() {
      df2 <- new_tbl2()
      class(df2) <- "data.frame"
      class(df2$tb) <- "data.frame"
      df2
    }
    df2 <- new_df2()
    tbl2 <- new_tbl2()

    new_tbl()
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2    NA f     <int [2]>
    #> 3     3 g     <int [3]>
    #> 4    NA h     <chr [1]>

For subset assignment (subassignment, for short), we need a fresh copy of the data for each test. The `with_*()` functions (omitted here for brevity) allow for a more concise notation. These functions take an assignment expression, execute it on a fresh copy of the data, and return the data for printing. The first example prints what’s really executed, further examples omit this output.

    with_df(df$n <- rev(df$n), verbose = TRUE)
    #> {
    #>   df <- new_df()
    #>   df$n <- rev(df$n)
    #>   df
    #> }
    #>    n c         li
    #> 1 NA e          9
    #> 2  3 f     10, 11
    #> 3 NA g 12, 13, 14
    #> 4  1 h       text
    with_tbl(tbl$n <- rev(tbl$n), verbose = TRUE)
    #> {
    #>   tbl <- new_tbl()
    #>   tbl$n <- rev(tbl$n)
    #>   tbl
    #> }
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1    NA e     <dbl [1]>
    #> 2     3 f     <int [2]>
    #> 3    NA g     <int [3]>
    #> 4     1 h     <chr [1]>

## Column extraction

### Definition of `x[[j]]`

`x[[j]]` is equal to `.subset2(x, j)`.

    tbl[[1]]
    #> [1]  1 NA  3 NA
    .subset2(tbl, 1)
    #> [1]  1 NA  3 NA

NB: `x[[j]]` always returns an object of size `nrow(x)` if the column exists.

`j` must be a single number or a string, as enforced by `.subset2(x, j)`.

    df[[1:2]]
    #> [1] NA
    tbl[[1:2]]
    #> Warning: The `j` argument of
    #> ``[[.tbl_df`()` can't be a vector of
    #> length 2 as of tibble 3.0.0.
    #> Recursive subsetting is deprecated for
    #> tibbles.
    #> [1] NA
    df[[c("n", "c")]]
    #> Error in .subset2(x, i, exact = exact):
    #> subscript out of bounds
    tbl[[c("n", "c")]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `c("n", "c")` has size 2 but
    #> must be size 1.
    df[[TRUE]]
    #> [1]  1 NA  3 NA
    tbl[[TRUE]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `TRUE` has the wrong type
    #> `logical`.
    #> [34mℹ[39m It must be numeric or character.
    df[[mean]]
    #> Error in .subset2(x, i, exact = exact):
    #> invalid subscript type 'closure'
    tbl[[mean]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `mean` has the wrong type
    #> `function`.
    #> [34mℹ[39m It must be numeric or character.

`NA` indexes, numeric out-of-bounds (OOB) values, and non-integers throw an error:

    df[[NA]]
    #> NULL
    tbl[[NA]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `NA` can't be `NA`.
    df[[NA_character_]]
    #> NULL
    tbl[[NA_character_]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `NA_character_` can't be
    #> `NA`.
    df[[NA_integer_]]
    #> NULL
    tbl[[NA_integer_]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `NA_integer_` can't be `NA`.
    df[[-1]]
    #> Error in .subset2(x, i, exact = exact):
    #> invalid negative subscript in get1index
    #> <real>
    tbl[[-1]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Subscript `-1` has value -1 but must
    #> be a positive location.
    df[[4]]
    #> Error in .subset2(x, i, exact = exact):
    #> subscript out of bounds
    tbl[[4]]
    #> Error: Can't subset columns that don't
    #> exist.
    #> [31mx[39m Location 4 doesn't exist.
    #> [34mℹ[39m There are only 3 columns.
    df[[1.5]]
    #> [1]  1 NA  3 NA
    tbl[[1.5]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Can't convert from <double> to
    #> <integer> due to loss of precision.
    df[[Inf]]
    #> NULL
    tbl[[Inf]]
    #> Error: Must extract column with a single
    #> valid subscript.
    #> [31mx[39m Can't convert from <double> to
    #> <integer> due to loss of precision.

Character OOB access is silent because a common package idiom is to check for the absence of a column with `is.null(df[[var]])`.

    tbl[["x"]]
    #> NULL

### Definition of `x$name`

`x$name` and `x$"name"` are equal to `x[["name"]]`.

    tbl$n
    #> [1]  1 NA  3 NA
    tbl$"n"
    #> [1]  1 NA  3 NA
    tbl[["n"]]
    #> [1]  1 NA  3 NA

Unlike data frames, tibbles do not partially match names. Because `df$x` is rarely used in packages, it can raise a warning:

    df$l
    #> [[1]]
    #> [1] 9
    #>
    #> [[2]]
    #> [1] 10 11
    #>
    #> [[3]]
    #> [1] 12 13 14
    #>
    #> [[4]]
    #> [1] "text"
    tbl$l
    #> Warning: Unknown or uninitialised
    #> column: `l`.
    #> NULL
    df$not_present
    #> NULL
    tbl$not_present
    #> Warning: Unknown or uninitialised
    #> column: `not_present`.
    #> NULL

## Column subsetting

### Definition of `x[j]`

`j` is converted to an integer vector by `vec_as_index(j, ncol(x), names = names(x))`. Then `x[c(j_1, j_2, ..., j_n)]` is equivalent to `tibble(x[[j_1]], x[[j_2]], ..., x[[j_3]])`, keeping the corresponding column names. This implies that `j` must be a numeric or character vector, or a logical vector with length 1 or `ncol(x)`.1

    tbl[1:2]
    #> # A tibble: 4 x 2
    #>       n c
    #>   <int> <chr>
    #> 1     1 e
    #> 2    NA f
    #> 3     3 g
    #> 4    NA h

When subsetting repeated indexes, the resulting column names are undefined, do not rely on them.

    df[c(1, 1)]
    #>    n n.1
    #> 1  1   1
    #> 2 NA  NA
    #> 3  3   3
    #> 4 NA  NA
    tbl[c(1, 1)]
    #> # A tibble: 4 x 2
    #>       n     n
    #>   <int> <int>
    #> 1     1     1
    #> 2    NA    NA
    #> 3     3     3
    #> 4    NA    NA

For tibbles with repeated column names, subsetting by name uses the first matching column.

`nrow(df[j])` equals `nrow(df)`.

    tbl[integer()]
    #> # A tibble: 4 x 0

Tibbles support indexing by a logical matrix, but only if all values in the returned vector are compatible.

    df[is.na(df)]
    #> [[1]]
    #> [1] NA
    #>
    #> [[2]]
    #> [1] NA
    tbl[is.na(tbl)]
    #> [1] NA NA
    df[!is.na(df)]
    #> [[1]]
    #> [1] 1
    #>
    #> [[2]]
    #> [1] 3
    #>
    #> [[3]]
    #> [1] "e"
    #>
    #> [[4]]
    #> [1] "f"
    #>
    #> [[5]]
    #> [1] "g"
    #>
    #> [[6]]
    #> [1] "h"
    #>
    #> [[7]]
    #> [1] 9
    #>
    #> [[8]]
    #> [1] 10 11
    #>
    #> [[9]]
    #> [1] 12 13 14
    #>
    #> [[10]]
    #> [1] "text"
    tbl[!is.na(tbl)]
    #> Error: Can't combine `n` <integer> and
    #> `c` <character>.

### Definition of `x[, j]`

`x[, j]` is equal to `x[j]`. Tibbles do not perform column extraction if `x[j]` would yield a single column.

    df[, 1]
    #> [1]  1 NA  3 NA
    tbl[, 1]
    #> # A tibble: 4 x 1
    #>       n
    #>   <int>
    #> 1     1
    #> 2    NA
    #> 3     3
    #> 4    NA
    tbl[, 1:2]
    #> # A tibble: 4 x 2
    #>       n c
    #>   <int> <chr>
    #> 1     1 e
    #> 2    NA f
    #> 3     3 g
    #> 4    NA h

### Definition of `x[, j, drop = TRUE]`

For backward compatiblity, `x[, j, drop = TRUE]` performs column extraction, returning `x[j][[1]]` when `ncol(x[j])` is 1.

    tbl[, 1, drop = TRUE]
    #> [1]  1 NA  3 NA

## Row subsetting

### Definition of `x[i, ]`

`x[i, ]` is equal to `tibble(vec_slice(x[[1]], i), vec_slice(x[[2]], i), ...)`.2

    tbl[3, ]
    #> # A tibble: 1 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     3 g     <int [3]>

This means that `i` must be a numeric vector, or a logical vector of length `nrow(x)` or 1. For compatibility, `i` can also be a character vector containing positive numbers.

    df[mean, ]
    #> Error in xj[i]: invalid subscript type
    #> 'closure'
    tbl[mean, ]
    #> Error: Must subset rows with a valid
    #> subscript vector.
    #> [31mx[39m Subscript `mean` has the wrong type
    #> `function`.
    #> [34mℹ[39m It must be logical, numeric, or
    #> character.
    df[list(1), ]
    #> Error in xj[i]: invalid subscript type
    #> 'list'
    tbl[list(1), ]
    #> Error: Must subset rows with a valid
    #> subscript vector.
    #> [31mx[39m Subscript `list(1)` has the wrong type
    #> `list`.
    #> [34mℹ[39m It must be logical, numeric, or
    #> character.
    tbl["1", ]
    #> # A tibble: 1 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>

Exception: OOB values generate warnings instead of errors:

    df[10, ]
    #>     n    c   li
    #> NA NA <NA> NULL
    tbl[10, ]
    #> Warning: The `i` argument of
    #> ``[.tbl_df`()` must lie in [0, rows] if
    #> positive, as of tibble 3.0.0.
    #> Use `NA_integer_` as row index to obtain
    #> a row full of `NA` values.
    #> # A tibble: 1 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1    NA <NA>  <NULL>
    df["x", ]
    #>     n    c   li
    #> NA NA <NA> NULL
    tbl["x", ]
    #> Warning: The `i` argument of
    #> ``[.tbl_df`()` must use valid row names
    #> as of tibble 3.0.0.
    #> Use `NA_integer_` as row index to obtain
    #> a row full of `NA` values.
    #> # A tibble: 1 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1    NA <NA>  <NULL>

Unlike data frames, only logical vectors of length 1 are recycled.

    df[c(TRUE, FALSE), ]
    #>   n c         li
    #> 1 1 e          9
    #> 3 3 g 12, 13, 14
    tbl[c(TRUE, FALSE), ]
    #> Error: Must subset rows with a valid
    #> subscript vector.
    #> [34mℹ[39m Logical subscripts must match the size
    #> of the indexed input.
    #> [31mx[39m Input has size 4 but subscript
    #> `c(TRUE, FALSE)` has size 2.

NB: scalar logicals are recycled, but scalar numerics are not. That makes the `x[NA, ]` and `x[NA_integer_, ]` return different results.

    tbl[NA, ]
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1    NA <NA>  <NULL>
    #> 2    NA <NA>  <NULL>
    #> 3    NA <NA>  <NULL>
    #> 4    NA <NA>  <NULL>
    tbl[NA_integer_, ]
    #> # A tibble: 1 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1    NA <NA>  <NULL>

### Definition of `x[i, , drop = TRUE]`

`drop = TRUE` has no effect when not selecting a single row:

    df[1, , drop = TRUE]
    #> $n
    #> [1] 1
    #>
    #> $c
    #> [1] "e"
    #>
    #> $li
    #> $li[[1]]
    #> [1] 9
    tbl[1, , drop = TRUE]
    #> # A tibble: 1 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>

## Row and column subsetting

### Definition of `x[]` and `x[,]`

`x[]` and `x[,]` are equivalent to `x`.3

### Definition of `x[i, j]`

`x[i, j]` is equal to `x[i, ][j]`.4

### Definition of `x[[i, j]]`

`i` must be a numeric vector of length 1. `x[[i, j]]` is equal to `x[i, ][[j]]`, or `vctrs::vec_slice(x[[j]], i)`.5

    df[[1, 1]]
    #> [1] 1
    df[[1, 3]]
    #> [1] 9

This implies that `j` must be a numeric or character vector of length 1.

NB: `vec_size(x[[i, j]])` always equals 1. Unlike `x[i, ]`, `x[[i, ]]` is not valid.

## Column update

### Definition of `x[[j]] <- a`

If `a` is a vector then `x[[j]] <- a` replaces the `j`th column with value `a`.

`a` is recycled to the same size as `x` so must have size `nrow(x)` or 1. (The only exception is when `a` is `NULL`, as described below.) Recycling also works for list, data frame, and matrix columns.

    with_tbl(tbl[["li"]] <- list(0))
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2    NA f     <dbl [1]>
    #> 3     3 g     <dbl [1]>
    #> 4    NA h     <dbl [1]>
    with_df2(df2[["tb"]] <- df[1, ])
    #> Error in `[[<-.data.frame`(`*tmp*`,
    #> "tb", value = structure(list(n = 1L, :
    #> replacement has 1 row, data has 4
    with_tbl2(tbl2[["tb"]] <- tbl[1, ])
    #> # A tibble: 4 x 2
    #>    tb$n $c    $li   m[,1]  [,2]  [,3]
    #>   <int> <chr> <lis> <dbl> <dbl> <dbl>
    #> 1     1 e     <dbl…     1     0     0
    #> 2     1 e     <dbl…     0     1     0
    #> 3     1 e     <dbl…     0     0     1
    #> 4     1 e     <dbl…     0     0     0
    with_df2(df2[["m"]] <- df2[["m"]][1, , drop = FALSE])
    #> Error in `[[<-.data.frame`(`*tmp*`, "m",
    #> value = structure(c(1, 0, 0, :
    #> replacement has 1 row, data has 4
    with_tbl2(tbl2[["m"]] <- tbl2[["m"]][1, , drop = FALSE])
    #> # A tibble: 4 x 2
    #>    tb$n $c    $li   m[,1]  [,2]  [,3]
    #>   <int> <chr> <lis> <dbl> <dbl> <dbl>
    #> 1     1 e     <dbl…     1     0     0
    #> 2    NA f     <int…     1     0     0
    #> 3     3 g     <int…     1     0     0
    #> 4    NA h     <chr…     1     0     0

`j` must be a scalar numeric or a string, and cannot be `NA`. If `j` is OOB, a new column is added on the right hand side, with name repair if needed.

    with_tbl(tbl[["x"]] <- 0)
    #> # A tibble: 4 x 4
    #>       n c     li            x
    #>   <int> <chr> <list>    <dbl>
    #> 1     1 e     <dbl [1]>     0
    #> 2    NA f     <int [2]>     0
    #> 3     3 g     <int [3]>     0
    #> 4    NA h     <chr [1]>     0
    with_df(df[[4]] <- 0)
    #>    n c         li V4
    #> 1  1 e          9  0
    #> 2 NA f     10, 11  0
    #> 3  3 g 12, 13, 14  0
    #> 4 NA h       text  0
    with_tbl(tbl[[4]] <- 0)
    #> # A tibble: 4 x 4
    #>       n c     li         ...4
    #>   <int> <chr> <list>    <dbl>
    #> 1     1 e     <dbl [1]>     0
    #> 2    NA f     <int [2]>     0
    #> 3     3 g     <int [3]>     0
    #> 4    NA h     <chr [1]>     0
    with_df(df[[5]] <- 0)
    #> Warning in format.data.frame(if (omit)
    #> x[seq_len(n0), , drop = FALSE] else
    #> x, : corrupt data frame: columns will be
    #> truncated or padded with NAs
    #>    n c         li      V5
    #> 1  1 e          9 NULL  0
    #> 2 NA f     10, 11 <NA>  0
    #> 3  3 g 12, 13, 14 <NA>  0
    #> 4 NA h       text <NA>  0
    with_tbl(tbl[[5]] <- 0)
    #> Error: Can't assign to columns beyond
    #> the end with non-consecutive locations.
    #> [34mℹ[39m Input has size 3.
    #> [31mx[39m Subscript `5` contains non-consecutive
    #> location 5.

`df[[j]] <- a` replaces the complete column so can change the type.

`[[<-` supports removing a column by assigning `NULL` to it.

Removing a nonexistent column is a no-op.

### Definition of `x$name <- a`

`x$name <- a` and `x$"name" <- a` are equivalent to `x[["name"]] <- a`.6

    with_tbl(tbl$n <- 0)
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <dbl> <chr> <list>
    #> 1     0 e     <dbl [1]>
    #> 2     0 f     <int [2]>
    #> 3     0 g     <int [3]>
    #> 4     0 h     <chr [1]>
    with_tbl(tbl[["n"]] <- 0)
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <dbl> <chr> <list>
    #> 1     0 e     <dbl [1]>
    #> 2     0 f     <int [2]>
    #> 3     0 g     <int [3]>
    #> 4     0 h     <chr [1]>

`$<-` does not perform partial matching.

    with_tbl(tbl$l <- 0)
    #> # A tibble: 4 x 4
    #>       n c     li            l
    #>   <int> <chr> <list>    <dbl>
    #> 1     1 e     <dbl [1]>     0
    #> 2    NA f     <int [2]>     0
    #> 3     3 g     <int [3]>     0
    #> 4    NA h     <chr [1]>     0
    with_tbl(tbl[["l"]] <- 0)
    #> # A tibble: 4 x 4
    #>       n c     li            l
    #>   <int> <chr> <list>    <dbl>
    #> 1     1 e     <dbl [1]>     0
    #> 2    NA f     <int [2]>     0
    #> 3     3 g     <int [3]>     0
    #> 4    NA h     <chr [1]>     0

## Column subassignment: `x[j] <- a`

- If `j` is missing, it’s replaced with `seq_along(x)`
- If `j` is logical vector, it’s converted to numeric with `seq_along(x)[j]`.

### `a` is a list or data frame

If `inherits(a, "list")` or `inherits(a, "data.frame")` is `TRUE`, then `x[j] <- a` is equivalent to `x[[j[[1]]] <- a[[1]]`, `x[[j[[2]]]] <- a[[2]]`, …

    with_tbl(tbl[1:2] <- list("x", 4:1))
    #> # A tibble: 4 x 3
    #>   n         c li
    #>   <chr> <int> <list>
    #> 1 x         4 <dbl [1]>
    #> 2 x         3 <int [2]>
    #> 3 x         2 <int [3]>
    #> 4 x         1 <chr [1]>
    with_tbl(tbl[c("li", "x", "c")] <- list("x", 4:1, NULL))
    #> # A tibble: 4 x 3
    #>       n li        x
    #>   <int> <chr> <int>
    #> 1     1 x         4
    #> 2    NA x         3
    #> 3     3 x         2
    #> 4    NA x         1

If `length(a)` equals 1, then it is recycled to the same length as `j`.

    with_tbl(tbl[1:2] <- list(1))
    #> # A tibble: 4 x 3
    #>       n     c li
    #>   <dbl> <dbl> <list>
    #> 1     1     1 <dbl [1]>
    #> 2     1     1 <int [2]>
    #> 3     1     1 <int [3]>
    #> 4     1     1 <chr [1]>
    with_df(df[1:2] <- list(0, 0, 0))
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 1:2, value = list(0, 0, 0)): provided 3
    #> variables to replace 2 variables
    #>   n c         li
    #> 1 0 0          9
    #> 2 0 0     10, 11
    #> 3 0 0 12, 13, 14
    #> 4 0 0       text
    with_tbl(tbl[1:2] <- list(0, 0, 0))
    #> Error: Can't recycle `list(0, 0, 0)`
    #> (size 3) to size 2.
    with_df(df[1:3] <- list(0, 0))
    #>   n c li
    #> 1 0 0  0
    #> 2 0 0  0
    #> 3 0 0  0
    #> 4 0 0  0
    with_tbl(tbl[1:3] <- list(0, 0))
    #> Error: Can't recycle `list(0, 0)` (size
    #> 2) to size 3.

An attempt to update the same column twice gives an error.

    with_df(df[c(1, 1)] <- list(1, 2))
    #> Error in `[<-.data.frame`(`*tmp*`, c(1,
    #> 1), value = list(1, 2)): duplicate
    #> subscripts for columns
    with_tbl(tbl[c(1, 1)] <- list(1, 2))
    #> Error: Column index 1 is used more than
    #> once for assignment.

If `a` contains `NULL` values, the corresponding columns are removed after updating (i.e. position indexes refer to columns before any modifications).

    with_tbl(tbl[1:2] <- list(NULL, 4:1))
    #> # A tibble: 4 x 2
    #>       c li
    #>   <int> <list>
    #> 1     4 <dbl [1]>
    #> 2     3 <int [2]>
    #> 3     2 <int [3]>
    #> 4     1 <chr [1]>

`NA` indexes are not supported.

Just like column updates, `[<-` supports changing the type of an existing column.

Appending columns at the end (without gaps) is supported. The name of new columns is determined by the LHS, the RHS, or by name repair (in that order of precedence).

    with_tbl(tbl[c("x", "y")] <- tibble("x", x = 4:1))
    #> # A tibble: 4 x 5
    #>       n c     li        x         y
    #>   <int> <chr> <list>    <chr> <int>
    #> 1     1 e     <dbl [1]> x         4
    #> 2    NA f     <int [2]> x         3
    #> 3     3 g     <int [3]> x         2
    #> 4    NA h     <chr [1]> x         1
    with_tbl(tbl[3:4] <- list("x", x = 4:1))
    #> # A tibble: 4 x 4
    #>       n c     li        x
    #>   <int> <chr> <chr> <int>
    #> 1     1 e     x         4
    #> 2    NA f     x         3
    #> 3     3 g     x         2
    #> 4    NA h     x         1
    with_df(df[4] <- list(4:1))
    #>    n c         li V4
    #> 1  1 e          9  4
    #> 2 NA f     10, 11  3
    #> 3  3 g 12, 13, 14  2
    #> 4 NA h       text  1
    with_tbl(tbl[4] <- list(4:1))
    #> # A tibble: 4 x 4
    #>       n c     li         ...4
    #>   <int> <chr> <list>    <int>
    #> 1     1 e     <dbl [1]>     4
    #> 2    NA f     <int [2]>     3
    #> 3     3 g     <int [3]>     2
    #> 4    NA h     <chr [1]>     1
    with_df(df[5] <- list(4:1))
    #> Error in `[<-.data.frame`(`*tmp*`, 5,
    #> value = list(4:1)): new columns would
    #> leave holes after existing columns
    with_tbl(tbl[5] <- list(4:1))
    #> Error: Can't assign to columns beyond
    #> the end with non-consecutive locations.
    #> [34mℹ[39m Input has size 3.
    #> [31mx[39m Subscript `5` contains non-consecutive
    #> location 5.

Tibbles support indexing by a logical matrix, but only for a scalar RHS, and if all columns updated are compatible with the value assigned.

    with_df(df[is.na(df)] <- 4)
    #>   n c         li
    #> 1 1 e          9
    #> 2 4 f     10, 11
    #> 3 3 g 12, 13, 14
    #> 4 4 h       text
    with_tbl(tbl[is.na(tbl)] <- 4)
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     4 f     <int [2]>
    #> 3     3 g     <int [3]>
    #> 4     4 h     <chr [1]>
    with_df(df[is.na(df)] <- 1:2)
    #>   n c         li
    #> 1 1 e          9
    #> 2 1 f     10, 11
    #> 3 3 g 12, 13, 14
    #> 4 2 h       text
    with_tbl(tbl[is.na(tbl)] <- 1:2)
    #> Error: Subscript `is.na(tbl)` is a
    #> matrix, the data `1:2` must have size 1.
    with_df(df[matrix(c(rep(TRUE, 5), rep(FALSE, 7)), ncol = 3)] <- 4)
    #>   n c         li
    #> 1 4 4          9
    #> 2 4 f     10, 11
    #> 3 4 g 12, 13, 14
    #> 4 4 h       text
    with_tbl(tbl[matrix(c(rep(TRUE, 5), rep(FALSE, 7)), ncol = 3)] <- 4)
    #> Error: Assigned data `4` must be
    #> compatible with existing data.
    #> ℹ Error occurred for column `c`.
    #> x Can't convert <double> to <character>.

### `a` is a matrix or array

If `is.matrix(a)`, then `a` is coerced to a data frame with `as.data.frame()` before assigning. If rows are assigned, the matrix type must be compatible with all columns. If `is.array(a)` and `any(dim(a)[-1:-2] != 1)`, an error is thrown.

    with_tbl(tbl[1:2] <- matrix(8:1, ncol = 2))
    #> # A tibble: 4 x 3
    #>       n     c li
    #>   <int> <int> <list>
    #> 1     8     4 <dbl [1]>
    #> 2     7     3 <int [2]>
    #> 3     6     2 <int [3]>
    #> 4     5     1 <chr [1]>
    with_df(df[1:3, 1:2] <- matrix(6:1, ncol = 2))
    #>    n c         li
    #> 1  6 3          9
    #> 2  5 2     10, 11
    #> 3  4 1 12, 13, 14
    #> 4 NA h       text
    with_tbl(tbl[1:3, 1:2] <- matrix(6:1, ncol = 2))
    #> Error: Assigned data `matrix(6:1, ncol =
    #> 2)` must be compatible with existing
    #> data.
    #> ℹ Error occurred for column `c`.
    #> x Can't convert <integer> to
    #> <character>.
    with_tbl(tbl[1:2] <- array(4:1, dim = c(4, 1, 1)))
    #> # A tibble: 4 x 3
    #>       n     c li
    #>   <int> <int> <list>
    #> 1     4     4 <dbl [1]>
    #> 2     3     3 <int [2]>
    #> 3     2     2 <int [3]>
    #> 4     1     1 <chr [1]>
    with_tbl(tbl[1:2] <- array(8:1, dim = c(4, 2, 1)))
    #> # A tibble: 4 x 3
    #>       n     c li
    #>   <int> <int> <list>
    #> 1     8     4 <dbl [1]>
    #> 2     7     3 <int [2]>
    #> 3     6     2 <int [3]>
    #> 4     5     1 <chr [1]>
    with_df(df[1:2] <- array(8:1, dim = c(2, 1, 4)))
    #>   n c         li
    #> 1 8 4          9
    #> 2 7 3     10, 11
    #> 3 6 2 12, 13, 14
    #> 4 5 1       text
    with_tbl(tbl[1:2] <- array(8:1, dim = c(2, 1, 4)))
    #> Error: `array(8:1, dim = c(2, 1, 4))`
    #> must be a vector, a bare list, a data
    #> frame, a matrix, or NULL.
    with_df(df[1:2] <- array(8:1, dim = c(4, 1, 2)))
    #>   n c         li
    #> 1 8 4          9
    #> 2 7 3     10, 11
    #> 3 6 2 12, 13, 14
    #> 4 5 1       text
    with_tbl(tbl[1:2] <- array(8:1, dim = c(4, 1, 2)))
    #> Error: `array(8:1, dim = c(4, 1, 2))`
    #> must be a vector, a bare list, a data
    #> frame, a matrix, or NULL.

### `a` is another type of vector

If `vec_is(a)`, then `x[j] <- a` is equivalent to `x[j] <- list(a)`. This is primarily provided for backward compatbility.

    with_tbl(tbl[1] <- 0)
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <dbl> <chr> <list>
    #> 1     0 e     <dbl [1]>
    #> 2     0 f     <int [2]>
    #> 3     0 g     <int [3]>
    #> 4     0 h     <chr [1]>
    with_tbl(tbl[1] <- list(0))
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <dbl> <chr> <list>
    #> 1     0 e     <dbl [1]>
    #> 2     0 f     <int [2]>
    #> 3     0 g     <int [3]>
    #> 4     0 h     <chr [1]>

Matrices must be wrapped in `list()` before assignment to create a matrix column.

    with_tbl(tbl[1] <- list(matrix(1:8, ncol = 2)))
    #> # A tibble: 4 x 3
    #>   n[,1]  [,2] c     li
    #>   <int> <int> <chr> <list>
    #> 1     1     5 e     <dbl [1]>
    #> 2     2     6 f     <int [2]>
    #> 3     3     7 g     <int [3]>
    #> 4     4     8 h     <chr [1]>
    with_tbl(tbl[1:2] <- list(matrix(1:8, ncol = 2)))
    #> # A tibble: 4 x 3
    #>   n[,1]  [,2] c[,1]  [,2] li
    #>   <int> <int> <int> <int> <list>
    #> 1     1     5     1     5 <dbl [1]>
    #> 2     2     6     2     6 <int [2]>
    #> 3     3     7     3     7 <int [3]>
    #> 4     4     8     4     8 <chr [1]>

### `a` is `NULL`

Entire columns can be removed. Specifying `i` is an error.

    with_tbl(tbl[1] <- NULL)
    #> # A tibble: 4 x 2
    #>   c     li
    #>   <chr> <list>
    #> 1 e     <dbl [1]>
    #> 2 f     <int [2]>
    #> 3 g     <int [3]>
    #> 4 h     <chr [1]>
    with_tbl(tbl[, 2:3] <- NULL)
    #> # A tibble: 4 x 1
    #>       n
    #>   <int>
    #> 1     1
    #> 2    NA
    #> 3     3
    #> 4    NA
    with_df(df[1, 2:3] <- NULL)
    #> Error in x[[jj]][iseq] <- vjj:
    #> replacement has length zero
    with_tbl(tbl[1, 2:3] <- NULL)
    #> Error: `NULL` must be a vector, a bare
    #> list, a data frame or a matrix.

### `a` is not a vector

Any other type for `a` is an error. Note that if `is.list(a)` is `TRUE`, but `inherits(a, "list")` is `FALSE`, then `a` is considered to be a scalar. See `?vec_is` and `?vec_proxy` for details.

    with_df(df[1] <- mean)
    #> Error in rep(value, length.out = n):
    #> attempt to replicate an object of type
    #> 'closure'
    with_tbl(tbl[1] <- mean)
    #> Error: `mean` must be a vector, a bare
    #> list, a data frame, a matrix, or NULL.
    with_df(df[1] <- lm(mpg ~ wt, data = mtcars))
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 1, value = structure(list(coefficients
    #> = c(`(Intercept)` = 37.285126167342, :
    #> replacement element 2 has 32 rows to
    #> replace 4 rows
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 1, value = structure(list(coefficients
    #> = c(`(Intercept)` = 37.285126167342, :
    #> replacement element 3 has 32 rows to
    #> replace 4 rows
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 1, value = structure(list(coefficients
    #> = c(`(Intercept)` = 37.285126167342, :
    #> replacement element 5 has 32 rows to
    #> replace 4 rows
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 1, value = structure(list(coefficients
    #> = c(`(Intercept)` = 37.285126167342, :
    #> replacement element 7 has 5 rows to
    #> replace 4 rows
    #> Error in `[<-.data.frame`(`*tmp*`, 1,
    #> value = structure(list(coefficients =
    #> c(`(Intercept)` = 37.285126167342, :
    #> replacement element 10 has 3 rows, need
    #> 4
    with_tbl(tbl[1] <- lm(mpg ~ wt, data = mtcars))
    #> Error: `lm(mpg ~ wt, data = mtcars)`
    #> must be a vector, a bare list, a data
    #> frame, a matrix, or NULL.

## Row subassignment: `x[i, ] <- list(...)`

`x[i, ] <- a` is the same as `vec_slice(x[[j_1]], i) <- a[[1]]`, `vec_slice(x[[j_2]], i) <- a[[2]]`, … .7

    with_tbl(tbl[2:3, ] <- tbl[1, ])
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     1 e     <dbl [1]>
    #> 3     1 e     <dbl [1]>
    #> 4    NA h     <chr [1]>
    with_tbl(tbl[c(FALSE, TRUE, TRUE, FALSE), ] <- tbl[1, ])
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     1 e     <dbl [1]>
    #> 3     1 e     <dbl [1]>
    #> 4    NA h     <chr [1]>

Only values of size one can be recycled.

    with_tbl(tbl[2:3, ] <- tbl[1, ])
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     1 e     <dbl [1]>
    #> 3     1 e     <dbl [1]>
    #> 4    NA h     <chr [1]>
    with_tbl(tbl[2:3, ] <- list(tbl$n[1], tbl$c[1:2], tbl$li[1]))
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     1 e     <dbl [1]>
    #> 3     1 f     <dbl [1]>
    #> 4    NA h     <chr [1]>
    with_df(df[2:4, ] <- df[1:2, ])
    #> Error in `[<-.data.frame`(`*tmp*`, 2:4,
    #> , value = structure(list(n = c(1L, :
    #> replacement element 1 has 2 rows, need 3
    with_tbl(tbl[2:4, ] <- tbl[1:2, ])
    #> Error: Assigned data `tbl[1:2, ]` must
    #> be compatible with row subscript `2:4`.
    #> x 3 rows must be assigned.
    #> x Element 1 of assigned data has 2 rows.
    #> ℹ Only vectors of size 1 are recycled.

For compatibility, only a warning is issued for indexing beyond the number of rows. Appending rows right at the end of the existing data is supported, without warning.

    with_tbl(tbl[5, ] <- tbl[1, ])
    #> # A tibble: 5 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2    NA f     <int [2]>
    #> 3     3 g     <int [3]>
    #> 4    NA h     <chr [1]>
    #> 5     1 e     <dbl [1]>
    with_tbl(tbl[5:7, ] <- tbl[1, ])
    #> # A tibble: 7 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2    NA f     <int [2]>
    #> 3     3 g     <int [3]>
    #> 4    NA h     <chr [1]>
    #> 5     1 e     <dbl [1]>
    #> 6     1 e     <dbl [1]>
    #> 7     1 e     <dbl [1]>
    with_df(df[6, ] <- df[1, ])
    #>    n    c         li
    #> 1  1    e          9
    #> 2 NA    f     10, 11
    #> 3  3    g 12, 13, 14
    #> 4 NA    h       text
    #> 5 NA <NA>       NULL
    #> 6  1    e          9
    with_tbl(tbl[6, ] <- tbl[1, ])
    #> Error: Can't assign to rows beyond the
    #> end with non-consecutive locations.
    #> [34mℹ[39m Input has size 4.
    #> [31mx[39m Subscript `6` contains non-consecutive
    #> location 6.
    with_df(df[-5, ] <- df[1, ])
    #>   n c li
    #> 1 1 e  9
    #> 2 1 e  9
    #> 3 1 e  9
    #> 4 1 e  9
    with_tbl(tbl[-5, ] <- tbl[1, ])
    #> Error: Can't negate rows that don't
    #> exist.
    #> [31mx[39m Location 5 doesn't exist.
    #> [34mℹ[39m There are only 4 rows.
    with_df(df[-(5:7), ] <- df[1, ])
    #>   n c li
    #> 1 1 e  9
    #> 2 1 e  9
    #> 3 1 e  9
    #> 4 1 e  9
    with_tbl(tbl[-(5:7), ] <- tbl[1, ])
    #> Error: Can't negate rows that don't
    #> exist.
    #> [31mx[39m Locations 5, 6, and 7 don't exist.
    #> [34mℹ[39m There are only 4 rows.
    with_df(df[-6, ] <- df[1, ])
    #>   n c li
    #> 1 1 e  9
    #> 2 1 e  9
    #> 3 1 e  9
    #> 4 1 e  9
    with_tbl(tbl[-6, ] <- tbl[1, ])
    #> Error: Can't negate rows that don't
    #> exist.
    #> [31mx[39m Location 6 doesn't exist.
    #> [34mℹ[39m There are only 4 rows.

For compatibility, `i` can also be a character vector containing positive numbers.

    with_tbl(tbl[as.character(1:3), ] <- tbl[1, ])
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     1 e     <dbl [1]>
    #> 3     1 e     <dbl [1]>
    #> 4    NA h     <chr [1]>

## Row and column subassignment

### Definition of `x[i, j] <- a`

`x[i, j] <- a` is equivalent to `x[i, ][j] <- a`.8

Subassignment to `x[i, j]` is stricter for tibbles than for data frames. `x[i, j] <- a` can’t change the data type of existing columns.

    with_df(df[2:3, 1] <- df[1:2, 2])
    #>      n c         li
    #> 1    1 e          9
    #> 2    e f     10, 11
    #> 3    f g 12, 13, 14
    #> 4 <NA> h       text
    with_tbl(tbl[2:3, 1] <- tbl[1:2, 2])
    #> Error: Assigned data `tbl[1:2, 2]` must
    #> be compatible with existing data.
    #> ℹ Error occurred for column `n`.
    #> x Can't convert <character> to
    #> <integer>.
    with_df(df[2:3, 2] <- df[1:2, 3])
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 2:3, 2, value = list(9, 10:11)):
    #> provided 2 variables to replace 1
    #> variables
    #>    n c         li
    #> 1  1 e          9
    #> 2 NA 9     10, 11
    #> 3  3 9 12, 13, 14
    #> 4 NA h       text
    with_tbl(tbl[2:3, 2] <- tbl[1:2, 3])
    #> Error: Assigned data `tbl[1:2, 3]` must
    #> be compatible with existing data.
    #> ℹ Error occurred for column `c`.
    #> x Can't convert <list> to <character>.
    with_df(df[2:3, 3] <- df2[1:2, 1])
    #> Warning in `[<-.data.frame`(`*tmp*`,
    #> 2:3, 3, value = structure(list(n =
    #> c(1L, : provided 3 variables to replace
    #> 1 variables
    #>    n c   li
    #> 1  1 e    9
    #> 2 NA f    1
    #> 3  3 g   NA
    #> 4 NA h text
    with_tbl(tbl[2:3, 3] <- tbl2[1:2, 1])
    #> Error: Internal error in
    #> `df_cast_opts()`: Data frame must have
    #> names.
    with_df2(df2[2:3, 1] <- df2[1:2, 2])
    #> Warning in matrix(value, n, p): data
    #> length [8] is not a sub-multiple or
    #> multiple of the number of columns [3]
    #>   tb.n tb.c tb.li m.1 m.2 m.3 m.4
    #> 1    1    e     9   1   0   0   0
    #> 2    1    0     0   0   1   0   0
    #> 3    0    1     0   0   0   1   0
    #> 4   NA    h  text   0   0   0   1
    with_tbl2(tbl2[2:3, 1] <- tbl2[1:2, 2])
    #> Error: Assigned data `tbl2[1:2, 2]` must
    #> be compatible with existing data.
    #> ℹ Error occurred for column `tb`.
    #> x Can't convert <double[,4]> to
    #> <tbl_df>.
    with_tbl2(tbl2[2:3, 2] <- tbl[1:2, 1])
    #> # A tibble: 4 x 2
    #>    tb$n $c    $li   m[,1]  [,2]  [,3]
    #>   <int> <chr> <lis> <dbl> <dbl> <dbl>
    #> 1     1 e     <dbl…     1     0     0
    #> 2    NA f     <int…     1     1     1
    #> 3     3 g     <int…    NA    NA    NA
    #> 4    NA h     <chr…     0     0     0

This means that columns initialized with `NA` (which is a logical) cannot be later filled with values of a different type. Use the correct type of `NA` to initialize columns.

    with_df({df$x <- NA; df[2:3, "x"] <- 3:2})
    #>    n c         li  x
    #> 1  1 e          9 NA
    #> 2 NA f     10, 11  3
    #> 3  3 g 12, 13, 14  2
    #> 4 NA h       text NA
    with_tbl({tbl$x <- NA; tbl[2:3, "x"] <- 3:2})
    #> Error: Assigned data `3:2` must be
    #> compatible with existing data.
    #> ℹ Error occurred for column `x`.
    #> x Can't convert from <integer> to
    #> <logical> due to loss of precision.
    #> * Locations: 1, 2.
    with_tbl({tbl$x <- NA_integer_; tbl[2:3, "x"] <- 3:2})
    #> # A tibble: 4 x 4
    #>       n c     li            x
    #>   <int> <chr> <list>    <int>
    #> 1     1 e     <dbl [1]>    NA
    #> 2    NA f     <int [2]>     3
    #> 3     3 g     <int [3]>     2
    #> 4    NA h     <chr [1]>    NA

For new columns, `x[i, j] <- a` fills the unassigned rows with `NA`.

    with_df(df[2:3, "n"] <- 1)
    #>    n c         li
    #> 1  1 e          9
    #> 2  1 f     10, 11
    #> 3  1 g 12, 13, 14
    #> 4 NA h       text
    with_tbl(tbl[2:3, "n"] <- 1)
    #> # A tibble: 4 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2     1 f     <int [2]>
    #> 3     1 g     <int [3]>
    #> 4    NA h     <chr [1]>
    with_tbl(tbl[2:3, "x"] <- 1)
    #> # A tibble: 4 x 4
    #>       n c     li            x
    #>   <int> <chr> <list>    <dbl>
    #> 1     1 e     <dbl [1]>    NA
    #> 2    NA f     <int [2]>     1
    #> 3     3 g     <int [3]>     1
    #> 4    NA h     <chr [1]>    NA
    with_df(df[2:3, "n"] <- NULL)
    #> Error in x[[jj]][iseq] <- vjj:
    #> replacement has length zero
    with_tbl(tbl[2:3, "n"] <- NULL)
    #> Error: `NULL` must be a vector, a bare
    #> list, a data frame or a matrix.

Likewise, for new rows, `x[i, j] <- a` fills the unassigned columns with `NA`.

    with_tbl(tbl[5, "n"] <- list(0L))
    #> # A tibble: 5 x 3
    #>       n c     li
    #>   <int> <chr> <list>
    #> 1     1 e     <dbl [1]>
    #> 2    NA f     <int [2]>
    #> 3     3 g     <int [3]>
    #> 4    NA h     <chr [1]>
    #> 5     0 <NA>  <NULL>

### Definition of `x[[i, j]] <- a`

`i` must be a numeric vector of length 1. `x[[i, j]] <- a` is equivalent to `x[i, ][[j]] <- a`.9

NB: `vec_size(a)` must equal 1. Unlike `x[i, ] <-`, `x[[i, ]] <-` is not valid.

1. `x[j][[jj]]` is equal to `x[[ j[[jj]] ]]`, in particular `x[j][[1]]` is equal to `x[[j]]` for scalar numeric or integer `j`.↩︎

2. Row subsetting `x[i, ]` is not defined in terms of `x[[j]][i]` because that definition does not generalise to matrix and data frame columns. For efficiency and backward compatibility, `i` is converted to an integer vector by `vec_as_index(i, nrow(x))` first.↩︎

3. `x[,]` is equivalent to `x[]` because `x[, j]` is equivalent to `x[j]`.↩︎

4. A more efficient implementation of `x[i, j]` would forward to `x[j][i, ]`.↩︎

5. Cell subsetting `x[[i, j]]` is not defined in terms of `x[[j]][[i]]` because that definition does not generalise to list, matrix and data frame columns. A more efficient implementation of `x[[i, j]]` would check that `j` is a scalar and forward to `x[i, j][[1]]`.↩︎

6. `$` behaves almost completely symmetrically to `[[` when comparing subsetting and subassignment.↩︎

7. `x[i, ]` is symmetrically for subset and subassignment.↩︎

8. `x[i, j]` is symmetrically for subsetting and subassignment. A more efficient implementation of `x[i, j] <- a` would forward to `x[j][i, ] <- a`.↩︎

9. `x[[i, j]]` is symmetrically for subsetting and subassignment. An efficient implementation would check that `i` and `j` are scalar and forward to `x[i, j][[1]] <- a`.↩︎