From 842c4ab5dd1eb9999a87a47e4c529d73c73e52f8 Mon Sep 17 00:00:00 2001 From: David Leal Date: Fri, 21 Apr 2023 10:10:54 -0600 Subject: [PATCH] docs: add self-test examples (#2452) * docs: add self-test examples * updating DIRECTORY.md --------- Co-authored-by: github-actions[bot] --- CONTRIBUTING.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++-- DIRECTORY.md | 1 + 2 files changed, 76 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f8f505ae8..18f7eab5d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -33,7 +33,7 @@ You can add new algorithms or data structures that are **not present in the repo - Make sure the file extensions are `*.hpp`, `*.h` or `*.cpp`. - Don't use **`bits/stdc++.h`** because this is quite Linux-specific and slows down the compilation process. - Organize your code using **`struct`**, **`class`**, and/or **`namespace`** keywords. -- If an implementation of the algorithm already exists, please refer to the [file-name section below](#new-file-name-guidelines). +- If an implementation of the algorithm already exists, please refer to the [file-name section below](#file-name-guidelines). - You can suggest reasonable changes to existing algorithms. - Strictly use snake_case (underscore_separated) in filenames. - If you have added or modified code, please make sure the code compiles before submitting. @@ -54,13 +54,85 @@ You can add new algorithms or data structures that are **not present in the repo - 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 `cassert` 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. [Quick sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/sorting/quick_sort.cpp#L137) testing (complex). + +```cpp +// Let's make sure the array of numbers is ordered after calling the function. +std::vector arr = {5, 3, 8, 12, 14, 16, 28, 96, 2, 5977}; +std::vector arr_sorted = sorting::quick_sort::quick_sort( + arr, 0, int(std::end(arr) - std::begin(arr)) - 1); + +assert(std::is_sorted(std::begin(arr_sorted), std::end(arr_sorted))); +``` + +2. [Subset Sum](https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/backtracking/subset_sum.cpp#L58) testing (medium). + +```cpp +std::vector array1 = {-7, -3, -2, 5, 8}; // input array +assert(backtracking::subset_sum::number_of_subsets(0, array1) == + 2); // first argument in subset_sum function is the required sum and + // second is the input array +``` + +3. Small C++ program that showcases and explains the use of tests. + +```cpp +#include /// for std::vector +#include /// for assert + +/** + * @brief Verifies if the given array + * contains the given number on it. + * @tparam T the type of array (e.g., `int`, `float`, etc.) + * @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 + */ +template +bool is_number_on_array(const std::vector &arr, const int &number) { + for (int i = 0; i < sizeof(arr) / sizeof(int); i++) { + if (arr[i] == number) { + return true; + } + else { + return false; + } + } + + return false; +} + +/** + * @brief Self-test implementations + * @returns void + */ +static void tests() { + std::vector arr = { 9, 14, 21, 98, 67 }; + + assert(is_number_on_array(arr, 9) == true); + assert(is_number_on_array(arr, 4) == false); +} + +/** + * @brief Main function + * @returns 0 on exit + */ +int main() { + tests(); // run self-test implementations +} +``` #### Typical structure of a program ```cpp /** * @file - * @brief Add one line description here. Should contain a Wikipedia + * @brief Add one-line description here. Should contain a Wikipedia * link or another source explaining the algorithm/implementation. * @details * This is a multi-line @@ -74,7 +146,7 @@ You can add new algorithms or data structures that are **not present in the repo #include /// for `some function here` /** - * @namespace + * @namespace * @brief */ namespace name { diff --git a/DIRECTORY.md b/DIRECTORY.md index 99c1c71b3..86d2835bc 100644 --- a/DIRECTORY.md +++ b/DIRECTORY.md @@ -374,6 +374,7 @@ * [Shell Sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/shell_sort.cpp) * [Shell Sort2](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/shell_sort2.cpp) * [Slow Sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/slow_sort.cpp) + * [Stooge Sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/stooge_sort.cpp) * [Strand Sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/strand_sort.cpp) * [Swap Sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/swap_sort.cpp) * [Tim Sort](https://github.com/TheAlgorithms/C-Plus-Plus/blob/HEAD/sorting/tim_sort.cpp)