Holders

Indefinite Holders

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.

A holder container allows the declaration of an object that can be used like an uninitialized variable or component of an indefinite type.

A holder container may be empty. An empty holder does not contain an element.

generic
   type Element_Type (<>) is private;
   with function "="(Left, Right: Element_Type) return Boolean is <>;
package Ada.Containers.Indefinite_Holders
   with Preelaborate, Remote_Types, Nonblocking,
        Global => in out synchronized is

   type Holder is tagged private;

   Empty_Holder: constant Holder;

   function Equal_Element(Left, Right: Element_Type) return Boolean renames "=";

   function "="(Left, Right: Holder) return Boolean;

   function Tampering_With_The_Element_Prohibited(Container: Holder) return Boolean;

   function Empty return Holder is
      (Empty_Holder);

   procedure Clear          (Container: in out Holder);
   procedure Replace_Element(Container: in out Holder; New_Item: Element_Type);

   function To_Holder(New_Item: Element_Type) return Holder;
   function Is_Empty(Container: Holder) return Boolean;
   function Element (Container: Holder) return Element_Type;

   procedure Query_Element(Container: Holder;
                           Process  : not null access procedure(Element: Element_Type));
   procedure Update_Element(Container: in out Holder;
                            Process  : not null access procedure(Element: in out Element_Type));

   type Constant_Reference_Type(Element: not null access constant Element_Type) is private;
   type Reference_Type         (Element: not null access          Element_Type) is private;

   function Constant_Reference(Container: aliased        Holder) return Constant_Reference_Type;
   function Reference         (Container: aliased in out Holder) return Reference_Type;

   function  Copy  (                       Source:        Holder) return Holder;
   procedure Assign(Target: in out Holder; Source:        Holder);
   procedure Move  (Target: in out Holder; Source: in out Holder);
   procedure Swap(Left, Right: in out Holder);
end Ada.Containers.Indefinite_Holders;

Bounded (Run-Time) Errors

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.

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

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.

Bounded Indefinite Holders

The language-defined generic package Containers.Bounded_Indefinite_Holders provides a private type Holder and a set of operations for that type. It provides the same operations as the package Containers.Indefinite_Holders (see A.18.18), with the difference that the maximum storage is bounded.

-- Following the generic parameter Element_Type
Max_Element_Size_in_Storage_Elements: Storage_Count;

Bounded (Run-Time) Errors

It is a bounded error to assign from a bounded holder object while tampering with elements of that object is prohibited. Either Program_Error is raised by the assignment, execution proceeds with the target object prohibiting tampering with elements, or execution proceeds normally.