Implement convert_lazy()

Fixes #428

Author: hadley

NAMESPACE

@@ -81,6 +81,7 @@ export(class_numeric)
 export(class_raw)
 export(class_vector)
 export(convert)
+export(convert_lazy)
 export(method)
 export(method_explain)
 export(methods_register)

NEWS.md

@@ -10,6 +10,7 @@
 * `convert()` now falls back to the corresponding `as.*()` function (e.g. `as.character()`) when converting to a base type like `class_character` and no method or inheritance-based default applies, so `convert(1, class_character)` works out of the box (#472).
 * `convert()` accepts a single unnamed list of property overrides when downcasting, as a shortcut for individual name-value pairs (#497).
 * `convert()` no longer errors when `from` is a base or S3 object and `to` is an S7 class that inherits from `from`'s class. The base/S3 value is now passed as `.data` to the `to` constructor (#537).
+* New `convert_lazy()` is a non-strict variant of `convert()` that returns `from` unchanged if it already inherits from `to`, preserving any extra properties instead of stripping them (#428).
 * `method<-` now works for double-dispatch operators (e.g. `+`, `==`, `%*%`) with plain S3 or S4 classes, even when neither operand is an S7 object (#544).
 * `method<-` no longer embeds a copy of a generic owned by another package in your package namespace. Instead it returns a sentinel value that the new `S7_on_build()` removes from the namespace at build time; call `S7_on_build()` at the top level of `zzz.R` (see `vignette("packages")`) (#364).
 * `method<-` now accepts `NULL` to unregister an existing method, e.g. `method(foo, class_character) <- NULL` (#613).

R/convert.R

@@ -54,6 +54,8 @@
 #'   programmatically.
 #' @return Either `from` coerced to class `to`, or an error if the coercion
 #'   is not possible.
+#' @seealso [convert_lazy()] for a non-strict variant that leaves `from`
+#'   unchanged when it already inherits from `to`.
 #' @export
 #' @examples
 #' Foo1 := new_class(properties = list(x = class_integer))
@@ -138,6 +140,45 @@ convert <- function(from, to, ...) {
   }
 }
 
+#' Non-strict conversion
+#'
+#' @description
+#' `convert_lazy()` is a non-strict variant of [convert()] that guarantees
+#' that the result inherits from `to`, without forcing `from` to become an exact
+#' instance of `to`, i.e. it never upcasts.
+#'
+#' @inheritParams convert
+#' @return `from`, unchanged, if it already inherits from `to`; otherwise the
+#'   result of `convert(from, to, ...)`.
+#' @seealso [convert()] for the strict variant that always returns an exact
+#'   instance of `to`.
+#' @export
+#' @examples
+#' Foo1 := new_class(properties = list(x = class_integer))
+#' Foo2 := new_class(Foo1, properties = list(y = class_double))
+#'
+#' # `convert()` upcasts by stripping the extra properties of `from`:
+#' convert(Foo2(x = 1L, y = 2), to = Foo1)
+#'
+#' # `convert_lazy()` never upcasts: because the object already inherits from
+#' # Foo1, it's returned unchanged, keeping `y`:
+#' convert_lazy(Foo2(x = 1L, y = 2), to = Foo1)
+#'
+#' # When `from` doesn't inherit from `to`, `convert_lazy()` falls back to
+#' # `convert()`, so it can still downcast or coerce to a base type:
+#' convert_lazy(Foo1(x = 1L), to = Foo2, y = 2.5)
+#' convert_lazy(1.5, to = class_character)
+convert_lazy <- function(from, to, ...) {
+  to <- as_class(to)
+  check_can_inherit(to)
+
+  if (class_inherits(from, to)) {
+    from
+  } else {
+    convert(from, to, ...)
+  }
+}
+
 # Resolve the `convert()` method for converting `from` to `to`, or `NULL` if
 # there's no registered method (so `convert()` falls back to its defaults).
 # See convert docs for the motivation for this design.

_pkgdown.yml

@@ -25,6 +25,7 @@ reference:
 - title: Method dispatch
   contents:
   - convert
+  - convert_lazy
   - class_missing
   - class_any
   - super

man/convert.Rd

@@ -245,3 +245,24 @@ test_that("base type fallback sits below user methods and inheritance", {
   expect_null(attributes(obj))
   expect_identical(obj, "hi")
 })
+
+test_that("convert_lazy() leaves `from` untouched if it inherits from `to` (#428)", {
+  foo1 := new_class(properties = list(x = class_double))
+  foo2 := new_class(foo1, properties = list(y = class_double))
+
+  obj <- foo2(x = 1, y = 2)
+  expect_identical(convert_lazy(obj, to = foo1), obj)
+  expect_identical(convert_lazy(obj, to = foo2), obj)
+})
+
+test_that("convert_lazy() falls back to convert() when not a subtype", {
+  foo1 := new_class(properties = list(x = class_double))
+  foo2 := new_class(foo1, properties = list(y = class_double))
+
+  # Downcasting still works
+  obj <- convert_lazy(foo1(x = 1), to = foo2, y = 2.5)
+  expect_equal(obj, foo2(x = 1, y = 2.5))
+
+  # As does casting to a different class
+  expect_identical(convert_lazy(1.5, class_character), "1.5")
+})