Summary

###########################################################################

	File:     scanset.icn

	Subject:  Procedures setup for string scanning procedures

	Author:   Robert J. Alexander

	Date:     June 4, 1993

###########################################################################

   This file is in the public domain.

###########################################################################

  Procedure to set up for user-written string-scanning procedures that
  are in the spirit of Icon's built-ins.

  The values passed are the s, i1, i2 parameters which are the last
  three arguments to all Icon scanning functions (such as
  upto(c,s,i1,i2)).  scan_setup() supplies any appropriate defaults and
  returns needed values.
 
  The value returned is a "scan_setup_result" record consisting of two
  values:

	1.  The substring of s to be scanned (ss).
	2.  The size of the substring of s that precedes the
	    substring to be scanned (offset).

  scan_setup() fails if i1 or i2 is out of range with respect to s.

  The user-written procedure can then match in the string ss to compute
  the position within ss appropriate to the scan (p).  The value
  returned (or suspended) to the caller is p + offset (the position
  within the original string, s).

  For example, the following function finds two words separated by
  spaces:

	procedure two_words(s,i1,i2)
	   local x,p
	   x := scan_setup(s,i1,i2) | fail	# fail if out of range
	   x.ss ? suspend {
	      tab(upto(&letters)) &
	      pos(1) | (move(-1) & tab(any(~&letters))) &
	      p := &pos &		# remember starting position
	      tab(many(&letters)) &
	      tab(many(' ')) &
	      tab(many(&letters)) &
	      p + x.offset		# return position in original s
	      }
	end

This file is part of the (main) package.

scan_setup(s, i1, i2)

scan_setup_result(ss, offset)

 length of substring preceding ss