DataMuseum.dk

top - download

    Length: 20164 (0x4ec4)
    Types: TextFile
    Names: »A_DOCUMENTATION«

└─⟦85b835f43⟧ Bits:30000549 8mm tape, Rational 1000, Xlib rev 6.00
    └─ ⟦0c20f784e⟧ »DATA« 
        └─⟦1abbe589f⟧ 
            └─⟦591c5b094⟧ 
                └─⟦this⟧ 

TextFile

------------------------------------------------------------------------------
-- Copyright 1988 - 1991 by Rational, Santa Clara, California.
--
--                  All Rights Reserved.
--
-- Permission to use, copy, modify, and distribute this software and its
-- documentation for any purpose and without fee is hereby granted,
-- provided that the above copyright notice(s) appear in all copies and that
-- both that copyright notice(s) and this permission notice appear in
-- supporting documentation, and that the name of Rational not be used in
-- advertising or publicity pertaining to distribution of the software
-- without specific, written prior permission.
--
-- Rational disclaims all warranties with regard to this software, including
-- all implied warranties of merchantability and fitness, in no event shall
-- Rational be liable for any special, indirect or consequential damages or
-- any damages whatsoever resulting from loss of use, data or profits, whether
-- in an action of contract, negligence or other tortious action, arising out
-- of or in connection with the use or performance of this software.
------------------------------------------------------------------------------

                               VString Library
                               ------- -------

                               Gary E. Barnes

                                  03/29/88

------------------------------------------------------------------------------
Table Of Contents
------------------------------------------------------------------------------

1)  Location
2)  Purpose
3)  Packages
4)  Vstring           - Vstring_Type
5)  Allocation        - Vstring_Heap
6)  Simple Operations - Vstring_Query
7)  I/O               - Vstring_Io
8)  Assignment        - Vstring_Assign
9)  Equality          - Vstring_Equal
10) Comparison        - Vstring_Compare
11) U/L Case          - Vstring_Case
12) Scanning          - Vstring_Case

------------------------------------------------------------------------------
1) Location
------------------------------------------------------------------------------

!X11.X_Tools.RevNN_Working.Units.Vstring

This directory contains all of the code and data used by the Vstring library. 
It can be expected to live on my home machine at any given date.  New
functionality will be added in the future as time and need permits.

------------------------------------------------------------------------------
2)  Purpose
------------------------------------------------------------------------------

The R1000 environment has several string packages of differing sorts.  They
are generally mediocre and have extremely sparse and uninteresting interfaces.
This led to the VString Library.  The intent is to have a single library that
implements a set of string operations that are sufficiently "interesting" as
to allow the creation of nontrivial string processing programs.

Goal: A library that will run reasonably on an R1000.

Goal: A library that would allow the construction of a compiler's lexical
      phase trivially in at most one day.

Goal: A library that allows for arbitrarily sized strings with an absolute
      minimum of programmer pain while trying not to grow heaps with great
      abandon.
      
Goal: A complete system; all of the common operators; I/O; at least simple
      pattern matching.

Goal: A library that is portable to all Ada compilers.

The VString Library implements a variable length string type.  Each Vstring
object, whether allocated as a local variable or as a heap object has a fixed
maximum string length and a variable current length.  Many of the Vstring
operations have two forms.  One form truncates the result to fit into the
destination Vstring and the other form reallocates (if necessary) a heap-based
Vstring destination.

------------------------------------------------------------------------------
3)  Packages
------------------------------------------------------------------------------

Vstring_Type    - Defines Vstring_Data and Vstring types.
Vstring_Assign  - Assign, Append, Prepend operations.
Vstring_Case    - Case changes for characters and Vstrings.    
Vstring_Compare - Compare strings for <, >, =, <=, >=, /=; with(out) case. 
Vstring_Equal   - Compare strings or string prefixes for equality;
                  with(out)case.   
Vstring_Heap    - (De)Allocate or Resize Vstring heap objects.    
Vstring_Io      - Input/Output of Vstring objects.      
Vstring_Query   - Query on Vstring objects; length, contents, character
                  lopping, substringing.   
Vstring_Scan    - Scanning (form of simple pattern matching) of Vstrings.    

------------------------------------------------------------------------------
4)  Vstring - Vstring_Type
------------------------------------------------------------------------------

The Vstring_Data type is the basic record that describes a Vstring object.  It
can be used to declare a local variable in those situations where speed is of
the essence or where there is a known maximum possible length to the strings
being processed.

The Vstring type is an ACCESS Vstring_Data type.  It is used to refer to
heap-based Vstring objects.

Vstrings have two fields.  The Length field contains a value in the range of
0..Maximum_Length.  This is the current length of the string.  Maximum_Length
is the length limit placed upon the Vstring when it was declared/allocated.

The Chars field is an array of 1..Maximum_Length characters.  At any given
time the string value of a Vstring object named AA is AA.Chars(1..AA.Length).

------------------------------------------------------------------------------
5)  Allocation - Vstring_Heap
------------------------------------------------------------------------------

Vstrings are either stack or heap based.  The stack based Vstrings are
variables declared using the Vstring_Data type.  These variables have a fixed
maximum length that cannot change as the program executes.  They have an
advantage over heap-based Vstrings in that they are allocated and deallocated
quickly and automatically.  They have a disadvantage compared to heap-based
Vstrings in that they cannot be reallocated with a larger size.

If speed is critical and some maximum-possible-ever size is known then use of
Vstring_Data variables is the way to go.  Most Vstring operations are
overloaded to take either Vstring or Vstring_Data variables.  The "Resize"
form of the various operations cannot take Vstring_Data objects as
destinations because they cannot be reallocated from the heap.

An alternative to local Vstring_Data variables are Vstring heap objects that
are "global" to a processing scope.  They are kept alive by an outer execution
scope and reused as needed.  This allows them to grow to whatever size is
necessary. 

------------------------------------------------------------------------------
6)  Simple Operations - Vstring_Query
------------------------------------------------------------------------------

    Empty_String( Vstr );

Sets the Vstr to the "empty"/null-string state.

    I := Length( Vstr );

Returns the current length of the Vstr.  Same as Vstr.Length.

    I := Maximum_Length( Vstr );

Returns the maximum length of the Vstr.  Same as Vstr.Maximum_Length.

    I := Length_Left( Vstr );

Returns the amount of unused space remaining in the Vstr.  Same as
Vstr.Maximum_Length - Vstr.Length.

    C := Char_At( Vstr, I );

Returns the I'th character in the Vstr.  Same as Vstr.Chars(I) except that it
returns Ascii.Nul if the I'th character does not exist.

    C := First( Vstr );

Returns the first character in the Vstr.  Same as Char_At(Vstr,1).

    C := Lop_First( Vstr );

Removes and returns the first character in the Vstr.  Returns Ascii.Nul if the
Vstr is empty.  Reduces the length of the string by one.

    C := Last( Vstr );

Returns the last character in the Vstr.  Same as Char_At(Vstr,Length(Vstr)) if
Length(Vstr) >= 1.  Returns Ascii.Nul if Vstr is empty.

    C := Lop_Last( Vstr );

Removes and returns the last character in the Vstr.  Returns Ascii.Nul if the
Vstr is empty.  Reduces the length of the string by one.

    S : constant e_string := Substring_To( Vstr, From, To );

Returns an Ada string corresponding to the From..To substring of the Vstr.  If
From > Length(Vstr) then the return value is "".  If To > Length(Vstr) then
the substring From..Length(Vstr) is returned.

    Truncstring_To( Vstr, From, To );

Same as Assign( Vstr, Substring_To( Vstr, From, To ) );.  Changes the contents
of the Vstr so that it contains only the From..To substring of its original
contents.

    S : constant e_string := Substring_For( Vstr, From, For );

Returns an Ada string corresponding to the substring of the Vstr starting at
character From and extending For characters; the From..From-1+For substring. 
If From > Length(Vstr) then the return value is "".  If From-1+For is >
Length(Vstr) then the substring From..Length(Vstr) is returned. 

    Truncstring_For( Vstr, From, For );

Same as Assign( Vstr, Substring_For( Vstr, From, For ) );.  Changes the
contents of the Vstr so that it contains only the From..From-1+For of its
original contents.

    S : constant e_string := To_String( Vstr );

Returns the contents of the Vstr as an Ada string.
Assign( Vstr, To_String(Vstr) ); is a no-op.

------------------------------------------------------------------------------
7)  I/O - Vstring_Io
------------------------------------------------------------------------------

    Get( File, Vstr, End_Of_Line, End_Of_Page, End_Of_File );

Returns the next line from the input file.  As much of the next line as will
fit into the Vstr is read.  Any unread portion of the next line will remain to
be read in the next Get.  The End_Of_@ flags are set to indicate the
conditions that terminated the reading.

    Get_Resize( File, Vstr, Resize_Amout,
                End_Of_Line, End_Of_Page, End_Of_File );

Just like Get up above but it only takes a Vstring; not a Vstring_Data.  If
the line does not fit in the Vstr then the Vstr is reallocated in a larger
size.  The size of the Vstr is increased in Resize_Amount increments until the
line will fit.

    Put     ( Vstr );
    Put_Line( Vstr );
    Put     ( File, Vstr );
    Put_Line( File, Vstr );

Puts the contents of a Vstr onto Standard_Output or to a specific output file.

------------------------------------------------------------------------------
8)  Assignment - Vstring_Assign
------------------------------------------------------------------------------

There are three types of Vstring assignment.

Assign  - replaces the contents of a Vstring.

Append  - increases the length of a Vstring and places new characters at the
          end of the existing string.

Prepend - increases the length of a Vstring and places new characters as the
          beginning of the existing string. 

Each form uses the source and destination contents to form a new value which
is assigned to the destination; the new value is truncated as necessary to
make it fit. 

    Assign( Vstr1, Vstr2 );         -- Vstr1 := Vstr2
    Assign( Vstr1, Str );           -- Vstr1 := Ada string literal
    Assign( Vstr1, Char );          -- Vstr1 := Ada character
    Assign( Vstr1, Char, Copies );  -- Vstr1 := (1..Copies => Char)

The former contents of Vstr1 are replaced by a string whose source is one of:
another Vstring, an Ada string, and Ada character, or a series of an Ada
character.  If the new data is longer than Vstr1.Maximum_Length then it is
truncated on the end. 

    Append( Vstr1, Vstr2 );         -- Vstr1 := Vstr1 & Vstr2
    Append( Vstr1, Str );           -- Vstr1 := Vstr1 & Ada string literal
    Append( Vstr1, Char );          -- Vstr1 := Vstr1 & Ada character
    Append( Vstr1, Char, Copies );  -- Vstr1 := Vstr1 & (1..Copies => Char)

The former contents of Vstr1 are extended on the end with new data.  The final
length of Vstr1 is MIN(Vstr1.Maximum_Length, Vstr1.Length+New_Data'Length).
If all of the new data cannot be accomodated then it will be truncated on the
end.  Same as Assign( Vstr, To_String(Vstr) & New_Data );. 

    Prepend( Vstr1, Vstr2 );         -- Vstr1 := Vstr2 & Vstr1
    Prepend( Vstr1, Str );           -- Vstr1 := Ada string literal & Vstr1
    Prepend( Vstr1, Char );          -- Vstr1 := Ada character & Vstr1
    Prepend( Vstr1, Char, Copies );  -- Vstr1 := (1..Copies => Char) & Vstr1

The former contents of Vstr1 are extended at the front with new data.  Same as
Assign( Vstr, New_Data & To_String(Vstr) );.  The final length of Vstr1 is
MIN(Vstr1.Maximum_Length, Vstr1.Length+New_Data'Length);.  The original
contents of Vstr1 can be pushed-off-the-end and lost if the New_Data is more
than can be accomodated in Length_Left(Vstr1) characters.

    Append_Resize( Vstr1, Vstr2, Resize_Amount );  -- Vstr1 := Vstr1 & Vstr2

Just like Append except that the Vstr1 must be a heap-base Vstring object.  If
Vstr1.Maximum_Length cannot accomdate the new Vstr2 data then Vstr1 will be
reallocated by N*Resize_Amount characters so that it can accomodate both the
old and the new characters.

------------------------------------------------------------------------------
9)  Equality - Vstring_Equal
------------------------------------------------------------------------------

"=" operations.  These are faster than the more general Comparison operations.

    Equal( Vstr1, Vstr2 )           -- Vstr1 = Vstr2
    Equal( Vstr1, Str )             -- Vstr1 = Ada string literal
    Equal( Vstr1, Char )            -- Vstr1 = Ada character
    Equal( Vstr1, Char, Copies )    -- Vstr1 = (1..Copies => Char)

Returns TRUE if the two operands contain the same characters.  "a" /= "A".

    Uc_Equal( Vstr1, Vstr2 )        -- Vstr1 = Vstr2
    Uc_Equal( Vstr1, Str )          -- Vstr1 = Ada string literal
    Uc_Equal( Vstr1, Char )         -- Vstr1 = Ada character
    Uc_Equal( Vstr1, Char, Copies ) -- Vstr1 = (1..Copies => Char)

Returns TRUE if the two operands contain the same characters ignoring case.
"a" = "A".

    Equal_Prefix( Vstr1, Str )      -- Vstr1(1..Str'Length) = Str
    Uc_Equal_Prefix( Vstr1, Str )   -- Vstr1(1..Str'Length) = Str

Returns TRUE if the Str'Length prefix characters of the Vstring are the same
as the contents of the Ada string literal; with or without case.

------------------------------------------------------------------------------
10) Comparison - Vstring_Compare
------------------------------------------------------------------------------

    Compare( Vstr1, Vstr2 ) = 0     -- Vstr1 = Vstr2
    Compare( Vstr1, Vstr2 ) < 0     -- Vstr1 < Vstr2
    Compare( Vstr1, Vstr2 ) > 0     -- Vstr1 > Vstr2
    Compare( Vstr1, Str )           -- Compare Vstr1 to Ada string literal
    Compare( Vstr1, Char )          -- Compare Vstr1 to (1 => Char)
    Compare( Vstr1, Char, Copies )  -- Compare Vstr1 to (1..Copies => Char)

Returns 0 for equality between arguments; negative for Vstr1 less than the
other argument; and positive for Vstr1 greater than the other argument.  "<="
and ">=" can be used as well as "=", "<", and ">".  This is not a caseless
comparison; "a" > "A".

------------------------------------------------------------------------------
11) U/L Case - Vstring_Case
------------------------------------------------------------------------------

    Uc_Char : constant Array (Character) of Character;
    Lc_Char : constant Array (Character) of Character;

Arrays useful for converting single characters to their Upper-Case or
Lower-Case form.

    Upper_Case( Vstr );
    Lower_Case( Vstr );

Converts all characters in the Vstr to upper or lower case.

    S : constant e_string := Upper_Case( Str );
    S : constant e_string := Lower_Case( Str );

Returns a string which is the upper/lower case form of its Ada string literal
argument.

------------------------------------------------------------------------------
12) Scanning - Vstring_Case
------------------------------------------------------------------------------

Scanning is a simple form of pattern matching.  The basic idea is to scan a
Source string, removing characters one at a time, and place the scanned
characters into a Destination string.  As characters are scanned they are
filtered.

Scanning filters for Vstrings are implemented using Breaksets.  A Breakset is
an array of Scan_Actions.  There is one Scan_Action for each Ascii character. 
A Scan begins with the first character in a Vstring and it proceeds until some
character in the Vstring activates a Scan_Action that terminates the scan or
until the last character in the Vstring has been scanned.

The possible Scan_Actions are:
    Sa_Transfer             - Copy character Src => Dest
    Sa_Skip                 - Discard the Src character
    Sa_Transfer_Uc          - Copy character Uc_Char(Src) => Dest
    Sa_Transfer_Lc          - Copy character Lc_Char(Src) => Dest
    Sa_Transfer_Break       - Copy charcter Src => Des and stop scan
    Sa_Transfer_Uc_Break    - Copy character Uc_Char(Src) => Dest and stop scan
    Sa_Transfer_Lc_Break    - Copy character Lc_Char(Src) => Dest and stop scan
    Sa_Skip_Break           - Discard the Src character and stop scan
    Sa_Retain_Break         - Retain Src character in Src string and stop scan

Breaksets are usually initialized with the Set_Breakset routine.

    Set_Breakset( Brk, Break, Omit, Mode );

Initializes the Brk Breakset.  The characters contained in the Break string
will be marked as characters that terminate a scan.  The characters in the
Omit string will be marked as characters which are discarded during a scan. 
The Mode string contains any combination of the following mode characters,
upper/lower case do not matter and if two mutually exclusive operations are
requested then the last one to appear "wins":

    I - Break contains characters that stop the scan (Inclusive scan)
    X - Break contains characters that don't stop the scan (eXclusive scan)
    A - Append the break'ing character to Dest and stop
    R - Retain the break'ing character to Dest and stop
    S - Skip (drop) break character and stop
    U - convert characters to Upper case as they are copied
    L - convert characters to Lower case as they are copied
    
There are a variety of scanning functions.  Scan assigns scanned characters to
the destination.  Append_Scan appends scanned characters to the destination. 
And, Trunc_Scan simply discards all scanned characters.

    Scan( To, From, Brk, Break_Char );

Scans the From string and assigns the scanned characters to To.  The scanned
characters are removed from From.  The character that terminated the scan is
returned in Break_Char.  Ascii.Nul is returned if the scan terminated because
the end of From was reached.

    Append_Scan( To, From, Brk, Break_Char );

Scans the From string and appends the scanned characters to To.  The scanned
characters are removed from From.  The character that terminated the scan is
returned in Break_Char.  Ascii.Nul is returned if the scan terminated because
the end of From was reached.

    Trunc_Scan( From, Brk, Break_Char );

Scans the From string and discards all scanned characters; equivalent to
scanning a Vstring with a To whose Maximum_Length is zero.  The scanned
characters are removed from From.  The character that terminated the scan is
returned in Break_Char.  Ascii.Nul is returned if the scan terminated because
the end of From was reached.

Examples:

    function Scan_Id( Vstr : Vstring ) return String is
        White_Space : Breakset;
        Identifier  : Breakset;
        Break       : Character;
        Id          : Vstring_Data(256);
    begin
        Set_Breakset( White_Space, " " & Ascii.Ht, "", "XR" );
        Set_Breakset( Identifier, "ABCDEFGHIJKLMNOPQRSTUVWXYZ" &
                                  "abcdefghijklmnopqrstuvwxyz" &
                                  "0123456789" &
                                  "_" , "", "XR" );
        Trunc_Scan( Vstr, White_Space, Break );     -- Skip whitespace 
        Scan( Id, Vstr, Identifier, Break );        -- Scan Ada identifier
        return To_String( Id );
    end;