export ud are convertible (#263)

* export ud_are_convertible * fix review remarks * minor changes Co-authored-by: Christophe_Regouby <[email protected]> Co-authored-by: Iñaki Úcar <[email protected]>
r-quantities · Nov 28, 2020 · 67c608f · 67c608f
1 parent 3648766
commit 67c608f
Show file tree

Hide file tree

Showing 5 changed files with 64 additions and 3 deletions.
diff --git a/NAMESPACE b/NAMESPACE
@@ -78,6 +78,7 @@ export(make_units)
 export(mixed_units)
 export(remove_symbolic_unit)
 export(set_units)
+export(ud_are_convertible)
 export(unitless)
 export(units_options)
 export(valid_udunits)

diff --git a/NEWS.md b/NEWS.md
@@ -3,6 +3,8 @@
 * add `load_units_xml` to enable database reloading as well as loading
   user-provided unit systems; #254 addressing #243, #244
 
+* export `ud_are_convertible`; #263 addressing #258 @cregouby
+
 * remove deprecations: `as.units`, `as_cf`, `make_unit`, `parse_unit`; #259
 
 * remove deprecated pre-computed `ud_units` database; #259

diff --git a/R/udunits.R b/R/udunits.R
@@ -1,6 +1,25 @@
-ud_are_convertible = function(u1, u2) {
-	res <- try(R_ut_are_convertible(R_ut_parse(as.character(u1)), R_ut_parse(as.character(u2))),
-		silent = TRUE)
+#' Test if two units are convertible
+#'
+#' Parses and checks whether units can be converted by UDUNITS-2. Units may not
+#' be convertible either because they are different magnitudes or because one
+#' (or both) units are not defined in the database.
+#'
+#' @param x character or object of class \code{symbolic_units}, for the symbol
+#' of the first unit.
+#' @param y character or object of class \code{symbolic_units}, for the symbol
+#' of the second unit.
+#'
+#' @return boolean, \code{TRUE} if both units exist and are convertible.
+#' @export
+#'
+#' @examples
+#' ud_are_convertible("m", "km")
+#' a <- set_units(1:3, m/s)
+#' ud_are_convertible(units(a), "km/h")
+#' ud_are_convertible("s", "kg")
+ud_are_convertible = function(x, y) {
+	res <- try(R_ut_are_convertible(
+	  R_ut_parse(as.character(x)), R_ut_parse(as.character(y))), silent = TRUE)
 	! inherits(res, "try-error") && res
 }
 

diff --git a/man/ud_are_convertible.Rd b/man/ud_are_convertible.Rd
diff --git a/tests/testthat/test_conversion.R b/tests/testthat/test_conversion.R
@@ -209,3 +209,13 @@ test_that("NA as units generate warnings", {
   expect_error(set_units(NA_real_, NA_character_, mode="standard"), "a missing value for units is not allowed")
   expect_error(set_units(NA_real_, NA, mode="standard"), "a missing value for units is not allowed")
 })
+
+test_that("ud_are_convertible return the expected value", {
+  x <- 1:10 * as_units("m")
+  expect_is(ud_are_convertible("m", "km"), "logical")
+  expect_true(ud_are_convertible("m", "km"))
+  expect_true(ud_are_convertible(units(x), "km"))
+  expect_false(ud_are_convertible("s", "kg"))
+
+})
+