I'm looking for a few kinds of feedback here.
First, there is a program at the end of this post that has a
function kgets() that I would like any feedback on - including
style.
Second, for those that are interested, I present an outline of
the approach I am looking at using in class this semester. I
would be very interesting in any feedback on that, but if you are
not interested, feel free to skip over it.
Third, I present a conceptual model of the input buffer to my
students and want to get feedback on whether or not it is
sufficiently accurate.
This is a long post - longer than what I had intended when I
started. I won't be offended if you skip the whole thing and move
on to the next person's post.
=============== =============== =============== =====
Proposed Teaching Approach
Motive: It seems that when I follow the typical course syllabus
that starts with formatted I/O and treats all of the underlying
details as a black box for about two-thirds of the semester that
the students have an enormous struggle grasping pointers,
null-terminated strings, the difference between numbers stored as
ASCII strings and numbers stored as unformatted bytes,
structures, and a whole host of other "advanced" topics. A year
ago I tried starting with what I called a "Card Math" module
where I invented a fictitious microprocessor that had just a few
basic instructions and I spent two weeks walking them from the
most basic SET statement and showing what indirection is and how
to use it and progressed to how all of the basic flowchart
topologies for structured programming can be implemented using a
simple conditional SKP instruction combined with unconditional
JMP instructions. We then mapped these code fragments to the
different parts of all of the flow control devices available in
C. They wrote a couple of short programs in this pseudo assembly
language, including a selection sort routine, and had to
translate the assembly into OP codes manually and had to execute
the program manually with pencil and paper.
The results were mixed - about half the class seemed to grasp
what was going on and the other half really struggled. A few
students commented, some then and some at the end of the
semester, that the exercise was very enlightening and one student
said at the end of the first two weeks, "Now I understand
pointers!" - this particular student had a semester of Java, I
believe, before taking my course.
Even though the rest seemed, on the surface, not to grasp what
was going on, I noticed later in the semester that, overall,
there did seem to be quite a bit fewer problems working with
pointers and structures and the like. So I think I am on the
right track but think I need to find an exercise that will make a
better connection for the typical student.
Approach: I am starting out with some short programs that only
use putc() and getc() for everything.
The first one is, of course, Hello World! and only uses putc().
Even with so few elements in the program, I am able to walk down
the program element by element and discuss the "low level"
details of what is going on in the context of that element. So
the very first program I get to go into the #include directive,
function headers, prototypes (for the putc() function), passing
by value and by reference (since putc() uses both), bits, bytes,
unsigned binary, the ASCII code, character escape sequences, and
function return values. A pretty amazing range of topics for so
few high-level elements. My hope is that, with so few elements
(for instance, no strings, no flow control structures, and no
variables) to get lost in, they can do a better job focusing on
the details we are discussing.
In the second program I only add an example of an object-like
macro and a function-like macro (the LF and PutC() macros below)
and cover them in some detail including the issues associated
with using parens to ensure proper evaluation (what I call the
"Golden Rules of Macros) and even the issue of macros that
evaluate an argument multiple times if that argument contains
side effects.
The third program we write the PutS() function that is included
below and now I can get into strings and string literals,
pointers, dereferencing pointers, pointer arithmetic, and how (at
least conceptually) a string literal is stored and converted to a
pointer constant and therefore not only why one can be used as an
argument to PutS() but also why it is a Bad Thing to modify one.
That brings us to the fourth program which is what is below. The
new element here is this function called kgets() - which will
also be the first time we are actually using getc(). By going
through the mechanics of reading in a string from the keyboard
character by character I can discuss a conceptual model of the
input buffer (a few questions on that later), one dimensional
arrays, the dangers of exceeding array bounds, how a string can
be read in such that it doesn't exceed the available memory,
determining if the string was completely read in, stripping the
newline character from a string, clearing out the input buffer,
and returning a value that can be used to tell how many, if any,
characters had to be read and discarded.
The fifth program will start with the question of how many
characters got discarded? Since we only have the ability to
output characters, we will have to write a function that takes an
integer value and converts it to character output one digit at a
time. We will then expand that to take a format string that
controls how the integer is displayed and will implement most of
the options that can used with the %i printf() format specifier.
We'll also write a simple function that can get a character or a
char, long, or long int from the keyboard. The hope here is that
they will gain a strong appreciation for the difference between a
character string representation of a number and the binary
representation of it. I also hope it will put them on a good
footing to understand the format string when we get to formatted
I/O and the importance of matching the specifiers to the
arguments properly.
The sixth program will get us to the printb() function I posted a
week or so ago that will let us examine the actual bit
representations of different objects and hence get into floating
point and IEEE representations .
At each stage I am making a point of mentioning what elements are
and are not implementation dependent. Most of their homework, up
to this point, will be implementing their versions of many of the
standard library functions from ctype.h, stdio.h, and string.h.
At about this point we will hit file I/O, including unformatted
I/O, and will start working with some type of standard file
format. Over the course of several weeks we will work towards a
reasonably complex goal. In the past I have done BMP (they wrote
a program to create a linked list that was used recursively to
create a Kock snowflake and the write an image to a bitmap file)
and WAV files (they wrote a program that could create a wave file
that, when played over a speaker with a phone handset nearby,
would dial the phone).
=============== =============== =============== =====
Conceptual Model of Input Buffer (fast draft of the lesson)
First off - this is purely a conceptual model. The actual
implementations may not resemble this in any way. What we are
trying to accomplish here is an understandable description of how
the input buffer behaves as far as our program's interaction with
it is concerned.
FIFO Model - A block of memory having two pointers. The first
pointer (the READ pointer) points at the leading character in the
FIFO and the second pointer (the WRITE pointer) points at the
location where the next character will be written to the FIFO -
so it points to the spot just after the trailing character in the
FIF0. If the READ and WRITE pointers point at the same location,
then the FIFO is empty and cannot be read from. Whenever
something is written to the FIFO it is placed at the position of
the WRITE pointer and the WRITE pointer is incremented. Whenever
something is read, the value returned is the value at the
position pointed to by the READ pointer and the READ pointer is
incremented. For our purposes, we'll assume that the FIFO is
large enough that we never fill it up - meaning that we are
reading data out of it, on average, as fast as data is being
written to it and that we never get far enough behind at any time
to cause a problem.
Now imagine two FIFOs. One is controlled by the operating system
and the second is controlled by our program.
Every time a key is pressed its code is written to the system's
FIFO. This includes the newline code associated with hitting the
Enter key. These codes may or may not be ASCII - it doesn't
matter because, at some point before we interact with the data,
they will be converted to ASCII codes (since our implementation
uses ASCII as its character set).
The second FIFO is controlled by our program, but in a way that
we have very little control over. Whenever we request input from
the standard input device using functions such as getc(), gets(),
fgets(), scanf(), etc, etc, they read characters from the second
FIFO. If that FIFO is empty - or empties before we have read the
requested amount of data from it, then characters are transferred
from the first FIFO (by reading them from the first FIFO and
writing them to the second FIFO) until a newline character is
transferred. Hence data is transferred from the system's FIFO to
the program's FIFO one line - and an entire line - at a time.
It's important to note that whenever the program has to transfer
another line of data from the system's FIFO nothing else will
happen until that newline character is transferred. This means
that if you ask for just a single character but the program's
FIFO is empty and the system's FIFO doesn't have a newline
character in it, that the program will stall until the User
eventually hits the Enter key. It also means that if the User
enters more characters than we need on a given line, that the
remaining characters will remain in the program's FIFO and will
be read out the next time we ask for input. This applies to the
newline character as much as any other character. This may or may
not be the behavior we want but, regardless, it is our
responsibility to deal with it. Functions like scanf() make this
very difficult to do, which is why its use is strongly
discouraged by many programmers. If you do use scanf(), the fine
details of how the input characters are read and skipped becomes
vitally important if you are mixing numeric and character input
and great care must be taken to be sure that the program behaves
as desired.
/* At this point I run a program where the behavior is not as
expected and then walk through the code by hand using this
FIFO-based model on the board and show that what happens is would
actually is expected, just not what is wanted, when the input
doesn't match what was asked for or when numeric data and string
data are mixed without taking this into account. */
With the standard library functions, we have no way of knowing
whether anything is presently in the program's FIFO or the
system's FIFO, so we can't just check it and see because, if they
are empty, our program will hang until the User hits the Return
key. But, when we do get input from the program's FIFO, we can
take steps to keep track of whether we have seen the newline
character and, if we haven't, then we have the option of reading
characters one at a time until we do read the newline character.
What we do with these characters is completely up to is - the key
issue is that, at this point, we know that the program's FIFO is
empty and that any and all additional characters that have been
entered by the User are sitting in the system's FIFO.
Many implementations include functions that interact directly
with the system's FIFO. For us, that includes functions such as
kbhit() and getch() from the conio.h library. While these
functions give us capabilities that we can't achieve with the
standard library functions, they are not Standard C compliant. If
you are going to use them, especially if you are also using the
standard library functions as well, then it is important to
understand that a given character, once it is read from the
system's FIFO to the program's FIFO by one of the standard
library functions, is inaccessible to the conio functions.
Similarly, if a character is read from the system's FIFO by one
of the conio functions then that character will not be part of
the data that eventually gets transferred to the program's FIFO.
Hence, if you are going to mix these functions, you should be
very careful to ensure that both FIFO's are in an acceptable
state before you switch to the other type of input function.
/* At least up to this point, with our compiler, I haven't run
across any behavior that wasn't explained by this model - even
including when scanf() was intermixed with getch() from the
conio.h library. */
//=============== =============== ============
#include <stdio.h> // putc(), getc(), EOF, NULL
#include <stdlib.h> // EXIT_SUCCESS
#define NUL ('\0')
#define LF ('\n')
#define PutC(c) (putc((c), stdout))
#define GetC() (getc(stdin))
int kgets(char *s, int n)
{
// This function stores at most (n-1) characters
// from stdin to the string s. It does not retain
// the newline character. If necessary, it reads
// and discards any remaining characters in the
// input buffer. It returns the number of charcters
// discarded.
// Require non-NULL pointer AND space in string
// Discard entire string in input buffer if necessary.
if ( (NULL == s) || (n <= 0) )
{
for(n = 0; LF != GetC(); n++);
return n;
}
// Load max of n-1 characters
// Stop at but don't retain LF character
// The loop will terminate one of two ways:
// n=0: no LF was encountered
// n-1 characters read and stored
// s points one past last character stored
// set *s to NUL
// clear out rest of input buffer
// n>0: LF was encountered
// s points where LF is stored.
// set *s to NUL (strip LF from string)
// return 0
while ( (--n > 0) && (LF != (*s = GetC())) )
s++;
*s = NUL; // Add null terminator
// Count and discard unstored characters in input buffer
if (n)
n = 0; // No discarded characters
else
while (LF != GetC())
n++;
return n;
}
void PutS(const char *s)
{
while(*s != NUL)
PutC(*s++);
return;
}
int main(void)
{
char name[10];
PutS("Your Name? : ");
kgets(name, 10);
PutS("\nHello World, my name is ");
PutS(name);
PutS(".\n");
// Test Code - not part of actual program for students
printf("Discard ed: %i\n", kgets(NULL, 20));
printf("Discard ed: %i\n", kgets(name, 0));
printf("Discard ed: %i\n", kgets(name, 5));
return EXIT_SUCCESS;
}
//=============== =============== ===
One particular style point I would like to get feedback is the
use of parens in macros. This is my present approach and
reasoning:
Golden Rules for Macros:
#1) Surround each and every instance of each macro parameter
within the macro body with parens.
#2) Surround the macro as a whole with parens.
The above is expected to be done with all macros unless doing so
would cause a problem. Even if a particular macro doesn't need a
particular set of parens - such at the PutC() macro in the above
code, it is expected to follow these rules because it is too easy
to overlook a situation where, used a particular way, not
protecting the macro could cause problems. For me to change this
rule I'll probably need a fair amount of convincing.
What I'm sure will be more controversial - and it won't take as
much persuading to get me to change - is my requirement that even
object-like macros be surrounding by parens unless, again, doing
so would cause a problem. The reasoning here is that, if the
habit is developed that all #define macro bodies are
paren-enclosed by default, that it will be natural to do so when
writing a function-like macro. The fewer of these types of macros
you write, the more valuable it is to be in the happen of
throwing parens at macros in general.
Also, I generally #define the alphabetic escape sequences - such
as BEL, CR, LF - if I am going to be using them as character
constants more than once or twice. I do this purely for, what I
believe is, enhanced readability. Is this considered good
practice?
Looking forward to any comments and suggestions.
First, there is a program at the end of this post that has a
function kgets() that I would like any feedback on - including
style.
Second, for those that are interested, I present an outline of
the approach I am looking at using in class this semester. I
would be very interesting in any feedback on that, but if you are
not interested, feel free to skip over it.
Third, I present a conceptual model of the input buffer to my
students and want to get feedback on whether or not it is
sufficiently accurate.
This is a long post - longer than what I had intended when I
started. I won't be offended if you skip the whole thing and move
on to the next person's post.
=============== =============== =============== =====
Proposed Teaching Approach
Motive: It seems that when I follow the typical course syllabus
that starts with formatted I/O and treats all of the underlying
details as a black box for about two-thirds of the semester that
the students have an enormous struggle grasping pointers,
null-terminated strings, the difference between numbers stored as
ASCII strings and numbers stored as unformatted bytes,
structures, and a whole host of other "advanced" topics. A year
ago I tried starting with what I called a "Card Math" module
where I invented a fictitious microprocessor that had just a few
basic instructions and I spent two weeks walking them from the
most basic SET statement and showing what indirection is and how
to use it and progressed to how all of the basic flowchart
topologies for structured programming can be implemented using a
simple conditional SKP instruction combined with unconditional
JMP instructions. We then mapped these code fragments to the
different parts of all of the flow control devices available in
C. They wrote a couple of short programs in this pseudo assembly
language, including a selection sort routine, and had to
translate the assembly into OP codes manually and had to execute
the program manually with pencil and paper.
The results were mixed - about half the class seemed to grasp
what was going on and the other half really struggled. A few
students commented, some then and some at the end of the
semester, that the exercise was very enlightening and one student
said at the end of the first two weeks, "Now I understand
pointers!" - this particular student had a semester of Java, I
believe, before taking my course.
Even though the rest seemed, on the surface, not to grasp what
was going on, I noticed later in the semester that, overall,
there did seem to be quite a bit fewer problems working with
pointers and structures and the like. So I think I am on the
right track but think I need to find an exercise that will make a
better connection for the typical student.
Approach: I am starting out with some short programs that only
use putc() and getc() for everything.
The first one is, of course, Hello World! and only uses putc().
Even with so few elements in the program, I am able to walk down
the program element by element and discuss the "low level"
details of what is going on in the context of that element. So
the very first program I get to go into the #include directive,
function headers, prototypes (for the putc() function), passing
by value and by reference (since putc() uses both), bits, bytes,
unsigned binary, the ASCII code, character escape sequences, and
function return values. A pretty amazing range of topics for so
few high-level elements. My hope is that, with so few elements
(for instance, no strings, no flow control structures, and no
variables) to get lost in, they can do a better job focusing on
the details we are discussing.
In the second program I only add an example of an object-like
macro and a function-like macro (the LF and PutC() macros below)
and cover them in some detail including the issues associated
with using parens to ensure proper evaluation (what I call the
"Golden Rules of Macros) and even the issue of macros that
evaluate an argument multiple times if that argument contains
side effects.
The third program we write the PutS() function that is included
below and now I can get into strings and string literals,
pointers, dereferencing pointers, pointer arithmetic, and how (at
least conceptually) a string literal is stored and converted to a
pointer constant and therefore not only why one can be used as an
argument to PutS() but also why it is a Bad Thing to modify one.
That brings us to the fourth program which is what is below. The
new element here is this function called kgets() - which will
also be the first time we are actually using getc(). By going
through the mechanics of reading in a string from the keyboard
character by character I can discuss a conceptual model of the
input buffer (a few questions on that later), one dimensional
arrays, the dangers of exceeding array bounds, how a string can
be read in such that it doesn't exceed the available memory,
determining if the string was completely read in, stripping the
newline character from a string, clearing out the input buffer,
and returning a value that can be used to tell how many, if any,
characters had to be read and discarded.
The fifth program will start with the question of how many
characters got discarded? Since we only have the ability to
output characters, we will have to write a function that takes an
integer value and converts it to character output one digit at a
time. We will then expand that to take a format string that
controls how the integer is displayed and will implement most of
the options that can used with the %i printf() format specifier.
We'll also write a simple function that can get a character or a
char, long, or long int from the keyboard. The hope here is that
they will gain a strong appreciation for the difference between a
character string representation of a number and the binary
representation of it. I also hope it will put them on a good
footing to understand the format string when we get to formatted
I/O and the importance of matching the specifiers to the
arguments properly.
The sixth program will get us to the printb() function I posted a
week or so ago that will let us examine the actual bit
representations of different objects and hence get into floating
point and IEEE representations .
At each stage I am making a point of mentioning what elements are
and are not implementation dependent. Most of their homework, up
to this point, will be implementing their versions of many of the
standard library functions from ctype.h, stdio.h, and string.h.
At about this point we will hit file I/O, including unformatted
I/O, and will start working with some type of standard file
format. Over the course of several weeks we will work towards a
reasonably complex goal. In the past I have done BMP (they wrote
a program to create a linked list that was used recursively to
create a Kock snowflake and the write an image to a bitmap file)
and WAV files (they wrote a program that could create a wave file
that, when played over a speaker with a phone handset nearby,
would dial the phone).
=============== =============== =============== =====
Conceptual Model of Input Buffer (fast draft of the lesson)
First off - this is purely a conceptual model. The actual
implementations may not resemble this in any way. What we are
trying to accomplish here is an understandable description of how
the input buffer behaves as far as our program's interaction with
it is concerned.
FIFO Model - A block of memory having two pointers. The first
pointer (the READ pointer) points at the leading character in the
FIFO and the second pointer (the WRITE pointer) points at the
location where the next character will be written to the FIFO -
so it points to the spot just after the trailing character in the
FIF0. If the READ and WRITE pointers point at the same location,
then the FIFO is empty and cannot be read from. Whenever
something is written to the FIFO it is placed at the position of
the WRITE pointer and the WRITE pointer is incremented. Whenever
something is read, the value returned is the value at the
position pointed to by the READ pointer and the READ pointer is
incremented. For our purposes, we'll assume that the FIFO is
large enough that we never fill it up - meaning that we are
reading data out of it, on average, as fast as data is being
written to it and that we never get far enough behind at any time
to cause a problem.
Now imagine two FIFOs. One is controlled by the operating system
and the second is controlled by our program.
Every time a key is pressed its code is written to the system's
FIFO. This includes the newline code associated with hitting the
Enter key. These codes may or may not be ASCII - it doesn't
matter because, at some point before we interact with the data,
they will be converted to ASCII codes (since our implementation
uses ASCII as its character set).
The second FIFO is controlled by our program, but in a way that
we have very little control over. Whenever we request input from
the standard input device using functions such as getc(), gets(),
fgets(), scanf(), etc, etc, they read characters from the second
FIFO. If that FIFO is empty - or empties before we have read the
requested amount of data from it, then characters are transferred
from the first FIFO (by reading them from the first FIFO and
writing them to the second FIFO) until a newline character is
transferred. Hence data is transferred from the system's FIFO to
the program's FIFO one line - and an entire line - at a time.
It's important to note that whenever the program has to transfer
another line of data from the system's FIFO nothing else will
happen until that newline character is transferred. This means
that if you ask for just a single character but the program's
FIFO is empty and the system's FIFO doesn't have a newline
character in it, that the program will stall until the User
eventually hits the Enter key. It also means that if the User
enters more characters than we need on a given line, that the
remaining characters will remain in the program's FIFO and will
be read out the next time we ask for input. This applies to the
newline character as much as any other character. This may or may
not be the behavior we want but, regardless, it is our
responsibility to deal with it. Functions like scanf() make this
very difficult to do, which is why its use is strongly
discouraged by many programmers. If you do use scanf(), the fine
details of how the input characters are read and skipped becomes
vitally important if you are mixing numeric and character input
and great care must be taken to be sure that the program behaves
as desired.
/* At this point I run a program where the behavior is not as
expected and then walk through the code by hand using this
FIFO-based model on the board and show that what happens is would
actually is expected, just not what is wanted, when the input
doesn't match what was asked for or when numeric data and string
data are mixed without taking this into account. */
With the standard library functions, we have no way of knowing
whether anything is presently in the program's FIFO or the
system's FIFO, so we can't just check it and see because, if they
are empty, our program will hang until the User hits the Return
key. But, when we do get input from the program's FIFO, we can
take steps to keep track of whether we have seen the newline
character and, if we haven't, then we have the option of reading
characters one at a time until we do read the newline character.
What we do with these characters is completely up to is - the key
issue is that, at this point, we know that the program's FIFO is
empty and that any and all additional characters that have been
entered by the User are sitting in the system's FIFO.
Many implementations include functions that interact directly
with the system's FIFO. For us, that includes functions such as
kbhit() and getch() from the conio.h library. While these
functions give us capabilities that we can't achieve with the
standard library functions, they are not Standard C compliant. If
you are going to use them, especially if you are also using the
standard library functions as well, then it is important to
understand that a given character, once it is read from the
system's FIFO to the program's FIFO by one of the standard
library functions, is inaccessible to the conio functions.
Similarly, if a character is read from the system's FIFO by one
of the conio functions then that character will not be part of
the data that eventually gets transferred to the program's FIFO.
Hence, if you are going to mix these functions, you should be
very careful to ensure that both FIFO's are in an acceptable
state before you switch to the other type of input function.
/* At least up to this point, with our compiler, I haven't run
across any behavior that wasn't explained by this model - even
including when scanf() was intermixed with getch() from the
conio.h library. */
//=============== =============== ============
#include <stdio.h> // putc(), getc(), EOF, NULL
#include <stdlib.h> // EXIT_SUCCESS
#define NUL ('\0')
#define LF ('\n')
#define PutC(c) (putc((c), stdout))
#define GetC() (getc(stdin))
int kgets(char *s, int n)
{
// This function stores at most (n-1) characters
// from stdin to the string s. It does not retain
// the newline character. If necessary, it reads
// and discards any remaining characters in the
// input buffer. It returns the number of charcters
// discarded.
// Require non-NULL pointer AND space in string
// Discard entire string in input buffer if necessary.
if ( (NULL == s) || (n <= 0) )
{
for(n = 0; LF != GetC(); n++);
return n;
}
// Load max of n-1 characters
// Stop at but don't retain LF character
// The loop will terminate one of two ways:
// n=0: no LF was encountered
// n-1 characters read and stored
// s points one past last character stored
// set *s to NUL
// clear out rest of input buffer
// n>0: LF was encountered
// s points where LF is stored.
// set *s to NUL (strip LF from string)
// return 0
while ( (--n > 0) && (LF != (*s = GetC())) )
s++;
*s = NUL; // Add null terminator
// Count and discard unstored characters in input buffer
if (n)
n = 0; // No discarded characters
else
while (LF != GetC())
n++;
return n;
}
void PutS(const char *s)
{
while(*s != NUL)
PutC(*s++);
return;
}
int main(void)
{
char name[10];
PutS("Your Name? : ");
kgets(name, 10);
PutS("\nHello World, my name is ");
PutS(name);
PutS(".\n");
// Test Code - not part of actual program for students
printf("Discard ed: %i\n", kgets(NULL, 20));
printf("Discard ed: %i\n", kgets(name, 0));
printf("Discard ed: %i\n", kgets(name, 5));
return EXIT_SUCCESS;
}
//=============== =============== ===
One particular style point I would like to get feedback is the
use of parens in macros. This is my present approach and
reasoning:
Golden Rules for Macros:
#1) Surround each and every instance of each macro parameter
within the macro body with parens.
#2) Surround the macro as a whole with parens.
The above is expected to be done with all macros unless doing so
would cause a problem. Even if a particular macro doesn't need a
particular set of parens - such at the PutC() macro in the above
code, it is expected to follow these rules because it is too easy
to overlook a situation where, used a particular way, not
protecting the macro could cause problems. For me to change this
rule I'll probably need a fair amount of convincing.
What I'm sure will be more controversial - and it won't take as
much persuading to get me to change - is my requirement that even
object-like macros be surrounding by parens unless, again, doing
so would cause a problem. The reasoning here is that, if the
habit is developed that all #define macro bodies are
paren-enclosed by default, that it will be natural to do so when
writing a function-like macro. The fewer of these types of macros
you write, the more valuable it is to be in the happen of
throwing parens at macros in general.
Also, I generally #define the alphabetic escape sequences - such
as BEL, CR, LF - if I am going to be using them as character
constants more than once or twice. I do this purely for, what I
believe is, enhanced readability. Is this considered good
practice?
Looking forward to any comments and suggestions.
Comment