From 9f1dd06bfc376225b898c62115a920fa62574149 Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Wed, 4 Oct 2023 19:24:17 +0200 Subject: [PATCH 1/7] Remove conceptual docummentation item Removed since is not applicable --- src/libraries/System.Formats.Cbor/src/PACKAGE.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index 96474955ed1b16..c3dd836ba6d329 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -30,8 +30,7 @@ The main types provided by this library are: -* [Conceptual documentation](https://learn.microsoft.com/en-us/dotnet/standard/serialization/**LIBRARYNAME**/overview) -* [API documentation](https://learn.microsoft.com/en-us/dotnet/api/**LIBRARYNAME**) +* [API documentation](https://learn.microsoft.com/en-us/dotnet/api/system.formats.cbor) ## Related Packages From 3493538bf4b555e8ec5ffc37c6d700ae6f39f06d Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Wed, 4 Oct 2023 19:27:25 +0200 Subject: [PATCH 2/7] List types library provides Add list of types which library provides. Listed public types, means exposed types. --- src/libraries/System.Formats.Cbor/src/PACKAGE.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index c3dd836ba6d329..54873ff1eb53a9 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -22,9 +22,12 @@ The main types provided by this library are: -* `` -* `` -* `` +* `System.Formats.Cbor.CborReader` +* `System.Formats.Cbor.CborWriter` +* `System.Formats.Cbor.CborReaderState` +* `System.Formats.Cbor.CborConformanceMode` +* `System.Formats.Cbor.CborContentException` +* `System.Formats.Cbor.CborTag` ## Addtional Documentation From 6240569a651abaf951b0d0f863e9f3d612a0c128 Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Wed, 4 Oct 2023 20:14:06 +0200 Subject: [PATCH 3/7] Add description and usage examples Add library description. Add few code examples showing basic functionality for CBOR wirter and reader types. --- .../System.Formats.Cbor/src/PACKAGE.md | 60 ++++++++++++++++++- 1 file changed, 57 insertions(+), 3 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index 54873ff1eb53a9..80aa235d1f7983 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -2,20 +2,74 @@ +Provides support for reading and writing values in Concise Binary Object Representation (CBOR), as originally defined in [IETF RFC 7049](https://www.ietf.org/rfc/rfc7049.html). ## Key Features -* -* -* +* Reader and writers types for the CBOR format. +* Built-in support for different CBOR conformance modes. ## How to Use +Write and read primitives: + +```csharp +using System.Formats.Cbor; + +var cborWriter = new CborWriter(CborConformanceMode.Lax); +cborWriter.WriteTextString("Hello World"); + +var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax); +Console.WriteLine(cborReader.ReadTextString()); +// Hello World +``` + +Write and read an array: + +```csharp +var cborWriter = new CborWriter(CborConformanceMode.Lax); +cborWriter.WriteStartArray(3); +cborWriter.WriteInt32(1); +cborWriter.WriteInt32(2); +cborWriter.WriteInt32(3); +cborWriter.WriteEndArray(); + +var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax); +Console.WriteLine(cborReader.ReadStartArray()); +// 3 +Console.WriteLine(cborReader.ReadInt32()); +// 1 +Console.WriteLine(cborReader.ReadInt32()); +// 2 +Console.WriteLine(cborReader.ReadInt32()); +// 3 +cborReader.ReadEndArray(); +``` + +Inspect writer and reader state: + +```csharp +var cborWriter = new CborWriter(CborConformanceMode.Lax); +cborWriter.WriteTextString("SomeArray"); +Console.WriteLine(cborWriter.BytesWritten); +// 10 +Console.WriteLine(cborWriter.IsWriteCompleted); +// True + +var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax); +Console.WriteLine(cborReader.BytesRemaining); +// 10 +Console.WriteLine(cborReader.ReadTextString()); +// SomeArray +Console.WriteLine(cborReader.BytesRemaining); +// 0 +``` + ## Main Types From e3386098c518b1666d05a4b9bc477257d96dc0e6 Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Wed, 4 Oct 2023 20:26:49 +0200 Subject: [PATCH 4/7] Add related packages section Since different targets have different dependencies so I have divided for each section. --- .../System.Formats.Cbor/src/PACKAGE.md | 28 +++++++++++++++++-- 1 file changed, 26 insertions(+), 2 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index 80aa235d1f7983..8ed42731f5d550 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -9,7 +9,7 @@ Provides support for reading and writing values in Concise Binary Object Represe -* Reader and writers types for the CBOR format. +* Reader and writer types for the CBOR format. * Built-in support for different CBOR conformance modes. ## How to Use @@ -83,7 +83,7 @@ The main types provided by this library are: * `System.Formats.Cbor.CborContentException` * `System.Formats.Cbor.CborTag` -## Addtional Documentation +## Additional Documentation @@ -93,6 +93,30 @@ The main types provided by this library are: +.NETFramework 4.6.2: + +* Provides HashCode types: [Microsoft.Bcl.HashCode](https://www.nuget.org/packages/Microsoft.Bcl.HashCode/) +* Resource pooling: [System.Buffers](https://www.nuget.org/packages/System.Buffers/) +* Efficient memory representation: [System.Memory](https://www.nuget.org/packages/System.Memory/) +* Provides functionality over pointers: [System.Runtime.CompilerServices.Unsafe](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/) +* Provides underlying type for tuples: [System.ValueTuple](https://www.nuget.org/packages/System.ValueTuple/) + + +.NETStandard 2.0: + +* Provides HashCode types: [Microsoft.Bcl.HashCode](https://www.nuget.org/packages/Microsoft.Bcl.HashCode/) +* Resource pooling: [System.Buffers](https://www.nuget.org/packages/System.Buffers/) +* Efficient memory representation: [System.Memory](https://www.nuget.org/packages/System.Memory/) +* Provides functionality over pointers: [System.Runtime.CompilerServices.Unsafe](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/) + +.net6.0: + +No dependencies. + +.net7.0: + +No dependencies. + ## Feedback & Contributing From c18809ddab9f9befd1deab57bbeda55856f89fda Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Wed, 4 Oct 2023 20:30:56 +0200 Subject: [PATCH 5/7] Improve short description Add 'format' word after abbreviation to have an object in sentence. --- src/libraries/System.Formats.Cbor/src/PACKAGE.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index 8ed42731f5d550..512f4b9a3c13eb 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -2,7 +2,7 @@ -Provides support for reading and writing values in Concise Binary Object Representation (CBOR), as originally defined in [IETF RFC 7049](https://www.ietf.org/rfc/rfc7049.html). +Provides support for reading and writing values in Concise Binary Object Representation (CBOR) format, as originally defined in [IETF RFC 7049](https://www.ietf.org/rfc/rfc7049.html). ## Key Features From 91705dd0b4804baad07773e9f479a5575accacc4 Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Wed, 4 Oct 2023 21:02:54 +0200 Subject: [PATCH 6/7] Remove related packages section Since there are no related packages. --- .../System.Formats.Cbor/src/PACKAGE.md | 28 ------------------- 1 file changed, 28 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index 512f4b9a3c13eb..fced223682b962 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -89,34 +89,6 @@ The main types provided by this library are: * [API documentation](https://learn.microsoft.com/en-us/dotnet/api/system.formats.cbor) -## Related Packages - - - -.NETFramework 4.6.2: - -* Provides HashCode types: [Microsoft.Bcl.HashCode](https://www.nuget.org/packages/Microsoft.Bcl.HashCode/) -* Resource pooling: [System.Buffers](https://www.nuget.org/packages/System.Buffers/) -* Efficient memory representation: [System.Memory](https://www.nuget.org/packages/System.Memory/) -* Provides functionality over pointers: [System.Runtime.CompilerServices.Unsafe](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/) -* Provides underlying type for tuples: [System.ValueTuple](https://www.nuget.org/packages/System.ValueTuple/) - - -.NETStandard 2.0: - -* Provides HashCode types: [Microsoft.Bcl.HashCode](https://www.nuget.org/packages/Microsoft.Bcl.HashCode/) -* Resource pooling: [System.Buffers](https://www.nuget.org/packages/System.Buffers/) -* Efficient memory representation: [System.Memory](https://www.nuget.org/packages/System.Memory/) -* Provides functionality over pointers: [System.Runtime.CompilerServices.Unsafe](https://www.nuget.org/packages/System.Runtime.CompilerServices.Unsafe/) - -.net6.0: - -No dependencies. - -.net7.0: - -No dependencies. - ## Feedback & Contributing From ca784892934927538af8784dc60296a15dddc55c Mon Sep 17 00:00:00 2001 From: Illia Larka Date: Thu, 5 Oct 2023 13:43:11 +0200 Subject: [PATCH 7/7] Improve array reading/writing example --- .../System.Formats.Cbor/src/PACKAGE.md | 23 +++++++++---------- 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/PACKAGE.md b/src/libraries/System.Formats.Cbor/src/PACKAGE.md index fced223682b962..ff26f0debbdc0a 100644 --- a/src/libraries/System.Formats.Cbor/src/PACKAGE.md +++ b/src/libraries/System.Formats.Cbor/src/PACKAGE.md @@ -33,21 +33,20 @@ Write and read an array: ```csharp var cborWriter = new CborWriter(CborConformanceMode.Lax); -cborWriter.WriteStartArray(3); -cborWriter.WriteInt32(1); -cborWriter.WriteInt32(2); -cborWriter.WriteInt32(3); +cborWriter.WriteStartArray(5); +for (var index = 0; index < 5; index++) +{ + cborWriter.WriteInt32(index); +} cborWriter.WriteEndArray(); var cborReader = new CborReader(cborWriter.Encode(), CborConformanceMode.Lax); -Console.WriteLine(cborReader.ReadStartArray()); -// 3 -Console.WriteLine(cborReader.ReadInt32()); -// 1 -Console.WriteLine(cborReader.ReadInt32()); -// 2 -Console.WriteLine(cborReader.ReadInt32()); -// 3 +var arrayLength = cborReader.ReadStartArray(); +for (var index = 0; index < arrayLength; index++) +{ + Console.Write(cborReader.ReadInt32()); +} +// 01234 cborReader.ReadEndArray(); ```