Add spec compliant histogram API while supporting legacy extension API

include/oneapi/dpl/pstl/histogram_extension_defs.h

@@ -22,12 +22,12 @@ namespace oneapi
 {
 namespace dpl
 {
-
-template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2,
-          typename _ValueType = typename ::std::iterator_traits<_RandomAccessIterator1>::value_type>
+template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2>
 oneapi::dpl::__internal::__enable_if_execution_policy<_ExecutionPolicy, _RandomAccessIterator2>
 histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIterator1 last, _Size num_bins,
-          _ValueType first_bin_min_val, _ValueType last_bin_max_val, _RandomAccessIterator2 histogram_first);
+          typename std::iterator_traits<_RandomAccessIterator1>::value_type first_bin_min_val,
+          typename std::iterator_traits<_RandomAccessIterator1>::value_type last_bin_max_val,
+          _RandomAccessIterator2 histogram_first);
 
 template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _RandomAccessIterator2,
           typename _RandomAccessIterator3>
@@ -36,6 +36,36 @@ histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIt
           _RandomAccessIterator2 boundary_first, _RandomAccessIterator2 boundary_last,
           _RandomAccessIterator3 histogram_first);
 
+// Support extension API to cover existing API (previous to specification) with the following two overloads
+
+// This overload is provided to support an extension to the oneDPL specification to support the original implementation
+// of the histogram API, where the boundary type _ValueType could differ from the value type of the input iterator,
+// and required `<`, `<=`, `+`, `-`, and `/` to be defined between _ValueType and
+// std::iterator_traits<_RandomAccessIterator1>::value_type rather than enforcing they were the same type or convertible
+template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2,
+          typename _ValueType>
+std::enable_if_t<
+    oneapi::dpl::execution::is_execution_policy_v<std::decay_t<_ExecutionPolicy>> &&
+        !std::is_convertible_v<_ValueType, typename std::iterator_traits<_RandomAccessIterator1>::value_type>,
+    _RandomAccessIterator2>
+histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIterator1 last, _Size num_bins,
+          _ValueType first_bin_min_val, _ValueType last_bin_max_val, _RandomAccessIterator2 histogram_first);
+
+// This overload is provided to support an extension to the oneDPL specification to support the original implementation
+// of the histogram API, where if users explicitly-specify all template arguments, their arguments for bin boundary min
+// and max are convertible to the specified _ValueType, and the _ValueType is convertible to the value type of the
+// input iterator. Note that _ValueType is not deducable from the function arguments, so this overload is only used
+// when users explicitly specify the _ValueType template argument.
+template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2,
+          typename _ValueType, typename _RealValueType1, typename _RealValueType2>
+std::enable_if_t<
+    oneapi::dpl::execution::is_execution_policy_v<std::decay_t<_ExecutionPolicy>> &&
+        std::is_convertible_v<_ValueType, typename std::iterator_traits<_RandomAccessIterator1>::value_type> &&
+        std::is_convertible_v<_RealValueType1, _ValueType> && std::is_convertible_v<_RealValueType2, _ValueType>,
+    _RandomAccessIterator2>
+histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIterator1 last, _Size num_bins,
+          _RealValueType1 first_bin_min_val, _RealValueType2 last_bin_max_val, _RandomAccessIterator2 histogram_first);
+
 } // end namespace dpl
 } // end namespace oneapi
 

include/oneapi/dpl/pstl/histogram_impl.h

@@ -46,17 +46,19 @@ __pattern_histogram(_Tag, _ExecutionPolicy&& exec, _RandomAccessIterator1 __firs
 
 } // namespace __internal
 
-template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2,
-          typename _ValueType>
+template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2>
 oneapi::dpl::__internal::__enable_if_execution_policy<_ExecutionPolicy, _RandomAccessIterator2>
 histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIterator1 last, _Size num_bins,
-          _ValueType first_bin_min_val, _ValueType last_bin_max_val, _RandomAccessIterator2 histogram_first)
+          typename std::iterator_traits<_RandomAccessIterator1>::value_type first_bin_min_val,
+          typename std::iterator_traits<_RandomAccessIterator1>::value_type last_bin_max_val,
+          _RandomAccessIterator2 histogram_first)
 {
+    using _BoundaryType = typename std::iterator_traits<_RandomAccessIterator1>::value_type;
     const auto __dispatch_tag = oneapi::dpl::__internal::__select_backend(exec, first, histogram_first);
 
     oneapi::dpl::__internal::__pattern_histogram(
-        __dispatch_tag, ::std::forward<_ExecutionPolicy>(exec), first, last, num_bins,
-        oneapi::dpl::__internal::__evenly_divided_binhash<_ValueType>(first_bin_min_val, last_bin_max_val, num_bins),
+        __dispatch_tag, std::forward<_ExecutionPolicy>(exec), first, last, num_bins,
+        oneapi::dpl::__internal::__evenly_divided_binhash<_BoundaryType>(first_bin_min_val, last_bin_max_val, num_bins),
         histogram_first);
     return histogram_first + num_bins;
 }
@@ -77,6 +79,63 @@ histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIt
     return histogram_first + num_bins;
 }
 
+// Support extension API to cover existing API (previous to specification) with the following two overloads
+
+// This overload is provided to support an extension to the oneDPL specification to support the original implementation
+// of the histogram API, where the boundary type _ValueType could differ from the value type of the input iterator,
+// and required `<`, `<=`, `+`, `-`, and `/` to be defined between _ValueType and
+// std::iterator_traits<_RandomAccessIterator1>::value_type rather than enforcing they were the same type or convertible
+template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2,
+          typename _ValueType>
+[[deprecated("Use of oneapi::dpl::histogram API with bin boundary value arguments which are not convertible to the "
+             " value type of the input iterator is deprecated and will be removed in a future release. Please use "
+             " the oneapi::dpl histogram API with the same value type for both the input iterator and bin boundary "
+             " values.")]]
+std::enable_if_t<
+    oneapi::dpl::execution::is_execution_policy_v<std::decay_t<_ExecutionPolicy>> &&
+        !std::is_convertible_v<_ValueType, typename std::iterator_traits<_RandomAccessIterator1>::value_type>,
+    _RandomAccessIterator2>
+histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIterator1 last, _Size num_bins,
+          _ValueType first_bin_min_val, _ValueType last_bin_max_val, _RandomAccessIterator2 histogram_first)
+{
+    const auto __dispatch_tag = oneapi::dpl::__internal::__select_backend(exec, first, histogram_first);
+
+    oneapi::dpl::__internal::__pattern_histogram(
+        __dispatch_tag, ::std::forward<_ExecutionPolicy>(exec), first, last, num_bins,
+        oneapi::dpl::__internal::__evenly_divided_binhash<_ValueType>(first_bin_min_val, last_bin_max_val, num_bins),
+        histogram_first);
+    return histogram_first + num_bins;
+}
+
+// This overload is provided to support an extension to the oneDPL specification to support the original implementation
+// of the histogram API, where if users explicitly-specify all template arguments, their arguments for bin boundary min
+// and max are convertible to the specified _ValueType, and the _ValueType is convertible to the value type of the
+// input iterator. Note that _ValueType is not deducable from the function arguments, so this overload is only used
+// when users explicitly specify the _ValueType template argument.
+template <typename _ExecutionPolicy, typename _RandomAccessIterator1, typename _Size, typename _RandomAccessIterator2,
+          typename _ValueType, typename _RealValueType1, typename _RealValueType2>
+[[deprecated("Use of oneapi::dpl::histogram API with explicit specification of the template type for the "
+             " bin boundary value parameters is deprecated and will be removed in a future release. Please use "
+             " the oneapi::dpl histogram API with the same value type for both the input iterator and bin boundary "
+             " values.")]]
+std::enable_if_t<
+    oneapi::dpl::execution::is_execution_policy_v<std::decay_t<_ExecutionPolicy>> &&
+        std::is_convertible_v<_ValueType, typename std::iterator_traits<_RandomAccessIterator1>::value_type> &&
+        std::is_convertible_v<_RealValueType1, _ValueType> && std::is_convertible_v<_RealValueType2, _ValueType>,
+    _RandomAccessIterator2>
+histogram(_ExecutionPolicy&& exec, _RandomAccessIterator1 first, _RandomAccessIterator1 last, _Size num_bins,
+          _RealValueType1 first_bin_min_val, _RealValueType2 last_bin_max_val, _RandomAccessIterator2 histogram_first)
+{
+    const auto __dispatch_tag = oneapi::dpl::__internal::__select_backend(exec, first, histogram_first);
+
+    oneapi::dpl::__internal::__pattern_histogram(
+        __dispatch_tag, ::std::forward<_ExecutionPolicy>(exec), first, last, num_bins,
+        oneapi::dpl::__internal::__evenly_divided_binhash<_ValueType>(_ValueType{first_bin_min_val},
+                                                                      _ValueType{last_bin_max_val}, num_bins),
+        histogram_first);
+    return histogram_first + num_bins;
+}
+
 } // end namespace dpl
 } // end namespace oneapi