Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

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,v 1.1.1.1.2.1 2003/06/10 11:54:49 chad 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 #include "ace/pre.h"
00017 
00018 #include "ace/ACE.h"
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 // Forward decl.
00026 class ACE_Allocator;
00027 
00028 /**
00029  * @class ACE_String_Base
00030  *
00031  * @brief This class provides a wrapper facade for C strings.
00032  *
00033  * This class uses an ACE_Allocator to allocate memory.  The
00034  * user can make this a persistant class by providing an
00035  * ACE_Allocator with a persistable memory pool.  This class is
00036  * optimized for efficiency, so it doesn't provide any internal
00037  * locking.
00038  * NOTE: if an instance of this class is constructed from or
00039  * assigned an empty string (with first element of '\0'), then it
00040  * is not allocated new space.  Instead, its internal
00041  * representation is set equal to a global empty string.
00042  * CAUTION: in cases when ACE_String_Base is constructed from a
00043  * provided buffer with the release parameter set to 0,
00044  * ACE_String_Base is not guaranteed to be '\0' terminated.
00045  */
00046 template <class CHAR> class ACE_String_Base : public ACE_String_Base_Const
00047 {
00048 public:
00049    /**
00050     *  Default constructor.
00051     *
00052     *  @param alloc ACE_Allocator associated with string
00053     *  @return Default ACE_String_Base string.
00054     */
00055   ACE_String_Base (ACE_Allocator * alloc = 0);
00056 
00057   /**
00058    * Constructor that copies @a s into dynamically allocated memory.
00059    * If @a release is non-0 then the @a ACE_Allocator is responsible for
00060    * freeing this memory. Memory is _not_ allocated/freed if @a release
00061    * is 0.
00062    *
00063    * @param s Zero terminated input string
00064    * @param alloc ACE_Allocator associated with string
00065    * @param release Allocator responsible(1)/not reponsible(0) for
00066    *    freeing memory.
00067    * @return ACE_String_Base containing const CHAR *s
00068    */
00069   ACE_String_Base (const CHAR * s,
00070                    ACE_Allocator * alloc = 0,
00071                    int release = 1);
00072 
00073   /**
00074    * Constructor that copies @a len CHARs of @a s into dynamically
00075    * allocated memory (will zero terminate the result).  If @a release
00076    * is non-0 then the @a ACE_allocator is responsible for freeing this
00077    * memory.  Memory is _not_ allocated/freed if @a release is 0.
00078    *
00079    * @param s Non-zero terminated input string
00080    * @param len Length of non-zero terminated input string
00081    * @param alloc ACE_Allocator associated with string
00082    * @param release Allocator responsible(1)/not reponsible(0) for
00083    *    freeing memory.
00084    * @return ACE_String_Base containing const CHAR *s
00085    */
00086   ACE_String_Base (const CHAR * s,
00087                    size_t len,
00088                    ACE_Allocator * alloc = 0,
00089                    int release = 1);
00090 
00091   /**
00092    *  Copy constructor.
00093    *
00094    *  @param s Input ACE_String_Base string to copy
00095    *  @return Copy of input string @a s
00096    */
00097   ACE_String_Base (const ACE_String_Base < CHAR > &s);
00098 
00099   /**
00100    *  Constructor that copies @a c into dynamically allocated memory.
00101    *
00102    *  @param c Single input character.
00103    *  @param alloc ACE_Allocator associated with string
00104    *  @return ACE_String_Base containing CHAR 'c'
00105    */
00106   ACE_String_Base (CHAR c,
00107                    ACE_Allocator * alloc = 0);
00108 
00109   /**
00110    *  Constructor that dynamically allocate @a len long of char array
00111    *  and initialize it to @a c using @a alloc to allocate the memory.
00112    *
00113    *  @param len Length of character array 'c'
00114    *  @param c Input character array
00115    *  @param alloc ACE_Allocator associated with string
00116    *  @return ACE_String_Base containing character array 'c'
00117    */
00118   ACE_String_Base (size_t len,
00119                    CHAR c = 0,
00120                    ACE_Allocator * alloc = 0);
00121 
00122   /**
00123    *  Deletes the memory...
00124    */
00125   ~ACE_String_Base (void);
00126 
00127   /**
00128    * Return the <slot'th> character in the string (doesn't perform
00129    * bounds checking).
00130    *
00131    * @param slot Index of the desired character
00132    * @return The character at index @a slot
00133    */
00134   const CHAR & operator[] (size_t slot) const;
00135 
00136   /**
00137    * Return the <slot'th> character by reference in the string
00138    * (doesn't perform bounds checking).
00139    *
00140    * @param slot Index of the desired character
00141    * @return The character at index @a slot
00142    */
00143   CHAR & operator[] (size_t slot);
00144 
00145   /**
00146    *  Assignment operator (does copy memory).
00147    *
00148    *  @param s Input ACE_String_Base string to assign to this object.
00149    *  @return Return a copy of the this string.
00150    */
00151   ACE_String_Base < CHAR > &operator = (const ACE_String_Base < CHAR > &s);
00152 
00153   /**
00154    *  Assignment alternative method (does not copy memory).
00155    *
00156    *  @param s Input ACE_String_Base string to assign to this object.
00157    *  @return Return this string.
00158    */
00159   ACE_String_Base < CHAR > &assign_nocopy (const ACE_String_Base < CHAR > &s);
00160 
00161   /**
00162    * Copy @a s into this @a ACE_String_Base.  Memory is _not_
00163    * allocated/freed if @a release is 0.
00164    *
00165    * @param s Null terminated input string
00166    * @param release Allocator responsible(1)/not reponsible(0) for
00167    *    freeing memory.
00168    */
00169   void set (const CHAR * s, int release = 1);
00170 
00171   /**
00172    *  Copy @a len bytes of @a s (will zero terminate the result).
00173    *  Memory is _not_ allocated/freed if @a release is 0.
00174    *
00175    *  @param s Non-zero terminated input string
00176    *  @param len Length of input string 's'
00177    *  @param release Allocator responsible(1)/not reponsible(0) for
00178    *    freeing memory.
00179    */
00180   void set (const CHAR * s, size_t len, int release);
00181 
00182   /**
00183    * Clear this string. Memory is _not_ freed if <release> is 0.
00184    *
00185    * @param release Memory is freed if 1 or not if 0.
00186    */
00187   void clear (int release = 0);
00188 
00189   /**
00190    * Return a substring given an offset and length, if length == -1
00191    * use rest of str.  Return empty substring if offset or
00192    * offset/length are invalid.
00193    *
00194    * @param offset Index of first desired character of the substring.
00195    * @param length How many characters to return starting at the offset.
00196    * @return The string containing the desired substring
00197    */
00198   ACE_String_Base < CHAR > substring (size_t offset,
00199                                       ssize_t length = -1) const;
00200 
00201   /**
00202    *  Same as <substring>.
00203    *
00204    * @param offset Index of first desired character of the substring.
00205    * @param length How many characters to return starting at the offset.
00206    * @return The string containing the desired substring
00207    */
00208   ACE_String_Base < CHAR > substr (size_t offset, ssize_t length = -1) const;
00209 
00210   /**
00211    *  Concat operator (copies memory).
00212    *
00213    *  @param s Input ACE_String_Base string to concatenate to another string.
00214    *  @return The combined string (input append to the end of the old). New
00215    *    string is zero terminated.
00216    */
00217   ACE_String_Base < CHAR > &operator += (const ACE_String_Base < CHAR > &s);
00218 
00219   /**
00220    *  Returns a hash value for this string.
00221    *
00222    *  @return Hash value of string
00223    */
00224   u_long hash (void) const;
00225 
00226   /**
00227    *  Return the length of the string.
00228    *
00229    *  @return Length of stored string
00230    */
00231   size_t length (void) const;
00232 
00233   /**
00234    * Get a copy of the underlying representation.
00235    *
00236    * This method allocates memory for a copy of the string and returns
00237    * a pointer to the new area. The caller is responsible for freeing
00238    * the memory when finished; use delete []
00239    *
00240    * @return Pointer reference to the string data. Returned string is
00241    *    zero terminated.
00242    */
00243   CHAR *rep (void) const;
00244 
00245   /**
00246    * Get at the underlying representation directly!
00247    * _Don't_ even think about casting the result to (char *) and modifying it,
00248    * if it has length 0!
00249    *
00250    * @return Pointer reference to the stored string data. No guarantee is
00251    *    that the string is zero terminated.
00252    *
00253    */
00254   const CHAR *fast_rep (void) const;
00255 
00256   /**
00257    *  Same as STL String's <c_str> and <fast_rep>.
00258    */
00259   const CHAR *c_str (void) const;
00260 
00261   /**
00262    *  Comparison operator that will match substrings.  Returns the
00263    *  slot of the first location that matches, else -1.
00264    *
00265    *  @param s Input ACE_String_Base string
00266    *  @return Integer index value of the first location of string @a s or
00267    *    -1 (not found).
00268    */
00269   ssize_t strstr (const ACE_String_Base<CHAR> &s) const;
00270 
00271   /**
00272    *  Find <str> starting at pos.  Returns the slot of the first
00273    *  location that matches (will be >= pos), else npos.
00274    *
00275    *  @param str Input ACE_String_Base string to search for in stored string.
00276    *  @param pos Starting index position to start searching for string @a str.
00277    *  @return Index value of the first location of string @a str else npos.
00278    */
00279   ssize_t find (const ACE_String_Base<CHAR> &str, size_t pos = 0) const;
00280 
00281   /**
00282    *  Find @a s starting at pos.  Returns the slot of the first
00283    *  location that matches (will be >= pos), else npos.
00284    *
00285    *  @param s non-zero input string to search for in stored string.
00286    *  @param pos Starting index position to start searching for string @a str.
00287    *  @return Index value of the first location of string @a str else npos.
00288    */
00289   ssize_t find (const CHAR *s, size_t pos = 0) const;
00290 
00291   /**
00292    *  Find @a c starting at pos.  Returns the slot of the first
00293    *  location that matches (will be >= pos), else npos.
00294    *
00295    *  @param c Input character to search for in stored string.
00296    *  @param pos Starting index position to start searching for string @a str.
00297    *  @return Index value of the first location of string @a str else npos.
00298    */
00299   ssize_t find (CHAR c, size_t pos = 0) const;
00300 
00301   /**
00302    *  Find @a c starting at pos (counting from the end).  Returns the
00303    *  slot of the first location that matches, else npos.
00304    *
00305    *  @param c Input character to search for in stored string.
00306    *  @param pos Starting index position to start searching for string @a str.
00307    *  @return Index value of the first location of string @a str else npos.
00308    */
00309   ssize_t rfind (CHAR c, ssize_t pos = npos) const;
00310 
00311   /**
00312    *  Equality comparison operator (must match entire string).
00313    *
00314    * @param s Input ACE_String_Base string to compare against stored string.
00315    * @return Integer value of result (1 = found, 0 = not found).
00316    */
00317   int operator == (const ACE_String_Base<CHAR> &s) const;
00318 
00319   /**
00320    *  Less than comparison operator.
00321    *
00322    *  @param s Input ACE_String_Base string to compare against stored string.
00323    *  @return Integer value of result (1 = less than, 0 = greater than or
00324    *  equal).
00325    */
00326   int operator < (const ACE_String_Base<CHAR> &s) const;
00327 
00328   /**
00329    *  Greater than comparison operator.
00330    *
00331    *  @param s Input ACE_String_Base string to compare against stored string.
00332    *  @return Integer value of result (1 = greater than, 0 = less than or
00333    *  equal).
00334    */
00335   int operator > (const ACE_String_Base<CHAR> &s) const;
00336 
00337   /**
00338    *  Inequality comparison operator.
00339    *
00340    *  @param s Input ACE_String_Base string to compare against stored string.
00341    *  @return Integer value of result (1 = not equal, 0 = equal).
00342    */
00343   int operator != (const ACE_String_Base<CHAR> &s) const;
00344 
00345   /**
00346    *  Performs a strncmp comparison.
00347    *
00348    *  @param s Input ACE_String_Base string to compare against stored string.
00349    *  @return Integer value of result (less than 0, 0, greater than 0)
00350    *    depending on how input string @a s is to the stored string.
00351    */
00352   int compare (const ACE_String_Base<CHAR> &s) const;
00353 
00354   /**
00355    *  Dump the state of an object.
00356    */
00357   void dump (void) const;
00358 
00359   /**
00360    * This method is designed for high-performance. Please use with
00361    * care ;-) If the current size of the string is less than <len>,
00362    * the string is resized to the new length. The data is zero'd
00363    * out after this operation.
00364    *
00365    * @param len New string size
00366    * @param c New input string
00367    */
00368   void resize (size_t len, CHAR c = 0);
00369 
00370   /**
00371    *  Declare the dynamic allocation hooks.
00372    */
00373   ACE_ALLOC_HOOK_DECLARE;
00374 
00375 protected:
00376   /**
00377    *  Pointer to a memory allocator.
00378    */
00379   ACE_Allocator * allocator_;
00380 
00381   /**
00382    *  Length of the ACE_String_Base data (not counting the trailing '\0').
00383    */
00384   size_t len_;
00385 
00386   /**
00387    *  Length of the ACE_String_Base data buffer.  Keeping track of the
00388    *  length allows to avoid unnecessary dynamic allocations.
00389    */
00390   size_t buf_len_;
00391 
00392   /**
00393    *  Pointer to data.
00394    */
00395   CHAR *rep_;
00396 
00397   /**
00398    *  Flag that indicates if we own the memory
00399    */
00400   int release_;
00401 
00402   /**
00403    *  Represents the "NULL" string to simplify the internal logic.
00404    */
00405   static CHAR NULL_String_;
00406 };
00407 
00408 template < class CHAR > ACE_INLINE
00409   ACE_String_Base < CHAR > operator + (const ACE_String_Base < CHAR > &,
00410                                        const ACE_String_Base < CHAR > &);
00411 template < class CHAR > ACE_INLINE
00412   ACE_String_Base < CHAR > operator + (const ACE_String_Base < CHAR > &,
00413                                        const CHAR *);
00414 template < class CHAR > ACE_INLINE
00415   ACE_String_Base < CHAR > operator + (const CHAR *,
00416                                        const ACE_String_Base < CHAR > &);
00417 
00418 template < class CHAR > ACE_INLINE
00419   ACE_String_Base < CHAR > operator + (const ACE_String_Base < CHAR > &t,
00420                                        const CHAR c);
00421 
00422 template < class CHAR > ACE_INLINE
00423   ACE_String_Base < CHAR > operator + (const CHAR c,
00424                                        const ACE_String_Base < CHAR > &t);
00425 
00426 #if defined (__ACE_INLINE__)
00427 #include "ace/String_Base.i"
00428 #endif /* __ACE_INLINE__ */
00429 
00430 #if defined (ACE_TEMPLATES_REQUIRE_SOURCE)
00431 #include "ace/String_Base.cpp"
00432 #endif /* ACE_TEMPLATES_REQUIRE_SOURCE */
00433 
00434 #if defined (ACE_TEMPLATES_REQUIRE_PRAGMA)
00435 #pragma implementation ("String_Base.cpp")
00436 #endif /* ACE_TEMPLATES_REQUIRE_PRAGMA */
00437 
00438 #include "ace/post.h"
00439 #endif /* ACE_STRING_BASE_H */

Generated on Mon Jun 16 11:21:31 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002