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:

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:

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.


[view class]
~IStringParser
public:
~IStringParser()
Destructs a string parser object.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
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.


[view class]
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.


[view class]
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:

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.


[view class]
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"


[view class]
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"


[view class]
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


[view class]
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

Inherited Public Data

Inherited Protected Functions

Inherited Protected Data