Implement first_scalar

doc/core.qbk

@@ -47,6 +47,7 @@ criteria for inclusion is that the utility component be:
 [include enable_if.qbk]
 [include exchange.qbk]
 [include explicit_operator_bool.qbk]
+[include first_scalar.qbk]
 [include ignore_unused.qbk]
 [include is_same.qbk]
 [include lightweight_test.qbk]

doc/first_scalar.qbk

@@ -0,0 +1,83 @@
+[/
+Copyright 2019 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+]
+
+[section:first_scalar first_scalar]
+
+[simplesect Authors]
+
+* Glen Fernandes
+
+[endsimplesect]
+
+[section Overview]
+
+The header <boost/core/first_scalar.hpp> provides the function template
+`boost::first_scalar` that can be used to obtain a pointer to the first scalar
+element of an array. Given a pointer of type `T*` it returns a pointer of type
+`remove_all_extents_t<T>*`.
+
+[endsect]
+
+[section Examples]
+
+The following function uses an allocator to allocate an array of arrays and
+constructs each scalar element in it.
+
+```
+#include <boost/alloc_construct.hpp>
+#include <boost/first_scalar.hpp>
+
+template<class A>
+auto create(const A& allocator)
+{
+    typename std::allocator_traits<A>::template
+        rebind_alloc<int[2][3]> other(allocator);
+    auto ptr = other.allocate(4);
+    try {
+        boost::alloc_construct_n(other,
+            boost::first_scalar(boost::to_address(ptr)), 24);
+    } catch (...) {
+        other.deallocate(ptr, 4);
+        throw;
+    }
+    return ptr;
+}
+```
+
+[endsect]
+
+[section Reference]
+
+```
+namespace boost {
+
+template<class T>
+constexpr T* first_scalar(T* p) noexcept;
+
+template<class T, std::size_t N>
+constexpr auto first_scalar(T (*p)[N]) noexcept;
+
+} /* boost */
+```
+
+[section Functions]
+
+[variablelist
+[[`template<class T> constexpr T* first_scalar(T* p) noexcept;`]
+[[variablelist
+[[Returns][`p`.]]]]]
+[[`template<class T, std::size_t N> constexpr auto first_scalar(T (*p)[N])
+noexcept;`]
+[[variablelist
+[[Returns][`first_scalar(&(*p)[0])`.]]]]]]
+
+[endsect]
+
+[endsect]
+
+[endsect]

include/boost/core/first_scalar.hpp

@@ -0,0 +1,45 @@
+/*
+Copyright 2019 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+*/
+#ifndef BOOST_CORE_FIRST_SCALAR_HPP
+#define BOOST_CORE_FIRST_SCALAR_HPP
+
+#include <boost/config.hpp>
+#include <cstddef>
+
+namespace boost {
+namespace detail {
+
+template<class T>
+struct make_scalar {
+    typedef T type;
+};
+
+template<class T, std::size_t N>
+struct make_scalar<T[N]> {
+    typedef typename make_scalar<T>::type type;
+};
+
+} /* detail */
+
+template<class T>
+BOOST_CONSTEXPR inline T*
+first_scalar(T* p) BOOST_NOEXCEPT
+{
+    return p;
+}
+
+template<class T, std::size_t N>
+BOOST_CONSTEXPR inline typename detail::make_scalar<T>::type*
+first_scalar(T (*p)[N]) BOOST_NOEXCEPT
+{
+    return boost::first_scalar(&(*p)[0]);
+}
+
+} /* boost */
+
+#endif

test/Jamfile.v2

@@ -127,6 +127,9 @@ run to_address_test.cpp ;
 run exchange_test.cpp ;
 run exchange_move_test.cpp ;
 
+run first_scalar_test.cpp ;
+compile first_scalar_constexpr_test.cpp ;
+
 run empty_value_test.cpp ;
 run empty_value_size_test.cpp ;
 run empty_value_final_test.cpp ;

test/first_scalar_constexpr_test.cpp

@@ -0,0 +1,19 @@
+/*
+Copyright 2019 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+*/
+#include <boost/config.hpp>
+#if !defined(BOOST_NO_CXX14_CONSTEXPR)
+#include <boost/core/first_scalar.hpp>
+#include <boost/static_assert.hpp>
+
+static int i1 = 0;
+BOOST_STATIC_ASSERT(boost::first_scalar(&i1) == &i1);
+static int i2[4] = { };
+BOOST_STATIC_ASSERT(boost::first_scalar(i2) == &i2[0]);
+static int i3[2][4][6] = { };
+BOOST_STATIC_ASSERT(boost::first_scalar(i3) == &i3[0][0][0]);
+#endif

test/first_scalar_test.cpp

@@ -0,0 +1,20 @@
+/*
+Copyright 2019 Glen Joseph Fernandes
+(glenjofe@gmail.com)
+
+Distributed under the Boost Software License, Version 1.0.
+(http://www.boost.org/LICENSE_1_0.txt)
+*/
+#include <boost/core/first_scalar.hpp>
+#include <boost/core/lightweight_test.hpp>
+
+int main()
+{
+    int i1 = 0;
+    BOOST_TEST_EQ(boost::first_scalar(&i1), &i1);
+    int i2[4] = { };
+    BOOST_TEST_EQ(boost::first_scalar(i2), &i2[0]);
+    int i3[2][4][6] = { };
+    BOOST_TEST_EQ(boost::first_scalar(i3), &i3[0][0][0]);
+    return boost::report_errors();
+}