[libc++] Extract __clamp_to_integral to its own header

[ldionne]

Summary

In addition to being more consistent with our approach for helpers, this
solves an actual issue where <cmath> was using numeric_limits but never
including the <limits> header directly. In a normal setup, this is not
an issue because the <math.h> header included by <cmath> does include
<limits>. However, I did stumble upon some code where that didn't work,
most likely because they were placing their own <math.h> header in front
of ours. I didn't bother investigating further.

[• Quuxplusone]

libcxx/include/module.modulemap

670

__numeric seems like a weird place for this, since IIUC it's actually used only in <random>. Shouldn't it go in __random?

libcxx/test/libcxx/numerics/clamp_to_integral.pass.cpp

18

This testing change implies that you meant to #include <__numeric/clamp_to_integral.h> from <numeric> (which would also be consistent with existing practice)... but you didn't.
If you move it to __random/, then this here should #include <random> instead of <numeric>.

[ldionne]

Address review comments

[ldionne]

libcxx/include/module.modulemap

670

I did that originally, but __clamp_to_integral seemed like a general algorithm that didn't belong to __random, so I changed it. I'll change it back to __random/ on the basis of "it's only used in __random" -- we can change that later if desired.

libcxx/test/libcxx/numerics/clamp_to_integral.pass.cpp

18

Yes, I forgot to do that indeed. Fixing, thanks.

[• Quuxplusone]

libcxx/include/__random/clamp_to_integral.h

41

type's :)

libcxx/include/CMakeLists.txt

set(files
   __numeric/transform_inclusive_scan.h
   __numeric/transform_reduce.h
   __node_handle
   __nullptr
   __random/bernoulli_distribution.h
   __random/binomial_distribution.h
   __random/cauchy_distribution.h
   __random/chi_squared_distribution.h
+  __random/clamp_to_integral.h
   __random/default_random_engine.h
   __random/discard_block_engine.h
   __random/discrete_distribution.h
   __random/exponential_distribution.h
   __random/extreme_value_distribution.h
   __random/fisher_f_distribution.h
   __random/gamma_distribution.h
   __random/generate_canonical.h

libcxx/include/__random/clamp_to_integral.h

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+#ifndef _LIBCPP___RANDOM_CLAMP_TO_INTEGRAL_H
+#define _LIBCPP___RANDOM_CLAMP_TO_INTEGRAL_H
+
+#include <__config>
+#include <cmath>
+#include <limits>
+#include <type_traits>
+
+#if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)
+#pragma GCC system_header
+#endif
+
+_LIBCPP_PUSH_MACROS
+#include <__undef_macros>
+
+_LIBCPP_BEGIN_NAMESPACE_STD
+
+template <class _IntT, class _FloatT,
+    bool _FloatBigger = (numeric_limits<_FloatT>::digits > numeric_limits<_IntT>::digits),
+    int _Bits = (numeric_limits<_IntT>::digits - numeric_limits<_FloatT>::digits)>
+_LIBCPP_INLINE_VISIBILITY
+_LIBCPP_CONSTEXPR _IntT __max_representable_int_for_float() _NOEXCEPT {
+  static_assert(is_floating_point<_FloatT>::value, "must be a floating point type");
+  static_assert(is_integral<_IntT>::value, "must be an integral type");
+  static_assert(numeric_limits<_FloatT>::radix == 2, "FloatT has incorrect radix");
+  static_assert((_IsSame<_FloatT, float>::value || _IsSame<_FloatT, double>::value
+                 || _IsSame<_FloatT,long double>::value), "unsupported floating point type");
+  return _FloatBigger ? numeric_limits<_IntT>::max() :  (numeric_limits<_IntT>::max() >> _Bits << _Bits);
+}
+
+// Convert a floating point number to the specified integral type after
+// clamping to the integral type's representable range.
+//
+// The behavior is undefined if `__r` is NaN.
+template <class _IntT, class _RealT>
+_LIBCPP_INLINE_VISIBILITY
+_IntT __clamp_to_integral(_RealT __r) _NOEXCEPT {
+  using _Lim = numeric_limits<_IntT>;
+  const _IntT _MaxVal = __max_representable_int_for_float<_IntT, _RealT>();
+  if (__r >= ::nextafter(static_cast<_RealT>(_MaxVal), INFINITY)) {
+    return _Lim::max();
+  } else if (__r <= _Lim::lowest()) {
+    return _Lim::min();
+  }
+  return static_cast<_IntT>(__r);
+}
+
+_LIBCPP_END_NAMESPACE_STD
+
+_LIBCPP_POP_MACROS
+
+#endif // _LIBCPP___RANDOM_CLAMP_TO_INTEGRAL_H

libcxx/include/__random/poisson_distribution.h

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 #ifndef _LIBCPP___RANDOM_POISSON_DISTRIBUTION_H
 #define _LIBCPP___RANDOM_POISSON_DISTRIBUTION_H
 
 #include <__config>
+#include <__random/clamp_to_integral.h>
 #include <__random/exponential_distribution.h>
 #include <__random/normal_distribution.h>
 #include <__random/uniform_real_distribution.h>
 #include <cmath>
 #include <iosfwd>
 #include <limits>
 
 #if !defined(_LIBCPP_HAS_NO_PRAGMA_SYSTEM_HEADER)

libcxx/include/cmath

 constexpr double
 lerp(double __a, double __b, double __t)                _NOEXCEPT { return __lerp(__a, __b, __t); }
 
 constexpr long double
 lerp(long double __a, long double __b, long double __t) _NOEXCEPT { return __lerp(__a, __b, __t); }
 
 #endif // _LIBCPP_STD_VER > 17
 
-template <class _IntT, class _FloatT,
-    bool _FloatBigger = (numeric_limits<_FloatT>::digits > numeric_limits<_IntT>::digits),
-    int _Bits = (numeric_limits<_IntT>::digits - numeric_limits<_FloatT>::digits)>
-_LIBCPP_INLINE_VISIBILITY
-_LIBCPP_CONSTEXPR _IntT __max_representable_int_for_float() _NOEXCEPT {
-  static_assert(is_floating_point<_FloatT>::value, "must be a floating point type");
-  static_assert(is_integral<_IntT>::value, "must be an integral type");
-  static_assert(numeric_limits<_FloatT>::radix == 2, "FloatT has incorrect radix");
-  static_assert((_IsSame<_FloatT, float>::value || _IsSame<_FloatT, double>::value
-                 || _IsSame<_FloatT,long double>::value), "unsupported floating point type");
-  return _FloatBigger ? numeric_limits<_IntT>::max() :  (numeric_limits<_IntT>::max() >> _Bits << _Bits);
-}
-
-// Convert a floating point number to the specified integral type after
-// clamping to the integral types representable range.
-//
-// The behavior is undefined if `__r` is NaN.
-template <class _IntT, class _RealT>
-_LIBCPP_INLINE_VISIBILITY
-_IntT __clamp_to_integral(_RealT __r) _NOEXCEPT {
-  using _Lim = numeric_limits<_IntT>;
-  const _IntT _MaxVal = __max_representable_int_for_float<_IntT, _RealT>();
-  if (__r >= ::nextafter(static_cast<_RealT>(_MaxVal), INFINITY)) {
-    return _Lim::max();
-  } else if (__r <= _Lim::lowest()) {
-    return _Lim::min();
-  }
-  return static_cast<_IntT>(__r);
-}
-
 _LIBCPP_END_NAMESPACE_STD
 
 _LIBCPP_POP_MACROS
 
 #endif // _LIBCPP_CMATH

libcxx/include/module.modulemap

module std [system] {
   }
   module numeric {
     header "numeric"
     export *
 
     module __numeric {
       module accumulate               { private header "__numeric/accumulate.h" }
       module adjacent_difference      { private header "__numeric/adjacent_difference.h" }
       module exclusive_scan           { private header "__numeric/exclusive_scan.h" }
       module gcd_lcm                  { private header "__numeric/gcd_lcm.h" }
       module inclusive_scan           { private header "__numeric/inclusive_scan.h" }
       module inner_product            { private header "__numeric/inner_product.h" }
       module iota                     { private header "__numeric/iota.h" }
       module midpoint                 { private header "__numeric/midpoint.h" }
       module partial_sum              { private header "__numeric/partial_sum.h" }
       module reduce                   { private header "__numeric/reduce.h" }
       module transform_exclusive_scan { private header "__numeric/transform_exclusive_scan.h" }
module random {
     export initializer_list
     export *
 
     module __random {
       module bernoulli_distribution          { private header "__random/bernoulli_distribution.h" }
       module binomial_distribution           { private header "__random/binomial_distribution.h" }
       module cauchy_distribution             { private header "__random/cauchy_distribution.h" }
       module chi_squared_distribution        { private header "__random/chi_squared_distribution.h" }
+      module clamp_to_integral               { private header "__random/clamp_to_integral.h" }
       module default_random_engine           { private header "__random/default_random_engine.h" }
       module discard_block_engine            { private header "__random/discard_block_engine.h" }
       module discrete_distribution           { private header "__random/discrete_distribution.h" }
       module exponential_distribution        { private header "__random/exponential_distribution.h" }
       module extreme_value_distribution      { private header "__random/extreme_value_distribution.h" }
       module fisher_f_distribution           { private header "__random/fisher_f_distribution.h" }
       module gamma_distribution              { private header "__random/gamma_distribution.h" }
       module generate_canonical              { private header "__random/generate_canonical.h" }

libcxx/include/random

 } // std
 */
 
 #include <__config>
 #include <__random/bernoulli_distribution.h>
 #include <__random/binomial_distribution.h>
 #include <__random/cauchy_distribution.h>
 #include <__random/chi_squared_distribution.h>
+#include <__random/clamp_to_integral.h>
 #include <__random/default_random_engine.h>
 #include <__random/discard_block_engine.h>
 #include <__random/discrete_distribution.h>
 #include <__random/exponential_distribution.h>
 #include <__random/extreme_value_distribution.h>
 #include <__random/fisher_f_distribution.h>
 #include <__random/gamma_distribution.h>
 #include <__random/generate_canonical.h>

libcxx/test/libcxx/diagnostics/detail.headers/random/clamp_to_integral.module.verify.cpp

+//===----------------------------------------------------------------------===//
+//
+// Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+//===----------------------------------------------------------------------===//
+
+// REQUIRES: modules-build
+
+// WARNING: This test was generated by 'generate_private_header_tests.py'
+// and should not be edited manually.
+
+// expected-error@*:* {{use of private header from outside its module: '__random/clamp_to_integral.h'}}
+#include <__random/clamp_to_integral.h>

libcxx/test/libcxx/numerics/clamp_to_integral.pass.cpp

 //===----------------------------------------------------------------------===//
 //
 // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 //===----------------------------------------------------------------------===//
 
 // __clamp_to_integral<IntT>(RealT)
 
 // Test the conversion function that truncates floating point types to the
 // closest representable value for the specified integer type, or
 // numeric_limits<IntT>::max()/min() if the value isn't representable.
 
-#include <limits>
 #include <cassert>
 #include <cmath>
+#include <limits>
+#include <random> // for __clamp_to_integral
 
 template <class IntT>
 void test() {
   typedef std::numeric_limits<IntT> Lim;
   const bool MaxIsRepresentable = sizeof(IntT) < 8;
   const bool IsSigned = std::is_signed<IntT>::value;
   struct TestCase {
     double Input;