#include <string.h>

char *strcat (

   char       *s1,

   const char *s2

);

 stand-alone

strcat appends a copy of string s2 to the end of string s1.

A pointer to the NUL-terminated result is returned.

#include <string.h>

char *strchr (

   const char *pstr,

   int         cval

);

 stand-alone

strchr locates the first occurrence of cval (converted to a char) in the string pointed to by pstr. The terminating NUL character is considered to be part of the string.

The function returns a pointer to the located character, or a null pointer if the character does not occur in the string.

#include <string.h>

int strcmp (

   const char *s1,

   const char *s2

);

 stand-alone

strcmp compares its arguments and returns an integer greater than, equal to, or less than 0, depending on whether s1 is lexicographically greater than, equal to or less than s2.

#include <string.h>

int strcoll (

   const char *s1,

   const char *s2

);

 stand-alone

strcoll compares its arguments, interpreting both in the light of the LC_COLLATE category of the current locale. It then returns an integer greater than, equal to, or less than 0, depending on whether s1 is lexicographically greater than, equal to or less than s2.

Note that as the current version of Diamond supports only the "C" and "" locales, strcoll is equivalent to a call on strcmp.

#include <string.h>

char *strcpy (

   char       *s1,

   const char *s2

);

 stand-alone

strcpy copies string s2 to s1, stopping after the NUL character has been moved. s1 is returned.

If copying takes place between objects that overlap, the behaviour is undefined.

#include <string.h>

size_t strcspn (

   const char *s1,

   const char *s2

);

 stand-alone

strcspn calculates the length of the initial part of the string pointed to by s1 which consists of characters not from the string pointed to by s2. The terminating NUL character is not considered part of s2.

The function returns the length of the part in characters (octets).

#include <string.h>

char *strerror (

   int errnum

);

 stand-alone

This function maps the error number in errnum into a textual error message string, to which it returns a pointer.

For example, an errnum argument of EDOM might return a pointer to the string "domain error".

The caller must not modify the string whose address is returned by strerror. In addition, subsequent calls to strerror may overwrite this string with a new error message. Thus, if the result of strerror is not to be used immediately (for example, to be printed out) you should copy it elsewhere until needed to avoid it being overwritten.

#include <string.h>

size_t strlen (

   const char *pstr

);

 stand-alone

strlen returns the number of non-NUL characters in pstr.

#include <string.h>

char *strncat (

   char       *s1,

   const char *s2,

   size_t      num

);

 stand-alone

strncat appends a copy of string s2 to the end of string s1. It copies at most num characters (octets).

A pointer to the NUL-terminated result is returned.

#include <string.h>

int strncmp (

   const char *s1,

   const char *s2,

   size_t      num

);

 stand-alone

strncmp compares its arguments and returns an integer greater than, equal to, or less than 0, depending on whether s1 is lexicographically greater than, equal to or less than s2. At most num characters (octets) are examined.

#include <string.h>

char *strncpy (

   char       *s1,

   const char *s2,

   size_t      num

);

 stand-alone

strncpy copies string s2 to s1. Exactly num characters (octets) are copied: s2 is truncated or NUL-padded as required. The target need not be NUL-terminated if the length of s2 is num or more.

s1 is returned.

#include <string.h>

char *strpbrk (

   const char *str,

   const char *cset

);

 stand-alone

The strpbrk function scans the string pointed to by str for the first character in that string which is also contained in the string pointed to by cset.

It returns a pointer to this character once located. If the string pointed to by str does not contain any of the characters from the string pointed to by cset then strpbrk returns a null pointer.

The following example shows how strpbrk might be used to scan a string, replacing any vowels with the character '*':

char str[] = "this is some example text";

char *p;

while (p = strpbrk(str, "aeiouAEIOU")) *p = '*';

After execution of this code fragment, the array str would contain the string: "th*s *s s*me *x*mpl* t*xt".

#include <string.h>

char *strrchr (

   char *s,

   int c

);

 stand-alone

This function locates the last occurrence of c (converted to a char) in the string pointed to by s.

It returns a pointer to the located copy of c. If no copy of c can be located in the string, a null pointer is returned.

Note that strrchr treats the NUL character that terminates the string pointed to by s to be part of that string; therefore, a call such as strrchr(s,0) locates that NUL terminator.

#include <string.h>

size_t strspn (

   const char *s1,

   const char *s2

);

 stand-alone

strspn calculates the length of the initial part of the string pointed to by s1 which consists of characters from the string pointed to by s2.

The function returns the length of the segment in characters (octets).

#include <string.h>

char *strstr (

   const char *str,

   const char *sub

);

 stand-alone

This function searches within the string pointed to by str for the string pointed to by sub.

If the substring cannot be located, a null pointer is returned; otherwise, strstr returns a pointer to the first occurrence of the substring.  If sub points to an empty string (i.e., just to a NUL character) then strstr returns str.

As an example of the use of strstr, consider the following code fragment:

char *str = "The quick fox jumps.";

char *sub1 = "fox";

char *sub2 = "dog";

char *ans1 = strstr(str, sub1);

char *ans2 = strstr(str, sub2);

After the execution of this code fragment, ans1 contains a pointer to the part of str starting at "fox", i.e., "fox jumps.". On the other hand, str does not contain the substring "dog", so ans2 contains a null pointer.

#include <stdlib.h>

double strtod (

   const char  *nptr,

   char       **endptr

);

 stand-alone

Starting from the place pointed to by nptr, strtod skips over initial white space, then attempts to interpret characters as forming part of a floating-point constant. Conversion stops at the first character that does not fit into the format of the constant.

The format expected is:

The value of the constant is returned as the value of the function, and the object pointed to by endptr is set to point to the first character which is not converted (unless endptr is NULL).

If no conversion could be performed or if the string is empty, zero is returned, and the initial value of nptr is stored in the object pointed to by endptr (unless endptr is NULL).

If the value is out of range, +HUGE_VAL or –HUGE_VAL, depending on the sign of the value, is returned. If the value causes underflow, zero is returned. In both these cases, errno is set to ERANGE.

#include <string.h>

char *strtok (

   char       *s1,

   const char *s2

);

 stand-alone

strtok breaks the string pointed to by s1 into tokens, each of which is delimited by a character from the string pointed to by s2. The first use of strtok must have s1 pointing at a string. Subsequent use can either have s1 pointing at a new string or a null pointer as its first argument. If a null pointer is used, the function starts from the position the last call terminated. s2 can be different for each call.

The function returns a pointer to a token or a null pointer if there is no token found.

#include <stdlib.h>

long int strtol (

   const char  *nptr,

   char       **endptr,

   int          base

);

 stand-alone

This function converts the initial portion of the string pointed to by nptr to long int representation.

First the string is split into three parts:

Then it attempts to convert the subject string to an integer, and returns the result.

If the value of base is in the range 2–36, the expected form of the subject string is a sequence of digits and letters representing an integer with the radix specified in base. The letters a–z (or A–Z) are ascribed the values 10–35. Only those characters that are representations of values less than base are allowed. If base has the value 16, the characters "0x" (or "0X") may precede the sequence of letters and digits, but have no effect.

If the value of base is 0, the subject string is treated as hexadecimal (if it starts with "0x" or "0X"), octal (if it starts with '0') or decimal (for any other case).

All other values of base are illegal.

Uppercase letters are everywhere equivalent to lowercase ones, and the subject string may start with a plus or minus sign. However, suffixes (like 'L' or 'U') are not allowed.

The function attempts to detect overflows, and if this happens the value LONG_MAX or LONG_MIN is returned (these are defined in <limits.h> ), and errno is set to ERANGE.

If the subject string is empty, or base has an illegal value, then zero is returned, errno is set to EDOM, and the object pointed to by endptr is set to the value of nptr (unless endptr is equal to NULL); in all other cases, including overflows, this object is set to the address of the start of the final string.

The subject string is empty if, for example, the input string is empty or contains white space only.

Here are some other input strings whose subject strings are empty:

"-"

"+"

"0x"

"/"

"- 1"

"0x-5"

#include <stdlib.h>

unsigned long int strtoul (

   const char  *nptr,

   char       **endptr,

   int          base

);

 stand-alone

This function operates in the same way as strtol, except:

#include <string.h>

size_t strxfrm (

   char       *s1,

   const char *s2,

   size_t      n

);

 stand-alone

The function transforms the string pointed to by s2 and places the result in the string pointed to by s1.

The nature of this transformation is controlled by the LC_COLLATE category of the current locale, and the effect is that two strings that have been transformed in this way can be correctly compared using strcmp. A maximum of n characters (octets is transformed, including the final NUL character; in any case, transformation stops after a NUL character has been converted. strxfrm returns the number of characters which have been transformed, excluding the NUL character. The s1 argument may be NULL if n is zero.

Note that, as the current version of Diamond supports only the "C" and "" locales, this function simply performs a copy operation.