String_Base.h

Go to the documentation of this file.
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 */

Generated on Sun Jan 27 12:05:40 2008 for ACE by doxygen 1.3.6