gcc/ada/libgnat/a-coboho.ads

   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-2023, 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
  32 private with System;
  33 private with Ada.Strings.Text_Buffers;
  34
  35 generic
  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
  41 package 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      with Preelaborable_Initialization
  75             => Element_Type'Preelaborable_Initialization;
  76
  77    function "=" (Left, Right : Holder) return Boolean;
  78
  79    function To_Holder (New_Item : Element_Type) return Holder;
  80    function "+" (New_Item : Element_Type) return Holder renames To_Holder;
  81
  82    function Get (Container : Holder) return Element_Type;
  83
  84    procedure Set (Container : in out Holder; New_Item  : Element_Type);
  85
  86    function Constant_Reference
  87      (Container : aliased Holder) return not null access constant Element_Type;
  88
  89    function Reference
  90      (Container : not null access Holder) return not null access Element_Type;
  91
  92 private
  93
  94    --  The implementation uses low-level tricks (Address clauses and unchecked
  95    --  conversions of access types) to treat the elements as storage arrays.
  96
  97    pragma Assert (Element_Type'Alignment <= Standard'Maximum_Alignment);
  98    --  This prevents elements with a user-specified Alignment that is too big
  99
 100    type Storage_Element is mod 2 ** System.Storage_Unit;
 101    type Storage_Array is array (Positive range <>) of Storage_Element;
 102    type Holder is record
 103       Data : Storage_Array (1 .. Max_Size_In_Storage_Elements);
 104    end record
 105      with Alignment => Standard'Maximum_Alignment, Put_Image => Put_Image;
 106    --  We would like to say "Alignment => Element_Type'Alignment", but that
 107    --  is illegal because it's not static, so we use the maximum possible
 108    --  (default) alignment instead.
 109
 110    procedure Put_Image
 111      (S : in out Ada.Strings.Text_Buffers.Root_Buffer_Type'Class; V : Holder);
 112
 113    type Element_Access is access all Element_Type;
 114    pragma Assert (Element_Access'Size = Standard'Address_Size,
 115                   "cannot instantiate with an array type");
 116    --  If Element_Access is a fat pointer, Element_Type must be an
 117    --  unconstrained array, which is not allowed. Arrays won't work, because
 118    --  the 'Address of an array points to the first element, thus losing the
 119    --  bounds.
 120
 121    pragma No_Strict_Aliasing (Element_Access);
 122    --  Needed because we are unchecked-converting from Address to
 123    --  Element_Access (see package body), which is a violation of the
 124    --  normal aliasing rules enforced by gcc.
 125
 126 end Ada.Containers.Bounded_Holders;