This section describes library functions that perform various kinds of search operations on strings and arrays. These functions are declared in the header file ‘string.h’.
Function
void *memchr (const void *block, intc, size_tsize)
This function finds the first occurrence of the byte c (converted to an
unsigned char) in the initial size bytes of the object beginning at block. The return value is a pointer to the located byte, or a null pointer if no match was found.
Function
wchar_t *wmemchr (const wchar_t *block, wchar_t
wc, size_tsize)
This function finds the first occurrence of the wide character wc in the initial
size wide characters of the object beginning at block. The return value is a pointer to the located wide character, or a null pointer if no match was found.
Function
void *rawmemchr (const void *block, intc)
Often thememchrfunction is used with the knowledge that the bytecis avail- able in the memory block specified by the parameters. But this means that the
size parameter is not really needed and that the tests performed with it at run time (to check whether the end of the block is reached) are not needed.
The rawmemchr function exists for just this situation, which is surprisingly frequent. The interface is similar tomemchrexcept that thesize parameter is missing. The function will look beyond the end of the block pointed to byblock
in case the programmer made an error in assuming that the bytec is present in the block. In this case, the result is unspecified. Otherwise, the return value is a pointer to the located byte.
This function is of special interest when looking for the end of a string. Since all strings are terminated by a null byte a call like:
rawmemchr (str, ’\0’)
will never go beyond the end of the string. This function is aGNUextension.
Chapter 5: String and Array Utilities 115 Function
void *memrchr (const void *block, intc, size_tsize)
The functionmemrchris likememchr, except that it searches backward from the end of the block defined by block and size (instead of forward from the front).
Function
char *strchr (const char *string, intc)
Thestrchrfunction finds the first occurrence of the characterc(converted to achar) in the null-terminated string beginning atstring. The return value is a pointer to the located character, or a null pointer if no match was found. For example:
strchr ("hello, world", ’l’)
⇒ "llo, world"
strchr ("hello, world", ’?’)
⇒ NULL
The terminating null character is considered to be part of the string, so you can use this function get a pointer to the end of a string by specifying a null character as the value of thec argument. It would be better (but less portable) to usestrchrnulin this case, though.
Function
wchar_t *wcschr (const wchar_t *wstring, intwc)
Thewcschrfunction finds the first occurrence of the wide characterwcin the null-terminated wide-character string beginning atwstring. The return value is a pointer to the located wide character, or a null pointer if no match was found. The terminating null character is considered to be part of the wide character string, so you can use this function get a pointer to the end of a wide-character string by specifying a null wide character as the value of thewc argument. It would be better (but less portable) to usewcschrnulin this case, though.
Function
char *strchrnul (const char *string, intc)
strchrnulis the same asstrchrexcept that if it does not find the charac- ter, it returns a pointer tostring’s terminating null character rather than a null pointer.
This function is aGNUextension.
Function
wchar_t *wcschrnul (const wchar_t *wstring, wchar_t wc)
wcschrnul is the same as wcschr except that if it does not find the wide character, it returns a pointer to the wide-character string’s terminating null wide character rather than a null pointer.
This function is aGNUextension.
One useful but unusual use of thestrchrfunction is when you want to have a pointer pointing to the NUL byte terminating a string. This is often written in this way:
s += strlen (s);
This is almost optimal, but the addition operation duplicated a bit of the work al- ready done in thestrlenfunction. A better solution is this:
s = strchr (s, ’\0’);
There is no restriction on the second parameter of strchr, so it could very well also be the NUL character. Thestrchrfunction is more expensive than the
strlenfunction, since we have two abort criteria. But in theGNUC Library, the
implementation ofstrchris optimized in a special way, so thatstrchractually is faster.
Function
char *strrchr (const char *string, intc)
The functionstrrchris likestrchr, except that it searches backward from the end of the stringstring (instead of forward from the front).
For example:
strrchr ("hello, world", ’l’)
⇒ "ld"
Function
wchar_t *wcsrchr (const wchar_t *wstring, wchar_t c)
The functionwcsrchris likewcschr, except that it searches backwards from the end of the stringwstring (instead of forward from the front).
Function
char *strstr (const char *haystack, const char *needle)
This is like strchr, except that it searches haystack for a substring needle
rather than just a single character. It returns a pointer into the string haystack
that is the first character of the substring, or a null pointer if no match was found. Ifneedleis an empty string, the function returnshaystack.
For example:
strstr ("hello, world", "l")
⇒ "llo, world"
strstr ("hello, world", "wo")
⇒ "world"
Function
wchar_t *wcsstr (const wchar_t *haystack, const wchar_t *needle)
This is like wcschr, except that it searches haystack for a substring needle
rather than just a single wide character. It returns a pointer into the string
haystack that is the first wide character of the substring, or a null pointer if no match was found. Ifneedleis an empty string, the function returnshaystack.
Chapter 5: String and Array Utilities 117 Function
wchar_t *wcswcs (const wchar_t *haystack, const wchar_t *needle)
wcsstris a deprecated alias forwcsstr. This is the name originally used in the X/Open Portability Guide1 before the Amendment 1 to
ISOC90 was pub- lished.
Function
char *strcasestr (const char *haystack, const char *needle)
This is likestrstr, except that it ignores case in searching for the substring. Likestrcasecmp, how uppercase and lowercase characters are related is lo- cale dependent.
For example:
strstr ("hello, world", "L")
⇒ "llo, world"
strstr ("hello, World", "wo")
⇒ "World"
Function
void *memmem (const void *haystack, size_t haystack-len,
const void *needle, size_tneedle-len)
This is likestrstr, butneedleandhaystack are byte arrays rather than null- terminated strings. needle-len is the length of needle andhaystack-len is the length ofhaystack.
This function is aGNUextension.
Function
size_tstrspn (const char *string, const char *skipset)
Thestrspn(“string span”) function returns the length of the initial substring ofstringthat consists entirely of characters that are members of the set specified by the stringskipset. The order of the characters inskipset is not important. For example:
strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
⇒ 5
Characterused here in the sense of byte. In a string using a multibyte-character encoding (abstract), characters consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale depen- dent.
Function
size_twcsspn (const wchar_t *wstring, const wchar_t *skipset)
The wcsspn(“wide-character string span”) function returns the length of the initial substring of wstring that consists entirely of wide characters that are members of the set specified by the stringskipset. The order of the wide char- acters inskipset is not important.
1
X/Open Company,X/Open Portability Guide,Issue 4, Version 2 (Reading, UK: X/Open Company,
Function
size_tstrcspn (const char *string, const char *stopset)
The strcspn (“string complement span”) function returns the length of the initial substring of string that consists entirely of characters that arenotmem- bers of the set specified by the string stopset. (In other words, it returns the offset of the first character instring that is a member of the setstopset.)
For example:
strcspn ("hello, world", " \t\n,.;!?")
⇒ 5
Character is used here in the sense of byte. In a string using a multibyte- character encoding (abstract), characters consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale dependent.
Function
size_twcscspn (const wchar_t *wstring, const wchar_t *stopset)
Thewcscspn(“wide-character string complement span”) function returns the length of the initial substring ofwstringthat consists entirely of wide characters that arenotmembers of the set specified by the stringstopset. (In other words, it returns the offset of the first character instring that is a member of the set
stopset.)
Function
char *strpbrk (const char *string, const char *stopset)
Thestrpbrk(“string pointer break”) function is related tostrcspn, except that it returns a pointer to the first character instring that is a member of the set
stopset instead of the length of the initial substring. It returns a null pointer if no such character fromstopset is found.
For example:
strpbrk ("hello, world", " \t\n,.;!?")
⇒ ", world"
Character is used here in the sense of byte. In a string using a multibyte- character encoding (abstract), characters consisting of more than one byte are not treated as an entity. Each byte is treated separately. The function is not locale dependent.
Function
wchar_t *wcspbrk (const wchar_t *wstring, const wchar_t *stopset)
The wcspbrk (“wide-character string pointer break”) function is related to
wcscspn, except that it returns a pointer to the first wide character inwstring
that is a member of the setstopset instead of the length of the initial substring. It returns a null pointer if no such character fromstopset is found.
Chapter 5: String and Array Utilities 119
5.7.1 Compatibility String Search Functions
Function
char *index (const char *string, intc)
index is another name for strchr; they are exactly the same. New code should always usestrchr, since this name is defined inISOC whileindex
is aBSDinvention that was never available on System V derived systems.
Function
char *rindex (const char *string, intc)
rindex is another name for strrchr; they are exactly the same. New code should always usestrrchr, since this name is defined in ISOC while
rindexis aBSDinvention that was never available on System V derived sys- tems.