8.5 Renaming Declarations
This Reference Manual output has not been verified, and may contain omissions or errors. Report any problems on the tracking issue
[A renaming_declaration declares another name for an entity, such as an object, exception, package, subprogram, entry, or generic unit. Alternatively, a subprogram_renaming_declaration can be the completion of a previous subprogram_declaration.]
renaming_declaration is a declaration that does not define a new entity, but instead defines a view of an existing entity.Syntax
3renaming_declaration ::=
object_renaming_declaration
| exception_renaming_declaration
| package_renaming_declaration
| subprogram_renaming_declaration
| generic_renaming_declaration
Dynamic Semantics
4The elaboration of a renaming_declaration evaluates the name that follows the reserved word renames and thereby determines the view and entity denoted by this name (the renamed view and renamed entity). [A name that denotes the renaming_declaration denotes (a new view of) the renamed entity.]
identifier or operator_symbol does not hide the old name; the new name and the old name can be visible at different places.subtype Mode is Ada.Text_IO.File_Mode;
Wording Changes from Ada 83
identifier might resolve to something else.8.5.1 Object Renaming Declarations
1/5[An object_renaming_declaration is used to rename an object or value.]
Syntax
2/5object_renaming_declaration ::=
defining_identifier [: [null_exclusion] subtype_mark] renames object_name
[aspect_specification];
| defining_identifier : access_definition renames object_name
[aspect_specification];
Name Resolution Rules
3/5The type of the object_name shall resolve to the type determined by the subtype_mark, if present. If no subtype_mark or access_definition is present, the expected type of the object_name is any type .
In the case where the type is defined by an access_definition, the type of the object_name shall resolve to an anonymous access type. If the anonymous access type is an access-to-object type, the type of the object_name shall have the same designated type as that of the access_definition. If the anonymous access type is an access-to-subprogram type, the type of the object_name shall have a designated profile that is type conformant with that of the access_definition.
“The expected type for the object_
name is that determined by the subtype_mark.”We changed it so that this would be illegal:
X: T;
Y: T'Class renames X; -- Illegal!
Z: T'Class := ...;
W: T renames F(Z);
Legality Rules
4/5The renamed entity shall be an object or value.
In the case where the type is defined by an access_definition, the type of the renamed entity and the type defined by the access_definition:
- shall both be access-to-object types with statically matching designated subtypes and with both or neither being access-to-constant types; or
- shall both be access-to-subprogram types with subtype conformant designated profiles.
For an object_renaming_declaration with a null_exclusion or an access_definition that has a null_exclusion, the subtype of the object_name shall exclude null. In addition, if the object_renaming_declaration occurs within the body of a generic unit G or within the body of a generic unit declared within the declarative region of generic unit G, then:
- if the object_
namestatically denotes a generic formal object of mode in out of G, then the declaration of that object shall have anull_exclusion; 4.6/5 - if the object_
namestatically denotes a call of a generic formal function of G, then the declaration of the result of that function shall have anull_exclusion.
null_exclusion. The bullets are assume-the-worst rules that prevent trouble in two obscure cases : type Acc_I is access Integer;
subtype Acc_NN_I is not null Acc_I;
Obj : Acc_I := null;
4.c/2generic
B : in out Acc_NN_I;
package Gen is
...
end Gen;
4.d/2package body Gen is
D : not null Acc_I renames B;
end Gen;
4.e/2package Inst is new Gen (B => Obj);
In the case where the object_name is a qualified_expression with a nominal subtype S and whose expression is a name that denotes an object Q:
- if S is an elementary subtype, then:
- Q shall be a constant other than a dereference of an access type; or
- the nominal subtype of Q shall be statically compatible with S; or
- S shall statically match the base subtype of its type if scalar, or the first subtype of its type if an access type.
- if S is a composite subtype, then Q shall be known to be constrained or S shall statically match the first subtype of its type.
expression is a value. {8652/0017} The renamed entity shall not be a subcomponent that depends on discriminants of an object whose nominal subtype is unconstrained unless the object is known to be constrained. A slice of an array shall not be renamed if this restriction disallows renaming of the array.
In addition to the places where Legality Rules normally apply (see 12.3), these rules also apply in the private part of an instance of a generic unit.
type T1 (D1 : Boolean) is
record
case D1 is
when False =>
C1 : Integer;
when True =>
null;
end case;
end record;
5.a.3/1generic
type F is new T1;
X : in out F;
package G is
C1_Ren : Integer renames X.C1;
end G;
5.a.4/1type T2 (D2 : Boolean := False) is new T1 (D1 => D2);
Y : T2;
package I is new G (T2, Y);
Y := (D1 => True); -- Oops! What happened to I.C1_Ren?
assignment_statements assigning to unconstrained definite objects, then it cannot represent renamings and access values as simple addresses, because the above rule does not apply to all components of such an object. Static Semantics
6/5An object_renaming_declaration declares a new view [of the renamed entity ] whose properties are identical to those of the renamed view. [Thus, the properties of the renamed entity are not affected by the renaming_declaration. In particular, its nominal subtype, whether it is a value or an object, its value if it is an object, and whether or not it is a constant, are unaffected; similarly, the constraints and other properties of its nominal subtype are not affected by renaming (any constraint implied by the subtype_mark or access_definition of the object_renaming_declaration is ignored).]
object_renaming_declaration.null_exclusion is given in the renaming, the object may or may not exclude null. This is similar to the way that constraints need not match, and constant is not specified. The renaming defines a view of the renamed entity, inheriting the original properties. Examples
7Example of renaming an object:
declare
L : Person renames Leftmost_Person; -- see 3.10.1
begin
L.Age := L.Age + 1;
end;
Example of renaming a value:
Uno renames One; -- see 3.3.2
Wording Changes from Ada 83
Incompatibilities With Ada 95
AT2 : aliased T2;
C1_Ren : Integer renames AT2.C1; -- Illegal in Ada 2005, legal in Ada 95
AT2 := (D1 => True); -- Raised Constraint_Error in Ada 95,
-- but does not in Ada 2005, so C1_Ren becomes
-- invalid when this is assigned.
Extensions to Ada 95
null_exclusion; if so, the renamed object must also exclude null, so that the null_exclusion does not lie. On the other hand, if the renaming does not have a null_exclusion. it excludes null if the renamed object does. Wording Changes from Ada 95
Incompatibilities With Ada 2005
Extensions to Ada 2005
aspect_specification can be used in an object_renaming_declaration. This is described in 13.1.1. Incompatibilities With Ada 2012
qualified_expression of a variable is allowed only if the variable will always remain within the nominal subtype of the qualified_expression. This was not required in Ada 2012. Renamings that are now illegal are at risk of causing erroneous execution if the variable value is changed to a bad value; this is consistent with other rules preventing renamings from changing to violate their known properties. Extensions to Ada 2012
subtype_mark in an object renaming is now optional, as the subtype information it provides is not trustworthy anyway (that comes from the renamed object and there is no requirement that it is the same as that of the object).name, but an arbitrary expression can be renamed by qualifying it. 8.5.2 Exception Renaming Declarations
1[An exception_renaming_declaration is used to rename an exception.]
Syntax
2/3exception_renaming_declaration ::= defining_identifier : exception renames exception_name
[aspect_specification];
Legality Rules
3The renamed entity shall be an exception.
Static Semantics
4An exception_renaming_declaration declares a new view [of the renamed exception].
Examples
5Example of renaming an exception:
EOF : exception renames Ada.IO_Exceptions.End_Error; -- see A.13
Extensions to Ada 2005
aspect_specification can be used in an exception_renaming_declaration. This is described in 13.1.1. 8.5.3 Package Renaming Declarations
1[A package_renaming_declaration is used to rename a package.]
Syntax
2/3package_renaming_declaration ::= package defining_program_unit_name renames package_name
[aspect_specification];
Legality Rules
3The renamed entity shall be a package.
If the package_name of a package_renaming_declaration denotes a limited view of a package P, then a name that denotes the package_renaming_declaration shall occur only within the immediate scope of the renaming or the scope of a with_clause that mentions the package P or, if P is a nested package, the innermost library package enclosing P.
with_clause). We don't want to make an implicit limited view, as those are not transitive like a regular view. Implementations should be able to see all limited views needed based on the context_clause. Static Semantics
4A package_renaming_declaration declares a new view [of the renamed package].
[At places where the declaration of the limited view of the renamed package is visible, a name that denotes the package_renaming_declaration denotes a limited view of the package (see 10.1.1).]
Examples
5Example of renaming a package:
package TM renames Table_Manager;
Wording Changes from Ada 95
Extensions to Ada 2005
aspect_specification can be used in a package_renaming_declaration. This is described in 13.1.1. 8.5.4 Subprogram Renaming Declarations
1/3A subprogram_renaming_declaration can serve as the completion of a subprogram_declaration; such a renaming_declaration is called a renaming-as-body. A subprogram_renaming_declaration that is not a completion is called a renaming-as-declaration[, and is used to rename a subprogram (possibly an enumeration literal) or an entry].
Syntax
2/3subprogram_renaming_declaration ::=
[overriding_indicator]
subprogram_specification renames callable_entity_name
[aspect_specification];
Name Resolution Rules
3The expected profile for the callable_entity_name is the profile given in the subprogram_specification.
Legality Rules
4/5The profile of a renaming-as-declaration shall be mode conformant with that of the renamed callable entity.
For a parameter or result subtype of the subprogram_specification that has an explicit null_exclusion:
- if the callable_entity_
namestatically denotes a generic formal subprogram of a generic unit G, and thesubprogram_renaming_declarationoccurs within the body of a generic unit G or within the body of a generic unit declared within the declarative region of the generic unit G, then the corresponding parameter or result subtype of the formal subprogram of G shall have anull_exclusion; 4.3/2 - otherwise, the subtype of the corresponding parameter or result type of the renamed callable entity shall exclude null. In addition to the places where Legality Rules normally apply (see 12.3), this rule applies also in the private part of an instance of a generic unit.
null_exclusion. The first bullet is an assume-the-worst rule which prevents trouble in generic bodies (including bodies of child units) when the formal subtype excludes null implicitly. {8652/0027} {8652/0028} The profile of a renaming-as-body shall conform fully to that of the declaration it completes. If the renaming-as-body completes that declaration before the subprogram it declares is frozen, the profile shall be mode conformant with that of the renamed callable entity and the subprogram it declares takes its convention from the renamed subprogram; otherwise, the profile shall be subtype conformant with that of the renamed callable entity and the convention of the renamed subprogram shall not be Intrinsic. A renaming-as-body is illegal if the declaration occurs before the subprogram whose declaration it completes is frozen, and the renaming renames the subprogram itself, through one or more subprogram renaming declarations, none of whose subprograms has been frozen.
subprogram_declaration is frozen. For some types (such as integer types), the parameter type for operators is the base type, and it would be very strange forfunction Equal (A, B : in T) return Boolean;
function Equal (A, B : in T) return Boolean renames "=";
to be illegal. (Note that predefined operators cannot be renamed this way after the
subprogram_declaration is frozen, as they have convention Intrinsic.)subprogram_declarations. entry_declaration, unlike a subprogram_declaration, cannot be completed with a renaming_declaration. Nor can a generic_subprogram_declaration.The callable_entity_name of a renaming shall not denote a subprogram that requires overriding (see 3.9.3).
name will denote the overriding subprogram, not the inherited one. The callable_entity_name of a renaming-as-body shall not denote an abstract subprogram.
If the callable_entity_name of a renaming is a prefixed view, the prefix of that view shall denote an object for which renaming is allowed.
A name that denotes a formal parameter of the subprogram_specification is not allowed within the callable_entity_name.
function F(X : Integer) return Integer renames Table(X).all;
function F(X : Integer; Y : Integer := X) return Integer;
Static Semantics
7A renaming-as-declaration declares a new view of the renamed entity. The profile of this new view takes its subtypes, parameter modes, and calling convention from the original profile of the callable entity, while taking the formal parameter names and default_expressions from the profile given in the subprogram_renaming_declaration. The new view is a function or procedure, never an entry.
entry_call_statement of a timed_entry_call to call the new view. But what looks like a procedure call will do things like barrier waiting.Dynamic Semantics
7.1/1{8652/0014} For a call to a subprogram whose body is given as a renaming-as-body, the execution of the renaming-as-body is equivalent to the execution of a subprogram_body that simply calls the renamed subprogram with its formal parameters as the actual parameters and, if it is a function, returns the value of the call.
For a call on a renaming of a dispatching subprogram that is overridden, if the overriding occurred before the renaming, then the body executed is that of the overriding declaration, even if the overriding declaration is not visible at the place of the renaming; otherwise, the inherited or predefined subprogram is called. A corresponding rule applies to a call on a renaming of a predefined equality operator for an untagged record type.
package P is
type T is tagged null record;
function Predefined_Equal(X, Y : T) return Boolean renames "=";
private
function "="(X, Y : T) return Boolean; -- Override predefined "=".
end P;
8.ewith P; use P;
package Q is
function User_Defined_Equal(X, Y : T) return Boolean renames P."=";
end Q;
Bounded (Run-Time) Errors
8.1/1{8652/0027} If a subprogram directly or indirectly renames itself, then it is a bounded error to call that subprogram. Possible consequences are that Program_Error or Storage_Error is raised, or that the call results in infinite recursion.
defining_designator is either an identifier or an operator_symbol can be renamed with either an identifier or an operator_symbol; for renaming as an operator, the subprogram specification given in the renaming_declaration is subject to the rules given in 6.6 for operator declarations. Enumeration literals can be renamed as functions; similarly, attribute_references that denote functions (such as references to Succ and Pred) can be renamed as functions. An entry can only be renamed as a procedure; the new name is only allowed to appear in contexts that allow a procedure name. An entry of a family can be renamed, but an entry family cannot be renamed as a whole.subprogram_renaming_declaration could more properly be called renaming_as_subprogram_declaration, since you're renaming something as a subprogram, but you're not necessarily renaming a subprogram. But that's too much of a mouthful. Or, alternatively, we could call it a callable_entity_renaming_declaration, but that's even worse. Not only is it a mouthful, it emphasizes the entity being renamed, rather than the new view, which we think is a bad idea. We'll live with the oddity. Examples
13Examples of subprogram renaming declarations:
procedure My_Write(C : in Character) renames Pool(K).Write; -- see 4.1.3
15function Real_Plus(Left, Right : Real ) return Real renames "+";
function Int_Plus (Left, Right : Integer) return Integer renames "+";
16function Rouge return Color renames Red; -- see 3.5.1
function Rot return Color renames Red;
function Rosso return Color renames Rouge;
17function Next(X : Color) return Color renames Color'Succ; -- see 3.5.1
Example of a subprogram renaming declaration with new parameter names:
function "*" (X,Y : Vector) return Real renames Dot_Product; -- see 6.1
Example of a subprogram renaming declaration with a new default expression:
function Minimum(L : Link := Head) return Cell renames Min_Cell; -- see 6.1
Extensions to Ada 95
Wording Changes from Ada 95
Inconsistencies With Ada 2005
Extensions to Ada 2005
aspect_specification can be used in a subprogram_renaming_declaration. This is described in 13.1.1. Incompatibilities With Ada 2012
Wording Changes from Ada 2012
8.5.5 Generic Renaming Declarations
1[A generic_renaming_declaration is used to rename a generic unit.]
Syntax
2/3generic_renaming_declaration ::=
generic package defining_program_unit_name renames generic_package_name
[aspect_specification];
| generic procedure defining_program_unit_name renames generic_procedure_name
[aspect_specification];
| generic function defining_program_unit_name renames generic_function_name
[aspect_specification];
Legality Rules
3The renamed entity shall be a generic unit of the corresponding kind.
Static Semantics
4A generic_renaming_declaration declares a new view [of the renamed generic unit].
generic_renaming_declaration occurs can affect the legality of subsequent renamings and instantiations that denote the generic_renaming_declaration, in particular if the renamed generic unit is a library unit (see 10.1.1). Examples
6Example of renaming a generic unit:
generic package Enum_IO renames Ada.Text_IO.Enumeration_IO; -- see A.10.10
Extensions to Ada 83
Wording Changes from Ada 83
Extensions to Ada 2005
aspect_specification can be used in a generic_renaming_declaration. This is described in 13.1.1.