gcc/ada/elists.ads

   1 ------------------------------------------------------------------------------
   2 --                                                                          --
   3 --                         GNAT COMPILER COMPONENTS                         --
   4 --                                                                          --
   5 --                               E L I S T S                                --
   6 --                                                                          --
   7 --                                 S p e c                                  --
   8 --                                                                          --
   9 --          Copyright (C) 1992-1998 Free Software Foundation, Inc.          --
  10 --                                                                          --
  11 -- GNAT is free software;  you can  redistribute it  and/or modify it under --
  12 -- terms of the  GNU General Public License as published  by the Free Soft- --
  13 -- ware  Foundation;  either version 2,  or (at your option) any later ver- --
  14 -- sion.  GNAT is distributed in the hope that it will be useful, but WITH- --
  15 -- OUT ANY WARRANTY;  without even the  implied warranty of MERCHANTABILITY --
  16 -- or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License --
  17 -- for  more details.  You should have  received  a copy of the GNU General --
  18 -- Public License  distributed with GNAT;  see file COPYING.  If not, write --
  19 -- to  the Free Software Foundation,  59 Temple Place - Suite 330,  Boston, --
  20 -- MA 02111-1307, USA.                                                      --
  21 --                                                                          --
  22 -- As a special exception,  if other files  instantiate  generics from this --
  23 -- unit, or you link  this unit with other files  to produce an executable, --
  24 -- this  unit  does not  by itself cause  the resulting  executable  to  be --
  25 -- covered  by the  GNU  General  Public  License.  This exception does not --
  26 -- however invalidate  any other reasons why  the executable file  might be --
  27 -- covered by the  GNU Public License.                                      --
  28 --                                                                          --
  29 -- GNAT was originally developed  by the GNAT team at  New York University. --
  30 -- Extensive contributions were provided by Ada Core Technologies Inc.      --
  31 --                                                                          --
  32 ------------------------------------------------------------------------------
  33
  34 --  This package provides facilities for manipulating lists of nodes (see
  35 --  package Atree for format and implementation of tree nodes). Separate list
  36 --  elements are allocated to represent elements of these lists, so it is
  37 --  possible for a given node to be on more than one element list at a time.
  38 --  See also package Nlists, which provides another form that is threaded
  39 --  through the nodes themselves (using the Link field), which is more time
  40 --  and space efficient, but a node can be only one such list.
  41
  42 with Types;  use Types;
  43 with System;
  44
  45 package Elists is
  46
  47    --  An element list is represented by a header that is allocated in the
  48    --  Elist header table. This header contains pointers to the first and
  49    --  last elements in the list, or to No_Elmt if the list is empty.
  50
  51    --  The elements in the list each contain a pointer to the next element
  52    --  and a pointer to the referenced node. Putting a node into an element
  53    --  list causes no change at all to the node itself, so a node may be
  54    --  included in multiple element lists, and the nodes thus included may
  55    --  or may not be elements of node lists (see package Nlists).
  56
  57    procedure Initialize;
  58    --  Initialize allocation of element list tables. Called at the start of
  59    --  compiling each new main source file. Note that Initialize must not be
  60    --  called if Tree_Read is used.
  61
  62    procedure Lock;
  63    --  Lock tables used for element lists before calling backend
  64
  65    procedure Tree_Read;
  66    --  Initializes internal tables from current tree file using Tree_Read.
  67    --  Note that Initialize should not be called if Tree_Read is used.
  68    --  Tree_Read includes all necessary initialization.
  69
  70    procedure Tree_Write;
  71    --  Writes out internal tables to current tree file using Tree_Write
  72
  73    function Last_Elist_Id return Elist_Id;
  74    --  Returns Id of last allocated element list header
  75
  76    function Elists_Address return System.Address;
  77    --  Return address of Elists table (used in Back_End for Gigi call)
  78
  79    function Num_Elists return Nat;
  80    --  Number of currently allocated element lists
  81
  82    function Last_Elmt_Id return Elmt_Id;
  83    --  Returns Id of last allocated list element
  84
  85    function Elmts_Address return System.Address;
  86    --  Return address of Elmts table (used in Back_End for Gigi call)
  87
  88    function Node (Elmt : Elmt_Id) return Node_Id;
  89    pragma Inline (Node);
  90    --  Returns the value of a given list element. Returns Empty if Elmt
  91    --  is set to No_Elmt.
  92
  93    function New_Elmt_List return Elist_Id;
  94    --  Creates a new empty element list. Typically this is used to initialize
  95    --  a field in some other node which points to an element list where the
  96    --  list is then subsequently filled in using Append calls.
  97
  98    function First_Elmt (List : Elist_Id) return Elmt_Id;
  99    pragma Inline (First_Elmt);
 100    --  Obtains the first element of the given element list or, if the
 101    --  list has no items, then No_Elmt is returned.
 102
 103    function Last_Elmt (List : Elist_Id) return Elmt_Id;
 104    pragma Inline (Last_Elmt);
 105    --  Obtains the last element of the given element list or, if the
 106    --  list has no items, then No_Elmt is returned.
 107
 108    function Next_Elmt (Elmt : Elmt_Id) return Elmt_Id;
 109    pragma Inline (Next_Elmt);
 110    --  This function returns the next element on an element list. The argument
 111    --  must be a list element other than No_Elmt. Returns No_Elmt if the given
 112    --  element is the last element of the list.
 113
 114    procedure Next_Elmt (Elmt : in out Elmt_Id);
 115    pragma Inline (Next_Elmt);
 116    --  Next_Elmt (Elmt) is equivalent to Elmt := Next_Elmt (Elmt)
 117
 118    function Is_Empty_Elmt_List (List : Elist_Id) return Boolean;
 119    pragma Inline (Is_Empty_Elmt_List);
 120    --  This function determines if a given tree id references an element list
 121    --  that contains no items.
 122
 123    procedure Append_Elmt (Node : Node_Id; To : Elist_Id);
 124    --  Appends Node at the end of To, allocating a new element.
 125
 126    procedure Prepend_Elmt (Node : Node_Id; To : Elist_Id);
 127    --  Appends Node at the beginning of To, allocating a new element.
 128
 129    procedure Insert_Elmt_After (Node : Node_Id; Elmt : Elmt_Id);
 130    --  Add a new element (Node) right after the pre-existing element Elmt
 131    --  It is invalid to call this subprogram with Elmt = No_Elmt.
 132
 133    procedure Replace_Elmt (Elmt : Elmt_Id; New_Node : Node_Id);
 134    pragma Inline (Replace_Elmt);
 135    --  Causes the given element of the list to refer to New_Node, the node
 136    --  which was previously referred to by Elmt is effectively removed from
 137    --  the list and replaced by New_Node.
 138
 139    procedure Remove_Elmt (List : Elist_Id; Elmt : Elmt_Id);
 140    --  Removes Elmt from the given list. The node itself is not affected,
 141    --  but the space used by the list element may be (but is not required
 142    --  to be) freed for reuse in a subsequent Append_Elmt call.
 143
 144    procedure Remove_Last_Elmt (List : Elist_Id);
 145    --  Removes the last element of the given list. The node itself is not
 146    --  affected, but the space used by the list element may be (but is not
 147    --  required to be) freed for reuse in a subsequent Append_Elmt call.
 148
 149    function No (List : Elist_Id) return Boolean;
 150    pragma Inline (No);
 151    --  Tests given Id for equality with No_Elist. This allows notations like
 152    --  "if No (Statements)" as opposed to "if Statements = No_Elist".
 153
 154    function Present (List : Elist_Id) return Boolean;
 155    pragma Inline (Present);
 156    --  Tests given Id for inequality with No_Elist. This allows notations like
 157    --  "if Present (Statements)" as opposed to "if Statements /= No_Elist".
 158
 159    function No (Elmt : Elmt_Id) return Boolean;
 160    pragma Inline (No);
 161    --  Tests given Id for equality with No_Elmt. This allows notations like
 162    --  "if No (Operation)" as opposed to "if Operation = No_Elmt".
 163
 164    function Present (Elmt : Elmt_Id) return Boolean;
 165    pragma Inline (Present);
 166    --  Tests given Id for inequality with No_Elmt. This allows notations like
 167    --  "if Present (Operation)" as opposed to "if Operation /= No_Elmt".
 168
 169 end Elists;