String_Base.h

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

Generated on Thu Nov 9 09:42:05 2006 for ACE by doxygen 1.3.6