SString.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file    SString.h
00006  *
00007  *  $Id: SString.h 78460 2007-05-23 13:33:56Z johnnyw $
00008  *
00009  *  @author Douglas C. Schmidt (schmidt@cs.wustl.edu)
00010  */
00011 //=============================================================================
00012 
00013 #ifndef ACE_SSTRING_H
00014 #define ACE_SSTRING_H
00015 #include /**/ "ace/pre.h"
00016 
00017 #include "ace/SStringfwd.h"
00018 
00019 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00020 # pragma once
00021 #endif /* ACE_LACKS_PRAGMA_ONCE */
00022 
00023 #include "ace/String_Base.h"
00024 
00025 #if !defined (ACE_DEFAULT_GROWSIZE)
00026 #define ACE_DEFAULT_GROWSIZE 32
00027 #endif /* ACE_DEFAULT_GROWSIZE */
00028 
00029 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
00030 #include "ace/iosfwd.h"
00031 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00032 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_CString &);
00033 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_WString &);
00034 ACE_END_VERSIONED_NAMESPACE_DECL
00035 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
00036 
00037 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00038 
00039 #if defined ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT
00040 template class ACE_Export ACE_String_Base<char>;
00041 template class ACE_Export ACE_String_Base<ACE_WSTRING_TYPE>;
00042 #endif /* ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT */
00043 
00044 /**
00045  * @class ACE_NS_WString
00046  *
00047  * @brief This class retain the backward compatibility for
00048  *        ACE_Naming_Context and related classes.  The only addition to
00049  *        ACE_WString is a very naive "wchar" to "char" conversion
00050  *        function.
00051  */
00052 class ACE_Export ACE_NS_WString : public ACE_WString
00053 {
00054 public:
00055 
00056   using ACE_WString::size_type;
00057 
00058   /// Default constructor.
00059   ACE_NS_WString (ACE_Allocator *alloc = 0);
00060 
00061   /// Constructor that copies @a s into dynamically allocated memory.
00062   ACE_NS_WString (const char *s,
00063                   ACE_Allocator *alloc = 0);
00064 
00065   /// Constructor that copies @a s into dynamically allocated memory.
00066   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
00067                   ACE_Allocator *alloc = 0);
00068 
00069 #if defined (ACE_WSTRING_HAS_USHORT_SUPPORT)
00070   /// Constructor that takes in a ushort16 string (mainly used by the
00071   /// ACE Name_Space classes)
00072   ACE_NS_WString (const ACE_USHORT16 *s,
00073                   size_type len,
00074                   ACE_Allocator *alloc = 0);
00075 #endif /* ACE_WSTRING_HAS_USHORT_SUPPORT */
00076 
00077   /// Constructor that copies @a len ACE_WSTRING_TYPE's of @a s into dynamically
00078   /// allocated memory (will NUL terminate the result).
00079   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
00080                   size_type len,
00081                   ACE_Allocator *alloc = 0);
00082 
00083   /// Constructor that dynamically allocates memory for @a len + 1
00084   /// ACE_WSTRING_TYPE characters. The newly created memory is set memset to 0.
00085   ACE_NS_WString (size_type len, ACE_Allocator *alloc = 0);
00086 
00087   /// Copy constructor.
00088   ACE_NS_WString (const ACE_NS_WString &s);
00089 
00090   /// Constructor that copies @a c into dynamically allocated memory.
00091   ACE_NS_WString (ACE_WSTRING_TYPE c, ACE_Allocator *alloc = 0);
00092 
00093   /// Transform into a copy of the ASCII character representation.
00094   /// (caller must delete)
00095   char *char_rep (void) const;
00096 
00097   /// Transform into a copy of a USHORT16 representation (caller must
00098   /// delete).  Note, behavior is undefined when sizeof (wchar_t) != 2.
00099   ACE_USHORT16 *ushort_rep (void) const;
00100 };
00101 
00102 ACE_Export
00103 ACE_NS_WString operator + (const ACE_NS_WString &,
00104                            const ACE_NS_WString &);
00105 
00106 // -----------------------------------------------------------------
00107 
00108 /**
00109  * @class ACE_SString
00110  *
00111  * @brief A very Simple String ACE_SString class.  This is not a
00112  * general-purpose string class, and you should probably consider
00113  * using ACE_CString is you don't understand why this class
00114  * exists...
00115  *
00116  * This class is optimized for efficiency, so it doesn't provide
00117  * any internal locking.
00118  * CAUTION: This class is only intended for use with applications
00119  * that understand how it works.  In particular, its destructor
00120  * does not deallocate its memory when it is destroyed...  We need
00121  * this class since the ACE_Map_Manager requires an object that
00122  * supports the operator == and operator !=.  This class uses an
00123  * ACE_Allocator to allocate memory.  The user can make this a
00124  * persistant class by providing an ACE_Allocator with a
00125  * persistable memory pool.
00126  */
00127 class ACE_Export ACE_SString
00128 {
00129 public:
00130 
00131   typedef ACE_Allocator::size_type size_type;
00132 
00133   /// No position constant
00134   static const size_type npos;
00135 
00136   /// Default constructor.
00137   ACE_SString (ACE_Allocator *alloc = 0);
00138 
00139   /// Constructor that copies @a s into dynamically allocated memory.
00140   ACE_SString (const char *s, ACE_Allocator *alloc = 0);
00141 
00142   /// Constructor that copies @a len chars of  @s  into dynamically
00143   /// allocated memory (will NUL terminate the result).
00144   ACE_SString (const char *s, size_type len, ACE_Allocator *alloc = 0);
00145 
00146   /// Copy constructor.
00147   ACE_SString (const ACE_SString &);
00148 
00149   /// Constructor that copies @a c into dynamically allocated memory.
00150   ACE_SString (char c, ACE_Allocator *alloc = 0);
00151 
00152   /// Default destructor.
00153   ~ACE_SString (void);
00154 
00155   /// Return the <slot'th> character in the string (doesn't perform
00156   /// bounds checking).
00157   char operator [] (size_type slot) const;
00158 
00159   /// Return the <slot'th> character by reference in the string
00160   /// (doesn't perform bounds checking).
00161   char &operator [] (size_type slot);
00162 
00163   /// Assignment operator (does copy memory).
00164   ACE_SString &operator = (const ACE_SString &);
00165 
00166   /**
00167    * Return a substring given an offset and length, if length == npos
00168    * use rest of str return empty substring if offset or offset/length
00169    * are invalid
00170    */
00171   ACE_SString substring (size_type offset, size_type length = npos) const;
00172 
00173   /// Same as substring
00174   ACE_SString substr (size_type offset, size_type length = npos) const;
00175 
00176   /// Returns a hash value for this string.
00177   u_long hash (void) const;
00178 
00179   /// Return the length of the string.
00180   size_type length (void) const;
00181 
00182   /// Set the underlying pointer.  Since this does not copy memory or
00183   /// delete existing memory use with extreme caution!!!
00184   void rep (char *s);
00185 
00186   /// Get the underlying pointer.
00187   const char *rep (void) const;
00188 
00189   /// Get the underlying pointer.
00190   const char *fast_rep (void) const;
00191 
00192   /// Same as STL String's <c_str> and <fast_rep>.
00193   const char *c_str (void) const;
00194 
00195   /// Comparison operator that will match substrings.  Returns the
00196   /// slot of the first location that matches, else @c npos.
00197   size_type strstr (const ACE_SString &s) const;
00198 
00199   /// Find <str> starting at pos.  Returns the slot of the first
00200   /// location that matches (will be >= pos), else npos.
00201   size_type find (const ACE_SString &str, size_type pos = 0) const;
00202 
00203   /// Find <s> starting at pos.  Returns the slot of the first
00204   /// location that matches (will be >= pos), else npos.
00205   size_type find (const char *s, size_type pos = 0) const;
00206 
00207   /// Find <c> starting at pos.  Returns the slot of the first
00208   /// location that matches (will be >= pos), else npos.
00209   size_type find (char c, size_type pos = 0) const;
00210 
00211   /// Find <c> starting at pos (counting from the end).  Returns the
00212   /// slot of the first location that matches, else npos.
00213   size_type rfind (char c, size_type pos = npos) const;
00214 
00215   /// Equality comparison operator (must match entire string).
00216   bool operator == (const ACE_SString &s) const;
00217 
00218   /// Less than comparison operator.
00219   bool operator < (const ACE_SString &s) const;
00220 
00221   /// Greater than comparison operator.
00222   bool operator > (const ACE_SString &s) const;
00223 
00224   /// Inequality comparison operator.
00225   bool operator != (const ACE_SString &s) const;
00226 
00227   /// Performs a <strcmp>-style comparison.
00228   int compare (const ACE_SString &s) const;
00229 
00230   /// Dump the state of an object.
00231   void dump (void) const;
00232 
00233   /// Declare the dynamic allocation hooks.
00234   ACE_ALLOC_HOOK_DECLARE;
00235 
00236 private:
00237   /// Pointer to a memory allocator.
00238   ACE_Allocator *allocator_;
00239 
00240   /// Length of the ACE_SString (not counting the trailing '\0').
00241   size_type len_;
00242 
00243   /// Pointer to data.
00244   char *rep_;
00245 };
00246 
00247 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
00248 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_SString &);
00249 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
00250 
00251 // This allows one to use W or C String based on the Unicode
00252 // setting
00253 #if defined (ACE_USES_WCHAR)
00254 typedef ACE_WString ACE_TString;
00255 #else /* ACE_USES_WCHAR */
00256 typedef ACE_CString ACE_TString;
00257 #endif /* ACE_USES_WCHAR */
00258 
00259 
00260 // ************************************************************
00261 
00262 /**
00263  * @class ACE_Tokenizer
00264  *
00265  * @brief Tokenizer
00266  *
00267  * Tokenizes a buffer.  Allows application to set delimiters and
00268  * preserve designators.  Does not allow special characters, yet
00269  * (e.g., printf ("\"like a quoted string\"")).
00270  */
00271 class ACE_Export ACE_Tokenizer
00272 {
00273 public:
00274   /**
00275    * \a buffer will be parsed.  Notice that ACE_Tokenizer will modify
00276    * \a buffer if you use <code> delimiter_replace </code> or <code>
00277    * preserve_designators </code> to do character substitution.
00278    * @note You should NOT pass a constant string or string literal
00279    * to this constructor, since ACE_Tokenizer will try to modify
00280    * the string.
00281    * \sa preserve_designators
00282    * \sa preserve_designators
00283    */
00284   ACE_Tokenizer (ACE_TCHAR *buffer);
00285 
00286   /**
00287    * \a d is a delimiter.
00288    * \return Returns 0 on success, -1 if there is no memory left.
00289    *
00290    * <B>Example:</B>
00291    * \verbatim
00292      char buf[30];
00293      ACE_OS::strcpy(buf, "William/Joseph/Hagins");
00294 
00295      ACE_Tokenizer tok (buf);
00296      tok.delimiter ('/');
00297      for (char *p = tok.next (); p; p = tok.next ())
00298       cout << p << endl;
00299     \endverbatim
00300    *
00301    * This will print out:
00302    * \verbatim
00303      William/Joseph/Hagins
00304       Joseph/Hagins
00305       Hagins \endverbatim
00306    */
00307   int delimiter (ACE_TCHAR d);
00308 
00309   /**
00310    * \a d is a delimiter and, when found, will be replaced by
00311    * \a replacement.
00312    * \return 0 on success, -1 if there is no memory left.
00313    *
00314    * <B>Example:</B>
00315    * \verbatim
00316      char buf[30];
00317      ACE_OS::strcpy(buf, "William/Joseph/Hagins");
00318 
00319      ACE_Tokenizer tok (buf);
00320      tok.delimiter_replace ('/', 0);
00321      for (char *p = tok.next (); p; p = tok.next ())
00322        cout << p << endl;
00323     \endverbatim
00324    *
00325    * This will print out:
00326    * \verbatim
00327        William
00328        Joseph
00329        Hagins \endverbatim
00330  */
00331   int delimiter_replace (ACE_TCHAR d, ACE_TCHAR replacement);
00332 
00333   /**
00334    * Extract string between a pair of designator characters.
00335    * For instance, quotes, or '(' and ')'.
00336    * \a start specifies the begin designator.
00337    * \a stop specifies the end designator.
00338    * \a strip If \a strip == 1, then the preserve
00339    * designators will be stripped from the tokens returned by next.
00340    * \return 0 on success, -1 if there is no memory left.
00341    *
00342    * <B>Example with strip = 0:</B>
00343    * \verbatim
00344      char buf[30];
00345      ACE_OS::strcpy(buf, "William(Joseph)Hagins");
00346 
00347      ACE_Tokenizer tok (buf);
00348      tok.preserve_designators ('(', ')', 0);
00349      for (char *p = tok.next (); p; p = tok.next ())
00350        cout << p << endl;
00351     \endverbatim
00352    *
00353    * This will print out:
00354    * \verbatim
00355       William(Joseph)Hagins
00356       (Joseph)Hagins
00357       )Hagins \endverbatim
00358    *
00359    * <B>Example with strip = 1:</B>
00360    * \verbatim
00361      char buf[30];
00362      ACE_OS::strcpy(buf, "William(Joseph)Hagins");
00363 
00364      ACE_Tokenizer tok (buf);
00365      tok.preserve_designators ('(', ')', 1);
00366      for (char *p = tok.next (); p; p = tok.next ())
00367        cout << p << endl;
00368     \endverbatim
00369    *
00370    * This will print out:
00371    * \verbatim
00372       William
00373       Joseph
00374       Hagins \endverbatim
00375    */
00376   int preserve_designators (ACE_TCHAR start, ACE_TCHAR stop, int strip=1);
00377 
00378   /// Returns the next token.
00379   ACE_TCHAR *next (void);
00380 
00381   enum {
00382     MAX_DELIMITERS=16,
00383     MAX_PRESERVES=16
00384   };
00385 
00386 protected:
00387   /// Returns 1 if <d> is a delimiter, 0 otherwise.  If <d> should be
00388   /// replaced with @a r, <replace> is set to 1, otherwise 0.
00389   int is_delimiter (ACE_TCHAR d, int &replace, ACE_TCHAR &r);
00390 
00391   /**
00392    * If <start> is a start preserve designator, returns 1 and sets
00393    * <stop> to the stop designator.  Returns 0 if <start> is not a
00394    * preserve designator.
00395    */
00396   int is_preserve_designator (ACE_TCHAR start, ACE_TCHAR &stop, int &strip);
00397 
00398   ACE_TCHAR *buffer_;
00399   int index_;
00400 
00401   /**
00402    * @class Preserve_Entry
00403    *
00404    * @brief Preserve Entry
00405    *
00406    * Defines a set of characters that designate an area that
00407    * should not be parsed, but should be treated as a complete
00408    * token.  For instance, in: (this is a preserve region), start
00409    * would be a left paren -(- and stop would be a right paren
00410    * -)-.  The strip determines whether the designators should be
00411    * removed from the token.
00412    */
00413   class Preserve_Entry
00414   {
00415   public:
00416     /**
00417      * E.g., "(".
00418      * E.g., ")".
00419      * Whether the designators should be removed from the token.
00420      */
00421     ACE_TCHAR start_;
00422     ACE_TCHAR stop_;
00423     int strip_;
00424   };
00425 
00426   /// The application can specify MAX_PRESERVES preserve designators.
00427   Preserve_Entry preserves_[MAX_PRESERVES];
00428 
00429   /// Pointer to the next free spot in preserves_.
00430   int preserves_index_;
00431 
00432   /**
00433    * @class Delimiter_Entry
00434    *
00435    * @brief Delimiter Entry
00436    *
00437    * Describes a delimiter for the tokenizer.
00438    */
00439   class Delimiter_Entry
00440   {
00441   public:
00442     /**
00443      * Most commonly a space ' '.
00444      * What occurrences of delimiter_ should be replaced with.
00445      * Whether replacement_ should be used.  This should be replaced
00446      * with a technique that sets replacement_ = delimiter by
00447      * default.  I'll do that next iteration.
00448      */
00449     ACE_TCHAR delimiter_;
00450     ACE_TCHAR replacement_;
00451     int replace_;
00452   };
00453 
00454   /// The tokenizer allows MAX_DELIMITERS number of delimiters.
00455   Delimiter_Entry delimiters_[MAX_DELIMITERS];
00456 
00457   /// Pointer to the next free space in delimiters_.
00458   int delimiter_index_;
00459 };
00460 
00461 // ****************************************************************
00462 
00463 /**
00464  * @class ACE_Auto_String_Free
00465  *
00466  * @brief Simple class to automatically de-allocate strings
00467  *
00468  * Keeps a pointer to a string and deallocates it (using
00469  * <ACE_OS::free>) on its destructor.
00470  * If you need to delete using "delete[]" the
00471  * ACE_Auto_Array_Ptr<char> is your choice.
00472  * The class plays the same role as auto_ptr<>
00473  */
00474 class ACE_Export ACE_Auto_String_Free
00475 {
00476 public:
00477   explicit ACE_Auto_String_Free (char* p = 0);
00478   ACE_Auto_String_Free (ACE_Auto_String_Free &rhs);
00479   ACE_Auto_String_Free& operator= (ACE_Auto_String_Free &rhs);
00480   ~ACE_Auto_String_Free (void);
00481 
00482   char* operator* () const;
00483   char operator[] (size_t i) const;
00484   char* get (void) const;
00485   char* release (void);
00486   void reset (char* p = 0);
00487 
00488 private:
00489   char* p_;
00490 };
00491 
00492 ACE_END_VERSIONED_NAMESPACE_DECL
00493 
00494 #if defined (__ACE_INLINE__)
00495 #include "ace/SString.inl"
00496 #endif /* __ACE_INLINE__ */
00497 
00498 #include /**/ "ace/post.h"
00499 #endif /* ACE_SSTRING_H */

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