00001 // -*- C++ -*- 00002 00003 //============================================================================= 00004 /** 00005 * @file String_Base.h 00006 * 00007 * String_Base.h,v 4.30 2006/06/08 17:27:13 schmidt Exp 00008 * 00009 * @author Douglas C. Schmidt (schmidt@cs.wustl.edu) 00010 * @author Nanbor Wang <nanbor@cs.wustl.edu> 00011 */ 00012 //============================================================================= 00013 00014 #ifndef ACE_STRING_BASE_H 00015 #define ACE_STRING_BASE_H 00016 00017 #include /**/ "ace/pre.h" 00018 00019 #include "ace/String_Base_Const.h" 00020 00021 #if !defined (ACE_LACKS_PRAGMA_ONCE) 00022 # pragma once 00023 #endif /* ACE_LACKS_PRAGMA_ONCE */ 00024 00025 #include "ace/Global_Macros.h" 00026 00027 ACE_BEGIN_VERSIONED_NAMESPACE_DECL 00028 00029 class ACE_Allocator; 00030 00031 /** 00032 * @class ACE_String_Base 00033 * 00034 * @brief This class provides a wrapper facade for C strings. 00035 * 00036 * This class uses an ACE_Allocator to allocate memory. The 00037 * user can make this a persistant class by providing an 00038 * ACE_Allocator with a persistable memory pool. This class is 00039 * optimized for efficiency, so it doesn't provide any internal 00040 * locking. 00041 * @note If an instance of this class is constructed from or 00042 * assigned an empty string (with first element of '\0'), then it 00043 * is not allocated new space. Instead, its internal 00044 * representation is set equal to a global empty string. 00045 * CAUTION: in cases when ACE_String_Base is constructed from a 00046 * provided buffer with the release parameter set to 0, 00047 * ACE_String_Base is not guaranteed to be '\0' terminated. 00048 */ 00049 template <class CHAR> class ACE_String_Base : public ACE_String_Base_Const 00050 { 00051 public: 00052 /** 00053 * Default constructor. 00054 * 00055 * @param the_allocator ACE_Allocator associated with string 00056 * @return Default ACE_String_Base string. 00057 */ 00058 ACE_String_Base (ACE_Allocator *the_allocator = 0); 00059 00060 /** 00061 * Constructor that copies @a s into dynamically allocated memory. 00062 * 00063 * if release == 1 then a new buffer is allocated internally, and 00064 * s is copied to the internal buffer. 00065 * if release == 0 then the s buffer is used directly. If s == 0 00066 * then it will _not_ be used, and instead the internal buffer 00067 * is set to NULL_String_. 00068 * 00069 * @param s Zero terminated input string 00070 * @param the_allocator ACE_Allocator associated with string 00071 * @param release Allocator responsible(1)/not reponsible(0) for 00072 * freeing memory. 00073 * @return ACE_String_Base containing const CHAR *s 00074 */ 00075 ACE_String_Base (const CHAR *s, 00076 ACE_Allocator *the_allocator = 0, 00077 int release = 1); 00078 00079 /** 00080 * Constructor that copies @a len CHARs of @a s into dynamically 00081 * allocated memory (will zero terminate the result). 00082 * 00083 * if release == 1 then a new buffer is allocated internally. 00084 * s is copied to the internal buffer. 00085 * if release == 0 then the s buffer is used directly. If s == 0 00086 * then it will _not_ be used, and instead the internal buffer 00087 * is set to NULL_String_. 00088 * 00089 * @param s Non-zero terminated input string 00090 * @param len Length of non-zero terminated input string 00091 * @param the_allocator ACE_Allocator associated with string 00092 * @param release Allocator responsible(1)/not reponsible(0) for 00093 * freeing memory. 00094 * @return ACE_String_Base containing const CHAR *s 00095 */ 00096 ACE_String_Base (const CHAR *s, 00097 size_t len, 00098 ACE_Allocator *the_allocator = 0, 00099 int release = 1); 00100 00101 /** 00102 * Copy constructor. 00103 * 00104 * @param s Input ACE_String_Base string to copy 00105 * @return Copy of input string @a s 00106 */ 00107 ACE_String_Base (const ACE_String_Base < CHAR > &s); 00108 00109 /** 00110 * Constructor that copies @a c into dynamically allocated memory. 00111 * 00112 * @param c Single input character. 00113 * @param the_allocator ACE_Allocator associated with string 00114 * @return ACE_String_Base containing CHAR 'c' 00115 */ 00116 ACE_String_Base (CHAR c, ACE_Allocator *the_allocator = 0); 00117 00118 /** 00119 * Constructor that allocates a len long string. 00120 * 00121 * Warning : This constructor was incorrectly documented in the past. 00122 * It simply calls resize(len, c). 00123 * It is probably not advisable to use the second parameter. See 00124 * resize() for more information. 00125 * 00126 * @param len Amount of space to reserve for the string. 00127 * @param c The array is filled with c's 00128 * @param the_allocator ACE_Allocator associated with string 00129 * @return Empty ACE_String_Base with room for len CHARs 00130 */ 00131 ACE_String_Base (size_t len, 00132 CHAR c = 0, 00133 ACE_Allocator *the_allocator = 0); 00134 00135 /** 00136 * Deletes the memory... 00137 */ 00138 ~ACE_String_Base (void); 00139 00140 /** 00141 * Return the <slot'th> character in the string (doesn't perform 00142 * bounds checking). 00143 * 00144 * @param slot Index of the desired character 00145 * @return The character at index @a slot 00146 */ 00147 const CHAR & operator[] (size_t slot) const; 00148 00149 /** 00150 * Return the <slot'th> character by reference in the string 00151 * (doesn't perform bounds checking). 00152 * 00153 * @param slot Index of the desired character 00154 * @return The character at index @a slot 00155 */ 00156 CHAR & operator[] (size_t slot); 00157 00158 /** 00159 * Assignment operator (does copy memory). 00160 * 00161 * @param s Input null-terminated CHAR string to assign to this object. 00162 * @return Return a copy of the this string. 00163 */ 00164 ACE_String_Base < CHAR > &operator = (const CHAR * s); 00165 00166 /** 00167 * Assignment operator (does copy memory). 00168 * 00169 * @param s Input ACE_String_Base string to assign to this object. 00170 * @return Return a copy of the this string. 00171 */ 00172 ACE_String_Base < CHAR > &operator = (const ACE_String_Base < CHAR > &s); 00173 00174 /** 00175 * Assignment alternative method (does not copy memory). 00176 * 00177 * @param s Input ACE_String_Base string to assign to this object. 00178 * @return Return this string. 00179 */ 00180 ACE_String_Base < CHAR > &assign_nocopy (const ACE_String_Base < CHAR > &s); 00181 00182 /** 00183 * Copy @a s into this @a ACE_String_Base. 00184 * 00185 * If release == 1 then a new buffer is allocated internally if the 00186 * existing one is not big enough to hold s. If the existing 00187 * buffer is big enough, then it will be used. This means that 00188 * set(*, 1) can be illegal when the string is constructed with a 00189 * const char*. (e.g. ACE_String_Base("test", 0, 0)). 00190 * 00191 * if release == 0 then the s buffer is used directly, and any 00192 * existing buffer is destroyed. If s == 0 then it will _not_ be 00193 * used, and instead the internal buffer is set to NULL_String_. 00194 * 00195 * @param s Null terminated input string 00196 * @param release Allocator responsible(1)/not reponsible(0) for 00197 * freeing memory. 00198 */ 00199 void set (const CHAR * s, int release = 1); 00200 00201 /** 00202 * Copy @a len bytes of @a s (will zero terminate the result). 00203 * 00204 * If release == 1 then a new buffer is allocated internally if the 00205 * existing one is not big enough to hold s. If the existing 00206 * buffer is big enough, then it will be used. This means that 00207 * set(*, *, 1) is illegal when the string is constructed with a 00208 * non-owned const char*. (e.g. ACE_String_Base("test", 0, 0)) 00209 * 00210 * If release == 0 then the s buffer is used directly, and any 00211 * existing buffer is destroyed. If s == 0 then it will _not_ be 00212 * used, and instead the internal buffer is set to NULL_String_. 00213 * 00214 * @param s Non-zero terminated input string 00215 * @param len Length of input string 's' 00216 * @param release Allocator responsible(1)/not reponsible(0) for 00217 * freeing memory. 00218 */ 00219 void set (const CHAR * s, size_t len, int release); 00220 00221 /** 00222 * Clear this string. Memory is _not_ freed if <release> is 0. 00223 * 00224 * Warning: This method was incorrectly documented in the past, but 00225 * the current implementation has been changed to match the documented 00226 * behavior. 00227 * 00228 * Warning: clear(0) behaves like fast_clear() below. 00229 * 00230 * @param release Memory is freed if 1 or not if 0. 00231 */ 00232 void clear (int release = 0); 00233 00234 /** 00235 * A more specialized version of clear(): "fast clear". fast_clear() 00236 * resets the string to 0 length. If the string owns the buffer 00237 * (@arg release_== 1): 00238 * - the string buffer is not freed 00239 * - the first character of the buffer is set to 0. 00240 * 00241 * If @arg release_ is 0 (this object does not own the buffer): 00242 * - the buffer pointer is reset to the NULL_String_ and does not 00243 * maintain a pointer to the caller-supplied buffer on return 00244 * - the maximum string length is reset to 0. 00245 * 00246 * Warning : Calling clear(0) or fast_clear() can have unintended 00247 * side-effects if the string was constructed (or set()) with an 00248 * external buffer. The string will be disassociated with the buffer 00249 * and the next append() or +=() will cause a new buffer to be 00250 * allocated internally. 00251 */ 00252 void fast_clear (void); 00253 00254 /** 00255 * Return a substring given an offset and length, if length == -1 00256 * use rest of str. Return empty substring if offset or 00257 * offset/length are invalid. 00258 * 00259 * @param offset Index of first desired character of the substring. 00260 * @param length How many characters to return starting at the offset. 00261 * @return The string containing the desired substring 00262 */ 00263 ACE_String_Base < CHAR > substring (size_t offset, 00264 ssize_t length = -1) const; 00265 00266 /** 00267 * Same as <substring>. 00268 * 00269 * @param offset Index of first desired character of the substring. 00270 * @param length How many characters to return starting at the offset. 00271 * @return The string containing the desired substring 00272 */ 00273 ACE_String_Base < CHAR > substr (size_t offset, ssize_t length = -1) const; 00274 00275 /** 00276 * Concat operator (copies memory). 00277 * 00278 * @param s Input ACE_String_Base string to concatenate to this string. 00279 * @return The combined string (input append to the end of the old). New 00280 * string is zero terminated. 00281 */ 00282 ACE_String_Base < CHAR > &operator += (const ACE_String_Base < CHAR > &s); 00283 00284 /** 00285 * Concat operator (copies memory). 00286 * 00287 * @param s Input C string to concatenate to this string. 00288 * @return The combined string (input append to the end of the old). New 00289 * string is zero terminated. 00290 */ 00291 ACE_String_Base < CHAR >& operator += (const CHAR* s); 00292 00293 /** 00294 * Concat operator (copies memory). 00295 * 00296 * @param c Input CHAR to concatenate to this string. 00297 * @return The combined string (input append to the end of the old). New 00298 * string is zero terminated. 00299 */ 00300 ACE_String_Base < CHAR >& operator += (const CHAR c); 00301 00302 /** 00303 * Append function (copies memory). 00304 * 00305 * @param s Input CHAR array to concatenate to this string. 00306 * @param slen The length of the array. 00307 * @return The combined string (input append to the end of the old). New 00308 * string is zero terminated. 00309 */ 00310 ACE_String_Base < CHAR >& append (const CHAR* s, size_t slen); 00311 00312 /** 00313 * Returns a hash value for this string. 00314 * 00315 * @return Hash value of string 00316 */ 00317 u_long hash (void) const; 00318 00319 /** 00320 * Return the length of the string. 00321 * 00322 * @return Length of stored string 00323 */ 00324 size_t length (void) const; 00325 00326 /** 00327 * Return @c true if the length of the string is zero, else @c false. 00328 */ 00329 bool is_empty (void) const; 00330 00331 /** 00332 * Return @c true if the length of the string is zero, else @c 00333 * false. We recommend using @c is_empty() instead since it's more 00334 * consistent with the ACE container naming conventions. 00335 */ 00336 bool empty (void) const; 00337 00338 /** 00339 * Get a copy of the underlying representation. 00340 * 00341 * This method allocates memory for a copy of the string and returns 00342 * a pointer to the new area. The caller is responsible for freeing 00343 * the memory when finished; use delete [] 00344 * 00345 * @return Pointer reference to the string data. Returned string is 00346 * zero terminated. 00347 */ 00348 CHAR *rep (void) const; 00349 00350 /** 00351 * Get at the underlying representation directly! 00352 * _Don't_ even think about casting the result to (char *) and modifying it, 00353 * if it has length 0! 00354 * 00355 * @return Pointer reference to the stored string data. No guarantee is 00356 * that the string is zero terminated. 00357 * 00358 */ 00359 const CHAR *fast_rep (void) const; 00360 00361 /** 00362 * Same as STL String's <c_str> and <fast_rep>. 00363 */ 00364 const CHAR *c_str (void) const; 00365 00366 /** 00367 * Comparison operator that will match substrings. Returns the 00368 * slot of the first location that matches, else -1. 00369 * 00370 * @param s Input ACE_String_Base string 00371 * @return Integer index value of the first location of string @a s or 00372 * -1 (not found). 00373 */ 00374 ssize_t strstr (const ACE_String_Base<CHAR> &s) const; 00375 00376 /** 00377 * Find <str> starting at pos. Returns the slot of the first 00378 * location that matches (will be >= pos), else npos. 00379 * 00380 * @param str Input ACE_String_Base string to search for in stored string. 00381 * @param pos Starting index position to start searching for string @a str. 00382 * @return Index value of the first location of string @a str else npos. 00383 */ 00384 ssize_t find (const ACE_String_Base<CHAR> &str, size_t pos = 0) const; 00385 00386 /** 00387 * Find @a s starting at pos. Returns the slot of the first 00388 * location that matches (will be >= pos), else npos. 00389 * 00390 * @param s non-zero input string to search for in stored string. 00391 * @param pos Starting index position to start searching for string @a str. 00392 * @return Index value of the first location of string @a str else npos. 00393 */ 00394 ssize_t find (const CHAR *s, size_t pos = 0) const; 00395 00396 /** 00397 * Find @a c starting at pos. Returns the slot of the first 00398 * location that matches (will be >= pos), else npos. 00399 * 00400 * @param c Input character to search for in stored string. 00401 * @param pos Starting index position to start searching for string @a str. 00402 * @return Index value of the first location of string @a str else npos. 00403 */ 00404 ssize_t find (CHAR c, size_t pos = 0) const; 00405 00406 /** 00407 * Find @a c starting at pos (counting from the end). Returns the 00408 * slot of the first location that matches, else npos. 00409 * 00410 * @param c Input character to search for in stored string. 00411 * @param pos Starting index position to start searching for string @a str. 00412 * @return Index value of the first location of string @a str else npos. 00413 */ 00414 ssize_t rfind (CHAR c, ssize_t pos = npos) const; 00415 00416 /** 00417 * Equality comparison operator (must match entire string). 00418 * 00419 * @param s Input ACE_String_Base string to compare against stored string. 00420 * @return @c true if equal, @c false otherwise. 00421 */ 00422 bool operator == (const ACE_String_Base<CHAR> &s) const; 00423 00424 /** 00425 * Equality comparison operator (must match entire string). 00426 * 00427 * @param s Null terminated string to compare against stored string. 00428 * @return @c true if equal, @c false otherwise. 00429 */ 00430 bool operator == (const CHAR *s) const; 00431 00432 /** 00433 * Less than comparison operator. 00434 * 00435 * @param s Input ACE_String_Base string to compare against stored string. 00436 * @return @c true if less than, @c false otherwise. 00437 */ 00438 bool operator < (const ACE_String_Base<CHAR> &s) const; 00439 00440 /** 00441 * Greater than comparison operator. 00442 * 00443 * @param s Input ACE_String_Base string to compare against stored string. 00444 * @return @c true if greater than, @c false otherwise. 00445 */ 00446 bool operator > (const ACE_String_Base<CHAR> &s) const; 00447 00448 /** 00449 * Inequality comparison operator. 00450 * 00451 * @param s Input ACE_String_Base string to compare against stored string. 00452 * @return @c true if not equal, @c false otherwise. 00453 */ 00454 bool operator != (const ACE_String_Base<CHAR> &s) const; 00455 00456 /** 00457 * Inequality comparison operator. 00458 * 00459 * @param s Null terminated string to compare against stored string. 00460 * @return @c true if not equal, @c false otherwise. 00461 */ 00462 bool operator != (const CHAR *s) const; 00463 00464 /** 00465 * Performs a strncmp comparison. 00466 * 00467 * @param s Input ACE_String_Base string to compare against stored string. 00468 * @return Integer value of result (less than 0, 0, greater than 0) 00469 * depending on how input string @a s is to the stored string. 00470 */ 00471 int compare (const ACE_String_Base<CHAR> &s) const; 00472 00473 /** 00474 * Dump the state of an object. 00475 */ 00476 void dump (void) const; 00477 00478 /** 00479 * This method is designed for high-performance. Please use with 00480 * care ;-) 00481 * 00482 * Warning : This method was documented incorrectly in the past. 00483 * The original intention was to change the length of the string to 00484 * len, and to fill the whole thing with c CHARs. 00485 * However, what was actually done was to set the length of the 00486 * string to zero, and fill the buffer with c's. The buffer was 00487 * also not null-terminated unless c happened to be zero. 00488 * Rather than fix the method to work as documented, the code is 00489 * left as is, but the second parameter should probably not be used. 00490 * 00491 * @param len The number of CHARs to reserve 00492 * @param c The CHAR to use when filling the string. 00493 */ 00494 void resize (size_t len, CHAR c = 0); 00495 00496 /** 00497 * Declare the dynamic allocation hooks. 00498 */ 00499 ACE_ALLOC_HOOK_DECLARE; 00500 00501 protected: 00502 /** 00503 * Pointer to a memory allocator. 00504 */ 00505 ACE_Allocator *allocator_; 00506 00507 /** 00508 * Length of the ACE_String_Base data (not counting the trailing '\0'). 00509 */ 00510 size_t len_; 00511 00512 /** 00513 * Length of the ACE_String_Base data buffer. Keeping track of the 00514 * length allows to avoid unnecessary dynamic allocations. 00515 */ 00516 size_t buf_len_; 00517 00518 /** 00519 * Pointer to data. 00520 */ 00521 CHAR *rep_; 00522 00523 /** 00524 * Flag that indicates if we own the memory 00525 */ 00526 int release_; 00527 00528 /** 00529 * Represents the "NULL" string to simplify the internal logic. 00530 */ 00531 static CHAR NULL_String_; 00532 }; 00533 00534 template < class CHAR > 00535 ACE_String_Base < CHAR > operator + (const ACE_String_Base < CHAR > &, 00536 const ACE_String_Base < CHAR > &); 00537 template < class CHAR > 00538 ACE_String_Base < CHAR > operator + (const ACE_String_Base < CHAR > &, 00539 const CHAR *); 00540 template < class CHAR > 00541 ACE_String_Base < CHAR > operator + (const CHAR *, 00542 const ACE_String_Base < CHAR > &); 00543 00544 template < class CHAR > 00545 ACE_String_Base < CHAR > operator + (const ACE_String_Base < CHAR > &t, 00546 const CHAR c); 00547 00548 template < class CHAR > 00549 ACE_String_Base < CHAR > operator + (const CHAR c, 00550 const ACE_String_Base < CHAR > &t); 00551 00552 template <class CHAR> 00553 bool operator == (const CHAR *s, 00554 const ACE_String_Base<CHAR> &t); 00555 00556 template <class CHAR> 00557 bool operator != (const CHAR *s, 00558 const ACE_String_Base<CHAR> &t); 00559 00560 ACE_END_VERSIONED_NAMESPACE_DECL 00561 00562 #if defined (__ACE_INLINE__) 00563 #include "ace/String_Base.inl" 00564 #endif /* __ACE_INLINE__ */ 00565 00566 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE) 00567 #include "ace/String_Base.cpp" 00568 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */ 00569 00570 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA) 00571 #pragma implementation ("String_Base.cpp") 00572 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */ 00573 00574 #include /**/ "ace/post.h" 00575 00576 #endif /* ACE_STRING_BASE_H */