From 94c6d6fd7559167d3dc13698dbd58f27fb46cde4 Mon Sep 17 00:00:00 2001 From: Gary Dismukes Date: Mon, 15 Mar 2021 19:27:34 -0400 Subject: [PATCH] [Ada] Add documentation for the array fixed-lower-bound feature gcc/ada/ * doc/gnat_rm/implementation_defined_pragmas.rst: Add documentation for the array fixed-lower-bound feature. * gnat_rm.texi: Regenerate. --- .../implementation_defined_pragmas.rst | 50 ++++++++++++++++- gcc/ada/gnat_rm.texi | 55 +++++++++++++++++-- 2 files changed, 97 insertions(+), 8 deletions(-) diff --git a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst index 0d20496a46d6..b4da3084ab2a 100644 --- a/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst +++ b/gcc/ada/doc/gnat_rm/implementation_defined_pragmas.rst @@ -2210,7 +2210,7 @@ extension mode (the use of Off as a parameter cancels the effect of the *-gnatX* command switch). In extension mode, the latest version of the Ada language is -implemented (currently Ada 202x), and in addition a small number +implemented (currently Ada 2022), and in addition a number of GNAT specific extensions are recognized as follows: * Constrained attribute for generic objects @@ -2235,7 +2235,7 @@ of GNAT specific extensions are recognized as follows: This new aggregate syntax for arrays and containers is provided under -gnatX to experiment and confirm this new language syntax. -* Casing on composite values +* Casing on composite values (aka pattern matching) The selector for a case statement may be of a composite type, subject to some restrictions (described below). Aggregate syntax is used for choices @@ -2246,7 +2246,7 @@ of GNAT specific extensions are recognized as follows: Consider this example: - .. code-block:: ada + .. code-block:: ada type Rec is record F1, F2 : Integer; @@ -2322,6 +2322,50 @@ of GNAT specific extensions are recognized as follows: for a given identifer must all statically match. Currently, the case of a binding for a nondiscrete component is not implemented. +* Fixed lower bounds for array types and subtypes + + Unconstrained array types and subtypes can be specified with a lower bound + that is fixed to a certain value, by writing an index range that uses the + syntax " .. <>". This guarantees that all objects + of the type or subtype will have the specified lower bound. + + For example, a matrix type with fixed lower bounds of zero for each + dimension can be declared by the following: + + .. code-block:: ada + + type Matrix is + array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; + + Objects of type Matrix declared with an index constraint must have index + ranges starting at zero: + + .. code-block:: ada + + M1 : Matrix (0 .. 9, 0 .. 19); + M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE + + Similarly, a subtype of String can be declared that specifies the lower + bound of objects of that subtype to be 1: + + .. code-block:: ada + + subtype String_1 is String (1 .. <>); + + If a string slice is passed to a formal of subtype String_1 in a call to + a subprogram S, the slice's bounds will "slide" so that the lower bound + is 1. Within S, the lower bound of the formal is known to be 1, so, unlike + a normal unconstrained String formal, there is no need to worry about + accounting for other possible lower-bound values. Sliding of bounds also + occurs in other contexts, such as for object declarations with an + unconstrained subtype with fixed lower bound, as well as in subtype + conversions. + + Use of this feature increases safety by simplifying code, and can also + improve the efficiency of indexing operations, since the compiler statically + knows the lower bound of unconstrained array formals when the formal's + subtype has index ranges with static fixed lower bounds. + .. _Pragma-Extensions_Visible: Pragma Extensions_Visible diff --git a/gcc/ada/gnat_rm.texi b/gcc/ada/gnat_rm.texi index 38a56f7a3561..471d40f8754a 100644 --- a/gcc/ada/gnat_rm.texi +++ b/gcc/ada/gnat_rm.texi @@ -3632,7 +3632,7 @@ extension mode (the use of Off as a parameter cancels the effect of the @emph{-gnatX} command switch). In extension mode, the latest version of the Ada language is -implemented (currently Ada 202x), and in addition a small number +implemented (currently Ada 2022), and in addition a number of GNAT specific extensions are recognized as follows: @@ -3665,7 +3665,7 @@ This new aggregate syntax for arrays and containers is provided under -gnatX to experiment and confirm this new language syntax. @item -Casing on composite values +Casing on composite values (aka pattern matching) The selector for a case statement may be of a composite type, subject to some restrictions (described below). Aggregate syntax is used for choices @@ -3676,8 +3676,6 @@ for discrete subcomponents). Consider this example: -@quotation - @example type Rec is record F1, F2 : Integer; @@ -3695,7 +3693,6 @@ begin end case; end Caser_1; @end example -@end quotation If Caser_1 is called and both components of X are positive, then Do_This will be called; otherwise, if either component is nonnegative @@ -3754,6 +3751,54 @@ Within the choice list for single alternative, each choice must define the same set of bindings and the component subtypes for for a given identifer must all statically match. Currently, the case of a binding for a nondiscrete component is not implemented. + +@item +Fixed lower bounds for array types and subtypes + +Unconstrained array types and subtypes can be specified with a lower bound +that is fixed to a certain value, by writing an index range that uses the +syntax " .. <>". This guarantees that all objects +of the type or subtype will have the specified lower bound. + +For example, a matrix type with fixed lower bounds of zero for each +dimension can be declared by the following: + +@example +type Matrix is + array (Natural range 0 .. <>, Natural range 0 .. <>) of Integer; +@end example + +Objects of type Matrix declared with an index constraint must have index +ranges starting at zero: + +@example +M1 : Matrix (0 .. 9, 0 .. 19); +M2 : Matrix (2 .. 11, 3 .. 22); -- Warning about bounds; will raise CE +@end example + +Similarly, a subtype of String can be declared that specifies the lower +bound of objects of that subtype to be 1: + +@quotation + +@example +subtype String_1 is String (1 .. <>); +@end example +@end quotation + +If a string slice is passed to a formal of subtype String_1 in a call to +a subprogram S, the slice's bounds will "slide" so that the lower bound +is 1. Within S, the lower bound of the formal is known to be 1, so, unlike +a normal unconstrained String formal, there is no need to worry about +accounting for other possible lower-bound values. Sliding of bounds also +occurs in other contexts, such as for object declarations with an +unconstrained subtype with fixed lower bound, as well as in subtype +conversions. + +Use of this feature increases safety by simplifying code, and can also +improve the efficiency of indexing operations, since the compiler statically +knows the lower bound of unconstrained array formals when the formal's +subtype has index ranges with static fixed lower bounds. @end itemize @node Pragma Extensions_Visible,Pragma External,Pragma Extensions_Allowed,Implementation Defined Pragmas -- 2.47.2