purrr 0.3.0 2019-01-27

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 single TRUE or FALSE.

    This change is meant to detect problems early with a more meaningful error message.

Plucking

  • New chuck() function. This is a strict variant of pluck() that throws errors when an element does not exist instead of returning NULL (@daniel-barnett, #482).

  • New assign_in() and pluck<- 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 a length() method for numeric indexing and a names() method for string indexing.

  • pluck() now supports primitive functions (#404).

Mapping

Rates

  • New rate_backoff() and rate_delay() functions to create rate objects. You can pass rates to insistently(), 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.

  • 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 calls as_closure() on primitive functions to ensure argument matching (#360).

  • The .lazy argument of partial() 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 in compose(). When set to "forward", the functions are composed from left to right rather than right to left.

  • list_modify() now supports the zap() sentinel (reexported from rlang) to remove elements from lists. Consequently, removing elements with the ambiguous sentinel NULL is soft-deprecated.

  • The requirements of list_modify() and 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.

  • 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 a labels attribute but no label attribute, attr_getter("label")(x) will no longer extract the labels attribute (#460, @huftis).

  • flatten_dfr() and flatten_dfc() now aborts if dplyr is not installed. (#454)

  • imap_dfr() now works with .id argument is provided (#429)

  • list_modify(), update_list() and list_merge() now handle duplicate duplicate argument names correctly (#441, @mgirlich).

  • map_raw, imap_raw, flatten_raw, invoke_map_raw, map2_raw and pmap_raw added to support raw vectors. (#455, @romainfrancois)

  • flatten() now supports raw and complex elements.

  • array_branch() and array_tree() now retain the dimnames() 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() and modify_at() now supports selection using vars() and tidyselect (@ColinFay, #608).

    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.

  • 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.

Simplification of partial()

The interface of partial() has been simplified (see more about partial() below):

  • The .lazy argument of partial() is soft-deprecated in favour of quasiquotation.

  • We had to rename ...f to .f in partial() in order to support ... = argument (which would otherwise partial-match on ...f). This also makes partial() more consistent with other purrr function signatures.

Retirement of invoke()

invoke() and invoke_map() are retired in favour of exec(). Note that retired functions are no longer under active development, but continue to be maintained undefinitely in the package.

Other lifecycle changes

  • %@% 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.

  • Removing elements from lists using NULL in list_modify() is soft-deprecated. Please use the new zap() sentinel reexported from rlang instead:

      # Before:
      list_modify(x, foo = NULL)
    
      # After:
      list_modify(x, foo = zap())

    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.

purrr 0.2.5 2018-05-29

  • This is a maintenance release following the release of dplyr 0.7.5.

purrr 0.2.4 2017-10-18

  • Fixes for R 3.1.

purrr 0.2.3 2017-08-02

Breaking changes

We noticed the following issues during reverse dependencies checks:

  • If reduce() fails with this message: Error: `.x` is empty, and no `.init` supplied, this is because reduce() now returns .init when .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.

Dependencies

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:

  • order_by(), sort_by() and split_by() have been removed. order_by() conflicted with dplyr::order_by() and the complete family doesn’t feel that useful. Use tibbles instead (#217).

  • contains() has been renamed to has_element() to avoid conflicts with dplyr (#217).

pluck()

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:

accessor(x[[1]])$foo

to the equivalent pluck:

x %>% pluck(1, accessor, "foo")

Map helpers

  • 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 map(1:10, partial(-, .x = 5)) produces list(5 - 1, 5 - 2, ...).

  • Recursive indexing can now extract objects out of environments (#213) and S4 objects (#200), as well as lists.

  • attr_getter() makes it possible to extract from attributes like map(list(iris, mtcars), attr_getter("row.names")).

  • The argument list for formula-functions has been tweaked so that you can refer to arguments by position with ..1, ..2, and so on. This makes it possible to use the formula shorthand for functions with more than two arguments (#289).

  • possibly(), safely() and friends no longer capture interrupts: this means that you can now terminate a mapper using one of these with Escape or Ctrl + C (#314)

Map functions

  • 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.

  • All map() functions now force their arguments in the same way that base R does for lapply() (#191). This makes map() etc easier to use when generating functions.

  • A new family of “indexed” map functions, imap(), imap_lgl() etc, provide a short-hand for map2(x, names(x)) or map2(x, seq_along(x)) (#240).

  • 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_rows()/dplyr::bind_cols() have better semantics for vectors.)

Modify functions

A new modify() family returns the same output of the type as the input .x. This is in contrast to the map() family which always returns a list, regardless of the input type.

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).

New functions

  • auto_browse(f) returns a new function that automatically calls browser() if f throws an error (#281).

  • vec_depth() computes the depth (i.e. the number of levels of indexing) or a vector (#243).

  • reduce2() and reduce2_right() make it possible to reduce with a 3 argument function where the first argument is the accumulated value, the second argument is .x, and the third argument is .y (#163).

  • list_modify() extends stats::modifyList() to replace by position if the list is not named.(#201). list_merge() operates similarly to list_modify() but combines instead of replacing (#322).

  • 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 dplyr::mutate().

Minor improvements and bug fixes

  • Thanks to @dchiu911, the unit test coverage of purrr is now much greater.

  • All predicate functions are re-exported from rlang (#124).

  • compact() now works with standard mapper conventions (#282).

  • cross_n() has been renamed to cross(). The _n suffix was removed for consistency with pmap() (originally called map_n() at the start of the project) and transpose() (originally called zip_n()). Similarly, cross_d() has been renamed to cross_df() for consistency with map_df().

  • every() and some() now return NA if present in the input (#174).

  • invoke() uses a more robust approach to generate the argument list (#249) It no longer uses lazyeval to figure out which enviroment a character f comes from.

  • is_numeric() and is_scalar_numeric() are deprecated because they don’t test for what you might expect at first sight.

  • reduce() now throws an error if .x is empty and .init is not supplied.

  • Deprecated functions flatmap(), map3(), map_n(), walk3(), walk_n(), zip2(), zip3(), zip_n() have been removed.

  • pmap() coerces data frames to lists to avoid the expensive [.data.frame which provides security that is unneeded here (#220).

  • rdunif() checks its inputs for validity (#211).

  • 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 rlang::set_names().

  • safely() now actually uses the quiet argument (#296).

  • transpose() now matches by name if available (#164). You can override the default choice with the new .names argument.

  • The function argument of detect() and detect_index() have been renamed from .p to .f. This is because they have mapper semantics rather than predicate semantics.

purrr 0.2.2.1 Unreleased

This is a compatibility release with dplyr 0.6.0.

  • All data-frame based mappers have been removed in favour of new functions and idioms in the tidyverse. dmap(), dmap_at(), dmap_if(), invoke_rows(), slice_rows(), map_rows(), by_slice(), by_row(), and unslice() have been moved to purrrlyr. This is a bit of an aggresive change but it allows us to make the dependencies much lighter.

purrr 0.2.2 2016-06-18

  • Fix for dev tibble support.

  • as_function() now supports list arguments which allow recursive indexing using either names or positions. They now always stop when encountering the first NULL (#173).

  • accumulate and reduce correctly pass extra arguments to the worker function.

purrr 0.2.1 2016-02-13

  • 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.

  • New is_function() that returns TRUE only for regular functions.

  • Fix crash on GCC triggered by invoke_rows().

purrr 0.2.0 2016-01-04

New functions

Row based functionals

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 map_df() and dmap(). The latter supports sliced data frames as a shortcut for the combination of by_slice() and dmap(): x %>% by_slice(dmap, fun, .collate = "rows"). The conditional variants dmap_at() and 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 plyr::mdply().

  • 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.

Bug fixes and minor changes

  • as_function(), which converts formulas etc to functions, is now exported (#123).

  • rerun() is correctly scoped (#95)

  • update_list() can now modify an element called x (#98).

  • map*() now use custom C code, rather than relying on lapply(), mapply() etc. The performance characteristcs are very similar, but it allows us greater control over the output (#118).

  • map_lgl() now has second argument .f, not .p (#134).

Deprecated functions