Releases: tidyverse/purrr
purrr 1.0.2
purrr 1.0.1
-
As of purrr 1.0.0, the
map()
family of functions wraps all errors generated
by.f
inside an wrapper error that tracks the iteration index. As of purrr
1.0.1, this error now has a custom class (purrr_error_indexed
),
location
andname
fields, and is documented in?purrr_error_indexed
(#1027). -
map()
errors with named inputs also report the name of the element that
errored. -
Fixed an issue where progress bars weren't being closed when user interrupts
or errors were encountered during amap()
call (#1024). -
Fixed an invalid C signature for
pluck()
(#1018). -
Set
Biarch: true
to build purrr on 32-bit Windows on R < 4.2.0 (#1017).
purrr 1.0.0
Breaking changes
Core purpose refinements
-
cross()
and all its variants have been deprecated in favour of
tidyr::expand_grid()
. These functions were slow and buggy and we
no longer think they are the right approach to solving this problem.
See #768 for more information. -
update_list()
(#858) andrerun()
(#877), and the use of tidyselect
withmap_at()
and friends (#874) have been deprecated. These functions
use some form of non-standard evaluation which we now believe is a poor
fit for purrr. -
The
lift_*
family of functions has been deprecated. We no longer believe
these to be a good fit for purrr because they rely on a style of function
manipulation that is very uncommon in R code (#871). -
prepend()
,rdunif()
,rbernoulli()
,when()
, andlist_along()
have
all been deprecated (#925). It's now clear that they don't align with the
core purpose of purrr. -
splice()
is deprecated because we no longer believe that automatic
splicing makes for good UI. Instead uselist2()
+!!!
or
list_flatten()
(#869).
Mapping
-
Use of map functions with expressions, calls, and pairlists has been
deprecated (#961). -
All map
_raw()
variants have been deprecated because they are of limited
use and you can now usemap_vec()
instead (#903). -
In
map_chr()
, automatic conversion from logical, integer, and double to
character is now deprecated. Use an explicitas.character()
if needed
(#904).
Deprecation next steps
-
as_function()
and the...f
argument topartial()
are no longer
supported. They have been defunct for quite some time. -
Soft deprecated functions:
%@%
,reduce_right()
,reduce2_right()
,
accumulate_right()
are now fully deprecated. Similarly, the
.lazy
,.env
, and.first
arguments topartial()
,
and the.right
argument todetect()
anddetect_index()
are fully deprecated. Removing elements withNULL
inlist_modify()
and
list_merge()
is now fully deprecated. -
is_numeric()
andis_scalar_numeric()
have been removed. They have
been deprecated since purrr 0.2.3 (Sep 2017). -
invoke_*()
is now deprecated. It was superseded in 0.3.0 (Jan 2019) and
3.5 years later, we have decided to deprecate it as part of the API
refinement in the 1.0.0 release. -
map_call()
has been removed. It was made defunct in 0.3.0 (Jan 2019).
New features
-
*_at()
can now take a function (or formula) that's passed the vector of
element names and returns the elements to select. -
New
map_vec()
,map2_vec()
, andpmap_vec()
work on all types of vectors,
extendingmap_lgl()
,map_int()
, and friends so that you can easily work
with dates, factors, date-times and more (#435). -
New
keep_at()
anddiscard_at()
that work likekeep()
anddiscard()
but operation on element names rather than element contents (#817). -
Some mapping functions have now a
.progress
argument to create a
progress bar. See?progress_bars
(#149). -
purrr is now licensed as MIT (#805).
-
modify()
,modify_if()
,modify_at()
, andmodify2()
are no longer
generics. We have discovered a simple implementation that no longer requires
genericity and methods were only provided by a very small number of packages
(#894). -
purrr now uses the base pipe (
|>
) and anonymous function short hand (\(x)
),
in all examples. This means that examples will no longer work in R 4.0 and
earlier so in those versions of R, the examples are automatically converted
to a regular section with a note that they might not work (#936). -
When map functions fail, they now report the element they failed at (#945).
-
New
modify_tree()
for recursively modifying nested data structures (#720).
Flattening and simplification
-
New
list_c()
,list_rbind()
, andlist_cbind()
make it easy to
c()
,rbind()
, orcbind()
all of the elements in a list. -
New
list_simplify()
reduces a list of length-1 vectors to a simpler atomic
or S3 vector (#900). -
New
list_transpose()
which automatically simplifies if possible (#875). -
accumulate()
andaccumulate2()
now both simplify the output if possible
using vctrs. New argumentssimplify
andptype
allow you to control the
details of simplification (#774, #809). -
flatten()
and friends are superseded in favour oflist_flatten()
,
list_c()
,list_cbind()
, andlist_rbind()
. -
*_dfc()
and*_dfr()
have been superseded in favour of using the
appropriate map function along withlist_rbind()
orlist_cbind()
(#912). -
simplify()
,simplify_all()
, andas_vector()
have been superseded in
favour oflist_simplify()
. It provides a more consistent definition of
simplification (#900). -
transpose()
has been superseded in favour oflist_transpose()
(#875).
It has built-in simplification.
Tidyverse consistency
-
_lgl()
,_int()
,_int()
, and_dbl()
now use the same (strict) coercion
methods as vctrs (#904). This means that:-
map_chr(TRUE, identity)
,map_chr(0L, identity)
, and
map_chr(1L, identity)
are deprecated because we now believe that
converting a logical/integer/double to a character vector should require
an explicit coercion. -
map_int(1.5, identity)
now fails because we believe that silently
truncating doubles to integers is dangerous. But note that
map_int(1, identity)
still works since no numeric precision is lost. -
map_int(c(TRUE, FALSE), identity)
,map_dbl(c(TRUE, FALSE), identity)
,
map_lgl(c(1L, 0L), identity)
andmap_lgl(c(1, 0), identity)
now
succeed because 1/TRUE and 0/FALSE should be interchangeable.
-
-
map2()
,modify2()
, andpmap()
now use tidyverse recycling rules where
vectors of length 1 are recycled to any size but all others must have
the same length (#878). -
map2()
andpmap()
now recycle names of their first input if
needed (#783). -
modify()
,modify_if()
, andmodify_at()
have been reimplemented using
vctrs principles. This shouldn't have an user facing impact, but it does
make the implementation much simpler.
Plucking
-
vec_depth()
is nowpluck_depth()
and works with more types of input
(#818). -
pluck()
now requires indices to be length 1 (#813). It also now reports
the correct type if you supply an unexpected index. -
pluck()
now accepts negative integers, indexing from the right (#603). -
pluck()
andchuck()
now fail if you provide named inputs to ... (#788). -
pluck()
no longer replaces 0-length vectors withdefault
; it now
only applies absent andNULL
components (#480). -
pluck<-
/assign_in()
can now modify non-existing locations (#704).
Setting with NULL
-
pluck<-
/assign_in()
now sets elements toNULL
rather than removing them
(#636). Now use the explicitzap()
if you want to remove elements. -
modify()
,modify2()
, andmodify_if()
now correctly handleNULL
s
in replacement values (#655, #746, #753). -
list_modify()
's interface has been standardised. Modifying withNULL
now always creates aNULL
in the output (#810)
list_
functions`
-
New
list_assign()
which is similar tolist_modify()
but doesn't work
recursively (#822). -
list_modify()
no longer recurses into data frames (and other objects built
on top of lists that are fundamentally non-list like) (#810). You can
revert to the previous behaviour by setting.is_node = is.list
.
Minor improvements and bug fixes
-
capture_output()
correctly usesconditionMessage()
instead of directly
interrogating themessage
field (#1010). -
modify()
no longer works with calls or pairlists. -
modify_depth()
is no longer a generic. This makes it more consistent
withmap_depth()
. -
map_depth()
andmodify_depth()
have a newis_node
argument that
allows you to control what counts as a level. The default uses
vec_is_list()
to avoid recursing into rich S3 objects like linear models
or data.frames (#958, #920). -
map_depth()
andmodify_depth()
now correctly recurse at depth 1. -
as_mapper()
is now around twice as fast when used with character,
integer, or list (#820). -
possibly()
now defaultsotherwise
to NULL. -
modify_if(.else)
is now actually evaluated for atomic vectors (@mgirlich,
#701). -
lmap_if()
correctly handles.else
functions (#847). -
every()
now correctly propagates missing values using the same
rules as&&
(#751). Internally, it has become a wrapper around
&&
. This makes it consistent with&&
and also withsome()
which has always been a wrapper around||
with the same
propagation rules. -
every()
andsome()
now properly check the return value of their
predicate function. It must now return aTRUE
,FALSE
, orNA
. -
Greatly improved performance of functions created with
partial()
(#715).
Their invocation is now as fast as for functions creating manually. -
partial()
no longer inlines the function in the call stack. This
fixes issues whenpartial()
is used withlm()
for instance (#707).
purrr 0.3.5
- Fixes for CRAN checks.
purrr 0.3.4
-
Added documentation for exporting functions created with purrr
adverb (@njtierney, #668). See?faq-adverbs-export
. -
Added
none()
, which tests that a predicate is false for all elements
(the opposite ofevery()
) (@AliciaSchep, #735).
purrr 0.3.3
purrr 0.3.2
- Fix protection issues reported by rchk.
purrr 0.3.1
purrr 0.3.0
Breaking changes
-
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. -
All functionals taking predicate functions (like
keep()
,
detect()
,some()
) got stricter. Predicate functions must now
return a singleTRUE
orFALSE
.This change is meant to detect problems early with a more meaningful
error message.
Plucking
-
New
chuck()
function. This is a strict variant ofpluck()
that
throws errors when an element does not exist instead of returning
NULL
(@daniel-barnett, #482). -
New
assign_in()
andpluck<-
functions. They modify a data
structure at an existing pluck location. -
New
modify_in()
function to map a function at a pluck location. -
pluck()
now dispatches properly with S3 vectors. The vector class
must implement alength()
method for numeric indexing and a
names()
method for string indexing. -
pluck()
now supports primitive functions (#404).
Mapping
-
New
.else
argument formap_if()
andmodify_if()
. They take an
alternative function that is mapped over elements of the input for
which the predicate function returnsFALSE
(#324). -
reduce()
,reduce2()
,accumulate()
, andaccumulate2()
now
terminate early when the function returns a value wrapped with
done()
(#253). When an emptydone()
is returned, the
value at the last iteration is returned instead. -
Functions taking predicates (
map_if()
,keep()
,some()
,
every()
,keep()
, etc) now fail with an informative message when
the return value is notTRUE
orFALSE
(#470).This is a breaking change for
every()
andsome()
which were
documented to be more liberal in the values they accepted as logical
(any vector was consideredTRUE
if not a singleFALSE
value, no
matter its length). These functions signal soft-deprecation warnings
instead of a hard failure. -
modify()
and variants are now implemented usinglength()
,[[
,
and[[<-
methods. This implementation should be compatible with
most vector classes. -
New
modify2()
andimodify()
functions. These work likemap()
andimap()
but preserve the type of.x
in the return value. -
pmap()
andpwalk()
now preserve class for inputs offactor
,
Date
,POSIXct
and other atomic S3 classes with an appropriate
[[
method (#358, @mikmart). -
modify()
,modify_if()
andmodify_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
map_depth()
. Likemodify_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). -
map_at()
,modify_at()
andlmap_at()
accept negative values for
.at
, ignoring elements at those positions. -
map()
andmodify()
now work with calls and pairlists (#412). -
modify_depth()
now modifies atomic leaves as well. This makes
modify_depth(x, 1, fn)
equivalent tomodify(x, fn)
(#359). -
New
accumulate2()
function which is toaccumulate()
what
reduce2()
is toreduce()
.
Rates
-
New
rate_backoff()
andrate_delay()
functions to create rate
objects. You can pass rates toinsistently()
,slowly()
, or the
lower level functionrate_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. -
insistently(f)
modifies a function,f
, so that it is repeatedly
called until it succeeds (@richierocks, @ijlyttle).slowly()
modifies a function so that it waits for a given amount
of time between calls.
partial()
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.
-
partial()
now supports empty... =
argument to specify the
position of future arguments, relative to partialised ones. This
syntax is borrowed from (and implemented with)rlang::call_modify()
.To prevent partial matching of
...
on...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). -
partial()
now callsas_closure()
on primitive functions to
ensure argument matching (#360). -
The
.lazy
argument ofpartial()
is soft-deprecated in favour of
quasiquotation:# Before partial(fn, u = runif(1), n = rnorm(1), .lazy = FALSE) # After partial(fn, u = !!runif(1), n = !!rnorm(1)) # All constant partial(fn, u = !!runif(1), n = rnorm(1)) # First constant
Minor improvements and fixes
-
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). -
New
.dir
argument incompose()
. When set to"forward"
, the
functions are composed from left to right rather than right to left. -
list_modify()
now supports thezap()
sentinel (reexported from
rlang) to remove elements from lists. Consequently, removing
elements with the ambiguous sentinelNULL
is soft-deprecated. -
The requirements of
list_modify()
andlist_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. -
compose()
now supports composition with lambdas (@ColinFay, #556) -
Fixed a
pmap()
crash with empty lists on the Win32 platform (#565). -
modify_depth
now has.ragged
argument evaluates correctly to
TRUE
by default when.depth < 0
(@cderv, #530). -
accumulate()
now inherits names from their first input (@AshesITR, #446). -
attr_getter()
no longer uses partial matching. For example, if an
x
object has alabels
attribute but nolabel
attribute,
attr_getter("label")(x)
will no longer extract thelabels
attribute (#460, @huftis). -
flatten_dfr()
andflatten_dfc()
now aborts if dplyr is not installed. (#454) -
imap_dfr()
now works with.id
argument is provided (#429) -
list_modify()
,update_list()
andlist_merge()
now handle duplicate
duplicate argument names correctly (#441, @mgirlich). -
map_raw
,imap_raw
,flatten_raw
,invoke_map_raw
,map2_raw
andpmap_raw
added to support raw vectors. (#455, @romainfrancois) -
flatten()
now supports raw and complex elements. -
array_branch()
andarray_tree()
now retain thedimnames()
of the input
array (#584, @flying-sheep) -
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. -
map_at()
,lmap_at()
andmodify_at()
now supports selection
usingvars()
andtidyselect
(@ColinFay, #608).Note that for now you need to import
vars()
from dplyr or call it
qualified likedplyr::vars()
. It will be reexported from rlang in
a future release. -
detect()
now has a .default argument to specify the value returned when
nothing is detected (#622, @ColinFay).
Life cycle
.dir
arguments
We have standardised the purrr API for reverse iteration with a common
.dir
argument.
-
reduce_right()
is soft-deprecated and replaced by a new.dir
argument ofreduce()
:# Before: reduce_right(1:3, f) # After: reduce(1:3, f, .dir = "backward")
Note that the details of the computation have changed. Whereas
reduce_right()
computedf(f(3, 2), 1)
, it now computesf(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:# Before: reduce_right(1:3, f) # After: reduce(rev(1:3), f)
-
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...
purrr 0.2.5
This is a maintenance release following the release of dplyr 0.7.5.