dep/ACE_wrappers/ace/SString.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SString.h
   6  *
   7  *  $Id: SString.h 80826 2008-03-04 14:51:23Z wotte $
   8  *
   9  *  @author Douglas C. Schmidt (schmidt@cs.wustl.edu)
  10  */
  11 //=============================================================================
  12
  13 #ifndef ACE_SSTRING_H
  14 #define ACE_SSTRING_H
  15 #include /**/ "ace/pre.h"
  16
  17 #include "ace/SStringfwd.h"
  18
  19 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  20 # pragma once
  21 #endif /* ACE_LACKS_PRAGMA_ONCE */
  22
  23 #include "ace/String_Base.h"
  24
  25 #if !defined (ACE_DEFAULT_GROWSIZE)
  26 #define ACE_DEFAULT_GROWSIZE 32
  27 #endif /* ACE_DEFAULT_GROWSIZE */
  28
  29 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
  30 #include "ace/iosfwd.h"
  31 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  32 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_CString &);
  33 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_WString &);
  34 ACE_END_VERSIONED_NAMESPACE_DECL
  35 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
  36
  37 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  38
  39 #if defined ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT
  40 template class ACE_Export ACE_String_Base<char>;
  41 template class ACE_Export ACE_String_Base<ACE_WSTRING_TYPE>;
  42 #endif /* ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT */
  43
  44 /**
  45  * @class ACE_NS_WString
  46  *
  47  * @brief This class retain the backward compatibility for
  48  *        ACE_Naming_Context and related classes.  The only addition to
  49  *        ACE_WString is a very naive "wchar" to "char" conversion
  50  *        function.
  51  */
  52 class ACE_Export ACE_NS_WString : public ACE_WString
  53 {
  54 public:
  55
  56   using ACE_WString::size_type;
  57
  58   /// Default constructor.
  59   ACE_NS_WString (ACE_Allocator *alloc = 0);
  60
  61   /// Constructor that copies @a s into dynamically allocated memory.
  62   ACE_NS_WString (const char *s,
  63                   ACE_Allocator *alloc = 0);
  64
  65   /// Constructor that copies @a s into dynamically allocated memory.
  66   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
  67                   ACE_Allocator *alloc = 0);
  68
  69 #if defined (ACE_WSTRING_HAS_USHORT_SUPPORT)
  70   /// Constructor that takes in a ushort16 string (mainly used by the
  71   /// ACE Name_Space classes)
  72   ACE_NS_WString (const ACE_USHORT16 *s,
  73                   size_type len,
  74                   ACE_Allocator *alloc = 0);
  75 #endif /* ACE_WSTRING_HAS_USHORT_SUPPORT */
  76
  77   /// Constructor that copies @a len ACE_WSTRING_TYPE's of @a s into dynamically
  78   /// allocated memory (will NUL terminate the result).
  79   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
  80                   size_type len,
  81                   ACE_Allocator *alloc = 0);
  82
  83   /// Constructor that dynamically allocates memory for @a len + 1
  84   /// ACE_WSTRING_TYPE characters. The newly created memory is set memset to 0.
  85   ACE_NS_WString (size_type len, ACE_Allocator *alloc = 0);
  86
  87   /// Copy constructor.
  88   ACE_NS_WString (const ACE_NS_WString &s);
  89
  90   /// Constructor that copies @a c into dynamically allocated memory.
  91   ACE_NS_WString (ACE_WSTRING_TYPE c, ACE_Allocator *alloc = 0);
  92
  93   /// Transform into a copy of the ASCII character representation.
  94   /// (caller must delete)
  95   char *char_rep (void) const;
  96
  97   /// Transform into a copy of a USHORT16 representation (caller must
  98   /// delete).  Note, behavior is undefined when sizeof (wchar_t) != 2.
  99   ACE_USHORT16 *ushort_rep (void) const;
 100 };
 101
 102 ACE_Export
 103 ACE_NS_WString operator + (const ACE_NS_WString &,
 104                            const ACE_NS_WString &);
 105
 106 // -----------------------------------------------------------------
 107
 108 /**
 109  * @class ACE_SString
 110  *
 111  * @brief A very Simple String ACE_SString class.  This is not a
 112  * general-purpose string class, and you should probably consider
 113  * using ACE_CString is you don't understand why this class
 114  * exists...
 115  *
 116  * This class is optimized for efficiency, so it doesn't provide
 117  * any internal locking.
 118  * CAUTION: This class is only intended for use with applications
 119  * that understand how it works.  In particular, its destructor
 120  * does not deallocate its memory when it is destroyed...  We need
 121  * this class since the ACE_Map_Manager requires an object that
 122  * supports the operator == and operator !=.  This class uses an
 123  * ACE_Allocator to allocate memory.  The user can make this a
 124  * persistant class by providing an ACE_Allocator with a
 125  * persistable memory pool.
 126  */
 127 class ACE_Export ACE_SString
 128 {
 129 public:
 130
 131   typedef ACE_Allocator::size_type size_type;
 132
 133   /// No position constant
 134   static const size_type npos;
 135
 136   /// Default constructor.
 137   ACE_SString (ACE_Allocator *alloc = 0);
 138
 139   /// Constructor that copies @a s into dynamically allocated memory.
 140   ACE_SString (const char *s, ACE_Allocator *alloc = 0);
 141
 142   /// Constructor that copies @a len chars of  @s  into dynamically
 143   /// allocated memory (will NUL terminate the result).
 144   ACE_SString (const char *s, size_type len, ACE_Allocator *alloc = 0);
 145
 146   /// Copy constructor.
 147   ACE_SString (const ACE_SString &);
 148
 149   /// Constructor that copies @a c into dynamically allocated memory.
 150   ACE_SString (char c, ACE_Allocator *alloc = 0);
 151
 152   /// Default destructor.
 153   ~ACE_SString (void);
 154
 155   /// Return the <slot'th> character in the string (doesn't perform
 156   /// bounds checking).
 157   char operator [] (size_type slot) const;
 158
 159   /// Return the <slot'th> character by reference in the string
 160   /// (doesn't perform bounds checking).
 161   char &operator [] (size_type slot);
 162
 163   /// Assignment operator (does copy memory).
 164   ACE_SString &operator = (const ACE_SString &);
 165
 166   /**
 167    * Return a substring given an offset and length, if length == npos
 168    * use rest of str return empty substring if offset or offset/length
 169    * are invalid
 170    */
 171   ACE_SString substring (size_type offset, size_type length = npos) const;
 172
 173   /// Same as substring
 174   ACE_SString substr (size_type offset, size_type length = npos) const;
 175
 176   /// Returns a hash value for this string.
 177   u_long hash (void) const;
 178
 179   /// Return the length of the string.
 180   size_type length (void) const;
 181
 182   /// Set the underlying pointer.  Since this does not copy memory or
 183   /// delete existing memory use with extreme caution!!!
 184   void rep (char *s);
 185
 186   /// Get the underlying pointer.
 187   const char *rep (void) const;
 188
 189   /// Get the underlying pointer.
 190   const char *fast_rep (void) const;
 191
 192   /// Same as STL String's <c_str> and <fast_rep>.
 193   const char *c_str (void) const;
 194
 195   /// Comparison operator that will match substrings.  Returns the
 196   /// slot of the first location that matches, else @c npos.
 197   size_type strstr (const ACE_SString &s) const;
 198
 199   /// Find <str> starting at pos.  Returns the slot of the first
 200   /// location that matches (will be >= pos), else npos.
 201   size_type find (const ACE_SString &str, size_type pos = 0) const;
 202
 203   /// Find <s> starting at pos.  Returns the slot of the first
 204   /// location that matches (will be >= pos), else npos.
 205   size_type find (const char *s, size_type pos = 0) const;
 206
 207   /// Find <c> starting at pos.  Returns the slot of the first
 208   /// location that matches (will be >= pos), else npos.
 209   size_type find (char c, size_type pos = 0) const;
 210
 211   /// Find <c> starting at pos (counting from the end).  Returns the
 212   /// slot of the first location that matches, else npos.
 213   size_type rfind (char c, size_type pos = npos) const;
 214
 215   /// Equality comparison operator (must match entire string).
 216   bool operator == (const ACE_SString &s) const;
 217
 218   /// Less than comparison operator.
 219   bool operator < (const ACE_SString &s) const;
 220
 221   /// Greater than comparison operator.
 222   bool operator > (const ACE_SString &s) const;
 223
 224   /// Inequality comparison operator.
 225   bool operator != (const ACE_SString &s) const;
 226
 227   /// Performs a <strcmp>-style comparison.
 228   int compare (const ACE_SString &s) const;
 229
 230   /// Dump the state of an object.
 231   void dump (void) const;
 232
 233   /// Declare the dynamic allocation hooks.
 234   ACE_ALLOC_HOOK_DECLARE;
 235
 236 private:
 237   /// Pointer to a memory allocator.
 238   ACE_Allocator *allocator_;
 239
 240   /// Length of the ACE_SString (not counting the trailing '\0').
 241   size_type len_;
 242
 243   /// Pointer to data.
 244   char *rep_;
 245 };
 246
 247 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
 248 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_SString &);
 249 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
 250
 251 // This allows one to use W or C String based on the Unicode
 252 // setting
 253 #if defined (ACE_USES_WCHAR)
 254 typedef ACE_WString ACE_TString;
 255 #else /* ACE_USES_WCHAR */
 256 typedef ACE_CString ACE_TString;
 257 #endif /* ACE_USES_WCHAR */
 258
 259
 260 // ************************************************************
 261
 262 /**
 263  * @class ACE_Tokenizer
 264  *
 265  * @brief Tokenizer
 266  *
 267  * Tokenizes a buffer.  Allows application to set delimiters and
 268  * preserve designators.  Does not allow special characters, yet
 269  * (e.g., printf ("\"like a quoted string\"")).
 270  */
 271 class ACE_Export ACE_Tokenizer
 272 {
 273 public:
 274   /**
 275    * \a buffer will be parsed.  Notice that ACE_Tokenizer will modify
 276    * \a buffer if you use <code> delimiter_replace </code> or <code>
 277    * preserve_designators </code> to do character substitution.
 278    * @note You should NOT pass a constant string or string literal
 279    * to this constructor, since ACE_Tokenizer will try to modify
 280    * the string.
 281    * \sa preserve_designators
 282    * \sa preserve_designators
 283    */
 284   ACE_Tokenizer (ACE_TCHAR *buffer);
 285
 286   /**
 287    * \a d is a delimiter.
 288    * \return Returns 0 on success, -1 if there is no memory left.
 289    *
 290    * <B>Example:</B>
 291    * \verbatim
 292      char buf[30];
 293      ACE_OS::strcpy(buf, "William/Joseph/Hagins");
 294
 295      ACE_Tokenizer tok (buf);
 296      tok.delimiter ('/');
 297      for (char *p = tok.next (); p; p = tok.next ())
 298       cout << p << endl;
 299     \endverbatim
 300    *
 301    * This will print out:
 302    * \verbatim
 303      William/Joseph/Hagins
 304       Joseph/Hagins
 305       Hagins \endverbatim
 306    */
 307   int delimiter (ACE_TCHAR d);
 308
 309   /**
 310    * \a d is a delimiter and, when found, will be replaced by
 311    * \a replacement.
 312    * \return 0 on success, -1 if there is no memory left.
 313    *
 314    * <B>Example:</B>
 315    * \verbatim
 316      char buf[30];
 317      ACE_OS::strcpy(buf, "William/Joseph/Hagins");
 318
 319      ACE_Tokenizer tok (buf);
 320      tok.delimiter_replace ('/', 0);
 321      for (char *p = tok.next (); p; p = tok.next ())
 322        cout << p << endl;
 323     \endverbatim
 324    *
 325    * This will print out:
 326    * \verbatim
 327        William
 328        Joseph
 329        Hagins \endverbatim
 330  */
 331   int delimiter_replace (ACE_TCHAR d, ACE_TCHAR replacement);
 332
 333   /**
 334    * Extract string between a pair of designator characters.
 335    * For instance, quotes, or '(' and ')'.
 336    * \a start specifies the begin designator.
 337    * \a stop specifies the end designator.
 338    * \a strip If \a strip == 1, then the preserve
 339    * designators will be stripped from the tokens returned by next.
 340    * \return 0 on success, -1 if there is no memory left.
 341    *
 342    * <B>Example with strip = 0:</B>
 343    * \verbatim
 344      char buf[30];
 345      ACE_OS::strcpy(buf, "William(Joseph)Hagins");
 346
 347      ACE_Tokenizer tok (buf);
 348      tok.preserve_designators ('(', ')', 0);
 349      for (char *p = tok.next (); p; p = tok.next ())
 350        cout << p << endl;
 351     \endverbatim
 352    *
 353    * This will print out:
 354    * \verbatim
 355       William(Joseph)Hagins
 356       (Joseph)Hagins
 357       )Hagins \endverbatim
 358    *
 359    * <B>Example with strip = 1:</B>
 360    * \verbatim
 361      char buf[30];
 362      ACE_OS::strcpy(buf, "William(Joseph)Hagins");
 363
 364      ACE_Tokenizer tok (buf);
 365      tok.preserve_designators ('(', ')', 1);
 366      for (char *p = tok.next (); p; p = tok.next ())
 367        cout << p << endl;
 368     \endverbatim
 369    *
 370    * This will print out:
 371    * \verbatim
 372       William
 373       Joseph
 374       Hagins \endverbatim
 375    */
 376   int preserve_designators (ACE_TCHAR start, ACE_TCHAR stop, int strip=1);
 377
 378   /// Returns the next token.
 379   ACE_TCHAR *next (void);
 380
 381   enum {
 382     MAX_DELIMITERS=16,
 383     MAX_PRESERVES=16
 384   };
 385
 386 protected:
 387   /// Returns 1 if <d> is a delimiter, 0 otherwise.  If <d> should be
 388   /// replaced with @a r, <replace> is set to 1, otherwise 0.
 389   int is_delimiter (ACE_TCHAR d, int &replace, ACE_TCHAR &r);
 390
 391   /**
 392    * If <start> is a start preserve designator, returns 1 and sets
 393    * <stop> to the stop designator.  Returns 0 if <start> is not a
 394    * preserve designator.
 395    */
 396   int is_preserve_designator (ACE_TCHAR start, ACE_TCHAR &stop, int &strip);
 397
 398   ACE_TCHAR *buffer_;
 399   int index_;
 400
 401   /**
 402    * @class Preserve_Entry
 403    *
 404    * @brief Preserve Entry
 405    *
 406    * Defines a set of characters that designate an area that
 407    * should not be parsed, but should be treated as a complete
 408    * token.  For instance, in: (this is a preserve region), start
 409    * would be a left paren -(- and stop would be a right paren
 410    * -)-.  The strip determines whether the designators should be
 411    * removed from the token.
 412    */
 413   class Preserve_Entry
 414   {
 415   public:
 416     /**
 417      * E.g., "(".
 418      * E.g., ")".
 419      * Whether the designators should be removed from the token.
 420      */
 421     ACE_TCHAR start_;
 422     ACE_TCHAR stop_;
 423     int strip_;
 424   };
 425
 426   /// The application can specify MAX_PRESERVES preserve designators.
 427   Preserve_Entry preserves_[MAX_PRESERVES];
 428
 429   /// Pointer to the next free spot in preserves_.
 430   int preserves_index_;
 431
 432   /**
 433    * @class Delimiter_Entry
 434    *
 435    * @brief Delimiter Entry
 436    *
 437    * Describes a delimiter for the tokenizer.
 438    */
 439   class Delimiter_Entry
 440   {
 441   public:
 442     /**
 443      * Most commonly a space ' '.
 444      * What occurrences of delimiter_ should be replaced with.
 445      * Whether replacement_ should be used.  This should be replaced
 446      * with a technique that sets replacement_ = delimiter by
 447      * default.  I'll do that next iteration.
 448      */
 449     ACE_TCHAR delimiter_;
 450     ACE_TCHAR replacement_;
 451     int replace_;
 452   };
 453
 454   /// The tokenizer allows MAX_DELIMITERS number of delimiters.
 455   Delimiter_Entry delimiters_[MAX_DELIMITERS];
 456
 457   /// Pointer to the next free space in delimiters_.
 458   int delimiter_index_;
 459 };
 460
 461 // ****************************************************************
 462
 463 /**
 464  * @class ACE_Auto_String_Free
 465  *
 466  * @brief Simple class to automatically de-allocate strings
 467  *
 468  * Keeps a pointer to a string and deallocates it (using
 469  * <ACE_OS::free>) on its destructor.
 470  * If you need to delete using "delete[]" the
 471  * ACE_Auto_Array_Ptr<char> is your choice.
 472  * The class plays the same role as auto_ptr<>
 473  */
 474 class ACE_Export ACE_Auto_String_Free
 475 {
 476 public:
 477   explicit ACE_Auto_String_Free (char* p = 0);
 478   ACE_Auto_String_Free (ACE_Auto_String_Free &rhs);
 479   ACE_Auto_String_Free& operator= (ACE_Auto_String_Free &rhs);
 480   ~ACE_Auto_String_Free (void);
 481
 482   char* operator* () const;
 483   char operator[] (size_t i) const;
 484   char* get (void) const;
 485   char* release (void);
 486   void reset (char* p = 0);
 487
 488 private:
 489   char* p_;
 490 };
 491
 492 ACE_END_VERSIONED_NAMESPACE_DECL
 493
 494 #if defined (__ACE_INLINE__)
 495 #include "ace/SString.inl"
 496 #endif /* __ACE_INLINE__ */
 497
 498 #include /**/ "ace/post.h"
 499 #endif /* ACE_SSTRING_H */