The GNU C Programming Tutorial - String library functions

Node:String library functions, Next:Questions for Chapter 15, Previous:String arrays, Up:Strings

String library functions

The GNU C Library provides a number of very useful functions which handle strings. Here is a list of the more common ones. To use the functions beginning with ato, you must include the header file stdlib.h; to use the functions beginning with str, you must include the header file string.h.

atof Converts an ASCII string to its floating-point equivalent; for example, converts -23.5 to the value -23.5.

#include <stdio.h>
#include <stdlib.h>

int main()
{
  double my_value;
  char my_string[] = "+1776.23";
  my_value = atof(my_string);
  printf("%f\n", my_value);

  return 0;
}

The output from the above code is 1776.230000.

atoi Converts an ASCII string to its integer equivalent; for example, converts -23.5 to the value -23.
```
int my_value;
char my_string[] = "-23.5";
my_value = atoi(my_string);
printf("%d\n", my_value);
```
atol Converts an ASCII string to its long integer equivalent; for example, converts +2000000000 to the value 2000000000.
```
long my_value;
char my_string[] = "+2000000000";
my_value = atol(my_string);
printf("%ld\n", my_value);
```
strcat Concatenates two strings: that is, joins them together into one string. Example:
```
char string1[50] = "Hello, ";
char string2[] = "world!\n";
strcat (string1, string2);
printf (string1);
```
The example above attaches the contents of string2 to the current contents of string1. The array string1 then contains the string Hello, world!\n.
Notice that string1 was declared to be 50 characters long, more than enough to contain the initial values of both string1 and string2. You must be careful to allocate enough space in the string variable that will receive the concatenated data; otherwise, your program is likely to crash. Again, on a GNU system, although your program won't run, nothing more drastic than an error message from the operating system is likely to occur in such a case.
strcmp Compares two strings and returns a value that indicates which string comes first alphabetically. Example:
```
int comparison;
char string1[] = "alpha";
char string2[] = "beta";

comparison = strcmp (string1, string2);
printf ("%d\n", comparison);
```
If the two strings are identical, strcmp returns 0. If the first string passed to strcmp comes alphabetically before the second (that is, the first string is "less than" the second one), strcmp returns a value less than 0. If the first string comes alphabetically after the second one (that is, the first string is "greater than" the second one), strcmp returns a value greater than zero. (Note that numbers come before letters in ASCII, and upper-case letters come before lower-case ones.)
The example above prints out -1, because alpha is alphabetically "less than" beta.
In all cases below, string1 comes alphabetically before string2, so strcmp(string1, string2) returns a negative value.

string1
string2
aaa
aab
aaa
aaba
aa
aaa
strcpy Copies a string into a string variable. Example:
```
char dest_string[50];
char source_string[] = "Are we not men?";

/* Example 1 */
strcpy (dest_string, source_string);
printf ("%s\n", dest_string);

/* Example 2 */
strcpy (dest_string, "Are we having fun yet?");
printf ("%s\n", dest_string);
```
The example above produces this output:
```
Are we not men?
Are we having fun yet?
```
Notes:
- The destination string in strcmp comes first, then the source string. This works in exactly the opposite way from the GNU/Linux shell command, cp.
- You can use strcmp to copy one string variable into another (Example 1), or to copy a string constant into a string variable (Example 2).
- Note the use of the characters %s in the printf statements to display a string, rather than %d to display an integer or %f to display a float.
strlen Returns an integer that gives the length of a string in characters, not including the null character at the end of the string. The following example displays the number 5.
```
int string_length
char my_string[] = "fnord";

string_length = strlen (my_string);
printf ("%d\n", string_length);
```
strncat Works like strcat, but concatenates only a specified number of characters. The example below displays the string Hello, world! Bye.
```
char string1[50] = "Hello, world! ";
char string2[] = "Bye now!";
strncat (string1, string2, 3);
printf ("%s\n", string1);
```
strncmp Works like strcmp, but compares only a specified number of characters of both strings. The example below displays 0, because dogberry and dogwood are identical for their first three characters.
```
int comparison;
char string1[] = "dogberry";
char string2[] = "dogwood";

comparison = strncmp (string1, string2, 3);
printf ("%d\n", comparison);
```
strncpy Works like strcpy, but copies only a specified number of characters. The example below displays the string Are we, because only the first six characters of source_string are being copied into dest_string.
```
char dest_string[50];
char source_string[] = "Are we not men?";

strncpy (dest_string, source_string, 6);
printf ("%s\n", dest_string);
```
Note: As in strcmp, the destination string in strncmp comes first, then the source string. This works in exactly the opposite way from the GNU/Linux shell command, cp.
strstr Tests whether a substring is present in a larger string. Returns a pointer to the first occurrence of the substring in the larger string, or zero if the substring is not present. (When the substring is empty, strstr returns a pointer to the first character of the larger string.)
The example below displays 'foo' is a substring of 'Got food?'..
```
char string1[] = "Got food?";
char string2[] = "foo";

if (strstr (string1, string2))
  printf("'%s' is a substring of '%s'.\n", string2, string1);
```