The Generic Package Containers.Indefinite_Holders
Author: JTC1/SC22/WG9/ARG, by Randall Brukardt, ARG Editor

Ada Reference Manual — Legal Information

# A.18.18 The Generic Package Containers.Indefinite_Holders

1/3
The language-defined generic package Containers.Indefinite_Holders provides a private type Holder and a set of operations for that type. A holder container holds a single element of an indefinite type.
2/3
A holder container allows the declaration of an object that can be used like an uninitialized variable or component of an indefinite type.
3/3
A holder container may be empty. An empty holder does not contain an element.

#### Static Semantics

4/3
The generic library package Containers.Indefinite_Holders has the following declaration:
5/3
generic
type Element_Type (<>) is private;
with function "=" (Left, Right : Element_Type) return Boolean is <>;
package Ada.Containers.Indefinite_Holders is
pragma Preelaborate(Indefinite_Holders);
pragma Remote_Types(Indefinite_Holders);
6/3
type Holder is tagged private;
pragma Preelaborable_Initialization (Holder);
7/3
Empty_Holder : constant Holder;
8/3
function "=" (Left, Right : Holder) return Boolean;
9/3
function To_Holder (New_Item : Element_Type) return Holder;
10/3
function Is_Empty (Container : Holder) return Boolean;
11/3
procedure Clear (Container : in out Holder);
12/3
function Element (Container : Holder) return Element_Type;
13/3
procedure Replace_Element (Container : in out Holder;
New_Item : in Element_Type);
14/3
procedure Query_Element
(Container : in Holder;
Process : not null access procedure (Element : in Element_Type));
15/3
procedure Update_Element
(Container : in out Holder;
Process : not null access procedure (Element : in out Element_Type));
16/3
type Constant_Reference_Type
(Element : not null access constant Element_Type) is private
with Implicit_Dereference => Element;
17/3
type Reference_Type (Element : not null access Element_Type) is private
with Implicit_Dereference => Element;
18/3
function Constant_Reference (Container : aliased in Holder)
return Constant_Reference_Type;
19/3
function Reference (Container : aliased in out Holder)
return Reference_Type;
20/3
procedure Assign (Target : in out Holder; Source : in Holder);
21/3
function Copy (Source : Holder) return Holder;
22/3
procedure Move (Target : in out Holder; Source : in out Holder);
23/3
private
24/3
... -- not specified by the language
25/3
end Ada.Containers.Indefinite_Holders;
26/3
The actual function for the generic formal function "=" on Element_Type values is expected to define a reflexive and symmetric relationship and return the same result value each time it is called with a particular pair of values. If it behaves in some other manner, the function "=" on holder values returns an unspecified value. The exact arguments and number of calls of this generic formal function by the function "=" on holder values are unspecified.
27/3
The type Holder is used to represent holder containers. The type Holder needs finalization (see 7.6).
28/3
Empty_Holder represents an empty holder object. If an object of type Holder is not otherwise initialized, it is initialized to the same value as Empty_Holder.
29/3
Some operations of this generic package have access-to-subprogram parameters. To ensure such operations are well-defined, they guard against certain actions by the designated subprogram. In particular, some operations check for “tampering with the element” of a container because they depend on the element of the container not being replaced.
30/3
A subprogram is said to tamper with the element of a holder object H if:
31/3
It clears the element contained by H, that is, it calls the Clear procedure with H as a parameter;
32/3
It replaces the element contained by H, that is, it calls the Replace_Element procedure with H as a parameter;
33/3
It calls the Move procedure with H as a parameter;
34/3
It finalizes H.
35/3
When tampering with the element is prohibited for a particular holder object H, Program_Error is propagated by a call of any language-defined subprogram that is defined to tamper with the element of H, leaving H unmodified.
36/3
function "=" (Left, Right : Holder) return Boolean;
37/3
If Left and Right denote the same holder object, then the function returns True. Otherwise, it compares the element contained in Left to the element contained in Right using the generic formal equality operator, returning the result of that operation. Any exception raised during the evaluation of element equality is propagated.
38/3
function To_Holder (New_Item : Element_Type) return Holder;
39/3
Returns a nonempty holder containing an element initialized to New_Item.
40/3
function Is_Empty (Container : Holder) return Boolean;
41/3
Returns True if Container is empty, and False if it contains an element.
42/3
procedure Clear (Container : in out Holder);
43/3
Removes the element from Container. Container is empty after a successful Clear operation.
44/3
function Element (Container : Holder) return Element_Type;
45/3
If Container is empty, Constraint_Error is propagated. Otherwise, returns the element stored in Container.
46/3
procedure Replace_Element (Container : in out Holder;
New_Item : in Element_Type);
47/3
Replace_Element assigns the value New_Item into Container, replacing any preexisting content of Container. Container is not empty after a successful call to Replace_Element.
48/3
procedure Query_Element
(Container : in Holder;
Process : not null access procedure (Element : in Element_Type));
49/3
If Container is empty, Constraint_Error is propagated. Otherwise, Query_Element calls Process.all with the contained element as the argument. Tampering with the element of Container is prohibited during the execution of the call on Process.all. Any exception raised by Process.all is propagated.
50/3
procedure Update_Element
(Container : in out Holder;
Process : not null access procedure (Element : in out Element_Type));
51/3
If Container is empty, Constraint_Error is propagated. Otherwise, Update_Element calls Process.all with the contained element as the argument. Tampering with the element of Container is prohibited during the execution of the call on Process.all. Any exception raised by Process.all is propagated.
52/3
type Constant_Reference_Type
(Element : not null access constant Element_Type) is private
with Implicit_Dereference => Element;
53/3
type Reference_Type (Element : not null access Element_Type) is private
with Implicit_Dereference => Element;
54/3
The types Constant_Reference_Type and Reference_Type need finalization.
55/3
The default initialization of an object of type Constant_Reference_Type or Reference_Type propagates Program_Error.
56/3
function Constant_Reference (Container : aliased in Holder)
return Constant_Reference_Type;
57/3
This function (combined with the Implicit_Dereference aspect) provides a convenient way to gain read access to the contained element of a holder container.
58/3
If Container is empty, Constraint_Error is propagated. Otherwise, Constant_Reference returns an object whose discriminant is an access value that designates the contained element. Tampering with the elements of Container is prohibited while the object returned by Constant_Reference exists and has not been finalized.
59/3
function Reference (Container : aliased in out Holder)
return Reference_Type;
60/3
This function (combined with the Implicit_Dereference aspects) provides a convenient way to gain read and write access to the contained element of a holder container.
61/3
If Container is empty, Constraint_Error is propagated. Otherwise, Reference returns an object whose discriminant is an access value that designates the contained element. Tampering with the elements of Container is prohibited while the object returned by Reference exists and has not been finalized.
62/3
procedure Assign (Target : in out Holder; Source : in Holder);
63/3
If Target denotes the same object as Source, the operation has no effect. If Source is empty, Clear (Target) is called. Otherwise, Replace_Element (Target, Element (Source)) is called.
64/3
function Copy (Source : Holder) return Holder;
65/3
If Source is empty, returns an empty holder container; otherwise, returns To_Holder (Element (Source)).
66/3
procedure Move (Target : in out Holder; Source : in out Holder);
67/3
If Target denotes the same object as Source, then the operation has no effect. Otherwise, the element contained by Source (if any) is removed from Source and inserted into Target, replacing any preexisting content. Source is empty after a successful call to Move.

#### Bounded (Run-Time) Errors

68/3
It is a bounded error for the actual function associated with a generic formal subprogram, when called as part of an operation of this package, to tamper with the element of any Holder parameter of the operation. Either Program_Error is raised, or the operation works as defined on the value of the Holder either prior to, or subsequent to, some or all of the modifications to the Holder.
69/3
It is a bounded error to call any subprogram declared in the visible part of Containers.Indefinite_Holders when the associated container has been finalized. If the operation takes Container as an in out parameter, then it raises Constraint_Error or Program_Error. Otherwise, the operation either proceeds as it would for an empty container, or it raises Constraint_Error or Program_Error.

#### Erroneous Execution

70/3
Execution is erroneous if the holder container associated with the result of a call to Reference or Constant_Reference is finalized before the result object returned by the call to Reference or Constant_Reference is finalized.

#### Implementation Requirements

71/3
No storage associated with a holder object shall be lost upon assignment or scope exit.
72/3
The execution of an assignment_statement for a holder container shall have the effect of copying the element (if any) from the source holder object to the target holder object.

#### Implementation Advice

73/3
Move should not copy the element, and should minimize copying of internal data structures.
74/3
If an exception is propagated from a holder operation, no storage should be lost, nor should the element be removed from a holder container unless specified by the operation.

Ada 2005 and 2012 Editions sponsored in part by Ada-Europe