Document expect_length() and expect_shape() together (#2134)

* Document `expect_length()` and `expect_shape()` together

* Update news bullet

Author: hadley

NEWS.md

@@ -43,7 +43,7 @@
 * Fixed an issue preventing compilation from succeeding due to deprecation / removal of `std::uncaught_exception()` (@kevinushey, #2047).
 * New `skip_unless_r()` to skip running tests on unsuitable versions of R, e.g. `skip_unless_r(">= 4.1.0")` to skip tests that require, say, `...names` (@MichaelChirico, #2022)
 * `skip_on_os()` gains an option `"emscripten"` of the `os` argument to skip tests on Emscripten (@eitsupi, #2103).
-* New expectation, `expect_shape()`, for testing the shape (i.e., the `length()`, `nrow()`, `ncol()`, or `dim()`), all in one place (#1423, @michaelchirico).
+* New expectation, `expect_shape()`, for testing the shape (i.e., the `nrow()`, `ncol()`, or `dim()`), all in one place (#1423, @michaelchirico).
 
 # testthat 3.2.3
 

R/expect-length.R

@@ -1,21 +1,44 @@
-#' Do you expect an object with this shape?
+#' Do you expect an object with this length or shape?
 #'
-#' This is a generalization of [expect_length()] to test the "shape" of
-#' more general objects like data.frames, matrices, and arrays.
+#' `expect_length()` inspects the [length()] of an object; `expect_shape()`
+#' inspects the "shape" (i.e. [nrow()], [ncol()], or [dim()]) of
+#' higher-dimensional objects like data.frames, matrices, and arrays.
 #'
-#' @seealso [expect_length()] to specifically make assertions about the
-#'   [length()] of a vector.
+#' @seealso [expect_vector()] to make assertions about the "size" of a vector.
 #' @inheritParams expect_that
-#' @param ... Ignored.
-#' @param nrow,ncol Expected [nrow()]/[ncol()] of `object`.
-#' @param dim Expected [dim()] of `object`.
+#' @param n Expected length.
 #' @family expectations
 #' @export
 #' @examples
+#' expect_length(1, 1)
+#' expect_length(1:10, 10)
+#' show_failure(expect_length(1:10, 1))
+#'
 #' x <- matrix(1:9, nrow = 3)
 #' expect_shape(x, nrow = 3)
+#' show_failure(expect_shape(x, nrow = 4))
 #' expect_shape(x, ncol = 3)
+#' show_failure(expect_shape(x, ncol = 4))
 #' expect_shape(x, dim = c(3, 3))
+#' show_failure(expect_shape(x, dim = c(3, 4, 5)))
+expect_length <- function(object, n) {
+  check_number_whole(n, min = 0)
+
+  act <- quasi_label(enquo(object))
+  act$n <- length(act$val)
+
+  if (act$n != n) {
+    msg <- sprintf("%s has length %i, not length %i.", act$lab, act$n, n)
+    return(fail(msg))
+  }
+  pass(act$val)
+}
+
+#' @param nrow,ncol Expected [nrow()]/[ncol()] of `object`.
+#' @param dim Expected [dim()] of `object`.
+#' @rdname expect_length
+#' @param ... Not used; used to force naming of other arguments.
+#' @export
 expect_shape = function(object, ..., nrow, ncol, dim) {
   check_dots_empty()
   check_exclusive(nrow, ncol, dim)

R/expect-shape.R

@@ -33,7 +33,6 @@ reference:
   - expect_named
   - expect_null
   - expect_setequal
-  - expect_shape
   - expect_type
   - expect_vector