513 lines
16 KiB
HTML
513 lines
16 KiB
HTML
<html>
|
|
<head>
|
|
<title>
|
|
C Guide--2.14 string.h
|
|
</title>
|
|
<!-- Changed by: eric huss, 12-Mar-1997 -->
|
|
</head>
|
|
<body text="#000000" bgcolor="#FFFFFF">
|
|
|
|
<center>
|
|
<table border=0 width=100%>
|
|
<tr>
|
|
<td align=left width=20% valign=top>
|
|
<a href="2.13.html">
|
|
<img src="left.gif" border=0>
|
|
Previous Section<br>
|
|
2.13 stdlib.h</a></td>
|
|
<td align=center width=60% valign=top>
|
|
| <a href="index.html">Table of Contents</a> |
|
|
<a href="index2.html">Index</a> |</td>
|
|
<td align=right width=20% valign=top>
|
|
<a href="2.15.html">
|
|
Next Section
|
|
<img src="right.gif" border=0><br>
|
|
2.15 time.h</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
<hr>
|
|
|
|
|
|
<h1> 2.14 string.h</h2>
|
|
<p>
|
|
The string header provides many functions useful for manipulating strings (character
|
|
arrays).
|
|
<p>
|
|
Macros:
|
|
<blockquote><code><b>
|
|
NULL
|
|
</b></code></blockquote>
|
|
<p>
|
|
Variables:
|
|
<blockquote><code><b>
|
|
typedef size_t
|
|
</b></code></blockquote>
|
|
<p>
|
|
Functions:
|
|
<blockquote><code><b>
|
|
memchr();<br>
|
|
memcmp();<br>
|
|
memcpy();<br>
|
|
memmove();<br>
|
|
memset();<br>
|
|
strcat();<br>
|
|
strncat();<br>
|
|
strchr();<br>
|
|
strcmp();<br>
|
|
strncmp();<br>
|
|
strcoll();<br>
|
|
strcpy();<br>
|
|
strncpy();<br>
|
|
strcspn();<br>
|
|
strerror();<br>
|
|
strlen();<br>
|
|
strpbrk();<br>
|
|
strrchr();<br>
|
|
strspn();<br>
|
|
strstr();<br>
|
|
strtok();<br>
|
|
strxfrm();
|
|
</b></code></blockquote>
|
|
|
|
<a name="variables"></a>
|
|
<h2>2.14.1 Variables and Definitions</h2>
|
|
<p>
|
|
<ode><b>size_t</b></code> is the unsigned integer result of the sizeof keyword.<br>
|
|
<code><b>NULL</b></code> is the value of a null pointer constant.
|
|
<a name="memchr"></a>
|
|
<h2> 2.14.2 memchr</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
void *memchr(const void *</b></code><i>str</i><code><b>, int </b></code><i>c</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Searches for the first occurrence of the character <i>c</i> (an <code><b>unsigned char</b></code>) in the first <i>n</i> bytes
|
|
of the string pointed to by the argument <i>str</i>.
|
|
<p>
|
|
Returns a pointer pointing to the first matching character, or null if no match was found.
|
|
<a name="memcmp"></a>
|
|
<h2>2.14.3 memcmp</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
int memcmp(const void *</b></code><i>str1</i><code><b>, const void *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Compares the first <i>n</i> bytes of <i>str1</i> and <i>str2</i>. Does not stop comparing even after the null
|
|
character (it always checks <i>n</i> characters).
|
|
<p>
|
|
Returns zero if the first <i>n</i> bytes of <i>str1</i> and <i>str2</i> are equal. Returns less than zero or
|
|
greater than zero if <i>str1</i> is less than or greater than <i>str2</i> respectively.
|
|
|
|
<a name="memcpy"></a>
|
|
<h2>2.14.4 memcpy</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
void *memcpy(void *</b></code><i>str1</i><code><b>, const void *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Copies n characters from <i>str2</i> to <i>str1</i>. If <i>str1</i> and <i>str2</i> overlap the behavior is undefined.
|
|
<p>
|
|
Returns the argument <i>str1</i>.
|
|
|
|
<a name="memmove"></a>
|
|
<h2>2.14.5 memmove</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
void *memmove(void *</b></code><i>str1</i><code><b>, const void *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Copies <i>n</i> characters from <i>str2</i> to <i>str1</i>. If <i>str1</i> and <i>str2</i> overlap the information is first
|
|
completely read from <i>str1</i> and then written to <i>str2</i> so that the characters are copied correctly.
|
|
<p>
|
|
Returns the argument <i>str1</i>.
|
|
|
|
<a name="memset"></a>
|
|
<h2>2.14.6 memset</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
void *memset(void *</b></code><i>str</i><code><b>, int </b></code><i>c</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Copies the character <i>c</i> (an <code><b>unsigned char</b></code>) to the first <i>n</i> characters of the string pointed to
|
|
by the argument <i>str</i>.
|
|
<p>
|
|
The argument <i>str</i> is returned.
|
|
|
|
<a name="strcat"></a>
|
|
<h2>2.14.7 strcat</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strcat(char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Appends the string pointed to by <i>str2</i> to the end of the string pointed to by <i>str1</i>. The
|
|
terminating null character of <i>str1</i> is overwritten. Copying stops once the terminating null
|
|
character of <i>str2</i> is copied. If overlapping occurs, the result is undefined.
|
|
<p>
|
|
The argument <i>str1</i> is returned.
|
|
|
|
<a name="strncat"></a>
|
|
<h2>2.14.8 strncat</h2>
|
|
<p>
|
|
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strncat(char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Appends the string pointed to by <i>str2</i> to the end of the string pointed to by <i>str1</i> up to <i>n</i>
|
|
characters long. The terminating null character of <i>str1</i> is overwritten. Copying stops once <i>n</i>
|
|
characters are copied or the terminating null character of <i>str2</i> is copied. A terminating null
|
|
character is always appended to <i>str1</i>. If overlapping occurs, the result is undefined.
|
|
<p>
|
|
The argument <i>str1</i> is returned.
|
|
|
|
<a name="strchr"></a>
|
|
<h2>2.14.9 strchr</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strchr(const char *</b></code><i>str</i><code><b>, int </b></code><i>c</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Searches for the first occurrence of the character <i>c</i> (an unsigned char) in the string
|
|
pointed to by the argument <i>str</i>. The terminating null character is considered to be part of the
|
|
string.
|
|
<p>
|
|
Returns a pointer pointing to the first matching character, or null if no match was found.
|
|
|
|
<a name="strcmp"></a>
|
|
<h2>2.14.10 strcmp</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
int strcmp(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Compares the string pointed to by <i>str1</i> to the string pointed to by <i>str2</i>.
|
|
<p>
|
|
Returns zero if <i>str1</i> and <i>str2</i> are equal. Returns less than zero or greater than zero if <i>str1</i>
|
|
is less than or greater than <i>str2</i> respectively.
|
|
|
|
<a name="strncmp"></a>
|
|
<h2>2.14.11 strncmp</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
int strncmp(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Compares at most the first <i>n</i> bytes of <i>str1</i> and <i>str2</i>. Stops comparing after the null
|
|
character.
|
|
<p>
|
|
Returns zero if the first <i>n</i> bytes (or null terminated length) of <i>str1</i> and <i>str2</i> are equal.
|
|
Returns less than zero or greater than zero if <i>str1</i> is less than or greater than <i>str2</i> respectively.
|
|
|
|
<a name="strcoll"></a>
|
|
<h2>2.14.12 strcoll</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
int strcoll(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Compares string <i>str1</i> to <i>str2</i>. The result is dependent on the <code><b>LC_COLLATE</b></code> setting of the
|
|
location.
|
|
<p>
|
|
Returns zero if <i>str1</i> and <i>str2</i> are equal. Returns less than zero or greater than zero if <i>str1</i>
|
|
is less than or greater than <i>str2</i> respectively.
|
|
|
|
<a name="strcpy"></a>
|
|
<h2>2.14.13 strcpy</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strcpy(char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Copies the string pointed to by <i>str2</i> to <i>str1</i>. Copies up to and including the null character
|
|
of <i>str2</i>. If <i>str1</i> and <i>str2</i> overlap the behavior is undefined.
|
|
<p>
|
|
Returns the argument <i>str1</i>.
|
|
|
|
<a name="strncpy"></a>
|
|
<h2>2.14.14 strncpy</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strncpy(char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Copies up to <i>n</i> characters from the string pointed to by <i>str2</i> to <i>str1</i>. Copying stops when
|
|
<i>n</i> characters are copied or the terminating null character in <i>str2</i> is reached. If the null character
|
|
is reached, the null characters are continually copied to <i>str1</i> until <i>n</i> characters have been copied.
|
|
<p>
|
|
Returns the argument <i>str1</i>.
|
|
|
|
<a name="strcspn"></a>
|
|
<h2>2.14.15 strcspn</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
size_t strcspn(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Finds the first sequence of characters in the string <i>str1</i> that does not contain any character
|
|
specified in <i>str2</i>.
|
|
<p>
|
|
Returns the length of this first sequence of characters found that do not match with <i>str2</i>.
|
|
|
|
<a name="strerror"></a>
|
|
<h2>2.14.16 strerror</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strerror(int </b></code><i>errnum</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Searches an internal array for the error number <i>errnum</i> and returns a pointer to an error
|
|
message string.
|
|
<p>
|
|
Returns a pointer to an error message string.
|
|
|
|
<a name="strlen"></a>
|
|
<h2>2.14.17 strlen</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
size_t strlen(const char *</b></code><i>str</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Computes the length of the string <i>str</i> up to but not including the terminating null
|
|
character.
|
|
<p>
|
|
Returns the number of characters in the string.
|
|
|
|
<a name="strpbrk"></a>
|
|
<h2>2.14.18 strpbrk</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strpbrk(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Finds the first character in the string <i>str1</i> that matches any character specified in <i>str2</i>.
|
|
<p>
|
|
A pointer to the location of this character is returned. A null pointer is returned if no
|
|
character in <i>str2</i> exists in <i>str1</i>.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<string.h>
|
|
#include<stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
char string[]="Hi there, Chip!";
|
|
char *string_ptr;
|
|
|
|
while((string_ptr=strpbrk(string," "))!=NULL)
|
|
*string_ptr='-';
|
|
|
|
printf("New string is \"%s\".\n",string);
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
|
|
The output should result in every space in the string being converted to a dash (-).
|
|
|
|
<a name="strrchr"></a>
|
|
<h2>2.14.19 strrchr</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strrchr(const char *</b></code><i>str</i><code><b>, int </b></code><i>c</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Searches for the last occurrence of the character <i>c</i> (an <code><b>unsigned char</b></code>) in the string
|
|
pointed to by the argument <i>str</i>. The terminating null character is considered to be part of the
|
|
string.
|
|
<p>
|
|
Returns a pointer pointing to the last matching character, or null if no match was found.
|
|
|
|
<a name="strspn"></a>
|
|
<h2>2.14.20 strspn</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
size_t strspn(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Finds the first sequence of characters in the string <i>str1</i> that contains any character
|
|
specified in <i>str2</i>.
|
|
<p>
|
|
Returns the length of this first sequence of characters found that match with <i>str2</i>.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<string.h>
|
|
#include<stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
char string[]="7803 Elm St.";
|
|
|
|
printf("The number length is %d.\n",strspn(string,"1234567890"));
|
|
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
The output should be:
|
|
The number length is 4.
|
|
|
|
<a name="strstr"></a>
|
|
<h2>2.14.21 strstr</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strstr(const char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Finds the first occurrence of the entire string <i>str2</i> (not including the terminating null
|
|
character) which appears in the string <i>str1</i>.
|
|
<p>
|
|
Returns a pointer to the first occurrence of <i>str2</i> in <i>str1</i>. If no match was found, then a
|
|
null pointer is returned. If <i>str2</i> points to a string of zero length, then the argument <i>str1</i> is
|
|
returned.
|
|
|
|
<a name="strtok"></a>
|
|
<h2>2.14.22 strtok</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
char *strtok(char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Breaks string <i>str1</i> into a series of tokens. If <i>str1</i> and <i>str2</i> are not null, then the following
|
|
search sequence begins. The first character in <i>str1</i> that does not occur in <i>str2</i> is found. If <i>str1</i>
|
|
consists entirely of characters specified in <i>str2</i>, then no tokens exist and a null pointer is
|
|
returned. If this character is found, then this marks the beginning of the first token. It then
|
|
begins searching for the next character after that which is contained in <i>str2</i>. If this character is
|
|
not found, then the current token extends to the end of <i>str1</i>. If the character is found, then it is
|
|
overwritten by a null character, which terminates the current token. The function then saves the
|
|
following position internally and returns.
|
|
<p>
|
|
Subsequent calls with a null pointer for <i>str1</i> will cause the previous position saved to be
|
|
restored and begins searching from that point. Subsequent calls may use a different value for
|
|
<i>str2</i> each time.
|
|
<p>
|
|
Returns a pointer to the first token in <i>str1</i>. If no token is found then a null pointer is
|
|
returned.
|
|
<p>
|
|
|
|
Example:
|
|
<blockquote><code><b><pre>
|
|
#include<string.h>
|
|
#include<stdio.h>
|
|
|
|
int main(void)
|
|
{
|
|
char search_string[]="Woody Norm Cliff";
|
|
char *array[50];
|
|
int loop;
|
|
|
|
array[0]=strtok(search_string," ");
|
|
if(array[0]==NULL)
|
|
{
|
|
printf("No test to search.\n");
|
|
exit(0);
|
|
}
|
|
|
|
for(loop=1;loop<50;loop++)
|
|
{
|
|
array[loop]=strtok(NULL," ");
|
|
if(array[loop]==NULL)
|
|
break;
|
|
}
|
|
|
|
for(loop=0;loop<50;loop++)
|
|
{
|
|
if(array[loop]==NULL)
|
|
break;
|
|
printf("Item #%d is %s.\n",loop,array[loop]);
|
|
}
|
|
|
|
return 0;
|
|
}
|
|
</pre></b></code></blockquote>
|
|
This program replaces each space into a null character and stores a pointer to each substring into
|
|
the array. It then prints out each item.
|
|
|
|
|
|
<a name="strxfrm"></a>
|
|
<h2>2.14.23 strxfrm</h2>
|
|
<p>
|
|
|
|
Declaration:
|
|
<blockquote><code><b>
|
|
size_t strxfrm(char *</b></code><i>str1</i><code><b>, const char *</b></code><i>str2</i><code><b>, size_t </b></code><i>n</i><code><b>);
|
|
</b></code></blockquote>
|
|
|
|
Transforms the string <i>str2</i> and places the result into <i>str1</i>. It copies at most <i>n</i> characters
|
|
into <i>str1</i> including the null terminating character. The transformation occurs such that <code><b>strcmp</b></code>
|
|
applied to two separate converted strings returns the same value as <code><b>strcoll</b></code> applied to the same
|
|
two strings. If overlapping occurs, the result is undefined.
|
|
<p>
|
|
Returns the length of the transformed string (not including the null character).
|
|
<hr>
|
|
|
|
<center>
|
|
<table border=0 width=100%>
|
|
<tr>
|
|
<td align=left width=20% valign=top>
|
|
<a href="2.13.html">
|
|
<img src="left.gif" border=0>
|
|
Previous Section<br>
|
|
2.13 stdlib.h</a></td>
|
|
<td align=center width=60% valign=top>
|
|
| <a href="index.html">Table of Contents</a> |
|
|
<a href="index2.html">Index</a> |</td>
|
|
<td align=right width=20% valign=top>
|
|
<a href="2.15.html">
|
|
Next Section
|
|
<img src="right.gif" border=0><br>
|
|
2.15 time.h</a></td>
|
|
</tr>
|
|
</table>
|
|
</center>
|
|
|
|
</body>
|
|
</html>
|
|
|
|
|