Defines functions for handling character arrays.
Implementation-Defined Specifications
|
Refer to section 10.5.6, Standard Library Error Messages. |
When using functions defined in this standard include file, note the following.
(1) On copying a string, if the destination area is smaller than the source area, correct operation is not guaranteed.
char a[]="abc";
char b[3];
.
.
.
strcpy (b, a);
In the above example, the size of array a (including the null character) is 4 bytes. Copying by strcpy overwrites data beyond the boundary of array b.
(2) On copying a string, if the source area overlaps the destination area, correct operation is not guaranteed.
int a[ ]="a";
:
:
strcpy(&a[1], a);
:
In the above example, before the null character of the source is read, 'a' is written over the null character. Then the subsequent data after the source string is overwritten in succession.
Copies the contents of a source storage area of a specified length to a destination storage area.
#include <string.h>
void *memcpy (void *s1, const void *s2, size_t n);
s1 Pointer to destination storage area
s2 Pointer to source storage area
n Number of characters to be copied
Copies the contents of a source string including the null character to a destination storage area.
#include <string.h>
char *strcpy (char *s1, const char *s2);
s1 Pointer to destination storage area
Copies a source string of a specified length to a destination storage area.
#include <string.h>
char *strncpy (char *s1, const char *s2, size_t n);
s1 Pointer to destination storage area
n Number of characters to be copied
The strncpy function copies up to n characters from the beginning of the string pointed by s2 to a storage area pointed by s1. If the length of the string specified by s2 is shorter than n characters, the function elongates the string to the length by padding with null characters.
If the length of the string specified by s2 is longer than n characters, the copied string in s1 storage area ends with a character other than the null character.
Concatenates a string after another string.
#include <string.h>
char *strcat (char *s1, const char *s2);
s1 Pointer to the string after which another string is appended
s2 Pointer to the string to be appended after the other string
The strcat function concatenates the string specified by s2 at the end of another string specified by s1. The null character indicating the end of the s2 string is also copied. The null character at the end of the s1 string is deleted.
Concatenates a string of a specified length after another string.
#include <string.h>
char *strncat (char *s1, const char *s2, size_t n);
s1 Pointer to the string after which another string is appended
s2 Pointer to the string to be appended after the other string
n Number of characters to concatenate
The strncat function concatenates up to n characters from the beginning of the string specified by s2 at the end of another string specified by s1. The null character at the end of the s1 string is replaced by the first character of the s2 string. A null character is appended to the end of the concatenated string.
Compares the contents of two storage areas specified.
#include <string.h>
long memcmp (const void *s1, const void *s2, size_t n);
s1 Pointer to the reference storage area to be compared
s2 Pointer to the storage area to compare to the reference
n Number of characters to compare
If storage area pointed by s1 > storage area pointed by s2: Positive value
If storage area pointed by s1 == storage area pointed by s2: 0
If storage area pointed by s1 < storage area pointed by s2: Negative value
The memcmp function compares the contents of the first n characters in the storage areas pointed by s1 and s2. The rules of comparison are implementation-defined.
Compares the contents of two strings specified.
#include <string.h>
long strcmp (const char *s1, const char *s2);
If string pointed by s1 > string pointed by s2: Positive value
If string pointed by s1 == string pointed by s2: 0
If string pointed by s1 < string pointed by s2: Negative value
s1 Pointer to the reference string to be compared
s2 Pointer to the string to compare to the reference
The strcmp function compares the contents of the strings pointed by s1 and s2, and sets up the comparison result as a return value. The rules of comparison are implementation-defined.
Compares two strings specified up to a specified length.
#include <string.h>
long strncmp (const char *s1, const char *s2, size_t n);
s1 Pointer to the reference string to be compared
s2 Pointer to the string to compare to the reference
n Maximum number of characters to compare
If string pointed by s1 > string pointed by s2: Positive value
If string pointed by s1 == string pointed by s2: 0
If string pointed by s1 < string pointed by s2: Negative value
The strncmp function compares the contents of the strings pointed by s1 and s2, up to n characters. The rules of comparison are implementation-defined.
Searches a specified storage area for the first occurrence of a specified character.
#include <string.h>
void *memchr (const void *s, long c, size_t n);
s Pointer to the storage area to be searched
n Number of characters to search
If the character is found: Pointer to the found character
If the character is not found: NULL
The memchr function searches the storage area specified by s from the beginning up to n characters, looking for the first occurrence of the character specified as c. If the c character is found, the function returns the pointer to the found character.
Searches a specified string for the first occurrence of a specified character.
char *strchr (const char *s, long c);
s Pointer to the string to be searched
If the character is found: Pointer to the found character
If the character is not found: NULL
The strchr function searches the string specified by s looking for the first occurrence of the character specified as c. If the c character is found, the function returns the pointer to the found character.
The null character at the end of the s string is included in the search object.
Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are not included in another string specified.
#include <string.h>
size_t strcspn (const char *s1, const char *s2);
s1 Pointer to the string to be checked
s2 Pointer to the string used to check s1
Number of characters at the beginning of the s1 string that are not included in the s2 string
The strcspn function checks from the beginning of the string specified by s1, counts the number of consecutive characters that are not included in another string specified by s2, and returns that length.
The null character at the end of the s2 string is not taken as a part of the s2 string.
Searches a specified string for the first occurrence of the character that is included in another string specified.
#include <string.h>
char *strpbrk (const char *s1, const char *s2);
s1 Pointer to the string to be searched
s2 Pointer to the string that indicates the characters to search s1 for
If the character is found: Pointer to the found character
If the character is not found: NULL
The strpbrk function searches the string specified by s1 looking for the first occurrence of any character included in the string specified by s2. If any searched character is found, the function returns the pointer to the first occurrence.
Searches a specified string for the last occurrence of a specified character.
#include <string.h>
char *strrchr (const char *s, long c);
s Pointer to the string to be searched
If the character is found: Pointer to the found character
If the character is not found: NULL
The strrchr function searches the string specified by s looking for the last occurrence of the character specified by c. If the c character is found, the function returns the pointer to the last occurrence of that character.
The null character at the end of the s string is included in the search objective.
Checks a specified string from the beginning and counts the number of consecutive characters at the beginning that are included in another string specified.
#include <string.h>
size_t strspn (const char *s1, const char *s2);
s1 Pointer to the string to be checked
s2 Pointer to the string used to check s1
Number of characters at the beginning of the s1 string that are included in the s2 string
The strspn function checks from the beginning of the string specified by s1, counts the number of consecutive characters that are included in another string specified by s2, and returns that length.
Searches a specified string for the first occurrence of another string specified.
#include <string.h>
char *strstr (const char *s1, const char *s2);
s1 Pointer to the string to be searched
s2 Pointer to the string to search for
If the string is found: Pointer to the found string
If the string is not found: NULL
The strstr function searches the string specified by s1 looking for the first occurrence of another string specified by s2, and returns the pointer to the first occurrence.
Divides a specified string into some tokens.
#include <string.h>
char *strtok (char *s1, const char *s2);
If division into tokens is successful: Pointer to the first token divided
If division into tokens is unsuccessful: NULL
s1 Pointer to the string to be divided into some tokens
s2 Pointer to the string representing string-dividing characters
The strtok function should be repeatedly called to divide a string.
(a) First call
The string pointed by s1 is divided at a character included in the string pointed by s2. If a token has been separated, the function returns a pointer to the beginning of that token. Otherwise, the function returns NULL.
(b) Second and subsequent calls
Starting from the next character separated before as the token, the function repeats division at a character included in the string pointed by s2. If a token has been separated, the function returns a pointer to the beginning of that token. Otherwise, the function returns NULL.
At the second and subsequent calls, specify NULL as the first parameter. The string pointed by s2 can be changed at each call. The null character is appended at the end of a separated token.
An example of use of the strtok function is shown below.
1 #include <string.h> 2 static char s1[ ]="a@b, @c/@d"; 3 char *ret; 4 5 ret = strtok(s1, "@"); 6 ret = strtok(NULL, ",@"); 7 ret = strtok(NULL, "/@"); 8 ret = strtok(NULL, "@");
The above example program uses the strtok function to divide string "a@b, @c/@d" into tokens a, b, c, and d.
The second line specifies string "a@b, @c/@d" as an initial value for string s1.
The fifth line calls the strtok function to divide tokens using '@' as the delimiter. As a result, a pointer to character 'a' is returned, and the null character is embedded at '@,' the first delimiter after character 'a.' Thus string 'a' has been separated.
Specify NULL for the first parameter to consecutively separate tokens from the same string, and repeat calling the strtok function.
Consequently, the function separates strings 'b,' 'c,' and 'd.'
Sets a specified character a specified number of times at the beginning of a specified storage area.
#include <string.h>
void *memset (void *s, long c, size_t n);
s Pointer to storage area to set characters in
n Number of characters to be set
The memset function sets the character specified by c a number of times specified by n in the storage area specified by s.
Returns an error message corresponding to a specified error number.
#include <string.h>
char *strerror (long s);
Pointer to the error message (string) corresponding to the specified error number
The strerror function receives an error number specified by s and returns an error message corresponding to the number. Contents of error messages are implementation-defined.
If the returned error message is modified, correct operation is not guaranteed.
Calculates the length of a string.
#include <string.h>
size_t strlen (const char *s);
s Pointer to the string to check the length of
Number of characters in the string
The null character at the end of the s string is excluded from the string length.
Copies the specified size of the contents of a source area to a destination storage area. If part of the source storage area and the destination storage area overlap, data is copied to the destination storage area before the overlapped source storage area is overwritten. Therefore, correct copy is enabled.
#include <string.h>
void *memmove (void *s1, const void *s2, size_t n);
s1 Pointer to the destination storage area
s2 Pointer to the source storage area