Merge branch 'master' into master

Author: giuseppe-coco

.github/workflows/codeql.yml

@@ -1,51 +1,61 @@
-name: "CodeQL"
+name: "Code Scanning - Action"
 
 on:
   push:
-    branches: [ "master" ]
+    branches: [master]
   pull_request:
-    branches: [ "master" ]
+    branches: [master]
+  schedule:
+    #        ┌───────────── minute (0 - 59)
+    #        │  ┌───────────── hour (0 - 23)
+    #        │  │ ┌───────────── day of the month (1 - 31)
+    #        │  │ │ ┌───────────── month (1 - 12 or JAN-DEC)
+    #        │  │ │ │ ┌───────────── day of the week (0 - 6 or SUN-SAT)
+    #        │  │ │ │ │
+    #        │  │ │ │ │
+    #        │  │ │ │ │
+    #        *  * * * *
+    - cron: '30 1 * * 0'
 
 jobs:
-  analyze:
-    name: Analyze
+  CodeQL-Build:
+    # CodeQL runs on ubuntu-latest, windows-latest, and macos-latest
     runs-on: ubuntu-latest
+
     permissions:
+      # required for all workflows
+      security-events: write
+
+      # only required for workflows in private repositories
       actions: read
       contents: read
-      security-events: write
+
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-    - name: Initialize CodeQL
-      uses: github/codeql-action/init@v2
-      with:
-        languages: cpp
-        # If you wish to specify custom queries, you can do so here or in a config file.
-        # By default, queries listed here will override any specified in a config file.
-        # Prefix the list here with "+" to use these queries and those in the config file.
-
-        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
-        # queries: security-extended,security-and-quality
-
-    # Autobuild attempts to build any compiled languages  (C/C++, C#, Go, or Java).
-    # If this step fails, then you should remove it and run the build manually (see below)
-    - name: Autobuild
-      uses: github/codeql-action/autobuild@v2
-
-    # ℹ️ Command-line programs to run using the OS shell.
-    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
-
-    #   If the Autobuild fails above, remove it and uncomment the following three lines.
-    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
-
-    # - run: |
-    #   echo "Run, Build Application using script"
-    #   ./location_of_script_within_repo/buildscript.sh
-    #
-    #   In our case, this would be a CMake build step.
-
-    - name: Perform CodeQL Analysis
-      uses: github/codeql-action/analyze@v2
-      with:
-        category: "/language:cpp"
+      - name: Checkout repository
+        uses: actions/checkout@v3
+
+      # Initializes the CodeQL tools for scanning.
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        # Override language selection by uncommenting this and choosing your languages
+        with:
+          languages: cpp
+
+      # Autobuild attempts to build any compiled languages (C/C++, C#, Go, or Java).
+      # If this step fails, then you should remove it and run the build manually (see below).
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      # ℹ️ Command-line programs to run using the OS shell.
+      # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+
+      # ✏️ If the Autobuild fails above, remove it and uncomment the following
+      #    three lines and modify them (or add more) to build your code if your
+      #    project uses a compiled language
+
+      #- run: |
+      #     make bootstrap
+      #     make release
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

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,91 @@ 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<uint64_t> arr = {5, 3, 8, 12, 14, 16, 28, 96, 2, 5977};
+std::vector<uint64_t> 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<int32_t> 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 <iostream>  /// for IO operations
+#include <vector>    /// for std::vector
+#include <cassert>   /// 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 <typename T>
+bool is_number_on_array(const std::vector<T> &arr, const int &number) {
+    for (int i = 0; i < sizeof(arr) / sizeof(int); 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() {
+    std::vector<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);
+
+    std::cout << "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
 
 ```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 +152,7 @@ You can add new algorithms or data structures that are **not present in the repo
 #include             /// for `some function here`
 
 /**
- * @namespace <folder name>
+ * @namespace
  * @brief <namespace description>
  */
 namespace name {
@@ -119,6 +197,9 @@ static void test() {
     assert(func(...) == ...); // this ensures that the algorithm works as expected
 
     // can have multiple checks
+
+    // this lets the user know that the tests have passed
+    std::cout << "All tests have successfully passed!\n";
 }
 
 /**

DIRECTORY.md

@@ -375,6 +375,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)

README.md

@@ -2,7 +2,7 @@
 <!-- the suffix in the above line is required for doxygen to consider this as the index page of the generated documentation site -->
 
 [![Gitpod Ready-to-Code](https://img.shields.io/badge/Gitpod-Ready--to--Code-blue?logo=gitpod)](https://gitpod.io/#https://github.com/TheAlgorithms/C-Plus-Plus)
-[![CodeQL CI](https://github.com/TheAlgorithms/C-Plus-Plus/actions/workflows/codeql.yml/badge.svg)](https://github.com/TheAlgorithms/C-Plus-Plus/actions/workflows/codeql_analysis.yml)
+[![CodeQL CI](https://github.com/TheAlgorithms/C-Plus-Plus/actions/workflows/codeql.yml/badge.svg)](https://github.com/TheAlgorithms/C-Plus-Plus/actions/workflows/codeql.yml)
 [![Gitter chat](https://img.shields.io/badge/Chat-Gitter-ff69b4.svg?label=Chat&logo=gitter&style=flat-square)](https://gitter.im/TheAlgorithms)
 [![contributions welcome](https://img.shields.io/static/v1.svg?label=Contributions&message=Welcome&color=0059b3&style=flat-square)](https://github.com/TheAlgorithms/C-Plus-Plus/blob/master/CONTRIBUTING.md)
 ![GitHub repo size](https://img.shields.io/github/repo-size/TheAlgorithms/C-Plus-Plus?color=red&style=flat-square)

data_structures/segment_tree.cpp

@@ -0,0 +1,133 @@
+/**
+ * @file
+ * @brief A data structure to quickly do operations on ranges: the [Segment Tree](https://en.wikipedia.org/wiki/Segment_tree) algorithm implementation
+ * @details
+ * Implementation of the segment tree data structre
+ *
+ * Can do point updates (updates the value of some position)
+ * and range queries, where it gives the value of some associative
+ * opperation done on a range
+ *
+ * Both of these operations take O(log N) time
+ * @author [Nishant Chatterjee](https://github.com/nishantc1527)
+ */
+
+#include <iostream>     /// For IO operations
+#include <vector>       /// For std::vector
+#include <algorithm>    /// For std::min and std::max
+#include <cassert>      /// For assert
+
+/*
+ * @namespace
+ * @brief Data structures
+ */
+namespace data_structures {
+/**
+ * @brief class representation of the segment tree
+ * @tparam T The type of the class that goes in the datastructure
+ */
+template <class T>
+class SegmentTree {
+private:
+    const T ID = 0;   ///< Comb(ID, x) = x
+    std::vector<T> t; ///< Vector to represent the tree
+    int size = 0;     ///< Number of elements available for querying in the tree
+private:
+    /**
+     * @brief Any associative function that combines x and y
+     * @param x The first operand
+     * @param y The second operand
+     * @return Some associative operation applied to these two values. In this case, I used addition
+     */
+    T comb(T x, T y) {
+        return x + y;
+    }
+    /**
+     * @brief Gives the midpoint between two integers
+     * @param l The left endpoint
+     * @param r The right endpoint
+     * @return the middle point between them
+     */
+    int mid(int l, int r) {
+        return l + (r - l) / 2;
+    }
+    /**
+     * @brief Helper method for update method below
+     * @param i The index of the current node
+     * @param l The leftmost node of the current node
+     * @param r The rightmost node of the current node
+     * @param pos The position to update
+     * @param val The value to update it to
+     */
+    void update(int i, int l, int r, int pos, T val) {
+        if(l == r) t[i] = val;
+        else {
+            int m = mid(l, r);
+            if(pos <= m) update(i * 2, l, m, pos, val);
+            else update(i * 2 + 1, m + 1, r, pos, val);
+            t[i] = comb(t[i * 2], t[i * 2 + 1]);
+        }
+    }
+    /**
+     * @brief Helper method for range_comb method below
+     * @param i The current node
+     * @param l The leftmost node of the current node
+     * @param r The rightmost node of the current node
+     * @param tl The left endpoint of the range
+     * @param tr The right endpoint of the range
+     * @return The comb operation applied to all values between tl and tr
+     */
+    T range_comb(int i, int l, int r, int tl, int tr) {
+        if(l == tl && r == tr) return t[i];
+        if(tl > tr) return 0;
+        int m = mid(l, r);
+        return comb(range_comb(i * 2, l, m, tl, std::min(tr, m)), range_comb(i * 2 + 1, m + 1, r, std::max(tl, m + 1), tr));
+    }
+public:
+    SegmentTree(int n) : t(n * 4, ID), size(n) {}
+    /** 
+     * @brief Updates a value at a certain position
+     * @param pos The position to update
+     * @param val The value to update it to
+     */
+    void update(int pos, T val) {
+        update(1, 1, size, pos, val);
+    }
+    /**
+     * @brief Returns comb across all values between l and r
+     * @param l The left endpoint of the range
+     * @param r The right endpoint of the range
+     * @return The value of the comb operations
+     */
+    T range_comb(int l, int r) {
+        return range_comb(1, 1, size, l, r);
+    }
+};
+} // namespace data_structures
+
+/**
+ * @brief Self-test implementations
+ * @returns void
+ */
+static void test() {
+    data_structures::SegmentTree<int> t(5);
+    t.update(1, 1);
+    t.update(2, 2);
+    t.update(3, 3);
+    t.update(4, 4);
+    t.update(5, 5);
+    assert(t.range_comb(1, 3) == 6); // 1 + 2 + 3 = 6
+    t.update(1, 3);
+    assert(t.range_comb(1, 3) == 8); // 3 + 2 + 3 = 8
+
+    std::cout << "All tests have successfully passed!\n";
+}
+
+/**
+ * @brief Main function
+ * @returns 0 on exit
+ */
+int main() {
+    test();  // run self-test implementations
+    return 0;
+}