home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / lambda / soundpot / p / ut-doc.lbr / SPLTSCAN.DZC / SPLTSCAN.DOC
Encoding:
Text File  |  1993-10-25  |  8.1 KB  |  171 lines
  1. .he                    spltscan.doc
  2. Character handling functions similar to those in Honeywell's TEX.
  3.  
  4. 1.  split(instring,col,starl,starr)
  5. 2.  splitr(instring,col,starl,starr)
  6. 3.  match=scan(instring,pat,starl,starm,starr)
  7. 4.  match=scann(instring,pat,starl,starm,starr)
  8. 5.  match=scanr(instring,pat,starl,starm,starr)
  9. 6.  match=scannr(instring,pat,starl,starm,starr)
  10.  
  11. General notes:
  12.  
  13.      instring is the input string to be split or scanned.
  14.           It must be terminated by '\0'.
  15.      starl,starm and starr are output strings.  They 
  16.           will be terminated by '\0'.
  17.      col, input to split and splitr, is an integer.
  18.      pat, input to the scan functions, is the pattern to
  19.           be matched and must be terminated by '\0'.  If
  20.           pat's first character is '_' (CLASC), then it
  21.           indicates a class match instead of a literal
  22.           match.  The classes available are:
  23.                _a  alphabetic.  52 ascii upper and lower.
  24.                _n  numeric.  digits 0-9.
  25.                _an alphanumeric.  52 alpha and the 10 digits.
  26.                _lc lower case.  26 ascii lower case alpha.
  27.                _uc upper case.  26 ascii upper case alpha.
  28.      match, output by scan functions, is 0 (FALSE) or 1 (TRUE).
  29.  
  30. Specific details on each function follow.
  31. .pa
  32. è1.  split(instring,col,starl,starr)
  33.  
  34.      normal case
  35.           0 < col <= strlen(instring)
  36.           starl will contain the leftmost col characters
  37.           of instring.  starr will contain the rest.
  38.  
  39.      special cases
  40.           (a)  if instring is null (instring[0]=='\0')
  41.                then starl and starr will be null.
  42.           (b)  if col>strlen(instring) then starl will
  43.                contain all of instring and starr will be null.
  44.           (c)  if col <=0 then starr will contain all of
  45.                instring and starl will be null.
  46.  
  47.  
  48. 2.  splitr(instring,col,starl,starr)
  49.  
  50.      normal case
  51.           0 < col <= strlen(instring)
  52.           starr will contain the rightmost col characters
  53.           of instring.  starl will contain the rest.
  54.  
  55.      special cases
  56.           (a)  if instring is null, then starl and starr will be
  57.                null.
  58.           (b)  if col>strlen(instring), then starr will contain
  59.                all of instring and starl will be null.
  60.           (c)  if col<=0 then starr will be null and starl
  61.                will contain all of instring.
  62. .pa
  63. è3.  match=scan(instring,pat,starl,starm,starr)
  64.  
  65.      normal case: where pat is a string
  66. ááááááááááIµáá pa⌠á i≤á iεá instring¼áá star∞á wil∞á contaiεá thσ ì
  67. áááááááááácharacter≤ t∩ thσ lef⌠ oµ it¼á starφ wil∞ contaiεá pat¼ ì
  68. áááááááááástar≥á wil∞á contaiε thσ character≤ t∩ thσ righ⌠ oµá i⌠ ì
  69. ááááááááááanΣ matcΦ wil∞ bσ ▒ (TRUE)«á  Iµ pa⌠ isn'⌠ iε instring¼ ì
  70. áááááááááástar∞á wil∞ contaiε instring¼á starφ anΣ star≥ wil∞á bσ ì
  71. áááááááááánull and match will be 0 (FALSE).
  72.  
  73.      normal case: where pat is a class
  74. ááááááááááIµá aε occurrencσ oµ thσ clas≤ i≤á iεá instring¼á star∞ ì
  75. ááááááááááwil∞á contaiεá thσ character≤ t∩ thσ lef⌠ oµ thσá firs⌠ ì
  76. ááááááááááoccurrence¼á starφ wil∞ bσ null¼ star≥ wil∞ contaiε thσ ì
  77. áááááááááárest¼á anΣ matcΦ wil∞ bσ ░ (FALSE)«  Iµ therσ isn'⌠ an∙ ì
  78. ááááááááááoccurrencσ oµ thσ clas≤ iε instring¼ star∞ wil∞ contaiε ì
  79. ááááááááááinstring¼á starφ anΣ star≥ wil∞ bσ nul∞ anΣ matcΦá wil∞ ì
  80. áááááááááábe 0 (FALSE).
  81.  
  82.      special cases
  83.           (a)  if instring is null, starl, starm and starr will
  84.                be null and match will be 0 (FALSE).
  85.           (b)  if pat is null and instring isn't null, starl
  86.                will contain instring, starm and starr will be
  87.                null and match will be 0 (FALSE).
  88. .pa
  89. è4.  match=scann(instring,pat,starl,starm,starr)
  90.  
  91.      normal case: where pat is a string
  92. áááááááááápa⌠ mus⌠ bσ ß singlσ character«  Iµ pa⌠ i≤ iε instring║  ì
  93. áááááááááástar∞á wil∞á contaiεá an∙ leadinτ occurrence≤á oµá pat¼ ì
  94. áááááááááástarφá wil∞á bσ null¼á star≥ wil∞ contaiε thσá res⌠á oµ ì
  95. ááááááááááinstrinτá anΣ matcΦ wil∞ bσ ▒ (TRUE⌐ iµ star≥á i≤á nul∞ ì
  96. áááááááááá(e.g«á iµá eacΦá oµ thσ character≤ oµ instrinτá matche≤ ì
  97. áááááááááápat⌐á anΣá ░á (FALSE⌐á otherwise«áá  Iµá pa⌠á isn'⌠á iε ì
  98. ááááááááááinstring║á  star∞á anΣ starφ wil∞ bσ null¼á star≥á wil∞ ì
  99. áááááááááácontain instring and match will be 0 (FALSE).
  100.  
  101.      normal case:  where pat is a class
  102. ááááááááááIµ instrinτ contain≤ aε occurrencσ oµ thσá class¼á theε ì
  103. áááááááááástar∞á wil∞á contaiεá al∞ leadinτá occurrence≤á oµá thσ ì
  104. ááááááááááclass¼á starφ wil∞ bσ null¼ star≥ wil∞ contaiε thσ res⌠ ì
  105. ááááááááááoµá instring¼á anΣá matcΦ wil∞ bσ ▒ (TRUE⌐ iµ star≥á i≤ ì
  106. áááááááááánul∞á (e.g«á iµá al∞ character≤ oµ instrinτá matcΦá thσ ì
  107. ááááááááááclass⌐á anΣ ░ (FALSE⌐ otherwise«á  Iµ instrinτá doesn'⌠ ì
  108. áááááááááácontaiεá an∙ occurrencσ oµ thσ class¼á star∞ anΣá starφ ì
  109. ááááááááááwil∞á bσ null¼á star≥ wil∞ contaiε instrinτá anΣá matcΦ ì
  110. ááááááááááwill be 0 (FALSE).
  111.  
  112.      special cases
  113.           (a)  If instring and/or pat is null, starl, starm
  114.                and starr will be null.  match will be 0 (FALSE).
  115.                In contrast, TEX considers it an error if pat is
  116.                null here and doesn't bother to return any 
  117.                values (it just issues the warning message).
  118. .pa
  119. è5.  match=scanr(instring,pat,starl,starm,starr)
  120.  
  121.      normal case:  where pat is a string
  122. ááááááááááIµ pa⌠ i≤ iε instring¼ star∞ wil∞ contaiε character≤ t∩ ì
  123. ááááááááááthσ lef⌠ oµ pat¼á starφ wil∞ contaiε pa⌠ anΣ star≥ wil∞ ì
  124. áááááááááácontaiε character≤ t∩ thσ righ⌠ oµ pat¼á anΣ matcΦ wil∞ ì
  125. áááááááááábσ ▒ (TRUE)«  Iµ pa⌠ isn'⌠ iε instring¼ star∞ anΣ starφ ì
  126. ááááááááááwil∞á bσá null¼á star≥ wil∞ contaiε instrinτ anΣá matcΦ ì
  127. ááááááááááwill be 0 (FALSE).
  128.  
  129.      normal case:  where pat is a class
  130. ááááááááááIµ instrinτ contain≤ aε occurrencσ oµ thσ class¼á star∞ ì
  131. ááááááááááwil∞ contaiε thσ rightmos⌠ occurrencσ oµ thσ clas≤á anΣ ì
  132. ááááááááááan∙á character≤ t∩ thσ lef⌠ oµ it¼á starφ wil∞ bσ null¼ ì
  133. áááááááááástar≥ wil∞ contaiε thσ res⌠ oµ instrinτ anΣ matcΦá wil∞ ì
  134. áááááááááábσáá ▒á (TRUE)«áá  Iµá instrinτá doesn'⌠á contaiεáá an∙ ì
  135. ááááááááááoccurrencσ oµ thσ class¼á star∞ anΣ starφ wil∞ bσ null¼ ì
  136. áááááááááástar≥á wil∞á contaiεá instrinτá anΣá matcΦá wil∞á bσá ░ ì
  137. áááááááááá(FALSE).
  138.  
  139.      special cases
  140.           (a)  If instring is null, then starl, starm and starr
  141.                will be null.  match will be 0 (FALSE).
  142.           (b)  If pat is null and instring isn't, then starl
  143.                and starm will be null.  starr will contain 
  144.                instring and match will be 0 (FALSE).
  145. .pa
  146. è6.  match=scannr(instring,pat,starl,starm,starr)
  147.  
  148.      normal case:  where pat is a string
  149. áááááááááápa⌠ mus⌠ bσ ß singlσ character«  Iµ pa⌠ i≤ iε instring¼ ì
  150. áááááááááástar∞ wil∞ contaiε thσ rightmos⌠ characte≥ tha⌠ doesn'⌠ ì
  151. áááááááááámatcΦá pa⌠ anΣ al∞ character≤ t∩ thσ lef⌠ oµ it¼á starφ ì
  152. ááááááááááwil∞á bσá null¼á anΣá star≥ wil∞ contaiεá thσá res⌠á oµ ì
  153. ááááááááááinstring«á  matcΦ wil∞ bσ ▒ (TRUE⌐ iµ star≥ isn'⌠á nul∞ ì
  154. áááááááááá(e.g« iµ al∞ thσ character≤ oµ instrinτ matcΦ pat)¼ anΣ ì
  155. áááááááááá░ (FALSE⌐ iµ star≥ i≤ null«á  Iµ pa⌠ isn'⌠ iε instring¼ ì
  156. áááááááááástar∞á wil∞ contaiε instring¼á starφ anΣ star≥ wil∞á bσ ì
  157. áááááááááánull and match will be 0 (FALSE).
  158.  
  159.      normal case:  where pat is a class
  160. ááááááááááIµ instrinτ contain≤ aε occurrencσ oµ thσ class¼á star∞ ì
  161. ááááááááááwil∞ contaiε thσ rightmos⌠ characte≥ tha⌠ doesn'⌠ matcΦ ì
  162. ááááááááááthσ clas≤ anΣ al∞ character≤ t∩ thσ lef⌠ oµ it«á  starφ ì
  163. ááááááááááwil∞ bσ null¼á star≥ wil∞ contaiε thσ res⌠ oµ instring«  ì
  164. ááááááááááIµá star≥á isn'⌠ nul∞ (e.g«á iµ al∞ thσá character≤á oµ ì
  165. ááááááááááinstrinτá matcΦ thσ class⌐ theε matcΦ wil∞ bσ ▒ (TRUE)«  ì
  166. ááááááááááIµ star≥ i≤ null¼ matcΦ wil∞ bσ ░ (FALSE)«  Iµ instrinτ ì
  167. áááááááááádoesn'⌠ contaiε an∙ occurrencσ oµ thσ class¼ star∞ wil∞ ì
  168. áááááááááácontaiεá instring¼á starφá anΣ star≥ wil∞ bσá nul∞á anΣ ì
  169. áááááááááámatch will be 0 (FALSE).
  170.  
  171.      special cases
  172. ááááááááááIµ instriε and/o≥ pa⌠ i≤ null¼á starl¼á starφ anΣ star≥ ì
  173. ááááááááááwil∞ bσ null«á  matcΦ wil∞ bσ ░ (FALSE)«á  Iε contrast¼ ì
  174. ááááááááááTE╪á consider≤ i⌠ aε erro≥ iµ pa⌠ i≤ nul∞ anΣ issue≤á ß ì
  175. áááááááááámessage without bothering to set any variables.
  176.