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 = nullptr);
  63
  64   /// Constructor that copies @a s into dynamically allocated memory.
  65   ACE_NS_WString (const char *s,
  66                   ACE_Allocator *alloc = nullptr);
  67
  68   /// Constructor that copies @a s into dynamically allocated memory.
  69   ACE_NS_WString (const ACE_WSTRING_TYPE *s,
  70                   ACE_Allocator *alloc = nullptr);
  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 = nullptr);
  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 = nullptr);
  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 = nullptr);
  89
  90   /// Copy constructor.
  91   ACE_NS_WString (const ACE_NS_WString &) = default;
  92   ACE_NS_WString &operator= (const ACE_NS_WString&) = default;
  93
  94   /// Constructor that copies @a c into dynamically allocated memory.
  95   ACE_NS_WString (ACE_WSTRING_TYPE c, ACE_Allocator *alloc = nullptr);
  96
  97   /// Transform into a copy of the ASCII character representation.
  98   /// (caller must delete)
  99   char *char_rep () const;
 100
 101   /// Transform into a copy of a USHORT16 representation (caller must
 102   /// delete).  Note, behavior is undefined when sizeof (wchar_t) != 2.
 103   ACE_UINT16 *ushort_rep () const;
 104 };
 105
 106 ACE_Export
 107 ACE_NS_WString operator + (const ACE_NS_WString &,
 108                            const ACE_NS_WString &);
 109
 110 // -----------------------------------------------------------------
 111
 112 /**
 113  * @class ACE_SString
 114  *
 115  * @brief A very Simple String ACE_SString class.  This is not a
 116  * general-purpose string class, and you should probably consider
 117  * using ACE_CString is you don't understand why this class
 118  * exists...
 119  *
 120  * This class is optimized for efficiency, so it doesn't provide
 121  * any internal locking.
 122  * CAUTION: This class is only intended for use with applications
 123  * that understand how it works.  In particular, its destructor
 124  * does not deallocate its memory when it is destroyed...  We need
 125  * this class since the ACE_Map_Manager requires an object that
 126  * supports the operator == and operator !=.  This class uses an
 127  * ACE_Allocator to allocate memory.  The user can make this a
 128  * persistant class by providing an ACE_Allocator with a
 129  * persistable memory pool.
 130  */
 131 class ACE_Export ACE_SString
 132 {
 133 public:
 134   typedef ACE_Allocator::size_type size_type;
 135
 136   /// No position constant
 137   static const size_type npos;
 138
 139   /// Default constructor.
 140   ACE_SString (ACE_Allocator *alloc = nullptr);
 141
 142   /// Constructor that copies @a s into dynamically allocated memory.
 143   ACE_SString (const char *s, ACE_Allocator *alloc = nullptr);
 144
 145   /// Constructor that copies @a len chars of @a s into dynamically
 146   /// allocated memory (will NUL terminate the result).
 147   ACE_SString (const char *s, size_type len, ACE_Allocator *alloc = nullptr);
 148
 149   /// Copy constructor.
 150   ACE_SString (const ACE_SString &);
 151
 152   /// Constructor that copies @a c into dynamically allocated memory.
 153   ACE_SString (char c, ACE_Allocator *alloc = nullptr);
 154
 155   /// Default destructor.
 156   ~ACE_SString ();
 157
 158   /// Return the slot'th character in the string (doesn't perform
 159   /// bounds checking).
 160   char operator [] (size_type slot) const;
 161
 162   /// Return the slot'th character by reference in the string
 163   /// (doesn't perform bounds checking).
 164   char &operator [] (size_type slot);
 165
 166   /// Assignment operator (does copy memory).
 167   ACE_SString &operator = (const ACE_SString &);
 168
 169   /**
 170    * Return a substring given an offset and length, if length == npos
 171    * use rest of str return empty substring if offset or offset/length
 172    * are invalid
 173    */
 174   ACE_SString substring (size_type offset, size_type length = npos) const;
 175
 176   /// Same as substring
 177   ACE_SString substr (size_type offset, size_type length = npos) const;
 178
 179   /// Returns a hash value for this string.
 180   u_long hash () const;
 181
 182   /// Return the length of the string.
 183   size_type length () const;
 184
 185   /// Set the underlying pointer.  Since this does not copy memory or
 186   /// delete existing memory use with extreme caution!!!
 187   void rep (char *s);
 188
 189   /// Get the underlying pointer.
 190   const char *rep () const;
 191
 192   /// Get the underlying pointer.
 193   const char *fast_rep () const;
 194
 195   /// Same as STL String's c_str() and fast_rep().
 196   const char *c_str () const;
 197
 198   /// Comparison operator that will match substrings.  Returns the
 199   /// slot of the first location that matches, else @c npos.
 200   size_type strstr (const ACE_SString &s) const;
 201
 202   /// Find @a str starting at pos.  Returns the slot of the first
 203   /// location that matches (will be >= pos), else npos.
 204   size_type find (const ACE_SString &str, size_type pos = 0) const;
 205
 206   /// Find @a s starting at pos.  Returns the slot of the first
 207   /// location that matches (will be >= pos), else npos.
 208   size_type find (const char *s, size_type pos = 0) const;
 209
 210   /// Find @a c starting at pos.  Returns the slot of the first
 211   /// location that matches (will be >= pos), else npos.
 212   size_type find (char c, size_type pos = 0) const;
 213
 214   /// Find @a c starting at pos (counting from the end).  Returns the
 215   /// slot of the first location that matches, else npos.
 216   size_type rfind (char c, size_type pos = npos) const;
 217
 218   /// Equality comparison operator (must match entire string).
 219   bool operator == (const ACE_SString &s) const;
 220
 221   /// Less than comparison operator.
 222   bool operator < (const ACE_SString &s) const;
 223
 224   /// Greater than comparison operator.
 225   bool operator > (const ACE_SString &s) const;
 226
 227   /// Inequality comparison operator.
 228   bool operator != (const ACE_SString &s) const;
 229
 230   /// Performs a strcmp()-style comparison.
 231   int compare (const ACE_SString &s) const;
 232
 233   /// Dump the state of an object.
 234   void dump () const;
 235
 236   /// Declare the dynamic allocation hooks.
 237   ACE_ALLOC_HOOK_DECLARE;
 238
 239 private:
 240   /// Pointer to a memory allocator.
 241   ACE_Allocator *allocator_;
 242
 243   /// Length of the ACE_SString (not counting the trailing '\\0').
 244   size_type len_;
 245
 246   /// Pointer to data.
 247   char *rep_;
 248 };
 249
 250 #if !defined (ACE_LACKS_IOSTREAM_TOTALLY)
 251 ACE_Export ACE_OSTREAM_TYPE &operator << (ACE_OSTREAM_TYPE &, const ACE_SString &);
 252 #endif /* ! ACE_LACKS_IOSTREAM_TOTALLY */
 253
 254 // This allows one to use W or C String based on the Unicode
 255 // setting
 256 #if defined (ACE_USES_WCHAR)
 257 typedef ACE_WString ACE_TString;
 258 #else /* ACE_USES_WCHAR */
 259 typedef ACE_CString ACE_TString;
 260 #endif /* ACE_USES_WCHAR */
 261
 262 // ****************************************************************
 263
 264 /**
 265  * @class ACE_Auto_String_Free
 266  *
 267  * @brief Simple class to automatically de-allocate strings
 268  *
 269  * Keeps a pointer to a string and deallocates it (using
 270  * <ACE_OS::free>) on its destructor.
 271  * If you need to delete using "delete[]" the
 272  * ACE_Auto_Array_Ptr<char> is your choice.
 273  * The class plays the same role as auto_ptr<>
 274  */
 275 class ACE_Export ACE_Auto_String_Free
 276 {
 277 public:
 278   explicit ACE_Auto_String_Free (char* p = 0);
 279   ACE_Auto_String_Free (ACE_Auto_String_Free &rhs);
 280   ACE_Auto_String_Free& operator= (ACE_Auto_String_Free &rhs);
 281   ~ACE_Auto_String_Free ();
 282
 283   char* operator* () const;
 284   char operator[] (size_t i) const;
 285   char* get () const;
 286   char* release ();
 287   void reset (char* p = 0);
 288
 289 private:
 290   char* p_;
 291 };
 292
 293 ACE_END_VERSIONED_NAMESPACE_DECL
 294
 295 #if defined (__ACE_INLINE__)
 296 #include "ace/SString.inl"
 297 #endif /* __ACE_INLINE__ */
 298
 299 #include /**/ "ace/post.h"
 300 #endif /* ACE_SSTRING_H */