ACE/ace/SString.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file    SString.h
   6  *
   7  *  @author Douglas C. Schmidt (d.schmidt@vanderbilt.edu)
   8  */
   9 //=============================================================================
  10
  11 #ifndef ACE_SSTRING_H
  12 #define ACE_SSTRING_H
  13 #include /**/ "ace/pre.h"
  14
  15 #include "ace/SStringfwd.h"
  16
  17 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  18 # pragma once
  19 #endif /* ACE_LACKS_PRAGMA_ONCE */
  20
  21 #include "ace/String_Base.h"
  22
  23 #if !defined (ACE_DEFAULT_GROWSIZE)
  24 #define ACE_DEFAULT_GROWSIZE 32
  25 #endif /* ACE_DEFAULT_GROWSIZE */
  26
  27 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
  28 #include "ace/iosfwd.h"
  29 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  30 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_CString &);
  31 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_WString &);
  32 ACE_END_VERSIONED_NAMESPACE_DECL
  33 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
  34
  35 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  36
  37 #if defined ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT
  38 template class ACE_Export ACE_String_Base<char>;
  39 template class ACE_Export ACE_String_Base<ACE_WSTRING_TYPE>;
  40
  41 template class ACE_Export ACE_String_Base_Iterator<char>;
  42 template class ACE_Export ACE_String_Base_Iterator<ACE_WSTRING_TYPE>;
  43
  44 template class ACE_Export ACE_String_Base_Const_Iterator<char>;
  45 template class ACE_Export ACE_String_Base_Const_Iterator<ACE_WSTRING_TYPE>;
  46 #endif /* ACE_HAS_EXPLICIT_TEMPLATE_INSTANTIATION_EXPORT */
  47
  48 /**
  49  * @class ACE_NS_WString
  50  *
  51  * @brief This class retain the backward compatibility for
  52  *        ACE_Naming_Context and related classes.  The only addition to
  53  *        ACE_WString is a very naive "wchar" to "char" conversion
  54  *        function.
  55  */
  56 class ACE_Export ACE_NS_WString : public ACE_WString
  57 {
  58 public:
  59   using ACE_WString::size_type;
  60
  61   /// Default constructor.
  62   ACE_NS_WString (ACE_Allocator *alloc = 0);
  63
  64   /// Constructor that copies @a s into dynamically allocated memory.
  65   ACE_NS_WString (const char *s,
  66                   ACE_Allocator *alloc = 0);
  67
  68   /// Constructor that copies @a s into dynamically allocated memory.
  69   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
  70                   ACE_Allocator *alloc = 0);
  71
  72 #if defined (ACE_WSTRING_HAS_USHORT_SUPPORT)
  73   /// Constructor that takes in a ushort16 string (mainly used by the
  74   /// ACE Name_Space classes)
  75   ACE_NS_WString (const ACE_UINT16 *s,
  76                   size_type len,
  77                   ACE_Allocator *alloc = 0);
  78 #endif /* ACE_WSTRING_HAS_USHORT_SUPPORT */
  79
  80   /// Constructor that copies @a len ACE_WSTRING_TYPE's of @a s into dynamically
  81   /// allocated memory (will NUL terminate the result).
  82   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
  83                   size_type len,
  84                   ACE_Allocator *alloc = 0);
  85
  86   /// Constructor that dynamically allocates memory for @a len + 1
  87   /// ACE_WSTRING_TYPE characters. The newly created memory is set memset to 0.
  88   ACE_NS_WString (size_type len, ACE_Allocator *alloc = 0);
  89
  90   /// Copy constructor.
  91   ACE_NS_WString (const ACE_NS_WString &s);
  92
  93   /// Constructor that copies @a c into dynamically allocated memory.
  94   ACE_NS_WString (ACE_WSTRING_TYPE c, ACE_Allocator *alloc = 0);
  95
  96   /// Transform into a copy of the ASCII character representation.
  97   /// (caller must delete)
  98   char *char_rep (void) const;
  99
 100   /// Transform into a copy of a USHORT16 representation (caller must
 101   /// delete).  Note, behavior is undefined when sizeof (wchar_t) != 2.
 102   ACE_UINT16 *ushort_rep (void) const;
 103 };
 104
 105 ACE_Export
 106 ACE_NS_WString operator + (const ACE_NS_WString &,
 107                            const ACE_NS_WString &);
 108
 109 // -----------------------------------------------------------------
 110
 111 /**
 112  * @class ACE_SString
 113  *
 114  * @brief A very Simple String ACE_SString class.  This is not a
 115  * general-purpose string class, and you should probably consider
 116  * using ACE_CString is you don't understand why this class
 117  * exists...
 118  *
 119  * This class is optimized for efficiency, so it doesn't provide
 120  * any internal locking.
 121  * CAUTION: This class is only intended for use with applications
 122  * that understand how it works.  In particular, its destructor
 123  * does not deallocate its memory when it is destroyed...  We need
 124  * this class since the ACE_Map_Manager requires an object that
 125  * supports the operator == and operator !=.  This class uses an
 126  * ACE_Allocator to allocate memory.  The user can make this a
 127  * persistant class by providing an ACE_Allocator with a
 128  * persistable memory pool.
 129  */
 130 class ACE_Export ACE_SString
 131 {
 132 public:
 133   typedef ACE_Allocator::size_type size_type;
 134
 135   /// No position constant
 136   static const size_type npos;
 137
 138   /// Default constructor.
 139   ACE_SString (ACE_Allocator *alloc = 0);
 140
 141   /// Constructor that copies @a s into dynamically allocated memory.
 142   ACE_SString (const char *s, ACE_Allocator *alloc = 0);
 143
 144   /// Constructor that copies @a len chars of @a s into dynamically
 145   /// allocated memory (will NUL terminate the result).
 146   ACE_SString (const char *s, size_type len, ACE_Allocator *alloc = 0);
 147
 148   /// Copy constructor.
 149   ACE_SString (const ACE_SString &);
 150
 151   /// Constructor that copies @a c into dynamically allocated memory.
 152   ACE_SString (char c, ACE_Allocator *alloc = 0);
 153
 154   /// Default destructor.
 155   ~ACE_SString (void);
 156
 157   /// Return the slot'th character in the string (doesn't perform
 158   /// bounds checking).
 159   char operator [] (size_type slot) const;
 160
 161   /// Return the slot'th character by reference in the string
 162   /// (doesn't perform bounds checking).
 163   char &operator [] (size_type slot);
 164
 165   /// Assignment operator (does copy memory).
 166   ACE_SString &operator = (const ACE_SString &);
 167
 168   /**
 169    * Return a substring given an offset and length, if length == npos
 170    * use rest of str return empty substring if offset or offset/length
 171    * are invalid
 172    */
 173   ACE_SString substring (size_type offset, size_type length = npos) const;
 174
 175   /// Same as substring
 176   ACE_SString substr (size_type offset, size_type length = npos) const;
 177
 178   /// Returns a hash value for this string.
 179   u_long hash (void) const;
 180
 181   /// Return the length of the string.
 182   size_type length (void) const;
 183
 184   /// Set the underlying pointer.  Since this does not copy memory or
 185   /// delete existing memory use with extreme caution!!!
 186   void rep (char *s);
 187
 188   /// Get the underlying pointer.
 189   const char *rep (void) const;
 190
 191   /// Get the underlying pointer.
 192   const char *fast_rep (void) const;
 193
 194   /// Same as STL String's c_str() and fast_rep().
 195   const char *c_str (void) const;
 196
 197   /// Comparison operator that will match substrings.  Returns the
 198   /// slot of the first location that matches, else @c npos.
 199   size_type strstr (const ACE_SString &s) const;
 200
 201   /// Find @a str starting at pos.  Returns the slot of the first
 202   /// location that matches (will be >= pos), else npos.
 203   size_type find (const ACE_SString &str, size_type pos = 0) const;
 204
 205   /// Find @a s starting at pos.  Returns the slot of the first
 206   /// location that matches (will be >= pos), else npos.
 207   size_type find (const char *s, size_type pos = 0) const;
 208
 209   /// Find @a c starting at pos.  Returns the slot of the first
 210   /// location that matches (will be >= pos), else npos.
 211   size_type find (char c, size_type pos = 0) const;
 212
 213   /// Find @a c starting at pos (counting from the end).  Returns the
 214   /// slot of the first location that matches, else npos.
 215   size_type rfind (char c, size_type pos = npos) const;
 216
 217   /// Equality comparison operator (must match entire string).
 218   bool operator == (const ACE_SString &s) const;
 219
 220   /// Less than comparison operator.
 221   bool operator < (const ACE_SString &s) const;
 222
 223   /// Greater than comparison operator.
 224   bool operator > (const ACE_SString &s) const;
 225
 226   /// Inequality comparison operator.
 227   bool operator != (const ACE_SString &s) const;
 228
 229   /// Performs a strcmp()-style comparison.
 230   int compare (const ACE_SString &s) const;
 231
 232   /// Dump the state of an object.
 233   void dump (void) const;
 234
 235   /// Declare the dynamic allocation hooks.
 236   ACE_ALLOC_HOOK_DECLARE;
 237
 238 private:
 239   /// Pointer to a memory allocator.
 240   ACE_Allocator *allocator_;
 241
 242   /// Length of the ACE_SString (not counting the trailing '\\0').
 243   size_type len_;
 244
 245   /// Pointer to data.
 246   char *rep_;
 247 };
 248
 249 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
 250 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_SString &);
 251 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
 252
 253 // This allows one to use W or C String based on the Unicode
 254 // setting
 255 #if defined (ACE_USES_WCHAR)
 256 typedef ACE_WString ACE_TString;
 257 #else /* ACE_USES_WCHAR */
 258 typedef ACE_CString ACE_TString;
 259 #endif /* ACE_USES_WCHAR */
 260
 261 // ****************************************************************
 262
 263 /**
 264  * @class ACE_Auto_String_Free
 265  *
 266  * @brief Simple class to automatically de-allocate strings
 267  *
 268  * Keeps a pointer to a string and deallocates it (using
 269  * <ACE_OS::free>) on its destructor.
 270  * If you need to delete using "delete[]" the
 271  * ACE_Auto_Array_Ptr<char> is your choice.
 272  * The class plays the same role as auto_ptr<>
 273  */
 274 class ACE_Export ACE_Auto_String_Free
 275 {
 276 public:
 277   explicit ACE_Auto_String_Free (char* p = 0);
 278   ACE_Auto_String_Free (ACE_Auto_String_Free &rhs);
 279   ACE_Auto_String_Free& operator= (ACE_Auto_String_Free &rhs);
 280   ~ACE_Auto_String_Free (void);
 281
 282   char* operator* () const;
 283   char operator[] (size_t i) const;
 284   char* get (void) const;
 285   char* release (void);
 286   void reset (char* p = 0);
 287
 288 private:
 289   char* p_;
 290 };
 291
 292 ACE_END_VERSIONED_NAMESPACE_DECL
 293
 294 #if defined (__ACE_INLINE__)
 295 #include "ace/SString.inl"
 296 #endif /* __ACE_INLINE__ */
 297
 298 #include /**/ "ace/post.h"
 299 #endif /* ACE_SSTRING_H */