[lmi-commits] [lmi] master 885ea92 2/5: Improve documentation

[Greg Chicares]

branch: master
commit 885ea92b81b7cfcc49500f4ef0c08546f3fab25c
Author: Gregory W. Chicares <address@hidden>
Commit: Gregory W. Chicares <address@hidden>

    Improve documentation
---
 ssize_lmi.hpp      | 41 ++++++++++++++++++++++++++++++++++++++++-
 ssize_lmi_test.cpp |  2 +-
 2 files changed, 41 insertions(+), 2 deletions(-)

diff --git a/ssize_lmi.hpp b/ssize_lmi.hpp
index ef3a073..3f561d4 100644
--- a/ssize_lmi.hpp
+++ b/ssize_lmi.hpp
@@ -1,4 +1,4 @@
-// Improved std::size() that returns a signed integer.
+// Reformed std::size() returning a signed integer.
 //
 // Copyright (C) 2018 Gregory W. Chicares.
 //
@@ -30,6 +30,12 @@
 #include <cstring>                      // strlen()
 #include <type_traits>                  // make_signed_t
 
+/// Reformed std::size() [C++17 27.8/2-3] returning a signed integer.
+///
+/// Precondition: Cardinality of array or container does not exceed
+///   numeric_limits<std::make_signed_t<std::size_t>>::max()
+/// . Throws, or fails to compile, if violated.
+///
 /// Motivation: to avoid error-prone mixing of signed and unsigned.
 ///
 ///   https://github.com/ericniebler/stl2/issues/182
@@ -76,6 +82,39 @@
 /// Question: "...it's gonna pollute, right?"
 /// Carruth: "We're sorry."
 /// Sutter: "As Scott would say, 'we were young'."
+///
+/// Implementation notes.
+///
+/// An array-bound parameter can be deduced as a signed integer: the
+/// deduced value need not be unsigned. See C++17 (N4659) [17.8.2.1]
+/// (i.e., [temp.deduc.call]):
+///
+/// | template<class T, int N> void h(T const(&)[N]);
+/// | h({1,2,3}); // T deduced to int, N deduced to 3
+///
+/// However, the array bound is of type std::size_t [17.8.2.5]
+/// (i.e., [temp.deduct.type]):
+///
+/// | The type of N in the type T[N] is std::size_t.
+///
+/// Presumably deduction works as if:
+///
+///   // explicit type of 'n' is signed char
+///   // deduced value of 'n' is an ICE
+///   // initialization is an error if the conversion is narrowing
+///   //
+///   template<typename T, signed char n>
+///   constexpr signed char foo(T const(&)[n])
+///   {
+///       n = signed char({ICE_deduced_for_n});
+///   }
+///
+/// and the compiler should emit a diagnostic if an array with more
+/// than SCHAR_MAX elements is passed. Because the standard does not
+/// specify this precisely, it seems best to use type std::size_t for
+/// array-bound template parameters and convert their values to the
+/// desired return type using a facility such as bourn_cast or a
+/// braced-init-list that ensures value preservation.
 
 namespace lmi
 {
diff --git a/ssize_lmi_test.cpp b/ssize_lmi_test.cpp
index c05f207..b5c1fbb 100644
--- a/ssize_lmi_test.cpp
+++ b/ssize_lmi_test.cpp
@@ -1,4 +1,4 @@
-// Improved std::size() that returns a signed integer: unit test.
+// Reformed std::size() returning a signed integer: unit test.
 //
 // Copyright (C) 2018 Gregory W. Chicares.
 //