### 5.7 Search Functions

This section describes library functions which perform various kinds of searching operations on strings and arrays. These functions are declared in the header file `string.h`.

— Function: void * memchr (const void *block, int c, size_t size)

> 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_t size)

> 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, int c)

> Often the `memchr` function is used with the knowledge that the byte c is available 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 runtime (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 to `memchr` except that the size parameter is missing. The function will look beyond the end of the block pointed to by block in case the programmer made an error in assuming that the byte c 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 a GNU extension.

— Function: void * memrchr (const void *block, int c, size_t size)

> The function `memrchr` is like `memchr`, except that it searches backwards from the end of the block defined by block and size (instead of forwards from the front).

> This function is a GNU extension.

— Function: char * strchr (const char *string, int c)

> The `strchr` function finds the first occurrence of the character c (converted to a `char`) in the null-terminated string beginning at string. 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 the c argument.

> When `strchr` returns a null pointer, it does not let you know the position of the terminating null character it has found. If you need that information, it is better (but less portable) to use `strchrnul` than to search for it a second time.

— Function: wchar_t * wcschr (const wchar_t *wstring, int wc)

> The `wcschr` function finds the first occurrence of the wide character wc in the null-terminated wide character string beginning at wstring. 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 wude character as the value of the wc argument. It would be better (but less portable) to use `wcschrnul` in this case, though.

— Function: char * strchrnul (const char *string, int c)

> `strchrnul` is the same as `strchr` except that if it does not find the character, it returns a pointer to string's terminating null character rather than a null pointer.

> This function is a GNU extension.

— 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 wide character string's terminating null wide character rather than a null pointer.

> This function is a GNU extension.

One useful, but unusual, use of the `strchr` function is when one wants 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 already done in the `strlen` function. 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. Those readers thinking very hard about this might now point out that the `strchr` function is more expensive than the `strlen` function since we have two abort criteria. This is right. But in the GNU C Library the implementation of `strchr` is optimized in a special way so that `strchr` actually is faster.

— Function: char * strrchr (const char *string, int c)

> The function `strrchr` is like `strchr`, except that it searches backwards from the end of the string string (instead of forwards from the front).

> For example,

>               strrchr ("hello, world", 'l')
>                   ⇒ "ld"

— Function: wchar_t * wcsrchr (const wchar_t *wstring, wchar_t c)

> The function `wcsrchr` is like `wcschr`, except that it searches backwards from the end of the string wstring (instead of forwards 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. If needle is an empty string, the function returns haystack.

> 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. If needle is an empty string, the function returns haystack.

— Function: wchar_t * wcswcs (const wchar_t *haystack, const wchar_t *needle)

> `wcswcs` is an deprecated alias for `wcsstr`. This is the name originally used in the X/Open Portability Guide before the Amendment 1 to ISO C90 was published.

— Function: char * strcasestr (const char *haystack, const char *needle)

> This is like `strstr`, except that it ignores case in searching for the substring. Like `strcasecmp`, it is locale dependent how uppercase and lowercase characters are related.

> For example,

>               strcasestr ("hello, world", "L")
>                   ⇒ "llo, world"
>               strcasestr ("hello, World", "wo")
>                   ⇒ "World"

— Function: void * memmem (const void *haystack, size_t haystack-len,
const void *needle, size_t needle-len)

> This is like `strstr`, but needle and haystack are byte arrays rather than null-terminated strings. needle-len is the length of needle and haystack-len is the length of haystack.

> This function is a GNU extension.

— Function: size_t strspn (const char *string, const char *skipset)

> The `strspn` (“string span”) function returns the length of the initial substring of string that consists entirely of characters that are members of the set specified by the string skipset. The order of the characters in skipset is not important.

> For example,

>               strspn ("hello, world", "abcdefghijklmnopqrstuvwxyz")
>                   ⇒ 5

> Note that “character” is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character 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_t wcsspn (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 string skipset. The order of the wide characters in skipset is not important.

— Function: size_t strcspn (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 are not members of the set specified by the string stopset. (In other words, it returns the offset of the first character in string that is a member of the set stopset.)

> For example,

>               strcspn ("hello, world", " \t\n,.;!?")
>                   ⇒ 5

> Note that “character” is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character 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_t wcscspn (const wchar_t *wstring, const wchar_t *stopset)

> The `wcscspn` (“wide character string complement span”) function returns the length of the initial substring of wstring that consists entirely of wide characters that are not members of the set specified by the string stopset. (In other words, it returns the offset of the first character in string that is a member of the set stopset.)

— Function: char * strpbrk (const char *string, const char *stopset)

> The `strpbrk` (“string pointer break”) function is related to `strcspn`, except that it returns a pointer to the first character in string 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 from stopset is found.

> For example,

>               strpbrk ("hello, world", " \t\n,.;!?")
>                   ⇒ ", world"

> Note that “character” is here used in the sense of byte. In a string using a multibyte character encoding (abstract) character 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 in wstring 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 from stopset is found.

#### 5.7.1 Compatibility String Search Functions

— Function: char * index (const char *string, int c)

> `index` is another name for `strchr`; they are exactly the same. New code should always use `strchr` since this name is defined in ISO C while `index` is a BSD invention which never was available on System V derived systems.

— Function: char * rindex (const char *string, int c)

> `rindex` is another name for `strrchr`; they are exactly the same. New code should always use `strrchr` since this name is defined in ISO C while `rindex` is a BSD invention which never was available on System V derived systems.