Document expect_length() and expect_shape() together

Author: hadley

R/expect-length.R

@@ -1,21 +1,44 @@
-#' Does code return an object with the specified shape?
+#' Does code return a vector with the specified 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) {
+  stopifnot(is.numeric(n), length(n) == 1)
+
+  act <- quasi_label(enquo(object), arg = "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, trace_env = parent.frame()))
+  }
+  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

@@ -26,7 +26,6 @@ reference:
 - subtitle: Vectors
   contents:
   - expect_length
-  - expect_shape
   - expect_gt
   - expect_match
   - expect_named