Subversion Repositories Kolibri OS

Rev

Blame | Last modification | View Log | RSS feed

  1. /* String handling <string.h>
  2.  
  3.    This file is part of the Public Domain C Library (PDCLib).
  4.    Permission is granted to use, modify, and / or redistribute at will.
  5. */
  6.  
  7. #ifndef _STRING_H_
  8. #define _STRING_H_
  9.  
  10. #include <stddef.h>
  11.  
  12. #ifdef __cplusplus
  13. extern "C" {
  14. #endif
  15.  
  16. /* String function conventions */
  17.  
  18. /*
  19.    In any of the following functions taking a size_t n to specify the length of
  20.    an array or size of a memory region, n may be 0, but the pointer arguments to
  21.    the call shall still be valid unless otherwise stated.
  22. */
  23.  
  24. /* Copying functions */
  25.  
  26. extern void* _FUNC(memccpy)(void *restrict dest, const void *restrict src, int c, size_t n);
  27.  
  28. /* Copy a number of n characters from the memory area pointed to by s2 to the
  29.    area pointed to by s1. If the two areas overlap, behaviour is undefined.
  30.    Returns the value of s1.
  31. */
  32. extern void* _FUNC(memcpy)(void* s1, const void* s2, size_t n);
  33.  
  34. /* Copy a number of n characters from the memory area pointed to by s2 to the
  35.    area pointed to by s1. The two areas may overlap.
  36.    Returns the value of s1.
  37. */
  38. extern void* _FUNC(memmove)(void* s1, const void* s2, size_t n);
  39.  
  40. /* Copy the character array s2 (including terminating '\0' byte) into the
  41.    character array s1.
  42.    Returns the value of s1.
  43. */
  44. extern char* _FUNC(strcpy)(char*  s1, const char* s2);
  45.  
  46. /* Copy a maximum of n characters from the character array s2 into the character
  47.    array s1. If s2 is shorter than n characters, '\0' bytes will be appended to
  48.    the copy in s1 until n characters have been written. If s2 is longer than n
  49.    characters, NO terminating '\0' will be written to s1. If the arrays overlap,
  50.    behaviour is undefined.
  51.    Returns the value of s1.
  52. */
  53. extern char* _FUNC(strncpy)(char* s1, const char* s2, size_t n);
  54.  
  55. /* Concatenation functions */
  56.  
  57. /* Append the contents of the character array s2 (including terminating '\0') to
  58.    the character array s1 (first character of s2 overwriting the '\0' of s1). If
  59.    the arrays overlap, behaviour is undefined.
  60.    Returns the value of s1.
  61. */
  62. extern char* _FUNC(strcat)(char* s1, const char* s2);
  63.  
  64. /* Append a maximum of n characters from the character array s2 to the character
  65.    array s1 (first character of s2 overwriting the '\0' of s1). A terminating
  66.    '\0' is ALWAYS appended, even if the full n characters have already been
  67.    written. If the arrays overlap, behaviour is undefined.
  68.    Returns the value of s1.
  69. */
  70. extern char* _FUNC(strncat)(char* s1, const char* s2, size_t n);
  71.  
  72. /* Comparison functions */
  73.  
  74. /* Compare the first n characters of the memory areas pointed to by s1 and s2.
  75.    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  76.    s1 > s2.
  77. */
  78. extern int _FUNC(memcmp)(const void * s1, const void* s2, size_t n);
  79.  
  80. /* Compare the character arrays s1 and s2.
  81.    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  82.    s1 > s2.
  83. */
  84. extern int _FUNC(strcmp)(const char * s1, const char* s2);
  85.  
  86. /* Compare the character arrays s1 and s2, interpreted as specified by the
  87.    LC_COLLATE category of the current locale.
  88.    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  89.    s1 > s2.
  90.    TODO: Currently a dummy wrapper for strcmp() as PDCLib does not yet support
  91.    locales.
  92. */
  93. extern int _FUNC(strcoll)(const char* s1, const char* s2);
  94.  
  95. /* Compare no more than the first n characters of the character arrays s1 and
  96.    s2.
  97.    Returns 0 if s1 == s2, a negative number if s1 < s2, and a positive number if
  98.    s1 > s2.
  99. */
  100. extern int _FUNC(strncmp)(const char* s1, const char* s2, size_t n);
  101.  
  102. /* Transform the character array s2 as appropriate for the LC_COLLATE setting of
  103.    the current locale. If length of resulting string is less than n, store it in
  104.    the character array pointed to by s1. Return the length of the resulting
  105.    string.
  106. */
  107. extern size_t _FUNC(strxfrm)(char* s1, const char* s2, size_t n);
  108.  
  109. /* Search functions */
  110.  
  111. /* Search the first n characters in the memory area pointed to by s for the
  112.    character c (interpreted as unsigned char).
  113.    Returns a pointer to the first instance found, or NULL.
  114. */
  115. extern void* _FUNC(memchr)(const void* s, int c, size_t n);
  116.  
  117. /* Search the character array s (including terminating '\0') for the character c
  118.    (interpreted as char).
  119.    Returns a pointer to the first instance found, or NULL.
  120. */
  121. extern char* _FUNC(strchr)(const char* s, int c);
  122.  
  123. /* Determine the length of the initial substring of character array s1 which
  124.    consists only of characters not from the character array s2.
  125.    Returns the length of that substring.
  126. */
  127. extern size_t _FUNC(strcspn)(const char* s1, const char* s2);
  128.  
  129. /* Search the character array s1 for any character from the character array s2.
  130.    Returns a pointer to the first occurrence, or NULL.
  131. */
  132. extern char* _FUNC(strpbrk)(const char* s1, const char* s2);
  133.  
  134. /* Search the character array s (including terminating '\0') for the character c
  135.    (interpreted as char).
  136.    Returns a pointer to the last instance found, or NULL.
  137. */
  138. extern char* _FUNC(strrchr)(const char * s, int c );
  139.  
  140. /* Determine the length of the initial substring of character array s1 which
  141.    consists only of characters from the character array s2.
  142.    Returns the length of that substring.
  143. */
  144. extern size_t _FUNC(strspn)(const char * s1, const char * s2);
  145.  
  146. /* Search the character array s1 for the substring in character array s2.
  147.    Returns a pointer to that sbstring, or NULL. If s2 is of length zero,
  148.    returns s1.
  149. */
  150. extern char* _FUNC(strstr)(const char * s1, const char * s2);
  151.  
  152. /* In a series of subsequent calls, parse a C string into tokens.
  153.    On the first call to strtok(), the first argument is a pointer to the to-be-
  154.    parsed C string. On subsequent calls, the first argument is NULL unless you
  155.    want to start parsing a new string. s2 holds an array of separator characters
  156.    which can differ from call to call. Leading separators are skipped, the first
  157.    trailing separator overwritten with '\0'.
  158.    Returns a pointer to the next token.
  159.    WARNING: This function uses static storage, and as such is not reentrant.
  160. */
  161. extern char* _FUNC(strtok)(char* s1, const char* s2);
  162.  
  163. /* Miscellaneous functions */
  164.  
  165. /* Write the character c (interpreted as unsigned char) to the first n
  166.    characters of the memory area pointed to by s.
  167.    Returns s.
  168. */
  169. extern void* _FUNC(memset)(void* s, int c, size_t n);
  170.  
  171. /* Map an error number to a (locale-specific) error message string. Error
  172.    numbers are typically errno values, but any number is mapped to a message.
  173.    TODO: PDCLib does not yet support locales.
  174. */
  175. extern char*  _FUNC(strerror)(int errnum);
  176.  
  177. /* Returns the length of the string s (excluding terminating '\0').*/
  178. extern size_t _FUNC(strlen)(const char * s);
  179.  
  180. /* The function reverses the sequence of characters in the string pointed to by str. */
  181. extern char* _FUNC(strrev)(char *str);
  182.  
  183. /* The strdup function executes the function pointed to by the str argument. */
  184. extern char* _FUNC(strdup)(const char *str);
  185.  
  186. #endif
  187.