String and Memory Functions

Header file

• string.h contains the function prototypes and any other definitions that are needed

String Length - strlen

• size_t strlen(const char *str)
  • strlen returns the number of characters in str that preceed the terminating null ('\0') character

Copying - strcpy and strncpy

• char *strcpy(char *dst, const char *src)
  
  • Copy characters from src to dst (up to and including the terminating null character ('\0') of src)
• char *strncpy(char *dst, const char *src, size_t len)
  • Copy up to len characters from src to dst
  • If src is shorter than len, dst is filled to len characters with null characters
  • If src is longer than len characters, the string in dst is not terminated with a null character
• strcpy and strncpy return a pointer to dst
• If src and dst are overlapping string, the results of strcpy and strncpy are undefined

Catenation - strcat and strncat

• char *strcat(char *dst, const char *src)
  
  • Append (catenate) the string src onto the end of dst, beginning by overwriting the terminating null in dst and continuing until the terminating null character of src is copied to dst
• char *strncat(char *dst, const char *src, size_t len)
  • Copy up to len characters from src to dst
  • If src is longer than len characters, len characters are copied to dst followed by a null character (in other words, len+1 characters may be copied)
• strcat and strncat return a pointer to dst
• If src and dst are overlapping string, the results of strcat and strncat are undefined
• In most cases, assigning '\0' to dst[0] and then calling strncat is probably preferable to strncpy

Comparison - strcmp, strncmp, strxfrm and strcoll

• int strcmp(const char *str1, const char *str2)
  • Compare each character in str1 to the corresponding character in str2 until either a dissimilar character or a null terminator ('\0' character) is found
  • If both strings are identical up to and including the terminating '\0', 0 is returned
  • If str1[n] < str2[n], -1 is returned
  • If str1[n] > str2[n], 1 is returned
  • If str1 is shorter than str2 (for example, str1 points to "abc" and str2 points to "abcdefg"), -1 is returned
  • Likewise, if str1 is longer than str2, 1 is returned
• int strncmp(const char *str1, const char *str2, size_t len)
  • strncat behaves exactly like strcat, except that only the first len characters are compared if both strings contain more than len characters
  • If len is 0 or negative, both strings are assumed to be equal (even though no comparison is actually performed) and 0 is returned
• size_t strxfrm(char *dst, const char *src, size_t len)
  • strxfrm transforms src in a locale-specific manner so that, when compared to another strxfrmed string using strcmp the results appropriate for that locale.
  • Up to len-1 characters of the transformed string are copied into dst (which is null terminated) and the length of the newly created string in dst is returned.
  • If dst is a null pointer and len is 0, strxfrm simply returns the length of the string that would have been created.
• int strcoll(const char *str1, const char *str2)
  • strcoll behaves exactly like strcmp, except that the comparison is done in a locale-specific manner
    • strcoll may need to perform the equivalent of strxfrm internally on str1 and str2 before comparing them

Character Search - strchr and strrchr

• char *strchr(const char *str, int ch)
  • strchr finds the first occurrence of the character ch in the string str and returns a pointer to it.
  • If ch is not found, a null pointer is returned.
  • The null terminator is considered part of the string and strchr(str,'\0'); will always return a pointer to the terminating null character.
• char *strrchr(const char *str, int ch)
  • strrchr is similar to strchr except that a pointer to the last occurence of ch is found (i.e. the search begins on the `right' side of the string)

Character Set Search - strspn, strcspn and strpbrk

• size_t strspn(const char *str, const char *charset)
  • strspn counts (or `spans') the characters from str which match a character in charset, stopping when a character not in charset is found.
  • strspn returns the number of matching characters spanned.
• size_t strcspn(const char *str, const char *charset)
  • strcspn is similar to strspn, except that strcspn spans the characters from str which do not match any character in charset and stops when a character in charset is matched.
  • strcspn returns the number of non-matching characters spanned.
• char *strpbrk(const char *str, const char *charset)
  • strpbrk is similar to strcspn, except that strpbrk returns a pointer to the first character in str which matches a character in charset, or a null pointer if no matching characters are found.

String Tokens - strtok

• char *strtok(char *str, const char *charset)
  • strtok is used to break str into tokens separated by characters from charset, by the following method:
    • The first time strtok is called, str is specified as the first argument. strtok will first span any characters in str which match a character in charset. It will then remember the location of the first character which does not match a character in charset and span sequential characters which are not found in charset until a character matches one in charset. If a second matching character is found, it is replaced with a '\0' and the remembered pointer to the first non-matching character is returned.
    • On subsequent calls, a null pointer is passed as the first argument and strtok begins searching from the character immediately following the previously set '\0' character
  • For example:

    {
      char str[] = "The rain, in Spain, falls *mainly* in the plain.";
      char *tok;
    
      while (tok = strtok(str, " ,*S"))
    	printf("%s ", tok);
    }
    

    would print "The rain in pain falls mainly in the plain." and leave str set to:
    The\0rain\0 in\0 Spain\0 falls\0*mainly\0 in\0the\0plain.

Substring Search - strstr

• char *strstr(const char *str, const char *substr);
  • strstr finds the first occurence of substr in str and returns a pointer to the first character of the substring in str
  • If substr is not found in str, a null pointer is returned.
  • If substr is the empty string (that is, if the first character in substr is a null character) a pointer to the first character in str is returned.

Memory Functions

• void *memchr(const void *ptr, int ch, size_t len)
  • memchr finds the first occurence of ch in ptr and returns a pointer to it (or a null pointer if ch was not found in the first len bytes
• int memcmp(const void *ptr1, const void *ptr2, size_t len)
  • memcmp is similar to strcmp, except that bytes equal to 0 are not treated as comparison terminators.
• void *memcpy(void *dst, const void *src, size_t len)
  • memcpy copies len characters from src to dst and returns the original value of dst
  • The result of memcpy is undefined if src and dst point to overlapping areas of memory
• void *memmove(void *dst, const void *src, size_t len)
  • memmove is just like memcpy except that memmove is guaranteed to work even if the memory areas overlap
• void *memset(void *ptr, int byteval, size_t len)
  • memset sets the first len bytes of the memory area pointed to by ptr to the value specified by byteval

Numeric Translation - strtol, strtoul and strtod

• long strtol(const char *str, char **ptr, int base)
  • strtol converts the string pointed to by str into a long value.
  • The conversion is done according to the number system represented by base
    • base must either be the special value 0 or must be greater than or equal to 2 and less than or equal to 36
    • If base is greater than 10, the letter 'A' (or 'a') represents 10, 'B' or 'b' represents 11, ... 'Z' or 'z' represents 35
  • Conversion stops at the first character which is not a valid digit in the given base
  • If ptr is non-null, *ptr is set to the address of the first unrecognized character
  • If the first character is unrecognized, *ptr is set to str and 0 is returned
  • Conversion proceeds like this:
    • Leading whitespace is skipped.
    • There may be an initial + or - sign
    • If base is 16, any leading 0x or 0X is skipped
    • If base is non-zero:
      • Any leading 0s are skipped
      • Successive valid digits are converted until an unrecognized character is found
      • ptr is set to the address of the unrecognized character
      • The converted value is returned
    • If base is zero, the string itself determines the base into which the number is converted:
      • If the first character is a 0:
        • If the second character is x or X, base is assumed to be 16
        • Otherwise, base is assumed to be 8
      • Otherwise (if the first digit is not 0), base is assumed to be 10
      • After base has been determined, conversion proceeds as before
  • If the conversion results in overflow, strtol returns LONG_MAX.
  • If the conversion results in underflow, strtol returns LONG_MIN.
  • If either underflow or overflow occurs, errno is set to ERANGE
• unsigned long strtoul(const char *str, char **ptr, int base)
  • strtoul is virtually identical to strtol, except that:
    • -1 gets converted to ULONG_MAX (or something close to it)
    • It is impossible to underflow an unsigned long
    • On overflow, returns ULONG_MAX and sets errno to ERANGE.
• double strtod(const char *str, char **ptr)
  • strtod converts the string pointed to by str into a double value.
  • Conversion stops at the first unrecognized character.
  • If ptr is non-null, *ptr is set to the address of the first unrecognized character
  • If the first character is unrecognized, *ptr is set to str and 0.0 is returned.
  • Conversion proceeds like this:
    • Leading whitespace is skipped.
    • There may be an initial + or - sign
    • Successive decimal digits (as well as an optional radix character) are converted
      • The radix character is locale-specific, but is a period by default.
    • This may be optionally followed by:
      • A e or E
      • An optional + or - sign
      • An integer representing the expontent
    • ptr is set to the address of the unrecognized character
    • The converted value is returned
  • If the conversion results in overflow, strtod returns either +HUGE_MAX or -HUGE_MAX (depending on the sign of the value).
  • If the conversion results in underflow, strtod returns 0.
  • If either underflow or overflow occurs, errno is set to ERANGE

Old Conversion Functions - atoi, atol and atof

• These routines are still available but their use is discouraged; use strtol, strtoul and strtod instead
• int atoi(const char *str)
  • Similar to (int) strtol(str, (char **)NULL, 10)
• long atol(const char *str)
  • Similar to strtol(str, (char **)NULL, 10)
• double atof(const char *str)
  • Similar to strtod(str, (char **)NULL)