Idioms for C programmers
Idioms for C programmers
This document collects some idiomatic examples of the C way of doing things. None of these examples have been tested. Please report errors or difficulties to comp40-staff.
For the include statements, I've inserted a backslash before the statement, because the generator for this document deletes them otherwise. When you put include statements in our programs, don't put a backslash in.
Table of Contents
Reading from standard input or from one or more files named on the command line
Reading one line of input
Design poisons for line-oriented input
Getting rid of "Unused variable" warnings
Comparing strings
Hanson's idiom for constant-time string comparison
Printing strings separated by commas
Using List_map to print strings separated by newlines
More detail on the indirections:
Idioms for void ** pointers
Type abbreviations for structure types
Using an abstraction defined in an interface Foo
Handling void * values of known type
Using unboxed arrays
Initializing array elements
Storing values into an unboxed array
Example of array of arrays
Allocating memory
Writing long string literals
Printing integers of known width
Reading from standard input or from one or more files named on the command line
The idea is to separate out the processing of an open file handle from the process of finding one or more open file handles. Idiom adapted from Kernighan and Ritchie, page 162, for a program without options:
#include <stdio.h>
extern void do_something(FILE *fp);
int main(int argc, char *argv[])
{
if (argc == 1) {
do_something(stdin);
} else {
for (int i = 1; i < argc; i++) {
FILE *fp = fopen(argv[i], "r");
if (fp == NULL) {
fprintf(stderr,
"%s: %s %s %s\n",
argv[0], "Could not open file ",
argv[i], "for reading");
exit(1);
}
do_something(fp);
fclose(fp);
}
}
}
Here's another approach:
\#include <stdio.h>
\#include <errno.h>
\#include <stdlib.h>
extern void do_something(FILE *fp);
static FILE *open_or_abort(char *fname, char *mode);
int main(int argc, char *argv[])
{
if (argc == 1) {
do_something(stdin);
} else {
for (int i = 1; i < argc; i++) {
FILE *fp = open_or_abort(argv[i], "r");
do_something(fp);
fclose(fp);
}
}
}
static FILE *open_or_abort(char *fname, char *mode)
{
FILE *fp = fopen(fname, mode);
if (fp == NULL) {
int rc = errno;
fprintf(stderr,
"Could not open file %s with mode %s\n",
fname,
mode);
exit(rc);
}
return fp;
}
Idiom for OS-specific error message on failing to open a file:
perror(argv[i]); /* print the filename with message about *why* fopen() failed */
Idiom for elaborate error messsage:
\#include <errno.h>
\#include <string.h>
...
fprintf(stderr, "%s: could not open %s (%s)\n",
argv[0], argv[i], strerror(errno));
Reading one line of input
The correct idiom for reading input is to
Allocate a buffer
Call fgets
Allocation may be static or dynamic. The main issue is how to recover if fgets does not return an entire line. Assuming you can't just halt the program with an error message, these are your options:
If your buffer is dynamically allocated, you can enlarge it and continue to read.
If your buffer is statically allocated, you should
Consume any characters remaining in the line
Indicate some sort of error condition and continue
Design poisons for line-oriented input
Here are some things to avoid when doing input one line at a time:
Never use gets; it's unsafe (because it can walk over more memory than you expect if the input is long).
Don't use scanf, especially not for interactive programs. It's too easy for scanf to become greedy and gobble up more than one line, especially if the input doesn't meet specifications.
If you have the urge to use the scanf interface, which can be quite useful, use fgets to read the line and then sscanf (note the extra 's') to read the pieces.
Getting rid of "Unused variable" warnings
Sometimes a contract insists that a function have certain arguments, but in some implementation you may not use the arguments. It may be that you don't use argc and argv in main, for example. Comp 40 does not permit you to have compile time warnings, so what can you do? This:
int main(int argc, char *argv[])
{
(void) argc;
(void) argv;
...
}
Comparing strings
Gotcha alert! The C++ strings you are used to do not exist in C. In C, you simulate a string by a char * pointer, which points to a sequence of bytes ending in '\0'. This style causes all sorts of problems, most notably
const char *s1, *s2; /* strings in the neighborhood */
if (s1 == s2) { /* SILENTLY GIVES WRONG ANSWERS */
...
/* go here only if *pointers* are identical */
...
}
The standard idiom for comparing strings is
if (strcmp(s1, s2) == 0) {
...
/* strings are equal here */
...
}
Old-fashioned C programmers often write (but you should not)
if (!strcmp(s1, s2)) {
...
/* strings are equal here */
...
}
The exclamation mark is easy to overlook, and the uncertain relationship between booleans, success/failure codes, and other finite conditions makes such code less clear. If the return value is intended as a boolean, then omit an explicit test; otherwise, put in an explicit test.
Problem: comparing equal strings costs time proportional to the length of the string.
Hanson's idiom for constant-time string comparison
Hanson's Atom_new or Atom_string functions use a shared hash table to ensure that equal strings are represented by identical pointers. A single Atom_new is more expensive than a single strcmp, but when you are using strings in data structures, you will recover the cost by saving comparisons down the road. You may also save memory. One idiom is
const char *s1, *s2; /* strings in the neighborhood */
s1 = Atom_string(s1); /* hash strings to unique pointers */
s2 = Atom_string(s2);
...
if (s1 == s2) {
...
/* strings are guaranteed equal */
...
}
The behavior is neatly expressed mathematically:
Atom_string(s1) == Atom_string(s2) if and only if strcmp(s1, s2) == 0.
You use Atom_new if you want to create atomic strings that contain zeroes, as you might in some binary network protocols.
Printing strings separated by commas
This idiom is notable for its simple control flow. It can be generalized to other separators besides commas and other things to print besides strings.
\#include <stdio.h>
...
const char *prefix = "";
for (int i = 0; i < nthings; i++) {
printf("%s%s", prefix, things[i]);
prefix = ", ";
}
Notice that to reuse this code, you'll have to reset prefix. If this code is in a function, it will get reset.
Using List_map to print strings separated by newlines
For a list we'd like to write
const char *prefix = "";
foreach name in list { /* the iteration abstraction does not exist in C */
printf("%s%s", prefix, name);
prefix = "\n";
}
Using the List_map interface, name will be pointed to by a parameter, and prefix will have to be stored in the "closure" state which persists across iterations.
Here's the state:
struct inner_state {
const char *prefix;
};
And here's the apply function:
static void inner_apply(void **x, void *cl)
{
struct inner_state *s = cl;
char *name = *x; /* x is &(x->first), so *x is p->first */
printf(cl->prefix, name);
cl->prefix = "\n";
}
Now we rewrit the code to assign the initial state and then call List_map in place of the loop:
struct inner_state s;
s.prefix = "";
List_map(list, inner_apply, &s);
Again, the prefix is still a newline after the call to List_map. A good idea is to write a print function that encapsulates the state structure and the call to List_map.
More detail on the indirections:
The indirections look like this:
p->first points to the sequence of characters "hello"
&p->first points to p->first
the void **x that is passed to inner_apply is &p->first
*x has type void * and is p->first, so we can assign it to char *name without a cast
Idioms for void ** pointers
A void ** pointer almost always means "pass by reference a pointer to an unknown type. Here are a couple of idioms:
To produce a value of type void ** always use &p, where p is a pointer of type void *.
To consume or observe a value of type void **, first you have to know what the unknown type is. For sake of argument let us assume that the unknown type is 'struct date'. Then you dereference the void ** pointer and put the result in a pointer of correct type:
static struct date *d;
void set_d_by_reference(void **ref)
{
d = *ref;
}
No cast is needed, because *ref has type void * and so can be assigned to any pointer variable.
Type abbreviations for structure types
Idiom #1: Hanson style (the type abbreviation includes a pointer):
typedef struct foo *Foo;
...
Foo f;
Idiom #2: Bell Labs style (the type abbreviation does not include a pointer):
typedef struct foo foo;
...
foo *f;
Poison: mixing the two styles!
Note: you'll sometimes see capitalized names used with Bell Labs style. I've never seen lowercase names used with Hanson style.
Using an abstraction defined in an interface Foo
Many abstractions require memory allocated dynamically on the heap. To use such abstractions correctly, without leaking memory, you must balance every allocation with a free. Here is a recipe:
Foo_T foo = Foo_new(...arguments...);
assert(foo != NULL);
...
/* operations on foo, including calling functions that use foo */
...
Foo_free(&foo); /* free *foo and set foo to NULL */
Handling void * values of known type
Suppose we are using qsort to sort an array of strings, where each string is represented by a char * pointer. No sane person wants to deal with typecasting, so we write the comparison function this way:
static int compare(const void *p1, const void *p2)
{
const char * const *ps1 = p1;
const char * const *ps2 = p2;
return strcmp(*ps1, *ps2);
}
The idiom is that if you have a void * value of known type, you immediately assign it to a variable of that type. No explicit cast is needed. Here's another example:
struct node *p = Table_get(t, Atom_string("root"));
Using unboxed arrays
Be alert that I have retired Hanson's Array abstraction. I have replaced it with `UArray', an abstraction of unboxed arrays. (The implementation is exactly what's in the book, but the interface is different.)
Suppose array a is an unboxed UArray_T containing values of type struct pixel. Here's how you get a pointer to the ith element:
The Ramsey approach:
struct pixel *p = UArray_at(a, i); /* capture pointer into the array
* (valid until resized or freed)
*/
assert(sizeof(*p) == UArray_size(a));
... *p ... /* use expression of struct type */
This idiom is robust against changes in type. Why? It has a single point of truth, that is, the type is mentioned in only one place. In Hanson's book, you will see types mentioned in multiple places, and it is easier to write inconsistent
code. That's one reason I've retired Hanson's arrays. (The other is that students found them hard to learn.)
Initializing array elements
Here's an idiom for initializing element i of an array with an empty Set_T:
Set_T *setp = UArray_at(array, i);
assert(sizeof(*setp) == UArray_size(array));
*setp = Set_new(10, NULL, NULL);
Storing values into an unboxed array
Suppose function f() returns a value of type struct pixel you want to store in an unboxed array. Here's how you do it:
struct pixel *p = Array_at(a, i); /* capture pointer into the array
* (valid until resized or freed)
*/
assert(Array_size(a) == sizeof(*p)); /* detects some errors */
*p = f();
Example of array of arrays
Here I initialize and use an array of arrays. Suppose you want a UArray_T of UArray_T of double:
/* n elements of type UArray_T */
UArray_T outer = UArray_new(n, sizeof(UArray_T));
for (i = 0; i < n; i++) {
UArray_T inner_array = UArray_new(length_of_row(i),
sizeof(double));
/* variable number of elements in each inner array */
for (j = 0; j < UArray_length(inner_array), j++) {
double *elemp = UArray_at(inner_array, j);
*elemp = 0..0; /* initial value of element */
}
/* point to slot for inner array */
UArray_T *innerp = UArray_at(outer, i);
*innerp = inner_array;
}
Now to access element (i, j), I remember that UArray_at returns a pointer to an element:
UArray_T *p = UArray_at(outer, i);
assert(sizeof(*p) == UArray_size(outer));
UArray_T inner_array = *p;
double *q = UArray_at(inner_array, j);
assert(sizeof(*q)) == UArray_size(inner_array);
return *q;
Allocating memory
The following anti-idiom, although seen frequently in the code of those who have not been taught better, is anathema to C programmers:
Thing_T p = malloc(sizeof(struct Thing_T)); /* not acceptable */
assert(p != NULL);
Such code is not acceptable for COMP 40:
It's easy to leave out the struct, in which case you have a memory error. valgrind will probably catch it, but it shouldn't happen in the first place.
There is no single point of truth about what the type of p is. In particular, suppose the program evolves to this:
NewThing_T p = malloc(sizeof(struct Thing_T)); /* actually wrong */
assert(p != NULL);
The correct way to write these allocations is with a single point of truth:
Thing_T p = malloc(sizeof(*p)); /* established C idiom */
assert(p != NULL);
This code is good because
There is a single point of truth about the type of p. If that type changes, the code adjusts automatically and is still correct.
If the name of p changes, you have at least a fighting chance of getting a decent error message from the compiler.
This business of allocation and deallocation is so tricky that we recommend you use Hanson's macros:
Thing_T p;
NEW(p); // the assertion is included in NEW
Writing long string literals
It can be difficult to cram a long printf or fprintf call into 80 columns. Exploit this unusual property of C: adjacent string literals are concatenated at compile time.
Example:
fprintf(stderr, "%s: Things have gone horribly wrong: "
"%s is a file format I don't recognize, "
"I can't find any bytes on standard input, "
"and the dog ate %d pages of my homework!\n",
argv[0], argv[1], n - 1);
Note especially there are no commas between the literals.
This idiom also enables many scurvy tricks with the C preprocessor.
Printing integers of known width
The designers of C, unlike the designers of Java, decided that programmers did not need to know how many bits are in a type like int or unsigned long. As a result, it is nearly impossible to write code that is portable against changes in the size of a machine word.
This problem was fixed in C99 with the introduction of the <inttypes.h> interface, which contains a variety of .integer types and some print macros. Most of you will need it only for printing. Here are some examples of the C99 idiom for printing integers of known sizes:
\#include <stdio.h>
\#include <stdlib.h>
\#include <inttypes.h>
int main()
{
uint64_t big = (uint64_t)1 << 63;
int16_t negative = ~(int16_t)0;
printf("%" PRIu64 " is a large number, as we can see by its"
" hex\nrepresentation 0x%016" PRIx64 ".\n%" PRId16 " is a "
" negative number of very small magnitude.\n",
big, big, negative);
return 0;
}
Macros PRIu64, PRIx64, and PRId16 are like a regular u, x, or d, except correctly sized for 64-bit, 64-bit, and 16-bit integers respectively.
Back to class home page