| ------------------------------------------------------------------------------ |
| -- -- |
| -- GNAT LIBRARY COMPONENTS -- |
| -- -- |
| -- ADA.CONTAINERS.FUNCTIONAL_SETS -- |
| -- -- |
| -- S p e c -- |
| -- -- |
| -- Copyright (C) 2016-2022, Free Software Foundation, Inc. -- |
| -- -- |
| -- This specification is derived from the Ada Reference Manual for use with -- |
| -- GNAT. The copyright notice above, and the license provisions that follow -- |
| -- apply solely to the contents of the part following the private keyword. -- |
| -- -- |
| -- GNAT is free software; you can redistribute it and/or modify it under -- |
| -- terms of the GNU General Public License as published by the Free Soft- -- |
| -- ware Foundation; either version 3, or (at your option) any later ver- -- |
| -- sion. GNAT is distributed in the hope that it will be useful, but WITH- -- |
| -- OUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY -- |
| -- or FITNESS FOR A PARTICULAR PURPOSE. -- |
| -- -- |
| -- As a special exception under Section 7 of GPL version 3, you are granted -- |
| -- additional permissions described in the GCC Runtime Library Exception, -- |
| -- version 3.1, as published by the Free Software Foundation. -- |
| -- -- |
| -- You should have received a copy of the GNU General Public License and -- |
| -- a copy of the GCC Runtime Library Exception along with this program; -- |
| -- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see -- |
| -- <http://www.gnu.org/licenses/>. -- |
| ------------------------------------------------------------------------------ |
| |
| pragma Ada_2012; |
| private with Ada.Containers.Functional_Base; |
| |
| generic |
| type Element_Type (<>) is private; |
| |
| with function Equivalent_Elements |
| (Left : Element_Type; |
| Right : Element_Type) return Boolean is "="; |
| |
| Enable_Handling_Of_Equivalence : Boolean := True; |
| -- This constant should only be set to False when no particular handling |
| -- of equivalence over elements is needed, that is, Equivalent_Elements |
| -- defines an element uniquely. |
| |
| package Ada.Containers.Functional_Sets with SPARK_Mode is |
| |
| type Set is private with |
| Default_Initial_Condition => Is_Empty (Set), |
| Iterable => (First => Iter_First, |
| Next => Iter_Next, |
| Has_Element => Iter_Has_Element, |
| Element => Iter_Element); |
| -- Sets are empty when default initialized. |
| -- "For in" quantification over sets should not be used. |
| -- "For of" quantification over sets iterates over elements. |
| -- Note that, for proof, "for of" quantification is understood modulo |
| -- equivalence (the range of quantification comprises all the elements that |
| -- are equivalent to any element of the set). |
| |
| ----------------------- |
| -- Basic operations -- |
| ----------------------- |
| |
| -- Sets are axiomatized using Contains, which encodes whether an element is |
| -- contained in a set. The length of a set is also added to protect Add |
| -- against overflows but it is not actually modeled. |
| |
| function Contains (Container : Set; Item : Element_Type) return Boolean with |
| -- Return True if Item is contained in Container |
| |
| Global => null, |
| Post => |
| (if Enable_Handling_Of_Equivalence then |
| |
| -- Contains returns the same result on all equivalent elements |
| |
| (if (for some E of Container => Equivalent_Elements (E, Item)) then |
| Contains'Result)); |
| |
| function Length (Container : Set) return Count_Type with |
| Global => null; |
| -- Return the number of elements in Container |
| |
| ------------------------ |
| -- Property Functions -- |
| ------------------------ |
| |
| function "<=" (Left : Set; Right : Set) return Boolean with |
| -- Set inclusion |
| |
| Global => null, |
| Post => "<="'Result = (for all Item of Left => Contains (Right, Item)); |
| |
| function "=" (Left : Set; Right : Set) return Boolean with |
| -- Extensional equality over sets |
| |
| Global => null, |
| Post => "="'Result = (Left <= Right and Right <= Left); |
| |
| pragma Warnings (Off, "unused variable ""Item"""); |
| function Is_Empty (Container : Set) return Boolean with |
| -- A set is empty if it contains no element |
| |
| Global => null, |
| Post => |
| Is_Empty'Result = (for all Item of Container => False) |
| and Is_Empty'Result = (Length (Container) = 0); |
| pragma Warnings (On, "unused variable ""Item"""); |
| |
| function Included_Except |
| (Left : Set; |
| Right : Set; |
| Item : Element_Type) return Boolean |
| -- Return True if Left contains only elements of Right except possibly |
| -- Item. |
| |
| with |
| Global => null, |
| Post => |
| Included_Except'Result = |
| (for all E of Left => |
| Contains (Right, E) or Equivalent_Elements (E, Item)); |
| |
| function Includes_Intersection |
| (Container : Set; |
| Left : Set; |
| Right : Set) return Boolean |
| with |
| -- Return True if every element of the intersection of Left and Right is |
| -- in Container. |
| |
| Global => null, |
| Post => |
| Includes_Intersection'Result = |
| (for all Item of Left => |
| (if Contains (Right, Item) then Contains (Container, Item))); |
| |
| function Included_In_Union |
| (Container : Set; |
| Left : Set; |
| Right : Set) return Boolean |
| with |
| -- Return True if every element of Container is the union of Left and Right |
| |
| Global => null, |
| Post => |
| Included_In_Union'Result = |
| (for all Item of Container => |
| Contains (Left, Item) or Contains (Right, Item)); |
| |
| function Is_Singleton |
| (Container : Set; |
| New_Item : Element_Type) return Boolean |
| with |
| -- Return True Container only contains New_Item |
| |
| Global => null, |
| Post => |
| Is_Singleton'Result = |
| (for all Item of Container => Equivalent_Elements (Item, New_Item)); |
| |
| function Not_In_Both |
| (Container : Set; |
| Left : Set; |
| Right : Set) return Boolean |
| -- Return True if there are no elements in Container that are in Left and |
| -- Right. |
| |
| with |
| Global => null, |
| Post => |
| Not_In_Both'Result = |
| (for all Item of Container => |
| not Contains (Left, Item) or not Contains (Right, Item)); |
| |
| function No_Overlap (Left : Set; Right : Set) return Boolean with |
| -- Return True if there are no equivalent elements in Left and Right |
| |
| Global => null, |
| Post => |
| No_Overlap'Result = |
| (for all Item of Left => not Contains (Right, Item)); |
| |
| function Num_Overlaps (Left : Set; Right : Set) return Count_Type with |
| -- Number of elements that are both in Left and Right |
| |
| Global => null, |
| Post => |
| Num_Overlaps'Result = Length (Intersection (Left, Right)) |
| and (if Left <= Right then Num_Overlaps'Result = Length (Left) |
| else Num_Overlaps'Result < Length (Left)) |
| and (if Right <= Left then Num_Overlaps'Result = Length (Right) |
| else Num_Overlaps'Result < Length (Right)) |
| and (Num_Overlaps'Result = 0) = No_Overlap (Left, Right); |
| |
| ---------------------------- |
| -- Construction Functions -- |
| ---------------------------- |
| |
| -- For better efficiency of both proofs and execution, avoid using |
| -- construction functions in annotations and rather use property functions. |
| |
| function Add (Container : Set; Item : Element_Type) return Set with |
| -- Return a new set containing all the elements of Container plus E |
| |
| Global => null, |
| Pre => |
| not Contains (Container, Item) |
| and Length (Container) < Count_Type'Last, |
| Post => |
| Length (Add'Result) = Length (Container) + 1 |
| and Contains (Add'Result, Item) |
| and Container <= Add'Result |
| and Included_Except (Add'Result, Container, Item); |
| |
| function Remove (Container : Set; Item : Element_Type) return Set with |
| -- Return a new set containing all the elements of Container except E |
| |
| Global => null, |
| Pre => Contains (Container, Item), |
| Post => |
| Length (Remove'Result) = Length (Container) - 1 |
| and not Contains (Remove'Result, Item) |
| and Remove'Result <= Container |
| and Included_Except (Container, Remove'Result, Item); |
| |
| function Intersection (Left : Set; Right : Set) return Set with |
| -- Returns the intersection of Left and Right |
| |
| Global => null, |
| Post => |
| Intersection'Result <= Left |
| and Intersection'Result <= Right |
| and Includes_Intersection (Intersection'Result, Left, Right); |
| |
| function Union (Left : Set; Right : Set) return Set with |
| -- Returns the union of Left and Right |
| |
| Global => null, |
| Pre => |
| Length (Left) - Num_Overlaps (Left, Right) <= |
| Count_Type'Last - Length (Right), |
| Post => |
| Length (Union'Result) = |
| Length (Left) - Num_Overlaps (Left, Right) + Length (Right) |
| and Left <= Union'Result |
| and Right <= Union'Result |
| and Included_In_Union (Union'Result, Left, Right); |
| |
| function Copy_Element (Item : Element_Type) return Element_Type is (Item); |
| -- Elements of containers are copied by numerous primitives in this |
| -- package. This function causes GNATprove to verify that such a copy is |
| -- valid (in particular, it does not break the ownership policy of SPARK, |
| -- i.e. it does not contain pointers that could be used to alias mutable |
| -- data). |
| |
| --------------------------- |
| -- Iteration Primitives -- |
| --------------------------- |
| |
| type Private_Key is private; |
| |
| function Iter_First (Container : Set) return Private_Key with |
| Global => null; |
| |
| function Iter_Has_Element |
| (Container : Set; |
| Key : Private_Key) return Boolean |
| with |
| Global => null; |
| |
| function Iter_Next |
| (Container : Set; |
| Key : Private_Key) return Private_Key |
| with |
| Global => null, |
| Pre => Iter_Has_Element (Container, Key); |
| |
| function Iter_Element |
| (Container : Set; |
| Key : Private_Key) return Element_Type |
| with |
| Global => null, |
| Pre => Iter_Has_Element (Container, Key); |
| pragma Annotate (GNATprove, Iterable_For_Proof, "Contains", Contains); |
| |
| private |
| |
| pragma SPARK_Mode (Off); |
| |
| subtype Positive_Count_Type is Count_Type range 1 .. Count_Type'Last; |
| |
| function "=" |
| (Left : Element_Type; |
| Right : Element_Type) return Boolean renames Equivalent_Elements; |
| |
| package Containers is new Ada.Containers.Functional_Base |
| (Element_Type => Element_Type, |
| Index_Type => Positive_Count_Type); |
| |
| type Set is record |
| Content : Containers.Container; |
| end record; |
| |
| type Private_Key is new Count_Type; |
| |
| function Iter_First (Container : Set) return Private_Key is (1); |
| |
| function Iter_Has_Element |
| (Container : Set; |
| Key : Private_Key) return Boolean |
| is |
| (Count_Type (Key) in 1 .. Containers.Length (Container.Content)); |
| |
| function Iter_Next |
| (Container : Set; |
| Key : Private_Key) return Private_Key |
| is |
| (if Key = Private_Key'Last then 0 else Key + 1); |
| |
| function Iter_Element |
| (Container : Set; |
| Key : Private_Key) return Element_Type |
| is |
| (Containers.Get (Container.Content, Count_Type (Key))); |
| |
| end Ada.Containers.Functional_Sets; |
