gcc/ada/libgnat/a-chtgfo.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT LIBRARY COMPONENTS                          --
   4 --                                                                          --
   5 --            ADA.CONTAINERS.HASH_TABLES.GENERIC_FORMAL_OPERATIONS          --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 2004-2022, Free Software Foundation, Inc.         --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 3,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.                                     --
  17 --                                                                          --
  18 -- As a special exception under Section 7 of GPL version 3, you are granted --
  19 -- additional permissions described in the GCC Runtime Library Exception,   --
  20 -- version 3.1, as published by the Free Software Foundation.               --
  21 --                                                                          --
  22 -- You should have received a copy of the GNU General Public License and    --
  23 -- a copy of the GCC Runtime Library Exception along with this program;     --
  24 -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
  25 -- <http://www.gnu.org/licenses/>.                                          --
  26 --                                                                          --
  27 -- This unit was originally developed by Matthew J Heaney.                  --
  28 ------------------------------------------------------------------------------
  29
  30 --  Hash_Table_Type is used to implement hashed containers. This package
  31 --  declares hash-table operations that do not depend on keys.
  32
  33 with Ada.Streams;
  34
  35 generic
  36    with package HT_Types is
  37      new Generic_Formal_Hash_Table_Types (<>);
  38
  39    use HT_Types;
  40
  41    with function Hash_Node (Node : Node_Type) return Hash_Type;
  42
  43    with function Next (Node : Node_Type) return Count_Type;
  44
  45    with procedure Set_Next
  46      (Node : in out Node_Type;
  47       Next : Count_Type);
  48
  49 package Ada.Containers.Hash_Tables.Generic_Formal_Operations is
  50    pragma Pure;
  51
  52    function Index
  53      (Buckets : Buckets_Type;
  54       Node    : Node_Type) return Hash_Type;
  55    pragma Inline (Index);
  56    --  Uses the hash value of Node to compute its Buckets array index
  57
  58    function Index
  59      (HT   : Hash_Table_Type;
  60       Node : Node_Type) return Hash_Type;
  61    pragma Inline (Index);
  62    --  Uses the hash value of Node to compute its Hash_Table buckets array
  63    --  index.
  64
  65    function Checked_Index
  66      (Hash_Table : Hash_Table_Type;
  67       Node       : Count_Type) return Hash_Type;
  68    --  Calls Index, but also locks and unlocks the container, per AI05-0022, in
  69    --  order to detect element tampering by the generic actual Hash function.
  70
  71    generic
  72       with function Find
  73         (HT  : Hash_Table_Type;
  74          Key : Node_Type) return Boolean;
  75    function Generic_Equal (L, R : Hash_Table_Type) return Boolean;
  76    --  Used to implement hashed container equality. For each node in hash table
  77    --  L, it calls Find to search for an equivalent item in hash table R. If
  78    --  Find returns False for any node then Generic_Equal terminates
  79    --  immediately and returns False. Otherwise if Find returns True for every
  80    --  node then Generic_Equal returns True.
  81
  82    procedure Clear (HT : in out Hash_Table_Type);
  83    --  Deallocates each node in hash table HT. (Note that it only deallocates
  84    --  the nodes, not the buckets array.) Program_Error is raised if the hash
  85    --  table is busy.
  86
  87    procedure Delete_Node_At_Index
  88      (HT   : in out Hash_Table_Type;
  89       Indx : Hash_Type;
  90       X    : Count_Type);
  91    --  Delete a node whose bucket position is known. extracted from following
  92    --  subprogram, but also used directly to remove a node whose element has
  93    --  been modified through a key_preserving reference: in that case we cannot
  94    --  use the value of the element precisely because the current value does
  95    --  not correspond to the hash code that determines its bucket.
  96
  97    procedure Delete_Node_Sans_Free
  98      (HT : in out Hash_Table_Type;
  99       X  : Count_Type);
 100    --  Removes node X from the hash table without deallocating the node
 101
 102    generic
 103       with procedure Set_Element (Node : in out Node_Type);
 104    procedure Generic_Allocate
 105      (HT   : in out Hash_Table_Type;
 106       Node : out Count_Type);
 107    --  Claim a node from the free store. Generic_Allocate first
 108    --  calls Set_Element on the potential node, and then returns
 109    --  the node's index as the value of the Node parameter.
 110
 111    procedure Free
 112      (HT : in out Hash_Table_Type;
 113       X  : Count_Type);
 114    --  Return a node back to the free store, from where it had
 115    --  been previously claimed via Generic_Allocate.
 116
 117    function First (HT : Hash_Table_Type) return Count_Type;
 118    --  Returns the head of the list in the first (lowest-index) non-empty
 119    --  bucket.
 120
 121    function Next
 122      (HT   : Hash_Table_Type;
 123       Node : Count_Type) return Count_Type;
 124    --  Returns the node that immediately follows Node. This corresponds to
 125    --  either the next node in the same bucket, or (if Node is the last node in
 126    --  its bucket) the head of the list in the first non-empty bucket that
 127    --  follows.
 128
 129    generic
 130       with procedure Process (Node : Count_Type);
 131    procedure Generic_Iteration (HT : Hash_Table_Type);
 132    --  Calls Process for each node in hash table HT
 133
 134    generic
 135       use Ada.Streams;
 136       with procedure Write
 137         (Stream : not null access Root_Stream_Type'Class;
 138          Node   : Node_Type);
 139    procedure Generic_Write
 140      (Stream : not null access Root_Stream_Type'Class;
 141       HT     : Hash_Table_Type);
 142    --  Used to implement the streaming attribute for hashed containers. It
 143    --  calls Write for each node to write its value into Stream.
 144
 145    generic
 146       use Ada.Streams;
 147       with function New_Node (Stream : not null access Root_Stream_Type'Class)
 148          return Count_Type;
 149    procedure Generic_Read
 150      (Stream : not null access Root_Stream_Type'Class;
 151       HT     : out Hash_Table_Type);
 152    --  Used to implement the streaming attribute for hashed containers. It
 153    --  first clears hash table HT, then populates the hash table by calling
 154    --  New_Node for each item in Stream.
 155
 156 end Ada.Containers.Hash_Tables.Generic_Formal_Operations;