diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 042434a0..0c65d1b6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ Welcome to [TheAlgorithms/Nim](https://github.com/TheAlgorithms/Nim)! -We are very happy that you are considering working on algorithm and data structure implementations in Nim! This repository is meant to be referenced and used by learners from all over the globe, and we aspire to maintain the highest possible quality of the code presented here. This is why we ask you to **read all of the following guidelines beforehand** to know what we expect of your contributions. If you have any doubts about this guide, please feel free to [state them clearly in an issue](https://github.com/TheAlgorithms/Nim/issues/new) or ask the community in [Discord](https://the-algorithms.com/discord). +We are very happy that you are considering working on the algorithm and data structure implementations in Nim! This repository is meant to be referenced and used by learners from all over the globe, and we aspire to maintain the highest possible quality of the code presented here. This is why we ask you to **read all of the following guidelines beforehand** to know what we expect of your contributions. If you have any doubts about this guide, please feel free to [state them clearly in an issue](https://github.com/TheAlgorithms/Nim/issues/new) or ask the community in [Discord](https://the-algorithms.com/discord). ## Table Of Contents @@ -29,7 +29,7 @@ An Algorithm is one or more functions that: - return one or more outputs, - have minimal side effects (Examples of side effects: `echo()`, `rand()`, `read()`, `write()`). -## Contributor agreement +## Contributor Agreement Being one of our contributors, you agree and confirm that: @@ -40,7 +40,7 @@ Being one of our contributors, you agree and confirm that: We appreciate any contribution, from fixing a grammar mistake in a comment to implementing complex algorithms. Please check the [directory](DIRECTORY.md) and [issues](https://github.com/TheAlgorithms/Nim/issues/) for an existing (or declined) implementation of your algorithm and relevant discussions. -**New implementations** are welcome! This includes: new solutions for a problem, different representations for a data structure, algorithm design with a different complexity or features. +**New implementations** are welcome! This includes: new solutions for a problem, different representations for a data structure, and algorithm design with different complexity or features. **Improving documentation and comments** and **adding tests** is also highly welcome. @@ -53,15 +53,15 @@ We appreciate any contribution, from fixing a grammar mistake in a comment to im - The module should be thoroughly documented with doc comments. Follow the [Nim documentation style](https://nim-lang.org/docs/docstyle.html). - The file begins with the module-level documentation with the general description and explanation of the algorithm/data-structure. If possible, please include: * Any restrictions of the implementation and any constraints for the input data. - * An overview of the use-cases. + * An overview of the use cases. * Recommendations for when to use or avoid using it. * Comparison with the alternatives. * Links to source materials and further reading. - Use intuitive and descriptive names for objects, functions, and variables. - Return all calculation results instead of printing or plotting them. -- This repository is not simply a compilation of *how-to* examples for existing Nim packages and routines. Each algorithm implementation should add unique value. It is fine to leverage the standard library or third-party packages as long as it doesn't substitute writing the algorithm itself. In other words, you don't need to reimplement a basic hash table ([`std/tables`](https://nim-lang.org/docs/tables.html)) each time you need to use it, unless it is the goal of the module. +- This repository is not simply a compilation of *how-to* examples for existing Nim packages and routines. Each algorithm implementation should add unique value. It is fine to leverage the standard library or third-party packages as long as it doesn't substitute writing the algorithm itself. In other words, you don't need to reimplement a basic hash table ([`std/tables`](https://nim-lang.org/docs/tables.html)) each time you need to use it unless it is the goal of the module. - Avoid importing third-party libraries. Only use those for complicated algorithms and only if the alternatives of relying on the standard library or including a short amount of the appropriately-licensed external code are not feasible. -- The module has to include tests that check valid and erroneous input values and the appropriate edge-cases. See [Documentation, examples and tests](#documentation-examples-and-tests) below. +- The module has to include tests that check valid and erroneous input values and the appropriate edge cases. See [Documentation, examples and tests](#documentation-examples-and-tests) below. ### Nim Coding Style @@ -71,7 +71,7 @@ We want your work to be readable by others; therefore, we encourage you to follo - Help your readers by using **descriptive names** that eliminate the need for redundant comments. - Follow Nim conventions for naming: camelCase for variables and functions, PascalCase for types and objects, PascalCase or UPPERCASE for constants. -- Avoid single-letter variable names, unless it has a minimal lifespan. If your variable comes from a mathematical context or no confusion is possible with another variable, you may use single-letter variables. Generally, single-letter variables stop being OK if there's more than just a couple of them in a scope. Some examples: +- Avoid single-letter variable names, unless it has a minimal lifespan. If your variable comes from a mathematical context or no confusion is possible with another variable, you may use single-letter variables. Generally, single-letter variables stop being OK if there are more than just a couple of them in scope. Some examples: * Prefer `index` or `idx` to `i` for loops. * Prefer `src` and `dst` to `a` and `b`. * Prefer `remainder` to `r` and `prefix` to `p`. @@ -83,9 +83,9 @@ We want your work to be readable by others; therefore, we encourage you to follo #### Types -- Use the strictest types possible for the input, output and object fields. Prefer `Natural`, `Positive` or custom [subrange types](https://nim-lang.org/docs/manual.html#types-subrange-types) to unconstrained `int` where applicable, use `Natural` for indexing. +- Use the strictest types possible for the input, output, and object fields. Prefer `Natural`, `Positive` or custom [subrange types](https://nim-lang.org/docs/manual.html#types-subrange-types) to unconstrained `int` where applicable, use `Natural` for indexing. - On the other hand, write generic code where appropriate. Do not impose arbitrary limitations if the code can work on a wider range of data types. -- Don't use unsigned numerical types (`uint` and its sized variants), unless wrapping behaviour or binary manipulation is required for the algorithm. +- Don't use unsigned numerical types (`uint` and its sized variants), unless wrapping behavior or binary manipulation is required for the algorithm. - Prefer the [`Option[T]`](https://nim-lang.org/docs/options.html) to encode an [optional value](https://en.wikipedia.org/wiki/Option_type) instead of using an invalid value (like the `-1` or an empty string `""`), unless it is critical for the algorithm. It may be also fitting if you are looking for the equivalent of "NULL" (default value for pointers)[^null]. #### Exceptions and side-effects @@ -93,7 +93,7 @@ We want your work to be readable by others; therefore, we encourage you to follo - Raise Nim exceptions (`ValueError`, etc.) on erroneous input values. - Use [exception tracking](https://nim-lang.org/docs/manual.html#effect-system-exception-tracking). Right after the module-level documentation, add a `{.push raises: [].}` module pragma. This enforces that all `func`s don't raise any exceptions. If they do raise at least one, list them all with the `raises` pragma after the return type and before the `=` sign like this: `func foo(bar: int) {.raises: [IOError].} =`. -#### Documentation, examples and tests +#### Documentation, examples, and tests - It is incited to give a usage example after the module documentation and the `push raises` pragma in the top-level `runnableExamples` block. - Use the [`std/unittest` module](https://nim-lang.org/docs/unittest.html) to test your program. @@ -135,11 +135,11 @@ when isMainModule: ### Submissions Requirements - Make sure the code compiles before submitting. -- Look up the name of your algorithm in other active repositories of [TheAlgorithms](https://github.com/TheAlgorithms/), like [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python). By reusing the same name, your implementation will be appropriately grouped alongside other implementations on the [project's web site](https://the-algorithms.com/). +- Look up the name of your algorithm in other active repositories of [TheAlgorithms](https://github.com/TheAlgorithms/), like [TheAlgorithms/Python](https://github.com/TheAlgorithms/Python). By reusing the same name, your implementation will be appropriately grouped alongside other implementations on the [project's website](https://the-algorithms.com/). - Please help us keep our issue list small by adding fixes: Add the number of the issue you solved — even if only partially — to the commit message of your pull request. - Use *snake_case* (words separated with an underscore `_`) for the filename. - Try to fit your work into the existing directory structure as much as possible. Please open an issue first if you want to create a new subdirectory. -- Writing documentation, be concise and check your spelling and grammar. +- Writing documentation, be concise, and check your spelling and grammar. - Add a corresponding explanation to [Algorithms-Explanation](https://github.com/TheAlgorithms/Algorithms-Explanation) (optional but recommended). - Most importantly, **be consistent in the use of these guidelines**. diff --git a/DIRECTORY.md b/DIRECTORY.md index 3a46fe67..efbb09ef 100644 --- a/DIRECTORY.md +++ b/DIRECTORY.md @@ -13,6 +13,9 @@ * [Arc Length](maths/arc_length.nim) * [Bitwise Addition](maths/bitwise_addition.nim) +## Strings + * [Check Anagram](strings/check_anagram.nim) + ## Searches * [Binary Search](searches/binary_search.nim) * [Linear Search](searches/linear_search.nim) diff --git a/dynamic_programming/catalan_numbers.nim b/dynamic_programming/catalan_numbers.nim index f1a6f76d..e2562251 100644 --- a/dynamic_programming/catalan_numbers.nim +++ b/dynamic_programming/catalan_numbers.nim @@ -1,7 +1,7 @@ ## Catalan Numbers #[ The Catalan numbers are a sequence of natural numbers that occur in the - most large set of combinatorial problems. + the largest set of combinatorial problems. For example, it describes: - the number of ways to parenthesize a product of n factors - the number of ways to form a binary search tree with n+1 leaves @@ -98,13 +98,13 @@ when isMainModule: doAssert (CatalanNumbersList[i] == createCatalanTable(36)[i]) suite "Catalan Numbers": - test "The seventeen first Catalan numbers recursively, first formula": + test "The seventeen first Catalan numbers recursively, the first formula": let limit = RecursiveLimit for index in 0 .. limit: let catalanNumber = catalanNumbersRecursive(index) check catalanNumber == CatalanNumbersList[index] - test "The thirty-one first Catalan numbers recursively, second formula": + test "The thirty-one first Catalan numbers recursively, the second formula": let limit = LowerLimit for index in 0 .. limit: let catalanNumber = catalanNumbersRecursive2(index) @@ -126,7 +126,7 @@ when isMainModule: check catalanNumber == CatalanNumbersList[index] inc index - test "Test the catalan number function with binomials": + test "Test the Catalan number function with binomials": let limit = LowerLimit for index in 0 .. limit: check catalanNumbers2(index) == CatalanNumbersList[index] diff --git a/dynamic_programming/viterbi.nim b/dynamic_programming/viterbi.nim index e8629fbd..1b1bd483 100644 --- a/dynamic_programming/viterbi.nim +++ b/dynamic_programming/viterbi.nim @@ -1,4 +1,13 @@ ## Viterbi +## The Viterbi algorithm is a dynamic programming algorithm +## for obtaining the maximum a posteriori probability estimate +## of the most likely sequence of hidden states +## https://en.wikipedia.org/wiki/Viterbi_algorithm +## +## Time Complexity: O(K2n) +## Space Complexity: O(Kn) +## https://www.cs.cmu.edu/~epxing/Class/10708-20/scribe/lec4_scribe.pdf + {.push raises: [].} type diff --git a/strings/check_anagram.nim b/strings/check_anagram.nim index 9a3ef7ba..433ce0e3 100644 --- a/strings/check_anagram.nim +++ b/strings/check_anagram.nim @@ -9,7 +9,7 @@ ## - They are not the same word (a word is not an anagram of itself). ## ## A word is any string of characters `{'A'..'Z', 'a'..'z'}`. Other characters, -## including whitespace, numbers and punctuation, are considered invalid and +## including whitespace, numbers, and punctuation, are considered invalid and ## raise a `ValueError` exception. ## ## Note: Generate full doc with `nim doc --docinternal check_anagram.nim` @@ -56,7 +56,7 @@ func toLowerUnchecked(c: char): char {.inline.} = assert c in UpperAlpha # The difference between numerical values for chars of uppercase and # lowercase alphabets in the ASCII table is 32. Uppercase letters start from - # 0b100_0001, so setting the sixth bit to 1 gives letter's lowercase pair. + # 0b100_0001, so setting the sixth bit to 1 gives the letter's lowercase pair. char(uint8(c) or 0b0010_0000'u8) template normalizeChar(c: char) =