Document and cleanup elementwise check/is.

Author: peterwicksstringfield

stan/math/opencl/matrix_cl.hpp

@@ -459,8 +459,7 @@ class matrix_cl<T, require_arithmetic_t<T>> {
    */
   template <typename Expr,
             require_all_valid_expressions_and_none_scalar_t<Expr>* = nullptr>
-  matrix_cl(const Expr& expression);  // NOLINT This constructor is
-                                      // intentionally implicit
+  matrix_cl(const Expr& expression);  // NOLINT(runtime/explicit)
 
   /** \ingroup opencl
    * Move assignment operator.

stan/math/prim/err/elementwise_check.hpp

@@ -5,6 +5,7 @@
 #include <stan/math/prim/fun/get.hpp>
 #include <stan/math/prim/fun/size.hpp>
 #include <stan/math/prim/fun/value_of_rec.hpp>
+#include <stan/math/prim/meta/is_vector.hpp>
 #include <string>
 #include <sstream>
 #include <vector>
@@ -13,80 +14,148 @@ namespace stan {
 namespace math {
 namespace internal {
 
-template <typename T_is_good, typename T_exception>
-struct Checker {
-  const T_is_good& is_good;
+/** Apply an error check to a container, signal failure by throwing.
+ * Apply a predicate like is_positive to the double underlying every scalar in a
+ * container, throw an exception if the predicate fails for any double.
+ * @tparam F type of predicate
+ * @tparam E type of exception thrown
+ */
+template <typename F, typename E>
+class Checker {
+  const F& is_good;
   const char* function;
   const char* name;
   const char* suffix;
 
-  void raise_error_impl(std::stringstream& ss) { throw T_exception{ss.str()}; }
-
-  template <typename... M>
-  void raise_error_impl(std::stringstream& ss, const char* message,
-                        const M&... messages) {
+ public:
+  /**
+   * @param is_good predicate to check, must accept doubles and produce bools
+   * @param function function name (for error messages)
+   * @param name variable name (for error messages)
+   * @param suffix message to print at end of error message
+   */
+  Checker(const F& is_good, const char* function, const char* name,
+          const char* suffix)
+      : is_good(is_good), function(function), name(name), suffix(suffix) {}
+
+  /**
+   * Throw an exception of type `E`.
+   * The error message is the string inside the provided stringstream.
+   * @param ss stringstream containing error message
+   * @throws `E`
+   */
+  void raise_error_ss(std::stringstream& ss) { throw E{ss.str()}; }
+
+  /**
+   * Throw an exception of type `E`.
+   * The error message is the concatenation of the string inside the provided
+   * stringstream with all the provided messages.
+   * @tparam M types of first message
+   * @tparam Ms types of other messages
+   * @param ss stringstream to accumulate error message in.
+   * @param message a message to append to `ss`
+   * @param messages more messages to append
+   * @throws `E`
+   */
+  template <typename M, typename... Ms>
+  void raise_error_ss(std::stringstream& ss, const M& message,
+                      const Ms&... messages) {
     ss << message;
-    raise_error_impl(ss, messages...);
-  }
-
-  template <typename... M>
-  void raise_error_impl(std::stringstream& ss, double value_of_x,
-                        const M&... messages) {
-    ss << value_of_x;
-    raise_error_impl(ss, messages...);
+    raise_error_ss(ss, messages...);
   }
 
-  template <typename... M>
-  void raise_error_impl(std::stringstream& ss, size_t index,
-                        const M&... messages) {
-    ss << index + 1;
-    raise_error_impl(ss, messages...);
-  }
-
-  template <typename... M>
-  void raise_error(const M&... messages) {
+  /**
+   * Throw an exception of type `E`.
+   * The error message is the concatenation of the provided messages.
+   * @tparam Ms types of messages
+   * @param messages a list of messages
+   * @throws `E`
+   */
+  template <typename... Ms>
+  void raise_error(const Ms&... messages) {
     std::stringstream ss{};
-    raise_error_impl(ss, messages...);
+    raise_error_ss(ss, messages...);
   }
 
-  template <typename T, typename = require_stan_scalar_t<T>,
-            typename... T_indices>
-  void check(const T& x, T_indices... indices) {
+  /**
+   * Check the scalar.
+   * @tparam T type of scalar
+   * @tparam Ms types of messages
+   * @param x scalar
+   * @param messages a list of messages to append to the error message
+   * @throws `E` if  the scalar fails the error check
+   */
+  template <typename T, typename = require_stan_scalar_t<T>, typename... Ms>
+  void check(const T& x, Ms... messages) {
     double xd = value_of_rec(x);
     if (!is_good(xd))
-      raise_error(function, ": ", name, indices..., " is ", xd, suffix);
+      raise_error(function, ": ", name, messages..., " is ", xd, suffix);
   }
 
-  template <typename T, typename = require_eigen_vector_t<T>, typename = void,
-            typename... T_indices>
-  void check(const T& x, T_indices... indices) {
+  /**
+   * Check all the scalars inside the vector.
+   * @tparam T type of vector
+   * @tparam Ms types of messages
+   * @param x vector
+   * @param messages a list of messages to append to the error message
+   * @throws `E` if any of the scalars fail the error check
+   */
+  template <typename T, typename = require_vector_t<T>, typename = void,
+            typename... Ms>
+  void check(const T& x, Ms... messages) {
     for (size_t i = 0; i < stan::math::size(x); ++i)
-      check(x(i), indices..., "[", i, "]");
+      check(x[i], messages..., "[", i + 1, "]");
   }
 
-  template <typename T, typename... T_indices>
-  void check(const std::vector<T>& x, T_indices... indices) {
-    for (size_t i = 0; i < stan::math::size(x); ++i)
-      check(x[i], indices..., "[", i, "]");
-  }
-
-  template <typename T, typename... T_indices>
-  void check(const Eigen::DenseBase<T>& x, T_indices... indices) {
+  /**
+   * Check all the scalars inside the matrix.
+   * @tparam Derived type of matrix
+   * @tparam Ms types of messages
+   * @param x matrix
+   * @param messages a list of messages to append to the error message
+   * @throws `E` if any of the scalars fail the error check
+   */
+  template <typename Derived, typename... Ms>
+  void check(const Eigen::DenseBase<Derived>& x, Ms... messages) {
     for (size_t n = 0; n < x.cols(); ++n)
       for (size_t m = 0; m < x.rows(); ++m)
-        check(x(m, n), indices..., "[row=", m, ", col=", n, "]");
+        check(x(m, n), messages..., "[row=", m + 1, ", col=", n + 1, "]");
   }
-};
-
-template <typename T_is_good>
-struct Iser {
-  const T_is_good& is_good;
+};  // namespace internal
 
+/** Apply an error check to a container, signal failure with `false`.
+ * Apply a predicate like is_positive to the double underlying every scalar in a
+ * container, producing true if the predicate holds everywhere and `false` if it
+ * fails anywhere.
+ * @tparam F type of predicate
+ */
+template <typename F>
+class Iser {
+  const F& is_good;
+
+ public:
+  /**
+   * @param is_good predicate to check, must accept doubles and produce bools
+   */
+  explicit Iser(const F& is_good) : is_good(is_good) {}
+
+  /**
+   * Check the scalar.
+   * @tparam T type of scalar
+   * @param x scalar
+   * @return `false` if the scalar fails the error check
+   */
   template <typename T, typename = require_stan_scalar_t<T>>
   bool is(const T& x) {
     return is_good(value_of_rec(x));
   }
 
+  /**
+   * Check all the scalars inside the container.
+   * @tparam T type of scalar
+   * @param x container
+   * @return `false` if any of the scalars fail the error check
+   */
   template <typename T, typename = require_not_stan_scalar_t<T>,
             typename = void>
   bool is(const T& x) {
@@ -100,35 +169,42 @@ struct Iser {
 }  // namespace internal
 
 /**
- * Check that the predicate holds for the value of x, working elementwise on
- * containers. If x is a container, check each element inside x, recursively.
- * @tparam T_is_good type of is_good predicate
- * @tparam T_x type of x
+ * Check that the predicate holds for the value of `x`, working elementwise on
+ * containers. If `x` is a scalar, check the double underlying the scalar. If
+ * `x` is a container, check each element inside `x`, recursively.
+ * @tparam F type of predicate
+ * @tparam T type of `x`
  * @param is_good predicate to check, must accept doubles and produce bools
  * @param function function name (for error messages)
  * @param name variable name (for error messages)
  * @param x variable to check, can be a scalar, a container of scalars, a
  * container of containers of scalars, etc
  * @param suffix message to print at end of error message
- * @throw <code>std::domain_error</code> if is_good returns false for the value
- * of any element in x the predicate
+ * @throws `std::domain_error` if `is_good` returns `false` for the value
+ * of any element in `x`
  */
-template <typename T_is_good, typename T_x>
-inline void elementwise_check(const T_is_good& is_good, const char* function,
-                              const char* name, const T_x& x,
+template <typename F, typename T>
+inline void elementwise_check(const F& is_good, const char* function,
+                              const char* name, const T& x,
                               const char* suffix) {
-  internal::Checker<T_is_good, std::domain_error>{is_good, function, name,
-                                                  suffix}
+  internal::Checker<F, std::domain_error>{is_good, function, name, suffix}
       .check(x);
 }
 
 /**
- * Like elementwise_check, but indicate failure by returning false instead of
- * by throwing.
+ * Check that the predicate holds for the value of `x`, working elementwise on
+ * containers. If `x` is a scalar, check the double underlying the scalar. If
+ * `x` is a container, check each element inside `x`, recursively.
+ * @tparam F type of predicate
+ * @tparam T type of `x`
+ * @param is_good predicate to check, must accept doubles and produce bools
+ * @param x variable to check, can be a scalar, a container of scalars, a
+ * container of containers of scalars, etc
+ * @return `false` if any of the scalars fail the error check
  */
-template <typename T_is_good, typename T_x>
-inline bool elementwise_is(const T_is_good& is_good, const T_x& x) {
-  return internal::Iser<T_is_good>{is_good}.is(x);
+template <typename F, typename T>
+inline bool elementwise_is(const F& is_good, const T& x) {
+  return internal::Iser<F>{is_good}.is(x);
 }
 
 }  // namespace math

test/unit/math/prim/err/elementwise_check_test.cpp

@@ -5,22 +5,18 @@
 #include <limits>
 #include <vector>
 
-template <typename T>
-bool example_predicate(const T& x) {
-  return !stan::math::is_nan(x);
-}
+auto p = [](const auto& x) { return !stan::math::is_nan(x); };
 
 template <typename T>
 void do_check(const T& x) {
-  stan::math::elementwise_check(
-      [](const auto& x) { return example_predicate(x); },
-      "elementwise_check_tests", "x", x, ", but must not be nan!");
+  stan::math::elementwise_check([](const auto& x) { return p(x); },
+                                "elementwise_check_tests", "x", x,
+                                ", but must not be nan!");
 }
 
 template <typename T>
 bool do_is(const T& x) {
-  return stan::math::elementwise_is(
-      [](const auto& x) { return example_predicate(x); }, x);
+  return stan::math::elementwise_is([](const auto& x) { return p(x); }, x);
 }
 
 template <typename T>