[Ada] Update Ada.Containers.Hashed_Maps documentation with Ada RM doc.

2018-05-24  Raphael Amiard  <amiard@adacore.com>

gcc/ada/

	* libgnat/a-cohama.ads: Add documentation.

From-SVN: r260656

gcc/ada/ChangeLog

 2018-05-24  Raphael Amiard  <amiard@adacore.com>
 
+	* libgnat/a-cohama.ads: Add documentation.
+
+2018-05-24  Raphael Amiard  <amiard@adacore.com>
+
 	* libgnat/a-convec.ads: Add documentation.
 
 2018-05-24  Justin Squirek  <squirek@adacore.com>

gcc/ada/libgnat/a-cohama.ads

@@ -37,14 +37,57 @@ private with Ada.Containers.Hash_Tables;
 private with Ada.Finalization;
 private with Ada.Streams;
 
+--  The language-defined generic package Containers.Hashed_Maps provides
+--  private types Map and Cursor, and a set of operations for each type. A map
+--  container allows an arbitrary type to be used as a key to find the element
+--  associated with that key. A hashed map uses a hash function to organize the
+--  keys.
+--
+--  A map contains pairs of keys and elements, called nodes. Map cursors
+--  designate nodes, but also can be thought of as designating an element (the
+--  element contained in the node) for consistency with the other containers.
+--  There exists an equivalence relation on keys, whose definition is different
+--  for hashed maps and ordered maps. A map never contains two or more nodes
+--  with equivalent keys. The length of a map is the number of nodes it
+--  contains.
+--
+--  Each nonempty map has two particular nodes called the first node and the
+--  last node (which may be the same). Each node except for the last node has a
+--  successor node. If there are no other intervening operations, starting with
+--  the first node and repeatedly going to the successor node will visit each
+--  node in the map exactly once until the last node is reached.
+
 generic
    type Key_Type is private;
    type Element_Type is private;
 
    with function Hash (Key : Key_Type) return Hash_Type;
+   --  The actual function for the generic formal function Hash is expected to
+   --  return the same value each time it is called with a particular key
+   --  value. For any two equivalent key values, the actual for Hash is
+   --  expected to return the same value. If the actual for Hash behaves in
+   --  some other manner, the behavior of this package is unspecified. Which
+   --  subprograms of this package call Hash, and how many times they call it,
+   --  is unspecified.
+
    with function Equivalent_Keys (Left, Right : Key_Type) return Boolean;
-   with function "=" (Left, Right : Element_Type) return Boolean is <>;
+   --  The actual function for the generic formal function Equivalent_Keys on
+   --  Key_Type values is expected to return the same value each time it is
+   --  called with a particular pair of key values. It should define an
+   --  equivalence relationship, that is, be reflexive, symmetric, and
+   --  transitive. If the actual for Equivalent_Keys behaves in some other
+   --  manner, the behavior of this package is unspecified. Which subprograms
+   --  of this package call Equivalent_Keys, and how many times they call it,
+   --  is unspecified.
 
+   with function "=" (Left, Right : Element_Type) return Boolean is <>;
+   --  The actual function for the generic formal function "=" on Element_Type
+   --  values is expected to define a reflexive and symmetric relationship and
+   --  return the same result value each time it is called with a particular
+   --  pair of values.  If it behaves in some other manner, the function "=" on
+   --  map values returns an unspecified value. The exact arguments and number
+   --  of calls of this generic formal function by the function "=" on map
+   --  values are unspecified.
 package Ada.Containers.Hashed_Maps is
    pragma Annotate (CodePeer, Skip_Analysis);
    pragma Preelaborate;
@@ -71,21 +114,27 @@ package Ada.Containers.Hashed_Maps is
    --  initialized to the value No_Element.
 
    function Has_Element (Position : Cursor) return Boolean;
-   --  Equivalent to Position /= No_Element
+   --  Returns True if Position designates an element, and returns False
+   --  otherwise.
 
    package Map_Iterator_Interfaces is new
      Ada.Iterator_Interfaces (Cursor, Has_Element);
 
    function "=" (Left, Right : Map) return Boolean;
-   --  For each key/element pair in Left, equality attempts to find the key in
-   --  Right; if a search fails the equality returns False. The search works by
-   --  calling Hash to find the bucket in the Right map that corresponds to the
-   --  Left key. If bucket is non-empty, then equality calls Equivalent_Keys
-   --  to compare the key (in Left) to the key of each node in the bucket (in
-   --  Right); if the keys are equivalent, then the equality test for this
-   --  key/element pair (in Left) completes by calling the element equality
-   --  operator to compare the element (in Left) to the element of the node
-   --  (in Right) whose key matched.
+   --  If Left and Right denote the same map object, then the function returns
+   --  True. If Left and Right have different lengths, then the function
+   --  returns False. Otherwise, for each key K in Left, the function returns
+   --  False if:
+   --
+   --  * a key equivalent to K is not present in Right; or
+   --
+   --  * the element associated with K in Left is not equal to the
+   --    element associated with K in Right (using the generic formal
+   --    equality operator for elements).
+   --
+   --  If the function has not returned a result after checking all of the
+   --  keys, it returns True. Any exception raised during evaluation of key
+   --  equivalence or element equality is propagated.
 
    function Capacity (Container : Map) return Count_Type;
    --  Returns the current capacity of the map. Capacity is the maximum length
@@ -111,31 +160,55 @@ package Ada.Containers.Hashed_Maps is
    --  Removes all of the items from the map
 
    function Key (Position : Cursor) return Key_Type;
-   --  Returns the key of the node designated by the cursor
+   --  Key returns the key component of the node designated by Position.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated.
 
    function Element (Position : Cursor) return Element_Type;
-   --  Returns the element of the node designated by the cursor
+   --  Element returns the element component of the node designated
+   --  by Position.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated.
 
    procedure Replace_Element
      (Container : in out Map;
       Position  : Cursor;
       New_Item  : Element_Type);
-   --  Assigns the value New_Item to the element designated by the cursor
+   --  Replace_Element assigns New_Item to the element of the node designated
+   --  by Position.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated; if
+   --  Position does not designate an element in Container, then Program_Error
+   --  is propagated.
 
    procedure Query_Element
      (Position : Cursor;
       Process  : not null access
                    procedure (Key : Key_Type; Element : Element_Type));
-   --  Calls Process with the key and element (both having only a constant
-   --  view) of the node designed by the cursor.
+   --  Query_Element calls Process.all with the key and element from the node
+   --  designated by Position as the arguments.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated.
+   --
+   --  Tampering with the elements of the map that contains the element
+   --  designated by Position is prohibited during the execution of the call on
+   --  Process.all. Any exception raised by Process.all is propagated.
 
    procedure Update_Element
      (Container : in out Map;
       Position  : Cursor;
       Process   : not null access
                     procedure (Key : Key_Type; Element : in out Element_Type));
-   --  Calls Process with the key (with only a constant view) and element (with
-   --  a variable view) of the node designed by the cursor.
+   --  Update_Element calls Process.all with the key and element from the node
+   --  designated by Position as the arguments.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated; if
+   --  Position does not designate an element in Container, then Program_Error
+   --  is propagated.
+   --
+   --  Tampering with the elements of Container is prohibited during the
+   --  execution of the call on Process.all. Any exception raised by
+   --  Process.all is propagated.
 
    type Constant_Reference_Type
       (Element : not null access constant Element_Type) is private
@@ -150,29 +223,60 @@ package Ada.Containers.Hashed_Maps is
      (Container : aliased Map;
       Position  : Cursor) return Constant_Reference_Type;
    pragma Inline (Constant_Reference);
+   --  This function (combined with the Constant_Indexing and
+   --  Implicit_Dereference aspects) provides a convenient way to gain read
+   --  access to an individual element of a map given a cursor.
+   --  Constant_Reference returns an object whose discriminant is an access
+   --  value that designates the element designated by Position.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated; if
+   --  Position does not designate an element in Container, then Program_Error
+   --  is propagated.
+   --
+   --  Tampering with the elements of Container is prohibited
+   --  while the object returned by Constant_Reference exists and has not been
+   --  finalized.
 
    function Reference
      (Container : aliased in out Map;
       Position  : Cursor) return Reference_Type;
    pragma Inline (Reference);
+   --  This function (combined with the Variable_Indexing and
+   --  Implicit_Dereference aspects) provides a convenient way to gain read and
+   --  write access to an individual element of a map given a cursor.
+   --  Reference returns an object whose discriminant is an access value that
+   --  designates the element designated by Position.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated; if
+   --  Position does not designate an element in Container, then Program_Error
+   --  is propagated.
+   --
+   --  Tampering with the elements of Container is prohibited while the object
+   --  returned by Reference exists and has not been finalized.
 
    function Constant_Reference
      (Container : aliased Map;
       Key       : Key_Type) return Constant_Reference_Type;
    pragma Inline (Constant_Reference);
+   --  Equivalent to Constant_Reference (Container, Find (Container, Key)).
 
    function Reference
      (Container : aliased in out Map;
       Key       : Key_Type) return Reference_Type;
    pragma Inline (Reference);
+   --  Equivalent to Reference (Container, Find (Container, Key)).
 
    procedure Assign (Target : in out Map; Source : Map);
+   --  If Target denotes the same object as Source, the operation has no
+   --  effect. Otherwise, the key/element pairs of Source are copied to Target
+   --  as for an assignment_statement assigning Source to Target.
 
    function Copy (Source : Map; Capacity : Count_Type := 0) return Map;
 
    procedure Move (Target : in out Map; Source : in out Map);
-   --  Clears Target (if it's not empty), and then moves (not copies) the
-   --  buckets array and nodes from Source to Target.
+   --  If Target denotes the same object as Source, then the operation has no
+   --  effect. Otherwise, the operation is equivalent to Assign (Target,
+   --  Source) followed by Clear (Source).
 
    procedure Insert
      (Container : in out Map;
@@ -180,105 +284,86 @@ package Ada.Containers.Hashed_Maps is
       New_Item  : Element_Type;
       Position  : out Cursor;
       Inserted  : out Boolean);
-   --  Conditionally inserts New_Item into the map. If Key is already in the
-   --  map, then Inserted returns False and Position designates the node
-   --  containing the existing key/element pair (neither of which is modified).
-   --  If Key is not already in the map, the Inserted returns True and Position
-   --  designates the newly-inserted node container Key and New_Item. The
-   --  search for the key works as follows. Hash is called to determine Key's
-   --  bucket; if the bucket is non-empty, then Equivalent_Keys is called to
-   --  compare Key to each node in that bucket. If the bucket is empty, or
-   --  there were no matching keys in the bucket, the search "fails" and the
-   --  key/item pair is inserted in the map (and Inserted returns True);
-   --  otherwise, the search "succeeds" (and Inserted returns False).
+   --  Insert checks if a node with a key equivalent to Key is already present
+   --  in Container. If a match is found, Inserted is set to False and Position
+   --  designates the element with the matching key.  Otherwise, Insert
+   --  allocates a new node, initializes it to Key and New_Item, and adds it to
+   --  Container; Inserted is set to True and Position designates the
+   --  newly-inserted node. Any exception raised during allocation is
+   --  propagated and Container is not modified.
 
    procedure Insert
      (Container : in out Map;
       Key       : Key_Type;
       Position  : out Cursor;
       Inserted  : out Boolean);
-   --  The same as the (conditional) Insert that accepts an element parameter,
-   --  with the difference that if Inserted returns True, then the element of
-   --  the newly-inserted node is initialized to its default value.
+   --  Insert inserts Key into Container as per the five-parameter Insert, with
+   --  the difference that an element initialized by default (see 3.3.1) is
+   --  inserted.
 
    procedure Insert
      (Container : in out Map;
       Key       : Key_Type;
       New_Item  : Element_Type);
-   --  Attempts to insert Key into the map, performing the usual search (which
-   --  involves calling both Hash and Equivalent_Keys); if the search succeeds
-   --  (because Key is already in the map), then it raises Constraint_Error.
-   --  (This version of Insert is similar to Replace, but having the opposite
-   --  exception behavior. It is intended for use when you want to assert that
-   --  Key is not already in the map.)
+   --  Insert inserts Key and New_Item into Container as per the five-parameter
+   --  Insert, with the difference that if a node with a key equivalent to Key
+   --  is already in the map, then Constraint_Error is propagated.
 
    procedure Include
      (Container : in out Map;
       Key       : Key_Type;
       New_Item  : Element_Type);
-   --  Attempts to insert Key into the map. If Key is already in the map, then
-   --  both the existing key and element are assigned the values of Key and
-   --  New_Item, respectively. (This version of Insert only raises an exception
-   --  if cursor tampering occurs. It is intended for use when you want to
-   --  insert the key/element pair in the map, and you don't care whether Key
-   --  is already present.)
+   --  Include inserts Key and New_Item into Container as per the
+   --  five-parameter Insert, with the difference that if a node with a key
+   --  equivalent to Key is already in the map, then this operation assigns Key
+   --  and New_Item to the matching node. Any exception raised during
+   --  assignment is propagated.
 
    procedure Replace
      (Container : in out Map;
       Key       : Key_Type;
       New_Item  : Element_Type);
-   --  Searches for Key in the map; if the search fails (because Key was not in
-   --  the map), then it raises Constraint_Error. Otherwise, both the existing
-   --  key and element are assigned the values of Key and New_Item rsp. (This
-   --  is similar to Insert, but with the opposite exception behavior. It is to
-   --  be used when you want to assert that Key is already in the map.)
+   --  Replace checks if a node with a key equivalent to Key is present in
+   --  Container. If a match is found, Replace assigns Key and New_Item to the
+   --  matching node; otherwise, Constraint_Error is propagated.
 
    procedure Exclude (Container : in out Map; Key : Key_Type);
-   --  Searches for Key in the map, and if found, removes its node from the map
-   --  and then deallocates it. The search works as follows. The operation
-   --  calls Hash to determine the key's bucket; if the bucket is not empty, it
-   --  calls Equivalent_Keys to compare Key to each key in the bucket. (This is
-   --  the deletion analog of Include. It is intended for use when you want to
-   --  remove the item from the map, but don't care whether the key is already
-   --  in the map.)
+   --  Exclude checks if a node with a key equivalent to Key is present in
+   --  Container. If a match is found, Exclude removes the node from the map.
 
    procedure Delete (Container : in out Map; Key : Key_Type);
-   --  Searches for Key in the map (which involves calling both Hash and
-   --  Equivalent_Keys). If the search fails, then the operation raises
-   --  Constraint_Error. Otherwise it removes the node from the map and then
-   --  deallocates it. (This is the deletion analog of non-conditional
-   --  Insert. It is intended for use when you want to assert that the item is
-   --  already in the map.)
+   --  Delete checks if a node with a key equivalent to Key is present in
+   --  Container. If a match is found, Delete removes the node from the map;
+   --  otherwise, Constraint_Error is propagated.
 
    procedure Delete (Container : in out Map; Position : in out Cursor);
-   --  Removes the node designated by Position from the map, and then
-   --  deallocates the node. The operation calls Hash to determine the bucket,
-   --  and then compares Position to each node in the bucket until there's a
-   --  match (it does not call Equivalent_Keys).
+   --  Delete removes the node designated by Position from the map. Position is
+   --  set to No_Element on return.
+   --
+   --  If Position equals No_Element, then Constraint_Error is propagated. If
+   --  Position does not designate an element in Container, then Program_Error
+   --  is propagated.
 
    function First (Container : Map) return Cursor;
-   --  Returns a cursor that designates the first non-empty bucket, by
-   --  searching from the beginning of the buckets array.
+   --  If Length (Container) = 0, then First returns No_Element.  Otherwise,
+   --  First returns a cursor that designates the first node in Container.
 
    function Next (Position : Cursor) return Cursor;
-   --  Returns a cursor that designates the node that follows the current one
-   --  designated by Position. If Position designates the last node in its
-   --  bucket, the operation calls Hash to compute the index of this bucket,
-   --  and searches the buckets array for the first non-empty bucket, starting
-   --  from that index; otherwise, it simply follows the link to the next node
-   --  in the same bucket.
+   --  Returns a cursor that designates the successor of the node designated by
+   --  Position. If Position designates the last node, then No_Element is
+   --  returned. If Position equals No_Element, then No_Element is returned.
 
    procedure Next (Position : in out Cursor);
    --  Equivalent to Position := Next (Position)
 
    function Find (Container : Map; Key : Key_Type) return Cursor;
-   --  Searches for Key in the map. Find calls Hash to determine the key's
-   --  bucket; if the bucket is not empty, it calls Equivalent_Keys to compare
-   --  Key to each key in the bucket. If the search succeeds, Find returns a
-   --  cursor designating the matching node; otherwise, it returns No_Element.
+   --  If Length (Container) equals 0, then Find returns No_Element.
+   --  Otherwise, Find checks if a node with a key equivalent to Key is present
+   --  in Container. If a match is found, a cursor designating the matching
+   --  node is returned; otherwise, No_Element is returned.
 
    function Contains (Container : Map; Key : Key_Type) return Boolean;
-   --  Equivalent to Find (Container, Key) /= No_Element
+   --  Equivalent to Find (Container, Key) /= No_Element.
 
    function Element (Container : Map; Key : Key_Type) return Element_Type;
    --  Equivalent to Element (Find (Container, Key))
@@ -298,7 +383,11 @@ package Ada.Containers.Hashed_Maps is
    procedure Iterate
      (Container : Map;
       Process   : not null access procedure (Position : Cursor));
-   --  Calls Process for each node in the map
+   --  Iterate calls Process.all with a cursor that designates each node in
+   --  Container, starting with the first node and moving the cursor according
+   --  to the successor relation. Tampering with the cursors of Container is
+   --  prohibited during the execution of a call on Process.all. Any exception
+   --  raised by Process.all is propagated.
 
    function Iterate
      (Container : Map) return Map_Iterator_Interfaces.Forward_Iterator'Class;