[gcc r12-1621] [Ada] Add documentation for the array fixed-lower-bound feature
Pierre-Marie de Rodat
pmderodat@gcc.gnu.org
Fri Jun 18 08:38:30 GMT 2021
https://gcc.gnu.org/g:94c6d6fd7559167d3dc13698dbd58f27fb46cde4
commit r12-1621-g94c6d6fd7559167d3dc13698dbd58f27fb46cde4
Author: Gary Dismukes <dismukes@adacore.com>
Date: Mon Mar 15 19:27:34 2021 -0400
[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.
Diff:
---
.../doc/gnat_rm/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 0d20496a46d..b4da3084ab2 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 "<lower-bound-expression> .. <>". 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 38a56f7a356..471d40f8754 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 "<lower-bound-expression> .. <>". 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
More information about the Gcc-cvs
mailing list