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