[gcc r16-1924] ada: Document restriction on array length

[Marc Poulhies via Gcc-cvs]

https://gcc.gnu.org/g:613e8bafecd2b54407a23d5636799a2c896f5360

commit r16-1924-g613e8bafecd2b54407a23d5636799a2c896f5360
Author: Tonu Naks <n...@adacore.com>
Date:   Wed May 28 09:50:19 2025 +0000

    ada: Document restriction on array length
    
    gcc/ada/ChangeLog:
    
            * libgnat/i-cstrin.ads (Value): add documentation

Diff:
---
 gcc/ada/libgnat/i-cstrin.ads | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/gcc/ada/libgnat/i-cstrin.ads b/gcc/ada/libgnat/i-cstrin.ads
index 0d057d074e5d..5939fe041a47 100644
--- 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);