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

SString.h

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

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