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