RWCSubString Class Reference

Allows some subsection of an RWCString to be addressed by defining a starting position and an extent. More...

#include <rw/cstring.h>

Public Member Functions
bool	isNull () const
size_t	length () const
int	operator! () const
char &	operator() (size_t i)
char	operator() (size_t i) const
RWCSubString &	operator= (const char *str)
RWCSubString &	operator= (const RWCConstSubString &str)
RWCSubString &	operator= (const RWCString &str)
RWCSubString &	operator= (const RWCSubString &str)
RWCSubString &	operator= (const std::string &str)
char &	operator[] (char i)
char	operator[] (char i) const
char &	operator[] (int i)
char	operator[] (int i) const
char &	operator[] (long i)
char	operator[] (long i) const
char &	operator[] (long long i)
char	operator[] (long long i) const
char &	operator[] (short i)
char	operator[] (short i) const
char &	operator[] (signed char i)
char	operator[] (signed char i) const
char &	operator[] (unsigned char i)
char	operator[] (unsigned char i) const
char &	operator[] (unsigned int i)
char	operator[] (unsigned int i) const
char &	operator[] (unsigned long i)
char	operator[] (unsigned long i) const
char &	operator[] (unsigned long long i)
char	operator[] (unsigned long long i) const
char &	operator[] (unsigned short i)
char	operator[] (unsigned short i) const
size_t	start () const
void	toLower ()
void	toUpper ()

Friends
class	RWCConstSubString
class	RWCString

Related Symbols
(Note that these are not member symbols.)
std::strong_ordering	operator (const RWCSubString &lhs, char rhs)
std::strong_ordering	operator (const RWCSubString &lhs, const char *rhs)
std::strong_ordering	operator (const RWCSubString &lhs, const RWCConstSubString &rhs)
std::strong_ordering	operator (const RWCSubString &lhs, const RWCSubString &rhs)
std::strong_ordering	operator (const RWCSubString &lhs, const std::string &rhs)
bool	operator== (const RWCSubString &lhs, char rhs)
bool	operator== (const RWCSubString &lhs, const char *rhs)
bool	operator== (const RWCSubString &lhs, const RWCConstSubString &rhs)
bool	operator== (const RWCSubString &lhs, const RWCSubString &rhs)
bool	operator== (const RWCSubString &lhs, const std::string &rhs)

Detailed Description

The class RWCSubString allows some subsection of an RWCString to be addressed by defining a starting position and an extent. For example the 7^th through the 11^th elements, inclusive, would have a starting position of 7 and an extent of 5. The specification of a starting position and extent can also be done on your behalf by such functions as RWCString::strip() or the overloaded function call operator taking a regular expression as an argument. There are no public constructors – RWCSubStrings are constructed by various functions of the RWCString class and then destroyed immediately.

A zero length substring is one with a defined starting position and an extent of zero. It can be thought of as starting just before the indicated character, but not including it. It can be used as an lvalue. A null substring is also legal and is frequently used to indicate that a requested substring, perhaps through a search, does not exist. A null substring can be detected with member function isNull(). However, it cannot be used as an lvalue.

Synopsis

#include <rw/cstring.h>
RWCString s("test string");
s(6, 3);  // "tri"

Persistence

None

Example

#include <rw/cstring.h>
#include <iostream>
 
int main() {
  RWCString s("What I tell you is true.");
 
  std::cout << "Take the string: [" << s << "]\n";
 
  // Create a substring and use it as an lvalue:
  s(16, 0) = "three times ";
 
  std::cout << "After assigning text to a substring, the full string "
               "becomes: \n["
            << s << "]" << std::endl;
 
  return 0;
}

Program output:

Take the string: [What I tell you is true.]
After assigning text to a substring, the full string becomes:
[What I tell you three times is true.]

Member Function Documentation

isNull()

bool RWCSubString::isNull ( ) const

inline

Returns true if this is a null substring.

length()

size_t RWCSubString::length ( ) const

inline

Returns the extent (i.e., length) of the substring.

operator!()

int RWCSubString::operator! ( ) const

inline

Returns true if this is a null substring.

operator()() [1/2]

char & RWCSubString::operator() ( size_t i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. Bounds checking is enabled by defining the preprocessor macro RWBOUNDS_CHECK before including <rw/cstring.h>.

Exceptions

RWBoundsErr

if RWBOUNDS_CHECK is defined and the index is out of range.

operator()() [2/2]

char RWCSubString::operator() ( size_t i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. Bounds checking is enabled by defining the preprocessor macro RWBOUNDS_CHECK before including <rw/cstring.h>.

Exceptions

RWBoundsErr

if RWBOUNDS_CHECK is defined and the index is out of range.

operator=() [1/5]

RWCSubString & RWCSubString::operator= ( const char * str )

inline

Assignment from a character string. Example:

RWCString str("Mary had a lamb");
char dat[] = "Perrier";
str(11, 4) = dat;  // "Mary had a Perrier"

The number of characters selected need not match; if they differ, str is resized appropriately. If self is the null substring, then the statement has no effect. Returns a reference to self.

operator=() [2/5]

RWCSubString & RWCSubString::operator= ( const RWCConstSubString & str )

inline

Assignment from an RWCConstSubString. Example:

const RWCString a(10, 'a');
RWCString b;
// ...
b(2, 3) = a(5, 5);

Copies 5 characters of a's data into the substring b(2,3). The number of elements need not match; if they differ, b is resized appropriately. If self is the null substring, then the statement has no effect. Returns a reference to self.

operator=() [3/5]

RWCSubString & RWCSubString::operator= ( const RWCString & str )

inline

Assignment from an RWCString. Example:

RWCString a;
RWCString b;
// ...
b(2, 3) = a;

Copies a's data into the substring b(2,3). The number of elements need not match; if they differ, b is resized appropriately. If self is the null substring, then the statement has no effect. Returns a reference to self.

operator=() [4/5]

RWCSubString & RWCSubString::operator= ( const RWCSubString & str )

inline

Assignment from an RWCSubString. Example:

RWCString a(10, 'a');
RWCString b;
// ...
b(2, 3) = a(5, 5);

Copies 5 characters of a's data into the substring b(2,3). The number of elements need not match; if they differ, b is resized appropriately. If self is the null substring, then the statement has no effect. Returns a reference to self.

operator=() [5/5]

RWCSubString & RWCSubString::operator= ( const std::string & str )

inline

Assignment from an std::string. Example:

std::string a;
RWCString b;
// ...
b(2, 3) = a;

Copies a's data into the substring b(2,3). The number of elements need not match; if they differ, b is resized appropriately. If self is the null substring, then the statement has no effect. Returns a reference to self.

operator[]() [1/22]

char & RWCSubString::operator[] ( char i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [2/22]

char RWCSubString::operator[] ( char i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [3/22]

char & RWCSubString::operator[] ( int i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [4/22]

char RWCSubString::operator[] ( int i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [5/22]

char & RWCSubString::operator[] ( long i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [6/22]

char RWCSubString::operator[] ( long i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [7/22]

char & RWCSubString::operator[] ( long long i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [8/22]

char RWCSubString::operator[] ( long long i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [9/22]

char & RWCSubString::operator[] ( short i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [10/22]

char RWCSubString::operator[] ( short i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [11/22]

char & RWCSubString::operator[] ( signed char i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [12/22]

char RWCSubString::operator[] ( signed char i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [13/22]

char & RWCSubString::operator[] ( unsigned char i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [14/22]

char RWCSubString::operator[] ( unsigned char i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [15/22]

char & RWCSubString::operator[] ( unsigned int i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [16/22]

char RWCSubString::operator[] ( unsigned int i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [17/22]

char & RWCSubString::operator[] ( unsigned long i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [18/22]

char RWCSubString::operator[] ( unsigned long i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [19/22]

char & RWCSubString::operator[] ( unsigned long long i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [20/22]

char RWCSubString::operator[] ( unsigned long long i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [21/22]

char & RWCSubString::operator[] ( unsigned short i )

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

operator[]() [22/22]

char RWCSubString::operator[] ( unsigned short i ) const

inline

Returns the i ^th character of the substring. The index i must be between zero and the length of the substring less one. i is converted to a size_t and bounds checking is performed.

Exceptions

RWBoundsErr

if the index is out of range.

start()

size_t RWCSubString::start ( ) const

inline

Returns the index of the starting element of the substring.

toLower()

void RWCSubString::toLower ( )

inline

Changes all upper-case letters in self to lower-case. Uses the C++ Standard Library function std::tolower().

toUpper()

void RWCSubString::toUpper ( )

inline

Changes all lower-case letters in self to upper-case. Uses the C++ Standard Library function std::toupper().

Friends And Related Symbol Documentation

operator() [1/5]

std::strong_ordering operator<=> ( const RWCSubString & lhs, char rhs )

related

Performs a lexicographical comparison of lhs to rhs, as if it were an RWCString containing that character. The function is equivalent to:

lhs <=> RWCString(rhs)

Note

If a compiler does not support rewritten expressions (i.e. before C++20), comparison operators are explicitly implemented to provide equivalent behavior.

operator() [2/5]

std::strong_ordering operator<=> ( const RWCSubString & lhs, const char * rhs )

related

Performs lexicographical comparison of lhs to rhs. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), comparison operators are explicitly implemented to provide equivalent behavior.

This function is incompatible with rhs strings with embedded nulls.

operator() [3/5]

std::strong_ordering operator<=> ( const RWCSubString & lhs, const RWCConstSubString & rhs )

related

Performs lexicographical comparison of lhs to rhs. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), comparison operators are explicitly implemented to provide equivalent behavior.

operator() [4/5]

std::strong_ordering operator<=> ( const RWCSubString & lhs, const RWCSubString & rhs )

related

Performs lexicographical comparison of lhs to rhs. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), comparison operators are explicitly implemented to provide equivalent behavior.

operator() [5/5]

std::strong_ordering operator<=> ( const RWCSubString & lhs, const std::string & rhs )

related

Performs lexicographical comparison of lhs to rhs. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), comparison operators are explicitly implemented to provide equivalent behavior.

operator==() [1/5]

bool operator== ( const RWCSubString & lhs, char rhs )

related

Returns true if lhs is equal to rhs, as if it were an RWCString containing that character. The function is equivalent to:

lhs == RWCString(rhs)

Note

If a compiler does not support rewritten expressions (i.e., before C++20), equality operators are explicitly implemented to provide equivalent behavior.

operator==() [2/5]

bool operator== ( const RWCSubString & lhs, const char * rhs )

related

Returns true if lhs is equal to rhs. Otherwise returns false. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), equality operators are explicitly implemented to provide equivalent behavior.

This function is incompatible with rhs strings with embedded nulls.

operator==() [3/5]

bool operator== ( const RWCSubString & lhs, const RWCConstSubString & rhs )

related

Returns true if lhs is equal to rhs. Otherwise returns false. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), equality operators are explicitly implemented to provide equivalent behavior.

operator==() [4/5]

bool operator== ( const RWCSubString & lhs, const RWCSubString & rhs )

related

Returns true if lhs is equal to rhs. Otherwise returns false. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), equality operators are explicitly implemented to provide equivalent behavior.

operator==() [5/5]

bool operator== ( const RWCSubString & lhs, const std::string & rhs )

related

Returns true if lhs is equal to rhs. Otherwise returns false. Use member RWCString::collate() or RWCString::strXForm() for locale-sensitive comparisons.

Note

If a compiler does not support rewritten expressions (i.e. before C++20), equality operators are explicitly implemented to provide equivalent behavior.