Merge branch 'main' of https://github.com/Hyperlnq/HyperSerializer

README.md

@@ -1,16 +1,40 @@
-# HyperSerializer
+# Overview
 ![]()
-[![NuGet version (HyperSerializer)](https://img.shields.io/badge/nuget-v1.0.7-blue?style=flat-square)](https://www.nuget.org/packages/HyperSerializer/)
+[![NuGet version (HyperSerializer)](https://img.shields.io/badge/nuget-v1.0.8-blue?style=flat-square)](https://www.nuget.org/packages/HyperSerializer/)
 
-If you're looking for the fastest Microsoft.Net binary serializer, look no further.  HyperSerializer is up to ***18x faster than MessagePack and Protobuf*** with roughly equivelant memory allocation (see Benchmarks below).  HyperSerializer was built as a champion/challenger (C++ vs C#) experiment to support the nanosecond latency requirements of high frequency trading.  HyperSerializer uses the managed Span\<T\> and Memory\<T\> structs to acheive extreme speed and low memory allocation without unsafe code.  HyperSerializer is 100% thread-safe and comes with both sync and async serialization and deserialization methods.  Out of the box support for .NETCoreApp 3.1, net5.0, net6.0.
+If you're looking for the fastest Microsoft.Net binary serializer, look no further.  HyperSerializer is up to ***18x faster than MessagePack and Protobuf*** with roughly equivelant memory.
+
+![Execution Duration](https://github.com/Hyperlnq/HyperSerializer/blob/main/BenchmarkAssets/Time.png)
+
+***See Benchmarks section below for additional information.***
+
+## Quick Start
+
+HyperSerializer is extremely easy to implement.  Simply install the Nuget package (Install-Package HyperSerializer) and serialize/deserialize with just 2 lines of code.
+
+```csharp
+//Sync Example
+Test obj = new();
+Span<byte> bytes = HyperSerializer<Test>.Serialize(obj);
+Test objDeserialized = HyperSerializer<Test>.Deserialize(bytes);
+```
+ """See the Usage section below for additional information."""
+
+# Implementation and Framework Support
+HyperSerializer was built as a champion/challenger (C++ vs C#) experiment to support the nanosecond latency requirements of high frequency trading.  HyperSerializer uses the managed Span\<T\> and Memory\<T\> structs to acheive extreme speed and low memory allocation without unsafe code.  HyperSerializer is 100% thread-safe and comes with both sync and async serialization and deserialization methods.  Out of the box support for .NETCoreApp 3.1, net5.0, net6.0.
 
 HyperSerializer is intended for use cases such as caching and interservice communication behind firewalls or between known parites.  It is implemented using a customer binary format (aka wire format) and uses bounding techniques to protect against buffer overflows.  As a result, attempting to deserialize a message that exceeds the size of an expected data type will result in an exception in most cases as described later in this section.  For example, the following code which can be found in SerializerTests.cs in the test project attempts to deserialize an 8 BYTE buffer as a 4 BYTE int, which results in an ArgumentOutOfRangeException:
 
 ```csharp
+//Simulate foreign serialization
 long i = 1L << 32;
 Span<byte> buffer = default;
 MemoryMarshal.Write(buffer, ref i);
+
+//Simulate attempting to deserialize Int64 (8 bytes) to Int32 (4 bytes)
 var deserialize = HyperSerializer<int>.Deserialize(buffer);
+
+//Result: ArguementOutOfRangeException
 ```
 In the event the destiation data type was (1) 8 BYTES in length or (2) an object containing properties with an aggregate size exceeding 8 BYTES, one of the following would occur: (1) a data type specific execption, in most cases - ArguementOutOfRangeException, OR (2) no exception at all if the bytes happen to represent valid values for the destination type(s).
 
@@ -47,6 +71,7 @@ public class Test {
     public TimeSpan F { get; set; }
     public Guid G { get; set; }
     public TestEnum H { get; set; }
+    public string I { get; set; }
 }
 ```
 ***Speed - Serializing and Deserializing 1M "Test" Objects***
@@ -74,7 +99,7 @@ Intel Core i9-10980XE CPU 3.00GHz, 1 CPU, 36 logical and 18 physical cores
 |    ProtobufSerializer|  917.73 ms|  10.020 ms|  9.372 ms|  18.37|     0.17|  35000.0000|     435 MB
 ```
 ## HyperSerializerUnsafe\<T\>
-The HyperSerializer project contains an unsafe implementation of the HyperSerializer\<T\>, named HyperSerializerUnsafe\<T\>.  It is an experimental version intended for benchmarking purposes and does not meaningfuly outperform HyperSerializer\<T\> in most scenarios, if at all (see table .  As such, it is not recommended for end user consumption.
+The HyperSerializer project contains an unsafe implementation of the HyperSerializer\<T\>, named HyperSerializerUnsafe\<T\>.  It is an experimental version intended for benchmarking purposes and does not meaningfuly outperform HyperSerializer\<T\> in most scenarios, if at all (see table above).  As such, it is not recommended for end user consumption.
 
 ## Limitations 
 ### Unsupported types