1------------------------------------------------------------------------------
2--                                                                          --
3--                         GNAT RUN-TIME COMPONENTS                         --
4--                                                                          --
5--                            G N A T . S E T S                             --
6--                                                                          --
7--                                 S p e c                                  --
8--                                                                          --
9--                        Copyright (C) 2018-2020, AdaCore                  --
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-- GNAT was originally developed  by the GNAT team at  New York University. --
28-- Extensive contributions were provided by Ada Core Technologies Inc.      --
29--                                                                          --
30------------------------------------------------------------------------------
31
32pragma Compiler_Unit_Warning;
33
34with GNAT.Dynamic_HTables; use GNAT.Dynamic_HTables;
35
36package GNAT.Sets is
37
38   --------------------
39   -- Membership_Set --
40   --------------------
41
42   --  The following package offers a membership set abstraction with the
43   --  following characteristics:
44   --
45   --    * Creation of multiple instances, of different sizes
46   --    * Iterable elements
47   --
48   --  The following use pattern must be employed with this set:
49   --
50   --    Set : Membership_Set := Create (<some size>);
51   --
52   --    <various operations>
53   --
54   --    Destroy (Set);
55   --
56   --  The destruction of the set reclaims all storage occupied by it.
57
58   generic
59      type Element_Type is private;
60
61      with function "="
62             (Left  : Element_Type;
63              Right : Element_Type) return Boolean;
64
65      with function Hash (Key : Element_Type) return Bucket_Range_Type;
66      --  Map an arbitrary key into the range of buckets
67
68   package Membership_Sets is
69
70      --------------------
71      -- Set operations --
72      --------------------
73
74      --  The following type denotes a membership set handle. Each instance
75      --  must be created using routine Create.
76
77      type Membership_Set is private;
78      Nil : constant Membership_Set;
79
80      function Contains
81        (S    : Membership_Set;
82         Elem : Element_Type) return Boolean;
83      --  Determine whether membership set S contains element Elem
84
85      function Create (Initial_Size : Positive) return Membership_Set;
86      --  Create a new membership set with bucket capacity Initial_Size. This
87      --  routine must be called at the start of the membership set's lifetime.
88
89      procedure Delete
90        (S    : Membership_Set;
91         Elem : Element_Type);
92      --  Delete element Elem from membership set S. The routine has no effect
93      --  if the element is not present in the membership set. This action will
94      --  raise Iterated if the membership set has outstanding iterators.
95
96      procedure Destroy (S : in out Membership_Set);
97      --  Destroy the contents of membership set S, rendering it unusable. This
98      --  routine must be called at the end of the membership set's lifetime.
99      --  This action will raise Iterated if the hash table has outstanding
100      --  iterators.
101
102      procedure Insert
103        (S    : Membership_Set;
104         Elem : Element_Type);
105      --  Insert element Elem in membership set S. The routine has no effect
106      --  if the element is already present in the membership set. This action
107      --  will raise Iterated if the membership set has outstanding iterators.
108
109      function Is_Empty (S : Membership_Set) return Boolean;
110      --  Determine whether set S is empty
111
112      function Present (S : Membership_Set) return Boolean;
113      --  Determine whether set S exists
114
115      procedure Reset (S : Membership_Set);
116      --  Destroy the contents of membership set S, and reset it to its initial
117      --  created state. This action will raise Iterated if the membership set
118      --  has outstanding iterators.
119
120      function Size (S : Membership_Set) return Natural;
121      --  Obtain the number of elements in membership set S
122
123      -------------------------
124      -- Iterator operations --
125      -------------------------
126
127      --  The following type represents an element iterator. An iterator locks
128      --  all mutation operations, and unlocks them once it is exhausted. The
129      --  iterator must be used with the following pattern:
130      --
131      --    Iter := Iterate (My_Set);
132      --    while Has_Next (Iter) loop
133      --       Next (Iter, Element);
134      --    end loop;
135      --
136      --  It is possible to advance the iterator by using Next only, however
137      --  this risks raising Iterator_Exhausted.
138
139      type Iterator is private;
140
141      function Iterate (S : Membership_Set) return Iterator;
142      --  Obtain an iterator over the elements of membership set S. This action
143      --  locks all mutation functionality of the associated membership set.
144
145      function Has_Next (Iter : Iterator) return Boolean;
146      --  Determine whether iterator Iter has more keys to examine. If the
147      --  iterator has been exhausted, restore all mutation functionality of
148      --  the associated membership set.
149
150      procedure Next (Iter : in out Iterator; Elem : out Element_Type);
151      --  Return the current element referenced by iterator Iter and advance
152      --  to the next available element. If the iterator has been exhausted
153      --  and further attempts are made to advance it, this routine restores
154      --  mutation functionality of the associated membership set, and then
155      --  raises Iterator_Exhausted.
156
157   private
158      procedure Destroy (B : in out Boolean);
159      --  Destroy boolean B
160
161      package Hashed_Set is new Dynamic_Hash_Tables
162        (Key_Type              => Element_Type,
163         Value_Type            => Boolean,
164         No_Value              => False,
165         Expansion_Threshold   => 1.5,
166         Expansion_Factor      => 2,
167         Compression_Threshold => 0.3,
168         Compression_Factor    => 2,
169         "="                   => "=",
170         Destroy_Value         => Destroy,
171         Hash                  => Hash);
172
173      type Membership_Set is new Hashed_Set.Dynamic_Hash_Table;
174      Nil : constant Membership_Set := Membership_Set (Hashed_Set.Nil);
175
176      type Iterator is new Hashed_Set.Iterator;
177   end Membership_Sets;
178
179end GNAT.Sets;
180