diff --git a/README.md b/README.md index 2f38a60..0b9fd70 100644 --- a/README.md +++ b/README.md @@ -15,23 +15,30 @@ X10D (pronounced *extend*), is a .NET package that provides extension methods fo *(I'm also [dogfooding](https://www.pcmag.com/encyclopedia/term/dogfooding) this library, so there's that.)* ## Installation + ### NuGet installation + ```ps Install-Package X10D -Version 4.0.0 ``` ### Manual installation + Download the [latest release](https://github.com/oliverbooth/X10D/releases/latest) from this repository and adding a direct assembly reference for your chosen platform. ### Unity installation + For the Unity installation guide, refer to the [README.md in X10D.Unity](X10D.Unity/README.md). -## Features -I'm planning on writing complete and extensive documentation in the near future. As of this time, feel free to browse the source or the API using your favourite IDE. -For those familiar with the 2.6.0 API, please read [CHANGELOG.md](CHANGELOG.md) for a complete list of changes. **3.0.0 is a major release and introduces many breaking changes.** +## Documentation + +Documentation and the API reference is available at https://oliverbooth.github.io/X10D/index.html. *I'm sorry this took +so long to get up and running. DocFX will be the death of me.* ## Contributing + Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). ## License + X10D is released under the MIT License. See [here](https://github.com/oliverbooth/X10D/blob/main/LICENSE.md) for more details. diff --git a/docfx_project/articles/intro.md b/docfx_project/articles/intro.md index c0478ce..3104f6b 100644 --- a/docfx_project/articles/intro.md +++ b/docfx_project/articles/intro.md @@ -1 +1,86 @@ -# Add your introductions here! +## X10D +X10D (pronounced *extend*), is a .NET package that provides extension methods for numerous types. The purpose of this library is to simplify a codebase by reducing the need for repeated code when performing common operations. Simplify your codebase. Take advantage of .NET. Use extension methods. + +*(I'm also [dogfooding](https://www.pcmag.com/encyclopedia/term/dogfooding) this library, so there's that.)* + +### What are extension methods? + +Extension methods are a clever .NET feature that augment existing types with new functionality. They are defined as +static methods in a static class, and are called as if they were instance methods on the type they are extending. Take, +for example, the following code: + +```csharp +public static class Program +{ + public static void Main() + { + string str = "Hello, world!"; + Console.WriteLine(str.Reverse()); + } +} + +public static class StringExtensions +{ + public static string Reverse(this string str) + { + char[] chars = str.ToCharArray(); + Array.Reverse(chars); + return new string(chars); + } +} +``` + +This will print `!dlrow ,olleH` to the console. The `Reverse` method is defined in the `StringExtensions` class, yet is +called as if it were an instance method on the `str` variable, even though it's not. + +### Why use extension methods? + +Extension methods were introduced when LINQ was added to .NET. LINQ is a set of extension methods that provide a way to +query, filter, and transform data. If you were to access LINQ's methods statically, you would have to write code like +this: + +```csharp +public static class Program +{ + public static void Main() + { + int[] numbers = { 1, 2, 3, 4, 5 }; + IEnumerable evenNumbers = Enumerable.Where(numbers, x => x % 2 == 0); + IEnumerable doubledNumbers = Enumerable.Select(evenNumbers, x => x * 2); + int sum = Enumerable.Sum(doubledNumbers); + Console.WriteLine(sum); + } +} +``` + +And if you wanted to one-line this, you'd have to write this: + +```csharp +public static class Program +{ + public static void Main() + { + int[] numbers = { 1, 2, 3, 4, 5 }; + Console.WriteLine(Enumerable.Sum(Enumerable.Select(Enumerable.Where(numbers, x => x % 2 == 0), x => x * 2))); + } +} +``` + +This is a lot of code to write, and it's not very readable. The nested method calls make it incredibly difficult to +follow. However, because LINQ is implemented as extension methods, you can write the following code instead: + +```csharp +public static class Program +{ + public static void Main() + { + int[] numbers = { 1, 2, 3, 4, 5 }; + Console.WriteLine(numbers.Where(x => x % 2 == 0).Select(x => x * 2).Sum()); + } +} +``` + +Because the methods are called as if they were instance methods on `IEnumerable`, they can be chained together, +making the code much more readable. + +X10D aims to provide these same benefits as LINQ, but for dozens of other types and for countless other use cases. \ No newline at end of file diff --git a/docfx_project/articles/migration-from-3.x.x.md b/docfx_project/articles/migration-from-3.x.x.md new file mode 100644 index 0000000..1dbe179 --- /dev/null +++ b/docfx_project/articles/migration-from-3.x.x.md @@ -0,0 +1,52 @@ +# Migration from 3.x.x + +X10D 4.0.0 is a major release that introduces breaking changes. This document will help you migrate your code from 3.x.x +to 4.0.0. + +## Removed APIs + +### X10D.DSharpPlus library + +The `X10D.DSharpPlus` library has been removed. This library was used to provide extension methods for the DSharpPlus +wrapper library. However, I have since moved to using a different library, and as such, I feel it is no longer in the +scope of X10D or in my best interest to maintain it. The library will remain available on NuGet until DSharpPlus release +5.0.0 as stable, and X10D.DSharpPlus will NOT be part of X10D 4.0.0. I'm sorry for any inconvenience this may cause. + +### `Endianness` enum + +The `Endianness` enum was used to specify the endianness of data when reading or writing to a stream. This was causing +some clutter, and makes it harder to develop X10D, so it was removed. In its stead, any method which accepted an +`Endianness` parameter now has two overloads: one for big-endian, and one for little-endian. For example, the following +code: + +```csharp +someStream.Write(12345, Endianness.BigEndian); + +// or + +Span buffer = stackalloc byte[4]; +12345.TryWriteBytes(buffer, Endianness.BigEndian); +``` + +would now be written as: + +```csharp +someStream.WriteBigEndian(12345); + +// or + +Span buffer = stackalloc byte[4]; +12345.TryWriteLittleEndianBytes(buffer); +``` + +### `IEnumerable.ConcatOne(T)` extension method + +The `IEnumerable.ConcatOne` extension method was used to concatenate a single item to an enumerable. At the time, I +was unaware of the `Enumerable.Append` method, which does the same thing. As such, `ConcatOne` has been removed. There +is no migration path for this, as the built in `Append` method from LINQ is a drop-in replacement. + +## Exception Changes + +If you were previously catching TypeInitializationException when calling `Stream.GetHash<>` or `Stream.TryWriteHash<>`, +you will now need to catch a ArgumentException instead. The justification for this change is that ArgumentException is +more general, and more easily understood by developers. \ No newline at end of file diff --git a/docfx_project/articles/toc.yml b/docfx_project/articles/toc.yml index ff89ef1..fb0eb80 100644 --- a/docfx_project/articles/toc.yml +++ b/docfx_project/articles/toc.yml @@ -1,2 +1,4 @@ - name: Introduction href: intro.md +- name: Migration from 3.x.x + href: migration-from-3.x.x.md \ No newline at end of file