diff --git a/source/elements/oneDPL/source/parallel_api.rst b/source/elements/oneDPL/source/parallel_api.rst index 77d0c192ba..511c09442c 100644 --- a/source/elements/oneDPL/source/parallel_api.rst +++ b/source/elements/oneDPL/source/parallel_api.rst @@ -519,5 +519,41 @@ than an element in the range being searched. The elements of ``[start, end)`` must be partitioned with respect to the comparator used. +.. code:: cpp + + template + OutputIt + histogram(Policy&& exec, InputIt start, InputIt end, Size num_intervals, + typename std::iterator_traits::value_type first_interval_begin, + typename std::iterator_traits::value_type last_interval_end, + OutputIt histogram_first); // (1) + + template + OutputIt + histogram(Policy&& exec, InputIt1 start, InputIt1 end, InputIt2 boundary_start, + InputIt2 boundary_end, OutputIt histogram_first); // (2) + +``oneapi::dpl::histogram`` computes the histogram over the data in ``[start, end)`` +by counting the number of elements that map to each of a set of bins and storing the counts into +the output sequence starting from ``histogram_first``. Input values that do not map to a defined +bin are skipped silently. The value type of ``OutputIt`` must be an integral type of sufficient +size to store the counts of the histogram without overflow. The return value is an iterator targeting +past the last element of the output sequence starting from ``histogram_first``. + +1. The elements of ``[start, end)`` are mapped into ``num_intervals`` bins that evenly divide the range + ``[first_interval_begin, last_interval_end)``. Each bin is of size + ``bin_size = (last_interval_end - first_interval_begin) / num_intervals`` as represented by a real + number without rounding or truncation. An input element ``start[i]`` maps to a bin + ``histogram_first[j]`` if and only if + ``(first_interval_begin + j * bin_size <= start[i]) && (start[i] < first_interval_begin + (j + 1) * bin_size)``. + The value type of ``InputIt`` must be an arithmetic type. + +2. The elements of ``[start, end)`` are mapped into ``std::distance(boundary_start, boundary_end) - 1)`` + bins defined by the values in ``[boundary_start, boundary_end)``. An input + element ``start[i]`` maps to a bin ``histogram_first[j]`` if and only if + ``(boundary_start[j] <= start[i]) && (start[i] < boundary_start[j + 1])``. The value types + of ``InputIt1`` and ``InputIt2`` must be arithmetic types. The values in + ``[boundary_start, boundary_end)`` must be sorted with respect to ``operator<``. + .. _`C++ Standard`: https://isocpp.org/std/the-standard .. _`SYCL`: https://registry.khronos.org/SYCL/specs/sycl-2020/html/sycl-2020.html