Partial apply a function, filling in some arguments.

Partial function application allows you to modify a function by pre-filling some of the arguments. It is particularly useful in conjunction with functionals and other function operators.

Note that an argument can only be partialised once.

partial(.f, ..., .env = NULL, .lazy = NULL, .first = NULL)

Arguments

.f	a function. For the output source to read well, this should be a named function.
...	named arguments to .f that should be partially applied. Pass an empty ... = argument to specify the position of future arguments relative to partialised ones. See rlang::call_modify() to learn more about this syntax. These dots support quasiquotation and quosures. If you unquote a value, it is evaluated only once at function creation time. Otherwise, it is evaluated each time the function is called.
.env	Soft-deprecated as of purrr 0.3.0. The environments are now captured via quosures.
.lazy	Soft-deprecated as of purrr 0.3.0. Please unquote the arguments that should be evaluated once at function creation time.
.first	Soft-deprecated as of purrr 0.3.0. Please pass an empty argument ... = to specify the position of future arguments.

Examples

# Partial is designed to replace the use of anonymous functions for
# filling in function arguments. Instead of:
compact1 <- function(x) discard(x, is.null)

# we can write:
compact2 <- partial(discard, .p = is.null)

# partial() works fine with functions that do non-standard
# evaluation
my_long_variable <- 1:10
plot2 <- partial(plot, my_long_variable)
plot2()
#> NULL
plot2(runif(10), type = "l")
#> NULL

# Note that you currently can't partialise arguments multiple times:
my_mean <- partial(mean, na.rm = TRUE)
my_mean <- partial(my_mean, na.rm = FALSE)
try(my_mean(1:10))
#> Error in mean.default(na.rm = TRUE, ...) : 
#>   formal argument "na.rm" matched by multiple actual arguments


# The evaluation of arguments normally occurs "lazily". Concretely,
# this means that arguments are repeatedly evaluated across invocations:
f <- partial(runif, n = rpois(1, 5))
f
#> <partialised>
#> function (...) 
#> runif(n = rpois(1, 5), ...)
f()
#> [1] 0.6999514 0.5723157 0.6044262 0.6568407 0.3489132 0.4725317 0.3447801
f()
#> [1] 0.58984497 0.21393130 0.27054784 0.08642937 0.70562574 0.75334296

# You can unquote an argument to fix it to a particular value.
# Unquoted arguments are evaluated only once when the function is created:
f <- partial(runif, n = !!rpois(1, 5))
f
#> <partialised>
#> function (...) 
#> runif(n = 7L, ...)
f()
#> [1] 0.9411215 0.9202303 0.4968767 0.2249484 0.8148729 0.4917854 0.7158358
f()
#> [1] 0.5548239 0.8256550 0.1783842 0.5351147 0.7178693 0.9787211 0.6174894


# By default, partialised arguments are passed before new ones:
my_list <- partial(list, 1, 2)
my_list("foo")
#> [[1]]
#> [1] 1
#> 
#> [[2]]
#> [1] 2
#> 
#> [[3]]
#> [1] "foo"
#> 

# Control the position of these arguments by passing an empty
# `... = ` argument:
my_list <- partial(list, 1, ... = , 2)
my_list("foo")
#> [[1]]
#> [1] 1
#> 
#> [[2]]
#> [1] "foo"
#> 
#> [[3]]
#> [1] 2
#>