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