File : strings-fields.ads
package Strings.Fields is
-- Compile this package with
-- gcc -c -O3 -gnatN
-- to get max speed
function Select_Field (
Item : String;
Field_No : Integer;
Field_Separator : Character) return String;
-- Returns a string that represents the nth string in the field.
-- The 'first of the return string is always set to one
-- Fields are separated by the supplied character
-- E.g.
--
-- Field ("cat:dog:mouse", 3, ':')
--
-- would result in the string
--
-- "mouse"
--
-- A -ve value indicates searching from the RHS.
--
-- E.g.
--
-- Field ("cat:dog:mouse", -1, ':')
--
-- would result in the string
-- "mouse"
--
-- To process each field in a string you can do the following
-- (presuming Line (1..Last) has the string you want to process)
--
-- i := 1;
-- loop
-- declare
-- Item : constant String := Field (Line (1..Last), i, ':');
-- begin
-- exit when Item = ""; -- no more fields (assumes all fields
-- -- have values!
-- -- process item...
-- I := I + 1;
-- end;
-- end loop;
function Count_Fields (
Item : String;
Field_Separator : Character) return Natural;
-- returns the # of fields separated by the field_separator
-- character
-- E.g.
--
-- Count_Fields ("cat:dog:mouse", ':') -> 3
-- Count_Fields ("cat:dog:mouse", 'o') -> 3
-- Count_Fields ("cat:dog:mouse", ' ') -> 1
-- Count_Fields ("", ' ') -> 0
function Select_Field (
Item : String;
Field_No : Integer) return String;
-- Returns a string that represents the nth string in the field.
-- The 'first of the return string is always set to one
-- Differs from the other 'field' function in that it considers
-- fields to be separated by multiple white space characters
-- As above -ve field numbers signify searching from the RHS
-- E.g.
--
-- Field ("cat dog mouse", 3)
--
-- would result in the string
--
-- "mouse"
-- Note that this is _not_ the same as
--
-- Field ("cat dog mouse", 3, ' ')
--
-- which sees _each_ space as separating (many empty) fields
function Select_Fields (
Line : String;
Format : String) return String;
-- Construct a new string from the string line, by applying the
-- fields according to the format specifier. Fields are considerd
-- to be separated by spaces.
-- As above -ve field numbers signify searching from the RHS
-- E.g.
--
-- Select_Fields ("cat dog mouse", "3 2")
--
-- would result in the string
--
-- "mouse dog"
function Build_String (
Line : String;
Format : String) return String;
Format_Error : Exception;
-- Construct a new string from Line, by applying the fields
-- according to the format specifier. The fields in line are
-- separated by whitespace (spaces and tabs).
--
-- Format allows for $1, $2..$n, $-1, $-2..$-n to select a field
-- from Line
-- $* represents all the fields.
-- $$ represents the characer '$'
-- Other characters in the format string are copied verbatim into
-- the output string
--
-- Format_Error is raised if
-- the character following a '$' is not one of the above
-- '$' is the last chacter in the string
-- the number following '$' is too long to be converted to an integer.
--
-- E.g.
-- Build_String ("cat mouse dog", "The $1 ate the $2")
--
-- would result in the string..
--
-- "The cat ate the mouse"
--
-- E.g.
-- Build_String ("cat mouse dog", "$3:$2:$1")
--
-- would result in the string..
--
-- "dog:mouse:cat"
--
-- E.g.
-- Build_String ("cat mouse dog", "the $1 ate the $");
--
-- would result in a Format_Exception error.
end Strings.Fields;