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