StringUpTo (StringTokenizer function)

String from start to current position (StringTokenizer class)

[Introduced in Sirius Mods 7.8]

This method returns a substring of the tokenizing string, starting at NextPosition and ending just before the occurrence of its argument string, and NextPosition is set to the start of the occurrence of the argument string.

Syntax

%string = stringTokenizer:StringUpTo( string)

Syntax terms

%string	A string variable to contain the returned substring, which starts at NextPosition and continues up to the occurrence of the needle string, or, if the needle is not found or is the null string, continues through the rest of the string being tokenized.
stringTokenizer	A StringTokenizer object expression.
string	The needle to search for, starting at NextPosition. If string is not found, or if it is the null string, StringUpTo returns the rest of the string being tokenized, and sets AtEnd to True and NextPosition to one more than the length of the string being tokenized.

Usage notes

• If StringUpTo locates an occurrence of its argument string, it advances NextToken to the start of that located argument string.
• Because a failure to match the target string returns the rest of the tokenizer string, StringUpTo does not directly indicate whether there was a match. Either of the following two techniques indicate there was a match:
  • AtEnd is False if there was a match, and True if there was not a match.
  • NextPosition is less than or equal to StringLength if there was a match, and greater than StringLength if there was not a match.

  Examples

  Spaces tokenization

  Here are two simple StringUpTo calls, the second of which does not locate its argument string:

  b %tk is object stringTokenizer %tk = new %tk:string = 'a b c --> d e' printText {~} = /{%tk:stringUpTo('-->')}/ printtext {~} = {%tk:nextPosition} printText {~} = /{%tk:stringUpTo('---')}/ printtext {~} = {%tk:nextPosition} end

  The result is:

  %tk:stringUpTo('-->') = /a b c / %tk:nextPosition = 7 %tk:stringUpTo('---') = /--> d e/ %tk:nextPosition = 14, %tk:atEnd = True

  Separators tokenization

  Similarly, in the following fragment, the second StringUpTo call does not locate its argument string. Note that NextPosition is the same before and after the second StringUpTo call, but AtEnd changes:

  %tk:separators = ',' %tk:string = 'a b c --> d e,q' printtext {~} = {%tk:nextToken} printtext {~} = {%tk:nextPosition}, {~} = {%tk:stringLength}, {~} = {%tk:atEnd} printText {~} = /{%tk:stringUpTo('?')}/ printtext {~} = {%tk:nextPosition}, {~} = {%tk:stringLength}, {~} = {%tk:atEnd} %tk:string = 'a b c --> d e,' printtext {~} = {%tk:nextToken} printtext {~} = {%tk:nextPosition}, {~} = {%tk:stringLength}, {~} = {%tk:atEnd} printText {~} = /{%tk:stringUpTo('?')}/ printtext {~} = {%tk:nextPosition}, {~} = {%tk:stringLength}, {~} = {%tk:atEnd}

  %tk:nextToken = a b c --> d e %tk:nextPosition = 15, %tk:stringLength = 15, %tk:atEnd = False %tk:stringUpTo('?') = /q/ %tk:nextPosition = 16, %tk:stringLength = 15, %tk:atEnd = True %tk:nextToken = a b c --> d e %tk:nextPosition = 15, %tk:stringLength = 14, %tk:atEnd = False %tk:stringUpTo('?') = // %tk:nextPosition = 15, %tk:stringLength = 14, %tk:atEnd = True

  See also

  StringTokenizer class	List of StringTokenizer methods	StringTokenizer methods syntax
  Notation conventions for methods