ACE/ace/OS_NS_string.h

   1 // -*- C++ -*-
   2
   3 //=============================================================================
   4 /**
   5  *  @file   OS_NS_string.h
   6  *
   7  *  @author Douglas C. Schmidt <d.schmidt@vanderbilt.edu>
   8  *  @author Jesper S. M|ller<stophph@diku.dk>
   9  *  @author and a cast of thousands...
  10  */
  11 //=============================================================================
  12
  13 #ifndef ACE_OS_NS_STRING_H
  14 #define ACE_OS_NS_STRING_H
  15
  16 # include /**/ "ace/pre.h"
  17
  18 # include "ace/config-lite.h"
  19
  20 # if !defined (ACE_LACKS_PRAGMA_ONCE)
  21 #  pragma once
  22 # endif /* ACE_LACKS_PRAGMA_ONCE */
  23
  24 #include "ace/Basic_Types.h" // to get ACE_WCHAR_T,
  25                             // should be in os_stddef.h or not used like this.
  26 #include /**/ "ace/ACE_export.h"
  27
  28 #if defined (ACE_EXPORT_MACRO)
  29 #  undef ACE_EXPORT_MACRO
  30 #endif
  31 #define ACE_EXPORT_MACRO ACE_Export
  32
  33 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  34
  35 namespace ACE_OS {
  36   /** @name Functions from <cstring>
  37    *
  38    *  Included are the functions defined in <cstring> and their <cwchar>
  39    *  equivalents.
  40    *
  41    *  @todo To be complete, we should add strcoll, and strxfrm.
  42    */
  43   //@{
  44   /// Finds characters in a buffer (const void version).
  45   ACE_NAMESPACE_INLINE_FUNCTION
  46   const void *memchr (const void *s, int c, size_t len);
  47
  48   /// Finds characters in a buffer (void version).
  49   ACE_NAMESPACE_INLINE_FUNCTION
  50   void *memchr (void *s, int c, size_t len);
  51
  52   /// Compares two buffers.
  53   ACE_NAMESPACE_INLINE_FUNCTION
  54   int memcmp (const void *t, const void *s, size_t len);
  55
  56   /// Copies one buffer to another.
  57   ACE_NAMESPACE_INLINE_FUNCTION
  58   void *memcpy (void *t, const void *s, size_t len);
  59
  60   /// Moves one buffer to another.
  61   ACE_NAMESPACE_INLINE_FUNCTION
  62   void *memmove (void *t, const void *s, size_t len);
  63
  64   /// Fills a buffer with a character value.
  65   ACE_NAMESPACE_INLINE_FUNCTION
  66   void *memset (void *s, int c, size_t len);
  67
  68   /// Appends a string to another string (char version).
  69   ACE_NAMESPACE_INLINE_FUNCTION
  70   char *strcat (char *s, const char *t);
  71
  72 #if defined (ACE_HAS_WCHAR)
  73   /// Appends a string to another string (wchar_t version).
  74   ACE_NAMESPACE_INLINE_FUNCTION
  75   wchar_t *strcat (wchar_t *s, const wchar_t *t);
  76 #endif /* ACE_HAS_WCHAR */
  77
  78   /// Finds the first occurrence of a character in a string (const char
  79   /// version).
  80   ACE_NAMESPACE_INLINE_FUNCTION
  81   const char *strchr (const char *s, int c);
  82
  83 #if defined (ACE_HAS_WCHAR)
  84   /// Finds the first occurrence of a character in a string (const wchar_t
  85   /// version).
  86   ACE_NAMESPACE_INLINE_FUNCTION
  87   const wchar_t *strchr (const wchar_t *s, wchar_t c);
  88 #endif /* ACE_HAS_WCHAR */
  89
  90   /// Finds the first occurrence of a character in a string (char version).
  91   ACE_NAMESPACE_INLINE_FUNCTION
  92   char *strchr (char *s, int c);
  93
  94 #if defined (ACE_HAS_WCHAR)
  95   /// Finds the first occurrence of a character in a string (wchar_t version).
  96   ACE_NAMESPACE_INLINE_FUNCTION
  97   wchar_t *strchr (wchar_t *s, wchar_t c);
  98 #endif /* ACE_HAS_WCHAR */
  99
 100   /// Compares two strings (char version).
 101   ACE_NAMESPACE_INLINE_FUNCTION
 102   int strcmp (const char *s, const char *t);
 103
 104   /// Compares two strings (wchar_t version).
 105   ACE_NAMESPACE_INLINE_FUNCTION
 106   int strcmp (const ACE_WCHAR_T *s, const ACE_WCHAR_T *t);
 107
 108   /// Copies a string (char version).
 109   ACE_NAMESPACE_INLINE_FUNCTION
 110   char *strcpy (char *s, const char *t);
 111
 112 #if defined (ACE_HAS_WCHAR)
 113   /// Copies a string (wchar_t version).
 114   ACE_NAMESPACE_INLINE_FUNCTION
 115   wchar_t *strcpy (wchar_t *s, const wchar_t *t);
 116 #endif /* ACE_HAS_WCHAR */
 117
 118   /// Searches for the first substring without any of the specified
 119   /// characters and returns the size of the substring (char version).
 120   ACE_NAMESPACE_INLINE_FUNCTION
 121   size_t strcspn (const char *s, const char *reject);
 122
 123 #if defined (ACE_HAS_WCHAR)
 124   /// Searches for the first substring without any of the specified
 125   /// characters and returns the size of the substring (wchar_t version).
 126   ACE_NAMESPACE_INLINE_FUNCTION
 127   size_t strcspn (const wchar_t *s, const wchar_t *reject);
 128 #endif /* ACE_HAS_WCHAR */
 129
 130   /// Returns a malloced duplicated string (char version).
 131   ACE_NAMESPACE_INLINE_FUNCTION
 132   char *strdup (const char *s);
 133
 134 #if (defined (ACE_LACKS_STRDUP) && !defined(ACE_STRDUP_EQUIVALENT)) \
 135   || defined (ACE_HAS_STRDUP_EMULATION)
 136   extern ACE_Export
 137   char *strdup_emulation (const char *s);
 138 #endif
 139
 140 #if defined (ACE_HAS_WCHAR)
 141   /// Returns a malloced duplicated string (wchar_t version).
 142   ACE_NAMESPACE_INLINE_FUNCTION
 143   wchar_t *strdup (const wchar_t *s);
 144
 145 #if (defined (ACE_LACKS_WCSDUP) && !defined(ACE_WCSDUP_EQUIVALENT)) \
 146   || defined (ACE_HAS_WCSDUP_EMULATION)
 147   extern ACE_Export
 148   wchar_t *strdup_emulation (const wchar_t *s);
 149 #endif
 150 #endif /* ACE_HAS_WCHAR */
 151
 152   /// Copies a string, but returns a pointer to the end of the
 153   /// copied region (char version).
 154   extern ACE_Export
 155   char *strecpy (char *des, const char *src);
 156
 157 #if defined (ACE_HAS_WCHAR)
 158   /// Copies a string, but returns a pointer to the end of the
 159   /// copied region (wchar_t version).
 160   extern ACE_Export
 161   wchar_t *strecpy (wchar_t *s, const wchar_t *t);
 162 #endif /* ACE_HAS_WCHAR */
 163
 164   /// Returns a system error message. If the supplied errnum is out of range,
 165   /// a string of the form "Unknown error %d" is used to format the string
 166   /// whose pointer is returned and errno is set to EINVAL.
 167   extern ACE_Export
 168   char *strerror (int errnum);
 169
 170 #if defined (ACE_LACKS_STRERROR)
 171   /// Emulated strerror - Returns a system error message.
 172   extern ACE_Export
 173   char *strerror_emulation (int errnum);
 174 #endif /* ACE_LACKS_STRERROR */
 175
 176
 177   /// Returns a string describing the signal number passed in the
 178   /// argument @a signum. If the supplied signal number is out of range,
 179   /// a string of the form "Unknown signal %d" is used to format the string
 180   /// whose pointer is returned.
 181   extern ACE_Export
 182   char *strsignal (int signum);
 183
 184   extern ACE_Export
 185   char *strerror_r (int errnum, char *buf, size_t buflen);
 186
 187   /// Finds the length of a string (char version).
 188   ACE_NAMESPACE_INLINE_FUNCTION
 189   size_t strlen (const char *s);
 190
 191   /// Finds the length of a string (ACE_WCHAR_T version).
 192   ACE_NAMESPACE_INLINE_FUNCTION
 193   size_t strlen (const ACE_WCHAR_T *s);
 194
 195   /// Appends part of a string to another string (char version).
 196   ACE_NAMESPACE_INLINE_FUNCTION
 197   char *strncat (char *s, const char *t, size_t len);
 198
 199   /// Appends part of a string to another string (wchar_t version).
 200   ACE_NAMESPACE_INLINE_FUNCTION
 201   ACE_WCHAR_T *strncat (ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
 202
 203   /// Finds the first occurrence of a character in an array (const char
 204   /// version).
 205   extern ACE_Export
 206   const char *strnchr (const char *s, int c, size_t len);
 207
 208   /// Finds the first occurrence of a character in an array (const ACE_WCHAR_T
 209   /// version).
 210   extern ACE_Export
 211   const ACE_WCHAR_T *strnchr (const ACE_WCHAR_T *s, ACE_WCHAR_T c, size_t len);
 212
 213   /// Finds the first occurrence of a character in an array (char version).
 214   ACE_NAMESPACE_INLINE_FUNCTION
 215   char *strnchr (char *s, int c, size_t len);
 216
 217   /// Finds the first occurrence of a character in an array (ACE_WCHAR_T version).
 218   ACE_NAMESPACE_INLINE_FUNCTION
 219   ACE_WCHAR_T *strnchr (ACE_WCHAR_T *s, ACE_WCHAR_T c, size_t len);
 220
 221   /// Compares two arrays (char version).
 222   ACE_NAMESPACE_INLINE_FUNCTION
 223   int strncmp (const char *s, const char *t, size_t len);
 224
 225   /// Compares two arrays (wchar_t version).
 226   ACE_NAMESPACE_INLINE_FUNCTION
 227   int strncmp (const ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
 228
 229   /// Copies an array (char version)
 230   ACE_NAMESPACE_INLINE_FUNCTION
 231   char *strncpy (char *s, const char *t, size_t len);
 232
 233   /// Copies an array (ACE_WCHAR_T version)
 234   ACE_NAMESPACE_INLINE_FUNCTION
 235   ACE_WCHAR_T *strncpy (ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
 236
 237   /// Finds the length of a limited-length string (char version).
 238   /**
 239    * @param s       The character string to find the length of.
 240    * @param maxlen  The maximum number of characters that will be
 241    *                scanned for the terminating nul character.
 242    *
 243    * @return The length of @arg s, if the terminating nul character
 244    *         is located, else @arg maxlen.
 245    */
 246   ACE_NAMESPACE_INLINE_FUNCTION
 247   size_t strnlen (const char *s, size_t maxlen);
 248
 249   /// Finds the length of a limited-length string (ACE_WCHAR_T version).
 250   /**
 251    * @param s       The character string to find the length of.
 252    * @param maxlen  The maximum number of characters that will be
 253    *                scanned for the terminating nul character.
 254    *
 255    * @return The length of @arg s, if the terminating nul character
 256    *         is located, else @arg maxlen.
 257    */
 258   ACE_NAMESPACE_INLINE_FUNCTION
 259   size_t strnlen (const ACE_WCHAR_T *s, size_t maxlen);
 260
 261   /// Finds the first occurrence of a substring in an array (const char
 262   /// version).
 263   extern ACE_Export
 264   const char *strnstr (const char *s, const char *t, size_t len);
 265
 266   /// Finds the first occurrence of a substring in an array (const wchar_t
 267   /// version).
 268   extern ACE_Export
 269   const ACE_WCHAR_T *strnstr (const ACE_WCHAR_T *s,
 270                               const ACE_WCHAR_T *t,
 271                               size_t len);
 272
 273   /// Finds the first occurrence of a substring in an array (char version).
 274   ACE_NAMESPACE_INLINE_FUNCTION
 275   char *strnstr (char *s, const char *t, size_t len);
 276
 277   /// Finds the first occurrence of a substring in an array (wchar_t version).
 278   ACE_NAMESPACE_INLINE_FUNCTION
 279   ACE_WCHAR_T *strnstr (ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
 280
 281   /// Searches for characters in a string (const char version).
 282   ACE_NAMESPACE_INLINE_FUNCTION
 283   const char *strpbrk (const char *s1, const char *s2);
 284
 285 #if defined (ACE_HAS_WCHAR)
 286   /// Searches for characters in a string (const wchar_t version).
 287   ACE_NAMESPACE_INLINE_FUNCTION
 288   const wchar_t *strpbrk (const wchar_t *s1, const wchar_t *s2);
 289 #endif /* ACE_HAS_WCHAR */
 290
 291   /// Searches for characters in a string (char version).
 292   ACE_NAMESPACE_INLINE_FUNCTION
 293   char *strpbrk (char *s1, const char *s2);
 294
 295 #if defined (ACE_HAS_WCHAR)
 296   /// Searches for characters in a string (wchar_t version).
 297   ACE_NAMESPACE_INLINE_FUNCTION
 298   wchar_t *strpbrk (wchar_t *s1, const wchar_t *s2);
 299 #endif /* ACE_HAS_WCHAR */
 300
 301   /// Finds the last occurrence of a character in a string (const char
 302   /// version).
 303   ACE_NAMESPACE_INLINE_FUNCTION
 304   const char *strrchr (const char *s, int c);
 305
 306 #if defined (ACE_HAS_WCHAR)
 307   /// Finds the last occurrence of a character in a string (const wchar_t
 308   /// version).
 309   ACE_NAMESPACE_INLINE_FUNCTION
 310   const wchar_t *strrchr (const wchar_t *s, wchar_t c);
 311 #endif /* ACE_HAS_WCHAR */
 312
 313   /// Finds the last occurrence of a character in a string (char version).
 314   ACE_NAMESPACE_INLINE_FUNCTION
 315   char *strrchr (char *s, int c);
 316
 317 #if defined (ACE_HAS_WCHAR)
 318   /// Finds the last occurrence of a character in a string (wchar_t version).
 319   ACE_NAMESPACE_INLINE_FUNCTION
 320   wchar_t *strrchr (wchar_t *s, wchar_t c);
 321 #endif /* ACE_HAS_WCHAR */
 322
 323   /// This is a "safe" c string copy function (char version).
 324   /**
 325    * Unlike strncpy() this function will always add a terminating '\0'
 326    * char if maxlen > 0.  So the user doesn't has to provide an extra
 327    * '\0' if the user wants a '\0' terminated dst.  The function
 328    * doesn't check for a 0 @a dst, because this will give problems
 329    * anyway.  When @a src is 0 an empty string is made.  We do not
 330    * "touch" * @a dst if maxlen is 0.  Returns @a dst.  Care should be
 331    * taken when replacing strncpy() calls, because in some cases a
 332    * strncpy() user is using the "not '\0' terminating" feature from
 333    * strncpy().  This happens most when the call to strncpy() was
 334    * optimized by using a maxlen which is 1 smaller than the size
 335    * because there's always written a '\0' inside this last position.
 336    * Very seldom it's possible that the '\0' padding feature from
 337    * strncpy() is needed.
 338    */
 339   extern ACE_Export
 340   char *strsncpy (char *dst,
 341                   const char *src,
 342                   size_t maxlen);
 343
 344   /// This is a "safe" c string copy function (wchar_t version).
 345   /**
 346    * Unlike strncpy() this function will always add a terminating '\0'
 347    * char if maxlen > 0.  So the user doesn't has to provide an extra
 348    * '\0' if the user wants a '\0' terminated dst.  The function
 349    * doesn't check for a 0 @a dst, because this will give problems
 350    * anyway.  When @a src is 0 an empty string is made.  We do not
 351    * "touch" * @a dst if maxlen is 0.  Returns @a dst.  Care should be
 352    * taken when replacing strncpy() calls, because in some cases a
 353    * strncpy() user is using the "not '\0' terminating" feature from
 354    * strncpy().  This happens most when the call to strncpy() was
 355    * optimized by using a maxlen which is 1 smaller than the size
 356    * because there's always written a '\0' inside this last position.
 357    * Very seldom it's possible that the '\0' padding feature from
 358    * strncpy() is needed.
 359    */
 360   extern ACE_Export
 361   ACE_WCHAR_T *strsncpy (ACE_WCHAR_T *dst,
 362                          const ACE_WCHAR_T *src,
 363                          size_t maxlen);
 364
 365   /// Searches for the first substring containing only the specified
 366   /// characters and returns the size of the substring (char version).
 367   ACE_NAMESPACE_INLINE_FUNCTION
 368   size_t strspn (const char *s1, const char *s2);
 369
 370 #if defined (ACE_HAS_WCHAR)
 371   /// Searches for the first substring containing only the specified
 372   /// characters and returns the size of the substring (wchar_t version).
 373   ACE_NAMESPACE_INLINE_FUNCTION
 374   size_t strspn (const wchar_t *s1, const wchar_t *s2);
 375 #endif /* ACE_HAS_WCHAR */
 376
 377   /// Finds the first occurrence of a substring in a string (const char
 378   /// version).
 379   ACE_NAMESPACE_INLINE_FUNCTION
 380   const char *strstr (const char *s, const char *t);
 381
 382 #if defined (ACE_HAS_WCHAR)
 383   /// Finds the first occurrence of a substring in a string (const wchar_t
 384   /// version).
 385   ACE_NAMESPACE_INLINE_FUNCTION
 386   const wchar_t *strstr (const wchar_t *s, const wchar_t *t);
 387 #endif /* ACE_HAS_WCHAR */
 388
 389   /// Finds the first occurrence of a substring in a string (char version).
 390   ACE_NAMESPACE_INLINE_FUNCTION
 391   char *strstr (char *s, const char *t);
 392
 393 #if defined (ACE_HAS_WCHAR)
 394   /// Finds the first occurrence of a substring in a string (wchar_t version).
 395   ACE_NAMESPACE_INLINE_FUNCTION
 396   wchar_t *strstr (wchar_t *s, const wchar_t *t);
 397 #endif /* ACE_HAS_WCHAR */
 398
 399   /// Finds the next token in a string (char version).
 400   ACE_NAMESPACE_INLINE_FUNCTION
 401   char *strtok (char *s, const char *tokens);
 402
 403 #if defined (ACE_HAS_WCHAR) && !defined (ACE_LACKS_WCSTOK)
 404   /// Finds the next token in a string (wchar_t version).
 405   ACE_NAMESPACE_INLINE_FUNCTION
 406   wchar_t *strtok (wchar_t *s, const wchar_t *tokens);
 407 #endif /* ACE_HAS_WCHAR && !ACE_LACKS_WCSTOK */
 408   //@}
 409
 410   /// Finds the next token in a string (safe char version).
 411   ACE_NAMESPACE_INLINE_FUNCTION
 412   char *strtok_r (char *s, const char *tokens, char **lasts);
 413
 414 #if defined (ACE_HAS_WCHAR)
 415   /// Finds the next token in a string (wchar_t version).
 416   ACE_NAMESPACE_INLINE_FUNCTION
 417   wchar_t *strtok_r (ACE_WCHAR_T *s, const ACE_WCHAR_T *tokens, ACE_WCHAR_T **lasts);
 418 #endif  // ACE_HAS_WCHAR
 419
 420 #if defined (ACE_LACKS_STRTOK_R)
 421   /// Emulated strtok_r.
 422   extern ACE_Export
 423   char *strtok_r_emulation (char *s, const char *tokens, char **lasts);
 424 #endif /* ACE_LACKS_STRTOK_R */
 425
 426 # if defined (ACE_HAS_WCHAR) && defined(ACE_LACKS_WCSTOK)
 427   /// Emulated strtok_r (wchar_t version).
 428   extern ACE_Export
 429   wchar_t *strtok_r_emulation (ACE_WCHAR_T *s, const ACE_WCHAR_T *tokens, ACE_WCHAR_T **lasts);
 430 # endif  // ACE_HAS_WCHAR && ACE_LACKS_WCSTOK
 431
 432 } /* namespace ACE_OS */
 433
 434 ACE_END_VERSIONED_NAMESPACE_DECL
 435
 436 # if defined (ACE_HAS_INLINED_OSCALLS)
 437 #   if defined (ACE_INLINE)
 438 #     undef ACE_INLINE
 439 #   endif /* ACE_INLINE */
 440 #   define ACE_INLINE inline
 441 #   include "ace/OS_NS_string.inl"
 442 # endif /* ACE_HAS_INLINED_OSCALLS */
 443
 444 # include /**/ "ace/post.h"
 445 #endif /* ACE_OS_NS_STRING_H */