Update c.html.markdown

c.html.markdown

@@ -5,19 +5,20 @@ language: c
 filename: learnc.c
 contributors:
     - ["Adam Bard", "http://adambard.com/"]
+    - ["Árpád Goretity", "http://twitter.com/h2co3_ios"]
 ---
 
-Ah, C. Still the language of modern high-performance computing.
+Ah, C. Still **the** language of modern high-performance computing.
 
 C is the lowest-level language most programmers will ever use, but
 it more than makes up for it with raw speed. Just be aware of its manual
 memory management and C will take you as far as you need to go.
 
 ```c
-// Single-line comments start with //
+// Single-line comments start with // - only available in C99 and later.
 
 /*
-Multi-line comments look like this.
+Multi-line comments look like this. They work in C89 as well.
 */
 
 // Import headers with #include
@@ -25,6 +26,11 @@ Multi-line comments look like this.
 #include <stdio.h>
 #include <string.h>
 
+// file names between <angle brackets> are headers from the C standard library.
+// They are searched for by the preprocessor in the system include paths
+// (usually /usr/lib on Unices, can be controlled with the -I<dir> option if you are using GCC or clang.)
+// For your
+
 // Declare function signatures in advance in a .h file, or at the top of
 // your .c file.
 void function_1();
@@ -33,7 +39,6 @@ void function_2();
 // Your program's entry point is a function called
 // main with an integer return type.
 int main() {
-
     // print output using printf, for "print formatted"
     // %d is an integer, \n is a newline
     printf("%d\n", 0); // => Prints 0
@@ -76,11 +81,22 @@ unsigned short ux_short;
     unsigned int ux_int;
     unsigned long long ux_long_long;
     
-// Other than char, which is always 1 byte, these types vary in size depending
+    // Other than char, which is always 1 byte (but not necessarily 8 bits!),
-// on your machine. sizeof(T) gives you the size of a variable with type T in 
+    // these types vary in size depending on your machine and compiler.
+    // sizeof(T) gives you the size of a variable with type T in 
     // bytes so you can express the size of these types in a portable way.
+    // sizeof(obj) yields the size of an actual expression (variable, literal, etc.).
     // For example,
-printf("%lu\n", sizeof(int)); // => 4 (on machines with 4-byte words)
+    printf("%zu\n", sizeof(int)); // => 4 (on most machines with 4-byte words)
+    
+    
+    // It's worth noting that if the argument of the `sizeof` operator is not a type but an expression,
+    // then its argument is not evaluated except VLAs (see below). Also, `sizeof()` is an operator, not a function,
+    // furthermore, the value it yields is a compile-time constant (except when used on VLAs, again.)
+    int a = 1;
+    size_t size = sizeof(a++); // a++ is not evaluated
+    printf("sizeof(a++) = %zu where a = %d\n", size, a);
+    // the above code prints "sizeof(a++) = 4 where a = 1" (on a usual 32-bit architecture)
     
     // Arrays must be initialized with a concrete size.
     char my_char_array[20]; // This array occupies 1 * 20 = 20 bytes
@@ -99,6 +115,19 @@ my_array[0]; // => 0
     my_array[1] = 2;
     printf("%d\n", my_array[1]); // => 2
     
+    // In C99 (and as an optional feature in C11), variable-length arrays (VLAs) can be declared as well.
+    // The size of such an array need not be a compile time constant:
+    printf("Enter the array size: "); // ask the user for an array size
+    char buf[0x100];
+    fgets(buf, sizeof buf, stdin);
+    size_t size = strtoul(buf, NULL, 10); // strtoul parses a string to an unsigned integer
+    int var_length_array[size]; // declare the VLA
+    printf("sizeof array = %zu\n", sizeof var_length_array);
+    
+    // A possible outcome of this program may be:
+    Enter the array size: 10
+    sizeof array = 40
+    
     // Strings are just arrays of chars terminated by a NUL (0x00) byte,
     // represented in strings as the special character '\0'.
     // (We don't have to include the NUL byte in string literals; the compiler
@@ -109,11 +138,19 @@ printf("%s\n", a_string); // %s formats a string
     /*
      You may have noticed that a_string is only 16 chars long.
      Char #17 is the NUL byte. 
-Chars #18, 19 and 20 have undefined values.
+     Chars #18, 19 and 20 are 0 as well - if an initializer list (in this case, the string literal)
+     has less elements than the array it is initializing, then excess array elements are implicitly
+     initialized to zero. This is why int ar[10] = { 0 } works as expected intuitively.
     */
     
     printf("%d\n", a_string[16]); // => 0
     
+    // So string literals are strings enclosed within double quotes, but if we have characters
+    // between single quotes, that's a character literal.
+    // It's of type `int`, and *not* `char` (for hystorical reasons).
+    int cha = 'a'; // fine
+    char chb = 'a'; // fine too (implicit conversion from int to char - truncation)
+    
     ///////////////////////////////////////
     // Operators
     ///////////////////////////////////////
@@ -127,7 +164,7 @@ i2 - i1; // => 1
     i2 * i1; // => 2
     i1 / i2; // => 0 (0.5, but truncated towards 0)
     
-f1 / f2; // => 0.5, plus or minus epsilon
+    f1 / f2; // => 0.5, plus or minus epsilon - floating-point numbers and calculations are not exact
     
     // Modulo is there as well
     11 % 3; // => 2
@@ -135,7 +172,7 @@ f1 / f2; // => 0.5, plus or minus epsilon
     // Comparison operators are probably familiar, but
     // there is no boolean type in c. We use ints instead.
     // 0 is false, anything else is true. (The comparison 
-// operators always return 0 or 1.)
+    // operators always yield 0 or 1.)
     3 == 2; // => 0 (false)
     3 != 2; // => 1 (true)
     3 > 2; // => 1
@@ -152,7 +189,7 @@ f1 / f2; // => 0.5, plus or minus epsilon
     0 || 0; // => 0
     
     // Bitwise operators!
-~0x0F; // => 0xF0 (bitwise negation)
+    ~0x0F; // => 0xF0 (bitwise negation, "1's complement")
     0x0F & 0xF0; // => 0x00 (bitwise AND)
     0x0F | 0xF0; // => 0xFF (bitwise OR)
     0x04 ^ 0x0F; // => 0x0B (bitwise XOR)
@@ -174,7 +211,7 @@ if (0) {
     // While loops exist
     int ii = 0;
     while (ii < 10) {
-    printf("%d, ", ii++); // ii++ increments ii in-place, after using its value.
+        printf("%d, ", ii++); // ii++ increments ii in-place, after yielding its value ("postincrement").
     } // => prints "0, 1, 2, 3, 4, 5, 6, 7, 8, 9, "
     
     printf("\n");
@@ -182,7 +219,7 @@ printf("\n");
     int kk = 0;
     do {
         printf("%d, ", kk);
-} while (++kk < 10); // ++kk increments kk in-place, before using its value
+    } while (++kk < 10); // ++kk increments kk in-place, and yields the already incremented value ("preincrement")
     // => prints "0, 1, 2, 3, 4, 5, 6, 7, 8, 9, "
     
     printf("\n");
@@ -200,7 +237,7 @@ printf("\n");
     ///////////////////////////////////////
     
     // Every value in C has a type, but you can cast one value into another type
-// if you want.
+    // if you want (with some constraints).
     
     int x_hex = 0x01; // You can assign vars with hex literals
     
@@ -210,7 +247,11 @@ printf("%d\n", (short) x_hex); // => Prints 1
     printf("%d\n", (char) x_hex); // => Prints 1
     
     // Types will overflow without warning
-printf("%d\n", (char) 257); // => 1 (Max char = 255)
+    printf("%d\n", (unsigned char) 257); // => 1 (Max char = 255 if char is 8 bits long)
+    // printf("%d\n", (unsigned char) 257); would be undefined behavior - `char' is usually signed
+    // on most modern systems, and signed integer overflow invokes UB.
+    // Also, for determining the maximal value of a `char`, a `signed char` and an `unisigned char`,
+    // respectively, use the CHAR_MAX, SCHAR_MAX and UCHAR_MAX macros from <limits.h>
     
     // Integral types can be cast to floating-point types, and vice-versa.
     printf("%f\n", (float)100); // %f formats a float
@@ -226,20 +267,21 @@ printf("%d\n", (char)100.0);
     // of your variables, then mess with them.
     
     int x = 0;
-printf("%p\n", &x); // Use & to retrieve the address of a variable
+    printf("%p\n", (void *)&x); // Use & to retrieve the address of a variable
-// (%p formats a pointer)
+    // (%p formats an object pointer of type void *)
     // => Prints some address in memory;
     
     
     // Pointers start with * in their declaration
     int *px, not_a_pointer; // px is a pointer to an int
     px = &x; // Stores the address of x in px
-printf("%p\n", px); // => Prints some address in memory
+    printf("%p\n", (void *)px); // => Prints some address in memory
-printf("%d, %d\n", (int)sizeof(px), (int)sizeof(not_a_pointer));
+    printf("%zu, %zu\n", sizeof(px), sizeof(not_a_pointer));
-// => Prints "8, 4" on 64-bit system
+    // => Prints "8, 4" on a typical 64-bit system
     
     // To retreive the value at the address a pointer is pointing to,
     // put * in front to de-reference it.
+    // Note: yes, it may be confusing that '*' is used for _both_ declaring a pointer and dereferencing it.
     printf("%d\n", *px); // => Prints 0, the value of x, which is what px is pointing to the address of
     
     // You can also change the value the pointer is pointing to.
@@ -258,38 +300,55 @@ for (xx=0; xx<20; xx++) {
     // Declare a pointer of type int and initialize it to point to x_array
     int* x_ptr = x_array;
     // x_ptr now points to the first element in the array (the integer 20). 
-// This works because arrays are actually just pointers to their first element.
+    // This works because arrays often decay into pointers to their first element.
+    // For example, when an array is passed to a function or is assigned to a pointer,
+    // it decays into (implicitly converted to) a pointer.
+    // Exceptions: when the array is the argument of the `&` (address-od) operator:
+    int arr[10];
+    int (*ptr_to_arr)[10] = &arr; // &arr is NOT of type `int *`! It's of type "pointer to array" (of ten `int`s).
+    // or when the array is a string literal used for initializing a char array:
+    char arr[] = "foobarbazquirk";
+    // or when it's the argument of the `sizeof` or `alignof` operator:
+    int arr[10];
+    int *ptr = arr; // equivalent with int *ptr = &arr[0];
+    printf("%zu %zu\n", sizeof arr, sizeof ptr); // probably prints "40, 4" or "40, 8"
     
-// Arrays are pointers to their first element
-printf("%d\n", *(x_ptr)); // => Prints 20
-printf("%d\n", x_array[0]); // => Prints 20
 
     // Pointers are incremented and decremented based on their type
+    // (this is called pointer arithmetic)
     printf("%d\n", *(x_ptr + 1)); // => Prints 19
     printf("%d\n", x_array[1]); // => Prints 19
     
     // You can also dynamically allocate contiguous blocks of memory with the
-// standard library function malloc, which takes one integer argument 
+    // standard library function malloc, which takes one argument of type size_t
-// representing the number of bytes to allocate from the heap.
+    // representing the number of bytes to allocate (usually from the heap, although this
-int* my_ptr = (int*) malloc(sizeof(int) * 20);
+    // may not be true on e. g. embedded systems - the C standard says nothing about it).
+    int *my_ptr = malloc(sizeof(*my_ptr) * 20);
     for (xx = 0; xx < 20; xx++) {
-    *(my_ptr + xx) = 20 - xx; // my_ptr[xx] = 20-xx would also work here
+        *(my_ptr + xx) = 20 - xx; // my_ptr[xx] = 20-xx would also work here, and it's also more readable
     } // Initialize memory to 20, 19, 18, 17... 2, 1 (as ints)
     
     // Dereferencing memory that you haven't allocated gives
-// unpredictable results
+    // "unpredictable results" - the program is said to invoke "undefined behavior"
-printf("%d\n", *(my_ptr + 21)); // => Prints who-knows-what?
+    printf("%d\n", *(my_ptr + 21)); // => Prints who-knows-what? It may even crash.
     
     // When you're done with a malloc'd block of memory, you need to free it, 
     // or else no one else can use it until your program terminates
+    // (this is called a "memory leak"):
     free(my_ptr);
     
-// Strings can be char arrays, but are usually represented as char
+    // Strings are arrays of char, but they are usually represented as a
-// pointers:
+    // pointer-to-char (which is a pointer to the first element of the array).
-char* my_str = "This is my very own string";
+    // It's good practice to use `const char *' when referring to a string literal,
-
+    // since string literals shall not be modified (i. e. "foo"[0] = 'a' is ILLEGAL.)
+    const char *my_str = "This is my very own string literal";
     printf("%c\n", *my_str); // => 'T'
     
+    // This is not the case if the string is an array (potentially initialized with a string literal)
+    // that resides in writable memory, as in:
+    char foo[] = "foo";
+    foo[0] = 'a'; // this is legal, foo now contains "aoo"
+    
     function_1();
 } // end main function
 
@@ -300,7 +359,8 @@ function_1();
 // Function declaration syntax:
 // <return type> <function name>(<args>)
 
-int add_two_ints(int x1, int x2){
+int add_two_ints(int x1, int x2)
+{
     return x1 + x2; // Use return to return a value
 }
 
@@ -312,9 +372,11 @@ Example: in-place string reversal
 */
 
 // A void function returns no value
-void str_reverse(char* str_in){
+void str_reverse(char *str_in)
+{
     char tmp;
-    int ii=0, len = strlen(str_in); // Strlen is part of the c standard library
+    int ii = 0;
+    size_t len = strlen(str_in); // `strlen()` is part of the c standard library
     for (ii = 0; ii < len / 2; ii++) {
         tmp = str_in[ii];
         str_in[ii] = str_in[len - ii - 1]; // ii-th char from end
@@ -336,15 +398,20 @@ printf("%s\n", c); // => ".tset a si sihT"
 typedef int my_type;
 my_type my_type_var = 0;
 
-// Structs are just collections of data
+// Structs are just collections of data, the members are allocated sequentially, in the order they are written:
 struct rectangle {
     int width;
     int height;
 };
 
+// it's generally not true that sizeof(struct rectangle) == sizeof(int) + sizeof(int) due to
+// potential padding between the structure members (this is for alignment reasons. Probably won't
+// happen if all members are of the same type, but watch out!
+// See http://stackoverflow.com/questions/119123/why-isnt-sizeof-for-a-struct-equal-to-the-sum-of-sizeof-of-each-member
+// for further information.
 
-void function_1(){
+void function_1()
-
+{
     struct rectangle my_rec;
 
     // Access struct members with .
@@ -357,17 +424,24 @@ void function_1(){
     // Use dereferencing to set struct pointer members...
     (*my_rec_ptr).width = 30;
 
-    // ... or use the -> shorthand
+    // ... or even better: prefer the -> shorthand for the sake of readability
     my_rec_ptr->height = 10; // Same as (*my_rec_ptr).height = 10;
 }
 
 // You can apply a typedef to a struct for convenience
 typedef struct rectangle rect;
 
-int area(rect r){
+int area(rect r)
+{
     return r.width * r.height;
 }
 
+// if you have large structs, you can pass them "by pointer" to avoid copying the whole struct:
+int area(const rect *r)
+{
+    return r->width * r->height;
+}
+
 ///////////////////////////////////////
 // Function pointers 
 ///////////////////////////////////////
@@ -383,6 +457,7 @@ void str_reverse_through_pointer(char * str_in) {
     // Define a function pointer variable, named f. 
     void (*f)(char *); // Signature should exactly match the target function.
     f = &str_reverse; // Assign the address for the actual function (determined at runtime)
+    // f = str_reverse; would work as well - functions decay into pointers, similar to arrays
     (*f)(str_in); // Just calling the function through the pointer
     // f(str_in); // That's an alternative but equally valid syntax for calling it.
 }
@@ -403,7 +478,15 @@ typedef void (*my_fnp_type)(char *);
 ## Further Reading
 
 Best to find yourself a copy of [K&R, aka "The C Programming Language"](https://en.wikipedia.org/wiki/The_C_Programming_Language)
+It is *the* book about C, written by the creators of C. Be careful, though - it's ancient and it contains some
+inaccuracies (well, ideas that are not considered good anymore) or now-changed practices.
 
-Another good resource is [Learn C the hard way](http://c.learncodethehardway.org/book/)
+Another good resource is [Learn C the hard way](http://c.learncodethehardway.org/book/).
+
+If you have a question, read the [compl.lang.c Frequently Asked Questions](http://c-faq.com).
+
+It's very important to use proper spacing, indentation and to be consistent with your coding style in general.
+Readable code is better than clever code and fast code. For a good, sane coding style to adopt, see the
+[Linux kernel coding stlye](https://www.kernel.org/doc/Documentation/CodingStyle).
 
 Other than that, Google is your friend.