---

tvr_std::basic_substring Template Class Reference

Provides generic substring capabilities to basic_string. More...

#include <basic_substring.h>

List of all members.

Public Types
typedef basic_string<Ch>::size_type	size_type
	The string's size_type.
Public Methods
Constructors.
	basic_substring (basic_string<Ch>& s, size_type start, size_type len, bool doReverse=false)
	Manual constructor. More...
	basic_substring (basic_string<Ch>& s, const basic_string<Ch>& s2, bool doReverse=false)
	String constructor. More...
	basic_substring (basic_string<Ch>& s, const Ch* p, bool doReverse=false)
	Character string constructor. More...
Assignment operators.
The assignment operators will modify the original string this substring was constructed from. The substring will attempt to find the next substring matching the original substring. If this substring is invalid, nothing happens (not even a thrown exception). This runs counter to the original idea in Stroustrup's book. I view it as an enhancement. Avoid infinite loops with the 'bool' operator.
basic_substring&	operator= (const basic_string<Ch>& in)
	Assigns a string to the substring. More...
basic_substring&	operator= (const basic_substring<Ch>& in)
	Assigns a substring to this substring. More...
basic_substring&	operator= (const Ch* in)
	Assigns a set of characters to the substring. More...
basic_substring&	operator= (Ch in)
	Assigns a character to the substring. More...
Inserts text before or after the substring.
This does not advance the substring. Use the iterators afterwards.
basic_substring&	prepend (const basic_string<Ch>& in)
	Inserts the text of the string before the substring. More...
basic_substring&	prepend (const Ch* in)
	Inserts the text of the string before the substring. More...
basic_substring&	append (const basic_string<Ch>& in)
	Inserts the text of the string after the substring. More...
basic_substring&	append (const Ch* in)
	Inserts the text of the string after the substring. More...
Casting operators.
	operator const basic_string () const
	Acquires the text of the substring. More...
	operator const bool () const
	Acquires the state of the substring. More...
Iterator operators.
When the iterator operator reaches the end, the substring becomes invalid. Once a substring becomes invalid, it will always remain invalid. You cannot reverse-iterate back to a valid substring.
basic_substring&	operator++ ()
basic_substring&	operator++ (int)
basic_substring&	operator-- ()
basic_substring&	operator-- (int)

---

Detailed Description

template<class Ch> template class tvr_std::basic_substring

Provides generic substring capabilities to basic_string.

This is inspired by Stroustrup's example in Section 20.3.13 of his "The C++ Programming Language". In it, he describes a substring class that's a little lighter than this one. He also mentioned that it might be more interesting to create a regular expression class along the same line (perhaps a project for another day). I thought it might be useful, so I extended it.

Basically, use the constructors to create a new substring. If you add a 'true' to the list of parameters, the substring will work in reverse (starting at the end, and working its way towards the beginning).

You may iterate to the next matching substring using either of the iterator operators(post or prefix,decrement or increment). The iterators will not modify the actual string.

The only way to actually modify a string through the substring is to assign a string to the substring. This causes the substring to replace the substring in the string with whatever you assigned, and iterate the substring to the next matching substring.

When you iterate past the end, the substring becomes invalid, and is no longer useful. You may, however, assign another substring to it (assigning substrings to a substring acts as a copy, and does not modify the string).

You may use the string operator to acquire the text of the substring.

You may also use the bool operator to test whether the substring is valid or not.

Some examples:

 #include "basic_substring.h"

 using namespace std;
 using namespace tvr_std;

 string someText("I'm a little teapot, short and stout.");
 cout << someText << endl;
 substring sub(someText, "little");
 sub = "gaudy";
 sub = substring(someText, "short");
 sub = "gaudy";
 sub = substring(someText, "stout");
 sub = "gaudy";
 // By now, the string is "I'm a gaudy teapot, gaudy and gaudy.".
 cout << someText << endl;
 sub = substring(someText, "gaudy");
 while (sub) {
         // uses the bool operator to check for validity
         sub = "little";
 }
 // Now, the string is "I'm a little teapot, little and little."
 cout << someText << endl;
 sub = substring(someText, "little", true); // reverse substring.
 sub = "stout";
 sub = "short";
 // And so, we should be back to "I'm a little teapot, short and stout."
 cout << someText << endl;

---

Constructor & Destructor Documentation

template<classCh> tvr_std::basic_substring<Ch>::basic_substring<Ch> ( basic_string< Ch >& s, size_type start, size_type len, bool doReverse = false ) [inline]

Manual constructor. Lets you manually set up the substring. Parameters: s   The string whose substring you want. start   The starting position for the substring. len   The length of the substring. doReverse   When set to true, this substring iterates in reverse.

template<classCh> tvr_std::basic_substring<Ch>::basic_substring<Ch> ( basic_string< Ch >& s, const basic_string< Ch >& s2, bool doReverse = false ) [inline]

String constructor. Lets you create a substring based on another string. Parameters: s   The string whose substring you want. s2   The substring you want to find. doReverse   When set to true, this substring iterates in reverse.

template<classCh> tvr_std::basic_substring<Ch>::basic_substring<Ch> ( basic_string< Ch >& s, const Ch * p, bool doReverse = false ) [inline]

Character string constructor. Lets you create a substring based on the base character string type. Parameters: s   The string whose substring you want. p   The substring you want to find. doReverse   When set to true, this substring iterates in reverse.

---

Member Function Documentation

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::append ( const Ch * in ) [inline]

Inserts the text of the string after the substring. Parameters: in   The string you wish to append. Returns: Returns this.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::append ( const basic_string< Ch >& in ) [inline]

Inserts the text of the string after the substring. Parameters: in   The string you wish to append. Returns: Returns this.

template<classCh> tvr_std::basic_substring<Ch>::operator const basic_string< Ch > ( ) const [inline]

Acquires the text of the substring. In case you forgot.

template<classCh> tvr_std::basic_substring<Ch>::operator const bool ( ) const [inline]

Acquires the state of the substring. Returns: Returns true if the substring is valid, false otherwise.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::operator= ( Ch in ) [inline]

Assigns a character to the substring. This replaces the contents of the substring with a single character. This iterates to the next substring thereafter. Parameters: in   The character you want to use to replace the substring. Returns: Returns this.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::operator= ( const Ch * in ) [inline]

Assigns a set of characters to the substring. This replaces the contents of the substring with a new string, iterating to the next substring. Parameters: in   The string you want to use to replace the substring. Returns: Returns this.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::operator= ( const basic_substring< Ch >& in ) [inline]

Assigns a substring to this substring. This completely changes the original state of the substring. This doesn't merely take the incoming substring's 'string' and assign it to this substring, this changes the internal state to match that of the incoming string. Use this operator to reuse substring variables. Parameters: in   The substring you want to copy. Returns: Returns this.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::operator= ( const basic_string< Ch >& in ) [inline]

Assigns a string to the substring. This replaces the contents of the substring with a new string, iterating to the next substring. Parameters: in   The string you want to use to replace the substring. Returns: Returns this.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::prepend ( const Ch * in ) [inline]

Inserts the text of the string before the substring. Parameters: in   The string you wish to prepend. Returns: Returns this.

template<classCh> basic_substring<Ch> & tvr_std::basic_substring<Ch>::prepend ( const basic_string< Ch >& in ) [inline]

Inserts the text of the string before the substring. Parameters: in   The string you wish to prepend. Returns: Returns this.

---

The documentation for this class was generated from the following file:

• basic_substring.h

---