ada: Document restriction on array length

gcc/ada/ChangeLog:

	* libgnat/i-cstrin.ads (Value): add documentation

diff --git a/gcc/ada/libgnat/i-cstrin.ads b/gcc/ada/libgnat/i-cstrin.ads
index 0d057d074e5d13f7ff0440e8da6b1ea1d3baa034..5939fe041a47eab54f5838c180bbbcf5cac1d0cc 100644 (file)
--- a/gcc/ada/libgnat/i-cstrin.ads
+++ b/gcc/ada/libgnat/i-cstrin.ads
@@ -100,6 +100,17 @@ is
 
    --  The Value functions copy the contents of a chars_ptr object
    --  into a char_array/String.
+   --  There is a guard for a storage error on an object declaration for
+   --  an array type with a modular index type with the size of
+   --  Long_Long_Integer. The special processing is needed in this case
+   --  to compute reliably the size of the object, and eventually, to
+   --  raise Storage_Error, when wrap-around arithmetic might compute
+   --  a meangingless size for the object.
+   --
+   --  The guard raises Storage_Error when
+   --
+   --    (Arr'Last / 2 - Arr'First / 2) > (2 ** 30)
+   --
    function Value (Item : chars_ptr) return char_array with
      Pre    => Item /= Null_Ptr,
      Global => (Input => C_Memory);