home *** CD-ROM | disk | FTP | other *** search
.TH STRING .SH NAME String Simple, dynamic string class .SH SYNOPSIS #include <cool/String.h> .SH DESCRIPTION The String\f1 class provides dynamic, efficient strings for a C++ application. The intent is to provide efficient \f3char*\f1-like functionality that frees the programmer from worrying about memory allocation and deallocation problems, yet retains the speed and compactness of a standard \f3char*\f1 implementation. The \f3String\f1 class is dynamic in the sense that if an operation such as concatenate results in more characters than can fit in the currently allocated memory, the string object \f2grows\f1 according to some established size or ratio value. All typical string operations are provided, including concatenation, case-sensitive and case-insensitive lexical comparison, string search, yank, delete, and replacement. System-provided functions for \f3char*\f1 such as \f3strcpy\f1 and \f3strcmp\f1 are also available via the overloaded \f3operator char* \f1 member function. .SH Base Classes .SH Friend Classes None .SH Constructors .TP String (); Initializes an empty string object with a default size block of memory allocated to hold 100 characters. .TP \f3String (char \f2c\f3);\f1 Initializes a string object with the default size block of memory allocated to hold 100 characters whose value is the string consisting of the single character argument \f2c\f1. .TP \f3String (const char* \f2str\f3);\f1 Initializes a string object with the default size block of memory allocated to hold 100 characters whose value is copied from the specified character string argument str . If \f2str\f1 is longer, the string will grow as necessary. .TP \f3String (const char* \f2str\f3, long \f2size\f3);\f1 Allocates an initial block of memory the size of the integer argument \f2size\f1, or the s\f3trlen(\f2str\f3)\f1, whichever is longer. and initializes the string object with a copy of the specified character string \f2str\f1. Note that \f2size\f1 is ignored if less than the length of \f2str\f1. .TP \f3String (const String& \f2str\f3);\f1 Duplicates the size and value of another string object \f2str\f1. .TP \f3String (const String& \f2str\f3, long \f2size)\f3;\f1 Duplicates the size and value of another string object \f2str\f1 by allocating an initial block of memory to be the size of the integer argument \f2size\f1, or \f3strlen(\f2str\f3)\f1, whichever is longer. The duplication is then performed. .SH Member Functions .TP inline long capacity () const; Returns the maximum number of characters that the string object can contain without having to grow. .TP void clear (); Resets the NULL character string terminator to the beginning of the string and sets the length of the string to zero. .TP \f3Boolean insert (const char* \f2str\f3, long \f2position\f3);\f1 Inserts a copy of the sequence of characters pointed to by the first argument \f2str\f1 at the zero-relative index provided by the second argument \f2position\f1. This function returns TRUE if successful; otherwise, this function returns FALSE if the index is out of range. .TP inline operator char* () const; Provides an implicit conversion operator to convert a string object into a \f3char*\f1 value. .TP \f3String operator+ (char \f2c\f3);\f1 Overloads the addition operator to concatenate a single character \f2c\f1 to a string object. This function returns a new string object, via the stack. .TP \f3String operator+ (const char* \f2str\f3);\f1 Overloads the addition operator to concatenate a copy of the specified character sequence \f2str\f1 to a string object. This function returns a new string object. .TP \f3String operator+ (const String& \f2str\f3);\f1 Overloads the addition operator to concatenate the value of the specified string object \f2str\f1 to a string object. This function returns a new string object. .TP \f3inline String& operator= (char \f2c\f3);\f1 Overloads the assignment operator to assign a single character \f2c\f1 to a string object. This function returns a reference to the modified string object. .TP \f3inline String& operator= (const char* \f2str\f3);\f1 Overloads the assignment operator to assign a copy of the specified character sequence \f2str\f1 to a string object. This function returns a reference to themodified string object. .TP \f3inline String& operator= (const String& \f2str\f3);\f1 Overloads the assignment operator to assign the value of another string object \f2str\f1 to a string object. This function returns a reference to the modified string object. .TP \f3inline String& operator+= (char \f2c\f3);\f1 Overloads the addition-and-assignment operator to concatenate a single character c to a string object. This function returns a reference to the modified string object. .TP \f3inline String& operator+= (const char* \f2str\f3);\f1 Overloads the addition-and-assignment operator to concatenate a copy of the specified character sequence \f2str\f1 to a string object. This function returns a reference to the modified string object. .TP \f3inline String& operator+= (const String& \f2str\f3);\f1 Overloads the addition-and-assignment operator to concatenate the value of the specified string object \f2str\f1 to a string object. This function returns a reference to the modified string object. .TP \f3inline Boolean operator== (const char* \f2str\f3) const;\f1 Overloads the equality operator for the String class. This function returns TRUE if the string object and str have the same sequence of characters; otherwise, this function returns FALSE . .TP \f3inline Boolean operator== (const String& \f2str\f3) const;\f1 Overloads the equality operator for the \f3String\f1 class. This function returns TRUE if the strings have the same sequence of characters; otherwise, this function returns FALSE . .TP \f3inline Boolean operator!= (const char* \f2str\f3) const;\f1 Overloads the inequality operator for the \f3String\f1 class. This function returns FALSE if the string object and \f2str\f1 have the same sequence of characters; otherwise, this function returns TRUE . .TP \f3inline Boolean operator!= (const String& \f2str\f3) const;\f1 Overloads the inequality operator for the \f3String\f1 class. This function returns FALSE if the strings have the same sequence of characters; otherwise, this function returns TRUE . .TP \f3inline Boolean operator< (const char* \f2str\f3) const;\f1 Overloads the less-than operator for the \f3String\f1 class. This function returns TRUE if the string is lexically less than the \f2char* s\f1 argument; otherwise, this function returns FALSE . .TP \f3inline Boolean operator< (const String& \f2str\f3) const;\f1 Overloads the less-than operator for the \f3String\f1 class. This function returns TRUE if the string object is lexically less than the string \f2str\f1\^; otherwise, this function returns FALSE . .TP \f3inline Boolean operator<= (const char* \f2str\f3) const;\f1 Overloads the less-than-or-equal operator for the \f3String\f1 class. This function returns TRUE if the string object is lexically less than or equal to the character string argument \f2str\f1\^; otherwise, this function returns FALSE . .TP \f3inline Boolean operator<= (const String& \f2str\f3) const;\f1 Overloads the less-than-or-equal operator for the \f3String\f1 class. This function returns TRUE if the string object is lexically less than or equal to the string \f2str\f1\^; otherwise, this function returns FALSE . .TP \f3inline Boolean operator> (const char* \f2str\f3) const;\f1 Overloads the greater-than operator for the \f3String\f1 class. This function returns TRUE if the string object is lexically greater than the character string argument \f2str\f1\^; otherwise, this function returns FALSE . .TP \f3inline Boolean operator> (const String& \f2str\f3) const;\f1 Overloads the greater-than operator for the String class. This function returns TRUE if the string object is lexically greater than the string str ; otherwise, this function returns FALSE . .TP \f3inline Boolean operator>= (const char* \f2str\f3) const;\f1 Overloads the greater-than-or-equal operator for the String class. This function returns TRUE if the string object is lexically greater than or equal to the character string argument str ; otherwise, this function returns FALSE . .TP \f3inline Boolean operator>= (const String& \f2str\f3) const;\f1 Overloads the greater-than-or-equal operator for the String class. This function returns TRUE if the string object is lexically greater than or equal to the string str ; otherwise, this function returns FALSE . .TP \f3inline char operator[] (long \f2position\f3) const;\f1 Returns the character at the zero-relative index position in the string. If the index is invalid, an \f3\f3Error\f1\f1 exception is raised. .TP \f3Boolean remove (long \f2start\f3, long \f2end\f3);\f1 Removes the sequence of characters between the zero-relative inclusive start and exclusive end indexes. This function returns TRUE if successful; otherwise, this function returns FALSE if either one or both of the indexes is out of range. .TP \f3Boolean replace (const char* \f2str\f3, long \f2start\f3, long \f2end\f3);\f1 Replaces the sequence of characters between the zero-relative inclusive start and exclusive end indexes with a copy of the character string str . This function returns TRUE if successful; otherwise, this function returns FALSE if either one or both of the indexes is out of range. .TP \f3void resize (long \f2size\f3);\f1 Resizes the string object to hold at least size number of characters. If size is less than existing length, the operation is ignored. .TP void reverse (); Reverses the ordering of the characters in a string object. .TP \f3inline void set_alloc_size (int \f2size\f3);\f1 Updates the allocation growth size to be used when the growth ratio is zero. Default allocation growth size is 100 bytes. If size is negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3inline void set_growth_ratio (float \f2ratio\f3);\f1 Updates the growth ratio for this instance of a string to the specified value. When a string needs to grow, the current size is multiplied by the ratio to determine the new size. If ratio is negative, an \f3\f3Error\f1\f1 exception is raised. .TP \f3void sub_string (String& \f2str\f3, long \f2start\f3, long \f2end\f3);\f1 Sets the given string object str to the values in the character sequence between the zero-relative inclusive start and exclusive end indexes provided. This function returns TRUE if successful; otherwise, this function returns FALSE if either one or both of the indexes is out of range. .TP \f3void yank (String& \f2str\f3, long \f2start\f3, long \f2end\f3);\f1 Deletes the sequence of characters between the zero-relative inclusive start and exclusive end indexes provided and sets the given string object str to the value of the deleted characters. .SH Friend Functions .TP \f3inline friend double atof (const String& \f2str\f3);\f1 Returns the floating-point value represented by the characters in the string object str . .TP \f3friend int atoi (const String& \f2str\f3);\f1 Returns the decimal radix integer number represented by the characters in the string object str . .TP \f3friend long atol (const String& \f2str\f3);\f1 Returns the decimal radix long number represented by the characters in the string object str . .TP \f3friend String& capitalize (String& \f2str\f3);\f1 Capitalizes each word and returns the modified string str . A word is defined to be any subsequence of alphanumeric characters. This function returns a reference to the modified string str . .TP \f3friend String& downcase (String& \f2str\f3);\f1 Converts any alphabetic character to lowercase. This function returns a reference to the modified string str . .TP \f3friend String& left_trim (String& \f2str1\f3, const char* \f2str2\f3);\f1 Removes any prefix occurrence of the character string str2 specified from the string object str1 . This function returns a reference to the modified string str1 . .TP \f3friend ostream& operator<< (ostream& \f2os\f3, const String& \f2str\f3);\f1 Overloads the output operator for a reference to a string object str . .TP \f3inline friend ostream& operator<< (ostream& \f2os\f3, const String* \f2str\f3);\f1 Overloads the output operator for a pointer to a string object str . .TP \f3friend String& right_trim (String& \f2str1\f3, const char* \f2str2\f3);\f1 Removes any suffix occurrence of the character string str2 specified from the string object str1 . This function returns a reference to the modified string str2 . .TP \f3friend String& strcat (String& \f2str\f3, char \f2c\f3);\f1 Returns the result of concatenating the character c to a string object str . .TP \f3friend String& strcat (String& \f2str1\f3, const char* \f2str2\f3);\f1 Returns the result of concatenating a copy of the specified character string str2 to a string object str1 . .TP \f3friend String& strcat (String& \f2str1\f3, const String& \f2str2\f3);\f1 Returns the result of concatenating one string object str2 to another str1 . This function returns the modified string object str1. .TP \f3friend char* strchr (const String& \f2str\f3, char \f2c\f3);\f1 Overloads the forward character search function to scan from left to right through a string object str for the first occurrence of the character c . This function returns a pointer to the character if found; otherwise, this function returns NULL . .TP \f3friend String& strcpy (String& \f2str1\f3, char \f2str2\f3);\f1 Overloads the copy string function to copy the character string str2 into a string argument str1 . This function returns a reference to the modified string object str1 . .TP \f3friend String& strcpy (String& \f2str1\f3, const char* \f2str2\f3);\f1 Overloads the copy string function to copy the specified character string str2 argument into the string argument str1 . This function returns a reference to the modified string object str1 . .TP \f3friend String& strcpy (String& \f2str1\f3, const String& \f2str2\f3);\f1 Overloads the copy string function to copy the second string argument str2 into the first string argument str1 . This function returns the modified string object str1 . .TP \f3inline friend long strlen (const String& \f2str\f3);\f1 Returns the number of characters (length) of the string str . .TP \f3friend String& strncat (String& \f2str1\f3, const char* \f2str2\f3, int \f2length\f3);\f1 Returns the result of concatenating a copy of some number of characters length from a character string str2 to a string object str1 . This function returns a reference to the modified string object str1 . .TP \f3friend String& strncat (String& \f2str1\f3, const String& \f2str2\f3, int \f2length\f3);\f1 Returns the result of concatenating some number of characters length from one string object str2 to another str1 . This function returns a reference to the modified string object str1 . .TP \f3friend String& strncpy (String& \f2str1\f3, const char* \f2str2\f3, long \f2length\f3);\f1 Overloads the strncpy function to copy some number of characters length from the specified character string argument str2 into the string argument str1 . This function returns a reference to the modified string object str1 . .TP \f3friend char* strrchr (const String& \f2str\f3, char \f2c\f3);\f1 Overloads the backward character search function to scan from right to left through a string object str for the last occurrence of a specific character c . This function returns a pointer to the character if found; otherwise, this function returns NULL . .TP \f3friend double strtod (const String& \f2str\f3, char** \f2ptr \f3= \f3 NULL); Returns the double floating-point value represented by the characters in the string object str . If the second argument is non-zero, it is set to the character terminating the converted string value. .TP \f3friend long strtol (const String& \f2str\f3, char** \f2ptr\f3 = \f3NULL\f3, int \f2radix\f1=10\f3);\f1 Returns the long number represented by the characters in the string object str . If a specific radix is not specified, the default radix is decimal. If the second argument is non-zero, it is set to the character terminating the converted string value. .TP \f3friend String& trim (String& \f2str1\f3, const char* \f2str2\f3);\f1 Removes any occurrence of the character string str2 from the string object str1 . This function returns a reference to the modified string str1 . .TP \f3friend String& upcase (\f2S\f3tring& \f2str\f3);\f1 Converts any alphabetic character to uppercase. This function returns a reference to the modified string str . .SH COPYRIGHT Copyright (C) 1991 Texas Instruments Incorporated. Permission is granted to any individual or institution to use, copy, modify, and distribute this software, provided that this complete copyright and permission notice is maintained, intact, in all copies and supporting documentation. Texas Instruments Incorporated provides this software "as is" without express or implied warranty. 
