exercism

Exercism solutions.
git clone git://code.dwrz.net/exercism
Log | Files | Refs

README.md (6656B)


      1 # Gigasecond
      2 
      3 Calculate the moment when someone has lived for 10^9 seconds.
      4 
      5 A gigasecond is 10^9 (1,000,000,000) seconds.
      6 
      7 ## Exercises without stub implementations
      8 
      9 Like the majority of C programs you will write, this exercise comes without any header file (`*.h`) or source file (`*.c`).
     10 
     11 
     12 ### Add the required files
     13 
     14 You will need to create these yourself as part of the exercise. 
     15 This is so that you get to practice deciding on and creating the program's interface yourself, which is an important part of programming in C.
     16 It does mean that when you first try to run the tests, they won't compile.
     17 They will give you an error similar to:
     18 
     19 ```bash
     20 make: *** No rule to make target 'src/exercise_name.c', needed by 'tests.out'.  Stop.
     21 ```
     22 
     23 This error occurs because the `makefile` attempts to use a file that hasn't been created yet (`exercise_name.c`).
     24 To resolve this error you will need to add a matching file to the `src` directory.
     25 For example, for the error above you would add a file called `exercise_name.c`.
     26 
     27 When you try to run the tests again you will get a slightly different error.
     28 
     29 ```bash
     30 make: *** No rule to make target 'src/exercise_name.h', needed by 'tests.out'.  Stop.
     31 ```
     32 
     33 Again the `makefile` still needs another file that has yet to be created (`exercise_name.h`).
     34 The solution to this error is similar to the last, add the matching file to the `src` directory.
     35 For example, for the above error you would add a file called `exercise_name.h`
     36 
     37 
     38 ### Add the required declarations
     39 
     40 Running the tests a third time you see you will get new errors, similar to:
     41 
     42 ```bash
     43 Compiling tests.out
     44 src/exercise_name.c:1:0: error: ISO C forbids an empty translation unit [-Werror=pedantic]
     45 cc1: all warnings being treated as errors
     46 test/test_exercise_name.c:13:1: error: unknown type name ‘bar_t’; did you mean ‘__bar_t’?
     47     bar_t b = foo(a, 2.5);
     48     ^~~~~~
     49  __bar_t
     50 test/test_exercise_name.c:15:14: error: storage size of fizz isn’t known
     51     struct baz fizz;
     52                ^~~~
     53 test/test_exercise_name.c:29:20: error: implicit declaration of function ‘foo’ [-Werror=implicit-function-declaration]
     54     bar_t b = foo_function(fizz, 2.5);
     55 ```
     56 
     57 This error means that you need to add function, type and variable decarations to the header file to match those the test file is attempting to use.
     58 In doing this you will need to look at the build errors and the test code to determine what needs to be declared in the header file.
     59 
     60 For example, for the error above you should declare a type named  `bar_t`, a `struct` called `baz` and a function named `foo()`. 
     61 Additionally we can tell from looking at the above errors that function `foo()` has two parameters. 
     62 
     63 The first parameter is passed an argument of `fizz` and thus should have a type of `struct baz`.
     64 The second parameter is passed `2.5` and so could have one of two types, either `float` or `double`.
     65 You will need to look at the test code to determine which.
     66 
     67 The _names_ of the parameters are not determined by the test code and so are left up to you to decide, though in keeping with C programming practices they should be descriptive but not overly long.
     68 
     69 Further, we can see that the the return type expected by the test code is of the type `bar_t`.
     70 
     71 Putting this all together we end up with a function declaration that looks like the following:
     72 
     73 ```c
     74 // The parameter names are not very good here they should be more descriptive in a real exercise.
     75 // We have decide on a double for the second parameter in this hypothetical example.
     76 bar_t foo(struct baz b, double d);
     77 ```
     78 
     79 You should continue to do this for any further similar errors.
     80 To check that you have correctly determined the required declaration, just run the tests again and analyse any errors similarly.
     81 
     82 Additionally, remember to add any includes to the header file any headers that it itself requires.
     83 
     84 
     85 ### Include guards
     86 
     87 Before you are finished with the header file, you should add include guards.
     88 Include guards are used to help prevent the file from being included multiple times by accident.
     89 If the file _was_ included multiple times then the functions and other items would be declared twice; In C this is an error because the compiler thinks you are trying to declare another _different_ function that has the same name.
     90 
     91 To add include guards, add something similar to the following as the first two lines of the header:
     92 
     93 ```c
     94 #ifndef EXERCISE_NAME_H
     95 #define EXERCISE_NAME_H
     96 ```
     97 
     98 And on the very last line:
     99 
    100 ```c
    101 #endif
    102 ```
    103 
    104 
    105 ### Add the required definitions
    106 
    107 Once the header file is complete you may still have build errors similar to the following:
    108 
    109 ```bash
    110 Compiling tests.out
    111 src/exercise_name.c:1:0: error: ISO C forbids an empty translation unit [-Werror=pedantic]
    112 cc1: all warnings being treated as errors
    113 makefile:24: recipe for target 'tests.out' failed
    114 make: *** [tests.out] Error 1
    115 ```
    116 
    117 This is because although you have _declared_ all the items you need to, they have not yet been _defined_.
    118 To define the needed items you need to add their implementation to the `exercise_name.c` file.
    119 For the function `foo()` from the previous example, this would look similar to:
    120 
    121 ```c
    122 #include "exercise_name.h"
    123 
    124 bar_t foo(struct baz b, double d)
    125 {
    126     // Your exercise code here
    127 }
    128 ```
    129 
    130 After having resolved these errors you should be ready to start making the tests pass!
    131 
    132 
    133 ## Getting Started
    134 
    135 Make sure you have read the "Guides" section of the
    136 [C track](https://exercism.io/my/tracks/c) on the Exercism site. This covers
    137 the basic information on setting up the development environment expected
    138 by the exercises.
    139 
    140 
    141 ## Passing the Tests
    142 
    143 Get the first test compiling, linking and passing by following the [three
    144 rules of test-driven development][3-tdd-rules].
    145 
    146 The included makefile can be used to create and run the tests using the `test`
    147 task.
    148 
    149     make test
    150 
    151 Create just the functions you need to satisfy any compiler errors and get the
    152 test to fail. Then write just enough code to get the test to pass. Once you've
    153 done that, move onto the next test.
    154 
    155 [3-tdd-rules]: http://butunclebob.com/ArticleS.UncleBob.TheThreeRulesOfTdd
    156 
    157 As you progress through the tests, take the time to refactor your
    158 implementation for readability and expressiveness and then go on to the next
    159 test.
    160 
    161 Try to use standard C99 facilities in preference to writing your own
    162 low-level algorithms or facilities by hand.
    163 
    164 ## Source
    165 
    166 Chapter 9 in Chris Pine's online Learn to Program tutorial. [http://pine.fm/LearnToProgram/?Chapter=09](http://pine.fm/LearnToProgram/?Chapter=09)
    167 
    168 ## Submitting Incomplete Solutions
    169 It's possible to submit an incomplete solution so you can see how others have completed the exercise.