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