negate() now works with generic functions and functions with early returns.
modify() and variants are now wrapping
[[<- instead of
[<-. This change increases the genericity of these functions but might cause different behaviour in some cases.
For instance, the
[[<- for data frames is stricter than the
[<- method and might throw errors instead of warnings. This is the case when assigning a longer vector than the number of rows.
[<- truncates the vector with a warning,
[[<- fails with an error (as is appropriate).
modify() and variants now return the same type as the input when the input is an atomic vector.
This change is meant to detect problems early with a more meaningful error message.
pluck<- functions. They modify a data structure at an existing pluck location.
modify_in() function to map a function at a pluck location.
accumulate2() now terminate early when the function returns a value wrapped with
done() (#253). When an empty
done() is returned, the value at the last iteration is returned instead.
This is a breaking change for
some() which were documented to be more liberal in the values they accepted as logical (any vector was considered
TRUE if not a single
FALSE value, no matter its length). These functions signal soft-deprecation warnings instead of a hard failure.
modify_at() now preserve the class of atomic vectors instead of promoting them to lists. New S3 methods are provided for character, logical, double, and integer classes (@t-kalinowski, #417).
By popular request,
at_depth() has been brought back as
modify_depth(), it applies a function at a specified level of a data structure. However, it transforms all traversed vectors up to
.depth to bare lists (#381).
rate_delay() functions to create rate objects. You can pass rates to
slowly(), or the lower level function
rate_sleep(). This will cause a function to wait for a given amount of time with exponential backoff (increasingly larger waiting times) or for a constant delay.
slowly() modifies a function so that it waits for a given amount of time between calls.
The interface of
partial() has been simplified. It now supports quasiquotation to control the timing of evaluation, and the
rlang::call_modify() syntax to control the position of partialised arguments.
To prevent partial matching of
...f, the latter has been renamed to
.f, which is more consistent with other purrr function signatures.
partial() now supports quasiquotation. When you unquote an argument, it is evaluated only once at function creation time. This is more flexible than the
.lazy argument since you can control the timing of evaluation for each argument. Consequently,
.lazy is soft-deprecated (#457).
Fixed an infinite loop when partialised function is given the same name as the original function (#387).
.lazy argument of
partial() is soft-deprecated in favour of quasiquotation:
The tibble package is now in Suggests rather than Imports. This brings the hard dependency of purrr to just rlang and magrittr.
compose() now returns an identity function when called without inputs.
Functions created with
compose() now have the same formal parameters as the first function to be called. They also feature a more informative print method that prints all composed functions in turn (@egnha, #366).
.dir argument in
compose(). When set to
"forward", the functions are composed from left to right rather than right to left.
The requirements of
list_merge() have been relaxed. Previously it required both the modified lists and the inputs to be either named or unnamed. This restriction now only applies to inputs in
.... When inputs are all named, they are matched to the list by name. When they are all unnamed, they are matched positionally. Otherwise, this is an error.
Fixed ordering of names returned by
accumulate_right() output. They now correspond to the order of inputs.
Fixed names of
accumulate() output when
.init is supplied.
attr_getter() no longer uses partial matching. For example, if an
x object has a
labels attribute but no
attr_getter("label")(x) will no longer extract the
labels attribute (#460, @huftis).
flatten() now supports raw and complex elements.
pluck() no longer flattens lists of arguments. You can still do it manually with
!!!. This change is for consistency with other dots-collecting functions of the tidyverse.
Note that for now you need to import
vars() from dplyr or call it qualified like
dplyr::vars(). It will be reexported from rlang in a future release.
We have standardised the purrr API for reverse iteration with a common
Note that the details of the computation have changed. Whereas
f(f(3, 2), 1), it now computes
f(1, f(2, 3)). This is the standard way of reducing from the right.
To produce the exact same reduction as
reduce_right(), simply reverse your vector and use a left reduction:
reduce2_right() is soft-deprecated without replacement. It is not clear what algorithmic properties should a right reduction have in this case. Please reach out if you know about a use case for a right reduction with a ternary function.
accumulate_right() is soft-deprecated and replaced by the new
.dir argument of
accumulate(). Note that the algorithm has slightly changed: the accumulated value is passed to the right rather than the left, which is consistent with a right reduction.
Note that retired functions are not removed from the package and will be maintained undefinitely.
%@% is soft-deprecated, please use the operator exported in rlang instead. The latter features an interface more consistent with
@ as it uses NSE, supports S4 fields, and has an assignment variant.
This change is motivated by the ambiguity of
NULL as a deletion sentinel because
NULL is also a valid value in lists. In the future,
NULL will set an element to
NULL rather than removing the element.
rerun() is now in the questioning stage because we are no longer convinced NSE functions are a good fit for purrr. Also,
rerun(n, x) can just as easily be expressed as
map(1:n, ~ x) (with the added benefit of being passed the current index as argument to the lambda).
map_call() is defunct.
We noticed the following issues during reverse dependencies checks:
reduce() fails with this message:
Error: `.x` is empty, and no `.init` supplied, this is because
reduce() now returns
.x is empty. Fix the problem by supplying an appropriate argument to
.init, or by providing special behaviour when
.x has length 0.
The type predicates have been migrated to rlang. Consequently the
bare-type-predicates documentation topic is no longer in purrr, which might cause a warning if you cross-reference it.
purrr no longer depends on lazyeval or Rcpp (or dplyr, as of the previous version). This makes the dependency graph of the tidyverse simpler, and makes purrr more suitable as a dependency of lower-level packages.
There have also been two changes to eliminate name conflicts between purrr and dplyr:
The plucking mechanism used for indexing into data structures with
map() has been extracted into the function
pluck(). Plucking is often more readable to extract an element buried in a deep data structure. Compare this syntax-heavy extraction which reads non-linearly:
to the equivalent pluck:
x %>% pluck(1, accessor, "foo")
as_function() is now
as_mapper() because it is a tranformation that makes sense primarily for mapping functions, not in general (#298).
.null has been renamed to
.default to better reflect its intent (#298).
.default is returned whenever an element is absent or empty (#231, #254).
as_mapper() sanitises primitive functions by transforming them to closures with standardised argument names (using
rlang::as_closure()). For instance
+ is transformed to
function(.x, .y) .x + .y. This results in proper argument matching so that
, .x = 5)) produces
list(5 - 1, 5 - 2, ...).
The argument list for formula-functions has been tweaked so that you can refer to arguments by position with
..2, and so on. This makes it possible to use the formula shorthand for functions with more than two arguments (#289).
All map functions now treat
NULL the same way as an empty vector (#199), and return an empty vector if any input is an empty vector.
The data frame suffix
_df has been (soft) deprecated in favour of
_dfr to more clearly indicate that it’s a row-bind. All variants now also have a
_dfc for column binding (#167). (These will not be terribly useful until
dplyr::bind_cols() have better semantics for vectors.)
The modify functions are S3 generics. However their default methods should be sufficient for most classes since they rely on the semantics of
modify.default() is thus a shorthand for
x <- map(x, f).
The legacy function
update_list() is basically a version of
list_modify that evaluates formulas within the list. It is likely to be deprecated in the future in favour of a tidyeval interface such as a list method for
Thanks to @dchiu911, the unit test coverage of purrr is now much greater.
All predicate functions are re-exported from rlang (#124).
cross_n() has been renamed to
_n suffix was removed for consistency with
pmap() (originally called
map_n() at the start of the project) and
transpose() (originally called
cross_d() has been renamed to
cross_df() for consistency with
reduce() now throws an error if
.x is empty and
.init is not supplied.
zip_n() have been removed.
set_names() can now take a function to tranform the names programmatically (#276), and you can supply names in
... to reduce typing even more more (#316).
set_names() is now powered by
This is a compatibility release with dplyr 0.6.0.
unslice()have been moved to purrrlyr. This is a bit of an aggresive change but it allows us to make the dependencies much lighter.
as_function() gains a
.null argument that for character and numeric values allows you to specify what to return for null/absent elements (#110). This can be used with any map function, e.g.
map_int(x, 1, .null = NA)
as_function() is now generic.
is_function() that returns
TRUE only for regular functions.
Fix crash on GCC triggered by
There are two handy infix functions:
accumulate() has been added to handle recursive folding. It is shortand for
Reduce(f, .x, accumulate = TRUE) and follows a similar syntax to
reduce() (#145). A right-hand version
accumulate_right() was also added.
invoke() has been overhauled to be more useful: it now works similarly to
.x is NULL, and hence
map_call() has been deprecated.
invoke_map() is a vectorised complement to
invoke() (#125), and comes with typed variants
zip_n() (#128). The name more clearly reflects the intent (transposing the first and second levels of list). It no longer has fields argument or the
.simplify argument; instead use the new
possibly() are experimental functions for working with functions with side-effects (e.g. printed output, messages, warnings, and errors) (#120).
safely() is a version of
try() that modifies a function (rather than an expression), and always returns a list with two components,
We are still figuring out what belongs in dplyr and what belongs in purrr. Expect much experimentation and many changes with these functions.
map() now always returns a list. Data frame support has been moved to
dmap(). The latter supports sliced data frames as a shortcut for the combination of
x %>% by_slice(dmap, fun, .collate = "rows"). The conditional variants
dmap_if() also support sliced data frames and will recycle scalar results to the slice size.
map_rows() has been renamed to
invoke_rows(). As other rows-based functionals, it collates results inside lists by default, but with column collation this function is equivalent to
The rows-based functionals gain a
.to option to name the output column as well as a
.collate argument. The latter allows to collate the output in lists (by default), on columns or on rows. This makes these functions more flexible and more predictable.