00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file SString.h 00006 * 00007 * SString.h,v 4.86 2006/01/25 19:56:26 jwillemsen Exp 00008 * 00009 * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) 00010 */ 00011 //============================================================================= 00012 00013 #ifndef ACE_SSTRING_H 00014 #define ACE_SSTRING_H 00015 #include /**/ "ace/pre.h" 00016 00017 #include "ace/SStringfwd.h" 00018 00019 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00020 # pragma once 00021 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00022 00023 #include "ace/String_Base.h" 00024 00025 #if !defined (ACE_DEFAULT_GROWSIZE) 00026 #define ACE_DEFAULT_GROWSIZE 32 00027 #endif /* ACE_DEFAULT_GROWSIZE */ 00028 00029 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY) 00030 #include "ace/iosfwd.h" 00031 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00032 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_CString &); 00033 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_WString &); 00034 ACE_END_VERSIONED_NAMESPACE_DECL 00035 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */ 00036 00037 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00038 00039 #if defined ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT 00040 template class ACE_Export ACE_String_Base<char>; 00041 template class ACE_Export ACE_String_Base<ACE_WSTRING_TYPE>; 00042 #endif /* ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT */ 00043 00044 /** 00045 * @class ACE_NS_WString 00046 * 00047 * @brief This class retain the backward compatibility for 00048 * ACE_Naming_Context and related classes. The only addition to 00049 * ACE_WString is a very naive "wchar" to "char" conversion 00050 * function. 00051 */ 00052 class ACE_Export ACE_NS_WString : public ACE_WString 00053 { 00054 public: 00055 /// Default constructor. 00056 ACE_NS_WString (ACE_Allocator *alloc = 0); 00057 00058 /// Constructor that copies @a s into dynamically allocated memory. 00059 ACE_NS_WString (const char *s, 00060 ACE_Allocator *alloc = 0); 00061 00062 /// Constructor that copies @a s into dynamically allocated memory. 00063 ACE_NS_WString (const ACE_WSTRING_TYPE *s, 00064 ACE_Allocator *alloc = 0); 00065 00066 #if defined (ACE_WSTRING_HAS_USHORT_SUPPORT) 00067 /// Constructor that takes in a ushort16 string (mainly used by the 00068 /// ACE Name_Space classes) 00069 ACE_NS_WString (const ACE_USHORT16 *s, 00070 size_t len, 00071 ACE_Allocator *alloc = 0); 00072 #endif /* ACE_WSTRING_HAS_USHORT_SUPPORT */ 00073 00074 /// Constructor that copies @a len ACE_WSTRING_TYPE's of @a s into dynamically 00075 /// allocated memory (will NUL terminate the result). 00076 ACE_NS_WString (const ACE_WSTRING_TYPE *s, 00077 size_t len, 00078 ACE_Allocator *alloc = 0); 00079 00080 /// Constructor that dynamically allocates memory for @a len + 1 00081 /// ACE_WSTRING_TYPE characters. The newly created memory is set memset to 0. 00082 ACE_NS_WString (size_t len, ACE_Allocator *alloc = 0); 00083 00084 /// Copy constructor. 00085 ACE_NS_WString (const ACE_NS_WString &s); 00086 00087 /// Constructor that copies @a c into dynamically allocated memory. 00088 ACE_NS_WString (ACE_WSTRING_TYPE c, ACE_Allocator *alloc = 0); 00089 00090 /// Transform into a copy of the ASCII character representation. 00091 /// (caller must delete) 00092 char *char_rep (void) const; 00093 00094 /// Transform into a copy of a USHORT16 representation (caller must 00095 /// delete). Note, behavior is undefined when sizeof (wchar_t) != 2. 00096 ACE_USHORT16 *ushort_rep (void) const; 00097 }; 00098 00099 ACE_INLINE ACE_Export 00100 ACE_NS_WString operator + (const ACE_NS_WString &, 00101 const ACE_NS_WString &); 00102 00103 // ----------------------------------------------------------------- 00104 00105 /** 00106 * @class ACE_SString 00107 * 00108 * @brief A very Simple String ACE_SString class. This is not a 00109 * general-purpose string class, and you should probably consider 00110 * using ACE_CString is you don't understand why this class 00111 * exists... 00112 * 00113 * This class is optimized for efficiency, so it doesn't provide 00114 * any internal locking. 00115 * CAUTION: This class is only intended for use with applications 00116 * that understand how it works. In particular, its destructor 00117 * does not deallocate its memory when it is destroyed... We need 00118 * this class since the ACE_Map_Manager requires an object that 00119 * supports the operator == and operator !=. This class uses an 00120 * ACE_Allocator to allocate memory. The user can make this a 00121 * persistant class by providing an ACE_Allocator with a 00122 * persistable memory pool. 00123 */ 00124 class ACE_Export ACE_SString 00125 { 00126 public: 00127 /// No position constant 00128 static const int npos; 00129 00130 /// Default constructor. 00131 ACE_SString (ACE_Allocator *alloc = 0); 00132 00133 /// Constructor that copies @a s into dynamically allocated memory. 00134 ACE_SString (const char *s, ACE_Allocator *alloc = 0); 00135 00136 /// Constructor that copies @a len chars of @s into dynamically 00137 /// allocated memory (will NUL terminate the result). 00138 ACE_SString (const char *s, size_t len, ACE_Allocator *alloc = 0); 00139 00140 /// Copy constructor. 00141 ACE_SString (const ACE_SString &); 00142 00143 /// Constructor that copies @a c into dynamically allocated memory. 00144 ACE_SString (char c, ACE_Allocator *alloc = 0); 00145 00146 /// Default destructor. 00147 ~ACE_SString (void); 00148 00149 /// Return the <slot'th> character in the string (doesn't perform 00150 /// bounds checking). 00151 char operator [] (size_t slot) const; 00152 00153 /// Return the <slot'th> character by reference in the string 00154 /// (doesn't perform bounds checking). 00155 char &operator [] (size_t slot); 00156 00157 /// Assignment operator (does copy memory). 00158 ACE_SString &operator = (const ACE_SString &); 00159 00160 /** 00161 * Return a substring given an offset and length, if length == -1 00162 * use rest of str return empty substring if offset or offset/length 00163 * are invalid 00164 */ 00165 ACE_SString substring (size_t offset, ssize_t length = -1) const; 00166 00167 /// Same as substring 00168 ACE_SString substr (size_t offset, ssize_t length = -1) const; 00169 00170 /// Returns a hash value for this string. 00171 u_long hash (void) const; 00172 00173 /// Return the length of the string. 00174 size_t length (void) const; 00175 00176 /// Set the underlying pointer. Since this does not copy memory or 00177 /// delete existing memory use with extreme caution!!! 00178 void rep (char *s); 00179 00180 /// Get the underlying pointer. 00181 const char *rep (void) const; 00182 00183 /// Get the underlying pointer. 00184 const char *fast_rep (void) const; 00185 00186 /// Same as STL String's <c_str> and <fast_rep>. 00187 const char *c_str (void) const; 00188 00189 /// Comparison operator that will match substrings. Returns the 00190 /// slot of the first location that matches, else -1. 00191 int strstr (const ACE_SString &s) const; 00192 00193 /// Find <str> starting at pos. Returns the slot of the first 00194 /// location that matches (will be >= pos), else npos. 00195 int find (const ACE_SString &str, int pos = 0) const; 00196 00197 /// Find <s> starting at pos. Returns the slot of the first 00198 /// location that matches (will be >= pos), else npos. 00199 int find (const char *s, int pos = 0) const; 00200 00201 /// Find <c> starting at pos. Returns the slot of the first 00202 /// location that matches (will be >= pos), else npos. 00203 int find (char c, int pos = 0) const; 00204 00205 /// Find <c> starting at pos (counting from the end). Returns the 00206 /// slot of the first location that matches, else npos. 00207 int rfind (char c, int pos = npos) const; 00208 00209 /// Equality comparison operator (must match entire string). 00210 bool operator == (const ACE_SString &s) const; 00211 00212 /// Less than comparison operator. 00213 bool operator < (const ACE_SString &s) const; 00214 00215 /// Greater than comparison operator. 00216 bool operator > (const ACE_SString &s) const; 00217 00218 /// Inequality comparison operator. 00219 bool operator != (const ACE_SString &s) const; 00220 00221 /// Performs a <strcmp>-style comparison. 00222 int compare (const ACE_SString &s) const; 00223 00224 /// Dump the state of an object. 00225 void dump (void) const; 00226 00227 /// Declare the dynamic allocation hooks. 00228 ACE_ALLOC_HOOK_DECLARE; 00229 00230 private: 00231 /// Pointer to a memory allocator. 00232 ACE_Allocator *allocator_; 00233 00234 /// Length of the ACE_SString (not counting the trailing '\0'). 00235 size_t len_; 00236 00237 /// Pointer to data. 00238 char *rep_; 00239 }; 00240 00241 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY) 00242 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_SString &); 00243 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */ 00244 00245 // This allows one to use W or C String based on the Unicode 00246 // setting 00247 #if defined (ACE_USES_WCHAR) 00248 typedef ACE_WString ACE_TString; 00249 #else /* ACE_USES_WCHAR */ 00250 typedef ACE_CString ACE_TString; 00251 #endif /* ACE_USES_WCHAR */ 00252 00253 00254 // ************************************************************ 00255 00256 /** 00257 * @class ACE_Tokenizer 00258 * 00259 * @brief Tokenizer 00260 * 00261 * Tokenizes a buffer. Allows application to set delimiters and 00262 * preserve designators. Does not allow special characters, yet 00263 * (e.g., printf ("\"like a quoted string\"")). 00264 */ 00265 class ACE_Export ACE_Tokenizer 00266 { 00267 public: 00268 /** 00269 * \a buffer will be parsed. Notice that ACE_Tokenizer will modify 00270 * \a buffer if you use <code> delimiter_replace </code> or <code> 00271 * preserve_designators </code> to do character substitution. 00272 * @note You should NOT pass a constant string or string literal 00273 * to this constructor, since ACE_Tokenizer will try to modify 00274 * the string. 00275 * \sa preserve_designators 00276 * \sa preserve_designators 00277 */ 00278 ACE_Tokenizer (ACE_TCHAR *buffer); 00279 00280 /** 00281 * \a d is a delimiter. 00282 * \return Returns 0 on success, -1 if there is no memory left. 00283 * 00284 * <B>Example:</B> 00285 * \verbatim 00286 char buf[30]; 00287 ACE_OS::strcpy(buf, "William/Joseph/Hagins"); 00288 00289 ACE_Tokenizer tok (buf); 00290 tok.delimiter ('/'); 00291 for (char *p = tok.next (); p; p = tok.next ()) 00292 cout << p << endl; 00293 \endverbatim 00294 * 00295 * This will print out: 00296 * \verbatim 00297 William/Joseph/Hagins 00298 Joseph/Hagins 00299 Hagins \endverbatim 00300 */ 00301 int delimiter (ACE_TCHAR d); 00302 00303 /** 00304 * \a d is a delimiter and, when found, will be replaced by 00305 * \a replacement. 00306 * \return 0 on success, -1 if there is no memory left. 00307 * 00308 * <B>Example:</B> 00309 * \verbatim 00310 char buf[30]; 00311 ACE_OS::strcpy(buf, "William/Joseph/Hagins"); 00312 00313 ACE_Tokenizer tok (buf); 00314 tok.delimiter_replace ('/', 0); 00315 for (char *p = tok.next (); p; p = tok.next ()) 00316 cout << p << endl; 00317 \endverbatim 00318 * 00319 * This will print out: 00320 * \verbatim 00321 William 00322 Joseph 00323 Hagins \endverbatim 00324 */ 00325 int delimiter_replace (ACE_TCHAR d, ACE_TCHAR replacement); 00326 00327 /** 00328 * Extract string between a pair of designator characters. 00329 * For instance, quotes, or '(' and ')'. 00330 * \a start specifies the begin designator. 00331 * \a stop specifies the end designator. 00332 * \a strip If \a strip == 1, then the preserve 00333 * designators will be stripped from the tokens returned by next. 00334 * \return 0 on success, -1 if there is no memory left. 00335 * 00336 * <B>Example with strip = 0:</B> 00337 * \verbatim 00338 char buf[30]; 00339 ACE_OS::strcpy(buf, "William(Joseph)Hagins"); 00340 00341 ACE_Tokenizer tok (buf); 00342 tok.preserve_designators ('(', ')', 0); 00343 for (char *p = tok.next (); p; p = tok.next ()) 00344 cout << p << endl; 00345 \endverbatim 00346 * 00347 * This will print out: 00348 * \verbatim 00349 William(Joseph)Hagins 00350 (Joseph)Hagins 00351 )Hagins \endverbatim 00352 * 00353 * <B>Example with strip = 1:</B> 00354 * \verbatim 00355 char buf[30]; 00356 ACE_OS::strcpy(buf, "William(Joseph)Hagins"); 00357 00358 ACE_Tokenizer tok (buf); 00359 tok.preserve_designators ('(', ')', 1); 00360 for (char *p = tok.next (); p; p = tok.next ()) 00361 cout << p << endl; 00362 \endverbatim 00363 * 00364 * This will print out: 00365 * \verbatim 00366 William 00367 Joseph 00368 Hagins \endverbatim 00369 */ 00370 int preserve_designators (ACE_TCHAR start, ACE_TCHAR stop, int strip=1); 00371 00372 /// Returns the next token. 00373 ACE_TCHAR *next (void); 00374 00375 enum { 00376 MAX_DELIMITERS=16, 00377 MAX_PRESERVES=16 00378 }; 00379 00380 protected: 00381 /// Returns 1 if <d> is a delimiter, 0 otherwise. If <d> should be 00382 /// replaced with <r>, <replace> is set to 1, otherwise 0. 00383 int is_delimiter (ACE_TCHAR d, int &replace, ACE_TCHAR &r); 00384 00385 /** 00386 * If <start> is a start preserve designator, returns 1 and sets 00387 * <stop> to the stop designator. Returns 0 if <start> is not a 00388 * preserve designator. 00389 */ 00390 int is_preserve_designator (ACE_TCHAR start, ACE_TCHAR &stop, int &strip); 00391 00392 ACE_TCHAR *buffer_; 00393 int index_; 00394 00395 /** 00396 * @class Preserve_Entry 00397 * 00398 * @brief Preserve Entry 00399 * 00400 * Defines a set of characters that designate an area that 00401 * should not be parsed, but should be treated as a complete 00402 * token. For instance, in: (this is a preserve region), start 00403 * would be a left paren -(- and stop would be a right paren 00404 * -)-. The strip determines whether the designators should be 00405 * removed from the token. 00406 */ 00407 class Preserve_Entry 00408 { 00409 public: 00410 /** 00411 * E.g., "(". 00412 * E.g., ")". 00413 * Whether the designators should be removed from the token. 00414 */ 00415 ACE_TCHAR start_; 00416 ACE_TCHAR stop_; 00417 int strip_; 00418 }; 00419 00420 /// The application can specify MAX_PRESERVES preserve designators. 00421 Preserve_Entry preserves_[MAX_PRESERVES]; 00422 00423 /// Pointer to the next free spot in preserves_. 00424 int preserves_index_; 00425 00426 /** 00427 * @class Delimiter_Entry 00428 * 00429 * @brief Delimiter Entry 00430 * 00431 * Describes a delimiter for the tokenizer. 00432 */ 00433 class Delimiter_Entry 00434 { 00435 public: 00436 /** 00437 * Most commonly a space ' '. 00438 * What occurrences of delimiter_ should be replaced with. 00439 * Whether replacement_ should be used. This should be replaced 00440 * with a technique that sets replacement_ = delimiter by 00441 * default. I'll do that next iteration. 00442 */ 00443 ACE_TCHAR delimiter_; 00444 ACE_TCHAR replacement_; 00445 int replace_; 00446 }; 00447 00448 /// The tokenizer allows MAX_DELIMITERS number of delimiters. 00449 Delimiter_Entry delimiters_[MAX_DELIMITERS]; 00450 00451 /// Pointer to the next free space in delimiters_. 00452 int delimiter_index_; 00453 }; 00454 00455 // **************************************************************** 00456 00457 /** 00458 * @class ACE_Auto_String_Free 00459 * 00460 * @brief Simple class to automatically de-allocate strings 00461 * 00462 * Keeps a pointer to a string and deallocates it (using 00463 * <ACE_OS::free>) on its destructor. 00464 * If you need to delete using "delete[]" the 00465 * ACE_Auto_Array_Ptr<char> is your choice. 00466 * The class plays the same role as auto_ptr<> 00467 */ 00468 class ACE_Export ACE_Auto_String_Free 00469 { 00470 public: 00471 explicit ACE_Auto_String_Free (char* p = 0); 00472 ACE_Auto_String_Free (ACE_Auto_String_Free &rhs); 00473 ACE_Auto_String_Free& operator= (ACE_Auto_String_Free &rhs); 00474 ~ACE_Auto_String_Free (void); 00475 00476 char* operator* () const; 00477 char operator[] (int i) const; 00478 char* get (void) const; 00479 char* release (void); 00480 void reset (char* p = 0); 00481 00482 private: 00483 char* p_; 00484 }; 00485 00486 ACE_END_VERSIONED_NAMESPACE_DECL 00487 00488 #if defined (__ACE_INLINE__) 00489 #include "ace/SString.inl" 00490 #endif /* __ACE_INLINE__ */ 00491 00492 #include /**/ "ace/post.h" 00493 #endif /* ACE_SSTRING_H */