⟦2ba127349⟧

E3 Source Code



--| @SUMMARY This package provides a lines abstraction, allowing an arbitrary
--| number of arbitrary-length lines to be collected together in a
--| well-defined order.
--|
--| @INDICES (Text_Processing, Data_Structure)
--|
--| @RAISES All operations raise "Not_Initialized" if passed an uninitialized
--| object. Also, all "Add" operations propagate Storage_Error if it occurs.
--|
with Unbounded_String;
with Doubly_Linked_List_Generic;
package Lines is

    type Line is private;

    --| @SUMMARY Returns an initialized line corresponding to the
    --| specified string.
    --|
    function Create (From_String : in String) return Line;

    --| @SUMMARY Returns an empty, initialized line.
    --|
    function Empty_Line return Line;

    --| @SUMMARY Returns a true (non-aliased) copy of the specified line.
    --| Very different from ":=".
    --|
    function Copy (Of_Line : in Line) return Line;

    --| @SUMMARY Returns the string image of the specified line.
    --|
    function Image (Of_Line : in Line) return String;

    type Iterator is private;

    --| @SUMMARY Returns an empty iterator.
    --|
    function Create return Iterator;

    --| @SUMMARY Returns True if the specified iterator contains no lines.
    --|
    function Is_Empty (This_Iterator : in Iterator) return Boolean;

    --| @SUMMARY Returns the number of lines in the specified iterator.
    --|
    function Lines_In (This_Iterator : in Iterator) return Natural;

    --| @SUMMARY Returns a true (non-aliased) copy of the specified iterator.
    --| Very different from ":=".
    --|
    function Copy (Of_Iterator : in Iterator) return Iterator;

    --| @SUMMARY Resets the current line in the iterator to be the first line.
    --|
    --| @SPECIAL_NOTES If the iterator is empty, has no effect (the iterator
    --| remains "Done").
    --|
    procedure Reset_To_First (This_Iterator : in out Iterator);

    --| @SUMMARY Resets the current line in the iterator to be the last line.
    --|
    --| @SPECIAL_NOTES If the iterator is empty, has no effect (the iterator
    --| remains "Done").
    --|
    procedure Reset_To_Last (This_Iterator : in out Iterator);

    --| @SUMMARY Returns True if the iterator has been advanced past the
    --| last element, has been backed-up past the first element, or is empty.
    --|
    --| @SPECIAL_NOTES Note that empty iterators are always "Done", but "Done"
    --| iterators are not necessarily empty.
    --|
    function Done (This_Iterator : in Iterator) return Boolean;

    --| @SUMMARY Returns True if the current position is the first line in
    --| the iterator.
    --|
    --| @SPECIAL_NOTES Will be True at the same time as "At_Last" if the
    --| iterator contains only one line.
    --|
    --| Returns False if the iterator is empty.
    --|
    function At_First (This_Iterator : in Iterator) return Boolean;

    --| @SUMMARY Returns True if the current position is the last line in
    --| the iterator.
    --|
    --| @SPECIAL_NOTES Will be True at the same time as "At_First" if the
    --| iterator contains only one line.
    --|
    --| Returns False if the iterator is empty.
    --|
    function At_Last (This_Iterator : in Iterator) return Boolean;

    --| @SUMMARY Advances the current line in the iterator to the
    --| previous line.
    --|
    --| @RAISES No_Previous_Line (if "Done").
    --|
    procedure Previous (This_Iterator : in out Iterator);

    --| @SUMMARY Advances the current line in the iterator to the next line.
    --|
    --| @RAISES No_Next_Line (if "Done").
    --|
    procedure Next (This_Iterator : in out Iterator);

    --| @SUMMARY Returns the current line in the iterator.
    --|
    --| @RAISES No_Current_Line (if "Done").
    --|
    function Current (This_Iterator : in Iterator) return Line;

    --| @SPECIAL_NOTES Lines are numbered 1..N
    type Line_Number is new Positive;

    --| @SUMMARY Returns the line number corresponding to the current line in
    --| the iterator.
    --|
    --| @RAISES No_Current_Line (if already "Done").
    --|
    function Position (In_Iterator : in Iterator) return Line_Number;

    --| @SUMMARY Sets the current line in the iterator to the specified
    --| line number.
    --|
    --| @RAISES Out_Of_Range (if the specified line number is out of range).
    --|
    procedure Set (This_Iterator : in out Iterator; To_Line : in Line_Number);

    --| @SUMMARY Returns the line corresponding to the specified line number.
    --|
    --| @RAISES Out_Of_Range (if the specified line number is out of range).
    --|
    function Line_At (This_Position : in Line_Number; In_Iterator : in Iterator)
                     return Line;

    --| @SUMMARY Adds the specified line to the end of the iterator.
    --|
    --| @SPECIAL_NOTES Does not alter iterator state. The iterator is still
    --| pointing to the same line as it was before the operation (the only
    --| exception to this is if the line just added is the only line in the
    --| iterator, in which case it becomes the first line, the last line, the
    --| current position, and the current line simultaneously).
    --|
    procedure Add (To_Iterator : in out Iterator;  
                   This_Line   : in     Line);

    --| @SPECIAL_NOTES Control position of additions.
    --|
    type Orientations is (Preceeding, Following);

    --| @SUMMARY If "With_Orientation" is "Following", adds the specified
    --| line to the iterator after the current position. If "With_Orientation"
    --| is "Preceeding", adds the specified line to the iterator before the
    --| current position.
    --|
    --| @RAISES No_Current_Line (if "Done").
    --|
    --| @SPECIAL_NOTES This operation does not alter iterator state. The
    --| iterator is still pointing to the same line as it was before the
    --| operation (note, however, that insertions which increase the number
    --| of lines preceeding the original position will increment the original
    --| position by 1).
    --|
    procedure Add (To_Iterator      : in out Iterator;
                   This_Line        : in     Line;
                   With_Orientation : in     Orientations);

    --| @SUMMARY If "With_Orientation" is "Following", adds the specified
    --| line to the iterator after the indicated position. If "With_Orientation"
    --| is "Preceeding", adds the specified line to the iterator before the
    --| specified position.
    --|
    --| @RAISES Out_Of_Range (if the specified position is out of range).
    --|
    --| @SPECIAL_NOTES This operation does not alter iterator state. The
    --| iterator is still pointing to the same line as it was before the
    --| operation (note, however, that insertions which increase the number
    --| of lines preceeding the original position will increment the original
    --| position by 1).
    --|
    procedure Add (To_Iterator      : in out Iterator;
                   This_Line        : in     Line;
                   At_Position      : in     Line_Number;
                   With_Orientation : in     Orientations);

    --| @SUMMARY Replaces the current line in the iterator with the new line.
    --| Can be called during iteration without altering iterator's position.
    --|
    --| @RAISES No_Current_Line (if already "Done").
    --|
    procedure Modify (This_Iterator : in out Iterator; New_Line : in Line);

    --| @SUMMARY Deletes the current line. Current line is set to the line
    --| immediately following the deleted line.
    --|
    --| @RAISES No_Current_Line (if the iterator is "Done" before the delete
    --| is attempted).
    --|
    --| @SPECIAL_NOTES If the deleted line was the last line in the iterator,
    --| the iterator becomes "Done".
    --|
    procedure Delete (From_Iterator : in out Iterator);

    --| @SUMMARY Deletes the line at the specified position from the iterator.
    --|
    --| @RAISES Out_Of_Range (if the specified line number is out of range).
    --|
    --| @SPECIAL_NOTES If the line at the specified position is not the current
    --| line, the state of the iterator is unchanged (note, however, that
    --| deletions which decrease the number of lines preceeding the original
    --| position will decrement the current position by 1).
    --|
    --| If the line at the specified position is the current line,
    --| the new current line is set to the line immediately following
    --| the deleted line (note that the position remains unchanged). If
    --| the deleted line was the last line in the iterator, the iterator
    --| becomes "Done".
    --|
    procedure Delete (From_Iterator : in out Iterator;
                      This_Position : in     Line_Number);

    --| @SUMMARY Reclaims storage.
    --|
    procedure Dispose (Of_This_Iterator : in out Iterator);

    Not_Initialized : exception;

    No_Current_Line  : exception;
    No_Previous_Line : exception;
    No_Next_Line     : exception;

    Out_Of_Range : exception;

private

    package Vstrings is new Unbounded_String;

    type Line is
        record
            Contents       : Vstrings.Variable_String;
            Is_Initialized : Boolean := False;
        end record;

    package Strings is new Doubly_Linked_List_Generic (Line);

    type Iterator is
        record
            Contents       : Strings.List := Strings.Create;
            Is_Initialized : Boolean      := False;
        end record;

end Lines;
DataMuseum.dk

Rational R1000/400

⟦2ba127349⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
