Skip to content

Commit

Permalink
Updated readme / docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Timmoth
Timmoth committed Jun 16, 2024
1 parent c106fdc commit e75a40c
Show file tree
Hide file tree
Showing 18 changed files with 101 additions and 340 deletions.
347 changes: 35 additions & 312 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,318 +1,41 @@
# DsaDotnet
A dotnet class library containing a collection of algorithms and datastructures.
[![NuGet](https://img.shields.io/nuget/v/DsaDotnet)](https://www.nuget.org/packages/DsaDotnet)

The objective of this library is to cement my understanding of datastructures & algorithms whilst also trying out some of dotnet 8' latest features.
A collection of optimised algorithms and datastructures.

If you can think of a way to improve any of the existing implementations feel free to open a PR and see if you can beat my benchmarks!

## [Benchmarks](Benchmarks/)
## [Docs](https://timmoth.github.io/DsaDotnet/)
- [Overview](https://timmoth.github.io/DsaDotnet/)
- [Releases](https://timmoth.github.io/DsaDotnet/releases/)
- [Tests](https://timmoth.github.io/DsaDotnet/tests/)
- [Benchmarks](https://timmoth.github.io/DsaDotnet/benchmarks/)
- [Contributing](https://timmoth.github.io/DsaDotnet/contributing/)

### Arithmetic
- [Greatest Common Divisor](https://timmoth.github.io/DsaDotnet/Arithmetic/greatest_common_divisor/)
- [Least Common Multiple](https://timmoth.github.io/DsaDotnet/Arithmetic/least_common_multiple/)

### Data Structures
- [Binary Tree](https://timmoth.github.io/DsaDotnet/DataStructures/binary_tree/)
- [Unweighted Graph](https://timmoth.github.io/DsaDotnet/DataStructures/unweighted_graph/)
- [Weighted Graph](https://timmoth.github.io/DsaDotnet/DataStructures/weighted_graph/)

### Search
- [Binary](https://timmoth.github.io/DsaDotnet/Search/binary_search/)
- [Breadth First](https://timmoth.github.io/DsaDotnet/Search/breadth_first_search/)
- [Depth First](https://timmoth.github.io/DsaDotnet/Search/depth_first_search/)
- [Djikstras](https://timmoth.github.io/DsaDotnet/Search/djikstras/)
- [Linear](https://timmoth.github.io/DsaDotnet/Search/linear_search/)

### Sequence And Series
- [Factorial](https://timmoth.github.io/DsaDotnet/SequenceAndSeries/factorial/)
- [Fibonacci](https://timmoth.github.io/DsaDotnet/SequenceAndSeries/fibonacci/)
- [Primes](https://timmoth.github.io/DsaDotnet/SequenceAndSeries/primes/)

### Sorting
- [Bubble](https://timmoth.github.io/DsaDotnet/Sorting/bubble_sort/)
- [Insertion](https://timmoth.github.io/DsaDotnet/Sorting/insertion_sort/)
- [Merge](https://timmoth.github.io/DsaDotnet/Sorting/merge_sort/)
- [Quick](https://timmoth.github.io/DsaDotnet/Sorting/quick_sort/)

Each push to main triggers the benchmarks to be ran and compared against the previous version, [you can see them here](https://timmoth.github.io/DsaDotnet/dev/bench/)

Run all the benchmarks locally
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release --job short --filter '*' --memory --join
```

Run a specific set of benchmarks
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release --job short --memory --f *Fibonacci*
```

## [Tests](Tests/)
All tests must pass before a PR can be merged into main.

Run all the tests locally
```console
dotnet test
```

I use [Stryker mutation testing](https://github.com/stryker-mutator/stryker-net) to help identify missing tests

[View the Stryker report here](https://dashboard.stryker-mutator.io/reports/github.com/Timmoth/DsaDotnet/main#mutant)
```console
dotnet tool install --global dotnet-stryker
dotnet-stryker
```
Running Stryker will output a report outlining which mutations (essentially bugs) were introduced into your code that did not cause any tests to fail.

## Data Structures

### [Binary Tree](DsaDotnet/Trees/BinaryTree.cs/)
A hierarchical data structure composed of nodes. Each node can have a left and right child node where left node is less than and the right node is greater than the parent node.

Usage
```cs
var tree = new BinaryTree<int>();
tree.Insert(0, 1, 2, 3);
var node = tree.Search(2);
```

### [Unweighted Graph](DsaDotnet/Graphs/UnWeightedGraph.cs)
A collection of vertices connected by edges.

Usage
```cs
var graph = new UnWeightedGraph<int>();
graph.AddEdges((0, 1), (1, 2), (2, 3));
```

### [Weighted Graph](DsaDotnet/Graphs/WeightedGraph.cs)
A collection of vertices connected by edges, where each edge has an associated weight.

Usage
```cs
var graph = new WeightedGraph<int>();
graph.AddEdges(new []{(0, 1), (1, 2), (2, 3)}, 1);
graph.AddEdges((3, 4, 1), (4, 5, 1));

```

## Sequence and Series Algorithms
To run the benchmarks for all Sequence and Series algorithms:
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --allCategories=Series --join
```

### [Factorial](DsaDotnet/Series/Factorial.cs)
---
Denoted by n!, the factorial of an unsigned integer is the product of all integers less then or equal to n.

```
n! = n * (n-1) * (n-2) * ... * 3 * 2 * 1
0! = 1
1! = 1
2! = 2
3! = 6
```

Usage
```cs
ulong result = Series.Factorial(1000);
result = 1000.Factorial();
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *Factorial*
```

### [Fibonacci](DsaDotnet/Series/Fibonacci.cs)
---
A sequence where each term is the sum of the two preceding terms, starting with 0 and 1.

```
f(0) = 0
f(1) = 1
f(n) = f(n-1) + f(n-2)
0, 1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144, ...
```

Usage
```cs
ulong result = Series.Fibonacci(1000);
result = 1000.Fibonacci();
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *Fibonacci*
```

### [Primes](DsaDotnet/Series/Primes.cs)
---
Unsigned integers greater than 1 that have no positive divisors other than 1 and themselves.

```
2, 3, 5, 7, 11, 13, 17, 19, 23, 29
```

Usage
```cs
List<int> result = Series.PrimesUpTo(1000);
result = 1000.PrimesUpTo();
```
Benchmarks
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *Primes*
```

## Search Algorithms
To run the benchmarks for all search algorithms:
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --allCategories=Search --join
```

### [Linear Search](DsaDotnet/Search/LinearSearch.cs)
---

Iterate through each element sequentially from the start until the end until the desired element is found.

Usage
```cs
var index = new []{ 1, 2, 3}.LinearSearch(2);
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *LinearSearch*
```

### [Binary Search](DsaDotnet/Search/BinarySearch.cs)
---

Find a value within a sorted array by dividing the search interval in half at each step.

Usage
```cs
var index = new []{ 1, 2, 3}.BinarySearch(2);
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *BinarySearch*
```

### [Breadth First Search](DsaDotnet/Search/Bfs.cs)
---

Explore all neighbor nodes at the present depth before moving on to nodes at the next depth level.

Usage
```cs
var graph = new UnWeightedGraph<int>();
graph.AddEdges((0, 1), (1, 2), (2, 3));
var node = graph.BreadthFirstSearch(0, n => n.Key == 3);
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *Bfs*
```

### [Depth First Search](DsaDotnet/Search/Dfs.cs)
---

Explore as far as possible along each branch before backtracking.

Usage
```cs
var graph = new UnWeightedGraph<int>();
graph.AddEdges((0, 1), (1, 2), (2, 3));
var node = graph.DepthFirstSearch(0, n => n.Key == 3);
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *Dfs*
```

### [Dijkstra's](DsaDotnet/Search/Dijkstra.cs)
---

Find the shortest path between nodes in a graph with non-negative edge weights, by iteratively selecting the node with the minimum distance from the starting node and updating distances to adjacent nodes.

Usage
```cs
var graph = new WeightedGraph<int>();
graph.AddEdges((0, 1), (1, 2), (2, 3));
var path = graph.Dijkstra(0, n => n.Key == 3);
```
Benchmarks
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *Dijkstra*
```

## Sorting Algorithms

To run the benchmarks for all sorting algorithms:
```
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --allCategories=Sorting --join
```

### [Bubble Sort](DsaDotnet/Sorting/Bubble.cs)
---

Repeatedly steps through the list, compares adjacent elements, and swaps them if they are in the wrong order, continuing until the list is sorted.

Usage
```cs
List<int> result = new[] { 5, 4, 3, 2, 1 }.BubbleSort();

int[] input = new[] { 5, 4, 3, 2, 1 };
input.BubbleSortInPlace();
```
Benchmarks
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *BubbleSort*
```

### [Insertion Sort](DsaDotnet/Sorting/Insertion.cs)
---

Builds the final sorted list one item at a time, taking each element from the input list and inserting it into its correct position within the already sorted part of the list.

Usage
```cs
List<int> result = new[] { 5, 4, 3, 2, 1 }.InsertionSort();

int[] input = new[] { 5, 4, 3, 2, 1 };
input.InsertionSort();
```
Benchmarks
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *InsertionSort*
```

### [Merge Sort](DsaDotnet/Sorting/Merge.cs)
---

Divides the input list into smaller lists, sorts those smaller lists, and then merges them back together in a sorted manner.

Usage
```cs
List<int> result = new[] { 5, 4, 3, 2, 1 }.MergeSort();

int[] input = new[] { 5, 4, 3, 2, 1 };
input.MergeSort();
```
Benchmarks
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *MergeSort*
```

### [Quick Sort](DsaDotnet/Sorting/Quick.cs)
---

Uses a divide-and-conquer strategy by selecting a "pivot" element from the list and partitioning the other elements into two sub-lists according to whether they are less than or greater than the pivot. The sub-lists are then sorted recursively.

Usage
```cs
List<int> result = new[] { 5, 4, 3, 2, 1 }.QuickSort();

int[] input = new[] { 5, 4, 3, 2, 1 };
input.QuickSort();
```
Benchmarks
```console
dotnet run --project ./Benchmarks/Benchmarks.csproj -c Release -- --job short --memory --f *QuickSort*
```

## Arithmetic Algorithms

### [Greatest Common Divisor](DsaDotnet/Arithmetic/GCD.cs)
---

The largest positive integer that divides two or more numbers without leaving a remainder.

Usage
```cs
var result = Arithmetic.GCD(10, 20);
```

### [Least Common Multiple](DsaDotnet/Arithmetic/LCM.cs)
---

The smallest positive integer that is a multiple of two or more numbers.

Usage
```cs
var result = Arithmetic.LCM(10, 20);
result = Arithmetic.LCM(10, 20, 30);
```
4 changes: 3 additions & 1 deletion docs/Arithmetic/greatest_common_divisor.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,4 +5,6 @@ The largest positive integer that divides two or more numbers without leaving a
#### Usage
```cs
var result = Arithmetic.GCD(10, 20);
```
```

#### [Tests](https://github.com/Timmoth/DsaDotnet/blob/main/Tests/Arithmetic/GCDTests.cs)
4 changes: 3 additions & 1 deletion docs/Arithmetic/least_common_multiple.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,6 @@ The smallest positive integer that is a multiple of two or more numbers.
```cs
var result = Arithmetic.LCM(10, 20);
result = Arithmetic.LCM(10, 20, 30);
```
```

#### [Tests](https://github.com/Timmoth/DsaDotnet/blob/main/Tests/Arithmetic/LCMTests.cs)
4 changes: 3 additions & 1 deletion docs/DataStructures/binary_tree.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,4 +7,6 @@ A hierarchical data structure composed of nodes. Each node can have a left and r
var tree = new BinaryTree<int>();
tree.Insert(0, 1, 2, 3);
var node = tree.Search(2);
```
```

#### [Tests](https://github.com/Timmoth/DsaDotnet/blob/main/Tests/Trees/BinaryTreeTests.cs)
4 changes: 3 additions & 1 deletion docs/DataStructures/unweighted_graph.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,4 +6,6 @@ A collection of vertices connected by edges.
```cs
var graph = new UnWeightedGraph<int>();
graph.AddEdges((0, 1), (1, 2), (2, 3));
```
```

#### [Tests](https://github.com/Timmoth/DsaDotnet/blob/main/Tests/Graphs/GraphTests.cs)
4 changes: 3 additions & 1 deletion docs/DataStructures/weighted_graph.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,6 @@ A collection of vertices connected by edges, where each edge has an associated w
graph.AddEdges(new []{(0, 1), (1, 2), (2, 3)}, 1);
graph.AddEdges((3, 4, 1), (4, 5, 1));

```
```

#### [Tests](https://github.com/Timmoth/DsaDotnet/blob/main/Tests/Graphs/GraphTests.cs)
Loading

0 comments on commit e75a40c

Please sign in to comment.