operator: Multiple assignment operators
In r-lib/zeallot: Multiple, Unpacking, and Destructuring Assignment

Description Usage Arguments Value Name Structure See Also Examples

Assign values to name(s).

1
2
3

x %<-% value

value %->% x

`x`	A name structure, see section below.
`value`	A list of values, vector of values, or R object to assign.

%<-% and %->% invisibly return value.

These operators are used primarily for their assignment side-effect. %<-% and %->% assign into the environment in which they are evaluated.

the basics

At its simplest, the name structure may be a single variable name, in which case %<-% and %->% perform regular assignment, x %<-% list(1, 2, 3) or list(1, 2, 3) %->% x.

To specify multiple variable names use a call to c(), for example c(x, y, z) %<-% c(1, 2, 3).

When value is neither an atomic vector nor a list, %<-% and %->% will try to destructure value into a list before assigning variables, see destructure().

object parts

Like assigning a variable, one may also assign part of an object, c(x, x[[1]]) %<-% list(list(), 1).

nested names

One can also nest calls to c() when needed, c(x, c(y, z)). This nested structure is used to unpack nested values, c(x, c(y, z)) %<-% list(1, list(2, 3)).

collector variables

To gather extra values from the beginning, middle, or end of value use a collector variable. Collector variables are indicated with a ... prefix, c(...start, z) %<-% list(1, 2, 3, 4).

skipping values

Use . in place of a variable name to skip a value without raising an error or assigning the value, c(x, ., z) %<-% list(1, 2, 3).

Use ... to skip multiple values without raising an error or assigning the values, c(w, ..., z) %<-% list(1, NA, NA, 4).

default values

Use = to specify a default value for a variable, c(x, y = NULL) %<-% tail(1, 2).

When assigning part of an object a default value may not be specified because of the syntax enforced by R. The following would raise an "unexpected '=' ..." error, c(x, x[[1]] = 1) %<-% list(list()).

For more on unpacking custom objects please refer to destructure().

# basic usage
c(a, b) %<-% list(0, 1)

a  # 0
b  # 1

# unpack and assign nested values
c(c(e, f), c(g, h)) %<-% list(list(2, 3), list(3, 4))

e  # 2
f  # 3
g  # 4
h  # 5

# can assign more than 2 values at once
c(j, k, l) %<-% list(6, 7, 8)

# assign columns of data frame
c(erupts, wait) %<-% faithful

erupts  # 3.600 1.800 3.333 ..
wait    # 79 54 74 ..

# assign only specific columns, skip
# other columns
c(mpg, cyl, disp, ...) %<-% mtcars

mpg   # 21.0 21.0 22.8 ..
cyl   # 6 6 4 ..
disp  # 160.0 160.0 108.0 ..

# skip initial values, assign final value
TODOs <- list("make food", "pack lunch", "save world")

c(..., task) %<-% TODOs

task  # "save world"

# assign first name, skip middle initial,
# assign last name
c(first, ., last) %<-% c("Ursula", "K", "Le Guin")

first  # "Ursula"
last   # "Le Guin"

# simple model and summary
mod <- lm(hp ~ gear, data = mtcars)

# extract call and fstatistic from
# the summary
c(modcall, ..., modstat, .) %<-% summary(mod)

modcall
modstat

# unpack nested values w/ nested names
fibs <- list(1, list(2, list(3, list(5))))

c(f2, c(f3, c(f4, c(f5)))) %<-% fibs

f2  # 1
f3  # 2
f4  # 3
f5  # 5

# unpack first numeric, leave rest
c(f2, fibcdr) %<-% fibs

f2      # 1
fibcdr  # list(2, list(3, list(5)))

# swap values without using temporary variables
c(a, b) %<-% c("eh", "bee")

a  # "eh"
b  # "bee"

c(a, b) %<-% c(b, a)

a  # "bee"
b  # "eh"

# unpack `strsplit` return value
names <- c("Nathan,Maria,Matt,Polly", "Smith,Peterson,Williams,Jones")

c(firsts, lasts) %<-% strsplit(names, ",")

firsts  # c("Nathan", "Maria", ..
lasts   # c("Smith", "Peterson", ..

# handle missing values with default values
parse_time <- function(x) {
  strsplit(x, " ")[[1]]
}

c(hour, period = NA) %<-% parse_time("10:00 AM")

hour    # "10:00"
period  # "AM"

c(hour, period = NA) %<-% parse_time("15:00")

hour    # "15:00"
period  # NA

# right operator
list(1, 2, "a", "b", "c") %->% c(x, y, ...chars)

x      # 1
y      # 2
chars  # list("a", "b", "c")

# magrittr chains, install.packages("magrittr") for this example
if (requireNamespace("magrittr", quietly = TRUE)) {
  library(magrittr)

  c("hello", "world!") %>%
    paste0("\n") %>%
    lapply(toupper) %->%
    c(greeting, subject)

  greeting  # "HELLO\n"
  subject   # "WORLD!\n"
}