1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT LIBRARY COMPONENTS                          --
4--                                                                          --
5--       A D A . C O N T A I N E R S . B O U N D E D _ H O L D E R S        --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--            Copyright (C) 2015-2020, Free Software Foundation, Inc.       --
10--                                                                          --
11-- This specification is derived from the Ada Reference Manual for use with --
12-- GNAT. The copyright notice above, and the license provisions that follow --
13-- apply solely to the  contents of the part following the private keyword. --
14--                                                                          --
15-- GNAT is free software;  you can  redistribute it  and/or modify it under --
16-- terms of the  GNU General Public License as published  by the Free Soft- --
17-- ware  Foundation;  either version 3,  or (at your option) any later ver- --
18-- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
19-- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
20-- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
21--                                                                          --
22-- As a special exception under Section 7 of GPL version 3, you are granted --
23-- additional permissions described in the GCC Runtime Library Exception,   --
24-- version 3.1, as published by the Free Software Foundation.               --
25--                                                                          --
26-- You should have received a copy of the GNU General Public License and    --
27-- a copy of the GCC Runtime Library Exception along with this program;     --
28-- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
29-- <http://www.gnu.org/licenses/>.                                          --
30------------------------------------------------------------------------------
31
32private with System;
33private with Ada.Strings.Text_Output;
34
35generic
36   type Element_Type (<>) is private;
37   Max_Size_In_Storage_Elements : Natural :=
38     Element_Type'Max_Size_In_Storage_Elements;
39   with function "=" (Left, Right : Element_Type) return Boolean is <>;
40
41package Ada.Containers.Bounded_Holders is
42   pragma Annotate (CodePeer, Skip_Analysis);
43
44   --  This package is patterned after Ada.Containers.Indefinite_Holders. It is
45   --  used to treat indefinite subtypes as definite, but without using heap
46   --  allocation. For example, you might like to say:
47   --
48   --     type A is array (...) of T'Class; -- illegal
49   --
50   --  Instead, you can instantiate this package with Element_Type => T'Class,
51   --  and say:
52   --
53   --     type A is array (...) of Holder;
54   --
55   --  Each object of type Holder is allocated Max_Size_In_Storage_Elements
56   --  bytes. If you try to create a holder from an object of type Element_Type
57   --  that is too big, an exception is raised (assuming assertions are
58   --  enabled). This applies to To_Holder and Set. If you pass an Element_Type
59   --  object that is smaller than Max_Size_In_Storage_Elements, it works fine,
60   --  but some space is wasted.
61   --
62   --  NOTE: If assertions are disabled, and you try to use an Element that is
63   --  too big, execution is erroneous, and anything can happen, such as
64   --  overwriting arbitrary memory locations.
65   --
66   --  Element_Type must not be an unconstrained array type. It can be a
67   --  class-wide type or a type with non-defaulted discriminants.
68   --
69   --  The 'Size of each Element_Type object must be a multiple of
70   --  System.Storage_Unit; e.g. creating Holders from 5-bit objects won't
71   --  work.
72
73   type Holder is private;
74
75   function "=" (Left, Right : Holder) return Boolean;
76
77   function To_Holder (New_Item : Element_Type) return Holder;
78   function "+" (New_Item : Element_Type) return Holder renames To_Holder;
79
80   function Get (Container : Holder) return Element_Type;
81
82   procedure Set (Container : in out Holder; New_Item  : Element_Type);
83
84private
85
86   --  The implementation uses low-level tricks (Address clauses and unchecked
87   --  conversions of access types) to treat the elements as storage arrays.
88
89   pragma Assert (Element_Type'Alignment <= Standard'Maximum_Alignment);
90   --  This prevents elements with a user-specified Alignment that is too big
91
92   type Storage_Element is mod 2 ** System.Storage_Unit;
93   type Storage_Array is array (Positive range <>) of Storage_Element;
94   type Holder is record
95      Data : Storage_Array (1 .. Max_Size_In_Storage_Elements);
96   end record
97     with Alignment => Standard'Maximum_Alignment, Put_Image => Put_Image;
98   --  We would like to say "Alignment => Element_Type'Alignment", but that
99   --  is illegal because it's not static, so we use the maximum possible
100   --  (default) alignment instead.
101
102   procedure Put_Image
103     (S : in out Ada.Strings.Text_Output.Sink'Class; V : Holder);
104
105   type Element_Access is access all Element_Type;
106   pragma Assert (Element_Access'Size = Standard'Address_Size,
107                  "cannot instantiate with an array type");
108   --  If Element_Access is a fat pointer, Element_Type must be an
109   --  unconstrained array, which is not allowed. Arrays won't work, because
110   --  the 'Address of an array points to the first element, thus losing the
111   --  bounds.
112
113   pragma No_Strict_Aliasing (Element_Access);
114   --  Needed because we are unchecked-converting from Address to
115   --  Element_Access (see package body), which is a violation of the
116   --  normal aliasing rules enforced by gcc.
117
118end Ada.Containers.Bounded_Holders;
119