2007-04-06 Javier Miranda <miranda@adacore.com>

	    Matt Heaney  <heaney@adacore.com>
	    Robert Dewar  <dewar@adacore.com>

	a-coprnu.ads, a-cohata.ads, a-chtgop.ads, a-chtgop.adb, a-cgcaso.ads,
	a-cgarso.ads, a-secain.ads, a-slcain.ads, a-shcain.ads, a-chtgke.ads,
	a-chtgke.ads, a-coprnu.ads, a-contai.ads, a-chtgke.ads, a-chtgke.adb,
	a-stwiha.ads, a-strhas.ads, a-lfztio.ads, a-liztio.ads, a-llfzti.ads,
	a-llizti.ads, a-sfztio.ads, a-siztio.ads, a-ssizti.ads, a-stzfix.ads,
	a-stzhas.ads, a-szuzha.ads, a-tiunio.ads, a-wwunio.ads, a-ztcoio.ads,
	a-ztinio.ads, a-zttest.ads, a-zzunio.ads, a-astaco.ads, a-charac.ads,
	a-chlat1.ads, ada.ads, a-dynpri.ads, a-flteio.ads, a-fwteio.ads,
	a-inteio.ads, a-intnam.ads, a-ioexce.ads, a-iwteio.ads, a-lfteio.ads,
	a-lfwtio.ads, a-liteio.ads, a-liwtio.ads, a-llftio.ads, a-llfwti.ads,
	a-llitio.ads, a-lliwti.ads, a-ncelfu.ads, a-ngcefu.ads, a-ngelfu.ads,
	a-nlcefu.ads, a-nlcoty.ads, a-nlelfu.ads, a-nllcef.ads, a-nllcty.ads,
	a-nllefu.ads, a-nscefu.ads, a-nscoty.ads, a-nselfu.ads, a-nucoty.ads,
	a-nuelfu.ads, a-numeri.ads, a-sfteio.ads, a-sfwtio.ads, a-siteio.ads,
	a-siwtio.ads, a-ssitio.ads, a-ssiwti.ads, a-storio.ads, a-strfix.ads,
	a-string.ads, a-stwifi.ads, a-titest.ads, a-unccon.ads, a-uncdea.ads,
	a-wtcoio.ads, a-wtinio.ads, a-wttest.ads, calendar.ads, directio.ads,
	i-c.ads, ioexcept.ads, machcode.ads, sequenio.ads, text_io.ads,
	unchconv.ads, unchdeal.ads, a-widcha.ads, a-zchara.ads, a-stboha.ads,
	a-stfiha.ads, a-coteio.ads, a-envvar.ads, a-lcteio.ads, a-llctio.ads,
	a-scteio.ads, a-swbwha.ads, a-swfwha.ads, a-szbzha.ads, a-szfzha.ads,
	a-tiboio.ads, a-wwboio.ads, a-zzboio.ads, a-dispat.ads, a-tgdico.ads,
	expander.adb, g-socket.ads, par-labl.adb, sinput-c.adb, s-tarest.ads,
	s-stchop.ads, g-expect-vms.adb, s-taprop-lynxos.adb,
	s-taprop-tru64.adb, s-taprop-irix.adb,
	s-taprop-hpux-dce.adb, s-traceb-hpux.adb,
	s-taprop-linux.adb, s-taprop-dummy.adb, s-osprim-unix.adb,
	s-osprim-solaris.adb, s-taprop-solaris.adb, s-taprop-vms.adb,
	s-osprim-mingw.adb, s-taprop-mingw.adb, s-osprim-posix.adb, 
	s-taprop-posix.adb, a-exexpr-gcc.adb, a-ststio.adb, a-ststio.ads, 
	a-textio.adb, a-textio.ads, a-tideau.adb, a-tideau.ads, a-witeio.adb, 
	a-witeio.ads, a-wtdeau.adb, a-wtdeau.ads, g-calend.adb, g-calend.ads, 
	g-dirope.adb, g-expect.ads, gnatchop.adb, g-spipat.adb, g-spipat.ads, 
	s-direio.adb, s-direio.ads, s-fatgen.adb, s-fatgen.ads, s-parint.adb, 
	s-sequio.adb, s-sequio.ads, s-taprop.ads, s-valdec.adb, s-valdec.ads, 
	s-valint.adb, s-valint.ads, s-vallld.adb, s-vallld.ads, s-vallli.adb, 
	s-vallli.ads, s-valllu.adb, s-valllu.ads, s-valrea.adb, s-valrea.ads, 
	s-valuns.adb, s-valuns.ads, s-valuti.adb, s-valuti.ads, xref_lib.adb, 
	s-stchop.adb, i-vxwork-x86.ads, a-crbtgo.ads, a-crbtgo.adb, 
	a-coorse.ads, a-coorse.adb, a-cohama.ads, a-cohama.adb, a-ciorse.ads, 
	a-ciorse.adb, a-cihama.ads, a-cihama.adb, a-chtgop.ads, a-chtgop.ads, 
	a-coormu.adb, a-ciormu.adb, a-cihase.adb, a-cihase.ads, a-cohase.adb, 
	a-cohase.ads, a-swuwha.ads, a-ciormu.ads, a-coormu.ads, a-rbtgso.ads,
	a-stunha.ads, a-ciorma.adb, a-coorma.adb, a-ztdeau.adb, a-ztdeau.ads, 
	a-ztexio.adb, a-ztexio.ads: Addition of null-exclusion to anonymous
	access types.
	Update documentation.
	Minor rewording.



git-svn-id: svn+ssh://gcc.gnu.org/svn/gcc/trunk@123538 138bc75d-0d04-0410-961f-82ee72b054a4

1 files changed, 69 insertions, 8 deletions

diff --git a/gcc/ada/a-chtgop.ads b/gcc/ada/a-chtgop.ads
index 7d6e545e271..03154219be6 100644
--- a/gcc/ada/a-chtgop.ads
+++ b/gcc/ada/a-chtgop.ads
@@ -7,13 +7,32 @@
 --                                                                          --
 --                                 S p e c                                  --
 --                                                                          --
--- This specification is adapted 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-2006, 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.                  --
 ------------------------------------------------------------------------------
 
+--  Hash_Table_Type is used to implement hashed containers. This package
+--  declares hash-table operations that do not depend on keys.
+
 with Ada.Streams;
 
 generic
@@ -39,20 +58,31 @@ package Ada.Containers.Hash_Tables.Generic_Operations is
    pragma Preelaborate;
 
    procedure Free_Hash_Table (Buckets : in out Buckets_Access);
+   --  First frees the nodes in all non-null buckets of Buckets, and then frees
+   --  the Buckets array itself.
 
    function Index
      (Buckets : Buckets_Type;
       Node    : Node_Access) return Hash_Type;
    pragma Inline (Index);
+   --  Uses the hash value of Node to compute its Buckets array index
 
    function Index
      (Hash_Table : Hash_Table_Type;
       Node       : Node_Access) return Hash_Type;
    pragma Inline (Index);
+   --  Uses the hash value of Node to compute its Hash_Table buckets array
+   --  index.
 
    procedure Adjust (HT : in out Hash_Table_Type);
+   --  Used to implement controlled Adjust. It is assumed that HT has the value
+   --  of the bit-wise copy that immediately follows controlled Finalize.
+   --  Adjust first allocates a new buckets array for HT (having the same
+   --  length as the source), and then allocates a copy of each node of source.
 
    procedure Finalize (HT : in out Hash_Table_Type);
+   --  Used to implement controlled Finalize. It first calls Clear to
+   --  deallocate any remaining nodes, and then deallocates the buckets array.
 
    generic
       with function Find
@@ -60,46 +90,77 @@ package Ada.Containers.Hash_Tables.Generic_Operations is
          Key : Node_Access) return Boolean;
    function Generic_Equal
      (L, R : Hash_Table_Type) return Boolean;
+   --  Used to implement hashed container equality. For each node in hash table
+   --  L, it calls Find to search for an equivalent item in hash table R. If
+   --  Find returns False for any node then Generic_Equal terminates
+   --  immediately and returns False. Otherwise if Find returns True for every
+   --  node then Generic_Equal returns True.
 
    procedure Clear (HT : in out Hash_Table_Type);
+   --  Deallocates each node in hash table HT. (Note that it only deallocates
+   --  the nodes, not the buckets array.)  Program_Error is raised if the hash
+   --  table is busy.
 
    procedure Move (Target, Source : in out Hash_Table_Type);
+   --  Moves (not copies) the buckets array and nodes from Source to
+   --  Target. Program_Error is raised if Source is busy. The Target is first
+   --  cleared to deallocate its nodes (implying that Program_Error is also
+   --  raised if Target is busy). Source is empty following the move.
 
    function Capacity (HT : Hash_Table_Type) return Count_Type;
+   --  Returns the length of the buckets array
 
    procedure Reserve_Capacity
      (HT : in out Hash_Table_Type;
       N  : Count_Type);
+   --  If N is greater than the current capacity, then it expands the buckets
+   --  array to at least the value N. If N is less than the current capacity,
+   --  then it contracts the buckets array. In either case existing nodes are
+   --  rehashed onto the new buckets array, and the old buckets array is
+   --  deallocated. Program_Error is raised if the hash table is busy.
 
    procedure Delete_Node_Sans_Free
      (HT : in out Hash_Table_Type;
       X  : Node_Access);
+   --  Removes node X from the hash table without deallocating the node
 
    function First (HT : Hash_Table_Type) return Node_Access;
+   --  Returns the head of the list in the first (lowest-index) non-empty
+   --  bucket.
 
    function Next
      (HT   : Hash_Table_Type;
       Node : Node_Access) return Node_Access;
+   --  Returns the node that immediately follows Node. This corresponds to
+   --  either the next node in the same bucket, or (if Node is the last node in
+   --  its bucket) the head of the list in the first non-empty bucket that
+   --  follows.
 
    generic
       with procedure Process (Node : Node_Access);
    procedure Generic_Iteration (HT : Hash_Table_Type);
+   --  Calls Process for each node in hash table HT
 
    generic
       use Ada.Streams;
       with procedure Write
-        (Stream : access Root_Stream_Type'Class;
+        (Stream : not null access Root_Stream_Type'Class;
          Node   : Node_Access);
    procedure Generic_Write
-     (Stream : access Root_Stream_Type'Class;
+     (Stream : not null access Root_Stream_Type'Class;
       HT     : Hash_Table_Type);
+   --  Used to implement the streaming attribute for hashed containers. It
+   --  calls Write for each node to write its value into Stream.
 
    generic
       use Ada.Streams;
-      with function New_Node (Stream : access Root_Stream_Type'Class)
+      with function New_Node (Stream : not null access Root_Stream_Type'Class)
          return Node_Access;
    procedure Generic_Read
-     (Stream : access Root_Stream_Type'Class;
+     (Stream : not null access Root_Stream_Type'Class;
       HT     : out Hash_Table_Type);
+   --  Used to implement the streaming attribute for hashed containers. It
+   --  first clears hash table HT, then populates the hash table by calling
+   --  New_Node for each item in Stream.
 
 end Ada.Containers.Hash_Tables.Generic_Operations;