Updates to Pointer Guide

[Foobarius Frobinium]

http://thelinuxlink.net/~fingolfin/pointer-guide/

I've made a lot of corrections, and put in more new stuff. I have
malloc and pointers to struct's and maybe a few more things and I'm
done.

Examine it and tell me what you think.

[Arthur J. O'Dwyer]

On Mon, 2 Aug 2004, Arthur J. O'Dwyer wrote:

[Copied to myself since I can't tell for sure whether that's
a real email address or a much-too-cute fake one in your From
header]
Apparently it's a too-cute fake one. Please change it to a
more obviously munged one, or one that's not munged at all.

On Sun, 1 Aug 2004, Foobarius Frobinium wrote:

http://thelinuxlink.net/~fingolfin/pointer-guide/
Examine it and tell me what you think.

...the addresss of each member...
s/addresss/address/
and similar spell-checking throughout.

...syntax sugar...
s/syntax/syntactic/

...foo[2] is nearly identical to *(foo + 2). The interchangabili ty...
s/is nearly identical to/has the same effect as/
s/interchangabili ty/interchangeabil ity/
unless it really is spelled that way in British English, but I
doubt it.

...single-dimension arrays...
s/single-dimension/one-dimensional/

You might consider changing the array values in the example that
uses the code
fprintf(stdout, "%i\n", *bar);
fprintf(stdout, "%i\n", *(bar + 1));
fprintf(stdout, "%i\n", *(bar + 2));
so that *(bar + 1) evaluates to a different value from (*bar + 1),
and so on. Especially since you made a big deal about the
difference earlier in the tutorial.

Is there a reason you're using 'fprintf(stdout , ...' instead of
'printf(...'? It looks a lot like needless complexity to me.

...So, instead, I must type &baz[0][0]...
You could just as well have typed 'baz[0]'. The ampersand cancels
out the dereference. Did you mention this already? It's a very
important and useful fact.

In fact, you never mention the word 'sizeof' in the entire
tutorial --- did you ever mention that while 'sizeof(int)' is
/not/ always 2, 'sizeof(char)' /is/ always 1? That's important.

By the time we get to "True Pointers to Arrays," you should be
using the array notation exclusively. '*(bar + 1)' should be
'bar[1]' from here on out; and so on.

...array of char's... ...array of int's...
Suggest "array of char", where "char" is set in a fixed-width
font, and so on. Either that, or reword the sentence
"We are aware that an array's name will always decay into a pointer to its
first element. In the case, for example, of an array of char's..."
The two apostrophes are too close together for comfort.
Similar complaints re: "an array of char's that is seven long."
The plural of "char" ought to be "chars," no matter how you decide
to format it; and the use of the type-name 'long' in this context
might confuse the reader. Formatting type-names in fixed-width font
would solve the latter problem.

Suggest placing comments in code examples which invoke undefined
behavior, for example

fprintf(stdout, "%s\n", *(bar + 2));

ought to read

printf("%s\n", bar[2]); /* ERROR! */

...pointers to arrays with a three dimensional array...
s/arrays/arrays,/
s/three dimensional/three-dimensional/

...If this confuses you, that's OK. There are very, very few people
whom it would not confuse at first glance...
Save the cute comments for the stuff that's /really/ difficult to
understand, not the stuff that's just poorly written. Making the
substitutions already discussed, and reflowing the array declaration
to mirror its actual use, we have

#include <stdio.h>

void foo(int (*bar)[3][4]);

int main(void)
{
int baz[][3][4] = {
{
{ 0, 1, 2, 3 },
{ 4, 5, 6, 7 },
{ 8, 9, 10, 11 }
}, {
{ 12, 13, 14, 15 },
{ 16, 17, 18, 19 },
{ 20, 21, 22, 23 }
}
};

foo(baz);
return 0;
}

void foo(int (*bar)[3][4])
{
int (*buzz)[4] = bar[1];
printf("%i\n", buzz[2][2]);
}

I don't think this should confuse anyone, except perhaps over the
relative precedence of * and [] in the function prototype declaration
of 'bar'. In fact, it might be better to write

void foo(int bar[][3][4]);

so as to make the parallel clearer. However, you do make a point of
explaining what's going on with '(*bar)[3][4]'; that's good.

The accompanying "Address/Value" table is more than a screen long.
Consider breaking it into multiple columns.

...bash, a CLI command interpreter...
The usual term is "shell." And you never explain what the acronym
"CLI" means --- I wouldn't expect a naive user to know what "CLI"
meant and yet not recognize the term "bash" from context.

...This is what prints... ...indpedence.. .
No, it isn't.

Your last sample program does not #include <string.h>, which is
a fatal error. And 'strlen' is defined in exactly the same way
on all systems; there's no reason to qualify your sentence with
"...on my system".
There are more typos and stylistic problems, but a good English-
language proofreader (I would think preferably one who's /not/ a
C expert) can catch those. These are most of the critical errors
that I saw.

HTH,
-Arthur

[Foobarius Frobinium]

"Arthur J. O'Dwyer" <aj*@nospam.and rew.cmu.edu> wrote in message news:<Pi******* *************** ************@un ix48.andrew.cmu .edu>...

On Mon, 2 Aug 2004, Arthur J. O'Dwyer wrote:

[Copied to myself since I can't tell for sure whether that's
a real email address or a much-too-cute fake one in your From
header]
Well, fingolfin AT thelinuxlink DOT net is the real one. P.S. I added
a special thanks section with your name on it. Very useful criticisms
here.
On Sun, 1 Aug 2004, Foobarius Frobinium wrote:

http://thelinuxlink.net/~fingolfin/pointer-guide/
Examine it and tell me what you think.

...the addresss of each member...
s/addresss/address/
and similar spell-checking throughout.
Done. Used ispell. :)

...syntax sugar...
s/syntax/syntactic/
Done.

...foo[2] is nearly identical to *(foo + 2). The interchangabili ty...
s/is nearly identical to/has the same effect as/
s/interchangabili ty/interchangeabil ity/
unless it really is spelled that way in British English, but I
doubt it.
I'm not British. Of British descent...but not British.

...single-dimension arrays...
s/single-dimension/one-dimensional/
Done.

You might consider changing the array values in the example that
uses the code
fprintf(stdout, "%i\n", *bar);
fprintf(stdout, "%i\n", *(bar + 1));
fprintf(stdout, "%i\n", *(bar + 2));
so that *(bar + 1) evaluates to a different value from (*bar + 1),
and so on. Especially since you made a big deal about the
difference earlier in the tutorial.
Hm. I am redundant in the guide. But I think one instance would be
good enough in this case.

Is there a reason you're using 'fprintf(stdout , ...' instead of
'printf(...'? It looks a lot like needless complexity to me.
A convention I picked up off of esr's earlier code.

...So, instead, I must type &baz[0][0]...
You could just as well have typed 'baz[0]'. The ampersand cancels
out the dereference. Did you mention this already? It's a very
important and useful fact.
Yes...but here's the problem: my explanation does not make sense until
later in the guide. This would use the 'double decay' effect if I am
not mistaken, yes?

1) baz decays into a pointer to its first element, an array of char,
of seven members
2) The pointer is dereferenced.
3) The resulting array decays once more.

In fact, you never mention the word 'sizeof' in the entire
tutorial --- did you ever mention that while 'sizeof(int)' is
/not/ always 2, 'sizeof(char)' /is/ always 1? That's important.
I will get to sizeof in malloc section. I did not know different
architectures have different int sizes.

By the time we get to "True Pointers to Arrays," you should be
using the array notation exclusively. '*(bar + 1)' should be
'bar[1]' from here on out; and so on.
Hm...I want to at least get people aware of the other, less popular
notation. But I will probably make some changes according to that
criticism

...array of char's... ...array of int's...
Suggest "array of char", where "char" is set in a fixed-width
font, and so on. Either that, or reword the sentence
"We are aware that an array's name will always decay into a pointer to its
first element. In the case, for example, of an array of char's..."
The two apostrophes are too close together for comfort.
Similar complaints re: "an array of char's that is seven long."
The plural of "char" ought to be "chars," no matter how you decide
to format it; and the use of the type-name 'long' in this context
might confuse the reader. Formatting type-names in fixed-width font
would solve the latter problem.
I see. I spent some time doing this as well.

Suggest placing comments in code examples which invoke undefined
behavior, for example

fprintf(stdout, "%s\n", *(bar + 2));

ought to read

printf("%s\n", bar[2]); /* ERROR! */
Done.

...pointers to arrays with a three dimensional array...
s/arrays/arrays,/
s/three dimensional/three-dimensional/
Done.

...If this confuses you, that's OK. There are very, very few people
whom it would not confuse at first glance...
Save the cute comments for the stuff that's /really/ difficult to
understand, not the stuff that's just poorly written. Making the
substitutions already discussed, and reflowing the array declaration
to mirror its actual use, we have
<snip>

I'll probably put something like that in there. Again, I did want to
show the unpopular method just to make sure no one confuses pointers
and arrays.

...This is what prints... ...indpedence.. .
No, it isn't.
Changed.

Your last sample program does not #include <string.h>, which is
a fatal error. And 'strlen' is defined in exactly the same way
on all systems; there's no reason to qualify your sentence with
"...on my system".
Changed.


There are more typos and stylistic problems, but a good English-
language proofreader (I would think preferably one who's /not/ a
C expert) can catch those. These are most of the critical errors
that I saw.

HTH,
-Arthur

Thx