### IStringParser

  The IStringParser class parses the content of an IString and places portions of the string into other strings. You can limit the parsing of a string by specifying the following:

  - Patterns that must be matched
  - Relative or absolute column numbers
  This class's functions work much like the REXX parse statement.

  Typically, you create IStringParser objects implicitly by applying the right-shift operator to an IString. IStringParser also provides the right-shift operator as a member function so you can chain together invocations of the operator. For example, a typical expression using IStringParser objects might look like the following:

      aFileName >> drive >> ':' >> path;

  The right-shift operator does one of four things, depending on the type of the right-hand operand:

  IString
    The string parser object sets this string to the next token from the text being parsed.
  pattern
    The parser advances to the next character beyond the occurrence of that pattern in its text. The pattern can be any of the following:
    const char*
      Searches for the sequence of characters described by the character array.
    const IString
      Searches for the sequence of characters described by the string. Note that the treatment of a const IString is fundamentally different from the treatment of a non-const IString.
    char
      Searches for the next occurrence of the specified character.
    IStringTest
      Searches for the next character in the text for which the string test object returns true.
  number
    The current parser text position is adjusted by the specified amount. The value can be positive or negative.
  special
    IStringParser defines special right-shift operands that perform the following special-purpose parser operations:
    IStringParser::reset
      This enumerator resets the parser text position to 1.
    IStringParser::skip
      This enumerator skips one token in the text. It is equivalent to >> temp, where temp is a temporary IString that is discarded. This is equivalent to using '.' in REXX.
    IStringParser::Skip
      An object of this class skips a given number of tokens.
  You can also use the left-shift operator with an unsigned numeric parameter. This repositions the parser object to the specified column. Note that the parameter is not relative as it is in the case of the right-shift operator. Instead, it is an absolute column position.

### IStringParser - Member Functions and Data by Group

### Constructors & Destructor

The destructor member is the default. The constructor members are protected to prevent you from creating objects except via use of the shift operators.

You can construct a string parser object by providing the following:

- A string that defines the text to be parsed
- An existing parser object (copy constructor)

You construct parser objects by applying the right-shift operator to a string. The constructor is protected to prevent you from creating objects except via use of those operators. Creation is prevented because of the nature of string parser objects. Because they hold references to operands, it is unwise to permit the objects to persist beyond the scope of those operands.

~IStringParser

      public:
      ~IStringParser()

  Destructs a string parser object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IStringParser
  Constructs a string parser object.

  Overload 1

      protected:
      IStringParser(const IStringParser& parser)

  Construct an object from an existing IStringParser object. The IStringParser object specifies the text string to parse. This constructor increments the usage count of the IStringParser object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      protected:
      IStringParser(const IString& text)

  Construct an object from an IString object. The IString object specifies the text string to parse.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Absolute Column Positioning

Use these members to reset the parser text position to an absolute column number.

operator <<

      public:
      IStringParser& operator <<(unsigned long position)

  Changes the parser text position to an absolute column number. This is a left-shift operator.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Parsing

These methods provide string parsing services.

operator >>

  Parses the text string. The right-shift operator is the primary function for parsing the text string. The Open Class Library overloads this function, so you can specify how you want the text string parsed via the type of parameter accepted by a particular overload.

  Overload 1

      public:
      IStringParser& operator >>(const SkipWords& skipObject)

  Skips the next n words in the parser text, where n is the number of words specified when constructing the IStringParser::SkipWords object.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IStringParser& operator >>(Command command)

  Resets the parser text position as follows:

  - To the beginning of the text
  - To skip the next token in the parser text
  Use the enumeration IStringParser::Command to specify the parsing token.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Pattern Matching

Use these members to advance to the next occurrence of the argument pattern in the parser text. Upon return, the parser is positioned at the next character beyond the text that matched the pattern. If the pattern is not found, the parser is positioned off the end of the text.

When using an IString as a pattern, you should cast it to a const IString reference.

operator >>

  Parses the text string. The right-shift operator is the primary function for parsing the text string. The Open Class Library overloads this function, so you can specify how you want the text string parsed via the type of parameter accepted by a particular overload.

  Overload 1

      public:
      IStringParser& operator >>(const IStringTest& test)

  Applies the IStringTest object to the parser text and moves the parser text position to the next character that satisfies the string test. If the string test is not satisfied, the parser moves the position off the end of the parser text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IStringParser& operator >>(const char* pattern)

  Finds a matching pattern within the parser text and moves the parser text position. If the pattern is not found, the parser moves the position off the end of the parser text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 3

      public:
      IStringParser& operator >>(const IString& pattern)

  Finds a matching pattern within the parser text and moves the parser text position. If the pattern is not found, the parser moves the position off the end of the parser text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 4

      public:
      IStringParser& operator >>(char pattern)

  Finds a matching pattern within the parser text and moves the parser text position. If the pattern is not found, the parser moves the position off the end of the parser text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Relative Column Positioning

Use these members to move the parser text position relative to its current position. A negative argument moves backward; a positive argument moves forward. The adjustment is made starting at the point at which the prior parsing instruction started.

For example:

       "1234" >> token1 >> 1 >> token2 >> 2 >> token3;

This results in the following:

       token1 == "1"
       token2 == "23"
       token3 == "4"

operator >>

  Parses the text string. The right-shift operator is the primary function for parsing the text string. The Open Class Library overloads this function, so you can specify how you want the text string parsed via the type of parameter accepted by a particular overload.

  Overload 1

      public:
      IStringParser& operator >>(unsigned long delta)

  Moves the parser text position relative to the current parser text position. For example:

         "1234" >> token1 >> 1 >> token2 >> 2 >> token3;

  results in:

         token1 == "1"
         token2 == "23"
         token3 == "4"

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      IStringParser& operator >>(int delta)

  Moves the parser text position relative to the current parser text position. For example:

         "1234" >> token1 >> 1 >> token2 >> 2 >> token3;

  results in:

         token1 == "1"
         token2 == "23"
         token3 == "4"

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Tokens

Use these members to parse the next token from the parser object and place it into the IString operand. By necessity, these members place the rest of the parser text into the string. When the parser encounters a subsequent parsing instruction, it goes back and adjusts the token placed into the string.

For example:

      "token1 token2" >> token1    // token1 == token1 token2 at this point
                      >> token2;          // token2 == "token2" and
                                              // token1 == "token1"

operator >>

      public:
      IStringParser& operator >>(IString& token)

  Parses the text string. The right-shift operator is the primary function for parsing the text string. The Open Class Library overloads this function, so you can specify how you want the text string parsed via the type of parameter accepted by a particular overload.

  Parses the next token from the object into the IString object. This parameter places the rest of the parser text into the IString object. When the parser encounters a subsequent parsing instruction, it adjusts the token placed into the string. For example:

        token1 token2 >> token1   // token1 == "token1 token2" at this point
                        >> token2;       // token2 == token2 and
                                             // token1  == token1.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IStringParser - Enumerations

Command

      enum Command { reset,
                     skipWord }

  These enumerators specify special-purpose parsing tokens:

  reset
    Resets the parser position to 1.
  skipWord
    Causes the parser to skip one token (that is, a word) in the input text.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IStringParser - Associated Globals

operator <<

      IStringParser operator <<(const IString& text, unsigned long position)

  Implicitly constructs an IStringParser object from a string and performs absolute positioning on the object.

operator >>

      IStringParser operator >>(const IString& text, const IStringParser::SkipWords& skipObject)

  Implicitly constructs an IStringParser object from a string and skips the number of words specified by the IStringParser::SkipWords object.

operator >>

      IStringParser operator >>(const IString& text, IString& token)

  Implicitly constructs an IStringParser object from a string and parses the text into the specified token string object.

operator >>

      IStringParser operator >>(const IString& text, const IString& pattern)

  Implicitly constructs an IStringParser object from a string and performs pattern matching on the object.

operator >>

      IStringParser operator >>(const IString& text, const IStringTest& test)

  Implicitly constructs an IStringParser object from a string and performs pattern matching based on the IStringTest object.

operator >>

      IStringParser operator >>(const IString& text, IStringParser::Command command)

  Implicitly constructs an IStringParser object from a string and applies the IStringParser::Command to the object.

operator >>

      IStringParser operator >>(const IString& text, unsigned long position)

  Implicitly constructs an IStringParser object from a string and performs relative positioning on the object.

operator >>

      IStringParser operator >>(const IString& text, int position)

  Implicitly constructs an IStringParser object from a string and performs relative positioning on the object.

operator >>

      IStringParser operator >>(const IString& text, const char* pattern)

  Implicitly constructs an IStringParser object from a string and performs pattern matching on the object.

operator >>

      IStringParser operator >>(const IString& text, char pattern)

  Implicitly constructs an IStringParser object from a string and performs pattern matching on the object.

### IStringParser - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None