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..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 @@ -7,48 +7,44 @@ 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..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 @@ -5,14 +5,12 @@ 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 { /// - /// 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) @@ -22,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. @@ -34,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/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..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 @@ -5,20 +5,14 @@ namespace System.Formats.Cbor { 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 +39,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..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 @@ -9,21 +9,15 @@ 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. 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,26 +79,18 @@ 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. - /// + /// 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. + /// 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..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 @@ -11,28 +11,21 @@ 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. - /// + /// 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. + /// 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 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, + /// for instance a map can contain keys that are maps themselves. /// public int? ReadStartMap() { @@ -70,19 +63,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..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 @@ -7,12 +7,9 @@ namespace System.Formats.Cbor { 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..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 @@ -7,20 +7,18 @@ namespace System.Formats.Cbor { 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 +43,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 +86,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 +130,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 +156,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 +180,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..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 @@ -7,43 +7,27 @@ namespace System.Formats.Cbor { 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..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 @@ -15,21 +15,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 +48,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 +91,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 +120,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 +147,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 +160,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 +204,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 +251,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 +287,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 +314,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..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 @@ -8,18 +8,14 @@ namespace System.Formats.Cbor { 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 +26,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 +86,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 +138,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 +185,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..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 @@ -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..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 @@ -3,118 +3,74 @@ 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. + /// 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. /// - /// - /// 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..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 @@ -9,24 +9,17 @@ public partial class CborWriter { // 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. - /// + /// 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. + /// In canonical conformance modes, the writer will reject indefinite-length writes unless + /// the flag is enabled. /// public void WriteStartArray(int? definiteLength) { @@ -40,13 +33,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..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 @@ -9,26 +9,22 @@ 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. 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,18 +64,16 @@ 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. - /// + /// 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 e19499a70ba204..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 @@ -14,36 +14,23 @@ 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. - /// + /// 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. - /// + /// 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 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) { @@ -57,14 +44,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..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 @@ -10,15 +10,13 @@ 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. 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..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 @@ -14,18 +14,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 +32,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,18 +58,16 @@ 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 - /// + /// 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. + /// 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() { @@ -97,33 +89,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 +116,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,18 +155,16 @@ 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 - /// + /// 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. + /// 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() { @@ -210,12 +186,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..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 @@ -8,17 +8,13 @@ namespace System.Formats.Cbor { 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 +27,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 +45,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 +77,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 +94,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..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 @@ -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();