OS_NS_string.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //=============================================================================
00004 /**
00005  *  @file   OS_NS_string.h
00006  *
00007  *  OS_NS_string.h,v 1.20 2006/02/02 17:52:06 jtc Exp
00008  *
00009  *  @author Douglas C. Schmidt <schmidt@cs.wustl.edu>
00010  *  @author Jesper S. M|ller<stophph@diku.dk>
00011  *  @author and a cast of thousands...
00012  *
00013  *  Originally in OS.h.
00014  */
00015 //=============================================================================
00016 
00017 #ifndef ACE_OS_NS_STRING_H
00018 #define ACE_OS_NS_STRING_H
00019 
00020 # include /**/ "ace/pre.h"
00021 
00022 # include "ace/config-lite.h"
00023 
00024 # if !defined (ACE_LACKS_PRAGMA_ONCE)
00025 #  pragma once
00026 # endif /* ACE_LACKS_PRAGMA_ONCE */
00027 
00028 #include "ace/Basic_Types.h" // to get ACE_WCHAR_T,
00029                             // should be in os_stddef.h or not used like this.
00030 #include "ace/ACE_export.h"
00031 
00032 #if defined (ACE_EXPORT_MACRO)
00033 #  undef ACE_EXPORT_MACRO
00034 #endif
00035 #define ACE_EXPORT_MACRO ACE_Export
00036 
00037 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
00038 
00039 namespace ACE_OS {
00040 
00041   /** @name Functions from <cstring>
00042    *
00043    *  Included are the functions defined in <cstring> and their <cwchar>
00044    *  equivalents.
00045    *
00046    *  @todo To be complete, we should add strcoll, and strxfrm.
00047    */
00048   //@{
00049 
00050   /// Finds characters in a buffer (const void version).
00051   ACE_NAMESPACE_INLINE_FUNCTION
00052   const void *memchr (const void *s, int c, size_t len);
00053 
00054   /// Finds characters in a buffer (void version).
00055   ACE_NAMESPACE_INLINE_FUNCTION
00056   void *memchr (void *s, int c, size_t len);
00057 
00058 #if !defined (ACE_HAS_MEMCHR)
00059   /// Emulated memchr - Finds a character in a buffer.
00060   extern ACE_Export
00061   const void *memchr_emulation (const void *s, int c, size_t len);
00062 #endif /* ACE_HAS_MEMCHR */
00063 
00064   /// Compares two buffers.
00065   ACE_NAMESPACE_INLINE_FUNCTION
00066   int memcmp (const void *t, const void *s, size_t len);
00067 
00068   /// Copies one buffer to another.
00069   ACE_NAMESPACE_INLINE_FUNCTION
00070   void *memcpy (void *t, const void *s, size_t len);
00071 
00072 #if defined (ACE_HAS_MEMCPY_LOOP_UNROLL)
00073 /*
00074  * Version of memcpy where the copy loop is unrolled.
00075  * On certain platforms this results in better performance.
00076  * This is determined and set via autoconf.
00077  */
00078   extern ACE_Export
00079   void *fast_memcpy (void *t, const void *s, size_t len);
00080 #endif
00081 
00082   /// Moves one buffer to another.
00083   ACE_NAMESPACE_INLINE_FUNCTION
00084   void *memmove (void *t, const void *s, size_t len);
00085 
00086   /// Fills a buffer with a character value.
00087   ACE_NAMESPACE_INLINE_FUNCTION
00088   void *memset (void *s, int c, size_t len);
00089 
00090   /// Appends a string to another string (char version).
00091   ACE_NAMESPACE_INLINE_FUNCTION
00092   char *strcat (char *s, const char *t);
00093 
00094 #if defined (ACE_HAS_WCHAR)
00095   /// Appends a string to another string (wchar_t version).
00096   ACE_NAMESPACE_INLINE_FUNCTION
00097   wchar_t *strcat (wchar_t *s, const wchar_t *t);
00098 #endif /* ACE_HAS_WCHAR */
00099 
00100   /// Finds the first occurance of a character in a string (const char
00101   /// version).
00102   ACE_NAMESPACE_INLINE_FUNCTION
00103   const char *strchr (const char *s, int c);
00104 
00105 #if defined (ACE_HAS_WCHAR)
00106   /// Finds the first occurance of a character in a string (const wchar_t
00107   /// version).
00108   ACE_NAMESPACE_INLINE_FUNCTION
00109   const wchar_t *strchr (const wchar_t *s, wchar_t c);
00110 #endif /* ACE_HAS_WCHAR */
00111 
00112   /// Finds the first occurance of a character in a string (char version).
00113   ACE_NAMESPACE_INLINE_FUNCTION
00114   char *strchr (char *s, int c);
00115 
00116 #if defined (ACE_HAS_WCHAR)
00117   /// Finds the first occurance of a character in a string (wchar_t version).
00118   ACE_NAMESPACE_INLINE_FUNCTION
00119   wchar_t *strchr (wchar_t *s, wchar_t c);
00120 #endif /* ACE_HAS_WCHAR */
00121 
00122   /// Compares two strings (char version).
00123   ACE_NAMESPACE_INLINE_FUNCTION
00124   int strcmp (const char *s, const char *t);
00125 
00126   /// Compares two strings (wchar_t version).
00127   ACE_NAMESPACE_INLINE_FUNCTION
00128   int strcmp (const ACE_WCHAR_T *s, const ACE_WCHAR_T *t);
00129 
00130   /// Copies a string (char version).
00131   ACE_NAMESPACE_INLINE_FUNCTION
00132   char *strcpy (char *s, const char *t);
00133 
00134 #if defined (ACE_HAS_WCHAR)
00135   /// Copies a string (wchar_t version).
00136   ACE_NAMESPACE_INLINE_FUNCTION
00137   wchar_t *strcpy (wchar_t *s, const wchar_t *t);
00138 #endif /* ACE_HAS_WCHAR */
00139 
00140   /// Searches for the first substring without any of the specified
00141   /// characters and returns the size of the substring (char version).
00142   ACE_NAMESPACE_INLINE_FUNCTION
00143   size_t strcspn (const char *s, const char *reject);
00144 
00145 #if defined (ACE_HAS_WCHAR)
00146   /// Searches for the first substring without any of the specified
00147   /// characters and returns the size of the substring (wchar_t version).
00148   ACE_NAMESPACE_INLINE_FUNCTION
00149   size_t strcspn (const wchar_t *s, const wchar_t *reject);
00150 #endif /* ACE_HAS_WCHAR */
00151 
00152   /// Returns a malloced duplicated string (char version).
00153   ACE_NAMESPACE_INLINE_FUNCTION
00154   char *strdup (const char *s);
00155 
00156 #if (defined (ACE_LACKS_STRDUP) && !defined(ACE_STRDUP_EQUIVALENT)) \
00157   || defined (ACE_HAS_STRDUP_EMULATION)
00158   extern ACE_Export
00159   char *strdup_emulation (const char *s);
00160 #endif
00161 
00162 #if defined (ACE_HAS_WCHAR)
00163   /// Returns a malloced duplicated string (wchar_t version).
00164   ACE_NAMESPACE_INLINE_FUNCTION
00165   wchar_t *strdup (const wchar_t *s);
00166 
00167 #if (defined (ACE_LACKS_WCSDUP) && !defined(ACE_WCSDUP_EQUIVALENT)) \
00168   || defined (ACE_HAS_WCSDUP_EMULATION)
00169   extern ACE_Export
00170   wchar_t *strdup_emulation (const wchar_t *s);
00171 #endif
00172 #endif /* ACE_HAS_WCHAR */
00173 
00174   /// Copies a string, but returns a pointer to the end of the
00175   /// copied region (char version).
00176   extern ACE_Export
00177   char *strecpy (char *des, const char *src);
00178 
00179 #if defined (ACE_HAS_WCHAR)
00180   /// Copies a string, but returns a pointer to the end of the
00181   /// copied region (wchar_t version).
00182   extern ACE_Export
00183   wchar_t *strecpy (wchar_t *s, const wchar_t *t);
00184 #endif /* ACE_HAS_WCHAR */
00185 
00186   /*
00187   ** Returns a system error message. If the supplied errnum is out of range,
00188   ** a string of the form "Unknown error %d" is used to format the string
00189   ** whose pointer is returned and errno is set to EINVAL.
00190   */
00191   extern ACE_Export
00192   char *strerror (int errnum);
00193 
00194 #if defined (ACE_LACKS_STRERROR)
00195   /// Emulated strerror - Returns a system error message.
00196   extern ACE_Export
00197   char *strerror_emulation (int errnum);
00198 #endif /* ACE_LACKS_STRERROR */
00199 
00200   /// Finds the length of a string (char version).
00201   ACE_NAMESPACE_INLINE_FUNCTION
00202   size_t strlen (const char *s);
00203 
00204   /// Finds the length of a string (ACE_WCHAR_T version).
00205   ACE_NAMESPACE_INLINE_FUNCTION
00206   size_t strlen (const ACE_WCHAR_T *s);
00207 
00208   /// Appends part of a string to another string (char version).
00209   ACE_NAMESPACE_INLINE_FUNCTION
00210   char *strncat (char *s, const char *t, size_t len);
00211 
00212   /// Appends part of a string to another string (wchar_t version).
00213   ACE_NAMESPACE_INLINE_FUNCTION
00214   ACE_WCHAR_T *strncat (ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
00215 
00216   /// Finds the first occurance of a character in an array (const char
00217   /// version).
00218   extern ACE_Export
00219   const char *strnchr (const char *s, int c, size_t len);
00220 
00221   /// Finds the first occurance of a character in an array (const ACE_WCHAR_T
00222   /// version).
00223   extern ACE_Export
00224   const ACE_WCHAR_T *strnchr (const ACE_WCHAR_T *s, ACE_WCHAR_T c, size_t len);
00225 
00226   /// Finds the first occurance of a character in an array (char version).
00227   ACE_NAMESPACE_INLINE_FUNCTION
00228   char *strnchr (char *s, int c, size_t len);
00229 
00230   /// Finds the first occurance of a character in an array (ACE_WCHAR_T version).
00231   ACE_NAMESPACE_INLINE_FUNCTION
00232   ACE_WCHAR_T *strnchr (ACE_WCHAR_T *s, ACE_WCHAR_T c, size_t len);
00233 
00234   /// Compares two arrays (char version).
00235   ACE_NAMESPACE_INLINE_FUNCTION
00236   int strncmp (const char *s, const char *t, size_t len);
00237 
00238   /// Compares two arrays (wchar_t version).
00239   ACE_NAMESPACE_INLINE_FUNCTION
00240   int strncmp (const ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
00241 
00242   /// Copies an array (char version)
00243   ACE_NAMESPACE_INLINE_FUNCTION
00244   char *strncpy (char *s, const char *t, size_t len);
00245 
00246   /// Copies an array (ACE_WCHAR_T version)
00247   ACE_NAMESPACE_INLINE_FUNCTION
00248   ACE_WCHAR_T *strncpy (ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
00249 
00250   /// Finds the length of a limited-length string (char version).
00251   /**
00252    * @param s       The character string to find the length of.
00253    * @param maxlen  The maximum number of characters that will be
00254    *                scanned for the terminating nul character.
00255    *
00256    * @return The length of @arg s, if the terminating nul character
00257    *         is located, else @arg maxlen.
00258    */
00259   ACE_NAMESPACE_INLINE_FUNCTION
00260   size_t strnlen (const char *s, size_t maxlen);
00261 
00262   /// Finds the length of a limited-length string (ACE_WCHAR_T version).
00263   /**
00264    * @param s       The character string to find the length of.
00265    * @param maxlen  The maximum number of characters that will be
00266    *                scanned for the terminating nul character.
00267    *
00268    * @return The length of @arg s, if the terminating nul character
00269    *         is located, else @arg maxlen.
00270    */
00271   ACE_NAMESPACE_INLINE_FUNCTION
00272   size_t strnlen (const ACE_WCHAR_T *s, size_t maxlen);
00273 
00274   /// Finds the first occurance of a substring in an array (const char
00275   /// version).
00276   extern ACE_Export
00277   const char *strnstr (const char *s, const char *t, size_t len);
00278 
00279   /// Finds the first occurance of a substring in an array (const wchar_t
00280   /// version).
00281   extern ACE_Export
00282   const ACE_WCHAR_T *strnstr (const ACE_WCHAR_T *s,
00283                               const ACE_WCHAR_T *t,
00284                               size_t len);
00285 
00286   /// Finds the first occurance of a substring in an array (char version).
00287   ACE_NAMESPACE_INLINE_FUNCTION
00288   char *strnstr (char *s, const char *t, size_t len);
00289 
00290   /// Finds the first occurance of a substring in an array (wchar_t version).
00291   ACE_NAMESPACE_INLINE_FUNCTION
00292   ACE_WCHAR_T *strnstr (ACE_WCHAR_T *s, const ACE_WCHAR_T *t, size_t len);
00293 
00294   /// Searches for characters in a string (const char version).
00295   ACE_NAMESPACE_INLINE_FUNCTION
00296   const char *strpbrk (const char *s1, const char *s2);
00297 
00298 #if defined (ACE_HAS_WCHAR)
00299   /// Searches for characters in a string (const wchar_t version).
00300   ACE_NAMESPACE_INLINE_FUNCTION
00301   const wchar_t *strpbrk (const wchar_t *s1, const wchar_t *s2);
00302 #endif /* ACE_HAS_WCHAR */
00303 
00304   /// Searches for characters in a string (char version).
00305   ACE_NAMESPACE_INLINE_FUNCTION
00306   char *strpbrk (char *s1, const char *s2);
00307 
00308 #if defined (ACE_HAS_WCHAR)
00309   /// Searches for characters in a string (wchar_t version).
00310   ACE_NAMESPACE_INLINE_FUNCTION
00311   wchar_t *strpbrk (wchar_t *s1, const wchar_t *s2);
00312 #endif /* ACE_HAS_WCHAR */
00313 
00314 #if defined (ACE_LACKS_STRPBRK)
00315   /// Emulated strpbrk - Searches for characters in a string.
00316   extern ACE_Export
00317   char *strpbrk_emulation (const char *string,
00318                            const char *charset);
00319 #endif /* ACE_LACKS_STRPBRK */
00320 
00321   /// Finds the last occurance of a character in a string (const char
00322   /// version).
00323   ACE_NAMESPACE_INLINE_FUNCTION
00324   const char *strrchr (const char *s, int c);
00325 
00326 #if defined (ACE_HAS_WCHAR)
00327   /// Finds the last occurance of a character in a string (const wchar_t
00328   /// version).
00329   ACE_NAMESPACE_INLINE_FUNCTION
00330   const wchar_t *strrchr (const wchar_t *s, wchar_t c);
00331 #endif /* ACE_HAS_WCHAR */
00332 
00333   /// Finds the last occurance of a character in a string (char version).
00334   ACE_NAMESPACE_INLINE_FUNCTION
00335   char *strrchr (char *s, int c);
00336 
00337 #if defined (ACE_HAS_WCHAR)
00338   /// Finds the last occurance of a character in a string (wchar_t version).
00339   ACE_NAMESPACE_INLINE_FUNCTION
00340   wchar_t *strrchr (wchar_t *s, wchar_t c);
00341 #endif /* ACE_HAS_WCHAR */
00342 
00343 #if defined (ACE_LACKS_STRRCHR)
00344   /// Emulated strrchr (char version) - Finds the last occurance of a
00345   /// character in a string.
00346   extern ACE_Export
00347   char *strrchr_emulation (char *s, int c);
00348 
00349   /// Emulated strrchr (const char version) - Finds the last occurance of a
00350   /// character in a string.
00351   extern ACE_Export
00352   const char *strrchr_emulation (const char *s, int c);
00353 #endif /* ACE_LACKS_STRRCHR */
00354 
00355   /// This is a "safe" c string copy function (char version).
00356   /**
00357    * Unlike strncpy() this function will always add a terminating '\0'
00358    * char if maxlen > 0.  So the user doesn't has to provide an extra
00359    * '\0' if the user wants a '\0' terminated dst.  The function
00360    * doesn't check for a 0 @a dst, because this will give problems
00361    * anyway.  When @a src is 0 an empty string is made.  We do not
00362    * "touch" * @a dst if maxlen is 0.  Returns @a dst.  Care should be
00363    * taken when replacing strncpy() calls, because in some cases a
00364    * strncpy() user is using the "not '\0' terminating" feature from
00365    * strncpy().  This happens most when the call to strncpy() was
00366    * optimized by using a maxlen which is 1 smaller than the size
00367    * because there's always written a '\0' inside this last position.
00368    * Very seldom it's possible that the '\0' padding feature from
00369    * strncpy() is needed.
00370    */
00371   extern ACE_Export
00372   char *strsncpy (char *dst,
00373                   const char *src,
00374                   size_t maxlen);
00375 
00376   /// This is a "safe" c string copy function (wchar_t version).
00377   /**
00378    * Unlike strncpy() this function will always add a terminating '\0'
00379    * char if maxlen > 0.  So the user doesn't has to provide an extra
00380    * '\0' if the user wants a '\0' terminated dst.  The function
00381    * doesn't check for a 0 @a dst, because this will give problems
00382    * anyway.  When @a src is 0 an empty string is made.  We do not
00383    * "touch" * @a dst if maxlen is 0.  Returns @a dst.  Care should be
00384    * taken when replacing strncpy() calls, because in some cases a
00385    * strncpy() user is using the "not '\0' terminating" feature from
00386    * strncpy().  This happens most when the call to strncpy() was
00387    * optimized by using a maxlen which is 1 smaller than the size
00388    * because there's always written a '\0' inside this last position.
00389    * Very seldom it's possible that the '\0' padding feature from
00390    * strncpy() is needed.
00391    */
00392   extern ACE_Export
00393   ACE_WCHAR_T *strsncpy (ACE_WCHAR_T *dst,
00394                          const ACE_WCHAR_T *src,
00395                          size_t maxlen);
00396 
00397   /// Searches for the first substring containing only the specified
00398   /// characters and returns the size of the substring (char version).
00399   ACE_NAMESPACE_INLINE_FUNCTION
00400   size_t strspn (const char *s1, const char *s2);
00401 
00402 #if defined (ACE_HAS_WCHAR)
00403   /// Searches for the first substring containing only the specified
00404   /// characters and returns the size of the substring (wchar_t version).
00405   ACE_NAMESPACE_INLINE_FUNCTION
00406   size_t strspn (const wchar_t *s1, const wchar_t *s2);
00407 #endif /* ACE_HAS_WCHAR */
00408 
00409 #if defined (ACE_LACKS_STRSPN)
00410   /// Emulated wcsspn.
00411   extern ACE_Export
00412   size_t strspn_emulation (const char *string,
00413                            const char *charset);
00414 #endif /* ACE_LACKS_STRSPN */
00415 
00416   /// Finds the first occurance of a substring in a string (const char
00417   /// version).
00418   ACE_NAMESPACE_INLINE_FUNCTION
00419   const char *strstr (const char *s, const char *t);
00420 
00421 #if defined (ACE_HAS_WCHAR)
00422   /// Finds the first occurance of a substring in a string (const wchar_t
00423   /// version).
00424   ACE_NAMESPACE_INLINE_FUNCTION
00425   const wchar_t *strstr (const wchar_t *s, const wchar_t *t);
00426 #endif /* ACE_HAS_WCHAR */
00427 
00428   /// Finds the first occurance of a substring in a string (char version).
00429   ACE_NAMESPACE_INLINE_FUNCTION
00430   char *strstr (char *s, const char *t);
00431 
00432 #if defined (ACE_HAS_WCHAR)
00433   /// Finds the first occurance of a substring in a string (wchar_t version).
00434   ACE_NAMESPACE_INLINE_FUNCTION
00435   wchar_t *strstr (wchar_t *s, const wchar_t *t);
00436 #endif /* ACE_HAS_WCHAR */
00437 
00438   /// Finds the next token in a string (char version).
00439   ACE_NAMESPACE_INLINE_FUNCTION
00440   char *strtok (char *s, const char *tokens);
00441 
00442 #if defined (ACE_HAS_WCHAR) && !defined (ACE_LACKS_WCSTOK)
00443   /// Finds the next token in a string (wchar_t version).
00444   ACE_NAMESPACE_INLINE_FUNCTION
00445   wchar_t *strtok (wchar_t *s, const wchar_t *tokens);
00446 #endif /* ACE_HAS_WCHAR && !ACE_LACKS_WCSTOK */
00447 
00448   //@}
00449 
00450   /// Finds the next token in a string (safe char version).
00451   ACE_NAMESPACE_INLINE_FUNCTION
00452   char *strtok_r (char *s, const char *tokens, char **lasts);
00453 
00454 #if defined (ACE_HAS_WCHAR)
00455   /// Finds the next token in a string (wchar_t version).
00456   ACE_NAMESPACE_INLINE_FUNCTION
00457   wchar_t *strtok_r (ACE_WCHAR_T *s, const ACE_WCHAR_T *tokens, ACE_WCHAR_T **lasts);
00458 #endif  // ACE_HAS_WCHAR
00459 
00460 #if !defined (ACE_HAS_REENTRANT_FUNCTIONS)
00461   /// Emulated strtok_r.
00462   extern ACE_Export
00463   char *strtok_r_emulation (char *s, const char *tokens, char **lasts);
00464 #endif /* !ACE_HAS_REENTRANT_FUNCTIONS */
00465 
00466 # if defined (ACE_HAS_WCHAR) && defined(ACE_LACKS_WCSTOK)
00467   /// Emulated strtok_r (wchar_t version).
00468   extern ACE_Export
00469   wchar_t *strtok_r_emulation (ACE_WCHAR_T *s, const ACE_WCHAR_T *tokens, ACE_WCHAR_T **lasts);
00470 # endif  // ACE_HAS_WCHAR && ACE_LACKS_WCSTOK
00471 
00472 } /* namespace ACE_OS */
00473 
00474 ACE_END_VERSIONED_NAMESPACE_DECL
00475 
00476 # if defined (ACE_HAS_INLINED_OSCALLS)
00477 #   if defined (ACE_INLINE)
00478 #     undef ACE_INLINE
00479 #   endif /* ACE_INLINE */
00480 #   define ACE_INLINE inline
00481 #   include "ace/OS_NS_string.inl"
00482 # endif /* ACE_HAS_INLINED_OSCALLS */
00483 
00484 # include /**/ "ace/post.h"
00485 #endif /* ACE_OS_NS_STRING_H */

Generated on Thu Nov 9 09:41:58 2006 for ACE by doxygen 1.3.6