⟦ffd60c9be⟧

E3 Source Code



--| @SUMMARY This package provides a means for iterating over the fields
--| in a line.
--|
--| @RAISES "Not_Initialized" (if passed an uninitialized object).
--|
--| @INDICES (Text_Processing, Utility)
--|
--| @SPECIAL_NOTES All strings are returned starting at index 1.
--|
generic

    --| @DESCRIPTION Specifies which characters are field separators. The
    --| beginning and the end of the string is always a field separator. For
    --| example, if the Is_Separator function recognizes '|' and '.' as field
    --| separators, then the following string contains five fields (three of
    --| which are null):
    --|
    --|      |a.|bcd|
    --|
    --| and the following string contains three fields (one of which is null):
    --|
    --|      a|.bdc
    --|
    --| @SPECIAL_NOTES The null string contains no fields.
    --|
    with function Is_Separator (This_Character : in Character) return Boolean;

package Fields is

    subtype Field is String;

    type Iterator is private;

    --| @SUMMARY Parses the specified string looking for fields, and returns
    --| an initialized field iterator.
    --|
    --| @SPECIAL_NOTES If the string is null, the resulting iterator
    --| contains no fields, and "Done" is always True; otherwise the
    --| current field in the iterator is reset to the first field in
    --| the iterator before the iterator is returned.
    --|
    function Create (From_String : in String) return Iterator;

    --| @SUMMARY Returns the image of the specified fields iterator. Is the
    --| inverse of the "Create" function.
    --|
    function Image (Of_Fields : in Iterator) return String;

    --| @SUMMARY Returns True if the iterator is "Done".
    --|
    function Done (This_Iterator : in Iterator) return Boolean;

    --| @SUMMARY Resets the current field in the iterator to the first field.
    --|
    --| @SPECIAL_NOTES If the iterator is empty, has no effect.   --|
    procedure Reset (This_Iterator : in out Iterator);

    --| @SUMMARY Returns the current field in the iterator.
    --|
    --| @RAISES No_Current_Field (if already "Done").
    --|
    function Current (This_Iterator : in Iterator) return Field;

    --| @SUMMARY Replaces the current field in the iterator with the new field.
    --|
    --| @RAISES No_Current_Field (if already "Done").
    --|
    --| Parse_Failure (if the new field contains a separator).
    --|
    --| @DESCRIPTION Can be called during iteration without altering
    --| iterator's position.
    --|
    procedure Modify (This_Iterator : in out Iterator; New_Field : in Field);

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

    --| @SPECIAL_NOTES Fields are numbered 1..N
    subtype Field_Number is Positive;

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

    --| @SUMMARY Sets the current field in the iterator to the specified
    --| field number.
    --|
    --| @RAISES Out_Of_Range (if the specified field number is out of range,
    --| or if the iterator is empty).
    --|
    procedure Set (This_Iterator : in out Iterator; To_Field : in Field_Number);

    --| @SUMMARY Returns the field corresponding to the specified field number.
    --|
    --| @RAISES Out_Of_Range (if the specified field number is out of range,
    --| or if the iterator is empty).
    --|
    --| @SPECIAL_NOTES Can be called during iteration without altering
    --| iterator's position.
    --|
    function Field_At
                (This_Position : in Field_Number; In_Iterator : in Iterator)
                return Field;

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

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

    --| @SUMMARY Adds the specified field to the end of the field iterator,
    --| using the specified separator (if the new field is the only field,
    --| no separator is used).
    --|
    --| @RAISES Parse_Failure (if the new field contains a separator,
    --| or if the specified separator character is not a valid separator).
    --|
    --| @SPECIAL_NOTES This operation is NOT safe to call during iteration.
    --|
    procedure Add (This_Field      : in     Field;
                   To_Iterator     : in out Iterator;
                   Using_Separator : in     Character);

    Not_Initialized : exception;

    Parse_Failure : exception;

    No_Current_Field : exception;
    No_Next_Field    : exception;

    Out_Of_Range : exception;

private

    type Fields_Pointer is access String;

    type Iterator is
        record
            The_Fields : Fields_Pointer := null;
            Characters_In_Current_Field : Natural := 0;
            Trailing_Separator_Position : Natural := 0;
            Current_Field_Number : Natural := 0;
            Done : Boolean := True;
        end record;

end Fields;
DataMuseum.dk

Rational R1000/400

⟦ffd60c9be⟧ Ada Source

Derivation

E3 Source Code

E3 Meta Data
