' PARSE%(1.0)  Parse Char String into SubStr Array     01/19/1996-06/01/2001
      ' --------------------------------------------------------------------------
      ' Copyright (C) 1996-2001 by Vladimir Veytsel                  www.davar.net

      ' Type ---------------------------------------------------------------------

      '    Function [actionable]

      ' Description --------------------------------------------------------------

      '    PARSE% function parses its first character string parameter into array
      '    of substrings specified by its second parameter, using its third
      '    parameter as a delimiter of substrings, and returns the actual number
      '    of resultant substrings parsed into the array.

      ' Declaration --------------------------------------------------------------

      '    DECLARE FUNCTION PARSE%(Strng$,SubStr$(),Delim$)

      ' Parameters ---------------------------------------------------------------

      '    Strng$   - Character string to be parsed
      '    SubStr$  - Array of substrings for parsed values
      '    Delim$   - Delimiter to be used for parsing

      ' Action -------------------------------------------------------------------

      '    Input string is parsed into specified array of substrings.

      ' Value --------------------------------------------------------------------

      '  - Actual number of parsed substrings in substring array.

      '  - If input string is EMPTY;
      '       then returned number of parsed substrings is 0.

      '  - If delimiter is not found in input string,
      '       then first array element contains entire input string.

      '  - If max number of substring array elements is LESS than number of substrings,
      '       then returned number of parsed substrings is NEGATIVE
      '       (last array element contains in this case entire tail of input string).

      '  - If max number of substring array elements is GREATER than number of substrings,
      '       then remaining array elements contain empty strings.

      ' Notes --------------------------------------------------------------------

      '  - If delimiter string is EMPTY,
      '       then input string is checked for presence of ",":
      '            If "," is found in input string
      '               then "," is taken as substring delimiter;
      '               else " " is taken as substring delimiter.

      '  - If delimiter string is longer than 1,
      '       then FIRST symbol is taken as delimiter.

      '  - If delimiter is "*" (self-defined),
      '       then FIRST symbol of string to be parsed is taken as delimiter.

      '  - If " " is specified or is taken as substring delimiter,
      '       then all successive SPACEs in the string to be parsed
      '            are compressed to the single space.
      '            This enables parameter alignment in batch files.

      ' Examples (for DIM SubStr(3) Array) ---------------------------------------

      '    PARSE%(""             ,SubStr$(),"." )= 0   SubStr$()="","",""
      '    PARSE%("A,BC,DEF"     ,SubStr$(),""  )= 3   SubStr$()="A","BC","DEF"
      '    PARSE%("A BC DEF"     ,SubStr$(),""  )= 3   SubStr$()="A","BC","DEF"
      '    PARSE%("A  BC   DEF"  ,SubStr$(),""  )= 3   SubStr$()="A","BC","DEF"
      '    PARSE%("A"            ,SubStr$(),"." )= 1   SubStr$()="A","",""
      '    PARSE%("A."           ,SubStr$(),"." )= 2   SubStr$()="A","",""
      '    PARSE%("A.BC"         ,SubStr$(),"." )= 2   SubStr$()="A","BC",""
      '    PARSE%("A.BC.DEF"     ,SubStr$(),"." )= 3   SubStr$()="A","BC","DEF"
      '    PARSE%("A.BC.DEF."    ,SubStr$(),".:")=-3   SubStr$()="A","BC","DEF."
      '    PARSE%(".A.BC.DEF"    ,SubStr$(),"*" )= 3   SubStr$()="A","BC","DEF"
      '    PARSE%("A.BC.DEF.GHIJ",SubStr$(),"." )=-3   SubStr$()="A","BC","DEF.GHIJ"
      '    PARSE%("A.BC.DEF.GHIJ",SubStr$(),":" )= 1   SubStr$()="A.BC.DEF.GHIJ","",""

      ' External Function --------------------------------------------------------

	   DECLARE FUNCTION COMPRES$(Strng$,Chars$)

      ' Start Function -----------------------------------------------------------

	   DEFINT A-Z	  ' All defaulted variables are integer
	   OPTION BASE 1  ' Default array indexation starts from "1"

	   FUNCTION PARSE%(Strng$,SubStr$(1),Delim$) PUBLIC

      ' Copy Modifiable Parameters Into Working Variables ------------------------

	   Work.Delim$=Delim$
	   Work.Strng$=Strng$

      ' Form Actual Delimiter for Input String Parsing ---------------------------

	   IF (LEN(Work.Delim$)>0) THEN
	      Work.Delim$=LEFT$(Work.Delim$,1)
	      IF (Work.Delim$="*") THEN
		 Work.Delim$=LEFT$(Work.Strng$,1)
		 Work.Strng$=MID$(Work.Strng$,2)
	      END IF
	   ELSE
	      IF (INSTR(Work.Strng$,",")>0) THEN
		 Work.Delim$=","  ' If string         contains ","
	      ELSE
		 Work.Delim$=" "  ' If string doesn't contain  ","
	      END IF
	   END IF

	   IF (Work.Delim$=" ") THEN Work.Strng$=COMPRES$(Work.Strng$," ")

      ' Parse String into SubString Array Using Actual Delimiter -----------------

	   SubStrings=UBOUND(SubStr$)
	   IF (LEN(Work.Strng$)=0) THEN
	      Act.SubStrs=0
	   ELSE
	      Delimiters=TALLY(Work.Strng$,Work.Delim$)+1
	      IF (Delimiters=0) THEN
		 SubStr$(1)=Work.Strng$ :I=2
	      ELSE
		 Act.SubStrs=MIN(SubStrings,Delimiters)
		 Work.Strng$=Work.Strng$+Work.Delim$	' Add post-last delimiter
		 FOR I=1 TO Act.SubStrs
		     J=INSTR(Work.Strng$,Work.Delim$)	' Find next delimiter
		     SubStr$(I)=LEFT$(Work.Strng$,J-1)	' Get next substring
		     Work.Strng$=MID$(Work.Strng$,J+1)	' Trim current substring
		 NEXT I
	      END IF
	   END IF

      ' Empty Remaining SubString Array Elements (if Any) ------------------------

	   FOR I=MAX(1,I) TO SubStrings
	       SubStr$(I)=""
	   NEXT I

      ' Adjustment when Array Dimensions is Less Than Number of SubStrings -------

	   IF (SubStrings<Delimiters) THEN
	      SubStr$(SubStrings)=SubStr$(SubStrings)+Work.Delim$+LEFT$(Work.Strng$,LEN(Work.Strng$)-1)
	      Act.SubStrs=-Act.SubStrs
	   END IF

      ' Return Function Value to the Point of Invocation and Finish It -----------

	   PARSE%=Act.SubStrs

	   END FUNCTION
  

      ' PARSE%(1.0)  Parse Char String into SubStr Array     01/20/1996-06/01/2001
      ' --------------------------------------------------------------------------

	$INCLUDE "PARSE"
	$LINK	 "MODULE.PBL"

	DECLARE FUNCTION PARSE%(Strng$,SubStr$(),Delim$)

	DIM SubStr$(3)

	CLS
        PRINT "PARSE%(0.0)  Parse Character String into SubStr Array  ";DATE$;
        PRINT "  ";LEFT$(TIME$,5)
	PRINT STRING$(72,"-")
	PRINT

	PRINT "PARSE%(''             ,SubStr$(),'.' )="; _
	       PARSE%(""             ,SubStr$(),"." )  ; :GOSUB Prt
	PRINT "PARSE%('A,BC,DEF'     ,SubStr$(),''  )="; _
	       PARSE%("A,BC,DEF"     ,SubStr$(),""  )  ; :GOSUB Prt
	PRINT "PARSE%('A BC DEF'     ,SubStr$(),''  )="; _
	       PARSE%("A BC DEF"     ,SubStr$(),""  )  ; :GOSUB Prt
	PRINT "PARSE%('A  BC   DEF'  ,SubStr$(),''  )="; _
	       PARSE%("A  BC   DEF"  ,SubStr$(),""  )  ; :GOSUB Prt
	PRINT "PARSE%('A'            ,SubStr$(),'.' )="; _
	       PARSE%("A"            ,SubStr$(),"." )  ; :GOSUB Prt
	PRINT "PARSE%('A.'           ,SubStr$(),'.' )="; _
	       PARSE%("A."           ,SubStr$(),"." )  ; :GOSUB Prt
	PRINT "PARSE%('A.BC'         ,SubStr$(),'.' )="; _
	       PARSE%("A.BC"         ,SubStr$(),"." )  ; :GOSUB Prt
	PRINT "PARSE%('A.BC.DEF'     ,SubStr$(),'.' )="; _
	       PARSE%("A.BC.DEF"     ,SubStr$(),"." )  ; :GOSUB Prt
	PRINT "PARSE%('A.BC.DEF.'    ,SubStr$(),'.:')="; _
	       PARSE%("A.BC.DEF."    ,SubStr$(),".:")  ; :GOSUB Prt
	PRINT "PARSE%('.A.BC.DEF'    ,SubStr$(),'*' )="; _
	       PARSE%(".A.BC.DEF"    ,SubStr$(),"*" )  ; :GOSUB Prt
	PRINT "PARSE%('A.BC.DEF.GHIJ',SubStr$(),'.' )="; _
	       PARSE%("A.BC.DEF.GHIJ",SubStr$(),"." )  ; :GOSUB Prt
	PRINT "PARSE%('A.BC.DEF.GHIJ',SubStr$(),':' )="; _
	       PARSE%("A.BC.DEF.GHIJ",SubStr$(),":" )  ; :GOSUB Prt

	PRINT
	PRINT "Execution completed - hit [Enter] to continue..."

	END

      Prt:

	PRINT "  "; "SubStr$()='"; SubStr$(1); "','"; SubStr$(2); "','"; SubStr$(3); "'"

	RETURN