docs: add self-test examples (#1250)

* docs: add self-test examples

* updating DIRECTORY.md

---------

Co-authored-by: github-actions[bot] <[email protected]>

Author: Panquesito7

CONTRIBUTING.md

@@ -57,6 +57,102 @@ For LeetCode solutions, please check its [**guide**](https://github.com/TheAlgor
 - Make sure to add examples and test cases in your `main()` function.
 - If you find an algorithm or document without tests, please feel free to create a pull request or issue describing suggested changes.
 - Please try to add one or more `test()` functions that will invoke the algorithm implementation on random test data with the expected output. Use the `assert()` function to confirm that the tests will pass. Requires including the `assert.h` library.
+- Test cases should fully verify that your program works as expected. Rather than asking the user for input, it's best to make sure the given output is the correct output.
+
+##### Self-test examples
+
+1. [ROT13 Cipher](https://github.com/TheAlgorithms/C/blob/master/cipher/rot13.c) (complex).
+
+```c
+    // NOTE: the `rot13` function is defined in another part of the code.
+
+    char test_01[] = "The more I C, the less I see.";
+    rot13(test_01);
+    assert(strcmp(test_01, "Gur zber V P, gur yrff V frr.") == 0);
+
+    char test_02[] = "Which witch switched the Swiss wristwatches?";
+    rot13(test_02);
+    assert(strcmp(test_02, "Juvpu jvgpu fjvgpurq gur Fjvff jevfgjngpurf?") == 0);
+
+    char test_03[] = "Juvpu jvgpu fjvgpurq gur Fjvff jevfgjngpurf?";
+    rot13(test_03);
+    assert(strcmp(test_03, "Which witch switched the Swiss wristwatches?") == 0);
+```
+
+2. [Sudoku Solver](https://github.com/TheAlgorithms/C/blob/master/misc/sudoku_solver.c) (medium).
+
+```c
+    uint8_t test_array[] = {3, 0, 6, 5, 0, 8, 4, 0, 0, 5, 2, 0, 0, 0, 0, 0, 0,
+                            0, 0, 8, 7, 0, 0, 0, 0, 3, 1, 0, 0, 3, 0, 1, 0, 0,
+                            8, 0, 9, 0, 0, 8, 6, 3, 0, 0, 5, 0, 5, 0, 0, 9, 0,
+                            6, 0, 0, 1, 3, 0, 0, 0, 0, 2, 5, 0, 0, 0, 0, 0, 0,
+                            0, 0, 7, 4, 0, 0, 5, 2, 0, 6, 3, 0, 0};
+    struct sudoku a = {.N = 9, .N2 = 3, .a = test_array};
+    assert(solve(&a));  // ensure that solution is obtained
+                        // NOTE: `solve` is defined in another part of the code.
+
+    uint8_t expected[] = {3, 1, 6, 5, 7, 8, 4, 9, 2, 5, 2, 9, 1, 3, 4, 7, 6,
+                          8, 4, 8, 7, 6, 2, 9, 5, 3, 1, 2, 6, 3, 4, 1, 5, 9,
+                          8, 7, 9, 7, 4, 8, 6, 3, 1, 2, 5, 8, 5, 1, 7, 9, 2,
+                          6, 4, 3, 1, 3, 8, 9, 4, 7, 2, 5, 6, 6, 9, 2, 3, 5,
+                          1, 8, 7, 4, 7, 4, 5, 2, 8, 6, 3, 1, 9};
+    for (int i = 0; i < a.N; i++)
+        for (int j = 0; j < a.N; j++)
+            assert(a.a[i * a.N + j] == expected[i * a.N + j]);
+```
+
+3. Small C program that showcases and explains the use of tests.
+
+```c
+#include <stdio.h>      /// for IO operations
+#include <assert.h>     /// for assert
+#include <stdbool.h>    /// for bool
+
+/**
+ * @brief Verifies if the given array
+ * contains the given number on it.
+ * @param arr the array to be used for checking
+ * @param number the number to check if it's inside the array
+ * @return false if the number was NOT found in the array
+ * @return true if the number WAS found in the array
+ */
+bool is_number_on_array(const int *arr, const int number) {
+    for (int i = 0; i < sizeof(arr); i++) {
+        if (arr[i] == number) {
+            return true;
+        }
+        else {
+            // Number not in the current index, keep searching.
+        }
+    }
+
+    return false;
+}
+
+/**
+ * @brief Self-test implementations
+ * @returns void
+ */
+static void tests() {
+    int arr[] = { 9, 14, 21, 98, 67 };
+
+    assert(is_number_on_array(arr, 9) == true);
+    assert(is_number_on_array(arr, 4) == false);
+    assert(is_number_on_array(arr, 98) == true);
+    assert(is_number_on_array(arr, 512) == false);
+
+    printf("All tests have successfully passed!\n");
+}
+
+/**
+ * @brief Main function
+ * @returns 0 on exit
+ */
+int main() {
+    tests(); // run self-test implementations
+    return 0;
+}
+```
 
 #### Typical structure of a program
 

DIRECTORY.md

@@ -3,6 +3,7 @@
   * [Alaw](https://github.com/TheAlgorithms/C/blob/HEAD/audio/alaw.c)
 
 ## Cipher
+  * [Affine](https://github.com/TheAlgorithms/C/blob/HEAD/cipher/affine.c)
   * [Rot13](https://github.com/TheAlgorithms/C/blob/HEAD/cipher/rot13.c)
 
 ## Client Server
@@ -182,6 +183,7 @@
   * [Cartesian To Polar](https://github.com/TheAlgorithms/C/blob/HEAD/math/cartesian_to_polar.c)
   * [Catalan](https://github.com/TheAlgorithms/C/blob/HEAD/math/catalan.c)
   * [Collatz](https://github.com/TheAlgorithms/C/blob/HEAD/math/collatz.c)
+  * [Euclidean Algorithm Extended](https://github.com/TheAlgorithms/C/blob/HEAD/math/euclidean_algorithm_extended.c)
   * [Factorial](https://github.com/TheAlgorithms/C/blob/HEAD/math/factorial.c)
   * [Factorial Large Number](https://github.com/TheAlgorithms/C/blob/HEAD/math/factorial_large_number.c)
   * [Factorial Trailing Zeroes](https://github.com/TheAlgorithms/C/blob/HEAD/math/factorial_trailing_zeroes.c)