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'.
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.
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.
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).
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. It
would be better (but less portable) to use strchrnul
in this
case, though.
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.
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.
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.
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"
wcsrchr
is like wcschr
, except that it searches
backwards from the end of the string wstring (instead of forwards
from the front).
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"
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.
wcsstr
is an depricated alias for wcsstr
. This is the
name originally used in the X/Open Portability Guide before the
Amendment 1 to ISO C90 was published.
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,
strstr ("hello, world", "L") => "llo, world" strstr ("hello, World", "wo") => "World"
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.
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.
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.
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.
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.)
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.
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.
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.
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.
Go to the first, previous, next, last section, table of contents.