Specification of package Corba.Optimized_Sequences

 ========================================================================= --
 ===                                                                   === --
 ===                 Top Graph'X CORBA 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 Ada.Finalization;
with Ada.Streams;
package Corba.Optimized_Sequences is

   ---------------------------------------------------------------------
   
    Corba.Optimized_Sequences is the parent of the bounded and unbounded sequence
    packages.  Some exceptions and types common to both 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 Alignment is (Left, Right, Center);
   type Truncation is (Left, Right, Error);
   type Membership is (Inside, Outside);
   type Direction is (Forward, Backward);
   type Trim_End is (Left, Right, Both);
   ---------------------------------------------------------------
   
    This package provides the definitions required by the IDL-to-Ada
    mapping specification for bounded sequences.
    This package is instantiated for each IDL bounded sequence type.
    This package defines the sequence type and the operations upon it.
    This package is modelled after Ada.Strings.
   
    Most query operations are not usable until the sequence object has
    been initialized through an assignment.
   
    Value semantics apply to assignment, that is, assignment of a sequence
    value to a sequence object yields a copy of the value.
   
    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;
      Max : Positive;     Maximum length of the bounded sequence
      Align : in Positive := 1 ;  Element alignment
      with procedure Iop_Read ( Stream : access Corba_Ios.Iop_Stream_Type ;
                                Item   : out Element ) is <> ;
      with procedure Iop_Write ( Stream : access Corba_Ios.Iop_Stream_Type ;
                                 Item   : in Element ) is <> ;
   package Bounded is
      Max_Length : constant Positive := Max;
      subtype Length_Range is Natural range 0 .. Max_Length;
      type Element_Array is array (Positive range <>) of Element;
      Null_Element_Array : Element_Array (1 .. 0);

      type Sequence (Length : Length_Range := 0) is private;
      Null_Sequence : constant Sequence;

      function Length (Source : in Sequence) return Length_Range;
      type Element_Array_Access is access all Element_Array;
      procedure Free (X : in out Element_Array_Access);

      ------------------------------------------------------
       Conversion, Concatenation, and Selection Functions --
      ------------------------------------------------------
      function To_Sequence
         (Source : in Element_Array; Drop : in Truncation := Error)
         return Sequence;
      function To_Sequence (Length : in Length_Range) return Sequence;
      function To_Element_Array (Source : in Sequence) return Element_Array;

      function Append (Left, Right : in Sequence;
                        Drop : in Truncation := Error) return Sequence;
      function Append (Left : in Sequence;
                        Right : in Element_Array;
                        Drop : in Truncation := Error) return Sequence;
      function Append (Left : in Element_Array;
                        Right : in Sequence;
                        Drop : in Truncation := Error) return Sequence;
      function Append (Left : in Sequence;
                        Right : in Element;
                        Drop : in Truncation := Error) return Sequence;
      function Append (Left : in Element;
                        Right : in Sequence;
                        Drop : in Truncation := Error) return Sequence;

      procedure Append (Source : in out Sequence;
                         New_Item : in Sequence;
                         Drop : in Truncation := Error);

      procedure Append (Source : in out Sequence;
                         New_Item : in Element_Array;
                         Drop : Truncation := Error);

      procedure Append (Source : in out Sequence;
                         New_Item : in Element;
                         Drop : in Truncation := Error);

      function "&" (Left, Right : in Sequence) return Sequence;
      function "&" (Left : in Sequence; Right : in Element_Array)
         return Sequence;
      function "&" (Left : in Element_Array; Right : in Sequence)
         return Sequence;
      function "&" (Left : in Sequence; Right : in Element) return Sequence;

      function "&" (Left : in Element; Right : in Sequence) return Sequence;

      function Element_Of
         (Source : in Sequence; Index : in Positive) return Element;

      procedure Replace_Element (Source : in out Sequence;
                                  Index : in Positive;
                                  By : in Element);

      function Slice (Source : in Sequence;
                       Low : in Positive;
                       High : in Natural) return Element_Array;

      function "=" (Left, Right : in Sequence) return Boolean;

      function "=" (Left : in Element_Array; Right : in Sequence)
         return Boolean;

      function "=" (Left : in Sequence; Right : in Element_Array)
         return Boolean;

      --------------------
       Search functions --
      --------------------
      function Index (Source : in Sequence;
                       Pattern : in Element_Array;
                       Going : in Direction := Forward) return Natural;
      function Count (Source : in Sequence; Pattern : in Element_Array)
         return Natural;
      ---------------------------------------
       Sequence transformation subprograms --
      ---------------------------------------
      function Replace_Slice (Source : in Sequence;
                               Low : in Positive;
                               High : in Natural;
                               By : in Element_Array;
                               Drop : in Truncation := Error) return Sequence;

      procedure Replace_Slice (Source : in out Sequence;
                                Low : in Positive;
                                High : in Natural;
                                By : in Element_Array;
                                Drop : in Truncation := Error);

      function Insert (Source : in Sequence;
                        Before : in Positive;
                        New_Item : in Element_Array;
                        Drop : in Truncation := Error) return Sequence;

      procedure Insert (Source : in out Sequence;
                         Before : in Positive;
                         New_Item : in Element_Array;
                         Drop : in Truncation := Error);

      function Overwrite (Source : in Sequence;
                           Position : in Positive;
                           New_Item : in Element_Array;
                           Drop : in Truncation := Error) return Sequence;

      procedure Overwrite (Source : in out Sequence;
                            Position : in Positive;
                            New_Item : in Element_Array;
                            Drop : in Truncation := Error);

      function Delete (Source : in Sequence;
                        From : in Positive;
                        Through : in Natural) return Sequence;

      procedure Delete (Source : in out Sequence;
                         From : in Positive;
                         Through : in Natural);

      ---------------------------------
       Sequence selector subprograms --
      ---------------------------------
      function Head (Source : in Sequence;
                      Count : in Natural;
                      Pad : in Element;
                      Drop : in Truncation := Error) return Sequence;

      procedure Head (Source : in out Sequence;
                       Count : in Natural;
                       Pad : in Element;
                       Drop : in Truncation := Error);

      function Tail (Source : in Sequence;
                      Count : in Natural;
                      Pad : in Element;
                      Drop : in Truncation := Error) return Sequence;

      procedure Tail (Source : in out Sequence;
                       Count : in Natural;
                       Pad : in Element;
                       Drop : in Truncation := Error);

      ------------------------------------
       Sequence constructor subprograms --
      ------------------------------------
      function "*" (Left : in Natural; Right : in Element) return Sequence;
      function "*" (Left : in Natural; Right : in Element_Array)
         return Sequence;
      function "*" (Left : in Natural; Right : in Sequence) return Sequence;

      function Replicate (Count : in Natural;
                           Item : in Element;
                           Drop : in Truncation := Error) return Sequence;

      function Replicate (Count : in Natural;
                           Item : in Element_Array;
                           Drop : in Truncation := Error) return Sequence;

      function Replicate (Count : in Natural;
                           Item : in Sequence;
                           Drop : in Truncation := Error) return Sequence;

      procedure Iop_Read
         (Stream : access Corba_Ios.Iop_Stream_Type;
           Item : out Sequence);

      procedure Iop_Write
         (Stream : access Corba_Ios.Iop_Stream_Type;
           Item : in Sequence);

   private
       implementation defined
      type Sequence (Length : Length_Range := 0) is
      record
         Contents : Element_Array (1 .. Length);
      end record;

      Null_Sequence : constant Sequence :=
         (Length => 0, Contents => Null_Element_Array);
   end Bounded;


   generic
      type Element is private;
      Align : in Positive := 1 ;  Element alignment
      with procedure Iop_Read ( Stream : access Corba_Ios.Iop_Stream_Type ;
                                Item   : out Element ) is <> ;
      with procedure Iop_Write ( Stream : access Corba_Ios.Iop_Stream_Type ;
                                 Item   : in Element ) is <> ;
   package Unbounded is
      type Element_Array is array (Integer range <>) of Element;
      Null_Element_Array : Element_Array (1 .. 0);
      type Sequence is private;
      Null_Sequence : constant Sequence;
      function Length (Source : in Sequence) return Natural;
      type Element_Array_Access is access all Element_Array;
      procedure Free (X : in out Element_Array_Access);
      ------------------------------------------------------
       Conversion, Concatenation, and Selection Functions --
      ------------------------------------------------------
      function To_Sequence (Source : in Element_Array) return Sequence;
      function To_Sequence (Length : in Natural) return Sequence;
      function To_Element_Array (Source : in Sequence) return Element_Array;
      procedure Append (Source : in out Sequence; New_Item : in Sequence);
      procedure Append (Source : in out Sequence;
                         New_Item : in Element_Array);
      procedure Append (Source : in out Sequence; New_Item : in Element);
      function "&" (Left, Right : in Sequence) return Sequence;
      function "&" (Left : in Sequence; Right : in Element_Array)
         return Sequence;
      function "&" (Left : in Element_Array; Right : in Sequence)
         return Sequence;
      function "&" (Left : in Sequence; Right : in Element) return Sequence;
      function "&" (Left : in Element; Right : in Sequence) return Sequence;
      function Element_Of
         (Source : in Sequence; Index : in Positive) return Element;
      procedure Replace_Element (Source : in out Sequence;
                                  Index : in Positive;
                                  By : in Element);
      function Slice (Source : in Sequence;
                       Low : in Positive;
                       High : in Natural) return Element_Array;
      function "=" (Left, Right : in Sequence) return Boolean;
      function "=" (Left : in Element_Array; Right : in Sequence)
         return Boolean;
      function "=" (Left : in Sequence; Right : in Element_Array)
         return Boolean;
      --------------------
       Search functions --
      --------------------
      function Index (Source : in Sequence;
                       Pattern : in Element_Array;
                       Going : in Direction := Forward) return Natural;
      function Count (Source : in Sequence; Pattern : in Element_Array)
         return Natural;
      ---------------------------------------
       Sequence transformation subprograms --
      ---------------------------------------
      function Replace_Slice (Source : in Sequence;
                               Low : in Positive;
                               High : in Natural;
                               By : in Element_Array) return Sequence;
      procedure Replace_Slice (Source : in out Sequence;
                                Low : in Positive;
                                High : in Natural;
                                By : in Element_Array);
      function Insert (Source : in Sequence;
                        Before : in Positive;
                        New_Item : in Element_Array) return Sequence;
      procedure Insert (Source : in out Sequence;
                         Before : in Positive;
                         New_Item : in Element_Array);
      function Overwrite (Source : in Sequence;
                           Position : in Positive;
                           New_Item : in Element_Array) return Sequence;
      procedure Overwrite (Source : in out Sequence;
                            Position : in Positive;
                            New_Item : in Element_Array);
      function Delete (Source : in Sequence;
                        From : in Positive;
                        Through : in Natural) return Sequence;
      procedure Delete (Source : in out Sequence;
                         From : in Positive;
                         Through : in Natural);
      ---------------------------------
       Sequence selector subprograms --
      ---------------------------------
      function Head (Source : in Sequence;
                      Count : in Natural;
                      Pad : in Element) return Sequence;
      procedure Head (Source : in out Sequence;
                       Count : in Natural;
                       Pad : in Element);
      function Tail (Source : in Sequence;
                      Count : in Natural;
                      Pad : in Element) return Sequence;
      procedure Tail (Source : in out Sequence;
                       Count : in Natural;
                       Pad : in Element);
      ------------------------------------
       Sequence constructor subprograms --
      ------------------------------------
      function "*" (Left : in Natural; Right : in Element) return Sequence;
      function "*" (Left : in Natural; Right : in Element_Array)
         return Sequence;
      function "*" (Left : in Natural; Right : in Sequence) return Sequence;

      procedure Iop_Read
         (Stream : access Corba_Ios.Iop_Stream_Type;
           Item : out Sequence);

      procedure Iop_Write
         (Stream : access Corba_Ios.Iop_Stream_Type;
           Item : in Sequence);

       Low level access, use with extreme care
      function To_Element_Array_Access (Source : in Sequence) return Element_Array_Access;
   private
       ... implementation defined ...

      type Ref_Counted_Element_Array (Length : Natural) is
      record
         Used      : Natural := 0 ;
         Ref_Count : Natural := 1;
         Table     : Element_Array_Access := new Element_Array (1 .. Length);
      end record;

      type Ref_Counted_Element_List is access all Ref_Counted_Element_Array;

      type Real_Sequence is new Ada.Finalization.Controlled with
      record
         Data : Ref_Counted_Element_List;
      end record;

      pragma Finalize_Storage_Only (Real_Sequence) ;

      function "=" (Left, Right : in Real_Sequence) return Boolean ;

      procedure Adjust (Object : in out Real_Sequence);

      procedure Finalize (Object : in out Real_Sequence);

      Null_Real_Sequence : constant Real_Sequence :=
         ( Ada.Finalization.Controlled with Data => null) ;

      type Sequence is
      record
         Real : Real_Sequence ;
      end record ;

      Null_Sequence : constant Sequence :=
         (Real => ( Ada.Finalization.Controlled with Data => null)) ;
   end Unbounded;
end Corba.Optimized_Sequences;

List of definition uses