Hunny Software Home || Hunny MIME++ Home || Hunny Mail++ Home

Main Page | Namespace List | Class Hierarchy | Class List | Namespace Members | Class Members

String Class Reference

List of all members.

Detailed Description

String is the workhorse of the Hunny MIME++ library. Creating, parsing, or otherwise manipulating MIME documents is basically a matter of manipulating strings. String provides all the basic functionality required of a string object, including copying, comparing, concatenating, and so on.

String is similar to the std::string class that is part of the ANSI standard C++ library. Some of the member functions present in the ANSI std::string are not present in String: mostly these are the functions that deal with iterators. String also includes some member functions and class utility functions that are not a part of the ANSI std::string class.

String makes extensive use of copy-on-write, even when extracting substrings. It is this feature that distiguishes String from most other string classes. String also handles binary data, which can contain embedded NUL characters.


Public Member Functions

 String ()
 Default constructor.
 String (const String &str, size_t pos=0, size_t len=npos)
 Copy constructor.
 String (const char *buf, size_t len)
 Constructor that takes a buffer intializer.
 String (const char *cstr)
 Constructor that takes a NUL-terminated C string initializer.
 String (size_t len, char ch)
 Constructor that takes a single character initializer.
 String (StringRep *rep, size_t offset, size_t length)
 Constructor that takes a StringRep initializer.
virtual ~String ()
 Destructor.
String & operator= (const String &str)
 Assignment operator.
String & operator= (const char *cstr)
 Assignment operator.
String & operator= (char ch)
 Assignment operator.
size_t size () const
 Returns the length of the string.
size_t length () const
 Returns the length of the string.
size_t max_size () const
 Returns the maximum length of the string.
void resize (size_t len, char ch)
 Changes the length of the string.
void resize (size_t len)
 Changes the length of the string.
size_t capacity () const
 Returns the size of the internal buffer.
void reserve (size_t size)
 Reserves internal buffer capacity.
void clear ()
 Sets the string to the empty string.
bool empty () const
 Returns true if the string is empty.
const char & operator[] (size_t pos) const
 Returns the char at the specified position.
char & operator[] (size_t pos)
 Returns the char at the specified position.
const char & at (size_t pos) const
 Returns the char at the specified position.
char & at (size_t pos)
 Returns the char at the specified position.
String & operator+= (const String &str)
 Appends a string.
String & operator+= (const char *cstr)
 Appends a NUL-terminated C string.
String & operator+= (char ch)
 Appends a single character.
String & append (const String &str)
 Appends a string.
String & append (const String &str, size_t pos, size_t len)
 Appends a substring.
String & append (const char *buf, size_t len)
 Appends a buffer.
String & append (const char *cstr)
 Appends a NUL-terminated C string.
String & append (size_t len, char ch)
 Appends a single character.
String & assign (const String &str)
 Assigns from a string.
String & assign (const String &str, size_t pos, size_t len)
 Assigns from a substring.
String & assign (const char *buf, size_t len)
 Assigns from a buffer.
String & assign (const char *cstr)
 Assigns from a NUL-terminated C string.
String & assign (size_t len, char ch)
 Assigns from a single character.
String & insert (size_t pos, const String &str)
 Inserts from a string.
String & insert (size_t pos1, const String &str, size_t pos2, size_t len)
 Inserts from a substring.
String & insert (size_t pos, const char *buf, size_t len)
 Inserts from a buffer.
String & insert (size_t pos, const char *cstr)
 Inserts from a NUL-terminated C string.
String & insert (size_t pos, size_t len, char ch)
 Inserts from a repeated character.
String & erase (size_t pos=0, size_t len=npos)
 Erases characters.
String & replace (size_t pos1, size_t len1, const String &str)
 Replaces characters.
String & replace (size_t pos1, size_t len1, const String &str, size_t pos2, size_t len2)
 Replaces characters.
String & replace (size_t pos1, size_t len1, const char *buf, size_t len2)
 Replaces characters.
String & replace (size_t pos1, size_t len1, const char *cstr)
 Replaces characters.
String & replace (size_t pos1, size_t len1, size_t len2, char ch)
 Replaces characters.
size_t copy (char *buf, size_t len, size_t pos=0) const
 Copies characters from a buffer to this string.
void swap (String &str)
 Swaps the contents of this string and another string.
const char * c_str () const
 Returns a pointer to the internal buffer (NUL-terminated).
const char * data () const
 Returns a pointer to the internal buffer (not NUL-terminated).
size_t find (const String &str, size_t pos=0) const
 Searches for a string.
size_t find (const char *buf, size_t pos, size_t len) const
 Searches for a string.
size_t find (const char *cstr, size_t pos=0) const
 Searches for a string.
size_t find (char ch, size_t pos=0) const
 Searches for a single character.
size_t rfind (const String &str, size_t pos=npos) const
 Searches backward for a string.
size_t rfind (const char *buf, size_t pos, size_t len) const
 Searches backward for a string.
size_t rfind (const char *cstr, size_t pos=npos) const
 Searches backward for a string.
size_t rfind (char ch, size_t pos=npos) const
 Searches backward for a single character.
size_t find_first_of (const String &str, size_t pos=0) const
 Searches forward for a matching character.
size_t find_first_of (const char *buf, size_t pos, size_t len) const
 Searches forward for a matching character.
size_t find_first_of (const char *cstr, size_t pos=0) const
 Searches forward for a matching character.
size_t find_last_of (const String &str, size_t pos=npos) const
 Searches backward for a matching character.
size_t find_last_of (const char *buf, size_t pos, size_t len) const
 Searches backward for a matching character.
size_t find_last_of (const char *cstr, size_t pos=npos) const
 Searches backward for a matching character.
size_t find_first_not_of (const String &str, size_t pos=0) const
 Searches forward for a non-matching character.
size_t find_first_not_of (const char *buf, size_t pos, size_t len) const
 Searches forward for a non-matching character.
size_t find_first_not_of (const char *cstr, size_t pos=0) const
 Searches forward for a non-matching character.
size_t find_last_not_of (const String &str, size_t pos=npos) const
 Searches backward for a non-matching character.
size_t find_last_not_of (const char *buf, size_t pos, size_t len) const
 Searches backward for a non-matching character.
size_t find_last_not_of (const char *cstr, size_t pos=npos) const
 Searches backward for a non-matching character.
String substr (size_t pos=0, size_t len=npos) const
 Returns a substring of this string.
int compare (const String &str) const
 Performs a string comparison.
int compare (size_t pos1, size_t len1, const String &str) const
 Performs a string comparison.
int compare (size_t pos1, size_t len1, const String &str, size_t pos2, size_t len2) const
 Performs a string comparison.
int compare (const char *cstr) const
 Performs a string comparison.
int compare (size_t pos1, size_t len1, const char *buf, size_t len2=npos) const
 Performs a string comparison.
void convertToLowerCase ()
 Converts all characters to lower case.
void convertToUpperCase ()
 Converts all characters to upper case.
void trim ()
 Removes space characters from the beginning and the end.

Static Public Attributes

const size_t npos = (size_t) -1
 Assigned the value (size_t)-1.

Constructor & Destructor Documentation

String (   ) 
 

This constructor is the default constructor, which sets the String object's contents to be empty.

String (  const String &  str,
size_t  pos = 0,
size_t  len = npos
) 
 

This constructor is the copy constructor, which copies at most len characters beginning at position pos from str to the new String object. It will not copy more characters than what are available in str. pos must be less than or equal to str.length().

Parameters:
str string containing the characters to copy
pos offset of the segment in str to copy
len length of the segment in str to copy

String (  const char *  buf,
size_t  len
) 
 

This constructor copies len characters from the buffer buf to the new String object. buf need not be NUL-terminated and may contain NUL characters.

Parameters:
buf buffer containing the characters to copy
len the number of characters to copy

String (  const char *  cstr  ) 
 

This constructor copies the contents of the NUL-terminated string cstr to the new String object.

Parameters:
cstr NUL-terminated string to copy

String (  size_t  len,
char  ch
) 
 

This constructor sets the contents of the new String object to be the character ch repeated len times.

Parameters:
len how many times to repeat the character
ch character value to initialize the string

~String (   )  [virtual]
 

Destructor

Member Function Documentation

String & append (  size_t  len,
char  ch
) 
 

Appends the character ch repeated len times.

Parameters:
len number of characters to append
ch character value to append
Returns:
*this

String & append (  const char *  cstr  ) 
 

Appends characters from the NUL-terminated string cstr.

Parameters:
cstr NUL-terminated C string to append
Returns:
*this

String & append (  const char *  buf,
size_t  len
) 
 

Appends len characters from buf, which is not assumed to be NUL-terminated and which may contain embedded NULs.

Parameters:
buf buffer containing the characters to append
len the number of characters from buf to append
Returns:
*this

String & append (  const String &  str,
size_t  pos,
size_t  len
) 
 

Appends at most len characters from str beginning at position pos. pos must be less than or equal to str.length(). The function will not append more characters than what are available in str.

Parameters:
str string containing the characters to append
pos offset of the characters in str to append
len number of characters to append
Returns:
*this

String & append (  const String &  str  ) 
 

Appends another string to this string.

Parameters:
str string to append
Returns:
*this

String & assign (  size_t  len,
char  ch
) 
 

Assigns the character ch repeated len times.

Parameters:
len number of characters to assign
ch character value to assign
Returns:
*this

String & assign (  const char *  cstr  ) 
 

Assigns characters from the NUL-terminated C string cstr.

Parameters:
cstr NUL-terminated C string to assign
Returns:
*this

String & assign (  const char *  buf,
size_t  len
) 
 

Assigns len characters from buf, which is not assumed to be NUL-terminated and which may contain embedded NULs.

Parameters:
buf buffer containing the characters to assign
len the number of characters in buf to assign
Returns:
*this

String & assign (  const String &  str,
size_t  pos,
size_t  len
) 
 

Assigns at most len characters from str beginning at position pos. pos must be less than or equal to str.length(). The function will not assign more characters than what are available in str.

Parameters:
str string containing the characters to assign
pos offset of the characters in str to assign
len number of characters to assign
Returns:
*this

String & assign (  const String &  str  ) 
 

Assigns all of the characters from str.

Parameters:
str string to assign
Returns:
*this

char & at (  size_t  pos  ) 
 

Returns the character at position pos in the string's contents. The non-const version returns an lvalue that may be assigned to. Note that the non-const version always assumes that the contents will be modified and therefore always copies a shared internal buffer before it returns.

Parameters:
pos position of the character to return
Returns:
character at the specified position

const char & at (  size_t  pos  )  const
 

Returns the character at position pos in the string's contents. The non-const version returns an lvalue that may be assigned to. Note that the non-const version always assumes that the contents will be modified and therefore always copies a shared internal buffer before it returns.

Parameters:
pos position of the character to return
Returns:
character at the specified position

const char * c_str (   )  const
 

Ths member function permits access to the internal buffer used by the String object. c_str() returns a NUL-terminated string suitable for use in C library functions. data() returns a pointer to the internal buffer, which may not be NUL-terminated.

c_str() may copy the internal buffer in order to place the terminating NUL. This is not a violation of the const declaration: it is a logical const, not a bit-representation const. It could have the side effect of invalidating a pointer previously returned by c_str() or data().

The characters in the returned string should not be modified, and should be considered invalid after any call to a non-const member function or another call to c_str().

Returns:
NUL-terminated string with same contents as the String object
See also:
data()

size_t capacity (   )  const
 

Returns the size of the internal buffer used for this string, which will always be greater than or equal to the length of the string.

Returns:
capacity of the string

void clear (   ) 
 

Sets this string's contents to be empty.

int compare (  size_t  pos1,
size_t  len1,
const char *  buf,
size_t  len2 = npos
)  const
 

Compares a substring of this string to an array of characters. Returns -1, 0, or 1, depending on whether this substring is less than, equal to, or greater than the array of characters, respectively.

Parameters:
pos1 offset of the substring
len1 length of the substring
buf array of characters to compare
len2 number of chars in buf to compare
Returns:
respectively, -1, 0, or 1, if this substring is <, =, or > the characters in buf

int compare (  const char *  cstr  )  const
 

Compares this string to a NUL-terminated string. Returns -1, 0, or 1, depending on whether this string is less than, equal to, or greater than the NUL-terminated string, respectively.

Parameters:
cstr NUL-terminated "C" string to compare to
Returns:
respectively, -1, 0, or 1, if this string is <, =, or > cstr

int compare (  size_t  pos1,
size_t  len1,
const String &  str,
size_t  pos2,
size_t  len2
)  const
 

Compares a substring of this string to a substring of another string. Returns -1, 0, or 1, depending on whether this substring is less than, equal to, or greater than the other substring, respectively.

Parameters:
pos1 offset of the substring of this string
len1 length of the substring of this string
str string containing the substring to compare to
pos2 offset of the substring of str
len2 length of the substring of str
Returns:
respectively, -1, 0, or 1, if this substring is <, =, or > the substring of str

int compare (  size_t  pos1,
size_t  len1,
const String &  str
)  const
 

Compares a substring of this string to another string. Returns -1, 0, or 1, depending on whether the substring is less than, equal to, or greater than the other string, respectively.

Parameters:
pos1 offset of the substring
len1 length of the substring
str string to compare to
Returns:
respectively, -1, 0, or 1, if the substring is <, =, or > str

int compare (  const String &  str  )  const
 

Compares this string to another string. Returns -1, 0, or 1, depending on whether this string is less than, equal to, or greater than the other string, respectively.

Parameters:
str string to compare to
Returns:
respectively, -1, 0, or 1, if this string is <, =, or > str

void convertToLowerCase (   ) 
 

Converts this String object's characters to all lower case.

void convertToUpperCase (   ) 
 

Converts this String object's characters to all upper case.

size_t copy (  char *  buf,
size_t  len,
size_t  pos = 0
)  const
 

Copies at most len characters beginning at position pos from this string to the buffer pointed to by buf. Returns the number of characters copied.

Parameters:
buf destination buffer
len number of characters to copy
pos offset in this string of the characters to copy
Returns:
number of characters copied

const char * data (   )  const
 

Ths member function permits access to the internal buffer used by the String object. data() returns a pointer to the internal buffer, which may not be NUL-terminated. c_str() returns a NUL-terminated string suitable for use in C library functions.

The characters in the returned string should not be modified, and should be considered invalid after any call to a non-const member function or a call to c_str().

Returns:
pointer to the string's internal buffer
See also:
c_str()

bool empty (   )  const
 

Returns a true value if this string is empty

Returns:
true if this string is empty

String & erase (  size_t  pos = 0,
size_t  len = npos
) 
 

Erases (removes) at most len characters from this string beginning at position pos. The function will not erase more characters than what are available.

Parameters:
pos position of the first character to erase
len number of characters to erase
Returns:
*this

size_t find (  char  ch,
size_t  pos = 0
)  const
 

Performs a forward search for a character. If the search succeeds, the function returns the position of the first occurrence of the character in the string. If the search fails, the function returns String::npos.

Parameters:
ch character to search for
pos position in this string to start the search
Returns:
position of the first occurrence of the character; or String::npos if the search fails

size_t find (  const char *  cstr,
size_t  pos = 0
)  const
 

Performs a forward search for a substring. If the search succeeds, the function returns the position of the start of the first occurrence of the substring. If the search fails, the function returns String::npos.

This version of find searches from position pos for the NUL-terminated string cstr.

Parameters:
cstr NUL-terminated C string containing the substring to search for
pos position in this string to start the search
Returns:
position of the first occurrence of the substring; or String::npos if the search fails

size_t find (  const char *  buf,
size_t  pos,
size_t  len
)  const
 

Performs a forward search for a substring. If the search succeeds, the function returns the position of the start of the first occurrence of the substring. If the search fails, the function returns String::npos.

This version of find searches from position pos for the substring of len characters in buf, which need not be NUL-terminated and which may contain embedded NUL characters.

Parameters:
buf array of characters containing the substring to search for
pos position in this string to start the search
len length of the substring
Returns:
position of the first occurrence of the substring; or String::npos if the search fails

size_t find (  const String &  str,
size_t  pos = 0
)  const
 

Performs a forward search for a substring. If the search succeeds, the function returns the position of the start of the first occurrence of the substring. If the search fails, the function returns String::npos.

This version of find searches from position pos for the substring str.

Parameters:
str substring to search for
pos position in this string to start the search
Returns:
position of the first occurrence of the substring; or String::npos if the search fails

size_t find_first_not_of (  const char *  cstr,
size_t  pos = 0
)  const
 

Performs a forward search for any character not in a specified set of characters. The search starts at position pos. If the search succeeds, the function returns the position of the first character not in the set. If the search fails, the function returns String::npos.

In this version of find_first_not_of, the NUL-terminated C string cstr specifies the set of characters to skip.

Parameters:
cstr NUL-terminated C string containing the set of characters to skip
pos position in this string to start the search
Returns:
position of the first character not in the specified set; or String::npos if the search fails

size_t find_first_not_of (  const char *  buf,
size_t  pos,
size_t  len
)  const
 

Performs a forward search for any character not in a specified set of characters. The search starts at position pos. If the search succeeds, the function returns the position of the first character not in the set. If the search fails, the function returns String::npos.

In this version of find_first_not_of, the first len characters in buf specify the set of characters to skip.

Parameters:
buf pointer to an array containing the set of characters to skip
pos position in this string to start the search
len number of characters in buf
Returns:
position of the first character not in the specified set; or String::npos if the search fails

size_t find_first_not_of (  const String &  str,
size_t  pos = 0
)  const
 

Performs a forward search for any character not in a specified set of characters. The search starts at position pos. If the search succeeds, the function returns the position of the first character not in the set. If the search fails, the function returns String::npos.

In this version of find_first_not_of, the string str specifies the set of characters to skip.

Parameters:
str string containing the set of characters to skip
pos position in this string to start the search
Returns:
position of the first character not in the specified set; or String::npos if the search fails

size_t find_first_of (  const char *  cstr,
size_t  pos = 0
)  const
 

Performs a forward search for any character in a specified set of characters. The search starts at position pos. If the search succeeds, the function returns the position of the first character in the set. If the search fails, the function returns String::npos.

In this version of find_first_of, the NUL-terminated C string cstr specifies the set of characters to match.

Parameters:
cstr NUL-terminated C string containing the set of characters to match
pos position in this string to start the search
Returns:
position of the first character in the specified set; or String::npos if the search fails

size_t find_first_of (  const char *  buf,
size_t  pos,
size_t  len
)  const
 

Performs a forward search for any character in a specified set of characters. The search starts at position pos. If the search succeeds, the function returns the position of the first character in the set. If the search fails, the function returns String::npos.

In this version of find_first_of, the first len characters in buf specify the set of characters to match.

Parameters:
buf pointer to an array containing the set of characters to match
pos position in this string to start the search
len number of characters in buf
Returns:
position of the first character in the specified set; or String::npos if the search fails

size_t find_first_of (  const String &  str,
size_t  pos = 0
)  const
 

Performs a forward search for any character in a specified set of characters. The search starts at position pos. If the search succeeds, the function returns the position of the first character in the set. If the search fails, the function returns String::npos.

In this version of find_first_of, the string str specifies the set of characters to match.

Parameters:
str string containing the set of characters to match
pos position in this string to start the search
Returns:
position of the first character in the specified set; or String::npos if the search fails

size_t find_last_not_of (  const char *  cstr,
size_t  pos = npos
)  const
 

Performs a reverse search for any character not in a specified set of characters. If pos is less than the length of the string, the search starts at position pos. If pos is greater than or equal to the length of the string, the search starts at the end of the string. If the search succeeds, the function returns the position of the first character not in the set. If the search fails, the function returns String::npos.

In this version of find_last_not_of, the NUL-terminated C string cstr specifies the set of characters to skip.

Parameters:
cstr NUL-terminated C string containing the set of characters to skip
pos position in this string to start the search
Returns:
position of the first character not in the specified set; or String::npos if the search fails

size_t find_last_not_of (  const char *  buf,
size_t  pos,
size_t  len
)  const
 

Performs a reverse search for any character not in a specified set of characters. If pos is less than the length of the string, the search starts at position pos. If pos is greater than or equal to the length of the string, the search starts at the end of the string. If the search succeeds, the function returns the position of the first character not in the set. If the search fails, the function returns String::npos.

In this version of find_last_not_of, the first len characters in buf specify the set of characters to skip.

Parameters:
buf pointer to an array containing the set of characters to skip
pos position in this string to start the search
len number of characters in buf
Returns:
position of the first character not in the specified set; or String::npos if the search fails

size_t find_last_not_of (  const String &  str,
size_t  pos = npos
)  const
 

Performs a reverse search for any character not in a specified set of characters. If pos is less than the length of the string, the search starts at position pos. If pos is greater than or equal to the length of the string, the search starts at the end of the string. If the search succeeds, the function returns the position of the first character not in the set. If the search fails, the function returns String::npos.

In this version of find_last_not_of, the string str specifies the set of characters to skip.

Parameters:
str string containing the set of characters to skip
pos position in this string to start the search
Returns:
position of the first character not in the specified set; or String::npos if the search fails

size_t find_last_of (  const char *  cstr,
size_t  pos = npos
)  const
 

Performs a reverse search for any character in a specified set of characters. If pos is less than the length of the string, the search starts at position pos. If pos is greater than or equal to the length of the string, the search starts at the end of the string. If the search succeeds, the function returns the position of the first character in the set. If the search fails, the function returns String::npos.

In this version of find_last_of, the NUL-terminated C string cstr specifies the set of characters to match.

Parameters:
cstr NUL-terminated C string containing the set of characters to match
pos position in this string to start the search
Returns:
position of the first character in the specified set; or String::npos if the search fails

size_t find_last_of (  const char *  buf,
size_t  pos,
size_t  len
)  const
 

Performs a reverse search for any character in a specified set of characters. If pos is less than the length of the string, the search starts at position pos. If pos is greater than or equal to the length of the string, the search starts at the end of the string. If the search succeeds, the function returns the position of the first character in the set. If the search fails, the function returns String::npos.

In this version of find_last_of, the first len characters in buf specify the set of characters to match.

Parameters:
buf pointer to an array containing the set of characters to match
pos position in this string to start the search
len number of characters in buf
Returns:
position of the first character in the specified set; or String::npos if the search fails

size_t find_last_of (  const String &  str,
size_t  pos = npos
)  const
 

Performs a reverse search for any character in a specified set of characters. If pos is less than the length of the string, the search starts at position pos. If pos is greater than or equal to the length of the string, the search starts at the end of the string. If the search succeeds, the function returns the position of the first character in the set. If the search fails, the function returns String::npos.

In this version of find_last_of, the string str specifies the set of characters to match.

Parameters:
str string containing the set of characters to match
pos position in this string to start the search
Returns:
position of the first character in the specified set; or String::npos if the search fails

String & insert (  size_t  pos,
size_t  len,
char  ch
) 
 

Inserts the character ch repeated len times into this string at position pos.

Parameters:
pos position in this string where characters should be inserted
len number of characters to insert
ch character to insert (which is repeated len times)
Returns:
*this

String & insert (  size_t  pos,
const char *  cstr
) 
 

Inserts characters from the NUL-terminated C string cstr into this string at position pos.

Parameters:
pos position in this string where characters should be inserted
cstr NUL-terminated C string containing characters to insert
Returns:
*this

String & insert (  size_t  pos,
const char *  buf,
size_t  len
) 
 

Inserts len characters from the array buf into this string at position pos. buf may contain embedded NULs.

Parameters:
pos position in this string where characters should be inserted
buf array containing characters to insert
len number of characters from buf to insert
Returns:
*this

String & insert (  size_t  pos1,
const String &  str,
size_t  pos2,
size_t  len
) 
 

Inserts at most len characters from str at position pos2 into this string at position pos1. pos2 must be less than or equal to str.size(). The function will not insert more characters than what are available in str.

Parameters:
pos1 position in this string where characters should be inserted
str string containing characters to insert
pos2 position in str of first character to insert
len number of characters from str to insert
Returns:
*this

String & insert (  size_t  pos,
const String &  str
) 
 

Inserts characters from str into this string at position pos.

Parameters:
pos position in this string where characters should be inserted
str string containing characters to insert
Returns:
*this

size_t length (   )  const
 

Returns the number of characters in this string's contents. This member function is identical to size().

Returns:
length of the string

size_t max_size (   )  const
 

Returns the maximum length that this string can ever attain.

Returns:
maximum length of string