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