dep/ACE_wrappers/ace/OS_NS_string.h

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