a-cgcaso.adb, [...]: (Swap, Sift): Avoid use of complex renaming.
authorArnaud Charlet <charlet@gcc.gnu.org>
Tue, 8 Apr 2008 06:44:51 +0000 (08:44 +0200)
committerArnaud Charlet <charlet@gcc.gnu.org>
Tue, 8 Apr 2008 06:44:51 +0000 (08:44 +0200)
2008-04-08  Arnaud Charlet  <charlet@adacore.com>
    Matthew Heaney  <heaney@adacore.com>

* a-cgcaso.adb, a-convec.adb: (Swap, Sift): Avoid use of complex
renaming.

* a-cgaaso.ads, a-secain.ads, a-slcain.ads, a-shcain.ads,
a-crdlli.ads, a-coormu.ads, a-ciormu.ads: modified header to conform
to convention for non-RM specs.
Add descriptive header, and documented each operation
document each operation

From-SVN: r134009

gcc/ada/a-cgaaso.ads
gcc/ada/a-cgcaso.adb
gcc/ada/a-ciormu.ads
gcc/ada/a-convec.adb
gcc/ada/a-coormu.ads
gcc/ada/a-crdlli.ads
gcc/ada/a-secain.ads
gcc/ada/a-shcain.ads
gcc/ada/a-slcain.ads

index fe2e9226adbd1c8e094e4deae6596e2a4b513d80..e189ccc572f7b4e4d5908af27840f55e091d535f 100644 (file)
@@ -6,11 +6,7 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
---          Copyright (C) 2004-2007, 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. --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
 -- 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- --
@@ -33,7 +29,9 @@
 -- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
---  Documentation of this unit is needed ???
+--  Allows an anonymous array (or array-like container) to be sorted. Generic
+--  formal Less returns the result of comparing the elements designated by the
+--  indices, and generic formal Swap exchanges the designated elements.
 
 generic
    type Index_Type is (<>);
@@ -42,5 +40,4 @@ generic
 
 procedure Ada.Containers.Generic_Anonymous_Array_Sort
   (First, Last : Index_Type'Base);
-
 pragma Pure (Ada.Containers.Generic_Anonymous_Array_Sort);
index ff7cdba1723a97b96634011b2a37a7d108384a1d..747c2a99ebf693fd8551d1ba6212bc7c98f4e5bb 100644 (file)
@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 B o d y                                  --
 --                                                                          --
---          Copyright (C) 2004-2007, Free Software Foundation, Inc.         --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
 -- 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- --
@@ -91,14 +91,11 @@ is
 
       while C /= S loop
          declare
-            Father      : constant T := C / 2;
-            Father_Elem : Element_Type renames A (To_Index (Father));
-
+            Father : constant T := C / 2;
          begin
-            if Father_Elem < Temp then           -- Lt (Father, 0)
-               A (To_Index (C)) := Father_Elem;  -- Move (Father, C)
+            if A (To_Index (Father)) < Temp then           -- Lt (Father, 0)
+               A (To_Index (C)) := A (To_Index (Father));  -- Move (Father, C)
                C := Father;
-
             else
                exit;
             end if;
@@ -117,12 +114,8 @@ begin
    end loop;
 
    while Max > 1 loop
-      declare
-         Max_Elem : Element_Type renames A (To_Index (Max));
-      begin
-         Temp := Max_Elem;         --  Move (Max, 0);
-         Max_Elem := A (A'First);  --  Move (1, Max);
-      end;
+      Temp := A (To_Index (Max));         --  Move (Max, 0);
+      A (To_Index (Max)) := A (A'First);  --  Move (1, Max);
 
       Max := Max - 1;
       Sift (1);
index e18e44fca9093a173bdf4523be85470136e29110..0b3719b5aa2b46c10498def9d62e403461130541 100644 (file)
@@ -8,10 +8,6 @@
 --                                                                          --
 --          Copyright (C) 2004-2008, 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 2,  or (at your option) any later ver- --
 -- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
---  Documentation of this unit is needed ???
+--  The indefinite ordered multiset container is similar to the indefinite
+--  ordered set, but with the difference that multiple equivalent elements are
+--  allowed. It also provides additional operations, to iterate over items that
+--  are equivalent.
 
 private with Ada.Containers.Red_Black_Trees;
 private with Ada.Finalization;
@@ -50,6 +49,8 @@ package Ada.Containers.Indefinite_Ordered_Multisets is
    pragma Remote_Types;
 
    function Equivalent_Elements (Left, Right : Element_Type) return Boolean;
+   --  Returns False if Left is less than Right, or Right is less than Left;
+   --  otherwise, it returns True.
 
    type Set is tagged private;
    pragma Preelaborable_Initialization (Set);
@@ -58,40 +59,91 @@ package Ada.Containers.Indefinite_Ordered_Multisets is
    pragma Preelaborable_Initialization (Cursor);
 
    Empty_Set : constant Set;
+   --  The default value for set objects declared without an explicit
+   --  initialization expression.
 
    No_Element : constant Cursor;
+   --  The default value for cursor objects declared without an explicit
+   --  initialization expression.
 
    function "=" (Left, Right : Set) return Boolean;
+   --  If Left denotes the same set object as Right, then equality returns
+   --  True. If the length of Left is different from the length of Right, then
+   --  it returns False. Otherwise, set equality iterates over Left and Right,
+   --  comparing the element of Left to the element of Right using the equality
+   --  operator for elements. If the elements compare False, then the iteration
+   --  terminates and set equality returns False. Otherwise, if all elements
+   --  compare True, then set equality returns True.
 
    function Equivalent_Sets (Left, Right : Set) return Boolean;
+   --  Similar to set equality, but with the difference that elements are
+   --  compared for equivalence instead of equality.
 
    function To_Set (New_Item : Element_Type) return Set;
+   --  Constructs a set object with New_Item as its single element
 
    function Length (Container : Set) return Count_Type;
+   --  Returns the total number of elements in Container
 
    function Is_Empty (Container : Set) return Boolean;
+   --  Returns True if Container.Length is 0
 
    procedure Clear (Container : in out Set);
+   --  Deletes all elements from Container
 
    function Element (Position : Cursor) return Element_Type;
+   --  If Position equals No_Element, then Constraint_Error is raised.
+   --  Otherwise, function Element returns the element designed by Position.
 
    procedure Replace_Element
      (Container : in out Set;
       Position  : Cursor;
       New_Item  : Element_Type);
+   --  If Position equals No_Element, then Constraint_Error is raised. If
+   --  Position is associated with a set different from Container, then
+   --  Program_Error is raised. If New_Item is equivalent to the element
+   --  designated by Position, then if Container is locked (element tampering
+   --  has been attempted), Program_Error is raised; otherwise, the element
+   --  designated by Position is assigned the value of New_Item. If New_Item is
+   --  not equivalent to the element designated by Position, then if the
+   --  container is busy (cursor tampering has been attempted), Program_Error
+   --  is raised; otherwise, the element designed by Position is assigned the
+   --  value of New_Item, and the node is moved to its new position (in
+   --  canonical insertion order).
 
    procedure Query_Element
      (Position : Cursor;
       Process  : not null access procedure (Element : Element_Type));
+   --  If Position equals No_Element, then Constraint_Error is
+   --  raised. Otherwise, it calls Process with the element designated by
+   --  Position as the parameter. This call locks the container, so attempts to
+   --  change the value of the element while Process is executing (to "tamper
+   --  with elements") will raise Program_Error.
 
    procedure Move (Target : in out Set; Source : in out Set);
+   --  If Target denotes the same object as Source, the operation does
+   --  nothing. If either Target or Source is busy (cursor tampering is
+   --  attempted), then it raises Program_Error. Otherwise, Target is cleared,
+   --  and the nodes from Source are moved (not copied) to Target (so Source
+   --  becomes empty).
 
    procedure Insert
      (Container : in out Set;
       New_Item  : Element_Type;
       Position  : out Cursor);
+   --  Insert adds New_Item to Container, and returns cursor Position
+   --  designating the newly inserted node. The node is inserted after any
+   --  existing elements less than or equivalent to New_Item (and before any
+   --  elements greater than New_Item). Note that the issue of where the new
+   --  node is inserted relative to equivalent elements does not arise for
+   --  unique-key containers, since in that case the insertion would simply
+   --  fail. For a multiple-key container (the case here), insertion always
+   --  succeeds, and is defined such that the new item is positioned after any
+   --  equivalent elements already in the container.
 
    procedure Insert (Container : in out Set; New_Item : Element_Type);
+   --  Inserts New_Item in Container, but does not return a cursor designating
+   --  the newly-inserted node.
 
 --  TODO: include Replace too???
 --
@@ -100,98 +152,184 @@ package Ada.Containers.Indefinite_Ordered_Multisets is
 --        New_Item  : Element_Type);
 
    procedure Exclude (Container : in out Set; Item : Element_Type);
+   --  Deletes from Container all of the elements equivalent to Item
 
    procedure Delete (Container : in out Set; Item : Element_Type);
+   --  Deletes from Container all of the elements equivalent to Item. If there
+   --  are no elements equivalent to Item, then it raises Constraint_Error.
 
    procedure Delete (Container : in out Set; Position : in out Cursor);
+   --  If Position equals No_Element, then Constraint_Error is raised. If
+   --  Position is associated with a set different from Container, then
+   --  Program_Error is raised. Otherwise, the node designated by Position is
+   --  removed from Container, and Position is set to No_Element.
 
    procedure Delete_First (Container : in out Set);
+   --  Removes the first node from Container
 
    procedure Delete_Last (Container : in out Set);
+   --  Removes the last node from Container
 
    procedure Union (Target : in out Set; Source : Set);
+   --  If Target is busy (cursor tampering is attempted), then Program_Error is
+   --  raised. Otherwise, it inserts each element of Source into Target.
+   --  Elements are inserted in the canonical order for multisets, such that
+   --  the elements from Source are inserted after equivalent elements already
+   --  in Target.
 
    function Union (Left, Right : Set) return Set;
+   --  Returns a set comprising the all elements from Left and all of the
+   --  elements from Right. The elements from Right follow the equivalent
+   --  elements from Left.
 
    function "or" (Left, Right : Set) return Set renames Union;
 
    procedure Intersection (Target : in out Set; Source : Set);
+   --  If Target denotes the same object as Source, the operation does
+   --  nothing. If Target is busy (cursor tampering is attempted),
+   --  Program_Error is raised. Otherwise, the elements in Target having no
+   --  equivalent element in Source are deleted from Target.
 
    function Intersection (Left, Right : Set) return Set;
+   --  If Left denotes the same object as Right, then the function returns a
+   --  copy of Left. Otherwise, it returns a set comprising the equivalent
+   --  elements from both Left and Right. Items are inserted in the result set
+   --  in canonical order, such that the elements from Left precede the
+   --  equivalent elements from Right.
 
    function "and" (Left, Right : Set) return Set renames Intersection;
 
    procedure Difference (Target : in out Set; Source : Set);
+   --  If Target is busy (cursor tampering is attempted), then Program_Error is
+   --  raised. Otherwise, the elements in Target that are equivalent to
+   --  elements in Source are deleted from Target.
 
    function Difference (Left, Right : Set) return Set;
+   --  Returns a set comprising the elements from Left that have no equivalent
+   --  element in Right.
 
    function "-" (Left, Right : Set) return Set renames Difference;
 
    procedure Symmetric_Difference (Target : in out Set; Source : Set);
+   --  If Target is busy, then Program_Error is raised. Otherwise, the elements
+   --  in Target equivalent to elements in Source are deleted from Target, and
+   --  the elements in Source not equivalent to elements in Target are inserted
+   --  into Target.
 
    function Symmetric_Difference (Left, Right : Set) return Set;
+   --  Returns a set comprising the union of the elements from Target having no
+   --  equivalent in Source, and the elements of Source having no equivalent in
+   --  Target.
 
    function "xor" (Left, Right : Set) return Set renames Symmetric_Difference;
 
    function Overlap (Left, Right : Set) return Boolean;
+   --  Returns True if Left contains an element equivalent to an element of
+   --  Right.
 
    function Is_Subset (Subset : Set; Of_Set : Set) return Boolean;
+   --  Returns True if every element in Subset has an equivalent element in
+   --  Of_Set.
 
    function First (Container : Set) return Cursor;
+   --  If Container is empty, the function returns No_Element. Otherwise, it
+   --  returns a cursor designating the smallest element.
 
    function First_Element (Container : Set) return Element_Type;
+   --  Equivalent to Element (First (Container))
 
    function Last (Container : Set) return Cursor;
+   --  If Container is empty, the function returns No_Element. Otherwise, it
+   --  returns a cursor designating the largest element.
 
    function Last_Element (Container : Set) return Element_Type;
+   --  Equivalent to Element (Last (Container))
 
    function Next (Position : Cursor) return Cursor;
+   --  If Position equals No_Element or Last (Container), the function returns
+   --  No_Element. Otherwise, it returns a cursor designating the node that
+   --  immediately follows (as per the insertion order) the node designated by
+   --  Position.
 
    procedure Next (Position : in out Cursor);
+   --  Equivalent to Position := Next (Position)
 
    function Previous (Position : Cursor) return Cursor;
+   --  If Position equals No_Element or First (Container), the function returns
+   --  No_Element. Otherwise, it returns a cursor designating the node that
+   --  immediately precedes (as per the insertion order) the node designated by
+   --  Position.
 
    procedure Previous (Position : in out Cursor);
+   --  Equivalent to Position := Previous (Position)
 
    function Find (Container : Set; Item : Element_Type) return Cursor;
+   --  Returns a cursor designating the first element in Container equivalent
+   --  to Item. If there is no equivalent element, it returns No_Element.
 
    function Floor (Container : Set; Item : Element_Type) return Cursor;
+   --  If Container is empty, the function returns No_Element. If Item is
+   --  equivalent to elements in Container, it returns a cursor designating the
+   --  first equivalent element. Otherwise, it returns a cursor designating the
+   --  largest element less than Item, or No_Element if all elements are
+   --  greater than Item.
 
    function Ceiling (Container : Set; Item : Element_Type) return Cursor;
+   --  If Container is empty, the function returns No_Element. If Item is
+   --  equivalent to elements of Container, it returns a cursor designating the
+   --  last equivalent element. Otherwise, it returns a cursor designating the
+   --  smallest element greater than Item, or No_Element if all elements are
+   --  less than Item.
 
    function Contains (Container : Set; Item : Element_Type) return Boolean;
+   --  Equivalent to Container.Find (Item) /= No_Element
 
    function Has_Element (Position : Cursor) return Boolean;
+   --  Equivalent to Position /= No_Element
 
    function "<" (Left, Right : Cursor) return Boolean;
+   --  Equivalent to Element (Left) < Element (Right)
 
    function ">" (Left, Right : Cursor) return Boolean;
+   --  Equivalent to Element (Right) < Element (Left)
 
    function "<" (Left : Cursor; Right : Element_Type) return Boolean;
+   --  Equivalent to Element (Left) < Right
 
    function ">" (Left : Cursor; Right : Element_Type) return Boolean;
+   --  Equivalent to Right < Element (Left)
 
    function "<" (Left : Element_Type; Right : Cursor) return Boolean;
+   --  Equivalent to Left < Element (Right)
 
    function ">" (Left : Element_Type; Right : Cursor) return Boolean;
+   --  Equivalent to Element (Right) < Left
 
    procedure Iterate
      (Container : Set;
       Process   : not null access procedure (Position : Cursor));
+   --  Calls Process with a cursor designating each element of Container, in
+   --  order from Container.First to Container.Last.
 
    procedure Reverse_Iterate
      (Container : Set;
       Process   : not null access procedure (Position : Cursor));
+   --  Calls Process with a cursor designating each element of Container, in
+   --  order from Container.Last to Container.First.
 
    procedure Iterate
      (Container : Set;
       Item      : Element_Type;
       Process   : not null access procedure (Position : Cursor));
+   --  Call Process with a cursor designating each element equivalent to Item,
+   --  in order from Container.Floor (Item) to Container.Ceiling (Item).
 
    procedure Reverse_Iterate
      (Container : Set;
       Item      : Element_Type;
       Process   : not null access procedure (Position : Cursor));
+   --  Call Process with a cursor designating each element equivalent to Item,
+   --  in order from Container.Ceiling (Item) to Container.Floor (Item).
 
    generic
       type Key_Type (<>) is private;
@@ -203,38 +341,75 @@ package Ada.Containers.Indefinite_Ordered_Multisets is
    package Generic_Keys is
 
       function Equivalent_Keys (Left, Right : Key_Type) return Boolean;
+      --  Returns False if Left is less than Right, or Right is less than Left;
+      --  otherwise, it returns True.
 
       function Key (Position : Cursor) return Key_Type;
+      --  Equivalent to Key (Element (Position))
 
       function Element (Container : Set; Key : Key_Type) return Element_Type;
+      --  Equivalent to Element (Find (Container, Key))
 
       procedure Exclude (Container : in out Set; Key : Key_Type);
+      --  Deletes from Container any elements whose key is equivalent to Key
 
       procedure Delete (Container : in out Set; Key : Key_Type);
+      --  Deletes from Container any elements whose key is equivalent to
+      --  Key. If there are no such elements, then it raises Constraint_Error.
 
       function Find (Container : Set; Key : Key_Type) return Cursor;
+      --  Returns a cursor designating the first element in Container whose key
+      --  is equivalent to Key. If there is no equivalent element, it returns
+      --  No_Element.
 
       function Floor (Container : Set; Key : Key_Type) return Cursor;
+      --  If Container is empty, the function returns No_Element. If Item is
+      --  equivalent to the keys of elements in Container, it returns a cursor
+      --  designating the first such element. Otherwise, it returns a cursor
+      --  designating the largest element whose key is less than Item, or
+      --  No_Element if all keys are greater than Item.
 
       function Ceiling (Container : Set; Key : Key_Type) return Cursor;
+      --  If Container is empty, the function returns No_Element. If Item is
+      --  equivalent to the keys of elements of Container, it returns a cursor
+      --  designating the last such element. Otherwise, it returns a cursor
+      --  designating the smallest element whose key is greater than Item, or
+      --  No_Element if all keys are less than Item.
 
       function Contains (Container : Set; Key : Key_Type) return Boolean;
+      --  Equivalent to Find (Container, Key) /= No_Element
 
-      procedure Update_Element
+      procedure Update_Element  -- Update_Element_Preserving_Key ???
         (Container : in out Set;
          Position  : Cursor;
          Process   : not null access
                        procedure (Element : in out Element_Type));
+      --  If Position equals No_Element, then Constraint_Error is raised. If
+      --  Position is associated with a set object different from Container,
+      --  then Program_Error is raised. Otherwise, it makes a copy of the key
+      --  of the element designated by Position, and then calls Process with
+      --  the element as the parameter. Update_Element then compares the key
+      --  value obtained before calling Process to the key value obtained from
+      --  the element after calling Process. If the keys are equivalent then
+      --  the operation terminates. If Container is busy (cursor tampering has
+      --  been attempted), then Program_Error is raised. Otherwise, the node
+      --  is moved to its new position (in canonical order).
 
       procedure Iterate
         (Container : Set;
          Key       : Key_Type;
          Process   : not null access procedure (Position : Cursor));
+      --  Call Process with a cursor designating each element equivalent to
+      --  Key, in order from Floor (Container, Key) to
+      --  Ceiling (Container, Key).
 
       procedure Reverse_Iterate
         (Container : Set;
          Key       : Key_Type;
          Process   : not null access procedure (Position : Cursor));
+      --  Call Process with a cursor designating each element equivalent to
+      --  Key, in order from Ceiling (Container, Key) to
+      --  Floor (Container, Key).
 
    end Generic_Keys;
 
index 5cbfa0915af3bbc117dc7af7ca4e196be8f09d70..6175c2f3daa7911d3f20fedc0d5efa6b8472d375 100644 (file)
@@ -6,7 +6,7 @@
 --                                                                          --
 --                                 B o d y                                  --
 --                                                                          --
---          Copyright (C) 2004-2007, Free Software Foundation, Inc.         --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
 -- 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- --
@@ -2077,14 +2077,10 @@ package body Ada.Containers.Vectors is
       end if;
 
       declare
-         EI : Element_Type renames Container.Elements.EA (I);
-         EJ : Element_Type renames Container.Elements.EA (J);
-
-         EI_Copy : constant Element_Type := EI;
-
+         EI_Copy : constant Element_Type := Container.Elements.EA (I);
       begin
-         EI := EJ;
-         EJ := EI_Copy;
+         Container.Elements.EA (I) := Container.Elements.EA (J);
+         Container.Elements.EA (J) := EI_Copy;
       end;
    end Swap;
 
index 05d71df4b0ea8bcf1d1ad92c5f51486a9405b565..b1a6d1a3f8b837aea0ae772e6f2910ab8c8f2d58 100644 (file)
@@ -8,10 +8,6 @@
 --                                                                          --
 --          Copyright (C) 2004-2008, 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 2,  or (at your option) any later ver- --
@@ -33,7 +29,9 @@
 -- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
---  Documentation is needed for this unit ???
+--  The ordered multiset container is similar to the ordered set, but with the
+--  difference that multiple equivalent elements are allowed. It also provides
+--  additional operations, to iterate over items that are equivalent.
 
 private with Ada.Containers.Red_Black_Trees;
 private with Ada.Finalization;
@@ -50,6 +48,8 @@ package Ada.Containers.Ordered_Multisets is
    pragma Remote_Types;
 
    function Equivalent_Elements (Left, Right : Element_Type) return Boolean;
+   --  Returns False if Left is less than Right, or Right is less than Left;
+   --  otherwise, it returns True.
 
    type Set is tagged private;
    pragma Preelaborable_Initialization (Set);
@@ -58,42 +58,93 @@ package Ada.Containers.Ordered_Multisets is
    pragma Preelaborable_Initialization (Cursor);
 
    Empty_Set : constant Set;
+   --  The default value for set objects declared without an explicit
+   --  initialization expression.
 
    No_Element : constant Cursor;
+   --  The default value for cursor objects declared without an explicit
+   --  initialization expression.
 
    function "=" (Left, Right : Set) return Boolean;
+   --  If Left denotes the same set object as Right, then equality returns
+   --  True. If the length of Left is different from the length of Right, then
+   --  it returns False. Otherwise, set equality iterates over Left and Right,
+   --  comparing the element of Left to the element of Right using the equality
+   --  operator for elements. If the elements compare False, then the iteration
+   --  terminates and set equality returns False. Otherwise, if all elements
+   --  compare True, then set equality returns True.
 
    function Equivalent_Sets (Left, Right : Set) return Boolean;
+   --  Similar to set equality, but with the difference that elements are
+   --  compared for equivalence instead of equality.
 
    function To_Set (New_Item : Element_Type) return Set;
+   --  Constructs a set object with New_Item as its single element
 
    function Length (Container : Set) return Count_Type;
+   --  Returns the total number of elements in Container
 
    function Is_Empty (Container : Set) return Boolean;
+   --  Returns True if Container.Length is 0
 
    procedure Clear (Container : in out Set);
+   --  Deletes all elements from Container
 
    function Element (Position : Cursor) return Element_Type;
+   --  If Position equals No_Element, then Constraint_Error is raised.
+   --  Otherwise, function Element returns the element designed by Position.
 
    procedure Replace_Element
      (Container : in out Set;
       Position  : Cursor;
       New_Item  : Element_Type);
+   --  If Position equals No_Element, then Constraint_Error is raised. If
+   --  Position is associated with a set different from Container, then
+   --  Program_Error is raised. If New_Item is equivalent to the element
+   --  designated by Position, then if Container is locked (element tampering
+   --  has been attempted), Program_Error is raised; otherwise, the element
+   --  designated by Position is assigned the value of New_Item. If New_Item is
+   --  not equivalent to the element designated by Position, then if the
+   --  container is busy (cursor tampering has been attempted), Program_Error
+   --  is raised; otherwise, the element designed by Position is assigned the
+   --  value of New_Item, and the node is moved to its new position (in
+   --  canonical insertion order).
 
    procedure Query_Element
      (Position : Cursor;
       Process  : not null access procedure (Element : Element_Type));
+   --  If Position equals No_Element, then Constraint_Error is
+   --  raised. Otherwise, it calls Process with the element designated by
+   --  Position as the parameter. This call locks the container, so attempts to
+   --  change the value of the element while Process is executing (to "tamper
+   --  with elements") will raise Program_Error.
 
    procedure Move (Target : in out Set; Source : in out Set);
+   --  If Target denotes the same object as Source, the operation does
+   --  nothing. If either Target or Source is busy (cursor tampering is
+   --  attempted), then it raises Program_Error. Otherwise, Target is cleared,
+   --  and the nodes from Source are moved (not copied) to Target (so Source
+   --  becomes empty).
 
    procedure Insert
      (Container : in out Set;
       New_Item  : Element_Type;
       Position  : out Cursor);
+   --  Insert adds New_Item to Container, and returns cursor Position
+   --  designating the newly inserted node. The node is inserted after any
+   --  existing elements less than or equivalent to New_Item (and before any
+   --  elements greater than New_Item). Note that the issue of where the new
+   --  node is inserted relative to equivalent elements does not arise for
+   --  unique-key containers, since in that case the insertion would simply
+   --  fail. For a multiple-key container (the case here), insertion always
+   --  succeeds, and is defined such that the new item is positioned after any
+   --  equivalent elements already in the container.
 
    procedure Insert
      (Container : in out Set;
       New_Item  : Element_Type);
+   --  Inserts New_Item in Container, but does not return a cursor designating
+   --  the newly-inserted node.
 
 --  TODO: include Replace too???
 --
@@ -104,102 +155,188 @@ package Ada.Containers.Ordered_Multisets is
    procedure Exclude
      (Container : in out Set;
       Item      : Element_Type);
+   --  Deletes from Container all of the elements equivalent to Item
 
    procedure Delete
      (Container : in out Set;
       Item      : Element_Type);
+   --  Deletes from Container all of the elements equivalent to Item. If there
+   --  are no elements equivalent to Item, then it raises Constraint_Error.
 
    procedure Delete
      (Container : in out Set;
       Position  : in out Cursor);
+   --  If Position equals No_Element, then Constraint_Error is raised. If
+   --  Position is associated with a set different from Container, then
+   --  Program_Error is raised. Otherwise, the node designated by Position is
+   --  removed from Container, and Position is set to No_Element.
 
    procedure Delete_First (Container : in out Set);
+   --  Removes the first node from Container
 
    procedure Delete_Last (Container : in out Set);
+   --  Removes the last node from Container
 
    procedure Union (Target : in out Set; Source : Set);
+   --  If Target is busy (cursor tampering is attempted), the Program_Error is
+   --  raised. Otherwise, it inserts each element of Source into
+   --  Target. Elements are inserted in the canonical order for multisets, such
+   --  that the elements from Source are inserted after equivalent elements
+   --  already in Target.
 
    function Union (Left, Right : Set) return Set;
+   --  Returns a set comprising the all elements from Left and all of the
+   --  elements from Right. The elements from Right follow the equivalent
+   --  elements from Left.
 
    function "or" (Left, Right : Set) return Set renames Union;
 
    procedure Intersection (Target : in out Set; Source : Set);
+   --  If Target denotes the same object as Source, the operation does
+   --  nothing. If Target is busy (cursor tampering is attempted),
+   --  Program_Error is raised. Otherwise, the elements in Target having no
+   --  equivalent element in Source are deleted from Target.
 
    function Intersection (Left, Right : Set) return Set;
+   --  If Left denotes the same object as Right, then the function returns a
+   --  copy of Left. Otherwise, it returns a set comprising the equivalent
+   --  elements from both Left and Right. Items are inserted in the result set
+   --  in canonical order, such that the elements from Left precede the
+   --  equivalent elements from Right.
 
    function "and" (Left, Right : Set) return Set renames Intersection;
 
    procedure Difference (Target : in out Set; Source : Set);
+   --  If Target is busy (cursor tampering is attempted), then Program_Error is
+   --  raised. Otherwise, the elements in Target that are equivalent to
+   --  elements in Source are deleted from Target.
 
    function Difference (Left, Right : Set) return Set;
+   --  Returns a set comprising the elements from Left that have no equivalent
+   --  element in Right.
 
    function "-" (Left, Right : Set) return Set renames Difference;
 
    procedure Symmetric_Difference (Target : in out Set; Source : Set);
+   --  If Target is busy, then Program_Error is raised. Otherwise, the elements
+   --  in Target equivalent to elements in Source are deleted from Target, and
+   --  the elements in Source not equivalent to elements in Target are inserted
+   --  into Target.
 
    function Symmetric_Difference (Left, Right : Set) return Set;
+   --  Returns a set comprising the union of the elements from Target having no
+   --  equivalent in Source, and the elements of Source having no equivalent in
+   --  Target.
 
    function "xor" (Left, Right : Set) return Set renames Symmetric_Difference;
 
    function Overlap (Left, Right : Set) return Boolean;
+   --  Returns True if Left contains an element equivalent to an element of
+   --  Right.
 
    function Is_Subset (Subset : Set; Of_Set : Set) return Boolean;
+   --  Returns True if every element in Subset has an equivalent element in
+   --  Of_Set.
 
    function First (Container : Set) return Cursor;
+   --  If Container is empty, the function returns No_Element. Otherwise, it
+   --  returns a cursor designating the smallest element.
 
    function First_Element (Container : Set) return Element_Type;
+   --  Equivalent to Element (First (Container))
 
    function Last (Container : Set) return Cursor;
+   --  If Container is empty, the function returns No_Element. Otherwise, it
+   --  returns a cursor designating the largest element.
 
    function Last_Element (Container : Set) return Element_Type;
+   --  Equivalent to Element (Last (Container))
 
    function Next (Position : Cursor) return Cursor;
+   --  If Position equals No_Element or Last (Container), the function returns
+   --  No_Element. Otherwise, it returns a cursor designating the node that
+   --  immediately follows (as per the insertion order) the node designated by
+   --  Position.
 
    procedure Next (Position : in out Cursor);
+   --  Equivalent to Position := Next (Position)
 
    function Previous (Position : Cursor) return Cursor;
+   --  If Position equals No_Element or First (Container), the function returns
+   --  No_Element. Otherwise, it returns a cursor designating the node that
+   --  immediately precedes (as per the insertion order) the node designated by
+   --  Position.
 
    procedure Previous (Position : in out Cursor);
+   --  Equivalent to Position := Previous (Position)
 
    function Find (Container : Set; Item : Element_Type) return Cursor;
+   --  Returns a cursor designating the first element in Container equivalent
+   --  to Item. If there is no equivalent element, it returns No_Element.
 
    function Floor (Container : Set; Item : Element_Type) return Cursor;
+   --  If Container is empty, the function returns No_Element. If Item is
+   --  equivalent to elements in Container, it returns a cursor designating the
+   --  first equivalent element. Otherwise, it returns a cursor designating the
+   --  largest element less than Item, or No_Element if all elements are
+   --  greater than Item.
 
    function Ceiling (Container : Set; Item : Element_Type) return Cursor;
+   --  If Container is empty, the function returns No_Element. If Item is
+   --  equivalent to elements of Container, it returns a cursor designating the
+   --  last equivalent element. Otherwise, it returns a cursor designating the
+   --  smallest element greater than Item, or No_Element if all elements are
+   --  less than Item.
 
    function Contains (Container : Set; Item : Element_Type) return Boolean;
+   --  Equivalent to Container.Find (Item) /= No_Element
 
    function Has_Element (Position : Cursor) return Boolean;
+   --  Equivalent to Position /= No_Element
 
    function "<" (Left, Right : Cursor) return Boolean;
+   --  Equivalent to Element (Left) < Element (Right)
 
    function ">" (Left, Right : Cursor) return Boolean;
+   --  Equivalent to Element (Right) < Element (Left)
 
    function "<" (Left : Cursor; Right : Element_Type) return Boolean;
+   --  Equivalent to Element (Left) < Right
 
    function ">" (Left : Cursor; Right : Element_Type) return Boolean;
+   --  Equivalent to Right < Element (Left)
 
    function "<" (Left : Element_Type; Right : Cursor) return Boolean;
+   --  Equivalent to Left < Element (Right)
 
    function ">" (Left : Element_Type; Right : Cursor) return Boolean;
+   --  Equivalent to Element (Right) < Left
 
    procedure Iterate
      (Container : Set;
       Process   : not null access procedure (Position : Cursor));
+   --  Calls Process with a cursor designating each element of Container, in
+   --  order from Container.First to Container.Last.
 
    procedure Reverse_Iterate
      (Container : Set;
       Process   : not null access procedure (Position : Cursor));
+   --  Calls Process with a cursor designating each element of Container, in
+   --  order from Container.Last to Container.First.
 
    procedure Iterate
      (Container : Set;
       Item      : Element_Type;
       Process   : not null access procedure (Position : Cursor));
+   --  Call Process with a cursor designating each element equivalent to Item,
+   --  in order from Container.Floor (Item) to Container.Ceiling (Item).
 
    procedure Reverse_Iterate
      (Container : Set;
       Item      : Element_Type;
       Process   : not null access procedure (Position : Cursor));
+   --  Call Process with a cursor designating each element equivalent to Item,
+   --  in order from Container.Ceiling (Item) to Container.Floor (Item).
 
    generic
       type Key_Type (<>) is private;
@@ -211,38 +348,75 @@ package Ada.Containers.Ordered_Multisets is
    package Generic_Keys is
 
       function Equivalent_Keys (Left, Right : Key_Type) return Boolean;
+      --  Returns False if Left is less than Right, or Right is less than Left;
+      --  otherwise, it returns True.
 
       function Key (Position : Cursor) return Key_Type;
+      --  Equivalent to Key (Element (Position))
 
       function Element (Container : Set; Key : Key_Type) return Element_Type;
+      --  Equivalent to Element (Find (Container, Key))
 
       procedure Exclude (Container : in out Set; Key : Key_Type);
+      --  Deletes from Container any elements whose key is equivalent to Key
 
       procedure Delete (Container : in out Set; Key : Key_Type);
+      --  Deletes from Container any elements whose key is equivalent to
+      --  Key. If there are no such elements, then it raises Constraint_Error.
 
       function Find (Container : Set; Key : Key_Type) return Cursor;
+      --  Returns a cursor designating the first element in Container whose key
+      --  is equivalent to Key. If there is no equivalent element, it returns
+      --  No_Element.
 
       function Floor (Container : Set; Key : Key_Type) return Cursor;
+      --  If Container is empty, the function returns No_Element. If Item is
+      --  equivalent to the keys of elements in Container, it returns a cursor
+      --  designating the first such element. Otherwise, it returns a cursor
+      --  designating the largest element whose key is less than Item, or
+      --  No_Element if all keys are greater than Item.
 
       function Ceiling (Container : Set; Key : Key_Type) return Cursor;
+      --  If Container is empty, the function returns No_Element. If Item is
+      --  equivalent to the keys of elements of Container, it returns a cursor
+      --  designating the last such element. Otherwise, it returns a cursor
+      --  designating the smallest element whose key is greater than Item, or
+      --  No_Element if all keys are less than Item.
 
       function Contains (Container : Set; Key : Key_Type) return Boolean;
+      --  Equivalent to Find (Container, Key) /= No_Element
 
-      procedure Update_Element
+      procedure Update_Element  -- Update_Element_Preserving_Key ???
         (Container : in out Set;
          Position  : Cursor;
          Process   : not null access
                        procedure (Element : in out Element_Type));
+      --  If Position equals No_Element, then Constraint_Error is raised. If
+      --  Position is associated with a set object different from Container,
+      --  then Program_Error is raised. Otherwise, it makes a copy of the key
+      --  of the element designated by Position, and then calls Process with
+      --  the element as the parameter. Update_Element then compares the key
+      --  value obtained before calling Process to the key value obtained from
+      --  the element after calling Process. If the keys are equivalent then
+      --  the operation terminates. If Container is busy (cursor tampering has
+      --  been attempted), then Program_Error is raised. Otherwise, the node
+      --  is moved to its new position (in canonical order).
 
       procedure Iterate
         (Container : Set;
          Key       : Key_Type;
          Process   : not null access procedure (Position : Cursor));
+      --  Call Process with a cursor designating each element equivalent to
+      --  Key, in order from Floor (Container, Key) to
+      --  Ceiling (Container, Key).
 
       procedure Reverse_Iterate
         (Container : Set;
          Key       : Key_Type;
          Process   : not null access procedure (Position : Cursor));
+      --  Call Process with a cursor designating each element equivalent to
+      --  Key, in order from Ceiling (Container, Key) to
+      --  Floor (Container, Key).
 
    end Generic_Keys;
 
index 00f17eb689077749731ba9b6e2907595a27b7f9c..a97f354d43e1f40e0fca1662f1e1f89509cb411a 100644 (file)
@@ -6,11 +6,7 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
---          Copyright (C) 2004-2007, 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. --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
 -- 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- --
 -- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
---  Documentation required for this unit ???
+--  The doubly-linked list container provides constant-time insertion and
+--  deletion at all positions, and allows iteration in both the forward and
+--  reverse directions. This list form allocates storage for all nodes
+--  statically (there is no dynamic allocation), and a discriminant is used to
+--  specify the capacity. This container is also "restricted", meaning that
+--  even though it does raise exceptions (as described below), it does not use
+--  internal exception handlers. No state changes are made that would need to
+--  be reverted (in the event of an exception), and so as a consequence, this
+--  container cannot detect tampering (of cursors or elements).
 
 generic
    type Element_Type is private;
@@ -51,40 +55,81 @@ package Ada.Containers.Restricted_Doubly_Linked_Lists is
    pragma Preelaborable_Initialization (Cursor);
 
    Empty_List : constant List;
+   --  The default value for list objects declared without an explicit
+   --  initialization expression.
 
    No_Element : constant Cursor;
+   --  The default value for cursor objects declared without an explicit
+   --  initialization expression.
 
    function "=" (Left, Right : List) return Boolean;
+   --  If Left denotes the same list object as Right, then equality returns
+   --  True. If the length of Left is different from the length of Right, then
+   --  it returns False. Otherwise, list equality iterates over Left and Right,
+   --  comparing the element of Left to the corresponding element of Right
+   --  using the generic actual equality operator for elements. If the elements
+   --  compare False, then the iteration terminates and list equality returns
+   --  False. Otherwise, if all elements return True, then list equality
+   --  returns True.
 
    procedure Assign (Target : in out List; Source : List);
+   --  If Target denotes the same list object as Source, the operation does
+   --  nothing. If Target.Capacity is less than Source.Length, then it raises
+   --  Constraint_Error. Otherwise, it clears Target, and then inserts each
+   --  element of Source into Target.
 
    function Length (Container : List) return Count_Type;
+   --  Returns the total number of (active) elements in Container
 
    function Is_Empty (Container : List) return Boolean;
+   --  Returns True if Container.Length is 0
 
    procedure Clear (Container : in out List);
+   --  Deletes all elements from Container. Note that this is a bounded
+   --  container and so the element is not "deallocated" in the same sense that
+   --  an unbounded form would deallocate the element. Rather, the node is
+   --  relinked off of the active part of the list and onto the inactive part
+   --  of the list (the storage from which new elements are "allocated").
 
    function Element (Position : Cursor) return Element_Type;
+   --  If Position equals No_Element, then Constraint_Error is raised.
+   --  Otherwise, function Element returns the element designed by Position.
 
    procedure Replace_Element
      (Container : in out List;
       Position  : Cursor;
       New_Item  : Element_Type);
+   --  If Position equals No_Element, then Constraint_Error is raised. If
+   --  Position is associated with a list object different from Container,
+   --  Program_Error is raised. Otherwise, the element designated by Position
+   --  is assigned the value New_Item.
 
    procedure Query_Element
      (Position : Cursor;
       Process  : not null access procedure (Element : Element_Type));
+   --  If Position equals No_Element, then Constraint_Error is raised.
+   --  Otherwise, it calls Process with (a constant view of) the element
+   --  designated by Position as the parameter.
 
    procedure Update_Element
      (Container : in out List;
       Position  : Cursor;
       Process   : not null access procedure (Element : in out Element_Type));
+   --  If Position equals No_Element, then Constraint_Error is raised.
+   --  Otherwise, it calls Process with (a variable view of) the element
+   --  designated by Position as the parameter.
 
    procedure Insert
      (Container : in out List;
       Before    : Cursor;
       New_Item  : Element_Type;
       Count     : Count_Type := 1);
+   --  Inserts Count new elements, all with the value New_Item, into Container,
+   --  immediately prior to the position specified by Before. If Before has the
+   --  value No_Element, this is interpreted to mean that the elements are
+   --  appended to the list. If Before is associated with a list object
+   --  different from Container, then Program_Error is raised. If there are
+   --  fewer than Count nodes available, then Constraint_Error is raised.
 
    procedure Insert
      (Container : in out List;
@@ -92,98 +137,171 @@ package Ada.Containers.Restricted_Doubly_Linked_Lists is
       New_Item  : Element_Type;
       Position  : out Cursor;
       Count     : Count_Type := 1);
+   --  Inserts elements into Container as described above, but with the
+   --  difference that cursor Position is returned, which designates the first
+   --  of the new elements inserted. If Count is 0, Position returns the value
+   --  Before.
 
    procedure Insert
      (Container : in out List;
       Before    : Cursor;
       Position  : out Cursor;
       Count     : Count_Type := 1);
+   --  Inserts elements in Container as described above, but with the
+   --  difference that the new elements are initialized to the default value
+   --  for objects of type Element_Type.
 
    procedure Prepend
      (Container : in out List;
       New_Item  : Element_Type;
       Count     : Count_Type := 1);
+   --  Inserts Count elements, all having the value New_Item, prior to the
+   --  first element of Container.
 
    procedure Append
      (Container : in out List;
       New_Item  : Element_Type;
       Count     : Count_Type := 1);
+   --  Inserts Count elements, all having the value New_Item, following the
+   --  last element of Container.
 
    procedure Delete
      (Container : in out List;
       Position  : in out Cursor;
       Count     : Count_Type := 1);
+   --  If Position equals No_Element, Constraint_Error is raised. If Position
+   --  is associated with a list object different from Container, then
+   --  Program_Error is raised. Otherwise, the Count nodes starting from
+   --  Position are removed from Container ("removed" meaning that the nodes
+   --  are unlinked from the active nodes of the list and relinked to inactive
+   --  storage). On return, Position is set to No_Element.
 
    procedure Delete_First
      (Container : in out List;
       Count     : Count_Type := 1);
+   --  Removes the first Count nodes from Container
 
    procedure Delete_Last
      (Container : in out List;
       Count     : Count_Type := 1);
+   --  Removes the last Count nodes from Container
 
    procedure Reverse_Elements (Container : in out List);
+   --  Relinks the nodes in reverse order
 
    procedure Swap
      (Container : in out List;
       I, J      : Cursor);
+   --  If I or J equals No_Element, then Constraint_Error is raised. If I or J
+   --  is associated with a list object different from Container, then
+   --  Program_Error is raised. Otherwise, Swap exchanges (copies) the values
+   --  of the elements (on the nodes) designated by I and J.
 
    procedure Swap_Links
      (Container : in out List;
       I, J      : Cursor);
+   --  If I or J equals No_Element, then Constraint_Error is raised. If I or J
+   --  is associated with a list object different from Container, then
+   --  Program_Error is raised. Otherwise, Swap exchanges (relinks) the nodes
+   --  designated by I and J.
 
    procedure Splice
      (Container : in out List;
       Before    : Cursor;
       Position  : in out Cursor);
+   --  If Before is associated with a list object different from Container,
+   --  then Program_Error is raised. If Position equals No_element, then
+   --  Constraint_Error is raised; if it associated with a list object
+   --  different from Container, then Program_Error is raised. Otherwise, the
+   --  node designated by Position is relinked immediately prior to Before. If
+   --  Before equals No_Element, this is interpreted to mean to move the node
+   --  designed by Position to the last end of the list.
 
    function First (Container : List) return Cursor;
+   --  If Container is empty, the function returns No_Element. Otherwise, it
+   --  returns a cursor designating the first element.
 
    function First_Element (Container : List) return Element_Type;
+   --  Equivalent to Element (First (Container))
 
    function Last (Container : List) return Cursor;
+   --  If Container is empty, the function returns No_Element. Otherwise, it
+   --  returns a cursor designating the last element.
 
    function Last_Element (Container : List) return Element_Type;
+   --  Equivalent to Element (Last (Container))
 
    function Next (Position : Cursor) return Cursor;
+   --  If Position equals No_Element or Last (Container), the function returns
+   --  No_Element. Otherwise, it returns a cursor designating the node that
+   --  immediately follows the node designated by Position.
 
    procedure Next (Position : in out Cursor);
+   --  Equivalent to Position := Next (Position)
 
    function Previous (Position : Cursor) return Cursor;
+   --  If Position equals No_Element or First (Container), the function returns
+   --  No_Element. Otherwise, it returns a cursor designating the node that
+   --  immediately precedes the node designated by Position.
 
    procedure Previous (Position : in out Cursor);
+   --  Equivalent to Position := Previous (Position)
 
    function Find
      (Container : List;
       Item      : Element_Type;
       Position  : Cursor := No_Element) return Cursor;
+   --  Searches for the node whose element is equal to Item, starting from
+   --  Position and continuing to the last end of the list. If Position equals
+   --  No_Element, the seach starts from the first node. If Position is
+   --  associated with a list object different from Container, then
+   --  Program_Error is raised. If no node is found having an element equal to
+   --  Item, then Find returns No_Element.
 
    function Reverse_Find
      (Container : List;
       Item      : Element_Type;
       Position  : Cursor := No_Element) return Cursor;
+   --  Searches in reverse for the node whose element is equal to Item,
+   --  starting from Position and continuing to the first end of the list. If
+   --  Position equals No_Element, the seach starts from the last node. If
+   --  Position is associated with a list object different from Container, then
+   --  Program_Error is raised. If no node is found having an element equal to
+   --  Item, then Reverse_Find returns No_Element.
 
    function Contains
      (Container : List;
       Item      : Element_Type) return Boolean;
+   --  Equivalent to Container.Find (Item) /= No_Element
 
    function Has_Element (Position : Cursor) return Boolean;
+   --  Equivalent to Position /= No_Element
 
    procedure Iterate
      (Container : List;
       Process   : not null access procedure (Position : Cursor));
+   --  Calls Process with a cursor designating each element of Container, in
+   --  order from Container.First to Container.Last.
 
    procedure Reverse_Iterate
      (Container : List;
       Process   : not null access procedure (Position : Cursor));
+   --  Calls Process with a cursor designating each element of Container, in
+   --  order from Container.Last to Container.First.
 
    generic
       with function "<" (Left, Right : Element_Type) return Boolean is <>;
    package Generic_Sorting is
 
       function Is_Sorted (Container : List) return Boolean;
+      --  Returns False if there exists an element which is less than its
+      --  predecessor.
 
       procedure Sort (Container : in out List);
+      --  Sorts the elements of Container (by relinking nodes), according to
+      --  the order specified by the generic formal less-than operator, such
+      --  that smaller elements are first in the list. The sort is stable,
+      --  meaning that the relative order of elements is preserved.
 
    end Generic_Sorting;
 
index 38f2ef04f57fa84457c671b1e522ea1da39546ab..9c2dfc3319fa35bfdc5dc5fc27cd212353548766 100644 (file)
@@ -6,14 +6,35 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
--- This specification is derived from the Ada Reference Manual for use with --
--- GNAT.  In accordance with the copyright of that document, you can freely --
--- copy and modify this specification,  provided that if you redistribute a --
--- modified version,  any changes that you have made are clearly indicated. --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
+-- 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 2,  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.  See the GNU General Public License --
+-- for  more details.  You should have  received  a copy of the GNU General --
+-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
+-- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
+-- Boston, MA 02110-1301, USA.                                              --
+--                                                                          --
+-- As a special exception,  if other files  instantiate  generics from this --
+-- unit, or you link  this unit with other files  to produce an executable, --
+-- this  unit  does not  by itself cause  the resulting  executable  to  be --
+-- covered  by the  GNU  General  Public  License.  This exception does not --
+-- however invalidate  any other reasons why  the executable file  might be --
+-- covered by the  GNU Public License.                                      --
+--                                                                          --
+-- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
 function Ada.Strings.Equal_Case_Insensitive
   (Left, Right : String) return Boolean;
-
 pragma Pure (Ada.Strings.Equal_Case_Insensitive);
+--  Performs a case-insensitive equality test of Left and Right. This is
+--  useful as the generic actual equivalence operation (Equivalent_Keys)
+--  when instantiating a hashed container package with type String as the
+--  key. It is also useful as the generic actual equality operator when
+--  instantiating a container package with type String as the element,
+--  allowing case-insensitive container equality tests.
index c7263b602fed353a42667631fd911bfb167f0d35..45f4ab340692afcd8e97fb9517b311b70df3aa26 100644 (file)
@@ -6,16 +6,34 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
--- This specification is derived from the Ada Reference Manual for use with --
--- GNAT.  In accordance with the copyright of that document, you can freely --
--- copy and modify this specification,  provided that if you redistribute a --
--- modified version,  any changes that you have made are clearly indicated. --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
+-- 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 2,  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.  See the GNU General Public License --
+-- for  more details.  You should have  received  a copy of the GNU General --
+-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
+-- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
+-- Boston, MA 02110-1301, USA.                                              --
+--                                                                          --
+-- As a special exception,  if other files  instantiate  generics from this --
+-- unit, or you link  this unit with other files  to produce an executable, --
+-- this  unit  does not  by itself cause  the resulting  executable  to  be --
+-- covered  by the  GNU  General  Public  License.  This exception does not --
+-- however invalidate  any other reasons why  the executable file  might be --
+-- covered by the  GNU Public License.                                      --
+--                                                                          --
+-- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
 with Ada.Containers;
 
 function Ada.Strings.Hash_Case_Insensitive
   (Key : String) return Containers.Hash_Type;
-
 pragma Pure (Ada.Strings.Hash_Case_Insensitive);
+--  Computes a hash value for Key without regard for character case. This is
+--  useful as the generic actual Hash function when instantiating a hashed
+--  container package with type String as the key.
index 2bb2d1ad4c7a62e6c358a4115252725dad2d2b6f..848c1b7f0210e0c2466a87deffdb16e35326da48 100644 (file)
@@ -6,14 +6,33 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
--- This specification is derived from the Ada Reference Manual for use with --
--- GNAT.  In accordance with the copyright of that document, you can freely --
--- copy and modify this specification,  provided that if you redistribute a --
--- modified version,  any changes that you have made are clearly indicated. --
+--          Copyright (C) 2004-2008, Free Software Foundation, Inc.         --
 --                                                                          --
+-- 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 2,  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.  See the GNU General Public License --
+-- for  more details.  You should have  received  a copy of the GNU General --
+-- Public License  distributed with GNAT;  see file COPYING.  If not, write --
+-- to  the  Free Software Foundation,  51  Franklin  Street,  Fifth  Floor, --
+-- Boston, MA 02110-1301, USA.                                              --
+--                                                                          --
+-- As a special exception,  if other files  instantiate  generics from this --
+-- unit, or you link  this unit with other files  to produce an executable, --
+-- this  unit  does not  by itself cause  the resulting  executable  to  be --
+-- covered  by the  GNU  General  Public  License.  This exception does not --
+-- however invalidate  any other reasons why  the executable file  might be --
+-- covered by the  GNU Public License.                                      --
+--                                                                          --
+-- This unit was originally developed by Matthew J Heaney.                  --
 ------------------------------------------------------------------------------
 
 function Ada.Strings.Less_Case_Insensitive
   (Left, Right : String) return Boolean;
-
 pragma Pure (Ada.Strings.Less_Case_Insensitive);
+--  Performs a case-insensitive lexicographic comparison of Left and
+--  Right. This is useful as the generic actual less-than operator when
+--  instantiating an ordered container package with type String as the key,
+--  allowing case-insensitive equivalence tests.