--------------------------------- COPYRIGHT ------------------------------------
-- (C) 1986 Swiss Federal Institute of Technology (EPFL).                     --
--     Represented by A. Strohmeier DMA-EPFL 1015 Lausanne Switzerland.       --
--     All Rights Reserved.                                                   --
--------------------------------------------------------------------------------

--+ TITLE:      PACKAGE FOR STORED STRINGS OF VARIABLE LENGTH.
--+ SUPPORT:    S.R.Y. Louboutin, CGL-DMA-EPFL 1015 LAUSANNE.
--+ APPROVAL:   16-APR-87 C. Genillard
--+ REVISION 1: 04-APR-87 A. Strohmeier, Suppression of the subprograms with
--+ parameter or result of type V_STRING.
--+ CREATION:   10-SEP-86 F. Mercier.

package Stored_String is
------------------------
--+ OVERVIEW:
--+   This package implements the type S_STRING (stored string of variable
--+ length). This type is especially designed for storing a string using the
--+ exact required space. When declared, an S_STRING has an implicit initial
--+ value of a null string.
--+ REQUIREMENT:
--+   Every S_STRING, which is not null,  must be destroyed when it is no
--+ longer used (especially at the end of the object scope). Otherwise storage
--+ space may be lost.

--+ PRIMITIVES:
--+   CONSTRUCTORS:
--+     CREATE (2)
--+     ASSIGN
--+   QUERIES:
--+     IS_EMPTY
--+     LENGTH
--+     TO_STRING
--+     "<" (3)
--+     ">" (3)
--+     "<=" (3)
--+     ">=" (3)
--+     "="
--+     EQUAL (3)
--+   HEAP MANAGEMENT:
--+     DESTROY

    type S_String is limited private;


--/ CONSTRUCTORS:

    procedure Create (Destination : in out S_String; Source : in Character);
    procedure Create (Destination : in out S_String; Source : in String);
    --+ OVERVIEW:
    --+   Destroys DESTINATION and then puts the value of SOURCE into
    --+ DESTINATION.

    procedure Assign (Destination : in out S_String; Source : in S_String);
    --+ OVERVIEW:
    --+   Destroys DESTINATION and then copies SOURCE into DESTINATION.

--/ QUERIES:

    function Is_Empty (Source : S_String) return Boolean;
    --+ OVERVIEW:
    --+   Tests if SOURCE is a null string.

    function Length (Source : S_String) return Natural;
    --+ OVERVIEW:
    --+   Returns the actual length of SOURCE.

    function To_String (Source : S_String) return String;
    --+ OVERVIEW:
    --+   Converts a S_STRING into a STRING.

    function "<" (Left : S_String; Right : S_String) return Boolean;
    function "<" (Left : S_String; Right : String) return Boolean;
    function "<" (Left : String; Right : S_String) return Boolean;
    pragma Inline ("<");

    function "<=" (Left : S_String; Right : S_String) return Boolean;
    function "<=" (Left : S_String; Right : String) return Boolean;
    function "<=" (Left : String; Right : S_String) return Boolean;
    pragma Inline ("<=");

    function ">" (Left : S_String; Right : S_String) return Boolean;
    function ">" (Left : S_String; Right : String) return Boolean;
    function ">" (Left : String; Right : S_String) return Boolean;
    pragma Inline (">");

    function ">=" (Left : S_String; Right : S_String) return Boolean;
    function ">=" (Left : S_String; Right : String) return Boolean;
    function ">=" (Left : String; Right : S_String) return Boolean;
    pragma Inline (">=");
    --+ OVERVIEW:
    --+   Lexicographic order comparisons.

    function "=" (Left, Right : S_String) return Boolean;
    pragma Inline ("=");

    function Equal (Left : S_String; Right : S_String) return Boolean;
    function Equal (Left : S_String; Right : String) return Boolean;
    function Equal (Left : String; Right : S_String) return Boolean;
    pragma Inline (Equal);
    --+ OVERVIEW:
    --+   Equality of strings.

--/ HEAP MANAGEMENT:

    procedure Destroy (Source : in out S_String);
    pragma Inline (Destroy);

private

    type Access_String is access String;
    type S_String is new Access_String;
    --+ NOTE:
    --+   Derivation of a new type is needed to distinguish operator "="
    --+ predefined for the access type from operator "=" defined by the package
    --+ for objects of type S_STRING.

end Stored_String;