OSDN Git Service

Remove s-crtl-vms64.ads, no longer used.
[pf3gnuchains/gcc-fork.git] / 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-2007, 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,  51  Franklin  Street,  Fifth  Floor, --
20 -- Boston, MA 02110-1301, 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 Unlock;
66    --  Unlock list tables, in cases where the back end needs to modify them
67
68    procedure Tree_Read;
69    --  Initializes internal tables from current tree file using the relevant
70    --  Table.Tree_Read routines. Note that Initialize should not be called if
71    --  Tree_Read is used. Tree_Read includes all necessary initialization.
72
73    procedure Tree_Write;
74    --  Writes out internal tables to current tree file using the relevant
75    --  Table.Tree_Write routines.
76
77    function Last_Elist_Id return Elist_Id;
78    --  Returns Id of last allocated element list header
79
80    function Elists_Address return System.Address;
81    --  Return address of Elists table (used in Back_End for Gigi call)
82
83    function Num_Elists return Nat;
84    --  Number of currently allocated element lists
85
86    function Last_Elmt_Id return Elmt_Id;
87    --  Returns Id of last allocated list element
88
89    function Elmts_Address return System.Address;
90    --  Return address of Elmts table (used in Back_End for Gigi call)
91
92    function Node (Elmt : Elmt_Id) return Node_Or_Entity_Id;
93    pragma Inline (Node);
94    --  Returns the value of a given list element. Returns Empty if Elmt
95    --  is set to No_Elmt.
96
97    function New_Elmt_List return Elist_Id;
98    --  Creates a new empty element list. Typically this is used to initialize
99    --  a field in some other node which points to an element list where the
100    --  list is then subsequently filled in using Append calls.
101
102    function First_Elmt (List : Elist_Id) return Elmt_Id;
103    pragma Inline (First_Elmt);
104    --  Obtains the first element of the given element list or, if the list has
105    --  no items, then No_Elmt is returned.
106
107    function Last_Elmt (List : Elist_Id) return Elmt_Id;
108    pragma Inline (Last_Elmt);
109    --  Obtains the last element of the given element list or, if the list has
110    --  no items, then No_Elmt is returned.
111
112    function Next_Elmt (Elmt : Elmt_Id) return Elmt_Id;
113    pragma Inline (Next_Elmt);
114    --  This function returns the next element on an element list. The argument
115    --  must be a list element other than No_Elmt. Returns No_Elmt if the given
116    --  element is the last element of the list.
117
118    procedure Next_Elmt (Elmt : in out Elmt_Id);
119    pragma Inline (Next_Elmt);
120    --  Next_Elmt (Elmt) is equivalent to Elmt := Next_Elmt (Elmt)
121
122    function Is_Empty_Elmt_List (List : Elist_Id) return Boolean;
123    pragma Inline (Is_Empty_Elmt_List);
124    --  This function determines if a given tree id references an element list
125    --  that contains no items.
126
127    procedure Append_Elmt (N : Node_Or_Entity_Id; To : Elist_Id);
128    --  Appends N at the end of To, allocating a new element. N must be a
129    --  non-empty node or entity Id, and To must be an Elist (not No_Elist).
130
131    procedure Append_Unique_Elmt (N : Node_Or_Entity_Id; To : Elist_Id);
132    --  Like Append_Elmt, except that a check is made to see if To already
133    --  contains N and if so the call has no effect.
134
135    procedure Prepend_Elmt (N : Node_Or_Entity_Id; To : Elist_Id);
136    --  Appends N at the beginning of To, allocating a new element
137
138    procedure Insert_Elmt_After (N : Node_Or_Entity_Id; Elmt : Elmt_Id);
139    --  Add a new element (N) right after the pre-existing element Elmt
140    --  It is invalid to call this subprogram with Elmt = No_Elmt.
141
142    procedure Replace_Elmt (Elmt : Elmt_Id; New_Node : Node_Or_Entity_Id);
143    pragma Inline (Replace_Elmt);
144    --  Causes the given element of the list to refer to New_Node, the node
145    --  which was previously referred to by Elmt is effectively removed from
146    --  the list and replaced by New_Node.
147
148    procedure Remove_Elmt (List : Elist_Id; Elmt : Elmt_Id);
149    --  Removes Elmt from the given list. The node itself is not affected,
150    --  but the space used by the list element may be (but is not required
151    --  to be) freed for reuse in a subsequent Append_Elmt call.
152
153    procedure Remove_Last_Elmt (List : Elist_Id);
154    --  Removes the last element of the given list. The node itself is not
155    --  affected, but the space used by the list element may be (but is not
156    --  required to be) freed for reuse in a subsequent Append_Elmt call.
157
158    function No (List : Elist_Id) return Boolean;
159    pragma Inline (No);
160    --  Tests given Id for equality with No_Elist. This allows notations like
161    --  "if No (Statements)" as opposed to "if Statements = No_Elist".
162
163    function Present (List : Elist_Id) return Boolean;
164    pragma Inline (Present);
165    --  Tests given Id for inequality with No_Elist. This allows notations like
166    --  "if Present (Statements)" as opposed to "if Statements /= No_Elist".
167
168    function No (Elmt : Elmt_Id) return Boolean;
169    pragma Inline (No);
170    --  Tests given Id for equality with No_Elmt. This allows notations like
171    --  "if No (Operation)" as opposed to "if Operation = No_Elmt".
172
173    function Present (Elmt : Elmt_Id) return Boolean;
174    pragma Inline (Present);
175    --  Tests given Id for inequality with No_Elmt. This allows notations like
176    --  "if Present (Operation)" as opposed to "if Operation /= No_Elmt".
177
178 end Elists;