From d07ab7d0f1b3845e3de73b1642ed2cb25638b933 Mon Sep 17 00:00:00 2001 From: David Leal Date: Thu, 27 Apr 2023 10:38:05 -0600 Subject: [PATCH] docs: add self-test examples (#1250) * docs: add self-test examples * updating DIRECTORY.md --------- Co-authored-by: github-actions[bot] --- CONTRIBUTING.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ DIRECTORY.md | 2 ++ 2 files changed, 98 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 87686af3..01638a59 100644 --- a/CONTRIBUTING.md +++ b/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 /// for IO operations +#include /// for assert +#include /// 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 diff --git a/DIRECTORY.md b/DIRECTORY.md index cad509a7..d970ad9c 100644 --- a/DIRECTORY.md +++ b/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)