From 0697e9e08e2c52a23a7f42f537b1fdd9d07ac14f Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Thu, 11 Mar 2021 21:07:39 +0000 Subject: [PATCH 1/4] initial backport of CBOR documentation --- .../Formats/Cbor/CborConformanceLevel.cs | 76 +++--- .../Formats/Cbor/CborContentException.cs | 4 +- .../src/System/Formats/Cbor/CborTag.cs | 89 ++----- .../Formats/Cbor/Reader/CborReader.Array.cs | 41 ++-- .../Formats/Cbor/Reader/CborReader.Integer.cs | 124 ++++------ .../Formats/Cbor/Reader/CborReader.Map.cs | 58 ++--- .../Cbor/Reader/CborReader.PeekState.cs | 10 +- .../Formats/Cbor/Reader/CborReader.Simple.cs | 139 +++++------ .../Cbor/Reader/CborReader.SkipValue.cs | 49 ++-- .../Formats/Cbor/Reader/CborReader.String.cs | 231 +++++++----------- .../Formats/Cbor/Reader/CborReader.Tag.cs | 146 +++++------ .../System/Formats/Cbor/Reader/CborReader.cs | 63 ++--- .../Formats/Cbor/Reader/CborReaderState.cs | 92 ++----- .../Formats/Cbor/Writer/CborWriter.Array.cs | 41 ++-- .../Formats/Cbor/Writer/CborWriter.Integer.cs | 80 +++--- .../Formats/Cbor/Writer/CborWriter.Map.cs | 59 ++--- .../Formats/Cbor/Writer/CborWriter.Simple.cs | 92 +++---- .../Formats/Cbor/Writer/CborWriter.String.cs | 131 ++++------ .../Formats/Cbor/Writer/CborWriter.Tag.cs | 96 +++----- .../System/Formats/Cbor/Writer/CborWriter.cs | 120 +++------ 20 files changed, 647 insertions(+), 1094 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs index 1ac844403c65d1..7f47b414321b77 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs @@ -7,49 +7,55 @@ namespace System.Formats.Cbor { - /// - /// Defines supported conformance modes for encoding and decoding CBOR data. - /// + /// Defines supported conformance modes for encoding and decoding CBOR data. public enum CborConformanceMode { - /// - /// Ensures that the CBOR data is well-formed, as specified in RFC7049. - /// + /// Ensures that the CBOR data is well-formed, as specified in RFC7049. Lax, - /// - /// Ensures that the CBOR data adheres to strict mode, as specified in RFC7049 section 3.10. - /// Extends lax conformance with the following requirements: - /// - /// Maps (major type 5) must not contain duplicate keys. - /// Simple values (major type 7) must be encoded as small a possible and exclude the reserved values 24-31. - /// UTF-8 string encodings must be valid. - /// - /// + /// Ensures that the CBOR data adheres to strict mode, as specified in RFC7049 section 3.10.Extends lax conformance with the following requirements: + /// + /// Maps (major type 5) must not contain duplicate keys. + /// + /// + /// Simple values (major type 7) must be encoded as small a possible and exclude the reserved values 24-31. + /// + /// + /// UTF-8 string encodings must be valid. + /// + /// Strict, - /// - /// Ensures that the CBOR data is canonical, as specified in RFC7049 section 3.9. - /// Extends strict conformance with the following requirements: - /// - /// Integers must be encoded as small as possible. - /// Maps (major type 5) must contain keys sorted by encoding. - /// Indefinite-length items must be made into definite-length items. - /// - /// + /// Ensures that the CBOR data is canonical, as specified in RFC7049 section 3.9.Extends strict conformance with the following requirements: + /// + /// Integers must be encoded as small as possible. + /// + /// + /// Maps (major type 5) must contain keys sorted by encoding. + /// + /// + /// Indefinite-length items must be made into definite-length items. + /// + /// Canonical, - /// - /// Ensures that the CBOR data is canonical, as specified by the CTAP v2.0 standard, section 6. - /// Extends strict conformance with the following requirements: - /// - /// Maps (major type 5) must contain keys sorted by encoding. - /// Indefinite-length items must be made into definite-length items. - /// Integers must be encoded as small as possible. - /// The representations of any floating-point values are not changed. - /// CBOR tags (major type 6) are not permitted. - /// - /// + /// Ensures that the CBOR data is canonical, as specified by the CTAP v2.0 standard, section 6.Extends strict conformance with the following requirements: + /// + /// Maps (major type 5) must contain keys sorted by encoding. + /// + /// + /// Indefinite-length items must be made into definite-length items. + /// + /// + /// Integers must be encoded as small as possible. + /// + /// + /// The representations of any floating-point values are not changed. + /// + /// + /// CBOR tags (major type 6) are not permitted. + /// + /// Ctap2Canonical, } diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs index 5bcfa984f6f050..f9f226618ded57 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs @@ -5,9 +5,7 @@ namespace System.Formats.Cbor { - /// - /// The exception that is thrown when a CBOR encoding is invalid. - /// + /// The exception that's thrown when CBOR data is invalid. [Serializable] public class CborContentException : Exception { diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborTag.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborTag.cs index 402f45d085b3db..599666a3100baa 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborTag.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborTag.cs @@ -3,117 +3,72 @@ namespace System.Formats.Cbor { - /// - /// Represents a CBOR semantic tag (major type 6). - /// + /// Represents a CBOR semantic tag (major type 6). [CLSCompliant(false)] public enum CborTag : ulong { - /// - /// Tag value for RFC3339 date/time strings. - /// + /// Tag value for RFC3339 date/time strings. DateTimeString = 0, - /// - /// Tag value for Epoch-based date/time strings. - /// + /// Tag value for Epoch-based date/time strings. UnixTimeSeconds = 1, - /// - /// Tag value for unsigned bignum encodings. - /// + /// Tag value for unsigned bignum encodings. UnsignedBigNum = 2, - /// - /// Tag value for negative bignum encodings. - /// + /// Tag value for negative bignum encodings. NegativeBigNum = 3, - /// - /// Tag value for decimal fraction encodings. - /// + /// Tag value for decimal fraction encodings. DecimalFraction = 4, - /// - /// Tag value for big float encodings. - /// + /// Tag value for big float encodings. BigFloat = 5, - /// - /// Tag value for byte strings, meant for later encoding to a base64url string representation. - /// + /// Tag value for byte strings, meant for later encoding to a base64url string representation. Base64UrlLaterEncoding = 21, - /// - /// Tag value for byte strings, meant for later encoding to a base64 string representation. - /// + /// Tag value for byte strings, meant for later encoding to a base64 string representation. Base64StringLaterEncoding = 22, - /// - /// Tag value for byte strings, meant for later encoding to a base16 string representation. - /// + /// Tag value for byte strings, meant for later encoding to a base16 string representation. Base16StringLaterEncoding = 23, - /// - /// Tag value for byte strings containing embedded CBOR data item encodings. - /// + /// Tag value for byte strings containing embedded CBOR data item encodings. EncodedCborDataItem = 24, - /// - /// Tag value for Uri strings, as defined in RFC3986. - /// + /// Tag value for Uri strings, as defined in RFC3986. Uri = 32, - /// - /// Tag value for base64url-encoded text strings, as defined in RFC4648. - /// + /// Tag value for base64url-encoded text strings, as defined in RFC4648. Base64Url = 33, - /// - /// Tag value for base64-encoded text strings, as defined in RFC4648. - /// + /// Tag value for base64-encoded text strings, as defined in RFC4648. Base64 = 34, - /// - /// Tag value for regular expressions in Perl Compatible Regular Expressions / Javascript syntax. - /// + /// Tag value for regular expressions in Perl Compatible Regular Expressions / Javascript syntax. Regex = 35, - /// - /// Tag value for MIME messages (including all headers), as defined in RFC2045. - /// + /// Tag value for MIME messages (including all headers), as defined in RFC2045. MimeMessage = 36, - /// - /// Tag value for the Self-Describe CBOR header (0xd9d9f7). - /// + /// Tag value for the Self-Describe CBOR header (0xd9d9f7). SelfDescribeCbor = 55799, } - /// - /// Represents a CBOR simple value (major type 7). - /// + /// Represents a CBOR simple value (major type 7). public enum CborSimpleValue : byte { - /// - /// Represents the value 'false'. - /// + /// Represents the value 'false'. False = 20, - /// - /// Represents the value 'true'. - /// + /// Represents the value 'true'. True = 21, - /// - /// Represents the value 'null'. - /// + /// Represents the value 'null'. Null = 22, - /// - /// Represents an undefined value, to be used by an encoder - /// as a substitute for a data item with an encoding problem. - /// + /// Represents an undefined value, to be used by an encoder as a substitute for a data item with an encoding problem. Undefined = 23, } } diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs index dc239e93e67443..51426cb9736d0c 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs @@ -3,22 +3,17 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { - /// - /// Reads the next data item as the start of an array (major type 4). - /// - /// - /// The length of the definite-length array, or if the array is indefinite-length. - /// - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as the start of an array (major type 4). + /// The length of the definite-length array, or if the array is indefinite-length. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public int? ReadStartArray() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Array); @@ -45,17 +40,13 @@ public partial class CborReader } } - /// - /// Reads the end of an array (major type 4). - /// - /// - /// the current context is not an array. -or- - /// the reader is not at the end of the array. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data - /// + /// Reads the end of an array (major type 4). + /// The current context is not an array. + /// -or- + /// The reader is not at the end of the array. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. public void ReadEndArray() { if (_definiteLength is null) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs index d0569e61768972..51b683768140ce 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs @@ -5,25 +5,19 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { - // Implements major type 0,1 decoding per https://tools.ietf.org/html/rfc7049#section-2.1 - - /// - /// Reads the next data item as a signed integer (major types 0,1) - /// + /// Reads the next data item as a signed integer (major types 0,1) /// The decoded integer value. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the encoded integer is out of range for . - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + // Implements major type 0,1 decoding per https://tools.ietf.org/html/rfc7049#section-2.1 public int ReadInt32() { int value = checked((int)PeekSignedInteger(out int bytesRead)); @@ -32,21 +26,15 @@ public int ReadInt32() return value; } - /// - /// Reads the next data item as an unsigned integer (major type 0). - /// + /// Reads the next data item as an unsigned integer (major type 0). /// The decoded integer value. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the encoded integer is out of range for . - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. [CLSCompliant(false)] public uint ReadUInt32() { @@ -56,21 +44,15 @@ public uint ReadUInt32() return value; } - /// - /// Reads the next data item as a signed integer (major types 0,1) - /// + /// Reads the next data item as a signed integer (major types 0,1) /// The decoded integer value. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the encoded integer is out of range for . - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public long ReadInt64() { long value = PeekSignedInteger(out int bytesRead); @@ -79,21 +61,15 @@ public long ReadInt64() return value; } - /// - /// Reads the next data item as an unsigned integer (major type 0). - /// + /// Reads the next data item as an unsigned integer (major type 0). /// The decoded integer value. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the encoded integer is out of range for . - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. [CLSCompliant(false)] public ulong ReadUInt64() { @@ -103,27 +79,17 @@ public ulong ReadUInt64() return value; } - /// - /// Reads the next data item as a CBOR negative integer representation (major type 1). - /// - /// - /// An unsigned integer denoting -1 minus the integer. - /// - /// - /// the next data item does not have the correct major type. - /// - /// - /// the encoded integer is out of range for - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// This method supports decoding integers between -18446744073709551616 and -1. - /// Useful for handling values that do not fit in the type. - /// + /// Reads the next data item as a CBOR negative integer representation (major type 1). + /// An unsigned integer denoting -1 minus the integer. + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// This method supports decoding integers between -18446744073709551616 and -1. + /// Useful for handling values that do not fit in the type. [CLSCompliant(false)] public ulong ReadCborNegativeIntegerRepresentation() { diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs index bcea2bd5c2dcb2..4176434c907201 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs @@ -6,34 +6,24 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { private KeyEncodingComparer? _keyEncodingComparer; private Stack>? _pooledKeyEncodingRangeAllocations; - /// - /// Reads the next data item as the start of a map (major type 5). - /// - /// - /// The number of key-value pairs in a definite-length map, or if the map is indefinite-length. - /// - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// Map contents are consumed as if they were arrays twice the length of the map's declared size. - /// For instance, a map of size 1 containing a key of type int with a value of type string - /// must be consumed by successive calls to and . - /// It is up to the caller to keep track of whether the next value is a key or a value. - /// - /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of arbitrary type, - /// for instance a map can contain keys that are maps themselves. - /// + /// Reads the next data item as the start of a map (major type 5). + /// The number of key-value pairs in a definite-length map, or if the map is indefinite-length. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// Map contents are consumed as if they were arrays twice the length of the map's declared size. + /// For instance, a map of size `1` containing a key of type `int` with a value of type `string` must be consumed by successive calls to and . + /// It is up to the caller to keep track of whether the next value is a key or a value. + /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of arbitrary type, for instance a map can contain keys that are maps themselves. public int? ReadStartMap() { int? length; @@ -70,19 +60,15 @@ public partial class CborReader return length; } - - /// - /// Reads the end of a map (major type 5). - /// - /// - /// the current context is not a map. -or- - /// the reader is not at the end of the map - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the end of a map (major type 5). + /// The current context is not a map. + /// -or- + /// The reader is not at the end of the map. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public void ReadEndMap() { if (_definiteLength is null) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs index ab8ff64207261d..59ff581dc3e77c 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs @@ -5,14 +5,12 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { - /// - /// Read the next CBOR token, without advancing the reader. - /// - /// - /// The underlying data is not a well-formed CBOR encoding. - /// + /// Reads the next CBOR token, without advancing the reader. + /// An object that represents the current CBOR reader state. + /// The underlying data is not a well-formed CBOR encoding. public CborReaderState PeekState() { if (_cachedState == CborReaderState.Undefined) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs index 567c527444cb2b..ccdb1d50de190b 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs @@ -5,22 +5,21 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { - /// - /// Reads the next data item as a half-precision floating point number (major type 7). - /// + /// Reads the next data item as a half-precision floating point number (major type 7). /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next simple value is not a floating-point number encoding. -or- - /// the encoded value is a double-precision float - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// -or- + /// The next simple value is not a floating-point number encoding. + /// -or- + /// The encoded value is a double-precision float. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public Half ReadHalf() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Simple); @@ -45,20 +44,18 @@ public Half ReadHalf() } } - /// - /// Reads the next data item as a single-precision floating point number (major type 7). - /// + /// Reads the next data item as a single-precision floating point number (major type 7). /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next simple value is not a floating-point number encoding. -or- - /// the encoded value is a double-precision float - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// -or- + /// The next simple value is not a floating-point number encoding. + /// -or- + /// The encoded value is a double-precision float + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public float ReadSingle() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Simple); @@ -90,19 +87,16 @@ public float ReadSingle() } } - /// - /// Reads the next data item as a double-precision floating point number (major type 7). - /// - /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next simple value is not a floating-point number encoding - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as a double-precision floating point number (major type 7). + /// The decoded value. + /// The next data item does not have the correct major type. + /// -or- + /// The next simple value is not a floating-point number encoding + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public double ReadDouble() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Simple); @@ -137,19 +131,16 @@ public double ReadDouble() } } - /// - /// Reads the next data item as a boolean value (major type 7). - /// - /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next simple value is not a boolean encoding - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as a boolean value (major type 7). + /// The decoded value. + /// The next data item does not have the correct major type. + /// -or- + /// The next simple value is not a boolean encoding + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public bool ReadBoolean() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Simple); @@ -166,18 +157,15 @@ public bool ReadBoolean() return result; } - /// - /// Reads the next data item as a null value (major type 7). - /// - /// - /// the next data item does not have the correct major type. -or- - /// the next simple value is not a null value encoding - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as a value (major type 7). + /// The next data item does not have the correct major type. + /// -or- + /// The next simple value is not a value encoding. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public void ReadNull() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Simple); @@ -193,19 +181,16 @@ public void ReadNull() } } - /// - /// Reads the next data item as a CBOR simple value (major type 7). - /// - /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next simple value is not a simple value encoding - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as a CBOR simple value (major type 7). + /// The decoded CBOR simple value. + /// The next data item does not have the correct major type. + /// -or- + /// The next simple value is not a simple value encoding. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public CborSimpleValue ReadSimpleValue() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.Simple); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs index 05db6b79a78e88..42ea1632df65a7 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs @@ -5,45 +5,30 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { - /// - /// Reads the contents of the next value, discarding the result and advancing the reader. - /// - /// - /// Disable conformance mode validation for the skipped value, - /// equivalent to using . - /// - /// - /// the reader is not at the start of new value. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the contents of the next value, discarding the result and advancing the reader. + /// to disable conformance mode validation for the skipped values, equivalent to using ; otherwise, . + /// The reader is not at the start of new value. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public void SkipValue(bool disableConformanceModeChecks = false) { SkipToAncestor(0, disableConformanceModeChecks); } - /// - /// Reads the remaining contents of the current value context, - /// discarding results and advancing the reader to the next value - /// in the parent context. - /// - /// - /// Disable conformance mode validation for the skipped values, - /// equivalent to using . - /// - /// - /// the reader is at the root context - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the remaining contents of the current value context, discarding results and advancing the reader to the next value in the parent context. + /// to disable conformance mode validation for the skipped values, equivalent to using ; otherwise, . + /// The reader is at the root context + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public void SkipToParent(bool disableConformanceModeChecks = false) { if (_currentMajorType is null) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs index e2ecb7f5c8a626..d5ccde2125d693 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs @@ -8,6 +8,7 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { // Implements major type 2,3 decoding per https://tools.ietf.org/html/rfc7049#section-2.1 @@ -15,21 +16,15 @@ public partial class CborReader // stores a reusable List allocation for storing indefinite length string chunk offsets private List<(int Offset, int Length)>? _indefiniteLengthStringRangeAllocation; - /// - /// Reads the next data item as a byte string (major type 2). - /// + /// Reads the next data item as a byte string (major type 2). /// The decoded byte array. - /// - /// the next date item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// The method accepts indefinite length strings, which it will concatenate to a single string. - /// + /// The next date item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// The method accepts indefinite length strings, which it concatenates to a single string. public byte[] ReadByteString() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.ByteString); @@ -54,28 +49,17 @@ public byte[] ReadByteString() return result; } - /// - /// Reads the next data item as a byte string (major type 2). - /// - /// The buffer in which to write. - /// - /// On success, receives the number of bytes written to . - /// - /// - /// and advances the reader if had sufficient - /// length to receive the value, otherwise and the reader does not advance. - /// - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// The method accepts indefinite length strings, which it will concatenate to a single string. - /// + /// Reads the next data item as a byte string (major type 2). + /// The buffer in which to write the read bytes. + /// On success, receives the number of bytes written to . + /// if had sufficient length to receive the value and the reader advances; otherwise, . + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// The method accepts indefinite length strings, which it will concatenate to a single string. public bool TryReadByteString(Span destination, out int bytesWritten) { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.ByteString); @@ -108,21 +92,16 @@ public bool TryReadByteString(Span destination, out int bytesWritten) return true; } - /// - /// Reads the next data item as a definite-length byte string (major type 2). - /// - /// - /// A view of the byte string payload. - /// - /// - /// the next data item does not have the correct major type. -or- - /// the data item is an indefinite-length byte string. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as a definite-length byte string (major type 2). + /// A view of the byte string payload. + /// The next data item does not have the correct major type. + /// -or- + /// The data item is an indefinite-length byte string. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public ReadOnlyMemory ReadDefiniteLengthByteString() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.ByteString); @@ -142,18 +121,15 @@ public ReadOnlyMemory ReadDefiniteLengthByteString() return byteSlice; } - /// - /// Reads the next data item as the start of an indefinite-length byte string (major type 2). - /// - /// - /// the next data item does not have the correct major type. -or- - /// the next data item is a definite-length encoded string. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as the start of an indefinite-length byte string (major type 2). + /// The next data item does not have the correct major type. + /// -or- + /// The next data item is a definite-length encoded string. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public void ReadStartIndefiniteLengthByteString() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.ByteString); @@ -172,16 +148,11 @@ public void ReadStartIndefiniteLengthByteString() PushDataItem(CborMajorType.ByteString, definiteLength: null); } - /// - /// End reading an indefinite-length byte string (major type 2). - /// - /// - /// the current context is not an indefinite-length string. -or- - /// the reader is not at the end of the string - /// - /// - /// there was an unexpected end of CBOR encoding data - /// + /// Ends reading an indefinite-length byte string (major type 2). + /// The current context is not an indefinite-length string. + /// -or- + /// The reader is not at the end of the string. + /// There was an unexpected end of CBOR encoding data. public void ReadEndIndefiniteLengthByteString() { ValidateNextByteIsBreakByte(); @@ -190,21 +161,15 @@ public void ReadEndIndefiniteLengthByteString() AdvanceBuffer(1); } - /// - /// Reads the next data item as a UTF-8 text string (major type 3). - /// + /// Reads the next data item as a UTF-8 text string (major type 3). /// The decoded string. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// The method accepts indefinite length strings, which it will concatenate to a single string. - /// + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// The method accepts indefinite length strings, which it will concatenate to a single string. public string ReadTextString() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.TextString); @@ -240,28 +205,17 @@ public string ReadTextString() return result; } - /// - /// Reads the next data item as a UTF-8 text string (major type 3). - /// + /// Reads the next data item as a UTF-8 text string (major type 3). /// The buffer in which to write. - /// - /// On success, receives the number of chars written to . - /// - /// - /// and advances the reader if had sufficient - /// length to receive the value, otherwise and the reader does not advance. - /// - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// The method accepts indefinite length strings, which it will concatenate to a single string. - /// + /// On success, receives the number of chars written to . + /// and advances the reader if had sufficient length to receive the value, otherwise and the reader does not advance. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// The method accepts indefinite length strings, which it will concatenate to a single string. public bool TryReadTextString(Span destination, out int charsWritten) { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.TextString); @@ -298,21 +252,16 @@ public bool TryReadTextString(Span destination, out int charsWritten) return true; } - /// - /// Reads the next data item as a definite-length UTF-8 text string (major type 3). - /// - /// - /// A view of the raw UTF-8 payload. - /// - /// - /// the next data item does not have the correct major type. -or- - /// the data item is an indefinite-length text string. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as a definite-length UTF-8 text string (major type 3). + /// A view of the raw UTF-8 payload. + /// The next data item does not have the correct major type. + /// -or- + /// The data item is an indefinite-length text string. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public ReadOnlyMemory ReadDefiniteLengthTextStringBytes() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.TextString); @@ -339,18 +288,15 @@ public ReadOnlyMemory ReadDefiniteLengthTextStringBytes() return encodedSlice; } - /// - /// Reads the next data item as the start of an indefinite-length UTF-8 text string (major type 3). - /// - /// - /// the next data item does not have the correct major type. -or- - /// the next data item is a definite-length encoded string. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// Reads the next data item as the start of an indefinite-length UTF-8 text string (major type 3). + /// The next data item does not have the correct major type. + /// -or- + /// The next data item is a definite-length encoded string. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public void ReadStartIndefiniteLengthTextString() { CborInitialByte header = PeekInitialByte(expectedType: CborMajorType.TextString); @@ -369,16 +315,11 @@ public void ReadStartIndefiniteLengthTextString() PushDataItem(CborMajorType.TextString, definiteLength: null); } - /// - /// End reading an indefinite-length UTF-8 text string (major type 3). - /// - /// - /// the current context is not an indefinite-length string. -or- - /// the reader is not at the end of the string - /// - /// - /// there was an unexpected end of CBOR encoding data - /// + /// Ends reading an indefinite-length UTF-8 text string (major type 3). + /// The current context is not an indefinite-length string. + /// -or- + /// The reader is not at the end of the string. + /// There was an unexpected end of CBOR encoding data. public void ReadEndIndefiniteLengthTextString() { ValidateNextByteIsBreakByte(); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs index a3135f6e965f6c..9462366269b0ef 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs @@ -6,20 +6,17 @@ namespace System.Formats.Cbor { + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { - /// - /// Reads the next data item as a semantic tag (major type 6). - /// + /// Reads the next data item as a semantic tag (major type 6). /// The decoded value. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. [CLSCompliant(false)] public CborTag ReadTag() { @@ -30,40 +27,30 @@ public CborTag ReadTag() return tag; } - /// - /// Reads the next data item as a semantic tag (major type 6), - /// without advancing the reader. - /// + /// Reads the next data item as a semantic tag (major type 6), without advancing the reader. /// The decoded value. - /// - /// the next data item does not have the correct major type. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// - /// - /// Useful in scenaria where the semantic value decoder needs to be determined at runtime. - /// + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. + /// Useful in scenarios where the semantic value decoder needs to be determined at run time. [CLSCompliant(false)] public CborTag PeekTag() => PeekTagCore(out int _); - /// - /// Reads the next data item as a tagged date/time string, - /// as described in RFC7049 section 2.4.1. - /// + /// Reads the next data item as a tagged date/time string, as described in RFC7049 section 2.4.1. /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next date item does not have the correct semantic tag. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// invalid semantic date/time encoding. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// -or- + /// The next date item does not have the correct semantic tag. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// Invalid semantic date/time encoding. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public DateTimeOffset ReadDateTimeOffset() { // implements https://tools.ietf.org/html/rfc7049#section-2.4.1 @@ -100,21 +87,18 @@ public DateTimeOffset ReadDateTimeOffset() } } - /// - /// Reads the next data item as a tagged unix time in seconds, - /// as described in RFC7049 section 2.4.1. - /// + /// Reads the next data item as a tagged unix time in seconds, as described in RFC7049 section 2.4.1. /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next date item does not have the correct semantic tag. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// invalid semantic date/time encoding. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// -or- + /// The next date item does not have the correct semantic tag. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// invalid semantic date/time encoding. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public DateTimeOffset ReadUnixTimeSeconds() { // implements https://tools.ietf.org/html/rfc7049#section-2.4.1 @@ -155,21 +139,18 @@ public DateTimeOffset ReadUnixTimeSeconds() } } - /// - /// Reads the next data item as a tagged bignum encoding, - /// as described in RFC7049 section 2.4.2. - /// + /// Reads the next data item as a tagged bignum encoding, as described in RFC7049 section 2.4.2. /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next date item does not have the correct semantic tag. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// invalid semantic bignum encoding. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// -or- + /// The next date item does not have the correct semantic tag. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// Invalid semantic bignum encoding. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public BigInteger ReadBigInteger() { // implements https://tools.ietf.org/html/rfc7049#section-2.4.2 @@ -205,24 +186,19 @@ public BigInteger ReadBigInteger() } } - /// - /// Reads the next data item as a tagged decimal fraction encoding, - /// as described in RFC7049 section 2.4.3. - /// + /// Reads the next data item as a tagged decimal fraction encoding, as described in RFC7049 section 2.4.3. /// The decoded value. - /// - /// the next data item does not have the correct major type. -or- - /// the next date item does not have the correct semantic tag. - /// - /// - /// Decoded decimal fraction is either too large or too small for a value. - /// - /// - /// the next value has an invalid CBOR encoding. -or- - /// there was an unexpected end of CBOR encoding data. -or- - /// invalid semantic decimal fraction encoding. -or- - /// the next value uses a CBOR encoding that is not valid under the current conformance mode. - /// + /// The next data item does not have the correct major type. + /// -or- + /// The next date item does not have the correct semantic tag. + /// Decoded decimal fraction is either too large or too small for a value. + /// The next value has an invalid CBOR encoding. + /// -or- + /// There was an unexpected end of CBOR encoding data. + /// -or- + /// Invalid semantic decimal fraction encoding. + /// -or- + /// The next value uses a CBOR encoding that is not valid under the current conformance mode. public decimal ReadDecimal() { // implements https://tools.ietf.org/html/rfc7049#section-2.4.3 diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs index 7454fc90343113..ce043f71958437 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs @@ -6,9 +6,7 @@ namespace System.Formats.Cbor { - /// - /// A stateful, forward-only reader for CBOR encoded data. - /// + /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { private readonly ReadOnlyMemory _data; @@ -33,42 +31,28 @@ public partial class CborReader // keeps a cached copy of the reader state; 'None' denotes uncomputed state private CborReaderState _cachedState = CborReaderState.Undefined; - /// - /// The conformance mode used by this reader. - /// + /// Gets the conformance mode used by this reader. + /// One of the enumeration values that represents the conformance mode used by this reader. public CborConformanceMode ConformanceMode { get; } - /// - /// Declares whether this reader allows multiple root-level CBOR data items. - /// + /// Gets a value that indicates whether this reader allows multiple root-level CBOR data items. + /// if this reader allows multiple root-level CBOR data items; otherwise. public bool AllowMultipleRootLevelValues { get; } - /// - /// Gets the reader's current level of nestedness in the CBOR document. - /// + /// Gets the reader's current level of nestedness in the CBOR document. + /// A number that represents the current level of nestedness in the CBOR document. public int CurrentDepth => _nestedDataItems is null ? 0 : _nestedDataItems.Count; - /// - /// Gets the total number of unread bytes in the buffer. - /// + /// Gets the total number of unread bytes in the buffer. + /// The total number of unread bytes in the buffer. public int BytesRemaining => _data.Length - _offset; - /// - /// Construct a CborReader instance over with given configuration. - /// + /// Initializes a instance over the specified with the given configuration. /// The CBOR encoded data to read. - /// - /// Specifies a conformance mode guiding the checks performed on the encoded data. - /// Defaults to conformance mode. - /// - /// - /// Specify if multiple root-level values are to be supported by the reader. - /// When set to , the reader will throw an - /// if trying to read beyond the scope of one root-level CBOR data item. - /// - /// - /// is not defined. - /// + /// One of the enumeration values to specify a conformance mode guiding the checks performed on the encoded data. + /// Defaults to conformance mode. + /// to indicate that multiple root-level values are supported by the reader; otherwise, . + /// is not defined. public CborReader(ReadOnlyMemory data, CborConformanceMode conformanceMode = CborConformanceMode.Strict, bool allowMultipleRootLevelValues = false) { CborConformanceModeHelpers.Validate(conformanceMode); @@ -79,19 +63,12 @@ public CborReader(ReadOnlyMemory data, CborConformanceMode conformanceMode _definiteLength = allowMultipleRootLevelValues ? null : (int?)1; } - /// - /// Reads the next CBOR data item, returning a view - /// of the encoded value. For indefinite length encodings this includes the break byte. - /// - /// - /// Disable conformance mode validation for the read value, - /// equivalent to using . - /// - /// A view of the encoded value. - /// - /// The data item is not a valid CBOR data item encoding. -or- - /// The CBOR encoding is not valid under the current conformance mode - /// + /// Reads the next CBOR data item, returning a view of the encoded value. For indefinite length encodings this includes the break byte. + /// to disable conformance mode validation for the read value, equivalent to using ; otherwise, . + /// A view of the encoded value as a contiguous region of memory. + /// The data item is not a valid CBOR data item encoding. + /// -or- + /// The CBOR encoding is not valid under the current conformance mode. public ReadOnlyMemory ReadEncodedValue(bool disableConformanceModeChecks = false) { // keep a snapshot of the current offset diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs index cb06ce31e88468..693922905e45ee 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs @@ -3,118 +3,70 @@ namespace System.Formats.Cbor { - /// - /// Specifies the state of a CborReader instance. - /// + /// Specifies the state of a CborReader instance. public enum CborReaderState { - /// - /// Indicates the undefined state. - /// + /// Indicates the undefined state. Undefined = 0, - /// - /// Indicates that the next CBOR data item is an unsigned integer (major type 0). - /// + /// Indicates that the next CBOR data item is an unsigned integer (major type 0). UnsignedInteger, - /// - /// Indicates that the next CBOR data item is a negative integer (major type 1). - /// + /// Indicates that the next CBOR data item is a negative integer (major type 1). NegativeInteger, - /// - /// Indicates that the next CBOR data item is a byte string (major type 2). - /// + /// Indicates that the next CBOR data item is a byte string (major type 2). ByteString, - /// - /// Indicates that the next CBOR data item denotes the start of an indefinite-length byte string (major type 2). - /// + /// Indicates that the next CBOR data item denotes the start of an indefinite-length byte string (major type 2). StartIndefiniteLengthByteString, - /// - /// Indicates that the reader is at the end of an indefinite-length byte string (major type 2). - /// + /// Indicates that the reader is at the end of an indefinite-length byte string (major type 2). EndIndefiniteLengthByteString, - /// - /// Indicates that the next CBOR data item is a UTF-8 string (major type 3). - /// + /// Indicates that the next CBOR data item is a UTF-8 string (major type 3). TextString, - /// - /// Indicates that the next CBOR data item denotes the start of an indefinite-length UTF-8 text string (major type 3). - /// + /// Indicates that the next CBOR data item denotes the start of an indefinite-length UTF-8 text string (major type 3). StartIndefiniteLengthTextString, - /// - /// Indicates that the reader is at the end of an indefinite-length UTF-8 text string (major type 3). - /// + /// Indicates that the reader is at the end of an indefinite-length UTF-8 text string (major type 3). EndIndefiniteLengthTextString, - /// - /// Indicates that the next CBOR data item denotes the start of an array (major type 4). - /// + /// Indicates that the next CBOR data item denotes the start of an array (major type 4). StartArray, - /// - /// Indicates that the reader is at the end of an array (major type 4). - /// + /// Indicates that the reader is at the end of an array (major type 4). EndArray, - /// - /// Indicates that the next CBOR data item denotes the start of a map (major type 5). - /// + /// Indicates that the next CBOR data item denotes the start of a map (major type 5). StartMap, - /// - /// Indicates that the reader is at the end of a map (major type 5). - /// + /// Indicates that the reader is at the end of a map (major type 5). EndMap, - /// - /// Indicates that the next CBOR data item is a semantic tag (major type 6). - /// + /// Indicates that the next CBOR data item is a semantic tag (major type 6). Tag, - /// - /// Indicates that the next CBOR data item is a simple value (major type 7). - /// + /// Indicates that the next CBOR data item is a simple value (major type 7). SimpleValue, - /// - /// Indicates that the next CBOR data item is an IEEE 754 Half-Precision float (major type 7). - /// + /// Indicates that the next CBOR data item is an IEEE 754 Half-Precision float (major type 7). HalfPrecisionFloat, - /// - /// Indicates that the next CBOR data item is an IEEE 754 Single-Precision float (major type 7). - /// + /// Indicates that the next CBOR data item is an IEEE 754 Single-Precision float (major type 7). SinglePrecisionFloat, - /// - /// Indicates that the next CBOR data item is an IEEE 754 Double-Precision float (major type 7). - /// + /// Indicates that the next CBOR data item is an IEEE 754 Double-Precision float (major type 7). DoublePrecisionFloat, - /// - /// Indicates that the next CBOR data item is a literal (major type 7). - /// + /// Indicates that the next CBOR data item is a literal (major type 7). Null, - /// - /// Indicates that the next CBOR data items encodes a value (major type 7). - /// + /// Indicates that the next CBOR data item encodes a value (major type 7). Boolean, - /// - /// Indicates that the reader has completed reading a full CBOR document. - /// - /// - /// If is set to , - /// the reader will report this value even if the buffer contains trailing bytes. - /// + /// Indicates that the reader has completed reading a full CBOR document.If is set to , the reader will report this value even if the buffer contains trailing bytes. Finished, } } diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs index 88a36a5028a377..6ff15a1a6e669d 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs @@ -5,29 +5,19 @@ namespace System.Formats.Cbor { + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { + /// Writes the start of a definite or indefinite-length array (major type 4). + /// The length of the definite-length array, or for an indefinite-length array. + /// The parameter cannot be negative. + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. // Implements major type 4 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 - - /// - /// Writes the start of an array (major type 4). - /// - /// - /// Writes a definite-length array if inhabited, - /// or an indefinite-length array if . - /// - /// - /// The parameter cannot be negative. - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// - /// - /// In canonical conformance modes, the writer will reject indefinite-length writes unless - /// the flag is enabled. - /// public void WriteStartArray(int? definiteLength) { if (definiteLength is null) @@ -40,13 +30,10 @@ public void WriteStartArray(int? definiteLength) } } - /// - /// Writes the end of an array (major type 4). - /// - /// - /// The written data is not accepted under the current conformance mode. -or- - /// The definite-length array anticipates more data items. - /// + /// Writes the end of an array (major type 4). + /// The written data is not accepted under the current conformance mode. + /// -or- + /// The definite-length array anticipates more data items. public void WriteEndArray() { PopDataItem(CborMajorType.Array); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs index ec8891fadec505..ee2ffb4a85423c 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs @@ -5,30 +5,26 @@ namespace System.Formats.Cbor { + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { - // Implements major type 0,1 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 - - /// - /// Writes an value as a signed integer encoding (major types 0,1) - /// + /// Writes a value as a signed integer encoding (major types 0,1) /// The value to write - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + // Implements major type 0,1 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 public void WriteInt32(int value) => WriteInt64(value); - /// - /// Writes the provided value as a signed integer encoding (major types 0,1) - /// + /// Writes the provided value as a signed integer encoding (major types 0,1) /// The value to write - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteInt64(long value) { if (value < 0) @@ -44,27 +40,23 @@ public void WriteInt64(long value) AdvanceDataItemCounters(); } - /// - /// Writes anvalue as an unsigned integer encoding (major type 0). - /// + /// Writes a value as an unsigned integer encoding (major type 0). /// The value to write - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. [CLSCompliant(false)] public void WriteUInt32(uint value) => WriteUInt64(value); - /// - /// Writes an value as an unsigned integer encoding (major type 0). - /// + /// Writes a value as an unsigned integer encoding (major type 0). /// The value to write - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. [CLSCompliant(false)] public void WriteUInt64(ulong value) { @@ -72,19 +64,15 @@ public void WriteUInt64(ulong value) AdvanceDataItemCounters(); } - /// - /// Writes the provided value as a CBOR negative integer representation (major type 1). - /// + /// Writes the provided value as a CBOR negative integer representation (major type 1). /// An unsigned integer denoting -1 minus the integer. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// - /// - /// This method supports encoding integers between -18446744073709551616 and -1. - /// Useful for handling values that do not fit in the type. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + /// This method supports encoding integers between -18446744073709551616 and -1. + /// Useful for handling values that do not fit in the type. [CLSCompliant(false)] public void WriteCborNegativeIntegerRepresentation(ulong value) { diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs index e19499a70ba204..b6866664a89b88 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs @@ -6,6 +6,7 @@ namespace System.Formats.Cbor { + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { // Implements major type 5 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 @@ -14,37 +15,19 @@ public partial class CborWriter private Stack>? _pooledKeyEncodingRangeSets; private Stack>? _pooledKeyValuePairEncodingRangeLists; - /// - /// Writes the start of a map (major type 5). - /// - /// - /// Writes a definite-length map if inhabited, - /// or an indefinite-length map if . - /// - /// - /// The parameter cannot be negative. - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// - /// - /// - /// In canonical conformance modes, the writer will reject indefinite-length writes unless - /// the flag is enabled. - /// - /// - /// Map contents are written as if arrays twice the length of the map's declared size. - /// For instance, a map of size 1 containing a key of type int with a value of type string - /// must be written by successive calls to and . - /// It is up to the caller to keep track of whether the next call is a key or a value. - /// - /// - /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of any type, - /// for instance a map can contain keys that are maps themselves. - /// - /// + /// Writes the start of a definite or indefinite-length map (major type 5). + /// The length of the definite-length map, or for an indefinite-length map. + /// The parameter cannot be negative. + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. + /// Map contents are written as if arrays twice the length of the map's declared size. + /// For instance, a map of size `1` containing a key of type int with a value of type string must be written by successive calls to and . + /// It is up to the caller to keep track of whether the next call is a key or a value. + /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of any type, for instance a map can contain keys that are maps themselves. public void WriteStartMap(int? definiteLength) { if (definiteLength is null) @@ -57,14 +40,12 @@ public void WriteStartMap(int? definiteLength) } } - /// - /// Writes the end of a map (major type 5). - /// - /// - /// The written data is not accepted under the current conformance mode. -or- - /// The definite-length map anticipates more data items. -or- - /// The latest key/value pair is lacking a value. - /// + /// Writes the end of a map (major type 5). + /// The written data is not accepted under the current conformance mode. + /// -or- + /// The definite-length map anticipates more data items. + /// -or- + /// The latest key/value pair is lacking a value. public void WriteEndMap() { if (_itemsWritten % 2 == 1) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs index b1a6fd31d64217..ade531bc646ea3 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs @@ -6,19 +6,17 @@ namespace System.Formats.Cbor { + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { - // Implements major type 7 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 - - /// - /// Writes a half-precision floating point number (major type 7). - /// + /// Writes a half-precision floating point number (major type 7). /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + // Implements major type 7 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 public void WriteHalf(Half value) { EnsureWriteCapacity(1 + HalfHelpers.SizeOfHalf); @@ -28,15 +26,13 @@ public void WriteHalf(Half value) AdvanceDataItemCounters(); } - /// - /// Writes a single-precision floating point number (major type 7). - /// + /// Writes a single-precision floating point number (major type 7). /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteSingle(float value) { if (!CborConformanceModeHelpers.RequiresPreservingFloatPrecision(ConformanceMode) && @@ -50,15 +46,13 @@ public void WriteSingle(float value) } } - /// - /// Writes a double-precision floating point number (major type 7). - /// + /// Writes a double-precision floating point number (major type 7). /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteDouble(double value) { if (!CborConformanceModeHelpers.RequiresPreservingFloatPrecision(ConformanceMode) && @@ -97,45 +91,37 @@ private void WriteDoubleCore(double value) AdvanceDataItemCounters(); } - /// - /// Writes a boolean value (major type 7). - /// + /// Writes a boolean value (major type 7). /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteBoolean(bool value) { WriteSimpleValue(value ? CborSimpleValue.True : CborSimpleValue.False); } - /// - /// Writes a null value (major type 7). - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// Writes a value (major type 7). + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteNull() { WriteSimpleValue(CborSimpleValue.Null); } - /// - /// Writes a simple value encoding (major type 7). - /// + /// Writes a simple value encoding (major type 7). /// The value to write. - /// - /// The parameter is in the invalid 24-31 range. - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// The parameter is in the invalid 24-31 range. + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteSimpleValue(CborSimpleValue value) { if (value < (CborSimpleValue)CborAdditionalInfo.Additional8BitData) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs index bb2ca9c2839e79..609ba4770f0ce0 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs @@ -7,6 +7,7 @@ namespace System.Formats.Cbor { + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { // Implements major type 2,3 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 @@ -14,18 +15,14 @@ public partial class CborWriter // keeps track of chunk offsets for written indefinite-length string ranges private List<(int Offset, int Length)>? _currentIndefiniteLengthStringRanges; - /// - /// Writes a buffer as a byte string encoding (major type 2). - /// + /// Writes a buffer as a byte string encoding (major type 2). /// The value to write. - /// - /// The provided value cannot be null. - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// The provided value cannot be . + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteByteString(byte[] value) { if (value is null) @@ -36,15 +33,13 @@ public void WriteByteString(byte[] value) WriteByteString(value.AsSpan()); } - /// - /// Writes a buffer as a byte string encoding (major type 2). - /// + /// Writes a buffer as a byte string encoding (major type 2). /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteByteString(ReadOnlySpan value) { WriteUnsignedInteger(CborMajorType.ByteString, (ulong)value.Length); @@ -64,19 +59,14 @@ public void WriteByteString(ReadOnlySpan value) AdvanceDataItemCounters(); } - /// - /// Writes the start of an indefinite-length byte string (major type 2). - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// - /// - /// Pushes a context where definite-length chunks of the same major type can be written. - /// In canonical conformance modes, the writer will reject indefinite-length writes unless - /// the flag is enabled. - /// + /// Writes the start of an indefinite-length byte string (major type 2). + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + /// Pushes a context where definite-length chunks of the same major type can be written. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. public void WriteStartIndefiniteLengthByteString() { if (!ConvertIndefiniteLengthEncodings && CborConformanceModeHelpers.RequiresDefiniteLengthItems(ConformanceMode)) @@ -97,33 +87,23 @@ public void WriteStartIndefiniteLengthByteString() PushDataItem(CborMajorType.ByteString, definiteLength: null); } - /// - /// Writes the end of an indefinite-length byte string (major type 2). - /// - /// - /// The written data is not accepted under the current conformance mode - /// + /// Writes the end of an indefinite-length byte string (major type 2). + /// The written data is not accepted under the current conformance mode. public void WriteEndIndefiniteLengthByteString() { PopDataItem(CborMajorType.ByteString); AdvanceDataItemCounters(); } - /// - /// Writes a buffer as a UTF-8 string encoding (major type 3). - /// + /// Writes a buffer as a UTF-8 string encoding (major type 3). /// The value to write. - /// - /// The provided value cannot be null. - /// - /// - /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// The provided value cannot be . + /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteTextString(string value) { if (value is null) @@ -134,18 +114,14 @@ public void WriteTextString(string value) WriteTextString(value.AsSpan()); } - /// - /// Writes a buffer as a UTF-8 string encoding (major type 3). - /// + /// Writes a buffer as a UTF-8 string encoding (major type 3). /// The value to write. - /// - /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteTextString(ReadOnlySpan value) { Encoding utf8Encoding = CborConformanceModeHelpers.GetUtf8Encoding(ConformanceMode); @@ -177,19 +153,14 @@ public void WriteTextString(ReadOnlySpan value) AdvanceDataItemCounters(); } - /// - /// Writes the start of an indefinite-length UTF-8 string (major type 3). - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// - /// - /// Pushes a context where definite-length chunks of the same major type can be written. - /// In canonical conformance modes, the writer will reject indefinite-length writes unless - /// the flag is enabled. - /// + /// Writes the start of an indefinite-length UTF-8 string (major type 3). + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. + /// Pushes a context where definite-length chunks of the same major type can be written. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. public void WriteStartIndefiniteLengthTextString() { if (!ConvertIndefiniteLengthEncodings && CborConformanceModeHelpers.RequiresDefiniteLengthItems(ConformanceMode)) @@ -210,12 +181,8 @@ public void WriteStartIndefiniteLengthTextString() PushDataItem(CborMajorType.TextString, definiteLength: null); } - /// - /// Writes the end of an indefinite-length UTF-8 string (major type 3). - /// - /// - /// The written data is not accepted under the current conformance mode - /// + /// Writes the end of an indefinite-length UTF-8 string (major type 3). + /// The written data is not accepted under the current conformance mode. public void WriteEndIndefiniteLengthTextString() { PopDataItem(CborMajorType.TextString); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs index c447dd80069d7b..6c4f66a9c4d476 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs @@ -6,19 +6,16 @@ namespace System.Formats.Cbor { + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { - // Implements major type 6 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 - - /// - /// Assign a semantic tag (major type 6) to the next data item. - /// + /// Assign a semantic tag (major type 6) to the next data item. /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. [CLSCompliant(false)] public void WriteTag(CborTag tag) { @@ -31,16 +28,13 @@ public void WriteTag(CborTag tag) _isTagContext = true; } - /// - /// Writes the provided value as a tagged date/time string, - /// as described in RFC7049 section 2.4.1. - /// + /// Writes the provided value as a tagged date/time string, as described in RFC7049 section 2.4.1. /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteDateTimeOffset(DateTimeOffset value) { string dateString = @@ -52,35 +46,27 @@ public void WriteDateTimeOffset(DateTimeOffset value) WriteTextString(dateString); } - /// - /// Writes a unix time in seconds as a tagged date/time value, - /// as described in RFC7049 section 2.4.1. - /// + /// Writes a unix time in seconds as a tagged date/time value, as described in RFC7049 section 2.4.1. /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteUnixTimeSeconds(long seconds) { WriteTag(CborTag.UnixTimeSeconds); WriteInt64(seconds); } - /// - /// Writes a unix time in seconds as a tagged date/time value, - /// as described in RFC7049 section 2.4.1. - /// + /// Writes a unix time in seconds as a tagged date/time value, as described in RFC7049 section 2.4.1. /// The value to write. - /// - /// The parameter cannot be infinite or NaN - /// - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// The parameter cannot be infinite or NaN + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteUnixTimeSeconds(double seconds) { if (double.IsInfinity(seconds) || double.IsNaN(seconds)) @@ -92,16 +78,13 @@ public void WriteUnixTimeSeconds(double seconds) WriteDouble(seconds); } - /// - /// Writes the provided value as a tagged bignum encoding, - /// as described in RFC7049 section 2.4.2. - /// + /// Writes the provided value as a tagged bignum encoding, as described in RFC7049 section 2.4.2. /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteBigInteger(BigInteger value) { bool isUnsigned = value.Sign >= 0; @@ -112,16 +95,13 @@ public void WriteBigInteger(BigInteger value) WriteByteString(unsignedBigEndianEncoding); } - /// - /// Writes the provided value value as a tagged decimal fraction encoding, - /// as described in RFC7049 section 2.4.3 - /// + /// Writes the provided value value as a tagged decimal fraction encoding, as described in RFC7049 section 2.4.3 /// The value to write. - /// - /// Writing a new value exceeds the definite length of the parent data item. -or- - /// The major type of the encoded value is not permitted in the parent data item. -or- - /// The written data is not accepted under the current conformance mode. - /// + /// Writing a new value exceeds the definite length of the parent data item. + /// -or- + /// The major type of the encoded value is not permitted in the parent data item. + /// -or- + /// The written data is not accepted under the current conformance mode. public void WriteDecimal(decimal value) { DecimalHelpers.Deconstruct(value, out decimal mantissa, out byte scale); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs index 9e5b0376265a50..640f29c27c5f64 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs @@ -8,9 +8,7 @@ namespace System.Formats.Cbor { - /// - /// A writer for CBOR encoded data. - /// + /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { private static readonly ArrayPool s_bufferPool = ArrayPool.Create(); @@ -32,62 +30,36 @@ public partial class CborWriter private List? _keyValuePairEncodingRanges; // all key/value pair encoding ranges private HashSet<(int Offset, int Length)>? _keyEncodingRanges; // all key encoding ranges up to encoding equality - /// - /// The conformance mode used by this writer. - /// + /// Gets the conformance mode used by this writer. + /// One of the enumeration values that represent the conformance mode used by this writer. public CborConformanceMode ConformanceMode { get; } - /// - /// Gets a value that indicates whether the writer automatically converts indefinite-length encodings into definite-length equivalents. - /// - /// - /// if the writer automatically converts indefinite-length encodings into definite-length equivalents; otherwise, . - /// + /// Gets a value that indicates whether the writer automatically converts indefinite-length encodings into definite-length equivalents. + /// if the writer automatically converts indefinite-length encodings into definite-length equivalents; otherwise, . public bool ConvertIndefiniteLengthEncodings { get; } - /// - /// Declares whether this writer allows multiple root-level CBOR data items. - /// - /// - /// if the writer allows multiple root-level CBOR data items; otherwise, . - /// + /// Gets a value that indicates whether this writer allows multiple root-level CBOR data items. + /// if the writer allows multiple root-level CBOR data items; otherwise, . public bool AllowMultipleRootLevelValues { get; } - /// - /// Gets the writer's current level of nestedness in the CBOR document. - /// + /// Gets the writer's current level of nestedness in the CBOR document. + /// A number that represents the current level of nestedness in the CBOR document. public int CurrentDepth => _nestedDataItems is null ? 0 : _nestedDataItems.Count; - /// - /// Gets the total number of bytes that have been written to the buffer. - /// + /// Gets the total number of bytes that have been written to the buffer. + /// The total number of bytes that have been written to the buffer. public int BytesWritten => _offset; - /// - /// True if the writer has completed writing a complete root-level CBOR document, - /// or sequence of root-level CBOR documents. - /// + /// Declares whether the writer has completed writing a complete root-level CBOR document, or sequence of root-level CBOR documents. + /// if the writer has completed writing a complete root-level CBOR document, or sequence of root-level CBOR documents; otherwise. public bool IsWriteCompleted => _currentMajorType is null && _itemsWritten > 0; - /// - /// Create a new CborWriter instance with given configuration. - /// - /// - /// Specifies a guiding the conformance checks performed on the encoded data. - /// Defaults to conformance mode. - /// - /// - /// Enables automatically converting indefinite-length encodings into definite-length equivalents. - /// Allows use of indefinite-length write APIs in conformance modes that otherwise do not permit it. - /// Defaults to . - /// - /// - /// to allow multiple root-level values to be written by the writer; otherwise, . - /// The default is . - /// - /// - /// is not a defined . - /// + /// Initializes a new instance of class using the specified configuration. + /// One of the enumeration values that specifies the guidance on the conformance checks performed on the encoded data. + /// Defaults to conformance mode. + /// to enable automatically converting indefinite-length encodings into definite-length equivalents and allow use of indefinite-length write APIs in conformance modes that otherwise do not permit it; otherwise, + /// to allow multiple root-level values to be written by the writer; otherwise, . + /// is not a defined . public CborWriter(CborConformanceMode conformanceMode = CborConformanceMode.Strict, bool convertIndefiniteLengthEncodings = false, bool allowMultipleRootLevelValues = false) { CborConformanceModeHelpers.Validate(conformanceMode); @@ -98,9 +70,7 @@ public CborWriter(CborConformanceMode conformanceMode = CborConformanceMode.Stri _definiteLength = allowMultipleRootLevelValues ? null : (int?)1; } - /// - /// Reset the writer to have no data, without releasing resources. - /// + /// Resets the writer to have no data, without releasing resources. public void Reset() { if (_offset > 0) @@ -123,14 +93,11 @@ public void Reset() } } - /// - /// Writes a single CBOR data item which has already been encoded. - /// + /// Writes a single CBOR data item which has already been encoded. /// The encoded value to write. - /// - /// is not a well-formed CBOR encoding. -or- - /// is not valid under the current conformance mode - /// + /// is not a well-formed CBOR encoding. + /// -or- + /// is not valid under the current conformance mode. public void WriteEncodedValue(ReadOnlySpan encodedValue) { ValidateEncoding(encodedValue, ConformanceMode); @@ -178,26 +145,16 @@ static unsafe void ValidateEncoding(ReadOnlySpan encodedValue, CborConform } } - /// - /// Returns a new array containing the encoded value. - /// + /// Returns a new array containing the encoded value. /// A precisely-sized array containing the encoded value. - /// - /// The writer does not contain a complete CBOR value or sequence of root-level values. - /// + /// The writer does not contain a complete CBOR value or sequence of root-level values. public byte[] Encode() => GetSpanEncoding().ToArray(); - /// - /// Write the encoded representation of the data to . - /// + /// Writes the encoded representation of the data to . /// The buffer in which to write. - /// The number of bytes written to . - /// - /// The writer does not contain a complete CBOR value or sequence of root-level values. - /// - /// - /// The destination buffer is not large enough to hold the encoded value. - /// + /// The number of bytes written to . + /// The writer does not contain a complete CBOR value or sequence of root-level values. + /// The destination buffer is not large enough to hold the encoded value. public int Encode(Span destination) { ReadOnlySpan encoding = GetSpanEncoding(); @@ -211,20 +168,11 @@ public int Encode(Span destination) return encoding.Length; } - /// - /// Write the encoded representation of the data to . - /// + /// Attempts to write the encoded representation of the data to . /// The buffer in which to write. - /// - /// On success, receives the number of bytes written to . - /// - /// - /// if the encode succeeded, - /// if is too small. - /// - /// - /// The writer does not contain a complete CBOR value or sequence of root-level values. - /// + /// When this method returns, contains the number of bytes written to . + /// if the encode succeeded, if is too small. + /// The writer does not contain a complete CBOR value or sequence of root-level values. public bool TryEncode(Span destination, out int bytesWritten) { ReadOnlySpan encoding = GetSpanEncoding(); From d2aa78a3e01ac1d4ecd98fc23206aa4c2ea2ca4d Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Mon, 19 Apr 2021 16:54:33 +0100 Subject: [PATCH 2/4] apply manual fixups to documentation --- .../Formats/Cbor/CborConformanceLevel.cs | 68 ++++++++----------- .../Formats/Cbor/CborContentException.cs | 6 +- .../Formats/Cbor/Reader/CborReader.Array.cs | 9 ++- .../Formats/Cbor/Reader/CborReader.Integer.cs | 40 +++++------ .../Formats/Cbor/Reader/CborReader.Map.cs | 19 +++--- .../Cbor/Reader/CborReader.PeekState.cs | 3 +- .../Formats/Cbor/Reader/CborReader.Simple.cs | 25 ++++--- .../Cbor/Reader/CborReader.SkipValue.cs | 13 ++-- .../Formats/Cbor/Reader/CborReader.String.cs | 45 ++++++------ .../Formats/Cbor/Reader/CborReader.Tag.cs | 27 ++++---- .../System/Formats/Cbor/Reader/CborReader.cs | 12 ++-- .../Formats/Cbor/Reader/CborReaderState.cs | 6 +- .../Formats/Cbor/Writer/CborWriter.Array.cs | 15 ++-- .../Formats/Cbor/Writer/CborWriter.Integer.cs | 20 +++--- .../Formats/Cbor/Writer/CborWriter.Map.cs | 18 +++-- .../Formats/Cbor/Writer/CborWriter.Simple.cs | 18 ++--- .../Formats/Cbor/Writer/CborWriter.String.cs | 39 ++++++----- .../Formats/Cbor/Writer/CborWriter.Tag.cs | 15 ++-- .../System/Formats/Cbor/Writer/CborWriter.cs | 16 ++--- 19 files changed, 210 insertions(+), 204 deletions(-) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs index 7f47b414321b77..df160c57d4c367 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborConformanceLevel.cs @@ -13,49 +13,39 @@ public enum CborConformanceMode /// Ensures that the CBOR data is well-formed, as specified in RFC7049. Lax, - /// Ensures that the CBOR data adheres to strict mode, as specified in RFC7049 section 3.10.Extends lax conformance with the following requirements: - /// - /// Maps (major type 5) must not contain duplicate keys. - /// - /// - /// Simple values (major type 7) must be encoded as small a possible and exclude the reserved values 24-31. - /// - /// - /// UTF-8 string encodings must be valid. - /// - /// + /// + /// Ensures that the CBOR data adheres to strict mode, as specified in RFC7049 section 3.10. + /// Extends lax conformance with the following requirements: + /// + /// Maps (major type 5) must not contain duplicate keys. + /// Simple values (major type 7) must be encoded as small a possible and exclude the reserved values 24-31. + /// UTF-8 string encodings must be valid. + /// + /// Strict, - /// Ensures that the CBOR data is canonical, as specified in RFC7049 section 3.9.Extends strict conformance with the following requirements: - /// - /// Integers must be encoded as small as possible. - /// - /// - /// Maps (major type 5) must contain keys sorted by encoding. - /// - /// - /// Indefinite-length items must be made into definite-length items. - /// - /// + /// + /// Ensures that the CBOR data is canonical, as specified in RFC7049 section 3.9. + /// Extends strict conformance with the following requirements: + /// + /// Integers must be encoded as small as possible. + /// Maps (major type 5) must contain keys sorted by encoding. + /// Indefinite-length items must be made into definite-length items. + /// + /// Canonical, - /// Ensures that the CBOR data is canonical, as specified by the CTAP v2.0 standard, section 6.Extends strict conformance with the following requirements: - /// - /// Maps (major type 5) must contain keys sorted by encoding. - /// - /// - /// Indefinite-length items must be made into definite-length items. - /// - /// - /// Integers must be encoded as small as possible. - /// - /// - /// The representations of any floating-point values are not changed. - /// - /// - /// CBOR tags (major type 6) are not permitted. - /// - /// + /// + /// Ensures that the CBOR data is canonical, as specified by the CTAP v2.0 standard, section 6. + /// Extends strict conformance with the following requirements: + /// + /// Maps (major type 5) must contain keys sorted by encoding. + /// Indefinite-length items must be made into definite-length items. + /// Integers must be encoded as small as possible. + /// The representations of any floating-point values are not changed. + /// CBOR tags (major type 6) are not permitted. + /// + /// Ctap2Canonical, } diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs index f9f226618ded57..4814f12c09b847 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/CborContentException.cs @@ -10,7 +10,7 @@ namespace System.Formats.Cbor public class CborContentException : Exception { /// - /// Initializes a new instance of the class, using the provided message. + /// Initializes a new instance of the class, using the provided message. /// /// The error message that explains the reason for the exception. public CborContentException(string? message) @@ -20,7 +20,7 @@ public CborContentException(string? message) } /// - /// Initializes a new instance of the class, + /// Initializes a new instance of the class, /// using the provided message and exception that is the cause of this exception. /// /// The error message that explains the reason for the exception. @@ -32,7 +32,7 @@ public CborContentException(string? message, Exception? inner) } /// - /// Initializes a new instance of the class with serialized data. + /// Initializes a new instance of the class with serialized data. /// /// The object that holds the serialized object data. /// The contextual information about the source or destination. diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs index 51426cb9736d0c..fe6f4f100e6901 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Array.cs @@ -3,13 +3,12 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { /// Reads the next data item as the start of an array (major type 4). /// The length of the definite-length array, or if the array is indefinite-length. - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -41,10 +40,10 @@ public partial class CborReader } /// Reads the end of an array (major type 4). - /// The current context is not an array. + /// The current context is not an array. /// -or- /// The reader is not at the end of the array. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. public void ReadEndArray() diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs index 51b683768140ce..ef384a892e809f 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Integer.cs @@ -5,19 +5,19 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { + // Implements major type 0,1 decoding per https://tools.ietf.org/html/rfc7049#section-2.1 + /// Reads the next data item as a signed integer (major types 0,1) /// The decoded integer value. - /// The next data item does not have the correct major type. - /// The encoded integer is out of range for . - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- /// The next value uses a CBOR encoding that is not valid under the current conformance mode. - // Implements major type 0,1 decoding per https://tools.ietf.org/html/rfc7049#section-2.1 public int ReadInt32() { int value = checked((int)PeekSignedInteger(out int bytesRead)); @@ -28,9 +28,9 @@ public int ReadInt32() /// Reads the next data item as an unsigned integer (major type 0). /// The decoded integer value. - /// The next data item does not have the correct major type. - /// The encoded integer is out of range for . - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -46,9 +46,9 @@ public uint ReadUInt32() /// Reads the next data item as a signed integer (major types 0,1) /// The decoded integer value. - /// The next data item does not have the correct major type. - /// The encoded integer is out of range for . - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -63,9 +63,9 @@ public long ReadInt64() /// Reads the next data item as an unsigned integer (major type 0). /// The decoded integer value. - /// The next data item does not have the correct major type. - /// The encoded integer is out of range for . - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for . + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -81,15 +81,17 @@ public ulong ReadUInt64() /// Reads the next data item as a CBOR negative integer representation (major type 1). /// An unsigned integer denoting -1 minus the integer. - /// The next data item does not have the correct major type. - /// The encoded integer is out of range for - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The encoded integer is out of range for + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- /// The next value uses a CBOR encoding that is not valid under the current conformance mode. - /// This method supports decoding integers between -18446744073709551616 and -1. - /// Useful for handling values that do not fit in the type. + /// + /// This method supports decoding integers between -18446744073709551616 and -1. + /// Useful for handling values that do not fit in the type. + /// [CLSCompliant(false)] public ulong ReadCborNegativeIntegerRepresentation() { diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs index 4176434c907201..1734556e273ee0 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs @@ -6,7 +6,6 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { private KeyEncodingComparer? _keyEncodingComparer; @@ -14,16 +13,20 @@ public partial class CborReader /// Reads the next data item as the start of a map (major type 5). /// The number of key-value pairs in a definite-length map, or if the map is indefinite-length. - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- /// The next value uses a CBOR encoding that is not valid under the current conformance mode. - /// Map contents are consumed as if they were arrays twice the length of the map's declared size. - /// For instance, a map of size `1` containing a key of type `int` with a value of type `string` must be consumed by successive calls to and . + /// + /// Map contents are consumed as if they were arrays twice the length of the map's declared size. + /// For instance, a map of size `1` containing a key of type `int` with a value of type `string` + /// must be consumed by successive calls to and . /// It is up to the caller to keep track of whether the next value is a key or a value. - /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of arbitrary type, for instance a map can contain keys that are maps themselves. + /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of arbitrary type, + /// for instance a map can contain keys that are maps themselves. + /// public int? ReadStartMap() { int? length; @@ -61,10 +64,10 @@ public partial class CborReader } /// Reads the end of a map (major type 5). - /// The current context is not a map. + /// The current context is not a map. /// -or- /// The reader is not at the end of the map. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs index 59ff581dc3e77c..35006c52f3b8b1 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.PeekState.cs @@ -5,12 +5,11 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { /// Reads the next CBOR token, without advancing the reader. /// An object that represents the current CBOR reader state. - /// The underlying data is not a well-formed CBOR encoding. + /// The underlying data is not a well-formed CBOR encoding. public CborReaderState PeekState() { if (_cachedState == CborReaderState.Undefined) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs index ccdb1d50de190b..9d2188ac347230 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Simple.cs @@ -5,17 +5,16 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { /// Reads the next data item as a half-precision floating point number (major type 7). /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next simple value is not a floating-point number encoding. /// -or- /// The encoded value is a double-precision float. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -46,12 +45,12 @@ public Half ReadHalf() /// Reads the next data item as a single-precision floating point number (major type 7). /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next simple value is not a floating-point number encoding. /// -or- /// The encoded value is a double-precision float - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -89,10 +88,10 @@ public float ReadSingle() /// Reads the next data item as a double-precision floating point number (major type 7). /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next simple value is not a floating-point number encoding - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -133,10 +132,10 @@ public double ReadDouble() /// Reads the next data item as a boolean value (major type 7). /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next simple value is not a boolean encoding - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -158,10 +157,10 @@ public bool ReadBoolean() } /// Reads the next data item as a value (major type 7). - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next simple value is not a value encoding. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -183,10 +182,10 @@ public void ReadNull() /// Reads the next data item as a CBOR simple value (major type 7). /// The decoded CBOR simple value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next simple value is not a simple value encoding. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs index 42ea1632df65a7..28257d82b1c8bc 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.SkipValue.cs @@ -5,13 +5,12 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { /// Reads the contents of the next value, discarding the result and advancing the reader. - /// to disable conformance mode validation for the skipped values, equivalent to using ; otherwise, . - /// The reader is not at the start of new value. - /// The next value has an invalid CBOR encoding. + /// to disable conformance mode validation for the skipped values, equivalent to using ; otherwise, . + /// The reader is not at the start of new value. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -22,9 +21,9 @@ public void SkipValue(bool disableConformanceModeChecks = false) } /// Reads the remaining contents of the current value context, discarding results and advancing the reader to the next value in the parent context. - /// to disable conformance mode validation for the skipped values, equivalent to using ; otherwise, . - /// The reader is at the root context - /// The next value has an invalid CBOR encoding. + /// to disable conformance mode validation for the skipped values, equivalent to using ; otherwise, . + /// The reader is at the root context + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs index d5ccde2125d693..6ede28d84230bd 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.String.cs @@ -8,7 +8,6 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { // Implements major type 2,3 decoding per https://tools.ietf.org/html/rfc7049#section-2.1 @@ -18,8 +17,8 @@ public partial class CborReader /// Reads the next data item as a byte string (major type 2). /// The decoded byte array. - /// The next date item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next date item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -53,8 +52,8 @@ public byte[] ReadByteString() /// The buffer in which to write the read bytes. /// On success, receives the number of bytes written to . /// if had sufficient length to receive the value and the reader advances; otherwise, . - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -93,11 +92,11 @@ public bool TryReadByteString(Span destination, out int bytesWritten) } /// Reads the next data item as a definite-length byte string (major type 2). - /// A view of the byte string payload. - /// The next data item does not have the correct major type. + /// A view of the byte string payload. + /// The next data item does not have the correct major type. /// -or- /// The data item is an indefinite-length byte string. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -122,10 +121,10 @@ public ReadOnlyMemory ReadDefiniteLengthByteString() } /// Reads the next data item as the start of an indefinite-length byte string (major type 2). - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next data item is a definite-length encoded string. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -149,10 +148,10 @@ public void ReadStartIndefiniteLengthByteString() } /// Ends reading an indefinite-length byte string (major type 2). - /// The current context is not an indefinite-length string. + /// The current context is not an indefinite-length string. /// -or- /// The reader is not at the end of the string. - /// There was an unexpected end of CBOR encoding data. + /// There was an unexpected end of CBOR encoding data. public void ReadEndIndefiniteLengthByteString() { ValidateNextByteIsBreakByte(); @@ -163,8 +162,8 @@ public void ReadEndIndefiniteLengthByteString() /// Reads the next data item as a UTF-8 text string (major type 3). /// The decoded string. - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -209,8 +208,8 @@ public string ReadTextString() /// The buffer in which to write. /// On success, receives the number of chars written to . /// and advances the reader if had sufficient length to receive the value, otherwise and the reader does not advance. - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -253,11 +252,11 @@ public bool TryReadTextString(Span destination, out int charsWritten) } /// Reads the next data item as a definite-length UTF-8 text string (major type 3). - /// A view of the raw UTF-8 payload. - /// The next data item does not have the correct major type. + /// A view of the raw UTF-8 payload. + /// The next data item does not have the correct major type. /// -or- /// The data item is an indefinite-length text string. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -289,10 +288,10 @@ public ReadOnlyMemory ReadDefiniteLengthTextStringBytes() } /// Reads the next data item as the start of an indefinite-length UTF-8 text string (major type 3). - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next data item is a definite-length encoded string. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -316,10 +315,10 @@ public void ReadStartIndefiniteLengthTextString() } /// Ends reading an indefinite-length UTF-8 text string (major type 3). - /// The current context is not an indefinite-length string. + /// The current context is not an indefinite-length string. /// -or- /// The reader is not at the end of the string. - /// There was an unexpected end of CBOR encoding data. + /// There was an unexpected end of CBOR encoding data. public void ReadEndIndefiniteLengthTextString() { ValidateNextByteIsBreakByte(); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs index 9462366269b0ef..edf6d868b7f62c 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Tag.cs @@ -6,13 +6,12 @@ namespace System.Formats.Cbor { - /// A stateful, forward-only reader for Concise Binary Object Representation (CBOR) encoded data. public partial class CborReader { /// Reads the next data item as a semantic tag (major type 6). /// The decoded value. - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -29,8 +28,8 @@ public CborTag ReadTag() /// Reads the next data item as a semantic tag (major type 6), without advancing the reader. /// The decoded value. - /// The next data item does not have the correct major type. - /// The next value has an invalid CBOR encoding. + /// The next data item does not have the correct major type. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -41,10 +40,10 @@ public CborTag ReadTag() /// Reads the next data item as a tagged date/time string, as described in RFC7049 section 2.4.1. /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next date item does not have the correct semantic tag. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -89,10 +88,10 @@ public DateTimeOffset ReadDateTimeOffset() /// Reads the next data item as a tagged unix time in seconds, as described in RFC7049 section 2.4.1. /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next date item does not have the correct semantic tag. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -141,10 +140,10 @@ public DateTimeOffset ReadUnixTimeSeconds() /// Reads the next data item as a tagged bignum encoding, as described in RFC7049 section 2.4.2. /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next date item does not have the correct semantic tag. - /// The next value has an invalid CBOR encoding. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- @@ -188,11 +187,11 @@ public BigInteger ReadBigInteger() /// Reads the next data item as a tagged decimal fraction encoding, as described in RFC7049 section 2.4.3. /// The decoded value. - /// The next data item does not have the correct major type. + /// The next data item does not have the correct major type. /// -or- /// The next date item does not have the correct semantic tag. - /// Decoded decimal fraction is either too large or too small for a value. - /// The next value has an invalid CBOR encoding. + /// Decoded decimal fraction is either too large or too small for a value. + /// The next value has an invalid CBOR encoding. /// -or- /// There was an unexpected end of CBOR encoding data. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs index ce043f71958437..5b366df2377a86 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.cs @@ -47,12 +47,12 @@ public partial class CborReader /// The total number of unread bytes in the buffer. public int BytesRemaining => _data.Length - _offset; - /// Initializes a instance over the specified with the given configuration. + /// Initializes a instance over the specified with the given configuration. /// The CBOR encoded data to read. /// One of the enumeration values to specify a conformance mode guiding the checks performed on the encoded data. - /// Defaults to conformance mode. + /// Defaults to conformance mode. /// to indicate that multiple root-level values are supported by the reader; otherwise, . - /// is not defined. + /// is not defined. public CborReader(ReadOnlyMemory data, CborConformanceMode conformanceMode = CborConformanceMode.Strict, bool allowMultipleRootLevelValues = false) { CborConformanceModeHelpers.Validate(conformanceMode); @@ -63,10 +63,10 @@ public CborReader(ReadOnlyMemory data, CborConformanceMode conformanceMode _definiteLength = allowMultipleRootLevelValues ? null : (int?)1; } - /// Reads the next CBOR data item, returning a view of the encoded value. For indefinite length encodings this includes the break byte. - /// to disable conformance mode validation for the read value, equivalent to using ; otherwise, . + /// Reads the next CBOR data item, returning a view of the encoded value. For indefinite length encodings this includes the break byte. + /// to disable conformance mode validation for the read value, equivalent to using ; otherwise, . /// A view of the encoded value as a contiguous region of memory. - /// The data item is not a valid CBOR data item encoding. + /// The data item is not a valid CBOR data item encoding. /// -or- /// The CBOR encoding is not valid under the current conformance mode. public ReadOnlyMemory ReadEncodedValue(bool disableConformanceModeChecks = false) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs index 693922905e45ee..96411385de033d 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReaderState.cs @@ -66,7 +66,11 @@ public enum CborReaderState /// Indicates that the next CBOR data item encodes a value (major type 7). Boolean, - /// Indicates that the reader has completed reading a full CBOR document.If is set to , the reader will report this value even if the buffer contains trailing bytes. + /// + /// Indicates that the reader has completed reading a full CBOR document. + /// If is set to , + /// the reader will report this value even if the buffer contains trailing bytes. + /// Finished, } } diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs index 6ff15a1a6e669d..ed20101513f98c 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Array.cs @@ -5,19 +5,22 @@ namespace System.Formats.Cbor { - /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { + // Implements major type 4 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 + /// Writes the start of a definite or indefinite-length array (major type 4). /// The length of the definite-length array, or for an indefinite-length array. - /// The parameter cannot be negative. - /// Writing a new value exceeds the definite length of the parent data item. + /// The parameter cannot be negative. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. - // Implements major type 4 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 + /// + /// In canonical conformance modes, the writer will reject indefinite-length writes unless + /// the flag is enabled. + /// public void WriteStartArray(int? definiteLength) { if (definiteLength is null) @@ -31,7 +34,7 @@ public void WriteStartArray(int? definiteLength) } /// Writes the end of an array (major type 4). - /// The written data is not accepted under the current conformance mode. + /// The written data is not accepted under the current conformance mode. /// -or- /// The definite-length array anticipates more data items. public void WriteEndArray() diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs index ee2ffb4a85423c..a35e6097feeaaf 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Integer.cs @@ -5,22 +5,22 @@ namespace System.Formats.Cbor { - /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { + // Implements major type 0,1 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 + /// Writes a value as a signed integer encoding (major types 0,1) /// The value to write - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - // Implements major type 0,1 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 public void WriteInt32(int value) => WriteInt64(value); /// Writes the provided value as a signed integer encoding (major types 0,1) /// The value to write - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -42,7 +42,7 @@ public void WriteInt64(long value) /// Writes a value as an unsigned integer encoding (major type 0). /// The value to write - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -52,7 +52,7 @@ public void WriteInt64(long value) /// Writes a value as an unsigned integer encoding (major type 0). /// The value to write - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -66,13 +66,15 @@ public void WriteUInt64(ulong value) /// Writes the provided value as a CBOR negative integer representation (major type 1). /// An unsigned integer denoting -1 minus the integer. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - /// This method supports encoding integers between -18446744073709551616 and -1. - /// Useful for handling values that do not fit in the type. + /// + /// This method supports encoding integers between -18446744073709551616 and -1. + /// Useful for handling values that do not fit in the type. + /// [CLSCompliant(false)] public void WriteCborNegativeIntegerRepresentation(ulong value) { diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs index b6866664a89b88..eb4e8071af6bf0 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs @@ -6,7 +6,6 @@ namespace System.Formats.Cbor { - /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { // Implements major type 5 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 @@ -17,17 +16,22 @@ public partial class CborWriter /// Writes the start of a definite or indefinite-length map (major type 5). /// The length of the definite-length map, or for an indefinite-length map. - /// The parameter cannot be negative. - /// Writing a new value exceeds the definite length of the parent data item. + /// The parameter cannot be negative. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. + /// + /// In canonical conformance modes, the writer will reject indefinite-length writes unless + /// the flag is enabled. /// Map contents are written as if arrays twice the length of the map's declared size. - /// For instance, a map of size `1` containing a key of type int with a value of type string must be written by successive calls to and . + /// For instance, a map of size `1` containing a key of type int with a value of type string must be written + /// by successive calls to and . /// It is up to the caller to keep track of whether the next call is a key or a value. - /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of any type, for instance a map can contain keys that are maps themselves. + /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of any type, + /// for instance a map can contain keys that are maps themselves. + /// public void WriteStartMap(int? definiteLength) { if (definiteLength is null) @@ -41,7 +45,7 @@ public void WriteStartMap(int? definiteLength) } /// Writes the end of a map (major type 5). - /// The written data is not accepted under the current conformance mode. + /// The written data is not accepted under the current conformance mode. /// -or- /// The definite-length map anticipates more data items. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs index ade531bc646ea3..6d4178bae79bbf 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Simple.cs @@ -6,17 +6,17 @@ namespace System.Formats.Cbor { - /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { + // Implements major type 7 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 + /// Writes a half-precision floating point number (major type 7). /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - // Implements major type 7 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 public void WriteHalf(Half value) { EnsureWriteCapacity(1 + HalfHelpers.SizeOfHalf); @@ -28,7 +28,7 @@ public void WriteHalf(Half value) /// Writes a single-precision floating point number (major type 7). /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -48,7 +48,7 @@ public void WriteSingle(float value) /// Writes a double-precision floating point number (major type 7). /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -93,7 +93,7 @@ private void WriteDoubleCore(double value) /// Writes a boolean value (major type 7). /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -104,7 +104,7 @@ public void WriteBoolean(bool value) } /// Writes a value (major type 7). - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -116,8 +116,8 @@ public void WriteNull() /// Writes a simple value encoding (major type 7). /// The value to write. - /// The parameter is in the invalid 24-31 range. - /// Writing a new value exceeds the definite length of the parent data item. + /// The parameter is in the invalid 24-31 range. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs index 609ba4770f0ce0..379163789c8321 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.String.cs @@ -7,7 +7,6 @@ namespace System.Formats.Cbor { - /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { // Implements major type 2,3 encoding per https://tools.ietf.org/html/rfc7049#section-2.1 @@ -17,8 +16,8 @@ public partial class CborWriter /// Writes a buffer as a byte string encoding (major type 2). /// The value to write. - /// The provided value cannot be . - /// Writing a new value exceeds the definite length of the parent data item. + /// The provided value cannot be . + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -35,7 +34,7 @@ public void WriteByteString(byte[] value) /// Writes a buffer as a byte string encoding (major type 2). /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -60,13 +59,16 @@ public void WriteByteString(ReadOnlySpan value) } /// Writes the start of an indefinite-length byte string (major type 2). - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - /// Pushes a context where definite-length chunks of the same major type can be written. - /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. + /// + /// Pushes a context where definite-length chunks of the same major type can be written. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless + /// the flag is enabled. + /// public void WriteStartIndefiniteLengthByteString() { if (!ConvertIndefiniteLengthEncodings && CborConformanceModeHelpers.RequiresDefiniteLengthItems(ConformanceMode)) @@ -88,7 +90,7 @@ public void WriteStartIndefiniteLengthByteString() } /// Writes the end of an indefinite-length byte string (major type 2). - /// The written data is not accepted under the current conformance mode. + /// The written data is not accepted under the current conformance mode. public void WriteEndIndefiniteLengthByteString() { PopDataItem(CborMajorType.ByteString); @@ -97,9 +99,9 @@ public void WriteEndIndefiniteLengthByteString() /// Writes a buffer as a UTF-8 string encoding (major type 3). /// The value to write. - /// The provided value cannot be . - /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. - /// Writing a new value exceeds the definite length of the parent data item. + /// The provided value cannot be . + /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -116,8 +118,8 @@ public void WriteTextString(string value) /// Writes a buffer as a UTF-8 string encoding (major type 3). /// The value to write. - /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. - /// Writing a new value exceeds the definite length of the parent data item. + /// The supplied string is not a valid UTF-8 encoding, which is not permitted under the current conformance mode. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -154,13 +156,16 @@ public void WriteTextString(ReadOnlySpan value) } /// Writes the start of an indefinite-length UTF-8 string (major type 3). - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- /// The written data is not accepted under the current conformance mode. - /// Pushes a context where definite-length chunks of the same major type can be written. - /// In canonical conformance modes, the writer will reject indefinite-length writes unless the flag is enabled. + /// + /// Pushes a context where definite-length chunks of the same major type can be written. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless + /// the flag is enabled. + /// public void WriteStartIndefiniteLengthTextString() { if (!ConvertIndefiniteLengthEncodings && CborConformanceModeHelpers.RequiresDefiniteLengthItems(ConformanceMode)) @@ -182,7 +187,7 @@ public void WriteStartIndefiniteLengthTextString() } /// Writes the end of an indefinite-length UTF-8 string (major type 3). - /// The written data is not accepted under the current conformance mode. + /// The written data is not accepted under the current conformance mode. public void WriteEndIndefiniteLengthTextString() { PopDataItem(CborMajorType.TextString); diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs index 6c4f66a9c4d476..bd94ca2acd15f6 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Tag.cs @@ -6,12 +6,11 @@ namespace System.Formats.Cbor { - /// A writer for Concise Binary Object Representation (CBOR) encoded data. public partial class CborWriter { /// Assign a semantic tag (major type 6) to the next data item. /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -30,7 +29,7 @@ public void WriteTag(CborTag tag) /// Writes the provided value as a tagged date/time string, as described in RFC7049 section 2.4.1. /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -48,7 +47,7 @@ public void WriteDateTimeOffset(DateTimeOffset value) /// Writes a unix time in seconds as a tagged date/time value, as described in RFC7049 section 2.4.1. /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -61,8 +60,8 @@ public void WriteUnixTimeSeconds(long seconds) /// Writes a unix time in seconds as a tagged date/time value, as described in RFC7049 section 2.4.1. /// The value to write. - /// The parameter cannot be infinite or NaN - /// Writing a new value exceeds the definite length of the parent data item. + /// The parameter cannot be infinite or NaN + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -80,7 +79,7 @@ public void WriteUnixTimeSeconds(double seconds) /// Writes the provided value as a tagged bignum encoding, as described in RFC7049 section 2.4.2. /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- @@ -97,7 +96,7 @@ public void WriteBigInteger(BigInteger value) /// Writes the provided value value as a tagged decimal fraction encoding, as described in RFC7049 section 2.4.3 /// The value to write. - /// Writing a new value exceeds the definite length of the parent data item. + /// Writing a new value exceeds the definite length of the parent data item. /// -or- /// The major type of the encoded value is not permitted in the parent data item. /// -or- diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs index 640f29c27c5f64..56170d127db9cd 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.cs @@ -54,12 +54,12 @@ public partial class CborWriter /// if the writer has completed writing a complete root-level CBOR document, or sequence of root-level CBOR documents; otherwise. public bool IsWriteCompleted => _currentMajorType is null && _itemsWritten > 0; - /// Initializes a new instance of class using the specified configuration. + /// Initializes a new instance of class using the specified configuration. /// One of the enumeration values that specifies the guidance on the conformance checks performed on the encoded data. - /// Defaults to conformance mode. + /// Defaults to conformance mode. /// to enable automatically converting indefinite-length encodings into definite-length equivalents and allow use of indefinite-length write APIs in conformance modes that otherwise do not permit it; otherwise, /// to allow multiple root-level values to be written by the writer; otherwise, . - /// is not a defined . + /// is not a defined . public CborWriter(CborConformanceMode conformanceMode = CborConformanceMode.Strict, bool convertIndefiniteLengthEncodings = false, bool allowMultipleRootLevelValues = false) { CborConformanceModeHelpers.Validate(conformanceMode); @@ -95,7 +95,7 @@ public void Reset() /// Writes a single CBOR data item which has already been encoded. /// The encoded value to write. - /// is not a well-formed CBOR encoding. + /// is not a well-formed CBOR encoding. /// -or- /// is not valid under the current conformance mode. public void WriteEncodedValue(ReadOnlySpan encodedValue) @@ -147,14 +147,14 @@ static unsafe void ValidateEncoding(ReadOnlySpan encodedValue, CborConform /// Returns a new array containing the encoded value. /// A precisely-sized array containing the encoded value. - /// The writer does not contain a complete CBOR value or sequence of root-level values. + /// The writer does not contain a complete CBOR value or sequence of root-level values. public byte[] Encode() => GetSpanEncoding().ToArray(); /// Writes the encoded representation of the data to . /// The buffer in which to write. /// The number of bytes written to . - /// The writer does not contain a complete CBOR value or sequence of root-level values. - /// The destination buffer is not large enough to hold the encoded value. + /// The writer does not contain a complete CBOR value or sequence of root-level values. + /// The destination buffer is not large enough to hold the encoded value. public int Encode(Span destination) { ReadOnlySpan encoding = GetSpanEncoding(); @@ -172,7 +172,7 @@ public int Encode(Span destination) /// The buffer in which to write. /// When this method returns, contains the number of bytes written to . /// if the encode succeeded, if is too small. - /// The writer does not contain a complete CBOR value or sequence of root-level values. + /// The writer does not contain a complete CBOR value or sequence of root-level values. public bool TryEncode(Span destination, out int bytesWritten) { ReadOnlySpan encoding = GetSpanEncoding(); From d16162dc218d3b071f858ea2050c4e5efefdb5fc Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Mon, 19 Apr 2021 18:45:53 +0100 Subject: [PATCH 3/4] Update src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs Co-authored-by: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> --- .../src/System/Formats/Cbor/Reader/CborReader.Map.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs index 1734556e273ee0..0fe7125e998423 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Reader/CborReader.Map.cs @@ -21,7 +21,7 @@ public partial class CborReader /// The next value uses a CBOR encoding that is not valid under the current conformance mode. /// /// Map contents are consumed as if they were arrays twice the length of the map's declared size. - /// For instance, a map of size `1` containing a key of type `int` with a value of type `string` + /// For instance, a map of size 1 containing a key of type with a value of type /// must be consumed by successive calls to and . /// It is up to the caller to keep track of whether the next value is a key or a value. /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of arbitrary type, From 1d3fa8a0cfd4301c3292a4884bec1ae5d0a4a76d Mon Sep 17 00:00:00 2001 From: Eirik Tsarpalis Date: Mon, 19 Apr 2021 18:46:00 +0100 Subject: [PATCH 4/4] Update src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs Co-authored-by: Carlos Sanchez <1175054+carlossanlop@users.noreply.github.com> --- .../src/System/Formats/Cbor/Writer/CborWriter.Map.cs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs index eb4e8071af6bf0..ccdedda9357cc9 100644 --- a/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs +++ b/src/libraries/System.Formats.Cbor/src/System/Formats/Cbor/Writer/CborWriter.Map.cs @@ -26,7 +26,7 @@ public partial class CborWriter /// In canonical conformance modes, the writer will reject indefinite-length writes unless /// the flag is enabled. /// Map contents are written as if arrays twice the length of the map's declared size. - /// For instance, a map of size `1` containing a key of type int with a value of type string must be written + /// For instance, a map of size 1 containing a key of type with a value of type string must be written /// by successive calls to and . /// It is up to the caller to keep track of whether the next call is a key or a value. /// Fundamentally, this is a technical restriction stemming from the fact that CBOR allows keys of any type,