home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / gnat-2.06-src.tgz / tar.out / fsf / gnat / ada / elists.ads < prev    next >
Text File  |  1996-09-28  |  7KB  |  149 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                         GNAT COMPILER COMPONENTS                         --
  4. --                                                                          --
  5. --                               E L I S T S                                --
  6. --                                                                          --
  7. --                                 S p e c                                  --
  8. --                                                                          --
  9. --                            $Revision: 1.9 $                              --
  10. --                                                                          --
  11. --        Copyright (c) 1992,1993,1994,1995 NYU, All Rights Reserved        --
  12. --                                                                          --
  13. -- The GNAT library is free software; you can redistribute it and/or modify --
  14. -- it under terms of the GNU Library General Public License as published by --
  15. -- the Free Software  Foundation; either version 2, or (at your option) any --
  16. -- later version.  The GNAT library is distributed in the hope that it will --
  17. -- be useful, but WITHOUT ANY WARRANTY;  without even  the implied warranty --
  18. -- of MERCHANTABILITY  or  FITNESS FOR  A PARTICULAR PURPOSE.  See the  GNU --
  19. -- Library  General  Public  License for  more  details.  You  should  have --
  20. -- received  a copy of the GNU  Library  General Public License  along with --
  21. -- the GNAT library;  see the file  COPYING.LIB.  If not, write to the Free --
  22. -- Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.        --
  23. --                                                                          --
  24. ------------------------------------------------------------------------------
  25.  
  26. --  This package provides facilities for manipulating lists of nodes (see
  27. --  package Atree for format and implementation of tree nodes). Separate list
  28. --  elements are allocated to represent elements of these lists, so it is
  29. --  possible for a given node to be on more than one element list at a time.
  30. --  See also package Nlists, which provides another form that is threaded
  31. --  through the nodes themselves (using the Link field), which is more time
  32. --  and space efficient, but a node can be only one such list.
  33.  
  34. with Types;  use Types;
  35. with System;
  36.  
  37. package Elists is
  38.  
  39.    --  An element list is represented by a header that is allocated in the
  40.    --  Elist header table. This header contains pointers to the first and
  41.    --  last elements in the list, or to No_Elmt if the list is empty.
  42.  
  43.    --  The elements in the list each contain a pointer to the next element
  44.    --  and a pointer to the referenced node. Putting a node into an element
  45.    --  list causes no change at all to the node itself, so a node may be
  46.    --  included in multiple element lists, and the nodes thus included may
  47.    --  or may not be elements of node lists (see package Nlists).
  48.  
  49.    procedure Initialize;
  50.    --  Initialize allocation of element list tables. Called at the start of
  51.    --  compiling each new main source file. Note that Initialize must not be
  52.    --  called if Tree_Read is used.
  53.  
  54.    procedure Tree_Read;
  55.    --  Initializes internal tables from current tree file using Tree_Read.
  56.    --  Note that Initialize should not be called if Tree_Read is used.
  57.    --  Tree_Read includes all necessary initialization.
  58.  
  59.    procedure Tree_Write;
  60.    --  Writes out internal tables to current tree file using Tree_Write
  61.  
  62.    function Last_Elist_Id return Elist_Id;
  63.    --  Returns Id of last allocated element list header
  64.  
  65.    function Elists_Address return System.Address;
  66.    --  Return address of Elists table (used in Back_End for Gigi call)
  67.  
  68.    function Num_Elists return Nat;
  69.    --  Number of currently allocated element lists
  70.  
  71.    function Last_Elmt_Id return Elmt_Id;
  72.    --  Returns Id of last allocated list element
  73.  
  74.    function Elmts_Address return System.Address;
  75.    --  Return address of Elmts table (used in Back_End for Gigi call)
  76.  
  77.    function Node (Elmt : Elmt_Id) return Node_Id;
  78.    pragma Inline (Node);
  79.    --  Returns the value of a given list element
  80.  
  81.    function New_Elmt_List return Elist_Id;
  82.    --  Creates a new empty element list. Typically this is used to initialize
  83.    --  a field in some other node which points to an element list where the
  84.    --  list is then subsequently filled in using Append calls.
  85.  
  86.    function First_Elmt (List : Elist_Id) return Elmt_Id;
  87.    pragma Inline (First_Elmt);
  88.    --  Obtains the first element of the given element list or, if the
  89.    --  list has no items, then No_Elmt is returned.
  90.  
  91.    function Last_Elmt (List : Elist_Id) return Elmt_Id;
  92.    pragma Inline (Last_Elmt);
  93.    --  Obtains the last element of the given element list or, if the
  94.    --  list has no items, then No_Elmt is returned.
  95.  
  96.    function Next_Elmt (Elmt : Elmt_Id) return Elmt_Id;
  97.    pragma Inline (Next_Elmt);
  98.    --  This function returns the next element on an element list. The argument
  99.    --  must be a list element other than No_Elmt. Returns No_Elmt if the given
  100.    --  element is the last element of the list.
  101.  
  102.    function Is_Empty_Elmt_List (List : Elist_Id) return Boolean;
  103.    pragma Inline (Is_Empty_Elmt_List);
  104.    --  This function determines if a given tree id references an element list
  105.    --  that contains no items.
  106.  
  107.    procedure Append_Elmt (Node : Node_Id; To : Elist_Id);
  108.    --  Appends Node at the end of To, allocating a new element.
  109.  
  110.    procedure Prepend_Elmt (Node : Node_Id; To : Elist_Id);
  111.    --  Appends Node at the beginning of To, allocating a new element.
  112.  
  113.    procedure Insert_Elmt_After (Node : Node_Id; Elmt : Elmt_Id);
  114.    --  Add a new element (Node) right after the pre-existing element Elmt
  115.    --  It is invalid to call this subprogram with Elmt = No_Elmt.
  116.  
  117.    procedure Replace_Elmt (Elmt : Elmt_Id; New_Node : Node_Id);
  118.    pragma Inline (Replace_Elmt);
  119.    --  Causes the given element of the list to refer to New_Node, the node
  120.    --  which was previously referred to by Elmt is effectively removed from
  121.    --  the list and replaced by New_Node.
  122.  
  123.    procedure Remove_Last_Elmt (List : Elist_Id);
  124.    --  Removes the last element of the given list. The node itself is not
  125.    --  affected, but the space used by the list element may be (but is not
  126.    --  required to be) freed for reuse in a subsequent Append_Elmt call.
  127.  
  128.    function No (List : Elist_Id) return Boolean;
  129.    pragma Inline (No);
  130.    --  Tests given Id for equality with No_Elist. This allows notations like
  131.    --  "if No (Statements)" as opposed to "if Statements = No_Elist".
  132.  
  133.    function Present (List : Elist_Id) return Boolean;
  134.    pragma Inline (Present);
  135.    --  Tests given Id for inequality with No_Elist. This allows notations like
  136.    --  "if Present (Statements)" as opposed to "if Statements /= No_Elist".
  137.  
  138.    function No (Elmt : Elmt_Id) return Boolean;
  139.    pragma Inline (No);
  140.    --  Tests given Id for equality with No_Elmt. This allows notations like
  141.    --  "if No (Operation)" as opposed to "if Operation = No_Elmt".
  142.  
  143.    function Present (Elmt : Elmt_Id) return Boolean;
  144.    pragma Inline (Present);
  145.    --  Tests given Id for inequality with No_Elmt. This allows notations like
  146.    --  "if Present (Operation)" as opposed to "if Operation /= No_Elmt".
  147.  
  148. end Elists;
  149.