Polaris: String.h Source File

String.h Go to the documentation of this file. /// #ifndef _POLARIS_STRING_H #define _POLARIS_STRING_H /// /// \class String /// \brief a string class /// \defgroup C /// \ingroup C++ CVDL /// Polaris /// \see base/String.h /// \see String.h /// \see String.cc /// /// \endcode /// \section Description Description /// The String class implements variable-length strings. Most of the /// standard and expected methods are defined, including operator== and /// operator!=, operator=, operator+, and operator+=. /// /// This implementation allows strings to be undefined or defined. The /// string is undefined if it is created by a parameterless constructor, /// and it remains undefined until an assignment. This condition may be /// checked through the method defined(). E.g., the following code /// /// String str; /// if ( ! str.defined()) { cout << "Undefined at beginning.\n"; } /// str = ""; /// if ( ! str.defined()) { cout << "Undefined at end.\n"; } /// /// will print ONLY the message "Undefined at beginning." /// (NOTE from the above that there is a difference between a String /// being equal to the empty string [""] and a String being undefined.) /// /// To make a String undefined, you can assign it the NULL character /// string: /// /// String str = "Defined"; /// ... /// str = 0; // make str undefined again /// /// \endcode /// \section Listable Listable Strings /// Note: This version of String is not listable. If you need a /// listable string, look at the class "StringElem." /// /// \endcode /// \section Other Other Utilities /// A few other String-related or char*-related utilities may be /// found in the file utilities/string_util.h. The utility functions /// to be found there may require more components of the base than /// just String (e.g. split() requires StringElem). Those found here /// are fairly self-dependent. /// /// \endcode /// \section Comparing Comparing strings /// Either the left or right side of an '==' operator must be a String /// for the '==' operator to do string-based (and not pointer-based) /// comparisons. For example, the following examples: /// /// String s1, s2; /// char *buf1, *buf2 /// ... /// if (s1 == s2) ... /// if (s1 == s2) ... /// if (s1 == s2) ... /// if ((String)s1 == s2) ... /// if (s1 == (String)) ... /// /// are all ways of doing string-based comparisons, but NOT: /// /// char *buf1, *buf2; /// if (buf1 == buf2) ... NO! Pointer-based comparison. /// /// This previous example will give a pointer-based comparison /// of the addresses pointed to by buf1 and buf2, and not a /// string-based comparison of the strings pointed to by buf1 /// and buf2. /// /// Since every construction of a String requires the copying of /// a character string, it is recommended that if a single character /// string is to be compared against several other strings that it /// should first be assigned to a single String before all the /// comparisons rather than having an explicit (String) typecast /// at every comparison. /// /// \endcode /// \section Examples Examples /// The following are examples of String usage (where what follows each /// "=>" is the output to standard output: /// /// String s; /// cout << "Undefined string: '" << s << "'\n"; /// /// => /// /// Undefined string: '(Undefined String)' /// /// /// /// String sblank(""); /// cout << "Zero-length string: '" << sblank << "'\n"; /// /// => /// /// Zero-length string: '' /// /// /// /// cout << ( (String)"First is" + " a String" ) << "\n"; /// cout << ( "Second is " + (String)"a String" ) << "\n"; /// cout << ( (String)"Both are " + (String)"Strings" ) << "\n"; /// /// => /// /// First is a String /// Second is a String /// Both are Strings /// /// /// /// String s; /// s += "Hello"; /// cout << s << "\n"; /// /// => /// /// Hello /// /// /// /// String s = "Hello"; /// s += " There"; /// cout << s << "\n"; /// /// => /// /// Hello There /// /// /// /// String s = "Hi."; /// s = "Hello again."; /// cout << s << "\n"; /// /// => /// /// Hello again. /// /// /// /// String s("1234567890", 5); /// cout << s << "\n"; /// /// => /// /// 12345 /// /// /// /// /// \endcode /// \section Bugs Bugs /// There is one pitfall in using strings, which has to do with /// functions which returns Strings. For instance, the following /// code will cause a program to bomb on many systems: /// /// String string(); /// void func(const char *s); /// void main() { /// func(string()); /// } /// /// The reason for the bomb is that the compiler creates a tempoary /// String class object for the return value of string(), and this /// string objects contains a local character buffer. Before /// calling func(), the compiler causes an automatic coercion from /// that temporary String into a const char *, and the String's /// pointer value is passed in to the function. Then the temporary /// String, which is no longer needed (or at least as far as the /// compiler can see) is deleted, which causes the string buffer to /// be deleted. Finally, the function is called, but by then the /// const char * which was passed in to it points to a deleted /// memory buffer. /// #ifdef POLARIS_GNU_PRAGMAS #pragma interface #endif /// #include "ClassNames.h" #include <stream.h> #include <string.h> /// #include "Boolean.h" /// /// \note A few other String-related or char*-related utilities may be /// found in the file utilities/string_util.h. The utility functions /// to be found there may require more components of the base than /// just String (e.g. split() requires StringElem). Those found here /// are fairly self-dependent. /// char *upcase_ch(const char *string); /// /// Returns a copy of a string with all characters converted to upper case /// int fortran_string_length(const char *string); /// /// Returns the length a char *string would be given in a Fortran program /// (this strips the enclosing quotes and any doubled internal quotes) /// class String { friend String operator + (const char *str, const String & string); friend Boolean operator == (const char *str, const String & string); friend Boolean operator != (const char *str, const String & string); friend Boolean operator<(const char *str, const String & string); friend inline ostream & operator << (ostream & o, const String & string); ///< Without this, String may be destroyed before printing if ///< created on fly private: int _len; char *_ptr; unsigned _defined:1; void fillin_string(const int size, const char *chars); ///< Fill in the fields of a String structure public: inline String(); ///< Construct an undefined String String(const char *str); ///< Construct a string with a copy of a character string. If str == 0, ///< the String will be undefined. String(const char *str, int max_len); ///< Construct a string with a copy of the first max_len characters ///< of a character string (up to the length of 'str') String(const String & other); ///< Construct a string with a copy of another String's current ///< value. String(const String & other, int first, int last); ///< Substring constructor String(const String & other, char *delim1, char *delim2); ///< Substring constructor using sets of delimiters virtual ~String(); ///< Virtual destructor unsigned hash_value() const; ///< Returns a hash value based on the contents of the String. String & operator = (const char *str); ///< Assignment from a character string String & operator = (const String * other); ///< Assignment from a String * String & operator = (const String & other); ///< Assignment from a String String operator + (const char *str) const; ///< Concatention with a character string String operator + (const String & other) const; ///< Concatention with a String String & operator += (const char *str); ///< Append a character string String & operator += (const String & other); ///< Append a String inline const char &operator[] (int index) const; inline char &operator[] (int index) ; ///< Return a modifiable character reference to the (index-1)th ///< character in the string. THERE IS NO CHECK FOR LEGALITY ///< OF THE INDEX inline int operator == (const char *str) const; ///< Case-sensitive test of equality inline int operator != (const char *str) const; ///< Case-sensitive test of inequality inline int operator<(const char *str) const; ///< Case-sensitive string comparison inline int operator == (const String & s) const; ///< Case-sensitive test of equality inline int operator != (const String & s) const; ///< Case-sensitive test of inequality inline int operator<(const String & s) const; ///< Case-sensitive string comparison inline operator const char *() const; inline int len() const; inline int defined() const; int index(const char *substring) const; ///< Return the index into a string where the given substring begins. ///< Returns -1 if 'substring' is not found, or if *this is undefined. int index_case(const char *substring) const; ///< Return the index into a string where the given substring begins, ///< ignoring the case of both strings. ///< Returns -1 if 'substring' is not found, or if *this is undefined. String upcase() const; ///< Returns a new String whose alphabetic chars have been converted ///< to upper case. If this object is undefined, the String returned ///< will also be undefined. int structures_OK() const; ///< Check the structure of the data for errors or inconsistency ///< Return 0 and print error message if problems found, otherwise ///< return 1 without message. void absorb(char *allocated_str); ///< Set the string to the value of allocated_str, without ///< allocating new memory. ///< Note: allocated_str must have been allocated using ///< the new operator (not malloc). ///< If allocated_str == 0, this String becomes undefined. ///< THIS MEMORY WILL BE DELETED UPON DESTROYING THE STRING!! }; /* String dec(int i); */ /* String hex(int i); */ ///< inline functions inline ostream & operator << (ostream & o, const String & string) { return o << (string.defined() ? (const char *) string : "(Undefined Str)"); } inline String::String() { #ifdef CLASS_INSTANCE_REGISTRY register_instance(STRING_CLASS, sizeof(String), this); #endif _len = 0; _ptr = ""; _defined = 0; } inline const char & String::operator[] (int index) const { return _ptr[index]; } inline char & String::operator[] (int index) { return _ptr[index]; } inline int String::operator == (const char *str) const { return _defined && 0 == strcmp(_ptr, str); } inline int String::operator != (const char *str) const { return !(*this == str); } inline int String::operator < (const char *str) const { return strcmp(_ptr, str) < 0; } inline int String::operator == (const String & s) const { return defined() && s.defined() && (0 == strcmp(_ptr, s._ptr)); } inline int String::operator != (const String & s) const { return !(*this == s); } inline int String::operator < (const String & s) const { return defined() && s.defined() && (strcmp(_ptr, s._ptr) < 0); } inline String::operator const char *() const { return _defined ? _ptr : "**-*-Undefined String**-*-"; } inline int String::len() const { return _len; } inline int String::defined() const { return _defined; } #endif

© 1995-2005 University of Illinois, Urbana-Champaign. All rights reserved.  Fri Mar 25 23:06:13 2005