Specification of package Tgx.Lists







 ========================================================================= --
 ===                                                                   === --
 ===                 Top Graph'X X Ada95  Implementation               === --
 ===                                                                   === --
 ===                 Copyright (c) 1996, Top Graph'X.                  === --
 ===                                                                   === --
 ===                     --- Copyright Notice ---                      === --
 ===                                                                   === --
 ===    This software is protected as an unpublished work under the    === --
 ===     Copyright Act of 1976.  All rights reserved.  Top Graph'X.    === --
 ===                                                                   === --
 ========================================================================= --

with System ;
with Ada.Finalization ;
package Tgx.Lists is

   ---------------------------------------------------------------------
   
     Some exceptions and types are declared here
    ( following the structure of Ada.Strings).
   
    Length_Error is raised when sequence lengths are exceeded.
    Pattern_Error is raised when a null pattern string is passed.
    Index_Error is raised when indexes are out of range.
   
   ---------------------------------------------------------------------
   Length_Error, Pattern_Error, Index_Error : exception;
   type Direction is (Forward, Backward);
   subtype Element_Range is Natural range 0 .. 2_000_000_000 ;
   subtype Positive_Range is Element_Range range 1 .. Element_Range'last ;
   ---------------------------------------------------------------
   
    This package defines the sequence type and the operations upon it.
    This package is modelled after Ada.Strings.Unbounded
   
    Most query operations are not usable until the sequence object has
    been initialized through an assignment.
   
    Reference counting semantics apply to assignment, that is, assignment of
    a sequence value to a sequence object increments the reference
    counter of the value. Hopefully, modification of a sequence object
    create a unique copy of the sequence. This reduces memory consumption,
    speeds up assignment, and duplicates the data only when needed.
   
    The exception Index_Error is raised when indexes are not in the range
    of the object being manipulated.
   
    The exception Constraint_Error is raised when objects that have not
    been initalized or assigned to are manipulated.
   
   -----------------------------------------------------------------

   generic
      type Element is private;
      Null_Element   : in Element ;
   package Simple_Lists is
      type Element_Array is array (Element_Range range <>) of Element;
      Null_Element_Array : Element_Array (1 .. 0);
      type List is private;
      Null_List : constant List;

      type Element_Array_Access is access all Element_Array;
      procedure Free (X : in out Element_Array_Access);

      function Is_Null (Source : in List) return Boolean;
      function Length (Source : in List) return Element_Range;

      --------------------------------------
       Conversion and Selection Functions --
      --------------------------------------
      function To_List (Source : in Element_Array) return List;
      function To_List (Length : in Element_Range) return List;
      function To_Element_Array (Source : in List) return Element_Array;
      procedure Append (Source : in out List; New_Item : in List);
      procedure Append ( Source   : in out List;
                         New_Item : in Element_Array);
      procedure Append (Source : in out List; New_Item : in Element);
      function Element_Of
         (Source : in List; Index : in Positive_Range) return Element;
      function Slice ( Source : in List;
                       Low    : in Positive_Range;
                       High   : in Element_Range) return Element_Array;
      function "=" (Left, Right : in List) return Boolean;
      function "=" (Left : in Element_Array; Right : in List)
         return Boolean;
      function "=" (Left : in List; Right : in Element_Array)
         return Boolean;

      --------------------
       Search functions --
      --------------------
      function Index ( Source  : in List;
                       Pattern : in Element_Array;
                       Going   : in Direction := Forward) return Element_Range;
      function Count (Source : in List; Pattern : in Element_Array)
         return Element_Range;

      ---------------------
       Destroy functions --
      ---------------------
      procedure Delete (Source : in out List) ;

      ---------------------
       Edition functions --
      ---------------------
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Item : in out Element ;
                              Context : in out Context_Type ) ;
      procedure Update ( Source  : in out List_Type ;
                         Index   : in Positive_Range ;
                         Context : in out Context_Type) ;

      ---------------------
       Iterators         --
      ---------------------
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Item : in Element ;
                              Context : in out Context_Type ) ;
      procedure Do_On_All ( Source : in List_Type ;
                            Context : in out Context_Type) ;
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Item : in out Element ;
                              Context : in out Context_Type ) ;
      procedure Update_All ( Source : in out List_Type ;
                             Context : in out Context_Type) ;

      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Items : in Element_Array ;
                              Context : in out Context_Type ) ;
      procedure Do_On_Range ( Source : in List_Type ;
                              First  : in Positive_Range ;
                              Last   : in Element_Range ;
                              Context : in out Context_Type) ;
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Items : in out Element_Array ;
                              Context : in out Context_Type ) ;
      procedure Update_Range ( Source : in out List_Type ;
                               First  : in Positive_Range ;
                               Last   : in Element_Range ;
                               Context : in out Context_Type) ;
      -------------------
       Raw data access --
      -------------------
      procedure Data_Address ( Source    : in out List;
                               Raw       : out System.Address ;
                               Read_Only : in Boolean) ;
   private
      type Ref_Counted_Element_Array (Length : Element_Range) is
      record
         Used      : Element_Range := 0 ;
         Ref_Count : Element_Range := 1 ;
         Table     : aliased Element_Array (1 .. Length) ;
      end record ;

      type Ref_Counted_Element_List is access all Ref_Counted_Element_Array ;

      type Real_List is new Ada.Finalization.Controlled with
      record
         Data : Ref_Counted_Element_List := null;
      end record ;

      procedure Adjust (Object : in out Real_List) ;

      procedure Finalize (Object : in out Real_List) ;

      pragma Finalize_Storage_Only (Real_List) ;

      type List is
      record
         Real : Real_List ;
      end record ;

      Null_List : constant List := ( Real => ( Ada.Finalization.Controlled with
                                               Data => null)) ;
   end Simple_Lists;

   generic
      type Element is private;
      Null_Element   : in Element ;
      Size_Increment : in Positive := 8 ;
   package Editable_Lists is
      type Element_Array is array (Element_Range range <>) of Element;
      Null_Element_Array : Element_Array (1 .. 0);
      type List is private;
      Null_List : constant List;

      type Element_Array_Access is access all Element_Array;
      procedure Free (X : in out Element_Array_Access);

      function Is_Null (Source : in List) return Boolean;
      function Length (Source : in List) return Element_Range;

      ------------------------------------------------------
       Conversion, Concatenation, and Selection Functions --
      ------------------------------------------------------
      function To_List (Source : in Element_Array) return List;
      function To_List (Length : in Element_Range) return List;
      function To_Element_Array (Source : in List) return Element_Array;
      procedure Append (Source : in out List; New_Item : in List);
      procedure Append ( Source   : in out List;
                         New_Item : in Element_Array);
      procedure Append (Source : in out List; New_Item : in Element);
      function "&" (Left, Right : in List) return List;
      function "&" (Left : in List; Right : in Element_Array)
         return List;
      function "&" (Left : in Element_Array; Right : in List)
         return List;
      function "&" (Left : in List; Right : in Element) return List;
      function "&" (Left : in Element; Right : in List) return List;
      function Element_Of
         (Source : in List; Index : in Positive_Range) return Element;
      procedure Replace_Element ( Source : in out List;
                                  Index  : in Positive_Range;
                                  By     : in Element);
      function Slice ( Source : in List;
                       Low    : in Positive_Range;
                       High   : in Element_Range) return Element_Array;
      function "=" (Left, Right : in List) return Boolean;
      function "=" (Left : in Element_Array; Right : in List)
         return Boolean;
      function "=" (Left : in List; Right : in Element_Array)
         return Boolean;

      --------------------
       Search functions --
      --------------------
      function Index ( Source  : in List;
                       Pattern : in Element_Array;
                       Going   : in Direction := Forward) return Element_Range;
      function Count (Source : in List; Pattern : in Element_Array)
         return Element_Range;

      -----------------------------------
       List transformation subprograms --
      -----------------------------------
      function Replace_Slice ( Source : in List;
                               Low    : in Positive_Range;
                               High   : in Element_Range;
                               By : in Element_Array) return List;
      procedure Replace_Slice ( Source : in out List;
                                Low    : in Positive_Range;
                                High   : in Element_Range;
                                By     : in Element_Array);
      function Insert ( Source   : in List;
                        Before   : in Positive_Range;
                        New_Item : in Element_Array) return List;
      procedure Insert ( Source   : in out List;
                         Before   : in Positive_Range;
                         New_Item : in Element_Array);
      function Overwrite ( Source   : in List;
                           Position : in Positive_Range;
                           New_Item : in Element_Array) return List;
      procedure Overwrite ( Source   : in out List;
                            Position : in Positive_Range;
                            New_Item : in Element_Array);
      function Delete ( Source  : in List;
                        From    : in Positive_Range;
                        Through : in Element_Range) return List;
      procedure Delete ( Source  : in out List;
                         From    : in Positive_Range;
                         Through : in Element_Range);

      ---------------------
       Destroy functions --
      ---------------------
       Delete the whole list
      procedure Delete (Source : in out List) ;
       Empty the list without deallocating memory
      procedure Clear (Source : in out List) ;

      -----------------------------
       List selector subprograms --
      -----------------------------
      function Head ( Source : in List;
                      Count  : in Element_Range;
                      Pad    : in Element) return List;
      procedure Head ( Source : in out List;
                       Count  : in Element_Range;
                       Pad    : in Element);
      function Tail ( Source : in List;
                      Count  : in Element_Range;
                      Pad    : in Element) return List;
      procedure Tail ( Source : in out List;
                       Count  : in Element_Range;
                       Pad    : in Element);

      --------------------------------
       List constructor subprograms --
      --------------------------------
      function "*" (Left : in Element_Range; Right : in Element) return List;
      function "*" (Left : in Element_Range; Right : in Element_Array)
         return List;
      function "*" (Left : in Element_Range; Right : in List) return List;
       Preallocate memory for a list (extend current size only if needed)
      procedure Allocate ( Source : in out List ;
                           Size   : in Positive_Range) ;

      ---------------------
       Edition functions --
      ---------------------
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Item : in out Element ;
                              Context : in out Context_Type ) ;
      procedure Update ( Source  : in out List_Type ;
                         Index   : in Positive_Range ;
                         Context : in out Context_Type) ;

      ---------------------
       Iterators         --
      ---------------------
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Item : in Element ;
                              Context : in out Context_Type ) ;
      procedure Do_On_All ( Source : in List_Type ;
                            Context : in out Context_Type) ;
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Item : in out Element ;
                              Context : in out Context_Type ) ;
      procedure Update_All ( Source : in out List_Type ;
                             Context : in out Context_Type) ;

      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Items : in Element_Array ;
                              Context : in out Context_Type ) ;
      procedure Do_On_Range ( Source : in List_Type ;
                              First  : in Positive_Range ;
                              Last   : in Element_Range ;
                              Context : in out Context_Type) ;
      generic
         type List_Type is new List ;
         type Context_Type is private ;
         with procedure Job ( Items : in out Element_Array ;
                              Context : in out Context_Type ) ;
      procedure Update_Range ( Source : in out List_Type ;
                               First  : in Positive_Range ;
                               Last   : in Element_Range ;
                               Context : in out Context_Type) ;

      -------------------
       Raw data access --
      -------------------
      procedure Data_Address ( Source    : in out List;
                               Raw       : out System.Address ;
                               Read_Only : in Boolean) ;
   private
      type Ref_Counted_Element_Array (Length : Element_Range) is
      record
         Used      : Element_Range := 0 ;
         Ref_Count : Element_Range := 1 ;
         Table     : aliased Element_Array (1 .. Length) ;
      end record ;

      type Ref_Counted_Element_List is access all Ref_Counted_Element_Array ;

      type Real_List is new Ada.Finalization.Controlled with
      record
         Data : Ref_Counted_Element_List := null;
      end record ;

      pragma Finalize_Storage_Only (Real_List) ;

      procedure Adjust (Object : in out Real_List) ;

      procedure Finalize (Object : in out Real_List) ;

      type List is
      record
         Real : Real_List ;
      end record ;

      Null_List : constant List := ( Real => ( Ada.Finalization.Controlled with
                                               Data => null)) ;
   end Editable_Lists;
end Tgx.Lists;



List of definition uses










This page was generated by PrismTech's ada2html on Friday Mai 12 2006 16:18