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 / table.ads < prev    next >
Text File  |  1996-09-28  |  7KB  |  138 lines
  1. ------------------------------------------------------------------------------
  2. --                                                                          --
  3. --                         GNAT COMPILER COMPONENTS                         --
  4. --                                                                          --
  5. --                                T A B L E                                 --
  6. --                                                                          --
  7. --                                 S p e c                                  --
  8. --                                                                          --
  9. --                            $Revision: 1.18 $                              --
  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. with Types; use Types;
  27.  
  28. generic
  29.    type Table_Component_Type is private;
  30.    type Table_Index_Type     is range <>;
  31.  
  32.    Table_Low_Bound  : Table_Index_Type;
  33.    Table_Initial    : Pos;
  34.    Table_Increment  : Nat;
  35.    Table_Name       : String;
  36.  
  37. package Table is
  38.  
  39. --  This package provides an implementation of dynamically resizable one
  40. --  dimensional arrays. The idea is to mimic the normal Ada semantics for
  41. --  arrays as closely as possible with the one additional capability of
  42. --  dynamically modifying the value of the Last attribute.
  43.  
  44.    --  Table_Component_Type and Table_Index_Type specify the type of the array,
  45.    --  Table_Low_Bound is the lower bound. Index_type must be an integer type.
  46.    --  The effect is roughly to declare:
  47.  
  48.    --    Table : array (Table_Low_Bound .. <>) of aliased Table_Component_Type;
  49.  
  50.    --  The Table_Initial and Table_Increment values control the allocation of
  51.    --  the table. When the table is first allocated, the Table_Initial value
  52.    --  controls the actual size of the allocated table. The Table_Increment
  53.    --  value is a percentage value used to determine the increase in the table
  54.    --  size (e.g. 100 = increase table size by 100%, i.e. double it). The
  55.    --  Table_Name parameter is simply use in debug output messages it has no
  56.    --  other usage, and is not referenced in non-debugging mode. A value of
  57.    --  zero for Table_Increment means that no table expansion is allowed.
  58.  
  59.    --  The Last and Set_Last subprograms provide control over the current
  60.    --  logical allocation. They are quite efficient, so they can be used freely
  61.    --  freely (expensive reallocation occurs only at major granularity chunks,
  62.    --  controlled by the allocation parameters.
  63.  
  64.    type Table_Type is
  65.      array (Table_Index_Type range <>) of aliased Table_Component_Type;
  66.  
  67.    subtype Big_Table_Type is
  68.      Table_Type (Table_Low_Bound .. Table_Index_Type'Last);
  69.    --  We work with pointers to a bogus array type that is constrained
  70.    --  with the maximum possible range bound. This means that the pointer
  71.    --  is a thin pointer, which is more efficient. Since subscript checks
  72.    --  in any case must be on the logical, rather than physical bounds,
  73.    --  safety is not compromised by this approach.
  74.  
  75.    type Table_Ptr is access all Big_Table_Type;
  76.    --  The table is actually represented as a pointer to allow reallocation
  77.  
  78.    Table : aliased Table_Ptr := null;
  79.    --  The table itself. The lower bound is the value of Low_Bound. Logically
  80.    --  the upper bound is the current value of Last (although the actual size
  81.    --  of the allocated table may be larger than this). The program may only
  82.    --  access and modify Table entries in the range First .. Last.
  83.  
  84.    procedure Init;
  85.    --  This procedure allocates a new table of size Initial (freeing any
  86.    --  previously allocated larger table). It is not necessary to call
  87.    --  Init when a table is first instantiated (since the instantiation does
  88.    --  the same initialization steps). However, it is harmless to do so, and
  89.    --  Init is convenient in reestablishing a table for new use.
  90.  
  91.    function Last return Table_Index_Type;
  92.    pragma Inline (Last);
  93.    --  Returns the current value of the last used entry in the table, which
  94.    --  can then be used as a subscript for Table. Note that the only way to
  95.    --  modify Last is to call the Set_Last procedure. Last must always be
  96.    --  used to determine the logically last entry.
  97.  
  98.    First : constant Table_Index_Type := Table_Low_Bound;
  99.    --  Export First as synonym for Low_Bound (to be parallel with use of Last)
  100.  
  101.    procedure Set_Last (New_Val : Table_Index_Type);
  102.    pragma Inline (Set_Last);
  103.    --  This procedure sets Last to the indicated value. If necessary the
  104.    --  table is reallocated to accomodate the new value (i.e. on return
  105.    --  the allocated table has an upper bound of at least Last). If Set_Last
  106.    --  reduces the size of the table, then logically entries are removed from
  107.    --  the table. If Set_Last increases the size of the table, then new entries
  108.    --  are logically added to the table.
  109.  
  110.    procedure Increment_Last;
  111.    pragma Inline (Increment_Last);
  112.    --  Adds 1 to Last (same as Set_Last (Last + 1).
  113.  
  114.    procedure Decrement_Last;
  115.    pragma Inline (Decrement_Last);
  116.    --  Subtracts 1 from Last (same as Set_Last (Last - 1).
  117.  
  118.    function Allocate (Num : Int := 1) return Table_Index_Type;
  119.    pragma Inline (Allocate);
  120.    --  Adds Num to Last, and returns the old value of Last + 1.
  121.  
  122.    function Copy return Table_Ptr;
  123.    --  This function returns a copy of the current table contents. The length
  124.    --  of the table is determined by the current value of Last. The current
  125.    --  contents of the table, and the setting of Last, are not modified.
  126.  
  127.    procedure Free (T : in out Table_Ptr);
  128.    --  Procedure used to free a table obtained by the Copy function
  129.  
  130.    procedure Tree_Write;
  131.    --  Writes out contents of table using Tree_IO
  132.  
  133.    procedure Tree_Read;
  134.    --  Initializes table by reading contents previously written
  135.    --  with the Tree_Write call (also using Tree_IO)
  136.  
  137. end Table;
  138.