The character-classification functions take a single argument on which they perform a logical operation. The argument can have any value; it does not have to be an ASCII character. The isascii function determines if the argument is an ASCII character (0 through 177 octal). The other functions determine whether the argument is a particular type of ASCII character, such as a graphic character or digit. The isw * functions test wide characters. Character-classification information is in the LC_CTYPE category of the program's current locale.

For all functions, a positive return value indicates TRUE. A return value of 0 indicates FALSE.

To briefly reference the character-classification functions in a subsequent table, each function is assigned a number, as shown in Table 3-2.

Table 3-2 Character-Classification Functions

Function Number	Function	Function Number	Function
1	isalnum	7	islower
2	isalpha	8	isprint
3	isascii	9	ispunct
4	iscntrl	10	isspace
5	isdigit	11	isupper
6	isgraph	12	isxdigit

Table 3-3 lists the numbers of the functions (as assigned in Table 3-2) that return the value TRUE for each of the given ASCII characters. The numeric code represents the octal value of each of the ASCII characters.

Table 3-3 ASCII Characters and the Character-Classification Functions

ASCII Values	Function Numbers	ASCII Values	Function Numbers
NUL 00	3,4	@ 100	3,6,8,9
SOH 01	3,4	A 101	1,2,3,6,8,11,12
STX 02	3,4	B 102	1,2,3,6,8,11,12
ETX 03	3,4	C 103	1,2,3,6,8,11,12
EOT 04	3,4	D 104	1,2,3,6,8,11,12
ENQ 05	3,4	E 105	1,2,3,6,8,11,12
ACK 06	3,4	F 106	1,2,3,6,8,11,12
BEL 07	3,4	G 107	1,2,3,6,8,11
BS 10	3,4	H 110	1,2,3,6,8,11
HT 11	3,4,10	I 111	1,2,3,6,8,11
LF 12	3,4,10	J 112	1,2,3,6,8,11
VT 13	3,4,10	K 113	1,2,3,6,8,11
FF 14	3,4,10	L 114	1,2,3,6,8,11
CR 15	3,4,10	M 115	1,2,3,6,8,11
SO 16	3,4	N 116	1,2,3,6,8,11
SI 17	3,4	O 117	1,2,3,6,8,11
DLE 20	3,4	P 120	1,2,3,6,8,11
DC1 21	3,4	Q 121	1,2,3,6,8,11
DC2 22	3,4	R 122	1,2,3,6,8,11
DC3 23	3,4	S 123	1,2,3,6,8,11
DC4 24	3,4	T 124	1,2,3,6,8,11
NAK 25	3,4	U 125	1,2,3,6,8,11
SYN 26	3,4	V 126	1,2,3,6,8,11
ETB 27	3,4	W 127	1,2,3,6,8,11
CAN 30	3,4	X 130	1,2,3,6,8,11
EM 31	3,4	Y 131	1,2,3,6,8,11
SUB 32	3,4	Z 132	1,2,3,6,8,11
ESC 33	3,4	[ 133	3,6,8,9
FS 34	3,4	\ 134	3,6,8,9
GS 35	3,4	] 135	3,6,8,9
RS 36	3,4	^ 136	3,6,8,9
US 37	3,4	-- 137	3,6,8,9
SP 40	3,8,10	` 140	3,6,8,9
! 41	3,6,8,9	a 141	1,2,3,6,7,8,12
" 42	3,6,8,9	b 142	1,2,3,6,7,8,12
# 43	3,6,8,9	c 143	1,2,3,6,7,8,12
$ 44	3,6,8,9	d 144	1,2,3,6,7,8,12
% 45	3,6,8,9	e 145	1,2,3,6,7,8,12
& 46	3,6,8,9	f 146	1,2,3,6,7,8,12
' 47	3,6,8,9	g 147	1,2,3,6,7,8
( 50	3,6,8,9	h 150	1,2,3,6,7,8
) 51	3,6,8,9	i 151	1,2,3,6,7,8
* 52	3,6,8,9	j 152	1,2,3,6,7,8
+ 53	3,6,8,9	k 153	1,2,3,6,7,8
' 54	3,6,8,9	l 154	1,2,3,6,7,8
- 55	3,6,8,9	m 155	1,2,3,6,7,8
. 56	3,6,8,9	n 156	1,2,3,6,7,8
/ 57	3,6,8,9	o 157	1,2,3,6,7,8
0 60	1,3,5,6,8,12	p 160	1,2,3,6,7,8
1 61	1,3,5,6,8,12	q 161	1,2,3,6,7,8
2 62	1,3,5,6,8,12	r 162	1,2,3,6,7,8
3 63	1,3,5,6,8,12	s 163	1,2,3,6,7,8
4 64	1,3,5,6,8,12	t 164	1,2,3,6,7,8
5 65	1,3,5,6,8,12	u 165	1,2,3,6,7,8
6 66	1,3,5,6,8,12	v 166	1,2,3,6,7,8
7 67	1,3,5,6,8,12	w 167	1,2,3,6,7,8
8 70	1,3,5,6,8,12	x 170	1,2,3,5,6,8
9 71	1,3,5,6,8,12	y 171	1,2,3,5,6,8
: 72	3,6,8,9	z 172	1,2,3,5,6,8
; 73	3,6,8,9	{ 173	3,6,8,9
< 74	3,6,8,9	| 174	3,6,8,9
= 75	3,6,8,9	} 175	3,6,8,9
> 76	3,6,8,9	~ 176	3,6,8,9
? 77	3,6,8,9	DEL 177	3,4

Example 3-1 shows how the character-classification functions are used.

Example 3-1 Character-Classification Functions

/* CHAP_3_CHARCLASS.C */ /* This example uses the isalpha, isdigit, and isspace */ /* functions to count the number of occurrences of letters, */ /* digits, and white-space characters entered through the */ /* standard input (stdin). */ #include <ctype.h> #include <stdio.h> #include <stdlib.h> main() { char c; int i = 0, j = 0, k = 0; while ((c = getchar()) != EOF) { if (isalpha(c)) i++; if (isdigit(c)) j++; if (isspace(c)) k++; } printf("Number of letters: %d\n", i); printf("Number of digits: %d\n", j); printf("Number of spaces: %d\n", k); }

The sample input and output from Example 3-1 follows:

$ RUN EXAMPLE1 I saw 35 people riding bicycles on Main Street.[Return] [Ctrl/Z] Number of letters: 36 Number of digits: 2 Number of spaces: 8 $

3.2 Character-Conversion Functions

The character-conversion functions convert one type of character to another type. These functions include:

ecvt _tolower fcvt toupper gcvt _toupper mbtowc towctrans mbrtowc wctrans mbsrtowcs wcrtomb toascii wcsrtombs tolower

For more information on each of these functions, see the Reference Section.

Example 3-2 shows how to use the ecvt function.

Example 3-2 Converting Double Values to an ASCII String

/* CHAP_3_CHARCONV.C */ /* This program uses the ecvt function to convert a double */ /* value to a string. The program then prints the string. */ #include <stdio.h> #include <stdlib.h> #include <unixlib.h> #include <string.h> main() { double val; /* Value to be converted */ int sign, /* Variables for sign */ point; /* and decimal place */ /* Array for the converted string */ static char string[20]; val = -3.1297830e-10; printf("original value: %e\n", val); if (sign) printf("value is negative\n"); else printf("value is positive\n"); printf("decimal point at %d\n", point); }

The output from Example 3-2 is as follows:

$ RUN EXAMPLE2 original value: -3.129783e-10 converted string: 31298 value is negative decimal point at -9 $

Example 3-3 shows how to use the toupper and tolower functions.

Example 3-3 Changing Characters to and from Uppercase Letters

/* CHAP_3_CONV_UPPERLOWER.C */ /* This program uses the functions toupper and tolower to */ /* convert uppercase to lowercase and lowercase to uppercase */ /* using input from the standard input (stdin). */ #include <ctype.h> #include <stdio.h> /* To use EOF identifier */ #include <stdlib.h> main() { char c, ch; while ((c = getchar()) != EOF) { if (c >= 'A' && c <= 'Z') ch = tolower(c); else ch = toupper(c); putchar(ch); } }

Sample input and output from Example 3-3 are as follows:

$ RUN EXAMPLE3 LET'S GO TO THE welcome INN.[Ctrl/Z] let's go to the WELCOME inn. $

3.3 String and Argument-List Functions

The HP C RTL contains a group of functions that manipulate strings. Some of these functions concatenate strings; others search a string for specific characters or perform some other comparison, such as determining the equality of two strings.

The HP C RTL also contains a set of functions that allow you to copy buffers containing binary data.

The set of functions defined and declared in the <varargs.h> and the <stdarg.h> header files provide a method of accessing variable-length argument lists. The <stdarg.h> functions are defined by the ANSI C Standard and are more portable than those defined in <varargs.h> .

The RTL functions such as printf and execl , for example, use variable-length argument lists. User-defined functions with variable-length argument lists that do not use <varargs.h> or <stdarg.h> are not portable due to the different argument-passing conventions of various machines.

The <stdarg.h> header file does not contain va_alist and va_dcl . The following shows a syntax example when using <stdarg.h> :

function_name(int arg1, ...) { va_list ap; . . .

When using <varargs.h> :

• The identifier va_alist is a parameter in the function definition.
• va_dcl declares the parameter va_alist, a declaration that is not terminated with a semicolon (;).
• The type va_list is used in the declaration of the variable used to traverse the list. You must declare at least one variable of type va_list when using <varargs.h> .

These names and declarations have the following syntax:

function_name(int arg1, ...) { va_list ap; . . .

3.4 Program Examples

Example 3-4 shows how to use the strcat and strncat functions.

Example 3-4 Concatenating Two Strings

/* CHAP_3_CONCAT.C */ /* This example uses strcat and strncat to concatenate two */ /* strings. */ #include <stdio.h> #include <string.h> main() { static char string1[80] = "Concatenates "; static char string2[] = "two strings "; static char string3[] = "up to a maximum of characters."; static char string4[] = "imum number of characters"; printf("strcat:\t%s\n", strcat(string1, string2)); printf("strncat ( 0):\t%s\n", strncat(string1, string3, 0)); printf("strncat (11):\t%s\n", strncat(string1, string3, 11)); printf("strncat (40):\t%s\n", strncat(string1, string4, 40)); }

Example 3-4 produces the following output:

$ RUN EXAMPLE1 strcat: Concatenates two strings strncat ( 0): Concatenates two strings strncat (11): Concatenates two strings up to a max strncat (40): Concatenates two strings up to a maximum number of characters. $

Example 3-5 shows how to use the strcspn function.

Example 3-5 Four Arguments to the strcspn Function

/* CHAP_3_STRCSPN.C */ /* This example shows how strcspn interprets four */ /* different kinds of arguments. */ #include <stdio.h> main() { printf("strcspn with null charset: %d\n", strcspn("abcdef", "")); printf("strcspn with null string: %d\n", strcspn("", "abcdef")); printf("strcspn(\"xabc\", \"abc\"): %d\n", strcspn("xabc", "abc")); printf("strcspn(\"abc\", \"def\"): %d\n", strcspn("abc", "def")); }

The sample output, to the file strcspn.out , in Example 3-5 is as follows:

$ RUN EXAMPLE2 strcspn with null charset: 6 strcspn with null string: 0 strcspn("xabc","abc"): 1 strcspn("abc","def"): 3

Example 3-6 shows how to use the <stdarg.h> functions and definitions.

Example 3-6 Using the <stdarg.h > Functions and Definitions

/* CHAP_3_STDARG.C */ /* This routine accepts a variable number of string arguments, */ /* preceded by a count of the number of such strings. It */ /* allocates enough space in which to concatenate all of the */ /* strings, concatenates them together, and returns the address */ /* of the new string. It returns NULL if there are no string */ /* arguments, or if they are all null strings. */ #include <stdarg.h> /* Include appropriate header files */ #include <stdlib.h> /* for the "example" call in main. */ #include <string.h> #include <stdio.h> /* NSTRINGS is the maximum number of string arguments accepted */ /* (arbitrary). */ #define NSTRINGS 10 char *concatenate(int n,...) { va_list ap; /* Declare the argument pointer. */ char *list[NSTRINGS], *string; int index = 0, size = 0; /* Check that the number of arguments is within range. */ if (n <= 0) return NULL; if (n > NSTRINGS) n = NSTRINGS; va_start(ap, n); /* Initialize the argument pointer. */ do { /* Extract the next argument and save it. */ list[index] = va_arg(ap, char *); size += strlen(list[index]); } while (++index < n); va_end(ap); /* Terminate use of ap. */ if (size == 0) return NULL; string = malloc(size + 1); string[0] = '\0'; /* Append each argument to the end of the growing result */ /* string. */ for (index = 0; index < n; ++index) strcat(string, list[index]); return string; } /* An example of calling this routine is */ main() { char *ret_string ; ret_string = concatenate(7, "This ", "message ", "is ", "built with ", "a", " variable arg", " list.") ; puts(ret_string) ; }

The call to Example 3-6 produces the following output:

This message is built with a variable arg list.